parseman 0.57.0 → 0.58.0

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

@@ -478,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()`.
  *
@@ -501,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/run-support.ts

@@ -13,6 +13,7 @@
  * reads only its arguments.
  */
 import type { ParseContext } from '../types.ts'
+import { popCstChild, pushCstChild } from '../cst/capture-buffer.ts'
 
 export type Span = { start: number; end: number }
 export type LineSpan = Span & {
@@ -64,3 +65,37 @@ export function lead(input: string, pos: number): number {
   if (c < 0xd800 || c > 0xdbff) return c
   return input.codePointAt(pos) ?? c
 }
+
+const EMPTY_KIDS: readonly unknown[] = Object.freeze([])
+const EMPTY_TRIVIA: readonly number[] = Object.freeze([])
+
+type CollapseBuild = (
+  children: readonly unknown[], fields: undefined, span: { start: number; end: number },
+  rawChildren: readonly unknown[], triviaLog: readonly number[], state: undefined,
+) => unknown
+
+/**
+ * A PASS-THROUGH COLLAPSE whose one child built `undefined` (`site-labels.ts`
+ * `passCollapse`).
+ *
+ * A collapse over a single node is that node: the node publishes its value into
+ * the collector the collapse's parent opened, exactly where the collapse would
+ * have published it, over the same span. So both engines run the body with no
+ * frame of the collapse's own and hand its value up. The one value a frame would
+ * have treated differently is `undefined`, which a frame does not count as a
+ * child: the collapse then builds from no children. This is that case — take the
+ * child's publication back and publish the build instead, as the frame would
+ * have. The caller has already set `EC.e`.
+ */
+export function collapseEmpty(
+  ctx: ParseContext, build: CollapseBuild, input: string, pos: number, end: number, readsRaw: boolean,
+): unknown {
+  const collected = ctx._cstBuf !== undefined || ctx._cstChildren !== undefined
+  if (collected) popCstChild(ctx)
+  // A frame keeps the raw entry of the child it does not count, for a reducer
+  // that reads `rawChildren`.
+  const raw = readsRaw ? [rawEntry(undefined, input, pos, end)] : EMPTY_KIDS
+  const nd = build(EMPTY_KIDS, undefined, { start: pos, end }, raw, EMPTY_TRIVIA, undefined)
+  if (collected) pushCstChild(ctx, nd, ctx._cstBuf?.noRaw === true ? undefined : rawEntry(nd, input, pos, end))
+  return nd
+}

package/src/table/scalar-terminal.ts

@@ -54,6 +54,14 @@ export function scalarTerminalNotChild(code: ArrayLike<number>, ip: number): num
   return op === OP_RX || op === OP_LIT ? child : -1
 }
 
+/** The same terminal under `peek()`: its match decides the lookahead, and nothing it captured survives it. */
+export function scalarTerminalPeekChild(code: ArrayLike<number>, ip: number): number {
+  if (code[ip] !== OP_PEEK) return -1
+  const child = code[ip + 1]!
+  const op = code[child]
+  return op === OP_RX || op === OP_LIT ? child : -1
+}
+
 /**
  * A direct scalar terminal that every successful execution of `ip` must match
  * first, through wrappers that cannot consume or select before their child.

package/src/table/site-labels.ts

@@ -60,9 +60,9 @@
  * label licenses at a leaf is dropping the TEST — never the capture.
  */
 import {
-  OP_ATTEMPT, OP_CHOICE, OP_DISPATCH, OP_EXPECT, OP_FIELD, OP_GATE, OP_LABEL, OP_LEAF, OP_SOURCE_LEAF,
+  OP_ATTEMPT, OP_CHOICE, OP_DISPATCH, OP_EXPECT, OP_FIELD, OP_GATE, OP_LABEL, OP_LEAF, OP_LIT, OP_SOURCE_LEAF,
   OP_NODE, OP_NODE_TRACK, OP_NOT, OP_OPT, OP_PEEK, OP_REP, OP_REPV, OP_ROUTED, OP_RULE,
-  OP_SCOPE, OP_SCOPE_CAP, OP_SCOPE_PLAIN, OP_SEQ, OP_SEQV, OP_SEQX, OP_TOKEN, OP_XFORM,
+  OP_SCAN, OP_SCOPE, OP_SCOPE_CAP, OP_SCOPE_PLAIN, OP_SEQ, OP_SEQV, OP_SEQX, OP_TOKEN, OP_XFORM,
 } from './ops.ts'
 import { childSlots } from './child-slots.ts'
 
@@ -142,6 +142,61 @@ export function reachableSites(code: Int32Array, roots: Iterable<number>): Set<n
   return seen
 }
 
+/**
+ * A node both engines lower as a PASS-THROUGH COLLAPSE (`run-support.ts`
+ * `collapseEmpty`): `collapse: true` over a direct reducer, no projection, no CST
+ * host, no line tracking, whose body is one node behind wrappers that consume and
+ * capture nothing (a first-set gate, a trivia scope, a rule reference). One
+ * predicate, so the two engines and the labels cannot disagree on a site.
+ */
+export function passCollapse(code: Int32Array, ip: number, hostCst: boolean): boolean {
+  const flags = code[ip + 3]!
+  if (hostCst || code[ip] !== OP_NODE || code[ip + 1]! < 0 || code[ip + 4]! >= 0) return false
+  if (flags !== 32 && flags !== 34) return false
+  let at = code[ip + 2]!
+  for (let n = 0; n < 8; n++) {
+    const op = code[at]
+    if (op === OP_GATE || op === OP_SCOPE_PLAIN || (op === OP_SCOPE && code[at + 3] === 0)) at = code[at + 2]!
+    else if (op === OP_RULE) at = code[at + 1]!
+    else break
+  }
+  return code[at] === OP_NODE
+}
+
+/**
+ * A collapse that a FIRST CHARACTER can reduce to a pass-through: its body is a
+ * sequence of `optional`/`not` terms, each behind a first-character gate, then
+ * one node. Where the character at the collapse's start opens none of those
+ * terms (nor its sequence's trivia — the engines test that against the site's
+ * label), every one of them matches empty there and the body is that node alone.
+ * `leads` are the gate rows, `lits` the constant indices of direct literal terms,
+ * `last` the node term. Not a `passCollapse`.
+ */
+export function gatedPassCollapse(code: Int32Array, ip: number, hostCst: boolean): { leads: number[]; lits: number[]; last: number } | undefined {
+  const flags = code[ip + 3]!
+  if (hostCst || code[ip] !== OP_NODE || code[ip + 1]! < 0 || code[ip + 4]! >= 0) return undefined
+  if (flags !== 32 && flags !== 34) return undefined
+  const seq = code[ip + 2]!
+  if (code[seq] !== OP_SEQ && code[seq] !== OP_SEQV) return undefined
+  const n = code[seq + 1]!
+  if (n < 2) return undefined
+  const leads: number[] = []
+  const lits: number[] = []
+  for (let i = 0; i < n - 1; i++) {
+    const t = code[seq + 2 + i]!
+    if (code[t] !== OP_OPT && code[t] !== OP_NOT) return undefined
+    const g = code[t + 1]!
+    // A gate row carries the term's first characters; a direct literal is its own.
+    if (code[g] === OP_GATE) leads.push(g)
+    else if (code[g] === OP_LIT) lits.push(code[g + 1]!)
+    else return undefined
+  }
+  const last = code[seq + 2 + n - 1]!
+  let at = last
+  for (let k = 0; k < 8 && (code[at] === OP_GATE || code[at] === OP_RULE); k++) at = code[at] === OP_RULE ? code[at + 1]! : code[at + 2]!
+  return code[at] === OP_NODE ? { leads, lits, last } : undefined
+}
+
 /**
  * What a site hands DOWN to its children. Every op but the two that write the
  * context passes its own label through unchanged.
@@ -159,6 +214,10 @@ function transfer(code: Int32Array, ip: number, at: SiteLabel, hostCst: boolean)
   }
   if (op === OP_NODE || op === OP_NODE_TRACK) {
     const flags = code[ip + 3]!
+    // A pass-through collapse opens nothing: its body runs in its parent's
+    // collector and capture setting.
+    if (passCollapse(code, ip, hostCst)) return at
+    const gated = gatedPassCollapse(code, ip, hostCst) !== undefined
     // The same selection `emit-assembly.ts` makes: the trailing-trivia bit (128)
     // keeps the children-only shape.
     const directChildren = !hostCst && op === OP_NODE && code[ip + 1]! >= 0 && code[ip + 4]! < 0
@@ -168,7 +227,9 @@ function transfer(code: Int32Array, ip: number, at: SiteLabel, hostCst: boolean)
       // arrays instead of a CstCaptureBuf. Descendants still capture, but they
       // must take the generic collector branch rather than dereference `_cstBuf`.
       // False means UNKNOWN in this lattice, which is exactly the safe answer.
-      return { tri: at.tri, buf: false, raw: RAW_UNKNOWN, cap: CAP_OFF }
+      const framed = { tri: at.tri, buf: false, raw: RAW_UNKNOWN, cap: CAP_OFF }
+      // A gated pass collapse runs its node term in its parent's collector too.
+      return gated ? meet(at, framed) : framed
     }
     // `ctx._cstBuf = buf` and `ctx.captureTrivia = <literal>`, both unconditional
     // — `emit-assembly.ts`'s `OP_NODE` body opens the buffer before it descends
@@ -178,7 +239,8 @@ function transfer(code: Int32Array, ip: number, at: SiteLabel, hostCst: boolean)
       ? RAW_OMIT
       : RAW_CAPTURE
     if (at.buf && raw === at.raw && cap === at.cap) return at
-    return { tri: at.tri, buf: true, raw, cap }
+    const framed = { tri: at.tri, buf: true, raw, cap }
+    return gated ? meet(at, framed) : framed
   }
   // THE TWO BOUNDARIES clear every capture sink for their child and contribute
   // ONE leaf for the whole match; `token()` clears `ctx.trivia` as well. So a
@@ -251,3 +313,72 @@ export function computeSiteLabels(
 
   return { at: (ip: number): SiteLabel => labels.get(ip) ?? TOP }
 }
+
+/**
+ * Does a piece entered at `ip` need the caller's INSTALLED trivia scanner handed
+ * across an engine boundary?
+ *
+ * Each table engine keeps its own installed-scanner slot, and the two hand theirs
+ * across at every call between them. A site whose label names its trivia (`tri`)
+ * reads no slot: both engines lower its skips onto that trivia's own scanner, and
+ * a call out of it can hand that scanner across instead of the slot. Only a site
+ * whose trivia the labels cannot name (`TRI_UNKNOWN`) reads the slot. So the
+ * handoff is needed exactly when such a site is reachable from `ip` before a
+ * scope installs a scanner of its own (an aliased scope, which installs what is
+ * already installed, does not). `false` is also the answer for a body with no
+ * trivia at all.
+ */
+/**
+ * A trivia scope that writes only what its label proves is already in force, so
+ * it runs as its child. A slot scope under that same slot is one; so is a scope
+ * with no trivia where the label proves none (inside `token()` or another such
+ * scope), since every way to `TRI_NONE` leaves no trivia, no kind labels and no
+ * scanner — what this scope would write. `OP_SCOPE_PLAIN` has no root policy; a
+ * policy-bearing `OP_SCOPE` is one only with policy zero, and `OP_SCOPE_CAP`
+ * never is, since it raises `captureTrivia`. `TRI_UNKNOWN` matches nothing.
+ */
+export function scopeIsIdentity(code: Int32Array, ip: number, at: SiteLabel): boolean {
+  const op = code[ip]
+  if (op !== OP_SCOPE_PLAIN && !(op === OP_SCOPE && code[ip + 3]! === 0)) return false
+  const ki = code[ip + 1]!
+  return at.tri === (ki < 0 ? TRI_NONE : ki)
+}
+
+export function scanHandoffNeeded(code: Int32Array, ip: number, labels: SiteLabels): boolean {
+  const seen = new Set<number>()
+  const stack = [ip]
+  const kids: number[] = []
+  while (stack.length > 0) {
+    const at = stack.pop()!
+    if (seen.has(at)) continue
+    seen.add(at)
+    const l = labels.at(at)
+    if (l.tri === TRI_UNKNOWN) return true
+    const op = code[at]
+    // A scan runs interpreted combinators that reach pieces through `prog.scans`.
+    if (op === OP_SCAN) return true
+    if (op === OP_TOKEN || op === OP_SCOPE_CAP) continue
+    if ((op === OP_SCOPE_PLAIN || op === OP_SCOPE) && !(code[at + 1]! >= 0 && l.tri === code[at + 1]!
+      && (op === OP_SCOPE_PLAIN || code[at + 3]! === 0))) continue
+    kids.length = 0
+    if (!childSlots(code, at, kids)) return true
+    for (const c of kids) stack.push(c)
+  }
+  return false
+}
+
+/**
+ * The first characters that can start trivia at a site labelled `tri`, as code
+ * point ranges: none for `TRI_NONE`, `undefined` where the labels cannot name the
+ * trivia or its first set is unbounded.
+ */
+export function triviaLeadRanges(
+  tri: number, trivia: readonly ({ _meta: { firstSet: { kind: string; ranges?: readonly { lo: number; hi: number }[] } } } | undefined)[],
+): readonly { lo: number; hi: number }[] | undefined {
+  if (tri === TRI_NONE) return []
+  if (tri < 0) return undefined
+  const fs = trivia[tri]?._meta.firstSet
+  if (fs === undefined) return undefined
+  if (fs.kind === 'empty') return []
+  return fs.kind === 'ranges' && fs.ranges !== undefined ? fs.ranges : undefined
+}

package/src/version.ts

@@ -13,4 +13,4 @@
  * Kept in sync with `package.json` by `test/unit/version-sync.test.ts`, which fails
  * the build if this constant drifts from the published version.
  */
-export const PARSEMAN_VERSION = '0.57.0'
+export const PARSEMAN_VERSION = '0.58.0'