---
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 `ParseEvent`s.
- 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 `ParseEvent`s 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.
