feat(orchestration): compose security scenarios

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a02929-244b-7391-b933-c04010e8eedb

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

@@ -0,0 +1,142 @@
+---
+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.