# ADR-0012 - Playbook Capability Contract Ownership

**Status:** Accepted
**Date:** 2026-05-22
**Deciders:** Bernd Worsch, Codex

## Context

ADR-0007 refined NetKingdom's orchestration role into a
meta-orchestration layer. NetKingdom selects the services and playbooks a
scenario needs, decides which parameters may be tuned, and holds the
responsibility map. Railiance remains the execution-orchestration layer:
Railiance playbooks provision and converge the actual infrastructure,
cluster, platform services, and application layers.

That split requires a stable interface. If a Railiance playbook only
describes behavior implicitly, NetKingdom cannot safely compose it into a
scenario, compare it with another playbook, or know which parameter
changes are safe. The IAM Profile provides the precedent: the consumer
that needs a stable contract defines the contract, and providers conform
to it.

## Decision

NetKingdom owns the Playbook Capability Contract schema and vocabulary.
Railiance owns playbook implementation and publishes one conformant
declaration per playbook.

The first canonical contract is
`canon/standards/playbook-capability-contract_v0.1.md`, backed by the
machine-readable schema in
`canon/schemas/playbook-capability-declaration_v0.1.schema.json` and the
validator in `tools/playbook-capability-contract/`.

The contract is NetKingdom-owned with Railiance co-design:

- NetKingdom defines the schema, controlled vocabulary, trust-state
  language, parameter-sensitivity rules, and conformance criteria.
- Railiance authors and maintains declarations beside the playbooks they
  describe.
- Railiance execution stays unchanged. The declaration never becomes the
  playbook runner.
- NetKingdom meta-orchestration consumes declarations to select,
  parametrize, sequence, and build responsibility maps for scenarios.

ADR-0007 remains unchanged: execution stays in Railiance.

## Versioning

The contract uses explicit document versions:

- Patch/editorial changes clarify wording or examples without changing
  declaration semantics.
- Minor versions add optional fields, vocabulary entries, or validator
  warnings that existing declarations can ignore.
- Breaking versions change required fields, field meanings, allowed
  vocabulary, parameter-sensitivity semantics, trust-state semantics, or
  catalog consumption rules.

Declarations carry `metadata.contract_version`. A catalog may accept more
than one contract version during a migration window, but must report the
version used for each selected playbook.

## Breaking-Change Governance

A breaking change requires:

1. an ADR or ADR refinement explaining the change and migration path;
2. a new versioned standard and schema;
3. an updated validator;
4. a coexistence window for the previous supported version where
   practical;
5. notice to known declaration publishers, especially Railiance repos.

Breaking changes include:

- removing or renaming required fields;
- changing capability ids or resource-kind vocabulary;
- changing trust-state meanings;
- changing which parameter sensitivities are tenant-tunable;
- changing catalog selection or override semantics;
- moving execution responsibility out of Railiance into NetKingdom.

## Consequences

- Playbook declaration files live beside Railiance playbooks, normally at
  `capabilities/playbooks/*.yaml`.
- NetKingdom can validate declarations before consuming them.
- A playbook interface change becomes visible and versioned instead of an
  implicit break.
- The responsibility map can be assembled from declarations, while
  Railiance keeps execution ownership.

## Alternatives Considered

### Put The Contract In Railiance

Railiance owns execution, so this is tempting. But NetKingdom is the
consumer that needs stable scenario composition and responsibility-map
inputs. Keeping the contract in NetKingdom mirrors the IAM Profile
pattern and keeps scenario semantics close to the responsibility map.

### Make Declarations Free-Form Documentation

Free-form docs are readable but not safely composable. NetKingdom needs a
validator and controlled vocabulary so a playbook change cannot silently
break a scenario.

### Build A Dedicated Execution-Orchestration Repo Now

ADR-0007 explicitly defers that. The contract is useful now and does not
require a new runner or repo boundary.