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.