From 5997c9b8dd30ce4144c47735954963bc5ba3d42a Mon Sep 17 00:00:00 2001
From: Sergei Zharinov <zharinov@users.noreply.github.com>
Date: Tue, 6 Jan 2026 01:03:37 -0300
Subject: [PATCH] refactor: add batch methods to `MatchIR` builder

---
 crates/plotnik-lib/src/bytecode/ir.rs         | 273 ++++++++++++---
 crates/plotnik-lib/src/compile/capture.rs     |   8 +-
 crates/plotnik-lib/src/compile/expressions.rs | 134 +++-----
 crates/plotnik-lib/src/compile/mod.rs         |  13 +-
 crates/plotnik-lib/src/compile/quantifier.rs  |  15 +-
 crates/plotnik-lib/src/compile/scope.rs       | 311 ++++++------------
 crates/plotnik-lib/src/compile/sequences.rs   |   6 +-
 crates/plotnik-lib/src/emit/layout_tests.rs   | 199 ++++-------
 8 files changed, 453 insertions(+), 506 deletions(-)

diff --git a/crates/plotnik-lib/src/bytecode/ir.rs b/crates/plotnik-lib/src/bytecode/ir.rs
index 2c7d9be6..e117a7fb 100644
--- a/crates/plotnik-lib/src/bytecode/ir.rs
+++ b/crates/plotnik-lib/src/bytecode/ir.rs
@@ -130,6 +130,66 @@ impl EffectIR {
         }
     }
 
+    /// Capture current node value.
+    pub fn node() -> Self {
+        Self::simple(EffectOpcode::Node, 0)
+    }
+
+    /// Capture current node text.
+    pub fn text() -> Self {
+        Self::simple(EffectOpcode::Text, 0)
+    }
+
+    /// Push null value.
+    pub fn null() -> Self {
+        Self::simple(EffectOpcode::Null, 0)
+    }
+
+    /// Push accumulated value to array.
+    pub fn push() -> Self {
+        Self::simple(EffectOpcode::Push, 0)
+    }
+
+    /// Begin array scope.
+    pub fn start_arr() -> Self {
+        Self::simple(EffectOpcode::Arr, 0)
+    }
+
+    /// End array scope.
+    pub fn end_arr() -> Self {
+        Self::simple(EffectOpcode::EndArr, 0)
+    }
+
+    /// Begin object scope.
+    pub fn start_obj() -> Self {
+        Self::simple(EffectOpcode::Obj, 0)
+    }
+
+    /// End object scope.
+    pub fn end_obj() -> Self {
+        Self::simple(EffectOpcode::EndObj, 0)
+    }
+
+    /// Begin enum scope.
+    pub fn start_enum() -> Self {
+        Self::simple(EffectOpcode::Enum, 0)
+    }
+
+    /// End enum scope.
+    pub fn end_enum() -> Self {
+        Self::simple(EffectOpcode::EndEnum, 0)
+    }
+
+    /// Begin suppression (suppress effects within).
+    pub fn suppress_begin() -> Self {
+        Self::simple(EffectOpcode::SuppressBegin, 0)
+    }
+
+    /// End suppression.
+    pub fn suppress_end() -> Self {
+        Self::simple(EffectOpcode::SuppressEnd, 0)
+    }
+
     /// Resolve this IR effect to a concrete EffectOp.
     ///
     /// - `lookup_member`: maps (field_name Symbol, field_type TypeId) to member index
