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

Accept WP-0009-T01: rights tiers confirmed, option (a) chosen over recommendation

Browse source 
Maintainer (Bernd) accepted 2026-07-30: four rights tiers
(Viewer/Contributor/Operator/Admin) confirmed as proposed. Selected
option (a) - per-human sub-credentials at the Trust Service layer -
over this concept's own recommended option (b), meaning the Trust
Service's signed ledger records can attest to the specific human who
acted, not merely the binky tenant.

This adds a real, firm prerequisite the workplan didn't have before:
extending WP-0006's already-finished licensors/token auth model.
Restructured T02 (was: backend+audit) into T02 (WP-0006 auth
extension, new) + T03 (Control Plane backend, renumbered) + T04
(interactive UI, renumbered) to keep that scope visible as its own
task rather than folding it silently into backend work.
This commit is contained in:
tegwick 2026-07-30 13:06:36 +02:00
parent 757cbbc371
commit 50b25947f9
3 changed files with 72 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

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

42
specs/TargetRevenueControlPlaneConcept.md
View file

@ -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

66
workplans/TREV-WP-0009-target-revenue-control-plane.md
View file

@ -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