parseman 0.51.2 → 0.53.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

@@ -523,8 +523,13 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
    * exact AST workloads execute the three shapes below 42k/66k/205k times per
    * CSS/Less/generated parse. Keep their bodies scalar and keep every other
    * shape on the generic oracle below.
+   *
+   * `trailing` is the node's `trailingTrivia` bit: consume the active trivia
+   * after a successful body, inside the node's span, exactly where the generic
+   * body does. It opens no capture: these shapes are the reducers that read no
+   * trivia log.
    */
-  function plainBuildNode(child: Piece, build: NodeBuilder): Piece {
+  function plainBuildNode(child: Piece, build: NodeBuilder, trailing: boolean): Piece {
     return (input, pos, ctx) => {
       const sCh = ctx._cstChildren
       const sLv = ctx._cstLeaves
@@ -542,6 +547,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
       ctx.captureTrivia = false
       ctx._fields = undefined
       const value = child(input, pos, ctx)
+      if (trailing && value !== FAIL && ctx.trivia !== undefined) EC.e = consumeTrivia(input, EC.e, ctx)
       const kids = buf.ch ?? (buf.single !== undefined ? [buf.single] : EMPTY_CH)
       const rawKids = buf.raw ?? (buf.rawSingle !== undefined ? [buf.rawSingle] : EMPTY_CH)
       ctx._fields = savedFields
@@ -578,7 +584,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
   /** Direct reducer whose declared arity proves `rawChildren` is unobservable.
    * Use the existing split children/leaves collector instead of opening a
    * duplicate raw capture buffer. The body shape is selected while linking. */
-  function childrenOnlyBuildNode(child: Piece, build: NodeBuilder): Piece {
+  function childrenOnlyBuildNode(child: Piece, build: NodeBuilder, trailing: boolean): Piece {
     return (input, pos, ctx) => {
       const sCh = ctx._cstChildren
       const sLv = ctx._cstLeaves
@@ -596,6 +602,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
       ctx.captureTrivia = false
       ctx._fields = undefined
       const value = child(input, pos, ctx)
+      if (trailing && value !== FAIL && ctx.trivia !== undefined) EC.e = consumeTrivia(input, EC.e, ctx)
       const captured = capturedFlatChildren(kids)
       ctx._fields = savedFields
       ctx._cstBuf = sBuf
@@ -1912,6 +1919,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
 
       case OP_ATTEMPT: {
         const child = link(code[ip + 1]!)
+        const contain = code[ip + 2] === 1
         return (input, pos, ctx) => {
           const need = markCst(ctx)
           const mRaw = MRAW
@@ -1924,8 +1932,12 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
           const v = child(input, pos, ctx)
           if (v !== FAIL) return v
           if (need) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
-          // A committed failure propagates VERBATIM — rolled back, not re-anchored.
-          if (committed(ctx)) return FAIL
+          // A committed failure propagates VERBATIM — rolled back, not re-anchored —
+          // unless the row contains commitment, where it is reported like any other.
+          if (committed(ctx)) {
+            if (!contain) return FAIL
+            ctx._fc = false
+          }
           ctx._fe = pos
           return FAIL
         }
@@ -3462,11 +3474,13 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         // data plus this assembly's fixed option set; direct/custom contexts and
         // every richer node shape retain the generic implementation below.
         if (!hostCst && !tracked) {
-          if (build !== undefined && proj < 0 && flags === 0) {
-            return plainBuildNode(child, build)
+          // The trailing-trivia bit (128) rides on the two leanest shapes; it adds
+          // a consume, not a capture.
+          if (build !== undefined && proj < 0 && (flags & ~128) === 0) {
+            return plainBuildNode(child, build, trailingTrivia)
           }
-          if (build !== undefined && proj < 0 && flags === 2) {
-            return childrenOnlyBuildNode(child, build)
+          if (build !== undefined && proj < 0 && (flags & ~128) === 2) {
+            return childrenOnlyBuildNode(child, build, trailingTrivia)
           }
           if (build !== undefined && proj < 0 && flags === 18) {
             return childrenOnlyFieldsBuildNode(child, build)

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

@@ -1,7 +1,7 @@
 import type { Combinator } from '../types.ts'
 import { hasDirectBuildDef } from '../analysis/commitment.ts'
 import type { HostMode } from '../cst/host-mode.ts'
-import { collectGrammarReflection, type GrammarReflection } from '../cst/reflection.ts'
+import { collectGrammarReflection, GRAMMAR_REFLECTION, type GrammarReflection } from '../cst/reflection.ts'
 import { encodeTableProgram, type TableSettings } from './encode.ts'
 import { defaultAssemblyCfgs, emitTableExpression } from './emit.ts'
 import { tableRules } from './assemble.ts'
@@ -54,6 +54,12 @@ const DEFAULT_PRECOMPILE_MIN_WORDS = 1_024
 export type TableRuleMapOptions = {
   /** Grammar-level ambient trivia, as `rules({ trivia }, …)` declares it. */
   readonly trivia?: Combinator<unknown>
+  /**
+   * `compileRuleMapRunnable` only: specialise the runnable table once with generated
+   * code (falling back to closures under CSP). `compile()` alone passes it — no other
+   * runtime path may construct code.
+   */
+  readonly specialise?: boolean
   /** Grammar-level ambient scan-skip, as `rules({ scanSkip }, …)` declares it. */
   readonly scanSkip?: Combinator<unknown>[]
   readonly recovery?: boolean
@@ -120,10 +126,11 @@ export type CompiledRuleMapTable = {
    * hands back text and nothing else, because its artifact only exists once the
    * emitted source is evaluated. A table exists as data before it is printed, so
    * the same call that produces the replacement can also hand back the parser.
-   * It may use runtime assembly specialisation; `prog` and `replacement` remain
-   * serialized closure artifacts. That is what makes a differential against the
-   * interpreter possible without `eval`, and it is why the table-vs-interpreter
-   * test can compare `expected` sets rather than only accept/reject.
+   * It runs the CLOSURE artifact — the engine printed output runs — so building
+   * it never constructs code: only `compile()` specialises (`specialise`), per
+   * docs/design/runtime-and-size-contract.md, rule 1. That is what makes a
+   * differential against the interpreter possible without `eval`, and it is why the
+   * table-vs-interpreter test can compare `expected` sets rather than only accept/reject.
    */
   rules: Record<string, TableRule>
   /** The closure-stamped wire program, for a caller that wants to fold or inspect it. */
@@ -232,13 +239,16 @@ export function compileRuleMapRunnable(
   if (encoded === null) return null
   const { prog, hostMode, plan } = encoded
   const artifact = closureArtifact(prog)
+  const reflection = collectGrammarReflection(ruleMap)
   return {
     keys: ruleMap.map(([key]) => key),
     hostMode,
     hostBranchElided: hostMode === 'ast' && ruleMap.some(([, rule]) => hasDirectBuildDef(rule)),
-    reflection: collectGrammarReflection(ruleMap),
+    reflection,
     ...(plan === undefined ? {} : { coverageDefinitions: plan.definitions }),
-    rules: tableRules(prog),
+    // Reflection rides on the map's metadata prototype from birth. Only `compile()`
+    // asks to specialise; every other caller runs the closure artifact.
+    rules: tableRules(opts.specialise === true ? prog : artifact, { [GRAMMAR_REFLECTION]: reflection }),
     prog: artifact,
   }
 }
@@ -349,7 +359,7 @@ export function compileRuleMap(
     hostBranchElided: hostMode === 'ast' && ruleMap.some(([, rule]) => hasDirectBuildDef(rule)),
     reflection: collectGrammarReflection(ruleMap),
     ...(plan === undefined ? {} : { coverageDefinitions: plan.definitions }),
-    rules: tableRules(prog),
+    rules: tableRules(artifact),
     prog: artifact,
   }
 }

package/src/table/compile.ts

@@ -8,6 +8,9 @@ import { closureArtifact } from './program.ts'
 import { buildGrammarPlan } from '../compiler/grammar-coverage-ids.ts'
 import { runDuplicationDiagnostic, type DuplicationOption } from './duplication-hook.ts'
 import { beginCompileDegradationDrain } from '../compiler/degradation.ts'
+import { compileRuleMapRunnable } from './compile-rule-map.ts'
+import { borrowedRuleMessage, borrowedRuleReference } from '../compiler/borrowed-rules.ts'
+import type { TableRule } from './program.ts'
 
 /**
  * `compile()` FOR THE TABLE LOWERING — same contract, different artifact.
@@ -110,7 +113,65 @@ export type TableCompileOptions = {
   readonly fnSources?: readonly string[]
 }
 
+/**
+ * Compile a whole RULE MAP — a `rules()` grammar or a runtime `compose()` result —
+ * into a map of runnable rules that `run()` / `parseDoc()` take like any other.
+ *
+ * This is how a caller opts a runtime composition into speed: `compose()` only
+ * links an interpreter grammar, and `compile()` encodes it to one table and
+ * specialises that table once. Where the environment forbids generated code (a
+ * Content-Security-Policy without `'unsafe-eval'`) the specialisation throws
+ * `EvalError` and the same table runs on the closure assembler instead.
+ */
+export function compile<T>(combinator: Combinator<T>, mapFnSources?: readonly string[], opts?: TableCompileOptions): CompiledParser<T>
+export function compile(grammar: Record<string, unknown> & { readonly _def?: never }, opts?: { readonly hostMode?: HostMode }): Record<string, TableRule>
 export function compile<T>(
+  target: Combinator<T> | Record<string, unknown>,
+  second?: readonly string[] | { readonly hostMode?: HostMode },
+  third?: TableCompileOptions,
+): CompiledParser<T> | Record<string, TableRule> {
+  if (!isCombinator(target)) return compileMap(target, second as { readonly hostMode?: HostMode } | undefined)
+  return compileRoot(target as Combinator<T>, second as readonly string[] | undefined, third)
+}
+
+function isCombinator(x: unknown): x is Combinator<unknown> {
+  return typeof x === 'object' && x !== null
+    && typeof (x as { parse?: unknown }).parse === 'function' && '_def' in x
+}
+
+function compileMap(grammar: Record<string, unknown>, opts: { readonly hostMode?: HostMode } = {}): Record<string, TableRule> {
+  const entries: Array<[string, Combinator<unknown>]> = []
+  for (const [key, value] of Object.entries(grammar)) {
+    if (!isCombinator(value)) throw new TypeError(`compile: grammar entry "${key}" is not a parser`)
+    // A referenced-but-undefined `g.X` is a hole, not a rule: it has nothing to encode.
+    if (value._def.tag === 'lazy') {
+      try { value._def.thunk() } catch { continue }
+    }
+    entries.push([key, value])
+  }
+  // A runtime composition was already checked when it linked; a plain map is checked
+  // here, because this encoder binds references by name.
+  const borrowed = borrowedRuleReference(Object.fromEntries(entries))
+  if (borrowed !== undefined) throw new Error(borrowedRuleMessage('compile', borrowed))
+  // One aggregated degradation block per compile, exactly as `compileRoot` drains it.
+  const drain = beginCompileDegradationDrain()
+  let done = false
+  try {
+    const refusals: string[] = []
+    const compiled = compileRuleMapRunnable(entries, {
+      ...(opts.hostMode ? { hostMode: opts.hostMode } : {}),
+      refusals,
+      specialise: true,
+    })
+    if (compiled === null) {
+      throw new Error(`compile: this grammar could not be encoded to a table${refusals.length ? ` — ${refusals.join('; ')}` : ''}`)
+    }
+    done = true
+    return compiled.rules
+  } finally { drain(done) }
+}
+
+function compileRoot<T>(
   combinator: Combinator<T>,
   mapFnSources?: readonly string[],
   opts: TableCompileOptions = {},

package/src/table/emit-assembly.ts

@@ -1552,7 +1552,7 @@ ${clean ? '' : emitMark(p, L.buf, L.raw, sinks)}
 const v=${child}(input,pos,ctx)
 if(v!==FAIL)return v
 ${clean ? '' : emitRollback(p, L.buf, L.raw, sinks)}
-if(ctx._fc===true)return FAIL
+${code[ip + 2] === 1 ? 'ctx._fc=false' : 'if(ctx._fc===true)return FAIL'}
 ctx._fe=pos
 return FAIL
 }`
@@ -2334,8 +2334,11 @@ return nd
         // not closure-only semantics. Print the same body for a precompiled
         // assembly so a large composeLeaf artifact does not fall back to opening
         // the generic raw/trivia buffer that its reducer arity proved unread.
+        // The trailing-trivia bit (128) rides on the children-only shape as it
+        // does in the closure assembler: a consume after the body, no capture.
+        const leanFlags = flags & ~128
         if (!hostCst && !tracked && build !== undefined && proj < 0
-          && (flags === 2 || flags === 18 || flags === 34)) {
+          && (leanFlags === 2 || (flags === 18 || flags === 34))) {
           const fields = flags === 18
           const collapseChildren = flags === 34
           const publish = L.buf && L.raw === RAW_OMIT
@@ -2382,7 +2385,9 @@ ctx._cstTriviaLog=undefined
 ctx.captureTrivia=false
 ctx._fields=${fields ? '[]' : 'undefined'}
 const v=${child}(input,pos,ctx)
-const captured=_capturedFlatChildren(flat)
+${trailingTrivia && L.tri !== TRI_NONE
+  ? `if(v!==FAIL${L.tri === TRI_UNKNOWN ? '&&ctx.trivia!==undefined' : ''})EC.e=consumeTrivia(input,EC.e,ctx)\n`
+  : ''}const captured=_capturedFlatChildren(flat)
 ${fields ? 'const fieldMap=buildFieldMap(ctx._fields)\n' : ''}ctx._fields=sFields
 ctx._cstBuf=sBuf
 ctx._cstChildren=sCh

package/src/table/encode-baseline.ts

@@ -295,9 +295,13 @@ class Encoder {
         return this.emit(OP_NOT, this.node(d.parser).ip)
       case 'peek':
         return this.emit(OP_PEEK, this.node(d.parser).ip)
+      // A contained transaction changes what an enclosing choice does next, so
+      // it cannot be transparent.
+      case 'attempt':
+        if (d.contain === true) throw new UnsupportedConstructBaseline('attempt(contain)')
+        return this.node(d.parser).ip
       // Transparent wrappers: no row of their own, no dispatch at run time.
       case 'token':
-      case 'attempt':
       case 'label':
       case 'trivia':
         return this.node(d.parser).ip

package/src/table/encode.ts

@@ -1344,24 +1344,24 @@ class Encoder {
         // 'cst'` forces them on, exactly as the emitted `cstOut` path does. The
         // driver reads a bit; it re-derives nothing and sees no setting.
         const cstOut = this.settings.hostMode === 'cst'
-        // THE THREE DERIVED CAPTURE BITS, mirroring `node.ts:215` term for term:
+        // THE THREE DERIVED CAPTURE BITS, mirroring `node.ts` term for term:
         //
-        //   capturesTrivia = captureTrivia || trailingTrivia
+        //   capturesTrivia = captureTrivia
         //                    || (build ? buildReadsTrivia(def) : project === undefined)
         //
         // `cstOut` is the static stand-in for "a CST host is coming", which the
         // interpreter reaches dynamically off `ctx.build`.
         //
-        // Two of these terms were MISSING and each was a real divergence:
+        // `captureTrivia` was once MISSING here and was a real divergence: an
+        // explicit request the arity analysis cannot express (an author can ask
+        // for capture on a 3-argument reducer). This used to REFUSE rather than
+        // lower, so a documented option no grammar could use through the table.
         //
-        //   `captureTrivia` — an explicit request the arity analysis cannot
-        //     express (an author can ask for capture on a 3-argument reducer).
-        //     This used to REFUSE rather than lower, so a documented option no
-        //     grammar could use through the table.
-        //   `trailingTrivia` — trivia consumed INSIDE the node's capture scope
-        //     lands in THIS node's log. The interpreter counts it; the table did
-        //     not, so a node with `trailingTrivia` and a non-trivia-reading
-        //     reducer captured under the interpreter and dropped under the table.
+        // `trailingTrivia` is NOT a capture term (bit 128 only). It moves the
+        // node's end past the trivia after the body; that trivia reaches the root
+        // table with or without a node log, and only a log the reducer reads is
+        // worth opening. Forcing bit 4 for it put every match of a
+        // non-trivia-reading node on the generic capture path.
         //
         // The `build ? … : project === undefined` split matters now that a
         // STRUCTURAL node lowers: with no builder the interpreter captures unless
@@ -1374,7 +1374,7 @@ class Encoder {
         // Field capture additionally requires the body to CONTAIN `field()`
         // captures: a node that reads fields but has none allocates nothing.
         const wantsFields = parserHasOwnFields(d.parser) && (cstOut || derivedFields)
-        const flags = (cstOut || d.captureTrivia === true || d.trailingTrivia === true || derivedTrivia ? 4 : 0)
+        const flags = (cstOut || d.captureTrivia === true || derivedTrivia ? 4 : 0)
           | (!cstOut && omitsRaw ? 2 : 0)
           | (cstOut || derivedState ? 8 : 0)
           | (wantsFields ? 16 : 0)
@@ -1596,7 +1596,7 @@ class Encoder {
       // A TRANSACTION IS A ROW. See `OP_ATTEMPT` for why the transparent
       // lowering was correct only for a choice arm.
       case 'attempt': {
-        const inner = this.emit(OP_ATTEMPT, this.node(d.parser).ip)
+        const inner = this.emit(OP_ATTEMPT, this.node(d.parser).ip, d.contain === true ? 1 : 0)
         if (!this.failureNeedsRollback(d.parser, undefined)) this.failureRollbackCleanSites.add(inner)
         // THE FIRST-SET FAIL-FAST GUARD, lowered as the `OP_GATE` row the `node()`
         // case already uses — it is the same guard, written twice in the