solve-engine 2.38.13 → 2.38.14

package/dist/{PackageCompatibility-Cu_bHpwY.d.cts → PackageCompatibility-ByCnkoxf.d.cts}

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

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

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

package/dist/{PackageRegistry-DMKDsYiA.d.ts → PackageRegistry-11ThI3Qg.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-BbNZtVJc.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-BN4zOado.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-5ATHQ045.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-5ATHQ045.d.cts}

@@ -892,6 +892,208 @@ 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;
+    /**
+     * 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 +1153,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-BbNZtVJc.d.ts}

@@ -892,6 +892,208 @@ 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;
+    /**
+     * 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 +1153,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-CW623SJ7.cjs → chunk-54MEZ574.cjs}

@@ -1,2 +1,2 @@
-'use strict';var chunk6SYU4MH7_cjs=require('./chunk-6SYU4MH7.cjs');var d="2.38.13";var m=d;var l={date:{maxOffsetYears:100,minOffsetYears:-100,defaultFormat:"YYYY-MM-DD",inputOrder:"auto",onAmbiguous:"refuse"},performance:{defaultCacheSize:2e3,maxDocumentLines:1e5},validation:{maxExpressionLength:2e3,maxComplexity:500,maxNestingDepth:50,autoBalanceParens:false},vm:{maxStackDepth:200,maxInstructions:5e4,maxCollectionSize:1e5,maxAllocatedElements:2e6,maxFunctionCalls:1e4,maxGoalSeekIterations:100},worker:{maxConcurrentWorkers:4,idleTimeoutMs:3e4,maxRetries:3,baseBackoffMs:1e3},diagnostic:{enabled:false,vmTraceEnabled:false},backgroundRefresh:{enabled:false},network:{enabled:true}};function n(s,e){return {date:{...s.date,...e.date},performance:{...s.performance,...e.performance},validation:{...s.validation,...e.validation},vm:{...s.vm,...e.vm},worker:{...s.worker,...e.worker},diagnostic:{...s.diagnostic,...e.diagnostic},backgroundRefresh:{...s.backgroundRefresh,...e.backgroundRefresh},network:{...s.network,...e.network}}}var c=class{constructor(e={}){this.config=n(l,e);}get(e){let o=e.split("."),t=this.config;for(let i of o)if(t&&typeof t=="object"&&i in t)t=t[i];else throw chunk6SYU4MH7_cjs.c.config("CONFIG_PATH_NOT_FOUND",`Configuration path not found: ${e}`,{path:e});return t}set(e,o){let t=e.split(".");if(t.length<2)throw chunk6SYU4MH7_cjs.c.config("INVALID_CONFIG_PATH",`Invalid path: ${e}. Must be in format 'section.property'`,{path:e});let i=t[0],u=t[1];if(!(i in this.config))throw chunk6SYU4MH7_cjs.c.config("CONFIG_SECTION_NOT_FOUND",`Configuration section not found: ${i}`,{section:i,path:e});let a=this.config[i];if(a&&typeof a=="object")a[u]=o;else throw chunk6SYU4MH7_cjs.c.config("CONFIG_PROPERTY_NOT_FOUND",`Configuration property not found: ${e}`,{path:e})}getConfig(){return n(this.config,{})}update(e){this.config=n(this.config,e);}reset(){this.config=n(l,{});}validate(){let e=[];return this.config.performance.maxDocumentLines>1e5&&e.push("maxDocumentLines cannot exceed 100,000"),this.config.date.maxOffsetYears>1e3&&e.push("maxOffsetYears cannot exceed 1000"),{valid:e.length===0,error:e.join("; "),warnings:[]}}};exports.a=m;exports.b=l;exports.c=n;exports.d=c;//# sourceMappingURL=chunk-CW623SJ7.cjs.map
-//# sourceMappingURL=chunk-CW623SJ7.cjs.map
+'use strict';var chunk6SYU4MH7_cjs=require('./chunk-6SYU4MH7.cjs');var d="2.38.14";var m=d;var l={date:{maxOffsetYears:100,minOffsetYears:-100,defaultFormat:"YYYY-MM-DD",inputOrder:"auto",onAmbiguous:"refuse"},performance:{defaultCacheSize:2e3,maxDocumentLines:1e5},validation:{maxExpressionLength:2e3,maxComplexity:500,maxNestingDepth:50,autoBalanceParens:false},vm:{maxStackDepth:200,maxInstructions:5e4,maxCollectionSize:1e5,maxAllocatedElements:2e6,maxFunctionCalls:1e4,maxGoalSeekIterations:100},worker:{maxConcurrentWorkers:4,idleTimeoutMs:3e4,maxRetries:3,baseBackoffMs:1e3},diagnostic:{enabled:false,vmTraceEnabled:false},backgroundRefresh:{enabled:false},network:{enabled:true}};function n(s,e){return {date:{...s.date,...e.date},performance:{...s.performance,...e.performance},validation:{...s.validation,...e.validation},vm:{...s.vm,...e.vm},worker:{...s.worker,...e.worker},diagnostic:{...s.diagnostic,...e.diagnostic},backgroundRefresh:{...s.backgroundRefresh,...e.backgroundRefresh},network:{...s.network,...e.network}}}var c=class{constructor(e={}){this.config=n(l,e);}get(e){let o=e.split("."),t=this.config;for(let i of o)if(t&&typeof t=="object"&&i in t)t=t[i];else throw chunk6SYU4MH7_cjs.c.config("CONFIG_PATH_NOT_FOUND",`Configuration path not found: ${e}`,{path:e});return t}set(e,o){let t=e.split(".");if(t.length<2)throw chunk6SYU4MH7_cjs.c.config("INVALID_CONFIG_PATH",`Invalid path: ${e}. Must be in format 'section.property'`,{path:e});let i=t[0],u=t[1];if(!(i in this.config))throw chunk6SYU4MH7_cjs.c.config("CONFIG_SECTION_NOT_FOUND",`Configuration section not found: ${i}`,{section:i,path:e});let a=this.config[i];if(a&&typeof a=="object")a[u]=o;else throw chunk6SYU4MH7_cjs.c.config("CONFIG_PROPERTY_NOT_FOUND",`Configuration property not found: ${e}`,{path:e})}getConfig(){return n(this.config,{})}update(e){this.config=n(this.config,e);}reset(){this.config=n(l,{});}validate(){let e=[];return this.config.performance.maxDocumentLines>1e5&&e.push("maxDocumentLines cannot exceed 100,000"),this.config.date.maxOffsetYears>1e3&&e.push("maxOffsetYears cannot exceed 1000"),{valid:e.length===0,error:e.join("; "),warnings:[]}}};exports.a=m;exports.b=l;exports.c=n;exports.d=c;//# sourceMappingURL=chunk-54MEZ574.cjs.map
+//# sourceMappingURL=chunk-54MEZ574.cjs.map