---
id: netkingdom-playbook-capability-contract
type: standard
title: "NetKingdom Playbook Capability Contract v0.1"
domain: netkingdom
status: accepted
version: "0.1"
created: "2026-05-22"
updated: "2026-05-22"
scope: meta-orchestration
adr:
  - docs/adr/ADR-0012-playbook-capability-contract-ownership.md
schema:
  - canon/schemas/playbook-capability-declaration_v0.1.schema.json
validator:
  - 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:

```text
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

```yaml
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:

```yaml
- 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.

```yaml
- 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:

```yaml
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:

```yaml
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:

```text
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:

```text
../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:

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