feat(workloads): define authoritative reference contract

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d

docs/adr-004-authoritative-workload-declarations.md

@@ -0,0 +1,92 @@
+---
+id: RMGR-ADR-004
+type: architecture-decision-record
+title: "Authoritative workload declarations and explicit consumer references"
+status: accepted
+decided: "2026-08-22"
+deciders: ["Bernd Worsch", "repo-manager"]
+related:
+  - RMGR-WP-0010
+  - RMASTER-ADR-0007
+  - ZONE-WP-0001-T03
+  - docs/workload-reference-contract_v1.md
+---
+
+# ADR-004: Authoritative workload declarations and explicit consumer references
+
+## Status
+
+**Accepted** (2026-08-22).
+
+## Context
+
+Zone Engine needs an authoritative workload subject before it can resolve
+security-zone membership. Its estate measurement found nine rapp declarations,
+but only one of 27 ops-warden credential lanes joined to one. Inferring a
+workload from `path_template`, `owner_repo`, or a repository slug would silently
+turn missing declarations into invented identity.
+
+Railiance Master ADR-0007 already defines the family authority: every running
+deployable belongs to exactly one rapp, while a rapp may contain multiple
+deployables that share rollout and rollback fate. Its JSON schema is normative.
+Repo Manager implements repository integration and must not fork that semantic
+vocabulary.
+
+## Decision
+
+1. `rapp-*/declarations/rapp.yaml` is the authoritative declaration surface for
+   every managed running deployable, including operational and tooling
+   workloads that participate in controls.
+2. There is no parallel declaration surface for managed workloads outside the
+   rapp family. A running unit awaiting rapp extraction is migration debt and
+   resolves as `unknown` to workload-based controls.
+3. Not every operational subject is a workload. Human access, credential
+   patterns, broker actions, one-shot jobs, and infrastructure resources retain
+   their native actor, lane, activity, or resource identity. They must not be
+   represented as fake workloads merely to make a join total.
+4. Authority is divided deliberately:
+   - Railiance Master owns the normative rapp/workload vocabulary and schema.
+   - Each rapp/package owner authors its declaration.
+   - Repo Manager owns discovery, validation integration, indexing, stable
+     reference resolution, and coverage findings.
+   - hub-core distributes normalized projections to cross-repository consumers.
+   - Consuming catalogs own their explicit pointers and never copy declaration
+     metadata as a second source.
+5. A v1 workload reference is the pair `rapp_id` and
+   `workload_identity.name`. A consumer may additionally identify one
+   `composition.member_repos[].deployables[]` member. Repository names and path
+   segments are not reference fallbacks.
+6. Resolution has three semantically distinct outcomes:
+   - `resolved`: exactly one authoritative declaration matches;
+   - `unknown`: the subject should be a workload but no unique declaration
+     resolves;
+   - `not-applicable`: the consumer explicitly declares that its subject is not
+     a workload.
+   Omission must not collapse these states.
+7. Ops-warden may add an explicit workload reference to each applicable lane.
+   It owns that catalog field and its applicability marker; Repo Manager owns
+   resolution of the reference. Zone Engine consumes the resolved declaration
+   and the catalog pointer and performs no name or path inference.
+
+## Consequences
+
+- Operational and tooling runtimes need rapp coverage just like application
+  workloads. Their ownership repositories do not become package repositories.
+- Existing pre-rapp runtimes may continue operating during migration, but
+  workload-based controls must expose their identity as unknown.
+- Repo Manager can detect missing declarations in `rapp-*` repositories,
+  duplicate reference pairs, and deployables claimed by more than one rapp.
+- Full estate coverage still requires a runtime/deployable observation source;
+  repository names alone cannot prove that every running unit is declared.
+- Consumer catalogs remain pointer layers. A resolved reference gives access to
+  current classification, criticality, readiness, and placement without copying
+  those values.
+
+## Rejected alternatives
+
+- **A generic second `workloads.yaml`.** This would create two authorities for
+  the same managed deployable and contradict RMASTER-ADR-0007.
+- **Path or repository-name inference.** Current `qonto`, `rapp-qonto`, and
+  `qonto-assistant` drift proves that convention is not identity.
+- **Making every credential lane a workload.** Several lanes describe actors,
+  patterns, or control-plane operations rather than running deployables.