solve-engine 2.16.0 → 2.18.0

package/dist/{BytecodeBuilder-CRYfrFfq.d.cts → BytecodeBuilder-aqVa7Plx.d.cts}

@@ -111,6 +111,16 @@ interface BytecodeProgram {
     opcodes: Uint8Array;
     numbers: Float64Array;
     strings: string[];
+    /**
+     * Numeric constants by opcode position, restored from a snapshot.
+     *
+     * Nothing in the compile path writes this: numbers are emitted inline into
+     * {@link numbers} instead. `build()` used to attach an empty Map to every
+     * program anyway, which was one allocation per compiled expression, around a
+     * tenth of parse-and-compile time, for a collection that was never read.
+     * It is left off now, and only {@link EngineSnapshot} sets it when restoring
+     * a program that carried one; every reader already guards on its absence.
+     */
     constants?: Map<number, number>;
     /**
      * Whether the program contains any async opcodes (CALL_PLUGIN, etc.).

package/dist/{BytecodeBuilder-CRYfrFfq.d.ts → BytecodeBuilder-aqVa7Plx.d.ts}

@@ -111,6 +111,16 @@ interface BytecodeProgram {
     opcodes: Uint8Array;
     numbers: Float64Array;
     strings: string[];
+    /**
+     * Numeric constants by opcode position, restored from a snapshot.
+     *
+     * Nothing in the compile path writes this: numbers are emitted inline into
+     * {@link numbers} instead. `build()` used to attach an empty Map to every
+     * program anyway, which was one allocation per compiled expression, around a
+     * tenth of parse-and-compile time, for a collection that was never read.
+     * It is left off now, and only {@link EngineSnapshot} sets it when restoring
+     * a program that carried one; every reader already guards on its absence.
+     */
     constants?: Map<number, number>;
     /**
      * Whether the program contains any async opcodes (CALL_PLUGIN, etc.).

package/dist/{EngineError-Cv5q4Rbv.d.cts → EngineError-DTk7I7hZ.d.cts}

@@ -313,6 +313,30 @@ declare class EngineError extends Error {
      * interop with no build-config change needed.
      */
     readonly cause?: unknown;
+    /**
+     * Whether a recoverable error captures a JavaScript stack trace.
+     *
+     * Off, because a recoverable EngineError is a value rather than a fault. A
+     * line of prose in a notepad is not an expression, so parsing it fails, and
+     * that failure is the answer for that line rather than a bug to debug. The
+     * engine builds one such error per non-expression line.
+     *
+     * Capturing a stack is not cheap, and its cost grows with how deep the stack
+     * is when it happens. Measured through `parseDocument`, where the throw site
+     * sits about a dozen frames down, each capture cost around 62 microseconds
+     * and a 250-line document built 74 of them: a CPU profile put the
+     * constructor at 46% of the whole pipeline, more than lexing, normalising,
+     * parsing and executing put together.
+     *
+     * Turn it on to debug where a recoverable error is raised from. Errors that
+     * are NOT recoverable always capture, since those are the genuine faults.
+     *
+     * @example
+     * ```ts
+     * EngineError.captureRecoverableStacks = true;
+     * ```
+     */
+    static captureRecoverableStacks: boolean;
     constructor(category: ErrorCategory, init: EngineErrorInit);
     /** `!recoverable`. See `EngineErrorInit.recoverable`'s doc comment for what this actually gates (message framing/telemetry, not whether evaluation continues). */
     isFatal(): boolean;

package/dist/{EngineError-Cv5q4Rbv.d.ts → EngineError-DTk7I7hZ.d.ts}

@@ -313,6 +313,30 @@ declare class EngineError extends Error {
      * interop with no build-config change needed.
      */
     readonly cause?: unknown;
+    /**
+     * Whether a recoverable error captures a JavaScript stack trace.
+     *
+     * Off, because a recoverable EngineError is a value rather than a fault. A
+     * line of prose in a notepad is not an expression, so parsing it fails, and
+     * that failure is the answer for that line rather than a bug to debug. The
+     * engine builds one such error per non-expression line.
+     *
+     * Capturing a stack is not cheap, and its cost grows with how deep the stack
+     * is when it happens. Measured through `parseDocument`, where the throw site
+     * sits about a dozen frames down, each capture cost around 62 microseconds
+     * and a 250-line document built 74 of them: a CPU profile put the
+     * constructor at 46% of the whole pipeline, more than lexing, normalising,
+     * parsing and executing put together.
+     *
+     * Turn it on to debug where a recoverable error is raised from. Errors that
+     * are NOT recoverable always capture, since those are the genuine faults.
+     *
+     * @example
+     * ```ts
+     * EngineError.captureRecoverableStacks = true;
+     * ```
+     */
+    static captureRecoverableStacks: boolean;
     constructor(category: ErrorCategory, init: EngineErrorInit);
     /** `!recoverable`. See `EngineErrorInit.recoverable`'s doc comment for what this actually gates (message framing/telemetry, not whether evaluation continues). */
     isFatal(): boolean;

package/dist/{PackageCompatibility-CHQ4kDT8.d.ts → PackageCompatibility-BGXSFuL9.d.ts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-YmfowYr1.js';
+import { I as IEnginePackage } from './PackageRegistry-BRoVOYzg.js';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageCompatibility-BET0iFb9.d.cts → PackageCompatibility-BZCqaTOO.d.cts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-DzmG-Rvu.cjs';
+import { I as IEnginePackage } from './PackageRegistry-rMGnTh7W.cjs';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageRegistry-YmfowYr1.d.ts → PackageRegistry-BRoVOYzg.d.ts}

@@ -1,12 +1,12 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-CK0bNO1l.js';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-B-WyUtX4.js';
 import { V as Value, b as ValueType } from './Value-DCTqTSeP.js';
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-CqagTewQ.js';
 import { IAsyncResolver } from './resolvers.js';
-import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-d7F1KQFs.js';
-import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-C6c1WmJD.js';
-import { a as BytecodeProgram } from './BytecodeBuilder-CRYfrFfq.js';
+import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-OTPS0Otq.js';
+import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-gB9UengK.js';
+import { a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.js';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-Cv5q4Rbv.js';
+import { E as EngineError } from './EngineError-DTk7I7hZ.js';
 import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-QIT4iD8f.js';
 import { T as Token } from './Token-CbP_OutD.js';
 import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-BGQn-cJ8.js';
@@ -1191,6 +1191,32 @@ interface NormalizerOutput {
     }[];
     /** Post-normalization tokens ready for parsing */
     tokens: Token[];
+    /**
+     * Every registered rule with the shape it declared, in priority order.
+     *
+     * A rule that declares a shape is tried only where that shape can match; one
+     * that declares none is tried at every position of every line. That
+     * distinction is invisible from outside the engine and is the difference
+     * between a package costing the documents that use it and costing all of
+     * them, so the playground draws it.
+     */
+    ruleShapes?: {
+        name: string;
+        priority: number;
+        shape: readonly {
+            types?: readonly string[];
+            values?: readonly string[];
+        }[];
+        unshapedReason?: string;
+        indexedSlots: number;
+    }[];
+    /**
+     * How many rules could fire at each position of the normalised stream.
+     *
+     * One entry per token. Mostly zeroes, which is the point of the index: a
+     * position where nothing can match is rejected without calling a rule.
+     */
+    candidatesPerPosition?: number[];
     /**
      * All registered phrase → tokenType mappings from the PhraseTrie.
      * Populated by the engine at diagnostic stage build time so the
@@ -1478,6 +1504,18 @@ interface EngineOptions {
     config?: EngineConfigOverride;
     /** Turn on the diagnostic pipeline (per-stage timing and detail). Defaults to `false`. */
     diagnostics?: boolean;
+    /**
+     * Run a few throwaway expressions through the pipeline at construction, so
+     * the first real one is not the one that pays for JIT warmup.
+     *
+     * Off by default, because it moves cost rather than removing it: a process
+     * that evaluates one expression and exits pays for warming paths it never
+     * reuses. Turn it on for anything interactive, where the first keystroke is
+     * the one a person notices. See {@link ExpressionEngine.warmUp}.
+     *
+     * @default false
+     */
+    warmup?: boolean;
 }
 /**
  * Core expression evaluation engine, the top-level orchestrator.
@@ -1650,6 +1688,41 @@ declare class ExpressionEngine {
      * had set, rather than assuming it was `null`.
      */
     getDocumentModel(): DocumentModel | null;
+    /**
+     * A handful of expressions run through the pipeline to warm it, chosen to
+     * cover the shapes the hot paths specialise on rather than to be
+     * interesting.
+     *
+     * V8 runs a function interpreted until it has been called enough times to
+     * be worth optimising, and it specialises on the types it has actually
+     * seen. So the point is breadth, not volume: a number, a unit, a phrase, a
+     * function call, a comparison and a string each drive a different branch of
+     * the lexer, the normalizer and the VM. Warming only with `1 + 1` would
+     * optimise those functions for integers and then deoptimise the moment a
+     * real document mentioned kilograms, which is worse than not warming at all.
+     */
+    private static readonly WARMUP_EXPRESSIONS;
+    /**
+     * Run the pipeline over a few throwaway expressions so the first real one
+     * is not the one that pays for JIT warmup.
+     *
+     * Nothing here reaches the engine's state: no variable is defined, no line
+     * is registered, no bytecode is cached and no async resolver is consulted.
+     * It lexes, normalises, parses, compiles and executes into a scratch
+     * builder and then drops the result, which is enough to move the hot
+     * functions past the interpreter and to build the normalizer's rule index.
+     *
+     * The cost lands on construction instead. That is the right trade for an
+     * editor, where the first keystroke is the one a person notices, and the
+     * wrong one for a process that evaluates a single expression and exits,
+     * which is why {@link EngineOptions.warmup} exists rather than this being
+     * unconditional.
+     *
+     * Failures are swallowed on purpose: a warmup expression that stops parsing
+     * because a package changed is a warmup that did less good, not a reason to
+     * refuse to construct an engine.
+     */
+    warmUp(): void;
     /**
      * Build the {@link LineExecutionContext} passed to `executeBytecode()`
      * for a given line. `lineNumber = -1` (the existing sentinel

package/dist/{PackageRegistry-DzmG-Rvu.d.cts → PackageRegistry-rMGnTh7W.d.cts}

@@ -1,12 +1,12 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-DOGmj6N6.cjs';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-Bkbp9CKD.cjs';
 import { V as Value, b as ValueType } from './Value-DCTqTSeP.cjs';
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-CCHFDcgP.cjs';
 import { IAsyncResolver } from './resolvers.cjs';
-import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-BfTHg1qt.cjs';
-import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-BtqiTVjG.cjs';
-import { a as BytecodeProgram } from './BytecodeBuilder-CRYfrFfq.cjs';
+import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-MXaKLJ_m.cjs';
+import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-bCYewWVt.cjs';
+import { a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.cjs';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-Cv5q4Rbv.cjs';
+import { E as EngineError } from './EngineError-DTk7I7hZ.cjs';
 import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-B4wf3M1h.cjs';
 import { T as Token } from './Token-CbP_OutD.cjs';
 import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-BGQn-cJ8.cjs';
@@ -1191,6 +1191,32 @@ interface NormalizerOutput {
     }[];
     /** Post-normalization tokens ready for parsing */
     tokens: Token[];
+    /**
+     * Every registered rule with the shape it declared, in priority order.
+     *
+     * A rule that declares a shape is tried only where that shape can match; one
+     * that declares none is tried at every position of every line. That
+     * distinction is invisible from outside the engine and is the difference
+     * between a package costing the documents that use it and costing all of
+     * them, so the playground draws it.
+     */
+    ruleShapes?: {
+        name: string;
+        priority: number;
+        shape: readonly {
+            types?: readonly string[];
+            values?: readonly string[];
+        }[];
+        unshapedReason?: string;
+        indexedSlots: number;
+    }[];
+    /**
+     * How many rules could fire at each position of the normalised stream.
+     *
+     * One entry per token. Mostly zeroes, which is the point of the index: a
+     * position where nothing can match is rejected without calling a rule.
+     */
+    candidatesPerPosition?: number[];
     /**
      * All registered phrase → tokenType mappings from the PhraseTrie.
      * Populated by the engine at diagnostic stage build time so the
@@ -1478,6 +1504,18 @@ interface EngineOptions {
     config?: EngineConfigOverride;
     /** Turn on the diagnostic pipeline (per-stage timing and detail). Defaults to `false`. */
     diagnostics?: boolean;
+    /**
+     * Run a few throwaway expressions through the pipeline at construction, so
+     * the first real one is not the one that pays for JIT warmup.
+     *
+     * Off by default, because it moves cost rather than removing it: a process
+     * that evaluates one expression and exits pays for warming paths it never
+     * reuses. Turn it on for anything interactive, where the first keystroke is
+     * the one a person notices. See {@link ExpressionEngine.warmUp}.
+     *
+     * @default false
+     */
+    warmup?: boolean;
 }
 /**
  * Core expression evaluation engine, the top-level orchestrator.
@@ -1650,6 +1688,41 @@ declare class ExpressionEngine {
      * had set, rather than assuming it was `null`.
      */
     getDocumentModel(): DocumentModel | null;
+    /**
+     * A handful of expressions run through the pipeline to warm it, chosen to
+     * cover the shapes the hot paths specialise on rather than to be
+     * interesting.
+     *
+     * V8 runs a function interpreted until it has been called enough times to
+     * be worth optimising, and it specialises on the types it has actually
+     * seen. So the point is breadth, not volume: a number, a unit, a phrase, a
+     * function call, a comparison and a string each drive a different branch of
+     * the lexer, the normalizer and the VM. Warming only with `1 + 1` would
+     * optimise those functions for integers and then deoptimise the moment a
+     * real document mentioned kilograms, which is worse than not warming at all.
+     */
+    private static readonly WARMUP_EXPRESSIONS;
+    /**
+     * Run the pipeline over a few throwaway expressions so the first real one
+     * is not the one that pays for JIT warmup.
+     *
+     * Nothing here reaches the engine's state: no variable is defined, no line
+     * is registered, no bytecode is cached and no async resolver is consulted.
+     * It lexes, normalises, parses, compiles and executes into a scratch
+     * builder and then drops the result, which is enough to move the hot
+     * functions past the interpreter and to build the normalizer's rule index.
+     *
+     * The cost lands on construction instead. That is the right trade for an
+     * editor, where the first keystroke is the one a person notices, and the
+     * wrong one for a process that evaluates a single expression and exits,
+     * which is why {@link EngineOptions.warmup} exists rather than this being
+     * unconditional.
+     *
+     * Failures are swallowed on purpose: a warmup expression that stops parsing
+     * because a package changed is a warmup that did less good, not a reason to
+     * refuse to construct an engine.
+     */
+    warmUp(): void;
     /**
      * Build the {@link LineExecutionContext} passed to `executeBytecode()`
      * for a given line. `lineNumber = -1` (the existing sentinel

package/dist/{Parselet-CK0bNO1l.d.ts → Parselet-B-WyUtX4.d.ts}

@@ -1,4 +1,4 @@
-import { B as BytecodeBuilder } from './BytecodeBuilder-CRYfrFfq.js';
+import { B as BytecodeBuilder } from './BytecodeBuilder-aqVa7Plx.js';
 import { T as Token } from './Token-CbP_OutD.js';
 import { D as DiagnosticPipeline } from './pipeline-QIT4iD8f.js';
 
@@ -149,6 +149,10 @@ declare class PrecedenceParser {
     private diagnosticPipeline;
     private currentExpression;
     private localeCode;
+    /** The locale's decimal separator, cached from {@link localeCode}. */
+    private readonly decimalSeparator;
+    /** The locale's thousands separator, cached from {@link localeCode}. */
+    private readonly thousandsSeparator;
     /**
      * The binding power the current infix parselet is being invoked at, i.e. the
      * `minBp` of the expression it sits inside. Set immediately before each Tier-2

package/dist/{Parselet-DOGmj6N6.d.cts → Parselet-Bkbp9CKD.d.cts}

@@ -1,4 +1,4 @@
-import { B as BytecodeBuilder } from './BytecodeBuilder-CRYfrFfq.cjs';
+import { B as BytecodeBuilder } from './BytecodeBuilder-aqVa7Plx.cjs';
 import { T as Token } from './Token-CbP_OutD.cjs';
 import { D as DiagnosticPipeline } from './pipeline-B4wf3M1h.cjs';
 
@@ -149,6 +149,10 @@ declare class PrecedenceParser {
     private diagnosticPipeline;
     private currentExpression;
     private localeCode;
+    /** The locale's decimal separator, cached from {@link localeCode}. */
+    private readonly decimalSeparator;
+    /** The locale's thousands separator, cached from {@link localeCode}. */
+    private readonly thousandsSeparator;
     /**
      * The binding power the current infix parselet is being invoked at, i.e. the
      * `minBp` of the expression it sits inside. Set immediately before each Tier-2

package/dist/{ScopeManager-BtqiTVjG.d.cts → ScopeManager-bCYewWVt.d.cts}

@@ -1,6 +1,6 @@
 import { V as Value } from './Value-DCTqTSeP.cjs';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-CRYfrFfq.cjs';
-import { E as EngineError } from './EngineError-Cv5q4Rbv.cjs';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.cjs';
+import { E as EngineError } from './EngineError-DTk7I7hZ.cjs';
 import { D as DiagnosticPipeline } from './pipeline-B4wf3M1h.cjs';
 
 /**

package/dist/{ScopeManager-C6c1WmJD.d.ts → ScopeManager-gB9UengK.d.ts}

@@ -1,6 +1,6 @@
 import { V as Value } from './Value-DCTqTSeP.js';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-CRYfrFfq.js';
-import { E as EngineError } from './EngineError-Cv5q4Rbv.js';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.js';
+import { E as EngineError } from './EngineError-DTk7I7hZ.js';
 import { D as DiagnosticPipeline } from './pipeline-QIT4iD8f.js';
 
 /**

package/dist/{TokenNormalizer-BfTHg1qt.d.cts → TokenNormalizer-MXaKLJ_m.d.cts}

@@ -69,6 +69,43 @@ interface NormalizerMatch {
      */
     ruleName?: string;
 }
+/**
+ * One position of a rule's leading shape, as a declarative constraint.
+ *
+ * A slot says what the token at that offset from the match position may be.
+ * Both fields are optional and an omitted one constrains nothing, so `{}` is a
+ * wildcard slot, useful for reaching past a position a rule does not care about
+ * to one it does.
+ *
+ * The exactness contract runs in one direction only, and it is the whole reason
+ * this is safe to adopt gradually. Declaring MORE than the rule can match costs
+ * a `match()` call that returns null, which is what happens today anyway.
+ * Declaring LESS makes the rule unreachable at the positions left out, which is
+ * a silent bug. So an incomplete shape (or none at all) is always correct, and
+ * only an over-narrow one is wrong. `NormalizerIndexFidelity.spec` checks every
+ * declaration against its rule's real behaviour.
+ */
+interface RuleSlot {
+    /**
+     * Token types admitted at this slot. Omit when the type is unconstrained,
+     * or when the rule accepts so many that naming them filters nothing.
+     */
+    readonly types?: readonly string[];
+    /**
+     * Token values admitted at this slot, compared case-insensitively.
+     *
+     * This is the axis that separates rules sharing a start type. The
+     * call-fusion rules all begin at an `IDENT`, the commonest token in prose,
+     * so type alone leaves every one of them a candidate at every word; the word
+     * itself is what tells them apart, and each already owns that set as an
+     * exported constant.
+     *
+     * A rule whose own check is case-SENSITIVE (the stock ticker rule matches
+     * upper case only) may still declare its lower-cased words here: the index
+     * only ever over-approximates, and the rule's own check still runs.
+     */
+    readonly values?: readonly string[];
+}
 /**
  * A pluggable normalization rule registered with the TokenNormalizer.
  *
@@ -139,6 +176,60 @@ interface NormalizerRule {
      * the rule silently unreachable there, which is a bug.
      */
     readonly startTokenTypes?: readonly string[];
+    /**
+     * The rule's leading shape: what the tokens from the match position onward
+     * may be, one {@link RuleSlot} per position.
+     *
+     * This generalises {@link startTokenTypes}, which constrains only the first
+     * token. Constraining the first token alone is not enough to separate the
+     * rules that matter: every rule firing on a bare `NUMBER` declares the same
+     * start type, so they all remain candidates at every number in the document.
+     * What distinguishes them is the token after it, `NUMBER COLON` being a clock
+     * time and `NUMBER SLASH` a network address, and that fact is only usable by
+     * an index if the rule states it rather than hiding it inside `match()`.
+     *
+     * Depth is the rule's choice, not the interface's. The normalizer builds one
+     * lookup plane per declared slot and intersects them, so a rule that declares
+     * three positions is filtered on three. It may also index fewer planes than
+     * were declared, which stays correct for the reason given on {@link RuleSlot}:
+     * a shallower filter admits more candidates, and each surviving rule still
+     * runs its own `match()`.
+     *
+     * Prefer this to {@link startTokenTypes} in new rules. When both are given,
+     * this wins; `startTokenTypes: ["IDENT"]` means exactly `shape: [{ types:
+     * ["IDENT"] }]`.
+     *
+     * @example
+     * ```ts
+     * // 9:00am, 16:00, a clock time is a number followed by a colon
+     * shape: [{ types: ["NUMBER"] }, { types: ["COLON"] }]
+     *
+     * // sha256("hi"), a known word followed by an opening parenthesis
+     * shape: [{ types: ["IDENT"], values: HASH_NAMES }, { types: ["LPAREN"] }]
+     * ```
+     */
+    readonly shape?: readonly RuleSlot[];
+    /**
+     * Why this rule cannot declare a {@link shape}, for the few that genuinely
+     * cannot.
+     *
+     * A rule with neither a shape nor a `startTokenTypes` hint is tried at every
+     * position of every line, so it raises the cost of the whole document rather
+     * than only its own feature. Registering one logs a warning naming the rule,
+     * which is how a package author finds out before their users do.
+     *
+     * Some rules really cannot be described by a leading shape: an unbounded
+     * forward scan, a greedy match against a table the host mutates at runtime.
+     * Setting this states that case, silences the warning, and leaves the reason
+     * in the code where the next person will read it. It is deliberately a
+     * sentence and not a boolean, because "why" is the part worth keeping.
+     *
+     * @example
+     * ```ts
+     * unshapedReason: "Scans forward an unbounded number of NUMBER UNIT pairs, so no fixed leading shape describes it.",
+     * ```
+     */
+    readonly unshapedReason?: string;
     /**
      * Attempt to match a pattern starting at position `pos` in the token stream.
      *
@@ -228,6 +319,19 @@ interface NormalizerOptions {
      * When `undefined`, fusions are still tracked internally but no callbacks fire.
      */
     onFusion?: (fusion: TokenFusion) => void;
