From 51aa55dcb248b552ce63c0737d4282c0a6d6ecbc Mon Sep 17 00:00:00 2001 From: codex Date: Sun, 23 Aug 2026 01:38:29 +0200 Subject: [PATCH] docs(RMASTER-WP-0025): define universal rapp coverage Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a02b90-83bf-75c2-81c8-aa705414e4d4 --- WORK-RECORDS.md | 4 + .../adr/ADR-0007-rapp-declaration-contract.md | 31 ++++- schemas/README.md | 33 +++++ ...P-0025-universal-rapp-workload-coverage.md | 120 ++++++++++++++++++ 4 files changed, 186 insertions(+), 2 deletions(-) create mode 100644 workplans/RMASTER-WP-0025-universal-rapp-workload-coverage.md diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 937e225..d89a422 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -9,6 +9,7 @@ | Kind | ID | Status | Lane | Source | | --- | --- | --- | --- | --- | | workplan | RMASTER-WP-0020 | blocked | — | workplans/RMASTER-WP-0020-openbao-migration-to-reef-railiance.md | +| workplan | RMASTER-WP-0025 | finished | — | workplans/RMASTER-WP-0025-universal-rapp-workload-coverage.md | | task | RMASTER-WP-0020-T01 | done | — | workplans/RMASTER-WP-0020-openbao-migration-to-reef-railiance.md | | task | RMASTER-WP-0020-T02 | done | — | workplans/RMASTER-WP-0020-openbao-migration-to-reef-railiance.md | | task | RMASTER-WP-0020-T03 | done | — | workplans/RMASTER-WP-0020-openbao-migration-to-reef-railiance.md | @@ -18,3 +19,6 @@ | task | RMASTER-WP-0020-T07 | done | — | workplans/RMASTER-WP-0020-openbao-migration-to-reef-railiance.md | | task | RMASTER-WP-0020-T08 | wait | — | workplans/RMASTER-WP-0020-openbao-migration-to-reef-railiance.md | | task | RMASTER-WP-0020-T09 | progress | — | workplans/RMASTER-WP-0020-openbao-migration-to-reef-railiance.md | +| task | RMASTER-WP-0025-T01 | done | — | workplans/RMASTER-WP-0025-universal-rapp-workload-coverage.md | +| task | RMASTER-WP-0025-T02 | done | — | workplans/RMASTER-WP-0025-universal-rapp-workload-coverage.md | +| task | RMASTER-WP-0025-T03 | done | — | workplans/RMASTER-WP-0025-universal-rapp-workload-coverage.md | diff --git a/docs/adr/ADR-0007-rapp-declaration-contract.md b/docs/adr/ADR-0007-rapp-declaration-contract.md index af29f09..47e41f4 100644 --- a/docs/adr/ADR-0007-rapp-declaration-contract.md +++ b/docs/adr/ADR-0007-rapp-declaration-contract.md @@ -2,9 +2,9 @@ id: RMASTER-ADR-0007 title: "Rapp Declaration Contract" status: accepted -revision: "accepted-1" +revision: "accepted-2" owner: railiance-master -last_reviewed: "2026-08-13" +last_reviewed: "2026-08-23" review_interval: 6m --- @@ -64,6 +64,27 @@ dimensions. Decision `d07ee5f9` already recorded this from the fields. Reef `bound_rapps` is a derived projection of `rapp.bound_reefs`, not a hand-maintained registry. +5. **Coverage includes every managed running deployable.** Application, + operational, and tooling runtimes participate in the same exactly-one-rapp + invariant when they are installed, scheduled, or otherwise operated as a + managed deployable. This includes a managed one-shot Job; it does not turn + a human command or approval act into a workload. Human access, credential + patterns, broker actions, one-off operational acts, and infrastructure + resources that are not workloads retain their native actor, lane, activity, + or resource identity. + + A running deployable that predates rapp extraction is migration debt. Until + an authoritative declaration claims it, workload-based controls report it + as `unknown`; they do not infer a rapp from its repository, namespace, path, + labels, or apparent owner. A subject explicitly established as not being a + workload is `not-applicable`. `unknown` and `not-applicable` are different + outcomes and omission must not collapse them. + + Railiance Master remains the sole owner of the normative rapp vocabulary and + schemas. Consumer catalogs may store explicit references and integration + owners may resolve them, but neither creates a parallel declaration surface + or copies rapp metadata as another source of truth. + The detailed shapes, including the single normative form of the rollout, smoke, and rollback contracts, live in the schema files and `schemas/README.md`. @@ -81,6 +102,12 @@ smoke, and rollback contracts, live in the schema files and `rapp-user-engine`) carry the family prefix and no declaration. They are visible to the validator as undeclared and must be declared, renamed, or retired by their owners. +- Operational and tooling deployables are not exempt from family coverage. + Existing pre-rapp runtimes may continue during migration, but their workload + identity remains visibly `unknown` to controls until declared. +- Runtime inventory is still required to prove universal coverage. Repository + discovery alone cannot establish that every running unit has exactly one + authoritative rapp. - Calling the validator from `fix-consistency` still waits on `the-custodian` admitting the family prefixes into the classification standard. That sequencing is not this repo's. diff --git a/schemas/README.md b/schemas/README.md index 5abe184..993e96a 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -30,6 +30,39 @@ deployable belong to exactly one rapp?* That single check catches stale reef bindings, unpackaged live workloads, and the workload-count gap at once. It is what turns this schema from a one-shot lint into a standing control loop. +## Coverage boundary + +Every **managed running deployable** needs exactly one authoritative rapp. The +rule applies equally to application services and to operational or tooling +runtimes that participate in controls. A long-lived controller, scheduled +tool, or managed one-shot Job is still a deployable; it is not exempt because +its purpose is operational. + +Not every operational subject is a workload. Human access, credential +patterns, broker actions, approval records, one-off commands, and +infrastructure resources retain their native actor, lane, activity, decision, +or resource identity when they are not themselves managed deployables. Do not +create a fake rapp merely to make a consumer join total. + +Consumers must preserve three distinct outcomes: + +| Outcome | Meaning | Required handling | +|---|---|---| +| `resolved` | Exactly one authoritative rapp claims the managed deployable. | Use its explicit rapp and workload reference. | +| `unknown` | The subject should be a workload, but no unique declaration resolves. | Report migration debt; do not infer identity. | +| `not-applicable` | The subject is explicitly not a workload. | Retain its native non-workload identity. | + +A pre-rapp running deployable is therefore migration debt and remains +`unknown` to workload-based controls until declared. Repository names, +namespaces, paths, labels, and apparent ownership are evidence inputs, not +fallback identity rules. + +Railiance Master owns this vocabulary and the normative family schemas. +Package owners author their declarations; integration owners may discover, +validate, index, project, and resolve explicit references. They must not create +a parallel generic workload declaration or copy rapp metadata into a second +source of truth. + Rapp bounded context is therefore its own dimension, derived neither from Forgejo organizations nor from State Hub domains. A repo lives in exactly one Forgejo org, so `org:repo` is one-to-many, and a many-to-many grouping cannot diff --git a/workplans/RMASTER-WP-0025-universal-rapp-workload-coverage.md b/workplans/RMASTER-WP-0025-universal-rapp-workload-coverage.md new file mode 100644 index 0000000..b89de32 --- /dev/null +++ b/workplans/RMASTER-WP-0025-universal-rapp-workload-coverage.md @@ -0,0 +1,120 @@ +--- +id: RMASTER-WP-0025 +type: workplan +title: "Universal rapp workload coverage" +domain: financials +repo: railiance-master +status: finished +owner: codex +topic_slug: universal-rapp-workload-coverage +created: "2026-08-23" +updated: "2026-08-23" +--- + +# RMASTER-WP-0025 - Universal rapp workload coverage + +## Goal + +Make the normative rapp contract explicit that every managed running +deployable belongs to exactly one rapp, including operational and tooling +workloads that participate in controls, without inventing workload identity for +subjects that are not workloads. + +## Source and disposition + +Repo Manager published owner interface +`helixforge.workloads.rapp-coverage.v1` for `RMGR-WP-0010-T05` at source +revision `890f3b05b596047a31605c544c56ed8a4f011868`. Railiance Master approves +that interface as supplied. The interface preserves this repository as the +sole owner of the normative rapp vocabulary and schema; Repo Manager remains +the integration, indexing, and reference-resolution owner. + +## Boundaries + +- Do not create a parallel generic workload declaration surface. +- Do not require one rapp per process where deployables share rollout and + rollback fate. +- Do not turn human access, credential patterns, broker actions, operational + approvals, or infrastructure resources into fake workloads. +- Distinguish a managed one-shot deployable from a one-off operational action: + the former needs rapp coverage; the latter retains its native activity or + actor identity. +- Do not infer missing workload ownership from a repository name, namespace, + path, label, or other convention. + +## T01 - Review and accept the owner interface + +```task +id: RMASTER-WP-0025-T01 +status: done +priority: high +``` + +Validate Repo Manager's interface bundle for owner `railiance-master`, inspect +the source ADR and current Railiance Master contract, and record the exact +source revision and disposition. + +Done when the file-backed workplan records `approved`, `amended`, or `rejected` +without reconstructing a duplicate Repo Manager task. + +Completed 2026-08-23. The interface validates cleanly and is approved without +amendment. Its objective already follows ADR-0007's distinct repo-to-rapp and +deployable-to-rapp cardinalities; the required change is a boundary +clarification, not a schema fork. + +## T02 - Clarify the normative coverage boundary + +```task +id: RMASTER-WP-0025-T02 +status: done +priority: high +``` + +Clarify ADR-0007 and the rapp authoring guide so they answer all of the +following directly: + +- operational and tooling deployables require rapp coverage; +- every managed running deployable resolves to exactly one rapp; +- an uncovered pre-rapp deployable is migration debt and remains `unknown` to + workload controls until declared; +- non-workload operational subjects are `not-applicable` and retain native + identity; +- schema vocabulary remains authoritative only in Railiance Master. + +Done when the coverage, migration-debt, and not-applicable states are distinct +without changing the declaration shape. + +Completed 2026-08-23. ADR-0007 revision `accepted-2` and `schemas/README.md` +now define universal managed-deployable coverage, explicitly distinguish a +managed one-shot Job from an operational act, and preserve `resolved`, +`unknown`, and `not-applicable` as separate outcomes. The declaration schema +shape is unchanged. + +## T03 - Verify compatibility and hand the ruling back + +```task +id: RMASTER-WP-0025-T03 +status: done +priority: high +``` + +Run the family validator self-test and the interface's two named declaration +checks. Notify Repo Manager with the workplan/task identifiers, exact source +revision, disposition, and verification result. + +Done when existing valid rapp declarations still validate and +`RMGR-WP-0010-T05` can consume the authoritative ruling without copying the +vocabulary. + +Completed 2026-08-23. Repo Manager's owner-interface validator reports one +matching interface and zero errors. The family validator self-test passes, and +both named repository checks (`rapp-issue-core` and `rapp-qonto`) report 14 +declarations, zero errors, and the same informational derived-reef warning. +The completion handoff is sent after the file-backed result is committed. + +## Outcome + +The owner interface is approved and implemented. Operational and tooling +deployables have no exemption from the exactly-one-rapp invariant; +non-workload subjects retain native identity; uncovered managed deployables +remain visible migration debt rather than receiving inferred identity.