repo-manager/docs/workload-reference-contract_v1.md

id	type	title	version	status	created	updated	workplan_task
RMGR-CONTRACT-WORKLOAD-REFERENCE-0001	contract	Authoritative workload reference and resolution contract	1	active	2026-08-22	2026-08-22	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

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

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.