parseman 0.44.0 → 0.46.0

package/dist/analysis/choice-cost-gate.d.ts

@@ -0,0 +1,158 @@
+/**
+ * CHOICE COST — the policy layer.
+ * ===============================
+ *
+ * Analysis says what the grammar costs. This says which of those numbers fail a build.
+ * They are separate because they have different consumers and different lifetimes: a
+ * developer wants the ranked list on every run, CI wants one bit, and the threshold
+ * that produces that bit is a decision the owner makes once and writes down.
+ *
+ * This module is PURE — it takes a report and a baseline and returns a verdict. It
+ * reads no files, spawns nothing, and prints nothing, so it is testable without a
+ * fixture checkout and cannot be the reason a gate is flaky.
+ *
+ * THE BASELINE IS ABSOLUTE, NOT DIFFERENTIAL
+ * ------------------------------------------
+ * Gating each commit against its parent lets +2% per commit land forever: every
+ * individual step is under tolerance and the total is unbounded. So the committed
+ * baseline records the ACTUAL byte counts, and drift is measured against those
+ * numbers, not against yesterday's.
+ *
+ * A baseline is committed DATA, reviewed like any other diff. Nothing here writes one.
+ * Rebaselining is a deliberate act with a reviewable artifact and owner sign-off; there
+ * is no automatic refresh, because a gate that rebaselines itself is a gate that
+ * records regressions rather than catching them.
+ *
+ * AND IT IS TWO-SIDED — A WIN MUST BE BANKED
+ * ------------------------------------------
+ * Growth past the committed number fails, and so does an unbanked IMPROVEMENT. This is
+ * the half usually left to a comment asking a human politely, and it is the half that
+ * rots: `bench/grammar-density/config.json` and `bench/workloads/config.json` each
+ * carried exactly such a comment and sat unbumped for TEN releases. If a reorder takes
+ * a site from 7,846 wasted bytes to 2,000 and the baseline does not move with it, 5,846
+ * bytes of fresh headroom silently become budget for the next regression — and the gate
+ * that was supposed to catch that regression reads green through the whole of it.
+ *
+ * So the committed number is a BAND, not a floor: leaving it in either direction fails,
+ * and only the remedy differs. Raising a number needs owner sign-off; lowering one is
+ * mandatory. Both are the same one-line rebaseline and the same reviewable diff.
+ *
+ * `bench/size-guard.ts` is the shape this follows — it earned the tightness in 0.45 by
+ * catching +0.14% moves a 1% tolerance would have waved through.
+ *
+ * A BASELINE CANNOT LAUNDER A CEILING
+ * -----------------------------------
+ * If a ceiling is configured, a baseline that records a number ABOVE it is rejected as
+ * invalid rather than honoured. Otherwise the ceiling would be waivable by rebaselining,
+ * which makes it a suggestion. (`bench/size-guard.ts` validates its own baseline for
+ * exactly this reason; this follows it.)
+ *
+ * FAILS CLOSED
+ * ------------
+ * Every way of not having measured is a failure, never a pass: a missing baseline, a
+ * baseline of the wrong shape, an empty baseline, a report over zero corpus files, a
+ * report where no site was instrumentable, a report whose grammar walk was incomplete
+ * (`unresolvedRoots` non-empty), a baselined key that no longer exists, and a measured
+ * key with no baseline entry. This repo already contains the alternative — `ratio:
+ * ordered.length === 0 ? 1` in src/coverage.ts reports 100% covered when nothing was
+ * analysable — and the whole point of a gate is to not be that.
+ */
+import type { WastedWorkReport } from './choice-cost.ts';
+export type WastedWorkBaseline = {
+    readonly schema: 'parseman.wasted-work-baseline/1';
+    /** Informational: which revision produced the numbers. Never compared. */
+    gitRev: string;
+    /** Informational, `YYYY-MM-DD`. Never compared — comparing it would make the
+     *  verdict depend on the clock. */
+    updatedAt: string;
+    /**
+     * Absolute per-corpus totals, keyed by corpus id.
+     *
+     * `totalWastedBytes` is the INTERPRETED column, and that is deliberate even though
+     * `WastedWorkReport` names `totalGatedWastedBytes` as the headline. For BYTES the two
+     * are the same number, structurally: the modelled first-char guard is derived from the
+     * arm's first SET, which over-approximates what the arm can start with, so wherever the
+     * guard rejects, the arm's own leading terminal would have rejected at the same position
+     * having consumed nothing. Measured over four dialect grammars, zero arms differ (see the
+     * header of `choice-cost.ts`). What the guard removes is ATTEMPTS, not rescanned bytes —
+     * so `gatedAttempts`, `gatedFailures` and the inversion ranking DO read the gated columns,
+     * and only the byte totals are recorded from the interpreted one, where it is additionally
+     * the conservative UPPER bound of the two.
+     *
+     * That identity is not enforced anywhere it could be relied on silently: `checkWastedWork`
+     * judges the compiled column against this same band wherever the two columns part, so a
+     * divergence goes red instead of unnoticed.
+     */
+    totals: Record<string, {
+        corpusBytes: number;
+        totalWastedBytes: number;
+        instrumentedSites: number;
+    }>;
+    /** Absolute per-site wasted bytes, keyed by `<corpus>::<siteKey>`. Interpreted column,
+     *  for the reason given on `totals` above. */
+    sites: Record<string, number>;
+};
+export type WastedWorkPolicy = {
+    /**
+     * Maximum wasted bytes per corpus byte. A hard ceiling no rebaseline can waive.
+     * Omit for drift-only gating; a project should set it once it knows its own number.
+     */
+    ceilingRatio?: number;
+    /**
+     * Half-width of the band around each committed number, as a percentage. Default 1.
+     *
+     * SYMMETRIC: a measurement more than this ABOVE its baseline is a regression, and a
+     * measurement more than this BELOW it is an unbanked win. Both fail.
+     *
+     * This is not a noise allowance — the metric is a deterministic count of input bytes,
+     * so its noise floor is exactly zero and any non-zero value here is pure headroom.
+     * It exists only so incidental one-byte churn does not thrash the baseline in both
+     * directions. Set it as near zero as the corpus permits; `bench/choice-cost-guard.ts`
+     * runs at 0.1, matching `bench/size-guard.ts`'s ratchet slack.
+     */
+    driftTolerancePct?: number;
+    /**
+     * Fail on an ordering inversion — an arm that failed every one of its attempts while
+     * a later arm at the same site matched. Off by default: on an existing grammar this
+     * fires immediately, and a gate that is red on arrival for a pre-existing condition
+     * gets disabled rather than fixed. Turn it on once the backlog is empty, to keep it
+     * empty.
+     */
+    failOnInversions?: boolean;
+};
+export type GateBreach = {
+    /** `drift` is growth past the band; `shrank` is an improvement that was not banked.
+     *  Both are failures, and the `detail` says which remedy applies. */
+    kind: 'ceiling' | 'drift' | 'shrank' | 'unbaselined' | 'stale' | 'inversion' | 'unmeasurable' | 'invalid-baseline';
+    key: string;
+    /** One line. Says what happened and what number to look at — never advice. */
+    detail: string;
+};
+export type GateVerdict = {
+    readonly schema: 'parseman.wasted-work-verdict/1';
+    ok: boolean;
+    /** Ascending by (kind, key). Deterministic, so a verdict is diffable. */
+    breaches: readonly GateBreach[];
+    checkedCorpora: number;
+    checkedSites: number;
+};
+/**
+ * Judge one or more measured corpora against a committed baseline.
+ *
+ * `reports` is keyed by corpus id — a grammar is usually gated over more than one body
+ * of input, and a single blended number would let a regression on one hide behind an
+ * improvement on another.
+ */
+export declare function checkWastedWork(reports: Readonly<Record<string, WastedWorkReport>>, baseline: unknown, policy?: WastedWorkPolicy): GateVerdict;
+/**
+ * Build the baseline a passing measurement would record.
+ *
+ * Deliberately NOT called by the gate. It exists so a rebaseline is one explicit
+ * command whose output is a file in the diff — the reviewable record — rather than
+ * something the gate can do to itself on a red run.
+ */
+export declare function buildWastedWorkBaseline(reports: Readonly<Record<string, WastedWorkReport>>, meta: {
+    gitRev: string;
+    updatedAt: string;
+}): WastedWorkBaseline;
+//# sourceMappingURL=choice-cost-gate.d.ts.map