@@ -235,6 +295,96 @@ pub struct MatchIR {
 }
 
 impl MatchIR {
+    /// Create a terminal/accept state (empty successors).
+    pub fn terminal(label: Label) -> Self {
+        Self {
+            label,
+            nav: Nav::Stay,
+            node_type: None,
+            node_field: None,
+            pre_effects: vec![],
+            neg_fields: vec![],
+            post_effects: vec![],
+            successors: vec![],
+        }
+    }
+
+    /// Start building a match instruction at the given label.
+    pub fn at(label: Label) -> Self {
+        Self::terminal(label)
+    }
+
+    /// Create an epsilon transition (no node interaction) to a single successor.
+    pub fn epsilon(label: Label, next: Label) -> Self {
+        Self::at(label).next(next)
+    }
+
+    /// Set the navigation command.
+    pub fn nav(mut self, nav: Nav) -> Self {
+        self.nav = nav;
+        self
+    }
+
+    /// Set the node type constraint.
+    pub fn node_type(mut self, t: impl Into<Option<NonZeroU16>>) -> Self {
+        self.node_type = t.into();
+        self
+    }
+
+    /// Set the field constraint.
+    pub fn node_field(mut self, f: impl Into<Option<NonZeroU16>>) -> Self {
+        self.node_field = f.into();
+        self
+    }
+
+    /// Add a negated field constraint.
+    pub fn neg_field(mut self, f: u16) -> Self {
+        self.neg_fields.push(f);
+        self
+    }
+
+    /// Add a pre-match effect.
+    pub fn pre_effect(mut self, e: EffectIR) -> Self {
+        self.pre_effects.push(e);
+        self
+    }
+
+    /// Add a post-match effect.
+    pub fn post_effect(mut self, e: EffectIR) -> Self {
+        self.post_effects.push(e);
+        self
+    }
+
+    /// Add multiple negated field constraints.
+    pub fn neg_fields(mut self, fields: impl IntoIterator<Item = u16>) -> Self {
+        self.neg_fields.extend(fields);
+        self
+    }
+
+    /// Add multiple pre-match effects.
+    pub fn pre_effects(mut self, effects: impl IntoIterator<Item = EffectIR>) -> Self {
+        self.pre_effects.extend(effects);
+        self
+    }
+
+    /// Add multiple post-match effects.
+    pub fn post_effects(mut self, effects: impl IntoIterator<Item = EffectIR>) -> Self {
+        self.post_effects.extend(effects);
+        self
+    }
+
+    /// Set a single successor.
+    pub fn next(mut self, s: Label) -> Self {
+        self.successors = vec![s];
+        self
+    }
+
+    /// Set multiple successors (for branches).
+    pub fn next_many(mut self, s: Vec<Label>) -> Self {
+        self.successors = s;
+        self
+    }
+
     /// Compute instruction size in bytes.
     pub fn size(&self) -> usize {
         // Match8 can be used if: no effects, no neg_fields, and at most 1 successor
@@ -309,6 +459,12 @@ impl MatchIR {
     }
 }
 
+impl From<MatchIR> for Instruction {
+    fn from(m: MatchIR) -> Self {
+        Self::Match(m)
+    }
+}
+
 /// Call instruction IR with symbolic target.
 #[derive(Clone, Debug)]
 pub struct CallIR {
@@ -325,6 +481,29 @@ pub struct CallIR {
 }
 
 impl CallIR {
+    /// Create a call instruction with default nav (Stay) and no field constraint.
+    pub fn new(label: Label, target: Label, next: Label) -> Self {
+        Self {
+            label,
+            nav: Nav::Stay,
+            node_field: None,
+            next,
+            target,
+        }
+    }
+
+    /// Set the navigation command.
+    pub fn nav(mut self, nav: Nav) -> Self {
+        self.nav = nav;
+        self
+    }
+
+    /// Set the field constraint.
+    pub fn node_field(mut self, f: impl Into<Option<NonZeroU16>>) -> Self {
+        self.node_field = f.into();
+        self
+    }
+
     /// Resolve labels and serialize to bytecode bytes.
     pub fn resolve(&self, map: &BTreeMap<Label, StepAddr>) -> [u8; 8] {
         let c = Call {
@@ -338,6 +517,12 @@ impl CallIR {
     }
 }
 
+impl From<CallIR> for Instruction {
+    fn from(c: CallIR) -> Self {
+        Self::Call(c)
+    }
+}
+
 /// Return instruction IR.
 #[derive(Clone, Debug)]
 pub struct ReturnIR {
@@ -346,6 +531,11 @@ pub struct ReturnIR {
 }
 
 impl ReturnIR {
+    /// Create a return instruction at the given label.
+    pub fn new(label: Label) -> Self {
+        Self { label }
+    }
+
     /// Serialize to bytecode bytes (no labels to resolve).
     pub fn resolve(&self) -> [u8; 8] {
         let r = Return { segment: 0 };
@@ -353,6 +543,12 @@ impl ReturnIR {
     }
 }
 
+impl From<ReturnIR> for Instruction {
+    fn from(r: ReturnIR) -> Self {
+        Self::Return(r)
+    }
+}
+
 /// Trampoline instruction IR with symbolic return address.
 ///
 /// Trampoline is like Call, but the target comes from VM context (external parameter)
@@ -366,6 +562,11 @@ pub struct TrampolineIR {
 }
 
 impl TrampolineIR {
+    /// Create a trampoline instruction.
+    pub fn new(label: Label, next: Label) -> Self {
+        Self { label, next }
+    }
+
     /// Resolve labels and serialize to bytecode bytes.
     pub fn resolve(&self, map: &BTreeMap<Label, StepAddr>) -> [u8; 8] {
         let t = Trampoline {
@@ -376,6 +577,12 @@ impl TrampolineIR {
     }
 }
 
+impl From<TrampolineIR> for Instruction {
+    fn from(t: TrampolineIR) -> Self {
+        Self::Trampoline(t)
+    }
+}
+
 /// Result of layout: maps labels to step addresses.
 #[derive(Clone, Debug)]
 pub struct LayoutResult {
@@ -391,32 +598,22 @@ mod tests {
 
     #[test]
     fn match_ir_size_match8() {
-        let m = MatchIR {
-            label: Label(0),
-            nav: Nav::Down,
-            node_type: NonZeroU16::new(10),
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![Label(1)],
-        };
+        let m = MatchIR::at(Label(0))
+            .nav(Nav::Down)
+            .node_type(NonZeroU16::new(10))
+            .next(Label(1));
 
         assert_eq!(m.size(), 8);
     }
 
     #[test]
     fn match_ir_size_extended() {
-        let m = MatchIR {
-            label: Label(0),
-            nav: Nav::Down,
-            node_type: NonZeroU16::new(10),
-            node_field: None,
-            pre_effects: vec![EffectIR::simple(EffectOpcode::Obj, 0)],
-            neg_fields: vec![],
-            post_effects: vec![EffectIR::simple(EffectOpcode::Node, 0)],
-            successors: vec![Label(1)],
-        };
+        let m = MatchIR::at(Label(0))
+            .nav(Nav::Down)
+            .node_type(NonZeroU16::new(10))
+            .pre_effect(EffectIR::start_obj())
+            .post_effect(EffectIR::node())
+            .next(Label(1));
 
         // 3 slots needed (1 pre + 1 post + 1 succ), fits in Match16 (4 slots)
         assert_eq!(m.size(), 16);
@@ -424,30 +621,19 @@ mod tests {
 
     #[test]
     fn instruction_successors() {
-        let m = Instruction::Match(MatchIR {
-            label: Label(0),
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![Label(1), Label(2)],
-        });
+        let m: Instruction = MatchIR::at(Label(0))
+            .next_many(vec![Label(1), Label(2)])
+            .into();
 
         assert_eq!(m.successors(), vec![Label(1), Label(2)]);
 
-        let c = Instruction::Call(CallIR {
-            label: Label(3),
-            nav: Nav::Down,
-            node_field: None,
-            next: Label(4),
-            target: Label(5),
-        });
+        let c: Instruction = CallIR::new(Label(3), Label(5), Label(4))
+            .nav(Nav::Down)
+            .into();
 
         assert_eq!(c.successors(), vec![Label(4)]);
 
-        let r = Instruction::Return(ReturnIR { label: Label(6) });
+        let r: Instruction = ReturnIR::new(Label(6)).into();
 
         assert!(r.successors().is_empty());
     }
@@ -455,16 +641,7 @@ mod tests {
     #[test]
     fn resolve_match_terminal() {
         // Terminal match: empty successors → next = 0 in bytecode
-        let m = MatchIR {
-            label: Label(0),
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![],
-        };
+        let m = MatchIR::terminal(Label(0));
 
         let mut map = BTreeMap::new();
         map.insert(Label(0), 1u16);
diff --git a/crates/plotnik-lib/src/compile/capture.rs b/crates/plotnik-lib/src/compile/capture.rs
index 0fc7c943..502eab83 100644
--- a/crates/plotnik-lib/src/compile/capture.rs
+++ b/crates/plotnik-lib/src/compile/capture.rs
@@ -79,12 +79,12 @@ impl Compiler<'_> {
         });
 
         if !is_structured_ref && !creates_structured_scope && !is_array {
-            let opcode = if cap.has_string_annotation() {
-                EffectOpcode::Text
+            let effect = if cap.has_string_annotation() {
+                EffectIR::text()
             } else {
-                EffectOpcode::Node
+                EffectIR::node()
             };
-            effects.push(EffectIR::simple(opcode, 0));
+            effects.push(effect);
         }
 
         // Add Set effect if we have a capture name.
diff --git a/crates/plotnik-lib/src/compile/expressions.rs b/crates/plotnik-lib/src/compile/expressions.rs
index d9c4a21f..abf8d08c 100644
--- a/crates/plotnik-lib/src/compile/expressions.rs
+++ b/crates/plotnik-lib/src/compile/expressions.rs
@@ -11,8 +11,8 @@ use std::num::NonZeroU16;
 
 use crate::analyze::type_check::TypeShape;
 use crate::bytecode::NAMED_WILDCARD;
+use crate::bytecode::Nav;
 use crate::bytecode::ir::{EffectIR, Instruction, Label, MatchIR};
-use crate::bytecode::{EffectOpcode, Nav};
 use crate::parser::ast::{self, Expr};
 
 use super::Compiler;
@@ -41,16 +41,15 @@ impl Compiler<'_> {
 
         // If no items, just match and exit (capture effects go here)
         if items.is_empty() {
-            self.instructions.push(Instruction::Match(MatchIR {
-                label: entry,
-                nav,
-                node_type,
-                node_field: None,
-                pre_effects: capture.pre,
-                neg_fields,
-                post_effects: capture.post,
-                successors: vec![exit],
-            }));
+            self.instructions.push(
+                MatchIR::epsilon(entry, exit)
+                    .nav(nav)
+                    .node_type(node_type)
+                    .neg_fields(neg_fields)
+                    .pre_effects(capture.pre)
+                    .post_effects(capture.post)
+                    .into(),
+            );
             return entry;
         }
 
@@ -100,28 +99,18 @@ impl Compiler<'_> {
             skip_exit,
         );
 
-        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![final_exit],
-        }));
+        self.instructions
+            .push(MatchIR::epsilon(up_label, final_exit).nav(up_nav).into());
 
         // Emit entry instruction into the node (only pre_effects here)
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: entry,
-            nav,
-            node_type,
-            node_field: None,
-            pre_effects: capture.pre,
-            neg_fields,
-            post_effects: vec![],
-            successors: vec![items_entry],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(entry, items_entry)
+                .nav(nav)
+                .node_type(node_type)
+                .neg_fields(neg_fields)
+                .pre_effects(capture.pre)
+                .into(),
+        );
 
         entry
     }
@@ -157,16 +146,8 @@ impl Compiler<'_> {
 
         // up_check: Match(up_nav) → final_exit
         let up_check = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: up_check,
-            nav: up_nav,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![final_exit],
-        }));
+        self.instructions
+            .push(MatchIR::epsilon(up_check, final_exit).nav(up_nav).into());
 
         // body: items with StayExact navigation → up_check
         // Items are compiled with StayExact because the skip-retry loop handles
@@ -198,16 +179,14 @@ impl Compiler<'_> {
         self.emit_wildcard_nav(down_wildcard, Nav::Down, try_label);
 
         // entry: match parent node → down_wildcard (only pre_effects here)
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: entry,
-            nav,
-            node_type,
-            node_field: None,
-            pre_effects: capture.pre,
-            neg_fields,
-            post_effects: vec![],
-            successors: vec![down_wildcard],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(entry, down_wildcard)
+                .nav(nav)
+                .node_type(node_type)
+                .neg_fields(neg_fields)
+                .pre_effects(capture.pre)
+                .into(),
+        );
 
         entry
     }
@@ -242,16 +221,14 @@ impl Compiler<'_> {
             self.resolve_anonymous_node_type(text)
         });
 
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: entry,
-            nav,
-            node_type,
-            node_field: None,
-            pre_effects: capture.pre,
-            neg_fields: vec![],
-            post_effects: capture.post,
-            successors: vec![exit],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(entry, exit)
+                .nav(nav)
+                .node_type(node_type)
+                .pre_effects(capture.pre)
+                .post_effects(capture.post)
+                .into(),
+        );
 
         entry
     }
