solve-engine 2.38.16 → 2.38.18

package/dist/{PackageCompatibility-zdsKvwQI.d.ts → PackageCompatibility-BRas0tSN.d.ts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-CStmqgw_.js';
+import { I as IEnginePackage } from './PackageRegistry-DMcI-_Qz.js';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageCompatibility-C-3vPMKp.d.cts → PackageCompatibility-CUWuzzGW.d.cts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-DiHxyxrn.cjs';
+import { I as IEnginePackage } from './PackageRegistry-JqudPxo6.cjs';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageRegistry-CStmqgw_.d.ts → PackageRegistry-DMcI-_Qz.d.ts}

@@ -2,7 +2,7 @@ import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from '
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-DPn5dfCH.js';
 import { IAsyncResolver } from './resolvers.js';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-DAzPp-j1.js';
-import { b as VMCheckpointer, D as DependencyGraph, V as VM, h as DagSnapshot, i as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-h09nijID.js';
+import { b as VMCheckpointer, D as DependencyGraph, V as VM, h as DagSnapshot, i as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-Bu6qaKi0.js';
 import { V as Value, b as ValueType, D as DatetimeGrain } from './Value-B55Hvn3e.js';
 import { a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.js';
 import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.js';
@@ -910,11 +910,37 @@ declare class AsyncResolutionBatcher {
     constructor(dag: DependencyGraph, lineCache: LineCache, vm: VM, highWaterMark?: number);
     /**
      * Create a fresh internal event stream and wire its controller.
-     * Called from the constructor and again from clearAll() so the batcher
-     * keeps emitting events after an engine clear, the engine instance
-     * (and this batcher) live on across clear() calls.
+     *
+     * Called from {@link eventStream} on first use and again after clearAll(),
+     * so the batcher keeps emitting events after an engine clear: the engine
+     * instance (and this batcher) live on across clear() calls.
      */
     private createEventStream;
+    /**
+     * The event stream, built the first time anything needs one.
+     *
+     * It used to be built in the constructor, and a ReadableStream is not free
+     * to build: its start algorithm queues promise reactions, so every engine
+     * paid for a stream, and a host that constructs engines in a synchronous
+     * loop accumulated one engine's worth of pending microtasks per engine
+     * because nothing drained them until the loop ended. At roughly nine
+     * kilobytes each that is ninety megabytes over ten thousand engines, for a
+     * stream almost none of them ever read.
+     *
+     * Building it on first use rather than on first subscribe is what keeps the
+     * behaviour identical. The stream buffers up to `highWaterMark` events with
+     * no reader attached, so a consumer that subscribes after some events have
+     * already flowed still receives them; deferring until {@link getEventStream}
+     * would have dropped exactly those. So the emit path asks for it too, and
+     * the engine that never resolves anything asynchronously and never
+     * subscribes is the only one that never builds it, which is the case worth
+     * optimising.
+     *
+     * A cancelled stream is not rebuilt: cancellation clears the controller but
+     * leaves the stream itself in place, so the check below sees one and the
+     * events go nowhere, which is what cancelling asked for.
+     */
+    private eventStream;
     /**
      * Add a resolved query key to the pending batch.
      *
@@ -2241,6 +2267,13 @@ declare class ExpressionEngine {
      * DAG walk + re-evaluation pass. Replaces the old single-callback pattern.
      */
     private batcher;
+    /**
+     * Names that may no longer be defined, pending the end of the pass.
+     *
+     * Null rather than an empty set, because a document that never removes a
+     * definition never allocates one. See {@link settleOrphanedNames}.
+     */
+    private orphanCandidates;
     /**
      * Drives proactive background refresh of live values, or `null` when the
      * host has not enabled it (the default). See {@link BackgroundRefreshManager}.
@@ -2386,6 +2419,27 @@ declare class ExpressionEngine {
      * Tests use this to access `batcher._testCaptures` for synchronous
      * event observation without async stream reader timing issues.
      */
+    /** The names of every user-defined unit in scope, for detecting a removal. */
+    userUnitNames(): string[];
+    /**
+     * Drop every user unit defined by `lineNumber`, for a line being removed.
+     *
+     * A line being recompiled clears its own definitions on the way through, so
+     * this is for the line that will never be compiled again.
+     *
+     * @param lineId - The persistent id of the line being deleted.
+     * @returns Whether the line had defined anything.
+     */
+    undefineUserUnitsFrom(lineId: number): boolean;
+    /**
+     * Recompile everything, because a user unit is no longer in scope.
+     *
+     * A unit is expanded while a line is compiled, so a line that used one holds
+     * bytecode built around it. Losing the definition has to reach that bytecode
+     * or the conversion goes on working from a definition the document no longer
+     * contains.
+     */
+    invalidateForRemovedUserUnits(): void;
     getBatcher(): AsyncResolutionBatcher;
     /**
      * Register a package with the engine's isolated registries.
@@ -2544,6 +2598,74 @@ declare class ExpressionEngine {
      * @param reads - Variable keys the line reads.
      * @param writes - Variable keys the line writes.
      */
+    /**
+     * Forget names that no line defines any more.
+     *
+     * The graph reports a key when the line that wrote it stops doing so and no
+     * other line writes it. The VM's variable store only ever accumulated, so
+     * the value outlived the line: deleting `:x = 12` left `x + 4` answering
+     * `16` for the rest of the session.
+     *
+     * The checkpoint chain is told as well, since it records what each line
+     * wrote and would otherwise put the name back on the next restore.
+     *
+     * Only variable names. The key space also holds category tags, globals,
+     * data sources and line positions, and none of those is a VM binding; a
+     * prefix is what tells them apart, and a variable's key is the bare name.
+     *
+     * @param orphaned - Keys the graph reports as no longer written by any line.
+     */
+    /**
+     * Forget a name the graph says no line writes any more.
+     *
+     * Reported by {@link DependencyGraph.registerLine} and its `removeLine` when
+     * the line that wrote a key stops doing so and no other line writes it. The
+     * VM's variable store only ever accumulated, so the value outlived the line:
+     * deleting `:x = 12` left `x + 4` answering `16` for the rest of the
+     * session.
+     *
+     * The graph is not the authority here, the document is, and for two
+     * ordering reasons. A line holding several inline expressions registers once
+     * per expression, so the one that defines a name is followed by one that
+     * does not, and the graph would report an orphan mid-line; the document
+     * holds the line's aggregate write set and does not. And a structural edit
+     * clears the graph, so afterwards it would call every name undefined. A
+     * line's recorded write set survives both, and is up to date for the line
+     * being registered, because a pass stores the line's results before it
+     * registers its edges.
+     *
+     * Answering here rather than at the end of the pass is what lets the lines
+     * BELOW the edit see it on the same pass rather than the next one.
+     *
+     * The checkpoint chain is told as well, since it records what each line
+     * wrote and would otherwise put the name back on the next restore.
+     *
+     * Only variable names: the key space also holds category tags, globals,
+     * data sources and line positions, and none of those is a VM binding.
+     *
+     * @param orphaned - Keys that just lost their last writer in the graph.
+     */
+    forgetOrphanedNames(orphaned: readonly string[]): void;
+    /**
+     * Decide the candidates: forget the ones no line defines any more.
+     *
+     * Asked once, at the end of a pass, because deciding as each line registers
+     * cannot work. A line holding several inline expressions registers once per
+     * expression, so the one that defines a name is followed by one that does
+     * not; and the engine registers a line before the pass records that line's
+     * results, so its recorded write set is a pass behind. Both would answer
+     * wrongly mid-pass. At the end of one, every line has registered and the
+     * document is current.
+     *
+     * The document is the authority, not the graph: a structural edit clears
+     * the graph, and a viewport leaves the lines outside it unregistered, while
+     * a line's recorded write set survives both.
+     *
+     * The reader of a forgotten name updates on the following pass, which an
+     * editor makes anyway. It is not made to happen sooner because every way of
+     * doing that answers the question before it can be answered correctly.
+     */
+    settleOrphanedNames(): void;
     private registerLineWithTags;
     /**
      * Execute bytecode and handle the result.

package/dist/{PackageRegistry-DiHxyxrn.d.cts → PackageRegistry-JqudPxo6.d.cts}

@@ -2,7 +2,7 @@ import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from '
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-DaWkCu84.cjs';
 import { IAsyncResolver } from './resolvers.cjs';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-D382VSYh.cjs';
-import { b as VMCheckpointer, D as DependencyGraph, V as VM, h as DagSnapshot, i as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-BwqFO2TY.cjs';
+import { b as VMCheckpointer, D as DependencyGraph, V as VM, h as DagSnapshot, i as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-0C4z3yDS.cjs';
 import { V as Value, b as ValueType, D as DatetimeGrain } from './Value-B55Hvn3e.cjs';
 import { a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.cjs';
 import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.cjs';
@@ -910,11 +910,37 @@ declare class AsyncResolutionBatcher {
     constructor(dag: DependencyGraph, lineCache: LineCache, vm: VM, highWaterMark?: number);
     /**
      * Create a fresh internal event stream and wire its controller.
-     * Called from the constructor and again from clearAll() so the batcher
-     * keeps emitting events after an engine clear, the engine instance
-     * (and this batcher) live on across clear() calls.
+     *
+     * Called from {@link eventStream} on first use and again after clearAll(),
+     * so the batcher keeps emitting events after an engine clear: the engine
+     * instance (and this batcher) live on across clear() calls.
      */
     private createEventStream;
+    /**
+     * The event stream, built the first time anything needs one.
+     *
+     * It used to be built in the constructor, and a ReadableStream is not free
+     * to build: its start algorithm queues promise reactions, so every engine
+     * paid for a stream, and a host that constructs engines in a synchronous
+     * loop accumulated one engine's worth of pending microtasks per engine
+     * because nothing drained them until the loop ended. At roughly nine
+     * kilobytes each that is ninety megabytes over ten thousand engines, for a
+     * stream almost none of them ever read.
+     *
+     * Building it on first use rather than on first subscribe is what keeps the
+     * behaviour identical. The stream buffers up to `highWaterMark` events with
+     * no reader attached, so a consumer that subscribes after some events have
+     * already flowed still receives them; deferring until {@link getEventStream}
+     * would have dropped exactly those. So the emit path asks for it too, and
+     * the engine that never resolves anything asynchronously and never
+     * subscribes is the only one that never builds it, which is the case worth
+     * optimising.
+     *
+     * A cancelled stream is not rebuilt: cancellation clears the controller but
+     * leaves the stream itself in place, so the check below sees one and the
+     * events go nowhere, which is what cancelling asked for.
+     */
+    private eventStream;
     /**
      * Add a resolved query key to the pending batch.
      *
@@ -2241,6 +2267,13 @@ declare class ExpressionEngine {
      * DAG walk + re-evaluation pass. Replaces the old single-callback pattern.
      */
     private batcher;
+    /**
+     * Names that may no longer be defined, pending the end of the pass.
+     *
+     * Null rather than an empty set, because a document that never removes a
+     * definition never allocates one. See {@link settleOrphanedNames}.
+     */
+    private orphanCandidates;
     /**
      * Drives proactive background refresh of live values, or `null` when the
      * host has not enabled it (the default). See {@link BackgroundRefreshManager}.
@@ -2386,6 +2419,27 @@ declare class ExpressionEngine {
      * Tests use this to access `batcher._testCaptures` for synchronous
      * event observation without async stream reader timing issues.
      */
+    /** The names of every user-defined unit in scope, for detecting a removal. */
+    userUnitNames(): string[];
+    /**
+     * Drop every user unit defined by `lineNumber`, for a line being removed.
+     *
+     * A line being recompiled clears its own definitions on the way through, so
+     * this is for the line that will never be compiled again.
+     *
+     * @param lineId - The persistent id of the line being deleted.
+     * @returns Whether the line had defined anything.
+     */
+    undefineUserUnitsFrom(lineId: number): boolean;
+    /**
+     * Recompile everything, because a user unit is no longer in scope.
+     *
+     * A unit is expanded while a line is compiled, so a line that used one holds
+     * bytecode built around it. Losing the definition has to reach that bytecode
+     * or the conversion goes on working from a definition the document no longer
+     * contains.
+     */
+    invalidateForRemovedUserUnits(): void;
     getBatcher(): AsyncResolutionBatcher;
     /**
      * Register a package with the engine's isolated registries.
@@ -2544,6 +2598,74 @@ declare class ExpressionEngine {
      * @param reads - Variable keys the line reads.
      * @param writes - Variable keys the line writes.
      */
+    /**
+     * Forget names that no line defines any more.
+     *
+     * The graph reports a key when the line that wrote it stops doing so and no
+     * other line writes it. The VM's variable store only ever accumulated, so
+     * the value outlived the line: deleting `:x = 12` left `x + 4` answering
+     * `16` for the rest of the session.
+     *
+     * The checkpoint chain is told as well, since it records what each line
+     * wrote and would otherwise put the name back on the next restore.
+     *
+     * Only variable names. The key space also holds category tags, globals,
+     * data sources and line positions, and none of those is a VM binding; a
+     * prefix is what tells them apart, and a variable's key is the bare name.
+     *
+     * @param orphaned - Keys the graph reports as no longer written by any line.
+     */
+    /**
+     * Forget a name the graph says no line writes any more.
+     *
+     * Reported by {@link DependencyGraph.registerLine} and its `removeLine` when
+     * the line that wrote a key stops doing so and no other line writes it. The
+     * VM's variable store only ever accumulated, so the value outlived the line:
+     * deleting `:x = 12` left `x + 4` answering `16` for the rest of the
+     * session.
+     *
+     * The graph is not the authority here, the document is, and for two
+     * ordering reasons. A line holding several inline expressions registers once
+     * per expression, so the one that defines a name is followed by one that
+     * does not, and the graph would report an orphan mid-line; the document
+     * holds the line's aggregate write set and does not. And a structural edit
+     * clears the graph, so afterwards it would call every name undefined. A
+     * line's recorded write set survives both, and is up to date for the line
+     * being registered, because a pass stores the line's results before it
+     * registers its edges.
+     *
+     * Answering here rather than at the end of the pass is what lets the lines
+     * BELOW the edit see it on the same pass rather than the next one.
+     *
+     * The checkpoint chain is told as well, since it records what each line
+     * wrote and would otherwise put the name back on the next restore.
+     *
+     * Only variable names: the key space also holds category tags, globals,
+     * data sources and line positions, and none of those is a VM binding.
+     *
+     * @param orphaned - Keys that just lost their last writer in the graph.
+     */
+    forgetOrphanedNames(orphaned: readonly string[]): void;
+    /**
+     * Decide the candidates: forget the ones no line defines any more.
+     *
+     * Asked once, at the end of a pass, because deciding as each line registers
+     * cannot work. A line holding several inline expressions registers once per
+     * expression, so the one that defines a name is followed by one that does
+     * not; and the engine registers a line before the pass records that line's
+     * results, so its recorded write set is a pass behind. Both would answer
+     * wrongly mid-pass. At the end of one, every line has registered and the
+     * document is current.
+     *
+     * The document is the authority, not the graph: a structural edit clears
+     * the graph, and a viewport leaves the lines outside it unregistered, while
+     * a line's recorded write set survives both.
+     *
+     * The reader of a forgotten name updates on the following pass, which an
+     * editor makes anyway. It is not made to happen sooner because every way of
+     * doing that answers the question before it can be answered correctly.
+     */
+    settleOrphanedNames(): void;
     private registerLineWithTags;
     /**
      * Execute bytecode and handle the result.

package/dist/{VMBuiltins-BwqFO2TY.d.cts → VMBuiltins-0C4z3yDS.d.cts}

@@ -680,7 +680,7 @@ declare class DependencyGraph {
      * @param reads - Variable names this line reads
      * @param writes - Variable names this line writes (assigns to)
      */
-    registerLine(lineNumber: number, reads: string[], writes: string[]): void;
+    registerLine(lineNumber: number, reads: string[], writes: string[]): readonly string[];
     /**
      * Register a line's dependency on an external data source (e.g., currency rate, OSRS GE price).
      *
@@ -729,6 +729,25 @@ declare class DependencyGraph {
      * @param dependsOnLine - 1-based line whose result it read
      */
     registerLinePositionDependency(lineNumber: number, dependsOnLine: number): void;
+    /**
+     * Every line that read some position's result, whichever position it was.
+     *
+     * For a structural edit, which changes what a position *means* rather than
+     * what any line says. Inserting a line moves everything below it, so `line 5`
+     * now names different text, `prev` names a different neighbour, and an
+     * `above` aggregate covers a different block, all without a character
+     * changing on the line that reads them.
+     *
+     * Deliberately not filtered by which positions moved. A reader whose target
+     * shifted has to re-run, and so does one that shifted past its own target and
+     * became a self-reference, and the second is not visible from the target
+     * alone. Positional readers are a small minority of a document's lines, so
+     * re-running all of them costs almost nothing and cannot be wrong.
+     *
+     * @returns The 1-based line numbers doing the reading, valid until the next
+     * structural change.
+     */
+    linesReadingAPosition(): Iterable<number>;
     /**
      * The lines that read the result of line `lineNumber`.
      *
@@ -758,7 +777,7 @@ declare class DependencyGraph {
      *
      * @param lineNumber - The line number being removed
      */
-    removeLine(lineNumber: number): void;
+    removeLine(lineNumber: number): readonly string[];
     /**
      * Get all line numbers that consume (read) a given variable.
      *
@@ -1058,6 +1077,17 @@ declare class VMCheckpointer {
      * @returns Whether a checkpoint existed at that line.
      */
     applyCheckpointAt(lineNumber: number): boolean;
+    /**
+     * Drop `names` from every checkpoint, as though no line had ever set them.
+     *
+     * A checkpoint records what its line wrote, so a name whose defining line
+     * has been deleted or edited into something else is still in the chain, and
+     * the next restore would put it back into the VM after the VM had been told
+     * to forget it. The two have to agree.
+     *
+     * @param names - The names no line defines any more.
+     */
+    forget(names: readonly string[]): void;
     /**
      * Find the nearest checkpoint at or before the given line number.
      *

package/dist/{VMBuiltins-h09nijID.d.ts → VMBuiltins-Bu6qaKi0.d.ts}

@@ -680,7 +680,7 @@ declare class DependencyGraph {
      * @param reads - Variable names this line reads
      * @param writes - Variable names this line writes (assigns to)
      */
-    registerLine(lineNumber: number, reads: string[], writes: string[]): void;
+    registerLine(lineNumber: number, reads: string[], writes: string[]): readonly string[];
     /**
      * Register a line's dependency on an external data source (e.g., currency rate, OSRS GE price).
      *
@@ -729,6 +729,25 @@ declare class DependencyGraph {
      * @param dependsOnLine - 1-based line whose result it read
      */
     registerLinePositionDependency(lineNumber: number, dependsOnLine: number): void;
+    /**
+     * Every line that read some position's result, whichever position it was.
+     *
+     * For a structural edit, which changes what a position *means* rather than
+     * what any line says. Inserting a line moves everything below it, so `line 5`
+     * now names different text, `prev` names a different neighbour, and an
+     * `above` aggregate covers a different block, all without a character
+     * changing on the line that reads them.
+     *
+     * Deliberately not filtered by which positions moved. A reader whose target
+     * shifted has to re-run, and so does one that shifted past its own target and
+     * became a self-reference, and the second is not visible from the target
+     * alone. Positional readers are a small minority of a document's lines, so
+     * re-running all of them costs almost nothing and cannot be wrong.
+     *
+     * @returns The 1-based line numbers doing the reading, valid until the next
+     * structural change.
+     */
+    linesReadingAPosition(): Iterable<number>;
     /**
      * The lines that read the result of line `lineNumber`.
      *
@@ -758,7 +777,7 @@ declare class DependencyGraph {
      *
      * @param lineNumber - The line number being removed
      */
-    removeLine(lineNumber: number): void;
+    removeLine(lineNumber: number): readonly string[];
     /**
      * Get all line numbers that consume (read) a given variable.
      *
@@ -1058,6 +1077,17 @@ declare class VMCheckpointer {
      * @returns Whether a checkpoint existed at that line.
      */
     applyCheckpointAt(lineNumber: number): boolean;
+    /**
+     * Drop `names` from every checkpoint, as though no line had ever set them.
+     *
+     * A checkpoint records what its line wrote, so a name whose defining line
+     * has been deleted or edited into something else is still in the chain, and
+     * the next restore would put it back into the VM after the VM had been told
+     * to forget it. The two have to agree.
+     *
+     * @param names - The names no line defines any more.
+     */
+    forget(names: readonly string[]): void;
     /**
      * Find the nearest checkpoint at or before the given line number.
      *

package/dist/{chunk-44BWHZ5V.js → chunk-2YHOWQ43.js}

@@ -1,2 +1,2 @@
-var f=class{constructor(t){this.checkpoints=[];this.vm=t;}snapshot(t,e,n){if(n.length===0)return null;let i=this.indexOfCheckpointAt(t),s=i>=0?i:this.insertionIndexFor(t),r=s>0?this.checkpoints[s-1]:null,h=Object.create(null),u=Object.create(null);for(let o of n){if(this.vm.hasUserFunction(o)){let l=this.vm.getUserFunction(o);l&&(u[o]=l);continue}let p=this.vm.getVar(o);p!==void 0&&(h[o]=p);}let c={lineNumber:t,lineId:e,variables:h,functions:u,parent:r};i>=0?this.checkpoints[i]=c:this.checkpoints.splice(s,0,c);let a=this.checkpoints[s+1];return a!==void 0&&(a.parent=c),c}restoreTo(t){let e=this.nearestCheckpointIndex(t);this.vm.reset();for(let n=0;n<=e;n++){let i=this.checkpoints[n];for(let s of Object.keys(i.variables))this.vm.setVar(s,i.variables[s]);for(let s of Object.keys(i.functions)){let r=i.functions[s];this.vm.defineUserFunction(r.name,r.params,r.program);}}}indexOfCheckpointAt(t){let e=this.nearestCheckpointIndex(t);return e>=0&&this.checkpoints[e].lineNumber===t?e:-1}insertionIndexFor(t){return this.nearestCheckpointIndex(t)+1}nearestCheckpointIndex(t){let e=0,n=this.checkpoints.length-1,i=-1;for(;e<=n;){let s=e+n>>1;this.checkpoints[s].lineNumber<=t?(i=s,e=s+1):n=s-1;}return i}updateCheckpointAt(t,e){let n=this.getCheckpointAt(t);if(!n)return  false;for(let i of e){if(this.vm.hasUserFunction(i)){let r=this.vm.getUserFunction(i);r&&(n.functions[i]=r);continue}let s=this.vm.getVar(i);s!==void 0&&(n.variables[i]=s);}return  true}applyCheckpointAt(t){let e=this.getCheckpointAt(t);if(!e)return  false;for(let n of Object.keys(e.variables))this.vm.setVar(n,e.variables[n]);for(let n of Object.keys(e.functions)){let i=e.functions[n];this.vm.defineUserFunction(i.name,i.params,i.program);}return  true}getNearestCheckpoint(t){let e=this.nearestCheckpointIndex(t);return e<0?null:this.checkpoints[e]}getCheckpointAt(t){let e=this.nearestCheckpointIndex(t);if(e<0)return;let n=this.checkpoints[e];return n.lineNumber===t?n:void 0}getAllCheckpoints(){return this.checkpoints}lookupVariable(t){if(this.checkpoints.length===0)return;let e=this.checkpoints[this.checkpoints.length-1];for(;e;){if(Object.prototype.hasOwnProperty.call(e.variables,t))return e.variables[t];e=e.parent;}}clear(){this.checkpoints=[];}get count(){return this.checkpoints.length}get isEmpty(){return this.checkpoints.length===0}get vmInstance(){return this.vm}};export{f as a};//# sourceMappingURL=chunk-44BWHZ5V.js.map
-//# sourceMappingURL=chunk-44BWHZ5V.js.map
+var f=class{constructor(t){this.checkpoints=[];this.vm=t;}snapshot(t,e,n){if(n.length===0)return null;let i=this.indexOfCheckpointAt(t),s=i>=0?i:this.insertionIndexFor(t),r=s>0?this.checkpoints[s-1]:null,h=Object.create(null),u=Object.create(null);for(let o of n){if(this.vm.hasUserFunction(o)){let l=this.vm.getUserFunction(o);l&&(u[o]=l);continue}let p=this.vm.getVar(o);p!==void 0&&(h[o]=p);}let c={lineNumber:t,lineId:e,variables:h,functions:u,parent:r};i>=0?this.checkpoints[i]=c:this.checkpoints.splice(s,0,c);let a=this.checkpoints[s+1];return a!==void 0&&(a.parent=c),c}restoreTo(t){let e=this.nearestCheckpointIndex(t);this.vm.reset();for(let n=0;n<=e;n++){let i=this.checkpoints[n];for(let s of Object.keys(i.variables))this.vm.setVar(s,i.variables[s]);for(let s of Object.keys(i.functions)){let r=i.functions[s];this.vm.defineUserFunction(r.name,r.params,r.program);}}}indexOfCheckpointAt(t){let e=this.nearestCheckpointIndex(t);return e>=0&&this.checkpoints[e].lineNumber===t?e:-1}insertionIndexFor(t){return this.nearestCheckpointIndex(t)+1}nearestCheckpointIndex(t){let e=0,n=this.checkpoints.length-1,i=-1;for(;e<=n;){let s=e+n>>1;this.checkpoints[s].lineNumber<=t?(i=s,e=s+1):n=s-1;}return i}updateCheckpointAt(t,e){let n=this.getCheckpointAt(t);if(!n)return  false;for(let i of e){if(this.vm.hasUserFunction(i)){let r=this.vm.getUserFunction(i);r&&(n.functions[i]=r);continue}let s=this.vm.getVar(i);s!==void 0&&(n.variables[i]=s);}return  true}applyCheckpointAt(t){let e=this.getCheckpointAt(t);if(!e)return  false;for(let n of Object.keys(e.variables))this.vm.setVar(n,e.variables[n]);for(let n of Object.keys(e.functions)){let i=e.functions[n];this.vm.defineUserFunction(i.name,i.params,i.program);}return  true}forget(t){if(t.length!==0)for(let e of this.checkpoints)for(let n of t)delete e.variables[n],delete e.functions[n];}getNearestCheckpoint(t){let e=this.nearestCheckpointIndex(t);return e<0?null:this.checkpoints[e]}getCheckpointAt(t){let e=this.nearestCheckpointIndex(t);if(e<0)return;let n=this.checkpoints[e];return n.lineNumber===t?n:void 0}getAllCheckpoints(){return this.checkpoints}lookupVariable(t){if(this.checkpoints.length===0)return;let e=this.checkpoints[this.checkpoints.length-1];for(;e;){if(Object.prototype.hasOwnProperty.call(e.variables,t))return e.variables[t];e=e.parent;}}clear(){this.checkpoints=[];}get count(){return this.checkpoints.length}get isEmpty(){return this.checkpoints.length===0}get vmInstance(){return this.vm}};export{f as a};//# sourceMappingURL=chunk-2YHOWQ43.js.map
+//# sourceMappingURL=chunk-2YHOWQ43.js.map

package/dist/chunk-2YHOWQ43.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vm/VMCheckpoints.ts"],"names":["VMCheckpointer","vm","lineNumber","lineId","variableNames","existing","insertAt","parent","variables","functions","name","fn","val","checkpoint","next","targetIndex","i","cp","key","index","low","high","result","mid","value","names","candidate"],"mappings":"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","file":"chunk-2YHOWQ43.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 * Each checkpoint holds only the variables that CHANGED at its line, and\n * reaches the rest through its `parent` link. A lookup walks that chain until\n * it finds the name; a restore walks it from the root applying each link's own\n * bindings in turn, so a later line's value naturally overwrites an earlier\n * one's.\n *\n * ```text\n * Checkpoint 0 (root):  {}                      // empty scope\n * Checkpoint 1 (:x=5):  { x: 5 }    parent → 0\n * Checkpoint 2 (:y=8):  { y: 8 }    parent → 1\n * Checkpoint 3 (:x=3):  { x: 3 }    parent → 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 parent 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 * Only the variables set or updated at this line; the rest are reached\n\t * through {@link VMCheckpoint.parent}.\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 * Records only what this line wrote; the rest is reached through the\n\t * parent link rather than copied.\n\t *\n\t * A line that is snapshotted again drops every checkpoint at or after it\n\t * first, so the list stays in document order and the new checkpoint\n\t * inherits from the line before it rather than from one after it. See the\n\t * body for what went wrong without that.\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\t// This line's own entry is replaced, and nothing else is touched.\n\t\t//\n\t\t// The list is a sequence of document positions and `restoreTo` reads it\n\t\t// as one, so a re-run must not append after entries that come later in\n\t\t// the document: editing line 2 of a document whose lines 1, 2 and 3 each\n\t\t// define something left the list as [1, 2, 3, 2], and a restore to line\n\t\t// 2 then found the stale entry.\n\t\t//\n\t\t// Replacing rather than truncating is the part that took a second go.\n\t\t// Dropping every entry at or after the line is sound only for a pass\n\t\t// running from line 1, which re-takes them as it continues. A pass\n\t\t// limited to a viewport does not: it re-snapshots the top of the\n\t\t// document and never reaches the definitions below its end line, so the\n\t\t// chain lost them, and `restoreTo` then RESET the VM and replayed a\n\t\t// prefix that no longer mentioned them. A line further down reading one\n\t\t// answered `Undefined variable` where it had answered a number. Absent\n\t\t// is worse than stale here: a stale entry is what the document is\n\t\t// currently showing anyway, and the pass corrects it when it reaches\n\t\t// that line.\n\t\tconst existing = this.indexOfCheckpointAt(lineNumber);\n\t\tconst insertAt = existing >= 0 ? existing : this.insertionIndexFor(lineNumber);\n\t\tconst parent = insertAt > 0 ? this.checkpoints[insertAt - 1] : null;\n\n\t\t// Each checkpoint holds only what its line wrote, and reaches the rest\n\t\t// through `parent`. It used to reach it through the prototype chain\n\t\t// instead, which held the same entries and cost the same memory, and\n\t\t// made the chain as deep as the document has definitions: a null\n\t\t// prototype is a flat object, and one per definition is a chain two\n\t\t// thousand deep on a document of two thousand definitions. Creating and\n\t\t// reading those took a pass over such a document from 6.0 ms to 23.1 ms.\n\t\t//\n\t\t// Nothing needed the inheritance. `restoreTo` walks `parent` and applies\n\t\t// each checkpoint's OWN keys, which is the same set either way, and the\n\t\t// one reader that did walk the prototype now walks `parent` too.\n\t\t//\n\t\t// Null-prototyped rather than `{}`, so a variable named `constructor` or\n\t\t// `toString` is a key like any other.\n\t\tconst variables: Record<string, Value> = Object.create(null) as Record<string, Value>;\n\t\tconst functions: Record<string, UserFunctionDef> = Object.create(null) 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\tif (existing >= 0) this.checkpoints[existing] = checkpoint;\n\t\telse this.checkpoints.splice(insertAt, 0, checkpoint);\n\t\t// The entry after this one now follows a different object.\n\t\tconst next = this.checkpoints[insertAt + 1];\n\t\tif (next !== undefined) next.parent = 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(total variable definitions before the line), since\n\t * each checkpoint in the chain contributes only the names its own line\n\t * wrote.\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\t// The chain from the root to the target IS the array up to that index.\n\t\t//\n\t\t// Every checkpoint is created with the one before it in the array as its\n\t\t// parent (see {@link snapshot}), and the array is kept in document\n\t\t// order, so walking parent links would visit exactly these entries in\n\t\t// exactly this order. Reading the array instead of the links costs no\n\t\t// allocation, and it was the links that made this quadratic: the walk\n\t\t// runs target-to-root, so the chain was assembled by `unshift`ing each\n\t\t// entry onto the front, which shifts every entry already there. A\n\t\t// document with two thousand definitions did four million shifts per\n\t\t// restore, and a scroll restores.\n\t\t//\n\t\t// `CheckpointsStayInDocumentOrder.spec.ts` asserts the invariant this\n\t\t// relies on, so a change that broke it would fail there rather than\n\t\t// quietly restoring the wrong state here.\n\t\tconst targetIndex = this.nearestCheckpointIndex(lineNumber);\n\n\t\tthis.vm.reset();\n\t\tfor (let i = 0; i <= targetIndex; i++) {\n\t\t\tconst cp = this.checkpoints[i];\n\t\t\t// Only the names this checkpoint's own line wrote; the ones before\n\t\t\t// it are applied by their own entries earlier in this same walk.\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 walk runs root-to-target.\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/** The index of the checkpoint recorded exactly at `lineNumber`, or -1. */\n\tprivate indexOfCheckpointAt(lineNumber: number): number {\n\t\tconst index = this.nearestCheckpointIndex(lineNumber);\n\t\treturn index >= 0 && this.checkpoints[index].lineNumber === lineNumber ? index : -1;\n\t}\n\n\t/** Where a checkpoint for `lineNumber` belongs, keeping the list in order. */\n\tprivate insertionIndexFor(lineNumber: number): number {\n\t\treturn this.nearestCheckpointIndex(lineNumber) + 1;\n\t}\n\n\t/**\n\t * The index of the last checkpoint at or before `lineNumber`, or -1.\n\t *\n\t * A binary search rather than a scan. The array is in document order, and\n\t * this is asked once per scroll and once per async batch, on a document\n\t * that can hold a checkpoint per definition.\n\t */\n\tprivate nearestCheckpointIndex(lineNumber: number): number {\n\t\tlet low = 0;\n\t\tlet high = this.checkpoints.length - 1;\n\t\tlet result = -1;\n\t\twhile (low <= high) {\n\t\t\tconst mid = (low + high) >> 1;\n\t\t\tif (this.checkpoints[mid].lineNumber <= lineNumber) {\n\t\t\t\tresult = mid;\n\t\t\t\tlow = mid + 1;\n\t\t\t} else {\n\t\t\t\thigh = mid - 1;\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Record what `lineNumber` has just written, without disturbing the chain\n\t * after it.\n\t *\n\t * {@link snapshot} drops every checkpoint at or after the line, which is\n\t * right for a pass running forward in document order: it re-takes them as it\n\t * goes. A caller re-running a few lines out of a document does not, and\n\t * dropping the entries for lines it will never visit would lose the very\n\t * bindings it is sweeping through them to collect. So this overwrites in\n\t * place instead.\n\t *\n\t * Safe against the prototype chain, because it replaces only the\n\t * checkpoint's OWN bindings: a later checkpoint that also writes the name\n\t * holds its own copy and goes on shadowing this one.\n\t *\n\t * @param lineNumber 1-based line whose recorded bindings are refreshed.\n\t * @param variableNames The names it wrote.\n\t * @returns Whether a checkpoint existed at that line to update.\n\t */\n\tupdateCheckpointAt(lineNumber: number, variableNames: string[]): boolean {\n\t\tconst checkpoint = this.getCheckpointAt(lineNumber);\n\t\tif (!checkpoint) return false;\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) checkpoint.functions[name] = fn;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst value = this.vm.getVar(name);\n\t\t\tif (value !== undefined) checkpoint.variables[name] = value;\n\t\t}\n\t\treturn true;\n\t}\n\n\t/**\n\t * Apply the bindings recorded AT `lineNumber`, leaving the rest of the VM\n\t * alone.\n\t *\n\t * {@link restoreTo} rebuilds the whole prefix, which costs the chain every\n\t * time it is called. A caller moving forward through the document already\n\t * holds the prefix up to the line before, and needs only what this line\n\t * added: restoring once and then applying each line in turn as it is passed\n\t * costs the chain once rather than once per line.\n\t *\n\t * @param lineNumber 1-based line whose own bindings are applied.\n\t * @returns Whether a checkpoint existed at that line.\n\t */\n\tapplyCheckpointAt(lineNumber: number): boolean {\n\t\tconst checkpoint = this.getCheckpointAt(lineNumber);\n\t\tif (!checkpoint) return false;\n\t\tfor (const key of Object.keys(checkpoint.variables)) {\n\t\t\tthis.vm.setVar(key, checkpoint.variables[key]);\n\t\t}\n\t\tfor (const key of Object.keys(checkpoint.functions)) {\n\t\t\tconst fn = checkpoint.functions[key];\n\t\t\tthis.vm.defineUserFunction(fn.name, fn.params, fn.program);\n\t\t}\n\t\treturn true;\n\t}\n\n\t/**\n\t * Drop `names` from every checkpoint, as though no line had ever set them.\n\t *\n\t * A checkpoint records what its line wrote, so a name whose defining line\n\t * has been deleted or edited into something else is still in the chain, and\n\t * the next restore would put it back into the VM after the VM had been told\n\t * to forget it. The two have to agree.\n\t *\n\t * @param names - The names no line defines any more.\n\t */\n\tforget(names: readonly string[]): void {\n\t\tif (names.length === 0) return;\n\t\tfor (const checkpoint of this.checkpoints) {\n\t\t\tfor (const name of names) {\n\t\t\t\tdelete checkpoint.variables[name];\n\t\t\t\tdelete checkpoint.functions[name];\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\tconst index = this.nearestCheckpointIndex(lineNumber);\n\t\treturn index < 0 ? null : this.checkpoints[index];\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\t// Searched, not scanned: the async sweep asks this once for every line\n\t\t// it walks past, and a scan would make that walk quadratic.\n\t\tconst index = this.nearestCheckpointIndex(lineNumber);\n\t\tif (index < 0) return undefined;\n\t\tconst candidate = this.checkpoints[index];\n\t\treturn candidate.lineNumber === lineNumber ? candidate : undefined;\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\tlet checkpoint: VMCheckpoint | null = this.checkpoints[this.checkpoints.length - 1];\n\t\twhile (checkpoint) {\n\t\t\tif (Object.prototype.hasOwnProperty.call(checkpoint.variables, name)) {\n\t\t\t\treturn checkpoint.variables[name];\n\t\t\t}\n\t\t\tcheckpoint = checkpoint.parent;\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"]}