parseman 0.52.0 → 0.53.0

package/dist/version.d.ts

@@ -13,5 +13,5 @@
  * Kept in sync with `package.json` by `test/unit/version-sync.test.ts`, which fails
  * the build if this constant drifts from the published version.
  */
-export declare const PARSEMAN_VERSION = "0.52.0";
+export declare const PARSEMAN_VERSION = "0.53.0";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parseman",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "packageManager": "pnpm@10.15.1",
   "engines": {
     "node": "^20.19.0 || >=22.13.0"

package/src/combinators/parser.ts

@@ -37,6 +37,31 @@ function isNamedRuleRefForAnotherRule(r: Combinator<unknown>, key: string): bool
   return name !== undefined && name !== key
 }
 
+/** Every rule value a finished `rules()` call holds. See `ownRule`. */
+const claimedRules = new WeakSet<object>()
+
+/**
+ * `rules()` stamps its options (`trivia`, `scanSkip`, `hostMode`, `trackLines`) and the
+ * rule name onto the rule object itself. So a value ANOTHER grammar already holds — one
+ * terminal returned by two factories, or a rule of grammar A returned by grammar B —
+ * must not be stamped in place: the second grammar would overwrite the first's options,
+ * or inherit them wherever it omits one, and the two would parse different input than
+ * either declared. This grammar takes its own shallow copy instead, with none of those
+ * stamps. (A rule ref's `parse` still reads the meta it closes over — that is the other
+ * grammar's rule carrying its own trivia, exactly as a `g.X` reference to it would.)
+ */
+function ownRule(p: Combinator<unknown>, copies: Map<object, Combinator<unknown>>): Combinator<unknown> {
+  // A trivia rule is never stamped, and its identity is what ties it to `{ trivia }`.
+  if (!claimedRules.has(p) || p._meta.isTrivia) return p
+  let own = copies.get(p)
+  if (own === undefined) {
+    const { grammarTrivia: _t, grammarScanSkip: _s, grammarHostMode: _h, grammarTrackLines: _l, ...meta } = p._meta
+    // One copy per grammar, so a value under two keys stays one object here too.
+    copies.set(p, own = { ...p, _meta: meta })
+  }
+  return own
+}
+
 /**
  * Define named grammar rules without forward declarations.
  *
@@ -140,7 +165,52 @@ export function rules<T extends Record<string, Combinator<unknown>>>(
 ): RulesResult<T> {
   const factory = (typeof a === 'function' ? a : b) as (self: any) => T
   const options = (typeof a === 'function' ? b : a) as RulesOptions | undefined
-  const cache: Partial<T> = {}
+  const recipe: RulesRecipe = { factory, options }
+  const map = linkRules([recipe])
+  Object.defineProperty(map, RULES_RECIPE, { value: [recipe], enumerable: false })
+  return map as RulesResult<T>
+}
+
+/**
+ * The recipe a `rules()` result was built from — its factory and options —
+ * non-enumerable, in piece order. Runtime `compose()` links grammars by running
+ * these again against ONE shared namespace (`linkRules`), which is what makes a
+ * composition the same graph as one `rules()` written over every piece. A
+ * composed result carries the concatenated list, so it composes again.
+ */
+export const RULES_RECIPE = Symbol.for('parseman.rulesRecipe')
+export type RulesRecipe = {
+  readonly factory: (self: Record<string, Combinator<unknown>>) => Record<string, Combinator<unknown>>
+  readonly options: RulesOptions | undefined
+}
+
+/**
+ * How a composition overrides its pieces' own options: the composing grammar's
+ * trivia governs every rule (composing-wins), and an explicit host mode wins
+ * over each piece's.
+ */
+export type LinkOptions = {
+  readonly trivia?: Combinator<unknown> | undefined
+  readonly hostMode?: HostMode | undefined
+}
+
+/**
+ * Build ONE rule map from one or more recipes, run in order against a single
+ * shared namespace, a later recipe's definition winning per rule name.
+ *
+ * `rules()` is the one-recipe case. Runtime `compose()` passes every piece's
+ * recipe plus `link`: each `g.X` in every factory then resolves to the one
+ * composed slot for X, so an override reroutes a base piece's own calls (open
+ * recursion) and every choice computes its first-set dispatch against the
+ * winners. The graph is built fresh, so no shared rule of any piece is touched;
+ * under `link` a winner is always held in a fresh slot, so the stamps below never
+ * land on a combinator a factory returned from module scope either.
+ */
+export function linkRules(
+  recipes: readonly RulesRecipe[],
+  link?: LinkOptions,
+): Record<string, Combinator<unknown>> {
+  const cache: Record<string, Combinator<unknown>> = {}
 
   // Proxy: accessing any property creates a ref() placeholder on first touch.
   const proxy = new Proxy(cache, {
@@ -161,13 +231,22 @@ export function rules<T extends Record<string, Combinator<unknown>>>(
 
   // Evaluate all rule definitions. JavaScript evaluates object-literal values
   // left-to-right, so any `g.ruleName` access inside triggers placeholder creation
-  // before the rule's own parser is built — enabling forward references.
-  const definitions = factory(proxy)
+  // before the rule's own parser is built — enabling forward references. A later
+  // recipe's definition of a name WINS; the name keeps its first position.
+  const winners = new Map<string, { parser: Combinator<unknown>; options: RulesOptions | undefined }>()
+  for (const recipe of recipes) {
+    const definitions = recipe.factory(proxy)
+    for (const key of Object.keys(definitions)) {
+      winners.set(key, { parser: definitions[key]!, options: recipe.options })
+    }
+  }
+  const keys = [...winners.keys()]
 
   // Fill each ref with its actual definition, or store directly if never accessed via proxy.
-  for (const key of Object.keys(definitions)) {
-    const placeholder = (cache as Record<string, Combinator<unknown>>)[key]
-    const parser = (definitions as Record<string, Combinator<unknown>>)[key]!
+  const copies = new Map<object, Combinator<unknown>>()
+  for (const [key, { parser: defined }] of winners) {
+    const placeholder = cache[key]
+    const parser = ownRule(defined, copies)
     if (placeholder === parser) {
       throw new Error(`rules(): rule "${key}" cannot be a direct alias to itself`)
     }
@@ -177,76 +256,63 @@ export function rules<T extends Record<string, Combinator<unknown>>>(
       // Propagate actual first-set so later choices wrapping this ref get correct dispatch.
       placeholder._meta.firstSet = parser._meta.firstSet
       placeholder._meta.canMatchNewline = parser._meta.canMatchNewline
-    } else if (isNamedRuleRefForAnotherRule(parser, key)) {
+    } else if (isNamedRuleRefForAnotherRule(parser, key) || link !== undefined) {
+      if (!isNamedRuleRefForAnotherRule(parser, key)) tagRule(parser, key)
       const alias = ref()
       tagRule(alias, key)
       alias.define(parser)
       alias._meta.firstSet = parser._meta.firstSet
       alias._meta.canMatchNewline = parser._meta.canMatchNewline
-      ;(cache as Record<string, Combinator<unknown>>)[key] = alias
+      cache[key] = alias
     } else {
       tagRule(parser, key)
-      ;(cache as Record<string, Combinator<unknown>>)[key] = parser
-    }
-  }
-
-  // Declare the grammar-level ambient trivia on every rule, so parsing ANY rule
-  // as an entry installs it (run()/parse() read this), and the macro can seed the
-  // compiled map. `parser({trivia})` / `noTrivia` still override it locally.
-  // `!= null`: a `trivia: null` grammar clears trivia — same as omitting it at the
-  // grammar level — so store nothing (and never write null, which has no `_meta`).
-  if (options?.trivia != null) {
-    for (const key of Object.keys(definitions)) {
-      const rule = (cache as Record<string, Combinator<unknown>>)[key]
-      // Skip trivia rules (e.g. the grammar's `rw`, returned so the driver can
-      // reach it as `g.rw`): a trivia rule must never carry ambient trivia, or it
-      // would recursively skip trivia within itself. Mirrors the codegen guard.
-      if (rule && !rule._meta.isTrivia) (rule._meta as { grammarTrivia?: Combinator<unknown> }).grammarTrivia = options.trivia
-    }
-  }
-
-  // Grammar-level ambient scan-skip, mirroring the trivia stamp above: every
-  // non-trivia rule carries it so any parse entry installs `ctx.scanSkip` and the
-  // compiled map can seed it. `!= null` so `scanSkip: null` clears (stores nothing).
-  if (options?.scanSkip != null) {
-    for (const key of Object.keys(definitions)) {
-      const rule = (cache as Record<string, Combinator<unknown>>)[key]
-      if (rule && !rule._meta.isTrivia) (rule._meta as { grammarScanSkip?: Combinator<unknown>[] }).grammarScanSkip = options.scanSkip
+      cache[key] = parser
     }
   }
 
-  // Grammar-level host mode, mirroring the two stamps above. Only `'cst'` is recorded:
-  // `'ast'` is the default everywhere, so stamping it would put a field on every rule of
-  // every grammar to say "unchanged". Trivia rules are skipped for the same reason as
-  // above — they build no nodes, so the mode is meaningless on them.
-  if (options?.hostMode === 'cst') {
-    for (const key of Object.keys(definitions)) {
-      const rule = (cache as Record<string, Combinator<unknown>>)[key]
-      if (rule && !rule._meta.isTrivia) (rule._meta as { grammarHostMode?: HostMode }).grammarHostMode = 'cst'
-    }
-  }
-
-  if (options?.trackLines === true) {
-    for (const key of Object.keys(definitions)) {
-      const rule = (cache as Record<string, Combinator<unknown>>)[key]
-      if (rule && !rule._meta.isTrivia) (rule._meta as { grammarTrackLines?: true }).grammarTrackLines = true
-    }
-    for (const key of Object.keys(definitions)) {
-      const rule = (cache as Record<string, Combinator<unknown>>)[key]
-      if (rule && !rule._meta.isTrivia && rule._def.tag !== 'grammar') {
-        const wrapped = grammarParser({ trackLines: true }, rule)
-        tagRule(wrapped, key)
-        ;(wrapped._meta as { grammarTrackLines?: true }).grammarTrackLines = true
-        ;(cache as Record<string, Combinator<unknown>>)[key] = wrapped
+  // Grammar-level stamps, per rule. Each touches only its own rule — a wrap
+  // replaces that rule's entry, and references hold the placeholder — so one pass
+  // is the same as a pass per stamp. Trivia rules (e.g. the grammar's `rw`,
+  // returned so the driver can reach it as `g.rw`) take none: a trivia rule must
+  // never carry ambient trivia, or it would recursively skip trivia within itself.
+  for (const key of keys) {
+    const options = winners.get(key)!.options
+    let rule = cache[key]!
+    if (!rule._meta.isTrivia) {
+      const meta = rule._meta as {
+        grammarTrivia?: Combinator<unknown>
+        grammarScanSkip?: Combinator<unknown>[]
+        grammarHostMode?: HostMode
+        grammarTrackLines?: true
+      }
+      // Ambient trivia, installed at the parse entry (run()/parse() read it) and
+      // seeded into the compiled map; `parser({trivia})` / `noTrivia` override it
+      // locally. `!= null`: `trivia: null` clears — store nothing. Under `link`
+      // the COMPOSING trivia governs every rule, inherited ones included.
+      const trivia = link !== undefined ? link.trivia : options?.trivia
+      if (trivia != null) meta.grammarTrivia = trivia
+      // Ambient scan-skip, per piece (never composing-wins: opaque units are
+      // dialect-specific), so any entry installs `ctx.scanSkip`.
+      if (options?.scanSkip != null) meta.grammarScanSkip = options.scanSkip
+      // Host mode: only `'cst'` is recorded — `'ast'` is the default everywhere.
+      if ((link?.hostMode ?? options?.hostMode) === 'cst') meta.grammarHostMode = 'cst'
+      if (options?.trackLines === true) {
+        meta.grammarTrackLines = true
+        if (rule._def.tag !== 'grammar') {
+          rule = grammarParser({ trackLines: true }, rule)
+          tagRule(rule, key)
+          ;(rule._meta as { grammarTrackLines?: true }).grammarTrackLines = true
+          cache[key] = rule
+        }
       }
     }
-  }
-
-  // Dead-value analysis: mark container aggregates that only feed a node()'s
-  // capture so the interpreter (and, via the same flag, the compiled output) skips
-  // building them. Each rule is its own root — refs are boundaries (see value-usage).
-  for (const key of Object.keys(definitions)) {
-    markUnusedValues((cache as Record<string, Combinator<unknown>>)[key]!)
+    // Dead-value analysis: mark container aggregates that only feed a node()'s
+    // capture so the interpreter (and, via the same flag, the compiled output) skips
+    // building them. Each rule is its own root — refs are boundaries (see value-usage).
+    markUnusedValues(rule)
+    // Claimed only after the define loop, so one value under two keys of THIS grammar
+    // stays one object. See `ownRule`.
+    claimedRules.add(winners.get(key)!.parser).add(rule)
   }
 
   // Record the factory's DECLARATION order (the returned object's key order).
@@ -256,11 +322,11 @@ export function rules<T extends Record<string, Combinator<unknown>>>(
   // Non-enumerable, so Object.keys / spread / for-in over the grammar are
   // unaffected and every existing consumer sees exactly the rules it did before.
   Object.defineProperty(cache, RULE_ORDER, {
-    value: Object.keys(definitions),
+    value: keys,
     enumerable: false,
     configurable: true,
   })
-  attachGrammarReflection(cache, collectGrammarReflection(Object.keys(definitions).map(key => [key, (cache as Record<string, Combinator<unknown>>)[key]!])))
+  attachGrammarReflection(cache, collectGrammarReflection(keys.map(key => [key, cache[key]!])))
 
-  return cache as RulesResult<T>
+  return cache
 }

package/src/combinators/ref.ts

@@ -26,6 +26,15 @@ function withRuleTrivia<T>(
  *
  * Unlike lazy(() => x), you use the ref directly — no wrapping at each call site.
  */
+/*
+ * What `thunk()` throws for an undefined ref. Grammar construction probes thunks
+ * constantly — a `rules()` factory runs before any of its refs is defined, and
+ * first-set, nullability and expected-set analysis all try a thunk and catch — so
+ * one shared error spares a stack capture per probe. Parsing through an undefined
+ * ref still throws a fresh error below, with the stack that locates it.
+ */
+const UNDEFINED_REF = new Error('ref<T>() used before .define() was called')
+
 export function ref<T>(): Combinator<T> & { define(p: Combinator<T>): void } {
   let resolved: Combinator<T> | null = null
   let resolvedScalar: ScalarParser | null = null
@@ -44,7 +53,7 @@ export function ref<T>(): Combinator<T> & { define(p: Combinator<T>): void } {
     _def: {
       tag: 'lazy' as const,
       thunk: () => {
-        if (!resolved) throw new Error('ref<T>() used before .define() was called')
+        if (!resolved) throw UNDEFINED_REF
         return resolved as Combinator<unknown>
       },
     },

package/src/compiler/borrowed-rules.ts

@@ -0,0 +1,88 @@
+/**
+ * Where the interpreter and a compiled table would bind one reference differently.
+ *
+ * A rule reference (`g.X`) is a slot object. The interpreter follows the slot it
+ * holds. The table encoder binds a reference to the map's rule of the same NAME
+ * (`encode.ts`, `winners`). Within one linked map the two are the same rule. They
+ * differ only for a rule object BORROWED from another grammar (`Entry: base.Entry`):
+ * its graph holds `base`'s own slots, so the interpreter keeps `base`'s `Atom` while
+ * the encoder binds this map's `Atom`. Both parse, and they accept different input.
+ *
+ * ponytail: refuses the pattern instead of rebinding borrowed graphs, which is the
+ * planned follow-up that lets both engines agree.
+ */
+import type { Combinator } from '../types.ts'
+import { childrenOf } from '../analysis/gating.ts'
+import { winnerWrapsReference } from './token-alphabet.ts'
+
+type Comb = Combinator<unknown>
+
+const nameOf = (c: Comb): string | undefined => (c as unknown as { _ruleName?: string })._ruleName
+
+/** Follow a slot to the combinator it resolves to, or `undefined` for a hole. */
+function deref(c: Comb): Comb | undefined {
+  const seen = new Set<Comb>()
+  let current: Comb = c
+  while (current._def.tag === 'lazy' && !seen.has(current)) {
+    seen.add(current)
+    try { current = current._def.thunk() } catch { return undefined }
+  }
+  return current
+}
+
+/**
+ * The first rule of `map` whose graph reaches another grammar's slot for a rule
+ * `map` also defines — the rule, and the name it references — or `undefined`.
+ */
+export function borrowedRuleReference(
+  map: Readonly<Record<string, Comb>>,
+): { rule: string; reference: string } | undefined {
+  const seen = new Set<Comb>()
+  for (const [rule, self] of Object.entries(map)) {
+    let found: string | undefined
+    const visit = (c: Comb): void => {
+      if (found !== undefined) return
+      if (c._def.tag === 'lazy') {
+        // The root's own slot leads to this rule's body; any other named slot is a
+        // reference, judged before it is ever marked seen (another root's own slot
+        // is that root's body, which its own walk covers).
+        if (!winnerWrapsReference(self, c)) {
+          const name = nameOf(c)
+          // OWN rules only: an inherited name (`toString`) is not a rule of the map.
+          const winner = name !== undefined && Object.hasOwn(map, name) ? map[name] : undefined
+          if (winner !== undefined) {
+            // This map's own reference, or another slot to the very same rule.
+            if (winnerWrapsReference(winner, c) || deref(c) === deref(winner)) return
+            found = name
+            return
+          }
+        }
+        // The root's body, or a rule this map does not define: both engines follow
+        // the slot, so its body matters only for what IT references. ONE step: the
+        // slot may resolve to another slot (an alias, `Entry: g.Atom`), and that one is
+        // a reference to judge too, not a hop to skip.
+        if (seen.has(c)) return
+        seen.add(c)
+        let body: Comb
+        try { body = c._def.thunk() } catch { return }
+        visit(body)
+        return
+      }
+      if (seen.has(c)) return
+      seen.add(c)
+      for (const child of childrenOf(c._def)) visit(child)
+    }
+    visit(self)
+    if (found !== undefined) return { rule, reference: found }
+  }
+  return undefined
+}
+
+/** The refusal, worded for the API that refused. */
+export function borrowedRuleMessage(api: string, hit: { rule: string; reference: string }): string {
+  return `${api}: rule "${hit.rule}" is a rule object borrowed from another grammar, and its graph references `
+    + `"${hit.reference}", which this grammar also defines. The interpreter would keep the other grammar's `
+    + `"${hit.reference}" while a compiled table binds this grammar's, so the two would accept different input. `
+    + `Compose the grammar that defines "${hit.rule}" instead of borrowing its rule object, so its `
+    + `references resolve to this grammar's rules.`
+}

package/src/compiler/compile-linkable-table.ts

@@ -31,7 +31,7 @@ import { PARSEMAN_VERSION } from '../version.ts'
  *                       composable half, and it is NOT new machinery: the plugin
  *                       already carries pieces as IR (`plugin/index.ts:1772`) and
  *                       the linker already re-lowers them (`linker.ts:640`,
- *                       `compileLinkable(evalRuleMapIR(p.ir), …)`).
+ *                       `compileLinkable(evalRuleMapIR(p.ir), …)` at build time).
  *
  * ── WHY THAT MAKES COMPOSITION THE EASY KIND ─────────────────────────────────
  * The open question was whether table-to-table composition has to merge two

package/src/compiler/grammar-coverage-ids.ts

@@ -60,7 +60,10 @@ function children(def: ParserDef, winners?: Record<string, Combinator<unknown>>)
         return []
       }
       const name = (resolved as Combinator<unknown> & { _ruleName?: string })._ruleName
-      return name && winners?.[name] ? [winners[name]!] : [resolved]
+      const winner = name ? winners?.[name] : undefined
+      // A slot that IS its rule's winner (a runtime composition's) descends into
+      // its own body; any other reference reroutes to the winner.
+      return winner !== undefined && winner._def !== def ? [winner] : [resolved]
     }
     default: return []
   }
@@ -92,18 +95,41 @@ export function buildGrammarPlan(entry: Combinator<unknown> | readonly Combinato
       }
     }
   }
+  /** The body behind a slot that is itself its rule's winner — how a runtime
+   * composition holds every rule. Transparent: its body owns the rule. */
+  const selfWinnerBody = (parser: Combinator<unknown>): Combinator<unknown> | undefined => {
+    if (parser._def.tag !== 'lazy' || winners === undefined) return undefined
+    const name = winnerNames.get(parser)
+    if (name === undefined || winners[name] !== parser) return undefined
+    try { return parser._def.thunk() } catch { return undefined }
+  }
+  // A body that SEVERAL winners' slots resolve to (`X: shared, Y: shared`) can carry
+  // only one name, so there each slot owns its own rule and the body owns none.
+  const slotsPerBody = new Map<Combinator<unknown>, number>()
+  if (winners) {
+    for (const winner of Object.values(winners)) {
+      const body = selfWinnerBody(winner)
+      if (body !== undefined) slotsPerBody.set(body, (slotsPerBody.get(body) ?? 0) + 1)
+    }
+  }
+  const sharedBody = (parser: Combinator<unknown>): boolean => (slotsPerBody.get(parser) ?? 0) > 1
+  const ownRule = (parser: Combinator<unknown>, rule: string): void => {
+    const id = `rule:${rule}`
+    definitions.set(id, { id, kind: 'rule' })
+    rules.set(parser, id)
+  }
   const seen = new Set<Combinator<unknown>>()
   const visit = (parser: Combinator<unknown>, path: string): void => {
     if (seen.has(parser)) return
     seen.add(parser)
     const rule = winnerNames.get(parser) ?? (parser as Combinator<unknown> & { _ruleName?: string })._ruleName
+    const body = selfWinnerBody(parser)
     // `rules()` references are tagged too for linker naming, but only the final
     // rule definition owns execution coverage; otherwise ref + target double-hit.
-    if (rule && (winnerNames.has(parser) || parser._def.tag !== 'lazy')) {
-      const id = `rule:${rule}`
-      definitions.set(id, { id, kind: 'rule' })
-      rules.set(parser, id)
+    if (rule && body === undefined && !sharedBody(parser) && (winnerNames.has(parser) || parser._def.tag !== 'lazy')) {
+      ownRule(parser, rule)
     }
+    if (rule && body !== undefined && sharedBody(body)) ownRule(parser, rule)
     if (parser._def.tag === 'choice') {
       const ids = parser._def.parsers.map((_, index) => `choice:${path}/arm:${index}`)
       choices.set(parser, ids)
@@ -128,7 +154,10 @@ export function buildGrammarPlan(entry: Combinator<unknown> | readonly Combinato
     // caller's winner map is then the only durable public identity for each
     // root; using the generic `entry` path would merge separate roots' choice
     // IDs and omit their rule definitions.
-    visit(root, winnerNames.get(root) ?? (root as Combinator<unknown> & { _ruleName?: string })._ruleName ?? 'entry')
+    const name = winnerNames.get(root) ?? (root as Combinator<unknown> & { _ruleName?: string })._ruleName ?? 'entry'
+    const body = selfWinnerBody(root)
+    if (body !== undefined && sharedBody(body) && !seen.has(root)) { seen.add(root); ownRule(root, name) }
+    visit(body ?? root, name)
   }
   return { definitions: [...definitions.values()].sort((a, b) => a.id.localeCompare(b.id)), choices, dispatches, attempts, labels, rules }
 }

package/src/compiler/ir-serialize.ts

@@ -33,7 +33,7 @@ import { peek } from '../combinators/peek.ts'
 import { node } from '../combinators/node.ts'
 import { parser } from '../combinators/grammar.ts'
 import { scanTo, balanced, type BalancedAmbient } from '../combinators/scanTo.ts'
-import { token, leaf, sourceLeaf } from '../combinators/token.ts'
+import { token, leaf } from '../combinators/token.ts'
 import { classifiedTrivia, transform, trivia, label, field } from '../combinators/map.ts'
 import { analyzeLabeledTrivia } from '../cst/trivia-kinds.ts'
 import { expect as expectC } from '../combinators/expect.ts'
@@ -157,123 +157,17 @@ export function serializeRuleMap(
   }
 }
 
-/** Reconstruct a rule map from serialized IR (the inverse of `serializeRuleMap`) —
- * evaluate the combinator-construction expression with every constructor in scope.
- * Used at fuse time (runtime linker + build-time plugin) to re-lower carried IR. */
-export function evalRuleMapIR(ir: string): Array<[string, Comb]> {
-  // `_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})`,
-  )
-  const map = fn(
-    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, expectC, adjacent, notAdjacent, _tf, _lf, _nd, _gch, _wc,
-  ) as Record<string, Comb>
-  return Object.entries(map)
+/**
+ * ONE plain combinator as IR — what a compiled module carries on an exported terminal
+ * so another module can import it into a grammar (the macro evaluates grammars, and a
+ * compiled parser function is not a combinator it can evaluate).
+ *
+ * No new format: it is `serializeRuleMap`'s `scanSkip` channel over an empty map, which
+ * already serializes rule-free terminals OUTSIDE any factory — exactly this shape. Its
+ * inverse, `evalCombinatorIR`, evaluates source and so lives in `src/plugin/ir-eval.ts`.
+ */
+export function serializeCombinator(c: Comb): string | null {
+  return serializeRuleMap([], [c])
 }
 
 /** A recursive combinator currently being emitted, and the local `ref()` var that