135 lines
5.7 KiB
Markdown
135 lines
5.7 KiB
Markdown
---
|
|
id: TREV-WP-0009
|
|
type: workplan
|
|
title: "Target Revenue Control Plane"
|
|
domain: infotech
|
|
repo: target-revenue
|
|
status: active
|
|
owner: claude
|
|
topic_slug: infotech
|
|
created: "2026-07-30"
|
|
updated: "2026-07-30"
|
|
state_hub_workstream_id: "0e8dfd43-a742-4458-9e9b-514a9284821b"
|
|
---
|
|
|
|
# Target Revenue Control Plane
|
|
|
|
An interactive UI over the hosted Trust Service
|
|
(`workplans/TREV-WP-0006-trust-service-implementation.md`, finished),
|
|
usable by a human user with appropriate rights acting as the `binky`
|
|
tenant. The specific, named requirement driving this workplan: make it
|
|
possible to interactively register Phases and create Development Credit
|
|
ledger entries, rather than requiring raw API calls or the
|
|
`scripts/trf_onboard.py` CLI.
|
|
|
|
**Split from the former combined `TREV-WP-0009-control-plane-and-effort-calculator.md`
|
|
(2026-07-30)** — the Development Effort Calculator is a separate concern
|
|
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 T04 below) but are sequenced and reviewed
|
|
independently.
|
|
|
|
**Does not include:** declaring any real Phase for any repo, or changing
|
|
the Trust Service's core guarantees (determinism, append-only, no
|
|
discretionary conversion authority) — the Control Plane is a client of
|
|
the existing hosted service, bound by the same rules any other client is.
|
|
|
|
Concept: `specs/TargetRevenueControlPlaneConcept.md`.
|
|
|
|
## User rights model — decision (human gate)
|
|
|
|
```task
|
|
id: TREV-WP-0009-T01
|
|
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"
|
|
```
|
|
|
|
`specs/TargetRevenueControlPlaneConcept.md` §2 proposes a four-tier rights
|
|
model (Viewer/Contributor/Operator/Admin) and recommends option (b) for
|
|
the auth-attribution question: the Control Plane holds the one `binky`
|
|
Licensor token server-side and layers its own human-user auth/audit log
|
|
in front of it, rather than requiring a WP-0006 schema change for
|
|
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`.
|
|
|
|
**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: "52ae3a7a-6b55-4694-8bc1-cb0e32a4fe31"
|
|
```
|
|
|
|
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 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 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
|
|
once available (not blocking — a manual `target_basis` entry path must
|
|
work standalone too, since the Calculator may not be ready first);
|
|
- the priority flow: interactively creating a `development-credit` ledger
|
|
entry against a selected, already-registered Phase (concept §3's
|
|
step-by-step description) — select Phase, fill amount/currency/
|
|
recognized-date/evidence-reference/Monetization-Extension, submit,
|
|
immediately show the updated `GET /phases/{id}/metrics` result;
|
|
- read-only views (Phase status, Ledger, Attestation, Breach/Compliance
|
|
Record history) — already public/unauthenticated at the Trust Service
|
|
layer, so these need no new backend work, only UI.
|