parseman 0.46.0 → 0.47.0

package/dist/spec/model.d.ts

@@ -128,6 +128,14 @@ export type SpecOptions = {
     regexDisplay?: (source: string, flags: string) => string | undefined;
 };
 export type GrammarInput = Record<string, Combinator<unknown>> | Combinator<unknown>;
+/**
+ * The fixed string(s) a regex matches — the terminal its author actually wrote —
+ * or `undefined` when the pattern has real structure. Handles the three shapes
+ * that spell a keyword: a bare literal, a literal guarded by a trailing word
+ * boundary (`word()` / `keywords()` and every hand-written copy of them), and a
+ * `\b…\b`-anchored word.
+ */
+export declare function fixedStringsOfRegex(source: string): string[] | undefined;
 /**
  * Build the notation-agnostic spec model from a `rules()` grammar (or a single
  * combinator). Following every referenced named rule keeps the closure complete;

package/dist/spec/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/spec/model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,aAAa,CAAA;AAQxD,qEAAqE;AACrE,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE;AACvC,oEAAoE;GAClE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE;AAChD;qEACqE;GACnE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AACjC;;;;GAIG;GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE;AACjG,sDAAsD;GACpD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC/B;;;;GAIG;GACD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE;AACtD,iFAAiF;GAC/E;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AACjC,4DAA4D;GAC1D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AAClC,oEAAoE;GAClE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACtC,gEAAgE;GAC9D;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAA;AAErB,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,QAAQ,CAAA;IACd,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAA;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;CACrE,CAAA;AAED,MAAM,MAAM,YAAY,GACpB,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,GACnC,UAAU,CAAC,OAAO,CAAC,CAAA;AAkSvB;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,WAAgB,GAAG,SAAS,CA4C1F"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/spec/model.ts"],"names":[],"mappings":"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"}

package/dist/table/assemble.d.ts

@@ -0,0 +1,307 @@
+/**
+ * THE ASSEMBLER — the table, LINKED into closures instead of interpreted.
+ *
+ * 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
+ * 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
+ * design exists to remove.
+ *
+ * ## The shape
+ *
+ * Assembly walks the reachable table ONCE and lowers each site to a PIECE: a
+ * closure with its operands already captured as `const`s and its children bound
+ * as DIRECT references to their own pieces. At parse time there is no opcode
+ * read, no operand decode and no switch — a piece is called, and it calls the
+ * pieces it holds.
+ *
+ * The numbers that make this obviously the right trade, measured not assumed:
+ *
+ *   2,241  distinct reachable sites in the less table (`bench/jess/g5-sites.ts`)
+ * 497,360  rows executed for one parse of `benchmark.less`
+ *
+ * Pieces are GRAMMAR-sized; rows are INPUT-sized. Assembly allocates ~2.2k
+ * closures once per process and removes a dispatch plus an operand decode from
+ * ~497k executions — a 222x ratio. Assembly cost is paid once and is not the
+ * metric; it is measured anyway (`bench/jess/g5-ms.ts`, `bench/jess/g5-profile.ts`).
+ *
+ * ## Why this is not "just tuning the switch"
+ *
+ * A 29-case switch on an `Int32Array` load is a jump table whose successor V8
+ * cannot know. The interpreter loop is ONE basic block with 29 merge edges, so
+ * TurboFan cannot specialise any arm against its caller and every operand stays
+ * an untyped load. Measured on this branch: `exec` reaches TURBOFAN and is
+ * deoptimised back to MAGLEV repeatedly — 100 deopt events in a 20-parse run.
+ * The design was not paying dispatch overhead, it was opting its whole hot path
+ * out of the optimising compiler.
+ *
+ * A piece is created once and its call sites see one shape, so they stay
+ * monomorphic and TurboFan can inline them. That is the structural win, and it is
+ * why the target is codegen's number rather than a fraction of the gap.
+ *
+ * ## Why this keeps the artifact small
+ *
+ * The pieces ship ONCE, here, shared by every grammar and every variant. What a
+ * bundle carries is still the table — DATA. Codegen's 2.10 MB is recognition
+ * machinery inlined bespoke per rule; this stays at the table's 0.56 MB because
+ * the machinery is one copy in the runtime and the variation lives in the
+ * ASSEMBLY, not in duplicated piece bodies.
+ *
+ * ## Options are consumed by SELECTION, not by testing
+ *
+ * The piece set is a SUPERSET; an option set reaches a subset of it. Assembly
+ * walks from the entry rule and instantiates only what it touches, so a piece an
+ * option excludes is never allocated, never linked and costs zero at run — not a
+ * cheap branch, zero. Where a decision is knowable from the option set
+ * (`hostCst` below), assembly picks the piece rather than emitting one that
+ * tests. `scripts/check-invariants.mjs` enforces that no piece body reads a
+ * config field; see `CONFIG_FIELDS` there.
+ *
+ * Semantics are `exec.ts`'s, case for case. That file remains the reference and
+ * the three-way identity sweep gates this against it.
+ */
+import type { Combinator, ParseContext } from '../types.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
+ * 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
+ * from the completion set.
+ *
+ * Dormant unless `completionsAt` set `_probe`, so an ordinary parse pays one
+ * property read per terminal miss — the same price codegen pays.
+ */
+import { type CompactProgram, type ResolvedTable, type TableProgram, type TableRule } from './program.ts';
+/**
+ * THE PIECE SIGNATURE — uniform, narrow, and the same for every one of the 29
+ * lowerings.
+ *
+ * Three arguments and one return, so every call site in the assembled graph sees
+ * one shape and stays monomorphic. A wider or varying signature (an out-param
+ * object, a per-op return shape) reintroduces the polymorphism this design
+ * exists to remove, and it would show up as exactly the megamorphic call sites
+ * `exec`'s switch already was.
+ *
+ * The end position travels in the assembly-scope `EC.e` slot, as it does in
+ * `exec.ts` and in codegen's `_pfEnd`, rather than in the return value — a
+ * `{ value, end }` pair would be an allocation per row.
+ */
+type Piece = (input: string, pos: number, ctx: ParseContext) => unknown;
+/**
+ * The option set an assembly is specialised for.
+ *
+ * These are the facts `run()` fixes BEFORE the entry is called and that never
+ * change during a parse, so they are resolved by choosing a piece rather than by
+ * a test inside one. Anything that varies DURING a parse (position, the capture
+ * sinks a `node()` opens and closes, the error sink's contents) is runtime and
+ * stays where it is.
+ */
+export type RunCfg = {
+    /** Is this parse's host a CST-output host? Fixes `OP_NODE`'s whole shape. */
+    readonly hostCst: boolean;
+    /**
+     * Does the structural host consume the semantic `children` array? `false`
+     * selects raw-only node collectors. Collapse forces this back to true at the
+     * run boundary because its predicate consumes both child views.
+     */
+    readonly hostReadsChildren?: boolean;
+    /**
+     * Structural node types whose host consumes trivia. Evaluated while an
+     * assembly is built, once per node site, never from the node execution path.
+     * Absent means the backwards-compatible default: capture every structural
+     * node's trivia.
+     */
+    readonly hostCaptureTrivia?: ((type: string) => boolean) | undefined;
+    /** `ctx.trackLines` — decides whether the trivia leaf swap is legal at all. */
+    readonly trackLines: boolean;
+    /**
+     * `ctx._tolerant` — is THIS parse allowed to recover?
+     *
+     * FIXED FOR THE LIFETIME OF A PARSE, which is what makes it legal here rather
+     * than a per-piece test. Every writer of `ctx._tolerant` sets it BEFORE the
+     * parse begins and never during — `compile.ts:119` (`parseWithErrors`),
+     * `functional/run.ts:399`, `functional/doc.ts:29`, `combinators/completions.ts:40`.
+     * The single mid-parse mutation is `recovery/scan.ts:36`, which CLEARS it for
+     * the duration of a sentinel probe and restores it in `finally`; a sentinel is
+     * a `firstSetSentinel` char-class combinator (or an `orSentinel` of two), never
+     * an assembled rule, so no piece runs under the cleared value. Even if one did,
+     * the selection would be the RIGHT one: a probe must not recover, and it would
+     * get the strict assembly.
+     *
+     * Contrast `cstCaptureActive`, which a previous lane proposed for the same
+     * treatment and which is per-NODE state — keying on that would have been
+     * incorrect, not merely redundant.
+     */
+    readonly tolerant: boolean;
+    /**
+     * `ctx._grammarCoverage` — is THIS parse counting grammar coverage?
+     *
+     * FIXED FOR THE LIFETIME OF A PARSE, checked the same way `tolerant` was. There
+     * are exactly two writers — `createGrammarInstrumentationContext` (coverage.ts),
+     * which builds the field into a FRESH context object before any parse, and
+     * `functional/run.ts:403`, which installs it on the context it is about to run
+     * — and no reader anywhere mutates or clears it, mid-parse or otherwise.
+     * `createParseContext` initialises it to `undefined` once, at construction.
+     *
+     * So it is per-PARSE, unlike `ctx._cstBuf`, which a previous lane proposed
+     * keying on and which `beginCstNodeCapture`/`endCstNodeCapture` replace per
+     * NODE — that selection would have been incorrect, not merely redundant.
+     *
+     * An ordinary table has no `OP_COV` rows at all, so this bit selects a DIFFERENT
+     * assembly only for a table encoded with a coverage plan. For every other table
+     * the two assemblies are identical work and the extra bit costs one cache slot.
+     */
+    readonly coverage: boolean;
+    /**
+     * `ctx._probe !== undefined` — is THIS parse feeding a completions probe?
+     *
+     * FIXED FOR THE LIFETIME OF A PARSE, on exactly the evidence `tolerant` is
+     * held to. The two writers both install it BEFORE the parse begins and never
+     * during — `combinators/grammar.ts:213` (built in `run()`'s prologue when
+     * `recover` is set) and `combinators/completions.ts:38`. The single mid-parse
+     * mutation is `recovery/scan.ts:29`, which CLEARS it for the duration of a
+     * sentinel probe and restores it in `finally`; a sentinel is a
+     * `firstSetSentinel` char-class combinator, never an assembled rule, so no
+     * piece runs under the cleared value. Even if one did the selection would be
+     * the RIGHT one — a sentinel probe must fail fast, and it would get the
+     * strict assembly.
+     *
+     * It is here for `OP_GATE`, which is the only piece that reads it on a
+     * SUCCESS path. The six leaf sites read it after their own `return`, on the
+     * failure path only, and are deliberately left alone: selecting a second body
+     * per literal length to remove a failure-path test would double the runtime's
+     * literal bodies to buy nothing measurable.
+     */
+    readonly probe: boolean;
+};
+/** The cfg key an assembly is cached under. */
+export declare function cfgKey(c: RunCfg): number;
+export type Assembly = {
+    /** One entry piece per rule name, already linked. */
+    readonly pieces: Readonly<Record<string, Piece>>;
+    readonly end: () => number;
+    /**
+     * Per-parse reset. What `exec.ts`'s `begin` DECIDED here (`trackLines`, the
+     * host mode) is exactly what assembly resolved, so all that is left is
+     * clearing the installed scanner and latching the host value.
+     */
+    readonly begin: (ctx: ParseContext) => void;
+    /** Close an invocation and restore a suspended re-entrant frame, if any. */
+    readonly finish: () => void;
+    readonly scanSkip: readonly (readonly Combinator<unknown>[])[];
+    /**
+     * The sites this option set actually REACHED. A strict subset of the table's
+     * reachable set whenever an option excludes anything, and the assertion
+     * `test/unit/table-assemble.test.ts` makes on that.
+     */
+    readonly reached: ReadonlySet<number>;
+    /**
+     * WHY THIS ASSEMBLY IS RUNNING CLOSURES, when it is.
+     *
+     * `undefined` means the emitted engine (`emit-assembly.ts`) built this
+     * assembly. A string names the construct it refused. It is a field rather
+     * than a log line because a grammar that quietly drops to the closure path
+     * is a permanently slow path nobody would ever find — the same failure
+     * `encode.ts:1208-1213` refuses to allow for `OP_LIVE`.
+     */
+    readonly emitRefusal: string | undefined;
+};
+/**
+ * Link one resolved table, for one option set, into a graph of closures.
+ *
+ * ONE walk. Each site is lowered at most once and memoised by its code offset,
+ * so a subtree shared by two parents is one piece with two references to it.
+ */
+export declare function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Assembly;
+/**
+ * Assemblies for one resolved table, one per option set, built on demand.
+ *
+ * The option set is not known when the rule map is created — `ctx.build`,
+ * `ctx.trackLines` and `ctx._tolerant` arrive with the parse — so the entry
+ * computes the scalar key and takes the assembly for it, building it the first
+ * time that combination is seen. That is the "assembled at run start" half of G5:
+ * only the option combinations a process actually uses, each holding the pieces
+ * its options reach. A process that never parses tolerantly never builds, and
+ * never runs, a single recovery piece.
+ */
+export declare class AssemblyCache {
+    private readonly t;
+    private readonly prog;
+    private readonly byCfg;
+    /**
+     * Monomorphic predicate inline cache. An assembly depends on the predicate
+     * FUNCTION and the scalar cfg key, not on the host object that carries it, so
+     * retaining the host would add neither correctness nor reuse. Stable parsing
+     * is one identity comparison plus an array index; replacing the predicate
+     * replaces this specialisation without retaining either host.
+     */
+    private hostPredicate;
+    private hostAssemblies;
+    constructor(prog: TableProgram, resolved?: ResolvedTable);
+    for(cfg: RunCfg): Assembly;
+    /**
+     * The assembly for the option set this `ctx` implies.
+     *
+     * ─── WHY THIS IS NOT A VIOLATION OF "NO OPTION READS AT PARSE TIME" ─────────
+     *
+     * The rule that shaped 0.47 is that consulting an option PER RULE or PER
+     * COMBINATOR is a fail, and the reason it is a fail is that such a consult
+     * scales with the input. This one does not, and the previous defence of it —
+     * "cheap, allocation-free, only once" — was the wrong argument, because
+     * cheapness is not the criterion. The right argument is that the consult is
+     * IRREDUCIBLE, and it is worth stating precisely so nobody re-opens it:
+     *
+     *   A table entry has the artifact signature `(input, pos, ctx)`, shared with
+     *   codegen. All scalar option bits live on that `ctx`, and every one of them is
+     *   supplied PER CALL by the caller — `run()` takes `tolerant`, `build` and
+     *   `instrumentation` as options on an artifact it was handed;
+     *   `combinators/grammar.ts` sets `trackLines` on scope entry;
+     *   `completionsAt` installs `_probe`. So the option set is not knowable
+     *   before the call, and a selection that cannot happen before the call must
+     *   happen at it.
+     *
+     * That is not a hole in G5, it is G5's own first clause: "quickly building the
+     * grammar reference ON RUN START, making some swaps on rules or sub-rules, and
+     * then the run actually runs with no logic branching for that option input"
+     * (`notes/TABLE-DRIVER.md`). This IS the run-start step. What the criterion
+     * forbids is the second sentence, and past this call there is no option read
+     * anywhere — `scripts/check-invariants.mjs` INV-6 decides that mechanically.
+     *
+     * MEASURED, not asserted: exactly ONE call per entry invocation, including
+     * `benchmark.less` at 106,802 bytes. Eliminating it would require binding the
+     * option set to the ARTIFACT rather than to the CALL, which is a change to the
+     * public run API (the map would have to hand back a cfg-keyed family and
+     * `run()` index it), not a change to this file.
+     *
+     * It allocates nothing: the key is packed from the ctx's own bits by `cfgKeyOf`,
+     * which takes them as arguments precisely so no `RunCfg` need exist here — that
+     * object is built only on the miss that builds an assembly. A host trivia
+     * predicate additionally selects its identity-specialised inline cache
+     * because a function cannot be represented by a scalar bit.
+     *
+     * DO NOT CACHE THE RESULT ACROSS CALLS. Keying it on anything but the `ctx`'s
+     * own option bits is how `tableRules` handed a strict parse the PREVIOUS
+     * parse's tolerant assembly (`test/unit/table-assemble.test.ts`).
+     */
+    forCtx(ctx: ParseContext): Assembly;
+}
+/**
+ * The ASSEMBLED rule map — the same artifact contract as `tableRules`, run
+ * through linked closures instead of the bytecode interpreter.
+ *
+ * THE ONE config read is HERE, at the boundary, once per entry invocation:
+ * `AssemblyCache.forCtx` turns the `ctx` into a scalar option set and takes the
+ * assembly built for it. Everything past that point is pieces, and no piece body
+ * reads an option — `scripts/check-invariants.mjs` INV-6 asserts it. `forCtx`
+ * carries the argument for why that read is irreducible rather than merely cheap.
+ */
+export declare function tableRules(source: TableProgram | CompactProgram, artifactMetadata?: Readonly<Record<symbol, unknown>>): Record<string, TableRule>;
+export {};
+//# sourceMappingURL=assemble.d.ts.map

