parseman 0.46.0 → 0.47.1

package/src/combinators/withCtx.ts

@@ -0,0 +1,45 @@
+import type { Combinator, ParseContext, ParseResult, ParserMeta } from '../types.ts'
+
+/**
+ * Runs `combinator` with `ctx.state` set to `extra` for the duration of the parse.
+ * The outer user context is restored on exit (lexical scoping).
+ *
+ *   const functionBody = withCtx({ inFn: true },
+ *     sequence(literal('{'), many(statement), literal('}'))
+ *   )
+ *
+ * Read back with guard() or from within a transform's span argument.
+ */
+export function withCtx<U, T>(extra: U, combinator: Combinator<T>): Combinator<T> {
+  const meta: ParserMeta = {
+    firstSet: combinator._meta.firstSet,
+    canMatchNewline: combinator._meta.canMatchNewline,
+    isTrivia: false,
+  }
+  return {
+    _tag: 'withCtx',
+    _meta: meta,
+    _def: { tag: 'withCtx', extra, parser: combinator as Combinator<unknown> },
+    parse(input: string, pos: number, ctx: ParseContext): ParseResult<T> {
+      // SAVE / RESTORE, not a clone. This used to run the child against
+      // `{ ...ctx, state: extra }`, which scopes far more than the state: every
+      // scalar the child writes on `ctx` lands on the clone and dies with it —
+      // including `_fe` / `_fx`, the furthest-failure position and its expected
+      // set. A failing `withCtx` subtree therefore contributed NOTHING to the
+      // parent's expected set, silently. Nobody asked for that isolation; the
+      // combinator's contract is "set `state` for the duration", and the clone
+      // was an implementation detail with a semantic reach nobody consented to.
+      //
+      // (Array MUTATIONS were never affected either way — `_triviaLog` and the
+      // CST buffers are the same objects through a spread — so this changes the
+      // scalars only, which is exactly the part that was being dropped.)
+      //
+      // It also allocated a full context per entry, on the object every
+      // combinator reads on every step.
+      const saved = ctx.state
+      ctx.state = extra
+      try { return combinator.parse(input, pos, ctx) }
+      finally { ctx.state = saved }
+    },
+  }
+}

package/src/compiler/build-arity.ts

