# Trust Service Onboarding: Multi-Repo Registration Mechanism Status: Draft v0.1 Date: 2026-07-29 Workplan: `workplans/TREV-WP-0006-trust-service-implementation.md` T07 Primary artifacts: `specs/PhaseManifestSpecification.md`, `specs/TargetLedgerSpecification.md`, `specs/TrustServiceProductRequirementsDocument.md`, `docs/adr/ADR-0002-hosted-trust-service-stack.md`, `scripts/trf_onboard.py` **Scope note:** this document defines the **mechanism** by which any repo registers a Phase against a running hosted Trust Service instance. It does **not** select which repos or Phases go first — that is `workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T02 (repo/Phase survey) and T03 (draft pilot manifests), which use this mechanism rather than redefine it. It also does not authorize any real Phase to go live — that remains gated behind WP-0008-T05 regardless of how well this mechanism works. --- ## 1. What a repo commits to itself vs. submits to the Trust Service A recurring confusion this document exists to close: a Phase Manifest is **not** solely a Trust Service database row. It has two authoritative copies with different roles, and both are required, not just one: | Artifact | Lives in | Role | |---|---|---| | Phase Manifest file (e.g. `trf/phase-.json`) | The declaring repo's own version control, committed | The repo's own durable, git-history-backed record of what it declared and when — survives independent of any Trust Service instance's uptime or even existence (TSD §1.2's offline-verifiability property applies here too: this file alone, plus its ledger export, must remain independently foldable forever). | | The same Phase Manifest, registered | The hosted Trust Service's `phase_manifests` table (`migrations/0001_registries.sql`) | The multi-tenant, queryable, publicly-servable copy other parties (Customers, auditors, Enforcement Partners) read without needing access to the declaring repo at all. | | Target Ledger entries | The hosted Trust Service's `ledger_entries` table only | Per ADR-0002, the Ledger's authoritative live copy is the hosted service once a Phase is registered there — a repo does **not** also maintain a second, competing ledger file post-registration (that would reintroduce exactly the "which copy is authoritative" ambiguity Stage 0's single-golden-fixture model never had to answer). A repo *may* keep periodic exports for its own archival/offline-verification purposes (§4 below), but those are copies, not a second source of truth. | | Extension registrations, Conversion Attestation | The hosted Trust Service, per T03/T06 | Same reasoning as the Ledger. | **Rule of thumb:** anything that must exist and remain meaningful even if this Trust Service instance is retired, replaced, or briefly down belongs committed to the repo (the Manifest declaration itself). Anything that must be a single, live, multi-party-queryable authority belongs exclusively in the hosted service once registered (the Ledger). ## 2. Licensor bootstrapping (out of band, not part of this mechanism) Before any repo can register a Phase, its Licensor identity must already be resolved (`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T01) and a row must exist in the `licensors` table with an issued API token (`migrations/0001_registries.sql`). This document assumes that step has already happened; it is a governance action, not a mechanical one, and is explicitly out of this task's scope. The token itself must never be committed to the repo — it is a deployment secret (CI secret store, environment variable at declaration time), referenced by name in the repo's own tooling, never by value. ## 3. Step-by-step mechanism 1. **Author the Phase Manifest locally**, conforming to `specs/PhaseManifestSpecification.md` and `schemas/phase_manifest.schema.json`, following the shape already established by `examples/phase-001/manifest.json`. 2. **Validate offline before doing anything else** — `python -m target_revenue.validation` equivalent via `scripts/trf_onboard.py validate ` (wraps `validation.validate_phase_manifest`, the same check the hosted service itself runs at registration, so a rejection is caught locally with the identical field-by-field diff rather than discovered only via a failed network call). 3. **Commit the Manifest file to the repo** before registering it — this preserves a git-history record of intent to declare, independent of whether registration succeeds on the first attempt. 4. **Register**: `scripts/trf_onboard.py register-phase --url --token-env --manifest `. Performs the same offline validation as step 2 again (defense in depth — a manifest edited after step 2 but before this step must still be caught), then `POST /phases`. 5. **Append Ledger entries as commercial payments are recognized.** In practice this step is automated by whatever billing/payment pipeline the product line already uses, not run manually per payment — `scripts/trf_onboard.py append-entry --url ... --token-env ... --phase-id ... --entry ` is the mechanism that pipeline calls, or a template for it. 6. **Monitor via the public, unauthenticated read endpoints** — `scripts/trf_onboard.py status --url ... --phase-id ...` (wraps `GET /phases/{id}/metrics`) — no token needed for this step, since metrics are public per FR-9/FR-10. 7. **Conversion and Attestation require no onboarding action at all.** Per WP-0006-T06, the moment the ledger fold reaches `Outstanding Target = 0`, conversion is already true; the Trust Service publishes the Attestation on first observation. Nothing in this mechanism gates on, waits for, or triggers that separately. ## 4. Offline verifiability remains intact after hosting Any party — including the declaring repo itself, independent of the Trust Service's continued availability — can export a Phase's current Ledger via `GET /phases/{id}/ledger` (public) and independently recompute Outstanding Target with `target_revenue.fold.fold_outstanding_target` against the committed Manifest file. This is the same offline-first property `docs/adr/ADR-0002-hosted-trust-service-stack.md` and `specs/TrustServiceProductRequirementsDocument.md` §3 require the hosted service to preserve, not a new guarantee invented for onboarding — this section just makes explicit that a repo can exercise it as part of its own routine (e.g., a periodic CI job that exports and re-verifies), not only a theoretical possibility. ## 5. Explicit non-goals - Selecting which of `coulomb-loop`, `net-kingdom`, `helix-forge`, or a `railiance-*` repo registers first, or which Milestone Release qualifies — `workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T02/T03. - Resolving Licensor identity — WP-0008-T01. - Authorizing any registration performed via this mechanism to bind real money or a real License header change — WP-0008-T05, unaffected by this mechanism existing or working correctly. - A CI/CD template for automated payment-pipeline integration — a reasonable future deliverable once a real pilot Phase's billing pipeline is known, not invented speculatively here.