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