generated from coulomb/repo-seed
113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# 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.
|