parseman 0.59.1 → 0.59.3

package/src/table/encode.ts

@@ -86,15 +86,14 @@ export type TableSettings = {
    * smaller, so the size argument for making it optional no longer holds.
    *
    * LOWERING RECOVERY IS NOT RUNNING IT. Every recovery path stays gated on
-   * `ctx._tolerant` — the same dormancy the source lowering emits
-   * (`codegen.ts:3153`) and the interpreter tests (`repeat.ts:163`) — so a strict
+   * `ctx._tolerant` — the same dormancy the source lowering (removed in 0.47.0)
+   * had and the interpreter tests (`repeat.ts:163`) — so a strict
    * parse is strict, and `test/parity/table-recovery-always.test.ts` pins that.
    *
-   * The field is kept rather than deleted so `compile` stays signature-
-   * compatible with `compile()`, whose `{ recovery: true }` is real. Passing it
-   * is harmless; passing `false` does NOT switch recovery off, and saying so here
-   * is the point — a setting that silently means nothing is the defect class this
-   * project keeps finding.
+   * @deprecated The field is kept only so existing callers still type-check, and
+   * is removed in the next minor release. Passing `false` does NOT switch recovery
+   * off, and saying so here is the point — a setting that silently means nothing is
+   * the defect class this project keeps finding.
    */
   readonly recovery?: boolean
   /**
@@ -531,8 +530,8 @@ class Encoder {
   /**
    * The class of the follow set of term `i` in a sequence — the sync sentinel a
    * list nested in that term resyncs to, INFERRED from structure exactly as
-   * `sequence()` (combinators/sequence.ts:58) and `emitSeqValues`
-   * (compiler/codegen.ts:1756) infer it: the union of every LATER term's first
+   * `sequence()` (combinators/sequence.ts:58) and the source
+   * lowering's `emitSeqValues` infer it: the union of every LATER term's first
    * set, not merely up to the first non-nullable one, so a mandatory middle term
    * cannot hide a later close. −1 where there is no usable sentinel, which is the
    * same set of cases `firstSetSentinel` answers `null` for.
@@ -1009,7 +1008,7 @@ class Encoder {
     }
     const patches: number[] = []
     this.pending.set(p, patches)
-    // A RULE IS CREDITED ON ENTRY, not on success — `codegen.ts:4529` emits the
+    // A RULE IS CREDITED ON ENTRY, not on success — the source lowering emitted the
     // hook as the first statement of the named function body, so a rule that is
     // reached and then fails still counts as exercised. The counter goes on the
     // MEMOISED offset, which is the one every reference to this combinator lands
@@ -1662,7 +1661,7 @@ class Encoder {
         // A `kinds` LIST IS VALIDATED HERE, at encode time, against the trivia
         // table in scope — the same `resolveAdjacencyKindMask` the interpreter
         // calls on first reach and codegen calls while emitting the `_akN` probe
-        // (`codegen.ts:1034`). Deferring it to the driver's parse-time resolution
+        // (in the source lowering). Deferring it to the driver's parse-time resolution
         // left `compile()` accepting a grammar whose kind name no active table
         // declares: an unlabelled table or a typo'd category compiled clean and
         // threw only when an input happened to reach the assertion.
@@ -1724,7 +1723,7 @@ class Encoder {
       }
       // A LABEL IS A ROW — see `OP_LABEL`. It replaces the child's expected set,
       // which is the entire combinator.
-      // A LABEL IS CREDITED ON SUCCESS, as `codegen.ts:4530` credits it: its hook
+      // A LABEL IS CREDITED ON SUCCESS, as the source lowering credited it: its hook
       // is emitted AFTER the child's statements, where a failed child has already
       // broken out of the labelled block.
       case 'label':
@@ -1782,8 +1781,8 @@ class Encoder {
         // Bit 1 is the STRICT-SCOPE refusal `grammar.ts:98` raises: with selected
         // root trivia active, a local scope whose trivia is not classified and is
         // not declared opaque cannot be reported faithfully, so it throws rather
-        // than silently dropping markers. Codegen emits the same throw
-        // (codegen.ts:4705); the table emitted nothing at all.
+        // than silently dropping markers. The source lowering emitted the
+        // same throw; the table emitted nothing at all.
         const flags = (d.rootCapture === 'opaque' ? 1 : 0)
           | (d.triviaParser !== undefined
             && d.triviaParser._meta.rootTriviaClassified !== true
@@ -1938,7 +1937,7 @@ class Encoder {
  *
  * TRACKING IS A WHOLE-TABLE DECISION, as it is a whole-compile decision for the
  * source lowering: `ctx.lineTracking` is `opts.trackLines || grammarTrackLines ||
- * hasLineTrackingDef(combinator)` (`compiler/codegen.ts`). The table read the
+ * hasLineTrackingDef(combinator)` (the source lowering). The table read the
  * SETTING alone and refused any `parser({ trackLines: true }, …)` scope it found
  * underneath, so a grammar that carries its own tracking compiled through
  * codegen and was rejected by the encoder. Same question, same answer.

package/src/table/exec.ts

@@ -30,9 +30,8 @@ import { failAt } from '../combinators/probe.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
@@ -552,7 +551,7 @@ function makeDriver(
         const err = { _tag: 'parseError' as const, span, expected: fx[code[ip + 2]!] as string[] }
         ctx._errors?.push(err)
         // A TOLERANT `expect()` also embeds the error in the TREE (expect.ts:150,
-        // codegen.ts:4470), so a tree walk finds every diagnostic and it survives
+        // as the source lowering did), so a tree walk finds every diagnostic and it survives
         // incremental subtree reuse — the flat sink alone is not the contract.
         if (REC && ctx._tolerant === true) captureError(ctx, err)
         // See assemble.ts OP_EXPECT: the recovered failure is a SUCCESS, so the
@@ -1222,7 +1221,7 @@ function makeDriver(
         // TOLERANT RECOVERY, dormant unless `ctx._tolerant`. `mySync` is captured
         // at ENTRY because an element's own sequence publishes over `_sync` while
         // it runs — the interpreter restores in a `finally` (sequence.ts:105) and
-        // codegen saves at entry (codegen.ts:3032); either way this is the list's
+        // the source lowering saved at entry; either way this is the list's
         // own sync. The item's expected set is at ip + 6 and the separator's
         // sentinel class at ip + 7, both laid down only for a recovery table.
         const mySync = REC ? ctx._sync : undefined

package/src/table/ops.ts

@@ -1,26 +1,26 @@
 /**
  * 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` — `k` indexes a string in the const pool. */
+/** `LIT k fx` — `k` indexes a string in the const pool; `fx` the expected set on failure. */
 export const OP_LIT = 1
-/** `RX k` — `k` indexes a STICKY `RegExp` in the const pool. */
+/** `RX k fx` — `k` indexes a STICKY `RegExp` in the const pool; `fx` as `LIT`. */
 export const OP_RX = 2
 /** `SEQ n c1 … cn` — n child offsets; value is the array of their values. */
 export const OP_SEQ = 3
@@ -80,9 +80,9 @@ export const OP_XFORM = 9
 export const OP_NODE = 10
 /** `RULE r` — `r` indexes `prog.rules`. */
 export const OP_RULE = 11
-/** `GATE cc c` — first-char gate: `cc` indexes a char class; then run `c`. */
+/** `GATE cc c fx` — first-char gate: `cc` indexes a char class; then run `c`. `fx` is the set reported when the gate rejects. */
 export const OP_GATE = 12
-/** `NOT c` — zero-width negative lookahead. */
+/** `NOT c fx` — zero-width negative lookahead; `fx` is the assertion's own set, as `PEEK`. */
 export const OP_NOT = 13
 /**
  * `PEEK c fx` — zero-width positive lookahead. `fx` is the ASSERTION's own set,
@@ -201,10 +201,10 @@ export const OP_LIT_CI_TRACK = 28
  */
 export const OP_TOKEN = 29
 /**
- * `SCOPE_CAP k c` — a `parser({ trivia, captureTrivia: true })` scope. Identical
+ * `SCOPE_CAP k c policy` — a `parser({ trivia, captureTrivia: true })` scope. Identical
  * operands to `SCOPE`; it additionally sets `ctx.captureTrivia` for the child.
  *
- * A SEPARATE OPCODE rather than a third operand on `SCOPE`, for two reasons.
+ * A SEPARATE OPCODE rather than another operand on `SCOPE`, for two reasons.
  * Widening an instruction means every walker that knows its shape has to learn
  * the new one, and there is no central arity table here to change in one place.
  * And the driver should SELECT this piece, not test a flag inside the scope
@@ -257,7 +257,7 @@ export 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
@@ -367,7 +367,7 @@ export 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.
@@ -436,7 +436,7 @@ export 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/src/table/program.ts

@@ -29,10 +29,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.
@@ -145,9 +145,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/src/table/stamp.ts

@@ -173,7 +173,7 @@ export function stampRuleMap(
         // `committed` IS PART OF THE FAILURE ENVELOPE, not a diagnostic extra.
         // The interpreter carries it on the result (`{ ok: false, …, committed: true }`)
         // and codegen re-derives it from the same bit this driver uses
-        // (`codegen.ts`: `...(_ctx._fc ? { committed: true } : {})`). The table
+        // (`...(_ctx._fc ? { committed: true } : {})`). The table
         // dropped it, so a table entry embedded as a CHILD of another parser — the
         // one place the field is read rather than merely reported — lost the cut.
         return committed(ctx)

package/src/types.ts

@@ -569,7 +569,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/src/version.ts

@@ -4,13 +4,13 @@
  *
  * ── 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 const PARSEMAN_VERSION = '0.59.1'
+export const PARSEMAN_VERSION = '0.59.3'