target-revenue/docs/adr/ADR-0001-stage0-library-stack.md

id	title	status	date	decided_by	workstream	alternatives_considered
ADR-0001	Stage 0 library stack: schemas, pure fold, and validators	proposed	2026-07-28	null	TREV-WP-0002 (trust-service-foundation)	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.