solve-engine 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/PackageRegistry-D-Tv_7ca.d.cts

@@ -0,0 +1,2572 @@
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-CK8cQu2a.cjs';
+import { V as Value } from './Value-KtAQNHur.cjs';
+import { IVariableSource } from './variables.cjs';
+import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-BJdhlnej.cjs';
+import { IAsyncResolver } from './resolvers.cjs';
+import { T as TokenFusion, N as NormalizerRule } from './NormalizerRule-BrVoVjmP.cjs';
+import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, L as LineExecutionContext } from './ScopeManager-CKfQtl7l.cjs';
+import { a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.cjs';
+import { QueryClient } from '@tanstack/query-core';
+import { E as EngineError } from './EngineError-DvPSnhZi.cjs';
+import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-DPUQt7yL.cjs';
+import { T as Token } from './Token-0jpvUdPY.cjs';
+import { D as DEFAULT_CONFIG, E as EngineConfig } from './Configuration-fVpd-HC-.cjs';
+
+/**
+ * One line's compiled bytecode, plus the variables it reads and writes.
+ *
+ * The reads and writes are what let the dependency graph re-evaluate only the
+ * lines an edit actually affected.
+ */
+declare class LineCacheEntry {
+    result: Value;
+    bytecode: BytecodeProgram;
+    readVariables: string[];
+    writeVariable: string | null;
+    constructor(result: Value, bytecode: BytecodeProgram, readVariables: string[], writeVariable: string | null);
+}
+/**
+ * Per-line result + bytecode cache.
+ *
+ * Entries are stored in a two-level map (line number → expression → entry)
+ * so per-line operations, getEntryForLine, removeAllForLine, are O(1)
+ * lookups instead of scans over every cached key. Entries with no
+ * expression are stored under the empty-string key.
+ *
+ * The string keys exposed by keys()/forEach() keep the historical
+ * "line" / "line:expression" format for diagnostics consumers.
+ *
+ * INVARIANT: at most one entry per line number at a time. `set()` stores
+ * the expression alongside the entry ONLY as a same-key staleness check for
+ * `get(line, expression)`, a line's previous text is never meaningfully
+ * cacheable once the line has moved on, since `get()`/`getEntryForLine()`
+ * are only ever called with the line's CURRENT text (see
+ * `ExpressionEngine.reEvaluateLine()`). Before this invariant was enforced,
+ * every distinct keystroke state of a line accumulated its own entry here
+ * forever (nothing ever called `remove()`/`removeAllForLine()` per-edit,
+ * only a full `clear()` on document switch), an unbounded, session-long
+ * memory leak reachable via ordinary typing, and a latent correctness bug
+ * in `getEntryForLine()`, which picks "first in insertion order" and could
+ * silently return a STALE entry from an old edit of the line instead of
+ * its current one once more than one entry had piled up.
+ */
+declare class LineCache {
+    /** line number → (expression, or "" for expressionless entries) → entry */
+    private byLine;
+    private count;
+    private static exprKey;
+    private static displayKey;
+    get(line: number, expression?: string): LineCacheEntry | undefined;
+    /** Find any cache entry for the given line number, regardless of expression suffix */
+    getEntryForLine(line: number): LineCacheEntry | undefined;
+    set(line: number, entry: LineCacheEntry, expression?: string): void;
+    has(line: number, expression?: string): boolean;
+    remove(line: number, expression?: string): void;
+    removeAllForLine(line: number): void;
+    clearLine(line: number): void;
+    /**
+     * Number of entries in the cache. Useful for diagnostics.
+     */
+    get size(): number;
+    clear(): void;
+    /**
+     * Iterate all cache entries for diagnostics/debugging.
+     */
+    forEach(callback: (key: string, entry: LineCacheEntry) => void): void;
+    /**
+     * Get all entry keys.
+     */
+    keys(): string[];
+}
+
+/**
+ * Persistent per-line state tracked by the DocumentModel.
+ *
+ * Each line receives an immutable `lineId` that survives structural edits
+ * (insertions, deletions, line shifts). This allows caches, the dependency
+ * graph, and VM checkpoints to reference lines by ID instead of by volatile
+ * line numbers.
+ *
+ * ── Multi-expression support ─────────────────────────────────────────
+ * A single document line may contain multiple inline solves (`s\`...\``).
+ * To support this without breaking the 1:1 line-to-DAG-node contract:
+ * - `expressions[]` holds all extracted expression strings (1 entry for
+ *   full-line expressions, N entries for N inline solves).
+ * - `bytecodes[]` holds compiled bytecode in corresponding order.
+ * - `results[]` holds evaluation **result groups** in corresponding order.
+ *   Each element is a `Value[]`, a group of Values produced by that expression.
+ *   For variable definitions, the group always has exactly 1 element.
+ *   For multi-output expressions (e.g., currency conversion), the group
+ *   may have multiple Values (one per target unit).
+ * - `reads[]` and `writes[]` are aggregated across ALL expressions on
+ *   the line, the DAG treats the line as a single dependency node.
+ * - `inlineSolveCount` is 0 for full-line expressions, >0 for inline solves.
+ */
+interface LineState {
+    /** Immutable unique identifier, survives all structural edits. */
+    readonly lineId: number;
+    /** djb2 hash of the line text, used for O(1) change detection. */
+    textHash: number;
+    /** The full line text (may include markdown). */
+    text: string;
+    /**
+     * Extracted expression texts.
+     * - Full-line expressions: one entry (the trimmed text).
+     * - Inline solve lines: one entry per `s\`...\`` span, in left-to-right order.
+     * - Markdown-only lines: empty array.
+     */
+    expressions: string[];
+    /**
+     * Compiled bytecode for each expression, in corresponding order.
+     * Parallel to {@link expressions}.
+     */
+    bytecodes: BytecodeProgram[];
+    /** Variables this line reads (for dependency tracking). Aggregated across all expressions. */
+    reads: string[];
+    /** Variables this line writes (empty if not a variable definition). Aggregated across all expressions. */
+    writes: string[];
+    /**
+     * Evaluation result groups for each expression, in corresponding order.
+     * Each `Value[]` is a group of Values produced by one expression.
+     * Variable definitions always produce exactly 1 Value per group.
+     * Multi-output expressions (e.g. currency conversion) may produce N Values.
+     */
+    results: Value[][];
+    /**
+     * Convenience accessor for the first expression's first result.
+     * Equals `results[0]?.[0] ?? null`. For single-expression lines,
+     * this is the primary result. For multi-expression (inline solve) lines,
+     * prefer accessing `results[i][j]` directly.
+     */
+    result: Value | null;
+    /** True if this line needs re-evaluation. */
+    dirty: boolean;
+    /** True if any expression on this line defines a variable (never evict bytecode). */
+    isVariableDef: boolean;
+    /** True if this line contains only markdown (no evaluable expression). */
+    isEmpty: boolean;
+    /**
+     * Number of inline solve expressions on this line.
+     * 0 = full-line expression (or markdown-only).
+     * >0 = N inline solves embedded in markdown text.
+     */
+    inlineSolveCount: number;
+}
+/** The visible line range, used to decide which lines are evaluated eagerly. */
+interface ViewportRange {
+    startLine: number;
+    endLine: number;
+}
+/** Describes a structural change to the document's line list. */
+interface LineChange {
+    /** 1-based line number where the change starts. */
+    startLine: number;
+    /** Number of lines deleted (0 for pure insertion). */
+    deleteCount: number;
+    /** New line texts inserted in place of deleted lines. */
+    insertLines: string[];
+}
+/** Result of applying changes to the document model. */
+interface ApplyChangesResult {
+    /** Line IDs of newly inserted lines. */
+    inserted: number[];
+    /** Line IDs that were removed. */
+    removed: number[];
+}
+/**
+ * Persistent document model with O(log N) line lookups and structural edits.
+ *
+ * Design:
+ * - Each line has an immutable `lineId` (monotonically increasing counter).
+ * - `LineState` objects are stored in a `Map<lineId, LineState>` for O(1) access.
+ * - Line ordering is maintained in a `SegmentTree` (order-statistic Treap) that
+ *   supports O(log N) insert, delete, and get-at-index operations.
+ * - A lazy position cache (`Map<lineId, number>`) provides O(1) position lookups
+ *   after the first `getLinePosition()` call and is invalidated on structural edits.
+ *
+ * Key invariant: line IDs never change, only their positions in the order tree.
+ * This means cached bytecode, dependency graph entries, and VM checkpoints
+ * keyed by lineId remain valid across all structural edits.
+ */
+declare class DocumentModel {
+    /** Persistent line ID → LineState. */
+    private lines;
+    /** Order-statistic treap representing the current document line order. */
+    private orderTree;
+    /** Monotonically increasing counter for new line IDs. */
+    private nextLineId;
+    /**
+     * Lazy position cache: lineId → 1-based position.
+     * Built on first `getLinePosition()` call, invalidated on structural edits.
+     */
+    private _positionCache;
+    /**
+     * Line IDs currently marked dirty, maintained alongside every
+     * `state.dirty` mutation (in this class and in every other module that
+     * holds a direct `LineState` reference: ThreeTierEvaluator, PageManager).
+     * Lets {@link hasAnyDirtyLineBefore} answer "is anything before position
+     * X dirty" in O(d log N), d = current dirty count, typically tiny once
+     * a document has settled after its initial evaluation, instead of
+     * O(N log N), which used to mean every scroll event re-walked the WHOLE
+     * document via `getLineAt()` regardless of how little of it was actually
+     * dirty. Benchmarked: ~10.6ms per setViewport() call scrolled near the
+     * bottom of a 20k-line document before this fix.
+     */
+    private dirtyLineIds;
+    /**
+     * Initialize or replace the entire document from a text blob.
+     * Clears all existing state and assigns new persistent line IDs.
+     */
+    setDocument(text: string): void;
+    /**
+     * Apply one or more line-level changes to the document.
+     *
+     * **Precondition:** Changes must be **non-overlapping** in their line ranges.
+     * If two changes target the same or adjacent lines, the reverse-order
+     * processing may produce incorrect results because the first-applied
+     * change shifts the line numbers that the second change references.
+     *
+     * Changes are applied in **reverse order** (highest startLine first) so
+     * that earlier changes in the document don't shift the indices of later
+     * changes during processing.
+     *
+     * Returns both the newly inserted line IDs and the removed line IDs.
+     * Callers should use `removed` to clean up the dependency graph and
+     * other data structures keyed by lineId.
+     */
+    applyChanges(changes: LineChange[]): ApplyChangesResult;
+    /**
+     * Insert new lines at the given 1-based position.
+     * Convenience wrapper around applyChanges.
+     */
+    insertLines(atLine: number, texts: string[]): number[];
+    /**
+     * Delete lines in the given 1-based range [startLine, endLine] inclusive.
+     * Convenience wrapper around applyChanges.
+     */
+    deleteLines(startLine: number, endLine: number): number[];
+    /**
+     * Update the text of a single line in place.
+     * If the text hash differs, marks the line dirty and clears its
+     * bytecode/result so it gets re-evaluated.
+     *
+     * Returns true if the text actually changed (hash mismatch).
+     */
+    editLine(lineNumber: number, newText: string): boolean;
+    /**
+     * Get the LineState at the given 1-based line position. O(1).
+     */
+    getLineAt(position: number): LineState | undefined;
+    /**
+     * Get the 1-based position of a line by its persistent ID.
+     * Returns -1 if the line ID is not in the document.
+     *
+     * Uses a lazy position cache: O(N) on first call after structural edit,
+     * O(1) on subsequent calls. The cache is invalidated by any structural edit.
+     */
+    getLinePosition(lineId: number): number;
+    /**
+     * Get all LineState entries within the given viewport range (1-based, inclusive).
+     * Uses SegmentTree.getRange() for O(viewport + log N) collection instead of
+     * O(viewport × log N) per-line lookups.
+     */
+    getVisibleLines(startLine: number, endLine: number): LineState[];
+    /**
+     * Get all LineState entries in order. Useful for batch processing.
+     */
+    getAllLines(): LineState[];
+    /**
+     * Get a LineState by its persistent line ID. O(1).
+     */
+    getLineById(lineId: number): LineState | undefined;
+    /**
+     * Get all lines that are marked dirty.
+     */
+    getDirtyLines(): LineState[];
+    /**
+     * Whether any line before `position` (1-based, exclusive) is dirty.
+     *
+     * Used by ThreeTierEvaluator.setViewport() to decide whether cached
+     * checkpoint state might be stale and a full evaluate() (from line 1) is
+     * needed instead of the cheap viewport-only path.
+     *
+     * O(d log N) where d = current dirty line count via {@link dirtyLineIds},
+     * not O(N log N), a document that's mostly clean (the steady state after
+     * initial load) answers this in the cost of resolving a handful of
+     * lineIds to positions, not walking every line up to `position`.
+     */
+    hasAnyDirtyLineBefore(position: number): boolean;
+    /**
+     * Whether any **variable-definition** line before `position` (1-based,
+     * exclusive) is dirty.
+     *
+     * Narrower than {@link hasAnyDirtyLineBefore}: `VMCheckpointer.snapshot()`
+     * only ever records state for lines with `writes.length > 0` (see
+     * VMCheckpoints.ts), so a dirty plain-expression line before the viewport
+     * cannot have invalidated any checkpoint, there's no checkpoint entry
+     * for it to invalidate. Only a dirty variable-def line can mean the VM
+     * state a checkpoint would restore is stale.
+     *
+     * This distinction matters because `PageManager.evictPageBytecode()`
+     * marks evicted non-variable-def lines dirty (so they get Tier 1 if
+     * scrolled back into view), and Tier 3's compile-only path never clears
+     * `dirty` for non-variable-def lines by design. Using the broader
+     * `hasAnyDirtyLineBefore` here meant scrolling far into a large,
+     * variable-def-free document would trip `setViewport()`'s fallback to
+     * `evaluate()` on every single call, evaluate() reprocesses the evicted
+     * lines via Tier 3, which recompiles their bytecode without clearing
+     * dirty, so the very next `maintainAfterEval()` re-evicts and re-dirties
+     * the same lines, forever re-triggering the fallback on an otherwise
+     * unchanged viewport.
+     */
+    hasAnyDirtyVariableDefLineBefore(position: number): boolean;
+    /** Number of lines currently marked dirty. For diagnostics/tests. */
+    get dirtyCount(): number;
+    /**
+     * Verify that bytecode compiled by a worker is still valid for this line.
+     *
+     * When Phase 5.2h sends compilation to a worker, the worker posts back
+     * `{lineId, bytecode, reads, writes, compiledAgainstHash}`. Between dispatch
+     * and response, the user may have edited the line. This method lets the
+     * main thread check whether the bytecode is still applicable.
+     *
+     * @returns true if the line still exists and its text hash matches.
+     */
+    isBytecodeValid(lineId: number, compiledAgainstHash: number): boolean;
+    /**
+     * Mark a line as clean (re-evaluated successfully).
+     */
+    markClean(lineId: number): void;
+    /**
+     * Mark a line as dirty (needs re-evaluation) by its 1-based position.
+     * Convenience for callers that have line numbers instead of line IDs.
+     */
+    markDirtyByLineNumber(lineNumber: number): void;
+    /**
+     * Mark a line as dirty (needs re-evaluation).
+     */
+    markDirty(lineId: number): void;
+    /**
+     * Mark all lines as dirty (e.g., after plugin register/unregister).
+     */
+    invalidateAll(): void;
+    /**
+     * Update a line's evaluation state after successful execution (Tier 1 / Tier 2).
+     *
+     * Sets results, bytecodes, reads, writes, and marks the line clean.
+     * Supports multi-expression lines (inline solves) via parallel arrays.
+     *
+     * @param lineId - Persistent line identifier.
+     * @param results - Evaluation result groups for each expression (in order). Each element is a Value[].
+     * @param bytecodes - Compiled bytecode for each expression (in order).
+     * @param expressions - Extracted expression strings (in order).
+     * @param reads - Aggregated read variables across all expressions.
+     * @param writes - Aggregated write variables across all expressions.
+     * @param isVariableDef - True if any expression defines a variable.
+     * @param inlineSolveCount - Number of inline solves (0 for full-line).
+     */
+    updateLineResult(lineId: number, results: Value[][], bytecodes: BytecodeProgram[], expressions: string[], reads: string[], writes: string[], isVariableDef: boolean, inlineSolveCount?: number): void;
+    /**
+     * Update a line's compile-only state (Tier 3: background compilation).
+     *
+     * Stores expressions, bytecodes, reads, and writes. Does NOT set results
+     * and does NOT mark the line clean, it still needs execution (Tier 1 or
+     * Tier 2) to produce results. This distinction allows the three-tier
+     * evaluation strategy: compile invisible lines in the background without
+     * executing them, then execute from cached bytecode when scrolled into view.
+     *
+     * @param lineId - Persistent line identifier.
+     * @param expressions - Extracted expression strings (in order).
+     * @param bytecodes - Compiled bytecode for each expression (in order).
+     * @param reads - Aggregated read variables across all expressions.
+     * @param writes - Aggregated write variables across all expressions.
+     * @param isVariableDef - True if any expression defines a variable.
+     * @param inlineSolveCount - Number of inline solves (0 for full-line).
+     */
+    updateLineCompiled(lineId: number, expressions: string[], bytecodes: BytecodeProgram[], reads: string[], writes: string[], isVariableDef: boolean, inlineSolveCount?: number): void;
+    get lineCount(): number;
+    get isEmpty(): boolean;
+    /**
+     * Iterator over LineState in document order.
+     */
+    [Symbol.iterator](): IterableIterator<LineState>;
+    clear(): void;
+    /**
+     * Serialize the document model to a plain object for debugging.
+     */
+    toJSON(): object;
+}
+
+/** Emitted when one or more lines have updated results after async resolution. */
+interface LinesUpdatedEvent {
+    type: "lines-updated";
+    /** Line numbers whose results changed (1-based). */
+    lineNumbers: number[];
+    /** The query keys whose resolution triggered this update. */
+    affectedQueryKeys: string[];
+}
+/** Emitted when an async resolution fails with an error. */
+interface AsyncErrorEvent {
+    type: "error";
+    /** The query key that failed. */
+    queryKey: string;
+    /** The package whose resolver failed. */
+    packageId: string;
+    /** The error that caused the failure. */
+    error: Error;
+}
+/** Something an async resolution produced: updated lines, or a failure. */
+type AsyncResolutionEvent = LinesUpdatedEvent | AsyncErrorEvent;
+interface BatchEntry {
+    /** The query key that just resolved (or errored). */
+    queryKey: string;
+    /** The package that owns this data. */
+    packageId: string;
+    /** AbortSignal for staleness detection. */
+    signal: AbortSignal;
+    /** Whether this was an error resolution. */
+    isError: boolean;
+    /** Error if isError. */
+    error?: Error;
+}
+/**
+ * Micro-batches async resolution completions into a single DAG walk + re-evaluation pass.
+ *
+ * When multiple promises resolve within the same event-loop tick (e.g., 3 currency
+ * rates: USD→GBP, USD→EUR, USD→JPY all return within 2ms), this batcher collapses
+ * them into ONE DAG walk and ONE re-execution pass instead of 3 separate ones.
+ *
+ * Lifecycle:
+ * - Engine calls `add()` after each `resolveAsync()` completes
+ * - `queueMicrotask()` schedules `flush()` for the end of the current tick
+ * - `flush()` deduplicates queryKeys, walks DAG once for all resolved keys,
+ *   topologically sorts affected lines, re-executes, and fires listener events
+ *
+ * Perf: For N resolutions in a tick, reduces DAG walks from N to 1 and
+ * re-executions from N*avgAffected to totalAffected.
+ *
+ * ## Streaming Architecture
+ *	 * Events are published to a native {@link ReadableStream}. Stream-based
+     * consumers read from the stream via `getReader()`, gaining built-in
+     * cancellation (`reader.cancel()`), proper resource cleanup
+     * (`reader.releaseLock()`), and the ability to
+     * `pipeTo()` / `pipeThrough()` / `tee()` the event flow.
+ *
+ * The stream uses a configurable {@link CountQueuingStrategy} with a default
+ * `highWaterMark` of 64 events to limit the internal buffer size.
+ */
+declare class AsyncResolutionBatcher {
+    private pending;
+    private scheduled;
+    /** Set to true by clearPending(), flush() checks this to abort stale work. */
+    private cleared;
+    private dag;
+    private lineCache;
+    private vm;
+    /**
+     * Worker pool for offloading VM re-execution when the affected line
+     * count exceeds WORKER_OFFLOAD_THRESHOLD (50). Lazily created on
+     * first dispatch; cleared on clearAll().
+     */
+    private executionPool;
+    /**
+     * Number of flushes actually dispatched to the worker pool (as opposed
+     * to falling back to the main thread because Worker is unavailable).
+     * Exposed via {@link workerOffloadCount} for the Workers diagnostic tab.
+     */
+    private workerOffloadDispatchCount;
+    /**
+     * Default high-water mark for the internal event stream.
+     * Limits the internal buffer size before the stream signals to
+     * consumers that they need to catch up.
+     */
+    private static readonly DEFAULT_HIGH_WATER_MARK;
+    /**
+     * Internal {@link ReadableStream} for async resolution events.
+     * All events (lines-updated and error) are enqueued here.
+     */
+    private _eventStream;
+    /**
+     * Controller for the internal event stream. Set during stream
+     * initialization; cleared on stream cancellation or clearAll().
+     */
+    private _streamController;
+    /**
+     * Test-only synchronous capture array. When enabled (non-null), every
+     * event is synchronously pushed here in addition to the stream.
+     * Tests read from this array to avoid async stream reader timing issues.
+     */
+    _testCaptures: AsyncResolutionEvent[] | null;
+    /**
+     * Called for each line whose result is patched after an async resolution,
+     * on both the main-thread and worker-pool paths.
+     *
+     * **A host that displays async results must set this.** It is the only
+     * mechanism that moves a resolved value out of the LineCache and into the
+     * host's own document state. The engine cannot do it itself: it does not own
+     * a document, the host does, and the batcher has no reference to one.
+     *
+     * Nullable rather than a constructor parameter because it is cleared by
+     * `clearAll()` and re-wired on re-subscribe, so it cannot be readonly. That
+     * makes it easy to miss, which is why {@link warnIfUnwired} exists: leaving
+     * it unset means async values resolve into the cache and are never shown,
+     * with nothing to indicate why. A host that genuinely does not want async
+     * results should not register async resolvers at all.
+     */
+    onLineResult: ((lineNumber: number, value: Value) => void) | null;
+    /**
+     * Whether {@link warnIfUnwired} has already fired.
+     *
+     * Once per instance, not once per resolution. A document with fifty live
+     * data lines would otherwise produce fifty identical warnings on the first
+     * fetch, which is how a useful warning becomes noise people filter out.
+     */
+    private warnedAboutMissingHook;
+    /**
+     * Warn once if an async result resolved with no {@link onLineResult} wired.
+     *
+     * The failure this catches is silent by nature: the value arrives, the cache
+     * updates, and the line keeps showing pending forever. Without this a host
+     * author has no thread to pull on.
+     */
+    private warnIfUnwired;
+    /** High-water mark used when (re)creating the event stream. */
+    private readonly highWaterMark;
+    constructor(dag: DependencyGraph, lineCache: LineCache, vm: VM, highWaterMark?: number);
+    /**
+     * Create a fresh internal event stream and wire its controller.
+     * Called from the constructor and again from clearAll() so the batcher
+     * keeps emitting events after an engine clear, the engine instance
+     * (and this batcher) live on across clear() calls.
+     */
+    private createEventStream;
+    /**
+     * Add a resolved query key to the pending batch.
+     *
+     * Called by ExpressionEngine.resolveAsync() after a promise resolves or errors.
+     * If this is the first entry in the current tick, schedules a microtask flush.
+     */
+    add(entry: BatchEntry): void;
+    /**
+     * Get the native event stream for stream-based consumers.
+     *
+     * Use this for backpressure, cancellation, or the ability
+     * to `pipeTo()` / `pipeThrough()` the event flow.
+     *
+     * @returns A {@link ReadableStream} that emits {@link AsyncResolutionEvent}
+     *          items as the batcher processes async resolutions.
+     */
+    getEventStream(): ReadableStream<AsyncResolutionEvent>;
+    /** Number of resolutions currently queued for the next flush. */
+    get pendingCount(): number;
+    /** Number of pending entries collapsed by (packageId, queryKey) deduplication. */
+    get dedupCount(): number;
+    /**
+     * Whether the internal event stream currently has an active reader.
+     * `1` if a consumer has called `getEventStream().getReader()` (or
+     * otherwise locked the stream) and not released it, `0` otherwise.
+     */
+    get listenerCount(): number;
+    /** Number of flushes that were actually dispatched to the worker pool. */
+    get workerOffloadCount(): number;
+    /** Remove all listeners and cancel pending batch. Called on engine clear. */
+    clearAll(): void;
+    /**
+     * Flush all pending resolutions in a single batched pass.
+     *
+     * Called automatically via queueMicrotask. Never called directly.
+     */
+    private flush;
+    /**
+     * Topologically sort affected lines using Kahn's algorithm.
+     *
+     * Lines that produce variables come before lines that consume them.
+     * This ensures correct evaluation order when multiple interdependent
+     * lines are affected by async resolution.
+     */
+    private topologicalSort;
+    /**
+     * Offload VM re-execution to the worker pool for large batches.
+     *
+     * Called when ordered.length > WORKER_OFFLOAD_THRESHOLD (50).
+     * Clones bytecode ArrayBuffers, dispatches to workers, and asynchronously
+     * patches results back into LineCache before notifying listeners.
+     *
+     * Handles pending results: lines that return { type: 'pending' } from the
+     * worker are NOT marked as updated, the engine's resolveAsync will handle
+     * them when the async resolver completes.
+     *
+     * Safety: checks this.cleared before applying results, if the engine was
+     * cleared while the worker batch was in-flight, results are discarded.
+     */
+    private reExecuteViaWorkerPool;
+    /**
+     * Execute ordered lines on the main thread, update LineCache, and notify
+     * listeners. Returns the list of line numbers that actually changed.
+     *
+     * Used by both flush() (≤50 lines) and reExecuteViaWorkerPool() (fallback
+     * when workers are unavailable). Extracted to avoid code duplication.
+     *
+     * **Per-line containment (fatal-bug fix)**: `executeBytecode()` used to
+     * run here with NO try/catch anywhere in this method's call chain, and
+     * this whole batch runs inside a bare `queueMicrotask` (see `add()`) with
+     * no surrounding try/catch at any caller either, so if any ONE line's
+     * cached bytecode threw (a stack/instruction-limit error, an undefined
+     * variable, a corrupted-bytecode `TypeError`), the `for` loop aborted
+     * immediately: every line scheduled AFTER the failure in this batch was
+     * silently never re-executed or notified even though nothing was wrong
+     * with them, every line BEFORE it had already had its `entry.result`
+     * mutated in-place but `notifyListeners()` was never reached (a silent
+     * `LineCache`/host desync), and, because a bare `queueMicrotask`
+     * callback has no caller to catch it, the exception was uncatchable:
+     * an `uncaughtException` that could crash the host process outright.
+     * (`__tests__/async/AsyncResolutionBatcher.spec.ts`'s topological-sort
+     * describe block used to have a test skipped specifically because of
+     * this. See that file, now un-skipped and rewritten.) Each line's
+     * execution is now its own try/catch: a failure is recorded as an
+     * `Error` `Value` for THAT line (still counted as "updated" so the host
+     * learns about it and stops showing a stale Pending state) and the loop
+     * continues, one line's failure can no longer take out its neighbors.
+     */
+    private reExecuteMainThread;
+    /**
+     * Notify all consumers of an async resolution event.
+     *
+     * Enqueues the event into the internal {@link ReadableStream}.
+     * If the stream has been closed or errored (consumer cancelled),
+     * the enqueue silently fails (caught by try/catch).
+     */
+    private notifyListeners;
+}
+
+/** The pipeline stages allocation is attributed to. */
+type PipelineStage = 'lexer' | 'normalizer' | 'parser' | 'resolver' | 'vm' | 'orchestrator';
+/** What one stage allocated during one measured span. */
+interface StageAllocation {
+    /** Pipeline stage name. */
+    stage: PipelineStage;
+    /** Number of objects allocated (reserved, requires --expose-gc snapshots). */
+    allocCount: number;
+    /** Heap bytes allocated (delta of process.memoryUsage().heapUsed). */
+    allocBytes: number;
+    /** Breakdown of object types allocated (reserved, requires heap snapshots). */
+    objectCounts: Record<string, number>;
+    /** Wall-clock duration in nanoseconds. */
+    wallTimeNs: number;
+    /** Optional: sub-stage name for finer-grained tracking within a stage. */
+    subStage?: string;
+    /** Optional: whether this stage hit a cache (zero-parse, zero-lex). */
+    cacheHit?: boolean;
+}
+/** Per-stage allocation for a single expression, in pipeline order. */
+interface PipelineTelemetry {
+    /** The expression text that was evaluated. */
+    expression: string;
+    /** Per-stage allocation and timing data, in execution order. */
+    stages: StageAllocation[];
+    /** Total heap bytes allocated across all stages. */
+    totalAllocBytes: number;
+    /** Total wall-clock duration in nanoseconds. */
+    totalWallTimeNs: number;
+    /** Whether the expression took the orchestrator fast path. */
+    fastPath: boolean;
+}
+
+/**
+ * Result shapes returned when a whole document is parsed rather than a single
+ * expression.
+ *
+ * These describe what a host renders: which lines carry results, where in each
+ * line those results belong, and what went wrong where it did.
+ */
+
+/**
+ * One inline solve, and where it sits in its line.
+ *
+ * An inline solve is an expression embedded in prose between backticks. A line
+ * can hold several, so positions are what let a host place each result against
+ * the right span rather than at the end of the line.
+ */
+interface InlineSolvePosition {
+    /** Character offset where the expression starts, within its line. */
+    start: number;
+    /** Character offset just past the end of the expression. */
+    end: number;
+    /** The expression text, without the surrounding backticks. */
+    expression: string;
+    /** One-based line number. */
+    lineNumber: number;
+    /** One-based column, for hosts that report positions to a user. */
+    columnNumber: number;
+    /** The evaluated value, or null when evaluation failed or was skipped. */
+    result?: Value | null;
+    /** Message when this span failed, leaving others on the line intact. */
+    error?: string | null;
+}
+/**
+ * One line of a parsed document.
+ *
+ * A line carries either a whole-line expression or a set of inline solves,
+ * never both. `isEmpty` covers the third case: prose, a heading, or a blank.
+ */
+interface ParsedLine {
+    /** One-based line number. */
+    lineNumber: number;
+    /** The raw line text as it appeared. */
+    text: string;
+    /** Character offset of the line start within the whole document. */
+    startPosition: number;
+    /** Character offset just past the line end within the whole document. */
+    endPosition: number;
+    /** Whether the line holds nothing to evaluate. */
+    isEmpty: boolean;
+    /** Whether the line holds backtick-delimited expressions. */
+    hasInlineSolves: boolean;
+    /** Each embedded expression and its position. Empty for a whole-line expression. */
+    inlineSolves: InlineSolvePosition[];
+    /** The whole-line expression, or null when the line has inline solves or nothing. */
+    expression: string | null;
+    /** The whole-line result, or null when there is none or it failed. */
+    result: Value | null;
+    /** Message when the whole-line expression failed. */
+    error: string | null;
+}
+/**
+ * Everything produced by parsing a document.
+ *
+ * Errors are collected rather than thrown. One bad line must not cost the
+ * results of every other line, so failures are reported alongside the lines
+ * that did evaluate.
+ */
+interface ParsingResult {
+    /** Every line in document order, including ones with nothing to evaluate. */
+    lines: ParsedLine[];
+    /** Line count, so a caller need not measure `lines`. */
+    totalLines: number;
+    /** Messages from lines that failed. Those lines are still present above. */
+    errors: string[];
+    /** Stage-by-stage trace, present only when diagnostics were requested. */
+    diagnostics?: DiagnosticReportJSON;
+}
+/** How a document should be parsed. */
+interface UnifiedParsingOptions {
+    /**
+     * How to read the input.
+     *
+     * `markdown` respects headings, comments and code fences, and looks for
+     * inline solves. `raw` treats every line as an expression. `code` is for
+     * input already known to be expressions.
+     */
+    inputType: 'markdown' | 'raw' | 'code';
+    /** Locale for keywords and number formatting. Defaults to English. */
+    localeCode?: string;
+    /** Include line offsets and positions. Costs a little to compute. */
+    includeLineInfo?: boolean;
+    /** Include syntax-highlighting spans. */
+    includeHighlights?: boolean;
+    /** Collect a stage-by-stage trace. For tooling only: it is not free. */
+    includeDiagnostics?: boolean;
+}
+
+/**
+ * DiagnosticPipelineResult, structured pipeline data contract.
+ *
+ * ## Purpose
+ * When `diagnosticMode = true`, the {@link ExpressionEngine} populates this
+ * structured result alongside the existing event-based diagnostic system.
+ * The playground consumes the `stages[]` array directly, no event
+ * reconstruction or timeline parsing needed.
+ *
+ * ## Dual-mode design
+ * - **Production** (`diagnosticMode = false`): stages are empty, zero overhead
+ * - **Diagnostic** (`diagnosticMode = true`): all 15 pipeline stages are populated
+ *   with typed outputs, plus the evaluation result (value, tokens, bytecode)
+ *
+ * ## Stage numbering
+ * | Step | Stage              | Description                                 |
+ * |------|--------------------|---------------------------------------------|
+ * | 1    | pipeline_start     | Pipeline initialization                     |
+ * | 2    | safety_length      | Expression length validation                |
+ * | 3    | lexer              | Token production                            |
+ * | 4    | normalizer         | TokenNormalizer phrase fusion + implicit ops|
+ * | 5    | safety_complexity  | Complexity score validation                 |
+ * | 6    | readwrite          | Variable reads/writes extraction            |
+ * | 7    | cache_check        | Bytecode cache lookup                       |
+ * | 8    | parser             | Pratt parser (skipped on cache hit)         |
+ * | 9    | compiler           | Bytecode compiler (skipped on cache hit)    |
+ * | 10   | async_preflight    | Async resolver preflight check              |
+ * | 11   | vm_execute         | Stack VM execution                          |
+ * | 12   | dag_registration   | Dependency graph registration               |
+ * | 13   | linecache          | Line-cache storage                          |
+ * | 14   | result             | Formatted result value                      |
+ * | 15   | pipeline_end       | Pipeline completion summary                 |
+ *
+ * @module DiagnosticPipelineResult
+ */
+
+/**
+ * A single pipeline stage result displayed in the playground's Pipeline tab.
+ *
+ * Each stage has display metadata (label, icon, color, step number) and
+ * a typed {@link StageOutput | output} payload. Stages are ordered by
+ * {@link stepNumber} and rendered as a vertical flow.
+ */
+interface PipelineStageResult {
+    /**
+     * Unique stage identifier: `'lexer'`, `'normalizer'`, `'vm_execute'`, etc.
+     * Used by the PipelineTab to select the correct renderer.
+     */
+    stage: string;
+    /** Human-readable label (e.g., "VM Execute", "Safety: Length") */
+    label: string;
+    /** Emoji icon for the stage header (e.g., "⚡", "🔤") */
+    icon: string;
+    /**
+     * CSS color class token for styling the stage header.
+     * Maps to `.flow-stage-header.{colorClass}` in main.css.
+     */
+    colorClass: string;
+    /** Sequential step number in the pipeline (1–15) */
+    stepNumber: number;
+    /**
+     * Elapsed nanoseconds from pipeline start.
+     * 0 when timing is disabled or the timeline collector isn't active.
+     */
+    elapsedNs: number;
+    /**
+     * Whether this stage was skipped.
+     * Examples: parser/compiler skipped on cache hit, normalizer skipped with no rules.
+     */
+    skipped: boolean;
+    /** Stage-specific typed output (see {@link StageOutput}) */
+    output: StageOutput;
+}
+/**
+ * Discriminated union of all pipeline stage output types.
+ *
+ * Each stage produces a specific output interface with a `type` discriminator.
+ * The playground uses `stage.output.type` to determine which renderer to use.
+ */
+type StageOutput = PipelineStartOutput | LineClassificationOutput | SafetyLengthOutput | LexerOutput | NormalizerOutput | SafetyComplexityOutput | ReadWriteOutput | CacheCheckOutput | ParserOutput | CompilerOutput | AsyncPreflightOutput | VmExecuteOutput | DagRegistrationOutput | LineCacheOutput | ResultOutput | PipelineEndOutput;
+/** Stage 1: Pipeline initialization with the expression and input type. */
+interface PipelineStartOutput {
+    type: "pipeline_start";
+    /** The raw expression being evaluated */
+    expression: string;
+    /** Input type: `"expression"`, `"markdown"`, etc. */
+    inputType: string;
+}
+/**
+ * Lightweight inline solve span with token indices for diagnostic rendering.
+ *
+ * Unlike {@link InlineSolveSpan} (which carries full character offsets),
+ * this is a diagnostics-only struct focused on token-level access. The
+ * playground uses `startTokenIndex`/`endTokenIndex` to highlight tokens
+ * within the inline solve, and `expression` to show what was evaluated.
+ */
+interface InlineSolveSpanInfo {
+    /** Token index of INLINE_SOLVE_START in the expression's token array */
+    startTokenIndex: number;
+    /** Token index of closing BACKTICK_OPEN in the expression's token array */
+    endTokenIndex: number;
+    /** The expression text between the backticks */
+    expression: string;
+    /** 1-based column of the `s`` marker */
+    columnNumber: number;
+}
+/** Stage 2: Markdown line classification (used by scanDocument path). */
+interface LineClassificationOutput {
+    type: "line_classification";
+    /** The markdown line type (heading, list, expression, etc.) */
+    classification: MarkdownLineType;
+    /** Whether this line should be skipped entirely */
+    skip: boolean;
+    /** Whether the line contains inline solve markers (`s`...``) */
+    hasInlineSolve: boolean;
+    /** Inline solve spans with token indices (empty if none detected). */
+    inlineSolveSpans: InlineSolveSpanInfo[];
+}
+/** Stage 3: Expression length validation against the configured limit. */
+interface SafetyLengthOutput {
+    type: "safety_length";
+    /** Whether the expression passed the length check */
+    passed: boolean;
+    /** Actual length of the expression in characters */
+    expressionLength: number;
+    /** Maximum allowed expression length from config */
+    maxLength: number;
+    /** Error message when the check fails */
+    errorMessage?: string;
+}
+/** Stage 4: Raw token production from the ExpressionLexer. */
+interface LexerOutput {
+    type: "lexer";
+    /** Total number of tokens produced (excluding whitespace) */
+    tokenCount: number;
+    /** Counts per token type (e.g., { NUMBER: 3, IDENT: 1, PLUS: 1 }) */
+    tokenTypes: Record<string, number>;
+    /** Whether parentheses are present in the expression */
+    hasParens: boolean;
+    /** Locale used for keyword resolution (e.g., "en") */
+    locale: string;
+    /**
+     * Raw tokens before normalization.
+     * These are the tokens as they come out of the lexer, before any
+     * phrase fusion or implicit operator insertion.
+     */
+    tokens: Token[];
+}
+/** Stage 5: TokenNormalizer pass with fusion tracking for diagnostic display. */
+interface NormalizerOutput {
+    type: "normalizer";
+    /** Number of tokens before normalization */
+    inputTokenCount: number;
+    /** Number of tokens after normalization (may be fewer due to fusions) */
+    outputTokenCount: number;
+    /**
+     * Fusion events recorded during normalization.
+     * Each entry shows the rule, source tokens, and resulting fused token.
+     * Rendered as the fusion detail table in the Pipeline tab.
+     */
+    fusions: TokenFusion[];
+    /** Per-rule application counts (e.g., [{ rule: "phrase:to the power of", count: 1 }]) */
+    rulesApplied: {
+        rule: string;
+        count: number;
+    }[];
+    /** Post-normalization tokens ready for parsing */
+    tokens: Token[];
+    /**
+     * All registered phrase → tokenType mappings from the PhraseTrie.
+     * Populated by the engine at diagnostic stage build time so the
+     * playground NormalizerTab can render the complete trie structure
+     * rather than only phrases that matched in this evaluation.
+     */
+    phrases: Record<string, string>;
+}
+/** Stage 6: Complexity scoring against the configured limit. */
+interface SafetyComplexityOutput {
+    type: "safety_complexity";
+    /** Whether the expression passed the complexity check */
+    passed: boolean;
+    /** Computed complexity score (tokens + function calls × 5 + max parens × 10) */
+    complexityScore: number;
+    /** Maximum allowed complexity from config */
+    maxComplexity: number;
+    /** Breakdown of the complexity score components */
+    breakdown: {
+        /** Number of tokens in the expression */
+        tokenCount: number;
+        /** Number of function call sites detected */
+        functionCalls: number;
+        /** Maximum parenthesis nesting depth */
+        nestingDepth: number;
+    };
+    /** Error message when the check fails */
+    errorMessage?: string;
+}
+/** Stage 7: Variable reads and writes extracted from the token stream. */
+interface ReadWriteOutput {
+    type: "readwrite";
+    /** Variable names read by this expression */
+    reads: string[];
+    /** Variable names written (assigned) by this expression */
+    writes: string[];
+    /** Whether this expression is a variable assignment (`:var = ...`) */
+    isAssignment: boolean;
+}
+/** Stage 8: Bytecode cache lookup before parsing. */
+interface CacheCheckOutput {
+    type: "cache_check";
+    /** Whether the expression was found in the bytecode cache */
+    hit: boolean;
+    /** Current number of entries in the bytecode cache */
+    cacheSize: number;
+    /** Cache key used for lookup (typically the expression text) */
+    cacheKey: string;
+}
+/** Stage 9: Pratt parser producing an AST from normalized tokens. Skipped on cache hit. */
+interface ParserOutput {
+    type: "parser";
+    /** Matched parselets during parsing */
+    parselets: {
+        type: string;
+        category: string;
+        prefix: boolean;
+    }[];
+    /** Unique parselet type names used in this expression */
+    uniqueParseletTypes: string[];
+    /** Maximum AST depth reached during parsing */
+    astDepth: number;
+}
+/** Stage 10: Bytecode compiler (AST → opcodes). Skipped on cache hit. */
+interface CompilerOutput {
+    type: "compiler";
+    /** Number of opcodes in the compiled program */
+    opcodeCount: number;
+    /** Number of numeric constants in the constant pool */
+    numberConstants: number;
+    /** Number of string constants in the constant pool */
+    stringConstants: number;
+    /** Whether the program contains async opcodes (CALL_PLUGIN) */
+    hasAsync: boolean;
+    /** Whether the program was served from cache */
+    cached: boolean;
+}
+/** Stage 11: Async resolver preflight check before VM execution. */
+interface AsyncPreflightOutput {
+    type: "async_preflight";
+    /**
+     * Resolution path.
+     * - `"sync"`: No async resolvers needed, proceed to VM
+     * - `"pending"`: Data not ready, return pending value and await resolution
+     */
+    path: "sync" | "pending";
+    /** Query key if the expression is pending async resolution */
+    pendingQueryKey?: string;
+    /** Number of registered async resolvers */
+    resolverCount: number;
+    /** Whether the preflight guard was skipped (no async opcodes, no resolvers) */
+    skippedGuard: boolean;
+}
+/** Stage 12: Stack VM execution of the compiled bytecode program. */
+interface VmExecuteOutput {
+    type: "vm_execute";
+    /** Total opcode instructions executed */
+    totalInstructions: number;
+    /** Maximum stack depth reached during execution */
+    stackDepth: number;
+    /** Result type: `"Number"`, `"Uom"`, `"Pending"`, etc. */
+    resultType: string;
+    /** String representation of the result value */
+    resultValue: string;
+    /** Whether the VM returned a pending async result */
+    isPending: boolean;
+}
+/** Stage 13: Dependency graph registration for incremental re-evaluation. */
+interface DagRegistrationOutput {
+    type: "dag_registration";
+    /** Variable reads registered in the DAG */
+    readsRegistered: string[];
+    /** Variable writes registered in the DAG */
+    writesRegistered: string[];
+    /** Data source dependencies registered in the DAG */
+    dataSourcesRegistered: string[];
+}
+/** Stage 14: Line-cache storage of the evaluation result. */
+interface LineCacheOutput {
+    type: "linecache";
+    /** Line number in the document (1-based) */
+    lineNumber: number;
+    /** The expression text stored in cache */
+    expression: string;
+    /** Whether the result was successfully stored */
+    stored: boolean;
+}
+/** Stage 14: Final evaluation result with formatting. */
+interface ResultOutput {
+    type: "result";
+    /** Raw value as a string */
+    rawValue: string;
+    /** Human-friendly formatted value (with locale formatting, units, etc.) */
+    formattedValue: string;
+    /** Value type: `"Number"`, `"Uom"`, `"Percentage"`, etc. */
+    valueType: string;
+    /** Unit of measurement if the result carries a unit (e.g., "km") */
+    unit?: string;
+    /** Error message if evaluation failed (null on success) */
+    error?: string;
+}
+/** Stage 15: Pipeline completion summary with final statistics. */
+interface PipelineEndOutput {
+    type: "pipeline_end";
+    /** Whether the pipeline completed successfully */
+    success: boolean;
+    /** Total tokens processed (pre-normalization) */
+    totalTokens: number;
+    /** Total opcodes in the compiled program */
+    totalOpcodes: number;
+    /** Whether the result came from the bytecode cache */
+    cacheHit: boolean;
+}
+/**
+ * Complete diagnostic pipeline result produced by
+ * {@link ExpressionEngine.evaluateExpressionWithDiagnostic | evaluateExpressionWithDiagnostic()}
+ * when `diagnosticMode = true`.
+ *
+ * Includes all 15 pipeline stages with typed outputs, plus the evaluation
+ * result data (value, tokens, bytecode). The playground renders the `stages`
+ * array as a data-driven pipeline flow diagram without any reconstruction
+ * from diagnostic events.
+ *
+ * When `diagnosticMode = false` (production), the `diagnostic` field is
+ * `undefined` and only the minimal result data is returned.
+ */
+interface DiagnosticPipelineResult {
+    /**
+     * Ordered pipeline stages (15 stages total).
+     * Each stage has display metadata and a typed output payload.
+     */
+    stages: PipelineStageResult[];
+    /** The final evaluation result value */
+    value: Value;
+    /** Normalized tokens (post-TokenNormalizer, ready for parsing) */
+    tokens: Token[];
+    /** The compiled bytecode program */
+    program: BytecodeProgram;
+    /** Error message if evaluation failed, `null` otherwise */
+    error: string | null;
+    /** DAG dependency graph snapshot (consumers, writes, reads, dataSourceDeps) */
+    dagSnapshot?: DagSnapshot;
+    /** Engine-wide cache snapshot (bytecode, line cache, async cache) */
+    cacheSnapshot?: CacheSnapshot;
+    /** AsyncResolutionBatcher metrics (pending, dedup, worker, listener counts) */
+    batcherMetrics?: BatcherMetrics;
+    /** VM checkpoints from the ThreeTierEvaluator's checkpointer */
+    checkpoints?: CheckpointSnapshot[];
+}
+/** Bytecode cache entry for diagnostic rendering. */
+interface BytecodeCacheEntry {
+    expression: string;
+    opcodesLength: number;
+    numbersLength: number;
+    stringsLength: number;
+    hasAsync: boolean;
+}
+/** Line cache entry info for diagnostic rendering. */
+/** One line's cached bytecode and the variables it reads and writes. */
+interface LineCacheEntryInfo {
+    key: string;
+    lineNumber: number;
+    resultType: string;
+    resultValue: string;
+    reads: string[];
+    writeVar: string | null;
+}
+/** Async cache package info for diagnostic rendering. */
+interface AsyncCachePackageInfo {
+    packageId: string;
+    resolvedCount: number;
+    inFlightCount: number;
+    errorCount: number;
+    /** Per-package TTL in milliseconds (undefined = no expiry). */
+    ttlMs?: number;
+    entries: Array<{
+        key: string;
+        status: "resolved" | "in_flight" | "error";
+        errorMessage?: string;
+        createdAt?: number;
+        value?: string;
+    }>;
+}
+/** Full cache snapshot for diagnostic rendering. */
+interface CacheSnapshot {
+    bytecode: BytecodeCacheEntry[];
+    lineCache: LineCacheEntryInfo[];
+    asyncCache: AsyncCachePackageInfo[];
+}
+/** Batcher metrics for Workers diagnostic tab. */
+interface BatcherMetrics {
+    pendingCount: number;
+    dedupCount: number;
+    workerOffloadCount: number;
+    listenerCount: number;
+}
+/** VM checkpoint snapshot for diagnostic rendering. */
+interface CheckpointSnapshot {
+    lineNumber: number;
+    variables: string[];
+    variableCount: number;
+}
+
+/**
+ * Return type of {@link evaluateLine} and {@link evaluateExpression}.
+ *
+ * A single-element `Value[]`, kept as an array (rather than a bare
+ * `Value`) for API stability.
+ */
+interface EvalResults extends Array<Value> {
+}
+/** Explicit result of {@link ExpressionEngine.evaluateLineDetailed}. */
+interface LineEvaluation {
+    /** The evaluated value, wrapped in a single-element array. */
+    values: Value[];
+}
+/**
+ * Core expression evaluation engine, the top-level orchestrator.
+ *
+ * Owns the full evaluation pipeline: lexing, parsing, bytecode compilation,
+ * VM execution, DAG-based dependency tracking, and async resolution.
+ *
+ * Key responsibilities:
+ * - Pipeline orchestration: lex → parse → compile → execute → cache
+ * - Bytecode caching for repeated expressions
+ * - DAG-based incremental re-evaluation on variable changes
+ * - Async resolution via ResolverRegistry + AsyncResolutionBatcher
+ * - Package registration (built-in + external plugins)
+ * - Safety validation (length, complexity, nesting)
+ * - Diagnostic pipeline integration
+ * - Keystroke-level AbortSignal management
+ *
+ * Each engine instance has its own isolated lexer, registry, parser, and
+ * LineCache. The VM uses this engine's own opcode registry, and each engine
+ * creates its own VM instance with configurable limits.
+ *
+ * ## Lifecycle
+ *
+ * Call {@link ExpressionEngine.clear} when you are finished with an engine that
+ * has parsed a document. Dropping your last reference is not sufficient: the
+ * async batcher is reachable from the module-level data-query service, so a
+ * parsed engine stays retained until `clear()` releases it. Measured per engine
+ * after a forced collection, with a 40-line document:
+ *
+ * | Lifecycle | Retained |
+ * | --- | --- |
+ * | constructed, never parsed | 8.2KB |
+ * | constructed and parsed | 46.9KB |
+ * | constructed, parsed, cleared | 10.0KB |
+ *
+ * This matters for hosts that create one engine per document or per tab, which
+ * is the intended usage. Reusing a single engine across documents is also fine:
+ * `clear()` resets it for the next one rather than consuming it.
+ *
+ * @example
+ * ```typescript
+ * import { ExpressionEngine } from "solve-engine";
+ * const engine = new ExpressionEngine("en");
+ * const [value] = engine.evaluateExpression("2 + 2 * 10");
+ * console.log(value.toNumber()); // 22
+ * ```
+ */
+declare class ExpressionEngine {
+    private dag;
+    private lineCache;
+    private scopeManager;
+    private lexer;
+    private registry;
+    private parser;
+    private localeCode;
+    private vm;
+    /**
+     * Registries this engine owns, rather than shares with every other
+     * instance in the process. See {@link EngineContext}.
+     */
+    private readonly context;
+    private config;
+    private diagnosticPipeline;
+    /**
+     * Direct reference to the timeline collector registered above (when
+     * diagnosticMode is on), kept alongside the generic `diagnosticPipeline`
+     * so `evaluateExpressionWithDiagnostic()` can cheaply read its current
+     * `parseletMatchCount` as a "before" baseline without paying for a full
+     * `getReport()` build (which copies the whole cumulative parselets
+     * array). See that method's use of it for why a baseline is needed at
+     * all, `TimelineDiagnosticCollector`'s state is deliberately cumulative
+     * across an entire document pass, not reset per line.
+     */
+    private timelineCollector?;
+    /** Registry of async resolvers from registered packages. */
+    private resolverRegistry;
+    /**
+     * Per-package record of contributions made to the SHARED registries
+     * (this engine's variable resolver / resolver namespaces), so
+     * {@link unregisterPackage} can reverse them. Keyed by package name.
+     */
+    private packageContributions;
+    /**
+     * The actual `IEnginePackage` descriptor of every package currently
+     * registered on this engine instance, keyed by name, separate from
+     * {@link packageContributions} (which tracks what was WRITTEN into
+     * shared registries, not the original descriptor). Used by
+     * {@link registerPackage}'s automatic `checkPackageCompatibility()` call
+     *. See `api/PackageCompatibility.ts`'s module doc for why this exists.
+     */
+    private registeredPackages;
+    /**
+     * The `DocumentModel` this engine is currently evaluating, if any
+     * `null` for a bare engine with no document (e.g. anything only ever
+     * calling `evaluateExpression()`). `ExpressionEngine` doesn't own its
+     * `DocumentModel` (`ThreeTierEvaluator` constructs and owns both as
+     * siblings). This is set once, via {@link setDocumentModel}, purely so
+     * {@link makeLineContext} can answer "what's line N's cached result"
+     * for cross-line features (`prev`/`line<N>`/aggregation. See
+     * `packages/lines/`) without the engine needing to own document
+     * lifecycle itself.
+     */
+    private documentModel;
+    /**
+     * Called once by `ThreeTierEvaluator`'s constructor. Not part of the
+     * public evaluate-a-document contract, purely internal wiring so
+     * {@link makeLineContext} has something to read from.
+     */
+    setDocumentModel(doc: DocumentModel | null): void;
+    /**
+     * Build the {@link LineExecutionContext} passed to `executeBytecode()`
+     * for a given line. `lineNumber = -1` (the existing sentinel
+     * `evaluateExpression()`/`evaluateLine(-1, ...)` already use for "no
+     * real document") naturally produces a context with both closures
+     * `undefined`, a cross-line plugin function must check for that itself
+     * and return a clear error, never assume line 0 exists.
+     */
+    private makeLineContext;
+    /**
+     * Package-contributed completion candidates (`IEnginePackage.completionItems`),
+     * keyed by package name, engine-instance-local, not a shared registry
+     * (unlike tokenCategories), so no separate register/unregister module is
+     * needed: registerPackage()/unregisterPackage() just set/delete the
+     * package's own entry. {@link getPackageCompletionItems} flattens it.
+     */
+    private packageCompletionItems;
+    /**
+     * Keystroke-level AbortSignal, set by the UI layer (MarkdownEditorViewPlugin)
+     * before each evaluation. When the user types a new keystroke, the old signal
+     * is aborted, causing all in-flight async work (fetches, preflight checks,
+     * batcher flushes) to be canceled atomically.
+     *
+     * executeAndStore() and executeRaw() link their local AbortControllers to
+     * this signal so that when the keystroke changes, all per-evaluation controllers
+     * are aborted together.
+     */
+    private keystrokeSignal;
+    /**
+     * Micro-batcher that collapses multiple async resolutions into a single
+     * DAG walk + re-evaluation pass. Replaces the old single-callback pattern.
+     */
+    private batcher;
+    /** Post-lexer token normalizer for phrase fusion, implicit multiply, etc. */
+    private normalizer;
+    /** TanStack Query client, injected into resolvers for cache reads/writes. */
+    readonly queryClient: QueryClient;
+    private bytecodeCache;
+    /**
+     * Insert into the bytecode cache, evicting the oldest entry when full.
+     *
+     * Bug fix (found during release hardening): this used to check against
+     * a hardcoded `BYTECODE_CACHE_MAX_ENTRIES = 2000` constant that never
+     * read `config.performance.defaultCacheSize`, despite that field being
+     * documented (see `EngineConfig`'s JSDoc example) as exactly this knob.
+     * A host raising `defaultCacheSize` for large documents had zero effect;
+     * every document beyond ~2000 unique expressions per line silently lost
+     * the bytecode-cache benefit on re-evaluation regardless of config.
+     */
+    private cacheBytecode;
+    private builderPool;
+    private builderPoolIndex;
+    private lastTelemetry;
+    constructor(localeCode?: string, diagnosticMode?: boolean, config?: Partial<typeof DEFAULT_CONFIG>, diagnosticPipeline?: DiagnosticPipeline, packages?: IEnginePackage[]);
+    /**
+     * Get the native event stream from the batcher for stream-based consumers.
+     *
+     * Use this instead of `addAsyncListener()` when you need:
+     * - **Backpressure**: the stream buffers up to `highWaterMark` events;
+     *   when full, `enqueue()` blocks until the consumer reads, preventing
+     *   unbounded memory growth.
+     * - **Cancellation**: call `reader.cancel()` or pass an `AbortSignal` to
+     *   `pipeTo()` to stop receiving events.
+     * - **Piping**: use `stream.pipeTo(writable)` or `stream.pipeThrough(transform)`
+     *   to build a reactive pipeline.
+     * - **Teeing**: use `stream.tee()` to serve multiple independent consumers.
+     *
+     * @returns A {@link ReadableStream} that emits {@link AsyncResolutionEvent}
+     *          items as the batcher processes async resolutions.
+     */
+    getEventStream(): ReadableStream<AsyncResolutionEvent>;
+    /**
+     * Get the batcher instance (for test infrastructure).
+     *
+     * Tests use this to access `batcher._testCaptures` for synchronous
+     * event observation without async stream reader timing issues.
+     */
+    getBatcher(): AsyncResolutionBatcher;
+    /**
+     * Register a package with the engine's isolated registries.
+     *
+     * Handles all IEnginePackage fields:
+     * - `lexerVocabulary` → engine's isolated lexer (via this.lexer.registerVocabulary)
+     * - `prefixParselets` → engine's isolated ParseletRegistry
+     * - `infixParselets` → engine's isolated ParseletRegistry
+     * - `variableSources` → this engine's own variable resolver
+     *
+     * Built-in packages (ARITHMETIC, FUNCTION, UOM, etc.) are registered
+     * via this method during construction. External user packages can also
+     * use this method for data-driven registration.
+     *
+     * @param pkg - The package to register.
+     */
+    registerPackage(pkg: IEnginePackage): void;
+    /**
+     * Unregister a package previously registered via {@link registerPackage}.
+     *
+     * Reverses the package's contributions to the SHARED registries, plugin
+     * functions (pluginFunctionRegistry), variable sources
+     * (this engine's variable resolver), async resolvers, and now
+     * token highlight categories (TokenCategoryMap), which registerPackage
+     * wrote into process-wide state. Also reverts
+     * the package's lexer plugin (custom keyword/operator token types
+     * revert to generic IDENT/ERROR, matching ExpressionLexer.unregisterVocabulary()'s
+     * own contract). This engine-instance-local registration is reversed
+     * here too, even though it isn't a "shared" registry, so a package's
+     * lexer and highlighting contributions clean up together rather than
+     * only half-reversing on unregister. Per-engine parselets/phrases are
+     * still left in place: they live in this engine's isolated registries
+     * and are discarded with the engine instance.
+     *
+     * Clears the bytecode cache, removing handlers changes what compiled
+     * bytecode is valid.
+     *
+     * @param packageName - The `name` the package was registered under.
+     * @returns true if the package was found and unregistered.
+     */
+    unregisterPackage(packageName: string): boolean;
+    /**
+     * Get the effective engine configuration currently in use.
+     * Includes all defaults merged with any constructor overrides.
+     * Useful for introspection, lets consumers see what values are actually
+     * in effect after merging with DEFAULT_CONFIG.
+     */
+    getConfig(): EngineConfig;
+    /**
+     * Get the underlying diagnostic pipeline for advanced usage.
+     */
+    getDiagnosticPipeline(): DiagnosticPipeline;
+    /**
+     * Store a result in the line cache (with DAG registration).
+     * Extracted common pattern from 8 call sites.
+     */
+    private storeLineResult;
+    /**
+     * Execute bytecode and handle the result.
+     *
+     * Replaces ALL 5 try/catch blocks that previously caught AsyncSuspenseError.
+     * Now that executeBytecode returns an EvalResult discriminated union,
+     * we simply check result.type instead of catching errors.
+     *
+     * Sets up AbortController → VM for stale-data prevention.
+     * Cleans up the VM stack after execution (success or pending).
+     * Fires async resolution via fire-and-forget for pending results.
+     *
+     * `tracePipeline`/`traceExpression`, when given, are passed straight
+     * through to `executeBytecode()`'s own optional VM-step-tracing
+     * parameters, used ONLY by {@link evaluateExpressionWithDiagnostic}
+     * when `vmTraceEnabled` is on. Omitted by every other caller, with zero
+     * behavior change (identical to today's hardcoded `undefined, undefined`).
+     */
+    private executeAndStore;
+    /**
+     * Execute bytecode and return the raw EvalResult without DAG/LineCache updates.
+     * Used by reEvaluateLine, executeCached, and evaluateIncremental which
+     * manage their own cache state differently.
+     *
+     * @param lineNumber - 1-based line this bytecode belongs to, for
+     * cross-line features (`prev`/`line<N>`/aggregation. See
+     * `makeLineContext()`). Defaults to -1 (the existing "no real
+     * document" sentinel) for any caller that doesn't have a real line
+     * number to pass.
+     */
+    private executeRaw;
+    /**
+     * Fire-and-forget async resolution using async/await.
+     *
+     * On resolution or error:
+     * 1. Checks AbortSignal, if aborted, stale data is discarded.
+     * 2. Stores result/error in AsyncResultCache (per-package scoped).
+     * 3. Defers re-evaluation to AsyncResolutionBatcher which collapses
+     *    multiple resolutions into a single DAG walk + re-execution pass
+     *    and fires typed events to all listeners.
+     */
+    private resolveAsync;
+    /**
+     * Unified parsing method that handles different input types and returns comprehensive results
+     * with precise coordinate mapping for inline solves.
+     */
+    parseDocument(input: string, options?: UnifiedParsingOptions): ParsingResult;
+    /**
+     * Batch-evaluate an array of lines in a single pass.
+     *
+     * Uses scanDocument() to classify and tokenize all lines in a single
+     * character-by-character walk through the re-joined document text.
+     * This eliminates the per-line Lexer.reset() + classifyLine() +
+     * findInlineSolvesInLine() overhead from the old three-pass approach.
+     *
+     * Tokenization results from scanDocument() are passed directly to the
+     * parser via evaluateLineWithPreTokenized(), skipping re-lexing.
+     */
+    /**
+     * Batch-evaluate an array of lines in a single pass.
+     *
+     * Primarily used by tests. For production, prefer parseDocument()
+     * which calls scanDocument() directly on the raw document string,
+     * bypassing the split→join roundtrip that this method performs.
+     */
+    evaluateLines(lines: string[]): ParsedLine[];
+    /**
+     * Process pre-scanned line results into ParsedLine objects.
+     *
+     * Shared by parseDocument() (which scanDocuments the raw input) and
+     * evaluateLines() (which scanDocuments joined line arrays). Handles
+     * inline solve extraction, variable assignment detection, and
+     * expression evaluation for each non-skipped line.
+     */
+    private processScanResults;
+    /**
+     * Evaluate a line using pre-tokenized tokens from scanDocument().
+     *
+     * Skips the lexing step entirely, the tokens are already available
+     * from the document-level scan. Only parsing, compilation, and
+     * execution are performed.
+     *
+     * This is the production fast path for evaluateLines(). Note: this
+     * path intentionally bypasses the diagnostic pipeline. For diagnostic
+     * events, use evaluateExpressionWithDiagnostic() directly.
+     */
+    private evaluateLineWithPreTokenized;
+    /**
+     * Route parse+compile to the active parser (PrecedenceParser or Recursive Descent).
+     *
+     * Sets up the builder on the active parser, loads tokens, and calls
+     * parseExpression(). Abstracts the API difference between the two parsers:
+     * - PrecedenceParser:  parser.setBuilder(builder); parser.parseExpression(0)
+     * - RD:                parser.builder = builder; parser.parseExpression(0)
+     */
+    private parseExpression;
+    /**
+     * Compiles a standalone token list into a fresh, independent
+     * `BytecodeProgram`, used for a `=>`-triggered expression and for a
+     * bare equation's own right-hand side. Reuses {@link parseExpression}
+     * (the SAME "compile a token list into a builder, then check for
+     * leftover trailing tokens" logic every ordinary line already goes
+     * through), just with a throwaway builder instead of the pooled one
+     * (this grammar is rare, a per-call allocation here is a non-issue).
+     */
+    private compileAdHoc;
+    /**
+     * Executes an already-compiled program in symbolic-tolerant mode (an
+     * undefined variable becomes a `Symbolic` placeholder instead of
+     * throwing `UNDEFINED_VARIABLE`. See `vm/VM.ts`'s `executeBytecode()`
+     * doc comment on its own `symbolicTolerant` parameter). Used by both
+     * the "just simplify this" `=>` mode and bare equation evaluation
+     * (a bare assignment's RHS, and an equation's own RHS at solve time)
+     *, every one of these needs forward-tolerant reads of not-yet-defined
+     * names, which ordinary evaluation deliberately never allows.
+     */
+    private executeSymbolicTolerant;
+    /** Compiles and executes `tokens` in symbolic-tolerant mode, the "just simplify this" `=>` fallback when there's no stored equation to solve. */
+    private simplifySymbolically;
+    /**
+     * Parses a bare (colon-less) equation's left-hand side, `factor1 *
+     * factor2 * ... * variable`, into an ordered list of bare names, or
+     * `null` if `tokens` isn't EXACTLY that shape (an alternating
+     * `IDENT/UNIT`, `STAR`, `IDENT/UNIT`, `STAR`, ... sequence with no
+     * other token types). Returning `null` means "don't intercept this
+     * line at all", it falls through to whatever the ordinary expression
+     * grammar already does with a bare `=` in it (today: a clear parse
+     * error), so this pattern-match can only ever ADD a new capability,
+     * never take one away.
+     *
+     * Requiring `IDENT`/`UNIT` at every name position is what keeps this
+     * safe from the reserved-keyword collision risk `VariableParselet.ts`
+     * guards against for the colon-prefixed form: a genuinely reserved
+     * word (`clamp`, `global`, ...) always lexes as ITS OWN token type,
+     * never `IDENT`/`UNIT`, so it can never satisfy this pattern, the
+     * same protection, for free, without a duplicated keyword list.
+     */
+    private parseFactorChain;
+    /**
+     * Solves a stored equation, `variable = inv(factor1*factor2*...) *
+     * rhs`. Every step is symbolic-aware (`vm/MatrixOps.ts`'s
+     * `matrixMultiply()`/`inverse()`), so a factor whose OWN cells are
+     * still-unassigned free variables (`s = [sx,0,0;...]`) solves
+     * correctly, producing a Matrix whose cells are algebraic formulas
+     * rather than plain numbers. Errors (a missing factor, a non-Matrix
+     * factor/RHS, a singular combined matrix) are returned as `Error`-typed
+     * Values, not thrown, matching this engine's established "matrix
+     * errors propagate as values" convention (DIMENSION_MISMATCH,
+     * SINGULAR_MATRIX, ...).
+     */
+    private solveEquation;
+    /**
+     * Detects and handles this session's two new symbolic-algebra grammar
+     * shapes on `normalizedTokens`, returning the computed result directly
+     * (bypassing ordinary bytecode compilation/caching entirely, since
+     * BOTH shapes have effects, a stored equation, a direct variable
+     * assignment, that a cached bytecode program can't represent) or
+     * `null` if neither shape matches (meaning ordinary processing should
+     * proceed exactly as it did before this feature existed):
+     *
+     * 1. `<bareIdent> =>` or `<expr> =>`, trailing `THEREFORE`. A bare
+     *    identifier with a STORED equation solves it (see
+     *    {@link solveEquation}); anything else (including a bare
+     *    identifier with NO stored equation) runs in symbolic-tolerant
+     *    mode and simplifies (see {@link simplifySymbolically}), a
+     *    near-free "just simplify this" mode.
+     * 2. `factor1*factor2*...*variable = rhs`, a bare (colon-less), NOT
+     *    already colon/global-prefixed, top-level `EQUALS` whose LHS
+     *    matches {@link parseFactorChain}'s narrow pattern. A single bare
+     *    name (`s = [sx,0,0;...]`) is an ORDINARY (colon-less) assignment
+     *, its RHS is ALWAYS evaluated symbolic-tolerantly (so a matrix
+     *    literal with still-unassigned entries assigns successfully,
+     *    carrying those free variables as real symbolic cells) and stored
+     *    via `vm.setVar()`. Two or more names (`s*t*v = rhs`) stores a
+     *    genuine equation keyed by the LAST name (`v`), solved later via
+     *    shape 1 above.
+     *
+     * This is a deliberately narrow pattern match, not a general equation
+     * solver. See `OpRegistry.ts`'s `EquationDef` doc comment and this
+     * session's own Phase H.2 scope decision (full symbolic MATRICES, not
+     * a general CAS).
+     */
+    private trySymbolicGrammar;
+    /**
+     * Stores a general scalar equation (`x^2 - 4 = 0`) keyed by its unknown, or
+     * returns `null` to let ordinary processing continue.
+     *
+     * This is the riskiest pattern match in the file, because a bare `=` is
+     * already claimed by three shipped grammars, and swallowing any of them
+     * would break a working feature silently. Each is excluded deliberately:
+     *
+     * - **A user-defined function definition** (`f(x) = 2*x`). Its left side is
+     *   a name followed by `(`, which no equation ever is, so a `LPAREN` in
+     *   second position declines outright. This is the exclusion that matters
+     *   most: `parseFactorChain` already returns `null` for it, so without this
+     *   guard the definition grammar would be intercepted before the parser
+     *   ever saw it.
+     * - **A bare assignment** (`a = [1,2;3,4]`) and **a product-chain matrix
+     *   equation** (`a*x = [60;70]`). Both are handled by `parseFactorChain`
+     *   above and never reach here.
+     * - **A colon-prefixed or global assignment**. Excluded earlier still.
+     *
+     * Two further conditions narrow it to genuine equations. There must be
+     * exactly one top-level `=` (an `==` comparison lexes as `EQUALITY`, a
+     * different token, so it cannot collide), and at least one side must carry
+     * an unknown. Without that last check `2+2 = 4` would become an equation
+     * with no variable and report an identity, where today it is a parse error;
+     * changing an unrelated line's behaviour is not this feature's business.
+     *
+     * @param normalizedTokens - The whole line's normalized tokens.
+     * @param eqIdx - Index of the first `EQUALS` token.
+     * @returns A confirmation value when stored, or `null` to decline.
+     */
+    private tryStoreScalarEquation;
+    /**
+     * The names in an equation that have no value yet, which is what makes them
+     * the thing to solve for.
+     *
+     * A name that already holds a value is not an unknown: in `y = 2` followed
+     * by `x + y = 5`, only `x` is being solved for. A name that is a defined
+     * function is likewise excluded, so a call to one never looks like an
+     * unknown.
+     *
+     * @param lhsTokens - Left-hand side tokens.
+     * @param rhsTokens - Right-hand side tokens.
+     * @returns The distinct unassigned names, in first-seen order.
+     */
+    private equationUnknowns;
+    /**
+     * Solves a stored scalar equation via `symbolic/Solve.ts`.
+     *
+     * Both sides are evaluated symbolic-tolerantly first, so the unknown
+     * survives as a `Symbolic` value rather than throwing, and a side that
+     * reduces to a plain number is lifted into the symbolic domain to match.
+     *
+     * @param equation - The stored equation.
+     * @returns The solution, rendered by the same helper `solve()` uses, so the
+     * two surfaces cannot disagree about how an outcome reads.
+     */
+    private solveScalarEquation;
+    /**
+     * Lex an expression via `resetExpression` (skips `classifyLine`
+     * callers already know this is an expression), filtering out COMMENT
+     * tokens (they have no parselet) and tracking whether any paren was
+     * seen. Shared by every lex-then-{@link prepareExpression} call site:
+     * {@link compileExpression}, {@link tryCompileExpression}, and
+     * {@link evaluateExpressionWithDiagnostic}. `onToken`, when given, is
+     * called once per emitted (already-filtered) token, used ONLY by the
+     * diagnostic path to fire its per-token `TokenEmitted` events; every
+     * other caller omits it.
+     */
+    private lexToTokens;
+    /**
+     * Shared pipeline front-half: safety checks → COMMENT filter →
+     * normalize → complexity → read/write extraction → bytecode cache
+     * lookup or parse+compile.
+     *
+     * Used by {@link evaluateWithTokens} (which continues into preflight +
+     * execution) and {@link compileExpression} (compile-only). Previously
+     * both carried their own copy of this sequence, which had already
+     * drifted. Returns a discriminated union instead of throwing so each
+     * caller decides whether/how to re-throw.
+     *
+     * The `'error'` variant carries the actual `EngineError` each safety
+     * check or `parseExpression()` itself already constructed, not just
+     * its flattened `.message` (the previous shape). A parse failure in
+     * particular can be any of dozens of specific codes (UNDEFINED_VARIABLE,
+     * NO_PREFIX_PARSELET, FUNCTION_ARITY_MISMATCH, ...), each with its own
+     * `expected`/`found`/`suggestion` detail, callers used to discard all
+     * of that and reconstruct a generic EVALUATION_ERROR/PARSE_ERROR wrapper
+     * around just the message, which directly worked against this session's
+     * "errors are verbose and easy to understand" goal. Callers should
+     * generally just `throw prep.error` (see {@link evaluateWithTokens},
+     * {@link compileExpression}) rather than wrapping it again.
+     *
+     * `onFusion`, when given, is passed straight through to the normalizer's
+     * own optional per-fusion callback, used ONLY by
+     * {@link evaluateExpressionWithDiagnostic} to observe individual token
+     * fusions for its `normalizer` diagnostic stage. Omitted by every other
+     * caller, with zero behavior change (identical to not passing a 2nd
+     * argument to `normalizer.normalize()` at all).
+     *
+     * The `'error'` variant's `normalizedTokens` is populated whenever
+     * normalization already ran before the failure (`'complexity'`/`'parse'`
+     * stages), `undefined` when it failed before tokens were even considered
+     * (`'length'` stage), lets {@link evaluateExpressionWithDiagnostic}
+     * reconstruct its own diagnostic-stage payloads (which need the
+     * normalized tokens to recompute a display-only complexity score) without
+     * re-deriving them by hand.
+     *
+     * The `'ready'` (uncached) variant's `parserAlloc` is the
+     * `AllocationTracker.track('parser', ...)` result for JUST the actual
+     * parse+build call (`null` whenever `AllocationTracker.isEnabled()` is
+     * false, or on a cache hit, no parsing happened). This has to be
+     * measured HERE, not reconstructed by a caller after the fact: unlike
+     * every other diagnostic field, a heap-delta measurement only means
+     * anything over the EXACT span it's wrapped around, wrapping the
+     * whole `prepareExpression()` call from the outside (as
+     * {@link evaluateExpressionWithDiagnostic} briefly did) widens that span
+     * to also cover normalize/complexity-check/cache-lookup, which measurably
+     * produced negative-allocation readings (a GC sweep landing inside the
+     * wider window) in `AllocationTracker.spec.ts` well over half the time.
+     */
+    private prepareExpression;
+    /**
+     * Shared async-resolver preflight check, run before VM execution.
+     *
+     * O(1) guard: skips the O(n) resolver scan when the bytecode has no
+     * async opcodes AND no resolvers are registered. Either condition alone
+     * is enough to warrant a preflight scan:
+     *   - program.hasAsync: bytecode contains CALL_PLUGIN (async VM path)
+     *   - resolverRegistry.size > 0: resolvers may intercept any expression
+     * For purely sync expressions (e.g., `2 + 2`) with no resolvers, this is
+     * an O(1) fast-path that bypasses the resolver scan entirely.
+     *
+     * If any registered resolver says "data not ready", registers a DAG
+     * data-source dependency, stores a Pending result, and fires async
+     * resolution (fire-and-forget, resolves later, re-evaluates on
+     * completion), the caller should skip VM execution entirely and return
+     * the pending Value as-is. Otherwise the caller should proceed to
+     * {@link executeAndStore}.
+     *
+     * Used by both {@link evaluateWithTokens} and
+     * {@link evaluateExpressionWithDiagnostic}, previously each carried its
+     * own copy of this exact sequence (differing only in a cosmetic
+     * abortLogger label), which is how the `=>` grammar shipped silently
+     * dead on the diagnostic path earlier this session: a future top-level
+     * grammar addition can no longer be wired into only one of the two.
+     */
+    private preflightAsync;
+    /**
+     * Evaluate an expression using already-lexed tokens.
+     *
+     * The lean, non-diagnostic-instrumented path, used by
+     * {@link evaluateLineWithPreTokenized} (tokens from `scanDocument()`)
+     * and, via {@link compileExpression}/{@link tryCompileExpression},
+     * compile-only callers. NOT used by `evaluateLine()`/
+     * `evaluateExpression()`, those route through
+     * {@link evaluateExpressionWithDiagnostic} instead (evaluateLine ->
+     * evaluateLineDetailed -> evaluateLineWithDebug ->
+     * evaluateExpressionWithDiagnostic), which does its own lexing and its
+     * own diagnostic-instrumented front-half, delegating to the SAME
+     * {@link prepareExpression} this method calls. Delegates the front-half
+     * to {@link prepareExpression}, then runs async preflight (via
+     * {@link preflightAsync}) + VM execution (via {@link executeAndStore}).
+     */
+    private evaluateWithTokens;
+    /**
+     * Evaluate a single expression line with full DAG and LineCache integration.
+     *
+     * @param lineNumber - 1-based line position in the document.
+     * @param lineText - The raw line text.
+     * @returns The evaluated Value, wrapped in a single-element array.
+     * @throws {EngineError} On evaluation failure.
+     */
+    evaluateLine(lineNumber: number, lineText: string): EvalResults;
+    /**
+     * Evaluate a line and return an explicit `{ values }` object.
+     *
+     * @throws {EngineError} On evaluation failure.
+     */
+    evaluateLineDetailed(lineNumber: number, lineText: string): LineEvaluation;
+    /**
+     * Evaluate a line with diagnostic information, supporting both regular expressions and inline solves.
+     *
+     * This is the primary entry point for the playground's debug/DIagnostic mode.
+     * It delegates to {@link evaluateExpressionWithDiagnostic} for all actual evaluation,
+     * but first checks for inline solve syntax (`s`expression``) and wraps the result
+     * with inline solve position metadata when found.
+     *
+     * @param lineNumber - 1-based line number in the document.
+     * @param lineText - Raw line text, which may be a regular expression or an inline solve.
+     * @param inputType - Optional input type hint passed through to the diagnostic pipeline.
+     * @returns An object containing the evaluated `value`, the raw `tokens`, the compiled
+     *          `program`, optional `error` message, optional `debug` report JSON, and optional
+     *          structured `diagnostic` pipeline result with all 15 pipeline stages.
+     */
+    evaluateLineWithDebug(lineNumber: number, lineText: string, inputType?: string): {
+        value: Value;
+        tokens: Token[];
+        program: BytecodeProgram;
+        error?: string;
+        engineError?: EngineError;
+        inlineSolve?: InlineSolvePosition;
+        debug?: DiagnosticReportJSON;
+        diagnostic?: DiagnosticPipelineResult;
+    };
+    /**
+     * Build a single pipeline stage result for the structured diagnostic output.
+     *
+     * Appends a `PipelineStageResult` to the given `stages` array with the provided
+     * metadata. This runs in parallel with the existing event-based diagnostic system
+     * (via `DiagnosticPipeline.fire*` methods). Both paths are enabled by the same
+     * `hasCollectors` guard so there is no performance impact when `diagnosticMode`
+     * is `false`, the stages array stays empty because this method is never called.
+     *
+     * Each stage captures:
+     * - **Identity**: `stage` name (e.g., `"lexer"`), display `label`, `icon`, `colorClass`
+     * - **Position**: `stepNumber` in the pipeline (0-15)
+     * - **Timing**: `elapsedNs` wall-time (overridden by TimelineDiagnosticCollector)
+     * - **State**: `skipped` flag for stages bypassed by cache hits or guard conditions
+     * - **Payload**: `output`, a discriminated union typed per stage
+     *
+     * @param stages - Mutable array being accumulated for the final DiagnosticPipelineResult.
+     * @param stage - Canonical stage identifier (kebab-case, e.g. `"async_preflight"`).
+     * @param label - Human-readable stage name for the dashboard.
+     * @param icon - Single emoji/character icon for visual identification.
+     * @param colorClass - CSS class name for color-coding the stage in the UI.
+     * @param stepNumber - Ordinal position in the 15-stage pipeline.
+     * @param elapsedNs - Wall-clock time in nanoseconds (0 placeholder; timeline overrides).
+     * @param skipped - Whether this stage was bypassed (e.g., cache hit, guard short-circuit).
+     * @param output - Stage-specific data payload typed via the StageOutput discriminated union.
+     */
+    private addDiagnosticStage;
+    /**
+     * Core expression evaluation logic with diagnostic pipeline integration.
+     *
+     * Executes the full 15-stage evaluation pipeline while simultaneously
+     * populating two diagnostic data structures:
+     *
+     * 1. **Event-based**, fires typed events to registered `DiagnosticCollector`
+     *    instances via `DiagnosticPipeline.fire*()` methods. Supports streaming
+     *    diagnostics via `TimelineDiagnosticCollector`.
+     * 2. **Structured stages**, accumulates a `PipelineStageResult[]` array
+     *    with per-stage typed payloads (see `DiagnosticPipelineResult.ts`).
+     *    This is returned as the `diagnostic` field for declarative rendering.
+     *
+     * The 15 stages, in order:
+     * ```
+     *  1  pipeline_start, Pipeline initialization + metadata
+     *  2  safety_length, Expression length validation
+     *  3  lexer, Tokenization via ExpressionLexer
+     *  4  normalizer, Token fusion (phrase, implicit multiply)
+     *  5  safety_complexity, Token-count & nesting-depth check
+     *  6  readwrite, Variable read/write extraction for DAG
+     *  7  cache_check, Bytecode cache hit/miss
+     *  8  parser, AST construction via PrecedenceParser
+     *  9  compiler, Bytecode generation + constant table
+     * 10  async_preflight, Async resolver pre-flight check
+     * 11  vm_execute, Bytecode execution on the VM
+     * 12  dag_registration, DAG node registration for incremental eval
+     * 13  linecache, Result stored in LineCache
+     * 14  result, Final value + formatting
+     * 15  pipeline_end, Completion summary + statistics
+     * ```
+     *
+     * Early-exit paths are taken for safety violations, empty expressions,
+     * parse failures, and async pending results. Each early exit still
+     * fires relevant pipeline events and records partial stages.
+     *
+     * When `AllocationTracker.isEnabled()`, each pipeline stage is wrapped
+     * with `AllocationTracker.track()` to capture wall-time and heap delta.
+     * When disabled (production), `track()` is a zero-overhead passthrough
+     * that returns the result directly.
+     *
+     * The stages above describe OBSERVABLE shape, not a second implementation
+     * of the underlying work: normalize/complexity-check/symbolic-grammar/
+     * readwrite/cache-lookup/parse/compile are delegated to
+     * {@link prepareExpression} (the SAME method the lean
+     * {@link evaluateWithTokens} path calls), async preflight to
+     * {@link preflightAsync}, and VM execution to {@link executeAndStore}
+     * every stage/event below is reconstructed from what those shared
+     * methods return, not fired from inside a second hand-duplicated copy
+     * of their logic. This matters: a new top-level grammar shape wired
+     * into `prepareExpression()` is automatically reachable from BOTH
+     * `evaluateLine()`/`evaluateExpression()` (this method) and the lean
+     * path, previously they were two independent implementations that had
+     * already drifted once (the `=>`/equation-statement grammar shipped
+     * dead on this, the real path, until a dedicated test caught it).
+     *
+     * @param expression - The raw expression string to evaluate.
+     * @param lineNumber - 1-based line number for DAG and LineCache entries.
+     * @param inputType - Input type hint (default `"expression"`), passed to
+     *                    the diagnostic pipeline for metadata.
+     * @returns An object with `value`, `tokens`, `program`, optional `error`,
+     *          optional `debug` report JSON, and optional `diagnostic` containing
+     *          the full structured pipeline stages array when collectors are active.
+     */
+    private evaluateExpressionWithDiagnostic;
+    /**
+     * Build a complete DiagnosticPipelineResult with engine-wide snapshot data.
+     *
+     * Populates dagSnapshot, cacheSnapshot, batcherMetrics, and checkpoints
+     * alongside the per-line pipeline stages, value, tokens, and program.
+     * Previously the playground made separate engine method calls for each.
+     */
+    private buildDiagnosticResult;
+    /**
+     * Re-evaluate a cached line without reparsing.
+     *
+     * Used when a variable referenced by this line has changed. Skips
+     * lexing, parsing, and compilation, performs only a pre-flight async
+     * check and VM execution against the cached bytecode.
+     *
+     * Returns `undefined` if the line is not in cache.
+     *
+     * @param lineNumber - The line to re-evaluate.
+     * @param expression - The original expression string (used for cache lookup).
+     * @returns The updated `Value`, or `undefined` if uncached.
+     */
+    reEvaluateLine(lineNumber: number, expression: string): Value | undefined;
+    getDag(): DependencyGraph;
+    getLineCache(): LineCache;
+    getBytecodeCache(): Map<string, BytecodeProgram>;
+    /**
+     * Get the shared VM instance.
+     * Used by VMCheckpointer to create/restore checkpoints.
+     */
+    getVM(): VM;
+    /**
+     * This engine's registries.
+     *
+     * For introspection: checking what a package registered, or asserting that
+     * unregistering removed it. These used to be module-level singletons a
+     * caller could import directly, which is exactly the coupling
+     * {@link EngineContext} removes, so reaching them now goes through the
+     * engine that owns them.
+     *
+     * @returns The context created for this engine. Mutating what it holds
+     * affects this engine's behaviour, so treat it as read-only unless you are
+     * deliberately registering something.
+     */
+    getContext(): EngineContext;
+    getScopeManager(): ScopeManager;
+    getLexer(): Lexer;
+    /**
+     * Every completion candidate contributed by currently-registered
+     * packages (`IEnginePackage.completionItems`), flattened across all of
+     * them. Used by `LanguageService.getCompletions()`.
+     */
+    getPackageCompletionItems(): CompletionItem[];
+    getParseletRegistry(): {
+        prefix: Array<{
+            tokenType: string;
+            bindingPower: number;
+            category?: string;
+        }>;
+        infix: Array<{
+            tokenType: string;
+            leftBindingPower: number;
+            rightBindingPower: number;
+            category?: string;
+        }>;
+    };
+    /**
+     * Lex + normalize (phrase fusion, implicit multiply, domain token
+     * merging) `text` WITHOUT parsing or executing it, a cheap way for a
+     * host to inspect what token stream a line would actually produce,
+     * without paying for a full parse/compile/VM pass.
+     *
+     * Built for line-classification heuristics like "does this look like a
+     * real expression, or is it prose I shouldn't bother evaluating", a
+     * host that only checks for digits/operators/symbols before deciding
+     * whether to evaluate a line will incorrectly skip genuine all-word
+     * expressions (`weather in Tokyo`, `time in Paris`, `average of X, Y,
+     * Z`), since none of those contain a digit or symbol. Checking whether
+     * `tokenizeForClassification(text)[0]?.type` is anything OTHER than the
+     * generic `IDENT` fallback is a reliable signal that the lexer/normalizer
+     * actually recognized a specific keyword or fused multi-word phrase
+     * i.e., this is real, registered vocabulary, not an arbitrary word that
+     * merely happens to be lexable (every word lexes as IDENT if nothing
+     * more specific claims it, so IDENT alone proves nothing about intent).
+     *
+     * Assumes the caller has already ruled out markdown-structural lines
+     * (headings, code fences, etc.) via `getLexer().classifyLine()`. This
+     * always tokenizes as a plain expression line, mirroring
+     * `Lexer.resetExpression()`'s own "caller already knows this is
+     * evaluable" contract.
+     */
+    tokenizeForClassification(text: string): Token[];
+    getParser(): PrecedenceParser;
+    isDiagnosticMode(): boolean;
+    /**
+     * Set the keystroke-level AbortSignal for the current evaluation cycle.
+     *
+     * Called by the UI layer (via ThreeTierEvaluator) before evaluate() or
+     * evaluateAll(). All per-evaluation AbortControllers created during this
+     * cycle link to this signal so that when the user types a new keystroke,
+     * all in-flight async work is canceled atomically.
+     *
+     * @param signal The keystroke's AbortSignal, or null to clear.
+     */
+    setKeystrokeSignal(signal: AbortSignal | null): void;
+    /**
+     * Get a serializable cache snapshot for diagnostic rendering.
+     *
+     * Returns bytecode cache entries, line cache entries, and async cache
+     * packages, all as plain objects with no internal references. Previously
+     * the playground accessed this via `(engine as any).getCacheSnapshot?.()`.
+     */
+    getCacheSnapshot(): CacheSnapshot;
+    /**
+     * Get serializable batcher metrics for the Workers diagnostic tab.
+     *
+     * Reads the typed read-only accessors on {@link AsyncResolutionBatcher}
+     * (`pendingCount`/`dedupCount`/`workerOffloadCount`/`listenerCount`)
+     * instead of reaching into its private fields via `(this.batcher as any)`.
+     */
+    getBatcherMetrics(): BatcherMetrics;
+    /**
+     * Get a serializable snapshot of VM checkpoints for diagnostics.
+     *
+     * The checkpointer lives on the ThreeTierEvaluator (not the engine),
+     * so this returns an empty array when no checkpointer is available.
+     * Previously accessed via `(vm as any).checkpointer.getAllCheckpoints?.()`.
+     */
+    getCheckpoints(): CheckpointSnapshot[];
+    /**
+     * Get the most recent pipeline telemetry from AllocationTracker.
+     *
+     * Returns null when AllocationTracker.isEnabled() is false (production
+     * zero overhead), or when no expression has been evaluated via
+     * evaluateExpressionWithDiagnostic() since the last clear().
+     *
+     * Use this in test/benchmark suites to inspect per-stage wall-time and
+     * heap allocation data without enabling the full diagnostic pipeline.
+     */
+    getLastTelemetry(): PipelineTelemetry | null;
+    /**
+     * Evaluate a raw expression string without line-number context.
+     * Returns the Value result. Throws on error.
+     */
+    evaluateExpression(expression: string): EvalResults;
+    /**
+     * Compile-only path: lex → parse → bytecode, without execution.
+     *
+     * Used by Tier 3 (background) evaluation to discover reads/writes
+     * for the dependency graph without running display-only expressions.
+     *
+     * Uses the bytecode cache, repeated compilations of the same expression
+     * return the cached program with zero allocation.
+     *
+     * @param expression - The raw expression string to compile.
+     * @returns Object with compiled `program`, lexed `tokens`, and extracted `reads`/`writes`.
+     * @throws ErrorFactory on parse failure or safety check failure.
+     */
+    compileExpression(expression: string): {
+        program: BytecodeProgram;
+        tokens: Token[];
+        reads: string[];
+        writes: string[];
+    };
+    /**
+     * Non-throwing "does this compile" check. Same lex → prepare pipeline as
+     * {@link compileExpression}, but returns a boolean instead of throwing on
+     * failure.
+     *
+     * compileExpression()'s failure path constructs a EngineError via
+     * ErrorFactory, which calls Error.captureStackTrace(), one of V8's more
+     * expensive operations. That's fine for genuine execution/compile errors
+     * (rare, and the caller needs the message), but LanguageService's
+     * syntax-highlighting gate calls compileExpression() purely to ask "does
+     * this parse", on every visible line, every keystroke, and the common
+     * case for a real markdown document is prose lines that DON'T parse, not
+     * the rare case. Benchmarked: constructing-and-throwing that exception on
+     * every non-matching line was responsible for highlighting an
+     * unrecognized-prose line costing roughly an order of magnitude more than
+     * a recognized expression. This skips that construction entirely, still
+     * reuses the bytecode cache and prepareExpression()'s normal work, just
+     * never builds an Error object for the "no" answer.
+     *
+     * Note: this only avoids the outer exception compileExpression() itself
+     * would construct. A genuinely deep parse failure (an unmatched token
+     * mid-expression, not just "stopped early with leftover tokens") still
+     * goes through the parser's own throw/catch inside prepareExpression()
+     * unavoidable without restructuring the parser's failure signaling, which
+     * is out of scope here.
+     */
+    tryCompileExpression(expression: string): boolean;
+    /**
+     * Execute pre-compiled bytecode against the engine's shared VM.
+     * Used by Tier 2 (scroll into view) to re-execute cached bytecode
+     * without re-lexing, re-parsing, or re-compiling.
+     *
+     * Preserves the VM stack, pops any leftover items after execution.
+     * Does NOT update DAG or LineCache (caller is responsible for state
+     * management via DocumentModel).
+     *
+     * @returns The execution result, or undefined if bytecode is empty.
+     * @param lineNumber - 1-based line this bytecode belongs to, for
+     * cross-line features (see `makeLineContext()`). Defaults to -1.
+     */
+    executeCached(program: BytecodeProgram, lineNumber?: number): Value;
+    /**
+     * Fast path: evaluate an expression and return a number directly.
+     *
+     * Skips Value object allocation when only a numeric result is needed.
+     * Returns NaN on error or for bare undefined variable references.
+     *
+     * Performs a pre-check for bare identifiers (single-token variable
+     * references). If the identifier is not a known variable, returns NaN
+     * immediately without attempting evaluation, avoids the ambiguity of
+     * "result === 0" when a variable might legitimately store the value 0.
+     *
+     * @param expression - The raw expression string to evaluate.
+     * @returns The numeric result, or NaN on error/undefined variable.
+     */
+    evaluateNumber(expression: string): number;
+    clear(): void;
+    /**
+     * Incrementally re-evaluate lines affected by a variable change.
+     * Walks the DAG from the changed variable to find exactly which lines
+     * need re-execution, no dirty-set indirection, no sorting guesswork.
+     * Uses Kahn's algorithm for topological ordering: producers always
+     * execute before consumers, regardless of document line order.
+     */
+    evaluateIncremental(variable: string, newValue: number): Map<number, Value>;
+}
+
+/** A single classified span within a line, the entire output contract of the language service. */
+interface SemanticToken {
+    from: number;
+    to: number;
+    category: TokenCategory;
+}
+/** A single completion candidate, the entire output contract of `getCompletions()`. */
+interface CompletionItem {
+    label: string;
+    /** Reuses the highlighting taxonomy, one adapter can serve both features. */
+    category: TokenCategory;
+    /** e.g. a unit's measure ("length"), or the category name for keywords/functions. */
+    detail?: string;
+}
+/** Options for the editor-facing language service: completions and highlighting. */
+interface LanguageServiceOptions {
+    /**
+     * Overrides how the service discovers "variable names known in this
+     * document", used to legitimize a lone bare identifier line (see
+     * `getSemanticTokens`'s single-token gate) and variable-name
+     * completions (`getCompletions`). Defaults to reading
+     * `engine.getDag().getSnapshot()`, which works for any consumer
+     * sharing one `ExpressionEngine` between evaluation and the language
+     * service (the real Obsidian editor).
+     *
+     * Required for consumers whose language service is backed by a
+     * *different*, non-evaluating engine than the one that actually runs
+     * the document (the playground's dedicated lexing-only engine, whose
+     * own DAG is always empty), pass a function reading the real
+     * evaluation engine's DAG snapshot instead.
+     */
+    variableNameSource?: () => Iterable<string>;
+}
+/**
+ * Editor-agnostic "language server" for solve expressions: turns a line of
+ * text into semantic token ranges, using the exact same lexer real
+ * evaluation uses (so it only ever classifies what the engine's grammar
+ * actually recognizes, never a separate/duplicated tokenizer). No
+ * knowledge of CSS, CodeMirror, VS Code, or any other rendering concept
+ * lives here. See `language/adapters/` for that.
+ *
+ * Classification happens at the LEXER stage, before the normalizer runs
+ * (normalization, phrase fusion, implicit multiply, and package-specific
+ * rules, happens later, only on the real evaluation path). A package's
+ * lexer-level custom token types (e.g. a custom keyword) are recognized
+ * here exactly as evaluation would see them. A package's *normalizer*-fused
+ * synthetic tokens (e.g. OSRS's GAME_ITEM, built by fusing several
+ * consecutive IDENT tokens against an item-name trie) are NOT. This
+ * service still shows the pre-fusion IDENT tokens individually for those.
+ * `IEnginePackage.tokenCategories` entries for normalizer-only token types
+ * are still valid, correct registrations (queryable via getTokenCategory)
+ *, they just won't currently be reachable through this lexer-only
+ * classification path. Folding normalization in would require running it
+ * per keystroke on the highlighting path too, which needs its own careful
+ * design (span recomputation for fused multi-token ranges, in particular)
+ * rather than a quick addition here.
+ *
+ * Lexing alone is NOT sufficient to decide "recognized", though: a run of
+ * plain-English words ("My name is ron") lexes into a sequence of
+ * individually-valid IDENT tokens with no grammar tying them together
+ * every word "recognized" at the token level, but the line as a whole is
+ * not something the engine would ever accept as an expression. Surfacing
+ * per-token colors for that case looks like the editor mistook prose for
+ * code. So a line's tokens are only surfaced once the line as a whole
+ * parses successfully (via `ExpressionEngine.compileExpression`, the same
+ * parse pipeline, and the same bytecode cache, real evaluation uses; no
+ * separate/duplicated grammar check). A single bare word ("hello", a valid
+ * variable reference) or a keyword-only line ("pi") still parses and still
+ * highlights, only genuinely ungrammatical text is suppressed, unless it's
+ * a known variable elsewhere in the document (see `variableNameSource`).
+ *
+ * `getCompletions()` is the other half of this "language server": unlike
+ * `getSemanticTokens()`, it's explicitly for *incomplete*, mid-typing text
+ *, it deliberately does NOT gate on parse validity (a half-typed
+ * expression almost never parses), using simple prefix matching instead.
+ *
+ * Must be constructed with an already-configured `ExpressionEngine` (one
+ * with all currently-relevant packages registered) rather than a bare
+ * lexer, reusing an existing engine is both the fast path (no throwaway
+ * lexer construction) and the *correct* one: a highlighting-only lexer
+ * built independently of the evaluation engine would silently fail to
+ * recognize plugin-contributed tokens (e.g. a package's custom keywords)
+ * unless it happened to have the identical packages registered.
+ */
+declare class LanguageService {
+    private engine;
+    private variableNameSource;
+    private cache;
+    private staticCompletionCandidates;
+    private staticCompletionIndex;
+    constructor(engine?: ExpressionEngine | null, options?: LanguageServiceOptions);
+    private defaultVariableNames;
+    /**
+     * Classify every recognized token on one line.
+     *
+     * @param lineText - The raw line text (may be a markdown-structural line
+     *   the engine's classifier skips, that's handled by the underlying
+     *   lexer, which returns no tokens for those).
+     * @param lineNumber - 1-based line number, used purely as a cache key.
+     */
+    getSemanticTokens(lineText: string, lineNumber: number): SemanticToken[];
+    /**
+     * Completion candidates for the identifier prefix immediately before
+     * `cursorOffset` on `lineText`. Deliberately simple prefix matching, not
+     * parser-driven "what's grammatically valid here" prediction, a
+     * half-typed expression almost never parses, so gating on parse
+     * validity (the way `getSemanticTokens` does) would suppress
+     * completions almost always. This is the safest, fastest option that
+     * still delivers real value.
+     *
+     * Candidates come from three sources: keywords (which already include
+     * function names. See `ExpressionLexer.getKeywords()`'s doc comment)
+     * and units, both static per engine configuration and cached lazily;
+     * package-contributed items (`IEnginePackage.completionItems`), same
+     * cache; and variable names, read fresh from `variableNameSource()` on
+     * every call since those change on every edit.
+     */
+    getCompletions(lineText: string, cursorOffset: number): CompletionItem[];
+    /** Lazily builds and caches the keyword/unit/package-item candidate list. See `staticCompletionCandidates`. */
+    private getStaticCompletionCandidates;
+    /**
+     * The static candidates bucketed by lowercased first character, built once
+     * from {@link getStaticCompletionCandidates} and invalidated alongside it.
+     */
+    private getStaticCompletionIndex;
+    private isKnownVariable;
+    /**
+     * Whether the engine's parser actually accepts a piece of text as a
+     * well-formed expression, not merely whether it lexes into individually
+     * recognized token types. See the class doc comment's prose example.
+     * `tryCompileExpression` is compile-only (lex → normalize → parse →
+     * cache bytecode, no VM execution, no network/async side effects) and
+     * reuses the engine's existing bytecode cache, so text that's already
+     * been evaluated (or previously highlight-checked) is a cache hit here
+     * too.
+     *
+     * Deliberately calls the non-throwing `tryCompileExpression` rather than
+     * try/catching `compileExpression`. This runs on every visible line on
+     * every keystroke, and the common case for a real markdown document is
+     * lines that DON'T parse (prose), not lines that do. Throwing there would
+     * mean constructing a EngineError (with V8 stack-trace capture) for the
+     * common case instead of the rare one.
+     */
+    private parsesAsExpression;
+    private putCache;
+    /**
+     * Evict specific lines (e.g. the lines actually touched by a CodeMirror
+     * change set) instead of the whole cache, the surgical counterpart to
+     * {@link invalidateCache}, letting a single-line edit stay cheap even in
+     * a large document: every other cached line is untouched and still hits
+     * on the next call.
+     */
+    invalidateLines(lineNumbers: Iterable<number>): void;
+    /**
+     * Full cache clear. Reserved for cases with no meaningful "which lines
+     * changed" (e.g. the document was swapped wholesale, or a package was
+     * registered/unregistered mid-session, changing what categories exist).
+     * Prefer {@link invalidateLines} for ordinary edits. Also rebuilds the
+     * lazily-cached keyword/unit/package-item completion candidates on next
+     * use, the only thing that can change that list mid-session.
+     */
+    invalidateCache(): void;
+}
+
+/**
+ * Public API for registering plugins with the solve-js engine.
+ *
+ * All registration goes through this interface, parselets, variable
+ * sources, and full packages. The default implementation is
+ * {@link PackageRegistry} (singleton via {@link packageRegistry}).
+ *
+ * @example
+ * ```typescript
+ * import { packageRegistry } from "solve-engine";
+ * packageRegistry.registerPackage(myCustomPackage);
+ * ```
+ */
+interface IPackageRegistry {
+    /** Register a prefix parselet (e.g., `GE`, `NOW`, `floor`). */
+    registerPrefixParselet(tokenType: string, parselet: PrefixParselet): void;
+    /** Register an infix parselet (e.g., `+`, `in`, `to`). */
+    registerInfixParselet(tokenType: string, parselet: InfixParselet): void;
+    /** @deprecated Has no effect. See {@link IEnginePackage.variableSources}. */
+    registerVariableSource(source: IVariableSource): void;
+    /** Register a complete package (parselets + variable sources). */
+    registerPackage(pkg: IEnginePackage): void;
+    /** Convenience reference to the Value class for creating typed values. */
+    Value: typeof Value;
+}
+/**
+ * Package descriptor for registering a complete provider with the engine.
+ *
+ * A package bundles all the pieces needed for a domain-specific provider:
+ * lexer plugins for custom token recognition, parselets for Pratt parsing,
+ * plugin functions dispatched via CALL_PLUGIN bytecode, variable sources,
+ * and optional async resolvers for data that loads asynchronously (e.g.,
+ * exchange rates, game prices).
+ *
+ * @example
+ * ```typescript
+ * const myPackage: IEnginePackage = {
+ *   name: "MyProvider",
+ *   lexerVocabulary: myLexerVocabulary,
+ *   prefixParselets: [{ tokenType: "MY_FUNC", parselet: new MyParselet() }],
+ *   pluginFunctions: [{ index: MY_FN_IDX, handler: myHandler }],
+ *   asyncResolvers: [myAsyncResolver],
+ * };
+ * packageRegistry.registerPackage(myPackage);
+ * ```
+ */
+interface IEnginePackage {
+    /** Human-readable name for debugging and error attribution. */
+    name: string;
+    /**
+     * Semver range of `solve-engine` versions this package is compatible with
+     * (e.g. `"^0.1.0"`, `">=0.1.0 <0.3.0"`), checked against the engine's own
+     * running version ({@link ENGINE_VERSION}, `@solve-js/constants/version`)
+     * via `checkEngineVersionCompatibility()`/`assertEngineVersionCompatible()`
+     * (`@solve-js/api/EngineVersionCompatibility`) at registration time.
+     *
+     * Optional, omitted means "no declared constraint," so every package
+     * that predates this field (all built-ins, `examples/osrs`) keeps
+     * registering exactly as before.
+     *
+     * Unlike every other compatibility signal in this codebase (e.g.
+     * `checkPackageCompatibility()`'s sibling-package collision warnings,
+     * which always log and proceed. See `api/PackageCompatibility.ts`), a
+     * declared `engineVersion` range the running engine does NOT satisfy is
+     * a deliberate, hard REJECTION: `registerPackage()` throws rather than
+     * warning. See `ARCHITECTURE.md` §5.3.
+     */
+    engineVersion?: string;
+    /** Optional lexer vocabulary (keywords/operators/units) for recognizing custom tokens (e.g., `GE`, `£`). */
+    lexerVocabulary?: LexerVocabulary;
+    /** Prefix parselets for this package's custom functions/operators. */
+    prefixParselets?: Array<{
+        tokenType: string;
+        parselet: PrefixParselet;
+    }>;
+    /** Infix parselets for this package's custom binary operators. */
+    infixParselets?: Array<{
+        tokenType: string;
+        parselet: InfixParselet;
+    }>;
+    /**
+     * Functions dispatched via CALL_PLUGIN bytecode (emitted by this package's
+     * parselets with `builder.emitIndex(index)`).
+     *
+     * Each entry's `index` MUST come from {@link allocatePluginFunctionIndex}
+     * (`@solve-js/vm/VMBuiltins`), never hardcode a number. Two packages
+     * independently picking the same index would silently overwrite each
+     * other's handler in the shared registry.
+     *
+     * The handler's optional second parameter, `context`, carries the
+     * current line's {@link LineExecutionContext} (line number, and, only
+     * inside a real document, never `evaluateExpression()`'s single-shot
+     * path, closures for reading another line's cached result). Every
+     * handler that doesn't need cross-line data can ignore it entirely.
+     *
+     * @example
+     * ```ts
+     * const MY_FN_IDX = allocatePluginFunctionIndex();
+     * // In a parselet's parse(): builder.emitOpcode(OpCode.CALL_PLUGIN); builder.emitIndex(MY_FN_IDX); builder.emitIndex(argCount);
+     * pluginFunctions: [{ index: MY_FN_IDX, handler: myHandler }]
+     * ```
+     */
+    pluginFunctions?: Array<{
+        index: number;
+        handler: (args: Value[], context?: LineExecutionContext) => Value | Promise<Value>;
+    }>;
+    /**
+     * Named-variable sources.
+     *
+     * @deprecated Currently has no effect. Sources declared here are registered
+     * into the engine's {@link EngineContext} and unregistered again on package
+     * removal, but no evaluation path ever calls `VariableResolver.resolve()`, so
+     * a variable a source provides is never found. Verified by searching every
+     * use of `IVariableSource` outside its own declaration: they are all
+     * registration bookkeeping.
+     *
+     * Declared here rather than deleted because removing a public field is a
+     * breaking change and the intended behaviour is worth keeping. Documented as
+     * dead so a package author does not spend an afternoon working out why their
+     * variables resolve to nothing. To expose a value today, contribute a plugin
+     * function through {@link IEnginePackage.pluginFunctions}.
+     */
+    variableSources?: IVariableSource[];
+    /**
+     * Async resolvers for this package's domain.
+     * When set, the ExpressionEngine runs preflight() before VM execution
+     * for each resolver. If async data is needed, a Pending result is
+     * returned immediately and the line re-evaluates when the data resolves.
+     *
+     * Each resolver must have a unique `namespace`, the ResolverRegistry
+     * is keyed by namespace. Multiple resolvers let a package handle
+     * distinct async operations (e.g., `fetch`, `wait`, `poll`) in
+     * separate, focused classes rather than one monolithic preflight().
+     */
+    asyncResolvers?: IAsyncResolver[];
+    /**
+     * Multi-word phrases to fuse into single compound tokens.
+     * Each key is a space-separated phrase (e.g., "to the power of"),
+     * each value is the target token type after fusion (e.g., "CARET").
+     *
+     * Registered into the engine's {@link PhraseTrie} for single-pass
+     * O(depth) matching, no separate rule scanning per phrase.
+     *
+     * @example
+     * ```ts
+     * phrases: {
+     *   "to the power of": "CARET",
+     *   "abyssal whip": "ITEM",
+     * }
+     * ```
+     */
+    phrases?: Record<string, string>;
+    /**
+     * Normalizer rules for post-lexer token transformation.
+     * Applied by the TokenNormalizer between lexing and parsing.
+     * For phrase fusion, prefer the declarative {@link phrases} field
+     * which uses the faster PhraseTrie. Use this for non-phrase rules
+     * like implicit operator insertion.
+     */
+    normalizerRules?: NormalizerRule[];
+    /**
+     * Semantic highlight categories for this package's custom token types
+     * (introduced via {@link lexerVocabulary} or {@link normalizerRules}), the
+     * plugin-facing half of solve-js's editor-agnostic language service (see
+     * `language/TokenCategoryMap.ts`). Without an entry here, a package's
+     * custom tokens (e.g. a game-item name fused from several identifiers)
+     * are still lexed and parsed correctly, but render with no highlight
+     * category in any editor integration.
+     *
+     * @example
+     * ```ts
+     * tokenCategories: { MY_KEYWORD: "keyword", MY_ITEM: "my-plugin-item" }
+     * ```
+     */
+    tokenCategories?: Record<string, TokenCategory>;
+    /**
+     * Completion candidates for this package, the plugin-facing half of
+     * solve-js's editor-agnostic completions API
+     * (`LanguageService.getCompletions()`). A package's single-word
+     * keywords (via {@link lexerVocabulary}) already flow into completions
+     * automatically; this field is for candidates that AREN'T lexer
+     * keywords, such as a vocabulary of item/entity names. A plain,
+     * pre-built list, not a callback, completion candidate lists are
+     * meant to be cheap and static within one engine configuration.
+     *
+     * @example
+     * ```ts
+     * completionItems: [{ label: "Abyssal whip", category: "my-plugin-item", detail: "Item" }]
+     * ```
+     */
+    completionItems?: CompletionItem[];
+    /**
+     * Custom `as <name>` converters, the extension point for the
+     * Converters package's general `<expr> as <type>` grammar (e.g.
+     * `50% as decimal`, `255 as hex`). The built-in converter names
+     * (`percent`, `decimal`, `hex`, `fraction`, `multiplier`, `sci`,
+     * `binary`, `octal`, ...) dispatch to dedicated fast opcodes; anything
+     * else, including any name a third-party package registers here
+     * resolves through `OpCode.CALL_AS_CONVERTER` against
+     * `vm/VMBuiltins.ts`'s `asConverterRegistry` at runtime. No lexer
+     * keyword registration is needed for a custom name: the AS parselet
+     * accepts any bare-word token after "as" and reads its raw text.
+     *
+     * Each handler is a pure, synchronous `(value: Value) => Value`, for
+     * async conversions (e.g. a live currency-style lookup), use
+     * {@link asyncResolvers} instead.
+     *
+     * @example
+     * ```ts
+     * asConverters: { roman: (v) => stringValue(toRomanNumeral(v.toNumber())) }
+     * ```
+     */
+    asConverters?: Record<string, (value: Value) => Value>;
+}
+/**
+ * Default implementation of {@link IPackageRegistry}, the plugin registration API.
+ *
+ * All registrations delegate to shared singletons (parselet registry,
+ * variable resolver, lexer). This ensures that packages registered through
+ * any PackageRegistry instance are visible engine-wide.
+ *
+ * @example
+ * ```typescript
+ * import { packageRegistry } from "solve-engine";
+ *
+ * // Register a complete provider package
+ * packageRegistry.registerPackage({
+ *   name: "MyProvider",
+ *   prefixParselets: [{ tokenType: "MY_FUNC", parselet: new MyParselet() }],
+ * });
+ * ```
+ *
+ * @deprecated Register on an engine instead:
+ * `engine.registerPackage(pkg)`.
+ *
+ * This class writes into process-wide singletons, which is incompatible with an
+ * engine owning its own registries. Since the introduction of
+ * {@link EngineContext}, an engine reads plugin functions, opcode handlers and
+ * variable sources from its own context, so a package registered here is not
+ * visible to any engine. Parselets and lexer vocabulary registered here reach
+ * the shared registries, which an engine also does not read: it builds its own
+ * `ParseletRegistry` and its own `Lexer`.
+ *
+ * In other words this path registers into state nothing evaluates against. It
+ * remains exported because removing it is a breaking change, and it is where
+ * the singletons that survive are still written from, but it should not be used
+ * in new code and will be removed before 1.0 proper.
+ */
+declare class PackageRegistry implements IPackageRegistry {
+    Value: typeof Value;
+    registerPrefixParselet(tokenType: string, parselet: PrefixParselet): void;
+    registerInfixParselet(tokenType: string, parselet: InfixParselet): void;
+    registerVariableSource(source: IVariableSource): void;
+    registerPackage(pkg: IEnginePackage): void;
+}
+/**
+ * Singleton PackageRegistry instance, the default plugin registration API.
+ *
+ * All packages should register through this instance. The underlying registries
+ * are shared singletons, so multiple PackageRegistry instances would be redundant.
+ */
+declare const packageRegistry: PackageRegistry;
+
+export { type ApplyChangesResult as A, type BatcherMetrics as B, type CacheSnapshot as C, DocumentModel as D, type EvalResults as E, type IEnginePackage as I, type LineEvaluation as L, PackageRegistry as P, type SemanticToken as S, type ViewportRange as V, ExpressionEngine as a, type IPackageRegistry as b, type LineChange as c, type InlineSolvePosition as d, type AsyncCachePackageInfo as e, type AsyncErrorEvent as f, AsyncResolutionBatcher as g, type AsyncResolutionEvent as h, type BytecodeCacheEntry as i, type CheckpointSnapshot as j, type LineCacheEntryInfo as k, type LineState as l, type LinesUpdatedEvent as m, type CompletionItem as n, LanguageService as o, packageRegistry as p, type LanguageServiceOptions as q };