---
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.