target-revenue/specs/TrustServiceProductRequirementsDocument.md

Trust Service — Product Requirements Document

Status: Draft v0.1 Date: 2026-07-29 Owner: target-revenue initiative Workplan: workplans/TREV-WP-0006-trust-service-implementation.md T01 Primary artifacts: specs/ProductRequirementsDocument.md (framework-level PRD; this document is its Phase 4b elaboration, not a replacement), specs/TechnicalSpecificationDocument.md §3 (schemas) and §4 (component architecture), specs/TargetRevenueLicenseConcept.md §14 (Trust Service normative source) Terminology alignment: This document does not redefine terms already normatively defined in specs/TargetRevenueLicenseConcept.md / specs/TargetRevenueFrameworkCore.md. It elaborates FR-8, FR-9, FR-10 from specs/ProductRequirementsDocument.md §8 into a hosted-service requirements set.

---

1. Purpose and relationship to the framework PRD

specs/ProductRequirementsDocument.md already states, at the framework level, that a Trust Service must exist and roughly what it must do (FR-8 Phase/Extension Registries, FR-9 Metrics, FR-10 evidence tiering) and that a hosted implementation is Phase 4b, distinct from Phase 4a's offline library (WP-0002, finished). This document is that Phase 4b elaboration: it takes the same requirements and specifies them at the level a hosted, multi-tenant, network-accessible service needs — stakeholders, authentication/authorization boundary, API surface shape, and operational requirements — without re-deriving or restating the underlying Phase/Ledger/Conversion semantics, which remain governed by specs/TechnicalSpecificationDocument.md §3 and are not reopened here.

What this document is not: it is not a replacement for the TSD's data model (§3.1–§3.5), not a new source of truth for core terms, and not a license or governance document. Hosting decisions here must not create a second, competing definition of any schema field.

---

2. Stakeholders

Stakeholder	Interest
Licensor (Phase declarer)	Declare Phases, receive Development/Remission Credit entries, trigger Conversion Events truthfully and without needing to run their own infrastructure
Commercial Entitlement holder (Customer)	Verify their payments are correctly recorded; confirm Outstanding Target status before/after purchase; access their own evidence
Independent auditor / conformance checker	Recompute Outstanding Target and conversion status from public data alone, without trusting the Trust Service's own conclusions
Enforcement Partner (specs/EnforcementNetworkConcept.md)	Read the public Breach/Compliance Record and Enforcement Registry to identify and evidence Alleged Violations
Downstream software consumer	Determine, for a given Milestone Release, whether it has converted and under what Future License
Framework maintainer (this repo)	Operate a reference instance; ensure no code path becomes a discretionary conversion gate (design guardrail 1, TSD §2)
Future federated Trust Service operator	Stand up an independent, interoperable instance without a data-model migration (NFR-3)

This is a strict superset of WP-0002's Stage 0 scope, which had exactly one implicit stakeholder: a developer running the pure-fold library locally against one golden Phase.

---

3. What Stage 0 already guarantees — inherited unchanged

The hosted service inherits these guarantees from WP-0002 (src/target_revenue/) without modification. Any Trust Service implementation task (T03–T08) that would weaken one of these must be treated as a design defect, not an acceptable trade-off:

1. Determinism (TSD §6.1). Given the same Phase Manifest and ordered Ledger, Outstanding Target computation is a pure fold — no hidden state, no floating-point-order sensitivity, no timezone ambiguity. Hosting adds an API in front of this fold; it must not add hidden inputs to it.
2. Offline verifiability (TSD §5). A complete Phase evidence package (manifest, ledger, extensions, attestation) must remain independently recomputable by a third party with no dependency on the Trust Service's own runtime or its being reachable. The hosted service's job is to serve this package, not to be the only thing that can interpret it.
3. No Trust Service discretion over conversion (TSD §2 guardrail 1, §4.1). No hosted code path may hold a conversion decision. Conversion is true the moment the ledger fold reaches Outstanding Target = 0; the Attestation service publishes that fact after it is already true (TSD §3.5) and its absence or delay must never be interpretable as "not yet converted."
4. Append-only ledger semantics (TSD §3.2, guardrail 5). Hosting must not introduce an update or delete path for a settled entry, including via an admin API, a support workflow, or a "fix a typo" convenience feature. Corrections are new compensating entries, full stop.
5. Closed core vocabulary (TSD guardrail 2). Phase, Milestone Release, Initial Target, Development Credit, Remission Credit, Outstanding Target, Conversion Event, Future License carry identical meaning in every hosted API response as in the offline schemas — no hosting-layer renaming, aliasing, or "friendlier" field for external consumers that could drift from the schema's own field.

---

4. Stage-0-only constraints that must now be lifted

WP-0002 deliberately left these unresolved because a single-developer, single-golden-Phase offline library did not need them. The hosted service does. Each of these is now in scope for WP-0006 (assigned to the tasks noted) rather than a silent scope creep:

