From 0ebf0a2246febc07d02f654502521fe9d7a909de Mon Sep 17 00:00:00 2001
From: Sergei Zharinov <zharinov@users.noreply.github.com>
Date: Wed, 31 Dec 2025 09:27:28 -0300
Subject: [PATCH 1/3] feat: add query compilation to bytecode

---
 crates/plotnik-lib/src/bytecode/dump_tests.rs |  131 ++
 crates/plotnik-lib/src/bytecode/mod.rs        |    2 +
 ...ecode__dump_tests__dump_comprehensive.snap |   81 ++
 .../src/query/{emit.rs => codegen.rs}         |  126 +-
 crates/plotnik-lib/src/query/codegen_tests.rs |  420 ++++++
 crates/plotnik-lib/src/query/compile.rs       | 1247 +++++++++++++++++
 crates/plotnik-lib/src/query/emit_tests.rs    |  333 -----
 crates/plotnik-lib/src/query/link.rs          |    6 +-
 crates/plotnik-lib/src/query/mod.rs           |    5 +-
 crates/plotnik-lib/src/query/query.rs         |   36 +-
 crates/plotnik-lib/src/query/query_tests.rs   |   46 +-
 11 files changed, 2060 insertions(+), 373 deletions(-)
 create mode 100644 crates/plotnik-lib/src/bytecode/dump_tests.rs
 create mode 100644 crates/plotnik-lib/src/bytecode/snapshots/plotnik_lib__bytecode__dump_tests__dump_comprehensive.snap
 rename crates/plotnik-lib/src/query/{emit.rs => codegen.rs} (85%)
 create mode 100644 crates/plotnik-lib/src/query/codegen_tests.rs
 create mode 100644 crates/plotnik-lib/src/query/compile.rs
 delete mode 100644 crates/plotnik-lib/src/query/emit_tests.rs

