# logicaffeine_jit > Native execution tier for the LOGOS bytecode VM: hot functions and loops tier up to x86-64 machine code Every public module and item of `logicaffeine_jit`, module by module, each with its one-line summary and its address. Item pages hold the full signature, documentation, trait implementations and a link to the source. - Crate page: [logicaffeine_jit](https://docs.logicaffeine.com/logicaffeine_jit/) - All items on one page: [logicaffeine_jit/all](https://docs.logicaffeine.com/logicaffeine_jit/all) - Source: [src/logicaffeine_jit/lib.rs](https://docs.logicaffeine.com/src/logicaffeine_jit/lib.rs) - Every crate: [llms.txt](https://docs.logicaffeine.com/llms.txt) ## logicaffeine_jit - [mod image](https://docs.logicaffeine.com/logicaffeine_jit/image/): Build and execute self-contained optimized bytecode images. Precompiled bytecode images for the native JIT. - [struct ForgeTier](https://docs.logicaffeine.com/logicaffeine_jit/struct.ForgeTier): The forge-backed native tier, with compile observability. - [struct JitBackendOptimizationTrace](https://docs.logicaffeine.com/logicaffeine_jit/struct.JitBackendOptimizationTrace): Stage-separated evidence for one execution through the production run-optimizer -> VM -> forge-JIT pipeline. - [struct JitOptimizationTrace](https://docs.logicaffeine.com/logicaffeine_jit/struct.JitOptimizationTrace): Monotonic firing counts. Snapshot before and after one benchmark run and subtract to obtain that program’s exact native-JIT optimization trace. - [enum JitOptimization](https://docs.logicaffeine.com/logicaffeine_jit/enum.JitOptimization): Native-only JIT optimizations which run after LOGOS bytecode has been produced. These cannot honestly share an `Opt` bit with the Rust emitter: they transform JIT micro-ops, so they have their own named trace and are reported alongside the shared compiler trace. - [const LOGOS_MEMMEM_DEOPT](https://docs.logicaffeine.com/logicaffeine_jit/constant.LOGOS_MEMMEM_DEOPT): The deopt sentinel `logos_rt_memmem` returns when the recognized search nest would, on bytecode, take an access the helper cannot reproduce in-bounds — a checked needle index past the needle buffer (`needleLen > len(needle)`). The caller’s stencil routes this to a side exit so the VM replays from the region head on bytecode and raises the EXACT same error at the EXACT same point. `i64::MIN` is never a legitimate count (a count is in `[0, haystack_len]`). - [static REGION_DEOPTS](https://docs.logicaffeine.com/logicaffeine_jit/static.REGION_DEOPTS) - [static REGION_RUNS](https://docs.logicaffeine.com/logicaffeine_jit/static.REGION_RUNS) - [fn adapt](https://docs.logicaffeine.com/logicaffeine_jit/fn.adapt): Translate WHOLE-PROGRAM Main bytecode into the J2 micro-op subset. - [fn install](https://docs.logicaffeine.com/logicaffeine_jit/fn.install) - [fn logos_rt_adopt_list_i64](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_adopt_list_i64): Adopt a list-returning callee’s Vec into a region’s pinned destination. The two input slots hold the returned and destination handles. An owned result moves; a borrowed result is copied. Pin refresh is a separate ListTriple micro-op, so every frame access is visible to code generation. - [fn logos_rt_alloc_list_i64](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_alloc_list_i64): Allocate a fresh Int list and plant its pin triple. - [fn logos_rt_alloc_list_i64_fixed](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_alloc_list_i64_fixed): Allocate a proof-sized Int list. The adapter places the capacity in `len_slot`; this helper consumes it and restores the observable length 0. - [fn logos_rt_alloc_scope_enter](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_alloc_scope_enter): Start one native function’s allocation lifetime. - [fn logos_rt_alloc_scope_leave](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_alloc_scope_leave): Release one native function’s scratch allocations, retaining its exported list handles for the caller. The first input is the return word; the rest are final mutable list parameters. A nonzero imm marks a scalar return. - [fn logos_rt_clear_bool](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_clear_bool): See `logos_rt_clear_i64` — `Vec` buffer. - [fn logos_rt_clear_f64](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_clear_f64): See `logos_rt_clear_i64` — `Vec` buffer. - [fn logos_rt_clear_i32](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_clear_i32): See `logos_rt_clear_i64` — half-width `Vec` buffer. - [fn logos_rt_clear_i64](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_clear_i64): In-place clear of a pinned list: `vec.clear()` (truncate to empty, KEEP the buffer/capacity) and refresh the pinned ptr/len slots (ptr unchanged — clear never reallocs — but refreshed for parity with push). Lowers an in-region `NewEmptyList` on a pinned array: an in-place mutation (like SetIndex), so the PRECISE region resumes over it soundly. See `logos_rt_push_i64` for the frame-slot convention. - [fn logos_rt_list_own](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_list_own): Copy-on-write: give the list in `frame[handle_slot]` its own registry-owned buffer — a copy of the shared one — and re-plant the register’s handle and pin triple on it. The native twin of the VM’s first write to a shared list; the original (a parameter’s, or a caller’s through a passthrough) is untouched from here on. - [fn logos_rt_list_triple](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_list_triple): Plant the pin triple for a list handle RETURNED by a self-call (the caller’s view of the callee’s result list). - [fn logos_rt_map_get_ii](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_map_get_ii) - [fn logos_rt_map_has_i](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_map_has_i): Map membership for an Int key. - [fn logos_rt_map_set_ii](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_map_set_ii): Map insert on the kernel’s own storage — identical hashing, identical iteration order. - [fn logos_rt_memmem](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_memmem): Count OVERLAPPING occurrences of an ASCII needle in an ASCII haystack, reproducing the LOGOS naive-search nest BIT-IDENTICALLY (the string_search benchmark idiom). The recognizer in `adapt_region` collapses the per-byte nested-loop region to a single call to this helper. - [fn logos_rt_memmem_frame](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_memmem_frame): Frame-driven entry the `MicroOp::MemMem` stencil calls: reads the search nest’s live values out of the JIT frame, runs `logos_rt_memmem`, and on success ADDS the count into `count_slot` and advances `i_slot` to the loop’s exit value (`bound + 1`). Returns `1` on success and `0` on the deopt sentinel — the stencil routes `0` to its side-exit continuation, untouched. - [fn logos_rt_push_bool](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_push_bool): See `logos_rt_push_i64` — nonzero stores `true`. - [fn logos_rt_push_f64](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_push_f64): See `logos_rt_push_i64` — f64 value travels as bits. - [fn logos_rt_push_i32](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_push_i32): Push helper for pinned half-width Int lists (`ListRepr::IntsI32` = `Vec`): the value TRUNCATES to its low 4 bytes. The narrowing proof guarantees every pushed value fits `i32`, so the truncation is lossless; `debug_assert` catches a proof violation in test builds. The refreshed `ptr_slot` is the `Vec` element buffer (4-byte stride — the stencil and regalloc loads `movsxd` from it). - [fn logos_rt_push_i64](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_push_i64): Push helper for pinned Int lists. - [fn logos_rt_region_alloc_reset](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_region_alloc_reset): Reclaim native lists whose allocation-site registers are dead at the hot loop backedge. The region adapter emits this only when every allocation destination is non-live-in and has no list-handle copy/rebind. - [fn logos_rt_side_exit](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_side_exit): An unconditional side exit: answers 0, so a precise chain resumes on the VM at the op that holds it. - [fn logos_rt_str_append](https://docs.logicaffeine.com/logicaffeine_jit/fn.logos_rt_str_append): MUTABLE-Text append helper for the `MicroOp::StrAppend` regalloc lowering of a `Set text to text + ` build loop. `frame[handle_slot]` holds a `*mut Value` pointing AT THE VM REGISTER CELL holding the accumulator (planted at region entry). `src`/`src_len` carry the appended operand: - [fn native_alloc_registry_len](https://docs.logicaffeine.com/logicaffeine_jit/fn.native_alloc_registry_len): Registry depth — drained-to-zero is part of every boundary’s contract (asserted by the test gates). - [fn native_alloc_scope_counts](https://docs.logicaffeine.com/logicaffeine_jit/fn.native_alloc_scope_counts): Cumulative scope entries and successful leaves. - [fn native_alloc_scope_depth](https://docs.logicaffeine.com/logicaffeine_jit/fn.native_alloc_scope_depth): Native allocation-scope depth. Success and deopt boundaries restore this to zero; exposed so parity tests can lock the lifetime invariant. - [fn native_region_alloc_reset_count](https://docs.logicaffeine.com/logicaffeine_jit/fn.native_region_alloc_reset_count): Number of hot-loop iteration boundaries that reclaimed dead native list temporaries. Exposed for the benchmark-shape lock test. - [fn optimization_trace_jit](https://docs.logicaffeine.com/logicaffeine_jit/fn.optimization_trace_jit): Execute through the production eager optimizer and a fresh private forge tier, returning both shared-pass and native-lowering evidence. Native refusals enter the common fallback channel as `Jit -> Vm`, so a missed tier can no longer hide behind a successful bytecode completion. - [fn segv_trace_install](https://docs.logicaffeine.com/logicaffeine_jit/fn.segv_trace_install): Install the forge tier as the process-wide native tier. Idempotent — the first call wins; later calls return the already-installed tier. ## logicaffeine_jit::image Build and execute self-contained optimized bytecode images. Precompiled bytecode images for the native JIT. - [struct ImageOutcome](https://docs.logicaffeine.com/logicaffeine_jit/image/struct.ImageOutcome): One image execution’s complete observable result. - [fn build](https://docs.logicaffeine.com/logicaffeine_jit/image/fn.build): Compile source through the production eager run-path optimizer into a self-contained LGB1 bytecode image. - [fn run](https://docs.logicaffeine.com/logicaffeine_jit/image/fn.run): Decode and execute an image on the bytecode VM with the supplied private copy-and-patch tier. `program_args` is the full argv, including `argv[0]`.