parseman 0.59.2 → 0.60.0

package/src/table/assemble.ts

@@ -4,7 +4,7 @@
  * This is ledger row G5 as stated: *"build the grammar reference at run start,
  * making the swaps on rules / sub-rules (leaves) at that point, then run with NO
  * logic branching for that option input"*. `exec.ts` builds the same table and
- * then interprets it: one `switch (code[ip])` over 29 opcodes, executed ONCE PER
+ * then interprets it: one `switch (code[ip])` over every opcode (29 then), executed ONCE PER
  * ROW — 497,360 rows for `benchmark.less` (`bench/jess/g5-rows.ts`) — each
  * re-reading its opcode and re-decoding its operands from the `Int32Array`, and
  * re-testing the same per-parse options. That is the per-node branching the
@@ -73,10 +73,11 @@ import { skipDeferredTrivia, triviaLeadTable } from './trivia-gap.ts'
 import { asciiFoldKey } from '../combinators/dispatch.ts'
 import { projectChild, unwrapChild } from '../combinators/node.ts'
 import { cstOutputHost } from '../compiler/build-arity.ts'
+import { PARSEMAN_VERSION } from '../version.ts'
 import { consumeTrivia } from '../combinators/trivia-skip.ts'
 import {
-  advanceTrivia, commitTriviaScan, needsDeferredTriviaCommit, rollbackScannedTriviaAt, rollbackTriviaAt,
-  scanTrivia, scanTriviaCompact, skipTriviaScanned, type FastTriviaScanner,
+  advanceTrivia, needsDeferredTriviaCommit, rollbackScannedTriviaAt, rollbackTriviaAt,
+  skipTriviaScanned, type FastTriviaScanner,
 } from '../combinators/trivia-skip.ts'
 import {
   cstCaptureActive, cstLeavesLen, cstTlLen,
@@ -90,8 +91,8 @@ import {
   OP_LIT_TRACK, OP_RX_TRACK, OP_NODE_TRACK, OP_SCOPE, OP_SCOPE_CAP, OP_SCOPE_PLAIN, OP_EXPECT, OP_SEQX, OP_SCAN,
   OP_LIVE,
   OP_FIELD, OP_DISPATCH, OP_ROUTED, OP_LIT_CI, OP_LIT_CI_TRACK, OP_TOKEN, OP_WITHCTX, OP_GUARD, OP_ATTEMPT, OP_LABEL,
-  OP_COV,
-  OP_ADJ, OP_GREEDY, OP_REJECT, OP_ARMGATE, OP_RGATE,
+  OP_COV, OP_GAPGATE, OP_STRICT,
+  OP_ADJ, OP_GREEDY, OP_REJECT, OP_ARMGATE, OP_RGATE, OP_RGATE2,
   OP_LEX_BODY, OP_LEX_PROGRAM,
 } from './ops.ts'
 import { adjacencyHolds, adjacencyMisuse } from '../combinators/adjacency.ts'
@@ -110,13 +111,13 @@ import {
 } from './emit-assembly.ts'
 import { collapseEmpty, lead, rawEntry, spanLines } from './run-support.ts'
 import { holdsGap, rowNullable } from './hold-gap.ts'
+import { gapRows, newGapSlot } from './gap-gate.ts'
 import { failCleanAnalysis } from './fail-clean.ts'
 /**
  * THE COMPLETIONS PROBE, at the terminal fail sites and nowhere else.
  *
- * `failAt` (combinators/probe.ts) is called from exactly three places in the
- * interpreter — `literal.ts`, `regex.ts`, `keywords.ts` — and codegen emits its
- * mirror (`probeUpdate`) at the same leaf-fail sites. The table recorded
+ * `failAt` (combinators/probe.ts) is called at the interpreter's terminal fail
+ * sites — `literal.ts`, `regex.ts`, `keywords.ts`, `lines.ts`. The table recorded
  * NOTHING, so `completionsAt` on a table artifact saw only the top-level
  * failure: a swallowed item failure inside a `sepBy` (`'{'` at offset 1 in a
  * `{ decl; }` grammar) never reached the probe and the item's opener vanished
@@ -413,6 +414,28 @@ export type Assembly = {
  * ONE walk. Each site is lowered at most once and memoised by its code offset,
  * so a subtree shared by two parents is one piece with two references to it.
  */
+/**
+ * A printed factory takes its helpers BY POSITION (`EMITTED_PARAMS`), so one printed
+ * against a different helper list would bind the wrong function to a name and run
+ * wrong rather than fail. A factory printed by 0.59.x guards only against FEWER
+ * helpers, and one printed before 0.59.0 has no guard at all. So the runtime checks
+ * too, before calling it: the assembly's printed `arity` must be exactly the list it
+ * passes. It reads that printed number, never `factory.length`, which a minifier that
+ * drops unused trailing parameters lowers on a valid artifact. An assembly printed
+ * before 0.60.0 carries no `arity` and is refused. A factory this version prints also
+ * checks the count it is called with (`FACTORY_ARITY_GUARD`, `emit.ts`).
+ */
+export function assertFactoryArity(pre: { readonly arity?: number }): void {
+  if (pre.arity === EMITTED_PARAMS.length) return
+  const printed = pre.arity === undefined
+    ? 'carries no helper count, so it was printed before parseman 0.60.0'
+    : `takes ${pre.arity} helpers, but parseman ${PARSEMAN_VERSION} passes ${EMITTED_PARAMS.length}: it was printed by an older or newer parseman`
+  throw new Error(
+    `parseman: this parser's printed assembly ${printed}. Reprint the parser with `
+    + `parseman ${PARSEMAN_VERSION}, or run it on the parseman version that printed it.`,
+  )
+}
+
 export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Assembly {
   const { code, k, fns, cc, fx, disp, dsp, trivia, triviaLabelled } = t
   // The leaf swap is only legal when line tracking is off, and that is a property
@@ -438,7 +461,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
    * graph with no recovery in it anywhere.
    *
    * Dormancy is unchanged for the OTHER two engines: the source lowering
-   * (`codegen.ts:3153`) and the interpreter (`repeat.ts:163`) still gate on
+   * (removed in 0.47.0) and the interpreter (`repeat.ts:163`) still gate on
    * `ctx._tolerant` at runtime, and the recovery pieces below keep their own
    * `_tolerant === true` failure-path gates so `exec.ts` stays the identity
    * reference.
@@ -503,6 +526,10 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
   }
 
   const labelExtraIps = assemblyExtraIps(prog)
+  // The regex rows an optional repeat hands a scanned gap to (`gap-gate.ts`),
+  // and the one slot it hands it through, shared with the emitted pieces.
+  const GAP_ROWS = gapRows(code, [...Object.values(prog.rules), ...labelExtraIps])
+  const GAP = newGapSlot()
   const closureLabels = computeSiteLabels(
     code, [...Object.values(prog.rules), ...labelExtraIps], hostCst,
   )
@@ -773,6 +800,32 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
     }
   }
 
