VMCheckpointer

Defined in: packages/engine/src/vm/VMCheckpoints.ts:88

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).

Constructors

Constructor

new VMCheckpointer(vm): VMCheckpointer;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:94

Parameters

Parameter	Type
`vm`	`VM`

Returns

VMCheckpointer

Accessors

count

Get Signature

get count(): number;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:294

Number of checkpoints stored.

Returns

number

isEmpty

Get Signature

get isEmpty(): boolean;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:299

Returns true if no checkpoints have been created.

Returns

boolean

vmInstance

Get Signature

get vmInstance(): VM;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:304

The associated VM instance.

Returns

VM

Methods

clear()

clear(): void;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:289

Clear all checkpoints. The underlying VM is NOT reset, call vm.reset() separately if needed.

Returns

void

getAllCheckpoints()

getAllCheckpoints(): readonly VMCheckpoint[];

Defined in: packages/engine/src/vm/VMCheckpoints.ts:251

Get the entire checkpoint chain from root to the last checkpoint. Useful for debugging and serialization.

Returns

readonly VMCheckpoint[]

getCheckpointAt()

getCheckpointAt(lineNumber):
  | VMCheckpoint
  | undefined;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:243

Get a specific checkpoint by its line number.

Parameters

Parameter	Type
`lineNumber`	`number`

Returns

| VMCheckpoint | undefined

The checkpoint, or undefined if not found.

getNearestCheckpoint()

getNearestCheckpoint(lineNumber): VMCheckpoint | null;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:227

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.

Parameters

Parameter	Type
`lineNumber`	`number`

Returns

VMCheckpoint | null

The nearest checkpoint, or null if none exists before the line.

lookupVariable()

lookupVariable(name): Value | undefined;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:269

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).

Parameters

Parameter	Type
`name`	`string`

Returns

Value | undefined

The Value, or undefined if the variable was never set.

restoreTo()

restoreTo(lineNumber): void;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:181

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.

Parameters

Parameter	Type	Description
`lineNumber`	`number`	Target 1-based line number. The VM will have the state that existed AFTER evaluating lines up to `lineNumber`.

Returns

void

snapshot()

snapshot(
   lineNumber,
   lineId,
   variableNames): VMCheckpoint | null;

Defined in: packages/engine/src/vm/VMCheckpoints.ts:113

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.

Parameters

Parameter	Type	Description
`lineNumber`	`number`	1-based line position.
`lineId`	`number`	Persistent line ID from DocumentModel.
`variableNames`	`string`[]	Names of variables that were written at this line.

Returns

VMCheckpoint | null

The new checkpoint, or null if no variable names provided.