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	active	claude	infotech	2026-07-28	2026-07-28	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: todo
priority: high
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. 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." 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 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).