diff --git a/crates/plotnik-lib/src/bytecode/dump_tests.rs b/crates/plotnik-lib/src/bytecode/dump_tests.rs
new file mode 100644
index 00000000..1121b82b
--- /dev/null
+++ b/crates/plotnik-lib/src/bytecode/dump_tests.rs
@@ -0,0 +1,131 @@
+//! Tests for bytecode dump functionality.
+
+use crate::Query;
+use indoc::indoc;
+
+#[test]
+fn dump_minimal() {
+    let input = "Test = (identifier) @id";
+
+    let res = Query::expect_valid_linked_bytecode(input);
+
+    insta::assert_snapshot!(res, @r#"
+    [header]
+    linked = true
+
+    [strings]
+    S00 "Beauty will save the world"
+    S01 "id"
+    S02 "Test"
+    S03 "identifier"
+
+    [types.defs]
+    T00 = void
+    T01 = Node
+    T02 = str
+    T03 = Struct(M0, 1)  ; { id }
+
+    [types.members]
+    M0 = (S01, T01)  ; id: Node
+
+    [types.names]
+    N0 = (S02, T03)  ; Test
+
+    [entry]
+    Test = 01 :: T03
+
+    [code]
+      00   𝜀                                    ◼
+
+    Test:
+      01   𝜀                                    02
+      02  *↓   (identifier)                     03
+      03   𝜀   [Node Set(M0)]                   ◼
+    "#);
+}
+
+#[test]
+fn dump_multiple_entrypoints() {
+    let input = indoc! {r#"
+        Expression = [(identifier) @name (number) @value]
+        Root = (function_declaration name: (identifier) @name)
+    "#};
+
+    let res = Query::expect_valid_linked_bytecode(input);
+
+    // Verify key sections exist
+    assert!(res.contains("[header]"));
+    assert!(res.contains("[strings]"));
+    assert!(res.contains("[types.defs]"));
+    assert!(res.contains("[types.members]"));
+    assert!(res.contains("[types.names]"));
+    assert!(res.contains("[entry]"));
+    assert!(res.contains("[code]"));
+
+    // Verify both entrypoints appear
+    assert!(res.contains("Expression"));
+    assert!(res.contains("Root"));
+
+    // Verify code section has entrypoint labels
+    assert!(res.contains("Expression:"));
+    assert!(res.contains("Root:"));
+}
+
+#[test]
+fn dump_with_field_constraints() {
+    let input = indoc! {r#"
+        Test = (binary_expression
+            left: (_) @left
+            right: (_) @right)
+    "#};
+
+    let res = Query::expect_valid_linked_bytecode(input);
+
+    // Should have field references in code section
+    assert!(res.contains("left:"));
+    assert!(res.contains("right:"));
+}
+
+#[test]
+fn dump_with_quantifier() {
+    let input = "Test = (identifier)* @items";
+
+    let res = Query::expect_valid_linked_bytecode(input);
+
+    // Should have array type
+    assert!(res.contains("Array") || res.contains("[]"));
+}
+
+#[test]
+fn dump_with_alternation() {
+    let input = "Test = [(identifier) @id (string) @str]";
+
+    let res = Query::expect_valid_linked_bytecode(input);
+
+    // Should have code section with branching
+    assert!(res.contains("[code]"));
+}
+
+#[test]
+fn dump_comprehensive() {
+    // A query that exercises most features:
+    // - Multiple definitions (entrypoints)
+    // - Field constraints (node_fields)
+    // - Multiple node types (node_types)
+    // - Captures with types (type_defs, type_members)
+    // - Alternation (branching in code)
+    let input = indoc! {r#"
+        Ident = (identifier) @name :: string
+        Expression = [
+            Literal: (number) @value
+            Variable: (identifier) @name
+        ]
+        Assignment = (assignment_expression
+            left: (identifier) @target
+            right: (Expression) @value)
+    "#};
+
+    let res = Query::expect_valid_linked_bytecode(input);
+
+    insta::assert_snapshot!(res);
+}
diff --git a/crates/plotnik-lib/src/bytecode/mod.rs b/crates/plotnik-lib/src/bytecode/mod.rs
index e288c04a..9fdf7557 100644
--- a/crates/plotnik-lib/src/bytecode/mod.rs
+++ b/crates/plotnik-lib/src/bytecode/mod.rs
@@ -47,6 +47,8 @@ pub use module::{
 
 pub use dump::dump;
 
+#[cfg(test)]
+mod dump_tests;
 #[cfg(test)]
 mod instructions_tests;
 #[cfg(test)]
diff --git a/crates/plotnik-lib/src/bytecode/snapshots/plotnik_lib__bytecode__dump_tests__dump_comprehensive.snap b/crates/plotnik-lib/src/bytecode/snapshots/plotnik_lib__bytecode__dump_tests__dump_comprehensive.snap
new file mode 100644
index 00000000..69ea7eae
--- /dev/null
+++ b/crates/plotnik-lib/src/bytecode/snapshots/plotnik_lib__bytecode__dump_tests__dump_comprehensive.snap
@@ -0,0 +1,81 @@
+---
+source: crates/plotnik-lib/src/bytecode/dump_tests.rs
+expression: res
+---
+[header]
+linked = true
+
+[strings]
+S00 "Beauty will save the world"
+S01 "name"
+S02 "value"
+S03 "Literal"
+S04 "Variable"
+S05 "target"
+S06 "Ident"
+S07 "Expression"
+S08 "Assignment"
+S09 "identifier"
+S10 "number"
+S11 "assignment_expression"
+S12 "left"
+S13 "right"
+
+[types.defs]
+T00 = void
+T01 = Node
+T02 = str
+T03 = Struct(M0, 1)  ; { name }
+T04 = Struct(M1, 1)  ; { value }
+T05 = Struct(M2, 1)  ; { name }
+T06 = Enum(M3, 2)  ; Literal | Variable
+T07 = Struct(M5, 2)  ; { value, target }
+
+[types.members]
+M0 = (S01, T02)  ; name: str
+M1 = (S02, T01)  ; value: Node
+M2 = (S01, T01)  ; name: Node
+M3 = (S03, T04)  ; Literal: T04
+M4 = (S04, T05)  ; Variable: T05
+M5 = (S02, T06)  ; value: Expression
+M6 = (S05, T01)  ; target: Node
+
+[types.names]
+N0 = (S06, T03)  ; Ident
+N1 = (S07, T06)  ; Expression
+N2 = (S08, T07)  ; Assignment
+
+[entry]
+Assignment = 08 :: T07
+Expression = 05 :: T06
+Ident      = 01 :: T03
+
+[code]
+  00   𝜀                                    ◼
+
+Ident:
+  01   𝜀                                    02
+  02  *↓   (identifier)                     03
+  03   𝜀   [Text Set(M0)]                   ◼
+
+Expression:
+  05   𝜀                                    06
+  06   𝜀                                    23, 30
+
+Assignment:
+  08   𝜀                                    09
+  09  *↓   (assignment_expression)          10
+  10   𝜀   left: _                          11
+  11  *↓   (identifier)                     12
+  12   𝜀   [Node Set(M1)]                   14
+  14   𝜀   right: _                         ▶(Expression)
+  15   𝜀   [Node Set(M0)]                   17
+  17  *↑¹                                   ◼
+  18   𝜀   [EndE]                           ◼
+  20   𝜀   [Node]                           18
+  22  *↓   (number)                         20
+  23   𝜀   [E(M0)]                          22
+  25   𝜀   [EndE]                           ◼
+  27   𝜀   [Node]                           25
+  29  *↓   (identifier)                     27
+  30   𝜀   [E(M1)]                          29
diff --git a/crates/plotnik-lib/src/query/emit.rs b/crates/plotnik-lib/src/query/codegen.rs
similarity index 85%
rename from crates/plotnik-lib/src/query/emit.rs
rename to crates/plotnik-lib/src/query/codegen.rs
index ab2f1665..2c2cbde7 100644
--- a/crates/plotnik-lib/src/query/emit.rs
+++ b/crates/plotnik-lib/src/query/codegen.rs
@@ -4,15 +4,20 @@
 
 use std::collections::{HashMap, HashSet};
 
+use indexmap::IndexMap;
 use plotnik_core::{Interner, NodeFieldId, NodeTypeId, Symbol};
 
+use crate::bytecode::ir::Label;
+use crate::bytecode::layout::CacheAligned;
 use crate::bytecode::{
     Entrypoint, FieldSymbol, Header, NodeSymbol, QTypeId, SECTION_ALIGN, StepId, StringId,
     TriviaEntry, TypeDef, TypeMember, TypeMetaHeader, TypeName,
 };
 use crate::type_system::TypeKind;
 
+use super::compile::Compiler;
 use super::query::LinkedQuery;
+use super::symbol_table::SymbolTable;
 use super::type_check::{
     FieldInfo, TYPE_NODE, TYPE_STRING, TYPE_VOID, TypeContext, TypeId, TypeShape,
 };
@@ -20,6 +25,8 @@ use super::type_check::{
 /// Error during bytecode emission.
 #[derive(Clone, Debug)]
 pub enum EmitError {
+    /// Query has validation errors (must be valid before emitting).
+    InvalidQuery,
     /// Too many strings (exceeds u16 max).
     TooManyStrings(usize),
     /// Too many types (exceeds u16 max).
@@ -28,29 +35,43 @@ pub enum EmitError {
     TooManyTypeMembers(usize),
     /// Too many entrypoints (exceeds u16 max).
     TooManyEntrypoints(usize),
+    /// Too many transitions (exceeds u16 max).
+    TooManyTransitions(usize),
     /// String not found in interner.
     StringNotFound(Symbol),
+    /// Compilation error.
+    Compile(super::compile::CompileError),
 }
 
 impl std::fmt::Display for EmitError {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
+            Self::InvalidQuery => write!(f, "query has validation errors"),
             Self::TooManyStrings(n) => write!(f, "too many strings: {n} (max 65534)"),
             Self::TooManyTypes(n) => write!(f, "too many types: {n} (max 65533)"),
             Self::TooManyTypeMembers(n) => write!(f, "too many type members: {n} (max 65535)"),
             Self::TooManyEntrypoints(n) => write!(f, "too many entrypoints: {n} (max 65535)"),
+            Self::TooManyTransitions(n) => write!(f, "too many transitions: {n} (max 65535)"),
             Self::StringNotFound(sym) => write!(f, "string not found for symbol: {sym:?}"),
+            Self::Compile(e) => write!(f, "compilation error: {e}"),
         }
     }
 }
 
 impl std::error::Error for EmitError {}
 
+/// Easter egg string at index 0 (Dostoevsky, The Idiot).
+/// StringId(0) is reserved and never referenced by instructions.
+pub const EASTER_EGG: &str = "Beauty will save the world";
+
 /// Builds the string table, remapping query Symbols to bytecode StringIds.
 ///
 /// The bytecode format requires a subset of the query interner's strings.
 /// This builder collects only the strings that are actually used and assigns
 /// compact StringId indices.
+///
+/// StringId(0) is reserved for an easter egg and is never referenced by
+/// instructions. Actual strings start at index 1.
 #[derive(Debug)]
 pub struct StringTableBuilder {
     /// Map from query Symbol to bytecode StringId.
@@ -63,11 +84,15 @@ pub struct StringTableBuilder {
 
 impl StringTableBuilder {
     pub fn new() -> Self {
-        Self {
+        let mut builder = Self {
             mapping: HashMap::new(),
             str_lookup: HashMap::new(),
             strings: Vec::new(),
-        }
+        };
+        // Reserve index 0 for easter egg
+        builder.strings.push(EASTER_EGG.to_string());
+        builder.str_lookup.insert(EASTER_EGG.to_string(), StringId(0));
+        builder
     }
 
     /// Get or create a StringId for a Symbol.
@@ -115,7 +140,8 @@ impl StringTableBuilder {
 
     /// Validate that the string count fits in u16.
     pub fn validate(&self) -> Result<(), EmitError> {
-        // Max count is 65534 because the table needs count+1 entries
+        // Max count is 65534 because the table needs count+1 entries.
+        // Index 0 is reserved for the easter egg, so we can have 65533 user strings.
         if self.strings.len() > 65534 {
             return Err(EmitError::TooManyStrings(self.strings.len()));
         }
@@ -211,10 +237,10 @@ impl TypeTableBuilder {
 
         // Emit TypeDefs and TypeMembers - fill in the placeholders.
         for (slot_index, &type_id) in ordered_types.iter().enumerate() {
-            let type_kind = type_ctx
+            let type_shape = type_ctx
                 .get_type(type_id)
                 .expect("collected type must exist");
-            self.emit_type_at_slot(slot_index, type_id, type_kind, type_ctx, interner, strings)?;
+            self.emit_type_at_slot(slot_index, type_id, type_shape, type_ctx, interner, strings)?;
         }
 
         // Collect TypeName entries for named definitions
@@ -236,12 +262,12 @@ impl TypeTableBuilder {
         &mut self,
         slot_index: usize,
         _type_id: TypeId,
-        type_kind: &TypeShape,
+        type_shape: &TypeShape,
         type_ctx: &TypeContext,
         interner: &Interner,
         strings: &mut StringTableBuilder,
     ) -> Result<(), EmitError> {
-        match type_kind {
+        match type_shape {
             TypeShape::Void | TypeShape::Node | TypeShape::String => {
                 // Builtins - should not reach here
                 unreachable!("builtins should be handled separately")
@@ -362,8 +388,8 @@ impl TypeTableBuilder {
         }
 
         // Handle Ref types by following the reference
-        if let Some(type_kind) = type_ctx.get_type(type_id)
-            && let TypeShape::Ref(def_id) = type_kind
+        if let Some(type_shape) = type_ctx.get_type(type_id)
+            && let TypeShape::Ref(def_id) = type_shape
             && let Some(def_type_id) = type_ctx.get_def_type(*def_id)
         {
             return self.resolve_type(def_type_id, type_ctx);
@@ -486,12 +512,12 @@ fn collect_types_dfs(
         return;
     }
 
-    let Some(type_kind) = type_ctx.get_type(type_id) else {
+    let Some(type_shape) = type_ctx.get_type(type_id) else {
         return;
     };
 
     // Resolve Ref types to their target
-    if let TypeShape::Ref(def_id) = type_kind {
+    if let TypeShape::Ref(def_id) = type_shape {
         if let Some(target_id) = type_ctx.get_def_type(*def_id) {
             collect_types_dfs(target_id, type_ctx, out, seen);
         }
@@ -501,7 +527,7 @@ fn collect_types_dfs(
     seen.insert(type_id);
 
     // Collect children first (depth-first), then add self
-    match type_kind {
+    match type_shape {
         TypeShape::Struct(fields) => {
             for field_info in fields.values() {
                 collect_types_dfs(field_info.type_id, type_ctx, out, seen);
@@ -542,8 +568,12 @@ fn pad_to_section(buf: &mut Vec<u8>) {
 }
 
 /// Emit bytecode from type context only (no node validation).
-pub fn emit(type_ctx: &TypeContext, interner: &Interner) -> Result<Vec<u8>, EmitError> {
-    emit_inner(type_ctx, interner, None, None)
+pub fn emit(
+    type_ctx: &TypeContext,
+    interner: &Interner,
+    symbol_table: &SymbolTable,
+) -> Result<Vec<u8>, EmitError> {
+    emit_inner(type_ctx, interner, symbol_table, None, None)
 }
 
 /// Emit bytecode from a LinkedQuery (includes node type/field validation info).
@@ -551,6 +581,7 @@ pub fn emit_linked(query: &LinkedQuery) -> Result<Vec<u8>, EmitError> {
     emit_inner(
         query.type_context(),
         query.interner(),
+        &query.symbol_table,
         Some(query.node_type_ids()),
         Some(query.node_field_ids()),
     )
@@ -560,13 +591,28 @@ pub fn emit_linked(query: &LinkedQuery) -> Result<Vec<u8>, EmitError> {
 fn emit_inner(
     type_ctx: &TypeContext,
     interner: &Interner,
-    node_type_ids: Option<&HashMap<Symbol, NodeTypeId>>,
-    node_field_ids: Option<&HashMap<Symbol, NodeFieldId>>,
+    symbol_table: &SymbolTable,
+    node_type_ids: Option<&IndexMap<Symbol, NodeTypeId>>,
+    node_field_ids: Option<&IndexMap<Symbol, NodeFieldId>>,
 ) -> Result<Vec<u8>, EmitError> {
+    let is_linked = node_type_ids.is_some();
     let mut strings = StringTableBuilder::new();
     let mut types = TypeTableBuilder::new();
     types.build(type_ctx, interner, &mut strings)?;
 
+    // Compile transitions (strings are interned here for unlinked mode)
+    let compile_result = Compiler::compile(interner, type_ctx, symbol_table, &mut strings, node_type_ids, node_field_ids)
+        .map_err(EmitError::Compile)?;
+
+    // Layout with cache alignment
+    let entry_labels: Vec<Label> = compile_result.def_entries.values().copied().collect();
+    let layout = CacheAligned::layout(&compile_result.instructions, &entry_labels);
+
+    // Validate transition count
+    if layout.total_steps as usize > 65535 {
+        return Err(EmitError::TooManyTransitions(layout.total_steps as usize));
+    }
+
     // Collect node symbols (empty if not linked)
     let mut node_symbols: Vec<NodeSymbol> = Vec::new();
     if let Some(ids) = node_type_ids {
@@ -591,15 +637,24 @@ fn emit_inner(
         }
     }
 
-    // Collect entrypoints
+    // Collect entrypoints with actual targets from layout
     let mut entrypoints: Vec<Entrypoint> = Vec::new();
     for (def_id, type_id) in type_ctx.iter_def_types() {
         let name_sym = type_ctx.def_name_sym(def_id);
         let name = strings.get_or_intern(name_sym, interner)?;
         let result_type = types.get(type_id).unwrap_or(QTypeId::VOID);
+
+        // Get actual target from compiled result
+        let target = compile_result
+            .def_entries
+            .get(&def_id)
+            .and_then(|label| layout.label_to_step.get(label))
+            .copied()
+            .unwrap_or(StepId::ACCEPT);
+
         entrypoints.push(Entrypoint {
             name,
-            target: StepId::ACCEPT,
+            target,
             result_type,
             _pad: 0,
         });
@@ -615,6 +670,9 @@ fn emit_inner(
     // Trivia (empty for now)
     let trivia_entries: Vec<TriviaEntry> = Vec::new();
 
+    // Resolve and serialize transitions
+    let transitions_bytes = emit_transitions(&compile_result.instructions, &layout);
+
     // Emit all byte sections
     let (str_blob, str_table) = strings.emit();
     let (type_defs_bytes, type_members_bytes, type_names_bytes) = types.emit();
@@ -649,7 +707,7 @@ fn emit_inner(
     emit_section(&mut output, &type_names_bytes);
 
     let entrypoints_offset = emit_section(&mut output, &entrypoints_bytes);
-    let transitions_offset = emit_section(&mut output, &[]); // Empty for now
+    let transitions_offset = emit_section(&mut output, &transitions_bytes);
 
     pad_to_section(&mut output);
     let total_size = output.len() as u32;
@@ -669,16 +727,44 @@ fn emit_inner(
         node_fields_count: field_symbols.len() as u16,
         trivia_count: trivia_entries.len() as u16,
         entrypoints_count: entrypoints.len() as u16,
-        transitions_count: 0,
+        transitions_count: layout.total_steps,
         total_size,
         ..Default::default()
     };
+    header.set_linked(is_linked);
     header.checksum = crc32fast::hash(&output[64..]);
     output[..64].copy_from_slice(&header.to_bytes());
 
     Ok(output)
 }
 
+/// Emit transitions section from instructions and layout.
+fn emit_transitions(
+    instructions: &[crate::bytecode::ir::Instruction],
+    layout: &crate::bytecode::ir::LayoutResult,
+) -> Vec<u8> {
+    // Allocate buffer for all steps (8 bytes each)
+    let mut bytes = vec![0u8; layout.total_steps as usize * 8];
+
+    for instr in instructions {
+        let label = instr.label();
+        let Some(&step_id) = layout.label_to_step.get(&label) else {
+            continue;
+        };
+
+        let offset = step_id.byte_offset();
+        let resolved = instr.resolve(&layout.label_to_step);
+
+        // Copy instruction bytes to the correct position
+        let end = offset + resolved.len();
+        if end <= bytes.len() {
+            bytes[offset..end].copy_from_slice(&resolved);
+        }
+    }
+
+    bytes
+}
+
 fn emit_section(output: &mut Vec<u8>, data: &[u8]) -> u32 {
     pad_to_section(output);
     let offset = output.len() as u32;
diff --git a/crates/plotnik-lib/src/query/codegen_tests.rs b/crates/plotnik-lib/src/query/codegen_tests.rs
new file mode 100644
index 00000000..942a2b42
--- /dev/null
+++ b/crates/plotnik-lib/src/query/codegen_tests.rs
@@ -0,0 +1,420 @@
+//! Tests for bytecode emission.
+
+use indoc::indoc;
+
+use crate::Query;
+use crate::bytecode::{Header, MAGIC, Module, QTypeId, VERSION};
+use crate::query::codegen::{StringTableBuilder, TypeTableBuilder};
+
+#[test]
+fn emit_minimal_query() {
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
+
+    // Verify header
+    assert!(bytes.len() >= 64);
+    let header = Header::from_bytes(&bytes);
+    assert_eq!(header.magic, MAGIC);
+    assert_eq!(header.version, VERSION);
+    assert_eq!(header.total_size as usize, bytes.len());
+
+    // Should have 1 entrypoint
+    assert_eq!(header.entrypoints_count, 1);
+
+    // Should have at least one string (the definition name "Test")
+    assert!(header.str_table_count >= 1);
+
+    // Should have at least one node type ("identifier")
+    assert!(header.node_types_count >= 1);
+}
+
+#[test]
+fn emit_roundtrip_via_module() {
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
+    let module = Module::from_bytes(bytes).expect("load module");
+
+    // Verify we can read back the strings
+    assert!(module.header().str_table_count >= 1);
+
+    // Verify we can read back entrypoints
+    let entrypoints = module.entrypoints();
+    assert_eq!(entrypoints.len(), 1);
+
+    // Verify we can read the entrypoint name
+    let ep = entrypoints.get(0);
+    let name = module.strings().get(ep.name);
+    assert_eq!(name, "Test");
+}
+
+#[test]
+fn emit_multiple_definitions() {
+    let input = indoc! {r#"
+        Foo = (identifier) @id
+        Bar = (string) @str
+    "#};
+
+    let bytes = Query::expect_valid_linked_bytes(input);
+    let header = Header::from_bytes(&bytes);
+
+    // Should have 2 entrypoints
+    assert_eq!(header.entrypoints_count, 2);
+
+    // Entrypoints preserve definition order
+    let module = Module::from_bytes(bytes).expect("load module");
+    let entrypoints = module.entrypoints();
+
+    let ep0 = entrypoints.get(0);
+    let ep1 = entrypoints.get(1);
+
+    let name0 = module.strings().get(ep0.name);
+    let name1 = module.strings().get(ep1.name);
+
+    assert_eq!(name0, "Foo"); // Foo defined first
+    assert_eq!(name1, "Bar");
+}
+
+#[test]
+fn emit_with_field_constraint() {
+    let input = "Test = (function_declaration name: (identifier) @name)";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
+    let header = Header::from_bytes(&bytes);
+
+    // Should have at least one field ("name")
+    assert!(header.node_fields_count >= 1);
+
+    let module = Module::from_bytes(bytes).expect("load module");
+    let fields = module.node_fields();
+
+    // Find the "name" field
+    let has_name_field = (0..fields.len()).any(|i| {
+        let f = fields.get(i);
+        module.strings().get(f.name) == "name"
+    });
+    assert!(has_name_field, "should have 'name' field");
+}
+
+#[test]
+fn emit_with_struct_type() {
+    let input = indoc! {r#"
+        Test = (function_declaration
+            name: (identifier) @name
+            body: (_) @body)
+    "#};
+
+    let bytes = Query::expect_valid_linked_bytes(input);
+    let module = Module::from_bytes(bytes).expect("load module");
+    let types = module.types();
+
+    // Should have type definitions for the struct
+    // The struct has 2 fields, so we expect type members
+    assert!(types.defs_count() >= 1 || types.members_count() >= 2);
+}
+
+#[test]
+fn emit_checksum_is_valid() {
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
+    let header = Header::from_bytes(&bytes);
+
+    // Verify checksum
+    let computed = crc32fast::hash(&bytes[64..]);
+    assert_eq!(header.checksum, computed, "checksum mismatch");
+}
+
+#[test]
+fn emit_sections_are_aligned() {
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
+    let header = Header::from_bytes(&bytes);
+
+    // All section offsets should be 64-byte aligned
+    assert_eq!(header.str_blob_offset % 64, 0, "str_blob not aligned");
+    assert_eq!(header.str_table_offset % 64, 0, "str_table not aligned");
+    assert_eq!(header.node_types_offset % 64, 0, "node_types not aligned");
+    assert_eq!(header.node_fields_offset % 64, 0, "node_fields not aligned");
+    assert_eq!(header.trivia_offset % 64, 0, "trivia not aligned");
+    assert_eq!(header.type_meta_offset % 64, 0, "type_meta not aligned");
+    assert_eq!(header.entrypoints_offset % 64, 0, "entrypoints not aligned");
+    assert_eq!(header.transitions_offset % 64, 0, "transitions not aligned");
+}
+
+// Builder API tests - these test internal APIs directly
+
+#[test]
+fn string_table_builder_deduplicates() {
+    use plotnik_core::Interner;
+
+    let mut interner = Interner::new();
+    let sym1 = interner.intern("foo");
+    let sym2 = interner.intern("bar");
+    let sym3 = interner.intern("foo"); // Same as sym1
+
+    let mut builder = StringTableBuilder::new();
+    let id1 = builder.get_or_intern(sym1, &interner).expect("id1");
+    let id2 = builder.get_or_intern(sym2, &interner).expect("id2");
+    let id3 = builder.get_or_intern(sym3, &interner).expect("id3");
+
+    assert_eq!(id1, id3); // Same symbol -> same StringId
+    assert_ne!(id1, id2); // Different symbols -> different StringIds
+    // 3 strings: easter egg at index 0, plus 2 unique user strings
+    assert_eq!(builder.len(), 3);
+}
+
+#[test]
+fn string_table_builder_intern_str() {
+    let mut builder = StringTableBuilder::new();
+
+    let id1 = builder.intern_str("hello");
+    let id2 = builder.intern_str("world");
+    let id3 = builder.intern_str("hello"); // Duplicate
+
+    assert_eq!(id1, id3);
+    assert_ne!(id1, id2);
+    // 3 strings: easter egg at index 0, plus 2 unique user strings
+    assert_eq!(builder.len(), 3);
+}
+
+#[test]
+fn type_table_builder_builtins() {
+    use crate::query::type_check::{TYPE_NODE, TYPE_STRING, TYPE_VOID};
+
+    let mut builder = TypeTableBuilder::new();
+
+    // Build with empty context
+    let type_ctx = crate::query::type_check::TypeContext::new();
+    let interner = plotnik_core::Interner::new();
+    let mut strings = StringTableBuilder::new();
+
+    builder
+        .build(&type_ctx, &interner, &mut strings)
+        .expect("build");
+
+    // Builtins should be mapped
+    assert_eq!(builder.get(TYPE_VOID), Some(QTypeId::VOID));
+    assert_eq!(builder.get(TYPE_NODE), Some(QTypeId::NODE));
+    assert_eq!(builder.get(TYPE_STRING), Some(QTypeId::STRING));
+}
+
+// Anchor bytecode emission tests
+
+#[test]
+fn emit_anchor_between_siblings() {
+    // Anchor between two named nodes should generate NextSkip
+    let input = "Test = (parent (a) . (b))";
+
+    let res = Query::expect_valid_bytecode(input);
+
+    insta::assert_snapshot!(res, @r#"
+    [header]
+    linked = false
+
+    [strings]
+    S00 "Beauty will save the world"
+    S01 "Test"
+    S02 "parent"
+    S03 "b"
+    S04 "a"
+
+    [types.defs]
+    T00 = void
+    T01 = Node
+    T02 = str
+    T03 = Struct(M0, 0)  ; {  }
+
+    [types.members]
+
+    [types.names]
+    N0 = (S01, T03)  ; Test
+
+    [entry]
+    Test = 01 :: T03
+
+    [code]
+      00   𝜀                                    ◼
+
+    Test:
+      01   𝜀                                    02
+      02  *↓   (parent)                         03
+      03  *↓   (a)                              04
+      04  ~    (b)                              05
+      05  *↑¹                                   ◼
+    "#);
+}
+
+#[test]
+fn emit_anchor_first_child() {
+    // Leading anchor should generate DownSkip
+    let input = "Test = (parent . (first))";
+
+    let res = Query::expect_valid_bytecode(input);
+
+    insta::assert_snapshot!(res, @r#"
+    [header]
+    linked = false
+
+    [strings]
+    S00 "Beauty will save the world"
+    S01 "Test"
+    S02 "parent"
+    S03 "first"
+
+    [types.defs]
+    T00 = void
+    T01 = Node
+    T02 = str
+    T03 = Struct(M0, 0)  ; {  }
+
+    [types.members]
+
+    [types.names]
+    N0 = (S01, T03)  ; Test
+
+    [entry]
+    Test = 01 :: T03
+
+    [code]
+      00   𝜀                                    ◼
+
+    Test:
+      01   𝜀                                    02
+      02  *↓   (parent)                         03
+      03  ~↓   (first)                          04
+      04  *↑¹                                   ◼
+    "#);
+}
+
+#[test]
+fn emit_anchor_last_child() {
+    // Trailing anchor should generate UpSkipTrivia
+    let input = "Test = (parent (last) .)";
+
+    let res = Query::expect_valid_bytecode(input);
+
+    insta::assert_snapshot!(res, @r#"
+    [header]
+    linked = false
+
+    [strings]
+    S00 "Beauty will save the world"
+    S01 "Test"
+    S02 "parent"
+    S03 "last"
+
+    [types.defs]
+    T00 = void
+    T01 = Node
+    T02 = str
+    T03 = Struct(M0, 0)  ; {  }
+
+    [types.members]
+
+    [types.names]
+    N0 = (S01, T03)  ; Test
+
+    [entry]
+    Test = 01 :: T03
+
+    [code]
+      00   𝜀                                    ◼
+
+    Test:
+      01   𝜀                                    02
+      02  *↓   (parent)                         03
+      03  *↓   (last)                           04
+      04  ~↑¹                                   ◼
+    "#);
+}
+
+#[test]
+fn emit_anchor_with_anonymous_node() {
+    // Anchor with anonymous node should generate NextExact
+    let input = r#"Test = (parent "+" . (next))"#;
+
+    let res = Query::expect_valid_bytecode(input);
+
+    insta::assert_snapshot!(res, @r#"
+    [header]
+    linked = false
+
+    [strings]
+    S00 "Beauty will save the world"
+    S01 "Test"
+    S02 "parent"
+    S03 "next"
+    S04 "+"
+
+    [types.defs]
+    T00 = void
+    T01 = Node
+    T02 = str
+    T03 = Struct(M0, 0)  ; {  }
+
+    [types.members]
+
+    [types.names]
+    N0 = (S01, T03)  ; Test
+
+    [entry]
+    Test = 01 :: T03
+
+    [code]
+      00   𝜀                                    ◼
+
+    Test:
+      01   𝜀                                    02
+      02  *↓   (parent)                         03
+      03  *↓   (+)                              04
+      04  .    (next)                           05
+      05  *↑¹                                   ◼
+    "#);
+}
+
+#[test]
+fn emit_no_anchor_uses_next() {
+    // No anchor between siblings uses Next
+    let input = "Test = (parent (a) (b))";
+
+    let res = Query::expect_valid_bytecode(input);
+
+    insta::assert_snapshot!(res, @r#"
+    [header]
+    linked = false
+
+    [strings]
+    S00 "Beauty will save the world"
+    S01 "Test"
+    S02 "parent"
+    S03 "b"
+    S04 "a"
+
+    [types.defs]
+    T00 = void
+    T01 = Node
+    T02 = str
+    T03 = Struct(M0, 0)  ; {  }
+
+    [types.members]
+
+    [types.names]
+    N0 = (S01, T03)  ; Test
+
+    [entry]
+    Test = 01 :: T03
+
+    [code]
+      00   𝜀                                    ◼
+
+    Test:
+      01   𝜀                                    02
+      02  *↓   (parent)                         03
+      03  *↓   (a)                              04
+      04  *    (b)                              05
+      05  *↑¹                                   ◼
+    "#);
+}
diff --git a/crates/plotnik-lib/src/query/compile.rs b/crates/plotnik-lib/src/query/compile.rs
new file mode 100644
index 00000000..a99fe385
--- /dev/null
+++ b/crates/plotnik-lib/src/query/compile.rs
@@ -0,0 +1,1247 @@
+//! Thompson-like NFA construction for query compilation.
+//!
+//! Compiles query AST expressions into bytecode IR with symbolic labels.
+//! Labels are resolved to concrete StepIds during the layout phase.
+
+use std::num::NonZeroU16;
+
+use indexmap::IndexMap;
+use plotnik_core::{Interner, NodeFieldId, NodeTypeId, Symbol};
+
+use crate::bytecode::ir::{CallIR, Instruction, Label, MatchIR, ReturnIR};
+use crate::bytecode::{EffectOp, EffectOpcode, Nav};
+use crate::parser::ast::{self, Expr, SeqItem};
+use crate::parser::cst::SyntaxKind;
+
+use super::codegen::StringTableBuilder;
+use super::symbol_table::SymbolTable;
+use super::type_check::{Arity, DefId, TypeContext, TypeShape};
+
+/// Error during compilation.
+#[derive(Clone, Debug)]
+pub enum CompileError {
+    /// Definition not found in symbol table.
+    DefinitionNotFound(String),
+    /// Expression body missing.
+    MissingBody(String),
+}
+
+impl std::fmt::Display for CompileError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::DefinitionNotFound(name) => write!(f, "definition not found: {name}"),
+            Self::MissingBody(name) => write!(f, "missing body for definition: {name}"),
+        }
+    }
+}
+
+impl std::error::Error for CompileError {}
+
+/// Result of compilation.
+#[derive(Clone, Debug)]
+pub struct CompileResult {
+    /// All generated instructions.
+    pub instructions: Vec<Instruction>,
+    /// Entry labels for each definition (in definition order).
+    pub def_entries: IndexMap<DefId, Label>,
+}
+
+/// Compiler state for Thompson construction.
+pub struct Compiler<'a> {
+    interner: &'a Interner,
+    type_ctx: &'a TypeContext,
+    symbol_table: &'a SymbolTable,
+    strings: &'a mut StringTableBuilder,
+    node_type_ids: Option<&'a IndexMap<Symbol, NodeTypeId>>,
+    node_field_ids: Option<&'a IndexMap<Symbol, NodeFieldId>>,
+    instructions: Vec<Instruction>,
+    next_label_id: u32,
+    def_entries: IndexMap<DefId, Label>,
+    ref_id_counter: u16,
+    /// Currently compiling definition (for member index lookup).
+    current_def_id: Option<DefId>,
+}
+
+impl<'a> Compiler<'a> {
+    /// Create a new compiler.
+    pub fn new(
+        interner: &'a Interner,
+        type_ctx: &'a TypeContext,
+        symbol_table: &'a SymbolTable,
+        strings: &'a mut StringTableBuilder,
+        node_type_ids: Option<&'a IndexMap<Symbol, NodeTypeId>>,
+        node_field_ids: Option<&'a IndexMap<Symbol, NodeFieldId>>,
+    ) -> Self {
+        Self {
+            interner,
+            type_ctx,
+            symbol_table,
+            strings,
+            node_type_ids,
+            node_field_ids,
+            instructions: Vec::new(),
+            next_label_id: 0,
+            def_entries: IndexMap::new(),
+            ref_id_counter: 0,
+            current_def_id: None,
+        }
+    }
+
+    /// Compile all definitions in the query.
+    pub fn compile(
+        interner: &'a Interner,
+        type_ctx: &'a TypeContext,
+        symbol_table: &'a SymbolTable,
+        strings: &'a mut StringTableBuilder,
+        node_type_ids: Option<&'a IndexMap<Symbol, NodeTypeId>>,
+        node_field_ids: Option<&'a IndexMap<Symbol, NodeFieldId>>,
+    ) -> Result<CompileResult, CompileError> {
+        let mut compiler = Self::new(interner, type_ctx, symbol_table, strings, node_type_ids, node_field_ids);
+
+        // Pre-allocate entry labels for all definitions
+        for (def_id, _) in type_ctx.iter_def_types() {
+            let label = compiler.fresh_label();
+            compiler.def_entries.insert(def_id, label);
+        }
+
+        // Compile each definition
+        for (def_id, _) in type_ctx.iter_def_types() {
+            compiler.compile_def(def_id)?;
+        }
+
+        Ok(CompileResult {
+            instructions: compiler.instructions,
+            def_entries: compiler.def_entries,
+        })
+    }
+
+    /// Generate a fresh label.
+    fn fresh_label(&mut self) -> Label {
+        let l = Label(self.next_label_id);
+        self.next_label_id += 1;
+        l
+    }
+
+    /// Generate a fresh ref_id for Call/Return verification.
+    fn fresh_ref_id(&mut self) -> u16 {
+        let id = self.ref_id_counter;
+        self.ref_id_counter += 1;
+        id
+    }
+
+    /// Compile a single definition.
+    fn compile_def(&mut self, def_id: DefId) -> Result<(), CompileError> {
+        let name_sym = self.type_ctx.def_name_sym(def_id);
+        let name = self.interner.resolve(name_sym);
+
+        let Some(body) = self.symbol_table.get(name) else {
+            return Err(CompileError::DefinitionNotFound(name.to_string()));
+        };
+
+        let entry_label = self.def_entries[&def_id];
+
+        // Track current definition for member index lookup
+        self.current_def_id = Some(def_id);
+
+        // Compile body, targeting accept state
+        let body_entry = self.compile_expr(body, Label::ACCEPT);
+
+        // If body_entry differs from our pre-allocated entry, emit an epsilon jump
+        if body_entry != entry_label {
+            self.emit_epsilon(entry_label, vec![body_entry]);
+        }
+
+        self.current_def_id = None;
+        Ok(())
+    }
+
+    /// Compile an expression, returning its entry label.
+    fn compile_expr(&mut self, expr: &Expr, exit: Label) -> Label {
+        match expr {
+            Expr::NamedNode(n) => self.compile_named_node(n, exit),
+            Expr::AnonymousNode(n) => self.compile_anonymous_node(n, exit),
+            Expr::Ref(r) => self.compile_ref(r, exit),
+            Expr::SeqExpr(s) => self.compile_seq(s, exit),
+            Expr::AltExpr(a) => self.compile_alt(a, exit),
+            Expr::QuantifiedExpr(q) => self.compile_quantified(q, exit),
+            Expr::FieldExpr(f) => self.compile_field(f, exit),
+            Expr::CapturedExpr(c) => self.compile_captured(c, exit),
+        }
+    }
+
+    /// Compile a named node: `(identifier)` or `(call_expression arg: ...)`.
+    fn compile_named_node(&mut self, node: &ast::NamedNode, exit: Label) -> Label {
+        self.compile_named_node_with_nav(node, exit, None)
+    }
+
+    /// Check if an expression is anonymous (string literal or wildcard).
+    fn expr_is_anonymous(&self, expr: Option<&Expr>) -> bool {
+        matches!(expr, Some(Expr::AnonymousNode(_)))
+    }
+
+    /// Check for trailing anchor in items, looking inside sequences if needed.
+    /// Returns (has_trailing_anchor, is_strict).
+    fn check_trailing_anchor(&self, items: &[SeqItem]) -> (bool, bool) {
+        // Direct trailing anchor
+        if matches!(items.last(), Some(SeqItem::Anchor(_))) {
+            let prev_expr = items.iter().rev().skip(1).find_map(|item| {
+                if let SeqItem::Expr(e) = item { Some(e) } else { None }
+            });
+            return (true, self.expr_is_anonymous(prev_expr));
+        }
+
+        // Check if only child is a sequence with trailing anchor
+        if items.len() == 1
+            && let Some(SeqItem::Expr(Expr::SeqExpr(seq))) = items.first()
+        {
+            let seq_items: Vec<_> = seq.items().collect();
+            return self.check_trailing_anchor(&seq_items);
+        }
+
+        (false, false)
+    }
+
+    /// Compile sequence items (expressions and anchors).
+    ///
+    /// Handles anchor semantics:
+    /// - First child uses Down, subsequent use Next
+    /// - Anchors determine strictness (Skip vs Exact)
+    /// - Leading anchors affect first child navigation
+    /// - Trailing anchors affect Up instruction (handled by caller)
+    fn compile_seq_items(&mut self, items: &[SeqItem], exit: Label, is_inside_node: bool) -> Label {
+        self.compile_seq_items_with_first_nav(items, exit, is_inside_node, None)
+    }
+
+    /// Compile sequence items with optional external nav override for first item.
+    fn compile_seq_items_with_first_nav(
+        &mut self,
+        items: &[SeqItem],
+        exit: Label,
+        is_inside_node: bool,
+        first_nav: Option<Nav>,
+    ) -> Label {
+        // Compute navigation modes first (immutable borrow)
+        let mut nav_modes = Self::compute_nav_modes(items, is_inside_node);
+
+        if nav_modes.is_empty() {
+            return exit;
+        }
+
+        // Apply navigation to first expression:
+        // 1. External nav (first_nav) takes precedence if provided
+        // 2. If no external nav but inside node, default to Down
+        // 3. Internal anchors (already computed) override these defaults
+        if let Some((_, first_mode)) = nav_modes.first_mut()
+            && first_mode.is_none()
+        {
+            *first_mode = first_nav.or_else(|| is_inside_node.then_some(Nav::Down));
+        }
+
+        // Build chain in reverse: last expression exits to `exit`, each prior exits to next
+        let mut current_exit = exit;
+        for (expr_idx, nav_override) in nav_modes.into_iter().rev() {
+            let expr = items[expr_idx].as_expr().expect("nav_modes only contains expr indices");
+            current_exit = self.compile_expr_with_nav(expr, current_exit, nav_override);
+        }
+        current_exit
+    }
+
+    /// Compute navigation modes for each expression based on anchor context.
+    /// Returns a vector of (expression index, nav mode) pairs.
+    fn compute_nav_modes(items: &[SeqItem], is_inside_node: bool) -> Vec<(usize, Option<Nav>)> {
+        let mut result = Vec::new();
+        let mut pending_anchor = false;
+        let mut prev_is_anonymous = false;
+        let mut is_first_expr = true;
+
+        for (idx, item) in items.iter().enumerate() {
+            match item {
+                SeqItem::Anchor(_) => {
+                    pending_anchor = true;
+                }
+                SeqItem::Expr(expr) => {
+                    let current_is_anonymous = matches!(expr, Expr::AnonymousNode(_));
+                    let nav = if pending_anchor {
+                        // Anchor between previous item and this one
+                        let is_exact = prev_is_anonymous || current_is_anonymous;
+                        if is_first_expr && is_inside_node {
+                            // First child with leading anchor
+                            Some(if is_exact { Nav::DownExact } else { Nav::DownSkip })
+                        } else if !is_first_expr {
+                            // Sibling with anchor
+                            Some(if is_exact { Nav::NextExact } else { Nav::NextSkip })
+                        } else {
+                            // First in sequence (not inside node)
+                            None
+                        }
+                    } else if !is_first_expr {
+                        // Normal sibling navigation (no anchor)
+                        Some(Nav::Next)
+                    } else {
+                        // First expression - use default (None for sequences, Down for nodes)
+                        None
+                    };
+
+                    result.push((idx, nav));
+                    pending_anchor = false;
+                    prev_is_anonymous = current_is_anonymous;
+                    is_first_expr = false;
+                }
+            }
+        }
+
+        result
+    }
+
+    /// Compile an expression with an optional navigation override.
+    fn compile_expr_with_nav(&mut self, expr: &Expr, exit: Label, nav_override: Option<Nav>) -> Label {
+        match expr {
+            // For expressions that emit their own Match instructions,
+            // we need to modify the navigation mode
+            Expr::NamedNode(n) => self.compile_named_node_with_nav(n, exit, nav_override),
+            Expr::AnonymousNode(n) => self.compile_anonymous_node_with_nav(n, exit, nav_override),
+            // For sequences and alternations, propagate nav to first item(s)
+            Expr::SeqExpr(s) => self.compile_seq_with_nav(s, exit, nav_override),
+            Expr::AltExpr(a) => self.compile_alt_with_nav(a, exit, nav_override),
+            // For wrapper expressions, propagate nav to inner expression
+            Expr::CapturedExpr(c) => self.compile_captured_with_nav(c, exit, nav_override),
+            Expr::QuantifiedExpr(q) => self.compile_quantified_with_nav(q, exit, nav_override),
+            Expr::FieldExpr(f) => self.compile_field_with_nav(f, exit, nav_override),
+            Expr::Ref(r) => self.compile_ref_with_nav(r, exit, nav_override),
+        }
+    }
+
+    /// Compile a named node: `(identifier)` or `(call_expression arg: ...)`.
+    ///
+    /// If `nav_override` is provided, uses that navigation instead of the default `Down`.
+    fn compile_named_node_with_nav(&mut self, node: &ast::NamedNode, exit: Label, nav_override: Option<Nav>) -> Label {
+        let entry = self.fresh_label();
+        let node_type = self.resolve_node_type(node);
+        let nav = nav_override.unwrap_or(Nav::Down);
+
+        // Collect items and negated fields
+        let items: Vec<_> = node.items().collect();
+        let neg_fields = self.collect_neg_fields(node);
+
+        // If no items, just match and exit
+        if items.is_empty() {
+            self.instructions.push(Instruction::Match(MatchIR {
+                label: entry,
+                nav,
+                node_type,
+                node_field: None,
+                pre_effects: vec![],
+                neg_fields,
+                post_effects: vec![],
+                successors: vec![exit],
+            }));
+            return entry;
+        }
+
+        // Determine Up navigation based on trailing anchor
+        let (has_trailing_anchor, trailing_strictness) = self.check_trailing_anchor(&items);
+
+        // With items: nav → items → Up → exit
+        let up_label = self.fresh_label();
+        let items_entry = self.compile_seq_items(&items, up_label, true);
+
+        // Emit Up instruction with appropriate strictness
+        let up_nav = if has_trailing_anchor {
+            if trailing_strictness {
+                Nav::UpExact(1)
+            } else {
+                Nav::UpSkipTrivia(1)
+            }
+        } else {
+            Nav::Up(1)
+        };
+        self.instructions.push(Instruction::Match(MatchIR {
+            label: up_label,
+            nav: up_nav,
+            node_type: None,
+            node_field: None,
+            pre_effects: vec![],
+            neg_fields: vec![],
+            post_effects: vec![],
+            successors: vec![exit],
+        }));
+
+        // Emit entry instruction into the node
+        self.instructions.push(Instruction::Match(MatchIR {
+            label: entry,
+            nav,
+            node_type,
+            node_field: None,
+            pre_effects: vec![],
+            neg_fields,
+            post_effects: vec![],
+            successors: vec![items_entry],
+        }));
+
+        entry
+    }
+
+    /// Compile an anonymous node: `"+"` or `_`.
+    ///
+    /// If `nav_override` is provided, uses that navigation instead of the default `Next`.
+    fn compile_anonymous_node_with_nav(&mut self, node: &ast::AnonymousNode, exit: Label, nav_override: Option<Nav>) -> Label {
+        let entry = self.fresh_label();
+        let nav = nav_override.unwrap_or(Nav::Next);
+
+        // Extract literal value (None for wildcard `_`)
+        let node_type = node.value().and_then(|token| {
+            let text = token.text();
+            self.resolve_anonymous_node_type(text)
+        });
+
+        self.instructions.push(Instruction::Match(MatchIR {
+            label: entry,
+            nav,
+            node_type,
+            node_field: None,
+            pre_effects: vec![],
+            neg_fields: vec![],
+            post_effects: vec![],
+            successors: vec![exit],
+        }));
+
+        entry
+    }
+
+    /// Compile an anonymous node: `"+"` or `_`.
+    fn compile_anonymous_node(&mut self, node: &ast::AnonymousNode, exit: Label) -> Label {
+        self.compile_anonymous_node_with_nav(node, exit, None)
+    }
+
+    /// Compile a reference: `(Expr)`.
+    fn compile_ref(&mut self, r: &ast::Ref, exit: Label) -> Label {
+        self.compile_ref_with_nav(r, exit, None)
+    }
+
+    /// Compile a reference with optional navigation override.
+    fn compile_ref_with_nav(&mut self, r: &ast::Ref, exit: Label, _nav_override: Option<Nav>) -> Label {
+        let Some(name_token) = r.name() else {
+            return exit;
+        };
+        let name = name_token.text();
+
+        let Some(sym) = self.type_ctx.get_def_id(self.interner, name) else {
+            return exit;
+        };
+
+        let Some(&target) = self.def_entries.get(&sym) else {
+            return exit;
+        };
+
+        // Check if this is a recursive reference
+        // Note: nav_override is not propagated here because the referenced
+        // definition has its own navigation semantics
+        if self.type_ctx.is_recursive(sym) {
+            // Emit Call instruction
+            let call_label = self.fresh_label();
+            let ref_id = self.fresh_ref_id();
+
+            self.instructions.push(Instruction::Call(CallIR {
+                label: call_label,
+                next: exit,
+                target,
+                ref_id,
+            }));
+
+            // Emit Return at the callee's exit
+            let return_label = self.fresh_label();
+            self.instructions.push(Instruction::Return(ReturnIR {
+                label: return_label,
+                ref_id,
+            }));
+
+            call_label
+        } else {
+            // Non-recursive: inline the body
+            // For simplicity, just jump to the target
+            target
+        }
+    }
+
+    /// Compile a sequence: `{a b c}`.
+    fn compile_seq(&mut self, seq: &ast::SeqExpr, exit: Label) -> Label {
+        self.compile_seq_with_nav(seq, exit, None)
+    }
+
+    /// Compile a sequence with optional navigation override for first item.
+    fn compile_seq_with_nav(&mut self, seq: &ast::SeqExpr, exit: Label, first_nav: Option<Nav>) -> Label {
+        let items: Vec<_> = seq.items().collect();
+        if items.is_empty() {
+            return exit;
+        }
+
+        // Determine if we're inside a node based on the navigation override
+        // Down variants mean we're descending into a node's children
+        let is_inside_node = matches!(first_nav, Some(Nav::Down | Nav::DownSkip | Nav::DownExact));
+
+        self.compile_seq_items_with_first_nav(&items, exit, is_inside_node, first_nav)
+    }
+
+    /// Compile an alternation: `[a b c]`.
+    fn compile_alt(&mut self, alt: &ast::AltExpr, exit: Label) -> Label {
+        self.compile_alt_with_nav(alt, exit, None)
+    }
+
+    /// Compile an alternation with optional navigation override for all branches.
+    fn compile_alt_with_nav(&mut self, alt: &ast::AltExpr, exit: Label, first_nav: Option<Nav>) -> Label {
+        let branches: Vec<_> = alt.branches().collect();
+        if branches.is_empty() {
+            return exit;
+        }
+
+        // Check if this is a tagged alternation (Enum type)
+        let alt_expr = Expr::AltExpr(alt.clone());
+        let is_enum = self
+            .type_ctx
+            .get_term_info(&alt_expr)
+            .and_then(|info| info.flow.type_id())
+            .and_then(|type_id| self.type_ctx.get_type(type_id))
+            .is_some_and(|shape| matches!(shape, TypeShape::Enum(_)));
+
+        // Compile each branch, collecting entry labels
+        // Each branch gets the same nav override since any branch could match first
+        let mut successors = Vec::new();
+        for (variant_idx, branch) in branches.iter().enumerate() {
+            let Some(body) = branch.body() else {
+                continue;
+            };
+
+            if is_enum {
+                // Tagged branch: E(variant_idx) → body → EndE → exit
+                let ende_step = self.fresh_label();
+                self.instructions.push(Instruction::Match(MatchIR {
+                    label: ende_step,
+                    nav: Nav::Stay,
+                    node_type: None,
+                    node_field: None,
+                    pre_effects: vec![],
+                    neg_fields: vec![],
+                    post_effects: vec![EffectOp {
+                        opcode: EffectOpcode::EndE,
+                        payload: 0,
+                    }],
+                    successors: vec![exit],
+                }));
+
+                let body_entry = self.compile_expr_with_nav(&body, ende_step, first_nav);
+
+                let e_step = self.fresh_label();
+                self.instructions.push(Instruction::Match(MatchIR {
+                    label: e_step,
+                    nav: Nav::Stay,
+                    node_type: None,
+                    node_field: None,
+                    pre_effects: vec![EffectOp {
+                        opcode: EffectOpcode::E,
+                        payload: variant_idx,
+                    }],
+                    neg_fields: vec![],
+                    post_effects: vec![],
+                    successors: vec![body_entry],
+                }));
+
+                successors.push(e_step);
+            } else {
+                // Untagged branch: direct compilation
+                let branch_entry = self.compile_expr_with_nav(&body, exit, first_nav);
+                successors.push(branch_entry);
+            }
+        }
+
+        if successors.is_empty() {
+            return exit;
+        }
+        if successors.len() == 1 {
+            return successors[0];
+        }
+
+        // Emit epsilon branch to choose among alternatives
+        let entry = self.fresh_label();
+        self.emit_epsilon(entry, successors);
+        entry
+    }
+
+    /// Compile a quantified expression: `a?`, `a*`, `a+`.
+    fn compile_quantified(&mut self, quant: &ast::QuantifiedExpr, exit: Label) -> Label {
+        self.compile_quantified_with_nav(quant, exit, None)
+    }
+
+    /// Compile a quantified expression with optional navigation override.
+    fn compile_quantified_with_nav(
+        &mut self,
+        quant: &ast::QuantifiedExpr,
+        exit: Label,
+        nav_override: Option<Nav>,
+    ) -> Label {
+        let Some(inner) = quant.inner() else {
+            return exit;
+        };
+
+        let Some(op) = quant.operator() else {
+            return self.compile_expr_with_nav(&inner, exit, nav_override);
+        };
+
+        let is_plus = matches!(op.kind(), SyntaxKind::Plus | SyntaxKind::PlusQuestion);
+        let is_star = matches!(op.kind(), SyntaxKind::Star | SyntaxKind::StarQuestion);
+        let is_greedy = matches!(
+            op.kind(),
+            SyntaxKind::Question | SyntaxKind::Star | SyntaxKind::Plus
+        );
+
+        if is_plus {
+            // +: body → loop_entry → [body, exit]
+            // First iteration uses nav_override, subsequent use default
+            let loop_entry = self.fresh_label();
+            let first_body_entry = self.compile_expr_with_nav(&inner, loop_entry, nav_override);
+            let repeat_body_entry = self.compile_expr(&inner, loop_entry);
+
+            let successors = if is_greedy {
+                vec![repeat_body_entry, exit]
+            } else {
+                vec![exit, repeat_body_entry]
+            };
+            self.emit_epsilon(loop_entry, successors);
+
+            first_body_entry
+        } else if is_star {
+            // *: loop_entry → [body → loop_entry, exit]
+            // First iteration uses nav_override, subsequent use default
+            let loop_entry = self.fresh_label();
+            let first_body_entry = self.compile_expr_with_nav(&inner, loop_entry, nav_override);
+            let repeat_body_entry = self.compile_expr(&inner, loop_entry);
+
+            // Entry point branches: first iteration or exit
+            let entry = self.fresh_label();
+            let successors = if is_greedy {
+                vec![first_body_entry, exit]
+            } else {
+                vec![exit, first_body_entry]
+            };
+            self.emit_epsilon(entry, successors);
+
+            // Loop point branches: repeat iteration or exit
+            let loop_successors = if is_greedy {
+                vec![repeat_body_entry, exit]
+            } else {
+                vec![exit, repeat_body_entry]
+            };
+            self.emit_epsilon(loop_entry, loop_successors);
+
+            entry
+        } else {
+            // ?: branch to body or exit
+            let body_entry = self.compile_expr_with_nav(&inner, exit, nav_override);
+            let entry = self.fresh_label();
+
+            let successors = if is_greedy {
+                vec![body_entry, exit]
+            } else {
+                vec![exit, body_entry]
+            };
+            self.emit_epsilon(entry, successors);
+
+            entry
+        }
+    }
+
+    /// Compile a field constraint: `name: pattern`.
+    fn compile_field(&mut self, field: &ast::FieldExpr, exit: Label) -> Label {
+        self.compile_field_with_nav(field, exit, None)
+    }
+
+    /// Compile a field constraint with optional navigation override.
+    fn compile_field_with_nav(
+        &mut self,
+        field: &ast::FieldExpr,
+        exit: Label,
+        nav_override: Option<Nav>,
+    ) -> Label {
+        let Some(value) = field.value() else {
+            return exit;
+        };
+
+        let node_field = self.resolve_field(field);
+
+        // Compile the value pattern with nav override
+        let value_entry = self.compile_expr_with_nav(&value, exit, nav_override);
+
+        // If we have a field constraint, wrap with a field-checking Match
+        if node_field.is_some() {
+            let entry = self.fresh_label();
+            self.instructions.push(Instruction::Match(MatchIR {
+                label: entry,
+                nav: Nav::Stay, // Check field without moving
+                node_type: None,
+                node_field,
+                pre_effects: vec![],
+                neg_fields: vec![],
+                post_effects: vec![],
+                successors: vec![value_entry],
+            }));
+            return entry;
+        }
+
+        value_entry
+    }
+
+    /// Compile a captured expression: `@name` or `pattern @name`.
+    fn compile_captured(&mut self, cap: &ast::CapturedExpr, exit: Label) -> Label {
+        self.compile_captured_with_nav(cap, exit, None)
+    }
+
+    /// Compile a captured expression with optional navigation override.
+    ///
+    /// Effects are emitted AFTER the inner pattern matches, not before.
+    /// Flow depends on captured type:
+    /// - Scalar: inner_pattern → [Node/Text, Set] → exit
+    /// - Struct: S → inner_pattern → [EndS, Node/Text, Set] → exit
+    /// - Array:  A → quantifier (with Push) → [EndA, Node/Text, Set] → exit
+    fn compile_captured_with_nav(
+        &mut self,
+        cap: &ast::CapturedExpr,
+        exit: Label,
+        nav_override: Option<Nav>,
+    ) -> Label {
+        // Determine effects based on capture type
+        let is_text = cap.type_annotation().is_some_and(|t| {
+            t.name().map(|n| n.text() == "string").unwrap_or(false)
+        });
+
+        // Build capture effects: Node/Text followed by Set(member_index)
+        let mut capture_effects = Vec::with_capacity(2);
+
+        let capture_effect = if is_text {
+            EffectOp { opcode: EffectOpcode::Text, payload: 0 }
+        } else {
+            EffectOp { opcode: EffectOpcode::Node, payload: 0 }
+        };
+        capture_effects.push(capture_effect);
+
+        // Add Set effect if we can resolve the member index
+        if let Some(name_token) = cap.name()
+            && let Some(member_idx) = self.lookup_member_index(name_token.text())
+        {
+            capture_effects.push(EffectOp {
+                opcode: EffectOpcode::Set,
+                payload: member_idx as usize,
+            });
+        }
+
+        // Query type system to determine structural effects needed
+        // - S/EndS: Check if INNER's flow is Bubble (has fields to collect)
+        // - A/Push/EndA: Check if INNER's arity is Many (star/plus quantifier)
+        let inner = cap.inner();
+        let inner_info = inner.as_ref().and_then(|inner| self.type_ctx.get_term_info(inner));
+        let inner_is_bubble = inner_info.map(|info| info.flow.is_bubble()).unwrap_or(false);
+
+        // Check for Many arity (star/plus) - use type system if available, else syntactic check
+        let inner_is_many = inner_info
+            .map(|info| matches!(info.arity, Arity::Many))
+            .unwrap_or_else(|| {
+                // Fallback: check syntactically for star/plus
+                inner.as_ref().is_some_and(|inner| {
+                    if let Expr::QuantifiedExpr(q) = inner {
+                        q.operator().is_some_and(|op| {
+                            matches!(
+                                op.kind(),
+                                SyntaxKind::Star | SyntaxKind::StarQuestion | SyntaxKind::Plus | SyntaxKind::PlusQuestion
+                            )
+                        })
+                    } else {
+                        false
+                    }
+                })
+            });
+
+        if let Some(inner) = cap.inner() {
+            // Pattern with capture: effects fire AFTER inner matches
+            let effect_label = self.fresh_label();
+
+            if inner_is_bubble {
+                // Struct scope: S → inner → EndS + capture_effects → exit
+                let mut post_effects = vec![EffectOp {
+                    opcode: EffectOpcode::EndS,
+                    payload: 0,
+                }];
+                post_effects.extend(capture_effects);
+
+                self.instructions.push(Instruction::Match(MatchIR {
+                    label: effect_label,
+                    nav: Nav::Stay,
+                    node_type: None,
+                    node_field: None,
+                    pre_effects: vec![],
+                    neg_fields: vec![],
+                    post_effects,
+                    successors: vec![exit],
+                }));
+
+                let inner_entry = self.compile_expr_with_nav(&inner, effect_label, nav_override);
+
+                // S step before inner
+                let s_step = self.fresh_label();
+                self.instructions.push(Instruction::Match(MatchIR {
+                    label: s_step,
+                    nav: Nav::Stay,
+                    node_type: None,
+                    node_field: None,
+                    pre_effects: vec![EffectOp {
+                        opcode: EffectOpcode::S,
+                        payload: 0,
+                    }],
+                    neg_fields: vec![],
+                    post_effects: vec![],
+                    successors: vec![inner_entry],
+                }));
+
+                s_step
+            } else if inner_is_many {
+                // Array: A → quantifier (with Push) → EndA + capture_effects → exit
+                let mut post_effects = vec![EffectOp {
+                    opcode: EffectOpcode::EndA,
+                    payload: 0,
+                }];
+                post_effects.extend(capture_effects);
+
+                self.instructions.push(Instruction::Match(MatchIR {
+                    label: effect_label,
+                    nav: Nav::Stay,
+                    node_type: None,
+                    node_field: None,
+                    pre_effects: vec![],
+                    neg_fields: vec![],
+                    post_effects,
+                    successors: vec![exit],
+                }));
+
+                // Compile quantifier with Push effects
+                let inner_entry = if let Expr::QuantifiedExpr(quant) = &inner {
+                    self.compile_quantified_for_array(quant, effect_label, nav_override)
+                } else {
+                    self.compile_expr_with_nav(&inner, effect_label, nav_override)
+                };
+
+                // A step before inner
+                let a_step = self.fresh_label();
+                self.instructions.push(Instruction::Match(MatchIR {
+                    label: a_step,
+                    nav: Nav::Stay,
+                    node_type: None,
+                    node_field: None,
+                    pre_effects: vec![EffectOp {
+                        opcode: EffectOpcode::A,
+                        payload: 0,
+                    }],
+                    neg_fields: vec![],
+                    post_effects: vec![],
+                    successors: vec![inner_entry],
+                }));
+
+                a_step
+            } else {
+                // Scalar: just capture effects
+                self.instructions.push(Instruction::Match(MatchIR {
+                    label: effect_label,
+                    nav: Nav::Stay,
+                    node_type: None,
+                    node_field: None,
+                    pre_effects: vec![],
+                    neg_fields: vec![],
+                    post_effects: capture_effects,
+                    successors: vec![exit],
+                }));
+
+                self.compile_expr_with_nav(&inner, effect_label, nav_override)
+            }
+        } else {
+            // Bare capture: just emit effects at current position
+            let entry = self.fresh_label();
+            self.instructions.push(Instruction::Match(MatchIR {
+                label: entry,
+                nav: Nav::Stay,
+                node_type: None,
+                node_field: None,
+                pre_effects: vec![],
+                neg_fields: vec![],
+                post_effects: capture_effects,
+                successors: vec![exit],
+            }));
+            entry
+        }
+    }
+
+    /// Compile a quantified expression for array capture, adding Push after each iteration.
+    fn compile_quantified_for_array(
+        &mut self,
+        quant: &ast::QuantifiedExpr,
+        exit: Label,
+        nav_override: Option<Nav>,
+    ) -> Label {
+        let Some(inner) = quant.inner() else {
+            return exit;
+        };
+
+        let Some(op) = quant.operator() else {
+            return self.compile_expr_with_nav(&inner, exit, nav_override);
+        };
+
+        let is_plus = matches!(op.kind(), SyntaxKind::Plus | SyntaxKind::PlusQuestion);
+        let is_star = matches!(op.kind(), SyntaxKind::Star | SyntaxKind::StarQuestion);
+        let is_greedy = matches!(
+            op.kind(),
+            SyntaxKind::Question | SyntaxKind::Star | SyntaxKind::Plus
+        );
+
+        // Push step: fires after each iteration completes
+        let push_step = self.fresh_label();
+        self.instructions.push(Instruction::Match(MatchIR {
+            label: push_step,
+            nav: Nav::Stay,
+            node_type: None,
+            node_field: None,
+            pre_effects: vec![],
+            neg_fields: vec![],
+            post_effects: vec![EffectOp {
+                opcode: EffectOpcode::Push,
+                payload: 0,
+            }],
+            successors: vec![], // Will be set below
+        }));
+        let push_idx = self.instructions.len() - 1;
+
+        if is_plus {
+            // +: first_body → push → loop_entry → [repeat_body → push, exit]
+            let loop_entry = self.fresh_label();
+
+            // Bodies target push_step
+            let first_body_entry = self.compile_expr_with_nav(&inner, push_step, nav_override);
+            let repeat_body_entry = self.compile_expr(&inner, push_step);
+
+            // Push leads to loop_entry
+            if let Instruction::Match(ref mut m) = self.instructions[push_idx] {
+                m.successors = vec![loop_entry];
+            }
+
+            // Loop chooses between repeat and exit
+            let successors = if is_greedy {
+                vec![repeat_body_entry, exit]
+            } else {
+                vec![exit, repeat_body_entry]
+            };
+            self.emit_epsilon(loop_entry, successors);
+
+            first_body_entry
+        } else if is_star {
+            // *: entry → [first_body → push → loop_entry → [repeat_body → push, exit], exit]
+            let loop_entry = self.fresh_label();
+
+            // Bodies target push_step
+            let first_body_entry = self.compile_expr_with_nav(&inner, push_step, nav_override);
+            let repeat_body_entry = self.compile_expr(&inner, push_step);
+
+            // Push leads to loop_entry
+            if let Instruction::Match(ref mut m) = self.instructions[push_idx] {
+                m.successors = vec![loop_entry];
+            }
+
+            // Entry point branches: first iteration or exit
+            let entry = self.fresh_label();
+            let successors = if is_greedy {
+                vec![first_body_entry, exit]
+            } else {
+                vec![exit, first_body_entry]
+            };
+            self.emit_epsilon(entry, successors);
+
+            // Loop point branches: repeat iteration or exit
+            let loop_successors = if is_greedy {
+                vec![repeat_body_entry, exit]
+            } else {
+                vec![exit, repeat_body_entry]
+            };
+            self.emit_epsilon(loop_entry, loop_successors);
+
+            entry
+        } else {
+            // ?: branch to body or exit (no Push needed for optional)
+            let body_entry = self.compile_expr_with_nav(&inner, exit, nav_override);
+            let entry = self.fresh_label();
+
+            let successors = if is_greedy {
+                vec![body_entry, exit]
+            } else {
+                vec![exit, body_entry]
+            };
+            self.emit_epsilon(entry, successors);
+
+            entry
+        }
+    }
+
+    /// Emit an epsilon transition (no node interaction).
+    fn emit_epsilon(&mut self, label: Label, successors: Vec<Label>) {
+        self.instructions.push(Instruction::Match(MatchIR {
+            label,
+            nav: Nav::Stay,
+            node_type: None,
+            node_field: None,
+            pre_effects: vec![],
+            neg_fields: vec![],
+            post_effects: vec![],
+            successors,
+        }));
+    }
+
+    /// Resolve an anonymous node's literal text to its node type ID.
+    ///
+    /// In linked mode, returns the grammar NodeTypeId for the literal.
+    /// In unlinked mode, returns the StringId of the literal text.
+    fn resolve_anonymous_node_type(&mut self, text: &str) -> Option<NonZeroU16> {
+        if let Some(ids) = self.node_type_ids {
+            // Linked mode: resolve to NodeTypeId from grammar
+            for (&sym, &id) in ids {
+                if self.interner.resolve(sym) == text {
+                    return NonZeroU16::new(id.get());
+                }
+            }
+            // If not found in grammar, treat as no constraint
+            None
+        } else {
+            // Unlinked mode: store StringId referencing the literal text
+            let string_id = self.strings.intern_str(text);
+            NonZeroU16::new(string_id.0)
+        }
+    }
+
+    /// Resolve a NamedNode to its node type ID.
+    ///
+    /// In linked mode, returns the grammar NodeTypeId.
+    /// In unlinked mode, returns the StringId of the type name.
+    fn resolve_node_type(&mut self, node: &ast::NamedNode) -> Option<NonZeroU16> {
+        // For wildcard (_), no constraint
+        if node.is_any() {
+            return None;
+        }
+
+        let type_token = node.node_type()?;
+        let type_name = type_token.text();
+
+        if let Some(ids) = self.node_type_ids {
+            // Linked mode: resolve to NodeTypeId from grammar
+            for (&sym, &id) in ids {
+                if self.interner.resolve(sym) == type_name {
+                    return NonZeroU16::new(id.get());
+                }
+            }
+            // If not found in grammar, treat as no constraint (linked mode)
+            None
+        } else {
+            // Unlinked mode: store StringId referencing the type name
+            let string_id = self.strings.intern_str(type_name);
+            NonZeroU16::new(string_id.0)
+        }
+    }
+
+    /// Resolve a field expression to its field ID.
+    ///
+    /// In linked mode, returns the grammar NodeFieldId.
+    /// In unlinked mode, returns the StringId of the field name.
+    fn resolve_field(&mut self, field: &ast::FieldExpr) -> Option<NonZeroU16> {
+        let name_token = field.name()?;
+        let field_name = name_token.text();
+        self.resolve_field_by_name(field_name)
+    }
+
+    /// Resolve a field name to its field ID.
+    ///
+    /// In linked mode, returns the grammar NodeFieldId.
+    /// In unlinked mode, returns the StringId of the field name.
+    fn resolve_field_by_name(&mut self, field_name: &str) -> Option<NonZeroU16> {
+        if let Some(ids) = self.node_field_ids {
+            // Linked mode: resolve to NodeFieldId from grammar
+            for (&sym, &id) in ids {
+                if self.interner.resolve(sym) == field_name {
+                    return NonZeroU16::new(id.get());
+                }
+            }
+            // If not found in grammar, treat as no constraint (linked mode)
+            None
+        } else {
+            // Unlinked mode: store StringId referencing the field name
+            let string_id = self.strings.intern_str(field_name);
+            NonZeroU16::new(string_id.0)
+        }
+    }
+
+    /// Collect negated fields from a NamedNode.
+    fn collect_neg_fields(&mut self, node: &ast::NamedNode) -> Vec<u16> {
+        node.as_cst()
+            .children()
+            .filter_map(ast::NegatedField::cast)
+            .filter_map(|nf| {
+                let name = nf.name()?;
+                self.resolve_field_by_name(name.text())
+            })
+            .map(|id| id.get())
+            .collect()
+    }
+
+    /// Look up a capture name's member index in the current definition's type.
+    ///
+    /// Returns the position (0-based) of the field in the struct's BTreeMap order,
+    /// or None if not found or not in a struct context.
+    fn lookup_member_index(&self, capture_name: &str) -> Option<u16> {
+        let def_id = self.current_def_id?;
+        let type_id = self.type_ctx.get_def_type(def_id)?;
+        let fields = self.type_ctx.get_struct_fields(type_id)?;
+
+        // BTreeMap iterates in key order (Symbol order)
+        for (index, (&sym, _)) in fields.iter().enumerate() {
+            if self.interner.resolve(sym) == capture_name {
+                return Some(index as u16);
+            }
+        }
+        None
+    }
+
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::query::QueryBuilder;
+
+    #[test]
+    fn compile_simple_named_node() {
+        let query = QueryBuilder::one_liner("Test = (identifier)")
+            .parse()
+            .unwrap()
+            .analyze();
+
+        let mut strings = StringTableBuilder::new();
+        let result = Compiler::compile(
+            query.interner(),
+            query.type_context(),
+            &query.symbol_table,
+            &mut strings,
+            None,
+            None,
+        )
+        .unwrap();
+
+        // Should have at least one instruction
+        assert!(!result.instructions.is_empty());
+        // Should have one entrypoint
+        assert_eq!(result.def_entries.len(), 1);
+    }
+
+    #[test]
+    fn compile_alternation() {
+        let query = QueryBuilder::one_liner("Test = [(identifier) (number)]")
+            .parse()
+            .unwrap()
+            .analyze();
+
+        let mut strings = StringTableBuilder::new();
+        let result = Compiler::compile(
+            query.interner(),
+            query.type_context(),
+            &query.symbol_table,
+            &mut strings,
+            None,
+            None,
+        )
+        .unwrap();
+
+        assert!(!result.instructions.is_empty());
+    }
+
+    #[test]
+    fn compile_sequence() {
+        let query = QueryBuilder::one_liner("Test = {(comment) (function)}")
+            .parse()
+            .unwrap()
+            .analyze();
+
+        let mut strings = StringTableBuilder::new();
+        let result = Compiler::compile(
+            query.interner(),
+            query.type_context(),
+            &query.symbol_table,
+            &mut strings,
+            None,
+            None,
+        )
+        .unwrap();
+
+        assert!(!result.instructions.is_empty());
+    }
+
+    #[test]
+    fn compile_quantified() {
+        let query = QueryBuilder::one_liner("Test = (identifier)*")
+            .parse()
+            .unwrap()
+            .analyze();
+
+        let mut strings = StringTableBuilder::new();
+        let result = Compiler::compile(
+            query.interner(),
+            query.type_context(),
+            &query.symbol_table,
+            &mut strings,
+            None,
+            None,
+        )
+        .unwrap();
+
+        assert!(!result.instructions.is_empty());
+    }
+
+    #[test]
+    fn compile_capture() {
+        let query = QueryBuilder::one_liner("Test = (identifier) @id")
+            .parse()
+            .unwrap()
+            .analyze();
+
+        let mut strings = StringTableBuilder::new();
+        let result = Compiler::compile(
+            query.interner(),
+            query.type_context(),
+            &query.symbol_table,
+            &mut strings,
+            None,
+            None,
+        )
+        .unwrap();
+
+        assert!(!result.instructions.is_empty());
+    }
+
+    #[test]
+    fn compile_nested() {
+        let query = QueryBuilder::one_liner("Test = (call_expression function: (identifier) @fn)")
+            .parse()
+            .unwrap()
+            .analyze();
+
+        let mut strings = StringTableBuilder::new();
+        let result = Compiler::compile(
+            query.interner(),
+            query.type_context(),
+            &query.symbol_table,
+            &mut strings,
+            None,
+            None,
+        )
+        .unwrap();
+
+        assert!(!result.instructions.is_empty());
+    }
+}
diff --git a/crates/plotnik-lib/src/query/emit_tests.rs b/crates/plotnik-lib/src/query/emit_tests.rs
deleted file mode 100644
index b166e35b..00000000
--- a/crates/plotnik-lib/src/query/emit_tests.rs
+++ /dev/null
@@ -1,333 +0,0 @@
-//! Tests for bytecode emission.
-
-use plotnik_langs::{Lang, from_name};
-
-use crate::bytecode::{Header, MAGIC, Module, QTypeId, VERSION};
-use crate::query::QueryBuilder;
-use crate::query::emit::{StringTableBuilder, TypeTableBuilder};
-
-fn javascript() -> Lang {
-    from_name("javascript").expect("javascript lang")
-}
-
-fn emit_query(src: &str) -> Vec<u8> {
-    QueryBuilder::one_liner(src)
-        .parse()
-        .expect("parse")
-        .analyze()
-        .link(&javascript())
-        .emit()
-        .expect("emit")
-}
-
-#[test]
-fn emit_minimal_query() {
-    let bytes = emit_query("Test = (identifier) @id");
-
-    // Verify header
-    assert!(bytes.len() >= 64);
-    let header = Header::from_bytes(&bytes);
-    assert_eq!(header.magic, MAGIC);
-    assert_eq!(header.version, VERSION);
-    assert_eq!(header.total_size as usize, bytes.len());
-
-    // Should have 1 entrypoint
-    assert_eq!(header.entrypoints_count, 1);
-
-    // Should have at least one string (the definition name "Test")
-    assert!(header.str_table_count >= 1);
-
-    // Should have at least one node type ("identifier")
-    assert!(header.node_types_count >= 1);
-}
-
-#[test]
-fn emit_roundtrip_via_module() {
-    let bytes = emit_query("Test = (identifier) @id");
-
-    // Load the bytes as a Module
-    let module = Module::from_bytes(bytes).expect("load module");
-
-    // Verify we can read back the strings
-    let strings = module.strings();
-    assert!(module.header().str_table_count >= 1);
-
-    // Verify we can read back entrypoints
-    let entrypoints = module.entrypoints();
-    assert_eq!(entrypoints.len(), 1);
-
-    // Verify we can read the entrypoint name
-    let ep = entrypoints.get(0);
-    let name = strings.get(ep.name);
-    assert_eq!(name, "Test");
-}
-
-#[test]
-fn emit_multiple_definitions() {
-    let bytes = emit_query(
-        r#"
-        Foo = (identifier) @id
-        Bar = (string) @str
-        "#,
-    );
-
-    let header = Header::from_bytes(&bytes);
-
-    // Should have 2 entrypoints
-    assert_eq!(header.entrypoints_count, 2);
-
-    // Entrypoints preserve definition order
-    let module = Module::from_bytes(bytes).expect("load module");
-    let entrypoints = module.entrypoints();
-
-    let ep0 = entrypoints.get(0);
-    let ep1 = entrypoints.get(1);
-
-    let name0 = module.strings().get(ep0.name);
-    let name1 = module.strings().get(ep1.name);
-
-    assert_eq!(name0, "Foo"); // Foo defined first
-    assert_eq!(name1, "Bar");
-}
-
-#[test]
-fn emit_with_field_constraint() {
-    let bytes = emit_query("Test = (function_declaration name: (identifier) @name)");
-
-    let header = Header::from_bytes(&bytes);
-
-    // Should have at least one field ("name")
-    assert!(header.node_fields_count >= 1);
-
-    let module = Module::from_bytes(bytes).expect("load module");
-    let fields = module.node_fields();
-
-    // Find the "name" field
-    let has_name_field = (0..fields.len()).any(|i| {
-        let f = fields.get(i);
-        module.strings().get(f.name) == "name"
-    });
-    assert!(has_name_field, "should have 'name' field");
-}
-
-#[test]
-fn emit_with_struct_type() {
-    // This should produce a struct type with two fields
-    let bytes =
-        emit_query("Test = (function_declaration name: (identifier) @name body: (_) @body)");
-
-    // Load the module to check type metadata
-    let module = Module::from_bytes(bytes).expect("load module");
-    let types = module.types();
-
-    // Should have type definitions for the struct
-    // The struct has 2 fields, so we expect type members
-    assert!(types.defs_count() >= 1 || types.members_count() >= 2);
-}
-
-#[test]
-fn string_table_builder_deduplicates() {
-    use plotnik_core::Interner;
-
-    let mut interner = Interner::new();
-    let sym1 = interner.intern("foo");
-    let sym2 = interner.intern("bar");
-    let sym3 = interner.intern("foo"); // Same as sym1
-
-    let mut builder = StringTableBuilder::new();
-    let id1 = builder.get_or_intern(sym1, &interner).expect("id1");
-    let id2 = builder.get_or_intern(sym2, &interner).expect("id2");
-    let id3 = builder.get_or_intern(sym3, &interner).expect("id3");
-
-    assert_eq!(id1, id3); // Same symbol -> same StringId
-    assert_ne!(id1, id2); // Different symbols -> different StringIds
-    assert_eq!(builder.len(), 2); // Only 2 unique strings
-}
-
-#[test]
-fn string_table_builder_intern_str() {
-    let mut builder = StringTableBuilder::new();
-
-    let id1 = builder.intern_str("hello");
-    let id2 = builder.intern_str("world");
-    let id3 = builder.intern_str("hello"); // Duplicate
-
-    assert_eq!(id1, id3);
-    assert_ne!(id1, id2);
-    assert_eq!(builder.len(), 2);
-}
-
-#[test]
-fn type_table_builder_builtins() {
-    use crate::query::type_check::{TYPE_NODE, TYPE_STRING, TYPE_VOID};
-
-    let mut builder = TypeTableBuilder::new();
-
-    // Build with empty context
-    let type_ctx = crate::query::type_check::TypeContext::new();
-    let interner = plotnik_core::Interner::new();
-    let mut strings = StringTableBuilder::new();
-
-    builder
-        .build(&type_ctx, &interner, &mut strings)
-        .expect("build");
-
-    // Builtins should be mapped
-    assert_eq!(builder.get(TYPE_VOID), Some(QTypeId::VOID));
-    assert_eq!(builder.get(TYPE_NODE), Some(QTypeId::NODE));
-    assert_eq!(builder.get(TYPE_STRING), Some(QTypeId::STRING));
-}
-
-#[test]
-fn emit_checksum_is_valid() {
-    let bytes = emit_query("Test = (identifier) @id");
-
-    let header = Header::from_bytes(&bytes);
-
-    // Verify checksum
-    let computed = crc32fast::hash(&bytes[64..]);
-    assert_eq!(header.checksum, computed, "checksum mismatch");
-}
-
-#[test]
-fn emit_sections_are_aligned() {
-    let bytes = emit_query("Test = (identifier) @id");
-
-    let header = Header::from_bytes(&bytes);
-
-    // All section offsets should be 64-byte aligned
-    assert_eq!(header.str_blob_offset % 64, 0, "str_blob not aligned");
-    assert_eq!(header.str_table_offset % 64, 0, "str_table not aligned");
-    assert_eq!(header.node_types_offset % 64, 0, "node_types not aligned");
-    assert_eq!(header.node_fields_offset % 64, 0, "node_fields not aligned");
-    assert_eq!(header.trivia_offset % 64, 0, "trivia not aligned");
-    assert_eq!(header.type_meta_offset % 64, 0, "type_meta not aligned");
-    assert_eq!(header.entrypoints_offset % 64, 0, "entrypoints not aligned");
-    assert_eq!(header.transitions_offset % 64, 0, "transitions not aligned");
-}
-
-#[test]
-fn debug_recursive_quantified() {
-    use crate::SourceMap;
-    use crate::bytecode::QTypeId;
-
-    let src = "Item = (item (Item)* @children)";
-    let source_map = SourceMap::one_liner(src);
-    let query = crate::query::QueryBuilder::new(source_map)
-        .parse()
-        .unwrap()
-        .analyze();
-
-    eprintln!("=== TypeContext ===");
-    for (id, kind) in query.type_context().iter_types() {
-        eprintln!("TypeId {:?}: {:?}", id, kind);
-    }
-
-    for (def_id, type_id) in query.type_context().iter_def_types() {
-        let name_sym = query.type_context().def_name_sym(def_id);
-        let name = query.interner().resolve(name_sym);
-        eprintln!("DefId {:?}: {} -> TypeId {:?}", def_id, name, type_id);
-    }
-
-    let bytecode = query.emit().expect("emit");
-    let module = Module::from_bytes(bytecode).expect("load");
-
-    eprintln!("\n=== Bytecode ===");
-    eprintln!("TypeDefs count: {}", module.types().defs_count());
-    for i in 0..module.types().defs_count() {
-        let def = module.types().get_def(i);
-        let type_id = QTypeId::from_custom_index(i);
-        eprintln!(
-            "  TypeDef[{}] (id={:?}): kind={}, data={}, count={}",
-            i, type_id, def.kind, def.data, def.count
-        );
-    }
-
-    eprintln!("\nEntrypoints: {}", module.entrypoints().len());
-    for i in 0..module.entrypoints().len() {
-        let ep = module.entrypoints().get(i);
-        let name = module.strings().get(ep.name);
-        eprintln!("  {}: result_type = {:?}", name, ep.result_type);
-    }
-
-    eprintln!("\n=== TypeScript Output ===");
-    let ts = crate::bytecode::emit::emit_typescript(&module);
-    eprintln!("{}", ts);
-}
-
-#[test]
-fn debug_untagged_alt() {
-    use crate::SourceMap;
-    use crate::bytecode::QTypeId;
-
-    let src = "Q = [(a) @a (b) @b]";
-    let source_map = SourceMap::one_liner(src);
-    let query = crate::query::QueryBuilder::new(source_map)
-        .parse()
-        .unwrap()
-        .analyze();
-
-    // Check type context
-    eprintln!("=== TypeContext ===");
-    for (def_id, type_id) in query.type_context().iter_def_types() {
-        let name_sym = query.type_context().def_name_sym(def_id);
-        let name = query.interner().resolve(name_sym);
-        eprintln!("DefId {:?}: {} -> TypeId {:?}", def_id, name, type_id);
-
-        if let Some(tk) = query.type_context().get_type(type_id) {
-            eprintln!("  TypeKind: {:?}", tk);
-        }
-    }
-
-    // Emit bytecode
-    let bytecode = query.emit().expect("emit");
-    let module = Module::from_bytes(bytecode).expect("load");
-
-    eprintln!("\n=== Bytecode ===");
-    eprintln!("Entrypoints: {}", module.entrypoints().len());
-    for i in 0..module.entrypoints().len() {
-        let ep = module.entrypoints().get(i);
-        let name = module.strings().get(ep.name);
-        eprintln!("  {}: result_type = {:?}", name, ep.result_type);
-
-        if let Some(def) = module.types().get(ep.result_type) {
-            eprintln!(
-                "    TypeDef: kind={}, data={}, count={}",
-                def.kind, def.data, def.count
-            );
-        } else if ep.result_type.is_builtin() {
-            eprintln!("    Builtin type: {:?}", ep.result_type);
-        }
-    }
-
-    eprintln!("\nTypeDefs count: {}", module.types().defs_count());
-    for i in 0..module.types().defs_count() {
-        let def = module.types().get_def(i);
-        let type_id = QTypeId::from_custom_index(i);
-        eprintln!(
-            "  TypeDef[{}] (id={:?}): kind={}, data={}, count={}",
-            i, type_id, def.kind, def.data, def.count
-        );
-    }
-
-    eprintln!("\nTypeMembers count: {}", module.types().members_count());
-    for i in 0..module.types().members_count() {
-        let m = module.types().get_member(i);
-        let name = module.strings().get(m.name);
-        eprintln!(
-            "  TypeMember[{}]: name={}, type_id={:?}",
-            i, name, m.type_id
-        );
-    }
-
-    eprintln!("\nTypeNames count: {}", module.types().names_count());
-    for i in 0..module.types().names_count() {
-        let tn = module.types().get_name(i);
-        let name = module.strings().get(tn.name);
-        eprintln!("  TypeName[{}]: name={}, type_id={:?}", i, name, tn.type_id);
-    }
-
-    eprintln!("\n=== TypeScript Output ===");
-    let ts = crate::bytecode::emit::emit_typescript(&module);
-    eprintln!("{}", ts);
-}
diff --git a/crates/plotnik-lib/src/query/link.rs b/crates/plotnik-lib/src/query/link.rs
index 2c6b42db..0b654dfb 100644
--- a/crates/plotnik-lib/src/query/link.rs
+++ b/crates/plotnik-lib/src/query/link.rs
@@ -7,7 +7,7 @@
 
 use std::collections::HashMap;
 
-use indexmap::IndexSet;
+use indexmap::{IndexMap, IndexSet};
 use plotnik_core::{Interner, NodeFieldId, NodeTypeId, Symbol};
 use plotnik_langs::Lang;
 use rowan::TextRange;
@@ -16,9 +16,9 @@ use rowan::TextRange;
 #[derive(Default)]
 pub struct LinkOutput {
     /// Interned name → NodeTypeId (for binary: StringId → NodeTypeId)
-    pub node_type_ids: HashMap<Symbol, NodeTypeId>,
+    pub node_type_ids: IndexMap<Symbol, NodeTypeId>,
     /// Interned name → NodeFieldId (for binary: StringId → NodeFieldId)
-    pub node_field_ids: HashMap<Symbol, NodeFieldId>,
+    pub node_field_ids: IndexMap<Symbol, NodeFieldId>,
 }
 
 use crate::diagnostics::{DiagnosticKind, Diagnostics};
diff --git a/crates/plotnik-lib/src/query/mod.rs b/crates/plotnik-lib/src/query/mod.rs
index 2bb96c16..39dc0fdb 100644
--- a/crates/plotnik-lib/src/query/mod.rs
+++ b/crates/plotnik-lib/src/query/mod.rs
@@ -10,8 +10,9 @@ pub use symbol_table::SymbolTable;
 
 pub mod alt_kinds;
 pub mod anchors;
+pub mod compile;
 mod dependencies;
-pub mod emit;
+pub mod codegen;
 pub mod link;
 #[allow(clippy::module_inception)]
 pub mod query;
@@ -26,7 +27,7 @@ mod anchors_tests;
 #[cfg(test)]
 mod dependencies_tests;
 #[cfg(all(test, feature = "plotnik-langs"))]
-mod emit_tests;
+mod codegen_tests;
 #[cfg(all(test, feature = "plotnik-langs"))]
 mod link_tests;
 #[cfg(test)]
diff --git a/crates/plotnik-lib/src/query/query.rs b/crates/plotnik-lib/src/query/query.rs
index 6d83e0c2..15c0920c 100644
--- a/crates/plotnik-lib/src/query/query.rs
+++ b/crates/plotnik-lib/src/query/query.rs
@@ -1,5 +1,3 @@
-#![allow(unused)]
-use std::collections::HashMap;
 use std::ops::{Deref, DerefMut};
 
 use indexmap::IndexMap;
@@ -8,7 +6,7 @@ use plotnik_core::{Interner, NodeFieldId, NodeTypeId, Symbol};
 use plotnik_langs::Lang;
 
 use crate::Diagnostics;
-use crate::parser::{ParseResult, Parser, Root, SyntaxNode, lexer::lex};
+use crate::parser::{Parser, Root, SyntaxNode, lexer::lex};
 use crate::query::alt_kinds::validate_alt_kinds;
 use crate::query::anchors::validate_anchors;
 use crate::query::dependencies;
@@ -165,7 +163,7 @@ impl QueryAnalyzed {
     }
 
     pub fn get_arity(&self, node: &SyntaxNode) -> Option<Arity> {
-        use crate::parser::ast::{self, Expr};
+        use crate::parser::ast;
 
         // Try casting to Expr first as it's the most common query
         if let Some(expr) = ast::Expr::cast(node.clone()) {
@@ -202,9 +200,14 @@ impl QueryAnalyzed {
         &self.interner
     }
 
-    /// Emit bytecode (types only, no node validation).
-    pub fn emit(&self) -> Result<Vec<u8>, super::emit::EmitError> {
-        super::emit::emit(&self.type_context, &self.interner)
+    /// Emit bytecode without language linking (no node type/field validation).
+    ///
+    /// Returns `Err(EmitError::InvalidQuery)` if the query has validation errors.
+    pub fn emit(&self) -> Result<Vec<u8>, super::codegen::EmitError> {
+        if !self.is_valid() {
+            return Err(super::codegen::EmitError::InvalidQuery);
+        }
+        super::codegen::emit(&self.type_context, &self.interner, &self.symbol_table)
     }
 
     pub fn link(mut self, lang: &Lang) -> LinkedQuery {
@@ -254,8 +257,8 @@ impl TryFrom<&str> for QueryAnalyzed {
 
 pub struct LinkedQuery {
     inner: QueryAnalyzed,
-    node_type_ids: HashMap<Symbol, NodeTypeId>,
-    node_field_ids: HashMap<Symbol, NodeFieldId>,
+    node_type_ids: IndexMap<Symbol, NodeTypeId>,
+    node_field_ids: IndexMap<Symbol, NodeFieldId>,
 }
 
 impl LinkedQuery {
@@ -263,17 +266,22 @@ impl LinkedQuery {
         &self.inner.interner
     }
 
-    pub fn node_type_ids(&self) -> &HashMap<Symbol, NodeTypeId> {
+    pub fn node_type_ids(&self) -> &IndexMap<Symbol, NodeTypeId> {
         &self.node_type_ids
     }
 
-    pub fn node_field_ids(&self) -> &HashMap<Symbol, NodeFieldId> {
+    pub fn node_field_ids(&self) -> &IndexMap<Symbol, NodeFieldId> {
         &self.node_field_ids
     }
 
-    /// Emit bytecode (includes node type/field validation info).
-    pub fn emit(&self) -> Result<Vec<u8>, super::emit::EmitError> {
-        super::emit::emit_linked(self)
+    /// Emit bytecode with node type/field symbols from language linking.
+    ///
+    /// Returns `Err(EmitError::InvalidQuery)` if the query has validation errors.
+    pub fn emit(&self) -> Result<Vec<u8>, super::codegen::EmitError> {
+        if !self.is_valid() {
+            return Err(super::codegen::EmitError::InvalidQuery);
+        }
+        super::codegen::emit_linked(self)
     }
 }
 
diff --git a/crates/plotnik-lib/src/query/query_tests.rs b/crates/plotnik-lib/src/query/query_tests.rs
index 75d14140..2593b0df 100644
--- a/crates/plotnik-lib/src/query/query_tests.rs
+++ b/crates/plotnik-lib/src/query/query_tests.rs
@@ -1,4 +1,4 @@
-use plotnik_langs::Lang;
+use plotnik_langs::{Lang, from_name};
 
 use crate::{
     SourceMap,
@@ -6,6 +6,10 @@ use crate::{
     query::query::{LinkedQuery, QueryAnalyzed, QueryBuilder},
 };
 
+fn javascript() -> Lang {
+    from_name("javascript").expect("javascript lang")
+}
+
 impl QueryAnalyzed {
     #[track_caller]
     fn parse_and_validate(src: &str) -> Self {
@@ -93,6 +97,46 @@ impl QueryAnalyzed {
         crate::bytecode::emit::emit_typescript(&module)
     }
 
+    #[track_caller]
+    pub fn expect_valid_bytecode(src: &str) -> String {
+        let query = Self::parse_and_validate(src);
+        let bytecode = query.emit().expect("bytecode emission should succeed");
+        let module = Module::from_bytes(bytecode).expect("module loading should succeed");
+        crate::bytecode::dump(&module)
+    }
+
+    #[track_caller]
+    pub fn expect_valid_linked_bytecode(src: &str) -> String {
+        let query = Self::parse_and_validate(src).link(&javascript());
+        if !query.is_valid() {
+            panic!(
+                "Expected valid linking, got error:\n{}",
+                query.dump_diagnostics()
+            );
+        }
+        let bytecode = query.emit().expect("bytecode emission should succeed");
+        let module = Module::from_bytes(bytecode).expect("module loading should succeed");
+        crate::bytecode::dump(&module)
+    }
+
+    #[track_caller]
+    pub fn expect_valid_bytes(src: &str) -> Vec<u8> {
+        let query = Self::parse_and_validate(src);
+        query.emit().expect("bytecode emission should succeed")
+    }
+
+    #[track_caller]
+    pub fn expect_valid_linked_bytes(src: &str) -> Vec<u8> {
+        let query = Self::parse_and_validate(src).link(&javascript());
+        if !query.is_valid() {
+            panic!(
+                "Expected valid linking, got error:\n{}",
+                query.dump_diagnostics()
+            );
+        }
+        query.emit().expect("bytecode emission should succeed")
+    }
+
     #[track_caller]
     pub fn expect_invalid(src: &str) -> String {
         let source_map = SourceMap::one_liner(src);

From a98f86922f78e2cbdc6eb48e9b71f9e69af85140 Mon Sep 17 00:00:00 2001
From: Sergei Zharinov <zharinov@users.noreply.github.com>
Date: Wed, 31 Dec 2025 09:28:07 -0300
Subject: [PATCH 2/3] feat: add --bytecode flag to debug command

---
 AGENTS.md                                    |  3 +-
 crates/plotnik-cli/src/cli.rs                | 27 ++++++++------
 crates/plotnik-cli/src/commands/debug/mod.rs | 37 +++++++++++++++-----
 crates/plotnik-cli/src/main.rs               |  1 +
 4 files changed, 47 insertions(+), 21 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index cc15da36..286196a5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -199,11 +199,12 @@ Inspect query AST/CST or parse source files with tree-sitter.
 cargo run -p plotnik-cli -- debug -q 'Test = (identifier) @id'
 cargo run -p plotnik-cli -- debug -q 'Test = (identifier) @id' --only-symbols
 cargo run -p plotnik-cli -- debug -q 'Test = (identifier) @id' --types
+cargo run -p plotnik-cli -- debug -q 'Test = (identifier) @id' --bytecode
 cargo run -p plotnik-cli -- debug -s app.ts
 cargo run -p plotnik-cli -- debug -s app.ts --raw
 ```
 
-Options: `--only-symbols`, `--cst`, `--raw`, `--spans`, `--arities`, `--types`
+Options: `--only-symbols`, `--cst`, `--raw`, `--spans`, `--arities`, `--types`, `--bytecode`
 
 ## types
 
diff --git a/crates/plotnik-cli/src/cli.rs b/crates/plotnik-cli/src/cli.rs
index 553dda6c..ee3a8062 100644
--- a/crates/plotnik-cli/src/cli.rs
+++ b/crates/plotnik-cli/src/cli.rs
@@ -32,11 +32,12 @@ pub struct Cli {
 pub enum Command {
     /// Debug and inspect queries and source files
     #[command(after_help = r#"EXAMPLES:
-  plotnik debug -q '(identifier) @id'
-  plotnik debug -q '(identifier) @id' --only-symbols
+  plotnik debug -q 'Q = (identifier) @id'
+  plotnik debug -q 'Q = (identifier) @id' --only-symbols
+  plotnik debug -q 'Q = (identifier) @id' --bytecode
   plotnik debug -s app.ts
   plotnik debug -s app.ts --raw
-  plotnik debug -q '(function_declaration) @fn' -s app.ts -l typescript"#)]
+  plotnik debug -q 'Q = (function_declaration) @fn' -s app.ts -l typescript"#)]
     Debug {
         #[command(flatten)]
         query: QueryArgs,
@@ -57,10 +58,10 @@ pub enum Command {
 
     /// Execute a query against source code and output JSON
     #[command(after_help = r#"EXAMPLES:
-  plotnik exec -q '(identifier) @id' -s app.js
-  plotnik exec -q '(identifier) @id' -s app.js --pretty
-  plotnik exec -q '(function_declaration) @fn' -s app.ts -l typescript --verbose-nodes
-  plotnik exec -q '(identifier) @id' -s app.js --check
+  plotnik exec -q 'Q = (identifier) @id' -s app.js
+  plotnik exec -q 'Q = (identifier) @id' -s app.js --pretty
+  plotnik exec -q 'Q = (function_declaration) @fn' -s app.ts -l typescript --verbose-nodes
+  plotnik exec -q 'Q = (identifier) @id' -s app.js --check
   plotnik exec --query-file query.ptk -s app.js --entry FunctionDef"#)]
     Exec {
         #[command(flatten)]
@@ -79,11 +80,11 @@ pub enum Command {
 
     /// Generate type definitions from a query
     #[command(after_help = r#"EXAMPLES:
-  plotnik types -q '(identifier) @id' -l javascript
+  plotnik types -q 'Q = (identifier) @id' -l javascript
   plotnik types --query-file query.ptk -l typescript
-  plotnik types -q '(function_declaration) @fn' -l js --format ts
-  plotnik types -q '(identifier) @id' -l js --verbose-nodes
-  plotnik types -q '(identifier) @id' -l js -o types.d.ts
+  plotnik types -q 'Q = (function_declaration) @fn' -l js --format ts
+  plotnik types -q 'Q = (identifier) @id' -l js --verbose-nodes
+  plotnik types -q 'Q = (identifier) @id' -l js -o types.d.ts
 
 NOTE: Use --verbose-nodes to match `exec --verbose-nodes` output shape."#)]
     Types {
@@ -202,4 +203,8 @@ pub struct OutputArgs {
     /// Show inferred types
     #[arg(long)]
     pub types: bool,
+
+    /// Show bytecode dump
+    #[arg(long)]
+    pub bytecode: bool,
 }
diff --git a/crates/plotnik-cli/src/commands/debug/mod.rs b/crates/plotnik-cli/src/commands/debug/mod.rs
index 02682339..841bc420 100644
--- a/crates/plotnik-cli/src/commands/debug/mod.rs
+++ b/crates/plotnik-cli/src/commands/debug/mod.rs
@@ -22,6 +22,7 @@ pub struct DebugArgs {
     pub graph: bool,
     pub graph_raw: bool,
     pub types: bool,
+    pub bytecode: bool,
     pub color: bool,
 }
 
@@ -47,7 +48,7 @@ pub fn run(args: DebugArgs) {
         })
     });
 
-    let show_query = has_query_input && !args.symbols && !args.graph && !args.types;
+    let show_query = has_query_input && !args.symbols && !args.graph && !args.types && !args.bytecode;
     let show_source = has_source_input;
 
     if show_query && let Some(ref q) = query {
@@ -82,6 +83,7 @@ pub fn run(args: DebugArgs) {
     if args.types
         && let Some(ref q) = query
     {
+        ensure_valid(q, args.color);
         let bytecode = q.emit().expect("bytecode emission failed");
         let module =
             plotnik_lib::bytecode::Module::from_bytes(bytecode).expect("module loading failed");
@@ -89,6 +91,17 @@ pub fn run(args: DebugArgs) {
         print!("{}", output);
     }
 
+    if args.bytecode
+        && let Some(ref q) = query
+    {
+        ensure_valid(q, args.color);
+        let bytecode = q.emit().expect("bytecode emission failed");
+        let module =
+            plotnik_lib::bytecode::Module::from_bytes(bytecode).expect("module loading failed");
+        let output = plotnik_lib::bytecode::dump(&module);
+        print!("{}", output);
+    }
+
     if show_source {
         if show_query || args.symbols {
             println!();
@@ -99,15 +112,21 @@ pub fn run(args: DebugArgs) {
         print!("{}", dump_source(&tree, &source_code, args.raw));
     }
 
-    if let Some(ref q) = query
-        && !q.is_valid()
-    {
-        eprint!(
-            "{}",
-            q.diagnostics().render_colored(q.source_map(), args.color)
-        );
-        std::process::exit(1);
+    if let Some(ref q) = query {
+        ensure_valid(q, args.color);
+    }
+}
+
+/// Ensure query is valid, exiting with diagnostics if not.
+fn ensure_valid(q: &Query, color: bool) {
+    if q.is_valid() {
+        return;
     }
+    eprint!(
+        "{}",
+        q.diagnostics().render_colored(q.source_map(), color)
+    );
+    std::process::exit(1);
 }
 
 fn load_query(args: &DebugArgs) -> String {
diff --git a/crates/plotnik-cli/src/main.rs b/crates/plotnik-cli/src/main.rs
index 9ad8eb72..9882c875 100644
--- a/crates/plotnik-cli/src/main.rs
+++ b/crates/plotnik-cli/src/main.rs
@@ -30,6 +30,7 @@ fn main() {
                 graph: output.graph,
                 graph_raw: output.graph_raw,
                 types: output.types,
+                bytecode: output.bytecode,
                 color: output.color.should_colorize(),
             });
         }

From 5acb64140b6cf1547259888c4fada42f8551200c Mon Sep 17 00:00:00 2001
From: Sergei Zharinov <zharinov@users.noreply.github.com>
Date: Wed, 31 Dec 2025 09:29:08 -0300
Subject: [PATCH 3/3] test: update module_tests for new bytecode format

---
 .../plotnik-lib/src/bytecode/module_tests.rs  | 342 ++++++------------
 1 file changed, 108 insertions(+), 234 deletions(-)

diff --git a/crates/plotnik-lib/src/bytecode/module_tests.rs b/crates/plotnik-lib/src/bytecode/module_tests.rs
index c4b8be1f..3d10eb67 100644
--- a/crates/plotnik-lib/src/bytecode/module_tests.rs
+++ b/crates/plotnik-lib/src/bytecode/module_tests.rs
@@ -1,321 +1,184 @@
 //! Tests for the bytecode module.
 
-use super::*;
-use crate::bytecode::nav::Nav;
-use crate::bytecode::{Header, MAGIC, Match, TypeMetaHeader, VERSION};
-
-/// Build a minimal valid bytecode for testing.
-fn build_test_bytecode() -> Vec<u8> {
-    // Layout (all sections 64-byte aligned):
-    // [0..64)     Header
-    // [64..128)   StringBlob + padding
-    // [128..192)  StringTable + padding (needs 2 u32 entries: offset + sentinel)
-    // [192..256)  NodeTypes + padding
-    // [256..320)  NodeFields + padding
-    // [320..384)  Trivia + padding
-    // [384..448)  TypeMeta: TypeMetaHeader (8 bytes) + padding
-    // [448..512)  TypeDefs sub-section (aligned)
-    // [512..576)  TypeMembers sub-section (aligned, empty)
-    // [576..640)  TypeNames sub-section (aligned, empty)
-    // [640..704)  Entrypoints + padding
-    // [704..768)  Transitions + padding
-
-    let mut bytes = vec![0u8; 768];
-
-    // String blob: "Test" at offset 0
-    let str_blob_offset = 64;
-    bytes[64] = b'T';
-    bytes[65] = b'e';
-    bytes[66] = b's';
-    bytes[67] = b't';
-
-    // String table: sequential u32 offsets with sentinel
-    // Entry 0: offset 0 (start of "Test")
-    // Entry 1: offset 4 (sentinel = end of blob)
-    let str_table_offset = 128;
-    bytes[128..132].copy_from_slice(&0u32.to_le_bytes()); // offset of string 0
-    bytes[132..136].copy_from_slice(&4u32.to_le_bytes()); // sentinel (end of blob)
-
-    // Node types: one entry (id=42, name=StringId(0))
-    let node_types_offset = 192;
-    bytes[192..194].copy_from_slice(&42u16.to_le_bytes());
-    bytes[194..196].copy_from_slice(&0u16.to_le_bytes());
-
-    // Node fields: one entry (id=7, name=StringId(0))
-    let node_fields_offset = 256;
-    bytes[256..258].copy_from_slice(&7u16.to_le_bytes());
-    bytes[258..260].copy_from_slice(&0u16.to_le_bytes());
-
-    // Trivia: one entry (node_type=100)
-    let trivia_offset = 320;
-    bytes[320..322].copy_from_slice(&100u16.to_le_bytes());
-
-    // TypeMeta section
-    let type_meta_offset = 384;
-
-    // TypeMetaHeader (8 bytes): type_defs_count=1, type_members_count=0, type_names_count=0
-    let type_meta_header = TypeMetaHeader {
-        type_defs_count: 1,
-        type_members_count: 0,
-        type_names_count: 0,
-        _pad: 0,
-    };
-    bytes[384..392].copy_from_slice(&type_meta_header.to_bytes());
-
-    // TypeDefs sub-section at aligned offset (448)
-    // One TypeDef (4 bytes): data=0, count=0, kind=3 (Struct)
-    bytes[448..450].copy_from_slice(&0u16.to_le_bytes()); // data (member index)
-    bytes[450] = 0; // count
-    bytes[451] = 3; // kind=Struct
-
-    // TypeMembers sub-section at 512 (empty)
-    // TypeNames sub-section at 576 (empty)
-
-    // Entrypoints: one entry (name=StringId(0), target=StepId(0), result_type=QTypeId(0))
-    let entrypoints_offset = 640;
-    bytes[640..642].copy_from_slice(&0u16.to_le_bytes()); // name
-    bytes[642..644].copy_from_slice(&0u16.to_le_bytes()); // target
-    bytes[644..646].copy_from_slice(&0u16.to_le_bytes()); // result_type
-    bytes[646..648].copy_from_slice(&0u16.to_le_bytes()); // padding
-
-    // Transitions: one Match8 instruction (accept state)
-    let transitions_offset = 704;
-    // type_id=0x00 (Match8, segment 0)
-    bytes[704] = 0x00;
-    // nav=Stay
-    bytes[705] = Nav::Stay.to_byte();
-    // node_type=None (0)
-    bytes[706..708].copy_from_slice(&0u16.to_le_bytes());
-    // node_field=None (0)
-    bytes[708..710].copy_from_slice(&0u16.to_le_bytes());
-    // next=0 (accept)
-    bytes[710..712].copy_from_slice(&0u16.to_le_bytes());
-
-    // Build header
-    let header = Header {
-        magic: MAGIC,
-        version: VERSION,
-        checksum: 0,
-        total_size: 768,
-        str_blob_offset: str_blob_offset as u32,
-        str_table_offset: str_table_offset as u32,
-        node_types_offset: node_types_offset as u32,
-        node_fields_offset: node_fields_offset as u32,
-        trivia_offset: trivia_offset as u32,
-        type_meta_offset: type_meta_offset as u32,
-        entrypoints_offset: entrypoints_offset as u32,
-        transitions_offset: transitions_offset as u32,
-        str_table_count: 1,
-        node_types_count: 1,
-        node_fields_count: 1,
-        trivia_count: 1,
-        entrypoints_count: 1,
-        transitions_count: 1,
-        ..Default::default()
-    };
-
-    bytes[0..64].copy_from_slice(&header.to_bytes());
-    bytes
-}
+use indoc::indoc;
+
+use crate::Query;
+use crate::bytecode::{Module, ModuleError, StepId, StringId};
 
 #[test]
 fn module_from_bytes_valid() {
-    let bytes = build_test_bytecode();
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
     let module = Module::from_bytes(bytes).unwrap();
 
     assert!(module.header().validate_magic());
     assert!(module.header().validate_version());
-    assert_eq!(module.header().total_size, 768);
 }
 
 #[test]
 fn module_from_bytes_too_small() {
-    let bytes = vec![0u8; 32];
-    let err = Module::from_bytes(bytes).unwrap_err();
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
+    let truncated = bytes[..32].to_vec();
+
+    let err = Module::from_bytes(truncated).unwrap_err();
     assert!(matches!(err, ModuleError::FileTooSmall(32)));
 }
 
 #[test]
 fn module_from_bytes_invalid_magic() {
-    let mut bytes = build_test_bytecode();
+    let input = "Test = (identifier) @id";
+
+    let mut bytes = Query::expect_valid_linked_bytes(input);
     bytes[0] = b'X'; // Corrupt magic
+
     let err = Module::from_bytes(bytes).unwrap_err();
     assert!(matches!(err, ModuleError::InvalidMagic));
 }
 
 #[test]
 fn module_from_bytes_wrong_version() {
-    let mut bytes = build_test_bytecode();
+    let input = "Test = (identifier) @id";
+
+    let mut bytes = Query::expect_valid_linked_bytes(input);
     bytes[4..8].copy_from_slice(&999u32.to_le_bytes()); // Wrong version
+
     let err = Module::from_bytes(bytes).unwrap_err();
     assert!(matches!(err, ModuleError::UnsupportedVersion(999)));
 }
 
 #[test]
 fn module_from_bytes_size_mismatch() {
-    let mut bytes = build_test_bytecode();
-    bytes[12..16].copy_from_slice(&1000u32.to_le_bytes()); // Wrong total_size
+    let input = "Test = (identifier) @id";
+
+    let mut bytes = Query::expect_valid_linked_bytes(input);
+    let actual_size = bytes.len() as u32;
+    bytes[12..16].copy_from_slice(&(actual_size + 100).to_le_bytes()); // Wrong total_size
+
     let err = Module::from_bytes(bytes).unwrap_err();
     assert!(matches!(
         err,
         ModuleError::SizeMismatch {
-            header: 1000,
-            actual: 768
-        }
+            header: h,
+            actual: a
+        } if h == actual_size + 100 && a == actual_size as usize
     ));
 }
 
-#[test]
-fn module_decode_step() {
-    let bytes = build_test_bytecode();
-    let module = Module::from_bytes(bytes).unwrap();
-
-    let instr = module.decode_step(StepId(0));
-    match instr {
-        Instruction::Match(m) => {
-            assert_eq!(m.nav, Nav::Stay);
-            assert!(m.is_epsilon());
-            assert!(m.is_terminal());
-        }
-        _ => panic!("expected Match instruction"),
-    }
-}
-
 #[test]
 fn module_strings_view() {
-    let bytes = build_test_bytecode();
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
     let module = Module::from_bytes(bytes).unwrap();
 
     let strings = module.strings();
-    assert_eq!(strings.get(StringId(0)), "Test");
+    // String 0 is the easter egg
+    assert_eq!(strings.get(StringId(0)), "Beauty will save the world");
+    // Other strings include "id", "Test", "identifier"
+    assert!(module.header().str_table_count >= 3);
 }
 
 #[test]
 fn module_node_types_view() {
-    let bytes = build_test_bytecode();
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
     let module = Module::from_bytes(bytes).unwrap();
 
     let node_types = module.node_types();
-    assert_eq!(node_types.len(), 1);
     assert!(!node_types.is_empty());
-
-    let sym = node_types.get(0);
-    assert_eq!(sym.id, 42);
-    assert_eq!(sym.name, StringId(0));
+    // Should have "identifier" node type
+    let has_identifier = (0..node_types.len()).any(|i| {
+        let sym = node_types.get(i);
+        module.strings().get(sym.name) == "identifier"
+    });
+    assert!(has_identifier);
 }
 
 #[test]
 fn module_node_fields_view() {
-    let bytes = build_test_bytecode();
-    let module = Module::from_bytes(bytes).unwrap();
-
-    let fields = module.node_fields();
-    assert_eq!(fields.len(), 1);
-
-    let sym = fields.get(0);
-    assert_eq!(sym.id, 7);
-    assert_eq!(sym.name, StringId(0));
-}
+    let input = "Test = (function_declaration name: (identifier) @name)";
 
-#[test]
-fn module_trivia_view() {
-    let bytes = build_test_bytecode();
+    let bytes = Query::expect_valid_linked_bytes(input);
     let module = Module::from_bytes(bytes).unwrap();
 
-    let trivia = module.trivia();
-    assert_eq!(trivia.len(), 1);
-    assert!(trivia.contains(100));
-    assert!(!trivia.contains(42));
+    let fields = module.node_fields();
+    assert!(!fields.is_empty());
+    // Should have "name" field
+    let has_name = (0..fields.len()).any(|i| {
+        let sym = fields.get(i);
+        module.strings().get(sym.name) == "name"
+    });
+    assert!(has_name);
 }
 
 #[test]
 fn module_types_view() {
-    let bytes = build_test_bytecode();
+    let input = indoc! {r#"
+        Test = (function_declaration
+            name: (identifier) @name
+            body: (_) @body)
+    "#};
+
+    let bytes = Query::expect_valid_linked_bytes(input);
     let module = Module::from_bytes(bytes).unwrap();
 
     let types = module.types();
-    assert_eq!(types.defs_count(), 1);
-    assert_eq!(types.members_count(), 0);
-    assert_eq!(types.names_count(), 0);
-
-    let def = types.get_def(0);
-    assert_eq!(def.kind, 3); // Struct
-    assert_eq!(def.data, 0); // member index
-    assert_eq!(def.count, 0); // member count
+    // Should have custom types (struct with fields)
+    assert!(types.defs_count() >= 1);
+    assert!(types.members_count() >= 2); // name and body fields
 }
 
 #[test]
 fn module_entrypoints_view() {
-    let bytes = build_test_bytecode();
+    let input = indoc! {r#"
+        Foo = (identifier) @id
+        Bar = (string) @str
+    "#};
+
+    let bytes = Query::expect_valid_linked_bytes(input);
     let module = Module::from_bytes(bytes).unwrap();
 
     let entrypoints = module.entrypoints();
-    assert_eq!(entrypoints.len(), 1);
+    assert_eq!(entrypoints.len(), 2);
     assert!(!entrypoints.is_empty());
 
-    let ep = entrypoints.get(0);
-    assert_eq!(ep.name, StringId(0));
-    assert_eq!(ep.target, StepId(0));
-
+    // Should be able to find by name
     let strings = module.strings();
-    let found = entrypoints.find_by_name("Test", &strings);
-    assert!(found.is_some());
-    assert_eq!(found.unwrap().target, StepId(0));
+    let foo = entrypoints.find_by_name("Foo", &strings);
+    let bar = entrypoints.find_by_name("Bar", &strings);
+    assert!(foo.is_some());
+    assert!(bar.is_some());
 }
 
 #[test]
-fn instruction_from_bytes_dispatch() {
-    // Test Match8
-    let match8 = Match {
-        segment: 0,
-        nav: Nav::Down,
-        node_type: std::num::NonZeroU16::new(42),
-        node_field: None,
-        pre_effects: vec![],
-        neg_fields: vec![],
-        post_effects: vec![],
-        successors: vec![StepId(10)],
-    };
-    let bytes = match8.to_bytes().unwrap();
-    let instr = Instruction::from_bytes(&bytes);
-    assert!(matches!(instr, Instruction::Match(_)));
-
-    // Test Call
-    let call = Call {
-        segment: 0,
-        next: StepId(5),
-        target: StepId(100),
-        ref_id: 1,
-    };
-    let bytes = call.to_bytes();
-    let instr = Instruction::from_bytes(&bytes);
-    assert!(matches!(instr, Instruction::Call(_)));
-
-    // Test Return
-    let ret = Return {
-        segment: 0,
-        ref_id: 1,
-    };
-    let bytes = ret.to_bytes();
-    let instr = Instruction::from_bytes(&bytes);
-    assert!(matches!(instr, Instruction::Return(_)));
-}
+fn module_decode_step() {
+    let input = "Test = (identifier) @id";
 
-#[test]
-fn byte_storage_deref() {
-    let data = vec![1, 2, 3, 4, 5];
-    let storage = ByteStorage::from_vec(data.clone());
+    let bytes = Query::expect_valid_linked_bytes(input);
+    let module = Module::from_bytes(bytes).unwrap();
 
-    assert_eq!(&*storage, &data[..]);
-    assert_eq!(storage.len(), 5);
-    assert_eq!(storage[2], 3);
+    // Step 0 is always the accept state (epsilon terminal)
+    let instr = module.decode_step(StepId(0));
+    match instr {
+        crate::bytecode::Instruction::Match(m) => {
+            assert!(m.is_epsilon());
+            assert!(m.is_terminal());
+        }
+        _ => panic!("expected Match instruction at step 0"),
+    }
 }
 
 #[test]
 fn module_from_path_mmap() {
     use std::io::Write;
 
-    let bytes = build_test_bytecode();
+    let input = "Test = (identifier) @id";
+
+    let bytes = Query::expect_valid_linked_bytes(input);
 
     // Write to temp file
     let mut tmpfile = tempfile::NamedTempFile::new().unwrap();
@@ -326,13 +189,24 @@ fn module_from_path_mmap() {
     let module = Module::from_path(tmpfile.path()).unwrap();
 
     assert!(module.header().validate_magic());
-    assert_eq!(module.header().total_size, 768);
 
     // Verify we can decode instructions
     let instr = module.decode_step(StepId(0));
-    assert!(matches!(instr, Instruction::Match(_)));
+    assert!(matches!(instr, crate::bytecode::Instruction::Match(_)));
 
     // Verify string lookup works through mmap
     let strings = module.strings();
-    assert_eq!(strings.get(StringId(0)), "Test");
+    assert_eq!(strings.get(StringId(0)), "Beauty will save the world");
+}
+
+#[test]
+fn byte_storage_deref() {
+    use crate::bytecode::ByteStorage;
+
+    let data = vec![1, 2, 3, 4, 5];
+    let storage = ByteStorage::from_vec(data.clone());
+
+    assert_eq!(&*storage, &data[..]);
+    assert_eq!(storage.len(), 5);
+    assert_eq!(storage[2], 3);
 }