@@ -359,16 +336,12 @@ impl Compiler<'_> {
             let value_entry = self.compile_expr_inner(&value, exit, None, capture);
 
             let entry = self.fresh_label();
-            self.instructions.push(Instruction::Match(MatchIR {
-                label: entry,
-                nav: nav_override.unwrap_or(Nav::Stay),
-                node_type: None,
-                node_field,
-                pre_effects: vec![],
-                neg_fields: vec![],
-                post_effects: vec![],
-                successors: vec![value_entry],
-            }));
+            self.instructions.push(
+                MatchIR::epsilon(entry, value_entry)
+                    .nav(nav_override.unwrap_or(Nav::Stay))
+                    .node_field(node_field)
+                    .into(),
+            );
             return entry;
         }
 
@@ -392,16 +365,11 @@ impl Compiler<'_> {
             // Fallback: wrap with field-checking Match for patterns that couldn't merge.
             // Use Stay since value was already compiled with navigation.
             let entry = self.fresh_label();
-            self.instructions.push(Instruction::Match(MatchIR {
-                label: entry,
-                nav: Nav::Stay,
-                node_type: None,
-                node_field: Some(field_id),
-                pre_effects: vec![],
-                neg_fields: vec![],
-                post_effects: vec![],
-                successors: vec![value_entry],
-            }));
+            self.instructions.push(
+                MatchIR::epsilon(entry, value_entry)
+                    .node_field(field_id)
+                    .into(),
+            );
             return entry;
         }
 
