parseman 0.46.0 → 0.47.1

package/src/table/cell.ts

@@ -0,0 +1,42 @@
+/**
+ * THE PROTOCOL THE THREE ENGINES SHARE — the failure sentinel and the
+ * end-position out-parameter.
+ *
+ * `exec.ts`, `assemble.ts` and `emit-assembly.ts` each ran a private copy of
+ * both: three `Symbol('pm.fail')` calls and three `let END = 0` closure slots.
+ * That was sound while an assembly picked ONE engine and ran it for the whole
+ * parse, which is what every shipped configuration does.
+ *
+ * It stops being sound the moment two engines are live in one parse. A piece
+ * from engine A returning A's `FAIL` to a caller in engine B is a VALUE to B —
+ * `!== FAIL` is true — so a failed match reads as a successful one carrying a
+ * symbol, and the parse continues from a position nobody wrote. Neither a type
+ * nor a test would catch it: the sentinels have the same description, and the
+ * three-way identity sweep only ever exercised one engine per process.
+ *
+ * So both halves move here:
+ *
+ * - `FAIL` is ONE symbol, module-level, imported by every engine. There is no
+ *   per-assembly variation possible in a sentinel, so there is no reason for it
+ *   to be per-assembly state.
+ * - `EndCell` is per-ASSEMBLY, not per-module. Two assemblies for two grammars
+ *   may be live in one process and must not share a slot; the engines *within*
+ *   one assembly must. `assemble()` mints one and hands it to whichever engines
+ *   that assembly builds.
+ *
+ * A one-property object rather than an `Int32Array`: the store is monomorphic
+ * either way, and `e` reads in emitted text as `EC.e`, which is the same shape
+ * the closure engine writes.
+ */
+
+/** The failure sentinel. ONE per process, shared by every engine. */
+export const FAIL: unique symbol = Symbol('pm.fail')
+export type Fail = typeof FAIL
+
+/**
+ * The end-position out-parameter — `_pfEnd` in emitted text, `END` in the
+ * closure walk and the driver. One per assembly.
+ */
+export type EndCell = { e: number }
+
+export const newEndCell = (): EndCell => ({ e: 0 })

package/src/table/child-slots.ts

