target-revenue/specs/TargetLedgerSpecification.md

# Target Ledger Specification (Normative Extract)

**Document version:** TRF-Ledger-0.1
**Status:** Normative extract, Stage 0
**Extracted from:** `spec/TargetRevenueLicenseConcept.md` §17 and `specs/TechnicalSpecificationDocument.md` §3.2
**Machine-readable counterpart:** `schemas/ledger_entry.schema.json` — implemented and tested under `workplans/TREV-WP-0002-trust-service-foundation.md` T03 (`src/target_revenue/hashing.py`, `src/target_revenue/fold.py`). This document is the prose normative reference; the schema and library are the authoritative machine-checkable implementation.

---

## 1. Purpose

The Target Ledger is the append-only record of everything that moves a Phase's Outstanding Target. It is the sole input, together with the Phase Manifest, to the Outstanding Target fold and therefore to Conversion Event detection (`specs/TargetRevenueFrameworkCore.md` §1.7–§1.8).

## 2. Entry types (closed set)

| Type | Effect on fold | Notes |
|---|---|---|
| `development-credit` | `+= amount` to Development Credit | Rule 4: normally arises only from settled payments. |
| `remission-credit` | `+= amount` to Remission Credit | Rule 5: never represented as revenue. |
| `credit-reversal` | `-= amount` from Development Credit | Rule 8: compensating entry; requires `reverses` pointing to the original entry id. Never edits or deletes the original. |
| `remission-correction` | `+= amount` to Remission Credit (amount may be negative) | Requires `reverses`. |
| `administrative-correction` | `+= amount` to Development Credit | **Stage 0 simplification:** a generic correction bucket, not yet specialized by which side of the target it corrects. Revisit if this proves ambiguous in practice. |
| `conversion-checkpoint` | No numeric effect | Marker only. |

This set is closed for Stage 0: a project **must not** invent new entry types; new monetization behavior belongs in an extension (`specs/MonetizationExtensionSpecification.md`), not a new ledger entry type.

## 3. Required entry fields

| Field | Type | Notes |
|---|---|---|
| `id` | string (URN `trsl:entry:<id>`) | Globally unique, monotonically orderable. |
| `phase` | string (Phase URN) | Must reference a published Phase Manifest. |
| `type` | enum (§2) | |
| `amount` | decimal | Sign convention per §2. |
| `currency` | ISO 4217 code | **Must match** the Phase's `initial_target.currency` (working default Q6). No FX conversion in the pure fold; a currency mismatch is rejected, not converted. |
| `recognized_at` | ISO 8601 timestamp | Settlement time, not invoice time (Rule 4; working default Q10: `payment-settled` recognition only). |
| `extension.id` / `extension.version` | string / string | Required for `development-credit` / `remission-credit`: identifies the monetization profile or degeneration policy that produced the entry. |
| `evidence_reference` | URI (`confidential:` scheme allowed) | Tiered per working default Q10 (E0 opaque id / E1 settled payment reference / E2 contract+invoice+settlement). |
| `previous_entry_hash` | hex-64 or literal `GENESIS` | SHA-256 of the prior entry's canonical serialization for this Phase (§4). |
| `signature` | string | Ed25519 signature over the canonical serialization (working default Q14); optional in Stage 0 fixtures, required for any public claim. |
| `reverses` | string (entry URN) | Required on `credit-reversal` and `remission-correction`. |

## 4. Hash chain and canonical serialization

**Working default (Q14), accepted via ADR-0001:** canonical serialization is JSON with sorted keys, no insignificant whitespace, UTF-8 encoding, excluding the `signature` and `previous_entry_hash` fields themselves. The chain hash is SHA-256 over that serialization. The first entry for a Phase has `previous_entry_hash: GENESIS`; every subsequent entry's `previous_entry_hash` must equal the SHA-256 digest of the immediately preceding entry's canonical bytes.

Reference implementation: `src/target_revenue/hashing.py::entry_hash`, `verify_chain`.

## 5. Corrections without erasure

Per Rule 8, the ledger is append-only. A correction or reversal is always a **new** entry (`credit-reversal`, `remission-correction`, or `administrative-correction`) referencing the entry it corrects via `reverses` — never an edit or deletion of the original. This preserves the audit trail even when the correction is disputed.

## 6. Outstanding Target fold (normative definition)

```text
Outstanding Target = max(0, Initial Target − Σ(development-credit, administrative-correction)
                                            − Σ(remission-credit, remission-correction)
                                            + Σ(credit-reversal))
```

Equivalently, per entry type effect in §2, folded left-to-right over the Phase's entries in ledger order. The fold is **pure**: identical `(Initial Target, entries)` input always yields identical output, with no hidden state (TSD §6.1). Reference implementation: `src/target_revenue/fold.py::fold_outstanding_target`.

The fold **must** be independently reproducible by any conformant external tool from the Phase Manifest and Target Ledger alone — no Trust Service state is required (PRD NFR-1).

## 7. Currency consistency rule

Working default Q6: every entry's `currency` must equal the Phase's `initial_target.currency`. A mismatch is rejected outright in Stage 0; there is no FX conversion step in the pure fold. A future FX extension may be registered, but until then multi-currency Phases are out of scope. Reference implementation: `src/target_revenue/validation.py::check_currency_consistency`.

## 8. Not covered here

- Phase Manifest fields: `specs/PhaseManifestSpecification.md`.
- Extension contract fields referenced by `extension.id`/`extension.version`: `specs/MonetizationExtensionSpecification.md`.
- Conversion Attestation document schema: `specs/TechnicalSpecificationDocument.md` §3.5 (a dedicated extract is not yet planned; the TSD section remains authoritative).
- Signature key management and rotation: working default Q14 notes an append-only key history document; not yet specified in a dedicated file.