tegwick
82024bd6a8
Bernd accepted the Stage 0 library stack (Python, jsonschema, pytest, hatchling) as proposed. Marks ADR-0001 accepted, closes WP-0002-T01, and marks the WP-0002 workplan finished (all six tasks done). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
218 lines
8.6 KiB
Markdown
218 lines
8.6 KiB
Markdown
---
|
||
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).
|