solve-engine 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/variables.js

@@ -1,3 +1,4 @@
 export { VariableResolver, sharedVariableResolver } from './chunk-GCM5JHMX.js';
+import './chunk-YLJ4XMA6.js';
 //# sourceMappingURL=variables.js.map
 //# sourceMappingURL=variables.js.map

package/dist/vm.cjs

@@ -12,6 +12,7 @@ var chunkOC6LTXYS_cjs = require('./chunk-OC6LTXYS.cjs');
 require('./chunk-QNJ4ACRT.cjs');
 require('./chunk-53B6KDDJ.cjs');
 require('./chunk-M4N5GA5Z.cjs');
+require('./chunk-B7LXJ6LC.cjs');
 
 // src/vm/VMCheckpoints.ts
 var VMCheckpointer = class {

package/dist/vm.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/vm/VMCheckpoints.ts"],"names":[],"mappings":"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","file":"vm.cjs","sourcesContent":["import { Value } from \"@solve-js/vm/Value\";\nimport type { VM } from \"@solve-js/vm/OpRegistry\";\nimport type { UserFunctionDef } from \"@solve-js/parser/BytecodeBuilder\";\n\n// ── VMCheckpoint ────────────────────────────────────────────────────────\n\n/**\n * A point-in-time snapshot of VM variable state.\n *\n * Uses **prototypal inheritance** for memory efficiency: each checkpoint's\n * `variables` object has its parent checkpoint's `variables` as its\n * `__proto__`. This means a `getVar(\"x\")` lookup walks the prototype chain\n * until it finds `x`, and only variables that CHANGED at this checkpoint\n * consume heap space. Unchanged variables are inherited from the parent.\n *\n * ```text\n * Checkpoint 0 (root):  {}                        // empty scope\n * Checkpoint 1 (:x=5):  { x: 5 }    __proto__ → 0\n * Checkpoint 2 (:y=8):  { y: 8 }    __proto__ → 1\n * Checkpoint 3 (:x=3):  { x: 3 }    __proto__ → 2   // shadows x=5\n * ```\n *\n * To look up `x` at checkpoint 3: find own `x=3` → done.\n * To look up `y` at checkpoint 3: not own → walk proto to checkpoint 2 → `y=8`.\n * To look up `z` at checkpoint 3: not found anywhere → undefined.\n *\n * **Memory:** O(number of variable definitions) heap, independent of\n * document length. Typical Obsidian documents have < 100 variable defs,\n * so total checkpoint heap is < 10 KB.\n */\nexport interface VMCheckpoint {\n\t/** 1-based line number where this checkpoint was created. */\n\tlineNumber: number;\n\t/** Persistent line ID from DocumentModel. */\n\tlineId: number;\n\t/**\n\t * Variable name → Value at this checkpoint.\n\t * Own properties are variables set/updated at this line.\n\t * The prototype chain provides inherited variables from parent checkpoints.\n\t */\n\tvariables: Record<string, Value>;\n\t/**\n\t * User-defined-function name → definition at this checkpoint. SEPARATE\n\t * from `variables` above (not prototypally chained the same way\n\t * `restoreTo()` replays every checkpoint in the chain in order, so a\n\t * later redefinition of the same function name naturally overwrites an\n\t * earlier one during replay, without needing its own prototype walk).\n\t *\n\t * Without this field, a function definition's checkpoint entry would be\n\t * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every\n\t * written name, which returns `undefined` for a function name (function\n\t * defs live in `vm.userFunctions`, not the flat variable store), and a\n\t * `val !== undefined` guard silently skipped it. A scroll-triggered\n\t * `restoreTo()` would then reset the VM and replay only `variables`,\n\t * making a function defined above the new viewport vanish (calling it\n\t * would throw `UNDEFINED_FUNCTION`) even though the document still\n\t * shows its definition line as clean/cached.\n\t */\n\tfunctions: Record<string, UserFunctionDef>;\n\t/** Parent checkpoint (closer to document start), or null for root. */\n\tparent: VMCheckpoint | null;\n}\n\n// ── VMCheckpointer ──────────────────────────────────────────────────────\n\n/**\n * Manages VM state checkpoints for the three-tier evaluation strategy.\n *\n * **Checkpoint creation:** After a variable-definition line executes\n * (Tier 1 or Tier 3), `snapshot()` records the current values of the\n * written variables. The checkpoint is linked via prototypal inheritance\n * to the previous checkpoint, so only changed variables consume memory.\n *\n * **Checkpoint restoration:** Before evaluating a viewport whose start line\n * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all\n * variable definitions up to and including that line. This avoids\n * re-evaluating the entire document from line 1 on every scroll.\n *\n * **Thread safety:** Checkpoints are created synchronously on the main\n * thread during evaluation. They are immutable after creation (Value is\n * an immutable type), so no synchronization is needed.\n *\n * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`\n * to find the checkpoint just before the new viewport start, then call\n * `restoreTo()` to set up the VM before evaluating only the visible lines.\n * This is the key to O(visible lines) scrolling instead of O(document).\n */\nexport class VMCheckpointer {\n\t/** Ordered array of checkpoints (ascending lineNumber). */\n\tprivate checkpoints: VMCheckpoint[] = [];\n\t/** The VM instance whose variables are snapshotted/restored. */\n\tprivate vm: VM;\n\n\tconstructor(vm: VM) {\n\t\tthis.vm = vm;\n\t}\n\n\t// ── Snapshot ─────────────────────────────────────────────────────\n\n\t/**\n\t * Create a checkpoint at the current line, recording the VM values of\n\t * the specified variables.\n\t *\n\t * Uses prototypal inheritance: `Object.create(parent.variables)` so\n\t * that inherited variable lookups fall through to previous checkpoints\n\t * without copying all variables into each checkpoint.\n\t *\n\t * @param lineNumber 1-based line position.\n\t * @param lineId Persistent line ID from DocumentModel.\n\t * @param variableNames Names of variables that were written at this line.\n\t * @returns The new checkpoint, or null if no variable names provided.\n\t */\n\tsnapshot(\n\t\tlineNumber: number,\n\t\tlineId: number,\n\t\tvariableNames: string[]\n\t): VMCheckpoint | null {\n\t\tif (variableNames.length === 0) return null;\n\n\t\tconst parent =\n\t\t\tthis.checkpoints.length > 0\n\t\t\t\t? this.checkpoints[this.checkpoints.length - 1]\n\t\t\t\t: null;\n\n\t\t// Create prototypal chain: new checkpoint inherits from parent\n\t\tconst variables: Record<string, Value> = Object.create(\n\t\t\tparent?.variables ?? null\n\t\t) as Record<string, Value>;\n\t\tconst functions: Record<string, UserFunctionDef> = Object.create(\n\t\t\tparent?.functions ?? null\n\t\t) as Record<string, UserFunctionDef>;\n\n\t\t// Record current VM values for the written names, routing each into\n\t\t// the right bag (a name is either a variable or a user-defined\n\t\t// function, never both; see VMCheckpoint.functions's doc comment for\n\t\t// why this dispatch is required, not optional).\n\t\tfor (const name of variableNames) {\n\t\t\tif (this.vm.hasUserFunction(name)) {\n\t\t\t\tconst fn = this.vm.getUserFunction(name);\n\t\t\t\tif (fn) functions[name] = fn;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst val = this.vm.getVar(name);\n\t\t\tif (val !== undefined) {\n\t\t\t\tvariables[name] = val;\n\t\t\t}\n\t\t}\n\n\t\tconst checkpoint: VMCheckpoint = {\n\t\t\tlineNumber,\n\t\t\tlineId,\n\t\t\tvariables,\n\t\t\tfunctions,\n\t\t\tparent,\n\t\t};\n\t\tthis.checkpoints.push(checkpoint);\n\t\treturn checkpoint;\n\t}\n\n\t// ── Restore ──────────────────────────────────────────────────────\n\n\t/**\n\t * Restore the VM to the state at or just after the given line number.\n\t *\n\t * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,\n\t * then replays all variable definitions from root → that checkpoint\n\t * into the VM via `setVar()`. The VM's stack is also reset.\n\t *\n\t * If no checkpoint exists at or before the target line, the VM is\n\t * fully reset (empty scope, empty stack).\n\t *\n\t * **Performance:** O(number of checkpoints × variables per checkpoint).\n\t * With prototypal inheritance, `Object.keys()` on each checkpoint\n\t * returns only the variables that were set at that checkpoint (not\n\t * inherited ones), so the total work is O(total variable definitions\n\t * in the document), which is < 100 for typical Obsidian documents.\n\t *\n\t * @param lineNumber Target 1-based line number. The VM will have the\n\t * state that existed AFTER evaluating lines up to `lineNumber`.\n\t */\n\trestoreTo(lineNumber: number): void {\n\t\tconst target = this.getNearestCheckpoint(lineNumber);\n\t\tif (!target) {\n\t\t\tthis.vm.reset();\n\t\t\treturn;\n\t\t}\n\n\t\t// Collect the checkpoint chain from root to target.\n\t\t// Walk parent links and reverse so root is first.\n\t\tconst chain: VMCheckpoint[] = [];\n\t\tlet current: VMCheckpoint | null = target;\n\t\twhile (current) {\n\t\t\tchain.unshift(current);\n\t\t\tcurrent = current.parent;\n\t\t}\n\n\t\tthis.vm.reset();\n\t\tfor (const cp of chain) {\n\t\t\t// Object.keys() returns only OWN enumerable properties\n\t\t\t// it does NOT include inherited properties from the prototype chain.\n\t\t\t// This means we only set variables that were defined/updated at this\n\t\t\t// specific checkpoint, not all variables from parent checkpoints.\n\t\t\tfor (const key of Object.keys(cp.variables)) {\n\t\t\t\tthis.vm.setVar(key, cp.variables[key]);\n\t\t\t}\n\t\t\t// Replay function definitions the same way, a later checkpoint's\n\t\t\t// redefinition of the same name naturally overwrites an earlier\n\t\t\t// one since the chain replays in root-to-target order.\n\t\t\tfor (const key of Object.keys(cp.functions)) {\n\t\t\t\tconst fn = cp.functions[key];\n\t\t\t\tthis.vm.defineUserFunction(fn.name, fn.params, fn.program);\n\t\t\t}\n\t\t}\n\t}\n\n\t// ── Queries ──────────────────────────────────────────────────────\n\n\t/**\n\t * Find the nearest checkpoint at or before the given line number.\n\t *\n\t * Uses linear scan (checkpoints are sorted by lineNumber and the list\n\t * is short, typically < 20 for Obsidian documents). Can be upgraded\n\t * to binary search if needed for documents with 1000+ variable defs.\n\t *\n\t * @returns The nearest checkpoint, or null if none exists before the line.\n\t */\n\tgetNearestCheckpoint(lineNumber: number): VMCheckpoint | null {\n\t\tlet result: VMCheckpoint | null = null;\n\t\tfor (const cp of this.checkpoints) {\n\t\t\tif (cp.lineNumber <= lineNumber) {\n\t\t\t\tresult = cp;\n\t\t\t} else {\n\t\t\t\tbreak; // checkpoints are sorted ascending\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Get a specific checkpoint by its line number.\n\t * @returns The checkpoint, or undefined if not found.\n\t */\n\tgetCheckpointAt(lineNumber: number): VMCheckpoint | undefined {\n\t\treturn this.checkpoints.find((cp) => cp.lineNumber === lineNumber);\n\t}\n\n\t/**\n\t * Get the entire checkpoint chain from root to the last checkpoint.\n\t * Useful for debugging and serialization.\n\t */\n\tgetAllCheckpoints(): readonly VMCheckpoint[] {\n\t\treturn this.checkpoints;\n\t}\n\n\t/**\n\t * Look up a variable's value through the checkpoint chain.\n\t *\n\t * Walks the prototype chain starting from the most recent checkpoint,\n\t * looking for the variable name as an own property. This is O(depth)\n\t * where depth is the number of checkpoints since the variable was\n\t * last set.\n\t *\n\t * **Note:** This queries the checkpointer's snapshot, not the VM.\n\t * The VM may have been modified since the last snapshot (e.g., by\n\t * Tier 2 execution of non-variable-def lines that don't create checkpoints).\n\t *\n\t * @returns The Value, or undefined if the variable was never set.\n\t */\n\tlookupVariable(name: string): Value | undefined {\n\t\tif (this.checkpoints.length === 0) return undefined;\n\n\t\tconst latest = this.checkpoints[this.checkpoints.length - 1];\n\t\tlet scope: Record<string, Value> | null = latest.variables;\n\t\twhile (scope) {\n\t\t\tif (Object.prototype.hasOwnProperty.call(scope, name)) {\n\t\t\t\treturn scope[name];\n\t\t\t}\n\t\t\tscope = Object.getPrototypeOf(scope) as Record<string, Value> | null;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// ── Lifecycle ────────────────────────────────────────────────────\n\n\t/**\n\t * Clear all checkpoints. The underlying VM is NOT reset, call\n\t * `vm.reset()` separately if needed.\n\t */\n\tclear(): void {\n\t\tthis.checkpoints = [];\n\t}\n\n\t/** Number of checkpoints stored. */\n\tget count(): number {\n\t\treturn this.checkpoints.length;\n\t}\n\n\t/** Returns true if no checkpoints have been created. */\n\tget isEmpty(): boolean {\n\t\treturn this.checkpoints.length === 0;\n\t}\n\n\t/** The associated VM instance. */\n\tget vmInstance(): VM {\n\t\treturn this.vm;\n\t}\n}\n"]}
+{"version":3,"sources":["../src/vm/VMCheckpoints.ts"],"names":[],"mappings":"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","file":"vm.cjs","sourcesContent":["import { Value } from \"@solve-js/vm/Value\";\nimport type { VM } from \"@solve-js/vm/OpRegistry\";\nimport type { UserFunctionDef } from \"@solve-js/parser/BytecodeBuilder\";\n\n// ── VMCheckpoint ────────────────────────────────────────────────────────\n\n/**\n * A point-in-time snapshot of VM variable state.\n *\n * Uses **prototypal inheritance** for memory efficiency: each checkpoint's\n * `variables` object has its parent checkpoint's `variables` as its\n * `__proto__`. This means a `getVar(\"x\")` lookup walks the prototype chain\n * until it finds `x`, and only variables that CHANGED at this checkpoint\n * consume heap space. Unchanged variables are inherited from the parent.\n *\n * ```text\n * Checkpoint 0 (root):  {}                        // empty scope\n * Checkpoint 1 (:x=5):  { x: 5 }    __proto__ → 0\n * Checkpoint 2 (:y=8):  { y: 8 }    __proto__ → 1\n * Checkpoint 3 (:x=3):  { x: 3 }    __proto__ → 2   // shadows x=5\n * ```\n *\n * To look up `x` at checkpoint 3: find own `x=3` → done.\n * To look up `y` at checkpoint 3: not own → walk proto to checkpoint 2 → `y=8`.\n * To look up `z` at checkpoint 3: not found anywhere → undefined.\n *\n * **Memory:** O(number of variable definitions) heap, independent of\n * document length. Typical Obsidian documents have < 100 variable defs,\n * so total checkpoint heap is < 10 KB.\n */\nexport interface VMCheckpoint {\n\t/** 1-based line number where this checkpoint was created. */\n\tlineNumber: number;\n\t/** Persistent line ID from DocumentModel. */\n\tlineId: number;\n\t/**\n\t * Variable name → Value at this checkpoint.\n\t * Own properties are variables set/updated at this line.\n\t * The prototype chain provides inherited variables from parent checkpoints.\n\t */\n\tvariables: Record<string, Value>;\n\t/**\n\t * User-defined-function name → definition at this checkpoint. SEPARATE\n\t * from `variables` above (not prototypally chained the same way\n\t * `restoreTo()` replays every checkpoint in the chain in order, so a\n\t * later redefinition of the same function name naturally overwrites an\n\t * earlier one during replay, without needing its own prototype walk).\n\t *\n\t * Without this field, a function definition's checkpoint entry would be\n\t * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every\n\t * written name, which returns `undefined` for a function name (function\n\t * defs live in `vm.userFunctions`, not the flat variable store), and a\n\t * `val !== undefined` guard silently skipped it. A scroll-triggered\n\t * `restoreTo()` would then reset the VM and replay only `variables`,\n\t * making a function defined above the new viewport vanish (calling it\n\t * would throw `UNDEFINED_FUNCTION`) even though the document still\n\t * shows its definition line as clean/cached.\n\t */\n\tfunctions: Record<string, UserFunctionDef>;\n\t/** Parent checkpoint (closer to document start), or null for root. */\n\tparent: VMCheckpoint | null;\n}\n\n// ── VMCheckpointer ──────────────────────────────────────────────────────\n\n/**\n * Manages VM state checkpoints for the three-tier evaluation strategy.\n *\n * **Checkpoint creation:** After a variable-definition line executes\n * (Tier 1 or Tier 3), `snapshot()` records the current values of the\n * written variables. The checkpoint is linked via prototypal inheritance\n * to the previous checkpoint, so only changed variables consume memory.\n *\n * **Checkpoint restoration:** Before evaluating a viewport whose start line\n * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all\n * variable definitions up to and including that line. This avoids\n * re-evaluating the entire document from line 1 on every scroll.\n *\n * **Thread safety:** Checkpoints are created synchronously on the main\n * thread during evaluation. They are immutable after creation (Value is\n * an immutable type), so no synchronization is needed.\n *\n * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`\n * to find the checkpoint just before the new viewport start, then call\n * `restoreTo()` to set up the VM before evaluating only the visible lines.\n * This is the key to O(visible lines) scrolling instead of O(document).\n */\nexport class VMCheckpointer {\n\t/** Ordered array of checkpoints (ascending lineNumber). */\n\tprivate checkpoints: VMCheckpoint[] = [];\n\t/** The VM instance whose variables are snapshotted/restored. */\n\tprivate vm: VM;\n\n\tconstructor(vm: VM) {\n\t\tthis.vm = vm;\n\t}\n\n\t// ── Snapshot ─────────────────────────────────────────────────────\n\n\t/**\n\t * Create a checkpoint at the current line, recording the VM values of\n\t * the specified variables.\n\t *\n\t * Uses prototypal inheritance: `Object.create(parent.variables)` so\n\t * that inherited variable lookups fall through to previous checkpoints\n\t * without copying all variables into each checkpoint.\n\t *\n\t * @param lineNumber 1-based line position.\n\t * @param lineId Persistent line ID from DocumentModel.\n\t * @param variableNames Names of variables that were written at this line.\n\t * @returns The new checkpoint, or null if no variable names provided.\n\t */\n\tsnapshot(\n\t\tlineNumber: number,\n\t\tlineId: number,\n\t\tvariableNames: string[]\n\t): VMCheckpoint | null {\n\t\tif (variableNames.length === 0) return null;\n\n\t\tconst parent =\n\t\t\tthis.checkpoints.length > 0\n\t\t\t\t? this.checkpoints[this.checkpoints.length - 1]\n\t\t\t\t: null;\n\n\t\t// Create prototypal chain: new checkpoint inherits from parent\n\t\tconst variables: Record<string, Value> = Object.create(\n\t\t\tparent?.variables ?? null\n\t\t) as Record<string, Value>;\n\t\tconst functions: Record<string, UserFunctionDef> = Object.create(\n\t\t\tparent?.functions ?? null\n\t\t) as Record<string, UserFunctionDef>;\n\n\t\t// Record current VM values for the written names, routing each into\n\t\t// the right bag (a name is either a variable or a user-defined\n\t\t// function, never both; see VMCheckpoint.functions's doc comment for\n\t\t// why this dispatch is required, not optional).\n\t\tfor (const name of variableNames) {\n\t\t\tif (this.vm.hasUserFunction(name)) {\n\t\t\t\tconst fn = this.vm.getUserFunction(name);\n\t\t\t\tif (fn) functions[name] = fn;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst val = this.vm.getVar(name);\n\t\t\tif (val !== undefined) {\n\t\t\t\tvariables[name] = val;\n\t\t\t}\n\t\t}\n\n\t\tconst checkpoint: VMCheckpoint = {\n\t\t\tlineNumber,\n\t\t\tlineId,\n\t\t\tvariables,\n\t\t\tfunctions,\n\t\t\tparent,\n\t\t};\n\t\tthis.checkpoints.push(checkpoint);\n\t\treturn checkpoint;\n\t}\n\n\t// ── Restore ──────────────────────────────────────────────────────\n\n\t/**\n\t * Restore the VM to the state at or just after the given line number.\n\t *\n\t * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,\n\t * then replays all variable definitions from root → that checkpoint\n\t * into the VM via `setVar()`. The VM's stack is also reset.\n\t *\n\t * If no checkpoint exists at or before the target line, the VM is\n\t * fully reset (empty scope, empty stack).\n\t *\n\t * **Performance:** O(number of checkpoints × variables per checkpoint).\n\t * With prototypal inheritance, `Object.keys()` on each checkpoint\n\t * returns only the variables that were set at that checkpoint (not\n\t * inherited ones), so the total work is O(total variable definitions\n\t * in the document), which is < 100 for typical Obsidian documents.\n\t *\n\t * @param lineNumber Target 1-based line number. The VM will have the\n\t * state that existed AFTER evaluating lines up to `lineNumber`.\n\t */\n\trestoreTo(lineNumber: number): void {\n\t\tconst target = this.getNearestCheckpoint(lineNumber);\n\t\tif (!target) {\n\t\t\tthis.vm.reset();\n\t\t\treturn;\n\t\t}\n\n\t\t// Collect the checkpoint chain from root to target.\n\t\t// Walk parent links and reverse so root is first.\n\t\tconst chain: VMCheckpoint[] = [];\n\t\tlet current: VMCheckpoint | null = target;\n\t\twhile (current) {\n\t\t\tchain.unshift(current);\n\t\t\tcurrent = current.parent;\n\t\t}\n\n\t\tthis.vm.reset();\n\t\tfor (const cp of chain) {\n\t\t\t// Object.keys() returns only OWN enumerable properties\n\t\t\t// it does NOT include inherited properties from the prototype chain.\n\t\t\t// This means we only set variables that were defined/updated at this\n\t\t\t// specific checkpoint, not all variables from parent checkpoints.\n\t\t\tfor (const key of Object.keys(cp.variables)) {\n\t\t\t\tthis.vm.setVar(key, cp.variables[key]);\n\t\t\t}\n\t\t\t// Replay function definitions the same way, a later checkpoint's\n\t\t\t// redefinition of the same name naturally overwrites an earlier\n\t\t\t// one since the chain replays in root-to-target order.\n\t\t\tfor (const key of Object.keys(cp.functions)) {\n\t\t\t\tconst fn = cp.functions[key];\n\t\t\t\tthis.vm.defineUserFunction(fn.name, fn.params, fn.program);\n\t\t\t}\n\t\t}\n\t}\n\n\t// ── Queries ──────────────────────────────────────────────────────\n\n\t/**\n\t * Find the nearest checkpoint at or before the given line number.\n\t *\n\t * Uses linear scan (checkpoints are sorted by lineNumber and the list\n\t * is short, typically < 20 for Obsidian documents). Can be upgraded\n\t * to binary search if needed for documents with 1000+ variable defs.\n\t *\n\t * @returns The nearest checkpoint, or null if none exists before the line.\n\t */\n\tgetNearestCheckpoint(lineNumber: number): VMCheckpoint | null {\n\t\tlet result: VMCheckpoint | null = null;\n\t\tfor (const cp of this.checkpoints) {\n\t\t\tif (cp.lineNumber <= lineNumber) {\n\t\t\t\tresult = cp;\n\t\t\t} else {\n\t\t\t\tbreak; // checkpoints are sorted ascending\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Get a specific checkpoint by its line number.\n\t * @returns The checkpoint, or undefined if not found.\n\t */\n\tgetCheckpointAt(lineNumber: number): VMCheckpoint | undefined {\n\t\treturn this.checkpoints.find((cp) => cp.lineNumber === lineNumber);\n\t}\n\n\t/**\n\t * Get the entire checkpoint chain from root to the last checkpoint.\n\t * Useful for debugging and serialization.\n\t */\n\tgetAllCheckpoints(): readonly VMCheckpoint[] {\n\t\treturn this.checkpoints;\n\t}\n\n\t/**\n\t * Look up a variable's value through the checkpoint chain.\n\t *\n\t * Walks the prototype chain starting from the most recent checkpoint,\n\t * looking for the variable name as an own property. This is O(depth)\n\t * where depth is the number of checkpoints since the variable was\n\t * last set.\n\t *\n\t * **Note:** This queries the checkpointer's snapshot, not the VM.\n\t * The VM may have been modified since the last snapshot (e.g., by\n\t * Tier 2 execution of non-variable-def lines that don't create checkpoints).\n\t *\n\t * @returns The Value, or undefined if the variable was never set.\n\t */\n\tlookupVariable(name: string): Value | undefined {\n\t\tif (this.checkpoints.length === 0) return undefined;\n\n\t\tconst latest = this.checkpoints[this.checkpoints.length - 1];\n\t\tlet scope: Record<string, Value> | null = latest.variables;\n\t\twhile (scope) {\n\t\t\tif (Object.prototype.hasOwnProperty.call(scope, name)) {\n\t\t\t\treturn scope[name];\n\t\t\t}\n\t\t\tscope = Object.getPrototypeOf(scope) as Record<string, Value> | null;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// ── Lifecycle ────────────────────────────────────────────────────\n\n\t/**\n\t * Clear all checkpoints. The underlying VM is NOT reset, call\n\t * `vm.reset()` separately if needed.\n\t */\n\tclear(): void {\n\t\tthis.checkpoints = [];\n\t}\n\n\t/** Number of checkpoints stored. */\n\tget count(): number {\n\t\treturn this.checkpoints.length;\n\t}\n\n\t/** Returns true if no checkpoints have been created. */\n\tget isEmpty(): boolean {\n\t\treturn this.checkpoints.length === 0;\n\t}\n\n\t/** The associated VM instance. */\n\tget vmInstance(): VM {\n\t\treturn this.vm;\n\t}\n}\n"]}

