target-revenue/specs/TrustServiceOnboarding.md

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-<slug>.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 <manifest-path> (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 <trust-service-url> --token-env <ENV_VAR_NAME> --manifest <path>. 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 <path> 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.