coulomb/target-revenue
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Extract normative core docs (TREV-WP-0003 T01-T05)

Browse source 
Stabilizes day-to-day terminology out of the exploratory concept draft:

- specs/TargetRevenueFrameworkCore.md — core terms, target formula,
  five-verb lifecycle, nine rules, invariants.
- specs/PhaseManifestSpecification.md — field tiers aligned with
  schemas/phase_manifest.schema.json.
- specs/TargetLedgerSpecification.md — entry types, hash chain, pure
  Outstanding Target fold, aligned with the WP-0002 library.
- specs/MonetizationExtensionSpecification.md — six-field contract,
  registered/canonical distinction, Stage 0 Q11 catalog.

Cross-links PRD/TSD/README/CONTRIBUTING to the new extracts, confirms no
placeholder tails remain, and prepares a review checklist for T06 (human
promotion gate, left open pending maintainer review).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-07-29 02:13:55 +02:00
parent 9279c7a3bb
commit 7d6b4f4f50
9 changed files with 557 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

6
CONTRIBUTING.md
View file

@ -17,7 +17,7 @@ This repository defines a **framework concept and specifications**. It does not
## Terminology
Use the normative terms from `spec/TargetRevenueLicenseConcept.md` §7. Do **not** reintroduce ambiguous synonyms for conversion metrics (e.g. treating total project “revenue captured” as equivalent to Development Credit).
Use the normative terms from `spec/TargetRevenueLicenseConcept.md` §7 (day-to-day reference: `specs/TargetRevenueFrameworkCore.md` §1). Do **not** reintroduce ambiguous synonyms for conversion metrics (e.g. treating total project “revenue captured” as equivalent to Development Credit).
Pre-conversion software is **source-available**, not OSI Open Source.
@ -34,8 +34,8 @@ A Developer Certificate of Origin (DCO) alone is **not** assumed sufficient for
The following must not be marked complete by agents alone without explicit human accept (comment, decision record, or maintainer message):
- Non-binding TRSL draft skeleton (WP-0001-T06)
- Library/stack ADR that locks implementation technology (WP-0002-T01)
- Promotion of working defaults into normative core wording
- Library/stack ADR that locks implementation technology (WP-0002-T01 — **accepted 2026-07-29**, see ADR-0001)
- Promotion of working defaults into normative core wording (WP-0003-T06, open)
## Workplans

27
README.md
View file

