CLI: trace

kairos trace provides a comprehensive set of trace management commands for exporting, comparing, inspecting, and packaging simulation traces.

Subcommands

Subcommand	Description
`export`	Export a trace from a scenario simulation
`diff`	Diff two trace files
`inspect`	Inspect a trace file and print summary
`baseline`	Generate baseline traces for one or more scenarios
`hash`	Compute SHA-256 hash of a file
`bundle`	Batch export traces with manifest
`manifest`	Output the embedded scenario manifest
`trend`	Per-step trend metrics for a trace
`report`	Generate a formatted trace report
`suite`	Trace suite operations (create, compare, lint, validate, pack)

`kairos trace export`

Export a trace from a scenario simulation.

kairos trace export \
  --scenario standard \
  --steps 200 \
  [--seed 1207] \
  [--output trace.json] \
  [--format json] \
  [--manifest manifest.json] \
  [--events events.json] \
  [--pretty]

Flag	Default	Description
`--scenario`	Required	Scenario ID to simulate
`--steps`	`200`	Number of simulation steps
`--seed`	From scenario	Override the scenario seed
`--output` / `-o`	stdout	Output file path
`--format`	`json`	Output format: `json` or `table`
`--manifest`	Embedded	Path to a custom scenario manifest
`--events`	None	Path to an EDMS event script
`--pretty`	Off	Pretty-print JSON output

`kairos trace diff`

Compare two trace files for differences.

kairos trace diff expected.json actual.json [--epsilon 1e-6] [--format json]

Flag	Default	Description
`--epsilon`	`1e-6`	Epsilon for floating-point comparison
`--format`	`json`	Output format

Trace diff is the primary tool for verifying determinism. Two traces from the same seed, config, and move sequence should have zero diffs at $\epsilon = 10^{-6}$ .

`kairos trace inspect`

Inspect a trace file and print summary.

kairos trace inspect trace.json [--summary] [--format json]

Flag	Description
`--summary`	Print a compact summary instead of full details
`--format`	Output format: `json` or `table`

`kairos trace baseline`

Generate baseline traces for one or more scenarios.

# Specific scenarios
kairos trace baseline --scenarios standard,axelrod-tournament --steps 200 --output-dir baselines/

# All scenarios
kairos trace baseline --all --steps 200 --output-dir baselines/

Flag	Default	Description
`--scenarios`	None	Comma-separated scenario IDs
`--all`	Off	Generate baselines for all scenarios
`--steps`	`200`	Number of simulation steps
`--output-dir`	`.`	Output directory for baseline files
`--manifest`	Embedded	Path to a custom scenario manifest

`kairos trace hash`

Compute the SHA-256 hash of a file.

kairos trace hash trace.json

`kairos trace bundle`

Batch export traces with a manifest.

kairos trace bundle --scenarios standard,axelrod --steps 200 --output-dir bundle/
kairos trace bundle --all --steps 200 --output-dir bundle/

Flag	Default	Description
`--scenarios`	None	Comma-separated scenario IDs
`--all`	Off	Bundle all scenarios
`--steps`	`200`	Number of simulation steps
`--output-dir`	`.`	Output directory
`--manifest`	Embedded	Path to a custom scenario manifest

`kairos trace manifest`

Output the embedded or custom scenario manifest.

kairos trace manifest [--manifest custom.json] [--format json]

`kairos trace trend`

Compute per-step trend metrics for a trace.

kairos trace trend trace.json [--format json]

`kairos trace report`

Generate a formatted trace report.

kairos trace report trace.json [--format json]

`kairos trace suite`

Suite operations manage collections of traces for regression testing.

`kairos trace suite create`

Create a baseline suite.

kairos trace suite create --steps 200 --output-dir suite/

`kairos trace suite compare`

Compare current traces against a baseline suite.

kairos trace suite compare --baseline-dir suite/ --steps 200 [--epsilon 1e-3]

Flag	Default	Description
`--baseline-dir`	Required	Directory containing baseline traces
`--steps`	`200`	Number of simulation steps
`--epsilon`	`1e-3`	Epsilon for floating-point comparison
`--manifest`	Embedded	Path to a custom scenario manifest

`kairos trace suite lint`

Lint suite structure for errors.

kairos trace suite lint suite/

`kairos trace suite validate`

Validate suite contents.

kairos trace suite validate suite/

`kairos trace suite pack`

Pack operations for suite archives.

# Create archive
kairos trace suite pack create suite/ --output suite.tar

# Validate archive
kairos trace suite pack validate suite.tar

# Diff two archives
kairos trace suite pack diff a.tar b.tar