From 09534f661711fc0ffec05997a56b29387987d577 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 21 May 2026 02:41:17 +0200 Subject: [PATCH] Draft NK-WP-0013: Playbook Capability Contract The orchestration-layer analog of the IAM Profile, realizing the playbook-contract dependency named in ADR-0007's meta-orchestration refinement. NetKingdom owns the contract schema (consumer-defines-contract, IAM Profile precedent); Railiance authors playbooks and publishes conformant declarations; execution stays in Railiance (ADR-0007 unchanged). Six tasks: ownership ADR + versioning; capability vocabulary (aligned to the C0-C6 ladder + responsibility-map resource kinds); parameter format (defaults, constraints, security-sensitivity); responsibility/trust-state claims; catalog + consumption model + conformance validator; reference adoption with one Railiance playbook. Status proposed; not yet registered. Co-Authored-By: Claude Opus 4.7 --- ...NK-WP-0013-playbook-capability-contract.md | 191 ++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 workplans/NK-WP-0013-playbook-capability-contract.md diff --git a/workplans/NK-WP-0013-playbook-capability-contract.md b/workplans/NK-WP-0013-playbook-capability-contract.md new file mode 100644 index 0000000..13aeaa3 --- /dev/null +++ b/workplans/NK-WP-0013-playbook-capability-contract.md @@ -0,0 +1,191 @@ +--- +id: NK-WP-0013 +type: workplan +title: "Playbook Capability Contract" +domain: netkingdom +repo: net-kingdom +status: proposed +owner: worsch +topic_slug: netkingdom +planning_priority: high +planning_order: 13 +created: "2026-05-21" +updated: "2026-05-21" +depends_on: + - NK-WP-0006 +state_hub_workstream_id: TBD +--- + +# NK-WP-0013 — Playbook Capability Contract + +> The **orchestration-layer analog of the IAM Profile**. ADR-0007's +> meta-orchestration refinement named this as a prerequisite: for NetKingdom +> to select and parametrize playbooks reliably, each Railiance playbook must +> publish a **declared interface** — the capability it provisions, its +> parameters (with defaults and constraints), and the responsibility it +> claims. Without it, meta-orchestration composes against implicit behavior +> and breaks silently when a playbook changes. This workplan defines that +> contract. + +## Goal + +Define the **Playbook Capability Contract** — the schema and vocabulary by +which a playbook declares: + +1. **what capability it provisions** (controlled vocabulary, aligned to the + capability ladder and the responsibility-map resource kinds), +2. **its parameters** — name, type, default, constraints, required/optional, + and which are security-sensitive, and +3. **the responsibility it claims** — which element owns which resources, and + which trust state(s) / readiness checks it satisfies or requires. + +…plus the **catalog/consumption model** NetKingdom meta-orchestration uses +to select, parametrize, and build a responsibility map for a scenario, and a +**conformance validator** for declarations. + +## Ownership (the boundary this realizes) + +By symmetry with the IAM Profile, the **consumer that needs a stable +interface defines the contract; the provider conforms**: + +| | Contract owner | Publishes conformant declarations | Consumer | +|---|---|---|---| +| Identity | NetKingdom (IAM Profile) | key-cape / Keycloak | apps, flex-auth | +| Orchestration | **NetKingdom (this contract)** | Railiance playbooks | NetKingdom meta-orchestration | + +NetKingdom owns the contract schema; Railiance owns the playbooks and +publishes one declaration per playbook; **execution stays in Railiance** +(ADR-0007 unchanged). The contract makes a playbook change a versioned event +rather than a silent break. + +## Scope + +In scope: + +- ownership & boundary decision (ADR) and contract versioning governance +- the capability vocabulary a declaration draws from +- the parameter declaration format (defaults, constraints, sensitivity) +- the responsibility-claim and trust-state/readiness format +- the catalog and the meta-orchestration consumption model +- a conformance validator for declarations +- coordinated adoption proof with one reference Railiance playbook + +Out of scope: + +- authoring the playbooks themselves (Railiance owns execution) +- writing declarations for every existing playbook (Railiance work; this + workplan proves the contract with one reference declaration) +- a dedicated execution-orchestration repo (deferred per ADR-0007) + +## Tasks + +```task +id: NK-WP-0013-T1 +status: todo +priority: high +``` + +**Ownership & boundary decision (ADR-0012).** Record that NetKingdom owns +the Playbook Capability Contract schema (consumer-defines-contract, IAM +Profile precedent), Railiance authors playbooks and publishes conformant +declarations, and execution stays in Railiance (ADR-0007). Decide whether +the contract is NetKingdom-owned outright or NetKingdom-owned with Railiance +co-design. Define contract **versioning and breaking-change governance**. + +```task +id: NK-WP-0013-T2 +status: todo +priority: high +``` + +**Capability vocabulary.** Define the controlled vocabulary of capabilities +a playbook can declare it provisions, aligned to the **capability ladder +(C0–C6)** and the **responsibility-map resource kinds** (identities, +roles/scopes/policies, secrets/credentials, infrastructure resources). This +is what "capability" means in a declaration, so two playbooks providing the +same capability are comparable. + +```task +id: NK-WP-0013-T3 +status: todo +priority: high +``` + +**Parameter declaration format.** Define how a playbook declares its +parameters: name, type, **default**, **constraints** (allowed values / +ranges), required vs optional, and a **security-sensitivity** marker so +NetKingdom knows which parameters it may tune versus which are +security-critical and constrained. This is what makes "parametrize where +adequate" safe rather than guesswork. + +```task +id: NK-WP-0013-T4 +status: todo +priority: high +``` + +**Responsibility-claim & trust-state format.** Define how a declaration +states which element **owns which resources** (feeding the responsibility +map) and which **trust state(s) / readiness checks** (ADR-0007 model) it +satisfies or requires. This lets NetKingdom assemble a coherent +responsibility map and sequence for a scenario from the declarations. + +```task +id: NK-WP-0013-T5 +status: todo +priority: high +``` + +**Catalog, consumption model, and conformance validator.** Define how +declarations are published and discovered (the catalog), how +meta-orchestration consumes them to **select**, **parametrize**, and build a +**responsibility map** for a scenario, and a **conformance validator** that +checks a declaration against the contract (the orchestration-layer analog of +the IAM Profile conformance check, NK-WP-0012-T5). + +```task +id: NK-WP-0013-T6 +status: todo +priority: medium +``` + +**Reference adoption with Railiance.** Coordinate with Railiance to have +**one reference playbook publish a conformant declaration end-to-end**, and +demonstrate NetKingdom selecting + parametrizing it from the declaration +alone. Proves the contract is sufficient and is the template for adopting +the rest. Cross-repo coordination item for the Railiance domain. + +## Acceptance Criteria + +- An ADR records contract ownership, the Railiance-publishes/NetKingdom- + consumes split, and ADR-0007 is confirmed unchanged. +- The contract specifies capability vocabulary, parameter format (defaults, + constraints, sensitivity), and responsibility/trust-state claims. +- A catalog/consumption model and a declaration conformance validator exist. +- At least one Railiance playbook publishes a conformant declaration, and + NetKingdom composes and parametrizes it from that declaration alone. +- Contract versioning and breaking-change governance is documented. + +## Dependencies & Sequencing + +- **Realizes** the playbook-contract dependency from ADR-0007's + meta-orchestration refinement; does not change ADR-0007. +- **Depends on NK-WP-0006** for the trust-state model and the + responsibility-map resource kinds the declarations reference. +- **Coordinates with the Railiance domain** — NetKingdom defines the + contract; Railiance publishes declarations (T6) and continues to own + execution. +- Parallels NK-WP-0012: same consumer-defines-contract pattern, same + conformance-check shape, applied to orchestration instead of identity. + +## Open Questions + +- Contract format and home: a net-kingdom canon standard plus a + machine-readable schema (e.g. JSON/YAML schema) the catalog validates + against? +- Catalog mechanism: a file convention in each playbook repo that NetKingdom + aggregates, or a published registry? +- How parameter sensitivity interacts with tenant boundaries (which + parameters a tenant-scoped scenario may set vs. platform-only). +- Whether the conformance validator is a standalone net-kingdom tool or a + shared library, mirroring the same open question in NK-WP-0012.