diff --git a/README.md b/README.md index 3c0b06a..dfb7955 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ The concept's §13 now defines a **Global Contingency Share Determination Rule** | [TREV-WP-0006](workplans/TREV-WP-0006-trust-service-implementation.md) | Hosted Trust Service reference implementation (PRD Phase 4b) — **finished**, all 9 tasks done (Postgres-backed registries/ledger/metrics/attestation/breach-record, ADR-0002 accepted, onboarding CLI, hosted conformance suite) | | [TREV-WP-0007](workplans/TREV-WP-0007-degeneration-policy-and-canonical-profiles.md) | Degeneration policy + canonical monetization profile catalog — **finished**, all 4 tasks done. `trsl:policy:linear-longstop-v0` confirmed 2026-07-29 as the v1 norm for the first pilot cohort; `progress-paused-longstop-v1` named as the next iteration, not yet adopted | | [TREV-WP-0008](workplans/TREV-WP-0008-governance-and-pilot-rollout.md) | Governance formalization + pilot rollout — active; T01–T04 done. `info-tech-canon` dry-run onboarding routine exercised end-to-end 2026-07-29. **Org-wide TRSL license adoption executed 2026-07-30** across ~90 `coulomb`-org repos (`history/260730-TRSL-OrgWideLicenseRollout.md`) — a license-text adoption, not a Phase declaration. T05 (real Phase go-live gate) remains `todo` by design; no Phase exists yet for any repo | -| [TREV-WP-0009](workplans/TREV-WP-0009-target-revenue-control-plane.md) | Target Revenue Control Plane — interactive UI for the `binky` tenant, incl. interactive Development Credit entry creation (`specs/TargetRevenueControlPlaneConcept.md`) — active, concept only so far; T01 (rights-model human gate) not yet decided | +| [TREV-WP-0009](workplans/TREV-WP-0009-target-revenue-control-plane.md) | Target Revenue Control Plane — interactive UI for the `binky` tenant, incl. interactive Development Credit entry creation (`specs/TargetRevenueControlPlaneConcept.md`) — active; **T01 accepted 2026-07-30** (four rights tiers confirmed; per-human sub-credentials at the Trust Service layer chosen over the concept's own simpler recommendation) — adds a real prerequisite: T02 extends WP-0006's finished auth layer before T03 (Control Plane backend) and T04 (interactive UI) can proceed | | [TREV-WP-0010](workplans/TREV-WP-0010-development-effort-calculator.md) | Development Effort Calculator — turns human time/workplan-task volume/repo size/AI token cost into `target_basis` values feeding the framework's existing Initial Target formula (`specs/DevelopmentEffortCalculatorConcept.md`) — active; **T01 accepted 2026-07-30 (Candidate A, labor-cost-anchored)**; T02 (implementation) next. Split from TREV-WP-0009 2026-07-30 | Hub index: [`WORK-RECORDS.md`](WORK-RECORDS.md) · brief: [`.custodian-brief.md`](.custodian-brief.md) diff --git a/specs/TargetRevenueControlPlaneConcept.md b/specs/TargetRevenueControlPlaneConcept.md index d67851d..f193969 100644 --- a/specs/TargetRevenueControlPlaneConcept.md +++ b/specs/TargetRevenueControlPlaneConcept.md @@ -40,8 +40,8 @@ script or CI pipeline acting *as* the Licensor, but not sufficient for **multiple human users**, potentially with **different rights**, acting *on behalf of* the same Licensor tenant (`binky`). -**Candidate rights tiers** (not yet decided, proposed for workplan T01 to -resolve): +**Rights tiers — adopted 2026-07-30** (`workplans/TREV-WP-0009-target-revenue-control-plane.md` +T01, maintainer-accepted, as proposed): | Right | Can do | |---|---| @@ -50,24 +50,26 @@ resolve): | Operator | Everything Contributor can, plus: directly append Development Credit/Remission Credit entries, register new Phases, publish breach/compliance records | | Admin | Everything Operator can, plus: manage which human users hold which right within the `binky` tenant | -**Design tension to resolve, not paper over:** WP-0006's Ledger append API -(`ledger.append_entry`) currently authenticates a single Licensor token, -not an individual human user — so "Operator Alice" and "Operator Bob" -both acting for `binky` are currently indistinguishable at the API layer -(both just look like "the `binky` token"). Either (a) the Control Plane -issues per-human-user sub-credentials that map to the same underlying -Licensor identity (requiring a schema/API change in WP-0006's auth -layer — a real, scoped follow-on task), or (b) the Control Plane holds -the one Licensor token server-side and layers its own human-user -authentication/authorization in front of it, recording *which human* -took an action in its own audit log distinct from the Trust Service's -own record (simpler, no WP-0006 changes required, but the Trust -Service's own signed records still only attest "the `binky` Licensor did -this," not "Alice, acting for `binky`, did this"). **Recommendation: start -with (b)** — it requires no changes to the already-finished, tested -WP-0006 auth model, and the Control Plane's own audit log (§5) can carry -the finer-grained human-attribution that the Trust Service's own -cryptographic signature does not need to. +**Design tension — resolved 2026-07-30, option (a) adopted, not (b):** +WP-0006's Ledger append API (`ledger.append_entry`) currently +authenticates a single Licensor token, not an individual human user — so +"Operator Alice" and "Operator Bob" both acting for `binky` are currently +indistinguishable at the API layer (both just look like "the `binky` +token"). The maintainer selected **(a): the Control Plane issues +per-human-user sub-credentials that map to the same underlying Licensor +identity**, over this document's own recommendation of (b) — meaning a +real, scoped auth-schema extension to WP-0006's already-finished +`licensors`/token model is now a genuine prerequisite for T02/T03, not a +hypothetical branch. The payoff: the Trust Service's own signed ledger +records can attest to the specific human who acted, "Alice, acting for +`binky`, did this," not merely "the `binky` Licensor did this" — a +stronger audit guarantee than (b) would have given, at the cost of +touching WP-0006's tested auth layer. See +`workplans/TREV-WP-0009-target-revenue-control-plane.md` T02 for the +resulting scope. (This document had recommended the simpler alternative +— the Control Plane holding one server-side token and layering its own +human-user audit log in front of it, with no WP-0006 changes required — +but the maintainer's choice of (a) is the adopted answer.) ## 3. Core interactive flow: creating a Development Credit entry diff --git a/workplans/TREV-WP-0009-target-revenue-control-plane.md b/workplans/TREV-WP-0009-target-revenue-control-plane.md index c1aa926..8320d03 100644 --- a/workplans/TREV-WP-0009-target-revenue-control-plane.md +++ b/workplans/TREV-WP-0009-target-revenue-control-plane.md @@ -27,7 +27,7 @@ ledger entries, rather than requiring raw API calls or the with its own formula decision and implementation arc; it now lives in `workplans/TREV-WP-0010-development-effort-calculator.md`. The two remain related (the Control Plane's Phase-registration flow is expected to use -the Calculator's output, per T03 below) but are sequenced and reviewed +the Calculator's output, per T04 below) but are sequenced and reviewed independently. **Does not include:** declaring any real Phase for any repo, or changing @@ -41,9 +41,11 @@ Concept: `specs/TargetRevenueControlPlaneConcept.md`. ```task id: TREV-WP-0009-T01 -status: todo +status: done priority: high human_accept_required: true +human_accepted_by: Bernd +human_accepted_at: "2026-07-30" state_hub_task_id: "177117e7-955b-4f12-b17b-75ee3f0357c4" ``` @@ -56,37 +58,67 @@ per-human sub-credentials (option (a)). Confirm the rights tiers and the (a)-vs-(b) choice, or propose a refinement. Agents may prepare a recommendation and leave this `todo`. -## Control Plane backend: auth layer and audit log +**Accepted 2026-07-30 by the maintainer (Bernd):** the four rights tiers +are confirmed as proposed. **Option (a) is adopted, not (b)** — the +Control Plane will issue per-human-user sub-credentials at the Trust +Service layer, mapped to the same underlying `binky` Licensor identity, +so that the Trust Service's own signed ledger records can attest to the +specific human who acted, not merely "the `binky` Licensor did this." +This means a real, scoped extension to WP-0006's already-finished +`licensors`/token auth model is now a firm prerequisite, not a +hypothetical branch — see T02 below, added specifically for this reason. + +## WP-0006 auth extension: per-human sub-credentials ```task id: TREV-WP-0009-T02 status: todo priority: high -state_hub_task_id: "86a58e61-dccd-4678-b694-22a9eaea2b3c" ``` -Using T01's confirmed rights model, implement the human-user -authentication/authorization layer and the Control Plane's own audit log -(concept §5) — which human user took which action, timestamped, alongside -the Trust Service's own signed record id for that action. This is the -piece that must exist before any write-capable UI flow (T03) can be built -responsibly, since the Trust Service's own signature only ever attests -"the `binky` Licensor did this," never which individual human initiated -it (concept §2's design tension). +Extend `migrations/0001_registries.sql`'s `licensors`/token model and +`src/target_revenue/registry.authenticate` so a single Licensor identity +(`binky`) can have multiple, individually-issued, individually-revocable +sub-credentials, each resolving to the same `licensor_id` for phase- +ownership checks (`registry.py`, `ledger.py`) but distinguishable in the +returned `Licensor`/signing context so a ledger entry's signature (or an +accompanying attributable field) can reflect *which* sub-credential +signed it. This is a change to WP-0006's finished, tested auth layer — +treat it with the same care as any change to already-shipped, tested +code: new tests proving existing single-token behavior is unaffected, +plus new tests for the sub-credential path. Does not change the Ledger's +append-only guarantees or the hash-chain/signature scheme itself, only +who may authenticate as `binky` and how that's distinguished. -## Control Plane interactive UI: Phase registration and Development Credit entry +## Control Plane backend: auth layer and audit log ```task id: TREV-WP-0009-T03 status: todo priority: high +state_hub_task_id: "86a58e61-dccd-4678-b694-22a9eaea2b3c" +``` + +Using T02's sub-credential extension, implement the Control Plane's own +human-user authentication/authorization layer (issuing and managing +sub-credentials per the four rights tiers) and its own audit log +(concept §5) — which human user took which action, timestamped, alongside +the Trust Service's own signed record id for that action. This is the +piece that must exist before any write-capable UI flow (T04) can be built +responsibly. + +## Control Plane interactive UI: Phase registration and Development Credit entry + +```task +id: TREV-WP-0009-T04 +status: todo +priority: high state_hub_task_id: "01b295f2-8f97-4fc4-a14e-6f68aa85458d" ``` -Implement the interactive flows themselves, using T02's auth/audit layer -and the existing hosted Trust Service API (`service/app.py`) as the -backend, unmodified unless T01 specifically selected the -per-human-sub-credential option: +Implement the interactive flows themselves, using T03's auth/audit layer +and the existing hosted Trust Service API (`service/app.py`) plus T02's +sub-credential extension as the backend: - Phase registration, informed by `workplans/TREV-WP-0010-development-effort-calculator.md`'s output