# 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.