target-revenue/workplans/TREV-WP-0002-trust-service-foundation.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id	supersedes_title
TREV-WP-0002	workplan	Trust Service foundation — schemas, pure fold, golden fixture	infotech	target-revenue	finished	claude	infotech	2026-07-28	2026-07-29	2b31c2c6-7c68-4c66-ae26-5f25e91a9af0	Trust Service implementation bootstrap

Trust Service foundation — schemas, pure fold, golden fixture

Rescoped (2026-07-28) from “Trust Service implementation bootstrap” per history/260728-SWOT-Assessment.md I-05 and SCOPE.md sequencing rules.

This workplan delivers the runnable specification foundation for the Trust Layer (PRD NFR-1, NFR-3; TSD §3, §5, §6) without a hosted multi-user Trust Service:

• machine-readable schemas;
• pure Outstanding Target fold and offline validators;
• golden Phase package (examples/) from concept §23;
• conversion status as a pure function of Manifest + Ledger (attestation optional evidence only).

It does not implement Phase Registry hosting, multi-tenant ledger APIs, metrics productization, production key management, or federation (PRD Roadmap Phases 4 service, 6–7). Those require a later workplan after WP-0003 normative extract and a Trust Service PRD (SCOPE.md §3–§4).

Depends on / parallels: Working defaults in specs/OpenQuestions-WorkingDefaults.md (currency, longstop, Future License enum, hash/signature Stage 0 choices). Normative prose extract is WP-0003; keep schema field names aligned with TSD §3 and that extract.

Human gate: Task T01 (library stack ADR) MUST NOT be marked done without explicit human accept if it locks language/runtime for the repo.

Record library stack ADR (schemas + fold only)

id: TREV-WP-0002-T01
status: done
priority: high
state_hub_task_id: "bdaa3e6a-e13d-4d4f-a6b0-9c56c18850a9"
human_accept_required: true
human_accepted_by: Bernd
human_accepted_at: "2026-07-29"

Result 2026-07-28: Drafted docs/adr/ADR-0001-stage0-library-stack.md — Python 3.11+, jsonschema, pytest, hatchling src-layout; SHA-256 canonical-serialization hash chain; Ed25519 signing. T02–T06 were implemented against this proposal so work could proceed in parallel, per the workplan note that "agents may draft the ADR for review."

Result 2026-07-29: Human accept received ("The stack as proposed is fine.") — ADR-0001 updated to status: accepted. Task closed.

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 serialization for hashing, and signature approach consistent with OpenQuestions-WorkingDefaults.md Q14 (SHA-256 chain, Ed25519 for examples).

Do not select production database hosting, multi-tenant ops, or federation protocols in this ADR. Full service storage ADRs wait for a later Trust Service implementation workplan.

Human accept gate: Required before treating the ADR as locking repo technology choices. Agents may draft the ADR for review.

Phase Manifest schema and pure conformance validator

id: TREV-WP-0002-T02
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:

• Required fields per TSD §3.1;
• phase.longstop_at required (working default Q8);
• future_license ∈ {MIT, Apache-2.0} (Q3);
• immutability rules documented for phase.id and initial target after credits (enforced in validator docs; registry service not required).

Reject non-conformant manifests offline. No hosted Phase Registry in this workplan.

Target Ledger schema, hash chain, and pure Outstanding Target fold

id: TREV-WP-0002-T03
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:

max(0, T0 − Σ development-credit effective − Σ remission-credit effective)

with reversals/corrections as compensating entries (Rule 8). No update/delete API. Folder layout under schemas/ + library/CLI fold is sufficient; hosted append service is out of scope.

Extension contract schema and conformance validator

id: TREV-WP-0002-T04
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; canonical promotion remains a documented human/governance action (not automated). Include at least one conforming and one deliberately non-conforming extension fixture (align names with working default Q11 where practical).

Conversion detection and attestation schema (evidence only)

id: TREV-WP-0002-T05
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 precondition for conversion status; tooling must recompute conversion without an attestation file (PRD FR-7 / G6; working default Q13).

Golden Phase package and conformance suite

id: TREV-WP-0002-T06
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;
• mixed Development/Remission credits through Outstanding Target zero;
• expected fold series and optional attestation matching final totals.

Automated suite: valid/invalid manifests, hash-chain integrity, extension conformance, full lifecycle fold. Prefer tests runnable without network services.

Deferred (not tasks of this workplan)

Do not implement under WP-0002:

• Hosted Phase / Extension Registry services
• Multi-user ledger append API and auth
• Metrics product and forecasts UI
• Federation replication protocol
• Production operator continuity SLA

Track those only after WP-0003 Stage 0 normative extract and an explicit Trust Service PRD / successor workplan (SCOPE.md §4).