Stage 0 constraint	Why it existed	What lifting it requires	Owning task
Single golden Phase (examples/phase-001/)	Proof of concept for the pure fold; no need to distinguish Phases at storage level	Multi-Phase storage with globally unique phase.id as the partition key (already schema-required, TSD §3.1)	T03 (Phase/Extension Registry hosting)
No authentication	Local library, no network boundary	Identify who may append a Ledger entry for a given Phase (the Licensor or its authorized Trust Service instance, per TSD §3.2 entry.signature), and who may read confidential vs. public evidence tiers (FR-10)	T04 (ledger append API)
No multi-tenancy	One repo, one Phase, one operator	Isolate Phases belonging to different Licensors so one Licensor cannot read another's confidential evidence or, worse, append to another's ledger	T03, T04
No network-facing API	Library was called in-process by tests	Define the actual request/response surface (§6 below) that external Customers, auditors, and Enforcement Partners can call	T04, T06
No metrics computation service	Fold was run ad hoc in tests	A running service computing and republishing FR-9's metrics on a schedule or on-demand, labeled fact/calculation/forecast per TSD §4.1 Metrics component's forbidden-action list	T05
No attestation publication mechanism	Conversion status was just recomputed by the test suite	A service that publishes a signed Conversion Attestation (TSD §3.5) once it independently observes Outstanding Target = 0 — as a public statement of an already-true fact, never a gate	T06
No Breach/Compliance Record component	This component postdates WP-0002 (added with License V1C1 §7.4, TSD §4.1 note)	A publication surface distinguishing alleged from determined breach status, defaulting to the anonymized Phase-and-category record per FR-10's 2026-07-29 revision, with named disclosure only where a Commercial Use Agreement's naming clause (License Appendix A item 10 / CUA Appendix A item 6) opts in	Not yet assigned a T0x — flagged as a gap this document surfaces; candidate for a new T09 or folding into T06
No repo/onboarding process	Nothing to onboard; this was the only Phase	A defined process for a new product line (per WP-0008's four target product lines) to register its first Phase against a running instance	T07 (multi-repo onboarding)
No hosted conformance suite	tests/ ran against the one golden fixture, locally	A conformance suite any Phase/extension author can run against a live instance before or after registration, mirroring TSD §5's two independent checks	T08

---

5. Functional requirements (hosted-service elaboration of framework PRD FR-8/9/10)

TS-FR-1 — Phase registration and immutability enforcement

The service shall accept a Phase Manifest for registration, validate it against TSD §3.1 (Required fields, immutability rules), and reject non-conformant manifests with a field-by-field diff — never a partial or silent acceptance. Once registered, phase.id and phase.initial_target.amount are immutable except through the versioned correction path TSD §3.1 already specifies; the hosted API must not expose any endpoint that could bypass this (e.g., a generic "update manifest" PATCH).

TS-FR-2 — Extension registration and status assignment

The service shall accept Monetization Extension registrations, validate against TSD §3.3's contract (including the non-redefinition rule for the seven closed core terms — specs/TargetRevenueFrameworkCore.md §1.11), and assign status: registered automatically on passing conformance. Promotion to status: canonical is a documented human/governance action (TSD §4.1, specs/MonetizationExtensionSpecification.md §4) — the hosted service must expose who performed a canonicalization and when, but must never perform it automatically.

TS-FR-3 — Ledger append API with authenticated, phase-scoped write access

The service shall expose an append-only write path for Target Ledger entries (TSD §3.2), scoped so that only the Licensor (or its designated Trust Service instance, for federated cases) can append for a given phase.id. Every accepted entry must be chained (previous_entry_hash) and signed (entry.signature) before being considered committed. The API must reject, not merge or reorder, any entry submission that does not extend the current chain tip.

TS-FR-4 — Public read access to ledger facts, gated confidential evidence

Per FR-10 (framework PRD) and TSD §6.2: aggregate Development/Remission Credit, Outstanding Target, applicable extensions, and conversion status are public and unauthenticated. entry.evidence_reference targets that use the confidential: scheme resolve only for authenticated, authorized parties (the Licensor, and any party the Licensor or applicable dispute process designates — e.g., an Enforcement Partner with a live Alleged Violation, per specs/EnforcementNetworkConcept.md). Private commercial data underlying an entry is never required to be uploaded to the service at all (framework PRD FR-10 acceptance criterion 3) — the hosted service must not silently start requiring it as a side effect of adding authentication.

TS-FR-5 — Metrics computation and labeling

The service shall compute and publish, per Phase: target satisfaction percentage, Development Credit velocity, Remission Credit velocity, time since last material progress (framework PRD FR-9). Every published figure must be labeled as one of fact (a ledger-derived value), calculation (a deterministic derivation, e.g. a percentage), or forecast (a projection, e.g. an estimated conversion date) — and a forecast must never be positioned where a fact is expected by API shape or documentation (TSD §4.1 Metrics component's forbidden action).

TS-FR-6 — Conversion Attestation publication as an observed fact

Once the service's own recomputation of a Phase's ledger fold reaches Outstanding Target = 0, it shall publish a signed Conversion Attestation (TSD §3.5) as a public record of an already-true fact. The service must document, and the API must make independently checkable, that conversion status can be recomputed by any external party from the raw Manifest and Ledger alone — the Attestation's absence, delay, or the service being unreachable must never be treated by any conformant tooling as evidence that conversion has not occurred.

TS-FR-7 — Breach/Compliance Record publication

The service shall publish breach and termination determinations under License V1C1 §7.4, distinguishing alleged (Licensor has given notice) from determined (cure period expired or breach otherwise established per the License's own terms) status, defaulting to an anonymized Phase-and-category record. Named disclosure of the Commercial Entitlement holder occurs only where the applicable Commercial Use Agreement's naming/disclosure clause (CUA §9, License Appendix A item 10) opts in, following that clause's notice period. The service must never itself adjudicate whether a breach occurred — it publishes the Licensor's determination, not its own (TSD §4.1 table, "Forbidden" column).

TS-FR-8 — Multi-repo / multi-tenant isolation

The service shall support Phases from multiple, independent Licensors/repos concurrently (the immediate driver being the four coulomb-org product lines in workplans/TREV-WP-0008-governance-and-pilot-rollout.md), with write access and confidential-evidence read access strictly isolated per Licensor. A defect that allows Licensor A to append to or read Licensor B's confidential evidence is a security-severity defect, not an enhancement backlog item.

TS-FR-9 — Hosted conformance suite

The service shall expose a way for any Phase or extension author to conformance-check a manifest or extension against TSD §5's two checks (manifest conformance, extension conformance) before or independent of registration — as a live-instance analogue to tests/'s offline conformance tests, not a new or divergent conformance definition.

---

6. API surface shape (non-binding sketch, not an interface freeze)

This section previews the request/response surface WP-0006-T04's ADR and implementation must produce; it does not fix a transport, framework, or wire format (that is explicitly T02's decision, not this PRD's).

• Write, authenticated, phase-scoped: register Phase Manifest; register Extension; append Ledger entry.
• Write, human/governance-gated: promote Extension to canonical; publish a breach/termination determination (Licensor-originated, service-recorded).
• Read, public, unauthenticated: Phase Manifest (public fields); ledger facts/aggregates; metrics (labeled); conversion status; Conversion Attestation; anonymized Breach/Compliance Record.
• Read, authenticated, scoped: confidential evidence references; named Breach/Compliance Record (where CUA-opted-in); a Licensor's own full ledger detail.
• Verification, no authentication required: given an exported evidence package (TSD §3, FR-8 acceptance criterion 3), recompute Outstanding Target and conversion status independent of this service being reachable at all.

---

7. Non-functional requirements (hosted-service elaboration of TSD §6)

ID	Requirement	Source
TS-NFR-1	Determinism: identical Manifest + Ledger input yields identical Outstanding Target regardless of which Trust Service instance computes it	TSD §6.1, inherited unchanged (§3 above)
TS-NFR-2	Auditability: every ledger entry resolves to an evidence reference for an authorized party; the hash chain is independently verifiable without trusting the serving infrastructure	TSD §6.2
TS-NFR-3	Federation readiness: identifiers remain meaningful and collision-free if this instance is later joined by, or replaced by, another conformant instance	TSD §6.3
TS-NFR-4	Legal determinacy: no hosted API response may introduce ambiguity about a Conversion Event's timing that the underlying schema did not already have	TSD §6.4
TS-NFR-5	Availability is explicitly not a legal-effect dependency: per TS-FR-6, downtime must never be interpretable as "conversion paused"	Derived from guardrail 1 (TSD §2)
TS-NFR-6	Multi-tenant isolation: a Licensor's confidential data is never exposed to another Licensor or an unauthenticated caller	§5 TS-FR-4, TS-FR-8

---

8. Explicit non-goals for this document

• Selecting a storage engine, hosting provider, or auth mechanism — that is WP-0006-T02 (stack ADR), a distinct, human-gated decision.
• Drafting the CUA naming/disclosure clause's operative text — that already exists (specs/TargetRevenueCommercialUseAgreement-V1C1.md §9); this document only specifies how the Trust Service must respect it.
• Resolving the degeneration policy or canonical profile catalog — that is workplans/TREV-WP-0007-degeneration-policy-and-canonical-profiles.md, a parallel workplan this service must be able to serve once finished, not redo.
• Authorizing any real Phase to go live — gated behind workplans/TREV-WP-0008-governance-and-pilot-rollout.md T05, unaffected by this document's completion.

---

9. Traceability

This document	Elaborates	Must not contradict
§3 (inherited guarantees)	—	specs/TechnicalSpecificationDocument.md §2, §6
§4 (lifted constraints)	workplans/TREV-WP-0006-trust-service-implementation.md T03–T08	TSD §1.2/§1.3
§5 TS-FR-1–2	Framework PRD FR-8	TSD §3.1, §3.3, §5
§5 TS-FR-3–4	Framework PRD FR-8, FR-10	TSD §3.2, §6.2
§5 TS-FR-5	Framework PRD FR-9	TSD §4.1 Metrics row
§5 TS-FR-6	Framework PRD FR-7 (via TSD §3.5)	TSD §3.5 legal-technical rule
§5 TS-FR-7	Framework PRD FR-10 (2026-07-29 revision)	License V1C1 §7.4, CUA §9, TSD §4.1 Breach/Compliance Record row