parseman 0.56.0 → 0.58.0

package/src/table/fail-clean.ts

@@ -0,0 +1,130 @@
+/**
+ * WHICH ROWS FAIL CLEAN.
+ *
+ * A choice, an `optional()` and a repeat item take a rollback mark before they
+ * try their child and restore it when the child fails, so a failed attempt leaves
+ * nothing in the capture sinks: the open frame's children, raw entries and trivia
+ * rows, the fields, the errors and the two trivia logs. Most children never write
+ * to a sink before they fail. A terminal fails before it pushes its leaf; a node
+ * that fails drops its own frame; a sequence whose later terms cannot fail can
+ * only fail in its first term, which has no trivia in front of it. For such a
+ * child the mark and the restore are work with nothing to undo.
+ *
+ * `failsClean(ip)` answers, from the table alone, whether every failure of the
+ * row at `ip` leaves every sink as the row found it. Only uncommitted failures
+ * count: a committed failure is propagated past every choice, optional and
+ * repeat without their restore, so the mark is never read for it.
+ *
+ * It is one memoised walk, run while the assembler links, so it is paid on the
+ * first parse. A rule reached again while it is still being answered counts as
+ * dirty, and so does a row whose behaviour is not modelled here: `false` keeps
+ * the mark, so every approximation errs towards the old cost, never a wrong tree.
+ */
+import {
+  OP_ATTEMPT, OP_CHOICE, OP_COV, OP_DISPATCH, OP_EMPTY, OP_EXPECT, OP_FIELD, OP_GATE, OP_GUARD, OP_LABEL,
+  OP_LEAF, OP_LIT, OP_LIT_CI, OP_LIT_CI_TRACK, OP_LIT_TRACK, OP_NODE, OP_NODE_TRACK, OP_NOT, OP_OPT, OP_PEEK,
+  OP_REP, OP_REPV, OP_ROUTED, OP_RULE, OP_RX, OP_RX_TRACK, OP_SCOPE, OP_SCOPE_CAP, OP_SCOPE_PLAIN, OP_SEQ,
+  OP_SEQV, OP_SEQX, OP_SOURCE_LEAF, OP_TOKEN, OP_WITHCTX, OP_XFORM,
+} from './ops.ts'
+
+export type FailClean = (ip: number) => boolean
+
+/**
+ * The child offset of a row that fails exactly when its one child fails and
+ * writes nothing of its own first, or −1.
+ */
+function passChild(code: ArrayLike<number>, ip: number): number {
+  switch (code[ip]) {
+    case OP_RULE: case OP_LABEL: case OP_COV: case OP_TOKEN:
+      return code[ip + 1]!
+    case OP_GATE: case OP_NODE: case OP_NODE_TRACK: case OP_XFORM: case OP_FIELD: case OP_SCOPE:
+    case OP_SCOPE_CAP: case OP_SCOPE_PLAIN: case OP_WITHCTX: case OP_LEAF: case OP_SOURCE_LEAF:
+      return code[ip + 2]!
+    default:
+      return -1
+  }
+}
+
+/** Sequence terms: `[first offset, count]` packed as the offset of the count word, or −1. */
+function seqCount(code: ArrayLike<number>, ip: number): number {
+  const op = code[ip]
+  return op === OP_SEQ || op === OP_SEQV ? ip + 1 : op === OP_SEQX ? ip + 2 : -1
+}
+
+export function failCleanAnalysis(code: ArrayLike<number>): FailClean {
+  // Per row: 0 unknown, 1 yes, 2 no, 3 being answered (answered as no).
+  const cleanAt = new Uint8Array(code.length)
+  const neverAt = new Uint8Array(code.length)
+
+  /** No uncommitted failure at all. */
+  const neverFails = (ip: number): boolean => {
+    const hit = neverAt[ip]!
+    if (hit !== 0) return hit === 1
+    neverAt[ip] = 3
+    let out = false
+    const op = code[ip]
+    if (op === OP_OPT || op === OP_EMPTY || op === OP_EXPECT) out = true
+    else if (op === OP_REP || op === OP_REPV) out = code[ip + 2] === 0
+    else {
+      const at = seqCount(code, ip)
+      if (at >= 0) {
+        out = true
+        for (let i = 1, n = code[at]!; out && i <= n; i++) out = neverFails(code[at + i]!)
+      } else if (op !== OP_GATE) {
+        const c = passChild(code, ip)
+        out = c >= 0 && neverFails(c)
+      }
+    }
+    neverAt[ip] = out ? 1 : 2
+    return out
+  }
+
+  const clean = (ip: number): boolean => {
+    const hit = cleanAt[ip]!
+    if (hit !== 0) return hit === 1
+    cleanAt[ip] = 3
+    let out = false
+    switch (code[ip]) {
+      // A terminal pushes its leaf only on a match; NOT/PEEK/ATTEMPT restore
+      // their own mark; OPT, EMPTY and EXPECT do not fail uncommitted.
+      case OP_LIT: case OP_RX: case OP_LIT_TRACK: case OP_RX_TRACK: case OP_LIT_CI: case OP_LIT_CI_TRACK:
+      case OP_GUARD: case OP_NOT: case OP_PEEK: case OP_ATTEMPT: case OP_EMPTY: case OP_OPT: case OP_EXPECT:
+        out = true
+        break
+      // Min 0 does not fail uncommitted; min 1 fails only with no item kept, and
+      // restores the failed item itself.
+      case OP_REP: case OP_REPV:
+        out = code[ip + 2]! <= 1
+        break
+      // Only the first term may fail: a later one fails after the terms before it
+      // wrote, and after the trivia scanned in front of it.
+      case OP_SEQ: case OP_SEQV: case OP_SEQX: {
+        const at = seqCount(code, ip)
+        const n = code[at]!
+        out = n > 0 && clean(code[at + 1]!)
+        for (let i = 2; out && i <= n; i++) out = neverFails(code[at + i]!)
+        break
+      }
+      case OP_CHOICE: {
+        out = true
+        for (let i = 0, n = code[ip + 2]!; out && i < n; i++) out = clean(code[ip + 4 + i]!)
+        break
+      }
+      case OP_ROUTED:
+        out = code[ip + 1]! < 0 || clean(code[ip + 1]!)
+        break
+      // An arm's failure and the fallback's are committed; only the selector's is
+      // not, and without a fallback an unknown key fails after the selector wrote.
+      case OP_DISPATCH:
+        out = code[ip + 3]! >= 0 && clean(code[ip + 1]!)
+        break
+      default: {
+        const c = passChild(code, ip)
+        out = c >= 0 && clean(c)
+      }
+    }
+    cleanAt[ip] = out ? 1 : 2
+    return out
+  }
+  return clean
+}

