parseman 0.45.0 → 0.47.0

package/src/compiler/degradation.ts

@@ -0,0 +1,266 @@
+/**
+ * Degradation diagnostics — "parseman could not do the fast/complete thing here".
+ *
+ * A fallback that is CORRECT but slower (or less complete) and announces nothing is
+ * indistinguishable from working properly. Every such path in the compiler and the
+ * analysis APIs reports through this one channel so a consumer's build gate can
+ * assert ZERO degradations, exactly the way jess's `check:macro` already asserts zero
+ * `"falling back to runtime"` lines.
+ *
+ * Machine-greppable contract (stable across minor versions):
+ *
+ *   [parseman] degraded [<code>] <where>: <subject> — <fell back to>; otherwise <what>
+ *
+ * Grep token is the literal `[parseman] degraded`. The `<code>` is a stable kebab-case
+ * identifier; new codes may be added, existing ones are not renamed without a note in
+ * CHANGELOG.md.
+ *
+ * NOT for: user errors (those throw), un-taken optimizations that cost nothing, or
+ * anything a grammar author cannot act on. A diagnostic that fires on every rule gets
+ * filtered out and becomes the same silence we are trying to end — so a code that is
+ * common and unavoidable AGGREGATES (see `DETAIL_CAP`) into one summary line with a
+ * count instead of one line per rule.
+ */
+
+/** Off / print / throw. */
+export type DegradationLevel = 'off' | 'warn' | 'error'
+
+/** Stable, greppable code per degradation class. */
+export type DegradationCode =
+  /** A node build's formal parameter list could not be read → all capture tiers kept. */
+  | 'build-arity-unconfirmed'
+  /** A composed/carried piece is an opaque artifact → its rules were not analysed. */
+  | 'opaque-artifact'
+  /** A coverage-definition request could not read the grammar → empty is NOT a zero. */
+  | 'coverage-definitions-unavailable'
+
+/**
+ * Severity. `warn` = a real, measurable cost the author can remove. `info` = the author
+ * has nothing to act on (e.g. an imported reducer in someone else's package), but the
+ * fact still has to be visible and countable.
+ */
+export type DegradationSeverity = 'warn' | 'info'
+
+export type Degradation = {
+  code: DegradationCode
+  severity: DegradationSeverity
+  /** Rule / node type / artifact the cost lands on. Never a bare "<unknown>" if avoidable. */
+  where: string
+  /** The reducer, identifier, or input that could not be analysed. */
+  subject: string
+  /** What parseman did instead. */
+  fellBackTo: string
+  /** What it would have done had the input been analysable. */
+  otherwise: string
+}
+
+/** One line per finding, in the documented greppable shape. */
+export function formatDegradation(d: Degradation): string {
+  return `[parseman] degraded [${d.code}] ${d.where}: ${d.subject} — ${d.fellBackTo}; otherwise ${d.otherwise}`
+}
+
+/**
+ * Per-code detail cap. Above it the remaining sites collapse to one counted summary
+ * line. Chosen small on purpose: the point of a detail line is to give an author a
+ * concrete place to start, and eight starting points is already more than anyone acts
+ * on in one pass. The COUNT is what makes the rest visible.
+ */
+const DETAIL_CAP = 8
+
+/** Group by code, cap the detail lines, and append a counted summary for the rest. */
+export function formatDegradations(list: readonly Degradation[]): string[] {
+  const byCode = new Map<DegradationCode, Degradation[]>()
+  for (const d of list) {
+    const bucket = byCode.get(d.code)
+    if (bucket) bucket.push(d)
+    else byCode.set(d.code, [d])
+  }
+  const out: string[] = []
+  for (const [code, items] of byCode) {
+    for (const d of items.slice(0, DETAIL_CAP)) out.push(formatDegradation(d))
+    if (items.length > DETAIL_CAP) {
+      out.push(
+        `[parseman] degraded [${code}] +${items.length - DETAIL_CAP} more site(s) not listed `
+        + `(${items.length} total). Set PARSEMAN_DEGRADATION=error to fail the build on these.`,
+      )
+    }
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Capture sink
+//
+// Compilation is single-module and synchronous, so a module-level sink (opened per
+// transform, drained after) records findings without threading a field through every
+// Ctx and every compile*() return — the same shape as the regex-lowering sink in
+// codegen.ts, for the same reason.
+// ---------------------------------------------------------------------------
+//
+// A STACK, not a single slot. `transformMacro` re-enters itself when it lowers a private
+// source module, so a single slot let the inner call's `endDegradationCapture()` close
+// the OUTER module's sink — every later finding in the outer pass then bypassed capture
+// and printed instead. A stack scopes each frame to its own module.
+// ---------------------------------------------------------------------------
+const _sinks: Array<Map<string, Degradation>> = []
+
+/** Begin collecting degradations instead of printing them. */
+export function beginDegradationCapture(): void {
+  _sinks.push(new Map())
+}
+
+/** Stop collecting and return the findings (deduped, insertion-ordered). */
+export function endDegradationCapture(): Degradation[] {
+  const sink = _sinks.pop()
+  return sink ? [...sink.values()] : []
+}
+
+/** Open-sink depth, for a caller that must unwind exactly its own frames. */
+export function degradationCaptureDepth(): number {
+  return _sinks.length
+}
+
+/**
+ * Close every sink opened above `depth` and return their findings, outermost first.
+ *
+ * The safety net for an ABORTED capture. `beginDegradationCapture()` and its matching
+ * `end` used to sit on the straight-line path of a function that throws between them, so
+ * one failed macro transform left the sink open for the REST OF THE PROCESS: every later
+ * `recordDegradation` — including from an unrelated runtime `compile()` — went into a
+ * dead Map and printed nothing. Calling this from a `finally` bounds the damage to the
+ * frame that failed, and returns what it had collected so it can still be reported
+ * rather than silently dropped.
+ */
+export function unwindDegradationCapture(depth: number): Degradation[] {
+  const found: Degradation[] = []
+  while (_sinks.length > depth) {
+    const sink = _sinks.pop()!
+    found.unshift(...sink.values())
+  }
+  return found
+}
+
+/**
+ * Resolve the level: explicit argument wins, else `PARSEMAN_DEGRADATION`, else
+ * default-on `'warn'`. Default-on is the whole point — this exists because the
+ * default was silence.
+ */
+export function resolveDegradationLevel(explicit?: DegradationLevel): DegradationLevel {
+  if (explicit !== undefined) return explicit
+  const env = typeof process !== 'undefined' ? (process.env?.PARSEMAN_DEGRADATION as DegradationLevel | undefined) : undefined
+  if (env === 'off' || env === 'warn' || env === 'error') return env
+  return 'warn'
+}
+
+/**
+ * The dedup key for one finding.
+ *
+ * `JSON.stringify` of the tuple, NOT a delimiter-joined string. Two of the three
+ * components are unbounded author text — `where` embeds a node type and `subject` is a
+ * verbatim slice of reducer SOURCE — so no single delimiter character can be shown absent
+ * from them, and picking a rarer one is the same bug one notch weaker. A JSON array is
+ * injective by construction and needs no such argument.
+ *
+ * It is also PRINTABLE, which is the property this file lost twice. The key was built
+ * with RAW 0x00 bytes in a template literal, which makes the whole source file BINARY:
+ * `git diff --numstat` reported `- -` for it, GitHub refused to render it, and `grep -rn`
+ * skipped it SILENTLY — no "binary file matches", no output, exit 0. The largest new file
+ * in the release was invisible to ordinary review. Commit `ed81612` had already removed
+ * exactly this pattern from `gating.ts` and `duplication.ts`; it came straight back here.
+ * `scripts/check-control-bytes.mjs` now fails CI on it, because a fix without a gate got
+ * us a second occurrence and would get us a third.
+ *
+ * This runs only when a degradation is actually recorded — never per match — so the
+ * encoding cost is irrelevant.
+ */
+function degradationKey(d: Degradation): string {
+  return JSON.stringify([d.code, d.where, d.subject])
+}
+
+/**
+ * Record one degradation. Deduped on `code + where + subject`, so the four capture-tier
+ * probes that all consult the same unreadable parameter list produce ONE finding, not
+ * four.
+ *
+ * With a sink open (a macro transform) the finding is collected and the drain site
+ * decides what to do with it. With NO sink open — a runtime `compile()` — this is the
+ * only place that ever sees the finding, so it is also the only place that can honour
+ * `'error'`. It therefore throws here. `docs/guide/degradation-diagnostics.md` documents
+ * `PARSEMAN_DEGRADATION=error` as "fail the build" without qualification, and until this
+ * throw existed that was false in library mode: `error` silently behaved as `warn`,
+ * because `endDegradationCapture()` had exactly one call site, in the macro plugin.
+ */
+export function recordDegradation(d: Degradation): void {
+  const level = resolveDegradationLevel()
+  if (level === 'off') return
+  const key = degradationKey(d)
+  const sink = _sinks[_sinks.length - 1]
+  if (sink) {
+    if (!sink.has(key)) sink.set(key, d)
+    return
+  }
+  if (_immediate.has(key)) return
+  _immediate.add(key)
+  if (level === 'error') throw new Error(`parseman: degraded compilation path\n${formatDegradation(d)}`)
+  console.warn(formatDegradation(d))
+}
+
+/** Dedup memo for the sink-less (runtime `compile()`) path. */
+const _immediate = new Set<string>()
+
+/**
+ * Open a per-`compile()` drain and return the function that closes it.
+ *
+ * This channel stays LOUD. `compile()` no longer prints gating advice — that is a
+ * deliberate diagnostic now (`diagnoseGrammar`) — but a degradation is not advice: it
+ * is parseman reporting that it could not do the thing the caller asked for, and this
+ * release exists to stop that happening silently. What changes here is only the SHAPE.
+ *
+ * Before, the sink-less path printed one ~500-character line per site as it went, with
+ * no aggregation — 31 of them for a single code in one `pnpm perf:workloads` run, each
+ * repeating the same advice. The macro drain has always aggregated (`formatDegradations`,
+ * `DETAIL_CAP`); the runtime path simply had no drain to aggregate at. It has one now,
+ * so both paths report the same way and a real count survives instead of a wall.
+ *
+ * Nested inside a macro transform this is a NO-OP: that transform's sink owns the whole
+ * module's findings and returns them on the bundler's warning channel. A per-compile
+ * drain underneath it would steal them and print them instead.
+ *
+ * @returns `drain(report)` — always unwinds the sink (so a `compile()` that throws
+ *   cannot leave it open for the rest of the process), and reports only when
+ *   `report` is true, so a failed compile does not mask its own error with a second one.
+ */
+export function beginCompileDegradationDrain(): (report: boolean) => void {
+  if (resolveDegradationLevel() === 'off' || _sinks.length > 0) return () => {}
+  const depth = degradationCaptureDepth()
+  beginDegradationCapture()
+  return (report: boolean) => {
+    const found = unwindDegradationCapture(depth)
+    if (!report || found.length === 0) return
+    // Process-level dedup, preserved from the immediate path: compiling the same grammar
+    // twice must not re-print what the author has already been told once.
+    const fresh = found.filter(d => {
+      const k = degradationKey(d)
+      if (_immediate.has(k)) return false
+      _immediate.add(k)
+      return true
+    })
+    if (fresh.length === 0) return
+    const lines = formatDegradations(fresh)
+    if (resolveDegradationLevel() === 'error') {
+      throw new Error(`parseman: ${fresh.length} degraded compilation path(s)\n${lines.join('\n')}`)
+    }
+    for (const l of lines) console.warn(l)
+  }
+}
+
+/** Test-only: forget the sink-less dedup memo. */
+export function resetDegradationMemo(): void {
+  _immediate.clear()
+}
+
+/** Test-only: is a sink open? Guards against a leaked capture between test files. */
+export function hasOpenDegradationSink(): boolean {
+  return _sinks.length > 0
+}
+

package/src/compiler/fields.ts

@@ -0,0 +1,191 @@
+import type { Combinator, FieldMap, ParserDef } from '../types.ts'
+import { confirmedArityForDef } from './build-arity.ts'
+
+type NodeDef = Extract<ParserDef, { tag: 'node' }>
+
+export function buildReadsFields(def: NodeDef): boolean {
+  if (!def.build) return true
+  const arity = confirmedArityForDef(def)
+  if (arity === null) return true
+  return arity >= 2
+}
+
+export function parserHasOwnFields(p: Combinator<unknown>, seen: Set<Combinator<unknown>> = new Set()): boolean {
+  if (seen.has(p)) return false
+  seen.add(p)
+  const d = p._def
+  switch (d.tag) {
+    case 'field': return true
+    case 'node': return false
+    case 'lazy': {
+      try { return parserHasOwnFields(d.thunk(), seen) } catch { return false }
+    }
+    case 'sequence':
+    case 'choice': return d.parsers.some(x => parserHasOwnFields(x, seen))
+    case 'dispatch': return parserHasOwnFields(d.selector, seen) || d.cases.some(x => parserHasOwnFields(x.parser, seen)) || (d.matchers ? d.matchers.some(entry => parserHasOwnFields(entry.parser, seen)) : false) || (d.otherwise ? parserHasOwnFields(d.otherwise, seen) : false)
+    case 'sepBy': return parserHasOwnFields(d.parser, seen) || parserHasOwnFields(d.separator, seen)
+    case 'grammar': return parserHasOwnFields(d.parser, seen) || (d.triviaParser ? parserHasOwnFields(d.triviaParser, seen) : false)
+    case 'scanTo': return parserHasOwnFields(d.sentinel, seen) || d.skip.some(x => parserHasOwnFields(x, seen))
+    case 'recover': return parserHasOwnFields(d.parser, seen) || parserHasOwnFields(d.sentinel, seen)
+    case 'routed': return d.fallback ? parserHasOwnFields(d.fallback, seen) : false
+    case 'many':
+    case 'oneOrMore':
+    case 'optional':
+    case 'attempt':
+    case 'transform':
+    case 'trivia':
+    case 'token':
+    case 'leaf':
+    case 'label':
+    case 'expect':
+    case 'withCtx':
+    case 'not':
+    case 'peek':
+      return parserHasOwnFields(d.parser, seen)
+    default:
+      return false
+  }
+}
+
+/**
+ * Does the node's OWN parse frame ever have a trivia run logged into it?
+ * Trivia is logged only by the trivia-skip fn, which runs at `sequence`/`many`/
+ * repeat boundaries. A bare terminal (regex/literal/keywords/…) has NO trivia
+ * site, so its `_cstTriviaLog` stays empty and its `captureTrivia`/`_cstTriviaLog`/
+ * `_triviaCaptureMask` save+install+restore is dead work — the per-node scope
+ * trivia frame can be elided for it (see emitNode `needsTriviaFrame`).
+ *
+ * Stops at a nested `node()` (it manages its OWN trivia frame; trivia inside it
+ * never logs to THIS node's frame). CONSERVATIVE: any unknown / trivia-bearing
+ * shape returns `true` (keep the frame) — we only elide when provably safe.
+ */
+export function parserHasTriviaSite(p: Combinator<unknown>, seen: Set<Combinator<unknown>> = new Set()): boolean {
+  return hasTriviaSite(p, seen, false)
+}
+
+/**
+ * The same question asked of the ROOT trivia log (`_ctx._rootTriviaLog`) instead
+ * of the current node's frame.
+ *
+ * The two differ in exactly one case, and it is the case that matters: a nested
+ * `node()` manages its own FRAME, so nothing inside it reaches the enclosing
+ * frame's log — but the root log is not a frame, and every trivia run inside that
+ * node still lands in it. Reusing `parserHasTriviaSite` for the root sink
+ * therefore under-reports: it dropped the mark on `node()` arms whose trivia does
+ * accumulate, and a parse-tree diff caught it as trivia entries that were no
+ * longer rewound on a failed choice arm (`length: 3` becoming `length: 6`).
+ */
+export function parserHasRootTriviaSite(p: Combinator<unknown>, seen: Set<Combinator<unknown>> = new Set()): boolean {
+  return hasTriviaSite(p, seen, true)
+}
+
+function hasTriviaSite(p: Combinator<unknown>, seen: Set<Combinator<unknown>>, throughNode: boolean): boolean {
+  if (seen.has(p)) return true // cycle → conservative (keep the frame)
+  seen.add(p)
+  const parserHasTriviaSite = (
+    x: Combinator<unknown>,
+    s: Set<Combinator<unknown>> = new Set(),
+  ): boolean => hasTriviaSite(x, s, throughNode)
+  const d = p._def
+  switch (d.tag) {
+    // Trivia is skipped between/around elements or iterations → a site.
+    case 'sequence':
+    case 'many':
+    case 'oneOrMore':
+    case 'sepBy':
+    case 'scanTo':
+    case 'recover':
+      return true
+    // Nested node manages its own trivia frame; none logs into THIS frame. The
+    // root log has no frames, so it must look inside.
+    case 'node': return throughNode ? parserHasTriviaSite(d.parser, seen) : false
+    // Pure terminals + trivia-suppressing token: no site.
+    case 'regex':
+    case 'literal':
+    case 'keywords':
+    case 'guard':
+    // The adjacency probe scans with capture OFF, so it logs nothing.
+    case 'adjacency':
+    case 'token':
+    case 'leaf':
+      return false
+    // In dispatch position routed() reuses the already-consumed selector and has
+    // no trivia boundary. Outside dispatch, only its concrete fallback runs.
+    case 'routed': return d.fallback ? parserHasTriviaSite(d.fallback, seen) : false
+    // Transparent single-child wrappers: recurse.
+    case 'optional':
+    case 'attempt':
+    case 'transform':
+    case 'trivia':
+    case 'label':
+    case 'expect':
+    case 'withCtx':
+    case 'not':
+    case 'peek':
+    case 'field':
+      return parserHasTriviaSite(d.parser, seen)
+    case 'choice': return d.parsers.some(x => parserHasTriviaSite(x, seen))
+    case 'dispatch': return parserHasTriviaSite(d.selector, seen) || d.cases.some(x => parserHasTriviaSite(x.parser, seen)) || (d.matchers ? d.matchers.some(entry => parserHasTriviaSite(entry.parser, seen)) : false) || (d.otherwise ? parserHasTriviaSite(d.otherwise, seen) : false)
+    case 'grammar': return parserHasTriviaSite(d.parser, seen)
+    case 'lazy': {
+      try { return parserHasTriviaSite(d.thunk(), seen) } catch { return true }
+    }
+    default: return true // unknown shape → conservative
+  }
+}
+
+/**
+ * Can this node's inner grammar explicitly enable trivia capture? A surrounding
+ * node owns the collector, so a nested `parser({ captureTrivia: true })` must
+ * allocate that collector before it enters the grammar scope. Nested node()
+ * rules own their separate collector and therefore do not contribute here.
+ */
+export function parserEnablesTriviaCapture(p: Combinator<unknown>, seen: Set<Combinator<unknown>> = new Set()): boolean {
+  if (seen.has(p)) return false
+  seen.add(p)
+  const d = p._def
+  switch (d.tag) {
+    case 'grammar': return d.captureTrivia === true || parserEnablesTriviaCapture(d.parser, seen)
+    case 'node': return false
+    case 'sequence':
+    case 'choice': return d.parsers.some(x => parserEnablesTriviaCapture(x, seen))
+    case 'dispatch': return parserEnablesTriviaCapture(d.selector, seen) || d.cases.some(x => parserEnablesTriviaCapture(x.parser, seen)) || (d.matchers ? d.matchers.some(entry => parserEnablesTriviaCapture(entry.parser, seen)) : false) || (d.otherwise ? parserEnablesTriviaCapture(d.otherwise, seen) : false)
+    case 'sepBy': return parserEnablesTriviaCapture(d.parser, seen) || parserEnablesTriviaCapture(d.separator, seen)
+    case 'scanTo': return parserEnablesTriviaCapture(d.sentinel, seen) || d.skip.some(x => parserEnablesTriviaCapture(x, seen))
+    case 'recover': return parserEnablesTriviaCapture(d.parser, seen) || parserEnablesTriviaCapture(d.sentinel, seen)
+    case 'routed': return d.fallback ? parserEnablesTriviaCapture(d.fallback, seen) : false
+    case 'many':
+    case 'oneOrMore':
+    case 'optional':
+    case 'attempt':
+    case 'transform':
+    case 'trivia':
+    case 'token':
+    case 'label':
+    case 'field':
+    case 'expect':
+    case 'withCtx':
+    case 'not':
+    case 'peek': return parserEnablesTriviaCapture(d.parser, seen)
+    // leaf() clears the inner CST/trivia collector and publishes only its own
+    // terminal result. An inner parser() capture cannot reach this node.
+    case 'leaf': return false
+    case 'lazy': {
+      try { return parserEnablesTriviaCapture(d.thunk(), seen) } catch { return false }
+    }
+    default: return false
+  }
+}
+
+export function buildFieldMap(captures: ReadonlyArray<{ name: string; value: unknown; span: { start: number; end: number } }> | undefined): FieldMap | undefined {
+  if (!captures?.length) return undefined
+  const out: FieldMap = {}
+  for (const cap of captures) {
+    const entry = { value: cap.value, span: cap.span }
+    const current = out[cap.name]
+    if (current === undefined) out[cap.name] = entry
+    else if (Array.isArray(current)) current.push(entry)
+    else out[cap.name] = [current, entry]
+  }
+  return out
+}

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

@@ -0,0 +1,129 @@
+import type { Combinator, ParserDef } from '../types.ts'
+import { recordDegradation } from './degradation.ts'
+
+export type GrammarCoverageDefinition = { id: string; kind: 'rule' | 'choice-arm' | 'dispatch-arm' | 'label' }
+export type GrammarCoveragePlan = {
+  definitions: readonly GrammarCoverageDefinition[]
+  choices: Map<Combinator<unknown>, readonly string[]>
+  dispatches: Map<Combinator<unknown>, readonly string[]>
+  /** Trace-only transaction identity. Attempts are not coverage definitions: a
+   * rejected transaction must not create a semantic winner or denominator. */
+  attempts: Map<Combinator<unknown>, string>
+  labels: Map<Combinator<unknown>, readonly string[]>
+  rules: Map<Combinator<unknown>, string>
+}
+
+function idPart(value: string): string {
+  return encodeURIComponent(value)
+}
+
+function dispatchArmIds(def: Extract<ParserDef, { tag: 'dispatch' }>, path: string): string[] {
+  const ids: string[] = []
+  for (const entry of def.cases) ids.push(`dispatch:${path}/when:${entry.keys.map(idPart).join('|')}`)
+  for (const entry of def.matchers ?? []) {
+    ids.push(`dispatch:${path}/matcher:${entry.kind}:${idPart(entry.value)}${entry.kind === 'matches' && entry.flags ? `:${idPart(entry.flags)}` : ''}`)
+  }
+  if (def.otherwise) ids.push(`dispatch:${path}/otherwise`)
+  return ids
+}
+
+function children(def: ParserDef, winners?: Record<string, Combinator<unknown>>): Combinator<unknown>[] {
+  switch (def.tag) {
+    case 'sequence': case 'choice': return def.parsers
+    case 'dispatch': return [def.selector, ...def.cases.map(entry => entry.parser), ...(def.matchers ? def.matchers.map(entry => entry.parser) : []), ...(def.otherwise ? [def.otherwise] : [])]
+    case 'many': case 'oneOrMore': case 'optional': case 'attempt': case 'transform': case 'trivia': case 'token': case 'leaf': case 'label': case 'field': case 'grammar': case 'not': case 'peek': case 'node': case 'guard': case 'adjacency': case 'withCtx': case 'recover': case 'expect': return 'parser' in def ? [def.parser] : []
+    case 'sepBy': return [def.parser, def.separator]
+    case 'scanTo': return [def.sentinel, ...def.skip]
+    case 'lazy': {
+      let resolved: Combinator<unknown>
+      try { resolved = def.thunk() } catch (e) {
+        // An unresolvable `ref()` / cross-artifact hole truncates the walk, so every
+        // definition beneath it is missing from the plan. That SHRINKS the coverage
+        // denominator, which pushes the reported ratio UP — a blind spot that reads as
+        // better coverage. `analyzeGatingRules` routes the same situation into
+        // `unanalysable`; the coverage walk has no such field, so it reports here.
+        recordDegradation({
+          code: 'coverage-definitions-unavailable',
+          severity: 'warn',
+          where: '<lazy rule reference>',
+          subject: `unresolvable reference (${(e as Error).message})`,
+          fellBackTo: 'the coverage walk stopped at this reference, so every definition below '
+            + 'it is ABSENT from the denominator — which raises the reported ratio rather than '
+            + 'lowering it',
+          otherwise: 'the referenced rule and its whole subtree would contribute definitions',
+        })
+        return []
+      }
+      const name = (resolved as Combinator<unknown> & { _ruleName?: string })._ruleName
+      return name && winners?.[name] ? [winners[name]!] : [resolved]
+    }
+    default: return []
+  }
+}
+
+/** Canonical deterministic IDs for one explicit entry closure, or every public
+ * entry in a `rules()` map. Multiple roots share identity maps so a shared
+ * subtree still has one stable owner. */
+export function buildGrammarPlan(entry: Combinator<unknown> | readonly Combinator<unknown>[], winners?: Record<string, Combinator<unknown>>): GrammarCoveragePlan {
+  const definitions = new Map<string, GrammarCoverageDefinition>()
+  // This plan is per grammar compilation and returned with its definitions; it
+  // does not need a process-global weak side cache.  Ordinary Maps make that
+  // finite ownership explicit and keep WeakMap out of the shipped table graph.
+  const choices = new Map<Combinator<unknown>, readonly string[]>()
+  const dispatches = new Map<Combinator<unknown>, readonly string[]>()
+  const attempts = new Map<Combinator<unknown>, string>()
+  const labels = new Map<Combinator<unknown>, readonly string[]>()
+  const rules = new Map<Combinator<unknown>, string>()
+  // A `rules()` map stores named lazy proxies while code generation may emit
+  // either that proxy or its resolved body.  Final composed winners are the
+  // authority for both identities; relying on `_ruleName` alone loses direct
+  // local leaf rules and cross-piece references after IR hydration.
+  const winnerNames = new Map<Combinator<unknown>, string>()
+  if (winners) {
+    for (const [name, winner] of Object.entries(winners)) {
+      winnerNames.set(winner, name)
+      if (winner._def.tag === 'lazy') {
+        try { winnerNames.set(winner._def.thunk(), name) } catch { /* unresolved external stays absent */ }
+      }
+    }
+  }
+  const seen = new Set<Combinator<unknown>>()
+  const visit = (parser: Combinator<unknown>, path: string): void => {
+    if (seen.has(parser)) return
+    seen.add(parser)
+    const rule = winnerNames.get(parser) ?? (parser as Combinator<unknown> & { _ruleName?: string })._ruleName
+    // `rules()` references are tagged too for linker naming, but only the final
+    // rule definition owns execution coverage; otherwise ref + target double-hit.
+    if (rule && (winnerNames.has(parser) || parser._def.tag !== 'lazy')) {
+      const id = `rule:${rule}`
+      definitions.set(id, { id, kind: 'rule' })
+      rules.set(parser, id)
+    }
+    if (parser._def.tag === 'choice') {
+      const ids = parser._def.parsers.map((_, index) => `choice:${path}/arm:${index}`)
+      choices.set(parser, ids)
+      ids.forEach(id => definitions.set(id, { id, kind: 'choice-arm' }))
+    }
+    if (parser._def.tag === 'dispatch') {
+      const ids = dispatchArmIds(parser._def, path)
+      dispatches.set(parser, ids)
+      ids.forEach(id => definitions.set(id, { id, kind: 'dispatch-arm' }))
+    }
+    if (parser._def.tag === 'attempt') attempts.set(parser, `attempt:${path}`)
+    if (parser._def.tag === 'label') {
+      const id = `label:${path}`
+      labels.set(parser, [id])
+      definitions.set(id, { id, kind: 'label' })
+    }
+    children(parser._def, winners).forEach((child, index) => visit(child, `${path}/${parser._def.tag}:${index}`))
+  }
+  const roots = Array.isArray(entry) ? entry : [entry]
+  for (const root of roots) {
+    // Rule-map compilation can receive ordinary, unannotated combinators. The
+    // caller's winner map is then the only durable public identity for each
+    // root; using the generic `entry` path would merge separate roots' choice
+    // IDs and omit their rule definitions.
+    visit(root, winnerNames.get(root) ?? (root as Combinator<unknown> & { _ruleName?: string })._ruleName ?? 'entry')
+  }
+  return { definitions: [...definitions.values()].sort((a, b) => a.id.localeCompare(b.id)), choices, dispatches, attempts, labels, rules }
+}