package/dist/analysis/choice-cost-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choice-cost-gate.d.ts","sourceRoot":"","sources":["../../src/analysis/choice-cost-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAA;IAClD,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAA;IACd;uCACmC;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpG;kDAC8C;IAC9C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB;yEACqE;IACrE,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,GAAG,WAAW,GAAG,cAAc,GAAG,kBAAkB,CAAA;IAClH,GAAG,EAAE,MAAM,CAAA;IACX,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,MAAM,EAAE,gCAAgC,CAAA;IACjD,EAAE,EAAE,OAAO,CAAA;IACX,yEAAyE;IACzE,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAA;IAC/B,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAQD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,EACnD,QAAQ,EAAE,OAAO,EACjB,MAAM,GAAE,gBAAqB,GAC5B,WAAW,CAkLb;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,EACnD,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1C,kBAAkB,CAWpB"}

package/dist/analysis/choice-cost-render.d.ts

@@ -0,0 +1,88 @@
+/**
+ * CHOICE COST — the human layer.
+ * ==============================
+ *
+ * Three layers, not two:
+ *
+ *   ANALYSIS   src/analysis/choice-cost.ts  — what the sites are and what they cost.
+ *   POLICY     bench/choice-cost-guard.ts   — which of those numbers fail a build.
+ *   RENDERING  this file                    — how a person reads either of them.
+ *
+ * The structured report is the source of truth. Nothing here computes a finding, and
+ * nothing here decides pass or fail; a gate consumes the data and never this text. If
+ * a number appears below that is not in the report, that is a bug in this file.
+ *
+ * WHAT A PARSER GENERATOR CAN SHOW THAT A COMPILER CANNOT
+ * -------------------------------------------------------
+ * A type error has one source to point at. A wasted-work finding has TWO, and relating
+ * them is the whole diagnostic:
+ *
+ *   - the GRAMMAR site — the ordered choice whose arm ordering costs the time
+ *   - the COST — measured, over a real corpus, per alternative
+ *
+ * So the ordering is printed WITH its measured cost beside each arm, which makes the
+ * fix self-evident without a paragraph explaining it:
+ *
+ *   StylesheetAtRule › dispatch[0]              1.31 MB rescanned
+ *     0  RoutedAtRuleStatement    failed 4,182 / 4,271     1.31 MB
+ *     1  RoutedLayerBlock         matched 4,182
+ *
+ * Reading that, nobody needs to be told what to do.
+ *
+ * QUIET BY DEFAULT
+ * ----------------
+ * Nothing in this module prints. It returns strings. There is no console call and no
+ * process-wide default-on channel, deliberately: importing `examples/css/parser.ts`
+ * already emits roughly sixty lines of gating advice before any user code runs, and a
+ * beautiful diagnostic that nobody reads because it is buried in build noise is not
+ * beautiful. This one is available on request — from the CLI gate, or by calling it —
+ * and silent otherwise.
+ *
+ * DETERMINISM BINDS THE RENDERING TOO
+ * -----------------------------------
+ * The rendering is diffable: it preserves the report's ordering, contains no timings,
+ * no dates, no absolute paths, and colour is opt-in rather than auto-detected, so the
+ * same report always renders to the same bytes. A renderer that sniffed `isTTY` would
+ * produce two different outputs from one report and break exactly that.
+ */
+import type { ChoiceInventoryReport, ChoiceInventoryEntry, WastedWorkReport } from './choice-cost.ts';
+export type RenderOptions = {
+    /** Rows to show. Default 20. The report always holds all of them. */
+    limit?: number;
+    /**
+     * ANSI colour. Default false — NOT auto-detected from `isTTY`, because a renderer
+     * whose bytes depend on where it is piped cannot be diffed or snapshotted.
+     */
+    color?: boolean;
+};
+/** Deterministic thousands grouping. `toLocaleString()` is locale-dependent and would
+ *  make the output differ between machines — the one thing a gateable rendering
+ *  cannot do. */
+export declare function groupDigits(n: number): string;
+/** Byte counts at a glance. Binary units, fixed to one decimal, so 1,376,256 renders
+ *  as `1.3 MB` on every machine. */
+export declare function bytes(n: number): string;
+/**
+ * The combinator source a left-factoring would produce, ready to paste.
+ *
+ * Offered ONLY for the shape where it is mechanical and total: every arm of the choice
+ * in one group. A partial group needs the author to decide which arms move and in what
+ * order — an ordering decision that changes what the grammar accepts, which no
+ * generated rewrite may make silently.
+ *
+ * This is a PREVIEW. It is not applied, and — until the digest-verification loop
+ * described in `docs/` is wired — it is not yet proven behaviour-preserving, so it is
+ * labelled a candidate rather than offered as a fix. An unverified rewrite presented
+ * as verified is worse than no suggestion at all.
+ */
+export declare function leftFactorPreview(e: ChoiceInventoryEntry): string | null;
+export declare function renderChoiceInventory(r: ChoiceInventoryReport, opts?: RenderOptions): string;
+/**
+ * The ranked list, with each top site expanded into its arm ordering.
+ *
+ * The expansion is the point. A ranked list of site keys tells you WHERE; the arm
+ * breakdown beside it tells you WHY, and "arm 0 failed 4,182 of 4,271 times" is an
+ * argument for moving arm 0 that needs no prose attached.
+ */
+export declare function renderWastedWork(r: WastedWorkReport, opts?: RenderOptions): string;
+//# sourceMappingURL=choice-cost-render.d.ts.map

