parseman 0.59.2 → 0.60.0

package/src/table/emit-assembly.ts

@@ -47,11 +47,11 @@
 import type { ParseContext } from '../types.ts'
 import { regexCanMatchEmpty } from '../regex/first-set.ts'
 import {
-  OP_ADJ, OP_ARMGATE, OP_RGATE, OP_ATTEMPT, OP_CHOICE, OP_DISPATCH, OP_EMPTY, OP_EXPECT, OP_FIELD, OP_GATE,
+  OP_ADJ, OP_ARMGATE, OP_RGATE, OP_RGATE2, OP_ATTEMPT, OP_CHOICE, OP_DISPATCH, OP_EMPTY, OP_EXPECT, OP_FIELD, OP_GATE,
   OP_LABEL, OP_LEAF, OP_SOURCE_LEAF, OP_LIT, OP_LIT_CI, OP_LIT_CI_TRACK, OP_LIT_TRACK, OP_NAMES,
   OP_NODE, OP_NODE_TRACK, OP_NOT, OP_OPT, OP_PEEK, OP_REP, OP_REPV, OP_ROUTED, OP_RULE, OP_RX,
   OP_RX_TRACK, OP_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_STRICT,
 } from './ops.ts'
 import {
   choiceCannotCommit, choiceRollbackMask, failureRollbackClean, validateDispatchSpec,
@@ -67,10 +67,16 @@ import {
   scalarTerminalNodeChild, scalarTerminalNotChild, scalarTerminalPeekChild, type LeadingScalarSequence,
 } from './scalar-terminal.ts'
 import { childSlots } from './child-slots.ts'
-import { holdsGap } from './hold-gap.ts'
+import { holdsGap, rowNullable } from './hold-gap.ts'
+import { gapRows } from './gap-gate.ts'
 import { fieldSpec, leadingTriviaFieldAt } from './field-spec.ts'
 import { FIELD_LEADING_TRIVIA, FIELD_TRAILING_TRIVIA } from '../combinators/field-trivia.ts'
 
+/** Does a gap's regex lower to an inline scan (`scanShapeFromRegex`)? */
+function gapRegexLowers(re: unknown): boolean {
+  return re instanceof RegExp && scanShapeFromRegex(re.source, re.flags) !== null
+}
+
 /** What the compiled factory hands back — the emitted twin of `Assembly`. */
 export type EmittedPiece = (input: string, pos: number, ctx: ParseContext) => unknown
 export type EmittedAssembly = {
@@ -109,12 +115,12 @@ export class Unemittable extends Error {
  * runs and is wrong, which no type in this file would catch.
  */
 export const EMITTED_PARAMS = [
-  'EC', 'FAIL', 'K', 'FX', 'FNS', 'MASK', 'CLS', 'AFX', 'TRIVIA', 'TRIVIALABELS', 'TRIVIASCAN',
+  'EC', 'FAIL', 'K', 'FX', 'FNS', 'MASK', 'CLS', 'AFX', 'TRIVIA', 'TRIVIASCAN',
   'SCANS', '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',
   // RECOVERY, bound rather than reimplemented. `SENTS` is the sync sentinel per
   // char-class index — the emitted twin of `assemble.ts`'s `sentinelFor` memo,
@@ -124,27 +130,24 @@ export const EMITTED_PARAMS = [
   // engine and cannot drift.
   'SENTS', 'matchesAt', 'recoverScan', 'orSentinel', 'captureError',
   // Pure scalar terminal recognizers, indexed by the terminal's existing const
-  // operand. Appended for compatibility with older precompiled factories.
-  'RECOG',
-  // Appended so precompiled factories produced by earlier runtimes keep every
-  // positional helper binding. Older factories ignore this trailing argument.
-  'commitTriviaScan', 'scanTriviaCompact', 'LEX',
-  // Appended for old precompiled-factory ABI: old factories ignore it.
-  'adjacencyHolds',
-  // Appended for selected composite lexical programs; old factories ignore it.
+  // operand; selected lexical bodies; the adjacency test.
+  'RECOG', 'LEX', 'adjacencyHolds',
+  // Selected composite lexical programs.
   'LEXPROG',
-  // Appended for trivia-attributing fields (`field(…, { leadingTrivia })`);
-  // old factories ignore them.
+  // Trivia-attributing fields (`field(…, { leadingTrivia })`).
   'LEAD', 'triviaFieldCapture',
-  // Appended for the deferred-commit trivia skip (`trivia-gap.ts`); old
-  // factories ignore it.
+  // The deferred-commit trivia skip (`trivia-gap.ts`).
   'skipDeferredTrivia',
-  // Appended for the pass-through collapse (`run-support.ts`); old factories
-  // ignore it.
+  // The pass-through collapse (`run-support.ts`).
   'collapseEmpty',
-  // Appended for constructor-built tree objects (`cst/plain.d.ts`): a `new` call has
-  // no allocation site, so V8 cannot pretenure them. Old factories ignore them.
+  // Constructor-built tree objects (`cst/plain.d.ts`): a `new` call has no
+  // allocation site, so V8 cannot pretenure them.
   '_SP', '_LF', '_ND', '_FC', '_BUF',
+  // The gap gate's slot (`gap-gate.ts`).
+  'GAP',
+  // Artifacts are version-locked (docs/design/artifact-format.md): a factory is
+  // only ever called by the runtime that emitted it, so a name nothing emitted
+  // reads is removed rather than kept for an older factory's positions.
 ] as const
 
 /**
@@ -605,6 +608,12 @@ export function emitAssemblySource(
    * then emitted with them.
    */
   scanSinkNeutral = false,
+  /**
+   * Lower every gap gate (`gap-gate.ts`) as the item it wraps. A selection is
+   * ranked on this lowering, so adding the gates moves no site's place in the
+   * order; the fit is judged by the source that ships, gates included.
+   */
+  gapNeutral = false,
 ): EmitResult {
   const { code, k, fx, disp, dsp, triviaLabelled } = t
   const swapLegal = !cfg.trackLines
@@ -643,6 +652,10 @@ export function emitAssemblySource(
   // emitted scope supplies a context this pass cannot see.
   const roots = [...Object.values(prog.rules), ...extraIps]
   const reachable = [...reachableSites(code, roots)]
+  // A gap whose regex lowers to an inline scan is scanned again by its row, for
+  // less than reading the slot costs; only a gap matched by its RegExp takes the
+  // slot (`gapRegexLowers`).
+  const GAP_ROWS = gapNeutral ? new Set<number>() : new Set([...gapRows(code, roots)].filter(row => !gapRegexLowers(k[code[row + 1]!])))
   const labels = computeSiteLabels(code, roots, hostCst)
   // Eligibility is pooled by the terminal's existing constant operand, matching
   // the closure recognizer pool: distinct terminal rows sharing one spec share
@@ -807,7 +820,7 @@ export function emitAssemblySource(
   const armExpectedPlan: number[][] = []
   const maskPlan: number[] = []
 
-  /** `codegen.ts`'s hoisted pools, same spelling: `_k<N>` / `_fx<N>` / `_fn<N>`. */
+  /** Hoisted pools, in the source lowering's spelling: `_k<N>` / `_fx<N>` / `_fn<N>`. */
   function hoist(kind: string, expr: string): string {
     const hit = pool.get(expr)
     if (hit !== undefined) return hit
@@ -1172,7 +1185,8 @@ ${cfg.probe ? `failAt(ctx,${xf},pos)\n` : ''}return FAIL
     // `OP_GATE` under a probe or a tolerant recovery is a no-op that forwards to
     // its child, exactly as `assemble.ts:952` resolves it.
     if (op === OP_GATE && (cfg.tolerant || cfg.probe)) return code[ip + 2]!
-    if (op === OP_RULE) return code[ip + 1]!
+    if (op === OP_RULE || op === OP_GAPGATE) return code[ip + 1]!
+    if (op === OP_STRICT) return code[cfg.tolerant || cfg.probe ? ip + 2 : ip + 1]!
     // A SCOPE THAT INSTALLS WHAT IS ALREADY INSTALLED. `encode.ts:520` wraps
     // EVERY rule of a `rules({ trivia }, …)` map in its own `OP_SCOPE_PLAIN`, so a
     // grammar with one ambient trivia re-installs the same slot at every rule
@@ -1191,6 +1205,7 @@ ${cfg.probe ? `failAt(ctx,${xf},pos)\n` : ''}return FAIL
   function lower(ip: number, fname: string): string {
     const op = code[ip]
     const head = `function ${fname}(input,pos,ctx){`
+    const outerHead = head
     const L = labels.at(ip)
     const sinks = sinksAt(ip)
     /**
@@ -1310,6 +1325,26 @@ ${cfg.probe ? `failAt(ctx,${xf},pos)\n` : ''}return FAIL
       case OP_RX_TRACK: {
         const xf = fxRef(code[ip + 2]!)
         const track = op === OP_RX_TRACK
+        // A gap row takes the end a repeat already scanned (`gap-gate.ts`), and
+        // otherwise matches its sticky regex: one compact body, no second copy of
+        // the success path.
+        if (GAP_ROWS.has(ip)) {
+          const re = hoist('gx', `K[${code[ip + 1]!}]`)
+          return `${outerHead}
+let e
+if(GAP.row===${ip}&&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)
+${captureLeaf('v')}
+${track ? '_trackLines(ctx,input,e)\n' : ''}EC.e=e
+return v
+}
+ctx._fe=pos;ctx._fx=${xf}
+${cfg.probe ? `failAt(ctx,${xf},pos)\n` : ''}return FAIL
+}`
+        }
+        const head = outerHead
         if (!track && scalarSpecs.has(code[ip + 1]!)) {
           const recognize = recognizerRef(code[ip + 1]!)
           return `${head}
@@ -1401,6 +1436,31 @@ return ${child}(input,pos,ctx)
 }`
       }
 
+      case OP_RGATE2: {
+        const child = link(code[ip + 2]!)
+        if (cfg.tolerant || cfg.probe) return `${head}
+return ${child}(input,pos,ctx)
+}`
+        // ASCII-only classes (the usual case: `:` then whitespace) are read as
+        // code units against their ASCII tables, with no call.
+        const idxs = [code[ip + 1]!, code[ip + 4]!, code[ip + 5]!]
+        const ascii = idxs.every(i => isAsciiOnlyClass(t.cc[i]!))
+        const ref = (idx: number, tag: string): string => {
+          const ci = classes.push([t.cc[idx]!]) - 1
+          classPlan.push([idx])
+          return hoist(tag, `CLS[${ci}][0]`)
+        }
+        const [cls, first, second] = [ref(idxs[0]!, 'cl'), ref(idxs[1]!, 'c1'), ref(idxs[2]!, 'c2')]
+        const has = (c: string, at: string): string => ascii ? `${c}.ascii[${at}]===1` : `classHas(${c},${at})`
+        const xf = fxRef(code[ip + 3]!)
+        return `${head}
+const it=ctx._routed
+if(it!==undefined&&it.span.start===pos){const e=it.span.end;const c=${ascii ? 'input.charCodeAt(e)' : 'lead(input,e)'}
+if(!(${has(cls, 'c')})||(${has(first, 'c')}&&!(${has(second, ascii ? 'input.charCodeAt(e+1)' : 'lead(input,e+1)')}))){ctx._fe=e;ctx._fx=${xf};return FAIL}}
+return ${child}(input,pos,ctx)
+}`
+      }
+
       case OP_ARMGATE: {
         // `choice({ gate, combinator })`, as `assemble.ts` lowers it. A blocked
         // arm is SKIPPED, not failed (choice.ts `continue`): it clears the cut,
@@ -1489,8 +1549,8 @@ return v
         const xf = fxRef(code[ip + 2]!)
         // TWO ARMS, mirroring `assemble.ts:1050`. A TOLERANT `expect()` EMBEDS
         // ITS ERROR IN THE TREE and not only in the flat `_errors` side-channel
-        // (`combinators/expect.ts:150`, codegen's `_ctx._rec.capture` at
-        // codegen.ts:4470) — so a tree walk finds every diagnostic and the node
+        // (`combinators/expect.ts:150`, the source lowering's
+        // `_ctx._rec.capture`) — so a tree walk finds every diagnostic and the node
         // survives incremental subtree reuse. `captureError` is the shared
         // function, called; the embedding is not restated here.
         //
@@ -1914,7 +1974,30 @@ if(ctx._fc===true)return FAIL
 const af=ctx._fx
 if(af!==undefined&&af.length>0){ctx._fe=pos;return FAIL}
 }
-ctx._fe=pos;ctx._fx=${choiceFx}
+${cfg.probe ? `if(arm<0){${arms.map(a => `${a}(input,pos,ctx)`).join(';')}}
+` : ''}ctx._fe=pos;ctx._fx=${choiceFx}
+return FAIL
+}`
+        }
+
+        if (cfg.probe) {
+          // A probe assembly enters every arm in source order, as the
+          // interpreter's `firstMatch` does, so each opener reaches `failAt`.
+          const p = tmp()
+          return `${head}
+${emitMark(p, L.buf, L.raw, sinks)}
+let acc
+let best=pos
+${arms.map(arm => `{ctx._fc=false
+const v=${arm}(input,pos,ctx)
+if(v!==FAIL)return v
+const at=ctx._fe??pos
+if(at>best){best=at;acc=undefined}
+if(at===best)acc=_accSet(ctx._fx,acc)
+if(ctx._fc===true){if(acc!==undefined)ctx._fx=acc;return FAIL}
+${emitRollback(p, L.buf, L.raw, sinks)}
+}`).join('\n')}
+ctx._fe=pos;ctx._fx=acc??${choiceFx}
 return FAIL
 }`
         }
@@ -2194,7 +2277,8 @@ return FAIL
         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]!
         validateDispatchSpec(spec, n, code[ip + 4]!)
         const armBase = ip + 6
@@ -2258,7 +2342,7 @@ ${fallbackCase}
 }
 if(v===FAIL){
 ${emitRollback(m2, L.buf, L.raw, sinks)}
-ctx._fc=true
+${other !== undefined && !otherCommits ? 'if(arm!==undefined)' : ''}ctx._fc=true
 return FAIL
 }
 return [key,v]
@@ -2293,6 +2377,69 @@ return [key,v]
         const itemMiss = (at: string): string => itemAscii
           ? `${itemCls}.ascii[input.charCodeAt(${at})]!==1`
           : `!classHas(${itemCls},lead(input,${at}))`
+        // The separator's own first set (ip+7, `assemble.ts` `sepClass`).
+        let sepCls: string | undefined
+        let sepAscii = false
+        if (!REC && sepIp >= 0 && (code[ip + 5]! & 8) !== 0 && !leadingTriviaFieldAt(code, k, sepIp) && !rowNullable(code, k, sepIp, nullable)) {
+          const resolved = t.cc[code[ip + 8]!]!
+          const ci = classes.push([resolved]) - 1
+          classPlan.push([code[ip + 8]!])
+          sepCls = hoist('rs', `CLS[${ci}][0]`)
+          sepAscii = isAsciiOnlyClass(resolved)
+        }
+        // THE GAP GATE (`gap-gate.ts`, `assemble.ts`): the item's leading gap is
+        // read once here and handed to its regex row through the slot.
+        const gapIp = !gapNeutral && sepIp < 0 && min === 0 && !REC && code[code[ip + 1]!] === OP_GAPGATE ? code[ip + 1]! : -1
+        let gapCode = (_rb: string): string => ''
+        if (gapIp >= 0) {
+          const row = code[gapIp + 2]!
+          const rx = k[code[row + 1]!]
+          const shape = gapRegexLowers(rx) ? scanShapeFromRegex((rx as RegExp).source, (rx as RegExp).flags) : null
+          const cls = (idx: number): string => {
+            const resolved = t.cc[idx]!
+            const ci = classes.push([resolved]) - 1
+            classPlan.push([idx])
+            const ref = hoist('gc', `CLS[${ci}][0]`)
+            return isAsciiOnlyClass(resolved) ? `${ref}.ascii[input.charCodeAt(${'@'})]!==1` : `!classHas(${ref},lead(input,${'@'}))`
+          }
+          const follow = cls(code[gapIp + 3]!).replaceAll('@', 'gq')
+          const other = code[gapIp + 4]! >= 0 ? cls(code[gapIp + 4]!).replaceAll('@', 'itemStart') : 'true'
+          if (shape !== null) {
+            // Scanned inline, as the row scans it: no slot to fill or read.
+            let n = 0
+            const q = tmp()
+            const m = emitShapeMatch(shape, 'itemStart', (prefix = '_v') => `${q}${prefix}${n++}`, '')
+            gapCode = (rbCode: string): string => `let gapped=false
+if(ctx._probe===undefined){
+${m.setup.join('\n')}
+const gq=${m.ok}?${m.end}:-1
+if((gq<0||${follow})&&${other}){
+${rbCode}
+break
+}
+}
+`
+          } else {
+            const re = hoist('gr', `K[${code[row + 1]!}]`)
+            gapCode = (rbCode: string): string => `let gapped=false
+if(ctx._probe===undefined){
+${re}.lastIndex=itemStart
+const gq=${re}.test(input)?${re}.lastIndex:-1
+if((gq<0||${follow})&&${other}){
+${rbCode}
+break
+}
+if(gq>=0){
+GAP.row=${row};GAP.at=itemStart;GAP.end=gq;GAP.input=input
+gapped=true
+}
+}
+`
+          }
+        }
+        const sepMiss = (at: string): string => sepAscii
+          ? `${sepCls}.ascii[input.charCodeAt(${at})]!==1`
+          : `!classHas(${sepCls},lead(input,${at}))`
         const skipBeforeFirst = sepIp < 0 && min === 0
         const p = tmp()
         // `viaRepItem` is `sep === undefined && count >= min && (count > 0 ||
@@ -2387,7 +2534,7 @@ ${p}rt=ctx._rootTriviaLog!==undefined?ctx._rootTriviaLog.length:0${markSinks}
         // is taken unconditionally by the closure engine (`assemble.ts:2067`), so
         // it is resolved separately from `itemFx` — reusing that one would hand
         // `EMPTY_FX` to every recovered error in a grammar that does not report.
-        const recFx = REC ? fxRef(code[ip + 6]!) : ''
+        const recFx = !REC ? '' : (flags & 16) !== 0 ? '[]' : fxRef(code[ip + 6]!)
         const sepSent = REC ? sentRef(code[ip + 7]!) : 'undefined'
         const recSent = sep === undefined
           ? my
@@ -2405,7 +2552,7 @@ continue
 `
         return `${head}
 const out=${collect ? '[]' : 'undefined'}
-${knownTrivia === undefined ? 'const hasTrivia=ctx.trivia!==undefined\n' : ''}${L.buf ? '' : 'const needMark=_rollbackNeeded(ctx)\n'}${REC ? `const ${my}=ctx._sync\n` : ''}${itemCls === undefined ? '' : `const ${p}gate=ctx._probe===undefined\n`}let cur=pos
+${knownTrivia === undefined ? 'const hasTrivia=ctx.trivia!==undefined\n' : ''}${L.buf ? '' : 'const needMark=_rollbackNeeded(ctx)\n'}${REC ? `const ${my}=ctx._sync\n` : ''}${itemCls === undefined && sepCls === undefined ? '' : `const ${p}gate=ctx._probe===undefined\n`}let cur=pos
 let count=0
 for(;;){
 ${max >= 0 ? `if(count>=${max})break\n` : ''}${sep !== undefined ? `if(count>0&&count>=${min}&&cur>=input.length)break\n` : ''}${itemCls !== undefined && sep === undefined ? `if(count>=${min}&&${p}gate&&${hasTrivia === 'false' ? 'true' : hasTrivia === 'true' ? 'false' : '!hasTrivia'}&&${itemMiss('cur')})break\n` : ''}let ${p}raw=0,${p}tl=0,${p}lv=0,${p}lg=0,${p}rt=0${sinks.fd ? `,${p}fd=0` : ''}${sinks.er ? `,${p}er=0` : ''}
@@ -2415,7 +2562,11 @@ let sepEnd=-1
 ${sep !== undefined ? `if(count>0){
 const lb=cstLeavesLen(ctx)
 let sp=cur
-${hasTrivia === 'false' ? '' : hasTrivia === 'true' ? `sp=${skip}(input,sp,ctx)\n` : `if(hasTrivia)sp=${skip}(input,sp,ctx)\n`}ctx._fc=false
+${hasTrivia === 'false' ? '' : hasTrivia === 'true' ? `sp=${skip}(input,sp,ctx)\n` : `if(hasTrivia)sp=${skip}(input,sp,ctx)\n`}${sepCls === undefined ? '' : `if(count>=${min}&&${p}gate&&${sepMiss('sp')}){
+${rb}
+break
+}
+`}ctx._fc=false
 ${sepIp >= 0 && leadingTriviaFieldAt(code, k, sepIp) ? 'LEAD.at=cur\n' : ''}const sv=${sep}(input,sp,ctx)
 if(sv===FAIL){
 ${rb}
@@ -2430,13 +2581,13 @@ itemStart=${hasTrivia === 'false' ? 'EC.e' : hasTrivia === 'true' ? `${skip}(inp
 ${rb}
 ${trailingAllowed ? 'if(sepEnd>=0)cur=sepEnd\n' : ''}break
 }
-${itemCls === undefined ? '' : `if(count>=${min}&&${p}gate&&${itemMiss('itemStart')}){
+${itemCls === undefined || (sep === undefined && hasTrivia === 'false') ? '' : `if(count>=${min}&&${p}gate&&${sep === undefined && hasTrivia === 'hasTrivia' ? 'hasTrivia&&' : ''}${itemMiss('itemStart')}){
 ${rb}
 ${trailingAllowed ? 'if(sepEnd>=0)cur=sepEnd\n' : ''}break
 }
-`}ctx._fc=false
+`}${gapCode(rb)}ctx._fc=false
 const v=${child}(input,itemStart,ctx)
-if(v===FAIL){
+${gapIp >= 0 ? 'if(gapped)GAP.at=-1\n' : ''}if(v===FAIL){
 ${REC
   // THE ROLLBACK MOVES INSIDE THE ARMS. The strict loop rolls back
   // unconditionally before testing `_fc`, which is sound because every path out
@@ -2734,7 +2885,7 @@ return nd
   const ruleEntries: string[] = []
   for (const [rname, entryIp] of Object.entries(prog.rules)) {
     if (!served(entryIp)) continue
-    // `_r_<Name>` — the composition surface, in `codegen.ts`'s own spelling and
+    // `_r_<Name>` — the composition surface, in the source lowering's spelling and
     // deliberately NOT namespaced, so a sibling calls it by name.
     const target = link(entryIp)
     const rn = `_r_${rname.replace(/[^A-Za-z0-9_$]/g, '_')}`

package/src/table/emit.ts

@@ -6,18 +6,20 @@ import { cfgKey, type RunCfg } from './assemble.ts'
 import { PARSEMAN_VERSION } from '../version.ts'
 
 /**
- * Opens every printed assembly factory. A runtime older than the printer passes fewer
- * helpers; refuse it when the assembly is built, instead of failing partway through the
- * first parse on whichever helper is reached first. Runs once per assembly.
+ * Opens every printed assembly factory. Helpers are bound BY POSITION, so a runtime that
+ * passes any other number of them, fewer or more, binds the wrong function to a name;
+ * refuse it when the assembly is built, instead of failing partway through the first parse
+ * on whichever helper is reached first. Runs once per assembly.
  */
-export const FACTORY_ARITY_GUARD = `if(arguments.length<${EMITTED_PARAMS.length})throw new Error(${JSON.stringify(`parseman: this parser was printed by parseman ${PARSEMAN_VERSION}; upgrade the parseman runtime to at least that version`)});`
+export const FACTORY_ARITY_GUARD = `if(arguments.length!==${EMITTED_PARAMS.length})throw new Error(${JSON.stringify(`parseman: this parser was printed by parseman ${PARSEMAN_VERSION}; run it on parseman ${PARSEMAN_VERSION} or reprint it`)});`
 
 /**
  * Print a program as the module a build emits.
  *
- * Everything here is DATA plus the author's own reducers. The recognizer is not
- * in this string — it is `exec.ts`, imported from the runtime, shared by every
- * grammar in the bundle and by every variant of each.
+ * Everything here is DATA plus the author's own reducers, and any assemblies
+ * the build pre-compiled (`a:`). The recognizer is not in this string: it is
+ * `tableRules` from `parseman/table`, shared by every grammar in the bundle and
+ * by every variant of each.
  */
 
 function jsString(s: string): string {
@@ -170,11 +172,10 @@ export function defaultAssemblyCfgs(prog: TableProgram): RunCfg[] {
  * Print the assemblies a build pre-compiled, as the `a:` field of the program
  * literal — see `TableProgram.asm`.
  *
- * THE FACTORY IS A REAL FUNCTION LITERAL. This is a low-level experiment, not
- * a normal compiler route: normal `compile()` and macro output both serialize
- * `a:[]` and use the compact closure assembler. If a future specialization can
- * meet semantic identity and the size budget, it must preserve that one public
- * artifact contract rather than recreate the old runtime/macro split.
+ * THE FACTORY IS A REAL FUNCTION LITERAL. A macro build emits one here for the
+ * AST, no-line-tracking option set, holding only the sites it selected within its
+ * budget (`compile-rule-map.ts`, `selectAssembly`); every other option set gets
+ * no entry and runs the closure assembler.
  *
  * A refusal is not an error. `Unemittable` names a construct the emitter does
  * not lower; that option set simply gets no entry, and `assemble.ts` runs the
@@ -186,7 +187,7 @@ function emitAssemblies(prog: TableProgram, cfgs: readonly AssemblyCfg[]): strin
    *
    * The field's PRESENCE is the compiler artifact contract. That is what switches
    * the runtime `Function` constructor off (`assemble.ts`), and it costs four
-   * bytes. Its CONTENTS are optional experimental factories; with none, the
+   * bytes. Its CONTENTS are the build's selected factories; with none, the
    * artifact runs the closure engine — no eval, no
    * size growth, and the refusal readable on `Assembly.emitRefusal`.
    *
@@ -229,6 +230,7 @@ function emitAssemblies(prog: TableProgram, cfgs: readonly AssemblyCfg[]): strin
     const plan = em.plan
     out.push('{'
       + `key:${key},`
+      + `arity:${EMITTED_PARAMS.length},`
       + `factory:function(${EMITTED_PARAMS.join(',')}){${FACTORY_ARITY_GUARD}${em.source}\n},`
       + 'plan:{'
       + `classes:[${plan.classes.map(r => `[${r.join(',')}]`).join(',')}],`
@@ -248,12 +250,11 @@ export type EmitOptions = {
   /** Name of the exported binding. */
   readonly name?: string
   /**
-   * Optional experimental emitted factories — see `defaultAssemblyCfgs`.
+   * Emitted factories to pre-compile — see `defaultAssemblyCfgs`.
    *
-   * The normal compiler and macro both emit `a:[]`: that is the canonical
-   * compact closure artifact and it never reaches the `Function` constructor.
-   * Supplying factories here is a low-level serialization experiment, not a
-   * second normal compilation path; it is not used by the macro plugin.
+   * Without them the artifact prints `a:[]`, the compact closure artifact, which
+   * never reaches the `Function` constructor. The macro plugin passes one
+   * selective assembly here (`compile-rule-map.ts`, `replacementWithMetadata`).
    */
   readonly assemblies?: readonly AssemblyCfg[]
   /**