net-kingdom/canon/standards/security-scenario-composition_v0.1.md

---
id: netkingdom-security-scenario-composition-v0.1
type: standard
title: "NetKingdom Security Scenario Composition v0.1"
domain: netkingdom
status: proposed
version: "0.1"
owner: net-kingdom
created: "2026-08-23"
updated: "2026-08-23"
last_reviewed: "2026-08-23"
review_interval: 3m
scope: meta-orchestration
schema:
  - canon/schemas/security-scenario_v0.1.schema.json
validator:
  - tools/security-scenario-composer/security_scenario_composer.py
adr:
  - docs/adr/ADR-0007-security-orchestration-boundary.md
  - docs/adr/ADR-0012-playbook-capability-contract-ownership.md
related:
  - canon/standards/playbook-capability-contract_v0.1.md
---

# NetKingdom Security Scenario Composition v0.1

## 1. Purpose

This contract defines the deterministic, plan-only boundary between a requested
NetKingdom capability set and the independently owned playbook entry points that
can realize it. It consumes conformant Playbook Capability Contract v0.1
declarations and produces an owner-routed responsibility, trust, parameter, and
readiness handoff.

Composition answers **what is selected, in which trust order, with which safe
parameters, and who must execute and evidence it**. It does not run a playbook,
mint a credential, infer authority, or declare a runtime ready.

## 2. Authority boundary

- NetKingdom owns scenario intent, provider selection, parameter-policy checks,
  trust sequencing, and the composed responsibility map.
- The declaration owner owns the playbook or stable entry point, execution,
  rollback, and readiness evidence.
- Railiance retains deployment execution for Railiance-owned declarations.
- A composed plan is not authorization to execute. Any approval, custody,
  credential, or change-window gate named by an owner remains in force.

## 3. Scenario input

Scenario files conform to
`canon/schemas/security-scenario_v0.1.schema.json`:

```yaml
id: scenario:c0-local-identity-reference
authority: netkingdom
initial_trust:
  - bare_host_trust
requires:
  capabilities:
    - c0.bootstrap-identity
providers:
  c0.bootstrap-identity: net-kingdom.local-identity
parameter_overrides:
  net-kingdom.local-identity:
    bootstrap_username: bootstrap-admin
```

`authority` uses the Playbook Capability Contract vocabulary: `platform`,
`netkingdom`, or `tenant`. Parameter sensitivity and tuning-authority rules are
applied before a plan is emitted.

`initial_trust` lists trust states established outside this composition. The
composer never assumes an initial trust state. A required state must be present
there or be satisfied by an earlier selected declaration.

`providers` pins a required capability to an exact declaration id. A pin is
mandatory when more than one valid declaration provides the capability. A pin
may not name an unrequested capability or a declaration that does not provide
the keyed capability.

## 4. Fail-closed selection rules

Composition fails when any of the following is true:

- a declaration is invalid or declaration ids are duplicated;
- a capability is unknown, duplicated, or has no provider;
- multiple providers match and the scenario does not pin one;
- a provider pin does not match the requested capability;
- an override targets an unselected declaration or unknown parameter;
- an override violates type, constraint, sensitivity, or tuning authority;
- a required parameter has neither a default nor an override;
- a required trust state cannot be established without a cycle or inference.

Selection order never resolves ambiguity. Filesystem order, catalog order,
lexical order, and prior deployment state are not provider authority.

## 5. Trust sequencing

The composer starts only with the scenario's explicit `initial_trust` set. It
then selects the lexically first **eligible** declaration, where eligible means
all of that declaration's required trust states have already been established.
After the step, and only for composition purposes, the declaration's satisfied
states become available to later steps.

Lexical ordering makes independent eligible steps reproducible; it does not
grant one provider precedence during selection. If no remaining declaration is
eligible, composition fails and reports the unresolved trust states.

Readiness checks attached to a satisfied state are obligations for the owning
executor. They are not marked satisfied merely because the plan contains them.

## 6. Composition output

A successful output has
`apiVersion: netkingdom.io/security-scenario-composition/v0.1` and
`kind: SecurityScenarioComposition`. It contains:

- the requested capabilities and exact selected declaration ids;
- effective parameter values with their source, sensitivity, and tuning
  authority;
- ordered execution handoffs containing owner, repository, entry point,
  required trust, produced trust, and readiness obligations;
- a flattened responsibility map attributable to declaration ids;
- the final *planned* trust-state set;
- an explicit `execution.permitted: false` boundary.

The output is non-secret planning material. Declarations and scenarios must use
secret references rather than secret values as required by the Playbook
Capability Contract.

## 7. Conformance

Use the canonical tool:

```text
python3 tools/security-scenario-composer/security_scenario_composer.py \
  --scenario <scenario.yaml> <declaration.yaml> [<declaration.yaml> ...]
```

Exit zero means the declarations and scenario compose deterministically. It
does not mean the plan was executed or its readiness evidence was observed.