parseman 0.52.0 → 0.54.0

package/src/plugin/index.ts

@@ -23,12 +23,12 @@ import { createUnplugin } from 'unplugin'
 import { parseSync } from 'oxc-parser'
 import { ResolverFactory } from 'oxc-resolver'
 import MagicString from 'magic-string'
-import { evaluateExpr, evaluateCombinatorArray, evaluateParserFactory, evaluateStaticValue, evaluateWordFactory, evaluateWhenFactory, evaluateRefDeclaration, applyDefineStatement, referencesAny, setReducerResolver, setBuilderImportResolver, propName, type Scope, type ScopeEntry } from './evaluator.ts'
+import { evaluateExpr, evaluateCombinatorArray, evaluateParserFactory, evaluateStaticValue, evaluateWordFactory, evaluateWhenFactory, evaluateRefDeclaration, applyDefineStatement, referencesAny, setReducerResolver, setBuilderImportResolver, propName, ModuleScope, type FreeNameResolution, type Scope, type ScopeEntry } from './evaluator.ts'
 import { classifyRuleMap } from '../analysis/commitment.ts'
 import { compile } from '../table/compile.ts'
 import { compileRuleMap } from '../table/compile-rule-map.ts'
 import { compileLinkableTable } from '../compiler/compile-linkable-table.ts'
