Files

tegwick 6973440b3c 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 <noreply@anthropic.com>

2026-05-21 01:26:31 +02:00

4.1 KiB

Raw Blame History

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

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.

4.1 KiB Raw Blame History