OpenParable
Skip to content
← Back to skills

Jit Overview

Development
jit-overview

Jit Overview is an Agent Skill for development published in the facet-rs/facet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/facet-rs/facet/blob/HEAD/.claude/skills/jit-overview/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/jit-overview, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.