@@ -0,0 +1,113 @@
+import {
+  OP_ADJ, OP_ARMGATE, OP_ATTEMPT, OP_CHOICE, OP_COV, OP_DISPATCH, OP_EMPTY, OP_EXPECT,
+  OP_FIELD, OP_GATE, OP_GREEDY, OP_GUARD, OP_LABEL, OP_LEAF, OP_LIT, OP_LIT_CI,
+  OP_LIT_CI_TRACK, OP_LIT_TRACK, OP_LIVE, OP_NODE, OP_NODE_TRACK, OP_NOT, OP_OPT,
+  OP_PEEK, OP_REJECT, OP_REP, OP_REPV, OP_ROUTED, OP_RULE, OP_RX, OP_RX_TRACK, OP_SCAN,
+  OP_SCOPE, OP_SCOPE_CAP, OP_SCOPE_PLAIN, OP_SEQ, OP_SEQV, OP_SEQX, OP_TOKEN, OP_WITHCTX, OP_XFORM,
+} from './ops.ts'
+
+/**
+ * THE EDGE TABLE. Which operand slots of an instruction are CHILD instructions.
+ *
+ * This is one fact about the operand layout, and it was written twice: once in
+ * `site-labels.ts` over the 35 opcodes `emit-assembly.ts` lowers, once fused into
+ * `inspect.ts`'s `reachableIps` traversal over all 40. The two agreed slot-for-slot
+ * on every opcode both covered — which is the problem, not the reassurance. Adding
+ * an opcode meant editing two switches in two files, and NOTHING failed if you
+ * edited one. `site-labels.ts`'s own header names that failure mode, then guards
+ * only against it happening WITHIN that file.
+ *
+ * The subset was never load-bearing. The five opcodes it omitted — COV, GREEDY,
+ * REJECT, ARMGATE, WITHCTX — are exactly the five `emit-assembly.ts` has no case
+ * for, so any program containing one throws `Unemittable` from the default arm and
+ * the whole assembly falls back to closures. Walking into their subtrees can
+ * therefore only affect a result that is about to be discarded. (Verified: none of
+ * the five is so much as imported by `emit-assembly.ts`. Its one consumer of these
+ * edges, the `fd`/`er` sink census, is computed before the lowering that throws.)
+ *
+ * `code` is `ArrayLike<number>` because the two callers hold different
+ * representations of the same stream — `TableProgram.code` is a `readonly number[]`,
+ * `ResolvedTable.code` is an `Int32Array`.
+ *
+ * Returns false for an opcode this table does not know, so each caller keeps its own
+ * answer to that: `inspect.ts` throws (a program it cannot decode is a bug it must
+ * report), `site-labels.ts` ignores it (an unwalked site resolves to `TOP` via
+ * `labelAt`, and the enclosing assembly is unemittable anyway).
+ */
+export function childSlots(code: ArrayLike<number>, ip: number, out: number[]): boolean {
+  switch (code[ip]) {
+    // ZERO-WIDTH / TERMINAL ROWS — no successor. `OP_GUARD` and `OP_ADJ` are both
+    // childless tests. `OP_LIVE` holds a hand-written combinator in `prog.fns`; its
+    // structure is a closure, so there is no successor row to reach.
+    case OP_LIT: case OP_RX: case OP_LIT_TRACK: case OP_RX_TRACK: case OP_EMPTY:
+    case OP_SCAN: case OP_LIT_CI: case OP_LIT_CI_TRACK:
+    case OP_GUARD: case OP_ADJ: case OP_LIVE:
+      return true
+
+    // Single child at `ip + 1`. `OP_COV` is a wrapper on the same footing as the
+    // rest — a coverage-encoded program is a program, and omitting it made
+    // `opHistogram` throw on every table the coverage build produces.
+    case OP_RULE: case OP_OPT: case OP_NOT: case OP_PEEK: case OP_EXPECT:
+    case OP_TOKEN: case OP_ATTEMPT: case OP_LABEL: case OP_COV: case OP_REJECT:
+      out.push(code[ip + 1]!)
+      return true
+
+    // Single child at `ip + 2`.
+    case OP_GATE: case OP_SCOPE: case OP_SCOPE_CAP: case OP_SCOPE_PLAIN: case OP_WITHCTX: case OP_XFORM:
+    case OP_NODE: case OP_NODE_TRACK: case OP_FIELD: case OP_LEAF: case OP_ARMGATE:
+      out.push(code[ip + 2]!)
+      return true
+
+    // `ROUTED fallback` — the operand is an offset or −1. The routed token itself is
+    // data the enclosing `dispatch()` already consumed, so the only edge is the
+    // fallback.
+    case OP_ROUTED:
+      if (code[ip + 1]! >= 0) out.push(code[ip + 1]!)
+      return true
+
+    // `DISPATCH sel d other otherRouted n a1 … an` — the SELECTOR is a child on
+    // exactly the same footing as the arms: it runs inside whatever node and scope
+    // this site sits in.
+    case OP_DISPATCH: {
+      out.push(code[ip + 1]!)
+      if (code[ip + 3]! >= 0) out.push(code[ip + 3]!)
+      const n = code[ip + 5]!
+      for (let i = 0; i < n; i++) out.push(code[ip + 6 + i]!)
+      return true
+    }
+
+    case OP_SEQ: case OP_SEQV: {
+      const n = code[ip + 1]!
+      for (let i = 0; i < n; i++) out.push(code[ip + 2 + i]!)
+      return true
+    }
+
+    case OP_SEQX: {
+      const n = code[ip + 2]!
+      for (let i = 0; i < n; i++) out.push(code[ip + 3 + i]!)
+      return true
+    }
+
+    case OP_CHOICE: {
+      const n = code[ip + 2]!
+      for (let i = 0; i < n; i++) out.push(code[ip + 4 + i]!)
+      return true
+    }
+
+    // Arms are stride-2 from `ip + 4` — the gate word sits beside each arm offset.
+    case OP_GREEDY: {
+      out.push(code[ip + 1]!)
+      const n = code[ip + 2]!
+      for (let i = 0; i < n; i++) out.push(code[ip + 4 + 2 * i]!)
+      return true
+    }
+
+    case OP_REP: case OP_REPV:
+      out.push(code[ip + 1]!)
+      if (code[ip + 4]! >= 0) out.push(code[ip + 4]!)
+      return true
+
+    default:
+      return false
+  }
+}

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

