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:

an ADR or ADR refinement explaining the change and migration path;
a new versioned standard and schema;
an updated validator;
a coexistence window for the previous supported version where practical;
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.

4.2 KiB Raw Blame History