tegwick
b36b68bc57
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
75 lines
2.7 KiB
Markdown
75 lines
2.7 KiB
Markdown
---
|
|
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.
|