TechnicalSpecificationDocument

*Technical structure for the Target Revenue Framework (TRF)*

# Technical Specification (TSD)

## Target Revenue Framework — Schemas, Layers, and Trust Service Orientation

**PRD-aligned / Pre-Implementation Version**

---

## 0. Positioning and Authority

This Technical Specification derives its authority **exclusively from `specs/ProductRequirementsDocument.md`** and serves as a **design-orientation document**, not a binding implementation plan.

It:

* translates the PRD's functional requirements into concrete data structures, component boundaries, and conformance rules;
* makes explicit what is **normative now**, what is **deferred to later specification work**, and what is **intentionally left open**;
* avoids encoding legal text, pricing decisions, or a fixed technology stack — those belong to the Legal Layer, canonical profiles, and future ADRs respectively.

Where a term, formula, or rule is already normatively defined in `spec/TargetRevenueLicenseConcept.md`, this document references it rather than restating it with variation. Where the PRD leaves a question open (PRD §14), this TSD does not resolve it by implication.

---

## 1. System Composition

The Target Revenue Framework, as it exists in this repository, is **currently a specification and schema artifact set**, not a running system. Two composition states apply:

### 1.1 Current state — documentation and schema repository

* `INTENT.md` — durable purpose and strategic boundaries.
* `spec/TargetRevenueLicenseConcept.md` — normative concept: terminology, formulas, rules, lifecycle.
* `specs/ProductRequirementsDocument.md` — product goals, scope, functional/non-functional requirements.
* `specs/TechnicalSpecificationDocument.md` (this document) — schema and component-boundary orientation.
* `history/` — dated exploration transcripts, non-normative.

### 1.2 Target future state — reference Trust Service

A centralized reference implementation (PRD §11.1 item 8, Roadmap Phase 4) providing the Phase Registry, Extension Registry, Target Ledger, Metrics, and Conversion Attestation responsibilities defined in `spec/TargetRevenueLicenseConcept.md` §14. This TSD specifies the **data model and component boundaries** that implementation must satisfy; it does not select a language, storage engine, or hosting model.

---

## 2. Design Guardrails (Derived from PRD)

The following constraints are **non-negotiable** and shape all downstream schema and implementation decisions:

1. **No discretionary conversion authority anywhere in the system**
   No component — Trust Service, registry, or metrics engine — may hold a code path whose output is required for a Conversion Event to take legal effect (PRD G6, FR-7).

2. **Core terms are immutable across all schemas**
   `Phase`, `Milestone Release`, `Initial Target`, `Development Credit`, `Remission Credit`, `Outstanding Target`, `Conversion Event`, `Future License` must carry identical meaning in every schema, API, and extension that references them (PRD G1, §6.1).

3. **Determinism over convenience**
   Any calculation that determines the Outstanding Target must be reproducible by an independent implementation from the same Phase Manifest and Ledger alone (PRD NFR-1).

4. **Explicit allocation, never inference**
   No schema may compute a `development_allocation` from a payment amount, monetization label, or heuristic. It must always be an explicit, stored field (PRD FR-2, Rule 2).

5. **Append-only, corrections-not-mutation**
   No schema may support in-place update or deletion of a settled ledger entry. Corrections are new compensating entries (PRD FR-5, Rule 8).

6. **Federation-ready data shapes from the first implementation**
   Every identifier must be globally unique and stable independent of hosting location; every authoritative record must be signable and exportable (PRD NFR-3).

---

## 3. Data Model Specifications

The following schemas formalize the YAML sketches already present in `spec/TargetRevenueLicenseConcept.md` (§16, §17, §12, §18) into typed field tables. Field names and semantics are authoritative from that document; this section adds required/recommended/optional tiering and type constraints per PRD FR-1.

### 3.1 Phase Manifest

