jit-overview

name	jit-overview
description	Orientation to facet-format JIT deserialization (tiering, fallbacks, key types/entry points) and where to look when changing or debugging JIT code

JIT deserialization overview (facet-format)

Facet’s JIT lives in facet-format and is used by format crates like facet-json.

When to read this

• You’re touching anything under facet-format/src/jit/ or enabling the jit feature.
• You’re investigating performance changes in deserialization (especially “tier2”/JIT benchmarks).
• You’re debugging a JIT crash (SIGSEGV/UB-ish symptoms).

Mental model

facet-format defines a format-neutral deserialization pipeline:

• A FormatParser (implemented by each format crate) produces a stream of ParseEvents.
• A shape-driven layer consumes those events and writes to an output value (often via facet-reflect).

The JIT accelerates this by compiling deserialization code specialized for:

1. the target type (T / its Shape), and sometimes
2. the format parser (P).

Two-tier architecture (high level)

Tier 1 (shape JIT)

• Compiles code that consumes ParseEvents and writes directly into the output’s memory at known offsets.
• Works with any format that implements FormatParser (JSON/YAML/TOML/…).

Tier 2 (format JIT)

• For the “entire input slice is available” case, a format crate can provide a FormatJitParser + JitFormat implementation.
• Tier 2 emits Cranelift IR to parse bytes directly, bypassing the ParseEvent stream for maximum throughput.

Fallbacks are part of the design

• Tier 2 may return “unsupported” for shapes/input it can’t handle, and must be side-effect-free in that case.
• Callers typically try tier 2, then tier 1, then reflection.

Entry points & where to look

• Main docs and contracts: facet-format/src/jit/mod.rs
• JIT-enabled parser trait: facet-format/src/parser.rs (FormatJitParser)
• JIT usage in a format crate:
  • facet-json/Cargo.toml feature jit = ["facet-format/jit"]
  • Example: facet-json/examples/profile_jit_vec (requires jit)
• Windows crash debugging notes: .claude/skills/windbg-jit.md
• Memory debugging: .claude/skills/debug-with-valgrind/SKILL.md (uses nextest profiles)

Debugging checklist (practical)

1. Reproduce with a minimal type + input (see .claude/skills/reproduce-reduce-regress/SKILL.md).
2. Run the failing test under:
   • valgrind: cargo nextest run --profile valgrind … (configured in .config/nextest.toml)
   • or Miri when applicable (just miri) for UB/provenance issues outside the JIT itself.
3. If the crash is in JIT codegen/execution:
   • Prefer isolating the smallest shape that triggers tier selection and failure.
   • Look for tier selection diagnostics and caching behavior in facet-format/src/jit/mod.rs.

Common pitfalls

• Assuming tier 2 supports “all shapes”: it intentionally supports a performance-focused subset.
• Forgetting that “unsupported” must not advance the parser cursor or partially initialize output.
• Introducing new unsafe paths without tests that exercise drop/cleanup on error paths.