+  /**
+   * A regex row a repeat may hand a scanned gap to (`gap-gate.ts`): the end comes
+   * from the slot when the slot is this row's, at this position, in this input,
+   * and from the regex otherwise. Everything after the end is the row's own.
+   */
+  function gapRegexPiece(row: number, re: RegExp, xf: string[], track: boolean): Piece {
+    return (input, pos, ctx) => {
+      let e: number
+      if (GAP.row === row && GAP.at === pos && GAP.input === input) e = GAP.end
+      else {
+        re.lastIndex = pos
+        e = re.test(input) ? re.lastIndex : -1
+      }
+      if (e >= 0) {
+        const v = input.slice(pos, e)
+        if (cstCaptureActive(ctx)) pushLeaf(ctx, v, pos, e)
+        if (track) trackLinesInto(ctx, input, e)
+        EC.e = e
+        return v
+      }
+      ctx._fe = pos; ctx._fx = xf
+      if (ctx._probe !== undefined) failAt(ctx, xf, pos)
+      return FAIL
+    }
+  }
+
   /**
    * A collapse over one node is that node — `run-support.ts` `collapseEmpty` has
    * the contract, and the one case the node's value cannot stand for itself.
@@ -1354,7 +1407,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
     }
   }
 
-  function dispatchBranch(child: Piece, usesRouted: boolean): DispatchBranch {
+  function dispatchBranch(child: Piece, usesRouted: boolean, commits = true): DispatchBranch {
     if (!usesRouted) {
       // The arm runs after the selector's match, so it marks where it starts.
       return (input, _pos, selEnd, key, ctx) => {
@@ -1369,7 +1422,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         const v = child(input, selEnd, ctx)
         if (v === FAIL) {
           if (need) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
-          ctx._fc = true
+          if (commits) ctx._fc = true
           return FAIL
         }
         return [key, v]
@@ -1389,7 +1442,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
       }
       if (v === FAIL) {
         if (need) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
-        ctx._fc = true
+        if (commits) ctx._fc = true
         return FAIL
       }
       return [key, v]
@@ -1663,6 +1716,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
       case OP_RX: {
         const re = k[code[ip + 1]!] as RegExp
         const xf = fx[code[ip + 2]!] as string[]
+        if (GAP_ROWS.has(ip)) return gapRegexPiece(ip, re, xf, false)
         const shared = rawScalarSpecs.has(code[ip + 1]!) ? scalarFor(ip) : undefined
         if (shared !== undefined) {
           return (input, pos, ctx) => {
@@ -1701,6 +1755,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
       case OP_RX_TRACK: {
         const re = k[code[ip + 1]!] as RegExp
         const xf = fx[code[ip + 2]!] as string[]
+        if (GAP_ROWS.has(ip)) return gapRegexPiece(ip, re, xf, true)
         return (input, pos, ctx) => {
           re.lastIndex = pos
           if (re.test(input)) {
@@ -1878,6 +1933,14 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         }
       }
 
+      // Transparent: only the repeat holding it reads its operands.
+      case OP_GAPGATE:
+        return link(code[ip + 1]!)
+
+      // One encoding per assembly: strict, or the construct as written.
+      case OP_STRICT:
+        return link(code[cfg.tolerant || cfg.probe ? ip + 2 : ip + 1]!)
+
       case OP_RULE:
         // Pure indirection in the tape; in the assembled graph the parent simply
         // holds the target's piece. The trampoline row disappears entirely — this
@@ -1914,8 +1977,8 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         const expectSpan = (ctx: ParseContext, pos: number) =>
           prog.lines === 1 ? spanLines(ctx, pos, pos) : new PlainSpan(pos, pos)
         // TOLERANT `expect()` EMBEDS ITS ERROR IN THE TREE, not only in the flat
-        // `_errors` side-channel (`combinators/expect.ts:150`, and codegen's
-        // `_ctx._rec.capture` at codegen.ts:4470) — so a tree walk finds every
+        // `_errors` side-channel (`combinators/expect.ts:150`, and the source
+        // lowering's `_ctx._rec.capture`) — so a tree walk finds every
         // diagnostic and the node survives incremental subtree reuse. The table
         // pushed to `_errors` and stopped, so a tolerant CST parse was missing the
         // `parseError` child the other two engines both produce.
@@ -2536,7 +2599,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
          *
          * The restore is `sequence()`'s `finally` (combinators/sequence.ts:105).
          * Codegen does not restore and compensates by having every list capture
-         * `_sync` at ENTRY (codegen.ts:3032); the table captures at entry too, so
+         * `_sync` at ENTRY; the table captures at entry too, so
          * this is unobservable either way — it is here because leaving a stale
          * sentinel published is the kind of state a later reader will trust.
          */