package/dist/analysis/choice-cost-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choice-cost-render.d.ts","sourceRoot":"","sources":["../../src/analysis/choice-cost-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EACV,qBAAqB,EAAE,oBAAoB,EAAE,gBAAgB,EAC9D,MAAM,kBAAkB,CAAA;AAEzB,MAAM,MAAM,aAAa,GAAG;IAC1B,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAID;;iBAEiB;AACjB,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;oCACoC;AACpC,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIvC;AA8CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,GAAG,IAAI,CAOxE;AAID,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,qBAAqB,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CA0ChG;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CAmEtF"}

package/dist/analysis/choice-cost.d.ts

@@ -0,0 +1,383 @@
+/**
+ * CHOICE COST — the shape of an ordered choice, and what that shape costs.
+ * ========================================================================
+ *
+ * READ THIS FIRST: THIS MEASURES THE INTERPRETER, NOT THE SHIPPED PARSER.
+ * ----------------------------------------------------------------------
+ * The interpreter's `firstMatch` loop (src/combinators/choice.ts:149-165) enters every
+ * alternative unconditionally. COMPILED output does not: `emitFirstMatch`
+ * (src/compiler/codegen.ts:2246-2277) emits a per-arm first-CHARACTER guard, so an arm
+ * whose first set excludes the character at the current position is never entered.
+ * First-set gating is this project's single largest parse lever — 25-48% across all
+ * four jess parsers — and a naive interpreted profile is blind to every byte of it.
+ *
+ * So `profileWastedWork` reports TWO columns and derives neither from the other:
+ * `attempts`/`wastedBytes` (interpreted) and `gatedAttempts`/`gatedWastedBytes`
+ * (modelling codegen's guard — see `compiledFirstCharGate`). Rankings use the compiled
+ * column. The DELTA is itself a result: an arm expensive interpreted and cheap gated is
+ * ALREADY SOLVED by codegen, and reordering it is unpaid work.
+ *
+ * WHAT THE GATE ACTUALLY REMOVES — measured, not assumed.
+ * Over jess's four dialect grammars (637 kB of CSS, 212 kB of Less):
+ *
+ *     dialect   arms whose GATED BYTES differ   arm entries removed by the gate
+ *     css                    0 of 158                  331,313 of 435,767  (76%)
+ *     less                   0 of 199                  413,737 of 562,852  (74%)
+ *     scss                   0 of 200                  617,735 of 777,356  (79%)
+ *     jess                   0 of 158                  325,655 of 388,263  (84%)
+ *
+ * The gate removes ATTEMPTS, not rescanned BYTES — and the byte columns are identical
+ * to the byte in all four. That is structural, not a coincidence of these corpora: the
+ * guard is derived from the arm's first SET, which over-approximates what the arm can
+ * start with, so whenever the guard rejects, the arm's own leading terminal would have
+ * rejected at the same position having consumed nothing.
+ *
+ * The practical consequence, and the reason this warning is at the top: any claim of
+ * the form "this arm is entered on every X and fails N% of the time" is a statement
+ * about the INTERPRETER and is usually false of the shipped parser. A byte ranking
+ * survives the correction; a failure-RATE or attempt-count claim does not. Measured on
+ * jess's CSS `Value` choice, arm 0 `Percentage` reads as 25,939 entries at 97% failure
+ * interpreted, and 7,455 at 90% gated — the same arm, a fifth as important. Arm 4
+ * `IdentBlock` is 100% failure in BOTH columns and carries 27,131 bytes; it is the real
+ * finding, and only the gated column makes that legible.
+ *
+ * KNOWN LIMIT OF THE MODEL. On the compose/linkable path a named-rule arm gets a
+ * DEFERRED guard (an `@FS:name@` placeholder) that fuse time rewrites with the winning rule's
+ * first set — or with `true`, always-try, if it cannot be resolved. This model always
+ * resolves, so for cross-artifact ref arms `gatedAttempts` is a LOWER bound: the
+ * shipped artifact may enter such an arm more often than modelled. Where a compiled
+ * measurement disagrees with this report on an arm that is a bare rule reference, the
+ * compiled measurement is right.
+ *
+ * A PEG `choice` is ordered: arm `i` is only reached once arms `0..i-1` have been
+ * TRIED AND FAILED, and every one of those failures re-scanned input that the
+ * winning arm then scans again. So each additional alternative, and each earlier
+ * alternative, has a time cost — and that cost is invisible in the grammar source,
+ * which is why grammar shape drifts without anything going red.
+ *
+ * This module makes it visible, in two halves that answer two different questions.
+ *
+ * STATIC — `analyzeChoiceInventory()`
+ *   Which choice sites have alternatives that share a leading term, and for each:
+ *   did the compiler LEFT-FACTOR it, or did it decline, and why? `detectSharedPrefix`
+ *   (src/combinators/choice.ts) already computes this to decide whether to emit the
+ *   `sharedPrefix` strategy, but it is ALL-OR-NOTHING (every arm must share) and it
+ *   returns `null` on the first arm that does not qualify — silently, with no record
+ *   of how close the site came or which arm blocked it. The inventory reports the
+ *   declines, with the blocking arm and the reason. That set is the refactor backlog,
+ *   GENERATED rather than noticed by a human reading grammar source.
+ *
+ *   It is complete, not sampled: every `choice` reachable from the rule map appears,
+ *   including the ones with nothing to report (`groups: []`).
+ *
+ * DYNAMIC — `profileWastedWork()`
+ *   How many BYTES were re-scanned because an alternative was tried and failed,
+ *   attributed per choice site and per arm, over a real corpus. Ordering pathologies
+ *   fall out of the ranking for free: an arm that fails 98% of the time while sitting
+ *   first is exactly the top entry.
+ *
+ *   The static half can only see shape. It cannot know that one declined site is on
+ *   the hot path of every stylesheet and another is reached twice a year. The dynamic
+ *   half supplies that weight. Neither is sufficient alone.
+ *
+ * WHY BYTES, AND WHY THIS IS GATEABLE
+ * -----------------------------------
+ * The metric is a COUNT of input bytes, not a timing. It is a pure function of
+ * (grammar, corpus): the same grammar over the same corpus yields the same number on
+ * an idle machine and on a machine at load 10. There is no noise floor to argue about
+ * and no rebaseline needed for a hardware change. That is what makes it usable as a
+ * deterministic gate rather than a benchmark.
+ *
+ * INTERPRETED MODE ONLY
+ * ---------------------
+ * Nothing here is emitted into a compiled parser and nothing here costs codegen a
+ * single byte or a single millisecond. The profiler does not add an instrumentation
+ * flag to the hot combinators either — `src/combinators/choice.ts` is UNTOUCHED by
+ * this file. Instrumentation is installed by temporarily substituting arm slots and
+ * terminal `parse` methods on the combinator tree, and removed in a `finally`. When
+ * you are not profiling, the cost is exactly zero because the shipping code contains
+ * no profiling branch to skip.
+ *
+ * (For contrast: `run({ profile })` — the node/slot-count profiler — was compiled-path
+ * only, was never implemented in the interpreter, and now throws rather than reporting
+ * zeros. See src/functional/run.ts. This is a different measurement and a new build,
+ * not a port of that one.)
+ *
+ * WHAT THIS INSTRUMENT CANNOT SEE
+ * -------------------------------
+ * Stated up front, because a diagnostic whose blind spots are undocumented gets read
+ * as complete:
+ *
+ *   0. It measures the INTERPRETER. See the top of this header — this is the blind spot
+ *      that reorders results rather than merely shifting them, which is why it is not
+ *      in this list but above it. The `gated*` columns model it; they do not remove it.
+ *   1. Only `firstMatch` and `sharedPrefix` choices are instrumented. Those are the
+ *      two strategies that try arms in order and can fail one. A `disjoint` choice
+ *      dispatches on the first character and tries exactly one arm; `greedyClassify`
+ *      runs one regex; `literalsLongestFirst` captures its sorted arm array at
+ *      construction, so slot substitution cannot reach it. Their sites still appear
+ *      in the static inventory, with zero dynamic cost recorded and `instrumented:
+ *      false` so the zero is not mistaken for a measurement.
+ *   2. Backtracking that is not a choice arm — a failed `many` element, a failed
+ *      `optional`, a rolled-back `attempt` — is not attributed. Those bytes are real
+ *      but they are not an ORDERING decision, which is what this instrument exists to
+ *      rank.
+ *   3. An arm that SUCCEEDS and is then rejected by the `autoNot` check is recorded as
+ *      a success, because the rejection happens inside the choice loop after the arm
+ *      has returned. Its rescan is invisible here.
+ *   4. `wastedBytes` is input bytes re-scanned, not CPU. An arm that fails after one
+ *      byte but allocated on the way is cheap by this metric and not by the clock.
+ *      This ranks ORDERING, and is deliberately not a profiler.
+ *
+ *      SET EXPECTATIONS ACCORDINGLY, because this has been measured. A jess lane acted
+ *      on a finding from this report and cut rescanned bytes at one route from 27,678
+ *      to 8,367 — a 69.8% reduction, exactly as this instrument predicts — for ZERO
+ *      measurable wall-clock change. A large byte win that produces no time win is the
+ *      expected outcome, not a failure of the fix: re-scanning is cheap per byte, and
+ *      what makes a grammar slow is usually allocation and node construction, which
+ *      this metric cannot see. Use it to find and rank ORDERING defects and to prove a
+ *      restructure did what it claimed. Do not use it to predict a speedup, and do not
+ *      let a flat benchmark be read as evidence the finding was wrong.
+ *   5. Reach is measured by the furthest position at which a TERMINAL was attempted
+ *      (`literal`/`regex`/`keywords`/`scanTo`). A combinator that consumes without
+ *      going through one of those would under-report; none exists today.
+ */
+import type { Combinator } from '../types.ts';
+import type { ChoiceStrategyTag } from './gating.ts';
+import type { FirstSet } from '../types.ts';
+/** A combinator's location in the grammar: owning rule plus structural path. */
+export type ChoiceSite = {
+    /** Nearest enclosing `_ruleName`, or the rule-map key it was reached under. */
+    rule: string;
+    /** Structural path inside that rule, e.g. `seq[2] › node(AtRule) › choice[0]`. */
+    path: string;
+};
+/** The stable identity of a site. Used as the sort key and the baseline key, so it
+ *  must be derived only from grammar structure — never from a file path or a run. */
+export declare const choiceSiteKey: (s: ChoiceSite) => string;
+/** Why one ARM contributed no shareable leading term. */
+export type ArmDeclineReason = 
+/** The arm is not a (wrapper-peeled) `sequence` — e.g. a bare ref, a nested
+ *  `choice`, an `optional`. `leadingTermOfArm` peels only node/grammar/transform/
+ *  label, because those are the wrappers that consume nothing before the sequence. */
+'not-a-sequence'
+/** A `sequence` of one term: there is no residual to factor out from. */
+ | 'sequence-shorter-than-2'
+/** The leading term is a case-INSENSITIVE literal. Excluded deliberately: the
+ *  matched text differs from the literal's own value, so a replayed leaf would
+ *  carry the wrong string. */
+ | 'lead-case-insensitive-literal'
+/** The leading term is not a bare literal/regex — a ref, a node, a label, a
+ *  transform, another choice. Factoring through it would change the value or
+ *  capture shape of the arm. */
+ | 'lead-not-concrete-terminal';
+/** Why the SITE as a whole was not left-factored. */
+export type SiteDeclineReason = 
+/** First-char dispatch already selects exactly one arm; there is nothing to factor.
+ *  Not a backlog entry — this is the good state. */
+'disjoint-dispatch'
+/** At least one arm carries a runtime gate; per-arm predicates are incompatible
+ *  with the factoring strategies. */
+ | 'gated-arms'
+/** `greedyClassify` or `literalsLongestFirst` matched first. Both are stronger than
+ *  `sharedPrefix` (neither backtracks), so this is also not a backlog entry. */
+ | 'strategy-preempted'
+/** Fewer than two arms. */
+ | 'fewer-than-two-arms'
+/** At least one arm produced no shareable leading term. See `armDeclines` for which
+ *  arm and why. THIS is the backlog: a subset of arms may still share a prefix that
+ *  the all-or-nothing detector never records. */
+ | 'arms-not-factorable'
+/** Every arm produced a leading term, but they are not all the same term. Also the
+ *  backlog: two arms out of nine sharing `@` is real, repeated work. */
+ | 'leads-differ';
+/** A maximal set of arms at one site sharing an identical concrete leading term. */
+export type PrefixGroup = {
+    /** Structural key of the shared term. Injective by construction (JSON-encoded), so
+     *  two structurally different regexes can never collide onto one group. */
+    key: string;
+    /** Human rendering, e.g. `"@"` or `/[-\w]+/`. */
+    render: string;
+    /** Arm indices, ascending. */
+    members: readonly number[];
+};
+export type ChoiceInventoryEntry = {
+    site: ChoiceSite;
+    siteKey: string;
+    arity: number;
+    strategy: ChoiceStrategyTag;
+    disjoint: boolean;
+    gated: boolean;
+    /** Every group of >= 2 arms sharing a concrete leading term, ordered by member
+     *  count descending then key. Empty when no two arms share one. */
+    groups: readonly PrefixGroup[];
+    /** Per-arm reasons, ascending by arm index. Only arms that produced no key. */
+    armDeclines: readonly {
+        arm: number;
+        reason: ArmDeclineReason;
+        detail: string;
+    }[];
+    factored: boolean;
+    /** Present iff `factored` is false. */
+    declineReason?: SiteDeclineReason;
+    /** Arms that sit in some group but whose site was NOT factored — the count of
+     *  alternatives currently re-scanning a prefix a sibling already scanned. */
+    unfactoredArms: number;
+};
+export type ChoiceInventoryReport = {
+    readonly schema: 'parseman.choice-inventory/1';
+    rules: number;
+    /** Distinct `choice` combinator instances reachable from the rule map. */
+    choiceSites: number;
+    factoredSites: number;
+    /** Sites with >= 1 prefix group that were NOT factored. The backlog. */
+    backlogSites: number;
+    backlogArms: number;
+    /**
+     * Rule-map entries that are unresolvable references — a `g.X` hole that only
+     * `compose()` binds. Their subtrees were NOT walked, so this report is partial by
+     * exactly this much. Ascending. Empty is the only value that means "complete".
+     */
+    unresolvedRoots: readonly string[];
+    /** Ascending by `siteKey`. Complete — every reachable choice, including the ones
+     *  with nothing to report. */
+    entries: readonly ChoiceInventoryEntry[];
+};
+export type WastedWorkArm = {
+    siteKey: string;
+    site: ChoiceSite;
+    arm: number;
+    /** Short rendering of the arm's head, so the ranked list reads without opening
+     *  the grammar. */
+    label: string;
+    /** INTERPRETED: every entry, because the interpreter's firstMatch loop gates nothing. */
+    attempts: number;
+    failures: number;
+    /** INTERPRETED: input bytes re-scanned by this arm's FAILED attempts, summed over the
+     *  corpus. For one attempt: (furthest position a terminal was tried) - (entry position). */
+    wastedBytes: number;
+    /** True when codegen emits a first-char guard for this arm, i.e. the shipped parser
+     *  enters it less often than the interpreter does. */
+    firstCharGated: boolean;
+    /** COMPILED MODEL: entries that survive codegen's first-char guard. This is the
+     *  number the shipped parser actually pays. Equals `attempts` when `firstCharGated`
+     *  is false. */
+    gatedAttempts: number;
+    gatedFailures: number;
+    /** COMPILED MODEL: the ranking column. Bytes re-scanned by failed attempts that
+     *  codegen's guard would NOT have skipped. */
+    gatedWastedBytes: number;
+};
+export type WastedWorkSite = {
+    siteKey: string;
+    site: ChoiceSite;
+    strategy: ChoiceStrategyTag;
+    arity: number;
+    /** False when the strategy cannot be instrumented; then `wastedBytes` is 0 because
+     *  nothing was measured, NOT because nothing was wasted. */
+    instrumented: boolean;
+    attempts: number;
+    failures: number;
+    wastedBytes: number;
+    gatedAttempts: number;
+    gatedFailures: number;
+    gatedWastedBytes: number;
+};
+export type WastedWorkReport = {
+    readonly schema: 'parseman.wasted-work/1';
+    corpusFiles: number;
+    corpusBytes: number;
+    parsedOk: number;
+    parsedFailed: number;
+    /** Sites the profiler installed instrumentation on. */
+    instrumentedSites: number;
+    /** Reachable choice sites whose strategy cannot be instrumented (see the module
+     *  header, blind spot 1). Reported so a low total is not read as a clean grammar. */
+    uninstrumentableSites: number;
+    /** Rule-map entries that are unresolvable references; their subtrees carry no
+     *  instrumentation, so the total below is a LOWER BOUND by exactly this much. */
+    unresolvedRoots: readonly string[];
+    /** INTERPRETED total. Read `totalGatedWastedBytes` for what the shipped parser pays. */
+    totalWastedBytes: number;
+    /** COMPILED MODEL total — the headline number, and the one a gate should use. */
+    totalGatedWastedBytes: number;
+    /** Descending by `gatedWastedBytes`, then `wastedBytes`, then `siteKey`, then `arm`. */
+    arms: readonly WastedWorkArm[];
+    /**
+     * ORDERING INVERSIONS: arms that were attempted at least `inversionMinAttempts`
+     * times and failed EVERY time, while a later arm at the same site matched.
+     *
+     * A second ranking, because bytes alone answer the wrong question for the clearest
+     * class of defect. Measured on jess's CSS grammar: `StylesheetAtRule › dispatch[3]`
+     * has arm 0 failing 19 of 19 attempts while arm 1 matches — an unambiguous ordering
+     * bug — yet it is only the 14th largest site by bytes, because the prelude it
+     * re-scans is short. Bytes rank what costs most; this ranks what is most obviously
+     * WRONG. Both are in the report and neither is derived from the other.
+     *
+     * Computed from the GATED columns, so an arm codegen already skips is not reported
+     * as an inversion in a parser that never enters it.
+     *
+     * Descending by `gatedAttempts` — NOT by bytes. An arm can fail 100% of its attempts
+     * and re-scan zero bytes, because it fails on its own first terminal; jess's `Value`
+     * arm 8 `CustomPropertyValue` does exactly that, 925 times, and is the one ungated arm
+     * at that site. Ranked by bytes it is invisible; ranked by attempts it is a finding.
+     */
+    inversions: readonly WastedWorkArm[];
+    /** Descending by `wastedBytes`, then ascending by `siteKey`. */
+    sites: readonly WastedWorkSite[];
+};
+/** A short, deterministic rendering of an arm's head, for the ranked list. */
+export declare function armLabel(arm: Combinator<unknown>): string;
+/**
+ * Every `choice` reachable from `ruleMap`, with its shared-prefix groups and whether
+ * the compiler factored the site.
+ *
+ * Complete by construction: the walk visits every reachable combinator instance and
+ * emits an entry for each `choice`, whether or not it has anything to report. A site
+ * missing from this report is a site the walk could not reach, never a site that was
+ * judged uninteresting.
+ */
+export declare function analyzeChoiceInventory(ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>): ChoiceInventoryReport;
+/** Exposed so the fidelity test can compare the model against emitted guards. */
+export declare function modelledFirstCharGate(p: Combinator<unknown>): FirstSet | null;
+export type WastedWorkCorpusEntry = {
+    /** Stable identifier. Use a repo-relative path, never an absolute one — it appears
+     *  in the report, and an absolute path would make the report machine-dependent. */
+    id: string;
+    text: string;
+};
+export type ProfileWastedWorkOptions = {
+    /** The combinator rule map, for site naming and instrumentation. */
+    rules: ReadonlyArray<readonly [string, Combinator<unknown>]>;
+    /** The rule to start each parse at. A key of `rules`, or a combinator. */
+    entry: string | Combinator<unknown>;
+    corpus: ReadonlyArray<WastedWorkCorpusEntry>;
+    /** Passed through to `run()`. Must not contain anything machine-dependent. */
+    runOptions?: Record<string, unknown>;
+    /**
+     * How to parse one corpus entry. Defaults to `run()` in interpreted mode.
+     *
+     * Overridable because a grammar can need a driver of its own — jess's Less dialect,
+     * for instance, requires `state: { source: input }` because its reducers read it —
+     * and because a caller who has already built a driver should not have to duplicate
+     * it here. It must be a plain interpreted parse; anything compiled defeats the
+     * instrumentation silently, since a compiled artifact never reads `def.parsers`.
+     */
+    runner?: (entry: Combinator<unknown>, input: string, options: Record<string, unknown>) => {
+        ok: boolean;
+    };
+    /** Minimum attempts before an always-failing arm counts as an ordering inversion.
+     *  Default 4 — below that, "failed every time" is a sample size, not a finding. */
+    inversionMinAttempts?: number;
+};
+/**
+ * Parse `corpus` with `rules` in INTERPRETED mode, counting input bytes re-scanned
+ * by failed choice alternatives.
+ *
+ * Fails closed on every way of measuring nothing: an empty rule map, an unknown entry
+ * rule, an empty corpus, an empty corpus file, or a grammar in which no instrumentable
+ * choice site exists. Each of those would otherwise produce a report of zero wasted
+ * bytes, which reads as a clean grammar.
+ */
+export declare function profileWastedWork(opts: ProfileWastedWorkOptions): WastedWorkReport;
+//# sourceMappingURL=choice-cost.d.ts.map

package/dist/analysis/choice-cost.d.ts.map

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