feat(workloads): define authoritative reference contract

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

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.