@@ -552,7 +520,7 @@ impl Compiler<'_> {
         };
 
         // SuppressEnd + outer capture effects → exit
-        let suppress_end = vec![EffectIR::simple(EffectOpcode::SuppressEnd, 0)];
+        let suppress_end = vec![EffectIR::suppress_end()];
         let end_label = self.emit_effects_epsilon(exit, suppress_end, outer_capture);
 
         // Compile inner → end_label (inner gets NO capture effects)
@@ -560,7 +528,7 @@ impl Compiler<'_> {
             self.compile_expr_inner(&inner, end_label, nav_override, CaptureEffects::default());
 
         // SuppressBegin → inner_entry
-        let suppress_begin = vec![EffectIR::simple(EffectOpcode::SuppressBegin, 0)];
+        let suppress_begin = vec![EffectIR::suppress_begin()];
         self.emit_effects_epsilon(inner_entry, suppress_begin, CaptureEffects::default())
     }
 
diff --git a/crates/plotnik-lib/src/compile/mod.rs b/crates/plotnik-lib/src/compile/mod.rs
index 1cb8497a..26708b0f 100644
--- a/crates/plotnik-lib/src/compile/mod.rs
+++ b/crates/plotnik-lib/src/compile/mod.rs
@@ -154,19 +154,14 @@ impl<'a> Compiler<'a> {
     fn emit_preamble(&mut self) -> Label {
         // Return (stack is empty after preamble, so this means Accept)
         let return_label = self.fresh_label();
-        self.instructions.push(Instruction::Return(ReturnIR {
-            label: return_label,
-        }));
+        self.instructions.push(ReturnIR::new(return_label).into());
 
         // Chain: Obj → Trampoline → EndObj → Return
         let endobj_label = self.emit_endobj_step(return_label);
 
         let trampoline_label = self.fresh_label();
         self.instructions
-            .push(Instruction::Trampoline(TrampolineIR {
-                label: trampoline_label,
-                next: endobj_label,
-            }));
+            .push(TrampolineIR::new(trampoline_label, endobj_label).into());
 
         self.emit_obj_step(trampoline_label)
     }
@@ -193,9 +188,7 @@ impl<'a> Compiler<'a> {
         // When stack is empty, Return means Accept (top-level match completed).
         // When stack is non-empty, Return pops frame and jumps to return address.
         let return_label = self.fresh_label();
-        self.instructions.push(Instruction::Return(ReturnIR {
-            label: return_label,
-        }));
+        self.instructions.push(ReturnIR::new(return_label).into());
 
         // Definition bodies use StayExact navigation: match at current position only.
         // The caller (alternation, sequence, quantifier, or VM top-level) owns the search.
diff --git a/crates/plotnik-lib/src/compile/quantifier.rs b/crates/plotnik-lib/src/compile/quantifier.rs
index 497852d9..50cc24d1 100644
--- a/crates/plotnik-lib/src/compile/quantifier.rs
+++ b/crates/plotnik-lib/src/compile/quantifier.rs
@@ -7,8 +7,8 @@
 //! - Whether skip/match need separate exits
 
 use crate::analyze::type_check::TypeId;
+use crate::bytecode::Nav;
 use crate::bytecode::ir::{EffectIR, Label};
-use crate::bytecode::{EffectOpcode, Nav};
 use crate::parser::ast::{self, Expr};
 use crate::parser::cst::SyntaxKind;
 
@@ -262,17 +262,14 @@ impl Compiler<'_> {
         let push_effects = CaptureEffects {
             pre: vec![],
             post: if self.quantifier_needs_node_for_push(inner) {
-                let opcode = if cap.has_string_annotation() {
-                    EffectOpcode::Text
+                let node_eff = if cap.has_string_annotation() {
+                    EffectIR::text()
                 } else {
-                    EffectOpcode::Node
+                    EffectIR::node()
                 };
-                vec![
-                    EffectIR::simple(opcode, 0),
-                    EffectIR::simple(EffectOpcode::Push, 0),
-                ]
+                vec![node_eff, EffectIR::push()]
             } else {
-                vec![EffectIR::simple(EffectOpcode::Push, 0)]
+                vec![EffectIR::push()]
             },
         };
         let inner_entry = self.compile_star_for_array_with_exits(
diff --git a/crates/plotnik-lib/src/compile/scope.rs b/crates/plotnik-lib/src/compile/scope.rs
index 0ad621aa..e643b325 100644
--- a/crates/plotnik-lib/src/compile/scope.rs
+++ b/crates/plotnik-lib/src/compile/scope.rs
@@ -5,7 +5,7 @@
 use std::num::NonZeroU16;
 
 use crate::analyze::type_check::TypeId;
-use crate::bytecode::ir::{CallIR, EffectIR, Instruction, Label, MatchIR, MemberRef};
+use crate::bytecode::ir::{CallIR, EffectIR, Label, MatchIR, MemberRef};
 use crate::bytecode::{EffectOpcode, Nav};
 use crate::parser::ast::Expr;
 
@@ -69,37 +69,25 @@ impl Compiler<'_> {
         capture_effects: Vec<EffectIR>,
         outer_capture: CaptureEffects,
     ) -> Label {
-        let mut end_effects = vec![EffectIR::simple(EffectOpcode::EndObj, 0)];
-        end_effects.extend(capture_effects);
-        end_effects.extend(outer_capture.post);
-
         let endobj_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: endobj_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: end_effects,
-            successors: vec![exit],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(endobj_step, exit)
+                .post_effect(EffectIR::end_obj())
+                .post_effects(capture_effects)
+                .post_effects(outer_capture.post)
+                .into(),
+        );
 
         let inner_entry = self.compile_with_optional_scope(scope_type_id, |this| {
             this.compile_expr_with_nav(inner, endobj_step, nav_override)
         });
 
         let obj_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: obj_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![EffectIR::simple(EffectOpcode::Obj, 0)],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![inner_entry],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(obj_step, inner_entry)
+                .pre_effect(EffectIR::start_obj())
+                .into(),
+        );
 
         obj_step
     }
@@ -130,16 +118,11 @@ impl Compiler<'_> {
                 exit
             } else {
                 let outer_step = self.fresh_label();
-                self.instructions.push(Instruction::Match(MatchIR {
-                    label: outer_step,
-                    nav: Nav::Stay,
-                    node_type: None,
-                    node_field: None,
-                    pre_effects: vec![],
-                    neg_fields: vec![],
-                    post_effects: outer_capture.post,
-                    successors: vec![exit],
-                }));
+                self.instructions.push(
+                    MatchIR::epsilon(outer_step, exit)
+                        .post_effects(outer_capture.post)
+                        .into(),
+                );
                 outer_step
             };
 
