# Phase Lifecycle Use Cases

`workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md` T01.
Written after using the Control Plane UI (WP-0009-T04) for the first time
surfaced that the Phase Manifest schema and the UI built on top of it
don't yet cover several use cases the framework's own normative documents
already commit to. This document enumerates those use cases systematically
— **as a map of what exists, what's missing, and what's out of scope by
design** — before T02–T05 turn any of the gaps into schema or UI
decisions.

This is a documentation-only artifact. It does not itself change any
schema, code, or UI.

---

## 1. First Phase ever declared for a repo

The common case today: a repo has never had a Phase before, and one is
declared for its first governed Milestone Release.

**Real examples** (`examples/pilot-candidates/*/manifest.json`,
`specs/PilotPhaseCandidateSurvey.md`): `net-kingdom-local-identity`,
`railiance-vergabe-teilnahme`, `info-tech-canon-service-surface`. All
three currently use a `trsl:phase:draft-...` id — none has actually been
registered against the hosted Trust Service. That's intentional: no real
Phase go-live is authorized yet
(`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` T05).

**What the manifest captures today**: `milestone_release.name` (a free-text
label, e.g. `"vergabe-teilnahme-v1 (RAILIANCE-WP-0002/RAILIANCE-WP-0014)"`)
and `milestone_release.source_revision` (a bare short SHA, e.g.
`"398b0fe"`). **What it does not capture**: which repo, or which Forgejo
instance, that revision belongs to. The workplan references embedded in
the `name` string are the only thing tying a Phase back to its source
today, and they're prose, not structured data — a human convention, not
something the schema or the UI can rely on.

**Gap → WP-0012-T02** (repo identification fields).

---

## 2. A successive Phase on a repo that already had an earlier Phase

FR-11 (`specs/ProductRequirementsDocument.md`) requires the framework to
"support multiple independently governed, sequential Phases over a
software's lifetime, each identifying its base release, included change
set, Milestone Release, Initial Target, Future License, degeneration
policy, and ledger." Rule 7 (`specs/TargetRevenueFrameworkCore.md` §4)
then requires that rights already granted by an earlier converted
Milestone Release can never be withdrawn or restricted by a later Phase.

**None of this is modeled in the schema today.** There is no field
anywhere in `phase_manifest.schema.json` for "the Phase this one
succeeds" or "the base release this Phase's change set is measured
against." A second Phase for the same repo today would look, structurally,
identical to a completely unrelated repo's first Phase — the only
difference would be human-readable text in `milestone_release.name`.

This matters concretely: `railiance-vergabe-teilnahme`'s candidate manifest
already names two workplans (`RAILIANCE-WP-0002/RAILIANCE-WP-0014`)
inside a single Milestone Release's `name` — a preview of exactly this
use case arriving before the schema was ready for it.

**Open question this use case raises, not yet answered**: what does a
first-ever Phase put in a "base Phase" field that a successive Phase
would use? A null/absent value works structurally, but the Trust
Service's fold and validation logic downstream should treat "no prior
Phase" and "prior Phase exists" as two branches it explicitly recognizes,
not an accidentally-empty string.

