parseman 0.56.0 → 0.58.0

package/src/plugin/index.ts

@@ -26,7 +26,7 @@ import MagicString from 'magic-string'
 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 { compileRuleMap, type CompiledRuleMapTable } from '../table/compile-rule-map.ts'
 import { compileLinkableTable } from '../compiler/compile-linkable-table.ts'
 import { createReducerResolver, topLevelIsStable } from './reducer-resolver.ts'
 import { findFreeIdentifiers } from './free-identifiers.ts'
@@ -36,9 +36,11 @@ import {
   resolveDegradationLevel, recordDegradation, degradationCaptureDepth, unwindDegradationCapture,
 } from '../compiler/degradation.ts'
 import type { HostMode } from '../cst/host-mode.ts'
-import { COMPOSED_PIECES } from '../compiler/linker.ts'
+import { COMPOSED_PIECES, type IRPiece } from '../compiler/linker.ts'
 import { serializeCombinator, serializeRuleMap } from '../compiler/ir-serialize.ts'
-import { evalCombinatorIR, evalRulesIR } from './ir-eval.ts'
+import { evalCombinatorIR, evalRulesIR, INERT_BUILDER } from './ir-eval.ts'
+import { countSiteVisits } from '../table/assemble.ts'
+import { run } from '../functional/run.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'
@@ -63,6 +65,48 @@ import type {
  */
 const TABLE_RUNTIME_SPECIFIER = 'parseman/table'
 
+/**
+ * BUILD-ONLY CARRIED PIECES.
+ *
+ * Nothing at runtime reads a grammar's carried IR: `compose()` links live `rules()`
+ * maps, and every runtime reader treats an IR piece as opaque
+ * (docs/design/runtime-and-size-contract.md, rules 1 and 2). Only a downstream macro
+ * build reads it. Under a rollup-family bundler the macro therefore leaves the IR out
+ * of the artifact and writes each chunk's carried lists beside it, as
+ * `<chunk>.parseman.json`; `resolveModulePieces` reads that file before it looks for
+ * an inline literal. Inline, the IR is about a quarter of a composed grammar's
+ * artifact, and the runtime spread that forwards an ancestor's pieces keeps that
+ * ancestor's module in the import graph of every parse.
+ *
+ * An item is an IR piece, or a reference to an export of a package module, resolved
+ * from the artifact's own location.
+ */
+export type CarriedSidecarItem = IRPiece | { from: string; name: string }
+/** One module's carried lists, by export name. */
+export type CarriedSink = Map<string, CarriedSidecarItem[]>
+export const CARRIED_SIDECAR_SUFFIX = '.parseman.json'
+type CarriedSidecar = { parseman: string; exports: Record<string, CarriedSidecarItem[]> }
+
+const _sidecarCache = new Map<string, { mtimeMs: number; sidecar: CarriedSidecar | null }>()
+/** The carried-pieces sidecar written beside a compiled artifact, or null. */
+function readCarriedSidecar(artifact: string): CarriedSidecar | null {
+  const file = artifact + CARRIED_SIDECAR_SUFFIX
+  let mtimeMs: number
+  try { mtimeMs = fs.statSync(file).mtimeMs } catch { return null }
+  const hit = _sidecarCache.get(file)
+  if (hit && hit.mtimeMs === mtimeMs) return hit.sidecar
+  let sidecar: CarriedSidecar | null = null
+  try {
+    // A file without an `exports` object is not a sidecar this plugin wrote: treat
+    // it as absent, so the inline literal is looked for and a missing one reports.
+    const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf8'))
+    const exports = typeof parsed === 'object' && parsed !== null ? (parsed as { exports?: unknown }).exports : undefined
+    if (typeof exports === 'object' && exports !== null) sidecar = parsed as CarriedSidecar
+  } catch { /* unreadable: no sidecar */ }
+  _sidecarCache.set(file, { mtimeMs, sidecar })
+  return sidecar
+}
+
 export type ParsecraftPluginOptions = {
   /** Extra module specifiers to treat as parseman re-exports */
   moduleAliases?: string[]
@@ -87,10 +131,59 @@ export type ParsecraftPluginOptions = {
   /** Emit grammar-coverage hooks in macro output. Off by default, so ordinary
    * macro output remains byte-identical. */
   grammarCoverage?: boolean
+  /**
+   * OPTIONAL TUNING for selective assemblies. **Off by default.**
+   *
+   * A grammar gets generated code only for its hottest sites, within a byte budget.
+   * Without this option the build ranks sites by a static estimate. With it, the
+   * build parses `files` from rule `entry` on the closure engine (nothing is
+   * generated to measure) and ranks sites by measured calls per byte instead. It
+   * changes which sites are generated, never what a parse returns.
+   */
+  assemblyProfile?: AssemblyProfile
+  /**
+   * Generated assembly bytes each module may spend, as a multiple of its own source
+   * length. **Default `0.25`.** `0` ships no assembly. The right number is
+   * per grammar: a larger one parses faster in steady state and costs import and
+   * first-parse time, so measure both, and keep the artifact within 5× its source
+   * (docs/design/runtime-and-size-contract.md, rules 4 and 6).
+   */
+  assemblyBudget?: number
+}
+
+/** A corpus a build parses to rank selective-assembly sites — see `assemblyProfile`. */
+export type AssemblyProfile = {
+  /** The rule each corpus file is parsed from, e.g. `'Stylesheet'`. A grammar
+   * without this rule keeps the static ranking. */
+  readonly entry: string
+  /** Paths of representative inputs. */
+  readonly files: readonly string[]
+}
+
+/** Corpus file contents, re-read when a file's mtime moves, so a watch build that
+ * re-lowers after a corpus edit ranks by the edited corpus. */
+const corpusCache = new Map<string, { readonly mtimeMs: number; readonly text: string }>()
+function corpusTexts(profile: AssemblyProfile): readonly string[] {
+  return profile.files.map(file => {
+    const mtimeMs = fs.statSync(file).mtimeMs
+    const hit = corpusCache.get(file)
+    if (hit !== undefined && hit.mtimeMs === mtimeMs) return hit.text
+    const text = fs.readFileSync(file, 'utf8')
+    corpusCache.set(file, { mtimeMs, text })
+    return text
+  })
 }
 
 const PARSEMAN_MODULE = 'parseman'
 
+/**
+ * The default `assemblyBudget`: generated assembly bytes a module may spend, as a
+ * multiple of its own source length. A quarter of the source keeps every jess
+ * grammar far under the 5x ceiling (contract rule 4); the 0.57.0 CHANGELOG has the
+ * measured curve.
+ */
+const DEFAULT_ASSEMBLY_BUDGET = 0.25
+
 /**
  * The REASON a lowering refused, appended to the warning that reports it.
  *
@@ -269,38 +362,142 @@ function parseModuleCached(filePath: string): ParsedModule | null {
   return parsed
 }
 
-export default createUnplugin((opts: ParsecraftPluginOptions = {}) => ({
-  name: 'parseman',
-  // Run BEFORE the bundler's TS/JS transform — otherwise esbuild (Vite) strips
-  // the `with { type: 'macro' }` import attribute before we ever see it, and the
-  // macro silently never fires.
-  enforce: 'pre' as const,
-
-  transformInclude(id: string) {
-    return /\.[jt]sx?$/.test(id) && !id.includes('node_modules')
-  },
-
-  transform(this: { warn?: (msg: string) => void }, code: string, id: string) {
-    if (!code.includes('parseman')) return null
-    if (!code.includes('macro')) return null
-    const moduleAliases = new Set([PARSEMAN_MODULE, ...(opts.moduleAliases ?? [])])
-    const result = transformMacro(code, id, moduleAliases, opts.warnUnloweredRegex === true, opts.recovery === true, opts.grammarCoverage === true)
-    if (result?.warnings.length) {
-      for (const w of result.warnings) {
-        if (typeof this?.warn === 'function') this.warn(`[parseman] ${w}`)
-        else console.warn(`[parseman] ${w}`)
-      }
+/** The rollup-family hook that writes each chunk's carried pieces beside it. */
+type SidecarBundle = Record<string, { type: string; fileName: string; exports?: string[]; moduleIds?: string[]; facadeModuleId?: string | null }>
+type SidecarEmitter = {
+  emitFile: (file: { type: 'asset'; fileName: string; source: string }) => unknown
+  getModuleInfo: (id: string) => { code: string | null } | null
+  resolve: (source: string, importer?: string) => Promise<{ id: string; external?: boolean | string } | null>
+}
+
+/**
+ * Where a module's export `exported` comes from when the module re-exports it,
+ * possibly renamed: `export { base as renamed } from './grammar'`, or an imported
+ * binding exported under another name. Null when the module declares it itself.
+ */
+function reexportSource(body: AnyNode[], exported: string): { source: string; imported: string } | null {
+  for (const st of body) {
+    if (st.type !== 'ExportNamedDeclaration') continue
+    for (const sp of (st.specifiers as AnyNode[] | undefined) ?? []) {
+      const exp = sp.exported as { name?: string; value?: string } | undefined
+      if ((exp?.name ?? exp?.value) !== exported) continue
+      const local = sp.local as { name?: string; value?: string } | undefined
+      const name = local?.name ?? local?.value
+      if (name === undefined) return null
+      const from = (st.source as { value?: string } | null | undefined)?.value
+      return from !== undefined ? { source: from, imported: name } : extractImportBindings(body).get(name) ?? null
     }
-    if (!result) return null
-    return { code: result.code, map: result.map }
-  },
-}))
+  }
+  return null
+}
+
+/**
+ * The carried list behind an entry chunk's export, followed from the entry module
+ * through its re-exports to the module that recorded it, under the name that module
+ * exports it as. A chunk's export names are its entry module's, so an entry that
+ * renames a grammar (`export { base as renamed } from './grammar'`) still finds the
+ * pieces recorded as `base`.
+ */
+async function followCarried(this: SidecarEmitter, sinks: Map<string, CarriedSink>, moduleId: string, name: string): Promise<CarriedSidecarItem[] | undefined> {
+  for (let hop = 0; hop < 64; hop++) {
+    const own = sinks.get(moduleId)?.get(name)
+    if (own !== undefined) return own
+    const code = this.getModuleInfo(moduleId)?.code
+    if (!code) return undefined
+    const parsed = parseSync(moduleId, code)
+    if (parsed.errors.length > 0) return undefined
+    const next = reexportSource(parsed.program.body as unknown as AnyNode[], name)
+    if (next === null) return undefined
+    const resolved = await this.resolve(next.source, moduleId)
+    if (resolved === null || resolved.external) return undefined
+    moduleId = resolved.id
+    name = next.imported
+  }
+  return undefined
+}
+
+/**
+ * Write `<chunk>.parseman.json` for every chunk that exports a grammar with carried
+ * pieces. An entry chunk's export is followed from its entry module to the module
+ * that recorded it (`followCarried`). Any other export is matched by name to the
+ * module that recorded it, preferring a module of the chunk itself; a name two
+ * modules of the bundle both record, and neither of them in the chunk, is ambiguous
+ * and is not written — a downstream compose of it then fails its build naming the
+ * artifact.
+ */
+async function emitCarriedSidecars(this: SidecarEmitter, sinks: Map<string, CarriedSink>, bundle: SidecarBundle): Promise<void> {
+  const recorders = new Map<string, string[]>()
+  for (const [moduleId, sink] of sinks) for (const name of sink.keys()) (recorders.get(name) ?? recorders.set(name, []).get(name)!).push(moduleId)
+  for (const chunk of Object.values(bundle)) {
+    if (chunk.type !== 'chunk') continue
+    const exports: Record<string, CarriedSidecarItem[]> = {}
+    for (const name of chunk.exports ?? []) {
+      const followed = chunk.facadeModuleId ? await followCarried.call(this, sinks, chunk.facadeModuleId, name) : undefined
+      if (followed !== undefined) { exports[name] = followed; continue }
+      const ids = recorders.get(name)
+      if (ids === undefined) continue
+      const own = ids.filter(m => chunk.moduleIds?.includes(m))
+      const moduleId = own.length === 1 ? own[0] : own.length === 0 && ids.length === 1 ? ids[0] : undefined
+      if (moduleId !== undefined) exports[name] = sinks.get(moduleId)!.get(name)!
+    }
+    if (Object.keys(exports).length === 0) continue
+    const sidecar: CarriedSidecar = { parseman: PARSEMAN_VERSION, exports }
+    this.emitFile({ type: 'asset', fileName: chunk.fileName + CARRIED_SIDECAR_SUFFIX, source: JSON.stringify(sidecar) })
+  }
+}
+
+const SIDECAR_FRAMEWORKS = new Set(['rollup', 'rolldown', 'vite'])
+
+export default createUnplugin((opts: ParsecraftPluginOptions = {}, meta) => {
+  // Module id → its carried lists, under a bundler that writes them beside the chunk.
+  // Any other bundler gets them inline, as before.
+  const sinks = SIDECAR_FRAMEWORKS.has(meta.framework) ? new Map<string, CarriedSink>() : undefined
+  const generateBundle = sinks === undefined ? undefined : {
+    generateBundle(this: SidecarEmitter, _options: unknown, bundle: SidecarBundle) { return emitCarriedSidecars.call(this, sinks, bundle) },
+  }
+  return {
+    name: 'parseman',
+    ...(generateBundle === undefined ? {} : { rollup: generateBundle, rolldown: generateBundle, vite: generateBundle }),
+    // Run BEFORE the bundler's TS/JS transform — otherwise esbuild (Vite) strips
+    // the `with { type: 'macro' }` import attribute before we ever see it, and the
+    // macro silently never fires.
+    enforce: 'pre' as const,
+
+    transformInclude(id: string) {
+      return /\.[jt]sx?$/.test(id) && !id.includes('node_modules')
+    },
+
+    transform(this: { warn?: (msg: string) => void; addWatchFile?: (file: string) => void }, code: string, id: string) {
+      if (!code.includes('parseman')) return null
+      if (!code.includes('macro')) return null
+      // A corpus edit changes which sites a profiled build generates, so a watch
+      // build re-lowers when one does.
+      for (const file of opts.assemblyProfile?.files ?? []) this?.addWatchFile?.(file)
+      const moduleAliases = new Set([PARSEMAN_MODULE, ...(opts.moduleAliases ?? [])])
+      const sink: CarriedSink | undefined = sinks && new Map()
+      const result = transformMacro(code, id, moduleAliases, opts.warnUnloweredRegex === true, opts.recovery === true, opts.grammarCoverage === true, opts.assemblyProfile, opts.assemblyBudget, sink)
+      if (sinks && sink) {
+        if (sink.size > 0) sinks.set(id, sink)
+        else sinks.delete(id)
+      }
+      if (result?.warnings.length) {
+        for (const w of result.warnings) {
+          if (typeof this?.warn === 'function') this.warn(`[parseman] ${w}`)
+          else console.warn(`[parseman] ${w}`)
+        }
+      }
+      if (!result) return null
+      return { code: result.code, map: result.map }
+    },
+  }
+})
 
 // ---------------------------------------------------------------------------
 // Reading carried pieces back out of a COMPILED grammar module
 // ---------------------------------------------------------------------------
