net-kingdom/canon/standards/playbook-capability-contract_v0.1.md

id, type, title, domain, status, version, created, updated, scope, adr, schema, validator

id	type	title	domain	status	version	created	updated	scope	adr	schema	validator
netkingdom-playbook-capability-contract	standard	NetKingdom Playbook Capability Contract v0.1	netkingdom	accepted	0.1	2026-05-22	2026-05-22	meta-orchestration	docs/adr/ADR-0012-playbook-capability-contract-ownership.md	canon/schemas/playbook-capability-declaration_v0.1.schema.json	tools/playbook-capability-contract/playbook_contract_validator.py

NetKingdom Playbook Capability Contract v0.1

Purpose

The Playbook Capability Contract is the declared interface between NetKingdom meta-orchestration and Railiance execution playbooks.

It lets a playbook state:

• which capability it provisions;
• which parameters it exposes, including defaults, constraints, and security sensitivity;
• which resources and responsibilities it claims;
• which trust states it requires or satisfies;
• how it is published into a catalog.

NetKingdom consumes declarations to select playbooks, choose safe parameter overrides, sequence trust states, and build a responsibility map. Railiance owns the playbooks and execution mechanics.

Ownership

NetKingdom owns this contract. Railiance publishes conformant declarations. Execution stays in Railiance. See ADR-0012.

File Convention

Declaration files SHOULD live in the publishing repo at:

capabilities/playbooks/<declaration-id>.yaml

Each file describes one playbook or one stable playbook entry point. A playbook with materially different modes may publish multiple declarations if those modes provide different capabilities or expose different security-sensitive parameters.

Top-Level Shape

apiVersion: netkingdom.io/playbook-capability/v0.1
kind: PlaybookCapabilityDeclaration
metadata:
  id: railiance-infra.bootstrap-host
  name: Railiance S1 host bootstrap
  owner: railiance-infra
  repo: railiance-infra
  domain: railiance
  contract_version: "0.1"
spec:
  playbook: {}
  capabilities: []
  parameters: []
  responsibilities: []
  trust: {}
  catalog: {}

Capability Vocabulary

spec.capabilities[].id MUST be one of the controlled vocabulary values below. Capability ids are stable comparison keys.

Capability id	Tier	Meaning
s1.os-baseline	S1	Host provisioning, OS convergence, hardening, and substrate access baseline
s1.secret-bootstrap	S1	Bootstrap secret material, SOPS/age handling, emergency material placement
s2.cluster-runtime	S2	Kubernetes runtime, ingress, networking, admission, and cluster access
s3.platform-services	S3	Databases, caches, object storage, brokers, and shared platform services
c0.bootstrap-identity	C0	Local/bootstrap identity before runtime IAM exists
c1.lightweight-sso	C1	key-cape lightweight SSO profile implementation
c2a.light-2fa	C2a	Lightweight built-in second factor such as TOTP/WebAuthn
c2b.token-authority	C2b	privacyIDEA or equivalent token authority
c3.runtime-secrets	C3	OpenBao or equivalent runtime secret authority
c4.fine-grained-authorization	C4	flex-auth and delegated PDP readiness
c5.enterprise-federation	C5	expanded-mode Keycloak, enterprise federation, or SAML brokering
c6.self-optimizing-audit	C6	audit feedback loops, drift surfacing, and continuous adaptation

The S* entries align to Railiance stack layers. The C* entries align to the NetKingdom capability progression. A declaration may list more than one capability only when the same playbook entry point truly provides each one.

Resource Kinds

Every capability and responsibility claim references one or more resource kinds:

Resource kind	Meaning
identities	humans, service accounts, agents, groups, tenants, and assurance evidence
roles_scopes_policies	roles, scopes, policy packages, protected-system registrations, decision records
secrets_credentials	bootstrap material, runtime secrets, dynamic credentials, leases, credential rotations
infrastructure_resources	hosts, runtime, networking, platform services, storage, and deployment substrate

Parameter Declarations

Each parameter entry has this shape:

- name: swapfile_size_mb
  type: integer
  required: false
  default: 4096
  constraints:
    minimum: 0
    maximum: 65536
  sensitivity: operational
  tuning_authority: netkingdom_tunable
  description: Swap size applied by the bootstrap playbook.

Allowed type values:

• string
• integer
• number
• boolean
• array
• object

Allowed sensitivity values:

• public - safe to display and tune freely.
• operational - affects behavior or sizing, not secret material.
• security_sensitive - affects security posture and requires platform review.
• secret_reference - points to secret material but must not contain the secret value itself.

Allowed tuning_authority values:

• playbook_default - NetKingdom should rely on the playbook default.
• netkingdom_tunable - NetKingdom may override for a scenario.
• platform_only - only platform-control-plane authority may override.
• tenant_tunable - tenant-scoped scenario owners may override within constraints.
• forbidden - declaration exposes the value for audit only; callers may not override it.

Security-sensitive and secret-reference parameters MUST NOT be tenant_tunable. Secret-reference defaults must be references or paths, not plaintext secret values.

Supported constraints:

Constraint	Applies to	Meaning
enum	all scalar types	value must be one of the listed values
minimum / maximum	integer, number	numeric bounds
min_items / max_items	array	array length bounds
pattern	string	regular expression the value must match

Responsibility Claims

Responsibility entries feed the responsibility map. They do not transfer execution ownership to NetKingdom.

- resource_kind: infrastructure_resources
  owner: railiance-infra
  resources:
    - server:target_hosts
    - os-baseline
  repo_owns: Provisioning, convergence, and verification mechanics.
  netkingdom_orchestrates: Whether this substrate capability is selected, and which security posture is required.

owner names the repo or provider that holds execution ownership. repo_owns explains the implementation responsibility. netkingdom_orchestrates explains the meta-orchestration responsibility.

Trust States And Readiness

Declarations use the trust-state vocabulary from the platform architecture:

• bare_host_trust
• cluster_trust
• bootstrap_secret_trust
• bootstrap_identity_trust
• runtime_secret_trust
• runtime_identity_trust
• runtime_authorization_trust
• tenant_onboarding_trust

Each declaration lists states it requires and states it satisfies:

trust:
  requires:
    - state: bare_host_trust
      readiness_checks: []
  satisfies:
    - state: bootstrap_secret_trust
      readiness_checks:
        - id: sops-age-material-present
          description: SOPS/age material is present for bootstrap secrets.
          evidence: ansible role sops_agent converged successfully

Readiness checks are evidence obligations. The declaration names the check; the Railiance playbook or verification tooling performs it.

Catalog And Consumption Model

A catalog is an index of declarations. For v0.1, the catalog mechanism is file-based:

1. Railiance repos publish declarations under capabilities/playbooks/*.yaml.
2. NetKingdom or a future catalog job discovers those files from known orchestrated repos.
3. The validator checks each declaration against this contract.
4. A scenario states required capability ids and parameter overrides.
5. NetKingdom selects declarations that provide the required capabilities.
6. NetKingdom applies only allowed parameter overrides, rejecting out-of-range, tenant-forbidden, or security-unsafe overrides.
7. NetKingdom composes the responsibility and trust-state claims into a scenario responsibility map and readiness sequence.

The declaration is not an execution plan. It is the interface that lets a separate playbook runner execute safely.

Scenario Shape

The validator supports a small scenario file for conformance demos:

id: scenario:s1-host-bootstrap-reference
authority: platform
requires:
  capabilities:
    - s1.os-baseline
parameter_overrides:
  railiance-infra.bootstrap-host:
    target_hosts:
      - railiance01
    swapfile_size_mb: 8192

Allowed scenario authorities are platform, netkingdom, and tenant. Tenant authority cannot override platform_only, security_sensitive, or secret_reference parameters.

Conformance

A declaration conforms when it passes:

tools/playbook-capability-contract/playbook_contract_validator.py

The validator checks:

• top-level API version and kind;
• required metadata;
• controlled capability ids and tiers;
• resource-kind vocabulary;
• parameter type/default/constraint/sensitivity/tuning rules;
• responsibility claims;
• trust-state and readiness-check shape;
• catalog publication metadata;
• optional scenario selection and parameter override compatibility.

Reference Adoption

The reference declaration for v0.1 is in:

../railiance-infra/capabilities/playbooks/railiance-infra.bootstrap-host.yaml

It describes the existing Railiance S1 Ansible bootstrap playbook and can be selected by the sample scenario in:

examples/playbook-capability-contract/scenario-s1-host-bootstrap.yaml