package/src/table/hold-gap.ts

@@ -0,0 +1,68 @@
+/**
+ * A GAP HELD OVER A LOOKAHEAD.
+ *
+ * In a sequence, the trivia before each term is scanned and recorded, and when
+ * the term matches nothing it is unrecorded and the cursor goes back before it:
+ * the next term scans the same gap again. Where the term that matched nothing is
+ * a lookahead (`not`/`peek`, always zero-width) and the next term cannot match
+ * empty, that second scan reads the same characters from the same position under
+ * the same trivia and records the same rows, and the next term then either
+ * consumes past the gap or the sequence fails. So the gap is kept: the lookahead
+ * runs at the gap's end, the cursor stays there, and the next term starts there
+ * with nothing left to scan. One scan where there were two and an undo.
+ *
+ * Not before an adjacency assertion or a leading-trivia field, which read the
+ * cursor from before the gap.
+ */
+import {
+  OP_ADJ, OP_ATTEMPT, OP_CHOICE, OP_COV, OP_EXPECT, OP_FIELD, OP_GATE, OP_LABEL, OP_LEAF, OP_LIT, OP_LIT_CI,
+  OP_NODE, OP_NOT, OP_PEEK, OP_REP, OP_REPV, OP_RULE, OP_RX, OP_SCOPE, OP_SCOPE_CAP, OP_SCOPE_PLAIN, OP_SEQ,
+  OP_SEQV, OP_SEQX, OP_SOURCE_LEAF, OP_TOKEN, OP_WITHCTX, OP_XFORM,
+} from './ops.ts'
+import { childSlots } from './child-slots.ts'
+import { leadingTriviaFieldAt } from './field-spec.ts'
+import { regexCanMatchEmpty } from '../regex/first-set.ts'
+
+const WRAPPERS = new Set([OP_NODE, OP_XFORM, OP_LEAF, OP_SOURCE_LEAF, OP_TOKEN, OP_SCOPE, OP_SCOPE_CAP,
+  OP_SCOPE_PLAIN, OP_FIELD, OP_LABEL, OP_EXPECT, OP_WITHCTX, OP_RULE, OP_ATTEMPT, OP_COV])
+
+/**
+ * Can the row at `ip` match empty? `true` wherever it cannot tell. A first-set
+ * gate row wraps only a child that cannot (`encode.ts` gates nothing nullable).
+ */
+export function rowNullable(code: ArrayLike<number>, k: readonly unknown[], ip: number, memo: Map<number, boolean>): boolean {
+  const hit = memo.get(ip)
+  if (hit !== undefined) return hit
+  memo.set(ip, true) // a cycle is answered conservatively
+  const op = code[ip]!
+  const kids: number[] = []
+  let out = true
+  if (op === OP_GATE) out = false
+  else if (op === OP_LIT || op === OP_LIT_CI) out = (k[code[ip + 1]!] as string).length === 0
+  else if (op === OP_RX) { const re = k[code[ip + 1]!]; out = !(re instanceof RegExp) || regexCanMatchEmpty(re.source) }
+  else if (op === OP_SEQ || op === OP_SEQV || op === OP_SEQX) {
+    childSlots(code, ip, kids)
+    out = kids.every(c => rowNullable(code, k, c, memo))
+  } else if (op === OP_CHOICE) {
+    childSlots(code, ip, kids)
+    out = kids.length === 0 || kids.some(c => rowNullable(code, k, c, memo))
+  } else if (op === OP_REP || op === OP_REPV) {
+    out = code[ip + 2] === 0 || rowNullable(code, k, code[ip + 1]!, memo)
+  } else if (WRAPPERS.has(op)) {
+    if (childSlots(code, ip, kids) && kids.length === 1) out = rowNullable(code, k, kids[0]!, memo)
+  }
+  memo.set(ip, out)
+  return out
+}
+
+/** Term `i` of the sequence at `seq` (terms from `base`, `n` of them) holds its gap. */
+export function holdsGap(
+  code: ArrayLike<number>, k: readonly unknown[], base: number, n: number, i: number, memo: Map<number, boolean>,
+): boolean {
+  if (i < 1 || i + 1 >= n) return false
+  const term = code[base + i]!
+  if (code[term] !== OP_NOT && code[term] !== OP_PEEK) return false
+  const next = code[base + i + 1]!
+  if (code[next] === OP_ADJ || leadingTriviaFieldAt(code, k, next)) return false
+  return !rowNullable(code, k, next, memo)
+}