-import { createReducerResolver } from './reducer-resolver.ts'
+import { createReducerResolver, topLevelIsStable } from './reducer-resolver.ts'
 import { findFreeIdentifiers } from './free-identifiers.ts'
 import { supercompileRuleMapReplacement } from './entry-supercompiler.ts'
 import {
@@ -37,7 +37,9 @@ import {
 } from '../compiler/degradation.ts'
 import type { HostMode } from '../cst/host-mode.ts'
 import { COMPOSED_PIECES } from '../compiler/linker.ts'
-import { evalRuleMapIR, serializeRuleMap } from '../compiler/ir-serialize.ts'
+import { serializeCombinator, serializeRuleMap } from '../compiler/ir-serialize.ts'
+import { evalCombinatorIR, evalRulesIR } from './ir-eval.ts'
+import { linkRules, RULES_RECIPE, type LinkOptions, type RulesRecipe } from '../combinators/parser.ts'
 import { PARSEMAN_VERSION } from '../version.ts'
 import { grammarReflectionSource, type GrammarReflection } from '../cst/reflection.ts'
 import { createHash } from 'node:crypto'
@@ -341,14 +343,44 @@ function topLevelInit(body: AnyNode[], name: string): AnyNode | null {
   return null
 }
 
-/** `Symbol.for('parseman.composedPieces')` ? */
-function isComposedPiecesSymbol(n: AnyNode | undefined): boolean {
+/** `Symbol.for('<key>')` ? */
+function isSymbolFor(n: AnyNode | undefined, key: string): boolean {
   if (!n || n.type !== 'CallExpression') return false
   const callee = n.callee as AnyNode | undefined
   const obj = (callee?.object as { name?: string } | undefined)?.name
   const prop = (callee?.property as { name?: string } | undefined)?.name
   const arg0 = (n.arguments as AnyNode[] | undefined)?.[0] as { value?: unknown } | undefined
-  return obj === 'Symbol' && prop === 'for' && arg0?.value === 'parseman.composedPieces'
+  return obj === 'Symbol' && prop === 'for' && arg0?.value === key
+}
+const isComposedPiecesSymbol = (n: AnyNode | undefined): boolean => isSymbolFor(n, 'parseman.composedPieces')
+
+/**
+ * The key a compiled terminal carries its combinator IR under — see `withCombinatorIR`.
+ * EMITTED SOURCE TEXT, like the composed-pieces key: the runtime never reads it, only a
+ * downstream macro build does, by finding it in the artifact's AST.
+ */
+const COMBINATOR_IR_KEY = 'parseman.combinatorIR'
+
+/** A compiled top-level const initializer's carried combinator IR, or null.
+ * The shape is exactly what `withCombinatorIR` emits:
+ * `Object.defineProperty(<parser>, Symbol.for('parseman.combinatorIR'), { value: '<ir>', … })`. */
+function carriedCombinatorIR(init: AnyNode): string | null {
+  let n = init
+  while (n.type === 'ParenthesizedExpression') n = n.expression as AnyNode
+  if (n.type !== 'CallExpression') return null
+  const callee = n.callee as AnyNode
+  const args = n.arguments as AnyNode[]
+  if ((callee.object as { name?: string } | undefined)?.name !== 'Object'
+    || (callee.property as { name?: string } | undefined)?.name !== 'defineProperty'
+    || !isSymbolFor(args[1], COMBINATOR_IR_KEY)) return null
+  for (const p of (args[2]?.properties as AnyNode[] | undefined) ?? []) {
+    const v = p.value as { type?: string; value?: unknown; expressions?: unknown[]; quasis?: Array<{ value: { cooked?: string | null } }> } | undefined
+    if (propName(p as never) !== 'value') continue
+    if (v?.type === 'Literal' && typeof v.value === 'string') return v.value
+    // A bundler may requote it as a template (esbuild does when it holds both quote kinds).
+    if (v?.type === 'TemplateLiteral' && v.expressions?.length === 0) return v.quasis?.[0]?.value.cooked ?? null
+  }
+  return null
 }
 
 /** Walk an initializer subtree for the `Object.defineProperty(_,
@@ -367,9 +399,10 @@ function findCarriedPiecesLiteral(root: AnyNode): { start: number; end: number }
       const args = node.arguments as AnyNode[] | undefined
       // Table lowering: `tableRules(program, { [Symbol.for('…composedPieces')]:
       // <literal>, … })`. The metadata object becomes the returned map's
-      // prototype, so the symbol remains readable without becoming an own key.
+      // prototype, so the symbol remains readable without becoming an own key. The
+      // callee's NAME is not checked: a bundler renames a clashing import
+      // (`tableRules2`), and the computed key below is what identifies the literal.
       if ((callee as { type?: string; name?: string } | undefined)?.type === 'Identifier'
-        && (callee as { name?: string }).name === 'tableRules'
         && (args?.[1] as AnyNode | undefined)?.type === 'ObjectExpression') {
         for (const p of ((args![1] as AnyNode).properties as AnyNode[] | undefined) ?? []) {
           if ((p as { computed?: boolean }).computed && isComposedPiecesSymbol(p.key as AnyNode) && p.value) {
@@ -555,16 +588,17 @@ function transformMacroImpl(
     specifiers: Array<{ type: string; local: string; start: number; end: number }>
   }> = []
 
+  // A macro import is a parseman-alias import carrying `with { type: 'macro' }`
+  // (oxc exposes this as ImportDeclaration.attributes).
+  const isMacroImport = (s: ImportDeclaration): boolean => s.attributes.some(a => {
+    const key = a.key.type === 'Identifier' ? a.key.name : String(a.key.value)
+    return key === 'type' && a.value.value === 'macro'
+  })
   for (const stmt of body) {
     if (stmt.type !== 'ImportDeclaration') continue
     const s = stmt as ImportDeclaration
 
-    // A macro import is a parseman-alias import carrying `with { type: 'macro' }`
-    // (oxc exposes this as ImportDeclaration.attributes).
-    const isMacro = moduleAliases.has(s.source.value) && s.attributes.some(a => {
-      const key = a.key.type === 'Identifier' ? a.key.name : String(a.key.value)
-      return key === 'type' && a.value.value === 'macro'
-    })
+    const isMacro = moduleAliases.has(s.source.value) && isMacroImport(s)
 
     if (!isMacro) {
       const specifiers: Array<{ type: string; local: string; start: number; end: number }> = []
@@ -670,8 +704,265 @@ function transformMacroImpl(
   setReducerResolver(reducerResolver, code)
   /* A direct builder's free name is rescuable when THIS module imported it — the
    * artifact carries `{ source, imported }` and a downstream compose() re-emits the
-   * import (see the re-lower pass below). Module-private consts stay refusals. */
-  setBuilderImportResolver(name => importBindings.get(name) ?? null)
+   * import (see the re-lower pass below). Module-private consts stay refusals.
+   * While a terminal of ANOTHER module is evaluated, its own imports answer instead
+   * (`moduleConstValue`), so its builder's helpers are re-emitted here. */
+  let builderImports = (name: string): { source: string; imported: string } | null => importBindings.get(name) ?? null
+  setBuilderImportResolver(name => builderImports(name))
+  const ownRoot = nearestPackageRoot(id)
+  let ownDir = path.dirname(id)
+  try { ownDir = fs.realpathSync(ownDir) } catch { /* a virtual module: keep its path */ }
+  /** `spec`, imported by `from`, as THIS module must write it; null when it can't: a
+   * relative import of another package names a file this one has no stable path to. */
+  const rebaseSpecifier = (from: string, spec: string): string | null => {
+    if (!spec.startsWith('.')) return spec
+    const target = path.resolve(path.dirname(from), spec)
+    if (ownRoot === null || nearestPackageRoot(target) !== ownRoot) return null
+    const rel = path.relative(ownDir, target).split(path.sep).join('/')
+    return rel.startsWith('../') ? rel : `./${rel}`
+  }
+
+  /*
+   * IMPORTED VALUES — a terminal, a skip set, an options object or a boundary string
+   * declared in ANOTHER module and used where the macro evaluates a grammar: a rule
+   * body, a combinator's arguments, a `rules({ trivia, scanSkip })` option.
+   *
+   * Before this, an imported name evaluated to `null`. In a rule body that made the
+   * factory "not statically evaluable"; in an option it was worse — the option became
+   * `undefined` and the build succeeded without it. So every grammar family re-declared
+   * its own copy of each shared terminal, because only a whole `rules()` map could
+   * cross a module boundary (as `compose()` pieces).
+   *
+   * Resolution reads the exporting module, and never runs it:
+   *   - a relative import resolves to its SOURCE (`resolvePrivateSourceModule`, the
+   *     same rule imported factories use), whose declaration is evaluated like a local;
+   *   - a package import resolves to its PUBLISHED ENTRY, a compiled artifact, where a
+   *     terminal survives only as a compiled parser. The macro therefore carries each
+   *     such terminal's combinator IR on the exported value (`withCombinatorIR`), the
+   *     way a grammar carries its composed pieces, and this reads it back. A plain
+   *     value (a string, an options object, an array of terminals) is left verbatim by
+   *     the macro and is evaluated as written.
+   *
+   * Values are rebuilt per transform, and within one transform two grammars returning
+   * the same value is safe: `rules()` stamps its options onto a rule's value, so it
+   * gives each grammar after the first an unstamped copy (`ownRule`, parser.ts).
+   *
+   * A binding that exists but cannot be resolved is recorded in `unresolvedImports`,
+   * and every place that fails for it fails the BUILD naming it (`failOnUnresolved`).
+   */
+  const unresolvedImports = new Set<string>()
+  type ValueModule = {
+    file: string
+    src: string
+    body: AnyNode[]
+    consts: Map<string, AnyNode>
+    imports: Map<string, { source: string; imported: string }>
+    opaqueImports: Set<string>
+    scope?: ModuleScope
+  }
+  const valueModules = new Map<string, ValueModule | null>()
+  const OPAQUE_IMPORT = 'is a default or namespace import, which the macro does not resolve — import the binding by name'
+  const opaqueImportsOf = (moduleBody: AnyNode[]): Set<string> => {
+    const out = new Set<string>()
+    for (const st of moduleBody) {
+      if (st.type !== 'ImportDeclaration') continue
+      for (const sp of (st as unknown as ImportDeclaration).specifiers) {
+        if (sp.type !== 'ImportSpecifier') out.add(sp.local.name)
+      }
+    }
+    return out
+  }
+  const valueModule = (file: string): ValueModule | null => {
+    if (valueModules.has(file)) return valueModules.get(file)!
+    const mod = parseModuleCached(file)
+    let out: ValueModule | null = null
+    if (mod) {
+      const consts = new Map<string, AnyNode>()
+      // A `let`/`var` counts when nothing reassigns it: a bundled entry declares its
+      // exports `var dq = …; export { dq }`.
+      let stable: ((name: string) => boolean) | undefined
+      for (const st of mod.body as Statement[]) {
+        const vd = unwrapVd(st)
+        if (!vd) continue
+        const isConst = (vd as unknown as { kind?: string }).kind === 'const'
+        for (const d of vd.declarations) {
+          const idn = d.id as unknown as { type?: string; name?: string }
+          if (idn.type !== 'Identifier' || !idn.name || !d.init) continue
+          if (isConst || (stable ??= topLevelIsStable(mod.body, mod.src.length))(idn.name)) consts.set(idn.name, d.init as unknown as AnyNode)
+        }
+      }
+      out = {
+        file,
+        src: mod.src,
+        body: mod.body as AnyNode[],
+        consts,
+        imports: extractImportBindings(mod.body as AnyNode[]),
+        opaqueImports: opaqueImportsOf(mod.body as AnyNode[]),
+      }
+    }
+    valueModules.set(file, out)
+    return out
+  }
+  const resolveValueFile = (from: string, specifier: string): string | null => {
+    const source = resolvePrivateSourceModule(from, specifier)
+    if (source) return source
+    try { return getCompiledResolver().resolveFileSync(from, specifier).path ?? null } catch { return null }
+  }
+  const evaluatingConsts = new Set<string>()
+  /** Rewrite each carried builder import in `combi`'s graph (written in `from`) to THIS
+   * module's spelling; the first that can't be is returned, for the refusal. */
+  const rebaseCarriedBuilderImports = (combi: unknown, from: string): { local: string; source: string } | null => {
+    const seen = new Set<unknown>()
+    const walk = (v: unknown): { local: string; source: string } | null => {
+      if (v === null || typeof v !== 'object' || seen.has(v)) return null
+      seen.add(v)
+      const def = (v as { _def?: { buildImports?: ReadonlyArray<{ local: string; source: string; imported: string }> } })._def
+      if (def?.buildImports) {
+        const out = []
+        for (const bi of def.buildImports) {
+          const source = rebaseSpecifier(from, bi.source)
+          if (source === null) return bi
+          out.push({ ...bi, source })
+        }
+        def.buildImports = out
+      }
+      for (const child of Object.values(v as Record<string, unknown>)) {
+        for (const c of Array.isArray(child) ? child : [child]) {
+          const stuck = walk(c)
+          if (stuck) return stuck
+        }
+      }
+      return null
+    }
+    return walk(combi)
+  }
+  /** Evaluate one top-level `const` of a foreign module, as the macro would locally. */
+  const moduleConstValue = (m: ValueModule, name: string): FreeNameResolution => {
+    const key = `${m.file}\0${name}`
+    if (evaluatingConsts.has(key)) return { unresolved: `is part of a declaration cycle in ${m.file}` }
+    evaluatingConsts.add(key)
+    const outerBuilderImports = builderImports
+    try {
+      const init = m.consts.get(name)! as unknown as Expression
+      const ir = carriedCombinatorIR(init as unknown as AnyNode)
+      if (ir !== null) {
+        let combi: Combinator<unknown> | null = null
+        let why = ''
+        try { combi = evalCombinatorIR(ir) } catch (e) { why = `: ${(e as Error).message}` }
+        if (!combi) return { unresolved: `carries combinator IR that does not evaluate (${m.file})${why}` }
+        const stuck = rebaseCarriedBuilderImports(combi, m.file)
+        return stuck
+          ? { unresolved: `has a node() builder reading \`${stuck.local}\` from '${stuck.source}' inside ${m.file}, which this module cannot import — import it there by package name` }
+          : { value: { combi, mfSrcs: [] } satisfies ScopeEntry }
+      }
+      const scope = moduleValueScope(m)
+      // Offsets inside this module's reducers must be answered against ITS scope tree.
+      reducerResolver.register(m.file)
+      // A builder's free names are THIS module's imports, re-spelled for the consumer.
+      builderImports = name => {
+        const b = m.imports.get(name)
+        const source = b ? rebaseSpecifier(m.file, b.source) : null
+        return b && source !== null ? { source, imported: b.imported } : null
+      }
+      const mfs: string[] = []
+      const combi = evaluateExpr(init, scope as unknown as Scope, m.src, mfs)
+      if (combi) return { value: { combi, mfSrcs: mfs } satisfies ScopeEntry }
+      const factory = evaluateWordFactory(init, scope as unknown as Scope, m.src) ?? evaluateWhenFactory(init, scope as unknown as Scope, m.src)
+      if (factory) return { value: factory }
+      const value = evaluateStaticValue(init, scope as unknown as Scope, m.src)
+      if (value !== null && value !== undefined || isStaticNullishExpression(init)) return { value }
+      return {
+        unresolved: /\btableRules\b/.test(m.src.slice(init.start, init.end))
+          ? `is a compiled parser in ${m.file} that carries no combinator IR — rebuild that module with parseman v${PARSEMAN_VERSION}`
+          : `is not a statically-known combinator or value (${m.file})`,
+      }
+    } finally {
+      evaluatingConsts.delete(key)
+      builderImports = outerBuilderImports
+    }
+  }
+  const moduleValueScope = (m: ValueModule): ModuleScope =>
+    m.scope ??= new ModuleScope(name => {
+      if (m.consts.has(name)) return moduleConstValue(m, name)
+      const binding = m.imports.get(name)
+      if (binding) return importedValue(m.file, binding)
+      return m.opaqueImports.has(name) ? { unresolved: OPAQUE_IMPORT } : null
+    }, unresolvedImports)
+  /** The value of export `name` of module `m`, following `export { x } from '…'`. */
+  const exportedValue = (m: ValueModule, name: string, depth: number): FreeNameResolution => {
+    for (const st of m.body) {
+      if (st.type !== 'ExportNamedDeclaration' || !(st as { source?: unknown }).source) continue
+      for (const sp of (st.specifiers as AnyNode[] | undefined) ?? []) {
+        if ((sp.exported as { name?: string }).name !== name) continue
+        const source = (st.source as { value: string }).value
+        const file = depth < 16 ? resolveValueFile(m.file, source) : null
+        const next = file ? valueModule(file) : null
+        if (!next) return { unresolved: `is re-exported from '${source}', which does not resolve from ${m.file}` }
+        return exportedValue(next, (sp.local as { name: string }).name, depth + 1)
+      }
+    }
+    const local = exportLocalName(m.body, name)
+    if (local === null) {
+      // A barrel: `export * from '…'`. ponytail: the first star that exports `name`
+      // wins; a name two stars both export is ambiguous in ES, which this does not flag.
+      for (const st of m.body) {
+        if (st.type !== 'ExportAllDeclaration' || (st as { exported?: unknown }).exported) continue
+        const file = depth < 16 ? resolveValueFile(m.file, (st.source as { value: string }).value) : null
+        const next = file ? valueModule(file) : null
+        if (!next) continue
+        const r = exportedValue(next, name, depth + 1)
+        if (r !== null && 'unresolved' in r && r.unresolved.startsWith('is not exported by ')) continue
+        return r
+      }
+      return { unresolved: `is not exported by ${m.file}` }
+    }
+    const scope = moduleValueScope(m)
+    if (!scope.has(local)) {
+      scope.get(local) // records WHY, for the error
+      return { unresolved: `could not be resolved in ${m.file}` }
+    }
+    return { value: scope.get(local) }
+  }
+  const importedValue = (from: string, binding: { source: string; imported: string }): FreeNameResolution => {
+    const file = resolveValueFile(from, binding.source)
+    const m = file ? valueModule(file) : null
+    if (!m) return { unresolved: `is imported from '${binding.source}', which does not resolve from ${from}` }
+    return exportedValue(m, binding.imported, 0)
+  }
+  /** Declarations of THIS module that no grammar construct references, kept unevaluated
+   * until a grammar reads the name. Ordinary code may read any import, and resolving a
+   * module for a value nothing compiles is pure build cost — or a build failure. */
+  const deferredLocals = new Map<string, Expression>()
+  /** Their results, once read: each grammar's factory reads through its own forked scope. */
+  const deferredResults = new Map<string, FreeNameResolution>()
+  const mainOpaqueImports = opaqueImportsOf(body as unknown as AnyNode[])
+  const resolveMainFree = (name: string): FreeNameResolution => {
+    const done = deferredResults.get(name)
+    if (done !== undefined) return done
+    const deferred = deferredLocals.get(name)
+    if (deferred !== undefined) {
+      deferredLocals.delete(name)
+      // Its own misses are reported through the local's name, not beside it.
+      const outer = [...unresolvedImports]
+      unresolvedImports.clear()
+      const value = evaluateStaticValue(deferred, scope, code)
+      const why = [...unresolvedImports]
+      unresolvedImports.clear()
+      for (const n of outer) unresolvedImports.add(n)
+      const result: FreeNameResolution = value !== null && value !== undefined || isStaticNullishExpression(deferred)
+        ? { value }
+        : why.length > 0 ? { unresolved: `could not be evaluated at build time, because: ${why.join('; ')}` } : null
+      deferredResults.set(name, result)
+      return result
+    }
+    const binding = importBindings.get(name)
+    if (!binding) return mainOpaqueImports.has(name) ? { unresolved: OPAQUE_IMPORT } : null
+    const resolved = importedValue(id, binding)
+    // Its value is now inside the compiled grammar; the import goes too unless
+    // something left verbatim still reads it (the same rule as an inlined factory).
+    if (resolved !== null && 'value' in resolved) usedImportedFactories.add(name)
+    return resolved
+  }
 
   const topLevelFunction = (moduleBody: AnyNode[], name: string): AnyNode | null => {
     for (const st of moduleBody) {
@@ -685,19 +976,21 @@ function transformMacroImpl(
     }
     return null
   }
-  const isParsemanMacroImport = (stmt: AnyNode): boolean => {
-    if (stmt.type !== 'ImportDeclaration') return false
-    const s = stmt as unknown as ImportDeclaration
-    return moduleAliases.has(s.source.value) && s.attributes.some(a => {
-      const key = a.key.type === 'Identifier' ? a.key.name : String(a.key.value)
-      return key === 'type' && a.value.value === 'macro'
-    })
-  }
-  const sourceScopeUntil = (moduleBody: AnyNode[], source: string, until: number): Scope | null => {
-    const out: Scope = new Map()
+  const sourceScopeUntil = (file: string, moduleBody: AnyNode[], source: string, until: number): Scope | null => {
+    // The module's own declarations are still evaluated EAGERLY, in order, up to the
+    // factory (a factory module the macro cannot fully account for still falls back).
+    // Its imports are what changed: they resolve on first read, like this module's.
+    const imports = extractImportBindings(moduleBody)
+    const opaque = opaqueImportsOf(moduleBody)
+    const out = new ModuleScope(name => {
+      const binding = imports.get(name)
+      if (binding) return importedValue(file, binding)
+      return opaque.has(name) ? { unresolved: OPAQUE_IMPORT } : null
+    }, unresolvedImports) as unknown as Scope
     for (const stmt of moduleBody as Statement[]) {
       if (stmt.type === 'ImportDeclaration') {
-        if (!isParsemanMacroImport(stmt as unknown as AnyNode)) return null
+        // A module that imports parseman WITHOUT the macro attribute is not macro code.
+        if (moduleAliases.has((stmt as unknown as ImportDeclaration).source.value) && !isMacroImport(stmt as unknown as ImportDeclaration)) return null
         continue
       }
       if (stmt.type === 'FunctionDeclaration') continue
@@ -747,6 +1040,11 @@ function transformMacroImpl(
     }
     return out
   }
+  /** Imported factories whose module could not be accounted for because of an
+   * unresolved import — reported when a `rules()` call actually uses one. */
+  const factoryFailures = new Map<string, string[]>()
+  /** Imports the macro inlined — a factory, or an imported terminal/value — and so
+   * may remove once nothing verbatim reads them. */
   const usedImportedFactories = new Set<string>()
   const markUsedImportedFactories = (names: readonly string[] | undefined): void => {
     for (const name of names ?? []) usedImportedFactories.add(name)
@@ -759,8 +1057,14 @@ function transformMacroImpl(
     const localFor = exportLocalName(mod.body as AnyNode[], binding.imported)
     const init = localFor ? topLevelInit(mod.body as AnyNode[], localFor) ?? topLevelFunction(mod.body as AnyNode[], localFor) : null
     if (!init || (init.type !== 'ArrowFunctionExpression' && init.type !== 'FunctionExpression' && init.type !== 'FunctionDeclaration')) continue
-    const factoryScope = sourceScopeUntil(mod.body as AnyNode[], mod.src, init.start)
-    if (!factoryScope) continue
+    unresolvedImports.clear()
+    const factoryScope = sourceScopeUntil(file, mod.body as AnyNode[], mod.src, init.start)
+    if (!factoryScope) {
+      // Not silent: `rules(<this factory>)` refuses the build naming the binding.
+      if (unresolvedImports.size > 0) factoryFailures.set(localName, [...unresolvedImports])
+      unresolvedImports.clear()
+      continue
+    }
     factoryDecls.set(localName, {
       fn: init as unknown as Expression,
       declaredAt: -1,
@@ -778,8 +1082,9 @@ function transformMacroImpl(
   // --- Pass 2: evaluate declarations in source order ---
   // Scope stores enriched ScopeEntry objects so evaluateParserFactory can
   // replay mfSrcs when outer-scope combinators are referenced inside factories.
-  const scope: Scope = new Map<string, ScopeEntry>()
-  const replacements: Array<{ start: number; end: number; replacement: string }> = []
+  const scope = new ModuleScope(resolveMainFree, unresolvedImports) as unknown as Scope
+  /** `carry`: a compiled terminal that may need its combinator IR — see `withCombinatorIR`. */
+  const replacements: Array<{ start: number; end: number; replacement: string; carry?: { name: string; combi: Combinator<unknown>; exported: boolean } }> = []
   const warnings: string[] = []
   // Collect degradations instead of printing them, so they arrive on the SAME channel
   // as every other macro warning (the bundler's `this.warn`) with a `file:line` anchor.
@@ -839,6 +1144,15 @@ function transformMacroImpl(
       for (const bi of def?.buildImports ?? []) {
         let m = pendingBuilderImports.get(bi.source)
         if (!m) { m = new Map(); pendingBuilderImports.set(bi.source, m) }
+        const prev = m.get(bi.local)
+        // Two builders reading one local name as different exports cannot share an import.
+        if (prev !== undefined && prev !== bi.imported) {
+          throw new Error(
+            `${id} — parseman will not emit this module: inlined builders read \`${bi.local}\` as both `
+            + `\`${prev}\` and \`${bi.imported}\` from ${JSON.stringify(bi.source)}. The builder source names `
+            + `\`${bi.local}\` verbatim, so one import cannot bind both; import them under different names.`,
+          )
+        }
         m.set(bi.local, bi.imported)
       }
       // An ANONYMOUS lazy is inline recursion — follow the thunk. A NAMED lazy is a
@@ -885,6 +1199,58 @@ function transformMacroImpl(
     warnings.push(`${id}:${lineOf(pos)} — ${msg} (running via the interpreter; add the plugin or simplify the declaration to compile it)`)
   }
 
+  /**
+   * REFUSE THE BUILD over something the macro could not evaluate, naming each binding
+   * it could not resolve (`unresolvedImports`, filled by the scopes as they miss).
+   *
+   * A warning is not enough here. For a `rules()` option the "fallback" was to build the
+   * grammar WITHOUT the option — `scanSkip` gone, every string and comment inside a
+   * `scanTo`/`balanced` region live again — with the build green and no interpreter
+   * fallback to count. And a terminal imported from a published package is a compiled
+   * parser at runtime, so there is no interpreter fallback for it to take either.
+   */
+  const unevaluable = (pos: number, what: string): never => {
+    const names = [...unresolvedImports]
+    unresolvedImports.clear()
+    throw new Error(
+      `${id}:${lineOf(pos)} — ${what} can't be evaluated at build time`
+      + (names.length > 0
+        ? `; unresolved binding(s):\n${names.map(n => `  - ${n}`).join('\n')}`
+        : ' (it is not a static combinator/value expression)')
+      + `\n  parseman will not emit this module rather than drop it silently.`,
+    )
+  }
+  /** A `rules()` option: absent/nullish → `undefined`; otherwise evaluated or the build fails. */
+  const requiredOption = <T>(label: string, name: string, value: Expression | undefined, evaluate: (v: Expression) => T | null): T | undefined => {
+    if (value === undefined || isStaticNullishExpression(value)) return undefined
+    unresolvedImports.clear()
+    const out = evaluate(value)
+    if (out === null) {
+      // A const bound to `null`/`undefined` means no option, exactly as the literal does.
+      const id = (value.type === 'Identifier' ? value.name : null)
+      if (id !== null && scope.has(id) && scope.get(id) == null) return undefined
+      return unevaluable(value.start, `${label}: rules({ ${name} })`)
+    }
+    unresolvedImports.clear()
+    return out
+  }
+  /** Options the macro reads by NAME, so a spread — or a computed key it cannot prove
+   * names no option — would hide one from it. */
+  const RULES_OPTIONS = new Set(['trivia', 'scanSkip', 'hostMode', 'trackLines'])
+  const assertPlainOptions = (optExpr: AnyNode | undefined, label: string): void => {
+    for (const p of (optExpr?.type === 'ObjectExpression' ? optExpr.properties as AnyNode[] : [])) {
+      if (propName(p as never) !== null) continue
+      const key = p.type === 'Property' ? evaluateStaticValue(p.key as unknown as Expression, scope, code) : null
+      if (typeof key !== 'string' || RULES_OPTIONS.has(key)) {
+        unevaluable(p.start, `${label}: an options ${p.type === 'Property' ? 'computed key' : 'spread'}`)
+      }
+    }
+  }
+  const triviaOption = (optExpr: AnyNode | undefined, label: string): Combinator<unknown> | undefined => {
+    assertPlainOptions(optExpr, label)
+    return requiredOption(label, 'trivia', optionProp(optExpr, 'trivia'), v => evaluateExpr(v, scope, code, []))
+  }
+
   /**
    * Compile a `rules(factory)` call into ONE shared replacement expression
    * for the whole call — see compileRuleMap() in codegen.ts for why this is
@@ -923,11 +1289,23 @@ function transformMacroImpl(
     const importedFactory = namedFactory?.imported === true && factoryArg === namedFactory.fn
       ? (factoryArgRaw as unknown as { name?: string }).name
       : undefined
+    const failedFactory = factoryArgRaw.type === 'Identifier'
+      ? factoryFailures.get((factoryArgRaw as unknown as { name: string }).name)
+      : undefined
+    if (failedFactory) {
+      for (const n of failedFactory) unresolvedImports.add(n)
+      unevaluable(init.start, `${label}: the imported rules() factory \`${(factoryArgRaw as unknown as { name: string }).name}\``)
+    }
 
     // Grammar-level options object — evaluate `trivia` / `scanSkip` so the compiled
     // map seeds them as the ambient defaults (build-time mirror of rules() tagging
     // grammarTrivia / grammarScanSkip at runtime).
     const optionsArg = (optionsFirst ? arg0 : arg1) as AnyNode | undefined
+    // `optionProp` reads an object LITERAL: a trailing `rules(factory, OPTS)` would hide
+    // every option from it and ship the grammar without them, as `compose()` would.
+    if (optionsArg !== undefined && optionsArg.type !== 'ObjectExpression' && !isStaticNullishExpression(optionsArg as unknown as Expression)) {
+      unevaluable(optionsArg.start as number, `${label}: rules() options`)
+    }
     const optionValue = (name: string): Expression | undefined => optionProp(optionsArg, name)
 
     // Read and VALIDATE hostMode before evaluating the factory, so a mode the macro
@@ -973,14 +1351,18 @@ function transformMacroImpl(
      *
      * Evaluated BEFORE the factory because they are now inputs to it.
      */
-    const triviaValue = optionValue('trivia')
-    const gTrivia = triviaValue ? evaluateExpr(triviaValue, scope, code, []) : undefined
-    const scanSkipValue = optionValue('scanSkip')
-    const gScanSkip = scanSkipValue
-      ? (evaluateCombinatorArray(scanSkipValue, scope, code) ?? undefined)
-      : undefined
+    const gTrivia = triviaOption(optionsArg, label)
+    const scanSkipArray = requiredOption(label, 'scanSkip', optionValue('scanSkip'), v => {
+      const units = evaluateCombinatorArray(v, scope, code)
+      if (units) return units
+      // An empty array means no skip units, whether written `[]` or named by a const.
+      const value = evaluateStaticValue(v, scope, code)
+      return Array.isArray(value) && value.length === 0 ? [] : null
+    })
+    const gScanSkip = scanSkipArray?.length ? scanSkipArray : undefined
 
     const why: { reason?: string } = {}
+    unresolvedImports.clear()
     const ruleMap = evaluateParserFactory(factoryArg, factoryScope, factoryCode, [], why, {
       ...(gTrivia ? { trivia: gTrivia as Combinator<unknown> } : {}),
       ...(gScanSkip ? { scanSkip: gScanSkip } : {}),
@@ -988,6 +1370,7 @@ function transformMacroImpl(
       ...(gTrackLines === true ? { trackLines: true } : {}),
     })
     if (!ruleMap) {
+      if (unresolvedImports.size > 0) unevaluable(init.start, `${label}: rules(...) factory`)
       warn(init.start, why.reason === undefined
         ? `${label}: rules(...) factory isn't statically evaluable`
         : `${label}: rules(...) factory isn't statically evaluable — ${why.reason}`)
@@ -1018,6 +1401,8 @@ function transformMacroImpl(
     // inlined" leaves the author with a ~5x silent perf regression and no lead.
     const refusals: string[] = []
     const compiled = compileRuleMap([...evaluated.ruleMap], { ...(evaluated.trivia ? { trivia: evaluated.trivia } : {}), ...(evaluated.scanSkip ? { scanSkip: evaluated.scanSkip } : {}), ...(evaluated.trackLines ? { trackLines: true } : {}), recovery, coverage: grammarCoverage, refusals })
+    // An imported terminal's inlined builder reads ITS module's helpers; import them here.
+    if (compiled !== null) collectBuilderImports([...evaluated.ruleMap])
     // A table replacement names `tableRules`, which nothing in the consumer's
     // module binds. That reference is the whole reason the artifact is small (the
     // driver is SHARED, not inlined per grammar), so the import is owned here.
@@ -1196,34 +1581,58 @@ function transformMacroImpl(
   // spread by following that module's own import of `binding` to its compiled file
   // and recursing, then eval the literal with the resolved ancestors stubbed in so
   // the spreads splice their pieces. `seen` guards against an import cycle.
-  const resolveModulePieces = (module: ResolvedGrammarModule, exportName: string, seen: Set<string>): RawItem[] | null => {
+  //
+  // A grammar whose literal IS found is BUILD-COMPILED: a runtime `compose()` cannot
+  // link it, so failing to resolve it is not a reason to fall back to runtime.
+  // `unresolved.why` then says what could not be followed, and the caller fails the
+  // build with it. `local` names a top-level binding of the module rather than an
+  // export — how a bundler leaves an ancestor it inlined.
+  const resolveModulePieces = (
+    module: ResolvedGrammarModule,
+    exportName: string,
+    seen: Set<string>,
+    unresolved: { why?: string },
+    local = false,
+  ): RawItem[] | null => {
     const { file } = module
     const mod = module.source
       ? lowerPrivateSourceModule(file, moduleAliases, warnUnloweredRegex, recovery)
       : parseModuleCached(file)
     if (!mod) return null
-    const localFor = exportLocalName(mod.body as AnyNode[], exportName)
+    const localFor = local ? exportName : exportLocalName(mod.body as AnyNode[], exportName)
     const initNode = localFor ? topLevelInit(mod.body as AnyNode[], localFor) : null
     const literalRange = initNode ? findCarriedPiecesLiteral(initNode) : null
     if (!literalRange) return null
     const literal = mod.src.slice(literalRange.start, literalRange.end)
+    const fail = (why: string): null => { unresolved.why ??= `${exportName} in ${file}: ${why}`; return null }
 
     const imports = extractImportBindings(mod.body as AnyNode[])
     const stubNames: string[] = []
     const stubVals: unknown[] = []
-    const spreadRe = /\.\.\.\s*\(?\s*([A-Za-z_$][\w$]*)\s*\[\s*Symbol\s*\.\s*for\s*\(\s*['"]parseman\.composedPieces['"]/g
+    // A bundler may reprint the key with an annotation inside the brackets — esbuild
+    // writes `syn[/* @__PURE__ */ Symbol.for("parseman.composedPieces")]` — so block
+    // comments before `Symbol` are allowed. Missing one leaves the spread unresolved.
+    const spreadRe = /\.\.\.\s*\(?\s*([A-Za-z_$][\w$]*)\s*\[\s*(?:\/\*[^]*?\*\/\s*)*Symbol\s*\.\s*for\s*\(\s*['"]parseman\.composedPieces['"]/g
     const done = new Set<string>()
     for (let m: RegExpExecArray | null; (m = spreadRe.exec(literal)); ) {
       const local = m[1]!
       if (done.has(local)) continue
       done.add(local)
       const b = imports.get(local)
-      let subPieces: RawItem[] = []
+      let subPieces: RawItem[] | null = []
       if (b) {
         const subModule = resolveGrammarModule(file, b.source)
-        if (subModule && !seen.has(subModule.file)) {
-          subPieces = resolveModulePieces(subModule, b.imported, new Set(seen).add(subModule.file)) ?? []
+        if (subModule === null) return fail(`its carried pieces spread \`${local}\` from '${b.source}', a module that could not be found`)
+        if (!seen.has(subModule.file)) {
+          subPieces = resolveModulePieces(subModule, b.imported, new Set(seen).add(subModule.file), unresolved)
+          if (subPieces === null) return fail(`its carried pieces spread \`${local}\` from '${b.source}', which could not be resolved`)
         }
+      } else if (topLevelInit(mod.body as AnyNode[], local) !== null && !seen.has(`${file}#${local}`)) {
+        // A bundled module: the ancestor was inlined as a top-level binding.
+        subPieces = resolveModulePieces(module, local, new Set(seen).add(`${file}#${local}`), unresolved, true)
+        if (subPieces === null) return fail(`its carried pieces spread the inlined binding \`${local}\`, which carries none`)
+      } else {
+        return fail(`its carried pieces spread \`${local}\`, which is neither an import nor a top-level binding of the module`)
       }
       stubNames.push(local)
       // The KEY comes from the linker, which owns it. Spelling `Symbol.for('…')`
@@ -1245,49 +1654,41 @@ function transformMacroImpl(
       // eslint-disable-next-line no-new-func
       const list = new Function(...stubNames, `return (${literal})`)(...stubVals) as RawItem[]
       return list
-    } catch { return null }
+    } catch (e) { return fail(`its carried pieces literal did not evaluate (${(e as Error).message})`) }
   }
 
+  // Imported build-compiled grammars whose carried pieces could not be resolved, by
+  // local name, with the reason. `compileComposeCall` fails the build on these.
+  const unresolvedCompiled = new Map<string, string>()
+
   const importedPieces = (localName: string): RawItem[] | null => {
     if (importedPiecesCache.has(localName)) return importedPiecesCache.get(localName)!
     let result: RawItem[] | null = null
     const binding = importBindings.get(localName)
     if (binding) {
       const module = resolveGrammarModule(id, binding.source)
-      result = module ? resolveModulePieces(module, binding.imported, new Set([module.file])) : null
+      const unresolved: { why?: string } = {}
+      result = module ? resolveModulePieces(module, binding.imported, new Set([module.file]), unresolved) : null
+      if (result === null && unresolved.why !== undefined) unresolvedCompiled.set(localName, unresolved.why)
     }
     importedPiecesCache.set(localName, result)
     return result
   }
 
   /**
-   * MERGE a carried list to ONE rule map — the table lowering's entire composition
-   * mechanism, and the reason it needs no linker.
-   *
-   * Source composition is a TEXTUAL splice: each piece is lowered on its own to
-   * namespaced `_r_<Name>` functions, and `fusedBody()` picks a winner per name and
-   * substitutes the `@FS:` dispatch placeholders with that winner's first-set
-   * condition. A table has no text to splice and no placeholders to resolve, so the
-   * merge moves one level UP, onto the combinators: evaluate each piece's IR back to
-   * a rule map, let a later piece's name override an earlier one — which is exactly
-   * what `compose()` means — and hand the single merged map to
-   * `compileRuleMap`, which encodes ONCE.
-   *
-   * This is what makes table composition the easy kind: no relocation of code
-   * offsets, no merging of const / fn / class / expected / dispatch pools between
-   * two already-encoded programs. `encodeTableProgram` points `enc.winners` at the
-   * merged map (`table/encode.ts:1383`), so a base piece's internal `g.Atom`
-   * resolves BY NAME to the override (`:1036`) rather than through a thunk that
-   * closes over the base. Open recursion — much of the point of compose — therefore
-   * survives the merge, and the result is the table the merged grammar would have
-   * produced had it been written as a single `rules()` call.
+   * Evaluate a carried list back to combinators, one entry per piece: its rule map
+   * and the `rules()` recipe it was built from. `compose()` links the recipes into
+   * one namespace (`mergedCarriedRules`); `composeLeaf()` merges the maps by name.
+   * Either way the merged grammar is encoded ONCE by `compileRuleMap` — no relocation
+   * of code offsets and no merging of const / fn / expected pools between two
+   * already-encoded programs.
    *
    * `null` means some piece cannot contribute combinators: a FULL BAKED piece (the
    * un-serializable fallback at `localCarried`) carries lowered SOURCE and nothing
    * else. That shape is codegen-only, so the caller falls back to fused source
    * rather than refusing the grammar.
    */
-  type CarriedRuleMap = { ns: string; rules: Array<[string, Combinator<unknown>]> }
+  type CarriedRuleMap = { ns: string; rules: Array<[string, Combinator<unknown>]>; recipes: readonly RulesRecipe[] }
   const carriedRuleMaps = (
     items: CarriedItem[],
   ): { pieces: CarriedRuleMap[]; trackLines: boolean } | null => {
@@ -1300,7 +1701,8 @@ function transformMacroImpl(
       // merged encode resolves `trackLines` from `_meta` alone and silently drops line
       // tracking for a grammar that asked for it.
       if (item.trackLines === true) trackLines = true
-      pieces.push({ ns: item.ns, rules: evalRuleMapIR(item.ir) })
+      const map = evalRulesIR(item.ir)
+      pieces.push({ ns: item.ns, rules: Object.entries(map), recipes: (map as Record<symbol, readonly RulesRecipe[]>)[RULES_RECIPE]! })
       return true
     }
     for (const item of items) {
@@ -1345,24 +1747,39 @@ function transformMacroImpl(
     return [...winners]
   }
 
+  /**
+   * LINK a carried list into the composed map, exactly as runtime `compose()` does:
+   * every piece's carried `rules()` recipe runs again against ONE namespace
+   * (`linkRules`), a later piece's rule winning by name, and the composing trivia and
+   * host mode stamped on every rule. A `g.X` in one piece is then the SAME slot as the
+   * `X` another piece defines, so everything the encoder derives from the graph —
+   * first sets, nullability, expected sets — sees the composed grammar. Merging
+   * per-piece maps by name instead left each piece's cross-piece `g.X` an unresolved
+   * thunk: parsing still bound it by name, but a failure derived as the bare rule name
+   * (or, through a nullable guess, a token the parse never required), so the macro
+   * table reported different `expected` sets than the interpreter and `compile()` of
+   * the same composition.
+   */
   const mergedCarriedRules = (
     items: CarriedItem[],
+    link: LinkOptions,
   ): { rules: Array<[string, Combinator<unknown>]>; trackLines: boolean } | null => {
     const carriedMaps = carriedRuleMaps(items)
     if (carriedMaps === null) return null
-    return { rules: mergeRuleMaps(carriedMaps.pieces.map(p => p.rules)), trackLines: carriedMaps.trackLines }
+    const linked = linkRules(carriedMaps.pieces.flatMap(p => p.recipes), link)
+    // A name some piece only REFERENCES and none defines stays an undefined slot in
+    // the namespace. It is not a rule, so it is not handed to the encoder as one.
+    const rules = Object.entries(linked).filter(([, rule]) => {
+      if (rule._def.tag !== 'lazy') return true
+      try { rule._def.thunk(); return true } catch { return false }
+    })
+    return { rules, trackLines: carriedMaps.trackLines }
   }
 
   /**
-   * COMPOSING-WINS, as an OVERRIDE rather than a gap-fill.
-   *
-   * `compileRuleMap`'s `applyAmbient` only fills a rule that carries no trivia of
-   * its own — correct for `composeLeaf`, whose pieces may legitimately disagree, and
-   * WRONG for `compose`, where the composing grammar's trivia governs every fused rule
-   * INCLUDING the inherited ones. Gap-filling leaves a base rule that declared its own
-   * `rules({ trivia }, …)` still skipping the base's trivia after a delta re-declared
-   * it, so `compose([css, less])` silently parses the inherited rules under css's
-   * whitespace — the multi-level composing-wins contract, inverted.
+   * COMPOSING-WINS for `composeLeaf()`'s carried pieces, as an OVERRIDE rather than
+   * a gap-fill: `compileRuleMap`'s `applyAmbient` only fills a rule that carries no
+   * trivia of its own. (`compose()` gets the same override from `linkRules`.)
    *
    * Safe to mutate: every rule here came from `evalRuleMapIR`, which constructs FRESH
    * combinators per piece per compose, so this cannot leak into another compose of the
@@ -1456,9 +1873,7 @@ function transformMacroImpl(
     const a0 = rulesArgs[0] as AnyNode | undefined
     const a1 = rulesArgs[1] as AnyNode | undefined
     const optExpr = (a0?.type === 'ObjectExpression' ? a0 : a1?.type === 'ObjectExpression' ? a1 : undefined) as AnyNode | undefined
-    const triviaValue = optionProp(optExpr, 'trivia')
-    if (!triviaValue) return undefined
-    return (evaluateExpr(triviaValue, scope, code, []) as Combinator<unknown> | null) ?? undefined
+    return triviaOption(optExpr, 'compose() element')
   }
   const composingTrivia = (elements: ReadonlyArray<Expression | null>): Combinator<unknown> | undefined => {
     for (let i = elements.length - 1; i >= 0; i--) {
@@ -1497,6 +1912,10 @@ function transformMacroImpl(
     // because the artifact genuinely WAS 'ast'. Same vacuous-classification shape this
     // change exists to remove, one call site over.
     const cOptions = (init as unknown as { arguments: Expression[] }).arguments[1] as AnyNode | undefined
+    // `optionProp` reads an object LITERAL: any other options expression, or a spread
+    // inside one, would hide `hostMode` from it and ship the default.
+    if (cOptions !== undefined && cOptions.type !== 'ObjectExpression') unevaluable(cOptions.start, 'compose() options')
+    assertPlainOptions(cOptions, 'compose()')
     const cHostModeValue = optionProp(cOptions, 'hostMode')
     const cHostMode = cHostModeValue?.type === 'Literal'
       ? (cHostModeValue as unknown as { value?: unknown }).value
@@ -1512,7 +1931,25 @@ function transformMacroImpl(
     const importedFactories: string[] = []
     for (let i = 0; i < elements.length; i++) {
       const r = argPieces(elements[i]!, `compose${init.start}_${i}`, composing)
-      if (!r) { warn(init.start, `compose(): argument ${i} isn't a build-resolvable grammar; falling back to runtime`); return null }
+      if (!r) {
+        // A build-compiled argument cannot fall back: runtime `compose()` links live
+        // `rules()` grammars only and would throw at import. Fail here instead.
+        const el = elements[i]!
+        const name = el.type === 'Identifier' ? (el as unknown as { name: string }).name : undefined
+        const why = name === undefined ? undefined : unresolvedCompiled.get(name)
+        if (why !== undefined) {
+          throw new Error(
+            `${id}:${lineOf(init.start)} — compose(): argument ${i} (\`${name}\` from '${importBindings.get(name!)?.source}') `
+            + `is a build-compiled grammar whose carried pieces could not be resolved: ${why}. `
+            + 'A runtime compose() cannot link a build-compiled grammar, so this would throw at import. '
+            + 'The usual cause is a bundler rewriting the upstream module (inlining or renaming an ancestor '
+            + 'grammar it composes, or reprinting its carried-pieces literal); keep upstream grammar packages '
+            + 'external to the bundle.',
+          )
+        }
+        warn(init.start, `compose(): argument ${i} isn't a build-resolvable grammar; falling back to runtime`)
+        return null
+      }
       carried.push(...r.carried)
       importedFactories.push(...(r.importedFactories ?? []))
     }
@@ -1523,9 +1960,11 @@ function transformMacroImpl(
     // does — one encode, one `tableRules(…)` expression, no linker. `carried` is
     // unchanged either way: it is the re-lowerable IR list, not a lowering artifact,
     // so a downstream re-compose behaves identically whichever engine emitted here.
-    const merged = mergedCarriedRules(carried)
+    const merged = mergedCarriedRules(carried, {
+      trivia: composing,
+      ...(cHostMode ? { hostMode: cHostMode as HostMode } : {}),
+    })
     if (merged !== null) {
-      if (composing) applyComposingTrivia(merged.rules, composing)
       // Harvest the direct-builder import provenance carried on the merged graph so
       // the re-lower pass at the end of this transform re-emits those imports.
       collectBuilderImports(merged.rules)
@@ -1809,10 +2248,8 @@ function transformMacroImpl(
         // ── Simple binding: const name = <expr> ──────────────────────────
         const varName = (d.id as unknown as { name: string }).name
         if (!referencesAny(init, allNames, scope)) {
-          const staticValue = evaluateStaticValue(init, scope, code)
-          if (staticValue !== null && staticValue !== undefined || isStaticNullishExpression(init)) {
-            ;(scope as Map<string, unknown>).set(varName, staticValue)
-          }
+          // Evaluated only if a grammar reads it — see `deferredLocals`.
+          deferredLocals.set(varName, init)
           continue
         }
 
@@ -1991,6 +2428,7 @@ function transformMacroImpl(
         }
 
         const mapFnSources: string[] = []
+        unresolvedImports.clear()
         const parser = evaluateExpr(init, scope, code, mapFnSources)
         if (parser === null) {
           const wordFactory = evaluateWordFactory(init, scope, code)
@@ -2034,6 +2472,7 @@ function transformMacroImpl(
             if (exportPrefix) exportedFactories.push({ name: varName, pos: init.start })
             continue
           }
+          if (unresolvedImports.size > 0) unevaluable(init.start, `"${varName}"`)
           warn(init.start, `"${varName}" references a parseman macro import but isn't a statically-evaluable combinator`)
           continue
         }
@@ -2055,6 +2494,7 @@ function transformMacroImpl(
           start: init.start,
           end: init.end,
           replacement: compiled.inlineExpression,
+          carry: { name: varName, combi: parser, exported: exportPrefix !== '' },
         })
 
         // Store enriched scope entry so factories can replay mfSrcs
@@ -2165,40 +2605,78 @@ function transformMacroImpl(
     )
   }
 
+  /**
+   * Carry a compiled terminal's combinator IR on its value, when another module can
+   * reach it: it is exported, or something left verbatim (an exported skip array, an
+   * options object) still names it.
+   *
+   * Lowering turns `export const blockComment = regex(…)` into a compiled PARSER, and a
+   * parser is not something the macro can evaluate. So without this, a package could
+   * share a grammar map (whose pieces it carries for `compose()`) but not one terminal,
+   * and every grammar that wanted the same string-or-comment skipper declared its own.
+   * The IR rides on the value exactly like composed pieces do — non-enumerable, under a
+   * `Symbol.for` key — and `carriedCombinatorIR` reads it back out of the artifact.
+   * The parser function itself is unchanged, so no parse runs differently.
+   */
+  const withCombinatorIR = <R extends (typeof replacements)[number]>(r: R): R => {
+    if (!r.carry || (!r.carry.exported && !referencedNames().live.has(r.carry.name))) return r
+    let ir: string | null = null
+    // An IR the serializer cannot produce leaves the terminal uncarried; a module that
+    // imports it then fails ITS build naming it (see `moduleConstValue`).
+    try { ir = serializeCombinator(r.carry.combi) } catch { /* uncarried */ }
+    return ir === null ? r : {
+      ...r,
+      replacement: `/* @__PURE__ */ Object.defineProperty(${r.replacement}, Symbol.for('${COMBINATOR_IR_KEY}'), { value: ${JSON.stringify(ir)}, enumerable: false })`,
+    }
+  }
   const ms = new MagicString(code)
   const replacementRanges = runtimeComposeFallback
     ? []
     : replacements.map(({ start, end }) => ({ start, end }))
   const isInsideReplacement = (start: number, end: number): boolean =>
     replacementRanges.some(r => start >= r.start && end <= r.end)
-  const importedBindingStillReferenced = (local: string): boolean => {
-    const walk = (node: unknown, parent?: AnyNode, parentKey?: string): boolean => {
-      if (!node || typeof node !== 'object') return false
+  /** Every name the EMITTED module still reads outside the replaced ranges — computed
+   * once (it used to be one whole-module walk per name asked about). A declaration's
+   * own binding name is not a read. `live` leaves out reads inside a local `rules()`
+   * factory, whose text survives lowering only as macro-only dead code, and inside the
+   * `.define()` statements lowering removes. */
+  let referenced: { all: Set<string>; live: Set<string> } | null = null
+  const referencedNames = (): { all: Set<string>; live: Set<string> } => {
+    if (referenced !== null) return referenced
+    const all = new Set<string>()
+    const live = new Set<string>()
+    // Also the `x.define(…)` statements lowering strips.
+    const deadRanges = [...[...factoryDecls.values()].filter(f => !f.imported).map(f => f.fn), ...(anyUnresolved ? [] : defineRemovals)]
+    const walk = (node: unknown, inFactory: boolean, parent?: AnyNode, parentKey?: string): void => {
+      if (!node || typeof node !== 'object') return
       const rec = node as AnyNode
-      if (rec.type === 'ImportDeclaration') return false
-      if (typeof rec.start === 'number' && typeof rec.end === 'number' && isInsideReplacement(rec.start, rec.end)) return false
-      if ((rec.type === 'Identifier' || rec.type === 'BindingIdentifier') && (rec as { name?: string }).name === local) {
-        if (
-          parentKey === 'key' &&
-          (parent?.type === 'ObjectProperty' || parent?.type === 'Property' || parent?.type === 'PropertyDefinition') &&
-          (parent as { computed?: boolean }).computed !== true
-        ) return false
-        if (parentKey === 'property' && parent?.type === 'StaticMemberExpression') return false
-        if (parentKey === 'property' && parent?.type === 'MemberExpression' && (parent as { computed?: boolean }).computed !== true) return false
-        return true
+      if (rec.type === 'ImportDeclaration') return
+      if (typeof rec.start === 'number' && typeof rec.end === 'number') {
+        if (isInsideReplacement(rec.start, rec.end)) return
+        inFactory ||= deadRanges.some(f => rec.start >= f.start && rec.end <= f.end)
+      }
+      if (rec.type === 'Identifier' || rec.type === 'BindingIdentifier') {
+        const isKey = parentKey === 'key'
+          && (parent?.type === 'ObjectProperty' || parent?.type === 'Property' || parent?.type === 'PropertyDefinition')
+          && (parent as { computed?: boolean }).computed !== true
+        const isMember = parentKey === 'property'
+          && (parent?.type === 'StaticMemberExpression' || (parent?.type === 'MemberExpression' && (parent as { computed?: boolean }).computed !== true))
+        const isDeclared = parentKey === 'id' && parent?.type === 'VariableDeclarator'
+        if (!isKey && !isMember && !isDeclared) {
+          all.add(rec.name as string)
+          if (!inFactory) live.add(rec.name as string)
+        }
+        return
       }
       for (const key of Object.keys(rec)) {
         if (key === 'type' || key === 'start' || key === 'end') continue
         const value = (rec as Record<string, unknown>)[key]
-        if (Array.isArray(value)) {
-          if (value.some(child => walk(child, rec, key))) return true
-        } else if (walk(value, rec, key)) {
-          return true
-        }
+        if (Array.isArray(value)) for (const child of value) walk(child, inFactory, rec, key)
+        else walk(value, inFactory, rec, key)
       }
-      return false
     }
-    return (body as unknown[]).some(stmt => walk(stmt))
+    for (const stmt of body as unknown[]) walk(stmt, false)
+    return referenced = { all, live }
   }
 
   for (const imp of ordinaryImports) {
@@ -2208,7 +2686,7 @@ function transformMacroImpl(
       imp.specifiers.every(spec =>
         spec.type === 'ImportSpecifier' &&
         usedImportedFactories.has(spec.local) &&
-        !importedBindingStillReferenced(spec.local),
+        !referencedNames().all.has(spec.local),
       )
     ) {
       ms.remove(imp.start, imp.end)
@@ -2239,7 +2717,7 @@ function transformMacroImpl(
   // Runtime compose consumes combinator objects. A partially lowered module mixes
   // compiled parser functions with those objects (for example `trivia(ws)` after
   // `ws` was lowered), so an unresolved compose makes the whole module runtime.
-  const applied = runtimeComposeFallback ? [] : replacements
+  const applied = runtimeComposeFallback ? [] : replacements.map(r => withCombinatorIR(r))
   // NO MODULE HOIST. It existed to deduplicate declarations across the fused IIFEs the
   // source lowering emitted — `_pfFail` and friends, one copy per variant. A table
   // replacement is a `tableRules(...)` call over a data literal: there are no emitted