parseman 0.45.0 → 0.47.0

package/src/compiler/linker.ts

@@ -0,0 +1,954 @@
+/**
+ * The linker: compose independently-carried grammar pieces into ONE runnable rule map.
+ *
+ * Composition is a RULE-MAP MERGE plus a single encode. Each piece carries its
+ * combinator graph as IR; `compose()` evaluates every piece's IR back to a rule map,
+ * lets a later piece's name override an earlier one, and encodes the merged map ONCE.
+ * `enc.winners` binds every by-name reference against that merged map, so overriding a
+ * rule reroutes EVERY call to it — including calls inside a base piece's own rules
+ * (open recursion) — with no shared scope and no relocation. Later piece wins per
+ * rule name.
+ *
+ * This replaced a textual splice. The source lowering compiled each piece to namespaced
+ * `_r_<Name>` function sources and concatenated them into one `new Function` scope,
+ * patching `@FS:` first-set placeholders per winner. That is why the linker needed
+ * `'unsafe-eval'`; the merge is now data, so it does not.
+ */
+import { ruleDependencies, childrenOf } from '../analysis/gating.ts'
+import { FUSED_HOST_MODE, FUSED_HOST_ELIDED, type HostMode } from '../cst/host-mode.ts'
+import { evalRuleMapIR, serializeRuleMap } from './ir-serialize.ts'
+import { compileLinkableTable, type LinkableTable } from './compile-linkable-table.ts'
+import { compileRuleMapRunnable } from '../table/compile-rule-map.ts'
+import { tableRules } from '../table/assemble.ts'
+import { GRAMMAR_REFLECTION } from '../cst/reflection.ts'
+import { PARSEMAN_VERSION } from '../version.ts'
+import type { BuildHost, Combinator, CstCollapsePredicate, ParseContext, ParseResult } from '../types.ts'
+import type { Runnable } from '../functional/run.ts'
+
+/**
+ * Compile a `rules()` map to a **linkable artifact** — the composable, shippable
+ * form (RULE_ABI_PLAN §4). A package exports `linkable(rules(g => …))`; consumers
+ * import that artifact and `fuse([...])` it — **no source of the base grammar is
+ * ever read**. Under the macro this is precompiled to static pieces; in the
+ * interpreter it compiles here at load (like `compile()`).
+ *
+ * `ns` is a per-artifact namespace; omit it to auto-assign a process-unique one
+ * (fine at runtime — the macro supplies a stable module-derived ns instead).
+ */
+let _nsCounter = 0
+export function linkable(
+  rulesMap: Record<string, Combinator<unknown>>,
+  ns?: string,
+  trivia?: Combinator<unknown>,
+  // Compile-time host mode, same meaning as `compile(g, { hostMode })`: 'ast' (default)
+  // emits the grammar's own builders and NO positioned-CST branch; 'cst' builds every
+  // node through the host. A linked/fused artifact is version- and mode-locked, so a
+  // language service links its own 'cst' artifact rather than switching at parse time.
+  hostMode?: HostMode,
+): LinkableTable {
+  const piece = compileLinkableTable(
+    Object.entries(rulesMap),
+    ns ?? `_lk${_nsCounter++}_`,
+    { ...(trivia ? { trivia } : {}), ...(hostMode ? { hostMode } : {}) },
+  )
+  if (!piece) throw new Error('linkable(): this grammar cannot be compiled to a linkable artifact (contains a runtime-only parser fallback)')
+  return piece
+}
+
+export type CstBuildHostOptions = {
+  /**
+   * Collapse transparent one-child CST wrapper nodes at build time.
+   * - `true`: collapse any one-child node whose rawChildren also has exactly one
+   *   entry, so trivia/error boundaries are not silently dropped.
+   * - `string[]`: collapse only these grammar node types.
+   * - predicate: final policy hook for language-specific public CSTs.
+   */
+  collapse?: boolean | readonly string[] | CstCollapsePredicate
+  /**
+   * Materialize `node(..., { tags })` grammar metadata onto produced CST nodes.
+   * When omitted, tags stay in grammar reflection for zero per-node tree cost.
+   */
+  tags?: boolean
+}
+
+function normalizeCstCollapse(collapse: CstBuildHostOptions['collapse']): CstCollapsePredicate | undefined {
+  if (collapse === true) return () => true
+  if (Array.isArray(collapse)) {
+    const types = new Set(collapse)
+    return type => types.has(type)
+  }
+  return typeof collapse === 'function' ? collapse : undefined
+}
+
+function buildCstNode(
+  type: string,
+  children: ReadonlyArray<unknown>,
+  _fields: unknown,
+  span: { start: number; end: number },
+  _rawChildren?: ReadonlyArray<unknown>,
+  _triviaLog?: readonly number[],
+  state?: unknown,
+  tags?: readonly string[] | undefined,
+): unknown {
+  // Carry the grammar's `ctx.state` snapshot onto the node (null when unset) — the
+  // CST contract includes `state` and incremental re-parse replays it on edit.
+  return tags !== undefined && tags.length > 0
+    ? { _tag: 'node', type, tags, span: { ...span }, state: state ?? null, children: [...children] }
+    : { _tag: 'node', type, span: { ...span }, state: state ?? null, children: [...children] }
+}
+
+/**
+ * A generic positioned-CST build host (RULE_ABI_PLAN §7). Pass as `ctx.build`
+ * (or `parseDoc(..., { build: cstBuildHost })`) to make ANY linkable/fused
+ * grammar produce a uniform CST — `{ _tag:'node', type, span, state, children }`
+ * — instead of its own eval-AST builders. This is the host the linter and IDE
+ * drivers use; the eval driver leaves `ctx.build` unset (grammar's own builders).
+ *
+ * For public syntax trees, call `cstBuildHost({ collapse })`: Parseman will skip
+ * allocating wrapper CST nodes whose single child should stand in for the rule.
+ */
+export function cstBuildHost(options?: CstBuildHostOptions): BuildHost
+export function cstBuildHost(
+  type: string,
+  children: ReadonlyArray<unknown>,
+  fields: unknown,
+  span: { start: number; end: number },
+  rawChildren?: ReadonlyArray<unknown>,
+  triviaLog?: readonly number[],
+  state?: unknown,
+  tags?: readonly string[] | undefined,
+): unknown
+export function cstBuildHost(
+  typeOrOptions?: string | CstBuildHostOptions,
+  children?: ReadonlyArray<unknown>,
+  _fields?: unknown,
+  span?: { start: number; end: number },
+  rawChildren?: ReadonlyArray<unknown>,
+  triviaLog?: readonly number[],
+  state?: unknown,
+  _tags?: readonly string[] | undefined,
+): unknown {
+  if (typeof typeOrOptions === 'string') {
+    return buildCstNode(typeOrOptions, children ?? [], _fields, span ?? { start: 0, end: 0 }, rawChildren, triviaLog, state)
+  }
+  const collapse = normalizeCstCollapse(typeOrOptions?.collapse)
+  const materializeTags = typeOrOptions?.tags === true
+  const host: BuildHost = (
+    type: string,
+    children: ReadonlyArray<unknown> | undefined,
+    fields: unknown,
+    span: { start: number; end: number },
+    rawChildren: ReadonlyArray<unknown>,
+    triviaLog: readonly number[],
+    state: unknown,
+    tags?: readonly string[] | undefined,
+    // A CST/collapse host always keeps `children` (chV) — the opt-out never
+    // applies — so `?? []` is unreachable defensive modeling for the widened type.
+  ) => buildCstNode(type, children ?? [], fields, span, rawChildren, triviaLog, state, materializeTags ? tags : undefined)
+  ;(host as typeof host & { _parsemanCstOutput?: true })._parsemanCstOutput = true
+  if (collapse) host._parsemanCstCollapse = collapse
+  return host
+}
+
+// `cstBuildHost` itself is also accepted as a BuildHost (without options).
+;(cstBuildHost as unknown as { _parsemanCstOutput?: true })._parsemanCstOutput = true
+
+/**
+ * A fused function receives the full ParseContext through `run()`. Direct
+ * callers historically supplied a plain context object, so keep that usage
+ * valid while making the function assignable to the public `Runnable` type.
+ * Generated code treats optional framework fields as absent when they are not
+ * provided, matching the interpreter's normal defaults.
+ */
+export type FusedRule = (
+  input: string,
+  pos: number,
+  ctx: ParseContext | Record<string, unknown>,
+) => ParseResult<unknown> & { readonly value?: unknown }
+
+
+/**
+ * Fuse carried pieces into a runnable rule map — the TABLE equivalent of the
+ * textual splice this file used to perform.
+ *
+ * `fusedBody()` concatenated namespaced `_r_<Name>` function sources, picked a winning
+ * function per name, and patched `@FS:` dispatch placeholders with the winner's
+ * first-set condition — roughly 200 lines whose entire job was to make separately
+ * lowered SOURCE agree about names. A table has no text to splice, so the merge moves
+ * up one level onto the combinators: merge the rule maps (later piece wins), then
+ * `encodeTable` ONCE over the merged map. `enc.winners` binds every by-name reference,
+ * including a base piece's internal `g.Atom` that an override replaced, so open
+ * recursion across pieces resolves without relocating a single encoded offset.
+ *
+ * One encode, no pools to merge, and the result is the table the merged grammar would
+ * have produced had it been written as a single `rules()` call.
+ */
+function fuseCarried(
+  carried: ReadonlyArray<LinkableTable | IRPiece>,
+  trivia?: Combinator<unknown>,
+  hostMode?: HostMode,
+): Record<string, FusedRule> {
+  const maps: Array<Array<[string, Combinator<unknown>]>> = []
+  for (const p of carried) {
+    // ARTIFACT VERSION LOCK. `fusedBody` enforced this and would have taken it with it:
+    // artifacts are version-locked and there is no cross-version read path, so an
+    // UNSTAMPED piece and a MISMATCHED one are both refused — a stale artifact that
+    // merely happens to still encode is exactly what this stops.
+    if (!isIRPiece(p)) {
+      if (typeof p.v !== 'string') {
+        throw new Error(
+          `parseman: artifact "${p.ns}" is UNSTAMPED (compiled before the version-lock invariant). `
+          + `Recompile the grammar with parseman ${PARSEMAN_VERSION}; parseman does not fuse unversioned or cross-version artifacts.`,
+        )
+      }
+      if (p.v !== PARSEMAN_VERSION) {
+        throw new Error(
+          `parseman: artifact "${p.ns}" was compiled with parseman ${p.v}, but is being fused with parseman ${PARSEMAN_VERSION}. `
+          + `Compiled grammar artifacts are version-locked — recompile the grammar with parseman ${PARSEMAN_VERSION}; parseman does not fuse across versions.`,
+        )
+      }
+    }
+    const rules = ruleMapOfCarried(p)
+    if (rules === undefined) {
+      throw new Error(`compose: carried piece "${p.ns}" has no re-lowerable IR and cannot be fused`)
+    }
+    maps.push(rules)
+  }
+  const merged = mergeCarriedRuleMaps(maps)
+  materializeDirectBuilders(merged)
+  // COMPOSING-WINS is an OVERRIDE, not a gap-fill: the composing grammar's trivia
+  // governs every fused rule INCLUDING inherited ones. `applyAmbient` inside
+  // `compileRuleMap` only fills a rule that declares none, which would leave an
+  // inherited rule still skipping its own base's whitespace after a delta re-declared
+  // it. Safe to mutate — `evalRuleMapIR` builds fresh combinators per fuse.
+  if (trivia) {
+    for (const [, rule] of merged) {
+      if (rule._meta.isTrivia) continue
+      ;(rule._meta as { grammarTrivia?: Combinator<unknown> }).grammarTrivia = trivia
+    }
+  }
+  // RUNNABLE, not printable. `compose()` returns a parser; it never emits source, so
+  // requiring a captured source per author callback would refuse every grammar built at
+  // runtime — which have live callbacks by construction.
+  const refusals: string[] = []
+  const compiled = compileRuleMapRunnable(merged, {
+    ...(trivia ? { trivia } : {}),
+    ...(hostMode ? { hostMode } : {}),
+    refusals,
+  })
+  if (compiled === null) {
+    throw new Error(`compose: the merged grammar could not be encoded to a table${refusals.length ? ` — ${refusals.join('; ')}` : ''}`)
+  }
+  // `tableRules`, NOT `exec.ts`'s same-named `tableRules`. Both return
+  // `Record<string, TableRule>`, so binding the interpreter here type-checked and ran
+  // correctly — it was just the SLOW engine, on the one path (compose/fuse) that never
+  // goes through `table/index.ts` and so never saw the `tableRules as tableRules`
+  // re-export. Import the assembler by its own name so the binding cannot go stale again.
+  const map = tableRules(compiled.prog) as unknown as Record<string, FusedRule>
+  // The host-mode stamp went on the fused closure before; a table carries nothing until
+  // it is stamped, and an UNSTAMPED map reads as `{ ast, false }` so every driver
+  // compatibility check passes vacuously. Stamped on the rule functions too, because
+  // `run(map.Rule, …)` is handed the rule and never sees the map.
+  for (const k of Object.keys(map)) {
+    Object.defineProperty(map[k]!, FUSED_HOST_MODE, { value: compiled.hostMode, enumerable: false })
+    Object.defineProperty(map[k]!, FUSED_HOST_ELIDED, { value: compiled.hostBranchElided, enumerable: false })
+  }
+  Object.defineProperty(map, FUSED_HOST_MODE, { value: compiled.hostMode, enumerable: false })
+  Object.defineProperty(map, FUSED_HOST_ELIDED, { value: compiled.hostBranchElided, enumerable: false })
+  // GRAMMAR REFLECTION, which `fusedBody` merged across pieces and stamped. A visitor
+  // built over a composed grammar reads it to know the node types; unstamped, it reads
+  // as an empty grammar and every visitor silently matches nothing.
+  Object.defineProperty(map, GRAMMAR_REFLECTION, { value: compiled.reflection, enumerable: false })
+  return map
+}
+
+/**
+ * Re-attach a DIRECT node builder that came back from IR as an inert sentinel.
+ *
+ * `evalRuleMapIR` deliberately refuses to evaluate a captured `buildSrc`: raw IR
+ * interpretation must not run arbitrary source, so `_nd` installs a thrower and keeps
+ * the text. Only a COMPILER consumer may materialize it — and the runtime fuse is one.
+ * The source lowering did exactly this, less visibly: it inlined `buildSrc` into the
+ * fused body and `new Function` evaluated it. The table parks callbacks in a pool
+ * instead of inlining them, so the same materialization has to be explicit or the
+ * sentinel reaches the pool and throws on the first parse through that node.
+ *
+ * Scoped to the runtime fuse. The MACRO never comes here: its encoder captures
+ * `buildSrc` and PRINTS it, so it needs no live function at all.
+ */
+function materializeDirectBuilders(ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>): void {
+  const seen = new Set<Combinator<unknown>>()
+  const visit = (p: Combinator<unknown>): void => {
+    if (seen.has(p)) return
+    seen.add(p)
+    const d = p._def as { tag: string; build?: unknown; buildSrc?: string }
+    if (d.tag === 'node' && typeof d.buildSrc === 'string') {
+      try {
+        // eslint-disable-next-line no-eval
+        const fn = (0, eval)(`(${d.buildSrc})`) as unknown
+        if (typeof fn === 'function') d.build = fn
+      } catch { /* leave the sentinel: it throws with its own message on reach */ }
+    }
+    if (d.tag === 'lazy') {
+      let resolved: Combinator<unknown> | undefined
+      try { resolved = (d as unknown as { thunk: () => Combinator<unknown> }).thunk() } catch { return }
+      if (resolved) visit(resolved)
+      return
+    }
+    for (const child of childrenOf(p._def)) visit(child)
+  }
+  for (const [, rule] of ruleMap) visit(rule)
+}
+
+/** The combinator map behind a carried piece: IR is evaluated back, a table piece
+ * uses the IR it always carries. `undefined` only for a piece with neither. */
+function ruleMapOfCarried(p: LinkableTable | IRPiece): Array<[string, Combinator<unknown>]> | undefined {
+  if (isIRPiece(p)) return evalRuleMapIR(p.ir)
+  // IR FIRST: re-evaluating it yields FRESH combinators, so seeding composing trivia
+  // onto their `_meta` cannot leak back into the artifact this piece came from. The live
+  // map is the fallback for a runtime-built grammar that has no serializable IR.
+  if (p.ir !== null) return evalRuleMapIR(p.ir)
+  return p.ruleMap.length > 0 ? p.ruleMap.map(([k, v]) => [k, v] as [string, Combinator<unknown>]) : undefined
+}
+
+/** Fold ordered rule maps into the composed map: a later piece's name WINS.
+ *
+ * A REFERENCE IS NOT A DEFINITION. A `rules(g => …)` cache also holds every `g.X` that
+ * was merely ACCESSED, as an unresolvable lazy. Merged in order, such an entry lands
+ * last and SHADOWS the piece that actually defines the name — the encoder then finds a
+ * hole where the winner should be and refuses the whole grammar. The reference is not
+ * lost: it stays inside the referring piece's rule bodies, where `enc.winners` binds it
+ * by name to whichever piece supplies the definition.
+ */
+function mergeCarriedRuleMaps(
+  maps: ReadonlyArray<ReadonlyArray<readonly [string, Combinator<unknown>]>>,
+): Array<[string, Combinator<unknown>]> {
+  const winners = new Map<string, Combinator<unknown>>()
+  for (const map of maps) {
+    for (const [name, rule] of map) {
+      if (rule._def.tag === 'lazy') {
+        try { rule._def.thunk() } catch { continue }
+      }
+      winners.set(name, rule)
+    }
+  }
+  return [...winners]
+}
+
+
+export { FUSED_HOST_MODE, FUSED_HOST_ELIDED } from '../cst/host-mode.ts'
+
+/** The host mode a fused/composed rule map was built for. Defaults to 'ast'. */
+export function fusedHostModeOf(registry: object): HostMode {
+  const m = (registry as Record<symbol, unknown>)[FUSED_HOST_MODE]
+  return m === 'cst' ? 'cst' : 'ast'
+}
+
+/** Whether a fused/composed rule map dropped any direct builder's CST branch. */
+export function fusedHostElidedOf(registry: object): boolean {
+  return (registry as Record<symbol, unknown>)[FUSED_HOST_ELIDED] === true
+}
+
+/**
+ * Compose grammars/artifacts into a runnable parser map — the ONLY public
+ * composition entry point. `compose([base, ext, …])`: later entries override
+ * earlier ones by rule name, and because fusion re-binds every reference in one
+ * shared scope, an override reroutes the base's OWN calls too (open recursion).
+ *
+ * Each entry may be a **grammar** (a `rules()` result — a map of combinators,
+ * linkable-ified here) OR an already-compiled **linkable artifact** (what the
+ * macro emits and a package ships). So a package needs no opt-in wrapper to be
+ * composable — `compose([importedGrammar, myRules])` just works.
+ *
+ * The macro compiles `compose([...])` to STATIC fused source (no `new Function`).
+ * Called at runtime (no macro, like `compile()`) it fuses via `new Function`.
+ */
+/** A composed parser carries its flattened source pieces (non-enumerable) so it
+ * can be composed AGAIN — `compose([lessGrammar, delta])` where `lessGrammar` is
+ * itself a `compose([...])` result. */
+export const COMPOSED_PIECES = Symbol.for('parseman.composedPieces')
+
+/** The carried pieces a `compose()`/`composeLeaf()` result holds, or `undefined` when
+ * the value is not a composed grammar. This is what makes a fused grammar analysable:
+ * the pieces are re-lowerable IR even though the fused map itself is only functions. */
+export function composedPiecesOf(
+  grammar: Record<string, unknown>,
+): ReadonlyArray<LinkableTable | IRPiece> | undefined {
+  const pieces = (grammar as unknown as Record<symbol, unknown>)[COMPOSED_PIECES]
+  return Array.isArray(pieces) ? pieces as ReadonlyArray<LinkableTable | IRPiece> : undefined
+}
+
+/**
+ * A terminal fused grammar may be used to run a parser, but not as an input to
+ * another composition. Macro `composeLeaf()` uses this for a local semantic
+ * reduction over imported recognition-only IR: the local reductions stay in
+ * their lexical module and therefore never become carried IR.
+ */
+const LEAF_COMPOSED = Symbol.for('parseman.leafComposed')
+
+/** The composing (outermost) trivia a runtime `compose()` applied — stored so a
+ * LATER `compose([thisResult, …])` that declares no trivia of its own still re-lowers
+ * these rules under the SAME trivia (composing-wins survives re-composition). The
+ * carried IR pieces hold no trivia of their own, so it must be remembered separately. */
+const COMPOSED_TRIVIA = Symbol.for('parseman.composedTrivia')
+
+/** Final winner map for semantic-coverage tooling. It exists only when every
+ * carried compose piece is re-lowerable IR; opaque precompiled artifacts have no
+ * combinator graph to inspect and therefore deliberately expose no fake map. */
+const COMPOSED_COVERAGE_RULES = Symbol.for('parseman.composedCoverageRules')
+
+/** The compact IR form a grammar carries instead of its lowered rule source: the
+ * combinator-construction expression, re-lowered here at fuse time. */
+export type IRPiece = { ns: string; ir: string; trackLines?: true }
+
+function isIRPiece(p: unknown): p is IRPiece {
+  return !!p && typeof p === 'object'
+    && typeof (p as IRPiece).ir === 'string' && typeof (p as IRPiece).ns === 'string'
+    && !('keys' in (p as object))
+}
+
+/** A `linkable()` artifact — a TABLE piece. Distinguished from a bare IR piece by the
+ * fields only a compiled artifact has (`keys`/`external`), and from a plain `rules()`
+ * map by carrying `ns` at all. */
+function isLinkableTable(p: unknown): p is LinkableTable {
+  return !!p && typeof p === 'object'
+    && typeof (p as LinkableTable).ns === 'string'
+    && Array.isArray((p as LinkableTable).keys)
+}
+
+/** Memoize a zero-arg thunk, keeping it LAZY. Used where two diagnostic thunks want
+ * the same carried-IR hydration: the work must not happen when the diagnostic is off,
+ * and must not happen twice when it is on. */
+export function once<T>(fn: () => T): () => T {
+  let done = false
+  let value: T
+  return () => {
+    if (!done) { value = fn(); done = true }
+    return value
+  }
+}
+
+/** The re-lowerable carried pieces' rule maps, in compose order — the input to the
+ * gating analysis (`diagnoseGrammar`). An opaque precompiled artifact contributes no
+ * combinator graph, so it is skipped: a hole it would have bound stays unresolved
+ * and its choice stays deferred, never falsely warned.
+ *
+ * Skipping is not the same as having nothing to say. Use `carriedRuleMapsDetailed`
+ * where the skip must be REPORTED — a diagnostic that drops part of the grammar and
+ * then returns a clean result is indistinguishable from one that verified it. */
+export function carriedRuleMaps(carried: ReadonlyArray<LinkableTable | IRPiece>): Array<Array<[string, Combinator<unknown>]>> {
+  return carriedRuleMapsDetailed(carried).maps
+}
+
+/** `carriedRuleMaps` plus the pieces it could NOT re-lower, named by namespace and
+ * rule count, so a caller can report exactly how much of the grammar went unseen. */
+export function carriedRuleMapsDetailed(
+  carried: ReadonlyArray<LinkableTable | IRPiece>,
+): { maps: Array<Array<[string, Combinator<unknown>]>>; opaque: Array<{ ns: string; ruleNames: string[] }> } {
+  const maps: Array<Array<[string, Combinator<unknown>]>> = []
+  const opaque: Array<{ ns: string; ruleNames: string[] }> = []
+  for (const p of carried) {
+    // A table artifact is recoverable far more often than a source one was: it carries
+    // IR, and failing that the live combinators. Ask for the map before declaring the
+    // piece opaque, or a perfectly analysable grammar is reported as unseen.
+    const rules = ruleMapOfCarried(p)
+    if (rules !== undefined) { maps.push(rules); continue }
+    // NAMED, not anonymous. `keys` is the artifact's rule-name list; the field this
+    // used to read (`ruleFns`) belonged to the source lowering, and reading a missing
+    // one degrades every opaque piece to `<artifact _lkN_>` — "reported, but uselessly",
+    // which is the exact failure this reporting exists to prevent.
+    opaque.push({ ns: p.ns, ruleNames: isIRPiece(p) ? [] : [...p.keys] })
+  }
+  return { maps, opaque }
+}
+
+/**
+ * Recover the override-winner COMBINATOR map behind a `compose()` result, plus the
+ * pieces that could not be recovered.
+ *
+ * A fused map holds rule functions, so any consumer that walks a combinator graph
+ * (gating analysis, the spec/EBNF/railroad model) cannot read it directly. The graph
+ * is not lost, though — `compose()` retains re-lowerable IR — so this is the single
+ * shared recovery both consumers use. Sharing it is the point: two copies of this
+ * logic is how one walker gets fixed and the other silently keeps failing.
+ *
+ * Returns `undefined` when `grammar` is not a composed result.
+ */
+export function recoverComposedRules(
+  grammar: Record<string, unknown>,
+): { rules: Map<string, Combinator<unknown>>; opaque: Array<{ ns: string; ruleNames: string[] }> } | undefined {
+  const carried = composedPiecesOf(grammar)
+  if (carried === undefined) return undefined
+  const { maps, opaque } = carriedRuleMapsDetailed(carried)
+  const rules = new Map<string, Combinator<unknown>>()
+  // Later wins, matching the linker's own fuse semantics. An accessed-but-undefined
+  // `g.X` leaks in as an unresolved lazy — a REFERENCE, not a definition — and must
+  // never shadow the artifact that really defines X.
+  for (const map of maps) for (const [name, rule] of map) {
+    if (rule._def.tag === 'lazy') { try { rule._def.thunk() } catch { continue } }
+    rules.set(name, rule)
+  }
+  return { rules, opaque }
+}
+
+function coverageRulesOf(carried: Array<LinkableTable | IRPiece>): Record<string, Combinator<unknown>> | undefined {
+  const winners: Record<string, Combinator<unknown>> = {}
+  for (const piece of carried) {
+    if (!isIRPiece(piece)) return undefined
+    const map = evalRuleMapIR(piece.ir)
+    for (const [name, rule] of map) {
+      // An accessed-but-undefined `g.Name` is an external reference, never a
+      // rule definition. Match compose's IR filtering rule exactly.
+      if (rule._def.tag === 'lazy') {
+        try { rule._def.thunk() } catch { continue }
+      }
+      winners[name] = rule
+    }
+  }
+  return winners
+}
+
+/** Return the final override-winner combinator map carried by runtime
+ * `compose()`, or `undefined` when a precompiled opaque artifact participated.
+ * This is intentionally internal: callers must not treat it as a parser API. */
+export function composedCoverageRules(grammar: Record<string, unknown>): Record<string, Combinator<unknown>> | undefined {
+  return (grammar as Record<symbol, unknown>)[COMPOSED_COVERAGE_RULES] as Record<string, Combinator<unknown>> | undefined
+}
+
+/** Flatten one `compose()` item to its pieces: a prior composed result → its
+ * carried list; an artifact → itself; a grammar (`rules()` map) → linkable-ified. */
+function nextComposeNs(used: Set<string>): string {
+  let ns: string
+  do { ns = `_lk${_nsCounter++}_` } while (used.has(ns))
+  used.add(ns)
+  return ns
+}
+
+/** Flatten one `compose()` item to its RE-LOWERABLE carried items — the form stored
+ * on the composed result so it can be composed AGAIN under a NEW composing trivia.
+ * A grammar (`rules()` map) is carried as compact IR (`{ns, ir}`), NOT baked source,
+ * so a later `compose([thisResult, delta])` re-lowers it with the delta's trivia
+ * (multi-level composing-wins). A prior composed result contributes its OWN carried
+ * items (already IR); a pre-compiled artifact has no source, so it stays baked. */
+function itemCarried(
+  item: LinkableTable | Record<string, unknown>,
+  used: Set<string>,
+  trivia?: Combinator<unknown>,
+  // Only reaches the non-serializable fallback below, where the grammar is baked
+  // immediately instead of carried as re-lowerable IR.
+  hostMode?: HostMode,
+): Array<LinkableTable | IRPiece> {
+  const carried = (item as Record<symbol, unknown>)[COMPOSED_PIECES]
+  // A prior composed result (runtime or macro-compiled): its carried list is already
+  // re-lowerable (IR pieces, plus any pre-compiled artifacts). Pass it through so THIS
+  // compose re-lowers it under its own composing trivia. Reserve its namespaces so a
+  // sibling grammar map can't collide with them.
+  if (Array.isArray(carried)) {
+    const items = carried as Array<LinkableTable | IRPiece>
+    for (const p of items) used.add(p.ns)
+    return items
+  }
+  // A pre-compiled artifact (`linkable()`): a table piece. It ALWAYS carries its IR,
+  // which is what makes table-to-table composition a rule-map merge rather than a
+  // relocation of two encoded programs — so unlike a source artifact it stays
+  // re-lowerable under a new composing trivia.
+  if (isLinkableTable(item)) {
+    used.add(item.ns)
+    return [item]
+  }
+  // A grammar (`rules()` map): carry it as compact IR so a later compose re-lowers it
+  // under ITS trivia. Unserializable → bake now with this compose's trivia (can't
+  // re-lower later; acceptable fallback, mirrors the macro's full-pieces fallback).
+  const map = item as Record<string, Combinator<unknown>>
+  const ns = nextComposeNs(used)
+  // Drop EXTERNAL entries first (same filter as compileLinkable): a `rules()` cache
+  // also holds every ACCESSED-but-undefined `g.X` as an unresolved-lazy entry. Left in,
+  // serializeRuleMap would emit `X: g["X"]` — a self-referential rule that shadows the
+  // sibling artifact defining X and recurses forever. They resolve by name at fuse time.
+  const entries = Object.entries(map).filter(([, val]) => {
+    const d = val._def
+    if (d.tag !== 'lazy') return true
+    try { d.thunk(); return true } catch { return false }
+  })
+  // Carry this grammar's ambient `scanSkip` (per-piece — opaque units are
+  // dialect-specific, NOT composing-wins) into the IR so a re-lower stamps
+  // `grammarScanSkip` back on. `linkable()`'s fallback reads it off `_meta` directly.
+  const scanSkip = entries
+    .map(([, val]) => (val._meta as { grammarScanSkip?: Combinator<unknown>[] }).grammarScanSkip)
+    .find(Boolean)
+  const ir = serializeRuleMap(entries, scanSkip)
+  return ir ? [{ ns, ir }] : [linkable(map, ns, trivia, hostMode)]
+}
+
+/** The composed grammar's ambient trivia = the LAST composed item that declares a
+ * grammar-level trivia (via `rules({ trivia }, …)`, which tags `grammarTrivia` on its
+ * rules). Outermost wins: the composing grammar's trivia applies to every fused rule,
+ * including those inherited from a base — so e.g. an SCSS `rw` (which extends Less's)
+ * governs the inherited Less/CSS rules too. `parser`/`noTrivia` still override locally. */
+function composingTriviaOf(items: Array<LinkableTable | Record<string, unknown>>): Combinator<unknown> | undefined {
+  for (let i = items.length - 1; i >= 0; i--) {
+    const item = items[i] as Record<string, unknown> | undefined
+    if (!item || isLinkableTable(item)) continue
+    // A COMPOSED item states its trivia on the stamp rather than on its values (its
+    // rules live in carried IR, which does not carry `_meta`). Skipping such an item
+    // entirely — as this did — loses the trivia of every grammar that reached this
+    // compose through a PRIOR compose.
+    const stamped = (item as Record<symbol, unknown>)[COMPOSED_TRIVIA] as Combinator<unknown> | undefined
+    if (stamped) return stamped
+    if ((item as Record<symbol, unknown>)[COMPOSED_PIECES]) continue
+    for (const v of Object.values(item)) {
+      const t = (v as Combinator<unknown> | undefined)?._meta?.grammarTrivia
+      if (t) return t
+    }
+  }
+  return undefined
+}
+
+export function compose(
+  items: Array<LinkableTable | Record<string, unknown>>,
+  /**
+   * Compile-time host mode for the fused artifact, same meaning as
+   * `compile(g, { hostMode })`. Omit (or `'ast'`) for the eval driver — the fused rules
+   * build through the grammar's own `build` callbacks and carry no positioned-CST
+   * branch. Pass `'cst'` to fuse a SECOND artifact from the same pieces for the linter /
+   * IDE / language-service driver. Two compilations of one grammar, decided here, rather
+   * than one artifact deciding per node on every parse.
+   */
+  opts?: { hostMode?: HostMode },
+): Record<string, FusedRule> {
+  if (items.some(item => (item as Record<symbol, unknown>)[LEAF_COMPOSED] === true)) {
+    throw new Error('compose: a composeLeaf() result is terminal and cannot be composed again')
+  }
+  const used = new Set<string>()
+  // The composed grammar's ambient trivia comes from the composing grammar itself —
+  // whatever the last piece declared via rules({ trivia }, …). No separate option:
+  // the trivia rides with the grammar that declared it.
+  const trivia = composingTriviaOf(items)
+  // Carried items are RE-LOWERABLE (IR); materialize them ONCE with this compose's
+  // trivia for the now-fuse, but STORE the un-materialized carried list so a later
+  // compose can re-lower it under a different trivia (multi-level composing-wins).
+  const carried = items.flatMap(item => itemCarried(item, used, trivia, opts?.hostMode))
+  const map = fuseCarried(carried, trivia, opts?.hostMode)
+  Object.defineProperty(map, COMPOSED_PIECES, { value: carried, enumerable: false })
+  if (trivia) Object.defineProperty(map, COMPOSED_TRIVIA, { value: trivia, enumerable: false })
+  const coverageRules = coverageRulesOf(carried)
+  if (coverageRules) Object.defineProperty(map, COMPOSED_COVERAGE_RULES, { value: coverageRules, enumerable: false })
+  return map
+}
+
+/**
+ * Compose a terminal grammar. This is for a leaf parser that overlays local
+ * semantic reductions on reusable recognition rules.
+ *
+ * Under the macro this lowers to STATIC fused source (functions), exactly like
+ * `compose()`. It is still macro-only as a *compiled* artifact: without macro
+ * lowering there is no safe way to keep lexical builders out of carried IR, so it
+ * never falls back to runtime CODEGEN composition.
+ *
+ * Called at runtime (no macro) it returns the INTERPRETED fuse of the same items —
+ * a combinator map, not a map of compiled functions (`fuseInterpreted`), fused lazily
+ * per rule name.
+ *
+ * THE RETURN TYPE IS `Runnable`, NOT `FusedRule`, BECAUSE BOTH PATHS ARE REAL. A macro
+ * build yields fused functions; an un-macro'd call yields combinators. `Runnable` is
+ * already the library's name for "either of those" — it is what `run()` and
+ * `parseDoc()` take — so the declared type is TRUE on both paths and a caller needs no
+ * narrowing to use the result. This used to declare `Record<string, FusedRule>` and
+ * launder the runtime path through an `as unknown as`, which let a caller hold a
+ * combinator map while the type promised compiled functions.
+ *
+ * Do NOT "fix" this by deleting the runtime path. It is load-bearing: the `bench/jess`
+ * harness family and two differential-gate legs (`emit-identity-one`,
+ * `scan-shape-oracle-one`) import un-macro'd grammar modules and depend on this lazy
+ * interpreted fuse, one dialect per process. Whether an un-macro'd `composeLeaf()`
+ * should exist at all is a separate, open owner question — but while the gates depend
+ * on it, it exists, and the type says so.
+ */
+export function composeLeaf(
+  items: Array<LinkableTable | Record<string, unknown>>,
+): Record<string, Runnable> {
+  const pieces = items.flatMap(interpretedPieces)
+  let fused: Record<string, Combinator<unknown>> | undefined
+  const map: Record<string, unknown> = {}
+  // LAZY on purpose. A grammar module typically builds SEVERAL leaf grammars over
+  // one shared recognition piece (`cssGrammar`, `cssLineGrammar`, `cssCstGrammar`,
+  // …). An interpreted fuse binds that shared piece IN PLACE, so only one of them
+  // can exist at a time — fusing all of them at import would make merely importing
+  // the module throw. Fusing on first ACCESS means the grammar you actually use
+  // works, and reaching for a second, conflicting one fails loudly at that point.
+  // (`trackLines`/`hostMode` are compile-time distinctions; the interpreter decides
+  // both per parse, so those variants are the same interpreted grammar anyway.)
+  for (const name of ruleNamesOf(pieces)) {
+    Object.defineProperty(map, name, {
+      enumerable: true,
+      configurable: true,
+      get: () => (fused ??= fusePieces(pieces))[name],
+    })
+  }
+  Object.defineProperty(map, LEAF_COMPOSED, { value: true, enumerable: false })
+  Object.defineProperty(map, INTERPRETED_PIECES, {
+    value: pieces.filter(p => p.plain).map(p => p.entries),
+    enumerable: false,
+  })
+  return map as Record<string, Runnable>
+}
+
+/* ── Interpreted fuse ─────────────────────────────────────────────────────────
+ *
+ * `compose()` fuses by CODEGEN: every piece is compiled to `_r_<Name>` functions
+ * dropped into one scope, so a reference resolves by NAME and an override reroutes
+ * the base piece's own calls (open recursion). None of that exists interpreted —
+ * the interpreter runs the combinator graph, and a cross-piece reference is an
+ * ordinary `ref()` placeholder that nobody ever `.define()`d. That is why a
+ * composed grammar could not be run interpreted at all, and why every diagnostic
+ * that must NOT reach codegen (profiling, gating analysis, coverage) had to be
+ * hand-fused in throwaway scripts.
+ *
+ * The interpreted fuse binds those placeholders directly, with the SAME semantics
+ * the compiled fuse gets from name resolution:
+ *   - later piece wins per rule name (matching the compiled merge);
+ *   - an override REPOINTS the slot every call site already holds, so a base
+ *     piece's internal calls reroute too (open recursion);
+ *   - the composing grammar's trivia governs every fused rule (`composingTriviaOf`);
+ *   - a referenced-but-undefined rule is a fuse-time error, not a parse-time one.
+ *
+ * It is MUTATING by construction: a hole is a shared object, and binding it is the
+ * only way its call sites can see the answer. `repointRef` therefore records what
+ * it changed and refuses a CONFLICTING second bind, so two different fusions over
+ * one shared piece fail loudly instead of silently rewriting each other's parser.
+ * ───────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * A rule slot produced by `ref()` — what `rules()` stores for every rule that is
+ * referenced by name, and for every `g.X` hole a piece leaves for another piece to
+ * fill. `parse`/`_def.thunk` are OWN properties of that object, which is what lets
+ * the interpreted fuse repoint it in place.
+ */
+type RefSlot = Combinator<unknown> & {
+  _def: { tag: 'lazy'; thunk: () => Combinator<unknown> }
+  define(p: Combinator<unknown>): void
+  parse(input: string, pos: number, ctx: ParseContext): ParseResult<unknown>
+}
+
+function isRefSlot(c: Combinator<unknown>): c is RefSlot {
+  return c._def.tag === 'lazy' && typeof (c as unknown as { define?: unknown }).define === 'function'
+}
+
+/** What a slot resolved to BEFORE any interpreted fuse touched it (`null` = it was
+ * an unbound cross-piece hole). Recorded on first repoint so a LATER fuse computes
+ * its winner from the grammar as authored, never from another fusion's binding. */
+const FUSE_ORIGINAL = Symbol.for('parseman.interpretedFuseOriginal')
+/** What an interpreted fuse repointed this slot at. */
+const FUSE_TARGET = Symbol.for('parseman.interpretedFuseTarget')
+/** The source rule maps behind a `fuseInterpreted()` result, so it can be fused
+ * again — the interpreted mirror of `COMPOSED_PIECES`. */
+const INTERPRETED_PIECES = Symbol.for('parseman.interpretedPieces')
+
+/** Whether `map` is an interpreted fuse (a combinator map) rather than a compiled
+ * `compose()` result (a map of fused functions). INTERNAL — not re-exported from
+ * `src/index.ts`. A consumer never has to ask this question: what it holds is
+ * whatever the macro built. Diagnostics that fuse interpreted on purpose do. */
+export function isInterpretedFuse(map: object): boolean {
+  return Array.isArray((map as Record<symbol, unknown>)[INTERPRETED_PIECES])
+}
+
+type NamedEntries = ReadonlyArray<[string, Combinator<unknown>]>
+/** `plain` = the item was an authored `rules()` map. Only plain maps declare the
+ * composing trivia, mirroring `composingTriviaOf`, which skips artifacts and prior
+ * composed results for exactly the same reason: their trivia was already applied. */
+type FusePiece = { entries: NamedEntries; plain: boolean }
+
+/** The rule a map entry DEFINES, or `undefined` when it is an external reference
+ * (an accessed-but-undefined `g.X`). Same local-vs-external test `compileLinkable`
+ * and `itemCarried` apply, so the two fuses agree on what a piece contributes. */
+function definitionOf(entry: Combinator<unknown>): Combinator<unknown> | undefined {
+  if (isRefSlot(entry)) {
+    const original = (entry as unknown as Record<symbol, unknown>)[FUSE_ORIGINAL]
+    if (original !== undefined) return (original as Combinator<unknown> | null) ?? undefined
+    try { return entry._def.thunk() } catch { return undefined }
+  }
+  if (entry._def.tag === 'lazy') {
+    try { (entry._def as { thunk: () => Combinator<unknown> }).thunk() } catch { return undefined }
+  }
+  return entry
+}
+
+/** Point `slot` at `target`, updating every call site that holds it. Mirrors
+ * `ref().define()`'s metadata propagation; refuses to overwrite a binding a
+ * DIFFERENT fusion already made (see the mutation note above). */
+function repointRef(slot: RefSlot, target: Combinator<unknown>, name: string): void {
+  const tagged = slot as unknown as Record<symbol, unknown>
+  const bound = tagged[FUSE_TARGET] as Combinator<unknown> | undefined
+  const original = FUSE_ORIGINAL in tagged
+    ? tagged[FUSE_ORIGINAL] as Combinator<unknown> | null
+    : (() => { try { return slot._def.thunk() } catch { return null } })()
+  if ((bound ?? original) === target) return
+  if (bound !== undefined) {
+    throw new Error(
+      `fuseInterpreted: rule "${name}" is already bound by a DIFFERENT interpreted fusion of the same grammar piece. `
+      + `An interpreted fuse binds the shared placeholder objects in place, so two fusions cannot share a piece — `
+      + `build a fresh instance of the piece (call its rules() factory again, or import the module under a distinct specifier) for the second fusion.`,
+    )
+  }
+  if (!(FUSE_ORIGINAL in tagged)) Object.defineProperty(slot, FUSE_ORIGINAL, { value: original, enumerable: false })
+  Object.defineProperty(slot, FUSE_TARGET, { value: target, enumerable: false })
+  slot._def.thunk = () => target
+  slot.parse = (input, pos, ctx) => target.parse(input, pos, ctx)
+  const meta = slot._meta
+  meta.firstSet = target._meta.firstSet
+  meta.canMatchNewline = target._meta.canMatchNewline
+  meta.isTrivia = target._meta.isTrivia
+  if (target._meta.triviaKindLabels !== undefined) meta.triviaKindLabels = target._meta.triviaKindLabels
+  else (meta as { triviaKindLabels: readonly string[] | undefined }).triviaKindLabels = undefined
+  if (target._meta.disjoint !== undefined) meta.disjoint = target._meta.disjoint
+  else (meta as { disjoint: boolean | undefined }).disjoint = undefined
+}
+
+/** Flatten one `fuseInterpreted()` item to the rule maps it contributes, in order. */
+function interpretedPieces(item: LinkableTable | Record<string, unknown>): FusePiece[] {
+  const fused = (item as Record<symbol, unknown>)[INTERPRETED_PIECES]
+  if (Array.isArray(fused)) return (fused as NamedEntries[]).map(entries => ({ entries, plain: false }))
+  const carried = composedPiecesOf(item as Record<string, unknown>)
+  if (carried !== undefined) {
+    // A compiled `compose()` result. Its carried IR re-lowers to combinators, but a
+    // piece that arrived already COMPILED has no combinator graph at all — fusing
+    // around it would silently drop its rules, which is the one failure mode a
+    // diagnostic must never have.
+    const { maps, opaque } = carriedRuleMapsDetailed(carried)
+    if (opaque.length > 0) {
+      throw new Error(
+        `fuseInterpreted: cannot interpret a composed grammar containing precompiled artifact(s) `
+        + `${opaque.map(o => `"${o.ns}" (${o.ruleNames.length} rules)`).join(', ')} — they carry compiled functions, not a combinator graph. `
+        + `Pass the source grammars (the same items you passed to compose()) instead.`,
+      )
+    }
+    return maps.map(entries => ({ entries, plain: false }))
+  }
+  if (isLinkableTable(item)) {
+    // A table piece DOES carry its IR, so this is recoverable rather than fatal: hydrate
+    // the combinator graph back out of it and interpret that.
+    const rules = ruleMapOfCarried(item)
+    if (rules === undefined) {
+      throw new Error('fuseInterpreted: a precompiled linkable artifact with no carried IR has no combinator graph to interpret; pass the source grammar (a rules() map) instead')
+    }
+    return [{ entries: rules, plain: false }]
+  }
+  return [{ entries: Object.entries(item as Record<string, Combinator<unknown>>), plain: true }]
+}
+
+/**
+ * Materialize a composition as a RUNNABLE INTERPRETED rule map — the interpreted
+ * counterpart of `compose()`, with identical fuse semantics (later piece wins,
+ * override reroutes the base's own calls, composing trivia governs every rule).
+ * No codegen, no `new Function`, no macro build step: the result is a plain map of
+ * combinators that `run()` / `parseDoc()` accept exactly like a fused map.
+ *
+ * This is what diagnostics and profiling run against — they must stay in
+ * interpreted mode, and before this they could not see a composed grammar at all.
+ *
+ * Items are the SAME items `compose()`/`composeLeaf()` take: `rules()` maps
+ * (the intended input), a prior `fuseInterpreted()` result, or a runtime
+ * `compose()` result (re-lowered from its carried IR — note that carried IR cannot
+ * materialize direct `node()` builders, so prefer the source maps). A precompiled
+ * `linkable()` artifact is rejected: it has no combinator graph.
+ *
+ * MUTATION: binding a cross-piece hole rewrites the shared placeholder object every
+ * call site already holds — that IS how an override reaches a base piece's own
+ * calls. A second, DIFFERENT fusion over the same piece objects therefore throws
+ * rather than silently rewriting the first one's parser.
+ */
+export function fuseInterpreted(
+  items: Array<LinkableTable | Record<string, unknown>>,
+  opts?: { hostMode?: HostMode },
+): Record<string, Combinator<unknown>> {
+  return fusePieces(items.flatMap(interpretedPieces), opts)
+}
+
+/** The rule names a fusion of these pieces defines, in winner order — computable
+ * WITHOUT binding anything, which is what lets `composeLeaf()` expose its key set
+ * before it fuses. */
+function ruleNamesOf(pieces: FusePiece[]): string[] {
+  const names = new Set<string>()
+  for (const piece of pieces) {
+    for (const [name, value] of piece.entries) if (definitionOf(value) !== undefined) names.add(name)
+  }
+  return [...names]
+}
+
+function fusePieces(
+  pieces: FusePiece[],
+  opts?: { hostMode?: HostMode },
+): Record<string, Combinator<unknown>> {
+  // Composing-wins trivia, read exactly as `composingTriviaOf` reads it for compose():
+  // the LAST authored grammar that declared `rules({ trivia }, …)`.
+  let trivia: Combinator<unknown> | undefined
+  for (let i = pieces.length - 1; i >= 0 && trivia === undefined; i--) {
+    if (!pieces[i]!.plain) continue
+    for (const [, rule] of pieces[i]!.entries) {
+      const t = rule._meta.grammarTrivia
+      if (t) { trivia = t; break }
+    }
+  }
+
+  // Winner per rule name — later piece wins, matching `fuseRules`. The winner is the
+  // DEFINITION, never the slot holding it: a slot can be repointed, and a chain
+  // through one would make an override of X reroute into itself.
+  const winner = new Map<string, Combinator<unknown>>()
+  const entry = new Map<string, Combinator<unknown>>()
+  for (const piece of pieces) {
+    for (const [name, value] of piece.entries) {
+      const def = definitionOf(value)
+      if (def === undefined) continue
+      winner.set(name, def)
+      entry.set(name, value)
+    }
+  }
+
+  // Bind every hole (and repoint every overridden slot) before anything runs.
+  const missing = new Set<string>()
+  for (const piece of pieces) {
+    for (const [name, value] of piece.entries) {
+      if (!isRefSlot(value)) continue
+      const target = winner.get(name)
+      if (target === undefined) { missing.add(name); continue }
+      repointRef(value, target, name)
+    }
+  }
+  if (missing.size > 0) throw new Error(missingRuleMessage(pieces, missing))
+
+  const out: Record<string, Combinator<unknown>> = {}
+  for (const [name, value] of entry) {
+    out[name] = value
+    const meta = value._meta as {
+      isTrivia: boolean
+      grammarTrivia?: Combinator<unknown>
+      grammarHostMode?: HostMode
+    }
+    // A trivia rule must never carry the ambient trivia (it would recursively skip
+    // trivia within itself) — the same guard `compileLinkable` applies per rule.
+    if (trivia !== undefined && !meta.isTrivia) meta.grammarTrivia = trivia
+    // Host mode is PER PIECE, exactly as `compileLinkable` resolves it: an explicit
+    // option wins, otherwise the owning piece's own `rules({ hostMode })` stamp.
+    if (opts?.hostMode !== undefined && !meta.isTrivia) {
+      if (opts.hostMode === 'cst') meta.grammarHostMode = 'cst'
+      else (meta as { grammarHostMode: HostMode | undefined }).grammarHostMode = undefined
+    }
+  }
+  Object.defineProperty(out, INTERPRETED_PIECES, {
+    value: pieces.filter(p => p.plain).map(p => p.entries),
+    enumerable: false,
+  })
+  return out
+}
+
+/** Name-closure failure, reported the way the compiled fuse reports it: which rule
+ * referenced the missing name. Computed only on the error path. */
+function missingRuleMessage(pieces: FusePiece[], missing: Set<string>): string {
+  for (const piece of pieces) {
+    const deps = ruleDependencies(piece.entries.filter(([, v]) => definitionOf(v) !== undefined))
+    for (const [name, ds] of deps) {
+      for (const d of ds) if (missing.has(d)) return `fuseInterpreted: rule "${name}" references missing rule "${d}"`
+    }
+  }
+  return `fuseInterpreted: missing rule(s) ${[...missing].map(n => `"${n}"`).join(', ')}`
+}