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