| Field | Type | Tier | Notes |
|---|---|---|---|
| `framework` | string (semver-like tag) | Required | e.g. `TRF-0.1`. |
| `license` | string (semver-like tag) | Required | e.g. `TRSL-0.1`. |
| `phase.id` | string (URN, `trsl:phase:<slug>`) | Required | Globally unique; immutable once published. |
| `phase.milestone_release.name` | string | Required | Human-readable release name. |
| `phase.milestone_release.source_revision` | string | Required | Immutable VCS reference. |
| `phase.milestone_release.artifact_sha256` | string (hex digest) | Recommended | Required if a built artifact (not just source) is governed. |
| `phase.initial_target.amount` | decimal | Required | Immutable once Development Credits are accepted (Rule 1). |
| `phase.initial_target.currency` | ISO 4217 code | Required | |
| `phase.target_basis.estimated_effort_days` | decimal | Recommended | Transparency metadata, not legally required. |
| `phase.target_basis.daily_rate` | decimal | Recommended | |
| `phase.target_basis.approved_direct_costs` | decimal | Recommended | |
| `phase.target_basis.target_multiple` | decimal | Recommended | One of the indicative classes (PRD §6.1) or a declared custom value. |
| `phase.future_license` | enum (`MIT`, `Apache-2.0`, ...) | Required | |
| `phase.degeneration_policy` | string (URN, `trsl:policy:<slug>@<version>`) | Required | |
| `phase.ledger` | URL | Required | Location of the authoritative Target Ledger for this Phase. |
| `extensions[]` | list of `trsl:extension:<id>@<version>` | Optional | Applicable monetization profiles/extensions for this Phase. |

**Validation rules:**
- A manifest missing any Required field MUST be rejected at registration (not merely flagged).
- `phase.initial_target.amount` MUST NOT decrease or increase after first publication except through a versioned, historically-visible correction record distinct from ordinary Remission Credit.
- `phase.id` MUST be immutable and MUST NOT be reused across Phases, including a superseded or abandoned Phase.

### 3.2 Target Ledger Entry

| Field | Type | Tier | Notes |
|---|---|---|---|
| `entry.id` | string (URN, `trsl:entry:<ulid>`) | Required | Globally unique, monotonically orderable (ULID or equivalent). |
| `entry.phase` | string (Phase URN) | Required | Must reference an existing, published Phase Manifest. |
| `entry.type` | enum: `development-credit`, `remission-credit`, `credit-reversal`, `remission-correction`, `administrative-correction`, `conversion-checkpoint` | Required | Closed set; not extensible per-project (PRD FR-5). |
| `entry.amount` | decimal | Required | Signed only for reversal/correction types. |
| `entry.currency` | ISO 4217 code | Required | Must match `phase.initial_target.currency` or declare an explicit FX rule (PRD open question §14.6). |
| `entry.recognized_at` | ISO 8601 timestamp | Required | Settlement time, not invoice time (Rule 4). |
| `entry.extension.id` / `entry.extension.version` | string / string | Required for `development-credit`/`remission-credit` | Identifies the monetization profile or degeneration policy that produced the entry. |
| `entry.evidence_reference` | URI (may be `confidential:` scheme) | Required | Must resolve for authorized auditors even when not public. |
| `entry.previous_entry_hash` | string (hex digest) | Required | Cryptographic linkage to the prior entry for this Phase (append-only chain). |
| `entry.signature` | string | Required | Signed by the publishing Trust Service instance. |

**Validation rules:**
- Entries MUST be append-only; a correction is a new entry referencing the corrected entry's `id`, never an edit.
- The Outstanding Target for a Phase MUST be computable as a pure fold over its ordered ledger entries plus the Phase Manifest's `initial_target.amount` (PRD NFR-1); no entry type may require external state to interpret.
- `credit-reversal` and `remission-correction` entries MUST carry a reference to the entry they reverse or correct.

### 3.3 Monetization Extension Contract

| Field | Type | Tier | Notes |
|---|---|---|---|
| `extension.id` | string (URN, `trsl:extension:<slug>`) | Required | |
| `extension.version` | string (semver) | Required | |
| `value.description` | string | Required | What the payer receives. |
| `pricing.method` | string | Required | How the payment is calculated. |
| `allocation.rule` | string (formula or reference) | Required | What portion may become Development Credit. Must be expressible as a pure function of transaction fields. |
| `recognition.event` | enum: `order`, `invoice`, `payment-settled`, `delivery` | Required | When the allocation becomes eligible. |
| `reversal.rule` | string | Required | How refunds, chargebacks, or corrections are handled. |
| `evidence.requirement` | string | Required | What proves the transaction and allocation. |
| `status` | enum: `registered`, `canonical`, `deprecated` | Required (assigned by Trust Service, not the extension author) | `registered` = conformant; `canonical` = reviewed and recommended (PRD FR-4). |

**Conformance rule (PRD FR-4):** An extension is **admissible only if it passes a conformance check** verifying:
1. all Required fields are present and well-typed;
2. `allocation.rule` does not reference or redefine `Phase`, `Initial Target`, `Development Credit`, `Remission Credit`, `Outstanding Target`, `Conversion Event`, or `Future License` — it may only consume transaction-level fields and produce a `development_allocation` output.

