repo-manager/docs/adr-004-authoritative-workload-declarations.md

id	type	title	status	decided	deciders	related
RMGR-ADR-004	architecture-decision-record	Authoritative workload declarations and explicit consumer references	accepted	2026-08-22	Bernd Worsch repo-manager	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.