@@ -153,20 +136,13 @@ impl Compiler<'_> {
 
         // When scope_type_id is Some, we need Obj/EndObj to create the scope
         // EndObj step with ONLY outer_capture effects (like Push), NOT capture_effects
-        let mut end_effects = vec![EffectIR::simple(EffectOpcode::EndObj, 0)];
-        end_effects.extend(outer_capture.post);
-
         let endobj_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: endobj_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: end_effects,
-            successors: vec![exit],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(endobj_step, exit)
+                .post_effect(EffectIR::end_obj())
+                .post_effects(outer_capture.post)
+                .into(),
+        );
 
         // Compile inner WITH capture_effects on the match instruction
         // Note: pre effects don't propagate through Obj/EndObj scope wrapper
@@ -179,16 +155,11 @@ impl Compiler<'_> {
         });
 
         let obj_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: obj_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![EffectIR::simple(EffectOpcode::Obj, 0)],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![inner_entry],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(obj_step, inner_entry)
+                .pre_effect(EffectIR::start_obj())
+                .into(),
+        );
 
         obj_step
     }
@@ -206,37 +177,27 @@ impl Compiler<'_> {
         outer_capture: CaptureEffects,
         use_text_for_elements: bool,
     ) -> Label {
-        let mut end_effects = vec![EffectIR::simple(EffectOpcode::EndArr, 0)];
-        end_effects.extend(capture_effects);
-        end_effects.extend(outer_capture.post);
-
         let endarr_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: endarr_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: end_effects,
-            successors: vec![exit],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(endarr_step, exit)
+                .post_effect(EffectIR::end_arr())
+                .post_effects(capture_effects)
+                .post_effects(outer_capture.post)
+                .into(),
+        );
 
         let push_effects = CaptureEffects {
             pre: vec![],
             post: if self.quantifier_needs_node_for_push(inner) {
                 // Use Text if the capture has `:: string` annotation, else Node
-                let opcode = if use_text_for_elements {
-                    EffectOpcode::Text
+                let node_eff = if use_text_for_elements {
+                    EffectIR::text()
                 } else {
-                    EffectOpcode::Node
+                    EffectIR::node()
                 };
-                vec![
-                    EffectIR::simple(opcode, 0),
-                    EffectIR::simple(EffectOpcode::Push, 0),
-                ]
+                vec![node_eff, EffectIR::push()]
             } else {
-                vec![EffectIR::simple(EffectOpcode::Push, 0)]
+                vec![EffectIR::push()]
             },
         };
         let inner_entry = if let Expr::QuantifiedExpr(quant) = inner {
@@ -246,16 +207,11 @@ impl Compiler<'_> {
         };
 
         let arr_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: arr_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![EffectIR::simple(EffectOpcode::Arr, 0)],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![inner_entry],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(arr_step, inner_entry)
+                .pre_effect(EffectIR::start_arr())
+                .into(),
+        );
 
         arr_step
     }
