Authoring and inspecting configuration

Configuration work should start with declaration boundaries and compiler output—not by launching a heavyweight simulator. Most structure, component, and provenance failures can be checked without a backend.

Configuration layers

File	Responsibility	Should not contain
Run	Backend, runtime, Scenario, control, plugins, and run overrides	Registry search policy or shared asset internals
Project	Registries, trusted roots, cache, offline mode, deployment limits	One experiment's scene instances
Component Manifest	Release, kind, schema, variants, and resource digests	Consumer-specific instance poses
User settings	Explicitly allowed machine defaults	Inputs required for project reproduction

Recommended inspection sequence

Validate syntax and semantics, inspect normalized expansion, explain provenance for important fields, then create or verify a Lock. JSON output is available for CI and deployment systems.

bash

fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml runtime.physics_hz
fastsim config lock run.yaml --output run.lock --json
fastsim config verify-lock run.lock --json

Overrides

Shared facts belong in Runs, Projects, or components. CLI and API overrides are suitable for deployment selection or controlled experiments and must appear in final Plan provenance. Do not depend on working directories, import order, or machine-private environment values to alter semantics.

Schema failures should be corrected in author input. Missing components are Registry problems, kind mismatch is an identity problem, digest errors require trusted resource repair, and capability mismatch requires a compatible Provider or revised requirement.

See Configuration reference and Run, ExecutionPlan, and Lock.