net-kingdom/docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md

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.