package/src/table/lex-program.ts

@@ -1,5 +1,6 @@
 import type { Combinator, ParseContext } from '../types.ts'
 import { failAt } from '../combinators/probe.ts'
+import { lead } from './run-support.ts'
 import type { LexBodyRecognizer } from './lex-body.ts'
 import type { LexProgramSpec, ResolvedClass } from './program.ts'
 
@@ -16,11 +17,15 @@ export const LEX_NODE_SEQUENCE2 = 1
 export const LEX_NODE_SEQUENCE3 = 2
 export const LEX_NODE_SEQUENCE4 = 3
 export const LEX_NODE_SEQUENCE5 = 4
-export const LEX_NODE_CHOICE2 = 5
-export const LEX_NODE_CHOICE4 = 6
-export const LEX_NODE_CHOICE8 = 7
+/**
+ * `[op, armCount, exclusive, choiceFx, (armClass, armFx) × armCount]`: any arity,
+ * no padding. `exclusive` is the character choice's one-arm dispatch decision.
+ */
+export const LEX_NODE_CHOICE = 5
 export const LEX_NODE_NOT = 8
 export const LEX_NODE_OPTIONAL = 9
+/** `[op, min, max]` after the item: a separator-less repeat, `max` −1 unbounded. */
+export const LEX_NODE_REPEAT = 10
 
 export function lexProgramDigest(words: readonly number[]): number {
   let hash = 0x811C9DC5
@@ -60,73 +65,88 @@ function terminalNode(
   failure: readonly string[],
   tracksLines: boolean,
 ): BuiltLexNode {
-  const match: PureLexRunner = (input, pos) => {
-    const result = matcher(input, pos)
-    return result < 0 ? -1 : result / 2
-  }
   return {
-    match,
+    match: (input, pos) => {
+      const result = matcher(input, pos)
+      return result < 0 ? -1 : result / 2
+    },
     run: (input, pos, ctx) => {
-      const end = match(input, pos)
-      if (end < 0) {
+      const result = matcher(input, pos)
+      if (result < 0) {
         ctx._fe = pos
         ctx._fx = failure as string[]
         if (ctx._probe !== undefined) failAt(ctx, ctx._fx, pos)
         return -1
       }
+      const end = result / 2
       if (tracksLines) trackLexLines(ctx, input, end)
       return end
     },
   }
 }
 
+// Each sequence captures its parts' runners as scalars: a part is reached by a
+// direct call, not a property read, and no arity nests another sequence.
 function sequence2(a: BuiltLexNode, b: BuiltLexNode): BuiltLexNode {
+  const am = a.match, bm = b.match, ar = a.run, br = b.run
   return {
     match: (input, pos) => {
-      const e0 = a.match(input, pos)
-      return e0 < 0 ? -1 : b.match(input, e0)
+      const e0 = am(input, pos)
+      return e0 < 0 ? -1 : bm(input, e0)
     },
     run: (input, pos, ctx) => {
-      const e0 = a.run(input, pos, ctx)
+      const e0 = ar(input, pos, ctx)
       if (e0 < 0) return -1
       ctx._fc = false
-      return b.run(input, e0, ctx)
+      return br(input, e0, ctx)
     },
   }
 }
 
 function sequence3(a: BuiltLexNode, b: BuiltLexNode, c: BuiltLexNode): BuiltLexNode {
+  const am = a.match, bm = b.match, cm = c.match, ar = a.run, br = b.run, cr = c.run
   return {
     match: (input, pos) => {
-      const e0 = a.match(input, pos)
+      const e0 = am(input, pos)
       if (e0 < 0) return -1
-      const e1 = b.match(input, e0)
-      return e1 < 0 ? -1 : c.match(input, e1)
+      const e1 = bm(input, e0)
+      return e1 < 0 ? -1 : cm(input, e1)
     },
     run: (input, pos, ctx) => {
-      const e0 = a.run(input, pos, ctx)
+      const e0 = ar(input, pos, ctx)
       if (e0 < 0) return -1
       ctx._fc = false
-      const e1 = b.run(input, e0, ctx)
+      const e1 = br(input, e0, ctx)
       if (e1 < 0) return -1
       ctx._fc = false
-      return c.run(input, e1, ctx)
+      return cr(input, e1, ctx)
     },
   }
 }
 
 function sequence4(a: BuiltLexNode, b: BuiltLexNode, c: BuiltLexNode, d: BuiltLexNode): BuiltLexNode {
-  const abc = sequence3(a, b, c)
+  const am = a.match, bm = b.match, cm = c.match, dm = d.match
+  const ar = a.run, br = b.run, cr = c.run, dr = d.run
   return {
     match: (input, pos) => {
-      const end = abc.match(input, pos)
-      return end < 0 ? -1 : d.match(input, end)
+      const e0 = am(input, pos)
+      if (e0 < 0) return -1
+      const e1 = bm(input, e0)
+      if (e1 < 0) return -1
+      const e2 = cm(input, e1)
+      return e2 < 0 ? -1 : dm(input, e2)
     },
     run: (input, pos, ctx) => {
-      const end = abc.run(input, pos, ctx)
-      if (end < 0) return -1
+      const e0 = ar(input, pos, ctx)
+      if (e0 < 0) return -1
+      ctx._fc = false
+      const e1 = br(input, e0, ctx)
+      if (e1 < 0) return -1
+      ctx._fc = false
+      const e2 = cr(input, e1, ctx)
+      if (e2 < 0) return -1
       ctx._fc = false
-      return d.run(input, end, ctx)
+      return dr(input, e2, ctx)
     },
   }
 }
@@ -134,17 +154,33 @@ function sequence4(a: BuiltLexNode, b: BuiltLexNode, c: BuiltLexNode, d: BuiltLe
 function sequence5(
   a: BuiltLexNode, b: BuiltLexNode, c: BuiltLexNode, d: BuiltLexNode, e: BuiltLexNode,
 ): BuiltLexNode {
-  const abcd = sequence4(a, b, c, d)
+  const am = a.match, bm = b.match, cm = c.match, dm = d.match, em = e.match
+  const ar = a.run, br = b.run, cr = c.run, dr = d.run, er = e.run
   return {
     match: (input, pos) => {
-      const end = abcd.match(input, pos)
-      return end < 0 ? -1 : e.match(input, end)
+      const e0 = am(input, pos)
+      if (e0 < 0) return -1
+      const e1 = bm(input, e0)
+      if (e1 < 0) return -1
+      const e2 = cm(input, e1)
+      if (e2 < 0) return -1
+      const e3 = dm(input, e2)
+      return e3 < 0 ? -1 : em(input, e3)
     },
     run: (input, pos, ctx) => {
-      const end = abcd.run(input, pos, ctx)
-      if (end < 0) return -1
+      const e0 = ar(input, pos, ctx)
+      if (e0 < 0) return -1
       ctx._fc = false
-      return e.run(input, end, ctx)
+      const e1 = br(input, e0, ctx)
+      if (e1 < 0) return -1
+      ctx._fc = false
+      const e2 = cr(input, e1, ctx)
+      if (e2 < 0) return -1
+      ctx._fc = false
+      const e3 = dr(input, e2, ctx)
+      if (e3 < 0) return -1
+      ctx._fc = false
+      return er(input, e3, ctx)
     },
   }
 }
@@ -169,9 +205,9 @@ function choiceNode(
 ): BuiltLexNode {
   let matchTail: PureLexRunner = () => -1
   for (let i = arms.length - 1; i >= 0; i--) {
-    const arm = arms[i]!, next = matchTail
+    const armMatch = arms[i]!.match, next = matchTail
     matchTail = (input, pos) => {
-      const end = arm.match(input, pos)
+      const end = armMatch(input, pos)
       return end < 0 ? next(input, pos) : end
     }
   }
@@ -181,7 +217,7 @@ function choiceNode(
     return -1
   }
   for (let i = arms.length - 1; i >= 0; i--) {
-    const arm = arms[i]!, cls = classes[i], staticExpected = armExpected[i]!, next = tail
+    const armRun = arms[i]!.run, cls = classes[i], staticExpected = armExpected[i]!, next = tail
     tail = (input, pos, ctx, lead, acc, best) => {
       if (cls !== undefined && !classHas(cls, lead)) {
         return next(
@@ -191,7 +227,7 @@ function choiceNode(
         )
       }
       ctx._fc = false
-      const end = arm.run(input, pos, ctx)
+      const end = armRun(input, pos, ctx)
       if (end >= 0) return end
       const at = ctx._fe ?? pos
       if (at > best) { best = at; acc = undefined }
@@ -211,11 +247,68 @@ function choiceNode(
   }
 }
 
+/**
+ * A choice whose arms' classes are disjoint, as the character choice's exclusive
+ * dispatch: the arm the lead selects runs alone, its failure is the choice's at
+ * the choice's position, and a lead no arm claims reports the arms' openers. The
+ * selected index reaches its arm through a fixed chain, never an array.
+ */
+function exclusiveChoiceNode(
+  arms: readonly BuiltLexNode[],
+  classes: readonly ResolvedClass[],
+  choiceFx: readonly string[],
+): BuiltLexNode {
+  // A signed byte holds every arm index up to 127, which is every real grammar's
+  // choice; a wider choice takes a wider table so its 129th arm is not read as -128.
+  const ascii = (classes.length <= 128 ? new Int8Array(128) : new Int32Array(128)).fill(-1)
+  const hi: number[] = []
+  for (let i = 0; i < classes.length; i++) {
+    const cls = classes[i]!
+    for (let c = 0; c < 128; c++) if (cls.ascii[c] === 1) ascii[c] = i
+    for (let r = 0; r < cls.hi.length; r += 2) hi.push(cls.hi[r]!, cls.hi[r + 1]!, i)
+  }
+  const select = (code: number): number => {
+    if (code < 0) return -1
+    if (code < 128) return ascii[code]!
+    for (let r = 0; r < hi.length; r += 3) if (code >= hi[r]! && code <= hi[r + 1]!) return hi[r + 2]!
+    return -1
+  }
+  let matchArm: (arm: number, input: string, pos: number) => number = () => -1
+  let selectRun: (arm: number, input: string, pos: number, ctx: ParseContext) => number = () => -1
+  for (let i = arms.length - 1; i >= 0; i--) {
+    const armMatch = arms[i]!.match, armRun = arms[i]!.run, nextMatch = matchArm, nextRun = selectRun
+    matchArm = (selected, input, pos) => selected === i ? armMatch(input, pos) : nextMatch(selected, input, pos)
+    selectRun = (selected, input, pos, ctx) => selected === i ? armRun(input, pos, ctx) : nextRun(selected, input, pos, ctx)
+  }
+  const runArm: LexProgramRunner = (input, pos, ctx) => {
+    const arm = select(lead(input, pos))
+    if (arm >= 0) {
+      ctx._fc = false
+      const end = selectRun(arm, input, pos, ctx)
+      if (end >= 0) return end
+      if (committed(ctx)) return -1
+      const failed = ctx._fx
+      if (failed !== undefined && failed.length > 0) { ctx._fe = pos; return -1 }
+    }
+    ctx._fe = pos
+    ctx._fx = choiceFx as string[]
+    return -1
+  }
+  return {
+    match: (input, pos) => {
+      const arm = select(lead(input, pos))
+      return arm < 0 ? -1 : matchArm(arm, input, pos)
+    },
+    run: runArm,
+  }
+}
+
 function notNode(body: BuiltLexNode, failure: readonly string[]): BuiltLexNode {
+  const bodyMatch = body.match
   return {
-    match: (input, pos) => body.match(input, pos) < 0 ? pos : -1,
+    match: (input, pos) => bodyMatch(input, pos) < 0 ? pos : -1,
     run: (input, pos, ctx) => {
-      if (body.match(input, pos) < 0) return pos
+      if (bodyMatch(input, pos) < 0) return pos
       ctx._fe = pos
       ctx._fx = failure as string[]
       return -1
@@ -224,19 +317,65 @@ function notNode(body: BuiltLexNode, failure: readonly string[]): BuiltLexNode {
 }
 
 function optionalNode(body: BuiltLexNode): BuiltLexNode {
+  const bodyMatch = body.match, bodyRun = body.run
   return {
     match: (input, pos) => {
-      const end = body.match(input, pos)
+      const end = bodyMatch(input, pos)
       return end < 0 ? pos : end
     },
     run: (input, pos, ctx) => {
       ctx._fc = false
-      const end = body.run(input, pos, ctx)
+      const end = bodyRun(input, pos, ctx)
       return end < 0 && !committed(ctx) ? pos : end
     },
   }
 }
 
+/**
+ * The table's separator-less `OP_REP` under `token()`: no trivia, no separator,
+ * nothing to roll back. Only an optional item stops at end of input or on a
+ * zero-width match (`repItem`); a failed item ends the loop with its own
+ * failure published, and a committed one fails the repeat.
+ */
+function repeatNode(item: BuiltLexNode, min: number, max: number): BuiltLexNode {
+  const itemMatch = item.match, itemRun = item.run
+  return {
+    match: (input, pos) => {
+      let cur = pos
+      let count = 0
+      for (;;) {
+        if (max >= 0 && count >= max) break
+        const optional = count >= min && (count > 0 || min === 0)
+        if (optional && cur >= input.length) break
+        const end = itemMatch(input, cur)
+        if (end < 0 || (optional && end === cur)) break
+        cur = end
+        count++
+      }
+      return count < min ? -1 : cur
+    },
+    run: (input, pos, ctx) => {
+      let cur = pos
+      let count = 0
+      for (;;) {
+        if (max >= 0 && count >= max) break
+        const optional = count >= min && (count > 0 || min === 0)
+        if (optional && cur >= input.length) break
+        ctx._fc = false
+        const end = itemRun(input, cur, ctx)
+        if (end < 0) {
+          if (committed(ctx)) return -1
+          break
+        }
+        if (optional && end === cur) break
+        cur = end
+        count++
+      }
+      return count < min ? -1 : cur
+    },
+  }
+}
+
 function fixedTreeRunner(
   words: readonly number[],
   matchers: readonly LexBodyRecognizer[],
@@ -269,9 +408,14 @@ function fixedTreeRunner(
       else stack.push(sequence5(nodes[0]!, nodes[1]!, nodes[2]!, nodes[3]!, nodes[4]!))
       continue
     }
-    if (op >= LEX_NODE_CHOICE2 && op <= LEX_NODE_CHOICE8) {
-      const count = op === LEX_NODE_CHOICE2 ? 2 : op === LEX_NODE_CHOICE4 ? 4 : 8
+    if (op === LEX_NODE_CHOICE) {
+      const count = words[at++]!
+      const exclusive = words[at++]!
+      if (exclusive !== 0 && exclusive !== 1) throw new TypeError('table lexical tree choice has an invalid dispatch mode')
       const choiceFx = expected[words[at++]!]
+      if (!Number.isInteger(count) || count < 2 || count > stack.length) {
+        throw new TypeError('table lexical tree choice has an invalid arm count')
+      }
       if (choiceFx === undefined) throw new TypeError('table lexical tree choice has an invalid expected set')
       const armClasses: Array<ResolvedClass | undefined> = []
       const armFx: Array<readonly string[]> = []
@@ -284,7 +428,9 @@ function fixedTreeRunner(
         armFx.push(fx)
       }
       const arms = Array.from({ length: count }, pop).reverse()
-      stack.push(choiceNode(arms, armClasses, armFx, choiceFx))
+      stack.push(exclusive === 1
+        ? exclusiveChoiceNode(arms, armClasses as ResolvedClass[], choiceFx)
+        : choiceNode(arms, armClasses, armFx, choiceFx))
       continue
     }
     if (op === LEX_NODE_NOT) {
@@ -294,6 +440,14 @@ function fixedTreeRunner(
       continue
     }
     if (op === LEX_NODE_OPTIONAL) { stack.push(optionalNode(pop())); continue }
+    if (op === LEX_NODE_REPEAT) {
+      const min = words[at++]!, max = words[at++]!
+      if (!Number.isInteger(min) || min < 0 || !Number.isInteger(max) || (max >= 0 && max < min)) {
+        throw new TypeError('table lexical tree repeat has invalid bounds')
+      }
+      stack.push(repeatNode(pop(), min, max))
+      continue
+    }
     throw new TypeError('table lexical tree has an unknown fixed body')
   }
   if (stack.length !== 1) throw new TypeError('table lexical tree does not resolve to one root body')

package/src/table/ops.ts

@@ -339,13 +339,16 @@ export const OP_REJECT = 35
  * arm INSTEAD of sitting inside it, so the encoder still reads the arm's own
  * first set for `disp` and the site keeps its dispatch slot.
  *
- * A blocked arm is SKIPPED, not failed — `choice.ts:150` is `continue`. The row
- * therefore clears `_fc` on the gate-false path exactly as `OP_REJECT` does:
+ * A blocked arm is SKIPPED, not failed — `choice.ts` firstMatch `continue`s. The
+ * row therefore clears `_fc` on the gate-false path exactly as `OP_REJECT` does:
  * "pretend this arm was never entered", so no cut it might have raised survives
- * to cut the choice. It still reports `e`, because the OTHER path a blocked arm
- * can be reached by is first-char dispatch, where skip-and-retry and
- * fail-the-choice are the same thing (choice.ts:23-34, :100-105) and the
- * interpreter answers with `deriveExpected(arm)` — this set.
+ * to cut the choice. It sets `_fe` to −1, so an ORDERED choice, which ranks arms
+ * by failure position, takes nothing from it, as the interpreter does. It still
+ * leaves `e` in `_fx`, because the other path a blocked arm can be reached by is
+ * exclusive first-char dispatch, where skip-and-retry and fail-the-choice are the
+ * same thing and the interpreter answers with `deriveExpected(arm)` — this set.
+ * On an ordered site the encoder gives a gated arm no char class, so it is always
+ * entered and this row, not a char gate, decides what it contributes.
  *
  * The predicate is a live function, like `OP_GUARD`'s, so a grammar using one is
  * runtime-only for `emitTableModule` unless `fnSources` are supplied.
@@ -475,6 +478,14 @@ export const OP_LEX_BODY = 42
 export const OP_LEX_PROGRAM = 43
 /** `SOURCE_LEAF f c` — `sourceLeaf()`: reduce semantically, capture source text. */
 export const OP_SOURCE_LEAF = 44
+/**
+ * `RGATE cls child fx` — a choice arm that opens with the token its `dispatch()`
+ * already routed. `cls` is what may follow that token (the arm's next term,
+ * with the sequence's trivia), tested at the routed token's END; a miss fails
+ * there with the next term's set `fx`, as running the arm would. No routed token
+ * at this position, a completions probe, or tolerant recovery enters the arm.
+ */
+export const OP_RGATE = 45
 /**
  * `DISPATCH sel d other otherRouted n a1 … an` — `dispatch()`.
  *
@@ -498,7 +509,7 @@ export const OP_NAMES: Record<number, string> = {
   [OP_LIT]: 'LIT', [OP_RX]: 'RX', [OP_SEQ]: 'SEQ', [OP_SEQV]: 'SEQV',
   [OP_CHOICE]: 'CHOICE', [OP_REP]: 'REP', [OP_REPV]: 'REPV', [OP_OPT]: 'OPT',
   [OP_XFORM]: 'XFORM', [OP_NODE]: 'NODE', [OP_RULE]: 'RULE', [OP_GATE]: 'GATE',
-  [OP_NOT]: 'NOT', [OP_PEEK]: 'PEEK', [OP_LEAF]: 'LEAF', [OP_SOURCE_LEAF]: 'SOURCE_LEAF', [OP_EMPTY]: 'EMPTY',
+  [OP_NOT]: 'NOT', [OP_PEEK]: 'PEEK', [OP_LEAF]: 'LEAF', [OP_SOURCE_LEAF]: 'SOURCE_LEAF', [OP_RGATE]: 'RGATE', [OP_EMPTY]: 'EMPTY',
   [OP_LIT_TRACK]: 'LIT_TRACK', [OP_RX_TRACK]: 'RX_TRACK', [OP_NODE_TRACK]: 'NODE_TRACK',
   [OP_SCOPE]: 'SCOPE', [OP_EXPECT]: 'EXPECT', [OP_SEQX]: 'SEQX', [OP_SCAN]: 'SCAN',
   [OP_FIELD]: 'FIELD', [OP_LIT_CI]: 'LIT_CI', [OP_LIT_CI_TRACK]: 'LIT_CI_TRACK', [OP_DISPATCH]: 'DISPATCH', [OP_ROUTED]: 'ROUTED',

package/src/table/program.ts

@@ -273,6 +273,19 @@ export function scanRefs(s: ScanSpec): SubtreeRef[] {
   return refs
 }
 
+/**
+ * The sites an assembly links from OUTSIDE its rule entries — the scan pool's
+ * subtrees, then the scan-skip sets — in the one order every assembler names
+ * them. The emitted source is keyed by this order, so a second copy of the list
+ * that disagrees prints different source for the same program.
+ */
+export function assemblyExtraIps(prog: TableProgram): number[] {
+  const ips: number[] = []
+  for (const s of prog.scans ?? []) for (const r of scanRefs(s)) ips.push(r[0])
+  for (const set of prog.scanSkip ?? []) for (const r of set) ips.push(r[0])
+  return ips
+}
+
 /** A trivia combinator as data. `arms` empty means a plain `trivia(regex)`. */
 export type TriviaSpec = {
   /** `[label, regexSource, regexFlags]` per classified arm. */
@@ -644,6 +657,17 @@ export function classHas(cls: ResolvedClass, code: number): boolean {
   return false
 }
 
+/**
+ * Whether a choice with these arm classes (indices into the class-spec pool `cc`)
+ * takes the O(1) exclusive dispatch — the same decision `resolveDispatch` makes,
+ * for an encoder that has only the specs.
+ */
+export function dispatchIsExclusive(arms: readonly number[], cc: readonly string[]): boolean {
+  const resolved: ResolvedClass[] = []
+  for (const ci of arms) if (ci >= 0) resolved[ci] = resolveClass(cc[ci]!)
+  return resolveDispatch(arms, resolved).exclusive
+}
+
 function resolveDispatch(arms: readonly number[], cc: readonly ResolvedClass[]): ResolvedDispatch {
   const ascii = new Uint8Array(128)
   const hi: number[] = []