Implement TREV-WP-0002 Stage 0 foundation: schemas, pure fold, golden Phase

Delivers the offline runnable specification foundation for the Trust Layer
(TSD §3-§6), not a hosted Trust Service:

- JSON Schemas for Phase Manifest, Ledger Entry, Extension Contract, and
  Conversion Attestation, encoding the Stage 0 working defaults (Q3 future
  license enum, Q6 single-currency Phases, Q8 required longstop_at).
- src/target_revenue: pure Outstanding Target fold, SHA-256 hash-chain
  verification, Ed25519 signing helpers, extension conformance checks
  (including a core-term-redefinition heuristic), and conversion detection
  that never requires an attestation document to determine conversion status.
- examples/phase-001: golden Phase package matching the concept doc's
  worked example, generated via scripts/generate_golden_phase.py so the
  hash chain is computed by the library itself, not hand-typed.
- 32 passing pytest tests covering manifest/ledger/extension conformance,
  tamper/reorder detection, and the full lifecycle fold to conversion.
- docs/adr/ADR-0001: proposed (not accepted) Stage 0 stack choice, per the
  WP-0002-T01 human-accept gate — implementation proceeded against the
  proposal as the workplan note permits, but the task stays open.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-07-28 18:47:29 +02:00
parent 658b1af00d
commit 57c7111cbc
28 changed files with 1751 additions and 7 deletions

View file

@ -51,6 +51,14 @@ state_hub_task_id: "bdaa3e6a-e13d-4d4f-a6b0-9c56c18850a9"
human_accept_required: true
```
Result 2026-07-28: Drafted `docs/adr/ADR-0001-stage0-library-stack.md`
(status: **proposed**) — Python 3.11+, `jsonschema`, `pytest`, `hatchling`
src-layout; SHA-256 canonical-serialization hash chain; Ed25519 signing.
T02T06 were implemented against this proposal so work could proceed in
parallel, per the workplan note that "agents may draft the ADR for review."
**This task stays `todo`** until a maintainer accepts or revises the ADR —
implementation proceeding does not constitute acceptance.
`specs/TechnicalSpecificationDocument.md` is non-binding on language and
storage (§10). Record an ADR for the **Stage 0 library only**: language for
JSON Schema (or equivalent) validators and the pure fold, canonical
@ -68,11 +76,18 @@ technology choices. Agents may draft the ADR for review.
```task
id: TREV-WP-0002-T02
status: todo
status: done
priority: high
state_hub_task_id: "92568684-2dff-497c-9593-7a0e91cb95a3"
```
Result 2026-07-28: `schemas/phase_manifest.schema.json` +
`src/target_revenue/validation.py::validate_phase_manifest` /
`check_manifest_immutability`. `longstop_at` required, `future_license`
closed to `{MIT, Apache-2.0}`, `phase.id`/`initial_target` immutability
checked across manifest versions. Covered by
`tests/test_manifest_validation.py` (8 tests, all passing).
Implement machine-readable schema + pure validator for Phase Manifest
(TSD §3.1), applying Stage 0 working defaults:
@ -89,11 +104,19 @@ this workplan.
```task
id: TREV-WP-0002-T03
status: todo
status: done
priority: high
state_hub_task_id: "df4133ee-9776-438d-901a-78a906356cfb"
```
Result 2026-07-28: `schemas/ledger_entry.schema.json` (six-type closed enum,
`reverses` required on `credit-reversal`/`remission-correction`);
`src/target_revenue/hashing.py` (SHA-256 canonical-serialization chain +
Ed25519 sign/verify helpers); `src/target_revenue/fold.py`
(`fold_outstanding_target` / `fold_phase`, pure `max(0, T0-C-R)`). Covered by
`tests/test_ledger_fold.py` (10 tests: currency mismatch, tamper/reorder
detection, §23 checkpoint numbers, reversal/correction paths).
Implement ledger entry schema (TSD §3.2): six entry types, currency match to
Phase native currency (Q6), `previous_entry_hash` chain, signature field
shape. Implement Outstanding Target as a pure fold:
@ -108,11 +131,19 @@ hosted append service is out of scope.
```task
id: TREV-WP-0002-T04
status: todo
status: done
priority: medium
state_hub_task_id: "8454269e-fb3d-4751-b564-ef0cc33f9c97"
```
Result 2026-07-28: `schemas/extension_contract.schema.json` +
`validation.validate_extension_contract` /
`check_extension_core_term_redefinition` (documented as a Stage 0 pattern
heuristic, not full semantic review). Four working-default-Q11 fixtures
under `examples/phase-001/extensions/` (all `registered`); one deliberately
non-conforming fixture at `tests/fixtures/non_conforming_extension.json`.
Covered by `tests/test_extension_conformance.py` (9 tests).
Implement Monetization Extension Contract schema (TSD §3.3) and conformance
check: required fields; `allocation.rule` must not redefine core terms.
Support status values `registered` / `canonical` / `deprecated` as data;
@ -125,11 +156,18 @@ practical).
```task
id: TREV-WP-0002-T05
status: todo
status: done
priority: high
state_hub_task_id: "e60c8ccf-cd98-4b15-8ad2-e7718b08acc4"
```
Result 2026-07-28: `schemas/conversion_attestation.schema.json` +
`src/target_revenue/conversion.py` (`conversion_status`,
`generate_attestation`). `conversion_status` never reads an attestation
file; `generate_attestation` raises `ValueError` if called before Outstanding
Target actually reaches zero. Covered by `tests/test_conversion.py` (5
tests) plus the generated `examples/phase-001/attestation.json`.
Implement Conversion Event detection as pure read over Manifest + fold
(Outstanding Target reaches zero) and Conversion Attestation **document
schema** / optional generator (TSD §3.5). Enforce: attestation is never a
@ -140,11 +178,19 @@ an attestation file (PRD FR-7 / G6; working default Q13).
```task
id: TREV-WP-0002-T06
status: todo
status: done
priority: medium
state_hub_task_id: "90711ebf-3d89-4b45-8300-489f39cfa3cc"
```
Result 2026-07-28: `examples/phase-001/` (manifest, six-entry ledger, four
extension fixtures, generated attestation) built via
`scripts/generate_golden_phase.py` so the hash chain is computed by the
library itself, never hand-typed. Full pytest suite: 32 tests across
`tests/test_manifest_validation.py`, `tests/test_ledger_fold.py`,
`tests/test_extension_conformance.py`, `tests/test_conversion.py` — all
passing, no network dependency (`python3 -m pytest tests/`).
Build `examples/phase-001/` (or equivalent) exercising concept §23:
- Initial Target $100,000;