target-revenue/workplans/TREV-WP-0012-phase-provenance-and-policy-modeling.md

---
id: TREV-WP-0012
type: workplan
title: "Phase provenance, ledger reference, and degeneration-policy modeling"
domain: infotech
repo: target-revenue
status: active
owner: claude
topic_slug: infotech
created: "2026-07-30"
updated: "2026-07-30"
state_hub_workstream_id: "763a31ee-85fe-43d0-9040-1e6fd432601c"
---

# Phase provenance, ledger reference, and degeneration-policy modeling

Triggered by using the Control Plane UI for the first time (WP-0009-T04):
the Phase registration form asked for a bare `source_revision` with no
repo attribution, a hand-typed `ledger` URI, and an opaque
`degeneration_policy` id with no way to see what it actually specifies.
These aren't UI bugs — the Phase Manifest schema
(`schemas/phase_manifest.schema.json`) itself doesn't yet carry the
structure the UI would need to show any of this properly, and FR-11
(Successive Phases, `specs/ProductRequirementsDocument.md`) already commits
the framework to base-release/prior-Phase provenance that the schema has
never modeled either.

This is a **modeling-only** workplan: it produces documents (a use-cases
spec and a discussable spec addendum) and decisions, not schema or UI
changes. Implementation follows in later workplans once the addendum is
reviewed (T05).

```task
id: TREV-WP-0012-T01
status: done
priority: high
state_hub_task_id: "2871b8ff-b845-4ed4-aaa1-8fdfd1f601b7"
```

**Write the use-cases document**, as its own spec file (not folded into
`specs/PhaseManifestSpecification.md`) — working title
`specs/PhaseLifecycleUseCases.md`. Cover, systematically, at minimum:

1. First Phase ever declared for a repo (the three real pilot candidates:
   `net-kingdom`, `railiance-vergabe-teilnahme`, `info-tech-canon`).
2. A successive Phase on a repo that already had an earlier, converted
   Phase (FR-11) — including what "base release" means when the prior
   Phase's Milestone Release is itself the base.
3. Operator registers a Phase; Contributor proposes a Development Credit;
   Operator/Admin reviews (already built, WP-0009 — include for
   completeness/cross-reference, not to redesign it).
4. Remission Credit accrual over time under the active degeneration
   policy — note as an open gap for WP-0013, not solved here.
5. Conversion Event fires, Attestation published — note as a UI gap for
   WP-0014.
6. Monetization Extension registration and canonical-status review — note
   as a UI gap for WP-0014.
