generated from coulomb/repo-seed
tegwick
84e9a56f6c
Create docs/responsibility-map.md: the single home for NetKingdom's orchestration relationships, kept out of the orchestrated repos' intents per ADR-0010. Records the classification criterion, the current minimal-foundation scope, and per orchestrated repo (railiance-infra, railiance-cluster, railiance-platform, key-cape, flex-auth) the resources held, what the repo owns (execution), and what NetKingdom orchestrates (meta). Lists dependencies and out-of-scope repos so the scoping decision is explicit and revisitable. Update ADR-0010 to point at the now-created map. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# ADR-0010 - Orchestration vs Dependency, and Self-Coherent Intent
|
|
|
|
**Status:** Accepted (repo classification subject to ongoing refinement)
|
|
**Date:** 2026-05-21
|
|
**Deciders:** Bernd Worsch, Codex
|
|
|
|
## Context
|
|
|
|
While aligning the ecosystem's `INTENT.md` files, two relationships that
|
|
had been blurred turned out to be fundamentally different, and a content
|
|
principle for intent emerged. Both are foundational enough that future
|
|
interface and boundary refinements should be measured against them.
|
|
|
|
NetKingdom performs meta-orchestration (ADR-0007): it selects, parametrizes,
|
|
and assigns responsibility across an IT landscape. But "things NetKingdom
|
|
meta-orchestrates" is not the same as "things NetKingdom depends on," and
|
|
the two had been conflated.
|
|
|
|
## Decision
|
|
|
|
### Principle 1 — Orchestration is not dependency
|
|
|
|
NetKingdom relates to other repositories in two distinct ways:
|
|
|
|
- **Orchestrated** — the repo provides a service that **holds resources
|
|
NetKingdom must manage**: users, roles, scopes, policies, credentials,
|
|
infrastructure resources, and the like. NetKingdom composes,
|
|
parametrizes, and holds responsibility for those resources.
|
|
- **Dependency** — NetKingdom **uses the repo as a tool** to provide its
|
|
own interface, without managing resources the tool holds.
|
|
|
|
**The defining question:** *does the repo provide a service holding
|
|
resources that NetKingdom needs to orchestrate?*
|
|
|
|
- Yes → **orchestrated**.
|
|
- No, it is merely used → **dependency**.
|
|
|
|
Worked examples:
|
|
|
|
- `railiance-fabric` is a tool NetKingdom uses to provide an interface; it
|
|
holds no NetKingdom-managed resources → **dependency**.
|
|
- `railiance-infra`, `railiance-cluster`, `railiance-platform` define and
|
|
hold resources → **orchestrated**.
|
|
- An IAM directory (users, groups) or a policy store (roles, scopes,
|
|
policies) holds exactly the resource kinds in the criterion →
|
|
**orchestrated**.
|
|
|
|
This classification is applied now (see the responsibility map) and will
|
|
be refined as interfaces and boundaries mature. Borderline cases are
|
|
expected.
|
|
|
|
### Principle 2 — Intent is self-coherent
|
|
|
|
Every repository's `INTENT.md` describes **that repository's own** purpose
|
|
and direction, abstractly and stably. Therefore:
|
|
|
|
- It must **not** define itself in terms of NetKingdom.
|
|
- It must **not** reference the intent of sister projects.
|
|
- It must **not** even encode dependencies — dependencies are more
|
|
concrete and less stable than intent should be.
|
|
|
|
Intent is the most abstract, most stable layer. Relationships —
|
|
orchestration, dependency, interfaces, boundaries — are recorded
|
|
**outside** intent: in NetKingdom's responsibility map, architecture docs,
|
|
ADRs, and interface contracts. This keeps every repo's intent free of
|
|
external reference points, so it stays stable while the interfaces and
|
|
boundaries between repos are refined over time.
|
|
|
|
## Consequences
|
|
|
|
- The earlier idea of adding a "place in the NetKingdom-orchestrated
|
|
landscape" block to downstream `INTENT.md` files is **rejected**. It
|
|
would violate Principle 2.
|
|
- Cross-repo `INTENT.md` work becomes: ensure each orchestrated repo has a
|
|
**self-coherent** intent — author one where missing, and remove external
|
|
references (to NetKingdom or sister projects) where present.
|
|
- The orchestration/dependency relationship and the per-repo
|
|
**responsibility map** live in net-kingdom, not in the downstream repos.
|
|
- A responsibility-map artifact in net-kingdom enumerates, per orchestrated
|
|
repo, which resources NetKingdom manages: `docs/responsibility-map.md`.
|
|
- ADR-0007's meta-orchestration layer is unchanged; this ADR clarifies
|
|
*what* NetKingdom orchestrates versus merely uses.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Treat every related repo uniformly
|
|
|
|
Simpler, but it conflates "manages the resources this service holds" with
|
|
"uses this tool," which produces an incoherent responsibility map and
|
|
tempts downstream repos to encode NetKingdom into their intent.
|
|
|
|
### Record relationships inside each repo's intent
|
|
|
|
Convenient for a reader of a single repo, but it couples intents to each
|
|
other and to NetKingdom, making the most-stable layer the least stable.
|
|
Relationships belong in interface contracts and the responsibility map.
|