@@ -0,0 +1,330 @@
+import type { ParserDef } from '../types.ts'
+import { recordDegradation } from './degradation.ts'
+
+/**
+ * Per-node children/fields/raw/trivia/state capture is dead work when the build
+ * never declares the corresponding formal param. This module derives a build's
+ * *confirmed* formal-parameter arity so the compiler and macro can elide their
+ * direct-AST-only CST collectors without changing structural/CST output.
+ *
+ * Conservative by construction: any source we can't confidently parse — rest params,
+ * destructuring, `arguments`, an unrecognized shape — yields `null` (arity unknown),
+ * and callers KEEP full capture. We only ever return a number when the parameter list
+ * is a plain comma-separated list of simple identifiers.
+ */
+
+type NodeDef = Extract<ParserDef, { tag: 'node' }>
+
+/**
+ * Is a positioned-CST host installed for this parse?
+ *
+ * `cstBuildHost` (and the language-service hosts) mark themselves with
+ * `_parsemanCstOutput`. That flag is what re-routes a node with its OWN direct builder
+ * through the host — and therefore what makes the direct builder's formal arity the
+ * WRONG basis for eliding capture, since the consumer is no longer that builder.
+ *
+ * The COMPILED engine answers this at compile time (`hostMode`, 0.37.0). The interpreter
+ * has no compile step, so it asks per parse.
+ */
+export function cstOutputHost(build: unknown): boolean {
+  return (build as { _parsemanCstOutput?: true } | undefined)?._parsemanCstOutput === true
+}
+
+/**
+ * ── THE ONE RULE IN THIS FILE ────────────────────────────────────────────────────
+ * A WRONG NUMBER IS THE BUG. `null` (unknown) IS ALWAYS ACCEPTABLE.
+ *
+ * `null` fails open: the caller keeps every capture tier and records a degradation, so
+ * the output is correct and the cost is visible. A wrong NUMBER silently drops capture
+ * tiers — fields vanish from the AST with no diagnostic, because a confident answer
+ * never reaches `recordDegradation`. Every branch below that cannot decide with
+ * certainty must therefore return `null`, never a guess.
+ * ─────────────────────────────────────────────────────────────────────────────────
+ */
+
+/** `x => ...` — a single unparenthesised identifier parameter. */
+const SINGLE_IDENT_ARROW_RE = /^[A-Za-z_$][\w$]*\s*=>/
+
+/** Start of a formal-parameter list: `(`, or `function name?(`. */
+const PARAM_LIST_OPEN_RE = /^(?:function\b[^(]*)?\(/
+
+/**
+ * A host builtin, a `Function.prototype.bind` result and a `Proxy` all stringify to
+ * `function () { [native code] }`. That has an EMPTY parameter list which says nothing
+ * whatever about the underlying function's arity — reading it as arity 0 is a confident
+ * lie that silently drops every capture tier. None of those are documented reducer
+ * shapes and parseman does not owe them support; it owes them an honest `null`.
+ */
+const NATIVE_CODE_RE = /\{\s*\[native code\]\s*\}/
+
+/** Identifier head of a formal param, with its optional `?`. */
+const PARAM_HEAD_RE = /^[A-Za-z_$][\w$]*\s*\??\s*/
+
+/**
+ * Confirmed count of simple formal parameters the build declares, or `null` when the
+ * source can't be parsed into a plain identifier list (→ caller keeps full capture).
+ */
+export function confirmedBuildArity(src: string): number | null {
+  const s = src.trim()
+
+  // Unreadable source → unknown. Checked FIRST: its parameter list is empty, and the
+  // empty-list answer below would otherwise report a confident 0.
+  if (NATIVE_CODE_RE.test(s)) return null
+
+  // A stray `arguments` reference defeats formal-arity reasoning entirely; only a
+  // full-source scan can rule it out. Cheap guard against the obvious cases.
+  //
+  // Checked BEFORE the empty-parameter-list answer below. It used to sit after it, which
+  // made it unreachable for exactly the shape it matters most for: `function () { return
+  // arguments[0] }` has an empty formal list and real arity ≥ 1, and was reported 0.
+  if (/\barguments\b/.test(s)) return null
+
+  // Single-ident arrow: `x => ...` → exactly one param.
+  if (SINGLE_IDENT_ARROW_RE.test(s)) return 1
+
+  const inner = paramListText(s)
+  if (inner === null) return null
+  if (inner.trim() === '') return 0
+
+  const parts = splitTopLevel(inner)
+  if (parts === null) return null
+
+  // Reject anything that isn't a flat list of simple identifiers. A rest param
+  // (`...args`), destructuring (`{a}`, `[a]`), or default (`a = 1`) all appear here.
+  for (const part of parts) {
+    if (!isConfirmableParam(part.trim())) return null
+  }
+
+  return parts.length
+}
+
+/**
+ * The text between a build's parameter parentheses, or `null` when it cannot be located
+ * with certainty.
+ *
+ * Found by a BALANCED scan rather than a character class. The previous `[^)]*` stopped at
+ * the first `)`, which in ordinary TypeScript is the one inside a function-typed
+ * annotation: `(children: (n: N) => N, fields) => …` yielded `children: (n: N` and
+ * reported arity 1 instead of 2 — a silent under-capture on precisely the typed shape the
+ * docs tell authors to write.
+ */
+function paramListText(s: string): string | null {
+  const open = PARAM_LIST_OPEN_RE.exec(s)
+  if (!open) return null
+  const start = open[0].length
+  const end = matchingParen(s, start)
+  if (end === null) return null
+  // An arrow's list must be followed by `=>`; a `function`'s is followed by its body.
+  // Without this a parenthesised expression could be read as a parameter list.
+  if (!s.startsWith('function') && !/^\s*=>/.test(s.slice(end + 1))) return null
+  return s.slice(start, end)
+}
+
+/** Index of the `)` closing the list opened just before `start`, else `null`. */
+function matchingParen(s: string, start: number): number | null {
+  let depth = 0
+  for (let i = start; i < s.length; i++) {
+    const c = s[i]!
+    if (c === '"' || c === "'" || c === '`') {
+      const close = skipString(s, i)
+      if (close === null) return null
+      i = close
+      continue
+    }
+    if (c === '(' || c === '[' || c === '{') depth++
+    else if (c === ']' || c === '}') { if (--depth < 0) return null }
+    else if (c === ')') { if (depth === 0) return i; depth-- }
+  }
+  return null
+}
+
+/** Index of the closing quote of the literal opened at `open`, else `null`. */
+function skipString(s: string, open: number): number | null {
+  const quote = s[open]!
+  for (let i = open + 1; i < s.length; i++) {
+    if (s[i] === '\\') { i++; continue }
+    if (s[i] === quote) return i
+  }
+  return null
+}
+
+/**
+ * Split a parameter list on TOP-LEVEL commas, or `null` if it cannot be split with
+ * certainty.
+ *
+ * Tracks `()`/`[]`/`{}` AND `<>`, because a comma inside type arguments belongs to the
+ * annotation, not the list: a plain `,`-split turned `(a: Map<K, V>, b) => …` into three
+ * fragments. `=>` is consumed as a unit so the `>` of an arrow type is not mistaken for
+ * the close of a type-argument list.
+ */
+function splitTopLevel(inner: string): string[] | null {
+  const parts: string[] = []
+  let depth = 0
+  let angle = 0
+  let last = 0
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i]!
+    if (c === '=' && inner[i + 1] === '>') { i++; continue }
+    if (c === '"' || c === "'" || c === '`') {
+      const close = skipString(inner, i)
+      if (close === null) return null
+      i = close
+      continue
+    }
+    if (c === '(' || c === '[' || c === '{') depth++
+    else if (c === ')' || c === ']' || c === '}') { if (--depth < 0) return null }
+    else if (c === '<') angle++
+    else if (c === '>') { if (--angle < 0) return null }
+    else if (c === ',' && depth === 0 && angle === 0) { parts.push(inner.slice(last, i)); last = i + 1 }
+  }
+  if (depth !== 0 || angle !== 0) return null
+  parts.push(inner.slice(last))
+  return parts
+}
+
+/**
+ * A confirmable formal param: a plain identifier, optionally `?`-optional and optionally
+ * carrying a TypeScript type annotation (`c`, `c?`, `c: any`, `c?: Map<K, V>`, `c: (n: N)
+ * => N`). The build source is sliced verbatim from the (possibly TS) grammar source, so
+ * typed params must be recognized or every typed grammar keeps full capture.
+ *
+ * A DEFAULT (`a = 1`, `a: number = 1`) stays unconfirmed: the parameter is optional, so
+ * the formal count overstates what the reducer is guaranteed to receive.
+ */
+function isConfirmableParam(part: string): boolean {
+  const head = PARAM_HEAD_RE.exec(part)
+  if (!head) return false // rest `...a`, destructuring `{a}` / `[a]`
+  const rest = part.slice(head[0].length)
+  if (rest === '') return true
+  if (rest[0] !== ':') return false // `a = 1`, or anything else we cannot read
+  return !hasDefaultAssign(rest.slice(1))
+}
+
+/** An `=` that is not part of `=>`, `>=`, `<=`, `==` or `!=` — i.e. a default value. */
+function hasDefaultAssign(annotation: string): boolean {
+  for (let i = 0; i < annotation.length; i++) {
+    if (annotation[i] !== '=') continue
+    if (annotation[i + 1] === '>' || annotation[i + 1] === '=') { i++; continue }
+    const prev = annotation[i - 1]
+    if (prev === '<' || prev === '>' || prev === '!' || prev === '=') continue
+    return true
+  }
+  return false
+}
+
+/**
+ * The source a def's arity/shape analysis must read.
+ *
+ * `buildSrc` is the source text of the EXPRESSION written at the `node(...)` call
+ * site. When the reducer is passed as a bare identifier — `node('Foo', p, { build:
+ * foldOperation })` — that text is just `"foldOperation"`, which matches no parameter
+ * list and used to fail open into all five capture tiers, silently. The macro plugin
+ * already holds the whole module's AST, so it resolves such an identifier to its
+ * module-scope declaration and parks that declaration's source here. `buildSigSrc` is
+ * ANALYSIS-ONLY: it is never emitted, so the generated builder reference is unchanged.
+ */
+export function buildAnalysisSrc(def: NodeDef): string {
+  return def.buildSigSrc ?? def.buildSrc ?? def.build!.toString()
+}
+
+/**
+ * Why a parameter list could not be read — the actionable half of the diagnostic.
+ *
+ * Only genuinely undecidable shapes reach here. The resolver (`plugin/reducer-resolver.
+ * ts`) handles named reducers, cross-module imports, namespace members, aliases,
+ * non-reassigned `let`/`var`, defaults and destructuring; a decline from it carries a
+ * machine-readable reason, which is what the author needs in order to fix or declare it.
+ */
+const RESOLVER_REASONS: Record<string, string> = {
+  'rest-parameter': 'its parameter list uses a rest parameter, so the declared arity is unbounded',
+  'arguments': 'its body references `arguments`',
+  'reassigned': 'the binding it names is reassigned, so the function read here is not decidable',
+  'not-a-function': 'the binding it names is not a function declaration',
+  'unresolved-import': 'its module could not be resolved or parsed',
+  'not-found': 'the name did not resolve to any binding',
+  'computed': 'it is a computed expression',
+  'foreign-source': 'it is named in a module the resolver was never told about, so its '
+    + 'offsets index no scope tree the resolver holds',
+  'ambiguous-source': 'two distinct registered modules hold byte-identical text, so that '
+    + 'text no longer names the module its offsets index',
+}
+
+function unconfirmableReason(def: NodeDef, src: string): string {
+  const declared = def.buildArityUnresolved
+  if (declared !== undefined && RESOLVER_REASONS[declared]) return RESOLVER_REASONS[declared]!
+  const s = src.trim()
+  const params = s.slice(0, s.indexOf(')') + 1)
+  if (params.includes('...')) return RESOLVER_REASONS['rest-parameter']!
+  if (/\barguments\b/.test(s)) return RESOLVER_REASONS['arguments']!
+  if (/^[A-Za-z_$][\w$]*(\s*\.\s*[A-Za-z_$][\w$]*)?$/.test(s)) {
+    return 'it names a binding this build could not resolve to a function declaration'
+  }
+  return 'its parameter list could not be parsed'
+}
+
+/**
+ * Confirmed formal arity for a node def, reporting once when it cannot be confirmed.
+ *
+ * Order of authority:
+ *   1. `node(..., { buildArity })` — the author DECLARED it. Nothing overrides that.
+ *   2. `def.buildArity` as resolved by the macro's reducer resolver (real scope analysis
+ *      and cross-module import following).
+ *   3. Reading the parameter list out of whatever source we have.
+ *
+ * Fail-open is the correct BEHAVIOR — capturing too much is safe, capturing too little
+ * is a correctness bug. Fail-open with no diagnostic was the defect. But a diagnostic is
+ * the right answer only for the genuinely undecidable; for everything a static analysis
+ * can decide, the right answer is to decide it, which is why (2) exists and why (1) gives
+ * the author a way out of (3) entirely.
+ */
+export function confirmedArityForDef(def: NodeDef): number | null {
+  if (def.buildArity !== undefined) return def.buildArity
+  const src = buildAnalysisSrc(def)
+  const arity = confirmedBuildArity(src)
+  if (arity !== null) return arity
+  const subject = `build reducer \`${(def.buildSrc ?? '<runtime fn>').trim().split('\n')[0]!.slice(0, 60)}\``
+  recordDegradation({
+    code: 'build-arity-unconfirmed',
+    severity: 'warn',
+    where: `node("${def.type ?? '<inferred>'}")`,
+    subject,
+    fellBackTo: `could not confirm its declared arity — ${unconfirmableReason(def, src)} — `
+      + 'so this node captures children, fields and raw children, logs trivia, and clones `_ctx.state` on every match',
+    otherwise: 'only the tiers the reducer actually declares would be captured '
+      + '(arity >= 1 children, >= 2 fields, >= 4 raw, >= 5 trivia, >= 6 state). '
+      + 'Declare it with `node(..., { buildArity: n })` if it cannot be derived',
+  })
+  return null
+}
+
+/** Build reads its 1st (`children`) arg? Unknown/unparseable → true (keep capture). */
+export function buildReadsChildren(def: NodeDef): boolean {
+  if (!def.build) return true // structural node: CST output always owns children
+  const arity = confirmedArityForDef(def)
+  if (arity === null) return true
+  return arity >= 1
+}
+
+/** Build reads its 4th (`rawChildren`) arg? Unknown/unparseable → true (keep capture). */
+export function buildReadsRaw(def: NodeDef): boolean {
+  if (!def.build) return true // structural node: host/default CST may read raw children
+  const arity = confirmedArityForDef(def)
+  if (arity === null) return true
+  return arity >= 4
+}
+
+/** Build reads the 5th (triviaLog) arg? Unknown/unparseable → true (keep capture). */
+export function buildReadsTrivia(def: NodeDef): boolean {
+  if (!def.build) return true // structural node: host may read trivia — keep capture
+  const arity = confirmedArityForDef(def)
+  if (arity === null) return true
+  return arity >= 5
+}
+
+/** Build reads the 6th (state) arg? Unknown/unparseable → true (keep state clone). */
+export function buildReadsState(def: NodeDef): boolean {
+  if (!def.build) return true // structural node: host may read state — keep clone
+  const arity = confirmedArityForDef(def)
+  if (arity === null) return true
+  return arity >= 6
+}

