NetKingdom Security Scenario Composition v0.1

01Purpose

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.

02Authority 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.

03Scenario input

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

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.

04Fail-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.

05Trust 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.

06Composition 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.

07Conformance

Use the canonical tool:

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.