package/dist/vm.js

@@ -10,6 +10,7 @@ export { Value, ValueType, bigIntValue, colVectorValue, hexValue, matrixValue, n
 import './chunk-NH2O2AUR.js';
 import './chunk-4MG4XKO2.js';
 import './chunk-6RDSQURE.js';
+import './chunk-YLJ4XMA6.js';
 
 // src/vm/VMCheckpoints.ts
 var VMCheckpointer = class {

package/dist/vm.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/vm/VMCheckpoints.ts"],"names":[],"mappings":"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","file":"vm.js","sourcesContent":["import { Value } from \"@solve-js/vm/Value\";\nimport type { VM } from \"@solve-js/vm/OpRegistry\";\nimport type { UserFunctionDef } from \"@solve-js/parser/BytecodeBuilder\";\n\n// ── VMCheckpoint ────────────────────────────────────────────────────────\n\n/**\n * A point-in-time snapshot of VM variable state.\n *\n * Uses **prototypal inheritance** for memory efficiency: each checkpoint's\n * `variables` object has its parent checkpoint's `variables` as its\n * `__proto__`. This means a `getVar(\"x\")` lookup walks the prototype chain\n * until it finds `x`, and only variables that CHANGED at this checkpoint\n * consume heap space. Unchanged variables are inherited from the parent.\n *\n * ```text\n * Checkpoint 0 (root):  {}                        // empty scope\n * Checkpoint 1 (:x=5):  { x: 5 }    __proto__ → 0\n * Checkpoint 2 (:y=8):  { y: 8 }    __proto__ → 1\n * Checkpoint 3 (:x=3):  { x: 3 }    __proto__ → 2   // shadows x=5\n * ```\n *\n * To look up `x` at checkpoint 3: find own `x=3` → done.\n * To look up `y` at checkpoint 3: not own → walk proto to checkpoint 2 → `y=8`.\n * To look up `z` at checkpoint 3: not found anywhere → undefined.\n *\n * **Memory:** O(number of variable definitions) heap, independent of\n * document length. Typical Obsidian documents have < 100 variable defs,\n * so total checkpoint heap is < 10 KB.\n */\nexport interface VMCheckpoint {\n\t/** 1-based line number where this checkpoint was created. */\n\tlineNumber: number;\n\t/** Persistent line ID from DocumentModel. */\n\tlineId: number;\n\t/**\n\t * Variable name → Value at this checkpoint.\n\t * Own properties are variables set/updated at this line.\n\t * The prototype chain provides inherited variables from parent checkpoints.\n\t */\n\tvariables: Record<string, Value>;\n\t/**\n\t * User-defined-function name → definition at this checkpoint. SEPARATE\n\t * from `variables` above (not prototypally chained the same way\n\t * `restoreTo()` replays every checkpoint in the chain in order, so a\n\t * later redefinition of the same function name naturally overwrites an\n\t * earlier one during replay, without needing its own prototype walk).\n\t *\n\t * Without this field, a function definition's checkpoint entry would be\n\t * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every\n\t * written name, which returns `undefined` for a function name (function\n\t * defs live in `vm.userFunctions`, not the flat variable store), and a\n\t * `val !== undefined` guard silently skipped it. A scroll-triggered\n\t * `restoreTo()` would then reset the VM and replay only `variables`,\n\t * making a function defined above the new viewport vanish (calling it\n\t * would throw `UNDEFINED_FUNCTION`) even though the document still\n\t * shows its definition line as clean/cached.\n\t */\n\tfunctions: Record<string, UserFunctionDef>;\n\t/** Parent checkpoint (closer to document start), or null for root. */\n\tparent: VMCheckpoint | null;\n}\n\n// ── VMCheckpointer ──────────────────────────────────────────────────────\n\n/**\n * Manages VM state checkpoints for the three-tier evaluation strategy.\n *\n * **Checkpoint creation:** After a variable-definition line executes\n * (Tier 1 or Tier 3), `snapshot()` records the current values of the\n * written variables. The checkpoint is linked via prototypal inheritance\n * to the previous checkpoint, so only changed variables consume memory.\n *\n * **Checkpoint restoration:** Before evaluating a viewport whose start line\n * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all\n * variable definitions up to and including that line. This avoids\n * re-evaluating the entire document from line 1 on every scroll.\n *\n * **Thread safety:** Checkpoints are created synchronously on the main\n * thread during evaluation. They are immutable after creation (Value is\n * an immutable type), so no synchronization is needed.\n *\n * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`\n * to find the checkpoint just before the new viewport start, then call\n * `restoreTo()` to set up the VM before evaluating only the visible lines.\n * This is the key to O(visible lines) scrolling instead of O(document).\n */\nexport class VMCheckpointer {\n\t/** Ordered array of checkpoints (ascending lineNumber). */\n\tprivate checkpoints: VMCheckpoint[] = [];\n\t/** The VM instance whose variables are snapshotted/restored. */\n\tprivate vm: VM;\n\n\tconstructor(vm: VM) {\n\t\tthis.vm = vm;\n\t}\n\n\t// ── Snapshot ─────────────────────────────────────────────────────\n\n\t/**\n\t * Create a checkpoint at the current line, recording the VM values of\n\t * the specified variables.\n\t *\n\t * Uses prototypal inheritance: `Object.create(parent.variables)` so\n\t * that inherited variable lookups fall through to previous checkpoints\n\t * without copying all variables into each checkpoint.\n\t *\n\t * @param lineNumber 1-based line position.\n\t * @param lineId Persistent line ID from DocumentModel.\n\t * @param variableNames Names of variables that were written at this line.\n\t * @returns The new checkpoint, or null if no variable names provided.\n\t */\n\tsnapshot(\n\t\tlineNumber: number,\n\t\tlineId: number,\n\t\tvariableNames: string[]\n\t): VMCheckpoint | null {\n\t\tif (variableNames.length === 0) return null;\n\n\t\tconst parent =\n\t\t\tthis.checkpoints.length > 0\n\t\t\t\t? this.checkpoints[this.checkpoints.length - 1]\n\t\t\t\t: null;\n\n\t\t// Create prototypal chain: new checkpoint inherits from parent\n\t\tconst variables: Record<string, Value> = Object.create(\n\t\t\tparent?.variables ?? null\n\t\t) as Record<string, Value>;\n\t\tconst functions: Record<string, UserFunctionDef> = Object.create(\n\t\t\tparent?.functions ?? null\n\t\t) as Record<string, UserFunctionDef>;\n\n\t\t// Record current VM values for the written names, routing each into\n\t\t// the right bag (a name is either a variable or a user-defined\n\t\t// function, never both; see VMCheckpoint.functions's doc comment for\n\t\t// why this dispatch is required, not optional).\n\t\tfor (const name of variableNames) {\n\t\t\tif (this.vm.hasUserFunction(name)) {\n\t\t\t\tconst fn = this.vm.getUserFunction(name);\n\t\t\t\tif (fn) functions[name] = fn;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst val = this.vm.getVar(name);\n\t\t\tif (val !== undefined) {\n\t\t\t\tvariables[name] = val;\n\t\t\t}\n\t\t}\n\n\t\tconst checkpoint: VMCheckpoint = {\n\t\t\tlineNumber,\n\t\t\tlineId,\n\t\t\tvariables,\n\t\t\tfunctions,\n\t\t\tparent,\n\t\t};\n\t\tthis.checkpoints.push(checkpoint);\n\t\treturn checkpoint;\n\t}\n\n\t// ── Restore ──────────────────────────────────────────────────────\n\n\t/**\n\t * Restore the VM to the state at or just after the given line number.\n\t *\n\t * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,\n\t * then replays all variable definitions from root → that checkpoint\n\t * into the VM via `setVar()`. The VM's stack is also reset.\n\t *\n\t * If no checkpoint exists at or before the target line, the VM is\n\t * fully reset (empty scope, empty stack).\n\t *\n\t * **Performance:** O(number of checkpoints × variables per checkpoint).\n\t * With prototypal inheritance, `Object.keys()` on each checkpoint\n\t * returns only the variables that were set at that checkpoint (not\n\t * inherited ones), so the total work is O(total variable definitions\n\t * in the document), which is < 100 for typical Obsidian documents.\n\t *\n\t * @param lineNumber Target 1-based line number. The VM will have the\n\t * state that existed AFTER evaluating lines up to `lineNumber`.\n\t */\n\trestoreTo(lineNumber: number): void {\n\t\tconst target = this.getNearestCheckpoint(lineNumber);\n\t\tif (!target) {\n\t\t\tthis.vm.reset();\n\t\t\treturn;\n\t\t}\n\n\t\t// Collect the checkpoint chain from root to target.\n\t\t// Walk parent links and reverse so root is first.\n\t\tconst chain: VMCheckpoint[] = [];\n\t\tlet current: VMCheckpoint | null = target;\n\t\twhile (current) {\n\t\t\tchain.unshift(current);\n\t\t\tcurrent = current.parent;\n\t\t}\n\n\t\tthis.vm.reset();\n\t\tfor (const cp of chain) {\n\t\t\t// Object.keys() returns only OWN enumerable properties\n\t\t\t// it does NOT include inherited properties from the prototype chain.\n\t\t\t// This means we only set variables that were defined/updated at this\n\t\t\t// specific checkpoint, not all variables from parent checkpoints.\n\t\t\tfor (const key of Object.keys(cp.variables)) {\n\t\t\t\tthis.vm.setVar(key, cp.variables[key]);\n\t\t\t}\n\t\t\t// Replay function definitions the same way, a later checkpoint's\n\t\t\t// redefinition of the same name naturally overwrites an earlier\n\t\t\t// one since the chain replays in root-to-target order.\n\t\t\tfor (const key of Object.keys(cp.functions)) {\n\t\t\t\tconst fn = cp.functions[key];\n\t\t\t\tthis.vm.defineUserFunction(fn.name, fn.params, fn.program);\n\t\t\t}\n\t\t}\n\t}\n\n\t// ── Queries ──────────────────────────────────────────────────────\n\n\t/**\n\t * Find the nearest checkpoint at or before the given line number.\n\t *\n\t * Uses linear scan (checkpoints are sorted by lineNumber and the list\n\t * is short, typically < 20 for Obsidian documents). Can be upgraded\n\t * to binary search if needed for documents with 1000+ variable defs.\n\t *\n\t * @returns The nearest checkpoint, or null if none exists before the line.\n\t */\n\tgetNearestCheckpoint(lineNumber: number): VMCheckpoint | null {\n\t\tlet result: VMCheckpoint | null = null;\n\t\tfor (const cp of this.checkpoints) {\n\t\t\tif (cp.lineNumber <= lineNumber) {\n\t\t\t\tresult = cp;\n\t\t\t} else {\n\t\t\t\tbreak; // checkpoints are sorted ascending\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Get a specific checkpoint by its line number.\n\t * @returns The checkpoint, or undefined if not found.\n\t */\n\tgetCheckpointAt(lineNumber: number): VMCheckpoint | undefined {\n\t\treturn this.checkpoints.find((cp) => cp.lineNumber === lineNumber);\n\t}\n\n\t/**\n\t * Get the entire checkpoint chain from root to the last checkpoint.\n\t * Useful for debugging and serialization.\n\t */\n\tgetAllCheckpoints(): readonly VMCheckpoint[] {\n\t\treturn this.checkpoints;\n\t}\n\n\t/**\n\t * Look up a variable's value through the checkpoint chain.\n\t *\n\t * Walks the prototype chain starting from the most recent checkpoint,\n\t * looking for the variable name as an own property. This is O(depth)\n\t * where depth is the number of checkpoints since the variable was\n\t * last set.\n\t *\n\t * **Note:** This queries the checkpointer's snapshot, not the VM.\n\t * The VM may have been modified since the last snapshot (e.g., by\n\t * Tier 2 execution of non-variable-def lines that don't create checkpoints).\n\t *\n\t * @returns The Value, or undefined if the variable was never set.\n\t */\n\tlookupVariable(name: string): Value | undefined {\n\t\tif (this.checkpoints.length === 0) return undefined;\n\n\t\tconst latest = this.checkpoints[this.checkpoints.length - 1];\n\t\tlet scope: Record<string, Value> | null = latest.variables;\n\t\twhile (scope) {\n\t\t\tif (Object.prototype.hasOwnProperty.call(scope, name)) {\n\t\t\t\treturn scope[name];\n\t\t\t}\n\t\t\tscope = Object.getPrototypeOf(scope) as Record<string, Value> | null;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// ── Lifecycle ────────────────────────────────────────────────────\n\n\t/**\n\t * Clear all checkpoints. The underlying VM is NOT reset, call\n\t * `vm.reset()` separately if needed.\n\t */\n\tclear(): void {\n\t\tthis.checkpoints = [];\n\t}\n\n\t/** Number of checkpoints stored. */\n\tget count(): number {\n\t\treturn this.checkpoints.length;\n\t}\n\n\t/** Returns true if no checkpoints have been created. */\n\tget isEmpty(): boolean {\n\t\treturn this.checkpoints.length === 0;\n\t}\n\n\t/** The associated VM instance. */\n\tget vmInstance(): VM {\n\t\treturn this.vm;\n\t}\n}\n"]}
+{"version":3,"sources":["../src/vm/VMCheckpoints.ts"],"names":[],"mappings":"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","file":"vm.js","sourcesContent":["import { Value } from \"@solve-js/vm/Value\";\nimport type { VM } from \"@solve-js/vm/OpRegistry\";\nimport type { UserFunctionDef } from \"@solve-js/parser/BytecodeBuilder\";\n\n// ── VMCheckpoint ────────────────────────────────────────────────────────\n\n/**\n * A point-in-time snapshot of VM variable state.\n *\n * Uses **prototypal inheritance** for memory efficiency: each checkpoint's\n * `variables` object has its parent checkpoint's `variables` as its\n * `__proto__`. This means a `getVar(\"x\")` lookup walks the prototype chain\n * until it finds `x`, and only variables that CHANGED at this checkpoint\n * consume heap space. Unchanged variables are inherited from the parent.\n *\n * ```text\n * Checkpoint 0 (root):  {}                        // empty scope\n * Checkpoint 1 (:x=5):  { x: 5 }    __proto__ → 0\n * Checkpoint 2 (:y=8):  { y: 8 }    __proto__ → 1\n * Checkpoint 3 (:x=3):  { x: 3 }    __proto__ → 2   // shadows x=5\n * ```\n *\n * To look up `x` at checkpoint 3: find own `x=3` → done.\n * To look up `y` at checkpoint 3: not own → walk proto to checkpoint 2 → `y=8`.\n * To look up `z` at checkpoint 3: not found anywhere → undefined.\n *\n * **Memory:** O(number of variable definitions) heap, independent of\n * document length. Typical Obsidian documents have < 100 variable defs,\n * so total checkpoint heap is < 10 KB.\n */\nexport interface VMCheckpoint {\n\t/** 1-based line number where this checkpoint was created. */\n\tlineNumber: number;\n\t/** Persistent line ID from DocumentModel. */\n\tlineId: number;\n\t/**\n\t * Variable name → Value at this checkpoint.\n\t * Own properties are variables set/updated at this line.\n\t * The prototype chain provides inherited variables from parent checkpoints.\n\t */\n\tvariables: Record<string, Value>;\n\t/**\n\t * User-defined-function name → definition at this checkpoint. SEPARATE\n\t * from `variables` above (not prototypally chained the same way\n\t * `restoreTo()` replays every checkpoint in the chain in order, so a\n\t * later redefinition of the same function name naturally overwrites an\n\t * earlier one during replay, without needing its own prototype walk).\n\t *\n\t * Without this field, a function definition's checkpoint entry would be\n\t * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every\n\t * written name, which returns `undefined` for a function name (function\n\t * defs live in `vm.userFunctions`, not the flat variable store), and a\n\t * `val !== undefined` guard silently skipped it. A scroll-triggered\n\t * `restoreTo()` would then reset the VM and replay only `variables`,\n\t * making a function defined above the new viewport vanish (calling it\n\t * would throw `UNDEFINED_FUNCTION`) even though the document still\n\t * shows its definition line as clean/cached.\n\t */\n\tfunctions: Record<string, UserFunctionDef>;\n\t/** Parent checkpoint (closer to document start), or null for root. */\n\tparent: VMCheckpoint | null;\n}\n\n// ── VMCheckpointer ──────────────────────────────────────────────────────\n\n/**\n * Manages VM state checkpoints for the three-tier evaluation strategy.\n *\n * **Checkpoint creation:** After a variable-definition line executes\n * (Tier 1 or Tier 3), `snapshot()` records the current values of the\n * written variables. The checkpoint is linked via prototypal inheritance\n * to the previous checkpoint, so only changed variables consume memory.\n *\n * **Checkpoint restoration:** Before evaluating a viewport whose start line\n * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all\n * variable definitions up to and including that line. This avoids\n * re-evaluating the entire document from line 1 on every scroll.\n *\n * **Thread safety:** Checkpoints are created synchronously on the main\n * thread during evaluation. They are immutable after creation (Value is\n * an immutable type), so no synchronization is needed.\n *\n * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`\n * to find the checkpoint just before the new viewport start, then call\n * `restoreTo()` to set up the VM before evaluating only the visible lines.\n * This is the key to O(visible lines) scrolling instead of O(document).\n */\nexport class VMCheckpointer {\n\t/** Ordered array of checkpoints (ascending lineNumber). */\n\tprivate checkpoints: VMCheckpoint[] = [];\n\t/** The VM instance whose variables are snapshotted/restored. */\n\tprivate vm: VM;\n\n\tconstructor(vm: VM) {\n\t\tthis.vm = vm;\n\t}\n\n\t// ── Snapshot ─────────────────────────────────────────────────────\n\n\t/**\n\t * Create a checkpoint at the current line, recording the VM values of\n\t * the specified variables.\n\t *\n\t * Uses prototypal inheritance: `Object.create(parent.variables)` so\n\t * that inherited variable lookups fall through to previous checkpoints\n\t * without copying all variables into each checkpoint.\n\t *\n\t * @param lineNumber 1-based line position.\n\t * @param lineId Persistent line ID from DocumentModel.\n\t * @param variableNames Names of variables that were written at this line.\n\t * @returns The new checkpoint, or null if no variable names provided.\n\t */\n\tsnapshot(\n\t\tlineNumber: number,\n\t\tlineId: number,\n\t\tvariableNames: string[]\n\t): VMCheckpoint | null {\n\t\tif (variableNames.length === 0) return null;\n\n\t\tconst parent =\n\t\t\tthis.checkpoints.length > 0\n\t\t\t\t? this.checkpoints[this.checkpoints.length - 1]\n\t\t\t\t: null;\n\n\t\t// Create prototypal chain: new checkpoint inherits from parent\n\t\tconst variables: Record<string, Value> = Object.create(\n\t\t\tparent?.variables ?? null\n\t\t) as Record<string, Value>;\n\t\tconst functions: Record<string, UserFunctionDef> = Object.create(\n\t\t\tparent?.functions ?? null\n\t\t) as Record<string, UserFunctionDef>;\n\n\t\t// Record current VM values for the written names, routing each into\n\t\t// the right bag (a name is either a variable or a user-defined\n\t\t// function, never both; see VMCheckpoint.functions's doc comment for\n\t\t// why this dispatch is required, not optional).\n\t\tfor (const name of variableNames) {\n\t\t\tif (this.vm.hasUserFunction(name)) {\n\t\t\t\tconst fn = this.vm.getUserFunction(name);\n\t\t\t\tif (fn) functions[name] = fn;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst val = this.vm.getVar(name);\n\t\t\tif (val !== undefined) {\n\t\t\t\tvariables[name] = val;\n\t\t\t}\n\t\t}\n\n\t\tconst checkpoint: VMCheckpoint = {\n\t\t\tlineNumber,\n\t\t\tlineId,\n\t\t\tvariables,\n\t\t\tfunctions,\n\t\t\tparent,\n\t\t};\n\t\tthis.checkpoints.push(checkpoint);\n\t\treturn checkpoint;\n\t}\n\n\t// ── Restore ──────────────────────────────────────────────────────\n\n\t/**\n\t * Restore the VM to the state at or just after the given line number.\n\t *\n\t * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,\n\t * then replays all variable definitions from root → that checkpoint\n\t * into the VM via `setVar()`. The VM's stack is also reset.\n\t *\n\t * If no checkpoint exists at or before the target line, the VM is\n\t * fully reset (empty scope, empty stack).\n\t *\n\t * **Performance:** O(number of checkpoints × variables per checkpoint).\n\t * With prototypal inheritance, `Object.keys()` on each checkpoint\n\t * returns only the variables that were set at that checkpoint (not\n\t * inherited ones), so the total work is O(total variable definitions\n\t * in the document), which is < 100 for typical Obsidian documents.\n\t *\n\t * @param lineNumber Target 1-based line number. The VM will have the\n\t * state that existed AFTER evaluating lines up to `lineNumber`.\n\t */\n\trestoreTo(lineNumber: number): void {\n\t\tconst target = this.getNearestCheckpoint(lineNumber);\n\t\tif (!target) {\n\t\t\tthis.vm.reset();\n\t\t\treturn;\n\t\t}\n\n\t\t// Collect the checkpoint chain from root to target.\n\t\t// Walk parent links and reverse so root is first.\n\t\tconst chain: VMCheckpoint[] = [];\n\t\tlet current: VMCheckpoint | null = target;\n\t\twhile (current) {\n\t\t\tchain.unshift(current);\n\t\t\tcurrent = current.parent;\n\t\t}\n\n\t\tthis.vm.reset();\n\t\tfor (const cp of chain) {\n\t\t\t// Object.keys() returns only OWN enumerable properties\n\t\t\t// it does NOT include inherited properties from the prototype chain.\n\t\t\t// This means we only set variables that were defined/updated at this\n\t\t\t// specific checkpoint, not all variables from parent checkpoints.\n\t\t\tfor (const key of Object.keys(cp.variables)) {\n\t\t\t\tthis.vm.setVar(key, cp.variables[key]);\n\t\t\t}\n\t\t\t// Replay function definitions the same way, a later checkpoint's\n\t\t\t// redefinition of the same name naturally overwrites an earlier\n\t\t\t// one since the chain replays in root-to-target order.\n\t\t\tfor (const key of Object.keys(cp.functions)) {\n\t\t\t\tconst fn = cp.functions[key];\n\t\t\t\tthis.vm.defineUserFunction(fn.name, fn.params, fn.program);\n\t\t\t}\n\t\t}\n\t}\n\n\t// ── Queries ──────────────────────────────────────────────────────\n\n\t/**\n\t * Find the nearest checkpoint at or before the given line number.\n\t *\n\t * Uses linear scan (checkpoints are sorted by lineNumber and the list\n\t * is short, typically < 20 for Obsidian documents). Can be upgraded\n\t * to binary search if needed for documents with 1000+ variable defs.\n\t *\n\t * @returns The nearest checkpoint, or null if none exists before the line.\n\t */\n\tgetNearestCheckpoint(lineNumber: number): VMCheckpoint | null {\n\t\tlet result: VMCheckpoint | null = null;\n\t\tfor (const cp of this.checkpoints) {\n\t\t\tif (cp.lineNumber <= lineNumber) {\n\t\t\t\tresult = cp;\n\t\t\t} else {\n\t\t\t\tbreak; // checkpoints are sorted ascending\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Get a specific checkpoint by its line number.\n\t * @returns The checkpoint, or undefined if not found.\n\t */\n\tgetCheckpointAt(lineNumber: number): VMCheckpoint | undefined {\n\t\treturn this.checkpoints.find((cp) => cp.lineNumber === lineNumber);\n\t}\n\n\t/**\n\t * Get the entire checkpoint chain from root to the last checkpoint.\n\t * Useful for debugging and serialization.\n\t */\n\tgetAllCheckpoints(): readonly VMCheckpoint[] {\n\t\treturn this.checkpoints;\n\t}\n\n\t/**\n\t * Look up a variable's value through the checkpoint chain.\n\t *\n\t * Walks the prototype chain starting from the most recent checkpoint,\n\t * looking for the variable name as an own property. This is O(depth)\n\t * where depth is the number of checkpoints since the variable was\n\t * last set.\n\t *\n\t * **Note:** This queries the checkpointer's snapshot, not the VM.\n\t * The VM may have been modified since the last snapshot (e.g., by\n\t * Tier 2 execution of non-variable-def lines that don't create checkpoints).\n\t *\n\t * @returns The Value, or undefined if the variable was never set.\n\t */\n\tlookupVariable(name: string): Value | undefined {\n\t\tif (this.checkpoints.length === 0) return undefined;\n\n\t\tconst latest = this.checkpoints[this.checkpoints.length - 1];\n\t\tlet scope: Record<string, Value> | null = latest.variables;\n\t\twhile (scope) {\n\t\t\tif (Object.prototype.hasOwnProperty.call(scope, name)) {\n\t\t\t\treturn scope[name];\n\t\t\t}\n\t\t\tscope = Object.getPrototypeOf(scope) as Record<string, Value> | null;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// ── Lifecycle ────────────────────────────────────────────────────\n\n\t/**\n\t * Clear all checkpoints. The underlying VM is NOT reset, call\n\t * `vm.reset()` separately if needed.\n\t */\n\tclear(): void {\n\t\tthis.checkpoints = [];\n\t}\n\n\t/** Number of checkpoints stored. */\n\tget count(): number {\n\t\treturn this.checkpoints.length;\n\t}\n\n\t/** Returns true if no checkpoints have been created. */\n\tget isEmpty(): boolean {\n\t\treturn this.checkpoints.length === 0;\n\t}\n\n\t/** The associated VM instance. */\n\tget vmInstance(): VM {\n\t\treturn this.vm;\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solve-engine",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "description": "The expression evaluation engine behind Solve — lexer, parser, bytecode VM, and an extensible package system.",
   "keywords": [
     "expression-evaluator",
@@ -208,9 +208,7 @@
     "typecheck:tsc": "tsc --noEmit --skipLibCheck"
   },
   "dependencies": {
-    "@tanstack/query-core": "^5.100.10",
-    "semver": "^7.6.0",
-    "tslib": "^2.6.1"
+    "@tanstack/query-core": "^5.100.10"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -218,9 +216,11 @@
     "@types/semver": "^7.5.0",
     "convert": "^7.0.0",
     "jest": "^30.4.2",
+    "semver": "^7.6.0",
     "ts-jest": "^29.4.12",
     "tsup": "8.5.1",
     "typescript": "5.9.3"
   },
+  "//sideEffects": "Load-bearing claim, not boilerplate. tsup's splitting emits bare chunk imports at the top of dist/index.js, and this field tells Rollup, webpack and Vite they may delete them, which esbuild reports as [ignored-bare-import] once per import during `npm run size`. The engine does have module-level work to lose: registerAllTokenTypes(), _PrecedenceParser.BP_TABLE and its cached token ids, and several process-wide registries. It is safe because every chunk doing that work is also imported for its bindings somewhere, so no bundler can drop it. That is a property of how tsup currently splits the code rather than a design guarantee, so `npm run smoke:bundled` (scripts/check-tree-shaking.mjs) proves it on every run of `npm run verify` instead of assuming it, and its header explains the two fixes if it ever stops holding.",
   "sideEffects": false
 }

package/dist/NormalizerRule-BrVoVjmP.d.cts

@@ -1,163 +0,0 @@
-import { T as Token } from './Token-0jpvUdPY.cjs';
-
-/**
- * NormalizerRule, pluggable token normalization rule for the
- * TokenNormalizer post-lexer pass.
- *
- * ## Purpose
- * After the ExpressionLexer produces raw tokens (numbers, identifiers,
- * operators, etc.), the TokenNormalizer applies domain-specific rules
- * to transform the token stream before parsing. This keeps the lexer
- * focused on single-token production and moves multi-token pattern
- * matching into a dedicated normalization layer.
- *
- * ## How rules work
- * Rules are applied in priority order (highest first). At each token
- * position, the normalizer tries every rule in priority order until one
- * matches. Matched tokens are consumed and replaced; unmatched tokens
- * pass through unchanged.
- *
- * ## What rules can do
- * - **Phrase fusion**: Merge consecutive words into compound tokens
- *   (e.g., `"to" "the" "power" "of"` → `CARET`)
- * - **Implicit operators**: Insert missing operators between tokens
- *   (e.g., `NUMBER IDENT` → `NUMBER STAR IDENT`)
- * - **Domain transformations**: Coalesce item names, currency pairs, etc.
- *
- * ## Why a separate file?
- * This is a duplicate-free copy of the interface defined in
- * TokenNormalizer.ts. Storing it in a separate file avoids circular
- * imports, TokenNormalizer imports NormalizerRule, and rule factories
- * import TokenNormalizer's `createFusedToken`.
- *
- * @module NormalizerRule
- */
-
-/**
- * Result of a successful rule match attempt against the token stream.
- *
- * When a {@link NormalizerRule.match} function finds a pattern at the
- * current position, it returns a NormalizerMatch describing how many
- * tokens to consume and what to replace them with.
- *
- * @example
- * ```ts
- * // The phrase "to the power of" (5 tokens) becomes a single CARET token
- * const match: NormalizerMatch = {
- *   consumed: 5,
- *   replacement: [caretToken],
- * };
- * ```
- */
-interface NormalizerMatch {
-    /**
-     * Number of tokens consumed from the stream at the match position.
-     * Must be ≥ 1, a match always advances the cursor.
-     */
-    consumed: number;
-    /**
-     * Replacement tokens to insert at the match position.
-     * May be empty (deletion), a single token (fusion), or multiple
-     * tokens (expansion/splitting).
-     */
-    replacement: Token[];
-    /**
-     * Human-readable rule name for diagnostic fusion tracking.
-     * When set, the normalizer uses this instead of the rule's `name`
-     * in {@link TokenFusion} records. Used by {@link PhraseTrie} to
-     * report which specific phrase matched (e.g., "phrase:to the power of").
-     */
-    ruleName?: string;
-}
-/**
- * A pluggable normalization rule registered with the TokenNormalizer.
- *
- * Each rule has a {@link name}, {@link priority}, and {@link match} function.
- * The match function receives the current token stream and a position,
- * and returns a {@link NormalizerMatch} on success or `null` on failure.
- *
- * ## Priority ordering
- * Higher priority rules are tried first at each position. This allows
- * long phrases (priority 100, e.g. "to the power of") to match before
- * shorter fragments (priority 80, e.g. "power of").
- *
- * ## Match contract
- * - Must be pure (no side effects, no mutation of input tokens)
- * - Must return `null` for any position that doesn't match
- * - Consumed tokens must be consecutive starting at `pos`
- * - Replacement tokens must be valid for downstream parsing
- *
- * @example
- * ```ts
- * // A phrase fusion rule that converts "to the power of" into CARET
- * const phraseRule: NormalizerRule = {
- *   name: 'phrase:to the power of',
- *   priority: 100,
- *   match: (tokens, pos) => {
- *     if (pos + 4 > tokens.length) return null;
- *     const phrase = tokens.slice(pos, pos + 5)
- *       .map(t => t.value.toLowerCase()).join(' ');
- *     if (phrase === 'to the power of') {
- *       return {
- *         consumed: 5,
- *         replacement: [createFusedToken('CARET', 'to the power of', tokens.slice(pos, pos + 5))],
- *       };
- *     }
- *     return null;
- *   },
- * };
- * ```
- */
-interface NormalizerRule {
-    /**
-     * Human-readable name for debugging and diagnostic display.
-     * Convention: `"category:description"`, e.g. `"phrase:to the power of"`.
-     */
-    readonly name: string;
-    /**
-     * Priority for ordering rules. Higher values are tried first.
-     * Recommended ranges:
-     * - 100: Long multi-word phrase fusion (e.g., "to the power of")
-     * - 80:  Short phrase fusion (e.g., "power of", "times by")
-     * - 50:  Implicit operator insertion (e.g., implicit multiply)
-     * - 20:  Domain-specific transformations
-     */
-    readonly priority: number;
-    /**
-     * Attempt to match a pattern starting at position `pos` in the token stream.
-     *
-     * @param tokens - The current token stream (may be partially normalized from prior passes)
-     * @param pos    - The current position to attempt matching from
-     * @returns A {@link NormalizerMatch} if the pattern is found, or `null` if no match
-     */
-    match(tokens: Token[], pos: number): NormalizerMatch | null;
-}
-/**
- * Record of a token fusion event performed by the normalizer.
- *
- * When a rule merges multiple source tokens into fewer replacement tokens,
- * the normalizer fires a {@link NormalizerOptions.onFusion | fusion callback}
- * with this record. The playground uses these records to render the
- * fusion detail table showing exactly which tokens were merged and by
- * which rule.
- *
- * @example
- * ```ts
- * // "to" "the" "power" "of" fused into CARET "^"
- * const fusion: TokenFusion = {
- *   rule: "phrase:to the power of",
- *   sourceTokens: [toToken, theToken, powerToken, ofToken],
- *   fusedToken: caretToken,
- * };
- * ```
- */
-interface TokenFusion {
-    /** The name of the rule that triggered this fusion (e.g., "phrase:to the power of") */
-    rule: string;
-    /** The original tokens before fusion, always ≥ 2 tokens */
-    sourceTokens: Token[];
-    /** The resulting fused token with its new type and combined value */
-    fusedToken: Token;
-}
-
-export type { NormalizerRule as N, TokenFusion as T, NormalizerMatch as a };

package/dist/NormalizerRule-CEjf1FyD.d.ts

@@ -1,163 +0,0 @@
-import { T as Token } from './Token-0jpvUdPY.js';
-
-/**
- * NormalizerRule, pluggable token normalization rule for the
- * TokenNormalizer post-lexer pass.
- *
- * ## Purpose
- * After the ExpressionLexer produces raw tokens (numbers, identifiers,
- * operators, etc.), the TokenNormalizer applies domain-specific rules
- * to transform the token stream before parsing. This keeps the lexer
- * focused on single-token production and moves multi-token pattern
- * matching into a dedicated normalization layer.
- *
- * ## How rules work
- * Rules are applied in priority order (highest first). At each token
- * position, the normalizer tries every rule in priority order until one
- * matches. Matched tokens are consumed and replaced; unmatched tokens
- * pass through unchanged.
- *
- * ## What rules can do
- * - **Phrase fusion**: Merge consecutive words into compound tokens
- *   (e.g., `"to" "the" "power" "of"` → `CARET`)
- * - **Implicit operators**: Insert missing operators between tokens
- *   (e.g., `NUMBER IDENT` → `NUMBER STAR IDENT`)
- * - **Domain transformations**: Coalesce item names, currency pairs, etc.
- *
- * ## Why a separate file?
- * This is a duplicate-free copy of the interface defined in
- * TokenNormalizer.ts. Storing it in a separate file avoids circular
- * imports, TokenNormalizer imports NormalizerRule, and rule factories
- * import TokenNormalizer's `createFusedToken`.
- *
- * @module NormalizerRule
- */
-
-/**
- * Result of a successful rule match attempt against the token stream.
- *
- * When a {@link NormalizerRule.match} function finds a pattern at the
- * current position, it returns a NormalizerMatch describing how many
- * tokens to consume and what to replace them with.
- *
- * @example
- * ```ts
- * // The phrase "to the power of" (5 tokens) becomes a single CARET token
- * const match: NormalizerMatch = {
- *   consumed: 5,
- *   replacement: [caretToken],
- * };
- * ```
- */
-interface NormalizerMatch {
-    /**
-     * Number of tokens consumed from the stream at the match position.
-     * Must be ≥ 1, a match always advances the cursor.
-     */
-    consumed: number;
-    /**
-     * Replacement tokens to insert at the match position.
-     * May be empty (deletion), a single token (fusion), or multiple
-     * tokens (expansion/splitting).
-     */
-    replacement: Token[];
-    /**
-     * Human-readable rule name for diagnostic fusion tracking.
-     * When set, the normalizer uses this instead of the rule's `name`
-     * in {@link TokenFusion} records. Used by {@link PhraseTrie} to
-     * report which specific phrase matched (e.g., "phrase:to the power of").
-     */
-    ruleName?: string;
-}
-/**
- * A pluggable normalization rule registered with the TokenNormalizer.
- *
- * Each rule has a {@link name}, {@link priority}, and {@link match} function.
- * The match function receives the current token stream and a position,
- * and returns a {@link NormalizerMatch} on success or `null` on failure.
- *
- * ## Priority ordering
- * Higher priority rules are tried first at each position. This allows
- * long phrases (priority 100, e.g. "to the power of") to match before
- * shorter fragments (priority 80, e.g. "power of").
- *
- * ## Match contract
- * - Must be pure (no side effects, no mutation of input tokens)
- * - Must return `null` for any position that doesn't match
- * - Consumed tokens must be consecutive starting at `pos`
- * - Replacement tokens must be valid for downstream parsing
- *
- * @example
- * ```ts
- * // A phrase fusion rule that converts "to the power of" into CARET
- * const phraseRule: NormalizerRule = {
- *   name: 'phrase:to the power of',
- *   priority: 100,
- *   match: (tokens, pos) => {
- *     if (pos + 4 > tokens.length) return null;
- *     const phrase = tokens.slice(pos, pos + 5)
- *       .map(t => t.value.toLowerCase()).join(' ');
- *     if (phrase === 'to the power of') {
- *       return {
- *         consumed: 5,
- *         replacement: [createFusedToken('CARET', 'to the power of', tokens.slice(pos, pos + 5))],
- *       };
- *     }
- *     return null;
- *   },
- * };
- * ```
- */
-interface NormalizerRule {
-    /**
-     * Human-readable name for debugging and diagnostic display.
-     * Convention: `"category:description"`, e.g. `"phrase:to the power of"`.
-     */
-    readonly name: string;
-    /**
-     * Priority for ordering rules. Higher values are tried first.
-     * Recommended ranges:
-     * - 100: Long multi-word phrase fusion (e.g., "to the power of")
-     * - 80:  Short phrase fusion (e.g., "power of", "times by")
-     * - 50:  Implicit operator insertion (e.g., implicit multiply)
-     * - 20:  Domain-specific transformations
-     */
-    readonly priority: number;
-    /**
-     * Attempt to match a pattern starting at position `pos` in the token stream.
-     *
-     * @param tokens - The current token stream (may be partially normalized from prior passes)
-     * @param pos    - The current position to attempt matching from
-     * @returns A {@link NormalizerMatch} if the pattern is found, or `null` if no match
-     */
-    match(tokens: Token[], pos: number): NormalizerMatch | null;
-}
-/**
- * Record of a token fusion event performed by the normalizer.
- *
- * When a rule merges multiple source tokens into fewer replacement tokens,
- * the normalizer fires a {@link NormalizerOptions.onFusion | fusion callback}
- * with this record. The playground uses these records to render the
- * fusion detail table showing exactly which tokens were merged and by
- * which rule.
- *
- * @example
- * ```ts
- * // "to" "the" "power" "of" fused into CARET "^"
- * const fusion: TokenFusion = {
- *   rule: "phrase:to the power of",
- *   sourceTokens: [toToken, theToken, powerToken, ofToken],
- *   fusedToken: caretToken,
- * };
- * ```
- */
-interface TokenFusion {
-    /** The name of the rule that triggered this fusion (e.g., "phrase:to the power of") */
-    rule: string;
-    /** The original tokens before fusion, always ≥ 2 tokens */
-    sourceTokens: Token[];
-    /** The resulting fused token with its new type and combined value */
-    fusedToken: Token;
-}
-
-export type { NormalizerRule as N, TokenFusion as T, NormalizerMatch as a };