7. Breach/Compliance Record publication — note as a UI gap for WP-0014.
8. A second Licensor tenant besides `binky` onboards.
9. An external auditor verifies a Phase's evidence package offline,
   without needing to trust or even reach the Control Plane UI (FR-8/FR-9
   — call out explicitly that this use case has *no* UI surface by
   design, so it doesn't get silently forgotten as "not yet built").

**Result:** `specs/PhaseLifecycleUseCases.md` written, covering all nine
use cases. Two findings worth flagging beyond the original scope: (a) use
case 2 (successive Phases) and use case 1 (first Phase) turned out to
share one underlying provenance model rather than being separate
concerns, so T02 below covers both together; (b) cross-checking
`specs/TargetRevenueControlPlaneConcept.md` §2's rights table while
writing use cases 6–7 found that breach-record publication already has a
decided rights tier (Operator+) but extension registration/canonicalization
does not — that's now recorded as an explicit open question for
WP-0014-T01 rather than something to assume while building that UI.

```task
id: TREV-WP-0012-T02
status: done
priority: high
human_accept_required: true
human_accepted_by: Bernd
human_accepted_at: "2026-07-30"
state_hub_task_id: "1d888dc7-360d-4ee5-8f4c-d1173670b0f7"
```

**Decide repo identification and Phase-provenance fields (human gate).**
Per direction already given: identity rests on the Forgejo instance
("home hub") plus the repo's own stable id within that instance, *and*
the Forgejo service URI and repo name are also retained (not derived) —
so a rename or instance move stays repairable rather than silently
breaking a Phase's provenance link. Concretely decide and record:

- Field names/shape for `milestone_release`: a hub identifier, a
  Forgejo-internal repo id, the Forgejo service URI, and the repo name
  (owner/repo slug) — four values, not one string.
- Whether this is required or recommended for Stage 0 (precedent:
  `longstop_at` moved from recommended to required under a working
  default, `specs/OpenQuestions-WorkingDefaults.md` Q8).
- How a successive Phase (use case 2 above) references its base — a
  `trsl:phase:...` id, and what a first-ever Phase puts there instead
  (null, or an explicit "no prior Phase" marker — decide which is
  cleaner for fold/validation logic downstream).
- Whether any of this is retroactively backfillable for the three
  existing pilot-candidate example manifests, or only required going
  forward.

**Result (accepted 2026-07-30):** Grounded against the real Forgejo
instance before deciding, not assumed — confirmed live that
`forgejo.coulomb.social` assigns every repo a stable numeric id
(`target-revenue` is `103`, via `GET /api/v1/repos/coulomb/target-revenue`)
that survives renames, and confirmed it has **no** instance-level identity
endpoint (`/api/v1/nodeinfo` → 404, `/api/v1/version` returns only a
version string) — so unlike the repo id, a hub identifier is necessarily
something this project mints, not something Forgejo already provides.

Decided:

- `phase.milestone_release` gains four **required** fields: `repo_hub`
  (a stable slug, e.g. `"forgejo-coulomb"`), `repo_hub_uri` (the Forgejo
  service URL, e.g. `"https://forgejo.coulomb.social"`), `repo_id`
  (Forgejo's own numeric repo id), `repo_name` (`"owner/repo"` slug).
  Required immediately, not merely recommended — no grace period, unlike
  `target_basis`'s current recommended-only status.
- `phase.base_phase_id` (optional, `trsl:phase:...` pattern) references
  a prior Phase for a successive Phase; simply **absent** for a
  first-ever Phase — no sentinel value, matching how
  `ledger_entry.schema.json`'s `reverses` is already optional-only-when-
  applicable.
- **Important refinement from the maintainer's own steer**: the
  `repo_hub` → `repo_hub_uri` mapping is *not* static data checked into
  this repo. `target-revenue` is the generic framework, not a specific
  deployment's list of repos it happens to monetize — that mapping is
  operational data owned by the **hosted Trust Service** (a new table,
  analogous to `licensor_identities`, auto-populated the first time a hub
  is seen), never a file in this git repo. A Phase Manifest stays fully
  self-describing and offline-verifiable regardless (it carries
  `repo_hub_uri`/`repo_name` directly at registration time, per use case
  9) — the hosted table exists purely as an admin/repair convenience if
  a hub's URI ever needs correcting after the fact, not a validation
  dependency.
- The three existing example manifests will be backfilled — deferred
  until after T03/T04 and the T05 spec addendum, since the schema change
  is shared across all three decision tasks and the maintainer's own
  process (item f, chat 2026-07-30) calls for the addendum to be
  discussed before any implementation, including this backfill.

```task
id: TREV-WP-0012-T03
status: todo
priority: high
human_accept_required: true
state_hub_task_id: "dbbabc02-8694-4e7d-8a15-c626ff72875b"
```

**Decide the degeneration-policy / calculation-model spec-file
convention (human gate).** Per direction already given: every policy or
calculation model (this includes the Development Effort Calculator's own
Candidate A formula, `specs/DevelopmentEffortCalculatorConcept.md`, not
just degeneration policies) corresponds to a markdown specification file
with a simple, distinct name, an id, and a revision — built on git's own
mechanisms (commit hash and/or file path, no new versioning
infrastructure). Concretely decide:

- Where these spec files live (likely already `specs/*.md` — decide
  whether a dedicated subdirectory or naming convention is needed so a
  policy id like `trsl:policy:linear-longstop-v0` maps unambiguously to
  one file).
- What "id and revision, built on git internals" means precisely — e.g.
  the policy id embeds the file path and a pinned commit hash, or the
  file's own frontmatter carries an id/revision pair that a human commits
  to alongside code changes (check how `the-custodian`/state-hub already
  present read-only reference-documentation views linked by id, per the
  user's explicit steer to reuse that pattern rather than invent a new
  one, and follow whichever mechanism is actually in use there).
- How the Control Plane UI links a policy id shown next to a Phase to a
  **read-only** rendered view of that spec file — no in-UI editing,
  consistent with every other governance-action pattern in this project.
- Whether this same convention should also cover the six canonical
  monetization profiles (`specs/CanonicalMonetizationProfiles.md`) for
  consistency, or is scoped to degeneration policies and calculators only
  for now.

```task
id: TREV-WP-0012-T04
status: todo
priority: medium
human_accept_required: true
state_hub_task_id: "a1cf0180-2dc7-44bb-a34f-99b5e92f5144"
```

**Decide the ledger's UI treatment (human gate).** Per direction already
given: keep the `ledger` field in the schema — not as something the
standard Phase view surfaces, but as an internal reference reachable only
via an explicit drill-down/details action. This is intentional groundwork
for eventually supporting more than one ledger per Phase (federation,
`specs/ProductRequirementsDocument.md` NFR-3), not just a display
preference. Decide:

- What the drill-down actually shows (the raw ledger URI/reference plus a
  link to `GET /phases/{id}/ledger`'s live data, or something more), and
  where it lives in the Control Plane's navigation (a "details" link on
  `phase_detail.html` rather than a top-level field).
- Whether the Phase registration form still needs a `ledger` input at
  all going forward, or whether the Trust Service should compute/assign
  it automatically now that it is always the ledger's host in Stage 0 —
  distinct from the schema question of whether the field stays.

```task
id: TREV-WP-0012-T05
status: todo
priority: high
state_hub_task_id: "152b54a6-08a9-4ced-a5f6-d5638d102900"
```

**Draft the spec addendum** reflecting T01–T04's accepted decisions, for
review before any implementation — schema changes (`schemas/
phase_manifest.schema.json`), the policy-spec-file convention, and the
Control Plane UI changes it implies. Do not implement anything from this
task; it produces a reviewable document only. Once accepted, file the
implementation work as its own workplan(s), consistent with how WP-0009
and WP-0010 were split from a single combined plan.

## Related gaps spun out as their own workplans

Use cases 4, 6, and 7 above are bigger than a modeling exercise — they
are missing implementation, not missing documentation — and are tracked
separately rather than folded in here:

- `workplans/TREV-WP-0013-remission-credit-automation.md` — use case 4.
- `workplans/TREV-WP-0014-control-plane-extensions-breach-attestation-ui.md`
  — use cases 5, 6, 7.

Use case 8 (second Licensor tenant onboarding) is judged small enough to
stay under `workplans/TREV-WP-0008-governance-and-pilot-rollout.md`
rather than warrant its own workplan — revisit that call if it turns out
to need real design work once a second tenant is actually on the table.