Run, ExecutionPlan, and Lock

Run, Plan, and Lock represent one simulation application at three stages: author intent, normalized executable input, and a reproducibility snapshot.

Run: the author declaration

A Run is the human-readable YAML, JSON, or TOML entry. It selects schema, name, backend, runtime policy, Scenario, control policy, plugins, and explicit overrides. It should state what this execution selects instead of copying every component detail.

yaml

schema: fastsim/2
name: kitchen-evaluation
backend: isaaclab
runtime:
  physics_hz: 60
  control_hz: 30
  seed: 7
scenario:
  use: scenario://kitchen/evaluation
plugins:
  recorder:
    use: plugin://official/record

ExecutionPlan: execution authority

The compiler expands Project and Registry inputs, resolves component releases and variants, validates bindings, rates, and resources, then creates a deeply immutable ExecutionPlan. It contains normalized Scenario data, runtime policy, resolved entities, plugin bindings, and provenance.

Runtime does not keep a mutable raw configuration dictionary and rediscover meaning midway through execution.

Lock: the verification boundary

A Lock freezes exact component releases, manifests, resource digests, and the plan digest. It answers “what actually executed” for deployment and audit, but is not a replacement authoring format.

Artifact	Primary reader	Hand editing	Lifetime
Run	Project author	Yes	Changes with the project
ExecutionPlan	Runtime and diagnostics	No	Generated per compilation
Lock	Deployment, reproduction, audit	Discouraged	Frozen with approved inputs

Syntax, component conflicts, digests, capabilities, and plugin contracts should fail during compilation whenever possible. See Configuration and CLI and outputs for exact surfaces.

The full compilation path

Run validation, resolution, binding, ExecutionPlan, and Lock pipelineEnlarge diagram

Compilation is not YAML-to-YAML conversion. It turns component URIs into selected releases, resource references into trusted digest-checked files, Scenario aliases into stable entity identities, plugin declarations into instance bindings and grants, and control sources into complete precedence.

Validate checks schema and cross-field rules; resolve handles Projects, Registries, versions, variants, and resources; bind connects entities, plugin services, and authority; normalization produces a stable digest. Runtime receives the finished Plan and never rereads the author's mutable dictionaries.

Use a Lock for CI, deployment, formal recording, or any run where identical input matters. Regenerate it after an approved dependency or asset change and review both the semantic Plan diff and the digest change. Do not hand-edit a Lock or treat a pinned Python package as a substitute for pinned physical resources.

When a value is surprising, use expand and explain to inspect its effective form and provenance. Store validation JSON, exit codes, Plan digest, Lock digest, and distribution versions as deployment evidence.