+    /**
+     * Try every registered rule at every position, ignoring the shape index.
+     *
+     * Diagnostic only, and much slower. It exists so the indexed walk can be
+     * compared against the unindexed one over a corpus: the index is a pure
+     * filter, so the two must agree token for token, and a rule whose declared
+     * {@link NormalizerRule.shape} is too narrow shows up as a difference rather
+     * than as a feature that quietly stopped working.
+     * `NormalizerIndexFidelity.spec` is the consumer.
+     *
+     * @default false
+     */
+    ignoreRuleIndex?: boolean;
 }
 /**
  * Creates a new normalized token from fused source tokens.
@@ -298,6 +402,28 @@ declare class TokenNormalizer {
      * identifier. Invalidated alongside {@link sortedRulesCache}.
      */
     private rulesByTokenType;
+    /**
+     * Shape index over the priority-sorted rules, rebuilt alongside
+     * {@link sortedRulesCache}. `null` means "stale, rebuild on next use".
+     *
+     * This is what turns the per-position scan from "try every rule that could
+     * fire on this token type" into "AND a few lookup planes and try what
+     * survives", which is usually nothing. See {@link RuleIndex}.
+     */
+    private ruleIndexCache;
+    /** Reused by {@link rulesAt} so a position's candidate list costs no allocation. */
+    private candidateBuffer;
+    /**
+     * How many times {@link normalize} has run, capped once the index is in use.
+     *
+     * The index costs a few tens of microseconds to build and pays that back
+     * within a line or two, but an engine that normalises exactly once, which is
+     * what evaluating a single expression on a fresh engine does, would never
+     * reach the payback. Skipping the build on the first call keeps that case at
+     * the cost it had before the index existed, and a document reaches line two
+     * immediately.
+     */
+    private normalizeCalls;
     /**
      * Phrase trie for single-pass multi-word phrase fusion.
      * Tried at each token position BEFORE other rules, the trie walk
@@ -348,11 +474,67 @@ declare class TokenNormalizer {
      * and cached, which is what turns the per-position rule scan from "try all R
      * rules" into "try only the ones that could fire on this token".
      */
