target-revenue/specs/TechnicalSpecificationDocument.md

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 unless specs/OpenQuestions-WorkingDefaults.md states a Stage 0 working default for schema unblocking (those defaults remain provisional until human promotion into core specs).

Sequencing (SCOPE.md): Stage 0 technical delivery is offline schemas, pure fold, and golden fixtures (WP-0002), not a hosted Trust Service. Hosted registries and multi-user ledger APIs are deferred to PRD Phase 4b.

---

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 Stage 0 foundation

• INTENT.md — durable purpose and strategic boundaries.
• SCOPE.md — living Stage 0 in/out scope and sequencing rules.
• 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.
• specs/OpenQuestions-WorkingDefaults.md — provisional Stage 0 defaults for open questions.
• workplans/ — TREV-WP-0001 (legal research), TREV-WP-0002 (schemas/fold), TREV-WP-0003 (core extract).
• history/ — dated exploration and assessments, non-normative.
• Planned by WP-0002: schemas/, examples/ (machine-readable contracts + golden Phase).

1.2 Near-term target — offline runnable specification (PRD Phase 4a)

JSON Schema (or equivalent), pure Outstanding Target fold, offline validators, and golden fixtures. No requirement for multi-tenant hosting. Conversion status must be computable without network services or attestation files.

1.3 Later target — reference Trust Service (PRD Phase 4b)

A centralized reference implementation 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. Hosted implementation is out of scope for WP-0002.

---

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	Stage 0 closed set per working default Q3; additional Future Licenses require core revision.
phase.degeneration_policy	string (URN, trsl:policy:<slug>@<version>)	Required	Stage 0 pilot: trsl:policy:linear-longstop-v0 (working default Q7).
phase.longstop_at	ISO 8601 timestamp	Required (Stage 0)	Working default Q8: every Phase must declare a full-remission / maximum-protection instant. Promote to permanent core via WP-0003 extract + human accept.
phase.ledger	URL or path URI	Required	Location of the authoritative Target Ledger for this Phase (may be relative path in offline packages).
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 or offline validation (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.
• entry.currency for all ledger entries MUST match phase.initial_target.currency in Stage 0 (working default Q6); FX is out of scope for the pure fold.

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:

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)

target-revenue/
├── INTENT.md
├── SCOPE.md
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── history/
│   ├── 260728-InitialExploration.md
│   └── 260728-SWOT-Assessment.md
├── spec/
│   └── TargetRevenueLicenseConcept.md    # normative concept (singular path, stable)
├── specs/
│   ├── ProductRequirementsDocument.md
│   ├── TechnicalSpecificationDocument.md  # this document
│   ├── OpenQuestions-WorkingDefaults.md
│   └── (near-term extracts / drafts:)
│       ├── TargetRevenueFrameworkCore.md      # WP-0003
│       ├── PhaseManifestSpecification.md      # WP-0003
│       ├── TargetLedgerSpecification.md       # WP-0003
│       ├── MonetizationExtensionSpecification.md
│       ├── TargetRevenueSourceLicense-Draft.md # WP-0001
│       ├── CanonicalMonetizationProfiles.md
│       ├── TargetDegenerationPolicyResearch.md
│       ├── TrustServiceProductRequirementsDocument.md  # before hosted service
│       ├── TrustServiceFederationArchitecture.md
│       └── TRSL-Governance.md
├── workplans/
│   ├── TREV-WP-0001-license-prior-art-research.md
│   ├── TREV-WP-0002-trust-service-foundation.md
│   └── TREV-WP-0003-normative-core-extraction.md
├── schemas/     # planned — WP-0002
└── examples/    # planned — WP-0002 golden Phase package

spec/ vs specs/ policy: The concept document remains under singular spec/ so git history and existing citations stay valid. New product, technical, research, and extracted normative artifacts go under plural specs/. Do not relocate the concept file without an explicit migration note in README and this section.

---

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. Stage 0 working defaults (provisional) from OpenQuestions-WorkingDefaults.md:

#	Question	Stage 0 working default
1	Currency mismatches vs FX extension?	Reject mismatches; single native currency; no FX in fold
2	target_multiple closed enum or open decimal?	Open decimal; classes are guidance; optional warn
3	evidence.requirement grammar?	Free text or short tier tag (E0–E2) until controlled vocab
4	extension.status history?	Mutable registry metadata outside Target Ledger for Stage 0
5	Signature scheme / key rotation?	SHA-256 chain + Ed25519 example signatures; append-only key history file

Unresolved beyond Stage 0: progress-sensitive degeneration parameters, federation discovery, multi-authority attestation.

---

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.