A non-conforming extension MUST be rejected at registration, with a field-by-field diff against the contract, not silently accepted with reduced trust.

### 3.4 Transaction Allocation Record

| Field | Type | Tier | Notes |
|---|---|---|---|
| `payment.collected_amount` | decimal | Required | |
| `payment.development_allocation` | decimal | Required | Explicit; MUST NOT be derived from `monetization_type` by any core code path (PRD FR-2). |
| `payment.non_target_allocation` | decimal | Required | `collected_amount − development_allocation`, after taxes/fees/reversals per the applicable extension. |
| `payment.phase` | string (Phase URN) | Required | |
| `payment.monetization_profile` | string (extension URN) | Required | Explanatory label only; has no independent effect on target math. |

### 3.5 Conversion Attestation

| Field | Type | Tier | Notes |
|---|---|---|---|
| `attestation.phase` | string (Phase URN) | Required | |
| `attestation.milestone_release` | string | Required | Matches `phase.milestone_release.name`. |
| `attestation.conversion_timestamp` | ISO 8601 timestamp | Required | The moment the ledger fold first reaches `Outstanding Target = 0`. |
| `attestation.future_license` | enum | Required | Copied from the Phase Manifest at conversion time. |
| `attestation.final_development_credit` | decimal | Required | |
| `attestation.final_remission_credit` | decimal | Required | |
| `attestation.final_outstanding_target` | decimal | Required | MUST equal `0`. |
| `attestation.ledger_checkpoint` | string (hash or entry id) | Required | Points to the last ledger entry included in the fold. |
| `attestation.signature` | string | Required | |

**Legal-technical rule (PRD FR-7, G6):** The attestation is generated **after** the fact of conversion is already true from the ledger; no code path may treat attestation generation as a precondition for the Future License taking effect. An attestation's absence or delay MUST NOT be interpretable as "not yet converted" by any conformant tooling — tooling must independently recompute conversion status from the raw ledger.

---

## 4. Component Architecture

Maps the four-layer architecture from `specs/ProductRequirementsDocument.md` §10 to concrete technical boundaries:

```text
Legal Layer            → TRSL text + Commercial/Service Agreements (documents; no runtime component)
Declarative Layer       → Phase Manifest store, Degeneration Policy registry, Extension registry
                          (schema validation only; no business logic beyond §3 validation rules)
Trust Layer             → Registry service, Target Ledger service, Metrics service,
                          Attestation service (the only components with runtime state)
Federation Layer        → Export/verification tooling, replication protocol, signature
                          verification (consumes Trust Layer output; adds no new authority)
```

**Boundary rule:** Only the Trust Layer holds mutable state (the append-only ledger and registries). The Legal Layer is text; the Declarative Layer is validated-but-static-per-Phase input; the Federation Layer is read-only relative to a single authoritative Trust Service instance. No layer above the Trust Layer may write to it except through the Declarative Layer's validated publication path (Phase Manifest, Extension registration).

### 4.1 Trust Service internal responsibility boundary

Per `spec/TargetRevenueLicenseConcept.md` §14.2, every Trust Service component is limited to: **observe, record, validate conformance, calculate, publish, attest.** None may **decide** whether a conversion occurs — that is a pure function of Manifest + Ledger, computable by any conformant external tool.

| Component | Responsibility | Forbidden |
|---|---|---|
| Phase Registry | Store and serve immutable Phase Manifests | Approving or blocking a Phase's validity beyond schema conformance |
| Extension Registry | Store and serve extension records with `registered`/`canonical` status | Silently promoting an extension to `canonical` without a documented review process (PRD Roadmap Phase 7) |
| Target Ledger | Append entries; serve the entry chain per Phase | Editing, deleting, or reordering settled entries |
| Metrics | Calculate and label facts/calculations/forecasts/recommendations distinctly | Presenting a forecast as if it were a ledger fact |
| Attestation | Publish a signed statement once the ledger fold reaches zero | Requiring its own publication as a condition of conversion |

---

## 5. Conformance Model

Two independent conformance checks are required before this system can be considered specification-complete (PRD MVP acceptance criteria):

1. **Manifest conformance** — a Phase Manifest validates against §3.1's Required-field set and immutability rules.
2. **Extension conformance** — an extension validates against §3.3's contract and does not redefine core terms.

Both checks MUST be implementable as pure, deterministic validation functions with no dependency on Trust Service runtime state, so that any independent party can conformance-check a Manifest or Extension offline.

---

## 6. Non-Functional Orientation