+    private getRuleIndex;
+    /**
+     * The rules to try at a position, in priority order.
+     *
+     * With a candidate mask, walks its set bits low to high, which is descending
+     * priority because bit `i` is the rule at index `i` of the priority-sorted
+     * list.
+     *
+     * The walk shifts a bit at a time rather than jumping to the next set bit
+     * with `Math.clz32(bits & -bits)`, which is the idiomatic form and was 36x
+     * SLOWER here: 45us per line against 1.2us, measured over the built-in rule
+     * set. `clz32` is specified on uint32 and the masks come out of a
+     * `Uint32Array` as doubles above 2^31, so every call pays a conversion that
+     * swamps the handful of iterations it saves. A de Bruijn table matched the
+     * shift scan to within noise and needs a magic constant, so the plain shift
+     * wins on both counts. Worst case is 32 iterations per word of pure integer
+     * work.
+     *
+     * With `null` (the {@link NormalizerOptions.ignoreRuleIndex} path) it falls
+     * back to the type-bucketed list, which is the behaviour this replaced.
+     *
+     * Returns a buffer reused across positions, so the caller must finish with it
+     * before calling again. Copying the surviving rules out here rather than
+     * yielding them lazily is deliberate twice over: it keeps the mask's own
+     * scratch buffer from being read after the next position overwrites it, and
+     * it avoids a generator on the hottest loop in the pass.
+     */
+    private rulesAt;
     private rulesForTokenType;
     /**
      * Get the number of currently registered rules (excludes phrase trie entries).
      */
     get ruleCount(): number;
+    /**
+     * Every registered rule with the shape it declared, for diagnostic display.
+     *
+     * Exposes what the index is actually working with: a rule that declares a
+     * shape is only tried where that shape can match, and one that declares none
+     * is tried at every position of every line. Which is which is invisible from
+     * the outside otherwise, and it is the difference between a package that
+     * costs the documents that use it and one that costs all of them, so the
+     * playground draws it.
+     *
+     * Returned in priority order, highest first, which is the order the
+     * normalizer tries them in.
+     */
+    private ruleShapesCache;
+    getRuleShapes(): Array<{
+        name: string;
+        priority: number;
+        shape: readonly RuleSlot[];
+        unshapedReason?: string;
+        indexedSlots: number;
+    }>;
+    /**
+     * How many rules could fire at each position of `tokens`, against the total.
+     *
+     * The point of the index is that most positions admit no rule at all, and
+     * this is what makes that visible rather than asserted.
+     */
+    getCandidateCounts(tokens: Token[]): number[];
     /**
      * Register a multi-word phrase for fusion into a single compound token.
      *