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:
parent
658b1af00d
commit
57c7111cbc
28 changed files with 1751 additions and 7 deletions
128
docs/adr/ADR-0001-stage0-library-stack.md
Normal file
128
docs/adr/ADR-0001-stage0-library-stack.md
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
---
|
||||
id: ADR-0001
|
||||
title: "Stage 0 library stack: schemas, pure fold, and validators"
|
||||
status: proposed
|
||||
date: 2026-07-28
|
||||
decided_by: null
|
||||
workstream: TREV-WP-0002 (trust-service-foundation)
|
||||
alternatives_considered: [TypeScript/Node, Go]
|
||||
---
|
||||
|
||||
# ADR-0001 — Stage 0 Library Stack (Schemas, Pure Fold, Validators)
|
||||
|
||||
## Status
|
||||
|
||||
**Proposed.** Per `CONTRIBUTING.md` "Human decision gates" and
|
||||
`workplans/TREV-WP-0002-trust-service-foundation.md` T01, this ADR locks
|
||||
implementation technology for the repository and **must not be treated as
|
||||
accepted without explicit human sign-off**. Agents may implement against
|
||||
this proposal, but WP-0002-T01 stays `todo` (not `done`) until a maintainer
|
||||
accepts or revises it.
|
||||
|
||||
## Scope
|
||||
|
||||
This decision covers **only** the Stage 0 deliverables of WP-0002:
|
||||
|
||||
- JSON Schema (or equivalent) definitions for Phase Manifest, Target Ledger
|
||||
Entry, Extension Contract, Transaction Allocation, Conversion Attestation;
|
||||
- a pure, deterministic Outstanding Target fold;
|
||||
- offline conformance validators;
|
||||
- a golden Phase package and its test suite.
|
||||
|
||||
It explicitly does **not** cover: hosted Phase/Extension Registry services,
|
||||
multi-tenant ledger APIs, a metrics product, or a federation protocol
|
||||
(`SCOPE.md` §3–§4). Those require a separate, later ADR once a Trust Service
|
||||
implementation workplan exists.
|
||||
|
||||
## Context
|
||||
|
||||
`specs/TechnicalSpecificationDocument.md` §10 is deliberately non-binding on
|
||||
language, runtime, and storage. Something has to be chosen to write the
|
||||
Stage 0 library, but the choice should be cheap to revisit later since the
|
||||
hosted Trust Service is a different, larger decision.
|
||||
|
||||
Requirements pulled from TSD §3, §6 and `specs/OpenQuestions-WorkingDefaults.md`
|
||||
Q14:
|
||||
|
||||
- deterministic, pure computation (no hidden state, no floating-point order
|
||||
sensitivity) for the Outstanding Target fold;
|
||||
- JSON-Schema-shaped validation that a non-Python tool could later
|
||||
reimplement against the same `.schema.json` files;
|
||||
- SHA-256 canonical-serialization hash chaining and Ed25519 signatures over
|
||||
the same canonical bytes;
|
||||
- a test suite runnable offline, with no network services.
|
||||
|
||||
## Decision
|
||||
|
||||
**Python 3.11+, `jsonschema` for schema validation, dataclasses for typed
|
||||
domain objects, `pytest` for the conformance suite, `hatchling` src-layout
|
||||
packaging.**
|
||||
|
||||
Canonical serialization for hashing: JSON with sorted keys, no insignificant
|
||||
whitespace, UTF-8 encoding (`json.dumps(..., sort_keys=True,
|
||||
separators=(",", ":"))`), hashed with SHA-256. Signatures: Ed25519 via
|
||||
`cryptography` or `PyNaCl`, over the same canonical bytes.
|
||||
|
||||
## Rationale
|
||||
|
||||
| What Stage 0 needs | Python fit |
|
||||
|---|---|
|
||||
| JSON Schema authoring and validation | `jsonschema` is a direct, widely-used implementation |
|
||||
| Pure fold over ledger entries | Trivial with dataclasses + `functools.reduce`; no framework needed |
|
||||
| Canonical serialization + hashing | Stdlib `json` + `hashlib` sufficient |
|
||||
| Ed25519 signing for examples | `cryptography` covers this without custom crypto code |
|
||||
| Offline conformance test suite | `pytest` is the de facto standard; matches this workspace's other Python repos (e.g. `shard-wiki`) |
|
||||
| Low ceremony for a schema/fold library, not a service | Python's scripting ergonomics outweigh static-typing benefits at this scope |
|
||||
|
||||
### Why not TypeScript/Node
|
||||
|
||||
Would be a reasonable alternative if the primary consumer were browser-based
|
||||
tooling (cf. `binect-js`), but Stage 0 has no UI deliverable — it is a
|
||||
schema + pure-function library consumed by CLI/tests. Node adds packaging
|
||||
overhead (npm registry, `package.json` versioning discipline) without a
|
||||
corresponding benefit here.
|
||||
|
||||
### Why not Go
|
||||
|
||||
Go would fit well if this were becoming a long-lived, standalone,
|
||||
performance-sensitive service (cf. `key-cape` ADR-0001's reasoning) — but
|
||||
Stage 0 is explicitly **not** the hosted Trust Service. A statically-typed,
|
||||
compiled toolchain is more ceremony than a schema/fold/test library needs at
|
||||
this stage. Revisit for the later hosted-service ADR.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Fast path to a working, testable schema + fold library.
|
||||
- `jsonschema` files are directly reusable by a future non-Python
|
||||
implementation (hosted service ADR is unconstrained by this choice).
|
||||
- Matches existing Python conventions in this workspace (pytest, hatchling
|
||||
src-layout) for reviewer familiarity.
|
||||
|
||||
### Negative / risks
|
||||
|
||||
- Python's dynamic typing means domain-model discipline must be enforced by
|
||||
convention (dataclasses + docstrings + tests), not the compiler.
|
||||
- Should not be read as a decision about the hosted Trust Service's stack —
|
||||
that is explicitly deferred and must not be assumed to inherit this choice
|
||||
without its own ADR.
|
||||
|
||||
### Compensating guardrails
|
||||
|
||||
1. Typed domain objects (`dataclasses`, `frozen=True` where the schema marks
|
||||
a field immutable) — no raw dicts crossing function boundaries in
|
||||
`fold.py` or `conversion.py`.
|
||||
2. All schema validation goes through the `.schema.json` files under
|
||||
`schemas/` — no ad hoc field checks duplicated in Python without a
|
||||
corresponding schema entry.
|
||||
3. The fold function must be pure: same `(manifest, entries)` input always
|
||||
produces the same Outstanding Target output, with no I/O.
|
||||
|
||||
## Revisit trigger
|
||||
|
||||
Reconsider this decision when a hosted Trust Service implementation
|
||||
workplan is opened (`SCOPE.md` §3 "Production Trust Service"). That
|
||||
decision should weigh multi-tenant hosting, storage, and operational
|
||||
concerns not in scope here, and may reasonably choose a different stack
|
||||
without invalidating this one.
|
||||
Loading…
Add table
Add a link
Reference in a new issue