package/dist/table/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/table/assemble.ts"],"names":[],"mappings":"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"}

package/dist/table/cell.d.ts

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

package/dist/table/cell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell.d.ts","sourceRoot":"","sources":["../../src/table/cell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,qEAAqE;AACrE,eAAO,MAAM,IAAI,EAAE,OAAO,MAA0B,CAAA;AACpD,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAA;AAE9B;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG;IAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnC,eAAO,MAAM,UAAU,QAAO,OAAqB,CAAA"}

package/dist/table/child-slots.d.ts

@@ -0,0 +1,30 @@
+/**
+ * THE EDGE TABLE. Which operand slots of an instruction are CHILD instructions.
+ *
+ * This is one fact about the operand layout, and it was written twice: once in
+ * `site-labels.ts` over the 35 opcodes `emit-assembly.ts` lowers, once fused into
+ * `inspect.ts`'s `reachableIps` traversal over all 40. The two agreed slot-for-slot
+ * on every opcode both covered — which is the problem, not the reassurance. Adding
+ * an opcode meant editing two switches in two files, and NOTHING failed if you
+ * edited one. `site-labels.ts`'s own header names that failure mode, then guards
+ * only against it happening WITHIN that file.
+ *
+ * The subset was never load-bearing. The five opcodes it omitted — COV, GREEDY,
+ * REJECT, ARMGATE, WITHCTX — are exactly the five `emit-assembly.ts` has no case
+ * for, so any program containing one throws `Unemittable` from the default arm and
+ * the whole assembly falls back to closures. Walking into their subtrees can
+ * therefore only affect a result that is about to be discarded. (Verified: none of
+ * the five is so much as imported by `emit-assembly.ts`. Its one consumer of these
+ * edges, the `fd`/`er` sink census, is computed before the lowering that throws.)
+ *
+ * `code` is `ArrayLike<number>` because the two callers hold different
+ * representations of the same stream — `TableProgram.code` is a `readonly number[]`,
+ * `ResolvedTable.code` is an `Int32Array`.
+ *
+ * Returns false for an opcode this table does not know, so each caller keeps its own
+ * answer to that: `inspect.ts` throws (a program it cannot decode is a bug it must
+ * report), `site-labels.ts` ignores it (an unwalked site resolves to `TOP` via
+ * `labelAt`, and the enclosing assembly is unemittable anyway).
+ */
+export declare function childSlots(code: ArrayLike<number>, ip: number, out: number[]): boolean;
+//# sourceMappingURL=child-slots.d.ts.map

