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

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

```task
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

```task
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

```task
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

```task
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)

```task
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

```task
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).