diff --git a/docs/wip/bytecode.md b/docs/binary-format/07-dump-format.md
similarity index 100%
rename from docs/wip/bytecode.md
rename to docs/binary-format/07-dump-format.md
diff --git a/docs/wip/anchor-restrictions.md b/docs/wip/anchor-restrictions.md
deleted file mode 100644
index f3557ee7..00000000
--- a/docs/wip/anchor-restrictions.md
+++ /dev/null
@@ -1,317 +0,0 @@
-# Anchor Restrictions Implementation Plan
-
-## Problem Statement
-
-Anchors (`.`) are parsed but:
-1. **Ignored in bytecode** - compiler drops anchors entirely
-2. **Create garbage in alternations** - `[(a) . (b)]` creates empty branches
-3. **No semantic validation** - boundary anchors without context are silently accepted
-
-## Current Behavior (CLI Tests)
-
-| Pattern | Parser | AST | Should Be |
-|---------|--------|-----|-----------|
-| `Q = . (a)` | Two defs created, error | Anchor absorbed | Error: anchor at def level |
-| `Q = {. (a)}` | ✓ Parses | ✓ Anchor in Seq | Error: boundary without context |
-| `Q = {(a) . (b)}` | ✓ Parses | ✓ Anchor between | ✓ Valid |
-| `Q = (p . (a))` | ✓ Parses | ✓ In node | ✓ Valid |
-| `Q = [(a) . (b)]` | ⚠️ Parses | Empty branch created! | Error: anchor in alternation |
-
-## Two-Level Solution
-
-### Level 1: Parser — Reject Anchors in Alternations
-
-**Problem**: In `parse_alt_children()`, anchors create empty branches because `.` is in `EXPR_FIRST_TOKENS` but produces an `Anchor` node, not an expression.
-
-**Fix**: In `structures.rs:parse_alt_children()`, check for `Dot` before `EXPR_FIRST_TOKENS` and emit error.
-
-**File**: `crates/plotnik-lib/src/parser/grammar/structures.rs`
-
-```rust
-// In parse_alt_children(), before line 280:
-if self.currently_is(SyntaxKind::Dot) {
-    let span = self.current_span();
-    self.diagnostics
-        .report(self.source_id, DiagnosticKind::AnchorInAlternation, span)
-        .emit();
-    self.skip_token();  // Skip the dot, don't create empty branch
-    continue;
-}
-if self.currently_is_one_of(EXPR_FIRST_TOKENS) {
-    // ... existing code
-}
-```
-
-**New Diagnostic** in `diagnostics/message.rs`:
-```rust
-// Add after InvalidSeparator (line 34):
-AnchorInAlternation,
-
-// In fallback_message():
-Self::AnchorInAlternation => "anchors cannot appear directly in alternations",
-
-// In default_hint():
-Self::AnchorInAlternation => Some("use `[{(a) . (b)} (c)]` to anchor within a branch"),
-```
-
-**Error output**:
-```
-error: anchors cannot appear directly in alternations
-  |
-1 | Q = [(a) . (b)]
-  |          ^
-  |
-help: use `[{(a) . (b)} (c)]` to anchor within a branch
-```
-
----
-
-### Level 2: Analyzer — Validate Anchor Context
-
-**Problem**: `{. (a)}` at definition level parses correctly but is semantically invalid — boundary anchors need parent node context.
-
-**Rule**:
-- **Boundary anchors** (position 0 or last in sequence) require parent named node context
-- **Interior anchors** (between items) are always valid
-- **Named node children** always have context (the node provides it)
-
-**New File**: `crates/plotnik-lib/src/query/anchors.rs`
-
-```rust
-//! Semantic validation for anchor placement.
-
-use super::visitor::{Visitor, walk, walk_named_node, walk_seq_expr};
-use crate::SourceId;
-use crate::diagnostics::{DiagnosticKind, Diagnostics};
-use crate::parser::ast::{NamedNode, SeqExpr, SeqItem, Root};
-
-pub fn validate_anchors(source_id: SourceId, ast: &Root, diag: &mut Diagnostics) {
-    let mut visitor = AnchorValidator {
-        diag,
-        source_id,
-        in_named_node: false,
-    };
-    visitor.visit(ast);
-}
-
-struct AnchorValidator<'a> {
-    diag: &'a mut Diagnostics,
-    source_id: SourceId,
-    in_named_node: bool,
-}
-
-impl Visitor for AnchorValidator<'_> {
-    fn visit_named_node(&mut self, node: &NamedNode) {
-        let prev = self.in_named_node;
-        self.in_named_node = true;
-
-        // Anchors inside named node children are always valid
-        // (the node provides first/last/adjacent context)
-        walk_named_node(self, node);
-
-        self.in_named_node = prev;
-    }
-
-    fn visit_seq_expr(&mut self, seq: &SeqExpr) {
-        let items: Vec<_> = seq.items().collect();
-        let len = items.len();
-
-        for (i, item) in items.iter().enumerate() {
-            if let SeqItem::Anchor(anchor) = item {
-                let is_boundary = i == 0 || i == len - 1;
-
-                if is_boundary && !self.in_named_node {
-                    self.diag
-                        .report(
-                            self.source_id,
-                            DiagnosticKind::AnchorWithoutContext,
-                            anchor.text_range(),
-                        )
-                        .emit();
-                }
-            }
-        }
-
-        walk_seq_expr(self, seq);
-    }
-}
-```
-
-**New Diagnostic** in `diagnostics/message.rs`:
-```rust
-// Add after AnchorInAlternation:
-AnchorWithoutContext,
-
-// In fallback_message():
-Self::AnchorWithoutContext => "boundary anchor requires parent node context",
-
-// In default_hint():
-Self::AnchorWithoutContext => Some("wrap in a named node: `(parent . (child))`"),
-```
-
-**Error output**:
-```
-error: boundary anchor requires parent node context
-  |
-1 | Q = {. (a)}
-  |      ^
-  |
-help: wrap in a named node: `(parent . (child))`
-```
-
-**Integration** in `query/query.rs` (after line 75):
-```rust
-validate_alt_kinds(source.id, &res.ast, &mut diag);
-validate_anchors(source.id, &res.ast, &mut diag);  // NEW
-```
-
----
-
-## Valid vs Invalid Patterns (Final)
-
-| Pattern | Valid? | Reason |
-|---------|--------|--------|
-| `Q = . (a)` | ❌ | Parser: creates separate def (existing behavior) |
-| `Q = {. (a)}` | ❌ | Analyzer: boundary without context |
-| `Q = {(a) .}` | ❌ | Analyzer: boundary without context |
-| `Q = {(a) . (b)}` | ✓ | Interior anchor, both sides defined |
-| `Q = (p . (a))` | ✓ | Inside node, first child anchor |
-| `Q = (p (a) .)` | ✓ | Inside node, last child anchor |
-| `Q = (p (a) . (b))` | ✓ | Inside node, adjacent siblings |
-| `Q = (p {. (a)})` | ✓ | Seq inside node, context from p |
-| `Q = (p {(a) . (b)})` | ✓ | Interior anchor in nested seq |
-| `Q = [(a) . (b)]` | ❌ | Parser: anchor in alternation |
-| `Q = [{(a) . (b)} (c)]` | ✓ | Anchor inside seq branch |
-
----
-
-## Documentation Update
-
-Update `docs/lang-reference.md` section "## Anchors" to add:
-
-```markdown
-### Anchor Placement Rules
-
-Anchors require context to be meaningful:
-
-**Valid positions:**
-- Inside a named node's children: `(parent . (first))`, `(parent (a) . (b))`
-- Between items in a sequence inside a node: `(parent {(a) . (b)})`
-
-**Invalid positions:**
-- At definition level: `Q = . (a)` ❌
-- At sequence boundaries without parent node: `Q = {. (a)}` ❌
-- Directly in alternations: `Q = [(a) . (b)]` ❌
-
-The rule: **boundary anchors need a parent named node to provide context**
-(first child, last child, or adjacent sibling semantics).
-
-Interior anchors (between sequence items) are always valid because both sides
-are explicitly defined.
-```
-
----
-
-## Files to Modify
-
-### Parser Level
-1. `crates/plotnik-lib/src/parser/grammar/structures.rs` — Check for Dot before EXPR_FIRST_TOKENS in alternation parsing
-2. `crates/plotnik-lib/src/diagnostics/message.rs` — Add `AnchorInAlternation`
-3. `crates/plotnik-lib/src/parser/tests/` — Add tests for anchor-in-alt error
-
-### Analyzer Level
-4. `crates/plotnik-lib/src/query/anchors.rs` — NEW: semantic validation
-5. `crates/plotnik-lib/src/query/anchors_tests.rs` — NEW: tests
-6. `crates/plotnik-lib/src/query/mod.rs` — Export anchors module
-7. `crates/plotnik-lib/src/query/query.rs` — Call `validate_anchors()`
-8. `crates/plotnik-lib/src/diagnostics/message.rs` — Add `AnchorWithoutContext`
-
-### Documentation
-9. `docs/lang-reference.md` — Add "Anchor Placement Rules" section
-
----
-
-## Test Cases
-
-### Parser Tests (`parser/tests/recovery/anchors_tests.rs`)
-
-```rust
-#[test]
-fn anchor_in_alternation_error() {
-    let input = "Q = [(a) . (b)]";
-    let res = Query::expect_invalid(input);
-    insta::assert_snapshot!(res.dump_diagnostics(), @r#"
-    error: anchors cannot appear directly in alternations
-      |
-    1 | Q = [(a) . (b)]
-      |          ^
-      |
-    help: use `[{(a) . (b)} (c)]` to anchor within a branch
-    "#);
-}
-
-#[test]
-fn anchor_in_seq_inside_alt_ok() {
-    let input = "Q = [{(a) . (b)} (c)]";
-    let _ = Query::expect_valid_ast(input);
-}
-```
-
-### Analyzer Tests (`query/anchors_tests.rs`)
-
-```rust
-#[test]
-fn boundary_anchor_without_context() {
-    let input = "Q = {. (a)}";
-    let res = Query::expect_invalid(input);
-    insta::assert_snapshot!(res.dump_diagnostics(), @r#"
-    error: boundary anchor requires parent node context
-      |
-    1 | Q = {. (a)}
-      |      ^
-      |
-    help: wrap in a named node: `(parent . (child))`
-    "#);
-}
-
-#[test]
-fn boundary_anchor_with_context_ok() {
-    let input = "Q = (parent {. (a)})";
-    let _ = Query::expect_valid_ast(input);
-}
-
-#[test]
-fn interior_anchor_always_valid() {
-    let input = "Q = {(a) . (b)}";
-    let _ = Query::expect_valid_ast(input);
-}
-
-#[test]
-fn anchor_in_named_node_ok() {
-    let input = "Q = (parent . (first) (second) .)";
-    let _ = Query::expect_valid_ast(input);
-}
-```
-
----
-
-## Implementation Order
-
-1. **Parser fix** (30 min): Add `AnchorInAlternation` diagnostic, check in `parse_alt_children()`
-2. **Analyzer validation** (45 min): Create `anchors.rs`, add `AnchorWithoutContext`, integrate
-3. **Tests** (30 min): Add parser and analyzer tests
-4. **Documentation** (15 min): Update lang-reference.md
-
-Total: ~2 hours
-
----
-
-## Future Work (Not in Scope)
-
-After anchor restrictions are in place, the next step is implementing anchor **compilation**:
-- Use `items()` instead of `children()` in compiler
-- Fix sibling navigation (Down → Next for non-first children)
-- Generate `NextSkip`/`NextExact`/`DownSkip`/`DownExact` based on anchor presence
-- Handle `UpExact`/`UpSkipTrivia` for last-child anchors
-
-This is tracked separately as bytecode emission work.
diff --git a/docs/wip/bytecode-linking.md b/docs/wip/bytecode-linking.md
deleted file mode 100644
index 8a6d5c97..00000000
--- a/docs/wip/bytecode-linking.md
+++ /dev/null
@@ -1,196 +0,0 @@
-# Bytecode Linking Design
-
-## Scope
-
-**Design** the bytecode format to support future post-compilation linking, but **implement only**:
-- Emit linked bytecode (current behavior)
-- Emit unlinked bytecode (new: StringIds in instructions)
-- CLI dumps both for debugging
-- Runtime executes only linked bytecode, rejects unlinked
-
-**NOT implementing**: Actual relinking logic. The format supports it; we don't use it yet.
-
-## Chosen Design: Header Flag + StringId References
-
-**Key insight**: `StringId` and `NodeTypeId` are both `u16`. Instructions always store a `u16` in bytes 2-3 (node_type) and 4-5 (node_field). A header flag indicates how to interpret them.
-
-### StringId(0) Reservation
-
-Since `0` means "no constraint" (wildcard) in instruction bytes, `StringId(0)` can never be referenced by instructions. Reserve it as an easter egg:
-
-```
-strings[0] = "Beauty will save the world"   // Dostoevsky, The Idiot
-strings[1] = first actual string
-strings[2] = second actual string
-...
-```
-
-Actual string references use 1-based indices. The easter egg sits at index 0, visible to anyone who hexdumps the bytecode.
-
-### Unlinked Bytecode
-```
-Header: linked = false
-Match instruction bytes 2-3: StringId (index into string table)
-Match instruction bytes 4-5: StringId (index into string table)
-node_types section: empty (reserved)
-node_fields section: empty (reserved)
-```
-
-### Linked Bytecode (emitted via `LinkedQuery::emit()`)
-```
-Header: linked = true
-Match instruction bytes 2-3: NodeTypeId (grammar ID)
-Match instruction bytes 4-5: NodeFieldId (grammar ID)
-node_types section: [(NodeTypeId, StringId), ...] for verification
-node_fields section: [(NodeFieldId, StringId), ...] for verification
-```
-
-### Runtime Behavior
-- If `linked = false`: reject execution, require linking first
-- If `linked = true`: execute directly, optionally verify symbol tables match loaded grammar
-
----
-
-## Current Architecture
-
-### Compilation Flow
-```
-Query → Parse → Analyze → [Link against grammar] → Compile → Emit bytecode
-                              ↓
-                         node_type_ids: HashMap<Symbol, NodeTypeId>
-                         node_field_ids: HashMap<Symbol, NodeFieldId>
-```
-
-### Key Structures
-
-**MatchIR** (`bytecode/ir.rs:74-93`):
-```rust
-pub struct MatchIR {
-    pub node_type: Option<NonZeroU16>,  // Already numeric (tree-sitter ID)
-    pub node_field: Option<NonZeroU16>, // Already numeric
-    pub successors: Vec<Label>,         // Symbolic, resolved at emit
-    // ...
-}
-```
-
-**Match instruction wire format** (8 bytes minimum):
-```
-[0]   opcode + segment
-[1]   nav command
-[2-3] node_type (u16 LE, 0 = wildcard)  ← Target for relinking
-[4-5] node_field (u16 LE, 0 = wildcard) ← Target for relinking
-[6-7] next StepId or counts
-```
-
-### Two Emit Paths
-
-| Path | `node_type_ids` | Result |
-|------|-----------------|--------|
-| `QueryAnalyzed::emit()` | `None` | All node_type/field = 0 (wildcard) |
-| `LinkedQuery::emit()` | `Some(HashMap)` | Actual grammar IDs |
-
-## Implementation Plan
-
-### 1. Header Flag
-
-Add `linked: bool` flag to `Header` struct:
-
-```rust
-// In bytecode/mod.rs or bytecode/header.rs
-pub struct Header {
-    // ... existing fields ...
-    pub flags: u16,  // bit 0 = linked
-}
-
-impl Header {
-    pub fn is_linked(&self) -> bool {
-        self.flags & 0x01 != 0
-    }
-}
-```
-
-### 2. StringTableBuilder: Reserve Index 0
-
-```rust
-impl StringTableBuilder {
-    pub fn new() -> Self {
-        let mut builder = Self { strings: Vec::new(), ... };
-        // Reserve index 0 for easter egg
-        builder.strings.push("Beauty will save the world".to_string());
-        builder
-    }
-
-    pub fn get_or_intern(&mut self, ...) -> StringId {
-        // Indices now start at 1
-        let id = StringId((self.strings.len()) as u16);  // No +1 needed, index 0 already occupied
-        // ...
-    }
-}
-```
-
-### 3. Compiler: Store StringId When Unlinked
-
-Modify `Compiler` to accept a "linked" flag and store `StringId` in unlinked mode:
-
-```rust
-fn resolve_node_type(&self, node: &ast::NamedNode) -> Option<NonZeroU16> {
-    let type_name = node.node_type()?.text();
-
-    if self.linked {
-        // Current behavior: resolve to NodeTypeId
-        self.node_type_ids?.get(type_name).map(|id| NonZeroU16::new(id.get()))
-    } else {
-        // New: store StringId instead
-        let string_id = self.strings.get_or_intern(type_name);
-        NonZeroU16::new(string_id.0)
-    }
-}
-```
-
-### 4. Emit Paths
-
-| Method | `linked` flag | Instructions contain | Symbol sections |
-|--------|---------------|---------------------|-----------------|
-| `QueryAnalyzed::emit()` | `false` | StringId | empty |
-| `LinkedQuery::emit()` | `true` | NodeTypeId | populated |
-
-### 5. CLI: Dump Both Formats
-
-`debug --bytecode` should display:
-- Header linked flag
-- For unlinked: show string names from StringId
-- For linked: show grammar IDs with resolved names from symbol sections
-
-### 6. Runtime: Reject Unlinked
-
-```rust
-fn load_bytecode(bytes: &[u8]) -> Result<Runtime, Error> {
-    let header = Header::from_bytes(&bytes[..64]);
-    if !header.is_linked() {
-        return Err(Error::UnlinkedBytecode);
-    }
-    // ... continue loading
-}
-```
-
-Future work (NOT now): Implement `link_bytecode()` that walks transitions and resolves StringIds.
-
-## Files to Modify
-
-| File | Changes |
-|------|---------|
-| `bytecode/mod.rs` | Add `flags` field to `Header`, `is_linked()` method |
-| `query/emit.rs` | Reserve StringId(0) easter egg, set linked flag |
-| `query/compile.rs` | Store StringId when unlinked (needs access to StringTableBuilder) |
-| `plotnik-cli/src/commands/debug/mod.rs` | Display linked flag, decode instructions appropriately |
-| `bytecode/dump.rs` | Update dump logic for linked/unlinked awareness |
-
-## Documentation Updates
-
-| File | Changes |
-|------|---------|
-| `docs/binary-format/01-overview.md` | Add `flags` field to header layout, document linked bit |
-| `docs/binary-format/02-header.md` | Document `flags` field, `is_linked` semantics |
-| `docs/binary-format/03-strings.md` | Document StringId(0) reservation (easter egg) |
-| `docs/binary-format/06-transitions.md` | Clarify bytes 2-5 meaning differs based on linked flag |
-| `docs/wip/bytecode.md` | Update WIP notes on linking design |
diff --git a/docs/wip/grammar-verify.md b/docs/wip/grammar-verify.md
deleted file mode 100644
index ac037ec2..00000000
--- a/docs/wip/grammar-verify.md
+++ /dev/null
@@ -1,296 +0,0 @@
-# Grammar-Based Query Validation
-
-Validate that query structural patterns (sequences, anchors, parent-child relationships) are actually derivable from the grammar's production rules.
-
-## Problem Statement
-
-Current validation uses `node-types.json`, which is a **lossy summary**:
-
-```json
-{
-  "type": "function_declaration",
-  "fields": {
-    "name": { "types": [{"type": "identifier"}] },
-    "body": { "types": [{"type": "statement_block"}] }
-  }
-}
-```
-
-This tells you "identifier can be a child" but loses **sequence information**.
-
-The actual grammar (`grammar.json`) has production rules:
-
-```json
-{
-  "type": "SEQ",
-  "members": [
-    {"type": "CHOICE", "members": [{"type": "STRING", "value": "async"}, {"type": "BLANK"}]},
-    {"type": "STRING", "value": "function"},
-    {"type": "FIELD", "name": "name", "content": {"type": "SYMBOL", "name": "identifier"}},
-    {"type": "SYMBOL", "name": "_call_signature"},
-    {"type": "FIELD", "name": "body", "content": {"type": "SYMBOL", "name": "statement_block"}}
-  ]
-}
-```
-
-**Query**: `(function_declaration . (identifier) @name)` — first-child anchor on identifier
-
-**Reality**: First children are `"async"` (optional) then `"function"` keyword. Identifier is 3rd.
-
-**Verdict**: Pattern is **structurally impossible**. But `node-types.json` can't detect this.
-
-## Grammar JSON Structure
-
-Tree-sitter's `grammar.json` uses these combinators:
-
-| Type | Meaning |
-|------|---------|
-| `SEQ` | Sequence of members (order matters) |
-| `CHOICE` | Alternatives (any branch) |
-| `REPEAT` | Zero or more (`*`) |
-| `REPEAT1` | One or more (`+`) |
-| `SYMBOL` | Reference to another rule |
-| `STRING` | Literal token (becomes anonymous node) |
-| `PATTERN` | Regex for token |
-| `FIELD` | Named child |
-| `BLANK` | Epsilon (empty) |
-| `PREC` / `PREC_LEFT` / `PREC_RIGHT` | Precedence wrappers |
-| `ALIAS` | Rename a node |
-| `TOKEN` / `IMMEDIATE_TOKEN` | Tokenization control |
-
-### Example: `array`
-
-```json
-{
-  "type": "SEQ",
-  "members": [
-    {"type": "STRING", "value": "["},
-    {"type": "CHOICE", "members": [
-      {"type": "SEQ", "members": [
-        {"type": "CHOICE", "members": [{"type": "SYMBOL", "name": "expression"}, {"type": "BLANK"}]},
-        {"type": "REPEAT", "content": {"type": "SEQ", "members": [
-          {"type": "STRING", "value": ","},
-          {"type": "CHOICE", "members": [{"type": "SYMBOL", "name": "expression"}, {"type": "BLANK"}]}
-        ]}}
-      ]},
-      {"type": "BLANK"}
-    ]},
-    {"type": "STRING", "value": "]"}
-  ]
-}
-```
-
-Query `(array . (identifier))` with first-child anchor: **impossible** — `"["` is always first.
-
-## Proposed Architecture
-
-```
-┌─────────────────┐
-│  grammar.json   │
-└────────┬────────┘
-         ▼
-┌─────────────────┐
-│ Grammar IR      │  Parse SEQ/CHOICE/REPEAT/FIELD/SYMBOL/STRING/BLANK
-└────────┬────────┘
-         ▼
-┌─────────────────┐
-│ Visibility      │  Which elements produce visible tree nodes?
-│ Analysis        │  - SYMBOL(name) → visible if not `_` prefixed
-│                 │  - STRING("x") → anonymous node (visible)
-│                 │  - _hidden_rule → inline its children
-└────────┬────────┘
-         ▼
-┌─────────────────┐
-│ Child Sequence  │  For each node type, build NFA accepting
-│ NFA             │  valid child sequences
-└────────┬────────┘
-         ▼
-┌─────────────────┐
-│ Pattern Match   │  Query pattern → path constraints
-│                 │  Check: ∃ path through NFA matching pattern?
-└─────────────────┘
-```
-
-### 1. Grammar IR
-
-```rust
-enum GrammarExpr {
-    Seq(Vec<GrammarExpr>),
-    Choice(Vec<GrammarExpr>),
-    Repeat(Box<GrammarExpr>),      // *
-    Repeat1(Box<GrammarExpr>),     // +
-    Optional(Box<GrammarExpr>),    // implicit from CHOICE with BLANK
-    Symbol(String),                 // reference to rule
-    String(String),                 // literal token
-    Pattern(String),                // regex token
-    Field { name: String, content: Box<GrammarExpr> },
-    Blank,                          // epsilon
-    Prec { value: i32, content: Box<GrammarExpr> },
-    Alias { value: String, content: Box<GrammarExpr> },
-}
-```
-
-### 2. Visibility Analysis
-
-Determine which grammar elements produce visible tree nodes:
-
-- **Named rules** (`identifier`, `function_declaration`): Produce named nodes
-- **Hidden rules** (`_call_signature`, `_expression`): Inlined, don't produce nodes themselves
-- **STRING values** (`"function"`, `"["`): Produce anonymous nodes
-- **FIELD**: Just names a child, doesn't affect visibility
-
-Hidden rules must be recursively inlined to get the actual child sequence.
-
-### 3. Child Sequence NFA
-
-For each visible node type, build an NFA:
-
-- **States**: Positions in the flattened production rule
-- **Transitions**: Node types (named and anonymous)
-- **CHOICE**: ε-transitions to each branch
-- **REPEAT**: Loop transition back to start state
-- **BLANK**: ε-transition to next state
-
-Example for `function_declaration`:
-
-```
-[0] ──"async"?──► [1] ──"function"──► [2] ──identifier──► [3] ──(params)──► [4] ──statement_block──► [5]
-     └──────ε──────┘
-```
-
-### 4. Pattern Matching
-
-Query patterns become path constraints on the NFA:
-
-- **Regular child**: Must match a transition
-- **Gap (no anchor)**: Allow any path between
-- **First-child anchor (`. x`)**: x must be reachable from start with no prior named nodes
-- **Last-child anchor (`x .`)**: x must reach accepting state with no following named nodes
-- **Adjacent anchor (`x . y`)**: y immediately follows x (no intermediate named transitions)
-
-### 5. Validation Algorithm
-
-```
-fn validate_sequence(parent: NodeTypeId, pattern: &QueryPattern) -> Result<(), Diagnostic> {
-    let nfa = build_nfa(parent);
-    let constraints = pattern_to_constraints(pattern);
-
-    if !nfa.satisfies(constraints) {
-        return Err(Diagnostic::ImpossibleSequence {
-            parent,
-            pattern,
-            reason: explain_failure(nfa, constraints),
-        });
-    }
-    Ok(())
-}
-```
-
-## Complications
-
-### Hidden Rule Inlining
-
-`_call_signature` doesn't produce a node, but its children do:
-
-```
-_call_signature = SEQ(formal_parameters, type_annotation?)
-```
-
-When validating `function_declaration`, we inline this to get:
-
-```
-SEQ("async"?, "function", identifier, formal_parameters, type_annotation?, statement_block)
-```
-
-### Extras (Trivia)
-
-The grammar's `extras` field lists nodes that can appear anywhere (comments, whitespace):
-
-```json
-"extras": [
-  {"type": "SYMBOL", "name": "comment"},
-  {"type": "PATTERN", "value": "\\s"}
-]
-```
-
-These are handled by trivia-skipping in anchors, not by the NFA.
-
-### Supertypes
-
-`SYMBOL("expression")` matches any expression subtype. The NFA transition accepts any node that is a subtype of `expression`.
-
-### Partial Matching
-
-Query patterns don't match ALL children — they match a subsequence:
-
-- Query `{(a) (c)}` matches actual children `[a, b, c]` (b skipped)
-- The NFA must allow "gap" transitions between pattern elements
-
-### Anchor Semantics
-
-| Pattern | Meaning |
-|---------|---------|
-| `(P . (x))` | x is first child of P (or first after trivia for named nodes) |
-| `(P (x) .)` | x is last child of P |
-| `(P (x) . (y))` | y immediately follows x (no named nodes between) |
-| `(P {. (x) (y) .})` | x is first AND y is last in the sequence |
-
-## Diagnostics
-
-```
-error[E0XX]: impossible child sequence
-  --> query.ptk:5:3
-   |
- 5 |   (function_declaration . (identifier) @name)
-   |                         ^^^^^^^^^^^^^^^^^
-   |
-   = note: `identifier` cannot be the first child of `function_declaration`
-   = note: the grammar requires `"function"` keyword before the name
-   = help: remove the first-child anchor: `(function_declaration (identifier) @name)`
-```
-
-## Effort Estimate
-
-| Component | LOC | Notes |
-|-----------|-----|-------|
-| Grammar JSON parser | ~400 | Serde, known schema |
-| Grammar IR | ~300 | Recursive enum |
-| Visibility analysis | ~300 | Inline hidden rules |
-| NFA construction | ~500 | Per node type |
-| Pattern matching | ~400 | Path satisfiability |
-| Integration | ~200 | Hook into link.rs |
-| Tests | ~500 | Edge cases |
-| **Total** | **~2600** | |
-
-## Build-time vs Runtime
-
-**Option 1: Runtime**
-- Load `grammar.json` at link time
-- More flexible (supports dynamic languages)
-- Slower startup, more memory
-
-**Option 2: Build-time**
-- Pre-compile grammar to static NFA tables in `build.rs`
-- Faster, but larger binaries
-- Matches current `node-types.json` approach
-
-Recommendation: Start with runtime, optimize to build-time if needed.
-
-## Open Questions
-
-1. **How to handle recursive rules?** Some rules reference themselves (expressions containing expressions). NFAs must handle cycles.
-
-2. **Grammar version matching?** Different tree-sitter versions may have different grammars. Need to ensure grammar matches the compiled parser.
-
-3. **Error recovery nodes?** `ERROR` and `MISSING` nodes bypass normal grammar. Should they skip validation?
-
-4. **Performance?** Building NFAs for all node types might be expensive. Consider lazy construction.
-
-## Next Steps
-
-1. Parse `grammar.json` into IR (new module in `plotnik-core` or `plotnik-lib`)
-2. Implement visibility analysis and hidden rule inlining
-3. Build NFA for a simple node type (e.g., `array`)
-4. Validate a simple anchor pattern
-5. Expand to full pattern matching
-6. Integrate into `link.rs`