@@ -273,19 +229,12 @@ impl Compiler<'_> {
     ) -> Label {
         // EndObj Push → exit
         let endobj_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: endobj_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![
-                EffectIR::simple(EffectOpcode::EndObj, 0),
-                EffectIR::simple(EffectOpcode::Push, 0),
-            ],
-            successors: vec![exit],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(endobj_step, exit)
+                .post_effect(EffectIR::end_obj())
+                .post_effect(EffectIR::push())
+                .into(),
+        );
 
         // Compile inner with row scope (for Set effects to work)
         let inner_entry = self.compile_with_optional_scope(row_type_id, |this| {
@@ -294,16 +243,11 @@ impl Compiler<'_> {
 
         // Obj → inner_entry
         let obj_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: obj_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![EffectIR::simple(EffectOpcode::Obj, 0)],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![inner_entry],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(obj_step, inner_entry)
+                .pre_effect(EffectIR::start_obj())
+                .into(),
+        );
 
         obj_step
     }
@@ -315,69 +259,47 @@ impl Compiler<'_> {
         outer_effects: &[EffectIR],
         exit: Label,
     ) -> Label {
-        let mut effects = vec![EffectIR::simple(EffectOpcode::EndArr, 0)];
-        effects.extend(capture_effects.iter().cloned());
-        effects.extend(outer_effects.iter().cloned());
-
         let label = self.fresh_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: effects,
-            successors: vec![exit],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(label, exit)
+                .post_effect(EffectIR::end_arr())
+                .post_effects(capture_effects.iter().cloned())
+                .post_effects(outer_effects.iter().cloned())
+                .into(),
+        );
         label
     }
 
     /// Emit an Obj epsilon step.
     pub(super) fn emit_obj_step(&mut self, successor: Label) -> Label {
         let label = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![EffectIR::simple(EffectOpcode::Obj, 0)],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![successor],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(label, successor)
+                .pre_effect(EffectIR::start_obj())
+                .into(),
+        );
         label
     }
 
     /// Emit an EndObj epsilon step.
     pub(super) fn emit_endobj_step(&mut self, successor: Label) -> Label {
         let label = self.fresh_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![EffectIR::simple(EffectOpcode::EndObj, 0)],
-            successors: vec![successor],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(label, successor)
+                .post_effect(EffectIR::end_obj())
+                .into(),
+        );
         label
     }
 
     /// Emit an Arr epsilon step.
     pub(super) fn emit_arr_step(&mut self, successor: Label) -> Label {
         let label = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![EffectIR::simple(EffectOpcode::Arr, 0)],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![successor],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(label, successor)
+                .pre_effect(EffectIR::start_arr())
+                .into(),
+        );
         label
     }
 
@@ -390,13 +312,12 @@ impl Compiler<'_> {
         target: Label,
     ) -> Label {
         let label = self.fresh_label();
-        self.instructions.push(Instruction::Call(CallIR {
-            label,
-            nav,
-            node_field,
-            next,
-            target,
-        }));
+        self.instructions.push(
+            CallIR::new(label, target, next)
+                .nav(nav)
+                .node_field(node_field)
+                .into(),
+        );
         label
     }
 
@@ -404,21 +325,16 @@ impl Compiler<'_> {
     pub(super) fn emit_effects_epsilon(
         &mut self,
         exit: Label,
-        mut effects: Vec<EffectIR>,
+        effects: Vec<EffectIR>,
         outer: CaptureEffects,
     ) -> Label {
-        effects.extend(outer.post);
         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: effects,
-            successors: vec![exit],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(entry, exit)
+                .post_effects(effects)
+                .post_effects(outer.post)
+                .into(),
+        );
         entry
     }
 
@@ -440,7 +356,7 @@ impl Compiler<'_> {
             .post
             .iter()
             .filter(|eff| eff.opcode == EffectOpcode::Set)
-            .flat_map(|set_eff| [EffectIR::simple(EffectOpcode::Null, 0), set_eff.clone()])
+            .flat_map(|set_eff| [EffectIR::null(), set_eff.clone()])
             .collect();
 
         if null_effects.is_empty() {
@@ -448,16 +364,11 @@ impl Compiler<'_> {
         }
 
         let null_step = self.fresh_label();