@ -20,7 +20,7 @@ Before conversion, software under TRSL is **source-available** with commercial-u
1. [`INTENT.md`](INTENT.md) — durable purpose and design principles
2. [`SCOPE.md`](SCOPE.md) — what is in scope *now* vs later maturity
3. [`spec/TargetRevenueLicenseConcept.md`](spec/TargetRevenueLicenseConcept.md) — normative concept (§1–10 for the kernel)
3. [`spec/TargetRevenueLicenseConcept.md`](spec/TargetRevenueLicenseConcept.md) — normative concept draft (ultimate source; governs if it and the extracts below ever diverge)
4. [`specs/ProductRequirementsDocument.md`](specs/ProductRequirementsDocument.md) — goals, FRs, roadmap
5. [`specs/TechnicalSpecificationDocument.md`](specs/TechnicalSpecificationDocument.md) — schema field tables and boundaries
6. [`specs/OpenQuestions-WorkingDefaults.md`](specs/OpenQuestions-WorkingDefaults.md) — provisional Stage 0 defaults
@ -28,6 +28,19 @@ Before conversion, software under TRSL is **source-available** with commercial-u
Exploration transcript (non-normative): [`history/260728-InitialExploration.md`](history/260728-InitialExploration.md)
Program assessment: [`history/260728-SWOT-Assessment.md`](history/260728-SWOT-Assessment.md)
## Normative documents (day-to-day reference)
Extracted and stabilized from the concept draft under `workplans/TREV-WP-0003-normative-core-extraction.md` (T01–T05 done; T06 human review still open — see that workplan). Use these for terminology, not the concept draft's prose, in ordinary implementation work:
| Document | Covers |
| --- | --- |
| [`specs/TargetRevenueFrameworkCore.md`](specs/TargetRevenueFrameworkCore.md) | Seven core terms, target formula, five-verb lifecycle, nine core rules, foundational invariants |
| [`specs/PhaseManifestSpecification.md`](specs/PhaseManifestSpecification.md) | Phase Manifest field tiers and validation rules |
| [`specs/TargetLedgerSpecification.md`](specs/TargetLedgerSpecification.md) | Ledger entry types, hash chain, Outstanding Target fold |
| [`specs/MonetizationExtensionSpecification.md`](specs/MonetizationExtensionSpecification.md) | Six-field extension contract, registered vs. canonical |
**Forbidden synonyms:** do not treat undifferentiated "revenue captured" as equivalent to Development Credit (see `CONTRIBUTING.md` § Terminology); do not call pre-conversion software "Open Source" (see the guardrail table above).
## Repository layout
| Path | Role |
@ -35,7 +48,7 @@ Program assessment: [`history/260728-SWOT-Assessment.md`](history/260728-SWOT-As
| `INTENT.md` | Stable purpose (change rarely) |
| `SCOPE.md` | Living Stage 0 scope |
| `spec/` | Normative **concept** source (`TargetRevenueLicenseConcept.md`) |
| `specs/` | Product/tech specs, working defaults, future normative extracts |
| `specs/` | Product/tech specs, working defaults, and normative extracts (WP-0003) |
| `workplans/` | Active delivery plans |
| `history/` | Dated non-normative exploration and assessments |
| `examples/` | Golden Phase packages (`phase-001`, from WP-0002) |
@ -49,9 +62,9 @@ Program assessment: [`history/260728-SWOT-Assessment.md`](history/260728-SWOT-As
| Workplan | Focus |
| --- | --- |
| [TREV-WP-0001](workplans/TREV-WP-0001-license-prior-art-research.md) | Prior-art research → non-binding TRSL draft skeleton |
| [TREV-WP-0002](workplans/TREV-WP-0002-trust-service-foundation.md) | Schemas, pure Outstanding Target fold, golden fixture (not full service) |
| [TREV-WP-0003](workplans/TREV-WP-0003-normative-core-extraction.md) | Extract stable normative core docs (PRD Phase 1) |
| [TREV-WP-0001](workplans/TREV-WP-0001-license-prior-art-research.md) | Prior-art research → non-binding TRSL draft skeleton (open) |
| [TREV-WP-0002](workplans/TREV-WP-0002-trust-service-foundation.md) | Schemas, pure Outstanding Target fold, golden fixture — **finished** |
| [TREV-WP-0003](workplans/TREV-WP-0003-normative-core-extraction.md) | Extract stable normative core docs — T01–T05 done, T06 human review open |
Hub index: [`WORK-RECORDS.md`](WORK-RECORDS.md) · brief: [`.custodian-brief.md`](.custodian-brief.md)
@ -69,8 +82,8 @@ python3 scripts/generate_golden_phase.py # regenerate examples/phase-001/ledge
```
The implementation stack (Python, `jsonschema`, `pytest`, `hatchling`) is
proposed in [`docs/adr/ADR-0001-stage0-library-stack.md`](docs/adr/ADR-0001-stage0-library-stack.md)
and is **not yet accepted** — see `CONTRIBUTING.md` human decision gates.
recorded in [`docs/adr/ADR-0001-stage0-library-stack.md`](docs/adr/ADR-0001-stage0-library-stack.md),
**accepted 2026-07-29**.
## What this repo does not claim yet

70
specs/MonetizationExtensionSpecification.md Normal file
View file

@ -0,0 +1,70 @@
# Monetization Extension Specification (Normative Extract)
**Document version:** TRF-Extension-0.1
**Status:** Normative extract, Stage 0
**Extracted from:** `spec/TargetRevenueLicenseConcept.md` §11–§12 and `specs/TechnicalSpecificationDocument.md` §3.3
**Machine-readable counterpart:** `schemas/extension_contract.schema.json` — implemented and tested under `workplans/TREV-WP-0002-trust-service-foundation.md` T04 (`src/target_revenue/validation.py::validate_extension_contract`).
This is a complete short specification, not a stub — it freezes the extension contract and the registered/canonical distinction. It intentionally does **not** catalog all canonical profiles in depth; that remains a follow-on, `specs/CanonicalMonetizationProfiles.md` (planned).
---
## 1. Purpose
Monetization Extensions let new commercial mechanisms be published without redefining or fragmenting the core (`specs/TargetRevenueFrameworkCore.md`). The framework's central economic distinction is between **target-relevant allocation** (may become Development Credit) and **non-target allocation** (everything else) — a monetization label explains the transaction; the explicit allocation determines its effect on conversion.
## 2. The six-field extension contract
Every extension must answer exactly these six questions and no more:
| Field | Question | Type |
|---|---|---|
| `value.description` | What does the payer receive? | string |
| `pricing.method` | How is the payment calculated? | string |
| `allocation.rule` | What portion may become Development Credit? | string, plus optional `default_rate` (0–1) |
| `recognition.event` | When is the allocation recognized? | enum `{order, invoice, payment-settled, delivery}` |
| `reversal.rule` | How are refunds, chargebacks, or corrections handled? | string |
| `evidence.requirement` | What proves the transaction and allocation? | string |
**Working default (Q10):** `recognition.event` should be `payment-settled` for any entry that is to count as Development Credit or Remission Credit in the Stage 0 fold. Invoice/order without settlement does not create a fold-eligible entry in Stage 0.
## 3. What an extension must not do
An extension **may** define pricing and allocation logic. An extension **must not** reference or redefine: `Phase`, `Initial Target`, `Development Credit`, `Remission Credit`, `Outstanding Target`, `Conversion Event`, or `Future License` (`specs/TargetRevenueFrameworkCore.md` §1). This is the constitutional boundary between flexibility and complexity (concept §20.1's complexity budget applies equally here).
**Conformance check:** structural conformance (all six fields present and well-typed) is validated against `schemas/extension_contract.schema.json`. The core-term-redefinition rule is checked by a pattern-based heuristic in `src/target_revenue/validation.py::check_extension_core_term_redefinition` — documented there as a Stage 0 limitation, not a substitute for human review before an extension is promoted to `canonical`.
A non-conforming extension is **rejected at registration**, with a field-by-field diff, not silently accepted with reduced trust.
## 4. Registered vs. canonical
| Status | Meaning |
|---|---|
| `registered` | Passes the conformance check. No endorsement implied. |
| `canonical` | Reviewed and maintained as a recommended framework profile. Promotion is a documented human/governance action (`SCOPE.md` §4), never automated. |
| `deprecated` | No longer recommended; existing registrations remain valid evidence, but should not be used for new Phases. |
## 5. Stage 0 canonical profile catalog (working default Q11)
Six initial canonical-candidate profiles, shipped as `registered` fixtures pending formal canonical review:
| Profile | Default `development_allocation` | Fixture |
|---|---:|---|
| `development-license` | 100% of settled development fee (net of tax/refunds) | `examples/phase-001/extensions/development-license.json` |
| `cost-plus-operations` | 0% | `examples/phase-001/extensions/cost-plus-operations.json` |
| `phase-sponsorship` | Explicitly declared per transaction | `examples/phase-001/extensions/phase-sponsorship.json` |
| `service-with-development-allocation` | 0% (explicit split when reusable work enters the Milestone) | `examples/phase-001/extensions/service-with-development-allocation.json` |
| `product-ideation` | 0% or declared | Not yet fixture-backed |
| `general-consulting` | 0% | Not yet fixture-backed |
A full worked catalog with pricing narratives belongs in `specs/CanonicalMonetizationProfiles.md` (planned, PRD Roadmap Phase 3).
## 6. Conservation rule
One monetary unit may create no more than one monetary unit of Development Credit (Rule 3). A payment may be split across allocation purposes, but the split must be declared when the transaction is created — never inferred after the fact from a monetization label.
## 7. Not covered here
- The Target Ledger entries that record an extension's effect: `specs/TargetLedgerSpecification.md`.
- Full pricing narratives and worked examples per canonical profile: `specs/CanonicalMonetizationProfiles.md` (planned).
- Extension registry hosting and canonical-promotion workflow tooling: deferred to a Trust Service implementation workplan (`SCOPE.md` §3).

86
specs/PhaseManifestSpecification.md Normal file
View file

@ -0,0 +1,86 @@
# Phase Manifest Specification (Normative Extract)
**Document version:** TRF-PhaseManifest-0.1
**Status:** Normative extract, Stage 0
**Extracted from:** `spec/TargetRevenueLicenseConcept.md` §16 and `specs/TechnicalSpecificationDocument.md` §3.1
**Machine-readable counterpart:** `schemas/phase_manifest.schema.json` — implemented and tested under `workplans/TREV-WP-0002-trust-service-foundation.md` T02 (`src/target_revenue/validation.py::validate_phase_manifest`). This document is the prose normative reference; the schema file is the authoritative machine-checkable definition. They must not drift — a change to one requires reviewing the other.
---
## 1. Purpose
A Phase Manifest is the immutable, machine-readable declaration that establishes a Phase per `specs/TargetRevenueFrameworkCore.md` §1.1. No Development Credit may be accepted for a Phase before its Manifest is published (Rule 1).
## 2. Field tiers
| Field | Type | Tier | Notes |
|---|---|---|---|
| `framework` | string | Required | Framework version tag, e.g. `TRF-0.1`. |
| `license` | string | Required | TRSL version tag, 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-64) | Recommended | Required if a built artifact (not just source) is governed. |
| `phase.initial_target.amount` | decimal (> 0) | Required | Immutable once Development Credits are accepted (Rule 1). |
| `phase.initial_target.currency` | ISO 4217 code | Required | One native currency per Phase (working default Q6). |
| `phase.target_basis.estimated_effort_days` | decimal | Recommended | Transparency metadata (working default Q5), 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 | Open decimal (working default Q4); guidance classes are not a closed enum. |
| `phase.future_license` | enum `{MIT, Apache-2.0}` | Required | Closed set for Stage 0 (working default Q3). |
| `phase.degeneration_policy` | string (URN `trsl:policy:<slug>@<version>`) | Required | e.g. `trsl:policy:linear-longstop-v0@1.0`. |
| `phase.longstop_at` | ISO 8601 timestamp | **Required for Stage 0** | Stage 0 working default (Q8): elevates this from TSD's original "recommended" to required, so every Phase has a maximum-protection instant. **Marked provisional pending promotion** — see §4. |
| `phase.ledger` | URL or path URI | Required | Location of the authoritative Target Ledger for this Phase. |
| `extensions[]` | list of `trsl:extension:<id>@<version>` | Optional | Applicable monetization profiles/extensions. |
## 3. Validation rules
1. A manifest missing any Required field **must** be rejected at registration or offline validation, not merely flagged.
2. `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 (Rule 1). Stage 0 has no such correction-record type yet; any observed change is a violation (`src/target_revenue/validation.py::check_manifest_immutability`).
3. `phase.id` **must** be immutable and **must not** be reused across Phases, including a superseded or abandoned Phase.
4. `phase.initial_target.currency` fixes the Phase's native currency; every Target Ledger entry for this Phase must use the same currency (working default Q6, enforced in `specs/TargetLedgerSpecification.md`).
## 4. Stage 0 working default requiring promotion
`phase.longstop_at` is required by Stage 0 validators as a working default (Q8), not yet a permanent normative rule. Promoting this requirement into permanent status (i.e., removing the "working default" qualifier) requires human accept per `SCOPE.md` §4 and `workplans/TREV-WP-0003-normative-core-extraction.md` T06. Until then, treat it as: **binding for Stage 0 conformance, provisional as permanent norm.**
## 5. Minimal example
```yaml
framework: TRF-0.1
license: TRSL-0.1
phase:
id: trsl:phase:example-001
milestone_release:
name: release-1.0
source_revision: abc123
artifact_sha256: "44cd1493bd179c1207c7025c1372cdad89aac114e151db27aba2bdf3d55c688"
initial_target:
amount: 100000
currency: USD
target_basis:
estimated_effort_days: 1
daily_rate: 1000
approved_direct_costs: 0
target_multiple: 100
future_license: MIT
degeneration_policy: trsl:policy:linear-longstop-v0@1.0
longstop_at: "2031-08-01T00:00:00Z"
ledger: examples/phase-001/ledger.json
extensions:
- trsl:extension:development-license@1.0
- trsl:extension:cost-plus-operations@1.0
```
A working, schema-validated instance of this example lives at `examples/phase-001/manifest.json`.
## 6. Not covered here
- Ledger entry schema and the Outstanding Target fold: `specs/TargetLedgerSpecification.md`.
- Extension contract fields: `specs/MonetizationExtensionSpecification.md`.
- Final legal text for what a Phase Manifest legally binds: deferred to specialist legal review (`workplans/TREV-WP-0001-license-prior-art-research.md`).

4
specs/ProductRequirementsDocument.md
View file

@ -111,7 +111,7 @@ Per `INTENT.md` "Strategic Boundaries" and `spec/TargetRevenueLicenseConcept.md`
### 6.1 Core entities
The seven core terms and their relationships are normatively defined in `spec/TargetRevenueLicenseConcept.md` §7 and must not be restated with variant meaning elsewhere in the framework:
The seven core terms and their relationships are normatively defined in `spec/TargetRevenueLicenseConcept.md` §7 (day-to-day reference: `specs/TargetRevenueFrameworkCore.md` §1, WP-0003 extract) and must not be restated with variant meaning elsewhere in the framework:
| Entity | Summary |
|---|---|
@ -129,7 +129,7 @@ The seven core terms and their relationships are normatively defined in `spec/Ta
### 6.2 Core lifecycle
Five verbs (§9): **Define → Allocate → Credit / Remit → Convert**. See the state diagram and rule set in `spec/TargetRevenueLicenseConcept.md` §9–§10 for the authoritative lifecycle and the nine core rules (immutable phase definition, explicit allocation, no duplicate credit, settled-payment recognition, separate remission, automatic conversion, permanent prior freedom, correction without erasure, conversion irreversibility).
Five verbs (§9): **Define → Allocate → Credit / Remit → Convert**. See the state diagram and rule set in `spec/TargetRevenueLicenseConcept.md` §9–§10 (day-to-day reference: `specs/TargetRevenueFrameworkCore.md` §3–§4) for the authoritative lifecycle and the nine core rules (immutable phase definition, explicit allocation, no duplicate credit, settled-payment recognition, separate remission, automatic conversion, permanent prior freedom, correction without erasure, conversion irreversibility).
### 6.3 Monetization architecture

74
specs/TargetLedgerSpecification.md Normal file
View file

@ -0,0 +1,74 @@
# Target Ledger Specification (Normative Extract)
**Document version:** TRF-Ledger-0.1
**Status:** Normative extract, Stage 0
**Extracted from:** `spec/TargetRevenueLicenseConcept.md` §17 and `specs/TechnicalSpecificationDocument.md` §3.2
**Machine-readable counterpart:** `schemas/ledger_entry.schema.json` — implemented and tested under `workplans/TREV-WP-0002-trust-service-foundation.md` T03 (`src/target_revenue/hashing.py`, `src/target_revenue/fold.py`). This document is the prose normative reference; the schema and library are the authoritative machine-checkable implementation.
---
## 1. Purpose
The Target Ledger is the append-only record of everything that moves a Phase's Outstanding Target. It is the sole input, together with the Phase Manifest, to the Outstanding Target fold and therefore to Conversion Event detection (`specs/TargetRevenueFrameworkCore.md` §1.7–§1.8).
## 2. Entry types (closed set)
| Type | Effect on fold | Notes |
|---|---|---|
| `development-credit` | `+= amount` to Development Credit | Rule 4: normally arises only from settled payments. |
| `remission-credit` | `+= amount` to Remission Credit | Rule 5: never represented as revenue. |
| `credit-reversal` | `-= amount` from Development Credit | Rule 8: compensating entry; requires `reverses` pointing to the original entry id. Never edits or deletes the original. |
| `remission-correction` | `+= amount` to Remission Credit (amount may be negative) | Requires `reverses`. |
| `administrative-correction` | `+= amount` to Development Credit | **Stage 0 simplification:** a generic correction bucket, not yet specialized by which side of the target it corrects. Revisit if this proves ambiguous in practice. |
| `conversion-checkpoint` | No numeric effect | Marker only. |
This set is closed for Stage 0: a project **must not** invent new entry types; new monetization behavior belongs in an extension (`specs/MonetizationExtensionSpecification.md`), not a new ledger entry type.
## 3. Required entry fields
| Field | Type | Notes |
|---|---|---|
| `id` | string (URN `trsl:entry:<id>`) | Globally unique, monotonically orderable. |
| `phase` | string (Phase URN) | Must reference a published Phase Manifest. |
| `type` | enum (§2) | |
| `amount` | decimal | Sign convention per §2. |
| `currency` | ISO 4217 code | **Must match** the Phase's `initial_target.currency` (working default Q6). No FX conversion in the pure fold; a currency mismatch is rejected, not converted. |
| `recognized_at` | ISO 8601 timestamp | Settlement time, not invoice time (Rule 4; working default Q10: `payment-settled` recognition only). |
| `extension.id` / `extension.version` | string / string | Required for `development-credit` / `remission-credit`: identifies the monetization profile or degeneration policy that produced the entry. |
| `evidence_reference` | URI (`confidential:` scheme allowed) | Tiered per working default Q10 (E0 opaque id / E1 settled payment reference / E2 contract+invoice+settlement). |
| `previous_entry_hash` | hex-64 or literal `GENESIS` | SHA-256 of the prior entry's canonical serialization for this Phase (§4). |
| `signature` | string | Ed25519 signature over the canonical serialization (working default Q14); optional in Stage 0 fixtures, required for any public claim. |
| `reverses` | string (entry URN) | Required on `credit-reversal` and `remission-correction`. |
## 4. Hash chain and canonical serialization
**Working default (Q14), accepted via ADR-0001:** canonical serialization is JSON with sorted keys, no insignificant whitespace, UTF-8 encoding, excluding the `signature` and `previous_entry_hash` fields themselves. The chain hash is SHA-256 over that serialization. The first entry for a Phase has `previous_entry_hash: GENESIS`; every subsequent entry's `previous_entry_hash` must equal the SHA-256 digest of the immediately preceding entry's canonical bytes.
Reference implementation: `src/target_revenue/hashing.py::entry_hash`, `verify_chain`.
## 5. Corrections without erasure
Per Rule 8, the ledger is append-only. A correction or reversal is always a **new** entry (`credit-reversal`, `remission-correction`, or `administrative-correction`) referencing the entry it corrects via `reverses` — never an edit or deletion of the original. This preserves the audit trail even when the correction is disputed.
## 6. Outstanding Target fold (normative definition)
```text
Outstanding Target = max(0, Initial Target − Σ(development-credit, administrative-correction)
− Σ(remission-credit, remission-correction)
+ Σ(credit-reversal))
```
Equivalently, per entry type effect in §2, folded left-to-right over the Phase's entries in ledger order. The fold is **pure**: identical `(Initial Target, entries)` input always yields identical output, with no hidden state (TSD §6.1). Reference implementation: `src/target_revenue/fold.py::fold_outstanding_target`.
The fold **must** be independently reproducible by any conformant external tool from the Phase Manifest and Target Ledger alone — no Trust Service state is required (PRD NFR-1).
## 7. Currency consistency rule
Working default Q6: every entry's `currency` must equal the Phase's `initial_target.currency`. A mismatch is rejected outright in Stage 0; there is no FX conversion step in the pure fold. A future FX extension may be registered, but until then multi-currency Phases are out of scope. Reference implementation: `src/target_revenue/validation.py::check_currency_consistency`.
## 8. Not covered here
- Phase Manifest fields: `specs/PhaseManifestSpecification.md`.
- Extension contract fields referenced by `extension.id`/`extension.version`: `specs/MonetizationExtensionSpecification.md`.
- Conversion Attestation document schema: `specs/TechnicalSpecificationDocument.md` §3.5 (a dedicated extract is not yet planned; the TSD section remains authoritative).
- Signature key management and rotation: working default Q14 notes an append-only key history document; not yet specified in a dedicated file.

225
specs/TargetRevenueFrameworkCore.md Normal file
View file

@ -0,0 +1,225 @@
# Target Revenue Framework — Core (Normative Extract)
**Document version:** TRF-Core-0.1
**Status:** Normative extract, Stage 0
**Extracted from:** `spec/TargetRevenueLicenseConcept.md` §7–§10, §18, §22 (concept draft remains the source; this document freezes day-to-day terminology per `workplans/TREV-WP-0003-normative-core-extraction.md`)
**Authority:** This is the day-to-day normative reference for terminology, formulas, lifecycle, and rules. It does not invent meaning beyond the concept document — where the two ever appear to diverge, the concept document governs and this extract must be corrected, not reinterpreted.
**Working defaults:** Several fields below are marked **Stage 0 working default** — provisional per `specs/OpenQuestions-WorkingDefaults.md`, not yet promoted to permanent norm. Everything else in this document reflects concept §24 open questions that remain genuinely open; this extract does not resolve them by omission.
---
## 1. Minimal core terminology
Seven core terms plus the Target Multiple and Trust Service/Extension boundary concepts. No other document may define these terms with variant meaning (PRD §6.1).
### 1.1 Phase
A bounded development undertaking governed by one Initial Target, one Milestone Release, one degeneration policy, and one Future License declaration.
A Phase may cover a bug fix, a refactoring, a performance improvement, a new feature, a new integration, a product-defining capability, or a platform-level improvement.
### 1.2 Milestone Release
The precisely identified software release that becomes available under the Future License when the Conversion Event occurs. Identifiable through an immutable release artifact, source revision, cryptographic digest, or equivalent reproducible reference.
### 1.3 Initial Target
The immutable monetary target declared for the Phase. A historical statement of the intended development monetization opportunity — it must not be silently increased or rewritten after the Phase has begun.
### 1.4 Target Multiple
A multiplier applied to the estimated development cost to determine the Initial Target. Represents a product and commercial hypothesis, not an objectively measurable claim.
| Class | Multiple | Indicative interpretation |
|---|---:|---|
| Commons | 0x | Immediate permissive release or no development monetization target |
| Recovery | 1x | Direct development cost recovery |
| Incremental | 10x | Material enhancement of an existing use case |
| Product-defining | 100x | Significant commercial differentiator or new product capability |
| Platform-defining | 1000x | New platform, market, ecosystem, or foundational capability |
**Stage 0 working default (Q4):** these classes are guidance, not a closed enum — `target_multiple` is an open non-negative decimal. Validators may warn (not fail) on values outside `{0,1,10,100,1000}`.
### 1.5 Development Credit
The portion of a collected and settled payment explicitly allocated toward satisfying the Initial Target of a specific Phase. An accounting concept of the framework — not synonymous with total revenue, recognized accounting revenue, cash flow, profit, or contribution margin.
### 1.6 Remission Credit
A transparent, non-revenue reduction of the Outstanding Target generated under the published degeneration policy. Records the expiry or reduction of the remaining commercial protection opportunity; must never be represented as revenue captured.
### 1.7 Outstanding Target
The remaining amount required for conversion:
```text
Outstanding Target = max(0, Initial Target − Development Credit − Remission Credit)
```
### 1.8 Conversion Event
The moment the Outstanding Target reaches zero. The Milestone Release automatically and irrevocably becomes available under the declared Future License.
### 1.9 Future License
The permissive open-source license applying to the Milestone Release after the Conversion Event. Initial candidates: MIT (simplicity, broad compatibility) or Apache License 2.0 (explicit patent grant).
**Stage 0 working default (Q3):** `future_license` is closed to `{MIT, Apache-2.0}` for Stage 0 schema validation. Phase authors choose one at publication.
### 1.10 Trust Service
The publication, accounting, metrics, evidence, and attestation infrastructure for the framework. Observes, records, calculates, and attests — must not possess discretionary power to prevent a conversion that has occurred under the license.
### 1.11 Monetization Profile or Extension
A standardized or project-specific declaration describing what value is supplied, how it is priced, how payments are allocated, when allocations are recognized, how reversals are handled, and what evidence is required. May not redefine the core meaning of any term in this section.
---
## 2. Target determination
```text
Estimated Development Cost = Estimated Effort × Published Rate + Approved Direct Costs
Initial Target = Estimated Development Cost × Target Multiple
```
Example:
```text
Estimated effort: 1 day
Published daily rate: $1,000
Approved direct costs: $0
Target Multiple: 100x
Initial Target: $100,000
```
The estimate and multiple should be published before Development Credits are accepted. The Initial Target may be reduced through Remission Credits; it should not be retroactively rewritten, to preserve the historical product hypothesis and audit trail.
**Stage 0 working default (Q5):** target-basis transparency fields are `estimated_effort_days`, `daily_rate`, `approved_direct_costs`. Marketing, general overhead, unrelated R&D, opportunity cost, and speculative market-value uplifts not expressed via the Target Multiple are excluded from the Stage 0 basis by default.
---
## 3. Core lifecycle (five verbs)
### Define
Publish the Phase, Milestone Release, Initial Target, Future License, degeneration policy, and applicable monetization extensions.
### Allocate
Classify each payment and allocate it between target-relevant and non-target purposes.
### Credit
Recognize the eligible target-relevant allocation as Development Credit for one identified Phase.
### Remit
Generate Remission Credit according to the published degeneration policy.
### Convert
Automatically apply the Future License to the Milestone Release when the Outstanding Target reaches zero.
```mermaid
stateDiagram-v2
[*] --> Defined
Defined --> Active: Phase published
Active --> Active: Development Credit
Active --> Active: Remission Credit
Active --> Converted: Outstanding Target = 0
Converted --> [*]
```
---
## 4. Core rules
The normative kernel is limited to rules that are universal, interoperability-critical, and trust-critical (governance test in §6 below).
### Rule 1 — Immutable phase definition
The Phase, Milestone Release, Initial Target, Target Multiple, Future License, and applicable degeneration policy must be published before Development Credits are accepted. Subsequent changes must be versioned, historically visible, and constrained by the framework. The Initial Target may not be increased for commercial convenience after the Phase begins.
### Rule 2 — Explicit allocation
No payment creates Development Credit unless its development allocation is explicitly defined.
### Rule 3 — No duplicate credit
The same economic value may not be credited more than once, whether against one Phase or several Phases.
### Rule 4 — Settled-payment recognition
Development Credit normally arises only from collected and settled payments. Refunds, chargebacks, and equivalent reversals must generate compensating ledger entries.
### Rule 5 — Separate remission
Target degeneration must be recorded as Remission Credit and never misrepresented as captured revenue.
### Rule 6 — Automatic conversion
When the Outstanding Target reaches zero, conversion occurs automatically and irrevocably without requiring further discretionary action by the licensor or Trust Service.
### Rule 7 — Permanent prior freedom
Rights granted to an earlier Milestone Release may not be withdrawn or restricted by a later Phase.
### Rule 8 — Correction without erasure
Published ledger history should be append-only. Errors and reversals should be corrected through compensating entries rather than deletion or silent modification.
### Rule 9 — Conversion irreversibility
Once a valid Conversion Event has occurred, later refunds, accounting corrections, service failures, or disputes must not revoke the Future License grant.
---
## 5. Conversion — legal-technical requirements
The legal mechanism must establish that:
1. the Conversion Event is objectively determined by the Phase Manifest, ledger, and degeneration policy;
2. conversion occurs automatically when the Outstanding Target reaches zero;
3. no declaration by the licensor or Trust Service is required for legal effect;
4. the Future License grant is irrevocable;
5. the Milestone Release remains permanently available under the Future License;
6. later Phases may govern later improvements but may not restrict the converted release;
7. later accounting reversals do not restore the prior restriction.
Full Conversion Attestation field requirements and publication mechanics belong to `specs/TargetLedgerSpecification.md` and `specs/TechnicalSpecificationDocument.md` §3.5, not this core document — this section states only the legal-technical requirements the mechanism must satisfy, not the attestation schema.
---
## 6. Governance: what belongs in the core
A rule enters this core document only when it passes three tests (concept §20.1):
- **Universal:** nearly every Phase needs it.
- **Interoperable:** different implementations would otherwise produce incompatible meanings.
- **Trust-critical:** its absence would permit manipulation of the conversion bargain.
Otherwise, it belongs in a canonical profile (`specs/CanonicalMonetizationProfiles.md`, planned), an extension (`specs/MonetizationExtensionSpecification.md`), implementation guidance, or project policy — not here.
---
## 7. Foundational invariants
1. Every Phase has one identifiable Milestone Release.
2. Every Phase has one immutable Initial Target.
3. Every target-affecting movement is either Development Credit, Remission Credit, or an explicit correction or reversal.
4. No payment contributes without an explicit allocation rule.
5. The same value cannot be credited twice.
6. Operations monetization remains independent by default.
7. Degeneration is visible and is never represented as earned revenue.
8. Conversion is automatic, objective, and irrevocable.
9. The Trust Service supplies evidence, not discretionary permission.
10. Earlier permissive rights cannot be withdrawn by later Phases.
11. Extensions may add commercial models but cannot redefine the core.
12. Centralized operation must not prevent independent future verification or federation.
---
## 8. Open questions not resolved by this extract
Concept §24 lists fifteen open design questions. This extract resolves none of them by silent omission — where a Stage 0 working default exists (`specs/OpenQuestions-WorkingDefaults.md`), it is cited explicitly above (§1.4, §1.9, §2); everything else remains open and must not be treated as decided because it is absent from this document.

11
specs/TechnicalSpecificationDocument.md
View file

@ -22,6 +22,8 @@ It:
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).
**Normative documents (WP-0003 extract, done 2026-07-29):** day-to-day terminology, formulas, lifecycle, and rules now live in `specs/TargetRevenueFrameworkCore.md`, `specs/PhaseManifestSpecification.md`, `specs/TargetLedgerSpecification.md`, and `specs/MonetizationExtensionSpecification.md`. These extracts are stabilized references; the concept document remains the ultimate source and governs if the two ever appear to diverge.
**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.
---
@ -38,13 +40,14 @@ The Target Revenue Framework, as it exists in this repository, is **currently a
* `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).
* `specs/TargetRevenueFrameworkCore.md`, `specs/PhaseManifestSpecification.md`, `specs/TargetLedgerSpecification.md`, `specs/MonetizationExtensionSpecification.md` — normative extracts (WP-0003, done).
* `workplans/` — TREV-WP-0001 (legal research, active), TREV-WP-0002 (schemas/fold, finished), TREV-WP-0003 (core extract, T01–T05 done / T06 human review gate open).
* `history/` — dated exploration and assessments, non-normative.
* Planned by WP-0002: `schemas/`, `examples/` (machine-readable contracts + golden Phase).
* Delivered by WP-0002: `schemas/*.schema.json`, `src/target_revenue/` (validators, hash chain, pure fold, conversion detection), `examples/phase-001/` (golden Phase package), `tests/` (32 passing).
### 1.2 Near-term target — offline runnable specification (PRD Phase 4a)
### 1.2 Delivered — offline runnable specification (PRD Phase 4a, WP-0002 finished)
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.
JSON Schema validators, a pure Outstanding Target fold, offline conformance checks, and a golden Phase fixture (`examples/phase-001/`) are implemented and tested (32 passing tests, no network dependency). Conversion status is computable from the Phase Manifest and Target Ledger alone; no attestation file is required (`src/target_revenue/conversion.py`).
### 1.3 Later target — reference Trust Service (PRD Phase 4b)

75
workplans/TREV-WP-0003-normative-core-extraction.md
View file

@ -37,11 +37,16 @@ into profiles or federation.
```task
id: TREV-WP-0003-T01
status: todo
status: done
priority: high
state_hub_task_id: "e3e5fa79-2412-45b6-8e55-1cfad01c7136"
```
Result 2026-07-29: `specs/TargetRevenueFrameworkCore.md` (TRF-Core-0.1)
produced, extracting concept §7–§10, §18 (points 1–7), §22 without
paraphrase drift; §8 lists which open questions remain unresolved by this
extract rather than answering them by omission.
Produce `specs/TargetRevenueFrameworkCore.md` containing:
- minimal core terminology (concept §7);
@ -59,11 +64,17 @@ questions remain open except where working defaults apply provisionally.
```task
id: TREV-WP-0003-T02
status: todo
status: done
priority: high
state_hub_task_id: "c0b4462a-599b-46e0-87bb-53d50129e3cb"
```
Result 2026-07-29: `specs/PhaseManifestSpecification.md` (TRF-PhaseManifest-0.1)
produced, aligned field-for-field with `schemas/phase_manifest.schema.json`.
`longstop_at` explicitly marked "Required for Stage 0" with a dedicated §4
flagging it as a working default pending promotion, not silently folded
into permanent Rule 1 scope.
Produce `specs/PhaseManifestSpecification.md` from concept §16 and TSD §3.1:
- required / recommended / optional field tiers;
@ -76,11 +87,19 @@ Produce `specs/PhaseManifestSpecification.md` from concept §16 and TSD §3.1:
```task
id: TREV-WP-0003-T03
status: todo
status: done
priority: high
state_hub_task_id: "ab11ec85-9c4c-4ca1-bc58-a0a044241c01"
```
Result 2026-07-29: `specs/TargetLedgerSpecification.md` (TRF-Ledger-0.1)
produced, aligned with `schemas/ledger_entry.schema.json` and
`src/target_revenue/fold.py`/`hashing.py`. Flags the
`administrative-correction` fold-side effect as a Stage 0 simplification
(concept §17 names the entry type but does not specify which side of the
target it corrects) — called out explicitly for T06 review rather than
presented as settled.
Produce `specs/TargetLedgerSpecification.md` from concept §17 and TSD §3.2:
- entry types (closed set);
@ -95,11 +114,18 @@ Produce `specs/TargetLedgerSpecification.md` from concept §17 and TSD §3.2:
```task
id: TREV-WP-0003-T04
status: todo
status: done
priority: medium
state_hub_task_id: "5129e0a2-8e7c-4279-8b3a-3570778bd749"
```
Result 2026-07-29: Produced the full `specs/MonetizationExtensionSpecification.md`
(TRF-Extension-0.1), not just a stub — freezes the six-field contract,
registered/canonical distinction, and the Stage 0 Q11 catalog table (with
`product-ideation`/`general-consulting` correctly marked as not yet
fixture-backed). Deep profile narratives deferred to the planned
`CanonicalMonetizationProfiles.md`, as the task allowed.
Produce either a full `specs/MonetizationExtensionSpecification.md` (PRD
Phase 3 item) or a clearly labeled Stage 0 stub that freezes the six-field
extension contract (concept §12, TSD §3.3) and the registered vs canonical
@ -111,11 +137,18 @@ may remain a follow-on: `CanonicalMonetizationProfiles.md`).
```task
id: TREV-WP-0003-T05
status: todo
status: done
priority: medium
state_hub_task_id: "ae77d3ac-81ea-4bf9-8e19-21b8d758e9b0"
```
Result 2026-07-29: Added "Normative documents" section to README with a
table pointing at all four extracts plus forbidden-synonym guidance.
Updated PRD §6.1/§6.2 and TSD §0/§1.1 to cite the extracts as the
day-to-day reference alongside the concept document as ultimate authority.
Updated CONTRIBUTING.md terminology and human-gate sections. Confirmed via
`grep -rn "^xxx$" spec/ specs/` — no placeholder tails remain.
- Add a short “Normative documents” section pointer from README and/or
concept header to the extracted files once they exist.
- Ensure PRD §6.1 and TSD §0 still point at the correct authority documents.
@ -137,3 +170,35 @@ Human maintainer reviews T01–T05 extracts for term consistency with concept
and for accidental elevation of working defaults to permanent norm without
labeling. Mark this task `done` only after human accept; agents prepare the
diff and a short review checklist.
**Review checklist prepared 2026-07-29** (task remains `todo` pending human
accept):
- [ ] `specs/TargetRevenueFrameworkCore.md` — terms in §1 match concept §7
wording; formula in §2 matches concept §8; five verbs (§3) and nine
rules (§4) copied without paraphrase drift; §7 invariants match concept
§22 twelve items exactly.
- [ ] `specs/PhaseManifestSpecification.md` — field tiers match
`schemas/phase_manifest.schema.json` (already implemented, WP-0002-T02);
`phase.longstop_at` is explicitly labeled a Stage 0 working default
(Q8), not silently presented as permanent Rule 1 scope.
- [ ] `specs/TargetLedgerSpecification.md` — entry-type table matches
`schemas/ledger_entry.schema.json`; the `administrative-correction`
"Stage 0 simplification" note in §2 is flagged for maintainer judgment
— this is the one place this extraction added interpretation beyond a
direct concept citation (concept §17 lists the entry type but does not
specify its fold-side effect).
- [ ] `specs/MonetizationExtensionSpecification.md` — six-field contract
matches concept §12; registered/canonical distinction matches concept
§12.1–§12.2; Stage 0 catalog table (Q11) correctly shows
`product-ideation` and `general-consulting` as not yet fixture-backed.
- [ ] Cross-links (T05) — confirm PRD §6.1/§6.2, TSD §0/§1.1, README, and
CONTRIBUTING.md all point at the new extracts without contradicting
`spec/TargetRevenueLicenseConcept.md` as ultimate authority.
- [ ] No open question (concept §24) is answered by omission — each extract
either cites a working default explicitly or states the item remains
open.
Once accepted, update this task's `status` to `done` and record
`human_accepted_by` / `human_accepted_at`, following the ADR-0001 /
WP-0002-T01 pattern.