Translating `specs/ProductRequirementsDocument.md` §9 into technical terms:

### 6.1 Determinism
Given identical Phase Manifest + Ledger input, Outstanding Target computation MUST be a pure fold with no hidden state, floating-point-order sensitivity, or timezone ambiguity (all timestamps ISO 8601 UTC).

### 6.2 Auditability
Every ledger entry MUST carry an `evidence_reference` resolvable by an authorized party; the cryptographic chain (`previous_entry_hash`) MUST allow tamper-evidence without requiring trust in the serving infrastructure.

### 6.3 Federation readiness
All identifiers (`phase.id`, `entry.id`, `extension.id`) MUST be globally unique independent of any single Trust Service's hostname, so records remain meaningful after replication or operator change.

### 6.4 Legal determinacy
No schema field may be optional if its absence would make the Conversion Event's timing ambiguous (§3.1, §3.2 Required tiers are drawn conservatively for this reason).

---

## 7. Repository Structure (Current and Near-Term)

```text
target-revenue/
├── INTENT.md
├── README.md
├── LICENSE
├── history/
│   └── 260728-InitialExploration.md
└── specs/
    ├── ProductRequirementsDocument.md
    ├── TechnicalSpecificationDocument.md      (this document)
    └── (near-term, per PRD §11.1 MVP list:)
        ├── TargetRevenueFrameworkCore.md
        ├── TargetRevenueSourceLicense-Draft.md
        ├── PhaseManifestSpecification.md
        ├── TargetLedgerSpecification.md
        ├── TargetDegenerationPolicyResearch.md
        ├── MonetizationExtensionSpecification.md
        ├── CanonicalMonetizationProfiles.md
        ├── TrustServiceProductRequirementsDocument.md
        ├── TrustServiceFederationArchitecture.md
        └── TRSL-Governance.md
```

Note that `spec/TargetRevenueLicenseConcept.md` (singular `spec/`) predates the `specs/` directory established by the PRD and this TSD; it remains the normative concept source and is referenced, not moved, to preserve its history.

---

## 8. Out-of-Scope Reinforcement (Explicit)

The following are **explicitly excluded** from this TSD, consistent with `specs/ProductRequirementsDocument.md` §4 and §7.2:

* Final legal license text or clause-level drafting.
* A finalized degeneration formula (§3.1's `degeneration_policy` is a reference slot, not a formula definition).
* A concrete technology stack, storage engine, or hosting model for the Trust Service.
* Any specific product's actual Phase declaration — the schemas above are the contract, not an instance.
* Tax, statutory revenue-recognition, or accounting-standard treatment of any ledger entry type.

Any future inclusion of these concerns requires a PRD revision or an explicit ADR, not a silent TSD amendment.

---

## 9. Open Technical Questions

Carried forward from `specs/ProductRequirementsDocument.md` §14 and narrowed to schema-level impact:

1. Should `entry.currency` mismatches across a Phase's entries be rejected outright, or resolved via a declared FX-rate extension field?
2. Should `phase.target_basis.target_multiple` be a closed enum (the five indicative classes) or an open decimal with the classes as guidance only?
3. What is the minimum `evidence.requirement` string grammar — free text, a controlled vocabulary, or a reference to an external evidence schema?
4. Should `extension.status` transitions (`registered` → `canonical`) be recorded as their own ledger-like append-only history, or as mutable registry metadata outside the Target Ledger's append-only guarantee?
5. What signature scheme (and key-rotation record format) should `entry.signature` and `attestation.signature` assume, given the federation-readiness requirement in §6.3?

---

## 10. Traceability Note

This TSD is intentionally **non-binding** with respect to:

* programming language, runtime, or framework choice for a future Trust Service implementation;
* storage technology (relational, document, event-sourced, or ledger-native);
* specific cryptographic signature algorithms;
* UI or API surface design for registry/ledger access.

Its sole purpose is to ensure that any future implementation, extension author, or federated operator can validate their work against the same schemas and boundary rules, keeping technical choices aligned with the product intent defined in `specs/ProductRequirementsDocument.md` and the normative concept in `spec/TargetRevenueLicenseConcept.md`.

---

## 11. Status

* **TSD** is **PRD-aligned**.
* Safe to use as:

  * schema reference for `PhaseManifestSpecification.md`, `TargetLedgerSpecification.md`, and `MonetizationExtensionSpecification.md` drafting;
  * conformance-check baseline for future Manifest/Extension validators;
  * pre-ADR reference for the eventual Trust Service reference implementation.