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

id	type	title	domain	status	version	created	updated	scope	supersedes	adr	schema	related
netkingdom-playbook-capability-contract	standard	NetKingdom Playbook Capability Contract v0.2	netkingdom	proposed	0.2	2026-09-27	2026-09-27	meta-orchestration	canon/standards/playbook-capability-contract_v0.1.md	docs/adr/ADR-0012-playbook-capability-contract-ownership.md	canon/schemas/playbook-capability-declaration_v0.1.schema.json	NK-WP-0040 history/2026-09-23-railiance-clock-identity-and-layer-review.md

NetKingdom Playbook Capability Contract v0.2

Everything in v0.1 stands unchanged except where this document says otherwise. v0.1 remains accepted and governs declaration conformance; this document adds the execution-attribution receipt as a proposed amendment. It becomes conformance-checked only once NK-WP-0040-T02 lands the schema, evidence-holder agreement with audit-core and Railiance, and the corresponding validator addition. Until then, no declaration is required to emit a receipt.

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;
• the execution-attribution receipt one run of it emits.

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.

For executable validation, a secret_reference value MUST be a non-whitespace URI such as openbao://kv/platform/example or kubernetes://namespace/name#key, or an explicit absolute/relative path beginning with /, ./, or ../. Bare strings are rejected because the composer cannot distinguish them from 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 single-provider 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.

The demo composer refuses ambiguous providers and overrides aimed at unselected declarations. Deterministic multi-provider selection, explicit provider pins, trust sequencing, responsibility maps, and owner-routed readiness handoffs are defined by security-scenario-composition_v0.1.md and implemented by tools/security-scenario-composer/. Use that contract for operational planning; the demo path does not authorize or execute playbooks.

Execution Attribution Receipt (proposed)

Raised by the railiance-clock identity review (history/2026-09-23-railiance-clock-identity-and-layer-review.md, Ruling 1). IAM Profile v0.3 defines who acts. This contract's responsibility claims define what is selected and who is responsible. Neither defines the record that ties one execution to its actor chain, artifact, and result. This section is that record's field list. It is a proposal: it does not obligate any declaration to emit a receipt until conformance is enforced per NK-WP-0040-T02.

A receipt is a single, non-secret, structured record describing one completed (or failed) execution of a declared capability. It never embeds bearer credentials — tokens, secret values, or role response bodies. Unknown attribution is recorded as an explicit unknown, never inferred from path strings, repository ownership, or convenience defaults.

Fields

Field	Meaning
initiator.iss / initiator.sub	Issuer and subject of the initiating actor, from its IAM Profile token
delegation	The delegation reference (actor_sub / act.sub) when the initiator acted through a delegating agent; absent, not unknown, when there was no delegation
executing_workload	The authoritative workload binding (Tenancy Posture workload_identity, proposed) that ran the playbook
runtime_principal	The runtime credential's principal identity (e.g. service account, agent runtime identity) that executed it, distinct from the workload binding
tenant	The tenant the execution acted for
environment	The environment the execution ran in
run_id	A stable, unique identifier for this one execution
source_commit	The source commit of the executed playbook or declaration
artifact_digest	The content digest of the executed artifact (image, package, or script)
target	The inventory reference of what the execution acted on
action	The action taken against the target
decision_refs	Decision and approval record identifiers that authorized the execution, where one was required
time_interval.start / time_interval.end	The attributed start and end of the execution
time_interval.clock_source	The clock the interval was measured against
time_interval.bound	The interval's precision bound, when one exists (e.g. clock skew tolerance); absent when no bound is established, never fabricated

Emission and custody (open)

Who emits the receipt, who holds it as evidence, and how a consumer validates one are not decided by this section. NK-WP-0040-T02 routes that decision to audit-core (candidate evidence holder, per the security layer model's Evidence role) and Railiance (candidate emitter, since it executes). The receipt schema under canon/schemas/ and its validator land together with that agreement, not before it.

Non-goals

• This is not an authorization decision record. decision_refs points at one; it does not restate it.
• This is not a substitute for the Playbook Capability Contract's responsibility claims or trust-state readiness checks, which describe what a declaration is allowed to do, not what one run of it did.
• This does not create a fourth IAM principal type. executing_workload and runtime_principal name existing principals and bindings; they do not grant anything by themselves (railiance-clock review, Ruling 1).

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.

The execution-attribution receipt above is not yet enforced by this validator; see NK-WP-0040-T02.

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