parseman 0.59.2 → 0.59.3

package/dist/table/ops.d.ts

@@ -1,21 +1,21 @@
 /**
  * Opcodes for the TABLE lowering (design ledger row G5).
  *
- * The premise, stated so it can be falsified: today every rule's recognizer is
- * INLINED BESPOKE into its own emitted function, so an artifact pays the full
- * cost of the recognition machinery once PER RULE (measured: ~4.9 kB for a
- * `node()` rule; ~186 B for each additional call site). Emitting a rule as a
- * TABLE ROW interpreted by one shared driver moves that machinery out of the
- * artifact and into the runtime, where it is emitted ONCE for all grammars and
- * all variants.
+ * The source lowering this replaced (removed in 0.47.0) inlined every rule's
+ * recognizer into its own emitted function, so an artifact paid for the
+ * recognition machinery once PER RULE (measured then: ~4.9 kB for a `node()`
+ * rule; ~186 B for each additional call site). As TABLE ROWS run by one shared
+ * driver, that machinery lives in the runtime, once for all grammars and all
+ * variants.
  *
  * The instruction stream is a flat `number[]`: `code[ip]` is the opcode and the
  * operands follow it inline. Child instructions are referenced by ABSOLUTE code
- * offset, never by nesting, so the driver is a plain recursive read — no node
- * objects, no closures, no per-combinator allocation.
+ * offset, never by nesting.
  *
- * Operand layouts are documented per opcode below and are the contract between
- * `encode.ts` and `exec.ts`. Nothing else may read the stream.
+ * Operand layouts are documented per opcode below. `encode.ts` writes them; the
+ * engines (`assemble.ts`, `emit-assembly.ts`, the reference `exec.ts`) and the
+ * table analyses (`child-slots.ts`, `site-labels.ts`, `fail-clean.ts`, …) read
+ * them.
  */
 /** `LIT k fx` — `k` indexes a string in the const pool; `fx` the expected set on failure. */
 export declare const OP_LIT = 1;
@@ -256,7 +256,7 @@ export declare const OP_GUARD = 32;
  * would become a no-op and `notAdjacent()` a guaranteed failure. So the SEQ
  * pieces read this row at assembly and run the test themselves, exactly as
  * `sequence()` forks `parseAdjacent` (combinators/sequence.ts:118) and as
- * codegen lowers it at the boundary (codegen.ts:1765).
+ * the source lowering lowered it at the boundary.
  *
  * Reached as a row in its own right only where there IS no boundary — a bare
  * choice arm, a `node()` body, a repeat item. The interpreter throws there
@@ -366,7 +366,7 @@ export declare const OP_ARMGATE = 36;
  * library never sees.
  *
  * It exists because codegen accepts exactly this and delegates at run time
