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.

docs/workload-reference-contract_v1.md

@@ -0,0 +1,75 @@
+---
+id: RMGR-CONTRACT-WORKLOAD-REFERENCE-0001
+type: contract
+title: "Authoritative workload reference and resolution contract"
+version: "1"
+status: active
+created: "2026-08-22"
+updated: "2026-08-22"
+workplan_task: RMGR-WP-0010-T02
+---
+
+# Authoritative workload reference and resolution contract v1
+
+## Authority
+
+The referenced record is authoritative at
+`rapp-*/declarations/rapp.yaml`, under the normative Railiance Master rapp
+schema. Repo Manager indexes and resolves that file; it does not redefine or
+copy its semantic fields.
+
+## Reference
+
+```yaml
+workload_ref:
+  rapp_id: rapp-issue-core
+  name: issue-core
+  deployable: issue-core  # optional
+```
+
+`rapp_id` and `name` are required and must exactly equal `rapp_id` and
+`workload_identity.name` in one declaration. `deployable`, when present, must
+exactly equal a member of `composition.member_repos[].deployables[]` in that
+same declaration.
+
+Names are case-sensitive canonical slugs. A resolver must not strip prefixes,
+parse secret paths, consult `owner_repo`, or substitute a repository name.
+Renaming either required field is a reference migration, not an alias inferred
+by the reader.
+
+## Resolution outcomes
+
+| Outcome | Meaning | Consumer behavior |
+| --- | --- | --- |
+| `resolved` | Exactly one declaration matches, including the optional deployable. | Consume the authoritative declaration projection. |
+| `unknown` | A workload reference is expected but missing, ambiguous, invalid, or unresolved. | Fail closed where policy requires identity; expose the reason. |
+| `not-applicable` | The catalog owner asserts that the subject is not a workload. | Use the subject's native typed identity; do not call it unknown. |
+
+Repo Manager produces `resolved` or `unknown`. `not-applicable` is an explicit
+consumer-catalog assertion because only that catalog knows what its lane or
+control represents. Consumers must represent the distinction rather than using
+an absent field for both states.
+
+## Commands
+
+```bash
+rmgr workload index --root /home/worsch
+rmgr workload resolve \
+  --root /home/worsch \
+  --rapp-id rapp-issue-core \
+  --name issue-core \
+  --deployable issue-core
+```
+
+The index reports missing rapp declarations, duplicate reference pairs, and
+deployables claimed by more than one rapp. Resolution is read-only and returns
+`unknown` instead of applying a naming heuristic.
+
+## Consumer obligations
+
+- Ops-warden owns its lane field and whether a lane is workload-applicable.
+- Zone Engine consumes explicit references plus declaration projections.
+- hub-core may transport the normalized records but does not become their
+  authority.
+- Copied classification, criticality, readiness, or placement values are
+  caches and must retain source identity and observation metadata.

docs/workload-reference-contract_v1.yaml

@@ -0,0 +1,35 @@
+contract: helixforge.workload-reference
+version: 1
+status: active
+authority:
+  semantic_schema: railiance-master/schemas/rapp.schema.json
+  record_pattern: rapp-*/declarations/rapp.yaml
+  indexer: repo-manager
+reference:
+  required:
+    - rapp_id
+    - name
+  optional:
+    - deployable
+  source_fields:
+    rapp_id: rapp_id
+    name: workload_identity.name
+    deployable: composition.member_repos[].deployables[]
+  forbidden_fallbacks:
+    - repository_name
+    - owner_repo
+    - path_segment
+resolution:
+  producer_states:
+    - resolved
+    - unknown
+  consumer_asserted_states:
+    - not-applicable
+  unknown_reasons:
+    - not_found
+    - ambiguous
+    - deployable_not_declared
+consumer_rules:
+  ops-warden: owns lane reference and applicability
+  zone-engine: consumes references without identity inference
+  hub-core: transports normalized projection without assuming authority