parseman 0.52.0 → 0.54.0

package/src/plugin/ir-eval.ts

@@ -0,0 +1,165 @@
+/**
+ * The macro plugin's IR evaluator: turns a composed grammar's carried IR back
+ * into combinators so the build can re-lower it. Build time only — see below.
+ */
+import type { Combinator } from '../types.ts'
+import { rules } from '../combinators/parser.ts'
+import { ref } from '../combinators/ref.ts'
+import { regex } from '../combinators/regex.ts'
+import { literal } from '../combinators/literal.ts'
+import { keywords } from '../combinators/keywords.ts'
+import { sequence } from '../combinators/sequence.ts'
+import { choice } from '../combinators/choice.ts'
+import { dispatch, endsWith, matches, otherwise, routed, startsWith, when } from '../combinators/dispatch.ts'
+import { attempt } from '../combinators/attempt.ts'
+import { many, oneOrMore, optional, sepBy, keepSeparator } from '../combinators/repeat.ts'
+import { not } from '../combinators/not.ts'
+import { peek } from '../combinators/peek.ts'
+import { node } from '../combinators/node.ts'
+import { parser } from '../combinators/grammar.ts'
+import { scanTo, balanced } from '../combinators/scanTo.ts'
+import { token, leaf, sourceLeaf } from '../combinators/token.ts'
+import { classifiedTrivia, transform, trivia, label, field } from '../combinators/map.ts'
+import { expect as expectC } from '../combinators/expect.ts'
+import { withCtx } from '../combinators/withCtx.ts'
+import { adjacent, notAdjacent } from '../combinators/adjacency.ts'
+
+type Comb = Combinator<unknown>
+
+/** Reconstruct a rule map from serialized IR (the inverse of `serializeRuleMap`) —
+ * evaluate the combinator-construction expression with every constructor in scope.
+ *
+ * BUILD TIME ONLY. It evaluates source text, so it lives in the plugin, which runs
+ * in the bundler; no runtime module imports it
+ * (docs/design/runtime-and-size-contract.md, rule 1). */
+export function evalRuleMapIR(ir: string): Array<[string, Comb]> {
+  return Object.entries(evalRulesIR(ir))
+}
+
+/** The `rules()` grammar an IR expression builds — the map plus, non-enumerable,
+ * the recipe (`RULES_RECIPE`) a composition links it by. Build time only, as above. */
+export function evalRulesIR(ir: string): Record<string, Comb> {
+  return evalIR(ir, rules) as Record<string, Comb>
+}
+
+/** The inverse of `serializeCombinator`: the same evaluation, with `rules` reading the
+ * one `scanSkip` unit back instead of building a grammar around it. Build time only. */
+export function evalCombinatorIR(ir: string): Comb | null {
+  const units = evalIR(ir, (opts: { scanSkip?: Comb[] }) => opts.scanSkip) as Comb[] | undefined
+  return units?.length === 1 ? units[0]! : null
+}
+
+function evalIR(ir: string, rulesImpl: unknown): unknown {
+  // `_tf`/`_nd` reconstruct a transform/node AND restore its captured callback
+  // source (`_def.fnSrc`/`buildSrc`) so re-lowering inlines it statically. The live
+  // fn is only needed for interpreted mode; a self-contained transform source is
+  // eval'd, a node build (which may reference imported AST classes) is left to its
+  // source only. Macro-only validation metadata is carried as plain data: this
+  // runtime module never parses callback source or imports a compiler frontend.
+  const _tf = (child: Comb, src: string, recognitionOnly = false): Comb => {
+    let fn: (...a: unknown[]) => unknown
+    // eslint-disable-next-line no-eval
+    try { fn = (0, eval)(`(${src})`) } catch { fn = () => { throw new Error('IR transform fn not materialized') } }
+    const t = transform(child as never, fn as never)
+    ;(t._def as { fnSrc?: string }).fnSrc = src
+    if (recognitionOnly) (t._def as { recognitionOnly?: boolean }).recognitionOnly = true
+    return t as Comb
+  }
+  const _lf = (child: Comb, src: string, source = false): Comb => {
+    let fn: (...a: unknown[]) => unknown
+    // eslint-disable-next-line no-eval
+    try { fn = (0, eval)(`(${src})`) } catch { fn = () => { throw new Error('IR leaf fn not materialized') } }
+    const l = source ? sourceLeaf(child as never, fn as never) : leaf(child as never, fn as never)
+    ;(l._def as { fnSrc?: string }).fnSrc = src
+    return l as Comb
+  }
+  const _nd = (type: string, child: Comb, src: string, opts?: unknown, staticError?: readonly string[], sigSrc?: string, buildImports?: ReadonlyArray<{ local: string; source: string; imported: string }>, rawUnused?: true): Comb => {
+    if (staticError !== undefined && staticError.length > 0) {
+      // Fail closed: a builder with an un-rescuable binding is NOT fused. The
+      // plugin catches this and leaves the runtime compose() in place rather than
+      // shipping a fused table that would ReferenceError on import. Import-rescued
+      // free names never reach here — they ride in `buildImports`, not `staticError`.
+      throw new Error(`IR direct node builder for ${type} must be macro-static and self-contained; unsupported binding(s): ${staticError.join(', ')}`)
+    }
+    // A serialized direct builder needs an inert sentinel as well as buildSrc.
+    // `node(..., undefined)` is structural, so re-lowering a composed artifact
+    // silently routes it through ctx.build/default CST even though the IR still
+    // carries the callback source. The compiler is the only consumer that may
+    // materialize `buildSrc`; raw IR interpretation deliberately rejects direct
+    // builders rather than evaluating arbitrary captured source at runtime.
+    const n = node(type, child as never, (() => { throw new Error('IR node build requires static re-lowering') }) as never, opts as never)
+    ;(n._def as { buildSrc?: string; buildStaticError?: readonly string[] }).buildSrc = src
+    if (staticError !== undefined) (n._def as { buildStaticError?: readonly string[] }).buildStaticError = staticError
+    // Analysis-only resolved reducer signature (see `buildAnalysisSrc`). Without it a
+    // re-lowered composed artifact silently re-acquires the fail-open capture cost the
+    // authoring module had already resolved away.
+    if (sigSrc !== undefined) (n._def as { buildSigSrc?: string }).buildSigSrc = sigSrc
+    if (rawUnused === true) (n._def as { buildRawUnused?: true }).buildRawUnused = true
+    // Re-attach the direct-builder import provenance so the plugin's re-lower pass
+    // can re-emit the imports into the consuming module. Plain data — this runtime
+    // module never resolves or emits imports itself.
+    if (buildImports !== undefined) (n._def as { buildImports?: ReadonlyArray<{ local: string; source: string; imported: string }> }).buildImports = buildImports
+    return n as Comb
+  }
+  // `_gch` rebuilds a GATED choice AND restores its `_def.gateSrcs` (parallel to the
+  // arms) — the gate mirror of `_tf`/`_nd`. Each item is either a plain arm or a
+  // `[gateSource, arm]` tuple: the source is eval'd to the live predicate (interpreted
+  // mode) and recorded as the arm's gateSrcs entry so re-lowering INLINES the gate
+  // statically (keeping the artifact fusible via `emitFusedSource`). A missing/failed
+  // source falls back to a throwing predicate — the same contract as `_tf`.
+  const _gch = (items: Array<Comb | [string, Comb]>): Comb => {
+    const gateSrcs: (string | null)[] = []
+    const arms = items.map(it => {
+      if (Array.isArray(it)) {
+        const [src, comb] = it
+        gateSrcs.push(src)
+        let gate: (s: unknown) => boolean
+        // eslint-disable-next-line no-eval
+        try { gate = (0, eval)(`(${src})`) } catch { gate = () => { throw new Error('IR gate fn not materialized') } }
+        return { gate, combinator: comb }
+      }
+      gateSrcs.push(null)
+      return it
+    })
+    const c = (choice as (...a: unknown[]) => Comb)(...arms)
+    // `choice` is the authority on gate alignment; `gateSrcs` must line up 1:1 with
+    // the constructed `_def.gates`. They always do on the normal path (both from the
+    // same `items.map`), but assert it so a future change in `choice` that coalesces
+    // or drops arms can't silently ship a mis-aligned gate-source array.
+    const gates = (c._def as { gates?: unknown[] }).gates
+    if (gates && gates.length !== gateSrcs.length) {
+      throw new Error(`_gch: gateSrcs length ${gateSrcs.length} != choice gates length ${gates.length}`)
+    }
+    ;(c._def as { gateSrcs?: (string | null)[] }).gateSrcs = gateSrcs
+    return c
+  }
+  // `_wc` rebuilds a `withCtx` AND restores its `_def.extraSrc` (the source of the
+  // `extra`/state value) — the withCtx mirror of `_tf`/`_nd`/`_gch`. The source is
+  // eval'd to the live `extra` value (interpreted mode) and recorded on the def so
+  // re-lowering INLINES the state getter statically (`() => (extraSrc)`), keeping the
+  // artifact fusible via `emitFusedSource`. A plain `withCtx(value, inner)` would
+  // leave `extraSrc` unset → codegen emits a source-less runtime closure (a non-static
+  // callback) → `emitFusedSource` fails and a downstream `compose()` silently falls
+  // back to a runtime fuse. A missing/failed source falls back to `undefined` state —
+  // the same best-effort contract as `_tf`.
+  const _wc = (src: string, inner: Comb): Comb => {
+    let extra: unknown
+    // eslint-disable-next-line no-eval
+    try { extra = (0, eval)(`(${src})`) } catch { extra = undefined }
+    const w = (withCtx as (e: unknown, c: Comb) => Comb)(extra, inner)
+    ;(w._def as { extraSrc?: string }).extraSrc = src
+    return w
+  }
+  // eslint-disable-next-line no-new-func
+  const fn = new Function(
+    'rules', 'ref', 'regex', 'literal', 'keywords', 'sequence', 'choice', 'dispatch', 'when', 'startsWith', 'endsWith', 'matches', 'otherwise', 'routed', 'attempt',
+    'many', 'oneOrMore', 'optional', 'sepBy', 'keepSeparator', 'not', 'peek', 'node', 'parser',
+    'scanTo', 'balanced', 'token', 'leaf', 'transform', 'trivia', 'classifiedTrivia', 'label', 'field', 'expect', 'adjacent', 'notAdjacent', '_tf', '_lf', '_nd', '_gch', '_wc',
+    `return (${ir})`,
+  )
+  return fn(
+    rulesImpl, ref, regex, literal, keywords, sequence, choice, dispatch, when, startsWith, endsWith, matches, otherwise, routed, attempt,
+    many, oneOrMore, optional, sepBy, keepSeparator, not, peek, node, parser,
+    scanTo, balanced, token, leaf, transform, trivia, classifiedTrivia, label, field, expectC, adjacent, notAdjacent, _tf, _lf, _nd, _gch, _wc,
+  )
+}

