tegwick
55a1756f7c
Moves TargetRevenueLicenseConcept.md from the separate singular spec/ directory into specs/ (git mv, preserving history) and updates every live cross-reference (README, CONTRIBUTING, all specs/*.md, workplans, schema comments, source docstrings, test file) to the new path. This resolves the spec/ vs specs/ split that history/260728-SWOT-Assessment.md flagged as a "perpetual footgun" and recommended deciding on. The historical record of that split and the recommendation itself are left unedited in history/ (a dated assessment, not a living document) — only README and TSD now document the merge as resolved, with a pointer back to that history file for context. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
70 lines
5.2 KiB
Markdown
70 lines
5.2 KiB
Markdown
# Monetization Extension Specification (Normative Extract)
|
||
|
||
**Document version:** TRF-Extension-0.1
|
||
**Status:** Normative extract, Stage 0
|
||
**Extracted from:** `specs/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).
|