solve-engine 2.38.20 → 2.38.22

package/dist/chunk-X2QJE3SV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vm/VMCheckpoints.ts"],"names":["VMCheckpointer","vm","lineNumber","lineId","variableNames","functionNames","existing","insertAt","parent","variables","functions","name","fn","val","checkpoint","next","targetIndex","i","cp","key","index","low","high","result","mid","value","positionOf","kept","position","a","b","names","candidate"],"mappings":"AAuFO,IAAMA,EAAN,KAAqB,CAM3B,YAAYC,CAAAA,CAAQ,CAJpB,KAAQ,WAAA,CAA8B,EAAC,CAKtC,IAAA,CAAK,GAAKA,EACX,CAyBA,SACCC,CAAAA,CACAC,CAAAA,CACAC,EACAC,CAAAA,CACsB,CACtB,GAAID,CAAAA,CAAc,SAAW,CAAA,CAAG,OAAO,KAqBvC,IAAME,CAAAA,CAAW,KAAK,mBAAA,CAAoBJ,CAAU,EAC9CK,CAAAA,CAAWD,CAAAA,EAAY,EAAIA,CAAAA,CAAW,IAAA,CAAK,kBAAkBJ,CAAU,CAAA,CACvEM,EAASD,CAAAA,CAAW,CAAA,CAAI,IAAA,CAAK,WAAA,CAAYA,EAAW,CAAC,CAAA,CAAI,KAgBzDE,CAAAA,CAAmC,MAAA,CAAO,OAAO,IAAI,CAAA,CACrDC,EAA6C,MAAA,CAAO,MAAA,CAAO,IAAI,CAAA,CAQrE,IAAA,IAAWC,KAAQP,CAAAA,CAAe,CAEjC,GADmBC,CAAAA,GAAkB,MAAA,CAAYA,CAAAA,CAAc,GAAA,CAAIM,CAAI,CAAA,CAAI,IAAA,CAAK,GAAG,eAAA,CAAgBA,CAAI,EACvF,CACf,IAAMC,EAAK,IAAA,CAAK,EAAA,CAAG,gBAAgBD,CAAI,CAAA,CACnCC,IAAIF,CAAAA,CAAUC,CAAI,EAAIC,CAAAA,CAAAA,CAC1B,QACD,CACA,IAAMC,EAAM,IAAA,CAAK,EAAA,CAAG,OAAOF,CAAI,CAAA,CAC3BE,IAAQ,MAAA,GACXJ,CAAAA,CAAUE,CAAI,CAAA,CAAIE,CAAAA,EAEpB,CAEA,IAAMC,CAAAA,CAA2B,CAChC,UAAA,CAAAZ,CAAAA,CACA,OAAAC,CAAAA,CACA,SAAA,CAAAM,CAAAA,CACA,SAAA,CAAAC,EACA,MAAA,CAAAF,CACD,EACIF,CAAAA,EAAY,CAAA,CAAG,KAAK,WAAA,CAAYA,CAAQ,EAAIQ,CAAAA,CAC3C,IAAA,CAAK,YAAY,MAAA,CAAOP,CAAAA,CAAU,EAAGO,CAAU,CAAA,CAEpD,IAAMC,CAAAA,CAAO,IAAA,CAAK,WAAA,CAAYR,CAAAA,CAAW,CAAC,CAAA,CAC1C,OAAIQ,IAAS,MAAA,GAAWA,CAAAA,CAAK,OAASD,CAAAA,CAAAA,CAC/BA,CACR,CAqBA,SAAA,CAAUZ,CAAAA,CAA0B,CAgBnC,IAAMc,CAAAA,CAAc,KAAK,sBAAA,CAAuBd,CAAU,EAE1D,IAAA,CAAK,EAAA,CAAG,KAAA,EAAM,CACd,QAASe,CAAAA,CAAI,CAAA,CAAGA,GAAKD,CAAAA,CAAaC,CAAAA,EAAAA,CAAK,CACtC,IAAMC,CAAAA,CAAK,KAAK,WAAA,CAAYD,CAAC,EAG7B,IAAA,IAAWE,CAAAA,IAAO,OAAO,IAAA,CAAKD,CAAAA,CAAG,SAAS,CAAA,CACzC,IAAA,CAAK,EAAA,CAAG,MAAA,CAAOC,EAAKD,CAAAA,CAAG,SAAA,CAAUC,CAAG,CAAC,CAAA,CAKtC,QAAWA,CAAAA,IAAO,MAAA,CAAO,IAAA,CAAKD,CAAAA,CAAG,SAAS,CAAA,CAAG,CAC5C,IAAMN,CAAAA,CAAKM,CAAAA,CAAG,UAAUC,CAAG,CAAA,CAC3B,IAAA,CAAK,EAAA,CAAG,mBAAmBP,CAAAA,CAAG,IAAA,CAAMA,EAAG,MAAA,CAAQA,CAAAA,CAAG,OAAO,EAC1D,CACD,CACD,CAGQ,mBAAA,CAAoBV,EAA4B,CACvD,IAAMkB,EAAQ,IAAA,CAAK,sBAAA,CAAuBlB,CAAU,CAAA,CACpD,OAAOkB,CAAAA,EAAS,CAAA,EAAK,KAAK,WAAA,CAAYA,CAAK,EAAE,UAAA,GAAelB,CAAAA,CAAakB,EAAQ,EAClF,CAGQ,kBAAkBlB,CAAAA,CAA4B,CACrD,OAAO,IAAA,CAAK,sBAAA,CAAuBA,CAAU,CAAA,CAAI,CAClD,CASQ,sBAAA,CAAuBA,CAAAA,CAA4B,CAC1D,IAAImB,EAAM,CAAA,CACNC,CAAAA,CAAO,KAAK,WAAA,CAAY,MAAA,CAAS,EACjCC,CAAAA,CAAS,EAAA,CACb,KAAOF,CAAAA,EAAOC,CAAAA,EAAM,CACnB,IAAME,CAAAA,CAAOH,EAAMC,CAAAA,EAAS,CAAA,CACxB,KAAK,WAAA,CAAYE,CAAG,CAAA,CAAE,UAAA,EAActB,GACvCqB,CAAAA,CAASC,CAAAA,CACTH,EAAMG,CAAAA,CAAM,CAAA,EAEZF,EAAOE,CAAAA,CAAM,EAEf,CACA,OAAOD,CACR,CAqBA,kBAAA,CAAmBrB,CAAAA,CAAoBE,EAAkC,CACxE,IAAMU,EAAa,IAAA,CAAK,eAAA,CAAgBZ,CAAU,CAAA,CAClD,GAAI,CAACY,CAAAA,CAAY,OAAO,MAAA,CACxB,IAAA,IAAWH,KAAQP,CAAAA,CAAe,CACjC,GAAI,IAAA,CAAK,EAAA,CAAG,gBAAgBO,CAAI,CAAA,CAAG,CAClC,IAAMC,CAAAA,CAAK,KAAK,EAAA,CAAG,eAAA,CAAgBD,CAAI,CAAA,CACnCC,IAAIE,CAAAA,CAAW,SAAA,CAAUH,CAAI,CAAA,CAAIC,CAAAA,CAAAA,CACrC,QACD,CACA,IAAMa,EAAQ,IAAA,CAAK,EAAA,CAAG,OAAOd,CAAI,CAAA,CAC7Bc,IAAU,MAAA,GAAWX,CAAAA,CAAW,UAAUH,CAAI,CAAA,CAAIc,CAAAA,EACvD,CACA,OAAO,KACR,CAeA,kBAAkBvB,CAAAA,CAA6B,CAC9C,IAAMY,CAAAA,CAAa,IAAA,CAAK,gBAAgBZ,CAAU,CAAA,CAClD,GAAI,CAACY,CAAAA,CAAY,OAAO,MAAA,CACxB,IAAA,IAAWK,KAAO,MAAA,CAAO,IAAA,CAAKL,CAAAA,CAAW,SAAS,EACjD,IAAA,CAAK,EAAA,CAAG,OAAOK,CAAAA,CAAKL,CAAAA,CAAW,UAAUK,CAAG,CAAC,CAAA,CAE9C,IAAA,IAAWA,KAAO,MAAA,CAAO,IAAA,CAAKL,EAAW,SAAS,CAAA,CAAG,CACpD,IAAMF,CAAAA,CAAKE,CAAAA,CAAW,SAAA,CAAUK,CAAG,CAAA,CACnC,IAAA,CAAK,GAAG,kBAAA,CAAmBP,CAAAA,CAAG,KAAMA,CAAAA,CAAG,MAAA,CAAQA,EAAG,OAAO,EAC1D,CACA,OAAO,KACR,CAwBA,gBAAA,CAAiBV,CAAAA,CAA0B,CAC1C,IAAMkB,CAAAA,CAAQ,IAAA,CAAK,mBAAA,CAAoBlB,CAAU,CAAA,CACjD,GAAIkB,EAAQ,CAAA,CAAG,OACf,KAAK,WAAA,CAAY,MAAA,CAAOA,EAAO,CAAC,CAAA,CAChC,IAAML,CAAAA,CAAO,IAAA,CAAK,YAAYK,CAAK,CAAA,CAC/BL,IAAS,MAAA,GAAWA,CAAAA,CAAK,MAAA,CAASK,CAAAA,CAAQ,EAAI,IAAA,CAAK,WAAA,CAAYA,EAAQ,CAAC,CAAA,CAAI,MACjF,CAeA,QAAA,CAASM,EAA8C,CACtD,IAAMC,EAAuB,EAAC,CAC9B,QAAWb,CAAAA,IAAc,IAAA,CAAK,YAAa,CAC1C,IAAMc,CAAAA,CAAWF,CAAAA,CAAWZ,EAAW,MAAM,CAAA,CACzCc,EAAW,CAAA,GACfd,CAAAA,CAAW,WAAac,CAAAA,CACxBD,CAAAA,CAAK,KAAKb,CAAU,CAAA,EACrB,CACAa,CAAAA,CAAK,IAAA,CAAK,CAACE,CAAAA,CAAGC,CAAAA,GAAMD,EAAE,UAAA,CAAaC,CAAAA,CAAE,UAAU,CAAA,CAC/C,QAASb,CAAAA,CAAI,CAAA,CAAGA,EAAIU,CAAAA,CAAK,MAAA,CAAQV,IAAKU,CAAAA,CAAKV,CAAC,EAAE,MAAA,CAASA,CAAAA,CAAI,EAAIU,CAAAA,CAAKV,CAAAA,CAAI,CAAC,CAAA,CAAI,IAAA,CAC7E,KAAK,WAAA,CAAcU,EACpB,CAEA,MAAA,CAAOI,EAAgC,CACtC,GAAIA,EAAM,MAAA,GAAW,CAAA,CACrB,QAAWjB,CAAAA,IAAc,IAAA,CAAK,YAC7B,IAAA,IAAWH,CAAAA,IAAQoB,EAClB,OAAOjB,CAAAA,CAAW,UAAUH,CAAI,CAAA,CAChC,OAAOG,CAAAA,CAAW,SAAA,CAAUH,CAAI,EAGnC,CAaA,oBAAA,CAAqBT,CAAAA,CAAyC,CAC7D,IAAMkB,CAAAA,CAAQ,KAAK,sBAAA,CAAuBlB,CAAU,EACpD,OAAOkB,CAAAA,CAAQ,EAAI,IAAA,CAAO,IAAA,CAAK,YAAYA,CAAK,CACjD,CAMA,eAAA,CAAgBlB,CAAAA,CAA8C,CAG7D,IAAMkB,EAAQ,IAAA,CAAK,sBAAA,CAAuBlB,CAAU,CAAA,CACpD,GAAIkB,EAAQ,CAAA,CAAG,OACf,IAAMY,CAAAA,CAAY,IAAA,CAAK,YAAYZ,CAAK,CAAA,CACxC,OAAOY,CAAAA,CAAU,UAAA,GAAe9B,EAAa8B,CAAAA,CAAY,MAC1D,CAMA,iBAAA,EAA6C,CAC5C,OAAO,IAAA,CAAK,WACb,CA8CA,oBAAA,CAAqBrB,EAAcT,CAAAA,CAAiD,CACnF,IAAMkB,CAAAA,CAAQ,IAAA,CAAK,uBAAuBlB,CAAAA,CAAa,CAAC,EACpDY,CAAAA,CAAkCM,CAAAA,CAAQ,EAAI,IAAA,CAAO,IAAA,CAAK,WAAA,CAAYA,CAAK,EAC/E,KAAON,CAAAA,EAAY,CAClB,GAAI,MAAA,CAAO,UAAU,cAAA,CAAe,IAAA,CAAKA,EAAW,SAAA,CAAWH,CAAI,EAClE,OAAOG,CAAAA,CAAW,UAAUH,CAAI,CAAA,CAEjCG,EAAaA,CAAAA,CAAW,OACzB,CAED,CAEA,qBAAqBH,CAAAA,CAAcT,CAAAA,CAAuC,CACzE,IAAMkB,CAAAA,CAAQ,KAAK,sBAAA,CAAuBlB,CAAAA,CAAa,CAAC,CAAA,CACpDY,CAAAA,CAAkCM,EAAQ,CAAA,CAAI,IAAA,CAAO,KAAK,WAAA,CAAYA,CAAK,EAC/E,KAAON,CAAAA,EAAY,CAClB,GAAI,OAAO,SAAA,CAAU,cAAA,CAAe,KAAKA,CAAAA,CAAW,SAAA,CAAWH,CAAI,CAAA,CAClE,OAAOG,EAAW,SAAA,CAAUH,CAAI,EAEjCG,CAAAA,CAAaA,CAAAA,CAAW,OACzB,CAED,CAEA,eAAeH,CAAAA,CAAiC,CAC/C,GAAI,IAAA,CAAK,YAAY,MAAA,GAAW,CAAA,CAAG,OAEnC,IAAIG,CAAAA,CAAkC,KAAK,WAAA,CAAY,IAAA,CAAK,YAAY,MAAA,CAAS,CAAC,EAClF,KAAOA,CAAAA,EAAY,CAClB,GAAI,MAAA,CAAO,UAAU,cAAA,CAAe,IAAA,CAAKA,CAAAA,CAAW,SAAA,CAAWH,CAAI,CAAA,CAClE,OAAOG,EAAW,SAAA,CAAUH,CAAI,EAEjCG,CAAAA,CAAaA,CAAAA,CAAW,OACzB,CAED,CAQA,OAAc,CACb,IAAA,CAAK,YAAc,GACpB,CAGA,IAAI,KAAA,EAAgB,CACnB,OAAO,KAAK,WAAA,CAAY,MACzB,CAGA,IAAI,OAAA,EAAmB,CACtB,OAAO,IAAA,CAAK,YAAY,MAAA,GAAW,CACpC,CAGA,IAAI,UAAA,EAAiB,CACpB,OAAO,IAAA,CAAK,EACb,CACD","file":"chunk-X2QJE3SV.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 * @param functionNames Which of those names the line defined as functions,\n\t * from the bytecode it ran. Without it the VM is asked, which cannot tell\n\t * a line that defined `f` from one that set the variable `f` under a\n\t * function of that name defined above.\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\tfunctionNames?: ReadonlySet<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 bag its line wrote (see VMCheckpoint.functions's doc comment for\n\t\t// why this dispatch is required, not optional). A name can be bound\n\t\t// in both bags at once, `f(x) = x + 1` above `:f = 4`, so the caller\n\t\t// says which names it defined as functions; only without that is the\n\t\t// VM asked, and it answers for the function whichever line ran.\n\t\tfor (const name of variableNames) {\n\t\t\tconst isFunction = functionNames !== undefined ? functionNames.has(name) : this.vm.hasUserFunction(name);\n\t\t\tif (isFunction) {\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\t/**\n\t * Drop the entry a line holds, because the line no longer writes anything.\n\t *\n\t * A line's entry is replaced when the line writes again and left alone\n\t * otherwise, so a definition edited into an expression with no definition in\n\t * it (`:v3 = 44` edited to `7 + 7`) kept saying `v3 = 44` in the chain. The\n\t * lines below it that asked what the prefix holds were told 44, where a pass\n\t * from scratch has nothing there. The entry after it is re-parented to the\n\t * one before, the same way {@link snapshot} keeps the links straight.\n\t *\n\t * @param lineNumber - 1-based line whose entry, if any, goes.\n\t */\n\tdropCheckpointAt(lineNumber: number): void {\n\t\tconst index = this.indexOfCheckpointAt(lineNumber);\n\t\tif (index < 0) return;\n\t\tthis.checkpoints.splice(index, 1);\n\t\tconst next = this.checkpoints[index];\n\t\tif (next !== undefined) next.parent = index > 0 ? this.checkpoints[index - 1] : null;\n\t}\n\n\t/**\n\t * Follow every line to its new position after a structural edit.\n\t *\n\t * An insert or a delete moves every line below it, and the chain is read\n\t * by position. It used to be cleared instead and rebuilt as lines ran, but\n\t * a clean line above the viewport never runs, so its entry was gone for\n\t * good and a line below asking what the prefix held was told nothing:\n\t * `:a = 5` above the viewport was reported as undefined by `:b = a + c`\n\t * under it. Each entry follows its line by id, the entry of a deleted\n\t * line goes, and the parents are linked again in the new order.\n\t *\n\t * @param positionOf - The 1-based position a line id has now, or -1 for a line that is gone.\n\t */\n\trenumber(positionOf: (lineId: number) => number): void {\n\t\tconst kept: VMCheckpoint[] = [];\n\t\tfor (const checkpoint of this.checkpoints) {\n\t\t\tconst position = positionOf(checkpoint.lineId);\n\t\t\tif (position < 1) continue;\n\t\t\tcheckpoint.lineNumber = position;\n\t\t\tkept.push(checkpoint);\n\t\t}\n\t\tkept.sort((a, b) => a.lineNumber - b.lineNumber);\n\t\tfor (let i = 0; i < kept.length; i++) kept[i].parent = i > 0 ? kept[i - 1] : null;\n\t\tthis.checkpoints = kept;\n\t}\n\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\t/**\n\t * The value a name held at the end of the line before `lineNumber`, or\n\t * undefined if no line above it had set one.\n\t *\n\t * What a definition that failed leaves behind. A pass from scratch skips\n\t * the store when the right-hand side errors, so the name keeps whatever the\n\t * lines above it had put there: `:x = 1` then `:x = zz` leaves `x` at 1,\n\t * and `:x = zz` on its own leaves it undefined. The incremental path holds\n\t * the value from the previous pass instead, which for the line that failed\n\t * is its own old answer, so the evaluator asks here what the prefix holds\n\t * and puts that back. The chain records what each line wrote, in document\n\t * order, so the entry nearest before the line, followed through its\n\t * parents, is exactly the prefix.\n\t *\n\t * @param name - The variable.\n\t * @param lineNumber - The 1-based line whose own entry is to be excluded.\n\t * @returns The value the lines above set, or undefined.\n\t */\n\t/**\n\t * The function a name was bound to at the end of the line before\n\t * `lineNumber`, or undefined if no line above it had defined one.\n\t *\n\t * {@link lookupVariableBefore}, for the functions bag: a function\n\t * definition is a definition, and one edited away or failed leaves the name\n\t * as the lines above left it just as a variable does.\n\t *\n\t * @param name - The function name.\n\t * @param lineNumber - The 1-based line whose own entry is to be excluded.\n\t * @returns The definition the lines above made, or undefined.\n\t */\n\tlookupFunctionBefore(name: string, lineNumber: number): UserFunctionDef | undefined {\n\t\tconst index = this.nearestCheckpointIndex(lineNumber - 1);\n\t\tlet checkpoint: VMCheckpoint | null = index < 0 ? null : this.checkpoints[index];\n\t\twhile (checkpoint) {\n\t\t\tif (Object.prototype.hasOwnProperty.call(checkpoint.functions, name)) {\n\t\t\t\treturn checkpoint.functions[name];\n\t\t\t}\n\t\t\tcheckpoint = checkpoint.parent;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\tlookupVariableBefore(name: string, lineNumber: number): Value | undefined {\n\t\tconst index = this.nearestCheckpointIndex(lineNumber - 1);\n\t\tlet checkpoint: VMCheckpoint | null = index < 0 ? null : this.checkpoints[index];\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\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"]}