VMCheckpoint

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

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.

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.

Properties

functions

functions: Record<string, UserFunctionDef>;

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

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.

---

lineId

lineId: number;

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

Persistent line ID from DocumentModel.

---

lineNumber

lineNumber: number;

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

1-based line number where this checkpoint was created.

---

parent

parent: VMCheckpoint | null;

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

Parent checkpoint (closer to document start), or null for root.

---

variables

variables: Record<string, Value>;

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

Variable name → Value at this checkpoint. Own properties are variables set/updated at this line. The prototype chain provides inherited variables from parent checkpoints.