From 6973440b3c92ab6548e6587ad20ac4b9463ceae0 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 21 May 2026 01:26:31 +0200 Subject: [PATCH] Add ADR-0010: orchestration vs dependency, self-coherent intent Record two foundational principles that emerged while aligning ecosystem INTENT.md files: 1. Orchestration != dependency. NetKingdom orchestrates a repo when that repo holds resources NetKingdom must manage (users, roles, scopes, policies, infra resources). It depends on a repo when it merely uses it as a tool. Defining question: does the repo hold resources NetKingdom needs to orchestrate? (railiance-fabric = dependency; railiance-infra/cluster/platform = orchestrated.) 2. Intent is self-coherent. A repo's INTENT.md describes its own purpose abstractly; it must not reference NetKingdom, sister projects' intents, or even dependencies. Relationships live in the responsibility map / ADRs / interface contracts, not in intent. Rejects the earlier "place in the NetKingdom landscape" block idea as a Principle 2 violation. Co-Authored-By: Claude Opus 4.7 --- ...tion-vs-dependency-self-coherent-intent.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md diff --git a/docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md b/docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md new file mode 100644 index 0000000..0cb8c25 --- /dev/null +++ b/docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md @@ -0,0 +1,97 @@ +# 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 should enumerate, per + orchestrated repo, which resources NetKingdom manages. (Future work; not + created by this ADR.) +- 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.