package/dist/table/child-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-slots.d.ts","sourceRoot":"","sources":["../../src/table/child-slots.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CA4EtF"}

package/dist/table/compile-rule-map.d.ts

@@ -0,0 +1,136 @@
+import type { Combinator } from '../types.ts';
+import type { HostMode } from '../cst/host-mode.ts';
+import { type GrammarReflection } from '../cst/reflection.ts';
+import type { TableProgram, TableRule } from './program.ts';
+import { type GrammarCoverageDefinition } from '../compiler/grammar-coverage-ids.ts';
+import { type DuplicationOption } from './duplication-hook.ts';
+/**
+ * `compileRuleMap()` FOR THE TABLE LOWERING — the counterpart that did not exist.
+ *
+ * `compile` covered `compile()`, the SINGLE-ROOT entry point, which the
+ * plugin uses only for standalone combinators (`plugin/index.ts:1693`, `:1870`).
+ * The main path — every `rules()` grammar — goes through `compileRuleMap`, and
+ * with no table counterpart there was nothing for the macro build to point at.
+ * This is that function, and it is the EASY direction: `encodeTable` takes a
+ * named rule map natively, so nothing here adapts a shape. `compile` is the
+ * one that adapts (it wraps a root as `{ Entry: root }`).
+ *
+ * ── THE CONTRACT IT MATCHES ──────────────────────────────────────────────────
+ * `compileRuleMap` returns ONE `replacement` string: a self-contained expression
+ * that the plugin splices over the whole `rules(factory)` call-expression
+ * (`plugin/index.ts:1753`, and as an initialiser at `:1941`), evaluating ONCE to
+ * the `{ name: fn, … }` map. `keys` is the entry list, for the caller to check
+ * against the source's own keys. `hostMode` / `hostBranchElided` are what the
+ * macro stamps the emitted map with. `reflection` is per-grammar CST node
+ * reflection. It returns `null`, all-or-nothing, when the map cannot be inlined.
+ *
+ * Every one of those is reproduced here, with ONE stated divergence, the same
+ * one `compile` documents: the expression references `tableRules` and is
+ * therefore NOT self-contained. That reference is the entire reason a table
+ * artifact is small; inlining the driver per grammar rebuilds exactly the size
+ * this lowering exists to remove. The consumer owns the import.
+ *
+ * ── WHY `emitTableModule` WAS NOT ENOUGH ─────────────────────────────────────
+ * It emits a whole rule map as one module — `import` line, `export const` — and
+ * the plugin has no module to write; it has an expression slot inside an
+ * existing file. `emitTableExpression` was the right emitter and needed one
+ * thing: `entry: null`, meaning "the map itself" rather than one rule out of it.
+ * That is a two-line change to an existing emitter, not a new one.
+ */
+export type TableRuleMapOptions = {
+    /** Grammar-level ambient trivia, as `rules({ trivia }, …)` declares it. */
+    readonly trivia?: Combinator<unknown>;
+    /** Grammar-level ambient scan-skip, as `rules({ scanSkip }, …)` declares it. */
+    readonly scanSkip?: Combinator<unknown>[];
+    readonly recovery?: boolean;
+    readonly hostMode?: HostMode;
+    readonly trackLines?: boolean;
+    /**
+     * GRAMMAR-COVERAGE COUNTERS. This is the MACRO's path — `plugin/index.ts` passes
+     * `coverage: grammarCoverage` here for every `rules()` grammar — so this is what
+     * makes `{ grammarCoverage: true }` a working build under the table lowering.
+     *
+     * COUNTERS ONLY, per the owner ruling recorded in `notes/RELEASE-0.48-TARGET.md`
+     * §1; `_grammarTrace` parity is 0.48 work. The plugin's coverage path needs the
+     * DEFINITIONS STAMP and the HITS, and both are here.
+     */
+    readonly coverage?: boolean;
+    /** Identifier the emitted expression expects `tableRules` to be bound to. */
+    readonly runtimeRef?: string;
+    /**
+     * Reducer sources in `prog.fns` order, for a caller that holds them OUT OF
+     * BAND — the same escape `compile(combinator, mapFnSources?)` provides.
+     *
+     * The encoder captures a source per callback from the def (`fnSrc` /
+     * `buildSrc` / `predSrc` / `gateSrcs`), which the macro evaluator sets and a
+     * runtime-built combinator does not have. Supplying them here is what lets a
+     * grammar constructed at runtime still PRINT; it does not override captured
+     * ones, it fills in for a pool that has none.
+     */
+    readonly fnSources?: readonly string[];
+    /**
+     * WHY THIS REFUSED, filled in on the `null` return.
+     *
+     * `null` means "leave this grammar interpreted", which is ~79 ms against ~14 ms
+     * on `benchmark.less` — a ~5x regression that produces no test failure and no
+     * warning content beyond "couldn't be inlined". The reasons exist inside the
+     * encoder (`prog.runtimeOnly`) and simply had no way out; this is that way out,
+     * so the plugin's warning can name the construct instead of the outcome.
+     *
+     * An out-parameter rather than a changed return type: every existing caller
+     * checks for `null` and that contract is unchanged.
+     */
+    readonly refusals?: string[];
+    /**
+     * The structural duplication diagnostic. Ran inside the source lowering; it runs
+     * here for the same reason, so a build that asked for it keeps getting it.
+     */
+    readonly duplication?: DuplicationOption;
+};
+export type CompiledRuleMapTable = {
+    /** Every entry this saw, in order — same use as `compileRuleMap`'s `keys`. */
+    keys: string[];
+    /** The expression that replaces the whole `rules(factory)` call. */
+    replacement: string;
+    /** Re-emit the same table call with construction-time artifact metadata. */
+    replacementWithMetadata(metadataSource: string): string;
+    hostMode: HostMode;
+    hostBranchElided: boolean;
+    reflection: GrammarReflection;
+    /**
+     * The RUNNABLE map, which the source lowering has no counterpart for — it
+     * hands back text and nothing else, because its artifact only exists once the
+     * emitted source is evaluated. A table exists as data before it is printed, so
+     * the same call that produces the replacement can also hand back the parser.
+     * That is what makes a differential against the interpreter possible without
+     * `eval`, and it is why the table-vs-interpreter test can compare `expected`
+     * sets rather than only accept/reject.
+     */
+    rules: Record<string, TableRule>;
+    /** The encoded program, for a caller that wants to fold or inspect it. */
+    prog: TableProgram;
+    /**
+     * The coverage DENOMINATOR — every id this map can hit — present only under
+     * `{ coverage: true }`. Same field and same meaning as `compileRuleMap`'s, so
+     * the plugin's stamp site needs no branch on which lowering produced it.
+     */
+    coverageDefinitions?: readonly GrammarCoverageDefinition[];
+};
+/**
+ * ENCODE FOR RUNNING, with no printability requirement.
+ *
+ * `compileRuleMap` refuses a map whose author callbacks have no captured SOURCE,
+ * because PRINTING one would emit `() => {}` and the parse would return the wrong tree.
+ * That gate is right for the macro, which prints, and wrong for every caller that only
+ * ever RUNS the result: a grammar built at runtime has live callbacks and no sources by
+ * construction, and `encodeTableProgram` parks the live function in the pool where the
+ * driver calls it perfectly well.
+ *
+ * Conflating the two is the single defect this project has now hit three times — a
+ * runtime `compose()`, `linkable()`, and the fuse — each presenting as "this grammar
+ * cannot be compiled" for a grammar that runs. The split lives here, once, so the next
+ * caller inherits the right answer instead of rediscovering it.
+ */
+export declare function compileRuleMapRunnable(ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>, opts?: TableRuleMapOptions): Omit<CompiledRuleMapTable, 'replacement' | 'replacementWithMetadata'> | null;
+export declare function compileRuleMap(ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>, opts?: TableRuleMapOptions): CompiledRuleMapTable | null;
+//# sourceMappingURL=compile-rule-map.d.ts.map