**Gap → WP-0012-T02** (repo identification fields, same task — the two
questions are tightly coupled: "which repo" and "which prior Phase for
that repo" are really one provenance model, not two).

---

## 3. Operator registers a Phase; Contributor proposes; Operator/Admin reviews

**Already built** (`workplans/TREV-WP-0009-target-revenue-control-plane.md`,
all four tasks done). Included here for completeness and cross-reference,
not to redesign it:

- Rights model: Viewer / Contributor / Operator / Admin, ordinal via
  `registry.RIGHTS_TIERS`/`has_right()`
  (`specs/TargetRevenueControlPlaneConcept.md` §2's table).
- Operator+ registers a Phase (`control_plane.register_phase`) and
  appends Development Credit directly
  (`control_plane.append_development_credit`).
- Contributor submits a proposed entry instead
  (`control_plane.propose_ledger_entry`); Operator+ approves (appending
  under the *reviewer's own* credential,
  `control_plane.approve_proposed_entry`) or rejects
  (`control_plane.reject_proposed_entry`).
- Every action is recorded in the Control Plane's own audit log
  (`control_plane.record_audit_event`/`get_audit_log`), independent of
  the Trust Service's own signed records, which only ever attest "the
  `binky` tenant acted," never which individual human.
- UI: `service/control_plane_app.py` + `service/control_plane_templates/`
  (WP-0009-T04).

No gap here, no follow-up workplan.

---

## 4. Remission Credit accrual over time under the active degeneration policy

`trsl:policy:linear-longstop-v0` (the accepted v1 norm,
`specs/OpenQuestions-WorkingDefaults.md` Q7) defines
`R(t) = T0 × clamp((t − t0)/(tL − t0), 0, 1)`, with discrete
`remission-credit` ledger entries computed on a published schedule. FR-6
(`specs/ProductRequirementsDocument.md`) requires this to actually happen.

**Nothing in this codebase computes or writes these entries.**
`fold.py` can *consume* a `remission-credit` entry if one exists in the
ledger; nothing produces one. This is not a Control Plane UI gap — it
predates the UI entirely, and was never in scope for WP-0006 (Trust
Service) either. It surfaced now only because working through this
use-case list prompted a fuller look at what a Phase's lifecycle actually
requires end to end, not because anything about the recent UI work
introduced it.

**Gap → `workplans/TREV-WP-0013-remission-credit-automation.md`**
(its own workplan, not folded into this modeling pass, since it's a
missing *implementation*, not a missing *decision*).

---

## 5. Conversion Event fires; Attestation published

FR-7 defines the Conversion Event as the objective moment Outstanding
Target reaches zero, computable from the Manifest + Ledger alone, with no
Trust Service declaration required (`attestation.py`'s module docstring:
"a Conversion Event is true the instant the ledger fold first reaches
Outstanding Target = 0, independent of whether anything ever publishes an
attestation about it"). `attestation.publish_attestation` is implemented,
tested, and exposed at `GET /phases/{id}/attestation` — idempotent,
publish-on-first-observation, never regenerated.

**Resolved 2026-08-05** (WP-0014-T03): `phase_detail.html` shows the
Conversion Attestation (Future License, final credits, ledger checkpoint,
signature) via idempotent `get_or_publish_attestation` on page load.

---

## 6. Monetization Extension registration and canonical-status review

FR-4 defines the six-field extension contract; `registry.register_extension`
and `registry.promote_extension_canonical` are implemented and tested.
Canonicalization is a governance action (`set_extension_status`,
SECURITY DEFINER, never a plain `UPDATE`) — the same pattern already used
for credential revocation and proposed-entry review elsewhere in this
project.

**Resolved 2026-08-05** (`workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md`
T01, all four tasks finished):

- Control Plane UI: `GET/POST /extensions`, Admin promote-to-canonical.
- Rights (now in `specs/TargetRevenueControlPlaneConcept.md` §2):
  **Operator+** registers; **Admin** promotes to canonical. Trust Service
  `POST /extensions` remains open to any authenticated tenant token —
  Control Plane policy is layered on top.

---

## 7. Breach/Compliance Record publication

FR-10 and License V1C1 §7.4: a Licensor's own breach/termination
determination, anonymized (Phase + category only) by default, named only
with an explicit Commercial Use Agreement opt-in.
`breach_record.publish_breach_event`/`get_breach_records` are implemented
and tested. Rights tier is Operator+
(`specs/TargetRevenueControlPlaneConcept.md` §2).

**Resolved 2026-08-05** (WP-0014-T02): Control Plane form + list on
`phase_detail.html`; named disclosure requires explicit CUA-authorization
affirmation (records the assertion; does not verify CUA text).

---

## 8. A second Licensor tenant besides `binky` onboards

Today, `binky` is the only Licensor identity in every environment (test
fixtures, the local dev instance, presumably any eventual deployment).
`registry.create_licensor_identity`/`issue_sub_credential` support a
second tenant structurally and are exercised in tests, but never in any
real onboarding flow — there is no "onboard a new Licensor" use case
documented anywhere, only "issue another credential for the Licensor that
already exists."

**Judged not to need its own workplan** (per the decision recorded in
`workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md`'s
closing section) — this is squarely a governance matter and belongs under
`workplans/TREV-WP-0008-governance-and-pilot-rollout.md` if and when a
second real tenant is actually on the table. Revisit that call if it
turns out to need real design work once that happens, rather than
speculatively designing it now.

---

## 9. An external auditor verifies a Phase's evidence package offline

FR-8/FR-9: a complete Phase evidence package (manifest, ledger,
extensions, attestation) can be exported in an open format and
independently verified — recomputing the fold, checking the Ed25519
signature chain — **without trusting, or even being able to reach, the
Trust Service or the Control Plane at all** (NFR-1 determinism/
reproducibility; `attestation.py`'s own docstring makes the same point
about conversion status specifically).

**This use case has, by design, no Control Plane UI surface.** Recording
it here explicitly so it doesn't get silently miscounted as "not yet
built" alongside cases 4–7 above, which *are* real gaps. `fold.py` and
`hashing.py` are the offline-verifiable surface this use case depends on;
both are already implemented, tested, and covered by the hosted
conformance suite (`tests/test_hosted_conformance.py`).

---

## Summary table

| # | Use case | Status |
|---|---|---|
| 1 | First Phase for a repo | Done (WP-0015 provenance fields) |
| 2 | Successive Phase, same repo | Done (WP-0015 `base_phase_id`) |
| 3 | Register / propose / review (rights model) | Done (WP-0009) |
| 4 | Remission Credit accrual | Done (WP-0013) |
| 5 | Conversion Attestation view | Done (WP-0014-T03) |
| 6 | Extension registration/canonicalization | Done (WP-0014-T01) |
| 7 | Breach/Compliance Record | Done (WP-0014-T02) |
| 8 | Second Licensor tenant onboarding | Structurally supported, no onboarding flow — deferred to WP-0008 |
| 9 | Offline evidence verification | Done by design, no UI needed |