-        self.instructions.push(Instruction::Match(MatchIR {
-            label: null_step,
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: null_effects,
-            successors: vec![exit],
-        }));
+        self.instructions.push(
+            MatchIR::epsilon(null_step, exit)
+                .post_effects(null_effects)
+                .into(),
+        );
         null_step
     }
 
@@ -475,7 +386,7 @@ impl Compiler<'_> {
         let mut null_effects = Vec::new();
         for name in captures {
             if let Some(member_ref) = self.lookup_member_in_scope(&name) {
-                null_effects.push(EffectIR::simple(EffectOpcode::Null, 0));
+                null_effects.push(EffectIR::null());
                 null_effects.push(EffectIR::with_member(EffectOpcode::Set, member_ref));
             }
         }
@@ -513,16 +424,8 @@ impl Compiler<'_> {
     }
 
     fn push_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,
-        }));
+        self.instructions
+            .push(MatchIR::at(label).next_many(successors).into());
     }
 
     /// Emit a wildcard navigation step that accepts any node.
@@ -531,16 +434,8 @@ impl Compiler<'_> {
     /// and matches any node there. If navigation fails (no more siblings/children),
     /// the VM backtracks automatically.
     pub(super) fn emit_wildcard_nav(&mut self, label: Label, nav: Nav, successor: Label) {
-        self.instructions.push(Instruction::Match(MatchIR {
-            label,
-            nav,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![successor],
-        }));
+        self.instructions
+            .push(MatchIR::epsilon(label, successor).nav(nav).into());
     }
 
     /// Emit an epsilon branch preferring `prefer` when greedy, `other` when non-greedy.
diff --git a/crates/plotnik-lib/src/compile/sequences.rs b/crates/plotnik-lib/src/compile/sequences.rs
index a92fe104..57ad1b99 100644
--- a/crates/plotnik-lib/src/compile/sequences.rs
+++ b/crates/plotnik-lib/src/compile/sequences.rs
@@ -256,11 +256,11 @@ impl Compiler<'_> {
                         MemberRef::deferred_by_index(type_id, variant_idx),
                     )
                 } else {
-                    EffectIR::simple(EffectOpcode::Enum, 0)
+                    EffectIR::start_enum()
                 };
 
                 // Build capture effects: Enum as pre, EndEnum + outer as post