package/dist/table/compile-rule-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-rule-map.d.ts","sourceRoot":"","sources":["../../src/table/compile-rule-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAKvF,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAoB,KAAK,yBAAyB,EAAE,MAAM,qCAAqC,CAAA;AACtG,OAAO,EAAiC,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IACrC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAA;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAA;IACvD,QAAQ,EAAE,QAAQ,CAAA;IAClB,gBAAgB,EAAE,OAAO,CAAA;IACzB,UAAU,EAAE,iBAAiB,CAAA;IAC7B;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAChC,0EAA0E;IAC1E,IAAI,EAAE,YAAY,CAAA;IAClB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;CAC3D,CAAA;AA2ED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAC9D,IAAI,GAAE,mBAAwB,GAC7B,IAAI,CAAC,oBAAoB,EAAE,aAAa,GAAG,yBAAyB,CAAC,GAAG,IAAI,CAc9E;AAmCD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAC9D,IAAI,GAAE,mBAAwB,GAC7B,oBAAoB,GAAG,IAAI,CAkE7B"}

package/dist/table/compile.d.ts

@@ -0,0 +1,56 @@
+import type { Combinator, CompiledParser } from '../types.ts';
+import type { HostMode } from '../cst/host-mode.ts';
+import { type DuplicationOption } from './duplication-hook.ts';
+/**
+ * THE CONTRACT DIVERGENCE, stated rather than hidden.
+ *
+ * `CompiledParser.inlineExpression` is documented as a self-contained IIFE with
+ * "no external references". A table artifact cannot honour that clause and stay
+ * a table: the shared driver being EXTERNAL is the entire reason the artifact is
+ * 0.56 MB instead of source lowering's 2.10 MB. Inlining the driver per grammar
+ * reproduces exactly the size this lowering exists to avoid.
+ *
+ * So the expression references `tableRules`, and the consumer is responsible for
+ * having imported it. That is a real change to what an inliner must do, and it
+ * is the reason this is a lowering swap rather than a rename.
+ *
+ * It is NOT null. Returning null would be the quiet failure: `plugin/index.ts`
+ * warns and SKIPS on null, leaving the grammar interpreted — 79 ms against 14 ms
+ * on `benchmark.less`, a ~5x regression that no test would have reported.
+ */
+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 })`.
+     */
+    readonly recovery?: boolean;
+    /**
+     * GRAMMAR-COVERAGE COUNTERS, lowered as `OP_COV` rows plus the definition pool
+     * (`TableProgram.cov`). Same ids as the source lowering, because both mint them
+     * from the same `buildGrammarPlan` walk over the same combinator graph.
+     *
+     * COUNTERS ONLY — owner ruling. `_grammarTrace`'s six phases are emitted at
+     * ~40 fine-grained sites by codegen and are deferred to 0.48
+     * (`notes/RELEASE-0.48-TARGET.md` §1). A table entry rejects a context carrying
+     * a trace sink before parsing: silently returning an empty trace would look
+     * exactly like a real trace whose grammar sites were never visited. The
+     * plugin's coverage path reads `_grammarCoverage` and the definitions stamp,
+     * neither of which is trace.
+     *
+     * The remaining options below are accepted for signature compatibility with
+     * `compile()`. Any that the table lowering cannot honour THROWS rather than
+     * being ignored — a compile that silently drops the instrumentation its caller
+     * asked for is the failure class this project keeps finding, and coverage that
+     * silently reports nothing is worse than a build error that says why.
+     */
+    readonly coverage?: boolean;
+    readonly duplication?: DuplicationOption;
+    /** Identifier the emitted expression expects to find `tableRules` under. */
+    readonly runtimeRef?: string;
+    /** Source text per `prog.fns` entry, for a module/expression that must be printable. */
+    readonly fnSources?: readonly string[];
+};
+export declare function compile<T>(combinator: Combinator<T>, mapFnSources?: readonly string[], opts?: TableCompileOptions): CompiledParser<T>;
+//# sourceMappingURL=compile.d.ts.map

package/dist/table/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/table/compile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAyC,MAAM,aAAa,CAAA;AACpG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAOnD,OAAO,EAA4B,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAiDxF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAIxC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC,CAAA;AAED,wBAAgB,OAAO,CAAC,CAAC,EACvB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,EAChC,IAAI,GAAE,mBAAwB,GAC7B,cAAc,CAAC,CAAC,CAAC,CAmBnB"}