net-kingdom/workplans/NK-WP-0013-playbook-capability-contract.md

---
id: NK-WP-0013
type: workplan
title: "Playbook Capability Contract"
domain: netkingdom
repo: net-kingdom
status: finished
owner: worsch
topic_slug: netkingdom
planning_priority: high
planning_order: 13
created: "2026-05-21"
updated: "2026-05-22"
depends_on:
  - NK-WP-0006
state_hub_workstream_id: 32a54d8e-8633-42a6-8ec1-104842c581c1
---

# 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
state_hub_task_id: d40f8b29-e983-4d52-bc1f-5f1c51709e7d
status: done
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
state_hub_task_id: ece4b5b1-e1c2-449d-b0f4-83b7010bc838
status: done
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
state_hub_task_id: c956f4a8-b9fa-44ab-8174-31999b98e3b1
status: done
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
state_hub_task_id: e7de05a6-528a-4213-b6db-2c2e90353996
status: done
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
state_hub_task_id: 05a2ff7d-86c4-4de9-9ea8-39a9ad5352a8
status: done
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
state_hub_task_id: 769ed490-c091-41c1-b2e2-e8e378470b6b
status: done
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.

## Completion Notes

- ADR: `docs/adr/ADR-0012-playbook-capability-contract-ownership.md`
- Canonical contract:
  `canon/standards/playbook-capability-contract_v0.1.md`
- Machine-readable schema:
  `canon/schemas/playbook-capability-declaration_v0.1.schema.json`
- Validator and composition demo:
  `tools/playbook-capability-contract/playbook_contract_validator.py`
- Reference Railiance declaration:
  `../railiance-infra/capabilities/playbooks/railiance-infra.bootstrap-host.yaml`
- Sample scenario:
  `examples/playbook-capability-contract/scenario-s1-host-bootstrap.yaml`
- Fixture tests cover valid declarations, controlled vocabulary failures,
  forbidden tenant overrides, missing required parameters, and successful
  selection/parameter composition.

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

## Resolved Questions

- Contract format and home: NetKingdom canon standard plus a
  machine-readable JSON schema and standalone validator.
- Catalog mechanism: v0.1 uses file convention
  `capabilities/playbooks/*.yaml`; a registry can be layered on later.
- Parameter sensitivity: tenant scenarios cannot override
  `platform_only`, `forbidden`, `playbook_default`,
  `security_sensitive`, or `secret_reference` parameters.
- Validator form: standalone NetKingdom tool for v0.1, mirroring
  NK-WP-0012's executable-contract pattern.