target-revenue/specs/TargetLedgerSpecification.md

Target Ledger Specification (Normative Extract)

Document version: TRF-Ledger-0.1 Status: Normative extract, Stage 0 Extracted from: specs/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-development	+= amount to Development Credit	Generic correction on the development side, not tied to a specific prior credit entry.
administrative-correction-remission	+= amount to Remission Credit	Generic correction on the remission side, not tied to a specific prior remission entry.
conversion-checkpoint	No numeric effect	Marker only.

Resolved 2026-07-29: the concept document (§17) lists a single, non-exhaustive administrative-correction entry type ("permitted entry types may include...") without specifying which side of the target it adjusts. This extract specializes it into the two typed entries above, closing that ambiguity in the type name itself rather than leaving it as an unstated fold-side default. This does not contradict the concept document — its list was illustrative, not a closed enum — but it is a Stage 0 interpretation this extract adds beyond direct citation, so it remains listed for workplans/TREV-WP-0003-normative-core-extraction.md T06 review alongside the rest of this file.

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 and remission-correction reference the entry they correct via reverses; administrative-correction-development and administrative-correction-remission are generic corrections not tied to a specific prior entry (§2) — 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)

Outstanding Target = max(0, Initial Target − Σ(development-credit, administrative-correction-development)
                                            − Σ(remission-credit, remission-correction, administrative-correction-remission)
                                            + Σ(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.