solve-engine 2.38.13 → 2.38.15

package/dist/{PackageCompatibility-Cu_bHpwY.d.cts → PackageCompatibility-C-3vPMKp.d.cts}

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

package/dist/{PackageCompatibility-BILTZSHP.d.ts → PackageCompatibility-zdsKvwQI.d.ts}

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

package/dist/{PackageRegistry-DMKDsYiA.d.ts → PackageRegistry-CStmqgw_.d.ts}

@@ -2,7 +2,7 @@ import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from '
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-DPn5dfCH.js';
 import { IAsyncResolver } from './resolvers.js';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-DAzPp-j1.js';
-import { D as DependencyGraph, V as VM, f as DagSnapshot, g as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-Dd0KZR4G.js';
+import { b as VMCheckpointer, D as DependencyGraph, V as VM, h as DagSnapshot, i as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-h09nijID.js';
 import { V as Value, b as ValueType, D as DatetimeGrain } from './Value-B55Hvn3e.js';
 import { a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.js';
 import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.js';
@@ -842,6 +842,23 @@ declare class AsyncResolutionBatcher {
      * not register async resolvers at all.
      */
     onLineResult: ((lineNumber: number, value: Value) => void) | null;
+    /**
+     * The checkpoint chain to rebuild variable state from, when there is one.
+     *
+     * A re-run reads whatever the VM currently holds, which after a full pass is
+     * the state at the END of the document. That is the right answer only for a
+     * name written once. `:x = <fetched>` above `:x = 99` left the fetched value
+     * standing at every line below the redefinition, because the line that
+     * redefines it was not itself affected and so was not re-run: a line reading
+     * `x` below it answered with the value from the top of the document.
+     *
+     * With a chain, the batch is run as a sweep through the document instead:
+     * restore to the line before the first affected one, then walk forward,
+     * executing the affected lines and applying the recorded bindings of every
+     * writing line passed on the way. Null leaves the previous behaviour exactly
+     * as it was, which is what a host driving the batcher on its own gets.
+     */
+    checkpointer: VMCheckpointer | null;
     /**
      * Whether {@link warnIfUnwired} has already fired.
      *
@@ -990,6 +1007,24 @@ declare class AsyncResolutionBatcher {
      * 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.
      */
+    /**
+     * Begin a sweep: put the VM into the state the document has just before the
+     * earliest line about to be re-run.
+     *
+     * @param ordered - The lines about to run, in the order they will run.
+     * @returns The sweep's position cursor, or null when there is nothing to do.
+     */
+    private prepareSweep;
+    /**
+     * Advance the sweep to `lineNumber`, applying every checkpoint passed.
+     *
+     * A line between two affected ones is not re-run, but if it defines
+     * something it still governs what the lines below it read, so its recorded
+     * bindings are put back as the sweep goes by. A line the sweep has already
+     * passed is left alone: the batch runs producers before consumers, and going
+     * backwards would undo a value one of them has just written.
+     */
+    private sweepTo;
     private reExecuteMainThread;
     /**
      * Notify all consumers of an async resolution event.

package/dist/{PackageRegistry-wZgm2zzk.d.cts → PackageRegistry-DiHxyxrn.d.cts}

@@ -2,7 +2,7 @@ import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from '
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-DaWkCu84.cjs';
 import { IAsyncResolver } from './resolvers.cjs';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-D382VSYh.cjs';
-import { D as DependencyGraph, V as VM, f as DagSnapshot, g as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-D3rXBm2k.cjs';
+import { b as VMCheckpointer, D as DependencyGraph, V as VM, h as DagSnapshot, i as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-BwqFO2TY.cjs';
 import { V as Value, b as ValueType, D as DatetimeGrain } from './Value-B55Hvn3e.cjs';
 import { a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.cjs';
 import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.cjs';
@@ -842,6 +842,23 @@ declare class AsyncResolutionBatcher {
      * not register async resolvers at all.
      */
     onLineResult: ((lineNumber: number, value: Value) => void) | null;
+    /**
+     * The checkpoint chain to rebuild variable state from, when there is one.
+     *
+     * A re-run reads whatever the VM currently holds, which after a full pass is
+     * the state at the END of the document. That is the right answer only for a
+     * name written once. `:x = <fetched>` above `:x = 99` left the fetched value
+     * standing at every line below the redefinition, because the line that
+     * redefines it was not itself affected and so was not re-run: a line reading
+     * `x` below it answered with the value from the top of the document.
+     *
+     * With a chain, the batch is run as a sweep through the document instead:
+     * restore to the line before the first affected one, then walk forward,
+     * executing the affected lines and applying the recorded bindings of every
+     * writing line passed on the way. Null leaves the previous behaviour exactly
+     * as it was, which is what a host driving the batcher on its own gets.
+     */
+    checkpointer: VMCheckpointer | null;
     /**
      * Whether {@link warnIfUnwired} has already fired.
      *
@@ -990,6 +1007,24 @@ declare class AsyncResolutionBatcher {
      * 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.
      */
+    /**
+     * Begin a sweep: put the VM into the state the document has just before the
+     * earliest line about to be re-run.
+     *
+     * @param ordered - The lines about to run, in the order they will run.
+     * @returns The sweep's position cursor, or null when there is nothing to do.
+     */
+    private prepareSweep;
+    /**
+     * Advance the sweep to `lineNumber`, applying every checkpoint passed.
+     *
+     * A line between two affected ones is not re-run, but if it defines
+     * something it still governs what the lines below it read, so its recorded
+     * bindings are put back as the sweep goes by. A line the sweep has already
+     * passed is left alone: the batch runs producers before consumers, and going
+     * backwards would undo a value one of them has just written.
+     */
+    private sweepTo;
     private reExecuteMainThread;
     /**
      * Notify all consumers of an async resolution event.

package/dist/{VMBuiltins-D3rXBm2k.d.cts → VMBuiltins-BwqFO2TY.d.cts}

@@ -892,6 +892,220 @@ declare class ScopeManager {
     clear(): void;
 }
 
+/**
+ * A point-in-time snapshot of VM variable state.
+ *
+ * Each checkpoint holds only the variables that CHANGED at its line, and
+ * reaches the rest through its `parent` link. A lookup walks that chain until
+ * it finds the name; a restore walks it from the root applying each link's own
+ * bindings in turn, so a later line's value naturally overwrites an earlier
+ * one's.
+ *
+ * ```text
+ * Checkpoint 0 (root):  {}                      // empty scope
+ * Checkpoint 1 (:x=5):  { x: 5 }    parent → 0
+ * Checkpoint 2 (:y=8):  { y: 8 }    parent → 1
+ * Checkpoint 3 (:x=3):  { x: 3 }    parent → 2   // shadows x=5
+ * ```
+ *
+ * To look up `x` at checkpoint 3: find own `x=3` → done.
+ * To look up `y` at checkpoint 3: not own → walk parent to checkpoint 2 → `y=8`.
+ * To look up `z` at checkpoint 3: not found anywhere → undefined.
+ *
+ * **Memory:** O(number of variable definitions) heap, independent of
+ * document length. Typical Obsidian documents have < 100 variable defs,
+ * so total checkpoint heap is < 10 KB.
+ */
+interface VMCheckpoint {
+    /** 1-based line number where this checkpoint was created. */
+    lineNumber: number;
+    /** Persistent line ID from DocumentModel. */
+    lineId: number;
+    /**
+     * Variable name → Value at this checkpoint.
+     * Only the variables set or updated at this line; the rest are reached
+     * through {@link VMCheckpoint.parent}.
+     */
+    variables: Record<string, Value>;
+    /**
+     * User-defined-function name → definition at this checkpoint. SEPARATE
+     * from `variables` above (not prototypally chained the same way
+     * `restoreTo()` replays every checkpoint in the chain in order, so a
+     * later redefinition of the same function name naturally overwrites an
+     * earlier one during replay, without needing its own prototype walk).
+     *
+     * Without this field, a function definition's checkpoint entry would be
+     * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every
+     * written name, which returns `undefined` for a function name (function
+     * defs live in `vm.userFunctions`, not the flat variable store), and a
+     * `val !== undefined` guard silently skipped it. A scroll-triggered
+     * `restoreTo()` would then reset the VM and replay only `variables`,
+     * making a function defined above the new viewport vanish (calling it
+     * would throw `UNDEFINED_FUNCTION`) even though the document still
+     * shows its definition line as clean/cached.
+     */
+    functions: Record<string, UserFunctionDef>;
+    /** Parent checkpoint (closer to document start), or null for root. */
+    parent: VMCheckpoint | null;
+}
+/**
+ * Manages VM state checkpoints for the three-tier evaluation strategy.
+ *
+ * **Checkpoint creation:** After a variable-definition line executes
+ * (Tier 1 or Tier 3), `snapshot()` records the current values of the
+ * written variables. The checkpoint is linked via prototypal inheritance
+ * to the previous checkpoint, so only changed variables consume memory.
+ *
+ * **Checkpoint restoration:** Before evaluating a viewport whose start line
+ * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all
+ * variable definitions up to and including that line. This avoids
+ * re-evaluating the entire document from line 1 on every scroll.
+ *
+ * **Thread safety:** Checkpoints are created synchronously on the main
+ * thread during evaluation. They are immutable after creation (Value is
+ * an immutable type), so no synchronization is needed.
+ *
+ * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`
+ * to find the checkpoint just before the new viewport start, then call
+ * `restoreTo()` to set up the VM before evaluating only the visible lines.
+ * This is the key to O(visible lines) scrolling instead of O(document).
+ */
+declare class VMCheckpointer {
+    /** Ordered array of checkpoints (ascending lineNumber). */
+    private checkpoints;
+    /** The VM instance whose variables are snapshotted/restored. */
+    private vm;
+    constructor(vm: VM);
+    /**
+     * Create a checkpoint at the current line, recording the VM values of
+     * the specified variables.
+     *
+     * Records only what this line wrote; the rest is reached through the
+     * parent link rather than copied.
+     *
+     * A line that is snapshotted again drops every checkpoint at or after it
+     * first, so the list stays in document order and the new checkpoint
+     * inherits from the line before it rather than from one after it. See the
+     * body for what went wrong without that.
+     *
+     * @param lineNumber 1-based line position.
+     * @param lineId Persistent line ID from DocumentModel.
+     * @param variableNames Names of variables that were written at this line.
+     * @returns The new checkpoint, or null if no variable names provided.
+     */
+    snapshot(lineNumber: number, lineId: number, variableNames: string[]): VMCheckpoint | null;
+    /**
+     * Restore the VM to the state at or just after the given line number.
+     *
+     * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,
+     * then replays all variable definitions from root → that checkpoint
+     * into the VM via `setVar()`. The VM's stack is also reset.
+     *
+     * If no checkpoint exists at or before the target line, the VM is
+     * fully reset (empty scope, empty stack).
+     *
+     * **Performance:** O(total variable definitions before the line), since
+     * each checkpoint in the chain contributes only the names its own line
+     * wrote.
+     *
+     * @param lineNumber Target 1-based line number. The VM will have the
+     * state that existed AFTER evaluating lines up to `lineNumber`.
+     */
+    restoreTo(lineNumber: number): void;
+    /** The index of the checkpoint recorded exactly at `lineNumber`, or -1. */
+    private indexOfCheckpointAt;
+    /** Where a checkpoint for `lineNumber` belongs, keeping the list in order. */
+    private insertionIndexFor;
+    /**
+     * The index of the last checkpoint at or before `lineNumber`, or -1.
+     *
+     * A binary search rather than a scan. The array is in document order, and
+     * this is asked once per scroll and once per async batch, on a document
+     * that can hold a checkpoint per definition.
+     */
+    private nearestCheckpointIndex;
+    /**
+     * Record what `lineNumber` has just written, without disturbing the chain
+     * after it.
+     *
+     * {@link snapshot} drops every checkpoint at or after the line, which is
+     * right for a pass running forward in document order: it re-takes them as it
+     * goes. A caller re-running a few lines out of a document does not, and
+     * dropping the entries for lines it will never visit would lose the very
+     * bindings it is sweeping through them to collect. So this overwrites in
+     * place instead.
+     *
+     * Safe against the prototype chain, because it replaces only the
+     * checkpoint's OWN bindings: a later checkpoint that also writes the name
+     * holds its own copy and goes on shadowing this one.
+     *
+     * @param lineNumber 1-based line whose recorded bindings are refreshed.
+     * @param variableNames The names it wrote.
+     * @returns Whether a checkpoint existed at that line to update.
+     */
+    updateCheckpointAt(lineNumber: number, variableNames: string[]): boolean;
+    /**
+     * Apply the bindings recorded AT `lineNumber`, leaving the rest of the VM
+     * alone.
+     *
+     * {@link restoreTo} rebuilds the whole prefix, which costs the chain every
+     * time it is called. A caller moving forward through the document already
+     * holds the prefix up to the line before, and needs only what this line
+     * added: restoring once and then applying each line in turn as it is passed
+     * costs the chain once rather than once per line.
+     *
+     * @param lineNumber 1-based line whose own bindings are applied.
+     * @returns Whether a checkpoint existed at that line.
+     */
+    applyCheckpointAt(lineNumber: number): boolean;
+    /**
+     * Find the nearest checkpoint at or before the given line number.
+     *
+     * Uses linear scan (checkpoints are sorted by lineNumber and the list
+     * is short, typically < 20 for Obsidian documents). Can be upgraded
+     * to binary search if needed for documents with 1000+ variable defs.
+     *
+     * @returns The nearest checkpoint, or null if none exists before the line.
+     */
+    getNearestCheckpoint(lineNumber: number): VMCheckpoint | null;
+    /**
+     * Get a specific checkpoint by its line number.
+     * @returns The checkpoint, or undefined if not found.
+     */
+    getCheckpointAt(lineNumber: number): VMCheckpoint | undefined;
+    /**
+     * Get the entire checkpoint chain from root to the last checkpoint.
+     * Useful for debugging and serialization.
+     */
+    getAllCheckpoints(): readonly VMCheckpoint[];
+    /**
+     * Look up a variable's value through the checkpoint chain.
+     *
+     * Walks the prototype chain starting from the most recent checkpoint,
+     * looking for the variable name as an own property. This is O(depth)
+     * where depth is the number of checkpoints since the variable was
+     * last set.
+     *
+     * **Note:** This queries the checkpointer's snapshot, not the VM.
+     * The VM may have been modified since the last snapshot (e.g., by
+     * Tier 2 execution of non-variable-def lines that don't create checkpoints).
+     *
+     * @returns The Value, or undefined if the variable was never set.
+     */
+    lookupVariable(name: string): Value | undefined;
+    /**
+     * Clear all checkpoints. The underlying VM is NOT reset, call
+     * `vm.reset()` separately if needed.
+     */
+    clear(): void;
+    /** Number of checkpoints stored. */
+    get count(): number;
+    /** Returns true if no checkpoints have been created. */
+    get isEmpty(): boolean;
+    /** The associated VM instance. */
+    get vmInstance(): VM;
+}
+
 /**
  * Registry of built-in mathematical functions.
  * Indexed by the number pushed as an operand of OpCode.CALL_BUILTIN.
@@ -951,4 +1165,4 @@ declare function pluginFunctionIndexFor(qualifiedName: string): number;
  */
 type AsConverter = (value: Value, context?: LineExecutionContext) => Value;
 
-export { type AsConverter as A, 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, allocatePluginFunctionIndex as a, builtinFunctions as b, createVM as c, pluginFunctionRegistry as d, executeBytecode as e, type DagSnapshot as f, type EngineContext as g, pluginFunctionIndexFor as p, sharedOpRegistry as s };
+export { type AsConverter as A, 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 VMCheckpoint as a, VMCheckpointer as b, allocatePluginFunctionIndex as c, builtinFunctions as d, createVM as e, executeBytecode as f, pluginFunctionRegistry as g, type DagSnapshot as h, type EngineContext as i, pluginFunctionIndexFor as p, sharedOpRegistry as s };

package/dist/{VMBuiltins-Dd0KZR4G.d.ts → VMBuiltins-h09nijID.d.ts}

@@ -892,6 +892,220 @@ declare class ScopeManager {
     clear(): void;
 }
 
+/**
+ * A point-in-time snapshot of VM variable state.
+ *
+ * Each checkpoint holds only the variables that CHANGED at its line, and
+ * reaches the rest through its `parent` link. A lookup walks that chain until
+ * it finds the name; a restore walks it from the root applying each link's own
+ * bindings in turn, so a later line's value naturally overwrites an earlier
+ * one's.
+ *
+ * ```text
+ * Checkpoint 0 (root):  {}                      // empty scope
+ * Checkpoint 1 (:x=5):  { x: 5 }    parent → 0
+ * Checkpoint 2 (:y=8):  { y: 8 }    parent → 1
+ * Checkpoint 3 (:x=3):  { x: 3 }    parent → 2   // shadows x=5
+ * ```
+ *
+ * To look up `x` at checkpoint 3: find own `x=3` → done.
+ * To look up `y` at checkpoint 3: not own → walk parent to checkpoint 2 → `y=8`.
+ * To look up `z` at checkpoint 3: not found anywhere → undefined.
+ *
+ * **Memory:** O(number of variable definitions) heap, independent of
+ * document length. Typical Obsidian documents have < 100 variable defs,
+ * so total checkpoint heap is < 10 KB.
+ */
+interface VMCheckpoint {
+    /** 1-based line number where this checkpoint was created. */
+    lineNumber: number;
+    /** Persistent line ID from DocumentModel. */
+    lineId: number;
+    /**
+     * Variable name → Value at this checkpoint.
+     * Only the variables set or updated at this line; the rest are reached
+     * through {@link VMCheckpoint.parent}.
+     */
+    variables: Record<string, Value>;
+    /**
+     * User-defined-function name → definition at this checkpoint. SEPARATE
+     * from `variables` above (not prototypally chained the same way
+     * `restoreTo()` replays every checkpoint in the chain in order, so a
+     * later redefinition of the same function name naturally overwrites an
+     * earlier one during replay, without needing its own prototype walk).
+     *
+     * Without this field, a function definition's checkpoint entry would be
+     * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every
+     * written name, which returns `undefined` for a function name (function
+     * defs live in `vm.userFunctions`, not the flat variable store), and a
+     * `val !== undefined` guard silently skipped it. A scroll-triggered
+     * `restoreTo()` would then reset the VM and replay only `variables`,
+     * making a function defined above the new viewport vanish (calling it
+     * would throw `UNDEFINED_FUNCTION`) even though the document still
+     * shows its definition line as clean/cached.
+     */
+    functions: Record<string, UserFunctionDef>;
+    /** Parent checkpoint (closer to document start), or null for root. */
+    parent: VMCheckpoint | null;
+}
+/**
+ * Manages VM state checkpoints for the three-tier evaluation strategy.
+ *
+ * **Checkpoint creation:** After a variable-definition line executes
+ * (Tier 1 or Tier 3), `snapshot()` records the current values of the
+ * written variables. The checkpoint is linked via prototypal inheritance
+ * to the previous checkpoint, so only changed variables consume memory.
+ *
+ * **Checkpoint restoration:** Before evaluating a viewport whose start line
+ * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all
+ * variable definitions up to and including that line. This avoids
+ * re-evaluating the entire document from line 1 on every scroll.
+ *
+ * **Thread safety:** Checkpoints are created synchronously on the main
+ * thread during evaluation. They are immutable after creation (Value is
+ * an immutable type), so no synchronization is needed.
+ *
+ * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`
+ * to find the checkpoint just before the new viewport start, then call
+ * `restoreTo()` to set up the VM before evaluating only the visible lines.
+ * This is the key to O(visible lines) scrolling instead of O(document).
+ */
+declare class VMCheckpointer {
+    /** Ordered array of checkpoints (ascending lineNumber). */
+    private checkpoints;
+    /** The VM instance whose variables are snapshotted/restored. */
+    private vm;
+    constructor(vm: VM);
+    /**
+     * Create a checkpoint at the current line, recording the VM values of
+     * the specified variables.
+     *
+     * Records only what this line wrote; the rest is reached through the
+     * parent link rather than copied.
+     *
+     * A line that is snapshotted again drops every checkpoint at or after it
+     * first, so the list stays in document order and the new checkpoint
+     * inherits from the line before it rather than from one after it. See the
+     * body for what went wrong without that.
+     *
+     * @param lineNumber 1-based line position.
+     * @param lineId Persistent line ID from DocumentModel.
+     * @param variableNames Names of variables that were written at this line.
+     * @returns The new checkpoint, or null if no variable names provided.
+     */
+    snapshot(lineNumber: number, lineId: number, variableNames: string[]): VMCheckpoint | null;
+    /**
+     * Restore the VM to the state at or just after the given line number.
+     *
+     * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,
+     * then replays all variable definitions from root → that checkpoint
+     * into the VM via `setVar()`. The VM's stack is also reset.
+     *
+     * If no checkpoint exists at or before the target line, the VM is
+     * fully reset (empty scope, empty stack).
+     *
+     * **Performance:** O(total variable definitions before the line), since
+     * each checkpoint in the chain contributes only the names its own line
+     * wrote.
+     *
+     * @param lineNumber Target 1-based line number. The VM will have the
+     * state that existed AFTER evaluating lines up to `lineNumber`.
+     */
+    restoreTo(lineNumber: number): void;
+    /** The index of the checkpoint recorded exactly at `lineNumber`, or -1. */
+    private indexOfCheckpointAt;
+    /** Where a checkpoint for `lineNumber` belongs, keeping the list in order. */
+    private insertionIndexFor;
+    /**
+     * The index of the last checkpoint at or before `lineNumber`, or -1.
+     *
+     * A binary search rather than a scan. The array is in document order, and
+     * this is asked once per scroll and once per async batch, on a document
+     * that can hold a checkpoint per definition.
+     */
+    private nearestCheckpointIndex;
+    /**
+     * Record what `lineNumber` has just written, without disturbing the chain
+     * after it.
+     *
+     * {@link snapshot} drops every checkpoint at or after the line, which is
+     * right for a pass running forward in document order: it re-takes them as it
+     * goes. A caller re-running a few lines out of a document does not, and
+     * dropping the entries for lines it will never visit would lose the very
+     * bindings it is sweeping through them to collect. So this overwrites in
+     * place instead.
+     *
+     * Safe against the prototype chain, because it replaces only the
+     * checkpoint's OWN bindings: a later checkpoint that also writes the name
+     * holds its own copy and goes on shadowing this one.
+     *
+     * @param lineNumber 1-based line whose recorded bindings are refreshed.
+     * @param variableNames The names it wrote.
+     * @returns Whether a checkpoint existed at that line to update.
+     */
+    updateCheckpointAt(lineNumber: number, variableNames: string[]): boolean;
+    /**
+     * Apply the bindings recorded AT `lineNumber`, leaving the rest of the VM
+     * alone.
+     *
+     * {@link restoreTo} rebuilds the whole prefix, which costs the chain every
+     * time it is called. A caller moving forward through the document already
+     * holds the prefix up to the line before, and needs only what this line
+     * added: restoring once and then applying each line in turn as it is passed
+     * costs the chain once rather than once per line.
+     *
+     * @param lineNumber 1-based line whose own bindings are applied.
+     * @returns Whether a checkpoint existed at that line.
+     */
+    applyCheckpointAt(lineNumber: number): boolean;
+    /**
+     * Find the nearest checkpoint at or before the given line number.
+     *
+     * Uses linear scan (checkpoints are sorted by lineNumber and the list
+     * is short, typically < 20 for Obsidian documents). Can be upgraded
+     * to binary search if needed for documents with 1000+ variable defs.
+     *
+     * @returns The nearest checkpoint, or null if none exists before the line.
+     */
+    getNearestCheckpoint(lineNumber: number): VMCheckpoint | null;
+    /**
+     * Get a specific checkpoint by its line number.
+     * @returns The checkpoint, or undefined if not found.
+     */
+    getCheckpointAt(lineNumber: number): VMCheckpoint | undefined;
+    /**
+     * Get the entire checkpoint chain from root to the last checkpoint.
+     * Useful for debugging and serialization.
+     */
+    getAllCheckpoints(): readonly VMCheckpoint[];
+    /**
+     * Look up a variable's value through the checkpoint chain.
+     *
+     * Walks the prototype chain starting from the most recent checkpoint,
+     * looking for the variable name as an own property. This is O(depth)
+     * where depth is the number of checkpoints since the variable was
+     * last set.
+     *
+     * **Note:** This queries the checkpointer's snapshot, not the VM.
+     * The VM may have been modified since the last snapshot (e.g., by
+     * Tier 2 execution of non-variable-def lines that don't create checkpoints).
+     *
+     * @returns The Value, or undefined if the variable was never set.
+     */
+    lookupVariable(name: string): Value | undefined;
+    /**
+     * Clear all checkpoints. The underlying VM is NOT reset, call
+     * `vm.reset()` separately if needed.
+     */
+    clear(): void;
+    /** Number of checkpoints stored. */
+    get count(): number;
+    /** Returns true if no checkpoints have been created. */
+    get isEmpty(): boolean;
+    /** The associated VM instance. */
+    get vmInstance(): VM;
+}
+
 /**
  * Registry of built-in mathematical functions.
  * Indexed by the number pushed as an operand of OpCode.CALL_BUILTIN.
@@ -951,4 +1165,4 @@ declare function pluginFunctionIndexFor(qualifiedName: string): number;
  */
 type AsConverter = (value: Value, context?: LineExecutionContext) => Value;
 
-export { type AsConverter as A, 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, allocatePluginFunctionIndex as a, builtinFunctions as b, createVM as c, pluginFunctionRegistry as d, executeBytecode as e, type DagSnapshot as f, type EngineContext as g, pluginFunctionIndexFor as p, sharedOpRegistry as s };
+export { type AsConverter as A, 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 VMCheckpoint as a, VMCheckpointer as b, allocatePluginFunctionIndex as c, builtinFunctions as d, createVM as e, executeBytecode as f, pluginFunctionRegistry as g, type DagSnapshot as h, type EngineContext as i, pluginFunctionIndexFor as p, sharedOpRegistry as s };

package/dist/chunk-44BWHZ5V.js

@@ -0,0 +1,2 @@
+var f=class{constructor(t){this.checkpoints=[];this.vm=t;}snapshot(t,e,n){if(n.length===0)return null;let i=this.indexOfCheckpointAt(t),s=i>=0?i:this.insertionIndexFor(t),r=s>0?this.checkpoints[s-1]:null,h=Object.create(null),u=Object.create(null);for(let o of n){if(this.vm.hasUserFunction(o)){let l=this.vm.getUserFunction(o);l&&(u[o]=l);continue}let p=this.vm.getVar(o);p!==void 0&&(h[o]=p);}let c={lineNumber:t,lineId:e,variables:h,functions:u,parent:r};i>=0?this.checkpoints[i]=c:this.checkpoints.splice(s,0,c);let a=this.checkpoints[s+1];return a!==void 0&&(a.parent=c),c}restoreTo(t){let e=this.nearestCheckpointIndex(t);this.vm.reset();for(let n=0;n<=e;n++){let i=this.checkpoints[n];for(let s of Object.keys(i.variables))this.vm.setVar(s,i.variables[s]);for(let s of Object.keys(i.functions)){let r=i.functions[s];this.vm.defineUserFunction(r.name,r.params,r.program);}}}indexOfCheckpointAt(t){let e=this.nearestCheckpointIndex(t);return e>=0&&this.checkpoints[e].lineNumber===t?e:-1}insertionIndexFor(t){return this.nearestCheckpointIndex(t)+1}nearestCheckpointIndex(t){let e=0,n=this.checkpoints.length-1,i=-1;for(;e<=n;){let s=e+n>>1;this.checkpoints[s].lineNumber<=t?(i=s,e=s+1):n=s-1;}return i}updateCheckpointAt(t,e){let n=this.getCheckpointAt(t);if(!n)return  false;for(let i of e){if(this.vm.hasUserFunction(i)){let r=this.vm.getUserFunction(i);r&&(n.functions[i]=r);continue}let s=this.vm.getVar(i);s!==void 0&&(n.variables[i]=s);}return  true}applyCheckpointAt(t){let e=this.getCheckpointAt(t);if(!e)return  false;for(let n of Object.keys(e.variables))this.vm.setVar(n,e.variables[n]);for(let n of Object.keys(e.functions)){let i=e.functions[n];this.vm.defineUserFunction(i.name,i.params,i.program);}return  true}getNearestCheckpoint(t){let e=this.nearestCheckpointIndex(t);return e<0?null:this.checkpoints[e]}getCheckpointAt(t){let e=this.nearestCheckpointIndex(t);if(e<0)return;let n=this.checkpoints[e];return n.lineNumber===t?n:void 0}getAllCheckpoints(){return this.checkpoints}lookupVariable(t){if(this.checkpoints.length===0)return;let e=this.checkpoints[this.checkpoints.length-1];for(;e;){if(Object.prototype.hasOwnProperty.call(e.variables,t))return e.variables[t];e=e.parent;}}clear(){this.checkpoints=[];}get count(){return this.checkpoints.length}get isEmpty(){return this.checkpoints.length===0}get vmInstance(){return this.vm}};export{f as a};//# sourceMappingURL=chunk-44BWHZ5V.js.map
+//# sourceMappingURL=chunk-44BWHZ5V.js.map

package/dist/chunk-44BWHZ5V.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vm/VMCheckpoints.ts"],"names":["VMCheckpointer","vm","lineNumber","lineId","variableNames","existing","insertAt","parent","variables","functions","name","fn","val","checkpoint","next","targetIndex","i","cp","key","index","low","high","result","mid","value","candidate"],"mappings":"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","file":"chunk-44BWHZ5V.js","sourcesContent":["import { Value } from \"@solve-js/vm/Value\";\nimport type { VM } from \"@solve-js/vm/OpRegistry\";\nimport type { UserFunctionDef } from \"@solve-js/parser/BytecodeBuilder\";\n\n// ── VMCheckpoint ────────────────────────────────────────────────────────\n\n/**\n * A point-in-time snapshot of VM variable state.\n *\n * Each checkpoint holds only the variables that CHANGED at its line, and\n * reaches the rest through its `parent` link. A lookup walks that chain until\n * it finds the name; a restore walks it from the root applying each link's own\n * bindings in turn, so a later line's value naturally overwrites an earlier\n * one's.\n *\n * ```text\n * Checkpoint 0 (root):  {}                      // empty scope\n * Checkpoint 1 (:x=5):  { x: 5 }    parent → 0\n * Checkpoint 2 (:y=8):  { y: 8 }    parent → 1\n * Checkpoint 3 (:x=3):  { x: 3 }    parent → 2   // shadows x=5\n * ```\n *\n * To look up `x` at checkpoint 3: find own `x=3` → done.\n * To look up `y` at checkpoint 3: not own → walk parent to checkpoint 2 → `y=8`.\n * To look up `z` at checkpoint 3: not found anywhere → undefined.\n *\n * **Memory:** O(number of variable definitions) heap, independent of\n * document length. Typical Obsidian documents have < 100 variable defs,\n * so total checkpoint heap is < 10 KB.\n */\nexport interface VMCheckpoint {\n\t/** 1-based line number where this checkpoint was created. */\n\tlineNumber: number;\n\t/** Persistent line ID from DocumentModel. */\n\tlineId: number;\n\t/**\n\t * Variable name → Value at this checkpoint.\n\t * Only the variables set or updated at this line; the rest are reached\n\t * through {@link VMCheckpoint.parent}.\n\t */\n\tvariables: Record<string, Value>;\n\t/**\n\t * User-defined-function name → definition at this checkpoint. SEPARATE\n\t * from `variables` above (not prototypally chained the same way\n\t * `restoreTo()` replays every checkpoint in the chain in order, so a\n\t * later redefinition of the same function name naturally overwrites an\n\t * earlier one during replay, without needing its own prototype walk).\n\t *\n\t * Without this field, a function definition's checkpoint entry would be\n\t * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every\n\t * written name, which returns `undefined` for a function name (function\n\t * defs live in `vm.userFunctions`, not the flat variable store), and a\n\t * `val !== undefined` guard silently skipped it. A scroll-triggered\n\t * `restoreTo()` would then reset the VM and replay only `variables`,\n\t * making a function defined above the new viewport vanish (calling it\n\t * would throw `UNDEFINED_FUNCTION`) even though the document still\n\t * shows its definition line as clean/cached.\n\t */\n\tfunctions: Record<string, UserFunctionDef>;\n\t/** Parent checkpoint (closer to document start), or null for root. */\n\tparent: VMCheckpoint | null;\n}\n\n// ── VMCheckpointer ──────────────────────────────────────────────────────\n\n/**\n * Manages VM state checkpoints for the three-tier evaluation strategy.\n *\n * **Checkpoint creation:** After a variable-definition line executes\n * (Tier 1 or Tier 3), `snapshot()` records the current values of the\n * written variables. The checkpoint is linked via prototypal inheritance\n * to the previous checkpoint, so only changed variables consume memory.\n *\n * **Checkpoint restoration:** Before evaluating a viewport whose start line\n * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all\n * variable definitions up to and including that line. This avoids\n * re-evaluating the entire document from line 1 on every scroll.\n *\n * **Thread safety:** Checkpoints are created synchronously on the main\n * thread during evaluation. They are immutable after creation (Value is\n * an immutable type), so no synchronization is needed.\n *\n * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`\n * to find the checkpoint just before the new viewport start, then call\n * `restoreTo()` to set up the VM before evaluating only the visible lines.\n * This is the key to O(visible lines) scrolling instead of O(document).\n */\nexport class VMCheckpointer {\n\t/** Ordered array of checkpoints (ascending lineNumber). */\n\tprivate checkpoints: VMCheckpoint[] = [];\n\t/** The VM instance whose variables are snapshotted/restored. */\n\tprivate vm: VM;\n\n\tconstructor(vm: VM) {\n\t\tthis.vm = vm;\n\t}\n\n\t// ── Snapshot ─────────────────────────────────────────────────────\n\n\t/**\n\t * Create a checkpoint at the current line, recording the VM values of\n\t * the specified variables.\n\t *\n\t * Records only what this line wrote; the rest is reached through the\n\t * parent link rather than copied.\n\t *\n\t * A line that is snapshotted again drops every checkpoint at or after it\n\t * first, so the list stays in document order and the new checkpoint\n\t * inherits from the line before it rather than from one after it. See the\n\t * body for what went wrong without that.\n\t *\n\t * @param lineNumber 1-based line position.\n\t * @param lineId Persistent line ID from DocumentModel.\n\t * @param variableNames Names of variables that were written at this line.\n\t * @returns The new checkpoint, or null if no variable names provided.\n\t */\n\tsnapshot(\n\t\tlineNumber: number,\n\t\tlineId: number,\n\t\tvariableNames: string[]\n\t): VMCheckpoint | null {\n\t\tif (variableNames.length === 0) return null;\n\n\t\t// This line's own entry is replaced, and nothing else is touched.\n\t\t//\n\t\t// The list is a sequence of document positions and `restoreTo` reads it\n\t\t// as one, so a re-run must not append after entries that come later in\n\t\t// the document: editing line 2 of a document whose lines 1, 2 and 3 each\n\t\t// define something left the list as [1, 2, 3, 2], and a restore to line\n\t\t// 2 then found the stale entry.\n\t\t//\n\t\t// Replacing rather than truncating is the part that took a second go.\n\t\t// Dropping every entry at or after the line is sound only for a pass\n\t\t// running from line 1, which re-takes them as it continues. A pass\n\t\t// limited to a viewport does not: it re-snapshots the top of the\n\t\t// document and never reaches the definitions below its end line, so the\n\t\t// chain lost them, and `restoreTo` then RESET the VM and replayed a\n\t\t// prefix that no longer mentioned them. A line further down reading one\n\t\t// answered `Undefined variable` where it had answered a number. Absent\n\t\t// is worse than stale here: a stale entry is what the document is\n\t\t// currently showing anyway, and the pass corrects it when it reaches\n\t\t// that line.\n\t\tconst existing = this.indexOfCheckpointAt(lineNumber);\n\t\tconst insertAt = existing >= 0 ? existing : this.insertionIndexFor(lineNumber);\n\t\tconst parent = insertAt > 0 ? this.checkpoints[insertAt - 1] : null;\n\n\t\t// Each checkpoint holds only what its line wrote, and reaches the rest\n\t\t// through `parent`. It used to reach it through the prototype chain\n\t\t// instead, which held the same entries and cost the same memory, and\n\t\t// made the chain as deep as the document has definitions: a null\n\t\t// prototype is a flat object, and one per definition is a chain two\n\t\t// thousand deep on a document of two thousand definitions. Creating and\n\t\t// reading those took a pass over such a document from 6.0 ms to 23.1 ms.\n\t\t//\n\t\t// Nothing needed the inheritance. `restoreTo` walks `parent` and applies\n\t\t// each checkpoint's OWN keys, which is the same set either way, and the\n\t\t// one reader that did walk the prototype now walks `parent` too.\n\t\t//\n\t\t// Null-prototyped rather than `{}`, so a variable named `constructor` or\n\t\t// `toString` is a key like any other.\n\t\tconst variables: Record<string, Value> = Object.create(null) as Record<string, Value>;\n\t\tconst functions: Record<string, UserFunctionDef> = Object.create(null) as Record<string, UserFunctionDef>;\n\n\t\t// Record current VM values for the written names, routing each into\n\t\t// the right bag (a name is either a variable or a user-defined\n\t\t// function, never both; see VMCheckpoint.functions's doc comment for\n\t\t// why this dispatch is required, not optional).\n\t\tfor (const name of variableNames) {\n\t\t\tif (this.vm.hasUserFunction(name)) {\n\t\t\t\tconst fn = this.vm.getUserFunction(name);\n\t\t\t\tif (fn) functions[name] = fn;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst val = this.vm.getVar(name);\n\t\t\tif (val !== undefined) {\n\t\t\t\tvariables[name] = val;\n\t\t\t}\n\t\t}\n\n\t\tconst checkpoint: VMCheckpoint = {\n\t\t\tlineNumber,\n\t\t\tlineId,\n\t\t\tvariables,\n\t\t\tfunctions,\n\t\t\tparent,\n\t\t};\n\t\tif (existing >= 0) this.checkpoints[existing] = checkpoint;\n\t\telse this.checkpoints.splice(insertAt, 0, checkpoint);\n\t\t// The entry after this one now follows a different object.\n\t\tconst next = this.checkpoints[insertAt + 1];\n\t\tif (next !== undefined) next.parent = checkpoint;\n\t\treturn checkpoint;\n\t}\n\n\t// ── Restore ──────────────────────────────────────────────────────\n\n\t/**\n\t * Restore the VM to the state at or just after the given line number.\n\t *\n\t * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,\n\t * then replays all variable definitions from root → that checkpoint\n\t * into the VM via `setVar()`. The VM's stack is also reset.\n\t *\n\t * If no checkpoint exists at or before the target line, the VM is\n\t * fully reset (empty scope, empty stack).\n\t *\n\t * **Performance:** O(total variable definitions before the line), since\n\t * each checkpoint in the chain contributes only the names its own line\n\t * wrote.\n\t *\n\t * @param lineNumber Target 1-based line number. The VM will have the\n\t * state that existed AFTER evaluating lines up to `lineNumber`.\n\t */\n\trestoreTo(lineNumber: number): void {\n\t\t// The chain from the root to the target IS the array up to that index.\n\t\t//\n\t\t// Every checkpoint is created with the one before it in the array as its\n\t\t// parent (see {@link snapshot}), and the array is kept in document\n\t\t// order, so walking parent links would visit exactly these entries in\n\t\t// exactly this order. Reading the array instead of the links costs no\n\t\t// allocation, and it was the links that made this quadratic: the walk\n\t\t// runs target-to-root, so the chain was assembled by `unshift`ing each\n\t\t// entry onto the front, which shifts every entry already there. A\n\t\t// document with two thousand definitions did four million shifts per\n\t\t// restore, and a scroll restores.\n\t\t//\n\t\t// `CheckpointsStayInDocumentOrder.spec.ts` asserts the invariant this\n\t\t// relies on, so a change that broke it would fail there rather than\n\t\t// quietly restoring the wrong state here.\n\t\tconst targetIndex = this.nearestCheckpointIndex(lineNumber);\n\n\t\tthis.vm.reset();\n\t\tfor (let i = 0; i <= targetIndex; i++) {\n\t\t\tconst cp = this.checkpoints[i];\n\t\t\t// Only the names this checkpoint's own line wrote; the ones before\n\t\t\t// it are applied by their own entries earlier in this same walk.\n\t\t\tfor (const key of Object.keys(cp.variables)) {\n\t\t\t\tthis.vm.setVar(key, cp.variables[key]);\n\t\t\t}\n\t\t\t// Replay function definitions the same way, a later checkpoint's\n\t\t\t// redefinition of the same name naturally overwrites an earlier\n\t\t\t// one since the walk runs root-to-target.\n\t\t\tfor (const key of Object.keys(cp.functions)) {\n\t\t\t\tconst fn = cp.functions[key];\n\t\t\t\tthis.vm.defineUserFunction(fn.name, fn.params, fn.program);\n\t\t\t}\n\t\t}\n\t}\n\n\t/** The index of the checkpoint recorded exactly at `lineNumber`, or -1. */\n\tprivate indexOfCheckpointAt(lineNumber: number): number {\n\t\tconst index = this.nearestCheckpointIndex(lineNumber);\n\t\treturn index >= 0 && this.checkpoints[index].lineNumber === lineNumber ? index : -1;\n\t}\n\n\t/** Where a checkpoint for `lineNumber` belongs, keeping the list in order. */\n\tprivate insertionIndexFor(lineNumber: number): number {\n\t\treturn this.nearestCheckpointIndex(lineNumber) + 1;\n\t}\n\n\t/**\n\t * The index of the last checkpoint at or before `lineNumber`, or -1.\n\t *\n\t * A binary search rather than a scan. The array is in document order, and\n\t * this is asked once per scroll and once per async batch, on a document\n\t * that can hold a checkpoint per definition.\n\t */\n\tprivate nearestCheckpointIndex(lineNumber: number): number {\n\t\tlet low = 0;\n\t\tlet high = this.checkpoints.length - 1;\n\t\tlet result = -1;\n\t\twhile (low <= high) {\n\t\t\tconst mid = (low + high) >> 1;\n\t\t\tif (this.checkpoints[mid].lineNumber <= lineNumber) {\n\t\t\t\tresult = mid;\n\t\t\t\tlow = mid + 1;\n\t\t\t} else {\n\t\t\t\thigh = mid - 1;\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Record what `lineNumber` has just written, without disturbing the chain\n\t * after it.\n\t *\n\t * {@link snapshot} drops every checkpoint at or after the line, which is\n\t * right for a pass running forward in document order: it re-takes them as it\n\t * goes. A caller re-running a few lines out of a document does not, and\n\t * dropping the entries for lines it will never visit would lose the very\n\t * bindings it is sweeping through them to collect. So this overwrites in\n\t * place instead.\n\t *\n\t * Safe against the prototype chain, because it replaces only the\n\t * checkpoint's OWN bindings: a later checkpoint that also writes the name\n\t * holds its own copy and goes on shadowing this one.\n\t *\n\t * @param lineNumber 1-based line whose recorded bindings are refreshed.\n\t * @param variableNames The names it wrote.\n\t * @returns Whether a checkpoint existed at that line to update.\n\t */\n\tupdateCheckpointAt(lineNumber: number, variableNames: string[]): boolean {\n\t\tconst checkpoint = this.getCheckpointAt(lineNumber);\n\t\tif (!checkpoint) return false;\n\t\tfor (const name of variableNames) {\n\t\t\tif (this.vm.hasUserFunction(name)) {\n\t\t\t\tconst fn = this.vm.getUserFunction(name);\n\t\t\t\tif (fn) checkpoint.functions[name] = fn;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst value = this.vm.getVar(name);\n\t\t\tif (value !== undefined) checkpoint.variables[name] = value;\n\t\t}\n\t\treturn true;\n\t}\n\n\t/**\n\t * Apply the bindings recorded AT `lineNumber`, leaving the rest of the VM\n\t * alone.\n\t *\n\t * {@link restoreTo} rebuilds the whole prefix, which costs the chain every\n\t * time it is called. A caller moving forward through the document already\n\t * holds the prefix up to the line before, and needs only what this line\n\t * added: restoring once and then applying each line in turn as it is passed\n\t * costs the chain once rather than once per line.\n\t *\n\t * @param lineNumber 1-based line whose own bindings are applied.\n\t * @returns Whether a checkpoint existed at that line.\n\t */\n\tapplyCheckpointAt(lineNumber: number): boolean {\n\t\tconst checkpoint = this.getCheckpointAt(lineNumber);\n\t\tif (!checkpoint) return false;\n\t\tfor (const key of Object.keys(checkpoint.variables)) {\n\t\t\tthis.vm.setVar(key, checkpoint.variables[key]);\n\t\t}\n\t\tfor (const key of Object.keys(checkpoint.functions)) {\n\t\t\tconst fn = checkpoint.functions[key];\n\t\t\tthis.vm.defineUserFunction(fn.name, fn.params, fn.program);\n\t\t}\n\t\treturn true;\n\t}\n\n\t// ── Queries ──────────────────────────────────────────────────────\n\n\t/**\n\t * Find the nearest checkpoint at or before the given line number.\n\t *\n\t * Uses linear scan (checkpoints are sorted by lineNumber and the list\n\t * is short, typically < 20 for Obsidian documents). Can be upgraded\n\t * to binary search if needed for documents with 1000+ variable defs.\n\t *\n\t * @returns The nearest checkpoint, or null if none exists before the line.\n\t */\n\tgetNearestCheckpoint(lineNumber: number): VMCheckpoint | null {\n\t\tconst index = this.nearestCheckpointIndex(lineNumber);\n\t\treturn index < 0 ? null : this.checkpoints[index];\n\t}\n\n\t/**\n\t * Get a specific checkpoint by its line number.\n\t * @returns The checkpoint, or undefined if not found.\n\t */\n\tgetCheckpointAt(lineNumber: number): VMCheckpoint | undefined {\n\t\t// Searched, not scanned: the async sweep asks this once for every line\n\t\t// it walks past, and a scan would make that walk quadratic.\n\t\tconst index = this.nearestCheckpointIndex(lineNumber);\n\t\tif (index < 0) return undefined;\n\t\tconst candidate = this.checkpoints[index];\n\t\treturn candidate.lineNumber === lineNumber ? candidate : undefined;\n\t}\n\n\t/**\n\t * Get the entire checkpoint chain from root to the last checkpoint.\n\t * Useful for debugging and serialization.\n\t */\n\tgetAllCheckpoints(): readonly VMCheckpoint[] {\n\t\treturn this.checkpoints;\n\t}\n\n\t/**\n\t * Look up a variable's value through the checkpoint chain.\n\t *\n\t * Walks the prototype chain starting from the most recent checkpoint,\n\t * looking for the variable name as an own property. This is O(depth)\n\t * where depth is the number of checkpoints since the variable was\n\t * last set.\n\t *\n\t * **Note:** This queries the checkpointer's snapshot, not the VM.\n\t * The VM may have been modified since the last snapshot (e.g., by\n\t * Tier 2 execution of non-variable-def lines that don't create checkpoints).\n\t *\n\t * @returns The Value, or undefined if the variable was never set.\n\t */\n\tlookupVariable(name: string): Value | undefined {\n\t\tif (this.checkpoints.length === 0) return undefined;\n\n\t\tlet checkpoint: VMCheckpoint | null = this.checkpoints[this.checkpoints.length - 1];\n\t\twhile (checkpoint) {\n\t\t\tif (Object.prototype.hasOwnProperty.call(checkpoint.variables, name)) {\n\t\t\t\treturn checkpoint.variables[name];\n\t\t\t}\n\t\t\tcheckpoint = checkpoint.parent;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// ── Lifecycle ────────────────────────────────────────────────────\n\n\t/**\n\t * Clear all checkpoints. The underlying VM is NOT reset, call\n\t * `vm.reset()` separately if needed.\n\t */\n\tclear(): void {\n\t\tthis.checkpoints = [];\n\t}\n\n\t/** Number of checkpoints stored. */\n\tget count(): number {\n\t\treturn this.checkpoints.length;\n\t}\n\n\t/** Returns true if no checkpoints have been created. */\n\tget isEmpty(): boolean {\n\t\treturn this.checkpoints.length === 0;\n\t}\n\n\t/** The associated VM instance. */\n\tget vmInstance(): VM {\n\t\treturn this.vm;\n\t}\n}\n"]}