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.