package/src/plugin/reducer-resolver.ts

@@ -118,8 +118,11 @@ function patternNames(pat: unknown, out: string[]): void {
 }
 
 function declare(scope: ScopeNode, name: string, b: Binding): void {
-  // First declaration wins; a duplicate `var` re-declaration does not change the shape.
-  if (!scope.bindings.has(name)) scope.bindings.set(name, b)
+  // First declaration wins the shape, but a second one (`var x = a; … var x = b`, a
+  // repeated function) can rebind the name, so it counts as a reassignment.
+  const prev = scope.bindings.get(name)
+  if (prev) prev.reassigned = true
+  else scope.bindings.set(name, b)
 }
 
 /** `var` and function declarations hoist to the nearest FUNCTION scope, not the block. */
@@ -238,7 +241,10 @@ function markReassignments(body: unknown[], root: ScopeNode): void {
     if (Array.isArray(n)) { for (const item of n) walk(item); return }
     const node = n as AnyNode
     if (typeof node.type !== 'string') return
-    if (node.type === 'AssignmentExpression' || node.type === 'UpdateExpression') {
+    // `for (x of …)` / `for (x in …)` writes `x` too when its head declares nothing.
+    const loopWrite = (node.type === 'ForOfStatement' || node.type === 'ForInStatement')
+      && (node.left as AnyNode | undefined)?.type !== 'VariableDeclaration'
+    if (node.type === 'AssignmentExpression' || node.type === 'UpdateExpression' || loopWrite) {
       const target = (node.type === 'UpdateExpression' ? node.argument : node.left) as AnyNode | undefined
       const names: string[] = []
       if (target) patternNames(target, names)
@@ -255,6 +261,17 @@ function markReassignments(body: unknown[], root: ScopeNode): void {
   for (const stmt of body) walk(stmt)
 }
 
+/**
+ * Whether a top-level binding of a module is never reassigned or redeclared, so a `let` or
+ * `var` holds its initializer exactly as a `const` would. Bundlers emit top-level `const`
+ * as `var` (esbuild does), which is how a published entry's exports usually arrive.
+ */
+export function topLevelIsStable(body: unknown[], moduleEnd: number): (name: string) => boolean {
+  const root = buildScopeTree(body, moduleEnd)
+  markReassignments(body, root)
+  return name => root.bindings.get(name)?.reassigned !== true
+}
+
 // ---------------------------------------------------------------------------
 // Parameter list → arity, from the AST
 // ---------------------------------------------------------------------------

package/src/spec/railroad-lib.ts

@@ -2,12 +2,18 @@
  * Vendored copy of tabatkins railroad-diagrams (v1.0.0), license CC0-1.0.
  * https://github.com/tabatkins/railroad-diagrams
  *
- * Public domain (CC0) — embedded verbatim as strings so the generated
- * railroad-diagram HTML page is fully self-contained (no CDN, no runtime dep).
+ * Public domain (CC0). The library is held ONCE, as real code: `railroadLibrary`
+ * renders SVG in Node, and `RAILROAD_JS` embeds the same function's own source in
+ * the generated HTML page (no CDN, no runtime dep). Nothing evaluates a string —
+ * docs/design/runtime-and-size-contract.md, rule 1.
  * Do not edit by hand; regenerate from the npm package if bumping versions.
  */
 /* eslint-disable */
-export const RAILROAD_JS: string = `/*
+// @ts-nocheck — vendored third-party JavaScript, kept verbatim.
+
+/** Install the railroad-diagrams builders onto `exports`. */
+export function railroadLibrary(exports) {
+/*
 Railroad Diagrams
 by Tab Atkins Jr. (and others)
 http://xanthir.com
@@ -90,7 +96,7 @@ At runtime, these constants can be found on the Diagram class.
 	};
 	FakeSVG.prototype.escapeString = function(string) {
                 // Escape markdown and HTML special characters
-		return string.replace(/[*_\\\`\\[\\]<&]/g, function(charString) {
+		return string.replace(/[*_\`\[\]<&]/g, function(charString) {
 			return '&#' + charString.charCodeAt(0) + ';';
 		});
 	};
@@ -112,7 +118,7 @@ At runtime, these constants can be found on the Diagram class.
 			str += ' ' + attr + '="' + (this.attrs[attr]+'').replace(/&/g, '&amp;').replace(/"/g, '&quot;') + '"';
 		}
 		str += '>';
-		if(group) str += "\\n";
+		if(group) str += "\n";
 		if(typeof this.children == 'string') {
 			str += FakeSVG.prototype.escapeString(this.children);
 		} else {
@@ -120,7 +126,7 @@ At runtime, these constants can be found on the Diagram class.
 				str += e;
 			});
 		}
-		str += '</' + this.tagName + '>\\n';
+		str += '</' + this.tagName + '>\n';
 		return str;
 	}
 
@@ -522,7 +528,7 @@ At runtime, these constants can be found on the Diagram class.
 	*/
 	['Diagram', 'ComplexDiagram', 'Sequence', 'Choice', 'Optional', 'OneOrMore', 'ZeroOrMore', 'Terminal', 'NonTerminal', 'Comment', 'Skip']
 		.forEach(function(e,i) { root[e] = temp[i]; });
-}).call(this,
+}).call(undefined,
 	{
 	VERTICAL_SEPARATION: 8,
 	ARC_RADIUS: 10,
@@ -531,7 +537,11 @@ At runtime, these constants can be found on the Diagram class.
 	INTERNAL_ALIGNMENT: 'center',
 	}
 );
-`
+
+}
+
+/** The same library as page script: installs its builders as browser globals. */
+export const RAILROAD_JS: string = `(${railroadLibrary.toString()})(window);`
 
 export const RAILROAD_CSS: string = `svg.railroad-diagram {
     background-color: hsl(30,20%,95%);

package/src/spec/railroad.ts

@@ -8,7 +8,7 @@
  */
 import type { Production, SpecModel, SpecNode } from './model.ts'
 import { renderExpr } from './ebnf.ts'
-import { RAILROAD_CSS, RAILROAD_JS } from './railroad-lib.ts'
+import { RAILROAD_CSS, RAILROAD_JS, railroadLibrary } from './railroad-lib.ts'
 
 const j = (s: string): string => JSON.stringify(s)
 
@@ -69,7 +69,7 @@ function toDsl(node: SpecNode): string {
   }
 }
 
-// Vendored railroad-diagrams builders, evaluated once. `.toString()` on the
+// Vendored railroad-diagrams builders, installed once. `.toString()` on the
 // result walks an in-memory FakeSVG tree and emits SVG markup with no DOM — so a
 // diagram can be rendered to a static SVG string at build time (Node), not just
 // in the browser. The library exports onto `exports` when it's an object.
@@ -89,8 +89,7 @@ let _builders: RailroadBuilders | null = null
 function builders(): RailroadBuilders {
   if (_builders) return _builders
   const mod = {} as Record<string, unknown>
-  // eslint-disable-next-line no-new-func
-  new Function('exports', RAILROAD_JS)(mod)
+  railroadLibrary(mod)
   _builders = mod as unknown as RailroadBuilders
   return _builders
 }

package/src/table/assemble.ts

@@ -66,6 +66,7 @@
 import type { Combinator, FieldMap, FirstSet, ParseContext, ParseResult, ParserDef } from '../types.ts'
 import { balanced, scanTo } from '../combinators/scanTo.ts'
 import { buildFieldMap } from '../compiler/fields.ts'
+import { FIELD_LEADING_TRIVIA, FIELD_TRAILING_TRIVIA, LEAD, triviaFieldCapture } from '../combinators/field-trivia.ts'
 import { asciiFoldKey } from '../combinators/dispatch.ts'
 import { projectChild, unwrapChild } from '../combinators/node.ts'
 import { cstOutputHost } from '../compiler/build-arity.ts'
@@ -129,7 +130,7 @@ import { computeSiteLabels, reachableSites } from './site-labels.ts'
 import { refuseUnclassifiedRootScope } from '../cst/root-trivia-scope.ts'
 import { captureError, firstSetSentinel, matchesAt, orSentinel, recoverScan } from '../recovery/scan.ts'
 import {
-  leadingLiteralFamily, leadingScalarSequence, leadingScalarTerminal, makeScalarRecognizer, scalarTerminalNodeChild,
+  largeChoiceLiteralPretest, leadingScalarSequence, leadingScalarTerminal, makeScalarRecognizer, scalarTerminalNodeChild,
   scalarTerminalNotChild, type ScalarRecognizer,
 } from './scalar-terminal.ts'
 
@@ -146,6 +147,7 @@ const EMIT_ENABLED = (globalThis as { process?: { env?: Record<string, string |
 
 /** Failure sentinel — SHARED with the other two engines, see `cell.ts`. */
 import { FAIL, newEndCell } from './cell.ts'
+import { fieldSpec, leadingTriviaFieldAt } from './field-spec.ts'
 
 const EMPTY_TL: readonly number[] = Object.freeze([])
 /** `finishCstBuf`'s two empty sentinels, held here so the node piece can inline it. */
@@ -1053,6 +1055,15 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
     return cur
   }
 
+  /**
+   * A `field(…, { leadingTrivia: true })` term. The pre-scan cursor reaches the
+   * field AFTER `step`'s scan, right before the field runs, so a field inside the
+   * trivia grammar cannot take it first. One closure per call; only such terms pay.
+   */
+  function leadingFieldTerm(step: typeof nextTerm, child: Piece, input: string, cur: number, ctx: ParseContext): number {
+    return step((i, p, c) => { LEAD.at = cur; return child(i, p, c) }, input, cur, ctx)
+  }
+
   function committed(c: ParseContext): boolean {
     return c._fc === true
   }
@@ -1793,12 +1804,27 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
       }
 
       case OP_FIELD: {
-        const name = k[code[ip + 1]!] as string
+        const { name, bits } = fieldSpec(k[code[ip + 1]!])
         const child = link(code[ip + 2]!)
+        if (bits === 0) {
+          return (input, pos, ctx) => {
+            const v = child(input, pos, ctx)
+            if (v === FAIL) return FAIL
+            ctx._fields?.push({ name, value: v, span: { start: pos, end: EC.e } })
+            return v
+          }
+        }
+        const leading = (bits & FIELD_LEADING_TRIVIA) !== 0
+        const trailing = (bits & FIELD_TRAILING_TRIVIA) !== 0
         return (input, pos, ctx) => {
+          const leadFrom = leading ? LEAD.at : -1
+          LEAD.at = -1
           const v = child(input, pos, ctx)
           if (v === FAIL) return FAIL
-          ctx._fields?.push({ name, value: v, span: { start: pos, end: EC.e } })
+          const end = EC.e
+          const trailEnd = trailing && ctx.trivia !== undefined ? consumeTrivia(input, end, ctx) : end
+          ctx._fields?.push(triviaFieldCapture(name, v, input, pos, end, leadFrom, trailEnd))
+          EC.e = trailEnd
           return v
         }
       }
@@ -2322,6 +2348,12 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
             const kidIp = code[base + i]!
             if (code[kidIp] !== OP_ADJ) {
               const kid = link(kidIp)
+              if (leadingTriviaFieldAt(code, k, kidIp)) {
+                return (input, cur, ctx, inherited) => {
+                  ctx._sync = sync ?? inherited
+                  return leadingFieldTerm(step, kid, input, cur, ctx)
+                }
+              }
               return (input, cur, ctx, inherited) => {
                 ctx._sync = sync ?? inherited
                 return step(kid, input, cur, ctx)
@@ -2389,14 +2421,22 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
           }
         }
 
+        // A `field(…, { leadingTrivia: true })` term is a boundary fact too: the
+        // runner hands it the cursor from BEFORE the scan (`LEAD`, cell.ts).
         let hasAdj = false
-        for (let i = 1; i < n; i++) if (code[code[base + i]!] === OP_ADJ) { hasAdj = true; break }
+        for (let i = 1; i < n; i++) {
+          const kidIp = code[base + i]!
+          if (code[kidIp] === OP_ADJ || leadingTriviaFieldAt(code, k, kidIp)) { hasAdj = true; break }
+        }
         if (hasAdj) {
           const first = link(code[base]!)
           const runnerAt = (i: number): TermRunner => {
             const kidIp = code[base + i]!
             if (code[kidIp] !== OP_ADJ) {
               const kid = link(kidIp)
+              if (leadingTriviaFieldAt(code, k, kidIp)) {
+                return (input, cur, ctx) => leadingFieldTerm(step, kid, input, cur, ctx)
+              }
               return (input, cur, ctx) => step(kid, input, cur, ctx)
             }
             const negated = code[kidIp + 1] === 1
@@ -2791,7 +2831,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         if (n === 2 || n === 3) {
           const a0 = link(code[base]!), a1 = link(code[base + 1]!)
           const a2 = n === 3 ? link(code[base + 2]!) : undefined
-          const predecide = !hostCst && !REC && !cfg.probe && !cfg.coverage && !cfg.trackLines
+          const predecide = !REC && !cfg.probe && !cfg.coverage && !cfg.trackLines
           const p0ip = predecide ? leadingScalarTerminal(code, code[base]!, 2, true, true) : -1
           const p1ip = predecide ? leadingScalarTerminal(code, code[base + 1]!, 2, true, true) : -1
           const p2ip = predecide && n === 3 ? leadingScalarTerminal(code, code[base + 2]!, 2, true, true) : -1
@@ -2958,6 +2998,56 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
             )
           }
           const masked = bindMasked(0, EMPTY_EXPECTED_PREFIX)
+          // LITERAL PRETESTS. First-char dispatch cannot tell `@{…}` or `@@x` from
+          // `@x`, so every arm sharing the char is entered, and under a CST host
+          // each entered node opens a capture frame before failing on the second
+          // char. An arm that must begin with a literal of two or more chars (or
+          // one of a family of them) is tested on the literal first and, on a
+          // miss, skipped exactly as a char-excluded arm is: its static expected
+          // set is the one reported. The test is pure, so a miss leaves no
+          // capture, trivia or field to roll back.
+          const pBit: number[] = []
+          const pRec: ScalarRecognizer[] = []
+          if (!REC && !cfg.probe && !cfg.coverage && !cfg.trackLines) {
+            for (let i = 0; i < n; i++) {
+              for (const terminal of largeChoiceLiteralPretest(code, k, code[base + i]!) ?? []) {
+                pBit.push(1 << i)
+                pRec.push(scalarFor(terminal)!)
+              }
+            }
+          }
+          const pn = pBit.length
+          if (pn !== 0) {
+            return (input, pos, ctx) => {
+              const c = lead(input, pos)
+              const need = markCst(ctx)
+              const mRaw = MRAW
+              const mTl = MTL
+              const mLv = MLV
+              const mFl = need ? ctx._fields?.length ?? 0 : 0
+              const mEr = need ? ctx._errors?.length ?? 0 : 0
+              const mLog = need ? ctx._triviaLog?.length ?? 0 : 0
+              const mRoot = need ? ctx._rootTriviaLog?.length ?? 0 : 0
+              if (c < 128) {
+                const bits = mask[c < 0 ? 128 : c]!
+                let tested = 0
+                let hit = 0
+                for (let i = 0; i < pn; i++) {
+                  const b = pBit[i]!
+                  if ((bits & b) === 0 || (hit & b) !== 0) continue
+                  tested |= b
+                  if (pRec[i]!(input, pos) >= 0) hit |= b
+                }
+                return masked(
+                  input, pos, ctx, bits & (~tested | hit),
+                  need, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot, undefined, 0, pos,
+                )
+              }
+              return general(
+                input, pos, ctx, c, need, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot, undefined, 0, pos,
+              )
+            }
+          }
           return (input, pos, ctx) => {
             const c = lead(input, pos)
             const need = markCst(ctx)
@@ -3100,6 +3190,8 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         const max = code[ip + 3]!
         const sepIp = code[ip + 4]!
         const sep = sepIp >= 0 ? link(sepIp) : undefined
+        // A `field(…, { leadingTrivia: true })` separator reads the pre-scan cursor.
+        const sepLeads = sepIp >= 0 && leadingTriviaFieldAt(code, k, sepIp)
         const flags = code[ip + 5]!
         const keepSeparators = (flags & 2) !== 0
         const trailingAllowed = (flags & 1) !== 0
@@ -3183,6 +3275,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
                 let sp = cur
                 if (hasTrivia) sp = skipTrivia(input, sp, ctx)
                 ctx._fc = false
+                if (sepLeads) LEAD.at = cur
                 const sv = sep(input, sp, ctx)
                 if (sv === FAIL) {
                   if (needMark) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
@@ -3283,6 +3376,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
               let sp = cur
               if (hasTrivia) sp = skipTrivia(input, sp, ctx)
               ctx._fc = false
+              if (sepLeads) LEAD.at = cur
               const sv = sep(input, sp, ctx)
               if (sv === FAIL) {
                 if (needMark) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
@@ -3706,20 +3800,9 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
               if (child >= 0) scalarFor(child)
               continue
             }
-            if (child >= 0) {
-              const spec = k[code[child + 1]!]
-              if (code[child] === OP_LIT && typeof spec === 'string' && spec.length >= 2) {
-                scalarFor(child)
-                continue
-              }
-            }
-            const family = leadingLiteralFamily(code, k, armIp)
-            if (family !== undefined && family.length >= 2 && family.every(terminal => {
-              const value = k[code[terminal + 1]!]
-              return typeof value === 'string' && value.length >= 2
-            })) {
-              for (const terminal of family) scalarFor(terminal)
-            }
+            const literals = largeChoiceLiteralPretest(code, k, armIp)
+            if (literals !== undefined) for (const terminal of literals) scalarFor(terminal)
+            if (literals !== undefined && literals.length === 1 && literals[0] === child) continue
             const sequence = leadingScalarSequence(code, armIp)
             if (sequence !== undefined && (sequence.trivia < 0
               || triviaScan[sequence.trivia] != null)) {
@@ -3767,6 +3850,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         REC ? prog.cc.map((_, i) => sentinelFor(i)) : EMPTY_SENTS,
         matchesAt, recoverScan, orSentinel, captureError,
         scalarRecognizers, commitTriviaScan, scanTriviaCompact, t.lex, adjacencyHolds, t.lexPrograms,
+        LEAD, triviaFieldCapture,
       )
       emitReached = new Set(pre.reached)
     }
@@ -3848,6 +3932,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         REC ? prog.cc.map((_, i) => sentinelFor(i)) : EMPTY_SENTS,
         matchesAt, recoverScan, orSentinel, captureError,
         scalarRecognizers, commitTriviaScan, scanTriviaCompact, t.lex, adjacencyHolds, t.lexPrograms,
+        LEAD, triviaFieldCapture,
       )
       emitReached = em.reached
     } catch (e) {
@@ -4067,6 +4152,13 @@ export class AssemblyCache {
   }
 }
 
+/**
+ * One rule of the map. A lowered terminal is emitted as this call, not as
+ * `tableRules(…)["Entry"]`: `@__PURE__` covers a call and not a property read
+ * after it, so a bundler had to keep the whole table of every terminal nothing
+ * referenced. With the lookup inside the call the statement is droppable.
+ */
+export function tableRules(source: TableProgram | CompactProgram, entry: string): TableRule
 /**
  * The ASSEMBLED rule map — the same artifact contract as `tableRules`, run
  * through linked closures instead of the bytecode interpreter.
@@ -4076,11 +4168,19 @@ export class AssemblyCache {
  * assembly built for it. Everything past that point is pieces, and no piece body
  * reads an option — `scripts/check-invariants.mjs` INV-6 asserts it. `forCtx`
  * carries the argument for why that read is irreducible rather than merely cheap.
+ *
+ * Declared last, so `ReturnType<typeof tableRules>` stays the map.
  */
 export function tableRules(
   source: TableProgram | CompactProgram,
-  artifactMetadata: Readonly<Record<symbol, unknown>> = {},
-): Record<string, TableRule> {
+  artifactMetadata?: Readonly<Record<symbol, unknown>>,
+): Record<string, TableRule>
+export function tableRules(
+  source: TableProgram | CompactProgram,
+  metadataOrEntry: Readonly<Record<symbol, unknown>> | string = {},
+): Record<string, TableRule> | TableRule {
+  const entry = typeof metadataOrEntry === 'string' ? metadataOrEntry : undefined
+  const artifactMetadata = typeof metadataOrEntry === 'string' ? {} : metadataOrEntry
   const prog = expandCompact(source)
   const resolved = resolveTable(prog)
   const cache = new AssemblyCache(prog, resolved)
@@ -4105,7 +4205,7 @@ export function tableRules(
    * `runRule`, after the outer read.
    */
   let selected: Assembly | undefined
-  return stampRuleMap(prog, {
+  const map = stampRuleMap(prog, {
     runRule: (ri, input, pos, ctx) => {
       const a = selected ?? cache.forCtx(ctx)
       selected = undefined
@@ -4128,4 +4228,8 @@ export function tableRules(
       return a.scanSkip[skipOf?.[ri] ?? -1]
     },
   }, artifactMetadata, resolved)
+  if (entry === undefined) return map
+  // Own properties only: the map inherits `toString`, `constructor` and the rest.
+  if (!Object.hasOwn(map, entry)) throw new Error(`tableRules: the program has no rule ${JSON.stringify(entry)}`)
+  return map[entry]!
 }