-                let mut post_effects = vec![EffectIR::simple(EffectOpcode::EndEnum, 0)];
+                let mut post_effects = vec![EffectIR::end_enum()];
                 post_effects.extend(capture.post.iter().cloned());
 
                 let branch_capture = CaptureEffects {
@@ -287,7 +287,7 @@ impl Compiler<'_> {
                             })
                             .flat_map(|(idx, _)| {
                                 [
-                                    EffectIR::simple(EffectOpcode::Null, 0),
+                                    EffectIR::null(),
                                     EffectIR::with_member(
                                         EffectOpcode::Set,
                                         MemberRef::deferred_by_index(alt_type, idx as u16),
diff --git a/crates/plotnik-lib/src/emit/layout_tests.rs b/crates/plotnik-lib/src/emit/layout_tests.rs
index 5656ce7b..347eb6b0 100644
--- a/crates/plotnik-lib/src/emit/layout_tests.rs
+++ b/crates/plotnik-lib/src/emit/layout_tests.rs
@@ -1,9 +1,8 @@
 use std::num::NonZeroU16;
 
 use super::layout::CacheAligned;
-use crate::bytecode::EffectOpcode;
 use crate::bytecode::Nav;
-use crate::bytecode::ir::{CallIR, EffectIR, Instruction, Label, MatchIR, ReturnIR};
+use crate::bytecode::ir::{CallIR, EffectIR, Label, MatchIR, ReturnIR};
 
 #[test]
 fn layout_empty() {
@@ -15,16 +14,12 @@ fn layout_empty() {
 
 #[test]
 fn layout_single_instruction() {
-    let instructions = vec![Instruction::Match(MatchIR {
-        label: Label(0),
-        nav: Nav::Down,
-        node_type: NonZeroU16::new(10),
-        node_field: None,
-        pre_effects: vec![],
-        neg_fields: vec![],
-        post_effects: vec![],
-        successors: vec![], // Terminal - empty successors
-    })];
+    let instructions = vec![
+        MatchIR::terminal(Label(0))
+            .nav(Nav::Down)
+            .node_type(NonZeroU16::new(10))
+            .into(),
+    ];
 
     let result = CacheAligned::layout(&instructions, &[Label(0)]);
 
@@ -36,36 +31,17 @@ fn layout_single_instruction() {
 fn layout_linear_chain() {
     // A -> B -> C -> ACCEPT
     let instructions = vec![
-        Instruction::Match(MatchIR {
-            label: Label(0),
-            nav: Nav::Down,
-            node_type: NonZeroU16::new(10),
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![Label(1)],
-        }),
-        Instruction::Match(MatchIR {
-            label: Label(1),
-            nav: Nav::Next,
-            node_type: NonZeroU16::new(20),
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![Label(2)],
-        }),
-        Instruction::Match(MatchIR {
-            label: Label(2),
-            nav: Nav::Up(1),
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![], // Terminal
-        }),
+        MatchIR::at(Label(0))
+            .nav(Nav::Down)
+            .node_type(NonZeroU16::new(10))
+            .next(Label(1))
+            .into(),
+        MatchIR::at(Label(1))
+            .nav(Nav::Next)
+            .node_type(NonZeroU16::new(20))
+            .next(Label(2))
+            .into(),
+        MatchIR::terminal(Label(2)).nav(Nav::Up(1)).into(),
     ];
 
     let result = CacheAligned::layout(&instructions, &[Label(0)]);
@@ -80,44 +56,21 @@ fn layout_linear_chain() {
 fn layout_call_return() {
     // Entry -> Call(target=2) -> Return
     let instructions = vec![
-        Instruction::Match(MatchIR {
-            label: Label(0),
-            nav: Nav::Down,
-            node_type: NonZeroU16::new(10),
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![Label(1)],
-        }),
-        Instruction::Call(CallIR {
-            label: Label(1),
-            nav: Nav::Down,
-            node_field: None,
-            next: Label(3),
-            target: Label(2),
-        }),
-        Instruction::Match(MatchIR {
-            label: Label(2),
-            nav: Nav::Down,
-            node_type: NonZeroU16::new(20),
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![Label(4)],
-        }),
-        Instruction::Match(MatchIR {
-            label: Label(3),
-            nav: Nav::Up(1),
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![], // Terminal
-        }),
-        Instruction::Return(ReturnIR { label: Label(4) }),
+        MatchIR::at(Label(0))
+            .nav(Nav::Down)
+            .node_type(NonZeroU16::new(10))
+            .next(Label(1))
+            .into(),
+        CallIR::new(Label(1), Label(2), Label(3))
+            .nav(Nav::Down)
+            .into(),
+        MatchIR::at(Label(2))
+            .nav(Nav::Down)
+            .node_type(NonZeroU16::new(20))
+            .next(Label(4))
+            .into(),
+        MatchIR::terminal(Label(3)).nav(Nav::Up(1)).into(),
+        ReturnIR::new(Label(4)).into(),
     ];
 
     let result = CacheAligned::layout(&instructions, &[Label(0)]);
@@ -134,36 +87,17 @@ fn layout_call_return() {
 fn layout_branch() {
     // Entry -> [A, B] -> ACCEPT
     let instructions = vec![
-        Instruction::Match(MatchIR {
-            label: Label(0),
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![Label(1), Label(2)],
-        }),
-        Instruction::Match(MatchIR {
-            label: Label(1),
-            nav: Nav::Down,
-            node_type: NonZeroU16::new(10),
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![], // Terminal
-        }),
-        Instruction::Match(MatchIR {
-            label: Label(2),
-            nav: Nav::Down,
-            node_type: NonZeroU16::new(20),
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![], // Terminal
-        }),
+        MatchIR::at(Label(0))
+            .next_many(vec![Label(1), Label(2)])
+            .into(),
+        MatchIR::terminal(Label(1))
+            .nav(Nav::Down)
+            .node_type(NonZeroU16::new(10))
+            .into(),
+        MatchIR::terminal(Label(2))
+            .nav(Nav::Down)
+            .node_type(NonZeroU16::new(20))
+            .into(),
     ];
 
     let result = CacheAligned::layout(&instructions, &[Label(0)]);
@@ -182,24 +116,17 @@ fn layout_branch() {
 fn layout_large_instruction_cache_alignment() {
     // Large instruction (Match48 = 48 bytes = 6 steps) near cache line boundary
     // Start at step 5 (offset 40), would straddle - should pad
-    let large_match = MatchIR {
-        label: Label(1),
-        nav: Nav::Down,
-        node_type: NonZeroU16::new(10),
-        node_field: None,
-        pre_effects: vec![
-            EffectIR::simple(EffectOpcode::Obj, 0),
-            EffectIR::simple(EffectOpcode::Obj, 0),
-            EffectIR::simple(EffectOpcode::Obj, 0),
-        ],
-        neg_fields: vec![],
-        post_effects: vec![
-            EffectIR::simple(EffectOpcode::Node, 0),
-            EffectIR::simple(EffectOpcode::EndObj, 0),
-            EffectIR::simple(EffectOpcode::EndObj, 0),
-            EffectIR::simple(EffectOpcode::EndObj, 0),
-        ],
-        successors: vec![
+    let large_match = MatchIR::at(Label(1))
+        .nav(Nav::Down)
+        .node_type(NonZeroU16::new(10))
+        .pre_effect(EffectIR::start_obj())
+        .pre_effect(EffectIR::start_obj())
+        .pre_effect(EffectIR::start_obj())
+        .post_effect(EffectIR::node())
+        .post_effect(EffectIR::end_obj())
+        .post_effect(EffectIR::end_obj())
+        .post_effect(EffectIR::end_obj())
+        .next_many(vec![
             Label(100),
             Label(101),
             Label(102),
@@ -208,25 +135,15 @@ fn layout_large_instruction_cache_alignment() {
             Label(105),
             Label(106),
             Label(107),
-        ],
-    };
+        ]);
 
     // Verify it's large enough to trigger alignment
     assert!(large_match.size() >= 48);
 
     let instructions = vec![
         // Small instruction first
-        Instruction::Match(MatchIR {
-            label: Label(0),
-            nav: Nav::Stay,
-            node_type: None,
-            node_field: None,
-            pre_effects: vec![],
-            neg_fields: vec![],
-            post_effects: vec![],
-            successors: vec![Label(1)],
-        }),
-        Instruction::Match(large_match),
+        MatchIR::epsilon(Label(0), Label(1)).into(),
+        large_match.into(),
     ];
 
     let result = CacheAligned::layout(&instructions, &[Label(0)]);