-// The macro embeds a grammar's linkable pieces inside its exported const's
-// initializer (see `withCarriedPieces`). To compose an imported grammar we parse
+// Under a rollup-family bundler the pieces are in the sidecar beside the module
+// (`readCarriedSidecar`). Otherwise the macro embeds them inside its exported const's
+// initializer (see `withCarriedPieces`), and to compose an imported grammar we parse
 // its compiled module, find that const, and pull the pieces literal back out —
 // these three pure helpers do exactly that (no runtime, no source recompile).
 
@@ -544,10 +741,13 @@ export function transformMacro(
   warnUnloweredRegex = false,
   recovery = false,
   grammarCoverage = false,
+  assemblyProfile?: AssemblyProfile,
+  assemblyBudget = DEFAULT_ASSEMBLY_BUDGET,
+  carriedSink?: CarriedSink,
 ): TransformMacroResult | null {
   const depth = degradationCaptureDepth()
   try {
-    return transformMacroImpl(code, id, moduleAliases, warnUnloweredRegex, recovery, grammarCoverage)
+    return transformMacroImpl(code, id, moduleAliases, warnUnloweredRegex, recovery, grammarCoverage, assemblyProfile, assemblyBudget, carriedSink)
   } finally {
     setReducerResolver(null)
     setBuilderImportResolver(null)
@@ -564,6 +764,9 @@ function transformMacroImpl(
   warnUnloweredRegex: boolean,
   recovery: boolean,
   grammarCoverage: boolean,
+  assemblyProfile: AssemblyProfile | undefined,
+  assemblyBudgetShare: number,
+  carriedSink: CarriedSink | undefined,
 ): TransformMacroResult | null {
   let result: ReturnType<typeof parseSync>
   try {
@@ -1595,6 +1798,23 @@ function transformMacroImpl(
     local = false,
   ): RawItem[] | null => {
     const { file } = module
+    const fail = (why: string): null => { unresolved.why ??= `${exportName} in ${file}: ${why}`; return null }
+    // A build-only sidecar wins over an inline literal: an artifact that has one
+    // carries no literal (see `CarriedSidecarItem`).
+    const sidecarItems = module.source || local ? undefined : readCarriedSidecar(file)?.exports[exportName]
+    if (sidecarItems !== undefined) {
+      const list: RawItem[] = []
+      for (const item of sidecarItems) {
+        if ('ir' in item) { list.push(item); continue }
+        const sub = resolveGrammarModule(file, item.from)
+        if (sub === null) return fail(`its carried pieces name \`${item.name}\` from '${item.from}', a module that could not be found`)
+        if (seen.has(sub.file)) continue
+        const pieces = resolveModulePieces(sub, item.name, new Set(seen).add(sub.file), unresolved)
+        if (pieces === null) return fail(`its carried pieces name \`${item.name}\` from '${item.from}', which could not be resolved`)
+        list.push(...pieces)
+      }
+      return list
+    }
     const mod = module.source
       ? lowerPrivateSourceModule(file, moduleAliases, warnUnloweredRegex, recovery)
       : parseModuleCached(file)
@@ -1602,9 +1822,15 @@ function transformMacroImpl(
     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
+    if (!literalRange) {
+      // A compiled grammar with neither a literal nor a sidecar entry was built to be
+      // composed or it was not, and a runtime compose() cannot link it either way.
+      return initNode !== null && !module.source && mod.src.slice(initNode.start, initNode.end).includes('tableRules(')
+        ? fail(`is a compiled grammar with no carried pieces — no inline literal, and no entry in ${path.basename(file)}${CARRIED_SIDECAR_SUFFIX}. `
+          + 'Rebuild it with this parseman, and keep that file beside the artifact')
+        : 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[] = []
@@ -1675,6 +1901,32 @@ function transformMacroImpl(
     return result
   }
 
+  /**
+   * Record an exported grammar's carried list in the build-only sink rather than
+   * emitting it into the runtime artifact. `false` when there is no sink, or when an
+   * entry cannot be written as data; the caller then emits it inline, as before.
+   *
+   * A package import stays a reference, resolved from the artifact's location just as
+   * the import itself is, so a descendant never re-serializes its ancestor. A relative
+   * import names a module the bundler folds into this chunk, which has no artifact of
+   * its own to point at, so its pieces are written out here.
+   */
+  const sinkCarried = (name: string, list: CarriedItem[]): boolean => {
+    if (carriedSink === undefined) return false
+    const out: CarriedSidecarItem[] = []
+    for (const it of list) {
+      if (!isSpread(it)) { out.push(it); continue }
+      const b = importBindings.get(it.__spreadLocal)
+      if (b === undefined) return false
+      if (!b.source.startsWith('.') && !path.isAbsolute(b.source)) { out.push({ from: b.source, name: b.imported }); continue }
+      const pieces = importedPieces(it.__spreadLocal)
+      if (pieces === null) return false
+      out.push(...pieces)
+    }
+    carriedSink.set(name, out)
+    return true
+  }
+
   /**
    * 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
@@ -1984,9 +2236,10 @@ function transformMacroImpl(
           carried,
           reflection: compiled.reflection,
         })
+        const select = selectAssembly(init.start, 'compose()', compiled, !declaresLeaf())
         return {
-          replacement: compiled.replacementWithMetadata(reflectionMetadata),
-          exportedReplacement: compiled.replacementWithMetadata(exportedMetadata),
+          replacement: assembledReplacement(compiled, reflectionMetadata, select),
+          exportedReplacement: assembledReplacement(compiled, exportedMetadata, select),
           carried,
           ...(composing ? { trivia: composing } : {}),
           ...(importedFactories.length ? { importedFactories } : {}),
@@ -2006,6 +2259,74 @@ function transformMacroImpl(
     return null
   }
 
+  /**
+   * SELECTIVE ASSEMBLY, BUDGETED PER MODULE. A fused grammar's default AST/no-lines
+   * table carries generated code for its hottest sites only (`select-hot.ts`); the
+   * closure engine runs the rest. The site bodies of every fused grammar in this
+   * module together may not exceed `assemblyBudget` times the module's own source.
+   *
+   * A module that declares a `composeLeaf` has named its terminal parser, so its
+   * `compose()` results are composable PIECES: another build re-lowers them and
+   * never parses through their table, so they spend nothing. Without a
+   * `composeLeaf`, a `compose()` result is the module's parser.
+   */
+  let assemblyBudget = Math.floor(code.length * assemblyBudgetShare)
+  let leafDeclared: boolean | undefined
+  const declaresLeaf = (): boolean => leafDeclared ??= (body as Statement[]).some(stmt => {
+    const vd = unwrapVd(stmt)
+    return vd !== null && vd.declarations.some(d => d.init != null && isComposeLeafCall(d.init as Expression))
+  })
+  const selectAssembly = (
+    pos: number,
+    label: string,
+    compiled: CompiledRuleMapTable,
+    terminal: boolean,
+  ): ReadonlySet<number> => {
+    // A coverage build instruments the table; its counters are not the shipping
+    // parser, so it carries no assembly.
+    if (!terminal || grammarCoverage) return new Set()
+    const { sites, bytes, refusal } = compiled.selectAssembly(assemblyBudget, profileOf(compiled))
+    // The artifact still parses, on the closure engine, but a build that would
+    // have generated code says which construct stopped it rather than fall back
+    // silently. Not `warn()`: every declaration still lowers, so the module stays
+    // fully resolved.
+    if (refusal !== undefined) {
+      warnings.push(`${id}:${lineOf(pos)} — ${label}: its precompiled assembly cannot emit ${refusal}; the artifact runs on the closure engine`)
+    }
+    assemblyBudget -= bytes
+    return sites
+  }
+  /** Measured site calls over the optional corpus, or `undefined` for the static
+   * ranking. A file whose parse throws still contributes the calls it made. */
+  const profileOf = (compiled: CompiledRuleMapTable): Int32Array | undefined => {
+    // Only the default AST/no-lines table carries an assembly, so only it is profiled.
+    if (assemblyProfile === undefined || compiled.hostMode !== 'ast' || compiled.prog.lines === 1
+      || !(assemblyProfile.entry in compiled.prog.rules)) return undefined
+    let parsed = 0
+    // A builder re-lowered from carried IR is inert at build time; for COUNTING
+    // only, a plain node stands in for it, so the corpus can run past it.
+    const fns = compiled.prog.fns.map(fn => {
+      const type = (fn as { [INERT_BUILDER]?: string } | null)?.[INERT_BUILDER]
+      return type === undefined ? fn
+        : (children: unknown, _fields: unknown, span: unknown) => ({ type, span, children })
+    })
+    const counts = countSiteVisits(compiled.prog, rules => {
+      const entry = rules[assemblyProfile.entry]!
+      for (const text of corpusTexts(assemblyProfile)) {
+        try { if (run(entry, text).ok) parsed++ } catch { /* the calls it made still count */ }
+      }
+    }, fns)
+    if (parsed > 0) return counts
+    // Not `warn()`: nothing fell back to the interpreter — the build is only untuned.
+    warnings.push(`${id} — assemblyProfile: no corpus file parsed from rule "${assemblyProfile.entry}"; using the static ranking`)
+    return undefined
+  }
+  /** The fused table's replacement, with its selective default assembly if any. */
+  const assembledReplacement = (compiled: CompiledRuleMapTable, metadata: string, select: ReadonlySet<number>): string =>
+    select.size === 0
+      ? compiled.replacementWithMetadata(metadata)
+      : supercompileRuleMapReplacement(compiled.prog, compiled.replacementWithMetadata(metadata, { select }), select)
+
   /**
    * Compile a terminal composition. Imported/base pieces still travel as normal
    * re-lowerable IR, but the final local rules map is compiled directly in this
@@ -2136,12 +2457,10 @@ function transformMacroImpl(
         if (compiled !== null) {
           usedTableRuntime = true
           return {
-            replacement: supercompileRuleMapReplacement(
-              compiled.prog,
-              compiled.replacementWithMetadata(
-                staticTableMetadataSource({ reflection: compiled.reflection, leaf: true }),
-                { precompileDefault: true },
-              ),
+            replacement: assembledReplacement(
+              compiled,
+              staticTableMetadataSource({ reflection: compiled.reflection, leaf: true }),
+              selectAssembly(init.start, 'composeLeaf()', compiled, true),
             ),
             ...(importedFactories.length ? { importedFactories } : {}),
           }
@@ -2368,6 +2687,7 @@ function transformMacroImpl(
             else warn(init.start, `${varName}: exported grammar could not be serialized to IR, so it carries no `
               + 'composable pieces — a downstream compose() of this grammar will fall back to runtime. '
               + 'Re-run with PARSEMAN_IR_DEBUG=1 to print the combinator that blocked serialization.')
+            if (carriedMetadata !== undefined && sinkCarried(varName, carriedMetadata)) carriedMetadata = undefined
           }
           const replacement = compiledRules.replacement !== null
             ? compiledRules.replacementWithMetadata!(staticTableMetadataSource({
@@ -2403,7 +2723,7 @@ function transformMacroImpl(
           // grammar via `import { <name> }` (re-composition, no source) and re-lower it
           // under ITS composing trivia.
           localComposedCarried.set(varName, fused.carried)
-          const replacement = exportPrefix ? fused.exportedReplacement : fused.replacement
+          const replacement = exportPrefix && !sinkCarried(varName, fused.carried) ? fused.exportedReplacement : fused.replacement
           // Coverage definitions already ride in the table program's `cv` pool;
           // `tableRules` exposes that same pool through the metadata prototype.
           replacements.push({ start: init.start, end: init.end, replacement })

package/src/plugin/ir-eval.ts

@@ -27,6 +27,9 @@ import { adjacent, notAdjacent } from '../combinators/adjacency.ts'
 
 type Comb = Combinator<unknown>
 
+/** Marks a carried direct builder that cannot run at build time; its value is the node type. */
+export const INERT_BUILDER: unique symbol = Symbol('parseman.inertBuilder')
+
 /** Reconstruct a rule map from serialized IR (the inverse of `serializeRuleMap`) —
  * evaluate the combinator-construction expression with every constructor in scope.
  *
@@ -88,7 +91,10 @@ function evalIR(ir: string, rulesImpl: unknown): unknown {
     // 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)
+    const inert = (() => { throw new Error('IR node build requires static re-lowering') }) as (() => never) & { [INERT_BUILDER]?: string }
+    // Named, so a build-time profile run can stand a plain node in for it.
+    inert[INERT_BUILDER] = type
+    const n = node(type, child as never, inert 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

package/src/regex/classes.ts

@@ -63,6 +63,9 @@ export function literalCodePoints(frag: string): number[] | null {
     if (ch === '\\') {
       const e = frag[i + 1]
       if (e === undefined) return null
+      // Any other word-character escape is a class (`\d`), an assertion (`\b`), a
+      // backreference or a hex, unicode or control escape, never the character itself.
+      if (!(e in CLASS_ESCAPES) && /\w/.test(e)) return null
       out.push(e in CLASS_ESCAPES ? CLASS_ESCAPES[e]! : e.codePointAt(0)!)
       i += 2
       continue