---
title: "Why a Claim Ledger"
description: "Understand evidence, corrections, identity, and the ledger's three clocks."
canonical: https://y2.dev/docs/ontology/explanation/claim-ledger/
---

Ontology & Fusion

# Why a Claim Ledger

Understand evidence, corrections, identity, and the ledger's three clocks.

The entity ledger records sourced claims instead of overwriting the current answer. Each claim retains its evidence, verification state, and time interval. The displayed view is computed from those records.

## The subject of a claim is not its string

A **subject** represents a person, organization, or system. A **designator** is a name, handle, domain, or other public identifier. A **claim** connects them with evidence.

Two subjects can share a designator without being the same entity. A `same-as` claim records an identity hypothesis. It does not merge subjects. If `distinct-from` is also live, the pair is contested.

## Every change is a new line

A correction supersedes the current claim in its chain. A retraction removes it from the current view but preserves its history and supporting observation. Each record includes a SHA-256 hash and the previous record's hash.

This supports three needs:

- **Accountability:** inspect the evidence available before a correction.
- **Collaboration:** reject a correction that refers to an outdated claim.
- **Portability:** export canonical NDJSON and check it with the local tool.

A valid hash chain establishes internal consistency. It does not establish that the claims are true or that the export includes the latest records.

## Verification belongs to the claim

Verification describes a specific claim, not the person or organization. A handle claim can be `located` because one public page supports it. `cross-linked` requires retrievals from two different pages. `analytic` applies when all cited evidence consists of analyst notes.

Confidence and verification remain separate fields. See [verification states](https://y2.dev/docs/ontology/reference/vocabulary#verification-ladder).

## Three clocks

| Clock          | Field                    | Meaning                           |
| -------------- | ------------------------ | --------------------------------- |
| Record time    | `recorded_at`            | When the ledger stored the record |
| Valid time     | `valid_from`, `valid_to` | When the claim applies            |
| Retrieval time | `retrieved_at`           | When the source was retrieved     |

Record time selects the available history. Valid time filters the claims computed from that history. A missing bound means unknown. A retrieval date alone does not establish when the underlying relationship began.

## Passive by construction

The method vocabulary covers public retrievals and analyst notes. It has no method for authenticated or non-public access to the subject. The ledger stores a short excerpt and its hash, or a reference to preserved content.

## Related explanations

- [Catalog and ledger alignment](https://y2.dev/docs/ontology/explanation/catalog-alignment)
- [Cyber-market fusion](https://y2.dev/docs/ontology/explanation/cyber-market-fusion)
- [STIX export mapping](https://y2.dev/docs/ontology/reference/stix-export)