@@ -2950,7 +3013,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
           // `arms[]` merely to rediscover the same two or three children at
           // every dispatch. The classifier remains table data; only its result
           // is turned into a direct captured call.
-          if (n === 2) {
+          if (n === 2 && !cfg.probe) {
             const a0 = link(code[base]!), a1 = link(code[base + 1]!)
             return (input, pos, ctx) => {
               const c = lead(input, pos)
@@ -2975,7 +3038,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
               return FAIL
             }
           }
-          if (n === 3) {
+          if (n === 3 && !cfg.probe) {
             const a0 = link(code[base]!), a1 = link(code[base + 1]!), a2 = link(code[base + 2]!)
             return (input, pos, ctx) => {
               const c = lead(input, pos)
@@ -3008,6 +3071,9 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
             )
           }
           const selected = bindExclusive(0)
+          // Under a completions probe the interpreter runs every arm on a miss
+          // (`choice.ts`), so each opener reaches the probe.
+          const probeArms = cfg.probe ? Array.from({ length: n }, (_, i) => link(code[base + i]!)) : undefined
           // THERE ARE NO OPEN ARMS HERE, and the piece is written to say so. An
           // ungated arm is one whose class is −1, and `resolveDispatch` clears
           // `exclusive` for exactly those arms (program.ts) — so `table.open` is
@@ -3039,6 +3105,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
             // THE UNION IS REPORTED ONLY ON A DISPATCH MISS, where the interpreter's
             // `parsers.flatMap` over non-nullable, char-excluded arms yields exactly
             // each arm's own opener — this set, without running the arms.
+            if (arm < 0 && probeArms !== undefined) for (const a of probeArms) a(input, pos, ctx)
             ctx._fe = pos; ctx._fx = choiceFx
             return FAIL
           }
@@ -3046,8 +3113,9 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
 
         // THE PER-ARM GATE. Arms in source order, each skipped when its own class
         // excludes the char at `pos`. `null` means nullable or unmappable, and
-        // those arms are always entered.
-        const armCls = table.armCls
+        // those arms are always entered. A probe assembly enters every arm, as
+        // the interpreter's `firstMatch` does, so each opener reaches `failAt`.
+        const armCls = cfg.probe ? table.armCls.map(() => null) : table.armCls
         if (n === 2 || n === 3) {
           const a0 = link(code[base]!), a1 = link(code[base + 1]!)
           const a2 = n === 3 ? link(code[base + 2]!) : undefined
@@ -3355,6 +3423,43 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         }
       }
 
