solve-engine 2.38.13 → 2.38.14

package/dist/VMCheckpoints-BwLCnV8C.d.cts

@@ -1,176 +0,0 @@
-import { V as Value } from './Value-B55Hvn3e.cjs';
-import { V as VM } from './VMBuiltins-D3rXBm2k.cjs';
-import { U as UserFunctionDef } from './BytecodeBuilder-DSWKZi4f.cjs';
-
-/**
- * A point-in-time snapshot of VM variable state.
- *
- * Uses **prototypal inheritance** for memory efficiency: each checkpoint's
- * `variables` object has its parent checkpoint's `variables` as its
- * `__proto__`. This means a `getVar("x")` lookup walks the prototype chain
- * until it finds `x`, and only variables that CHANGED at this checkpoint
- * consume heap space. Unchanged variables are inherited from the parent.
- *
- * ```text
- * Checkpoint 0 (root):  {}                        // empty scope
- * Checkpoint 1 (:x=5):  { x: 5 }    __proto__ → 0
- * Checkpoint 2 (:y=8):  { y: 8 }    __proto__ → 1
- * Checkpoint 3 (:x=3):  { x: 3 }    __proto__ → 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 proto 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.
-     * Own properties are variables set/updated at this line.
-     * The prototype chain provides inherited variables from parent checkpoints.
-     */
-    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.
-     *
-     * Uses prototypal inheritance: `Object.create(parent.variables)` so
-     * that inherited variable lookups fall through to previous checkpoints
-     * without copying all variables into each checkpoint.
-     *
-     * 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(number of checkpoints × variables per checkpoint).
-     * With prototypal inheritance, `Object.keys()` on each checkpoint
-     * returns only the variables that were set at that checkpoint (not
-     * inherited ones), so the total work is O(total variable definitions
-     * in the document), which is < 100 for typical Obsidian documents.
-     *
-     * @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;
-    /**
-     * 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;
-}
-
-export { type VMCheckpoint as V, VMCheckpointer as a };