- * (`compiler/codegen.ts`, `emitRuntimeFallback`'s `_rp[i].parse(...)` row). The
+ * (the source lowering's `emitRuntimeFallback`). The
  * encoder used to throw `UnsupportedConstruct`, so the table lowering REJECTED
  * grammars the source lowering compiles, and the two lowerings must accept the
  * same language.
@@ -435,7 +435,7 @@ export declare const OP_LABEL = 39;
  * `on` is 0 for ENTRY and 1 for SUCCESS, and it is read at ASSEMBLY TIME, never
  * per parse: `assemble.ts` picks one of two closures from it, exactly as it picks
  * pieces from `RunCfg`. The two phases are not decoration — the source lowering
- * credits a RULE on entry (`codegen.ts:4529`) and a choice arm, dispatch arm or
+ * credited a RULE on entry and a choice arm, dispatch arm or
  * label only once it has SUCCEEDED, and a table that credited all four alike
  * would report a different denominator's worth of hits than the engine it is a
  * drop-in for.

package/dist/table/program.d.ts

@@ -22,10 +22,10 @@ export type PrecompiledAssembly = {
 /**
  * The emitted form of a grammar under the table lowering.
  *
- * This object is ALL a grammar contributes to a bundle. Every line of
- * recognition logic lives in `exec.ts`, which ships once in the runtime and is
- * shared by every grammar and every variant. A rule costs its row, not a
- * function.
+ * This object is ALL a grammar contributes to a bundle, apart from any
+ * build-time assemblies in `asm`. The recognition logic is the shared driver
+ * (`tableRules`, `assemble.ts`), which ships once in the runtime for every
+ * grammar and every variant. A rule costs its row, not a function.
  *
  * Serialized shape is deliberately JSON-ish (numbers, strings, and a pool of
  * author callbacks) so the emitter can print it as a literal.
@@ -138,9 +138,9 @@ export type TableProgram = {
      */
     readonly triviaSpecs?: readonly TriviaSpec[];
     /**
-     * 1 when this table was encoded with `TableSettings.recovery` — the sequences
-     * carry their inferred follow-set classes and the repetitions their item
-     * expected-set and separator sentinel class.
+     * Always 1: every table carries recovery operands — the sequences their inferred
+     * follow-set classes, the repetitions their item expected set and separator
+     * sentinel class. (`TableSettings.recovery` is a deprecated no-op.)
      *
      * TABLE DATA, read once when the driver/assembly is built. It selects the
      * recovery pieces; it is not a per-parse option, and a recovery table still

package/dist/types.d.ts

@@ -670,7 +670,7 @@ export type GatedArm<T = unknown> = {
  * This lives with the rest of the library's types rather than inside a lowering
  * because it is the shape BOTH lowerings answer to: `table/compile.ts` returns it
  * today and is what `src/index.ts` exports as `compile`. It started in
- * `compiler/codegen.ts`, which made the table import its own public contract from
+ * the source lowering, which made the table import its own public contract from
  * the engine the table replaced — backwards, and a reason the engine could not be
  * deleted.
  */

package/dist/version.d.ts

@@ -4,14 +4,14 @@
  *
  * ── ARTIFACTS ARE VERSION-LOCKED ────────────────────────────────────────────────
  * A grammar is compiled AND fused/linked by the SAME parseman version. Parseman does
- * NOT read a compiled artifact produced by a different version. The compiled-artifact
- * format (`firstSetRecipes`, `LinkablePieces`, the fused-body shape, …) may therefore
- * change freely between versions and carries NO back-compat shim: `fusedBody` refuses
- * to link a serialized artifact stamped with a different version, and there is no
- * "legacy format" read path. If you find yourself adding one, STOP — it is dead code.
+ * NOT read a compiled artifact produced by a different version. The artifact formats
+ * (the table program, `LinkableTable`, carried IR) may therefore change freely between
+ * versions and carry NO back-compat shim and no "legacy format" read path. If you find
+ * yourself adding one, STOP — it is dead code. The stamp is written but not yet checked
+ * on read (#186).
  *
  * Kept in sync with `package.json` by `test/unit/version-sync.test.ts`, which fails
  * the build if this constant drifts from the published version.
  */
-export declare const PARSEMAN_VERSION = "0.59.2";
+export declare const PARSEMAN_VERSION = "0.59.3";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parseman",
-  "version": "0.59.2",
+  "version": "0.59.3",
   "packageManager": "pnpm@10.15.1",
   "engines": {
     "node": "^20.19.0 || >=22.13.0"

package/src/analysis/commitment.ts

@@ -404,7 +404,7 @@ export function hasNodeDef(p: Combinator<unknown>, seen: Set<Combinator<unknown>
  *
  * It belongs in THIS module for the reason stated at the top of it: both lowerings
  * must reach the same answer, and a stamp they disagree about is a driver that
- * accepts a host it should refuse. It previously lived in `compiler/codegen.ts`,
+ * accepts a host it should refuse. It previously lived in the source lowering,
  * which forced `table/compile-rule-map.ts` to import the engine the table replaced.
  *
  * The descent mirrors the source lowering's own `childrenOf` exactly — including a

package/src/analysis/terminal.ts

@@ -252,7 +252,7 @@ export function render(lines: readonly Line[], target: RenderTarget = {}): strin
 }
 
 // linecraft's own escapes, for the one component whose plain form is not otherwise
-// reachable. Mirrors `packages/compiler/src/diagnostics.ts:246`. Built from a char code
+// reachable. Built from a char code
 // so the ESC byte cannot be lost in transit the way the old constant table's was.
 const ESC = String.fromCharCode(27)
 const OSC8 = new RegExp(`${ESC}\\]8;;.*?${ESC}\\\\`, 'g')

package/src/combinators/choice.ts

@@ -314,7 +314,7 @@ function bareLeadingTermKey(term: Combinator<unknown>): string | null {
   //
   // A `lazy` ref lead — excluded for correctness, not for want of a key. The
   // once-only prescan runs with `ctx.capturing = false`, which suppresses capture
-  // only for code emitted HERE (emitLeafCapture, codegen.ts). A ref compiles to a
+  // only for code emitted HERE (the source lowering's emitLeafCapture). A ref compiles to a
   // call into a function body generated under its OWN ctx (emitLazy), so its
   // captures and trivia writes would happen during the prescan and then AGAIN in
   // each arm. Replaying a ref needs recorded-and-spliced capture state, not the

package/src/combinators/completions.ts

@@ -3,8 +3,8 @@ import { REC } from '../recovery/scan.ts'
 import { createParseContext } from '../parse-context.ts'
 
 /** Anything `completionsAt` can probe: an interpreter combinator OR a `compile()`d
- * grammar. A grammar compiled with `{ recovery: true }` records the probe on its fast
- * path, so completions work on the published compiled artifact — no interpreter needed. */
+ * grammar, which records the probe on its fast path. A macro-built rule function has
+ * neither `parse` nor `parseWithContext`, so it is not accepted. */
 type CompletionsTarget =
   | Combinator<unknown>
   | { parseWithContext(input: string, ctx: ParseContext, pos?: number): ParseResult<unknown> }
@@ -17,7 +17,7 @@ type CompletionsTarget =
  * highest-position failure seen, even when sepBy/many backtrack past the cursor.
  * Returns the expected tokens from that deepest failure.
  *
- * Works on the interpreter combinator OR a `compile(g, { recovery: true })` grammar
+ * Works on the interpreter combinator OR a `compile()`d grammar
  * (the probe is recorded on the compiled fast path). Returns an empty array when the
  * input up to `offset` parses completely with no failures at or before the cursor.
  *

package/src/combinators/gate.ts

@@ -15,7 +15,7 @@ import type { Combinator, ParseContext, ParseResult, ParserMeta } from '../types
  * Naming: this matches the `gate:` field on a gated CHOICE arm
  * (`choice({ gate, combinator }, other)`). Use the arm FIELD to SELECT a branch by
  * a cheap state predicate; use this COMBINATOR to ASSERT a state predicate
- * mid-sequence. Formerly named `guard()` — see the deprecated alias in `guard.ts`.
+ * mid-sequence. Formerly named `guard()`; that alias was removed in 0.45.0.
  *
  * Note: like all state predicates its first-set is `any`, so a `gate(...)` as the
  * LEADING term of a choice arm poisons that choice's first-char dispatch. Keep it

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

@@ -29,9 +29,8 @@ import { PARSEMAN_VERSION } from '../version.ts'
  *                       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), …)` at build time).
+ *                       already carries pieces as IR (`plugin/index.ts`) and the
+ *                       macro re-lowers them from it at build time.
  *
  * ── WHY THAT MAKES COMPOSITION THE EASY KIND ─────────────────────────────────
  * The open question was whether table-to-table composition has to merge two

package/src/compiler/degradation.ts

@@ -93,8 +93,8 @@ export function formatDegradations(list: readonly Degradation[]): string[] {
 //
 // 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.
+// Ctx and every compile*() return — the same shape as the source lowering's regex-lowering
+// sink, for the same reason.
 // ---------------------------------------------------------------------------
 //
 // A STACK, not a single slot. `transformMacro` re-enters itself when it lowers a private

package/src/compiler/linker.ts

@@ -25,9 +25,11 @@ import { copySpan } from '../line-index.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()`).
+ * import that artifact and `compose([...])` it — **no source of the base grammar is
+ * ever read**. Under the macro this is precompiled to static pieces, and only a
+ * build-time `compose()` can link it. In the interpreter it compiles here at load
+ * (like `compile()`) and keeps the map's `RULES_RECIPE`, which is what a runtime
+ * `compose()` links; an artifact without one is refused there (`recipesOf`).
  *
  * `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).

package/src/cst/capture-buffer.ts

@@ -270,8 +270,8 @@ export function rollbackCstCaptureAt(
   // speculative branch leaves no ghost error (see saveCstMark). Guarded on a
   // present sink + a defined mark (rollbackTrivia forwards the same field).
   //
-  // Each truncation is guarded on `length !== mark`, mirroring the compiled
-  // engine (codegen.ts `captureRestoreBody`). Assigning `array.length` runs V8's
+  // Each truncation is guarded on `length !== mark`, as the source lowering's
+  // `captureRestoreBody` did. Assigning `array.length` runs V8's
   // length setter — a backing-store trim decision — and costs the same when the
   // value is unchanged, which is the overwhelmingly common case here: a
   // speculative branch that captured nothing still pays for every store. The

package/src/cst/host-mode.ts

@@ -1,7 +1,7 @@
 /**
  * The compiled-artifact ↔ host contract, in ONE place.
  *
- * This lives on its own — rather than in `compiler/codegen.ts` where it started —
+ * This lives on its own — rather than in the source lowering where it started —
  * because the DRIVER has to enforce it too. `functional/run.ts` is the `parseman/run`
  * entry, whose whole purpose is to stay small (see `test/unit/run-entry-closure.test.ts`),
  * so it cannot import the compiler to reach an assertion. Neither can it carry its own

package/src/cst/root-trivia-scope.ts

@@ -2,7 +2,7 @@
  * The ROOT-CAPTURE POLICY of one local trivia scope, in one place.
  *
  * Three engines install a `parser({ trivia })` scope — the interpreter
- * (`combinators/grammar.ts`), source lowering (`compiler/codegen.ts`) and the
+ * (`combinators/grammar.ts`), the source lowering (removed in 0.47.0) and the
  * table (`table/assemble.ts`, `table/exec.ts`) — and each of them has to answer
  * the same two questions about selected root trivia. The refusal below was a
  * string literal in two of them and ABSENT from the third, which is how a table

package/src/language-service/index.ts

@@ -6,7 +6,7 @@
  * name = node type, without ever modifying the grammar:
  *
  *   - `parse(src, { tolerant })` → CST + `ParseError[]` (recovers on the compiled
- *     fast path when `grammar` is a `compile(g, { recovery: true })` grammar).
+ *     fast path when `grammar` is a `compile()`d grammar).
  *   - `diagnostics(src)` → structural parse errors + your per-node-type lint rules.
  *   - `completionsAt(src, offset)` → the grammar's expected-token set at the cursor,
  *     mapped through your per-rule semantic completion handlers.

package/src/plugin/entry-supercompiler.ts

@@ -1,5 +1,6 @@
 /**
- * Experimental build-time Entry/SCC supercompiler for static table assemblies.
+ * Build-time Entry/SCC supercompiler for the selective assemblies a macro build
+ * emits (it runs on every macro build that selects sites).
  *
  * The table emitter remains the sole semantic backend.  This pass parses that
  * backend's ordinary JavaScript and joins uniquely-owned piece functions with

package/src/plugin/index.ts

@@ -5,8 +5,9 @@
  *
  * For each such import, walks the file's AST, finds variable declarations
  * whose RHS is a pure parseman combinator call, evaluates them at build time,
- * compiles the result to an optimized inline function, and replaces the
- * declaration — removing the import entirely.
+ * compiles the result to a table program (plus generated code for its hottest
+ * sites, within `assemblyBudget`), and replaces the declaration. The macro import
+ * is removed; the module imports the shared driver from `parseman/table` instead.
  *
  * Usage:
  *   // vite.config.ts
@@ -61,7 +62,7 @@ import type {
  * The PUBLIC subpath, not a deep path into `src/`: this string is written into a
  * consumer's build output, so it has to be a specifier their resolver can see.
  * `parseman/table` is declared in package.json `exports` and re-exports
- * `tableRules` as `tableRules` (src/table/index.ts:28).
+ * `tableRules` unrenamed (`src/table/index.ts`).
  */
 const TABLE_RUNTIME_SPECIFIER = 'parseman/table'
 
@@ -119,13 +120,9 @@ export type ParsecraftPluginOptions = {
    */
   warnUnloweredRegex?: boolean
   /**
-   * Bake automatic list recovery into the macro-compiled output. **Default `false`.**
-   * When on, `many`/`oneOrMore`/`sepBy` in every compiled grammar gain a
-   * `_ctx._tolerant`-gated recovery branch (dormant on strict parses — a normal
-   * parse is unaffected and allocates nothing). The output stays macro-inlinable
-   * (sentinels build via `_ctx._rec`, not `_rp`). Turn it on for grammars you drive
-   * from an editor/language service so `run(g, src, { tolerant: true })` recovers on
-   * the fast compiled path; leave it off for build-only grammars.
+   * @deprecated Has no effect: every compiled table carries recovery, and
+   * `run(g, src, { tolerant: true })` recovers on the compiled path whatever this is
+   * set to. Removed in the next minor release.
    */
   recovery?: boolean
   /** Emit grammar-coverage hooks in macro output. Off by default, so ordinary
@@ -1456,9 +1453,8 @@ function transformMacroImpl(
 
   /**
    * Compile a `rules(factory)` call into ONE shared replacement expression
-   * for the whole call — see compileRuleMap() in codegen.ts for why this is
-   * one shared codegen pass instead of one `compile()` per entry (a `rules()`
-   * factory's entries commonly share large reachable sub-rule graphs; a
+   * for the whole call: one shared `compileRuleMap()` pass instead of one
+   * `compile()` per entry (a `rules()` factory's entries commonly share large reachable sub-rule graphs; a
    * shared pass compiles each shared sub-rule once instead of once per entry
    * that reaches it).
    */
@@ -1977,9 +1973,8 @@ function transformMacroImpl(
    * shadows the base piece which actually defines `Pair` — the encoder then finds a
    * hole where the winner should be and refuses the whole grammar with "ref() used
    * before .define()". The same filter guards `compileLinkableTable`'s `isLocal`
-   * (`compile-linkable-table.ts:96`), `itemCarried` (`linker.ts:696`) and
-   * `recoverComposedRules`; this is the fourth site that needs it, for the same
-   * reason, and skipping it is why cross-piece composition looked blocked.
+   * (`compile-linkable-table.ts`) and `recoverComposedRules`; this site needs it
+   * for the same reason, and skipping it is why cross-piece composition looked blocked.
    *
    * The reference itself is not lost: it stays inside the delta's own rule bodies and
    * `enc.winners` binds it BY NAME to whichever piece supplies the definition.

package/src/table/assemble.ts

@@ -4,7 +4,7 @@
  * This is ledger row G5 as stated: *"build the grammar reference at run start,
  * making the swaps on rules / sub-rules (leaves) at that point, then run with NO
  * logic branching for that option input"*. `exec.ts` builds the same table and
- * then interprets it: one `switch (code[ip])` over 29 opcodes, executed ONCE PER
+ * then interprets it: one `switch (code[ip])` over every opcode (29 then), executed ONCE PER
  * ROW — 497,360 rows for `benchmark.less` (`bench/jess/g5-rows.ts`) — each
  * re-reading its opcode and re-decoding its operands from the `Int32Array`, and
  * re-testing the same per-parse options. That is the per-node branching the
@@ -114,9 +114,8 @@ import { failCleanAnalysis } from './fail-clean.ts'
 /**
  * THE COMPLETIONS PROBE, at the terminal fail sites and nowhere else.
  *
- * `failAt` (combinators/probe.ts) is called from exactly three places in the
- * interpreter — `literal.ts`, `regex.ts`, `keywords.ts` — and codegen emits its
- * mirror (`probeUpdate`) at the same leaf-fail sites. The table recorded
+ * `failAt` (combinators/probe.ts) is called at the interpreter's terminal fail
+ * sites — `literal.ts`, `regex.ts`, `keywords.ts`, `lines.ts`. The table recorded
  * NOTHING, so `completionsAt` on a table artifact saw only the top-level
  * failure: a swallowed item failure inside a `sepBy` (`'{'` at offset 1 in a
  * `{ decl; }` grammar) never reached the probe and the item's opener vanished
@@ -438,7 +437,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
    * graph with no recovery in it anywhere.
    *
    * Dormancy is unchanged for the OTHER two engines: the source lowering
-   * (`codegen.ts:3153`) and the interpreter (`repeat.ts:163`) still gate on
+   * (removed in 0.47.0) and the interpreter (`repeat.ts:163`) still gate on
    * `ctx._tolerant` at runtime, and the recovery pieces below keep their own
    * `_tolerant === true` failure-path gates so `exec.ts` stays the identity
    * reference.
@@ -1914,8 +1913,8 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         const expectSpan = (ctx: ParseContext, pos: number) =>
           prog.lines === 1 ? spanLines(ctx, pos, pos) : new PlainSpan(pos, pos)
         // TOLERANT `expect()` EMBEDS ITS ERROR IN THE TREE, not only in the flat
-        // `_errors` side-channel (`combinators/expect.ts:150`, and codegen's
-        // `_ctx._rec.capture` at codegen.ts:4470) — so a tree walk finds every
+        // `_errors` side-channel (`combinators/expect.ts:150`, and the source
+        // lowering's `_ctx._rec.capture`) — so a tree walk finds every
         // diagnostic and the node survives incremental subtree reuse. The table
         // pushed to `_errors` and stopped, so a tolerant CST parse was missing the
         // `parseError` child the other two engines both produce.
@@ -2536,7 +2535,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
          *
          * The restore is `sequence()`'s `finally` (combinators/sequence.ts:105).
          * Codegen does not restore and compensates by having every list capture
-         * `_sync` at ENTRY (codegen.ts:3032); the table captures at entry too, so
+         * `_sync` at ENTRY; the table captures at entry too, so
          * this is unobservable either way — it is here because leaving a stale
          * sentinel published is the kind of state a later reader will trust.
          */
@@ -3479,7 +3478,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
          *    delimiter (`orSentinel`, repeat.ts:454).
          *  - `mySync` is captured at ENTRY. An element's own sequence publishes
          *    over `_sync` while it runs; the interpreter restores in a `finally`
-         *    and codegen saves at entry (codegen.ts:3032) — same value, both ways.
+         *    and the source lowering saved at entry — same value, both ways.
          *  - the separator-less path rolls the leading trivia back BEFORE
          *    recovering (repeat.ts's `repItem`), and the separated path does NOT:
          *    a consumed separator and the error after it both belong to the list
@@ -3903,7 +3902,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
           ctx._fields = wantFields ? [] : undefined
           // PER-NODE-TYPE TRIVIA-KIND MASK, scoped to the body and restored —
           // `node.ts:259-273`, and codegen's `_triviaCaptureMask` save/install/
-          // restore around the same scope (`codegen.ts:4130-4136`). The table
+          // restore around the same scope. The table
           // installed nothing, so a host that asked `Outer` for comments only got
           // every kind the scanner saw.
           const savedMask = structural ? ctx._triviaCaptureMask : undefined

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

@@ -19,7 +19,7 @@ import { runDuplicationDiagnosticRules, type DuplicationOption } from './duplica
  * `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`).
+ * plugin uses only for standalone combinators.
  * 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
@@ -29,7 +29,7 @@ import { runDuplicationDiagnosticRules, type DuplicationOption } from './duplica
  * ── 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
+ * (`evaluateRulesFactory` in `plugin/index.ts`), 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
@@ -59,6 +59,7 @@ export type TableRuleMapOptions = {
   readonly specialise?: boolean
   /** Grammar-level ambient scan-skip, as `rules({ scanSkip }, …)` declares it. */
   readonly scanSkip?: Combinator<unknown>[]
+  /** @deprecated Has no effect (see `TableSettings.recovery`). Removed in the next minor release. */
   readonly recovery?: boolean
   readonly hostMode?: HostMode
   readonly trackLines?: boolean
@@ -264,7 +265,7 @@ function encodeForRun(
 ): { 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.
+  // WINNERS ARE THE NON-`lazy` ENTRIES, exactly as the source lowering picked 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

package/src/table/compile.ts

@@ -79,8 +79,8 @@ export type TableCompileOptions = {
   readonly hostMode?: HostMode
   readonly trackLines?: boolean
   /**
-   * ACCEPTED AND IGNORED — recovery is ALWAYS lowered (see `TableSettings.recovery`).
-   * Kept so this stays a drop-in for `compile(g, …, { recovery: true })`.
+   * @deprecated ACCEPTED AND IGNORED — recovery is ALWAYS lowered (see
+   * `TableSettings.recovery`). Removed in the next minor release.
    */
   readonly recovery?: boolean
   /**
@@ -178,7 +178,7 @@ function compileRoot<T>(
 ): CompiledParser<T> {
   // Argument order mirrors `compile(combinator, mapFnSources?, opts?)` so this is
   // a drop-in, not a second API with a different shape.
-  // THE SAME WALK CODEGEN USES FOR A SINGLE ROOT (`codegen.ts:5377`): no winner
+  // THE SAME WALK THE SOURCE LOWERING USED FOR A SINGLE ROOT: no winner
   // map, so the paths are rooted at `entry` and the ids are the ones a caller
   // switching lowerings already has. Building it differently here would produce a
   // set that is internally consistent and lines up with nothing.

package/src/table/emit-assembly.ts

@@ -807,7 +807,7 @@ export function emitAssemblySource(
   const armExpectedPlan: number[][] = []
   const maskPlan: number[] = []
 
-  /** `codegen.ts`'s hoisted pools, same spelling: `_k<N>` / `_fx<N>` / `_fn<N>`. */
+  /** Hoisted pools, in the source lowering's spelling: `_k<N>` / `_fx<N>` / `_fn<N>`. */
   function hoist(kind: string, expr: string): string {
     const hit = pool.get(expr)
     if (hit !== undefined) return hit
@@ -1489,8 +1489,8 @@ return v
         const xf = fxRef(code[ip + 2]!)
         // TWO ARMS, mirroring `assemble.ts:1050`. A TOLERANT `expect()` EMBEDS
         // ITS ERROR IN THE TREE and not only in the flat `_errors` side-channel
-        // (`combinators/expect.ts:150`, codegen's `_ctx._rec.capture` at
-        // codegen.ts:4470) — so a tree walk finds every diagnostic and the node
+        // (`combinators/expect.ts:150`, the source lowering's
+        // `_ctx._rec.capture`) — so a tree walk finds every diagnostic and the node
         // survives incremental subtree reuse. `captureError` is the shared
         // function, called; the embedding is not restated here.
         //
@@ -2734,7 +2734,7 @@ return nd
   const ruleEntries: string[] = []
   for (const [rname, entryIp] of Object.entries(prog.rules)) {
     if (!served(entryIp)) continue
-    // `_r_<Name>` — the composition surface, in `codegen.ts`'s own spelling and
+    // `_r_<Name>` — the composition surface, in the source lowering's spelling and
     // deliberately NOT namespaced, so a sibling calls it by name.
     const target = link(entryIp)
     const rn = `_r_${rname.replace(/[^A-Za-z0-9_$]/g, '_')}`

package/src/table/emit.ts

@@ -15,9 +15,10 @@ export const FACTORY_ARITY_GUARD = `if(arguments.length<${EMITTED_PARAMS.length}
 /**
  * Print a program as the module a build emits.
  *
- * Everything here is DATA plus the author's own reducers. The recognizer is not
- * in this string — it is `exec.ts`, imported from the runtime, shared by every
- * grammar in the bundle and by every variant of each.
+ * Everything here is DATA plus the author's own reducers, and any assemblies
+ * the build pre-compiled (`a:`). The recognizer is not in this string: it is
+ * `tableRules` from `parseman/table`, shared by every grammar in the bundle and
+ * by every variant of each.
  */
 
 function jsString(s: string): string {
@@ -170,11 +171,10 @@ export function defaultAssemblyCfgs(prog: TableProgram): RunCfg[] {
  * Print the assemblies a build pre-compiled, as the `a:` field of the program
  * literal — see `TableProgram.asm`.
  *
- * THE FACTORY IS A REAL FUNCTION LITERAL. This is a low-level experiment, not
- * a normal compiler route: normal `compile()` and macro output both serialize
- * `a:[]` and use the compact closure assembler. If a future specialization can
- * meet semantic identity and the size budget, it must preserve that one public
- * artifact contract rather than recreate the old runtime/macro split.
+ * THE FACTORY IS A REAL FUNCTION LITERAL. A macro build emits one here for the
+ * AST, no-line-tracking option set, holding only the sites it selected within its
+ * budget (`compile-rule-map.ts`, `selectAssembly`); every other option set gets
+ * no entry and runs the closure assembler.
  *
  * A refusal is not an error. `Unemittable` names a construct the emitter does
  * not lower; that option set simply gets no entry, and `assemble.ts` runs the
@@ -186,7 +186,7 @@ function emitAssemblies(prog: TableProgram, cfgs: readonly AssemblyCfg[]): strin
    *
    * The field's PRESENCE is the compiler artifact contract. That is what switches
    * the runtime `Function` constructor off (`assemble.ts`), and it costs four
-   * bytes. Its CONTENTS are optional experimental factories; with none, the
+   * bytes. Its CONTENTS are the build's selected factories; with none, the
    * artifact runs the closure engine — no eval, no
    * size growth, and the refusal readable on `Assembly.emitRefusal`.
    *
@@ -248,12 +248,11 @@ export type EmitOptions = {
   /** Name of the exported binding. */
   readonly name?: string
   /**
-   * Optional experimental emitted factories — see `defaultAssemblyCfgs`.
+   * Emitted factories to pre-compile — see `defaultAssemblyCfgs`.
    *
-   * The normal compiler and macro both emit `a:[]`: that is the canonical
-   * compact closure artifact and it never reaches the `Function` constructor.
-   * Supplying factories here is a low-level serialization experiment, not a
-   * second normal compilation path; it is not used by the macro plugin.
+   * Without them the artifact prints `a:[]`, the compact closure artifact, which
+   * never reaches the `Function` constructor. The macro plugin passes one
+   * selective assembly here (`compile-rule-map.ts`, `replacementWithMetadata`).
    */
   readonly assemblies?: readonly AssemblyCfg[]
   /**