VMCheckpoint

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

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.

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.

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. Only the variables set or updated at this line; the rest are reached through VMCheckpoint.parent.