Pass Snapshot Schema

This page defines the stable JSON lines schema emitted by:

  • --dump-pass-snapshots-json

JSON Envelope (schema v1)

Each line is one JSON object:

{
  "kind": "pass_snapshot",
  "schema_version": 1,
  "snapshot_kind": "hir_program",
  "name": "hir.lower_program",
  "detail": "functions=3 exprs=42 stmts=17",
  "fields": {
    "functions": 3,
    "exprs": 42,
    "stmts": 17
  }
}

Stable top-level keys:

  • kind: always pass_snapshot
  • schema_version: currently 1
  • snapshot_kind: stable semantic kind enum value
  • name: concrete pass name
  • detail: human-readable summary
  • fields: machine-readable key/value object

snapshot_kind Values

Stable values in schema v1:

  • meta_program
  • elab_program
  • hir_program
  • check_program
  • mir_program
  • codegen_rust
  • codegen_wasm

Field Contracts (schema v1)

meta_program (meta.expand_program):

  • functions (u64)
  • structs (u64)
  • enums (u64)

elab_program (elab.elaborate_program):

  • functions (u64)
  • structs (u64)
  • enums (u64)

hir_program (hir.lower_program):

  • functions (u64)
  • exprs (u64)
  • stmts (u64)

check_program (check.check_program):

  • signatures (u64)
  • local_symbols (u64)
  • occurrences (u64)

mir_program (mir.lower_program):

  • functions (u64)
  • locals (u64)
  • instrs (u64)

codegen_rust (codegen.rust.emit_program):

  • lines (u64)
  • bytes (u64)

codegen_wasm (codegen.wasm.emit_program):

  • wat_bytes (u64)
  • wasm_bytes (u64)
  • diagnostics (u64)

Compatibility Rules

  • Existing keys and snapshot_kind values are stable within schema v1.
  • New keys may be added to fields in v1, but existing keys keep their meaning.
  • Any breaking change requires incrementing schema_version.

Validation Script

Validate captured JSONL output with:

python3 scripts/validate-pass-snapshot-jsonl.py snapshots.jsonl

Example capture + validation:

cargo run -- --dump-pass-snapshots-json examples/basics.rk > snapshots.jsonl
python3 scripts/validate-pass-snapshot-jsonl.py --strict-pass-name snapshots.jsonl

CI integration note:

  • ./scripts/ci.sh validates any *.jsonl fixtures under tests/fixtures/pass-snapshots/.
  • If no fixtures exist, this check is skipped.