+      case OP_RGATE2: {
+        const cls = cc[code[ip + 1]!]!
+        const xf = fx[code[ip + 3]!] as string[]
+        const first = cc[code[ip + 4]!]!
+        const second = cc[code[ip + 5]!]!
+        const child = link(code[ip + 2]!)
+        if (cfg.tolerant || cfg.probe) return child
+        // ASCII-only classes are read as code units against their tables.
+        if (cls.hi.length === 0 && first.hi.length === 0 && second.hi.length === 0) {
+          const a0 = cls.ascii, a1 = first.ascii, a2 = second.ascii
+          return (input, pos, ctx) => {
+            const item = ctx._routed
+            if (item !== undefined && item.span.start === pos) {
+              const e = item.span.end
+              const c = input.charCodeAt(e)
+              if (a0[c] !== 1 || (a1[c] === 1 && a2[input.charCodeAt(e + 1)] !== 1)) {
+                ctx._fe = e; ctx._fx = xf
+                return FAIL
+              }
+            }
+            return child(input, pos, ctx)
+          }
+        }
+        return (input, pos, ctx) => {
+          const item = ctx._routed
+          if (item !== undefined && item.span.start === pos) {
+            const e = item.span.end
+            const c = lead(input, e)
+            if (!classHas(cls, c) || (classHas(first, c) && !classHas(second, lead(input, e + 1)))) {
+              ctx._fe = e; ctx._fx = xf
+              return FAIL
+            }
+          }
+          return child(input, pos, ctx)
+        }
+      }
+
       case OP_ARMGATE: {
         // Predicate, arm and expected set all bound HERE — the body reads no
         // opcode, decodes no operand and tests no setting.
@@ -3451,6 +3556,19 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         // `many()` — the min-0, separator-less repeat — is the only shape that runs
         // its FIRST item through `repItem` and so skips leading trivia. The shape
         // identifies itself, and it is table data, so it is decided here.
+        // A separated list's ip+8 (flag bit 8) is its separator's first set where the encoder
+        // found the test cheaper than entering it (`Encoder.sepGate`). Where the
+        // separator cannot match empty and reads no pre-scan cursor, a lead
+        // outside it stops the list at the separator, exactly as the strict
+        // optional item stops at its own class above.
+        const sepClassIndex = sepIp >= 0 && !sepLeads && (flags & 8) !== 0 ? code[ip + 8]! : -1
+        const sepClass = !REC && sepClassIndex >= 0 && !rowNullable(code, k, sepIp, NULLABLE) ? cc[sepClassIndex]! : undefined
+        // THE GAP GATE (`gap-gate.ts`): read the item's leading gap once, here.
+        const gapIp = sepIp < 0 && min === 0 && !REC && code[code[ip + 1]!] === OP_GAPGATE ? code[ip + 1]! : -1
+        const gapRow = gapIp >= 0 ? code[gapIp + 2]! : -1
+        const gapRe = gapIp >= 0 ? k[code[gapRow + 1]!] as RegExp : undefined
+        const gapFollow = gapIp >= 0 ? cc[code[gapIp + 3]!]! : undefined
+        const gapOther = gapIp >= 0 && code[gapIp + 4]! >= 0 ? cc[code[gapIp + 4]!]! : undefined
         const skipBeforeFirst = sepIp < 0 && min === 0
         const itemClean = sepIp < 0 && CLEAN(code[ip + 1]!) && !rowNullable(code, k, code[ip + 1]!, NULLABLE)
 
@@ -3479,7 +3597,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
          *    delimiter (`orSentinel`, repeat.ts:454).
          *  - `mySync` is captured at ENTRY. An element's own sequence publishes
          *    over `_sync` while it runs; the interpreter restores in a `finally`
-         *    and codegen saves at entry (codegen.ts:3032) — same value, both ways.
+         *    and the source lowering saved at entry — same value, both ways.
          *  - the separator-less path rolls the leading trivia back BEFORE
          *    recovering (repeat.ts's `repItem`), and the separated path does NOT:
          *    a consumed separator and the error after it both belong to the list
@@ -3487,6 +3605,8 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
          */
         if (REC) {
           const itemFx = fx[code[ip + 6]!] as string[]
+          // A resync error carries the item's set as derived (bit 16: empty).
+          const recFx = (flags & 16) !== 0 ? EMPTY_FX : itemFx
           const sepSent = sentinelFor(code[ip + 7]!)
           return (input, pos, ctx) => {
             const out: unknown[] | undefined = collect ? [] : undefined
@@ -3547,7 +3667,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
                   const rr = recoverScan(
                     input, itemStart, ctx,
                     sep === undefined ? mySync : orSentinel(sepSent ?? mySync, sepSent === undefined ? undefined : mySync),
-                    itemFx,
+                    recFx,
                   )
                   if (out !== undefined) out.push(rr.error)
                   captureError(ctx, rr.error)
@@ -3587,6 +3707,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
           // Keep the ordinary child path while one is active so this structural
           // fast stop cannot erase an item completion at the cursor.
           const gateItems = itemMayStart !== undefined && ctx._probe === undefined
+          const gateSep = sepClass !== undefined && ctx._probe === undefined
           let cur = pos
           let count = 0
           for (;;) {
@@ -3618,6 +3739,10 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
               const leavesBefore = cstLeavesLen(ctx)
               let sp = cur
               if (hasTrivia) sp = skipTrivia(input, sp, ctx)
+              if (count >= min && gateSep && !classHas(sepClass!, lead(input, sp))) {
+                if (markIt) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
+                break
+              }
               ctx._fc = false
               if (sepLeads) LEAD.at = cur
               const sv = sep(input, sp, ctx)
@@ -3637,13 +3762,33 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
               if (trailingAllowed && sepEnd >= 0) cur = sepEnd
               break
             }
-            if (count >= min && gateItems && !itemMayStart!(input, itemStart)) {
+            // Without a separator or trivia in front, the loop head already
+            // tested this same position.
+            if (count >= min && gateItems && (sep !== undefined || hasTrivia) && !itemMayStart!(input, itemStart)) {
               if (markIt) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
               if (trailingAllowed && sepEnd >= 0) cur = sepEnd
               break
             }
+            let gapped = false
+            if (gapRe !== undefined && ctx._probe === undefined) {
+              gapRe.lastIndex = itemStart
+              const q = gapRe.test(input) ? gapRe.lastIndex : -1
+              // No arm with the gap can match where the gap fails, or where the
+              // character after it opens nothing; an arm without it needs its
+              // own lead at the item's start.
+              if ((q < 0 || !classHas(gapFollow!, lead(input, q)))
+                && (gapOther === undefined || !classHas(gapOther, lead(input, itemStart)))) {
+                if (markIt) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
+                break
+              }
+              if (q >= 0) {
+                GAP.row = gapRow; GAP.at = itemStart; GAP.end = q; GAP.input = input
+                gapped = true
+              }
+            }
             ctx._fc = false
             const v = child(input, itemStart, ctx)
+            if (gapped) GAP.at = -1
             if (v === FAIL) {
               if (markIt) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
               if (committed(ctx)) return FAIL
@@ -3676,7 +3821,8 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         const selector = link(code[ip + 1]!)
         const otherIp = code[ip + 3]!
         const other = otherIp >= 0 ? link(otherIp) : undefined
-        const otherRouted = code[ip + 4]! === 1
+        const otherRouted = (code[ip + 4]! & 1) === 1
+        const otherCommits = (code[ip + 4]! & 2) === 0
         const n = code[ip + 5]!
         const armBase = ip + 6
         const byKey = spec.byKey
@@ -3723,7 +3869,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
           )
         }
         const runArm = n === 0 ? undefined : bindArms(0)
-        const runOther = other === undefined ? undefined : dispatchBranch(other, otherRouted)
+        const runOther = other === undefined ? undefined : dispatchBranch(other, otherRouted, otherCommits)
 
         return (input, pos, ctx) => {
           const need = markCst(ctx)
@@ -3903,7 +4049,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
           ctx._fields = wantFields ? [] : undefined
           // PER-NODE-TYPE TRIVIA-KIND MASK, scoped to the body and restored —
           // `node.ts:259-273`, and codegen's `_triviaCaptureMask` save/install/
-          // restore around the same scope (`codegen.ts:4130-4136`). The table
+          // restore around the same scope. The table
           // installed nothing, so a host that asked `Outer` for comments only got
           // every kind the scanner saw.
           const savedMask = structural ? ctx._triviaCaptureMask : undefined
@@ -4100,22 +4246,22 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
       ? prog.asm?.find(a => a.key === cfgKey(cfg))
       : undefined
     if (pre !== undefined) {
+      assertFactoryArity(pre)
       const pools = rebuildPools(t.cc, t.fx, t.disp, pre.plan)
       emitted = pre.factory(
-        EC, FAIL, k, fx, fns, pools.masks, pools.classes, pools.armExpected, trivia,
-        trivia.map(tv => tv?._meta.triviaKindLabels), triviaScan,
+        EC, FAIL, k, fx, fns, pools.masks, pools.classes, pools.armExpected, trivia, triviaScan,
         scansArr, disp, dsp, EMPTY_FX, EMPTY_CH, EMPTY_TLOG, EMPTY_TL,
         cstCaptureActive, pushCstLeaf, pushCstChild, rollbackTriviaAt, rollbackScannedTriviaAt, failAt,
         classHas, consumeTrivia, buildFieldMap, projectChild, unwrapChild,
         demoteCapturedToRaw, cstLeavesLen, skipTriviaScanned, needsDeferredTriviaCommit,
-        scanTrivia, advanceTrivia, refuseUnclassifiedRootScope, spanLines, rawEntry, lead,
+        advanceTrivia, refuseUnclassifiedRootScope, spanLines, rawEntry, lead,
         asciiFoldKey, ROUTED_FX,
         REC ? prog.cc.map((_, i) => sentinelFor(i)) : EMPTY_SENTS,
         matchesAt, recoverScan, orSentinel, captureError,
-        scalarRecognizers, commitTriviaScan, scanTriviaCompact, t.lex, adjacencyHolds, t.lexPrograms,
+        scalarRecognizers, t.lex, adjacencyHolds, t.lexPrograms,
         LEAD, triviaFieldCapture, skipDeferredTrivia,
         collapseEmpty,
-        PlainSpan, PlainLeaf, PlainNode, PlainField, PlainBuf,
+        PlainSpan, PlainLeaf, PlainNode, PlainField, PlainBuf, GAP,
       )
       emitReached = new Set(pre.reached)
       if (emitted.ext !== undefined) HYBRID = emitted
@@ -4182,13 +4328,12 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         throw new Unemittable(`the Function constructor (${String(e)})`)
       }
       emitted = factory(
-        EC, FAIL, k, fx, fns, em.masks, em.classes, em.armExpected, trivia,
-        trivia.map(tv => tv?._meta.triviaKindLabels), triviaScan,
+        EC, FAIL, k, fx, fns, em.masks, em.classes, em.armExpected, trivia, triviaScan,
         scansArr, disp, dsp, EMPTY_FX, EMPTY_CH, EMPTY_TLOG, EMPTY_TL,
         cstCaptureActive, pushCstLeaf, pushCstChild, rollbackTriviaAt, rollbackScannedTriviaAt, failAt,
         classHas, consumeTrivia, buildFieldMap, projectChild, unwrapChild,
         demoteCapturedToRaw, cstLeavesLen, skipTriviaScanned, needsDeferredTriviaCommit,
-        scanTrivia, advanceTrivia, refuseUnclassifiedRootScope, spanLines, rawEntry, lead,
+        advanceTrivia, refuseUnclassifiedRootScope, spanLines, rawEntry, lead,
         asciiFoldKey, ROUTED_FX,
         // THE SENTINEL POOL, dense over char-class indices so the emitted text can
         // index it the way it indexes `SCANS`. Built only for a recovery assembly
@@ -4197,10 +4342,10 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         // object rather than to two separately constructed ones.
         REC ? prog.cc.map((_, i) => sentinelFor(i)) : EMPTY_SENTS,
         matchesAt, recoverScan, orSentinel, captureError,
-        scalarRecognizers, commitTriviaScan, scanTriviaCompact, t.lex, adjacencyHolds, t.lexPrograms,
+        scalarRecognizers, t.lex, adjacencyHolds, t.lexPrograms,
         LEAD, triviaFieldCapture, skipDeferredTrivia,
         collapseEmpty,
-        PlainSpan, PlainLeaf, PlainNode, PlainField, PlainBuf,
+        PlainSpan, PlainLeaf, PlainNode, PlainField, PlainBuf, GAP,
       )
       emitReached = em.reached
     } catch (e) {

package/src/table/child-slots.ts

@@ -4,7 +4,7 @@ import {
   OP_LIT_CI_TRACK, OP_LIT_TRACK, OP_LIVE, OP_NODE, OP_NODE_TRACK, OP_NOT, OP_OPT,
   OP_PEEK, OP_REJECT, OP_REP, OP_REPV, OP_ROUTED, OP_RULE, OP_RX, OP_RX_TRACK, OP_SCAN,
   OP_SCOPE, OP_SCOPE_CAP, OP_SCOPE_PLAIN, OP_SEQ, OP_SEQV, OP_SEQX, OP_TOKEN, OP_WITHCTX, OP_XFORM,
-  OP_LEX_BODY, OP_LEX_PROGRAM,
+  OP_LEX_BODY, OP_LEX_PROGRAM, OP_GAPGATE, OP_RGATE2, OP_STRICT,
 } from './ops.ts'
 
 /**
@@ -47,16 +47,21 @@ export function childSlots(code: ArrayLike<number>, ip: number, out: number[]):
     // rest — a coverage-encoded program is a program, and omitting it made
     // `opHistogram` throw on every table the coverage build produces.
     case OP_RULE: case OP_OPT: case OP_NOT: case OP_PEEK: case OP_EXPECT:
-    case OP_TOKEN: case OP_ATTEMPT: case OP_LABEL: case OP_COV: case OP_REJECT:
+    case OP_TOKEN: case OP_ATTEMPT: case OP_LABEL: case OP_COV: case OP_REJECT: case OP_GAPGATE:
       out.push(code[ip + 1]!)
       return true
 
     // Single child at `ip + 2`.
     case OP_GATE: case OP_SCOPE: case OP_SCOPE_CAP: case OP_SCOPE_PLAIN: case OP_WITHCTX: case OP_XFORM:
-    case OP_NODE: case OP_NODE_TRACK: case OP_FIELD: case OP_LEAF: case OP_SOURCE_LEAF: case OP_ARMGATE: case OP_RGATE:
+    case OP_NODE: case OP_NODE_TRACK: case OP_FIELD: case OP_LEAF: case OP_SOURCE_LEAF: case OP_ARMGATE: case OP_RGATE: case OP_RGATE2:
       out.push(code[ip + 2]!)
       return true
 
+    // `STRICT strict tolerant` — both encodings are reachable; an assembly keeps one.
+    case OP_STRICT:
+      out.push(code[ip + 1]!, code[ip + 2]!)
+      return true
+
     // `ROUTED fallback` — the operand is an offset or −1. The routed token itself is
     // data the enclosing `dispatch()` already consumed, so the only edge is the
     // fallback.

package/src/table/compile-rule-map.ts

@@ -19,7 +19,7 @@ import { runDuplicationDiagnosticRules, type DuplicationOption } from './duplica
  * `compileRuleMap()` FOR THE TABLE LOWERING — the counterpart that did not exist.
  *
  * `compile` covered `compile()`, the SINGLE-ROOT entry point, which the
- * plugin uses only for standalone combinators (`plugin/index.ts:1693`, `:1870`).
+ * plugin uses only for standalone combinators.
  * The main path — every `rules()` grammar — goes through `compileRuleMap`, and
  * with no table counterpart there was nothing for the macro build to point at.
  * This is that function, and it is the EASY direction: `encodeTable` takes a
@@ -29,7 +29,7 @@ import { runDuplicationDiagnosticRules, type DuplicationOption } from './duplica
  * ── THE CONTRACT IT MATCHES ──────────────────────────────────────────────────
  * `compileRuleMap` returns ONE `replacement` string: a self-contained expression
  * that the plugin splices over the whole `rules(factory)` call-expression
- * (`plugin/index.ts:1753`, and as an initialiser at `:1941`), evaluating ONCE to
+ * (`evaluateRulesFactory` in `plugin/index.ts`), evaluating ONCE to
  * the `{ name: fn, … }` map. `keys` is the entry list, for the caller to check
  * against the source's own keys. `hostMode` / `hostBranchElided` are what the
  * macro stamps the emitted map with. `reflection` is per-grammar CST node
@@ -59,6 +59,7 @@ export type TableRuleMapOptions = {
   readonly specialise?: boolean
   /** Grammar-level ambient scan-skip, as `rules({ scanSkip }, …)` declares it. */
   readonly scanSkip?: Combinator<unknown>[]
+  /** @deprecated Has no effect (see `TableSettings.recovery`). Removed in the next minor release. */
   readonly recovery?: boolean
   readonly hostMode?: HostMode
   readonly trackLines?: boolean
@@ -264,7 +265,7 @@ function encodeForRun(
 ): { prog: TableProgram; fnSrcs: (string | null)[]; hostMode: HostMode; plan: ReturnType<typeof buildGrammarPlan> | undefined } | null {
   runDuplicationDiagnosticRules(ruleMap, opts.duplication)
   const encodeMap = withAmbient(ruleMap, opts)
-  // WINNERS ARE THE NON-`lazy` ENTRIES, exactly as `codegen.ts:5639` picks them.
+  // WINNERS ARE THE NON-`lazy` ENTRIES, exactly as the source lowering picked them.
   // A `rules()` map stores named lazy proxies beside resolved bodies, and the plan
   // uses the winner map to give a shared subtree ONE owner; filtering differently
   // here would mint `rule:` ids the source lowering does not, so a consumer
@@ -355,9 +356,12 @@ export function compileRuleMap(
     const roots = assemblyExtraIps(artifact)
     let siteBytes, fixed
     try {
-      // Priced without the `_errors` marks a lexical program over a scan adds
-      // (`scanSinkNeutral`), so they move no site in or out of the budget.
-      siteBytes = emitAssemblySource(table, artifact, cfg, roots, true, undefined, true).siteBytes
+      // RANKED with every gap gate lowered as its item (`gapNeutral`), so the
+      // gates move no site's place in the order; the fit below is judged by the
+      // source that ships, gates included. Priced throughout without the
+      // `_errors` marks a lexical program over a scan adds (`scanSinkNeutral`),
+      // so they move no site in or out of the budget.
+      siteBytes = emitAssemblySource(table, artifact, cfg, roots, true, undefined, true, true).siteBytes
       // What any selective assembly costs before its first site body: the shared
       // prelude and the factory's tail. A budget that cannot cover it buys nothing.
       fixed = emitAssemblySource(table, artifact, cfg, roots, true, new Set(), true).source.length

package/src/table/compile.ts

@@ -79,8 +79,8 @@ export type TableCompileOptions = {
   readonly hostMode?: HostMode
   readonly trackLines?: boolean
   /**
-   * ACCEPTED AND IGNORED — recovery is ALWAYS lowered (see `TableSettings.recovery`).
-   * Kept so this stays a drop-in for `compile(g, …, { recovery: true })`.
+   * @deprecated ACCEPTED AND IGNORED — recovery is ALWAYS lowered (see
+   * `TableSettings.recovery`). Removed in the next minor release.
    */
   readonly recovery?: boolean
   /**
@@ -178,7 +178,7 @@ function compileRoot<T>(
 ): CompiledParser<T> {
   // Argument order mirrors `compile(combinator, mapFnSources?, opts?)` so this is
   // a drop-in, not a second API with a different shape.
-  // THE SAME WALK CODEGEN USES FOR A SINGLE ROOT (`codegen.ts:5377`): no winner
+  // THE SAME WALK THE SOURCE LOWERING USED FOR A SINGLE ROOT: no winner
   // map, so the paths are rooted at `entry` and the ids are the ones a caller
   // switching lowerings already has. Building it differently here would produce a
   // set that is internally consistent and lines up with nothing.