package/src/compiler/compile-linkable-table.ts

@@ -0,0 +1,209 @@
+import type { Combinator } from '../types.ts'
+import type { HostMode } from '../cst/host-mode.ts'
+import { childrenOf } from '../analysis/gating.ts'
+import { collectGrammarReflection, type GrammarReflection } from '../cst/reflection.ts'
+import { classifyRuleMap } from '../analysis/commitment.ts'
+import { serializeRuleMap } from './ir-serialize.ts'
+import { compileRuleMap, compileRuleMapRunnable, type TableRuleMapOptions } from '../table/compile-rule-map.ts'
+import type { TableProgram, TableRule } from '../table/program.ts'
+import { PARSEMAN_VERSION } from '../version.ts'
+
+/**
+ * `compileLinkable()` FOR THE TABLE LOWERING — `linkable()` produces TABLES too.
+ *
+ * ── WHAT `compileLinkable` ACTUALLY RETURNS, AND WHY NONE OF IT TRANSFERS ─────
+ * `LinkablePieces` is `prelude` / `ruleFns` / `wrappers` / `firstSets` /
+ * `firstSetRecipes` / `nullable` / `deps` / `needsEmptyTl` — every field of it is
+ * SOURCE TEXT or an input to resolving source text. It exists because
+ * source-lowering composition is a TEXTUAL splice: `fusedBody()` concatenates
+ * namespaced preludes, picks a winning `_r_<Name>` per name, and substitutes
+ * `@FS:` dispatch placeholders with the winner's first-set condition. A table has
+ * no text to splice and no placeholders to resolve, so porting those fields would
+ * be porting the mechanism rather than the capability.
+ *
+ * The capability is: a piece must be RUNNABLE on its own, and COMPOSABLE with
+ * other pieces. This artifact carries exactly those two things.
+ *
+ *   `prog` / `rules`  — the piece AS A TABLE. Present whenever the piece is
+ *                       self-contained. This is the ruling: a `linkable()`
+ *                       artifact is a table, not a bag of compiled functions.
+ *   `ir`              — the piece's combinator graph, serialized. This is the
+ *                       composable half, and it is NOT new machinery: the plugin
+ *                       already carries pieces as IR (`plugin/index.ts:1772`) and
+ *                       the linker already re-lowers them (`linker.ts:640`,
+ *                       `compileLinkable(evalRuleMapIR(p.ir), …)`).
+ *
+ * ── WHY THAT MAKES COMPOSITION THE EASY KIND ─────────────────────────────────
+ * The open question was whether table-to-table composition has to merge two
+ * ALREADY-ENCODED programs — relocating code offsets and merging const, fn,
+ * class, expected and dispatch pools. It does not, as long as every piece
+ * carries its IR: the composer evaluates each piece's IR back to a rule map,
+ * merges the maps (later pieces overriding earlier names, which is what
+ * `compose()` means), and calls `encodeTable` ONCE over the merged map. One
+ * encode, no relocation, and the result is byte-for-byte the table the merged
+ * grammar would have produced if it had been written as one `rules()` call.
+ *
+ * The relocation route is only forced for a piece with NO IR, which is why `ir`
+ * being null is reported here as a first-class fact rather than folded into a
+ * bare `null` return.
+ *
+ * ── THE HOLE CASE IS NOT REFUSED ─────────────────────────────────────────────
+ * A piece that references a rule it does not define (`g.Value` with no
+ * `.define()` — `hasExternalRuleRef`'s SHARED-SHAPE signature) cannot be encoded
+ * standalone: `encodeTable` resolves a `lazy` by calling its thunk, and that
+ * thunk throws. Such a piece gets `prog: null` and `rules: null` and keeps its
+ * `ir`, which is the correct answer rather than a refusal: a shape with a hole
+ * is not a parser in ANY lowering, and it composes through the merge above,
+ * where the hole is filled by whichever piece supplies the name.
+ */
+export type LinkableTableOptions = Omit<TableRuleMapOptions, 'runtimeRef'>
+
+export type LinkableTable = {
+  /**
+   * The parseman version that produced this artifact — the same ARTIFACT VERSION
+   * LOCK `LinkablePieces.v` carries, for the same reason: artifacts are
+   * version-locked and the format has no back-compat read path.
+   */
+  v: string
+  ns: string
+  /** Local rule names, external (undefined) entries already dropped. */
+  keys: string[]
+  /** Rule names this piece REFERENCES but does not define. */
+  external: string[]
+  /** The piece as a table — null when it has holes (see `external`). */
+  prog: TableProgram | null
+  /** The runnable form of `prog` — null for the same reason. */
+  rules: Record<string, TableRule> | null
+  /** The emitted expression for `prog`, or null when there is no `prog`. */
+  replacement: string | null
+  /**
+   * The piece's combinator graph, serialized — the COMPOSABLE half. Null when
+   * the map cannot be faithfully serialized (a callback with no captured
+   * source); a null here is what would force composition to merge encoded
+   * programs instead of merging rule maps.
+   */
+  ir: string | null
+  /**
+   * The piece's rule map as LIVE COMBINATORS — present only for an in-process
+   * artifact, never serialized.
+   *
+   * `ir` is the portable composable half, and a grammar BUILT AT RUNTIME often has no
+   * `ir` at all (a live callback has no recoverable source). Such a piece still has to
+   * compose, and in-process it can: the combinators themselves are right there. Without
+   * this the runtime `compose([linkable(g)])` refused a grammar the source lowering
+   * composed happily.
+   */
+  ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>
+  hostMode: HostMode
+  hostBranchElided: boolean
+  /**
+   * Whether any rule carries a DIRECT builder, and whether the piece is free of
+   * semantic reduction. `composeLeaf` gates on both, and they are predicates over the
+   * combinator graph rather than products of lowering it — so they belong on the
+   * artifact regardless of which lowering produced it.
+   */
+  hasDirectBuilders: boolean
+  isRecognitionOnly: boolean
+  reflection: GrammarReflection
+}
+
+/**
+ * Local vs external, decided exactly as `compileLinkable` decides it: a
+ * `rules(g => …)` cache also holds every `g.X` that was merely ACCESSED, so an
+ * accessed-but-undefined rule leaks into `Object.entries` as an unresolvable
+ * lazy. Those are not local rules.
+ */
+function isLocal(rule: Combinator<unknown>): boolean {
+  const d = rule._def
+  if (d.tag !== 'lazy') return true
+  try { d.thunk(); return true } catch { return false }
+}
+
+/** Every named rule this map references but does not define, in first-seen order. */
+function externalNames(
+  ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>,
+): string[] {
+  const out: string[] = []
+  const seen = new Set<Combinator<unknown>>()
+  const visit = (p: Combinator<unknown>): void => {
+    if (seen.has(p)) return
+    seen.add(p)
+    const d = p._def
+    if (d.tag === 'lazy') {
+      let resolved: Combinator<unknown> | undefined
+      try { resolved = d.thunk() } catch { resolved = undefined }
+      if (resolved === undefined) {
+        const name = (p as unknown as { _ruleName?: string })._ruleName
+        if (name !== undefined && !out.includes(name)) out.push(name)
+        return
+      }
+      visit(resolved)
+      return
+    }
+    for (const child of childrenOf(d)) visit(child)
+  }
+  for (const [, rule] of ruleMap) visit(rule)
+  return out
+}
+
+export function compileLinkableTable(
+  ruleMapArg: ReadonlyArray<readonly [string, Combinator<unknown>]>,
+  ns: string,
+  opts: LinkableTableOptions = {},
+): LinkableTable | null {
+  if (!ns) throw new Error('compileLinkableTable: ns must be a non-empty namespace')
+  const ruleMap = ruleMapArg.filter(([, rule]) => isLocal(rule))
+  if (ruleMap.length === 0) return null
+  const external = externalNames(ruleMap)
+  // The duplication diagnostic is OPT-IN here, unlike at the owning `rules()` site: the
+  // macro lowers the same map through both, so letting `PARSEMAN_DUPLICATION` alone
+  // reach this call would repeat every finding the owning site already reported. An
+  // explicit option still runs. `'off'` is passed rather than omitted because omitting
+  // it is what resolves to the env var.
+  const dedupOpts = { ...opts, duplication: opts.duplication ?? ('off' as const) }
+  const compiled = external.length === 0 ? compileRuleMap(ruleMap, dedupOpts) : null
+  // Serialized BEFORE anything else needs it and independently of whether the
+  // piece encoded: a shape with a hole is precisely the case that has no table
+  // and must still compose.
+  const ir = serializeRuleMap(ruleMap, opts.scanSkip ?? null)
+  // RUNNABLE IS NOT PRINTABLE, and `linkable()` only needs the first.
+  //
+  // `compileRuleMap` refuses a map whose reducers have no captured SOURCE, because
+  // printing one would emit `() => {}` and silently return the wrong tree. That gate is
+  // right for the macro, which prints — and wrong here: a grammar BUILT AT RUNTIME (every
+  // interpreter-path `linkable()` caller) has live callbacks and no sources by
+  // construction, and it is never printed. Treating "cannot print" as "cannot compile"
+  // made `linkable()` reject the ordinary runtime grammar the source lowering accepted.
+  //
+  // So: encode again for RUNNING only. `prog` still holds the live callbacks in its
+  // pool, `tableRules` binds them, and `replacement` stays null — which is the
+  // artifact honestly saying it cannot be emitted as source.
+  const runnable = compiled === null && external.length === 0
+    ? compileRuleMapRunnable(ruleMap, dedupOpts)
+    : null
+  // NO REFUSAL PAST THIS POINT. A piece with neither a table nor IR is still USABLE
+  // in-process, because `ruleMap` carries the live combinators — which is exactly the
+  // case a grammar with holes AND unserializable callbacks lands in. Refusing it here
+  // made `compose()` throw for a grammar the interpreter fuses happily; the fields below
+  // already state, individually, what this piece can and cannot do.
+
+  const hostMode = compiled?.hostMode
+    ?? opts.hostMode
+    ?? ruleMap.map(([, r]) => r._meta.grammarHostMode).find(Boolean)
+    ?? 'ast'
+  return {
+    v: PARSEMAN_VERSION,
+    ns,
+    keys: ruleMap.map(([key]) => key),
+    external,
+    prog: compiled?.prog ?? runnable?.prog ?? null,
+    rules: compiled?.rules ?? runnable?.rules ?? null,
+    replacement: compiled?.replacement ?? null,
+    ir,
+    ruleMap,
+    hostMode,
+    hostBranchElided: hostMode === 'ast',
+    ...classifyRuleMap(ruleMap),
+    reflection: compiled?.reflection ?? collectGrammarReflection(ruleMap),
+  }
+}