target-revenue/specs/TargetRevenueControlPlaneConcept.md

Target Revenue Control Plane — Concept

Status: Concept v0.1 Date: 2026-07-30 Workplan: workplans/TREV-WP-0009-target-revenue-control-plane.md Primary artifacts: specs/TrustServiceProductRequirementsDocument.md, src/target_revenue/service/app.py, specs/TRSL-Governance.md §1 (Licensor identity), scripts/trf_onboard.py

Scope note: this is a concept, not an implementation. It defines what the Control Plane UI is for, who uses it, and what it must and must not be able to do — building directly on the hosted Trust Service (workplans/TREV-WP-0006-trust-service-implementation.md, finished) and the onboarding mechanism (specs/TrustServiceOnboarding.md) rather than replacing either.

---

1. Purpose

Everything in scripts/trf_onboard.py today is a CLI, operated by whoever has shell access and the Licensor's token in an environment variable. That is adequate for the dry-run routine already exercised (info-tech-canon), but not adequate for an actual "binky tenant" user — someone who should be able to interactively register Phases, review Phase status, and — the maintainer's specific requirement — interactively create Development Credit ledger entries, without needing to construct raw JSON payloads or hold the Licensor's raw API token directly in their own shell environment.

The Control Plane is a web (or equivalent interactive) front end over the existing hosted Trust Service API (service/app.py), for the binky tenant specifically, not a replacement for that API or a new Trust Service instance.

2. Users and rights model — the actual new design gap

This is the concept's main open design question, not something WP-0006 already solved: WP-0006's auth model is one token per Licensor (migrations/0001_registries.sql's licensors table), sufficient for a 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):

Right	Can do
Viewer	Read Phase status, metrics, ledger, attestations, breach records (all already public per FR-9/FR-10 — a Viewer arguably needs no new auth at all, since these are unauthenticated reads today)
Contributor	Everything Viewer can, plus: submit a proposed Development Credit entry for review (not directly appended)
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.

3. Core interactive flow: creating a Development Credit entry

The maintainer's specific requirement. Concretely, for an Operator-tier user:

1. Select a registered Phase (from a list, via GET /phases/{id} reads — already public, already implemented).
2. Fill a form for a new development-credit ledger entry: amount, currency, recognized date, evidence reference, applicable Monetization Extension (selected from specs/CanonicalMonetizationProfiles.md's catalog, not free text).
3. The Control Plane server-side calls POST /phases/{id}/ledger (ledger.append_entry, already implemented, WP-0006-T04) using the binky Licensor token it holds — the human user never sees or handles that token directly.
4. The Control Plane records, in its own audit log (§5), which human user initiated this specific entry, alongside the Trust Service's own returned signed record.
5. Display the updated Phase status (GET /phases/{id}/metrics, already implemented) immediately after, so the user sees the effect of what they just did.

Nothing here requires changing the Ledger append API itself — the Control Plane is a client of it, exactly like scripts/trf_onboard.py is today, just interactive and multi-user rather than single-shot CLI.

4. Other interactive capabilities (lower priority than §3)

• Registering a new Phase, using the Development Effort Calculator (specs/DevelopmentEffortCalculatorConcept.md) to help populate target_basis, rather than requiring the user to hand-author a JSON manifest.
• Viewing the Breach/Compliance Record history for a Phase and initiating a new breach/cure/determined event (Operator+ only, per License V1C1 §7.4's Licensor-determination principle — the Control Plane must not let this become the Control Plane's own discretionary judgment about whether a breach occurred, consistent with TSD §4.1's forbidden-action column).
• Viewing the Conversion Attestation once a Phase converts (read-only, already public).

5. Audit logging — a Control Plane responsibility, not a Trust Service one

Every write action taken through the Control Plane must be logged with: which human user, what action, when, and the resulting Trust-Service- signed record's id — in the Control Plane's own storage, since the Trust Service itself has no concept of individual human users under one Licensor token (§2). This log is the answer to "who actually clicked the button," which matters operationally even though it's not part of the Trust Service's own cryptographic guarantees.

6. Explicit non-goals

• Replacing scripts/trf_onboard.py — the CLI remains valid for scripted/CI use; the Control Plane is for interactive human use.
• Changing the Trust Service's core guarantees (determinism, append-only, no discretionary conversion authority) — the Control Plane is a client, bound by the same rules any other client is.
• Deciding the human-user rights model unilaterally — §2 is a proposal for workplan T01 to confirm, not a decided design.
• Multi-tenant support for Licensors other than binky — in scope structurally (the Trust Service already supports multiple Licensors, TS-FR-8), but this concept is scoped to the one tenant that currently exists; extending the UI to other tenants is natural future work, not blocking this concept.