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

package/dist/ScopeManager-CKfQtl7l.d.cts

@@ -0,0 +1,559 @@
+import { V as Value } from './Value-KtAQNHur.cjs';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.cjs';
+import { E as EngineError } from './EngineError-DvPSnhZi.cjs';
+import { D as DiagnosticPipeline } from './pipeline-DPUQt7yL.cjs';
+import { VariableResolver } from './variables.cjs';
+
+/**
+ * Create a new VM instance with the given opcode registry and configurable limits.
+ *
+ * The VM is a stack machine that executes compiled bytecode. It manages:
+ * - A value stack (bounded by `maxStackDepth`)
+ * - A variable store (Map of name → Value)
+ * - An instruction counter (bounded by `maxInstructions`)
+ * - An AbortSignal for async cancellation
+ *
+ * @param registry - Opcode handler registry for plugin-extensible opcodes
+ * @param maxStackDepth - Maximum stack slots (default 200)
+ * @param maxInstructions - Maximum opcodes per expression (default 50000)
+ * @param maxFunctionRecursionDepth - Maximum nested user-defined-function
+ *   calls (default 50). See the VM interface's `pushCallFrame` doc for why
+ *   this exists as its own dedicated guard, separate from `maxInstructions`.
+ */
+declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, context?: EngineContext): VM;
+/**
+ * Compiled bytecode ready for VM execution.
+ *
+ * Uses packed TypedArrays for cache-friendly memory layout:
+ * - `opcodes`: Uint8Array of OpCode values
+ * - `numbers`: Float64Array of numeric literals (indexed by opcode operands)
+ * - `strings`: String table for identifiers, UoM units, and BigInt literals
+ */
+interface Bytecode {
+    opcodes: Uint8Array;
+    numbers: Float64Array;
+    strings: string[];
+    /** User-defined-function bodies compiled alongside this program. See `parser/BytecodeBuilder.ts`'s `BytecodeProgram.userFunctionBodies`. */
+    userFunctionBodies?: UserFunctionDef[];
+    /** map/reduce anonymous transform bodies. See `parser/BytecodeBuilder.ts`'s `BytecodeProgram.anonymousBodies`. */
+    anonymousBodies?: AnonymousBodyDef[];
+}
+/**
+ * Per-line execution context, threaded optionally through
+ * {@link executeBytecode} down to `CALL_PLUGIN`'s plugin-function handlers
+ * (see `vm/VMBuiltins.ts`'s `pluginFunctionRegistry`).
+ *
+ * Exists so a package can implement cross-line features (`prev`, `line<N>`,
+ * range/above aggregation. See `packages/lines/`) without every other
+ * plugin function having to care: it's optional, and every existing
+ * handler ignores it unchanged. Before this, a plugin function's only
+ * input was its own call-site arguments, no line number, no access to
+ * any other line's cached result. `getLineResult`/`isLineBoundary` are
+ * both `undefined` when there's no real document (e.g.
+ * `ExpressionEngine.evaluateExpression()`'s single-expression path, which
+ * uses `lineIndex = -1` as its existing "no document" sentinel), a
+ * plugin function needing document access must check for that itself
+ * and return a clear error, never silently treat it as line 0.
+ */
+interface LineExecutionContext {
+    /** 1-based current line number, or -1 when there is no real document (see class doc above). */
+    lineIndex: number;
+    /** Look up another line's cached result by 1-based line number. `undefined` = not evaluated yet (or out of range), distinct from a line that evaluated to an actual `undefined`-like Value, which can't happen (every Value type has a concrete representation). */
+    getLineResult?: (lineNumber: number) => Value | undefined;
+    /** Whether line `lineNumber` is a blank line or a `#` heading, the stopping condition for "total above"/"sum above"/"average above" aggregation. */
+    isLineBoundary?: (lineNumber: number) => boolean;
+}
+/**
+ * Discriminated union returned by {@link executeBytecode}.
+ *
+ * Two variants:
+ * - `value`: execution completed synchronously with a concrete Value
+ * - `pending`: an async plugin call was encountered, the orchestrator
+ *   must await the resolver Promise, then re-execute
+ *
+ * Replaces the old throw-AsyncSuspenseError pattern, eliminating the need
+ * for try/catch in the engine.
+ */
+type EvalResult = {
+    type: 'value';
+    value: Value;
+} | {
+    type: 'pending';
+    queryKey: string;
+    resolver: Promise<Value>;
+    packageId: string;
+    signal: AbortSignal;
+}
+/**
+ * NEW third arm, an internal invariant violation (stack underflow via
+ * `safePop()`, an unresolved global variable bypassing preflight, a
+ * safety limit exceeded) surfaced as a controlled, structured
+ * `EngineError` instead of letting a raw exception escape
+ * `executeBytecode()` uncaught. See `executeBytecode()`'s own doc
+ * comment on the try/catch this arm makes possible.
+ */
+ | {
+    type: 'error';
+    error: EngineError;
+};
+/**
+ * Execute bytecode with optional diagnostic pipeline integration.
+ *
+ * Performance notes:
+ * - Uses a `switch(op)` statement for dispatch. V8 compiles dense integer
+ *   switches (OpCode values 0–200) into a jump table with O(1) dispatch.
+ *   All handler code is inlined directly in the switch cases, allowing
+ *   TurboFan to optimize across opcode boundaries.
+ * - ADD/SUB/MUL have an inlined numeric fast path that skips the `binaryOp()`
+ *   function call + closure allocation when both operands are plain numbers
+ *   (>90% of arithmetic ops).
+ * - Tracing uses a boolean guard (`shouldTrace`) that the JIT eliminates
+ *   entirely when diagnostics are disabled. No function call overhead.
+ * - `Value.toNumber()` caches its result, computed once, read thereafter.
+ */
+declare function executeBytecode(bytecode: Bytecode, vm: VM, pipeline?: DiagnosticPipeline | undefined, expression?: string, context?: LineExecutionContext, symbolicTolerant?: boolean): EvalResult;
+
+/**
+ * Per-engine state that used to live in module-level singletons.
+ *
+ * Two {@link ExpressionEngine} instances in one process could not be isolated
+ * from each other, because the registries they depend on were module globals
+ * shared by every instance. Registering a package mutated state that another
+ * engine was already reading. Tests worked only because they cleared those
+ * globals by hand, and per-document engines were safe only because
+ * registration happened to be idempotent.
+ *
+ * An `EngineContext` is created by the `ExpressionEngine` constructor and owned
+ * by that engine. Anything that needs one of these registries receives the
+ * context rather than importing a singleton.
+ *
+ * Runtime imports here are restricted to leaf modules of `vm/`. This file is
+ * imported by `vm/`, which `engine/` imports in turn, so pulling in anything
+ * that reaches back into `engine/` would close a cycle. `OpRegistry` and
+ * `VariableResolver` are safe because they import only types plus the error
+ * factory. Everything else arrives
+ * through `import type`, which is erased before the code runs.
+ */
+
+/**
+ * A function a package contributes to the VM, reachable from bytecode through
+ * `CALL_PLUGIN`.
+ *
+ * Returning a promise puts the line into the pending state rather than
+ * blocking: the engine resolves it and re-executes.
+ */
+type PluginFunctionHandler = (args: Value[], context?: LineExecutionContext) => Value | Promise<Value>;
+/**
+ * The registries one engine instance owns.
+ *
+ * Members are added here as each former singleton is migrated. The migration
+ * order is deliberate and recorded in `docs-internal/plans`: plugin functions,
+ * then the opcode registry, the variable resolver, the lexer, and finally
+ * currency exchange. The lexer comes near the end because package registration
+ * writes vocabularies into it, so moving it early would churn every package.
+ *
+ * Currency exchange is deliberately NOT migrated, which is a departure from
+ * that plan. `CurrencyExchangeService` holds a cache of live market rates with
+ * a fifteen minute freshness window and no per-engine configuration. Sharing is
+ * the correct behaviour there: giving each engine its own would make two
+ * engines in one process fetch the same public endpoint independently, and let
+ * them disagree about the rate for one currency pair at one moment. The
+ * singleton rationale, that one engine's registration should not be visible to
+ * another, does not apply to a cache of state that is global in the real world.
+ *
+ * If a host ever needs per-engine rates, for a what-if scenario against
+ * historical figures, the answer is an optional override on the context that
+ * falls back to the shared cache, not a private copy per engine.
+ */
+interface EngineContext {
+    /**
+     * Package-contributed VM functions, keyed by the index the bytecode
+     * carries.
+     *
+     * Indices come from `allocatePluginFunctionIndex()`. Two packages picking
+     * the same number by hand would silently overwrite one another, which is
+     * why the allocator exists and why nothing should hardcode an index.
+     */
+    readonly pluginFunctions: Record<number, PluginFunctionHandler>;
+    /**
+     * Custom opcode handlers a package registered.
+     *
+     * Largely vestigial: packages reach the VM through `CALL_PLUGIN` and
+     * {@link EngineContext.pluginFunctions} now, and nothing in the built-in
+     * set registers an opcode. It moves here anyway because the VM interface
+     * still requires a registry, and one shared instance would put any future
+     * registration back into every engine at once.
+     */
+    readonly opRegistry: OpRegistry;
+    /**
+     * Named-variable sources a package contributed.
+     *
+     * A package registering a source used to make its variables visible to
+     * every engine in the process, including ones that never registered it.
+     */
+    readonly variableResolver: VariableResolver;
+    /**
+     * Which package registered each plugin function index.
+     *
+     * The VM emits a pending result when a plugin function returns a promise,
+     * and that result carries the owning package so diagnostics and the error
+     * surface can name it. Without this the VM had nothing to report and sent an
+     * empty string, so every async failure looked as though it came from
+     * nowhere.
+     */
+    readonly pluginFunctionOwners: Record<number, string>;
+}
+
+/**
+ * A stored bare (colon-less) equation of the shape `factor1*factor2*...*
+ * variable = rhs` (e.g. `a*x = [60;70]`, or `s*t*v = [vx;vy;1]`)
+ * registered when that line is EXECUTED (mirroring `UserFunctionDef`'s own
+ * execution-time registration, not parse-time), and consulted when
+ * `<variable> =>` is later evaluated. Solving is `variable =
+ * inv(factor1*factor2*...) * rhs` (`vm/VM.ts`'s THEREFORE-handling code,
+ * `vm/MatrixOps.ts`'s `matrixMultiply()`/`inverse()`, both symbolic-aware
+ * so a factor whose OWN cells are still-unassigned free variables, e.g.
+ * `s = [sx,0,0;...]`, solves correctly too).
+ *
+ * `factorNames` are looked up via `vm.getVar()` at solve time (ordinary,
+ * ALREADY-evaluated Matrix values, ordinary ("bare") assignment always
+ * evaluates its RHS eagerly, even when that RHS itself contains
+ * unassigned names, via symbolic-tolerant evaluation, so by solve time
+ * each factor is already a genuine, possibly-partially-symbolic Matrix
+ * Value sitting in the variable store), NOT re-compiled bytecode, since
+ * this pattern only ever allows bare identifiers as factors (see
+ * `ExpressionEngine.ts`'s own equation-detection doc comment for why this
+ * stays a narrow, disclosed pattern rather than a general expression).
+ * `rhsProgram` IS a real compiled program (the right-hand side can be an
+ * arbitrary expression, e.g. `[vx;vy;1]`), evaluated in symbolic-tolerant
+ * mode at solve time.
+ */
+interface EquationDef {
+    variable: string;
+    factorNames: string[];
+    rhsProgram: BytecodeProgram;
+}
+/**
+ * A stored scalar equation, the general `x^2 - 4 = 0` shape, kept separate from
+ * {@link EquationDef} rather than merged into it.
+ *
+ * The two are genuinely different problems solved by different machinery.
+ * {@link EquationDef} is a product chain of matrix factors solved by inverting
+ * their product; this is an arbitrary polynomial in one unknown solved by
+ * `symbolic/Solve.ts`. Merging them into one optional-field type would mean
+ * every consumer branching on which half is populated, and would put the older,
+ * already-shipped matrix path at risk of being changed by accident.
+ *
+ * Both sides are compiled programs rather than pre-evaluated values, because
+ * neither side can be evaluated until solve time: they contain the very unknown
+ * being solved for.
+ */
+interface ScalarEquationDef {
+    /** The unknown this equation is keyed by and will be solved for. */
+    variable: string;
+    /** Compiled left-hand side, evaluated symbolic-tolerantly at solve time. */
+    lhsProgram: BytecodeProgram;
+    /** Compiled right-hand side, likewise. */
+    rhsProgram: BytecodeProgram;
+}
+/**
+ * Handler function for plugin-registered opcodes via CALL_PLUGIN (opcode 50).
+ * No longer dispatched directly from the VM switch, plugins register
+ * functions in pluginFunctionRegistry instead.
+ *
+ * @deprecated Use CALL_PLUGIN + pluginFunctionRegistry for plugin functionality.
+ *   OpRegistry remains for the VM interface contract only.
+ */
+type OpcodeHandler = (vm: VM, opcodes: Uint8Array, ip: number, numbers: Float64Array, strings: string[]) => number;
+/** Registration payload for an opcode handler. Binds an OpCode to its handler function with plugin attribution. */
+interface IOpcodeHandlerRegistration {
+    opcode: number;
+    handler: OpcodeHandler;
+    pluginName: string;
+}
+/**
+ * Legacy opcode registry, retained for the VM interface contract.
+ *
+ * Previously dispatched custom opcodes (>= 200) from the VM switch-default
+ * branch. Now plugins should use CALL_PLUGIN (opcode 50) via
+ * pluginFunctionRegistry instead.
+ */
+declare class OpRegistry {
+    private handlers;
+    private nextOpcode;
+    register(registration: IOpcodeHandlerRegistration): void;
+    /**
+     * Remove a previously registered opcode handler.
+     * Used by package unregistration to reverse shared-registry contributions.
+     */
+    unregister(opcode: number): void;
+    get(opcode: number): OpcodeHandler | undefined;
+    has(opcode: number): boolean;
+    /**
+     * Allocate a unique opcode for a plugin's custom bytecode handler.
+     *
+     * Returns the next available opcode (starting at 201). Each call
+     * returns a distinct value. Plugins should call this once during
+     * registration and store the result.
+     *
+     * @throws If the dynamic opcode pool is exhausted.
+     * @returns A unique opcode number for the calling plugin.
+     */
+    allocateOpcode(): number;
+}
+/**
+ * VM interface consumed by opcode handlers and the bytecode executor.
+ *
+ * Provides stack operations, variable access, instruction counting,
+ * and abort signal management for async cancellation.
+ */
+interface VM {
+    push(value: Value): void;
+    pop(): Value;
+    popNumber(): number;
+    popString(): string;
+    peek(): Value;
+    getStack(): Value[];
+    registry: OpRegistry;
+    /**
+     * Read a variable by name, checks the INNERMOST active user-defined-
+     * function call frame first (see `pushCallFrame`), then falls back to
+     * the flat, session-scoped variable store. This is why a function
+     * parameter needs no dedicated load opcode: an ordinary `LOAD_VAR
+     * "x"` inside a function body resolves to the current call's bound
+     * argument automatically, without the parser needing to know it's
+     * compiling a function body at all.
+     */
+    getVar(key: string): Value | undefined;
+    setVar(key: string, value: Value): void;
+    /**
+     * User-defined-function call frame, a name-keyed `Map` of this call's
+     * bound arguments, PUSHED before `CALL_USER_FUNCTION` executes the
+     * callee's body and POPPED immediately after (even if the body throws),
+     * so nested/recursive calls (`double(double(5))`) each get their own
+     * frame instead of clobbering a shared flat map. See `vm/VM.ts`'s
+     * `CALL_USER_FUNCTION` case. Deliberately NOT the same store as
+     * `setVar`'s flat `:name` variables, a call frame is call-scoped and
+     * stacked (only the INNERMOST frame is ever consulted by `getVar`, see
+     * its own doc comment, no lexical capture of an outer call's
+     * parameters), a variable is session-scoped and flat.
+     *
+     * @throws `FUNCTION_RECURSION_LIMIT_EXCEEDED` if pushing would exceed
+     *   the VM's configured `maxFunctionRecursionDepth`, the backstop for
+     *   `f(x) = f(x)`, which would otherwise recurse via nested
+     *   `executeBytecode()` calls until the native V8 stack overflows
+     *   uncatchably (each reentrant call gets its OWN fresh
+     *   `localInstructionCount`, so `maxInstructions` cannot catch this).
+     */
+    pushCallFrame(frame: Map<string, Value>): void;
+    popCallFrame(): void;
+    /** Register (or redefine, overwrites any previous definition, matching `:name = value`'s own reassignment semantics) a user-defined function. */
+    defineUserFunction(name: string, params: string[], program: BytecodeProgram): void;
+    getUserFunction(name: string): UserFunctionDef | undefined;
+    hasUserFunction(name: string): boolean;
+    /** Register (or redefine) a bare equation (`a*x = rhs`), keyed by its free variable. See {@link EquationDef}. */
+    defineEquation(variable: string, factorNames: string[], rhsProgram: BytecodeProgram): void;
+    getEquation(variable: string): EquationDef | undefined;
+    hasEquation(variable: string): boolean;
+    /** Register (or redefine) a stored scalar equation (`x^2-4 = 0`), keyed by its unknown. See {@link ScalarEquationDef}. */
+    defineScalarEquation(variable: string, lhsProgram: BytecodeProgram, rhsProgram: BytecodeProgram): void;
+    getScalarEquation(variable: string): ScalarEquationDef | undefined;
+    hasScalarEquation(variable: string): boolean;
+    reset(): void;
+    getMaxInstructions(): number;
+    getMaxStackDepth(): number;
+    getInstructionCount(): number;
+    incrementInstructions(n: number): void;
+    /** Active AbortSignal for the current expression evaluation. Checked before cache writes. */
+    activeSignal?: AbortSignal;
+    /** Abort the current evaluation (called when expression changes before resolution). */
+    abortCurrent?: () => void;
+    /**
+     * Registries belonging to the engine that created this VM.
+     *
+     * `CALL_PLUGIN` resolves handlers through here rather than through a
+     * module-level registry, so two engines in one process no longer share the
+     * plugin functions their packages registered. This follows what
+     * `userFunctions` and `equations` already do by being VM-instance scoped.
+     */
+    context: EngineContext;
+}
+/** Shared singleton OpRegistry, used when no custom opcodes are needed. */
+declare const sharedOpRegistry: OpRegistry;
+
+/** Serialized snapshot of the dependency graph for diagnostic rendering. */
+interface DagSnapshot {
+    consumers: Record<string, number[]>;
+    writes: Record<number, string[]>;
+    reads: Record<number, string[]>;
+    dataSourceDeps: Record<number, string[]>;
+    dataSourceConsumers: Record<string, number[]>;
+}
+/**
+ * Dependency graph for variable and data-source tracking across document lines.
+ *
+ * Tracks which lines read/write which variables, and propagates changes through
+ * the graph when a variable is modified. Supports:
+ * - Variable dependency tracking (registerLine, getAffectedLines)
+ * - Data-source dependency tracking (registerLineDataSourceDependency)
+ * - Topological ordering of affected lines (getAffectedLinesInOrder)
+ * - Efficient removal of deleted lines (removeLine)
+ */
+declare class DependencyGraph {
+    private consumers;
+    private dependencies;
+    private writes;
+    private lineReads;
+    private dataSourceDependencies;
+    private dataSourceConsumers;
+    /**
+     * Register a line's variable reads and writes in the dependency graph.
+     *
+     * If re-registering the same line (e.g., after editing), old consumer
+     * references are cleaned up first. Write-variables are removed from
+     * the consumer set so that redefinition breaks the old dependency chain.
+     *
+     * @param lineNumber - 1-based line number in the document
+     * @param reads - Variable names this line reads
+     * @param writes - Variable names this line writes (assigns to)
+     */
+    registerLine(lineNumber: number, reads: string[], writes: string[]): void;
+    /**
+     * Register a line's dependency on an external data source (e.g., currency rate, OSRS GE price).
+     *
+     * When the data source updates, {@link getAffectedLinesByDataSource} returns all lines
+     * that depend on this data, enabling targeted re-evaluation.
+     *
+     * @param lineNumber - 1-based line number in the document
+     * @param dataSourceId - Unique identifier for the data source (e.g., "currency", "osrs-ge")
+     * @param queryKey - Query key array identifying the specific data (e.g., ["USD", "EUR"])
+     */
+    registerLineDataSourceDependency(lineNumber: number, dataSourceId: string, queryKey: string[]): void;
+    /**
+     * Find all lines affected by a changed variable via BFS through the consumer graph.
+     *
+     * When a variable is modified (e.g., `:x = 5` changes to `:x = 10`), this returns
+     * all lines that transitively depend on it, lines that read `x`, lines that read
+     * variables written by those lines, and so on.
+     *
+     * @param changedVariable - The variable name that changed
+     * @returns Set of line numbers that need re-evaluation
+     */
+    getAffectedLines(changedVariable: string): Set<number>;
+    /**
+     * Phase 1.4 DAG-walk optimization: return affected lines in dependency-safe
+     * topological order. Uses Kahn's algorithm (BFS-based) to ensure every line
+     * is evaluated AFTER all lines it depends on have been processed.
+     *
+     * This is more correct than ascending line-number sort, which fails when
+     * variable definitions and their consumers are not in document order.
+     *
+     * @returns Line numbers in topological order (producers before consumers).
+     */
+    getAffectedLinesInOrder(startVariable: string): number[];
+    /**
+     * Find all lines affected by a data source update.
+     *
+     * When an async data source resolves (e.g., currency rate fetch completes),
+     * this returns all lines that depend on that specific data query.
+     *
+     * @param dataSourceId - The data source identifier
+     * @param queryKey - The query key that was updated
+     * @returns Set of line numbers that need re-evaluation
+     */
+    getAffectedLinesByDataSource(dataSourceId: string, queryKey: string[]): Set<number>;
+    /**
+     * Remove a line from the dependency graph (e.g., when a line is deleted from the document).
+     *
+     * Cleans up all consumer references, write registrations, and data source dependencies
+     * for the removed line. O(k) where k is the number of variables the line reads.
+     *
+     * @param lineNumber - The line number being removed
+     */
+    removeLine(lineNumber: number): void;
+    /**
+     * Get all line numbers that consume (read) a given variable.
+     *
+     * @param variable - The variable name
+     * @returns Set of line numbers that read this variable, or empty set if none
+     */
+    getConsumers(variable: string): Set<number>;
+    /**
+     * Get all variables that a line depends on (reads).
+     *
+     * @param lineNumber - The line number to query
+     * @returns Set of variable names this line reads, or empty set if none
+     */
+    getDependencies(lineNumber: number): Set<string>;
+    /**
+     * Get all variables that a line writes (assigns to).
+     *
+     * @param lineNumber - The line number to query
+     * @returns Set of variable names this line writes, or empty set if none
+     */
+    getWrites(lineNumber: number): Set<string>;
+    /**
+     * Get a serializable snapshot of the entire dependency graph for diagnostics.
+     *
+     * Returns plain objects (not Maps/Sets) so consumers don't need to reach
+     * into private fields. Used by playground diagnostic tabs for DAG visualization.
+     */
+    getSnapshot(): DagSnapshot;
+    /** Clear all dependency graph state. Called on document switch or engine reset. */
+    clear(): void;
+}
+
+/**
+ * Record of a compiled expression in the scope.
+ * Tracks the expression text, compiled bytecode, last evaluation result,
+ * and the variable reads/writes for dependency tracking.
+ */
+interface ExpressionRecord {
+    lineNumber: number;
+    expression: string;
+    bytecode: {
+        opcodes: Uint8Array;
+        numbers: Float64Array;
+        strings: string[];
+    };
+    lastResult: Value;
+    readVariables: string[];
+    writeVariable: string | null;
+}
+/**
+ * Scoped variable manager for expression evaluation.
+ *
+ * Tracks variable definitions across line numbers with write-on-read semantics.
+ * When a value is read, the most recent definition at or before the reading line
+ * is returned. Invalidation trims downstream definitions when a variable is redefined.
+ */
+declare class ScopeManager {
+    private definitions;
+    /**
+     * Record a variable definition at `lineNumber`. A variable may have
+     * multiple definitions across different lines (e.g. redefined further
+     * down a document), each call adds one, keeping the internal stack
+     * sorted by line so {@link read} can binary-scan for "most recent
+     * definition at or before" a given line.
+     */
+    write(variable: string, lineNumber: number, expr: ExpressionRecord): void;
+    /**
+     * Look up a variable's value as seen from `readLine`: returns the result
+     * of the closest definition at or before `readLine`, not simply the most
+     * recently-written one, so a read on line 5 of a variable redefined on
+     * lines 2 and 10 sees line 2's value, not line 10's. Returns `undefined`
+     * if the variable has no definition at or before `readLine`.
+     */
+    read(variable: string, readLine: number): Value | undefined;
+    /**
+     * Drop every definition of `variable` that comes strictly after
+     * `definitionLine`. Call this when a line is re-evaluated with a new
+     * definition, so stale later-line definitions from a previous edit don't
+     * linger and get returned by {@link read}.
+     */
+    invalidateDownstream(variable: string, definitionLine: number): void;
+    /** Remove every tracked variable definition, used when an engine/document is reset. */
+    clear(): void;
+}
+
+export { type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, type LineExecutionContext as L, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, type DagSnapshot as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };