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

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).