From 84e9a56f6c8dc6bb8820af9266a0f6779483a19a Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 21 May 2026 02:05:37 +0200 Subject: [PATCH] Add responsibility map; link from ADR-0010 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 --- ...tion-vs-dependency-self-coherent-intent.md | 5 +- docs/responsibility-map.md | 135 ++++++++++++++++++ 2 files changed, 137 insertions(+), 3 deletions(-) create mode 100644 docs/responsibility-map.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 index 0cb8c25..142c665 100644 --- a/docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md +++ b/docs/adr/ADR-0010-orchestration-vs-dependency-self-coherent-intent.md @@ -76,9 +76,8 @@ boundaries between repos are refined over time. 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.) +- 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. diff --git a/docs/responsibility-map.md b/docs/responsibility-map.md new file mode 100644 index 0000000..a62db0e --- /dev/null +++ b/docs/responsibility-map.md @@ -0,0 +1,135 @@ +# Responsibility Map + +> The single place that records **NetKingdom's orchestration relationships**: +> which repositories NetKingdom orchestrates, which it merely depends on, +> and — for each orchestrated repository — which resources NetKingdom is +> responsible for managing across the landscape. +> +> This is the deliberate counterpart to self-coherent intent: per ADR-0010, +> these relationships live **here**, not in the orchestrated repos' +> `INTENT.md` files. It complements ADR-0007 (meta-orchestration layer) and +> ADR-0010 (orchestration vs dependency, self-coherent intent). +> +> **Status:** living document. The classification is applied under the +> current scope and will be refined as interfaces and boundaries mature. + +--- + +## Current Scope + +The current focus is the **minimal setup of capabilities any IT landscape +needs to be stood up and secured** — compute/infra, cluster runtime, +platform services, identity, and authorization. Repositories that provide +**application or business capabilities** are out of scope for this map. + +--- + +## Classification Criterion + +NetKingdom relates to other repositories in two distinct ways (ADR-0010): + +- **Orchestrated** — the repo provides a service that **holds resources + NetKingdom must manage** (users, roles, scopes, policies, credentials, + infrastructure resources). The defining question: *does the repo provide + a service holding resources NetKingdom needs to orchestrate?* → yes. +- **Dependency** — NetKingdom **uses the repo as a tool** to build its own + interface, without managing resources the tool holds. + +NetKingdom's role over orchestrated repos is **meta-orchestration** +(ADR-0007): it does not re-implement execution. It (1) **selects** the +services/playbooks a scenario needs, (2) **parametrizes** them where +tuning is warranted, and (3) holds **responsibility** for the resources +and the security boundaries — leaving execution mechanics to the repo. + +--- + +## Orchestrated Repositories + +For each: the resources it holds, what the repository owns (execution), +and what NetKingdom is responsible for (meta-orchestration). + +### `railiance-infra` — infrastructure substrate + +| | | +| --- | --- | +| **Resources held** | hosts/servers, OS hardening baseline, substrate access, at-rest bootstrap secret material, server inventory | +| **Repo owns** | provisioning, convergence, hardening, and baseline verification mechanics | +| **NetKingdom orchestrates** | whether the substrate layer is in a scenario; hardening/security parametrization; bootstrap secret-material placement policy; substrate access policy; the requirement that the baseline is verified before higher layers run | + +### `railiance-cluster` — cluster runtime + +| | | +| --- | --- | +| **Resources held** | cluster runtime, networking/ingress, admission controls, cluster operators/addons, runtime access (kubeconfig) | +| **Repo owns** | runtime install, baseline configuration, and health-verification mechanics | +| **NetKingdom orchestrates** | whether the runtime layer is in a scenario; which security-relevant admission controls, operators, and addons are required; runtime access policy; the cluster-health gate before platform/identity deploy | + +### `railiance-platform` — shared platform services + +| | | +| --- | --- | +| **Resources held** | databases, caches, runtime secret-custody authority, object storage, message brokers, backups | +| **Repo owns** | operating these stateful services to durability/recovery guarantees behind stable interfaces | +| **NetKingdom orchestrates** | which platform services a scenario needs; runtime secret-authority boundaries (platform-root vs tenant) and policies; backup/DR requirements; the identity-integration point; runtime-secret-trust readiness | + +### `key-cape` — identity + +| | | +| --- | --- | +| **Resources held** | users, groups, sessions, MFA tokens, OIDC clients, the directory | +| **Repo owns** | the lightweight IAM implementation conforming to the IAM Profile | +| **NetKingdom orchestrates** | the IAM Profile contract it must conform to; which identity/2FA capabilities are enabled (capability ladder C1–C2); user/group/role and OIDC-client provisioning policy; assurance requirements; identity-trust readiness and profile conformance | + +### `flex-auth` — authorization + +| | | +| --- | --- | +| **Resources held** | roles, scopes, policies, protected-system registrations, resource/action vocabulary, decision/audit records | +| **Repo owns** | the authorization registry, control plane, and PDP adapters | +| **NetKingdom orchestrates** | the decision-envelope contract; platform vs tenant policy boundaries; which protected systems/resources are registered; policy-package import and governance; audit retention; authorization-trust readiness | + +--- + +## Resource Kinds NetKingdom Orchestrates (cross-cutting) + +Across the orchestrated repos, NetKingdom is responsible for the coherent, +cross-landscape management of: + +- **Identities** — humans, service accounts, agents, groups, tenants +- **Roles, scopes, and policies** — coarse claims through fine-grained + authorization +- **Secrets and credentials** — bootstrap material and runtime secret + authority +- **Infrastructure resources** — hosts, runtime, and platform services + +These resource kinds, not the repositories that happen to hold them, are +what the responsibility map exists to keep coherent. + +--- + +## Dependencies (used, not orchestrated) + +NetKingdom uses these as tools to provide its own interface; it does not +manage resources they hold, so they carry no NetKingdom references in +their intent and do not appear in the resource map above. + +- `railiance-fabric` — tooling NetKingdom uses to provide an interface +- `ops-bridge` — tunnel/transport tooling + +--- + +## Out of Scope (application/business capabilities or non-foundational tooling) + +Recorded so the scoping decision is explicit and revisitable: + +- `artifact-store` — artifact/object-storage **service** consumed by + applications (platform-level storage is held by `railiance-platform`) +- `railiance-apps` — applications +- `ops-warden` — operational SSH-credential tooling (post-setup, not part + of minimal bring-up) +- `railiance-enablement` — developer/CI tooling +- all other domain repositories (application/business capabilities) + +Out-of-scope status here is a **current-scope** decision, not a permanent +classification; some of these may become orchestrated as scope expands +(e.g. object-storage credential vending, NK-WP-0007).