@@ -0,0 +1,336 @@
+import type { Combinator } from '../types.ts'
+import { hasDirectBuildDef } from '../analysis/commitment.ts'
+import type { HostMode } from '../cst/host-mode.ts'
+import { collectGrammarReflection, type GrammarReflection } from '../cst/reflection.ts'
+import { encodeTableProgram, type TableSettings } from './encode.ts'
+import { emitTableExpression } from './emit.ts'
+import { tableRules } from './assemble.ts'
+import { closureArtifact } from './program.ts'
+import type { TableProgram, TableRule } from './program.ts'
+import { buildGrammarPlan, type GrammarCoverageDefinition } from '../compiler/grammar-coverage-ids.ts'
+import { runDuplicationDiagnosticRules, type DuplicationOption } from './duplication-hook.ts'
+
+/**
+ * `compileRuleMap()` FOR THE TABLE LOWERING — the counterpart that did not exist.
+ *
+ * `compile` covered `compile()`, the SINGLE-ROOT entry point, which the
+ * plugin uses only for standalone combinators (`plugin/index.ts:1693`, `:1870`).
+ * The main path — every `rules()` grammar — goes through `compileRuleMap`, and
+ * with no table counterpart there was nothing for the macro build to point at.
+ * This is that function, and it is the EASY direction: `encodeTable` takes a
+ * named rule map natively, so nothing here adapts a shape. `compile` is the
+ * one that adapts (it wraps a root as `{ Entry: root }`).
+ *
+ * ── THE CONTRACT IT MATCHES ──────────────────────────────────────────────────
+ * `compileRuleMap` returns ONE `replacement` string: a self-contained expression
+ * that the plugin splices over the whole `rules(factory)` call-expression
+ * (`plugin/index.ts:1753`, and as an initialiser at `:1941`), evaluating ONCE to
+ * the `{ name: fn, … }` map. `keys` is the entry list, for the caller to check
+ * against the source's own keys. `hostMode` / `hostBranchElided` are what the
+ * macro stamps the emitted map with. `reflection` is per-grammar CST node
+ * reflection. It returns `null`, all-or-nothing, when the map cannot be inlined.
+ *
+ * Every one of those is reproduced here, with ONE stated divergence, the same
+ * one `compile` documents: the expression references `tableRules` and is
+ * therefore NOT self-contained. That reference is the entire reason a table
+ * artifact is small; inlining the driver per grammar rebuilds exactly the size
+ * this lowering exists to remove. The consumer owns the import.
+ *
+ * ── WHY `emitTableModule` WAS NOT ENOUGH ─────────────────────────────────────
+ * It emits a whole rule map as one module — `import` line, `export const` — and
+ * the plugin has no module to write; it has an expression slot inside an
+ * existing file. `emitTableExpression` was the right emitter and needed one
+ * thing: `entry: null`, meaning "the map itself" rather than one rule out of it.
+ * That is a two-line change to an existing emitter, not a new one.
+ */
+export type TableRuleMapOptions = {
+  /** Grammar-level ambient trivia, as `rules({ trivia }, …)` declares it. */
+  readonly trivia?: Combinator<unknown>
+  /** Grammar-level ambient scan-skip, as `rules({ scanSkip }, …)` declares it. */
+  readonly scanSkip?: Combinator<unknown>[]
+  readonly recovery?: boolean
+  readonly hostMode?: HostMode
+  readonly trackLines?: boolean
+  /**
+   * GRAMMAR-COVERAGE COUNTERS. This is the MACRO's path — `plugin/index.ts` passes
+   * `coverage: grammarCoverage` here for every `rules()` grammar — so this is what
+   * makes `{ grammarCoverage: true }` a working build under the table lowering.
+   *
+   * COUNTERS ONLY, per the owner ruling recorded in `notes/RELEASE-0.48-TARGET.md`
+   * §1; `_grammarTrace` parity is 0.48 work. The plugin's coverage path needs the
+   * DEFINITIONS STAMP and the HITS, and both are here.
+   */
+  readonly coverage?: boolean
+  /** Identifier the emitted expression expects `tableRules` to be bound to. */
+  readonly runtimeRef?: string
+  /**
+   * Reducer sources in `prog.fns` order, for a caller that holds them OUT OF
+   * BAND — the same escape `compile(combinator, mapFnSources?)` provides.
+   *
+   * The encoder captures a source per callback from the def (`fnSrc` /
+   * `buildSrc` / `predSrc` / `gateSrcs`), which the macro evaluator sets and a
+   * runtime-built combinator does not have. Supplying them here is what lets a
+   * grammar constructed at runtime still PRINT; it does not override captured
+   * ones, it fills in for a pool that has none.
+   */
+  readonly fnSources?: readonly string[]
+  /**
+   * WHY THIS REFUSED, filled in on the `null` return.
+   *
+   * `null` means "leave this grammar interpreted", which is ~79 ms against ~14 ms
+   * on `benchmark.less` — a ~5x regression that produces no test failure and no
+   * warning content beyond "couldn't be inlined". The reasons exist inside the
+   * encoder (`prog.runtimeOnly`) and simply had no way out; this is that way out,
+   * so the plugin's warning can name the construct instead of the outcome.
+   *
+   * An out-parameter rather than a changed return type: every existing caller
+   * checks for `null` and that contract is unchanged.
+   */
+  readonly refusals?: string[]
+  /**
+   * The structural duplication diagnostic. Ran inside the source lowering; it runs
+   * here for the same reason, so a build that asked for it keeps getting it.
+   */
+  readonly duplication?: DuplicationOption
+}
+
+export type CompiledRuleMapTable = {
+  /** Every entry this saw, in order — same use as `compileRuleMap`'s `keys`. */
+  keys: string[]
+  /** The expression that replaces the whole `rules(factory)` call. */
+  replacement: string
+  /** Re-emit the same table call with construction-time artifact metadata. */
+  replacementWithMetadata(metadataSource: string): string
+  hostMode: HostMode
+  hostBranchElided: boolean
+  reflection: GrammarReflection
+  /**
+   * The RUNNABLE map, which the source lowering has no counterpart for — it
+   * hands back text and nothing else, because its artifact only exists once the
+   * emitted source is evaluated. A table exists as data before it is printed, so
+   * the same call that produces the replacement can also hand back the parser.
+   * That is what makes a differential against the interpreter possible without
+   * `eval`, and it is why the table-vs-interpreter test can compare `expected`
+   * sets rather than only accept/reject.
+   */
+  rules: Record<string, TableRule>
+  /** The encoded program, for a caller that wants to fold or inspect it. */
+  prog: TableProgram
+  /**
+   * The coverage DENOMINATOR — every id this map can hit — present only under
+   * `{ coverage: true }`. Same field and same meaning as `compileRuleMap`'s, so
+   * the plugin's stamp site needs no branch on which lowering produced it.
+   */
+  coverageDefinitions?: readonly GrammarCoverageDefinition[]
+}
+
+/**
+ * The host mode this map was lowered for, resolved the way `compileRuleMap`
+ * resolves it: an explicit option, else a `grammarHostMode` stamp left on the
+ * rules by `rules({ hostMode }, …)`. The stamp is the only channel a macro build
+ * has, since it passes no compile options.
+ */
+function resolveHostMode(
+  ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>,
+  explicit: HostMode | undefined,
+): HostMode {
+  return explicit
+    ?? ruleMap.map(([, r]) => r._meta.grammarHostMode).find(Boolean)
+    ?? 'ast'
+}
+
+function resolveTrackLines(
+  ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>,
+  explicit: boolean | undefined,
+): boolean {
+  return explicit === true || ruleMap.some(([, r]) => r._meta.grammarTrackLines === true)
+}
+
+/**
+ * Apply grammar-level trivia / scan-skip passed as OPTIONS to ENCODING-LOCAL
+ * rule wrappers.
+ *
+ * `rules({ trivia }, …)` stamps `_meta.grammarTrivia` on every non-trivia rule
+ * (combinators/parser.ts:203) and `encodeTable` reads it from there, per rule.
+ * A caller that instead threads the declaration as an option — which the macro
+ * does, because it re-evaluates the factory itself — must land it in the same
+ * place or the whole grammar encodes with NO ambient trivia and every
+ * whitespace-bearing input fails identically in every engine, which makes an
+ * identity check agree while proving nothing.
+ *
+ * Only fills a GAP: a rule that already carries its own stamp keeps it, so a
+ * `composeLeaf` map whose pieces legitimately disagree is not flattened.
+ *
+ * The wrappers are load-bearing. This used to write directly to `rule._meta`,
+ * which made a compile option part of the caller's grammar forever: compile the
+ * same map once with whitespace trivia and a later compile with comma trivia
+ * would still use whitespace. Encoding is synchronous, but a copy is safer than
+ * a save/restore mutation (including on the exception path), and keeps compiler
+ * options out of long-lived grammar metadata altogether.
+ */
+function withAmbient(
+  ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>,
+  opts: TableRuleMapOptions,
+): ReadonlyArray<readonly [string, Combinator<unknown>]> {
+  if (opts.trivia === undefined && opts.scanSkip === undefined) return ruleMap
+
+  const wrappers = new Map<Combinator<unknown>, Combinator<unknown>>()
+  return ruleMap.map(([name, rule]) => {
+    if (rule._meta.isTrivia) return [name, rule] as const
+    const addTrivia = opts.trivia !== undefined && rule._meta.grammarTrivia === undefined
+    const addScanSkip = opts.scanSkip !== undefined && rule._meta.grammarScanSkip === undefined
+    if (!addTrivia && !addScanSkip) return [name, rule] as const
+
+    let wrapped = wrappers.get(rule)
+    if (wrapped === undefined) {
+      wrapped = {
+        ...rule,
+        _meta: {
+          ...rule._meta,
+          ...(addTrivia ? { grammarTrivia: opts.trivia } : {}),
+          ...(addScanSkip ? { grammarScanSkip: opts.scanSkip } : {}),
+        },
+      }
+      wrappers.set(rule, wrapped)
+    }
+    return [name, wrapped] as const
+  })
+}
+
+/**
+ * ENCODE FOR RUNNING, with no printability requirement.
+ *
+ * `compileRuleMap` refuses a map whose author callbacks have no captured SOURCE,
+ * because PRINTING one would emit `() => {}` and the parse would return the wrong tree.
+ * That gate is right for the macro, which prints, and wrong for every caller that only
+ * ever RUNS the result: a grammar built at runtime has live callbacks and no sources by
+ * construction, and `encodeTableProgram` parks the live function in the pool where the
+ * driver calls it perfectly well.
+ *
+ * Conflating the two is the single defect this project has now hit three times — a
+ * runtime `compose()`, `linkable()`, and the fuse — each presenting as "this grammar
+ * cannot be compiled" for a grammar that runs. The split lives here, once, so the next
+ * caller inherits the right answer instead of rediscovering it.
+ */
+export function compileRuleMapRunnable(
+  ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>,
+  opts: TableRuleMapOptions = {},
+): Omit<CompiledRuleMapTable, 'replacement' | 'replacementWithMetadata'> | null {
+  const encoded = encodeForRun(ruleMap, opts)
+  if (encoded === null) return null
+  const { prog, hostMode, plan } = encoded
+  const artifact = closureArtifact(prog)
+  return {
+    keys: ruleMap.map(([key]) => key),
+    hostMode,
+    hostBranchElided: hostMode === 'ast' && ruleMap.some(([, rule]) => hasDirectBuildDef(rule)),
+    reflection: collectGrammarReflection(ruleMap),
+    ...(plan === undefined ? {} : { coverageDefinitions: plan.definitions }),
+    rules: tableRules(artifact),
+    prog: artifact,
+  }
+}
+
+function encodeForRun(
+  ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>,
+  opts: TableRuleMapOptions,
+): { prog: TableProgram; fnSrcs: (string | null)[]; hostMode: HostMode; plan: ReturnType<typeof buildGrammarPlan> | undefined } | null {
+  runDuplicationDiagnosticRules(ruleMap, opts.duplication)
+  const encodeMap = withAmbient(ruleMap, opts)
+  // WINNERS ARE THE NON-`lazy` ENTRIES, exactly as `codegen.ts:5639` picks them.
+  // A `rules()` map stores named lazy proxies beside resolved bodies, and the plan
+  // uses the winner map to give a shared subtree ONE owner; filtering differently
+  // here would mint `rule:` ids the source lowering does not, so a consumer
+  // comparing the two engines' coverage would be comparing two denominators.
+  const plan = opts.coverage === true
+    ? buildGrammarPlan(
+        encodeMap.map(([, rule]) => rule),
+        Object.fromEntries(encodeMap.filter(([, rule]) => rule._def.tag !== 'lazy')),
+      )
+    : undefined
+  const hostMode = resolveHostMode(ruleMap, opts.hostMode)
+  const settings: TableSettings = {
+    hostMode,
+    ...(resolveTrackLines(ruleMap, opts.trackLines) ? { trackLines: true } : {}),
+    ...(opts.recovery === true ? { recovery: true } : {}),
+    ...(plan === undefined ? {} : { coverage: plan }),
+  }
+  try {
+    const { prog, fnSrcs } = encodeTableProgram(Object.fromEntries(encodeMap), settings)
+    return { prog, fnSrcs, hostMode, plan }
+  } catch (e) {
+    opts.refusals?.push(e instanceof Error ? e.message : String(e))
+    return null
+  }
+}
+
+export function compileRuleMap(
+  ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>,
+  opts: TableRuleMapOptions = {},
+): CompiledRuleMapTable | null {
+  // ALL-OR-NOTHING, exactly as `compileRuleMap` is. A construct with no opcode
+  // (`UnsupportedConstruct`) and a `g.X` reference that resolves to nothing
+  // (the lazy thunk throws) both mean this map cannot become a table, and the
+  // caller's existing "leave this rules() call interpreted" fallback covers it.
+  const encoded = encodeForRun(ruleMap, opts)
+  if (encoded === null) return null
+  const { prog, fnSrcs, hostMode, plan } = encoded
+  const artifact = closureArtifact(prog)
+
+  // RUNTIME-ONLY: the program parses but cannot be PRINTED (a live trivia
+  // combinator parked in the pool, say). `compileRuleMap` returns null for its
+  // own unprintable cases rather than emitting something that loads and
+  // misbehaves; this is the same answer to the same question.
+  if (artifact.runtimeOnly !== undefined && artifact.runtimeOnly.length > 0) {
+    opts.refusals?.push(...artifact.runtimeOnly)
+    return null
+  }
+  // The `mfCovered && buildCovered` gate, for the table's reducer pool: without
+  // a source per author callback the emitters print `() => {}`, which produces a
+  // module that loads and returns the wrong tree. An out-of-band list fills in
+  // only where the encoder captured nothing, and only if it is COMPLETE — a
+  // partial list would leave the placeholders it was passed to remove.
+  const supplied = opts.fnSources
+  const sources = fnSrcs.map((s, i) => s ?? supplied?.[i] ?? null)
+  if (sources.some(s => s === null)) {
+    const missing = sources.flatMap((s, i) => (s === null ? [i] : []))
+    opts.refusals?.push(
+      `author reducer source missing for prog.fns[${missing.join(', ')}] — printing would emit \`() => {}\` and the parse would return no value`,
+    )
+    return null
+  }
+  if (supplied !== undefined && supplied.length > fnSrcs.length) {
+    throw new Error(
+      `compileRuleMap: got ${supplied.length} fnSources for a pool of ${fnSrcs.length}. `
+      + 'The list is positional, in prog.fns order, so a longer one means it belongs to a '
+      + 'different encode — and the entries would be silently misassigned.',
+    )
+  }
+
+  const replacementWithMetadata = (metadataSource?: string): string => emitTableExpression(artifact, {
+    entry: null,
+    runtimeRef: opts.runtimeRef ?? 'tableRules',
+    fnSources: sources as string[],
+    ...(metadataSource === undefined ? {} : { metadataSource }),
+  })
+  const replacement = replacementWithMetadata()
+
+  return {
+    keys: ruleMap.map(([key]) => key),
+    replacement,
+    replacementWithMetadata,
+    hostMode,
+    // WHAT THE FLAG MEANS is "a DIRECT BUILDER's positioned-CST branch was
+    // dropped", which is what the driver's `'ast' artifact + CST host` check keys
+    // off. `mode === 'ast'` alone over-reports it: an all-STRUCTURAL grammar has no
+    // direct builder, so there was no branch to drop and it stays usable with either
+    // host — the long-standing `node(parser)` contract. Same predicate codegen uses
+    // for its own `hasDirectBuilders` (both read `analysis/commitment.ts`), so the two
+    // lowerings stamp the same artifact rather than disagreeing about it.
+    hostBranchElided: hostMode === 'ast' && ruleMap.some(([, rule]) => hasDirectBuildDef(rule)),
+    reflection: collectGrammarReflection(ruleMap),
+    ...(plan === undefined ? {} : { coverageDefinitions: plan.definitions }),
+    rules: tableRules(artifact),
+    prog: artifact,
+  }
+}