solve-engine 1.0.1 → 1.1.0

package/dist/{chunk-V5PYO44Y.js → chunk-JIPATHVY.js}

@@ -1,20 +1,24 @@
-import { ParseletRegistry, PrecedenceParser } from './chunk-3LAEG75D.js';
+import { ParseletRegistry, PrecedenceParser } from './chunk-I4GAWIPW.js';
 import { ResolverRegistry } from './chunk-3VGDNEE3.js';
-import { abortLogger, djb2Hash } from './chunk-IF532O7C.js';
-import { executeBytecode, createVM, DependencyGraph, ScopeManager } from './chunk-5WVP4YHP.js';
-import { DiagnosticPipeline, TimelineDiagnosticCollector, DiagnosticEventType } from './chunk-G535KJEG.js';
-import { BUILTIN_PACKAGES, containsSymbolicCall } from './chunk-HMOISHXR.js';
-import { BytecodeBuilder } from './chunk-526PMQOA.js';
-import { TokenNormalizer, BUILTIN_PHRASES, implicitMultiplyRule } from './chunk-YPPPYLSR.js';
+import { abortLogger } from './chunk-FD5ZZHEU.js';
+import { executeBytecode, createVM, DependencyGraph, ScopeManager } from './chunk-WXEHD6TT.js';
+import { DiagnosticPipeline, TimelineDiagnosticCollector, DiagnosticEventType } from './chunk-CCBZZQAE.js';
+import { formatValue, DEFAULT_FORMATTING_SETTINGS } from './chunk-3OWCDIPN.js';
+import { BUILTIN_PACKAGES, containsSymbolicCall } from './chunk-RRLHC37V.js';
+import { BytecodeBuilder } from './chunk-ENKKJYD3.js';
+import { TokenNormalizer, BUILTIN_PHRASES, implicitMultiplyRule } from './chunk-JJIXHXFQ.js';
 import { countLines } from './chunk-3BOK2LDK.js';
 import { createQueryClient, setActiveQueryClient, getActiveQueryClient } from './chunk-NLNDMWZC.js';
-import { sharedOpRegistry, createEngineContext, registerAsConverter, unregisterAsConverter, solveEquationValues, globalDagKey, sharedGlobalVariableStore } from './chunk-Y7FT4IQT.js';
-import { matrixMultiply, inverse } from './chunk-O3ANBHSA.js';
-import { pendingValue, errorValue, stringValue, numberValue, freezeIfDev, boolValue, uomValue, percentageValue, datetimeValue, bigIntValue, hexValue, enableValueArena, disableValueArena } from './chunk-GQCOSXMG.js';
-import { mergeEngineConfig, DEFAULT_CONFIG, ENGINE_VERSION } from './chunk-TBN7DEHO.js';
-import { Lexer, buildTokenLookup, sharedLexer } from './chunk-5F4C26RU.js';
-import { registerTokenCategory, unregisterTokenCategory } from './chunk-AJA6LUI7.js';
-import { normalizeUnknownError, ErrorFactory, EngineError } from './chunk-3D7V24DG.js';
+import { sharedOpRegistry, createEngineContext, registerAsConverter, unregisterAsConverter, solveEquationValues, globalDagKey } from './chunk-NKW7LKYU.js';
+import { matrixMultiply, inverse } from './chunk-NNQ2TYDF.js';
+import { errorValue, pendingValue, stringValue, numberValue, freezeIfDev, Value, boolValue, uomValue, percentageValue, datetimeValue, bigIntValue, hexValue, ValueType } from './chunk-267JPOTF.js';
+import { mergeEngineConfig, DEFAULT_CONFIG, ENGINE_VERSION } from './chunk-G7Z4HJQA.js';
+import { Lexer, buildTokenLookup, sharedLexer } from './chunk-OADDUPT3.js';
+import { registerTokenCategory, unregisterTokenCategory } from './chunk-UO6BUV6K.js';
+import { LexerToken } from './chunk-GQMUHVE3.js';
+import { TokenTypes, tokenTypeId } from './chunk-4D6NIHE2.js';
+import { getLocale } from './chunk-XBTEO4OB.js';
+import { normalizeUnknownError, ErrorFactory, EngineError } from './chunk-ERCOHGXD.js';
 import { __commonJS, __toESM } from './chunk-YLJ4XMA6.js';
 
 // node_modules/semver/internal/constants.js
@@ -1965,106 +1969,41 @@ var require_semver2 = __commonJS({
   }
 });
 
-// src/cache/LineCache.ts
-var LineCacheEntry = class {
-  constructor(result, bytecode, readVariables, writeVariable) {
-    this.result = result;
-    this.bytecode = bytecode;
-    this.readVariables = readVariables;
-    this.writeVariable = writeVariable;
-  }
-};
-var LineCache = class _LineCache {
-  constructor() {
-    /** line number → (expression, or "" for expressionless entries) → entry */
-    this.byLine = /* @__PURE__ */ new Map();
-    this.count = 0;
-  }
-  static exprKey(expression) {
-    return expression ?? "";
-  }
-  static displayKey(line, exprKey) {
-    return exprKey === "" ? `${line}` : `${line}:${exprKey}`;
-  }
-  get(line, expression) {
-    return this.byLine.get(line)?.get(_LineCache.exprKey(expression));
-  }
-  /** Find any cache entry for the given line number, regardless of expression suffix */
-  getEntryForLine(line) {
-    const entries = this.byLine.get(line);
-    if (!entries) return void 0;
-    for (const entry of entries.values()) {
-      return entry;
-    }
-    return void 0;
-  }
-  set(line, entry, expression) {
-    let entries = this.byLine.get(line);
-    if (!entries) {
-      entries = /* @__PURE__ */ new Map();
-      this.byLine.set(line, entries);
-    }
-    const key = _LineCache.exprKey(expression);
-    if (entries.size > 0 && !entries.has(key)) {
-      this.count -= entries.size;
-      entries.clear();
-    }
-    if (!entries.has(key)) this.count++;
-    entries.set(key, entry);
-  }
-  has(line, expression) {
-    return this.byLine.get(line)?.has(_LineCache.exprKey(expression)) ?? false;
-  }
-  remove(line, expression) {
-    const entries = this.byLine.get(line);
-    if (!entries) return;
-    if (entries.delete(_LineCache.exprKey(expression))) {
-      this.count--;
-      if (entries.size === 0) this.byLine.delete(line);
-    }
-  }
-  removeAllForLine(line) {
-    const entries = this.byLine.get(line);
-    if (!entries) return;
-    this.count -= entries.size;
-    this.byLine.delete(line);
-  }
-  clearLine(line) {
-    this.removeAllForLine(line);
-  }
-  /**
-   * Number of entries in the cache. Useful for diagnostics.
-   */
-  get size() {
-    return this.count;
-  }
-  clear() {
-    this.byLine.clear();
-    this.count = 0;
+// src/api/EngineVersionCompatibility.ts
+var import_semver = __toESM(require_semver2(), 1);
+function checkEngineVersionCompatibility(pkg, engineVersion = ENGINE_VERSION) {
+  if (!pkg.engineVersion) return { compatible: true };
+  if ((0, import_semver.validRange)(pkg.engineVersion) === null) {
+    return { compatible: false, reason: "invalid-range", declaredRange: pkg.engineVersion, engineVersion };
   }
-  /**
-   * Iterate all cache entries for diagnostics/debugging.
-   */
-  forEach(callback) {
-    for (const [line, entries] of this.byLine) {
-      for (const [exprKey, entry] of entries) {
-        callback(_LineCache.displayKey(line, exprKey), entry);
-      }
-    }
+  const comparableVersion = (0, import_semver.coerce)(engineVersion)?.version ?? engineVersion;
+  if (!(0, import_semver.satisfies)(comparableVersion, pkg.engineVersion)) {
+    return { compatible: false, reason: "range-not-satisfied", declaredRange: pkg.engineVersion, engineVersion };
   }
-  /**
-   * Get all entry keys.
-   */
-  keys() {
-    const result = [];
-    for (const [line, entries] of this.byLine) {
-      for (const exprKey of entries.keys()) {
-        result.push(_LineCache.displayKey(line, exprKey));
-      }
-    }
-    return result;
+  return { compatible: true };
+}
+function assertEngineVersionCompatible(pkg, engineVersion = ENGINE_VERSION) {
+  const result = checkEngineVersionCompatibility(pkg, engineVersion);
+  if (result.compatible) return;
+  if (result.reason === "invalid-range") {
+    throw ErrorFactory.config({
+      code: "PACKAGE_ENGINE_VERSION_INVALID_RANGE",
+      message: `Package "${pkg.name}" declares an invalid engineVersion range: "${result.declaredRange}" is not a valid semver range.`,
+      expected: `a valid semver range string (e.g. "^0.1.0", ">=0.2.0 <1.0.0")`,
+      found: `"${result.declaredRange}"`,
+      suggestion: `This is a range-syntax typo in "${pkg.name}"'s own descriptor, not a version mismatch with the running engine \u2014 check for a stray character.`,
+      context: { packageName: pkg.name, declaredRange: result.declaredRange }
+    });
   }
-};
+  throw ErrorFactory.config({
+    code: "PACKAGE_ENGINE_VERSION_MISMATCH",
+    message: `Package "${pkg.name}" declares engineVersion "${result.declaredRange}", which is not satisfied by the running engine version "${result.engineVersion}".`,
+    expected: `an engine version satisfying "${result.declaredRange}"`,
+    found: `engine version "${result.engineVersion}"`,
+    suggestion: `Update "${pkg.name}" to a version built against solve-engine ${result.engineVersion}, or pin solve-engine to a version satisfying "${result.declaredRange}".`,
+    context: { packageName: pkg.name, declaredRange: result.declaredRange, engineVersion: result.engineVersion }
+  });
+}
 
 // src/api/PackageCompatibility.ts
 function collectParseletConflicts(kind, fieldName, existingPkg, candidate, out) {
@@ -2200,858 +2139,364 @@ function checkPackageCompatibility(candidate, existing) {
   };
 }
 
-// src/api/EngineVersionCompatibility.ts
-var import_semver = __toESM(require_semver2(), 1);
-function checkEngineVersionCompatibility(pkg, engineVersion = ENGINE_VERSION) {
-  if (!pkg.engineVersion) return { compatible: true };
-  if ((0, import_semver.validRange)(pkg.engineVersion) === null) {
-    return { compatible: false, reason: "invalid-range", declaredRange: pkg.engineVersion, engineVersion };
-  }
-  const comparableVersion = (0, import_semver.coerce)(engineVersion)?.version ?? engineVersion;
-  if (!(0, import_semver.satisfies)(comparableVersion, pkg.engineVersion)) {
-    return { compatible: false, reason: "range-not-satisfied", declaredRange: pkg.engineVersion, engineVersion };
-  }
-  return { compatible: true };
+// src/engine/EngineSnapshot.ts
+var SNAPSHOT_FORMAT = "solve-engine/snapshot";
+var SNAPSHOT_VERSION = 1;
+function encodeNumber(n) {
+  if (Number.isFinite(n)) return n;
+  if (Number.isNaN(n)) return "NaN";
+  return n > 0 ? "Infinity" : "-Infinity";
 }
-function assertEngineVersionCompatible(pkg, engineVersion = ENGINE_VERSION) {
-  const result = checkEngineVersionCompatibility(pkg, engineVersion);
-  if (result.compatible) return;
-  if (result.reason === "invalid-range") {
-    throw ErrorFactory.config({
-      code: "PACKAGE_ENGINE_VERSION_INVALID_RANGE",
-      message: `Package "${pkg.name}" declares an invalid engineVersion range: "${result.declaredRange}" is not a valid semver range.`,
-      expected: `a valid semver range string (e.g. "^0.1.0", ">=0.2.0 <1.0.0")`,
-      found: `"${result.declaredRange}"`,
-      suggestion: `This is a range-syntax typo in "${pkg.name}"'s own descriptor, not a version mismatch with the running engine \u2014 check for a stray character.`,
-      context: { packageName: pkg.name, declaredRange: result.declaredRange }
-    });
-  }
-  throw ErrorFactory.config({
-    code: "PACKAGE_ENGINE_VERSION_MISMATCH",
-    message: `Package "${pkg.name}" declares engineVersion "${result.declaredRange}", which is not satisfied by the running engine version "${result.engineVersion}".`,
-    expected: `an engine version satisfying "${result.declaredRange}"`,
-    found: `engine version "${result.engineVersion}"`,
-    suggestion: `Update "${pkg.name}" to a version built against solve-engine ${result.engineVersion}, or pin solve-engine to a version satisfying "${result.declaredRange}".`,
-    context: { packageName: pkg.name, declaredRange: result.declaredRange, engineVersion: result.engineVersion }
+function decodeNumber(n) {
+  if (typeof n === "number") return n;
+  if (n === "NaN") return NaN;
+  if (n === "Infinity") return Infinity;
+  if (n === "-Infinity") return -Infinity;
+  throw ErrorFactory.validation({
+    code: SnapshotErrorCodes.SNAPSHOT_MALFORMED,
+    message: `Snapshot holds an unrecognised number sentinel: ${JSON.stringify(n)}`,
+    expected: `a JSON number, or one of "NaN", "Infinity", "-Infinity"`,
+    found: JSON.stringify(n)
   });
 }
-
-// src/workers/engine.worker.ts
-var engine_worker_default = (() => {
-  throw new Error("engine.worker.ts was not processed by esbuild-plugin-inline-worker, so worker offload is unavailable");
-});
-var compileEngine = null;
-function getCompileEngine() {
-  if (!compileEngine) {
-    compileEngine = new ExpressionEngine("en", false);
+var SnapshotErrorCodes = {
+  /** The object handed to `fromJSON` is not a snapshot at all, or its version does not match this engine's reader. */
+  SNAPSHOT_VERSION_MISMATCH: "SNAPSHOT_VERSION_MISMATCH",
+  /** A snapshot with the right envelope but internally inconsistent contents (a bad number sentinel, a missing field). */
+  SNAPSHOT_MALFORMED: "SNAPSHOT_MALFORMED",
+  /** A value the snapshot format cannot yet represent (a symbolic expression, a symbolic matrix cell). Deferred, see the module doc. */
+  SNAPSHOT_UNSUPPORTED_VALUE: "SNAPSHOT_UNSUPPORTED_VALUE"
+};
+function serializeDecimal(d) {
+  return { coef: d.coef.toString(), scale: d.scale };
+}
+function deserializeDecimal(d) {
+  return { coef: BigInt(d.coef), scale: d.scale };
+}
+function serializeRational(r) {
+  return { n: r.n.toString(), d: r.d.toString() };
+}
+function deserializeRational(r) {
+  return { n: BigInt(r.n), d: BigInt(r.d) };
+}
+function valueTypeName(type) {
+  return ValueType[type] ?? String(type);
+}
+function unsupportedValue(type, where) {
+  throw ErrorFactory.validation({
+    code: SnapshotErrorCodes.SNAPSHOT_UNSUPPORTED_VALUE,
+    message: `A ${valueTypeName(type)} value (${where}) cannot be included in a snapshot yet.`,
+    expected: "a concrete number, string, boolean, unit, range, matrix, bigint, or money value",
+    found: `${valueTypeName(type)} value`,
+    suggestion: "Symbolic (algebra) values are deferred to a follow-up. Evaluate the document without the symbolic line, or re-derive it after restoring.",
+    context: { valueType: type, location: where }
+  });
+}
+function serializeValue(value, where) {
+  switch (value.type) {
+    case 0 /* Number */: {
+      const out = { t: 0 /* Number */, v: encodeNumber(value.value) };
+      if (value.exact !== void 0) out.exact = serializeDecimal(value.exact);
+      if (value.rational !== void 0) out.rational = serializeRational(value.rational);
+      return out;
+    }
+    case 1 /* Hex */: {
+      const raw = value.value;
+      if (typeof raw === "bigint") {
+        return { t: 1 /* Hex */, v: raw.toString(), big: true, base: value.unit };
+      }
+      return { t: 1 /* Hex */, v: encodeNumber(raw), base: value.unit };
+    }
+    case 2 /* BigInt */:
+      return { t: 2 /* BigInt */, v: value.value.toString() };
+    case 3 /* String */:
+      return { t: 3 /* String */, v: value.value };
+    case 4 /* Datetime */:
+      return { t: 4 /* Datetime */, v: encodeNumber(value.value) };
+    case 5 /* Percentage */:
+      return { t: 5 /* Percentage */, v: encodeNumber(value.value) };
+    case 6 /* Uom */: {
+      const out = { t: 6 /* Uom */, v: encodeNumber(value.value), unit: value.unit ?? "" };
+      if (value.exact !== void 0) out.exact = serializeDecimal(value.exact);
+      return out;
+    }
+    case 7 /* Matrix */: {
+      const m = value.value;
+      if (m.hasSymbolic) unsupportedValue(9 /* Symbolic */, `${where} (symbolic matrix cell)`);
+      const data = m.data.map((cell) => serializeMatrixCell(cell, where));
+      return { t: 7 /* Matrix */, rows: m.rows, cols: m.cols, data };
+    }
+    case 8 /* Range */: {
+      const r = value.value;
+      return { t: 8 /* Range */, min: encodeNumber(r.min), max: encodeNumber(r.max) };
+    }
+    case 10 /* Boolean */:
+      return { t: 10 /* Boolean */, v: value.value };
+    case 13 /* Error */:
+      return { t: 13 /* Error */, code: value.value, message: value.unit ?? "" };
+    default:
+      return unsupportedValue(value.type, where);
   }
-  return compileEngine;
 }
-var executeVm = null;
-function getExecuteVm() {
-  if (!executeVm) {
-    executeVm = createVM(sharedOpRegistry, 200, 5e4);
+function serializeMatrixCell(cell, where) {
+  if (typeof cell === "boolean") return cell;
+  if (typeof cell === "number") return encodeNumber(cell);
+  return unsupportedValue(9 /* Symbolic */, `${where} (symbolic matrix cell)`);
+}
+function deserializeValue(sv) {
+  switch (sv.t) {
+    case 0 /* Number */: {
+      const v = new Value(0 /* Number */, decodeNumber(sv.v));
+      if (sv.exact !== void 0) v.exact = deserializeDecimal(sv.exact);
+      if (sv.rational !== void 0) v.rational = deserializeRational(sv.rational);
+      return v;
+    }
+    case 1 /* Hex */: {
+      const value = sv.big ? BigInt(sv.v) : decodeNumber(sv.v);
+      return new Value(1 /* Hex */, value, sv.base);
+    }
+    case 2 /* BigInt */:
+      return new Value(2 /* BigInt */, BigInt(sv.v));
+    case 3 /* String */:
+      return new Value(3 /* String */, sv.v);
+    case 4 /* Datetime */:
+      return new Value(4 /* Datetime */, decodeNumber(sv.v));
+    case 5 /* Percentage */:
+      return new Value(5 /* Percentage */, decodeNumber(sv.v));
+    case 6 /* Uom */: {
+      const v = new Value(6 /* Uom */, decodeNumber(sv.v), sv.unit);
+      if (sv.exact !== void 0) v.exact = deserializeDecimal(sv.exact);
+      return v;
+    }
+    case 7 /* Matrix */: {
+      const data = sv.data.map((cell) => typeof cell === "boolean" ? cell : decodeNumber(cell));
+      const m = { rows: sv.rows, cols: sv.cols, data, hasSymbolic: false };
+      return new Value(7 /* Matrix */, m);
+    }
+    case 8 /* Range */:
+      return new Value(8 /* Range */, { min: decodeNumber(sv.min), max: decodeNumber(sv.max) });
+    case 10 /* Boolean */:
+      return new Value(10 /* Boolean */, sv.v);
+    case 13 /* Error */:
+      return new Value(13 /* Error */, sv.code, sv.message);
+    default:
+      throw ErrorFactory.validation({
+        code: SnapshotErrorCodes.SNAPSHOT_MALFORMED,
+        message: `Snapshot holds a value with an unknown type tag: ${JSON.stringify(sv.t)}`,
+        expected: "a known SerializedValue type tag",
+        found: JSON.stringify(sv.t)
+      });
   }
-  return executeVm;
 }
-function compileOne(item) {
-  const base = {
-    lineId: item.lineId,
-    expression: item.expression,
-    compiledAgainstHash: item.textHash,
-    strings: [],
-    reads: [],
-    writes: [],
-    isVariableDef: false,
-    error: null
+function serializeBytecode(program) {
+  const out = {
+    opcodes: Array.from(program.opcodes),
+    numbers: Array.from(program.numbers, encodeNumber),
+    strings: program.strings.slice(),
+    hasAsync: program.hasAsync
   };
-  try {
-    const eng = getCompileEngine();
-    const { program, reads, writes } = eng.compileExpression(item.expression);
-    const isVariableDef = writes.length > 0;
-    const opcodes = program.opcodes;
-    const numbers = program.numbers;
-    const opcodesBuffer = opcodes.buffer.slice(
-      opcodes.byteOffset,
-      opcodes.byteOffset + opcodes.byteLength
-    );
-    const numbersBuffer = numbers.buffer.slice(
-      numbers.byteOffset,
-      numbers.byteOffset + numbers.byteLength
-    );
-    return {
-      ...base,
-      opcodesBuffer,
-      numbersBuffer,
-      opcodesLength: opcodes.length,
-      numbersLength: numbers.length,
-      strings: [...program.strings],
-      reads,
-      writes,
-      isVariableDef
-    };
-  } catch (e) {
-    return {
-      ...base,
-      opcodesBuffer: new ArrayBuffer(0),
-      numbersBuffer: new ArrayBuffer(0),
-      opcodesLength: 0,
-      numbersLength: 0,
-      error: e instanceof Error ? e.message : String(e)
-    };
+  if (program.constants) out.constants = Array.from(program.constants.entries());
+  if (program.userFunctionBodies) out.userFunctionBodies = program.userFunctionBodies.map(serializeUserFunction);
+  if (program.anonymousBodies) {
+    out.anonymousBodies = program.anonymousBodies.map((b) => ({ params: b.params.slice(), program: serializeBytecode(b.program) }));
   }
+  return out;
 }
-function handleCompileBatch(msg) {
-  const results = [];
-  const transferList = [];
-  for (const item of msg.items) {
-    const result = compileOne(item);
-    results.push(result);
-    if (result.opcodesBuffer.byteLength > 0) transferList.push(result.opcodesBuffer);
-    if (result.numbersBuffer.byteLength > 0) transferList.push(result.numbersBuffer);
+function deserializeBytecode(sb) {
+  const program = {
+    opcodes: Uint8Array.from(sb.opcodes),
+    numbers: Float64Array.from(sb.numbers, decodeNumber),
+    strings: sb.strings.slice(),
+    hasAsync: sb.hasAsync
+  };
+  if (sb.constants) program.constants = new Map(sb.constants);
+  if (sb.userFunctionBodies) program.userFunctionBodies = sb.userFunctionBodies.map(deserializeUserFunction);
+  if (sb.anonymousBodies) {
+    program.anonymousBodies = sb.anonymousBodies.map((b) => ({ params: b.params.slice(), program: deserializeBytecode(b.program) }));
   }
-  self.postMessage(
-    { id: msg.id, type: "COMPILE_RESULT", results },
-    transferList
-  );
+  return program;
 }
-function executeOne(item) {
-  const vmm = getExecuteVm();
-  vmm.reset();
-  const opcodes = new Uint8Array(item.opcodesBuffer, 0, item.opcodesLength);
-  const numbers = new Float64Array(item.numbersBuffer, 0, item.numbersLength);
-  const bytecode = { opcodes, numbers, strings: item.strings };
-  try {
-    const result = executeBytecode(bytecode, vmm);
-    if (result.type === "pending") {
-      return {
-        lineNumber: item.lineNumber,
-        valueType: 12 /* Pending */,
-        value: 0,
-        isPending: true,
-        queryKey: result.queryKey
-      };
-    }
-    if (result.type === "error") {
-      return {
-        lineNumber: item.lineNumber,
-        valueType: 13 /* Error */,
-        value: 0,
-        isPending: false,
-        unit: result.error.message
-      };
-    }
-    const val = result.value;
-    return {
-      lineNumber: item.lineNumber,
-      valueType: val.type,
-      value: typeof val.value === "number" ? val.value : typeof val.value === "bigint" ? Number(val.value) : 0,
-      unit: val.unit,
-      isPending: false
-    };
-  } catch {
-    return {
-      lineNumber: item.lineNumber,
-      valueType: 13 /* Error */,
-      value: 0,
-      isPending: false,
-      unit: "Worker execution failed"
-    };
-  }
+function serializeUserFunction(fn) {
+  return { name: fn.name, params: fn.params.slice(), program: serializeBytecode(fn.program) };
 }
-function handleExecuteBatch(msg) {
-  const results = [];
-  for (const item of msg.items) {
-    results.push(executeOne(item));
-  }
-  self.postMessage({
-    id: msg.id,
-    type: "EXECUTE_RESULT",
-    results
-  });
+function deserializeUserFunction(fn) {
+  return { name: fn.name, params: fn.params.slice(), program: deserializeBytecode(fn.program) };
 }
-var inWorkerScope = typeof self !== "undefined" && typeof window === "undefined";
-var handleMessage = (event) => {
-  if (event.origin && self.location && event.origin !== self.location.origin) return;
-  const msg = event.data;
-  switch (msg.type) {
-    case "COMPILE_BATCH":
-      handleCompileBatch(msg);
-      break;
-    case "EXECUTE_BATCH":
-      handleExecuteBatch(msg);
-      break;
-    case "TERMINATE": {
-      if (compileEngine) {
-        compileEngine.clear();
-        compileEngine = null;
-      }
-      if (executeVm) {
-        executeVm.reset();
-        executeVm = null;
-      }
-      self.postMessage({
-        id: msg.id,
-        type: "COMPILE_RESULT",
-        results: []
-      });
-      break;
-    }
-    default: {
-      self.postMessage({
-        id: -1,
-        type: "COMPILE_RESULT",
-        results: [],
-        error: `Unknown message type: ${msg.type}`
-      });
-    }
+function assertRestorable(snapshot) {
+  if (typeof snapshot !== "object" || snapshot === null) {
+    throw ErrorFactory.validation({
+      code: SnapshotErrorCodes.SNAPSHOT_VERSION_MISMATCH,
+      message: "fromJSON was given something that is not a snapshot object.",
+      expected: `an object produced by ExpressionEngine.toJSON() with format "${SNAPSHOT_FORMAT}"`,
+      found: snapshot === null ? "null" : typeof snapshot
+    });
   }
-};
-if (inWorkerScope) {
-  self.onmessage = handleMessage;
-}
-
-// src/engine/ExecutionPool.ts
-var WORKER_BATCH_TIMEOUT_MS = 3e4;
-var WORKER_OFFLOAD_THRESHOLD = 50;
-var ExecutionPool = class {
-  constructor(poolSize) {
-    this.workers = [];
-    this.nextWorker = 0;
-    this.nextId = 1;
-    this.pendingBatches = /* @__PURE__ */ new Map();
-    this.terminated = false;
-    // ── Public API ────────────────────────────────────────────────────────
-    /** Cached availability flag. Checked once; createExecutionWorker never called again. */
-    this._available = null;
-    this.poolSize = Math.min(poolSize ?? this.defaultPoolSize(), 4);
+  const candidate = snapshot;
+  if (candidate.format !== SNAPSHOT_FORMAT) {
+    throw ErrorFactory.validation({
+      code: SnapshotErrorCodes.SNAPSHOT_VERSION_MISMATCH,
+      message: `This object is not a solve-engine snapshot (its "format" is ${JSON.stringify(candidate.format)}).`,
+      expected: `format "${SNAPSHOT_FORMAT}"`,
+      found: JSON.stringify(candidate.format)
+    });
   }
-  defaultPoolSize() {
-    if (typeof navigator !== "undefined" && navigator.hardwareConcurrency) {
-      return Math.min(navigator.hardwareConcurrency, 4);
-    }
-    return 2;
+  if (candidate.version !== SNAPSHOT_VERSION) {
+    throw ErrorFactory.validation({
+      code: SnapshotErrorCodes.SNAPSHOT_VERSION_MISMATCH,
+      message: `This snapshot was written for format version ${candidate.version}, but this engine restores version ${SNAPSHOT_VERSION}.`,
+      expected: `snapshot version ${SNAPSHOT_VERSION}`,
+      found: `version ${candidate.version}`,
+      suggestion: "Regenerate the snapshot with a matching engine version, or re-evaluate the document from source.",
+      context: { snapshotVersion: candidate.version, readerVersion: SNAPSHOT_VERSION, engineVersion: candidate.engineVersion }
+    });
   }
-  /**
-   * Whether worker-based execution is available.
-   * Returns false in Node.js / jsdom test environments where Worker
-   * may be polyfilled but execution workers aren't functional.
-   */
-  isAvailable() {
-    if (this.terminated) return false;
-    if (this._available !== null) return this._available;
-    if (typeof Worker === "undefined") {
-      this._available = false;
-      return false;
-    }
-    try {
-      const w = engine_worker_default();
-      w.terminate();
-      this._available = true;
-      return true;
-    } catch {
-      this._available = false;
-      return false;
-    }
+}
+
+// src/cache/LineCache.ts
+var LineCacheEntry = class {
+  constructor(result, bytecode, readVariables, writeVariable) {
+    this.result = result;
+    this.bytecode = bytecode;
+    this.readVariables = readVariables;
+    this.writeVariable = writeVariable;
   }
-  /**
-   * Execute a batch of line entries via the worker pool.
-   *
-   * Takes ordered line numbers and their LineCache entries. Clones bytecode
-   * ArrayBuffers for transfer, dispatches to workers round-robin, and
-   * returns the serialized results (with 30s timeout fallback).
-   *
-   * Falls back to undefined when workers are unavailable, caller should
-   * use the main-thread path.
-   *
-   * @returns ExecuteResult[] on success, undefined if workers unavailable.
-   */
-  executeBatch(orderedLineNumbers, entries) {
-    if (!this.isAvailable()) return void 0;
-    if (orderedLineNumbers.length === 0) return Promise.resolve([]);
-    this.ensureWorkers();
-    const items = [];
-    for (const lineNumber of orderedLineNumbers) {
-      const entry = entries.get(lineNumber);
-      if (!entry || entry.bytecode.opcodes.length === 0) continue;
-      const opcodes = entry.bytecode.opcodes;
-      const numbers = entry.bytecode.numbers;
-      const opcodesClone = opcodes.buffer.slice(
-        opcodes.byteOffset,
-        opcodes.byteOffset + opcodes.byteLength
-      );
-      const numbersClone = numbers.buffer.slice(
-        numbers.byteOffset,
-        numbers.byteOffset + numbers.byteLength
-      );
-      items.push({
-        lineNumber,
-        opcodesBuffer: opcodesClone,
-        numbersBuffer: numbersClone,
-        opcodesLength: opcodes.length,
-        numbersLength: numbers.length,
-        strings: [...entry.bytecode.strings]
-      });
-    }
-    if (items.length === 0) return Promise.resolve([]);
-    const transferList = [];
-    for (const item of items) {
-      if (item.opcodesBuffer.byteLength > 0) transferList.push(item.opcodesBuffer);
-      if (item.numbersBuffer.byteLength > 0) transferList.push(item.numbersBuffer);
-    }
-    const batchId = this.nextId++;
-    const worker = this.getNextWorker();
-    return new Promise((resolve) => {
-      const timeoutId = setTimeout(() => {
-        this.pendingBatches.delete(batchId);
-        resolve([]);
-      }, WORKER_BATCH_TIMEOUT_MS);
-      this.pendingBatches.set(batchId, {
-        id: batchId,
-        lineNumbers: orderedLineNumbers,
-        resolve: (results) => {
-          clearTimeout(timeoutId);
-          resolve(results);
-        }
-      });
-      worker.postMessage(
-        { type: "EXECUTE_BATCH", id: batchId, items },
-        transferList
-      );
-    });
+};
+var LineCache = class _LineCache {
+  constructor() {
+    /** line number → (expression, or "" for expressionless entries) → entry */
+    this.byLine = /* @__PURE__ */ new Map();
+    this.count = 0;
   }
-  /**
-   * Clean up all workers and pending batches. Called on engine clear.
-   * Workers are recreated lazily on next dispatch.
-   */
-  clear() {
-    for (const [, batch] of this.pendingBatches) {
-      batch.resolve([]);
-    }
-    this.pendingBatches.clear();
-    for (const w of this.workers) {
-      w.terminate();
-    }
-    this.workers = [];
-    this.nextWorker = 0;
+  static exprKey(expression) {
+    return expression ?? "";
   }
-  /**
-   * Full teardown. After destroy(), the pool is permanently unusable.
-   */
-  destroy() {
-    this.terminated = true;
-    this.clear();
+  static displayKey(line, exprKey) {
+    return exprKey === "" ? `${line}` : `${line}:${exprKey}`;
   }
-  // ── Private ────────────────────────────────────────────────────────────
-  ensureWorkers() {
-    if (this.workers.length > 0) return;
-    for (let i = 0; i < this.poolSize; i++) {
-      const worker = engine_worker_default();
-      worker.onmessage = (event) => {
-        this.handleWorkerMessage(event.data);
-      };
-      worker.onerror = (err) => {
-        console.error(`[ExecutionPool] Worker ${i} error:`, err.message);
-        for (const [id, batch] of this.pendingBatches) {
-          batch.resolve([]);
-          this.pendingBatches.delete(id);
-        }
-      };
-      this.workers.push(worker);
-    }
-  }
-  getNextWorker() {
-    const w = this.workers[this.nextWorker];
-    this.nextWorker = (this.nextWorker + 1) % this.workers.length;
-    return w;
-  }
-  handleWorkerMessage(data) {
-    if (data.type !== "EXECUTE_RESULT") return;
-    const batch = this.pendingBatches.get(data.id);
-    if (!batch) return;
-    this.pendingBatches.delete(data.id);
-    batch.resolve(data.results);
-  }
-};
-function reconstructValue(result) {
-  switch (result.valueType) {
-    case 0 /* Number */:
-      return numberValue(result.value);
-    case 1 /* Hex */:
-      return hexValue(result.value);
-    case 2 /* BigInt */:
-      return bigIntValue(BigInt(result.value));
-    case 3 /* String */:
-      return stringValue(String(result.value));
-    case 4 /* Datetime */:
-      return datetimeValue(result.value);
-    case 5 /* Percentage */:
-      return percentageValue(result.value);
-    case 6 /* Uom */:
-      return uomValue(result.value, result.unit ?? "");
-    case 7 /* Matrix */:
-      return numberValue(result.value);
-    case 10 /* Boolean */:
-      return boolValue(result.value !== 0);
-    case 12 /* Pending */:
-      return pendingValue(result.queryKey ?? "");
-    case 13 /* Error */:
-      return errorValue("WORKER_EXECUTION_ERROR", result.unit ?? "Unknown worker error");
-    default:
-      return numberValue(result.value);
-  }
-}
-
-// src/engine/AsyncResolutionBatcher.ts
-var _AsyncResolutionBatcher = class _AsyncResolutionBatcher {
-  constructor(dag, lineCache, vm, highWaterMark = _AsyncResolutionBatcher.DEFAULT_HIGH_WATER_MARK) {
-    this.pending = [];
-    this.scheduled = false;
-    /** Set to true by clearPending(), flush() checks this to abort stale work. */
-    this.cleared = false;
-    /**
-     * Worker pool for offloading VM re-execution when the affected line
-     * count exceeds WORKER_OFFLOAD_THRESHOLD (50). Lazily created on
-     * first dispatch; cleared on clearAll().
-     */
-    this.executionPool = null;
-    /**
-     * Number of flushes actually dispatched to the worker pool (as opposed
-     * to falling back to the main thread because Worker is unavailable).
-     * Exposed via {@link workerOffloadCount} for the Workers diagnostic tab.
-     */
-    this.workerOffloadDispatchCount = 0;
-    /**
-     * Controller for the internal event stream. Set during stream
-     * initialization; cleared on stream cancellation or clearAll().
-     */
-    this._streamController = null;
-    /**
-     * Test-only synchronous capture array. When enabled (non-null), every
-     * event is synchronously pushed here in addition to the stream.
-     * Tests read from this array to avoid async stream reader timing issues.
-     */
-    this._testCaptures = null;
-    /**
-     * Called for each line whose result is patched after an async resolution,
-     * on both the main-thread and worker-pool paths.
-     *
-     * **A host that displays async results must set this.** It is the only
-     * mechanism that moves a resolved value out of the LineCache and into the
-     * host's own document state. The engine cannot do it itself: it does not own
-     * a document, the host does, and the batcher has no reference to one.
-     *
-     * Nullable rather than a constructor parameter because it is cleared by
-     * `clearAll()` and re-wired on re-subscribe, so it cannot be readonly. That
-     * makes it easy to miss, which is why {@link warnIfUnwired} exists: leaving
-     * it unset means async values resolve into the cache and are never shown,
-     * with nothing to indicate why. A host that genuinely does not want async
-     * results should not register async resolvers at all.
-     */
-    this.onLineResult = null;
-    /**
-     * Whether {@link warnIfUnwired} has already fired.
-     *
-     * Once per instance, not once per resolution. A document with fifty live
-     * data lines would otherwise produce fifty identical warnings on the first
-     * fetch, which is how a useful warning becomes noise people filter out.
-     */
-    this.warnedAboutMissingHook = false;
-    this.dag = dag;
-    this.lineCache = lineCache;
-    this.vm = vm;
-    this.highWaterMark = highWaterMark;
-    this._eventStream = this.createEventStream();
-  }
-  /**
-   * Warn once if an async result resolved with no {@link onLineResult} wired.
-   *
-   * The failure this catches is silent by nature: the value arrives, the cache
-   * updates, and the line keeps showing pending forever. Without this a host
-   * author has no thread to pull on.
-   */
-  warnIfUnwired() {
-    if (this.onLineResult || this.warnedAboutMissingHook) return;
-    this.warnedAboutMissingHook = true;
-    console.warn(
-      "[solve-engine] An async result resolved but AsyncResolutionBatcher.onLineResult is not set, so the value cannot reach your document and the line will keep showing as pending. Set it to mirror resolved values into your own state. This warning appears once per batcher."
-    );
-  }
-  /**
-   * 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.
-   */
-  createEventStream() {
-    return new ReadableStream({
-      start: (controller) => {
-        this._streamController = controller;
-      },
-      cancel: () => {
-        this._streamController = null;
-      }
-    }, new CountQueuingStrategy({ highWaterMark: this.highWaterMark }));
-  }
-  // ── Public API ────────────────────────────────────────────────────
-  /**
-   * Add a resolved query key to the pending batch.
-   *
-   * Called by ExpressionEngine.resolveAsync() after a promise resolves or errors.
-   * If this is the first entry in the current tick, schedules a microtask flush.
-   */
-  add(entry) {
-    this.cleared = false;
-    for (const existing of this.pending) {
-      if (existing.packageId === entry.packageId && existing.queryKey === entry.queryKey) {
-        return;
-      }
-    }
-    this.pending.push(entry);
-    if (!this.scheduled) {
-      this.scheduled = true;
-      queueMicrotask(() => {
-        try {
-          this.flush();
-        } catch (e) {
-          const engineError = normalizeUnknownError(e);
-          console.error(`[AsyncResolutionBatcher] flush() failed unexpectedly \u2014 this should never happen; please report: ${engineError.format()}`);
-        }
-      });
-    }
-  }
-  /**
-   * Get the native event stream for stream-based consumers.
-   *
-   * Use this for backpressure, cancellation, or the ability
-   * to `pipeTo()` / `pipeThrough()` the event flow.
-   *
-   * @returns A {@link ReadableStream} that emits {@link AsyncResolutionEvent}
-   *          items as the batcher processes async resolutions.
-   */
-  getEventStream() {
-    return this._eventStream;
-  }
-  /** Number of resolutions currently queued for the next flush. */
-  get pendingCount() {
-    return this.pending.length;
-  }
-  /** Number of pending entries collapsed by (packageId, queryKey) deduplication. */
-  get dedupCount() {
-    const dedup = /* @__PURE__ */ new Set();
-    for (const entry of this.pending) {
-      dedup.add(`${entry.packageId}:${entry.queryKey}`);
-    }
-    return Math.max(0, this.pending.length - dedup.size);
-  }
-  /**
-   * Whether the internal event stream currently has an active reader.
-   * `1` if a consumer has called `getEventStream().getReader()` (or
-   * otherwise locked the stream) and not released it, `0` otherwise.
-   */
-  get listenerCount() {
-    return this._eventStream.locked ? 1 : 0;
-  }
-  /** Number of flushes that were actually dispatched to the worker pool. */
-  get workerOffloadCount() {
-    return this.workerOffloadDispatchCount;
-  }
-  /** Remove all listeners and cancel pending batch. Called on engine clear. */
-  clearAll() {
-    this.pending = [];
-    this.scheduled = false;
-    this.cleared = true;
-    this._testCaptures = null;
-    this.onLineResult = null;
-    try {
-      this._streamController?.close();
-    } catch {
-    }
-    this._streamController = null;
-    this._eventStream = this.createEventStream();
-    if (this.executionPool) {
-      this.executionPool.clear();
-      this.executionPool = null;
-    }
-    this.workerOffloadDispatchCount = 0;
-  }
-  // ── Private: flush ────────────────────────────────────────────────
-  /**
-   * Flush all pending resolutions in a single batched pass.
-   *
-   * Called automatically via queueMicrotask. Never called directly.
-   */
-  flush() {
-    this.scheduled = false;
-    if (this.cleared) return;
-    if (this.pending.length === 0) return;
-    const batch = this.pending;
-    this.pending = [];
-    const deduped = /* @__PURE__ */ new Map();
-    for (const entry of batch) {
-      const compositeKey = `${entry.packageId}:${entry.queryKey}`;
-      deduped.set(compositeKey, entry);
-    }
-    const errorEntries = [];
-    const okEntries = [];
-    for (const entry of deduped.values()) {
-      if (entry.isError) {
-        errorEntries.push(entry);
-      } else {
-        okEntries.push(entry);
-      }
-    }
-    for (const entry of errorEntries) {
-      if (entry.signal.aborted) continue;
-      this.notifyListeners({
-        type: "error",
-        queryKey: entry.queryKey,
-        packageId: entry.packageId,
-        error: entry.error ?? new Error("Unknown async resolution error")
-      });
-    }
-    const allAffected = /* @__PURE__ */ new Set();
-    const allQueryKeys = [];
-    const allEntries = [...okEntries, ...errorEntries];
-    for (const entry of allEntries) {
-      if (entry.signal.aborted) continue;
-      allQueryKeys.push(entry.queryKey);
-      const affected = this.dag.getAffectedLinesByDataSource(
-        entry.packageId,
-        [entry.queryKey]
-      );
-      for (const line of affected) {
-        allAffected.add(line);
-      }
+  get(line, expression) {
+    return this.byLine.get(line)?.get(_LineCache.exprKey(expression));
+  }
+  /** Find any cache entry for the given line number, regardless of expression suffix */
+  getEntryForLine(line) {
+    const entries = this.byLine.get(line);
+    if (!entries) return void 0;
+    for (const entry of entries.values()) {
+      return entry;
     }
-    if (allAffected.size === 0) {
-      this.notifyListeners({
-        type: "lines-updated",
-        lineNumbers: [],
-        affectedQueryKeys: allQueryKeys
-      });
-      return;
+    return void 0;
+  }
+  set(line, entry, expression) {
+    let entries = this.byLine.get(line);
+    if (!entries) {
+      entries = /* @__PURE__ */ new Map();
+      this.byLine.set(line, entries);
     }
-    const ordered = this.topologicalSort(Array.from(allAffected));
-    if (ordered.length > WORKER_OFFLOAD_THRESHOLD) {
-      const entryMap = /* @__PURE__ */ new Map();
-      for (const lineNumber of ordered) {
-        entryMap.set(lineNumber, this.lineCache.getEntryForLine(lineNumber));
-      }
-      void this.reExecuteViaWorkerPool(ordered, entryMap, allQueryKeys).catch((e) => {
-        const engineError = normalizeUnknownError(e);
-        console.error(`[AsyncResolutionBatcher] reExecuteViaWorkerPool() failed unexpectedly: ${engineError.format()}`);
-      });
-      return;
+    const key = _LineCache.exprKey(expression);
+    if (entries.size > 0 && !entries.has(key)) {
+      this.count -= entries.size;
+      entries.clear();
     }
-    this.reExecuteMainThread(ordered, allQueryKeys);
+    if (!entries.has(key)) this.count++;
+    entries.set(key, entry);
+  }
+  has(line, expression) {
+    return this.byLine.get(line)?.has(_LineCache.exprKey(expression)) ?? false;
+  }
+  remove(line, expression) {
+    const entries = this.byLine.get(line);
+    if (!entries) return;
+    if (entries.delete(_LineCache.exprKey(expression))) {
+      this.count--;
+      if (entries.size === 0) this.byLine.delete(line);
+    }
+  }
+  removeAllForLine(line) {
+    const entries = this.byLine.get(line);
+    if (!entries) return;
+    this.count -= entries.size;
+    this.byLine.delete(line);
+  }
+  clearLine(line) {
+    this.removeAllForLine(line);
   }
-  // ── Private: topological sort ─────────────────────────────────────
   /**
-   * Topologically sort affected lines using Kahn's algorithm.
-   *
-   * Lines that produce variables come before lines that consume them.
-   * This ensures correct evaluation order when multiple interdependent
-   * lines are affected by async resolution.
+   * Number of entries in the cache. Useful for diagnostics.
    */
-  topologicalSort(lines) {
-    if (lines.length <= 1) return lines;
-    const inDegree = /* @__PURE__ */ new Map();
-    const adjacency = /* @__PURE__ */ new Map();
-    const producerOf = /* @__PURE__ */ new Map();
-    for (const line of lines) {
-      inDegree.set(line, 0);
-      adjacency.set(line, []);
-    }
-    for (const line of lines) {
-      const writes = this.dag.getWrites(line);
-      for (const w of writes) {
-        producerOf.set(w, line);
-      }
-    }
-    for (const line of lines) {
-      const reads = this.dag.getDependencies(line);
-      for (const readVar of reads) {
-        const producer = producerOf.get(readVar);
-        if (producer !== void 0 && producer !== line) {
-          adjacency.get(producer).push(line);
-          inDegree.set(line, (inDegree.get(line) ?? 0) + 1);
-        }
-      }
-    }
-    const queue = [];
-    for (const [line, degree] of inDegree) {
-      if (degree === 0) queue.push(line);
-    }
-    if (queue.length === 0 && lines.length > 0) {
-      return [...lines].sort((a, b) => a - b);
-    }
-    const ordered = [];
-    while (queue.length > 0) {
-      const current = queue.shift();
-      ordered.push(current);
-      for (const downstream of adjacency.get(current) ?? []) {
-        const newDegree = (inDegree.get(downstream) ?? 1) - 1;
-        inDegree.set(downstream, newDegree);
-        if (newDegree === 0) queue.push(downstream);
-      }
-    }
-    if (ordered.length < lines.length) {
-      const remaining = lines.filter((l) => !ordered.includes(l)).sort((a, b) => a - b);
-      ordered.push(...remaining);
-    }
-    return ordered;
+  get size() {
+    return this.count;
+  }
+  clear() {
+    this.byLine.clear();
+    this.count = 0;
   }
-  // ── Private: worker-pool re-execution ─────────────────────────────
   /**
-   * Offload VM re-execution to the worker pool for large batches.
-   *
-   * Called when ordered.length > WORKER_OFFLOAD_THRESHOLD (50).
-   * Clones bytecode ArrayBuffers, dispatches to workers, and asynchronously
-   * patches results back into LineCache before notifying listeners.
-   *
-   * Handles pending results: lines that return { type: 'pending' } from the
-   * worker are NOT marked as updated, the engine's resolveAsync will handle
-   * them when the async resolver completes.
-   *
-   * Safety: checks this.cleared before applying results, if the engine was
-   * cleared while the worker batch was in-flight, results are discarded.
+   * Iterate all cache entries for diagnostics/debugging.
    */
-  async reExecuteViaWorkerPool(ordered, entryMap, allQueryKeys) {
-    if (!this.executionPool) {
-      this.executionPool = new ExecutionPool();
-    }
-    const results = this.executionPool.executeBatch(ordered, entryMap);
-    if (!results) {
-      this.reExecuteMainThread(ordered, allQueryKeys, entryMap);
-      return;
-    }
-    this.workerOffloadDispatchCount++;
-    const workerResults = await results;
-    if (this.cleared) return;
-    const updatedLineNumbers = [];
-    for (const wr of workerResults) {
-      const entry = entryMap.get(wr.lineNumber);
-      if (!entry) continue;
-      if (wr.isPending) {
-        continue;
+  forEach(callback) {
+    for (const [line, entries] of this.byLine) {
+      for (const [exprKey, entry] of entries) {
+        callback(_LineCache.displayKey(line, exprKey), entry);
       }
-      const value = reconstructValue(wr);
-      entry.result = value;
-      this.warnIfUnwired();
-      this.onLineResult?.(wr.lineNumber, value);
-      updatedLineNumbers.push(wr.lineNumber);
-    }
-    if (this.cleared) return;
-    if (updatedLineNumbers.length > 0 || allQueryKeys.length > 0) {
-      this.notifyListeners({
-        type: "lines-updated",
-        lineNumbers: updatedLineNumbers,
-        affectedQueryKeys: allQueryKeys
-      });
     }
   }
-  // ── Private: main-thread re-execution ────────────────────────────
   /**
-   * Execute ordered lines on the main thread, update LineCache, and notify
-   * listeners. Returns the list of line numbers that actually changed.
-   *
-   * Used by both flush() (≤50 lines) and reExecuteViaWorkerPool() (fallback
-   * when workers are unavailable). Extracted to avoid code duplication.
-   *
-   * **Per-line containment (fatal-bug fix)**: `executeBytecode()` used to
-   * run here with NO try/catch anywhere in this method's call chain, and
-   * this whole batch runs inside a bare `queueMicrotask` (see `add()`) with
-   * no surrounding try/catch at any caller either, so if any ONE line's
-   * cached bytecode threw (a stack/instruction-limit error, an undefined
-   * variable, a corrupted-bytecode `TypeError`), the `for` loop aborted
-   * immediately: every line scheduled AFTER the failure in this batch was
-   * silently never re-executed or notified even though nothing was wrong
-   * with them, every line BEFORE it had already had its `entry.result`
-   * mutated in-place but `notifyListeners()` was never reached (a silent
-   * `LineCache`/host desync), and, because a bare `queueMicrotask`
-   * callback has no caller to catch it, the exception was uncatchable:
-   * an `uncaughtException` that could crash the host process outright.
-   * (`__tests__/async/AsyncResolutionBatcher.spec.ts`'s topological-sort
-   * describe block used to have a test skipped specifically because of
-   * this. See that file, now un-skipped and rewritten.) Each line's
-   * execution is now its own try/catch: a failure is recorded as an
-   * `Error` `Value` for THAT line (still counted as "updated" so the host
-   * learns about it and stops showing a stale Pending state) and the loop
-   * continues, one line's failure can no longer take out its neighbors.
+   * Structured iteration for serialization: one record per stored entry,
+   * carrying the raw line number and expression key rather than the lossy
+   * "line:expression" display key `keys()`/`forEach()` produce (an expression
+   * containing a colon cannot be split back apart from that string). Used by
+   * the engine snapshot to walk every entry without re-parsing display keys.
    */
-  reExecuteMainThread(ordered, allQueryKeys, entryMap) {
-    const updatedLineNumbers = [];
-    for (const lineNumber of ordered) {
-      const entry = entryMap ? entryMap.get(lineNumber) : this.lineCache.getEntryForLine(lineNumber);
-      if (!entry || entry.bytecode.opcodes.length === 0) continue;
-      const stackBefore = this.vm.getStack().length;
-      try {
-        const result = executeBytecode(entry.bytecode, this.vm);
-        while (this.vm.getStack().length > stackBefore) {
-          this.vm.pop();
-        }
-        if (result.type === "value") {
-          entry.result = result.value;
-          this.warnIfUnwired();
-          this.onLineResult?.(lineNumber, result.value);
-          updatedLineNumbers.push(lineNumber);
-        } else if (result.type === "error") {
-          const value = errorValue(result.error.code, result.error.message);
-          entry.result = value;
-          this.warnIfUnwired();
-          this.warnIfUnwired();
-          this.onLineResult?.(lineNumber, value);
-          updatedLineNumbers.push(lineNumber);
-        }
-      } catch (e) {
-        while (this.vm.getStack().length > stackBefore) {
-          this.vm.pop();
-        }
-        const engineError = normalizeUnknownError(e);
-        const value = errorValue(engineError.code, engineError.message);
-        entry.result = value;
-        this.warnIfUnwired();
-        this.onLineResult?.(lineNumber, value);
-        updatedLineNumbers.push(lineNumber);
+  snapshotEntries() {
+    const out = [];
+    for (const [line, entries] of this.byLine) {
+      for (const [exprKey, entry] of entries) {
+        out.push({ line, expression: exprKey, entry });
       }
     }
-    if (updatedLineNumbers.length > 0 || allQueryKeys.length > 0) {
-      this.notifyListeners({
-        type: "lines-updated",
-        lineNumbers: updatedLineNumbers,
-        affectedQueryKeys: allQueryKeys
-      });
-    }
-    return updatedLineNumbers;
+    return out;
   }
   /**
-   * Notify all consumers of an async resolution event.
-   *
-   * Enqueues the event into the internal {@link ReadableStream}.
-   * If the stream has been closed or errored (consumer cancelled),
-   * the enqueue silently fails (caught by try/catch).
-   */
-  notifyListeners(event) {
-    if (this._testCaptures) {
-      this._testCaptures.push(event);
-    }
-    if (this._streamController) {
-      try {
-        this._streamController.enqueue(event);
-      } catch {
+   * Get all entry keys.
+   */
+  keys() {
+    const result = [];
+    for (const [line, entries] of this.byLine) {
+      for (const exprKey of entries.keys()) {
+        result.push(_LineCache.displayKey(line, exprKey));
       }
     }
+    return result;
   }
 };
-// ── Web Streams API integration ──────────────────────────────────
-/**
- * Default high-water mark for the internal event stream.
- * Limits the internal buffer size before the stream signals to
- * consumers that they need to catch up.
- */
-_AsyncResolutionBatcher.DEFAULT_HIGH_WATER_MARK = 64;
-var AsyncResolutionBatcher = _AsyncResolutionBatcher;
+
+// src/vm/HolidayCalendar.ts
+function localDateKey(epochMs) {
+  const d = new Date(epochMs);
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${d.getFullYear()}-${month}-${day}`;
+}
+function entryToKey(entry) {
+  if (entry instanceof Date) return localDateKey(entry.getTime());
+  if (typeof entry === "number") {
+    return Number.isFinite(entry) ? localDateKey(entry) : null;
+  }
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(entry.trim());
+  if (!match) return null;
+  return `${match[1]}-${match[2]}-${match[3]}`;
+}
+function resolveHolidayPredicate(calendar) {
+  if (calendar === void 0) return void 0;
+  if (typeof calendar === "function") {
+    return (epochMs) => calendar(new Date(epochMs));
+  }
+  const keys = /* @__PURE__ */ new Set();
+  for (const entry of calendar) {
+    const key = entryToKey(entry);
+    if (key !== null) keys.add(key);
+  }
+  return (epochMs) => keys.has(localDateKey(epochMs));
+}
 
 // src/telemetry/AllocationTracker.ts
 var AllocationTracker = class {
@@ -3346,8 +2791,318 @@ function findInlineSolvesInLine(lineText, lineNumber) {
   }));
 }
 
+// src/packages/uom/UserUnitTable.ts
+function pluralInsensitiveKey(words) {
+  const last = words[words.length - 1];
+  const singular = last.length > 1 && last.endsWith("s") ? last.slice(0, -1) : last;
+  return [...words.slice(0, -1), singular].join(" ");
+}
+var UserUnitTable = class {
+  constructor() {
+    this.byKey = /* @__PURE__ */ new Map();
+    this.longestName = 0;
+  }
+  /** Whether any unit has been defined, a cheap guard for the hot path. */
+  get isEmpty() {
+    return this.byKey.size === 0;
+  }
+  /** The most words any registered name spans, bounding the lookup scan. */
+  get maxWordCount() {
+    return this.longestName;
+  }
+  /**
+   * Register (or replace) a unit named by `nameWords`, defined as `ratioText`
+   * of `baseUnit`. Re-defining a name overwrites the earlier definition, so a
+   * corrected line wins over the one above it.
+   */
+  define(nameWords, ratioText, baseUnit) {
+    const key = pluralInsensitiveKey(nameWords);
+    this.byKey.set(key, {
+      displayName: nameWords.join(" "),
+      ratioText,
+      baseUnit
+    });
+    if (nameWords.length > this.longestName) this.longestName = nameWords.length;
+  }
+  /**
+   * Longest registered name that a run of identifier `words` begins with, or
+   * `null` if none. `words` is the consecutive identifiers following a value,
+   * so `story points each` matches the 2-word `story point` and leaves `each`.
+   */
+  match(words) {
+    const upper = Math.min(words.length, this.longestName);
+    for (let length = upper; length >= 1; length--) {
+      const definition = this.byKey.get(pluralInsensitiveKey(words.slice(0, length)));
+      if (definition !== void 0) return { definition, wordCount: length };
+    }
+    return null;
+  }
+  /** Drop every definition, called when a fresh document pass begins. */
+  clear() {
+    this.byKey.clear();
+    this.longestName = 0;
+  }
+};
+
+// src/packages/uom/normalizer/UserUnitNormalizerRule.ts
+function userUnitExpansionRule(table, priority = 82) {
+  return {
+    name: "uom:user-unit",
+    priority,
+    match(tokens, pos) {
+      if (table.isEmpty) return null;
+      const value = tokens[pos];
+      if (value.type !== "NUMBER" && value.type !== "RPAREN") return null;
+      const words = [];
+      const maxWords = table.maxWordCount;
+      for (let i = pos + 1; i < tokens.length && words.length < maxWords; i++) {
+        if (tokens[i].type !== "IDENT") break;
+        words.push(tokens[i].value);
+      }
+      if (words.length === 0) return null;
+      const matched = table.match(words);
+      if (matched === null) return null;
+      const after = tokens[pos + 1 + matched.wordCount];
+      if (after?.type === "EQUALS") return null;
+      const { ratioText, baseUnit } = matched.definition;
+      const star = new LexerToken("STAR", tokenTypeId("STAR"), "*", "*", value.offset, 0, value.line, value.col);
+      const ratio = new LexerToken("NUMBER", tokenTypeId("NUMBER"), ratioText, ratioText, value.offset, 0, value.line, value.col);
+      const unit = new LexerToken("UNIT", tokenTypeId("UNIT"), baseUnit, baseUnit, value.offset, 0, value.line, value.col);
+      return {
+        consumed: 1 + matched.wordCount,
+        replacement: [value, star, ratio, unit],
+        ruleName: "uom:user-unit"
+      };
+    }
+  };
+}
+
+// src/explain/LineExplainer.ts
+var SUM = 30;
+var PRODUCT = 40;
+var EXPONENT = 50;
+var ON_OFF = 24;
+function infixBindingPower(type) {
+  switch (type) {
+    case TokenTypes.PLUS:
+    case TokenTypes.MINUS:
+      return SUM;
+    case TokenTypes.STAR:
+    case TokenTypes.SLASH:
+    case TokenTypes.MOD:
+    case TokenTypes.OF:
+      return PRODUCT;
+    case TokenTypes.CARET:
+      return EXPONENT;
+    case TokenTypes.PCT_ON:
+    case TokenTypes.PCT_OFF:
+      return ON_OFF;
+    default:
+      return 0;
+  }
+}
+function connective(type) {
+  switch (type) {
+    case TokenTypes.PLUS:
+      return "plus";
+    case TokenTypes.MINUS:
+      return "minus";
+    case TokenTypes.STAR:
+      return "times";
+    case TokenTypes.SLASH:
+      return "divided by";
+    case TokenTypes.MOD:
+      return "mod";
+    case TokenTypes.CARET:
+      return "to the power of";
+    case TokenTypes.OF:
+      return "of";
+    case TokenTypes.PCT_ON:
+      return "plus";
+    case TokenTypes.PCT_OFF:
+      return "less";
+    default:
+      return type.toLowerCase();
+  }
+}
+function tokenEnd(t) {
+  return t.sourceEnd ?? t.offset + t.value.length;
+}
+var OPERAND_TOKEN_TYPES = /* @__PURE__ */ new Set([
+  TokenTypes.NUMBER,
+  TokenTypes.BIGINT,
+  TokenTypes.IDENT,
+  TokenTypes.UNIT,
+  TokenTypes.PERCENT,
+  TokenTypes.PI,
+  TokenTypes.E,
+  TokenTypes.TRUE,
+  TokenTypes.FALSE,
+  TokenTypes.DOLLAR,
+  TokenTypes.POUND,
+  TokenTypes.EURO,
+  TokenTypes.YEN,
+  TokenTypes.RUBLE,
+  TokenTypes.WON,
+  TokenTypes.CURRENCY_SYMBOL
+]);
+function isBoundary(type) {
+  return !OPERAND_TOKEN_TYPES.has(type);
+}
+var Parser = class {
+  constructor(tokens) {
+    this.tokens = tokens;
+    this.pos = 0;
+  }
+  peek() {
+    return this.tokens[this.pos];
+  }
+  next() {
+    return this.tokens[this.pos++];
+  }
+  /** Parse the whole stream, requiring every token to be consumed. */
+  parseAll() {
+    const node = this.parseExpression(0);
+    if (this.pos !== this.tokens.length) {
+      throw new Error("explain: unconsumed tokens");
+    }
+    return node;
+  }
+  parseExpression(minBindingPower) {
+    let left = this.parseOperand();
+    for (; ; ) {
+      const t = this.peek();
+      if (!t) break;
+      const bindingPower = infixBindingPower(t.type);
+      if (bindingPower === 0 || bindingPower <= minBindingPower) break;
+      this.next();
+      const rightBindingPower = t.type === TokenTypes.CARET ? bindingPower - 1 : bindingPower;
+      const right = this.parseExpression(rightBindingPower);
+      left = {
+        kind: "binary",
+        op: t.type,
+        left,
+        right,
+        start: left.start,
+        end: right.end
+      };
+    }
+    return left;
+  }
+  /** A parenthesised group, an optional sign, then a run of operand tokens. */
+  parseOperand() {
+    const first = this.peek();
+    if (!first) throw new Error("explain: expected an operand");
+    if (first.type === TokenTypes.LPAREN) {
+      return this.parseGroup();
+    }
+    const signStart = first.offset;
+    let sawSign = false;
+    while (this.peek() && (this.peek().type === TokenTypes.PLUS || this.peek().type === TokenTypes.MINUS)) {
+      this.next();
+      sawSign = true;
+    }
+    if (sawSign && this.peek() && this.peek().type === TokenTypes.LPAREN) {
+      const group = this.parseGroup();
+      return { kind: "wrap", child: group, start: signStart, end: group.end };
+    }
+    let end = -1;
+    while (this.peek() && !isBoundary(this.peek().type)) {
+      end = tokenEnd(this.next());
+    }
+    if (end === -1) {
+      throw new Error("explain: expected an operand");
+    }
+    return { kind: "leaf", start: signStart, end };
+  }
+  parseGroup() {
+    const open = this.next();
+    const inner = this.parseExpression(0);
+    const close = this.peek();
+    if (!close || close.type !== TokenTypes.RPAREN) {
+      throw new Error("explain: unbalanced parentheses");
+    }
+    this.next();
+    return { kind: "wrap", child: inner, start: open.offset, end: tokenEnd(close) };
+  }
+};
+var Builder = class {
+  constructor(source, evaluate, locale) {
+    this.source = source;
+    this.evaluate = evaluate;
+    this.steps = [];
+    this.cache = /* @__PURE__ */ new Map();
+    this.resultPrefix = getLocale(locale).display.resultPrefix;
+  }
+  build(root) {
+    this.emit(root);
+    return { steps: this.steps, result: this.valueOf(root) };
+  }
+  /** Walk in evaluation order, emitting one step per operation. */
+  emit(node) {
+    if (node.kind === "leaf") return;
+    if (node.kind === "wrap") {
+      this.emit(node.child);
+      return;
+    }
+    this.emit(node.left);
+    this.emit(node.right);
+    this.steps.push({
+      description: this.describe(node),
+      value: this.valueOf(node)
+    });
+  }
+  describe(node) {
+    const word = connective(node.op);
+    if (node.op === TokenTypes.PCT_ON || node.op === TokenTypes.PCT_OFF) {
+      return `${this.operand(node.right)} ${word} ${this.operand(node.left)}`;
+    }
+    return `${this.operand(node.left)} ${word} ${this.operand(node.right)}`;
+  }
+  /** How an operand appears inside a step's description. */
+  operand(node) {
+    if (node.kind === "leaf") {
+      return this.source.slice(node.start, node.end).trim();
+    }
+    return this.render(this.valueOf(node));
+  }
+  /** A node's value, evaluated once from its own span and then cached. */
+  valueOf(node) {
+    const cached = this.cache.get(node);
+    if (cached) return cached;
+    const value = this.evaluate(this.source.slice(node.start, node.end));
+    this.cache.set(node, value);
+    return value;
+  }
+  /** Format a value for inline display, without the result prefix ("= "). */
+  render(value) {
+    const formatted = formatValue(value, DEFAULT_FORMATTING_SETTINGS);
+    return formatted.startsWith(this.resultPrefix) ? formatted.slice(this.resultPrefix.length) : formatted;
+  }
+};
+function buildExplanation(params) {
+  const { expression, tokens, evaluate, locale } = params;
+  const terminal = () => ({
+    expression,
+    steps: [],
+    result: evaluate(expression)
+  });
+  let root;
+  try {
+    root = new Parser(tokens).parseAll();
+  } catch {
+    return terminal();
+  }
+  try {
+    const { steps, result } = new Builder(expression, evaluate, locale).build(root);
+    return { expression, steps, result };
+  } catch {
+    return terminal();
+  }
+}
+
 // src/engine/ExpressionEngine.ts
-var ExpressionEngine = class {
+var _ExpressionEngine = class _ExpressionEngine {
   //#endregion
   //#region Constructor
   constructor(localeCode = "en", diagnosticMode = false, config, diagnosticPipeline, packages) {
@@ -3384,6 +3139,25 @@ var ExpressionEngine = class {
      * lifecycle itself.
      */
     this.documentModel = null;
+    /**
+     * How deep goal seek is currently re-entering line evaluation, so a goal
+     * seek whose target line is itself a goal seek is refused rather than
+     * multiplying the search cost. One goal-seek line already re-runs its
+     * target up to `maxGoalSeekIterations` times; allowing a nested one would
+     * make that a product. See {@link makeLineContext}'s `evaluateLineWithBinding`.
+     */
+    this.goalSeekDepth = 0;
+    /**
+     * Batch cross-line source, set only for the duration of a
+     * `parseDocument`/`evaluateLines` pass (see {@link processScanResults}).
+     * The incremental path uses {@link documentModel}; the batch path has no
+     * such model, so cross-line closures read earlier lines from the scan and
+     * the results array the pass is already building. Both are references to
+     * arrays that exist regardless, so a document that uses no cross-line
+     * feature pays nothing: the closures are simply never called.
+     */
+    this.batchScanResults = null;
+    this.batchParsedLines = null;
     /**
      * Package-contributed completion candidates (`IEnginePackage.completionItems`),
      * keyed by package name, engine-instance-local, not a shared registry
@@ -3403,6 +3177,14 @@ var ExpressionEngine = class {
      * are aborted together.
      */
     this.keystrokeSignal = null;
+    /**
+     * Units defined by the current document (`1 sprint = 2 weeks`). Read by the
+     * user-unit normalizer rule to expand a name back to its definition, written
+     * by {@link tryDefineUserUnit} on a definition line. Document-scoped: cleared
+     * at the start of every {@link parseDocument} pass, so definitions never
+     * cross between documents.
+     */
+    this.userUnits = new UserUnitTable();
     // Bytecode cache, avoids re-parsing identical expressions.
     // Bounded by config.performance.defaultCacheSize: when full, the oldest
     // entry (Map insertion order) is evicted so unique expressions across a
@@ -3441,6 +3223,7 @@ var ExpressionEngine = class {
       50,
       (word) => this.normalizer.canStartPhrase(word)
     ));
+    this.normalizer.register(userUnitExpansionRule(this.userUnits));
     const pkgList = packages ?? BUILTIN_PACKAGES;
     for (const pkg of pkgList) {
       try {
@@ -3463,7 +3246,11 @@ var ExpressionEngine = class {
       this.config.vm.maxFunctionCalls,
       this.config.date.maxOffsetYears,
       this.config.date.minOffsetYears,
-      this.context
+      this.context,
+      // Resolved once here, not per evaluation: a host list becomes a
+      // Set lookup the walk can run cheaply. Undefined stays undefined,
+      // which the VM reads as weekends-only.
+      resolveHolidayPredicate(this.config.date.holidays)
     );
     this.queryClient = createQueryClient();
     this.batcher = new AsyncResolutionBatcher(this.dag, this.lineCache, this.vm);
@@ -3486,16 +3273,96 @@ var ExpressionEngine = class {
    */
   makeLineContext(lineNumber) {
     const doc = this.documentModel;
+    const scan = doc ? null : this.batchScanResults;
+    const parsed = doc ? null : this.batchParsedLines;
     return {
       lineIndex: lineNumber,
-      getLineResult: doc ? (n) => doc.getLineAt(n)?.result ?? void 0 : void 0,
+      getLineResult: doc ? (n) => doc.getLineAt(n)?.result ?? void 0 : parsed ? (n) => parsed[n - 1]?.result ?? void 0 : void 0,
       isLineBoundary: doc ? (n) => {
         const state = doc.getLineAt(n);
         if (!state) return true;
         return state.isEmpty || /^\s*#/.test(state.text);
-      } : void 0
+      } : scan ? (n) => {
+        const sr = scan[n - 1];
+        if (!sr) return true;
+        return sr.classification.skip || /^\s*#/.test(sr.text);
+      } : void 0,
+      getLineReads: doc ? (n) => {
+        const state = doc.getLineAt(n);
+        if (!state || state.bytecodes.length === 0) return void 0;
+        return state.reads;
+      } : void 0,
+      evaluateLineWithBinding: doc ? (n, variable, bound, symbolicTolerant) => this.evaluateLineWithBinding(n, variable, bound, symbolicTolerant) : void 0,
+      goalSeekMaxIterations: this.config.vm.maxGoalSeekIterations,
+      // Raw source text of a line, for features that read markdown the
+      // evaluator skipped (a table's rows). See the tables package. Reads
+      // from the document when evaluating incrementally, and from the scan
+      // in the batch parseDocument/evaluateLines path, so a table column
+      // aggregate resolves the same way through both, matching the other
+      // cross-line closures above.
+      getLineText: doc ? (n) => doc.getLineAt(n)?.text : scan ? (n) => scan[n - 1]?.text : void 0
     };
   }
+  /**
+   * Re-evaluate line `targetLine`'s compiled expression with `variable` bound
+   * to `bound` for that one run, the primitive goal seek drives while
+   * narrowing in on an input. See {@link LineExecutionContext.evaluateLineWithBinding}.
+   *
+   * The binding is a call frame, so `LOAD_VAR` reads it in preference to the
+   * document's own value and the document's value is untouched once the frame
+   * is popped, the same shadowing a function parameter gets. The target's
+   * bytecode is run as-is, so a line that defines a variable is refused: its
+   * `STORE_VAR` would write the probe's candidate into the real variable store
+   * as a side effect. The re-entry is bounded three ways, by
+   * {@link goalSeekDepth} against nesting, by the VM's own per-run instruction
+   * limit, and by the caller's iteration cap.
+   *
+   * @param targetLine - 1-based line whose expression is re-evaluated.
+   * @param variable - The unknown to bind for this run.
+   * @param bound - The value to bind it to (a number to probe, a symbolic node to read the relationship in closed form).
+   * @param symbolicTolerant - Whether an otherwise-undefined variable reads as a symbolic placeholder, needed for the closed-form read.
+   * @returns The line's re-evaluated Value, or an error Value when it cannot be probed.
+   */
+  evaluateLineWithBinding(targetLine, variable, bound, symbolicTolerant) {
+    const doc = this.documentModel;
+    if (!doc) {
+      return errorValue("GOAL_SEEK_NO_DOCUMENT", "Goal seek needs a document to solve against, which the single-expression entry point does not have.");
+    }
+    if (this.goalSeekDepth >= _ExpressionEngine.GOAL_SEEK_MAX_NESTING_DEPTH) {
+      return errorValue("GOAL_SEEK_NESTED", `A goal-seek line cannot target another goal-seek line, since each already re-runs its target many times.`);
+    }
+    const state = doc.getLineAt(targetLine);
+    if (!state || state.bytecodes.length === 0) {
+      return errorValue("GOAL_SEEK_LINE_NOT_READY", `Line ${targetLine} has no evaluated expression to solve (forward reference, out of range, or not an expression).`);
+    }
+    if (state.isVariableDef) {
+      return errorValue("GOAL_SEEK_TARGET_IS_DEFINITION", `Line ${targetLine} defines a variable, so re-running it would overwrite that variable. Target the line that uses ${variable}, not the one that sets a value.`);
+    }
+    const program = state.bytecodes[0];
+    this.goalSeekDepth++;
+    try {
+      const frame = /* @__PURE__ */ new Map([[variable, bound]]);
+      const stackBefore = this.vm.getStack().length;
+      this.vm.pushCallFrame(frame);
+      try {
+        const result = executeBytecode(program, this.vm, void 0, void 0, this.makeLineContext(targetLine), symbolicTolerant);
+        if (result.type === "pending") {
+          return errorValue("GOAL_SEEK_ASYNC_UNSUPPORTED", `Line ${targetLine} depends on an async value (weather, stocks, currency, ...), which goal seek cannot re-run.`);
+        }
+        if (result.type === "error") {
+          return errorValue(result.error.code ?? "GOAL_SEEK_TARGET_ERROR", result.error.message);
+        }
+        return result.value;
+      } finally {
+        this.vm.popCallFrame();
+        while (this.vm.getStack().length > stackBefore) this.vm.pop();
+      }
+    } catch (e) {
+      return errorValue("GOAL_SEEK_TARGET_ERROR", normalizeUnknownError(e).message);
+    } finally {
+      this.goalSeekDepth--;
+    }
+  }
   /**
    * Insert into the bytecode cache, evicting the oldest entry when full.
    *
@@ -3888,6 +3755,8 @@ var ExpressionEngine = class {
         { maxLines }
       );
     }
+    if (!this.userUnits.isEmpty) this.bytecodeCache.clear();
+    this.userUnits.clear();
     const scanResults = this.lexer.scanDocument(input);
     const processedLines = this.processScanResults(scanResults);
     const result = {
@@ -3933,6 +3802,8 @@ var ExpressionEngine = class {
    * bypassing the split→join roundtrip that this method performs.
    */
   evaluateLines(lines) {
+    if (!this.userUnits.isEmpty) this.bytecodeCache.clear();
+    this.userUnits.clear();
     const documentText = lines.join("\n");
     const scanResults = this.lexer.scanDocument(documentText);
     return this.processScanResults(scanResults);
@@ -3947,63 +3818,74 @@ var ExpressionEngine = class {
    */
   processScanResults(scanResults) {
     const result = [];
-    for (const scanResult of scanResults) {
-      const lineText = scanResult.text;
-      const lineNumber = scanResult.lineNumber;
-      const startPosition = scanResult.startOffset;
-      const endPosition = scanResult.endOffset;
-      const isEmpty = scanResult.classification.skip;
-      const inlineSolves = scanResult.inlineSolves.map((s) => ({
-        start: s.start,
-        end: s.end,
-        expression: s.expression,
-        lineNumber,
-        columnNumber: s.columnNumber
-      }));
-      const hasInlineSolves = inlineSolves.length > 0;
-      const parsedLine = {
-        lineNumber,
-        text: lineText,
-        startPosition,
-        endPosition,
-        isEmpty,
-        hasInlineSolves,
-        inlineSolves,
-        expression: null,
-        result: null,
-        error: null
-      };
-      if (!isEmpty) {
-        const isVariableAssignment = lineText.trim().startsWith(":");
-        if (hasInlineSolves && !isVariableAssignment) {
-          for (const solve of inlineSolves) {
-            try {
-              const values = this.evaluateLine(lineNumber, solve.expression);
-              solve.result = values[0];
-            } catch (error) {
-              const errorMessage = error instanceof Error ? error.message : String(error);
-              solve.error = errorMessage;
+    const previousBatchScanResults = this.batchScanResults;
+    const previousBatchParsedLines = this.batchParsedLines;
+    this.batchScanResults = scanResults;
+    this.batchParsedLines = result;
+    try {
+      for (const scanResult of scanResults) {
+        const lineText = scanResult.text;
+        const lineNumber = scanResult.lineNumber;
+        const startPosition = scanResult.startOffset;
+        const endPosition = scanResult.endOffset;
+        const isEmpty = scanResult.classification.skip;
+        const inlineSolves = scanResult.inlineSolves.map((s) => ({
+          start: s.start,
+          end: s.end,
+          expression: s.expression,
+          lineNumber,
+          columnNumber: s.columnNumber
+        }));
+        const hasInlineSolves = inlineSolves.length > 0;
+        const parsedLine = {
+          lineNumber,
+          text: lineText,
+          startPosition,
+          endPosition,
+          isEmpty,
+          hasInlineSolves,
+          inlineSolves,
+          expression: null,
+          result: null,
+          error: null
+        };
+        if (!isEmpty) {
+          const isVariableAssignment = lineText.trim().startsWith(":");
+          if (hasInlineSolves && !isVariableAssignment) {
+            for (const solve of inlineSolves) {
+              try {
+                const values = this.evaluateLine(lineNumber, solve.expression);
+                solve.result = values[0];
+              } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                solve.error = errorMessage;
+              }
             }
-          }
-        } else {
-          const expression = lineText.trim();
-          if (expression) {
-            try {
-              const values = this.evaluateLineWithPreTokenized(
-                lineNumber,
-                expression,
-                scanResult.tokens
-              );
-              parsedLine.expression = expression;
-              parsedLine.result = values[0];
-            } catch (error) {
-              const errorMessage = error instanceof Error ? error.message : String(error);
-              parsedLine.error = errorMessage;
+          } else {
+            const contentOffset = scanResult.classification.contentOffset;
+            const evaluable = contentOffset === void 0 ? lineText : lineText.slice(contentOffset - startPosition);
+            const expression = evaluable.trim();
+            if (expression) {
+              try {
+                const values = this.evaluateLineWithPreTokenized(
+                  lineNumber,
+                  expression,
+                  scanResult.tokens
+                );
+                parsedLine.expression = expression;
+                parsedLine.result = values[0];
+              } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                parsedLine.error = errorMessage;
+              }
             }
           }
         }
+        result.push(parsedLine);
       }
-      result.push(parsedLine);
+    } finally {
+      this.batchScanResults = previousBatchScanResults;
+      this.batchParsedLines = previousBatchParsedLines;
     }
     return result;
   }
@@ -4242,6 +4124,54 @@ var ExpressionEngine = class {
    * session's own Phase H.2 scope decision (full symbolic MATRICES, not
    * a general CAS).
    */
+  /**
+   * Registers a document-scoped user unit from a `1 <name> = <n> <unit>` line
+   * and returns the `<name> defined` confirmation, or `null` when the line is
+   * not a unit definition (so ordinary processing continues unchanged).
+   *
+   * Like the symbolic-grammar shapes it sits beside, this has an effect (a
+   * stored definition) that no cached bytecode program could represent, so it
+   * short-circuits compilation the same way. See {@link UserUnitTable}.
+   *
+   * The pattern is kept deliberately narrow so it cannot swallow an equation:
+   *
+   * - The coefficient must be exactly `1`. `2 x = 10` stays a scalar equation
+   *   (`x =>` solves it); only the natural `1 sprint = 2 weeks` shape is a
+   *   definition.
+   * - The name is one or more identifiers, never a built-in unit (those lex as
+   *   UNIT, not IDENT), so a built-in unit cannot be redefined.
+   * - The base must be a recognized unit (a UNIT token). A non-unit right side
+   *   declines here and is left to whatever handled it before, so a defined
+   *   unit is always dimensioned, never free-standing.
+   *
+   * `tokens` are already normalized, so the implicit-multiply pass has usually
+   * inserted a STAR between the coefficient and the name (`1 * sprint`); it is
+   * tolerated and skipped.
+   */
+  tryDefineUserUnit(tokens) {
+    if (tokens.length < 5) return null;
+    if (tokens[0].type !== "NUMBER" || Number(tokens[0].value) !== 1) return null;
+    let i = 1;
+    if (tokens[i].type === "STAR") i++;
+    const nameWords = [];
+    while (i < tokens.length && tokens[i].type === "IDENT") {
+      nameWords.push(tokens[i].value);
+      i++;
+    }
+    if (nameWords.length === 0) return null;
+    if (tokens[i]?.type !== "EQUALS") return null;
+    i++;
+    if (tokens[i]?.type !== "NUMBER") return null;
+    const ratioToken = tokens[i];
+    i++;
+    if (tokens[i]?.type !== "UNIT") return null;
+    const baseToken = tokens[i];
+    i++;
+    if (i !== tokens.length) return null;
+    this.userUnits.define(nameWords, ratioToken.value, baseToken.value);
+    this.bytecodeCache.clear();
+    return stringValue(`${nameWords.join(" ")} defined`);
+  }
   trySymbolicGrammar(normalizedTokens, lineNumber = -1) {
     if (normalizedTokens.length === 0) return null;
     const last = normalizedTokens[normalizedTokens.length - 1];
@@ -4269,6 +4199,7 @@ var ExpressionEngine = class {
       return this.simplifySymbolically(normalizedTokens, lineNumber);
     }
     if (normalizedTokens[0].type === "COLON" || normalizedTokens[0].type === "GLOBAL") return null;
+    if (normalizedTokens[0].type === "GOAL_SEEK") return null;
     const eqIdx = normalizedTokens.findIndex((t) => t.type === "EQUALS");
     if (eqIdx === -1) return null;
     const names = this.parseFactorChain(normalizedTokens.slice(0, eqIdx));
@@ -4459,7 +4390,7 @@ var ExpressionEngine = class {
     }
     let symbolicResult;
     try {
-      symbolicResult = this.trySymbolicGrammar(normalizedTokens, lineNumber);
+      symbolicResult = this.tryDefineUserUnit(normalizedTokens) ?? this.trySymbolicGrammar(normalizedTokens, lineNumber);
     } catch (e) {
       const { reads: reads2, writes: writes2 } = extractReadsAndWrites(normalizedTokens);
       return { kind: "error", stage: "parse", error: normalizeUnknownError(e), reads: reads2, writes: writes2, normalizedTokens };
@@ -5612,6 +5543,70 @@ var ExpressionEngine = class {
   evaluateExpression(expression) {
     return this.evaluateLine(-1, expression);
   }
+  /**
+   * Explain how a line reached its answer, as a readable derivation.
+   *
+   * This is a companion to {@link evaluateExpression}, not a replacement:
+   * `explainLine` is for the person reading the note, whereas the diagnostic
+   * pipeline (`evaluateLineWithDiagnostic`) is for the developer and reports
+   * stages, opcodes and timings. A host puts a derivation behind a hover or a
+   * disclosure, so this is an API rather than an `explain` keyword: it never
+   * consumes a word that a prose line might use, and it annotates a line the
+   * host has already chosen to explain.
+   *
+   * The returned {@link Explanation} walks the line's operations in evaluation
+   * order, each with the value it arrives at, and its `result` is identical to
+   * what {@link evaluateExpression} returns for the same line. Every value in
+   * the derivation is the engine's own, the operations are re-evaluated rather
+   * than re-derived, so a step can never disagree with the answer.
+   *
+   * A line with nothing to break down (a bare literal), or one built from a
+   * construct this slice does not derive yet (matrices, dates, function
+   * calls), comes back with an empty `steps` array and the answer in
+   * `result`, rather than an error.
+   *
+   * @param expression - The raw line to explain.
+   * @returns The ordered derivation and final value.
+   * @throws {EngineError} When the line does not evaluate at all, or resolves
+   * data asynchronously (a derivation has no meaning for either).
+   */
+  explainLine(expression) {
+    const { tokens } = this.lexToTokens(expression);
+    const exprTokens = tokens.filter((t) => t.type !== "COMMENT");
+    const normalized = this.normalizer.normalize(exprTokens);
+    return buildExplanation({
+      expression,
+      tokens: normalized,
+      evaluate: (source) => this.evaluateIsolated(source),
+      locale: this.localeCode
+    });
+  }
+  /**
+   * Evaluate a self-contained sub-expression without touching document state.
+   *
+   * Used only by {@link explainLine}. Unlike `evaluateExpression`, this never
+   * writes to the line cache or the dependency graph: it is handed the spans
+   * of a single line's own sub-expressions, and evaluating those to build a
+   * derivation must not disturb the document the line belongs to. An async
+   * (pending) result is rejected, a derivation cannot represent one.
+   */
+  evaluateIsolated(expression) {
+    const { tokens, hasParens } = this.lexToTokens(expression);
+    const prep = this.prepareExpression(expression, tokens, hasParens, void 0, -1);
+    if (prep.kind === "empty") return numberValue(0);
+    if (prep.kind === "error") throw prep.error;
+    if (prep.kind === "symbolic-solve") return prep.value;
+    const result = this.executeRaw(prep.program, -1);
+    if (result.type === "error") throw result.error;
+    if (result.type === "pending") {
+      throw ErrorFactory.execution(
+        "EXPLAIN_ASYNC_UNSUPPORTED",
+        `A derivation cannot be built for a line that resolves data asynchronously: "${expression}"`,
+        { expression }
+      );
+    }
+    return result.value;
+  }
   //#endregion
   //#region Compilation, Bytecode-only path
   /**
@@ -5782,1796 +5777,1016 @@ var ExpressionEngine = class {
     this.scopeManager.clear();
     this.bytecodeCache.clear();
     this.vm.reset();
+    this.userUnits.clear();
     this.lastTelemetry = null;
   }
   //#endregion
-  //#region Public API, Incremental evaluation
-  /**
-   * Incrementally re-evaluate lines affected by a variable change.
-   * Walks the DAG from the changed variable to find exactly which lines
-   * need re-execution, no dirty-set indirection, no sorting guesswork.
-   * Uses Kahn's algorithm for topological ordering: producers always
-   * execute before consumers, regardless of document line order.
+  //#region Public API, Snapshot / restore
+  /**
+   * Serialise this engine's session state into a plain, JSON-safe snapshot.
+   *
+   * Carries the three things a session accumulates in memory: named
+   * {@link ExpressionEngine} variables, user-defined functions, and the
+   * per-line result/bytecode cache (plus the expression-keyed bytecode cache).
+   * Restore it with {@link ExpressionEngine.fromJSON} onto a fresh engine, and
+   * later expressions resolve exactly as they would have on the engine that
+   * evaluated the document.
+   *
+   * What is deliberately NOT carried:
+   * - **Resolved async values.** Weather, stocks, currency, any package that
+   *   fetches: those results are point-in-time and must be re-fetched, not
+   *   restored stale. Every line backed by an async resolver (a DAG
+   *   data-source dependency, or an async plugin call in its bytecode) is
+   *   dropped from the line cache, and any variable whose most-recent
+   *   definition was such a line is dropped too. An in-flight (Pending) value
+   *   is likewise never written.
+   * - **Package-contributed state.** Core state only for v1; a package opt-in
+   *   is a follow-up.
+   * - **Symbolic (algebra) values.** Deferred: a variable holding one makes
+   *   this method throw {@link SnapshotErrorCodes.SNAPSHOT_UNSUPPORTED_VALUE}
+   *   (refused by name rather than dropped silently), and a cached line whose
+   *   result is symbolic is skipped (it re-evaluates on restore, algebra is
+   *   synchronous).
+   *
+   * The result survives `JSON.stringify` then `JSON.parse` unchanged.
+   *
+   * @returns A snapshot safe to store and hand back to `fromJSON`.
+   * @throws {@link SnapshotErrorCodes.SNAPSHOT_UNSUPPORTED_VALUE} if a variable
+   *   holds a value this v1 format cannot represent (a symbolic value).
    */
-  evaluateIncremental(variable, newValue) {
-    const affectedLines = this.dag.getAffectedLinesInOrder(variable);
-    this.vm.setVar(variable, numberValue(newValue));
-    const updated = /* @__PURE__ */ new Map();
-    for (const lineNumber of affectedLines) {
-      const entry = this.lineCache.getEntryForLine(lineNumber);
-      if (!entry || entry.bytecode.opcodes.length === 0) continue;
-      const evalResult = this.executeRaw(entry.bytecode, lineNumber);
-      if (evalResult.type === "pending") {
-        void this.resolveAsync(evalResult);
-        continue;
-      }
-      if (evalResult.type === "error") {
-        const value = errorValue(evalResult.error.code, evalResult.error.message);
-        updated.set(lineNumber, value);
-        entry.result = value;
-        continue;
+  toJSON() {
+    const dagSnapshot = this.dag.getSnapshot();
+    const asyncLines = /* @__PURE__ */ new Set();
+    for (const key of Object.keys(dagSnapshot.dataSourceDeps)) {
+      const line = Number(key);
+      if (!Number.isNaN(line)) asyncLines.add(line);
+    }
+    const lineEntries = this.lineCache.snapshotEntries();
+    const latestWriter = /* @__PURE__ */ new Map();
+    for (const { line, entry } of lineEntries) {
+      const isAsync = asyncLines.has(line) || entry.bytecode.hasAsync;
+      if (isAsync) asyncLines.add(line);
+      const writeVar = entry.writeVariable;
+      if (writeVar) {
+        const prev = latestWriter.get(writeVar);
+        if (!prev || line >= prev.line) latestWriter.set(writeVar, { line, async: isAsync });
+      }
+    }
+    const variables = {};
+    for (const [name, value] of this.vm.getVariableEntries()) {
+      if (value.type === 12 /* Pending */) continue;
+      if (latestWriter.get(name)?.async) continue;
+      variables[name] = serializeValue(value, `variable "${name}"`);
+    }
+    const userFunctions = this.vm.getUserFunctionDefs().map(serializeUserFunction);
+    const lineCache = [];
+    for (const { line, expression, entry } of lineEntries) {
+      if (asyncLines.has(line)) continue;
+      if (entry.result.type === 12 /* Pending */) continue;
+      let result;
+      try {
+        result = serializeValue(entry.result, `line ${line}`);
+      } catch (e) {
+        if (e instanceof EngineError && e.code === SnapshotErrorCodes.SNAPSHOT_UNSUPPORTED_VALUE) continue;
+        throw e;
       }
-      const result = evalResult.value;
-      updated.set(lineNumber, result);
-      entry.result = result;
-    }
-    return updated;
-  }
-  //#endregion
-};
-
-// src/engine/SegmentTree.ts
-var SegmentTree = class {
-  constructor() {
-    this.root = null;
-  }
-  // ── Public API ───────────────────────────────────────────────────────
-  /** Total number of elements in the tree. */
-  get length() {
-    return this.root ? this.root.size : 0;
-  }
-  /** Whether the tree is empty. */
-  get isEmpty() {
-    return this.root === null;
-  }
-  /**
-   * Get the lineId at the given 0-based index.
-   * Returns undefined if index is out of bounds.
-   * O(log N) expected.
-   */
-  getAt(index) {
-    if (index < 0 || index >= (this.root?.size ?? 0)) return void 0;
-    return this.nodeAt(this.root, index).lineId;
-  }
-  /**
-   * Insert a single lineId at the given 0-based index.
-   * O(log N) expected.
-   */
-  insertAt(index, lineId) {
-    const [left, right] = split(this.root, index);
-    this.root = merge(merge(left, createNode(lineId)), right);
-  }
-  /**
-   * Delete a single element at the given 0-based index.
-   * Returns the removed lineId, or undefined if out of bounds.
-   * O(log N) expected.
-   */
-  deleteAt(index) {
-    if (index < 0 || index >= (this.root?.size ?? 0)) return void 0;
-    const [left, midRight] = split(this.root, index);
-    const [mid, right] = split(midRight, 1);
-    const removed = mid ? mid.lineId : void 0;
-    this.root = merge(left, right);
-    return removed;
-  }
-  /**
-   * Bulk splice: delete `deleteCount` elements at `startIndex` (0-based),
-   * then insert `newIds` in their place.
-   *
-   * Returns the removed lineId array.
-   * O(log N + deleteCount + insertCount) expected.
-   */
-  spliceAt(startIndex, deleteCount, newIds) {
-    const clampedStart = Math.max(0, startIndex);
-    const clampedCount = Math.min(
-      Math.max(0, deleteCount),
-      (this.root?.size ?? 0) - clampedStart
-    );
-    const [left, midRight] = split(this.root, clampedStart);
-    const [mid, right] = split(midRight, clampedCount);
-    const removed = collectInOrder(mid);
-    const newTree = buildTreap(newIds, 0, newIds.length);
-    this.root = merge(merge(left, newTree), right);
-    return removed;
-  }
-  /**
-   * Replace the entire tree with a new set of lineIds.
-   * O(N), builds a balanced treap from a flat array.
-   */
-  replaceAll(lineIds) {
-    this.root = buildTreap(lineIds, 0, lineIds.length);
-  }
-  /**
-   * Get a contiguous range of lineIds by index.
-   * O(rangeSize + log N), single in-order walk instead of N × O(log N).
-   *
-   * This is the hot path for viewport rendering in DocumentModel.getVisibleLines().
-   */
-  getRange(startIndex, endIndex) {
-    const clampedStart = Math.max(0, startIndex);
-    const clampedEnd = Math.min((this.root?.size ?? 0) - 1, endIndex);
-    if (clampedStart > clampedEnd) return [];
-    const result = [];
-    this.collectRange(this.root, clampedStart, clampedEnd, 0, result);
-    return result;
-  }
-  /**
-   * Clear the tree.
-   */
-  clear() {
-    this.root = null;
-  }
-  // ── Iteration ─────────────────────────────────────────────────────────
-  /**
-   * In-order iterator yielding all lineIds.
-   */
-  *[Symbol.iterator]() {
-    yield* this.inOrder(this.root);
-  }
-  *inOrder(node) {
-    if (!node) return;
-    yield* this.inOrder(node.left);
-    yield node.lineId;
-    yield* this.inOrder(node.right);
-  }
-  // ── Private helpers ───────────────────────────────────────────────────
-  nodeAt(node, index) {
-    const leftSize = node.left ? node.left.size : 0;
-    if (index < leftSize) {
-      return this.nodeAt(node.left, index);
-    } else if (index === leftSize) {
-      return node;
-    } else {
-      return this.nodeAt(node.right, index - leftSize - 1);
-    }
-  }
-  /**
-   * Collect all node values in the range [targetStart, targetEnd] into result.
-   * `offset` is the 0-based start of the current subtree within the full tree.
-   * O(rangeSize + log N), skips entire subtrees outside the target range.
-   */
-  collectRange(node, targetStart, targetEnd, offset, result) {
-    if (!node) return;
-    const leftSize = node.left ? node.left.size : 0;
-    const nodeIndex = offset + leftSize;
-    if (nodeIndex > targetStart && node.left) {
-      this.collectRange(node.left, targetStart, targetEnd, offset, result);
-    }
-    if (nodeIndex >= targetStart && nodeIndex <= targetEnd) {
-      result.push(node.lineId);
-    }
-    if (nodeIndex < targetEnd && node.right) {
-      this.collectRange(node.right, targetStart, targetEnd, nodeIndex + 1, result);
+      lineCache.push({
+        line,
+        expression,
+        result,
+        bytecode: serializeBytecode(entry.bytecode),
+        reads: entry.readVariables.slice(),
+        writeVar: entry.writeVariable
+      });
     }
+    const bytecodeCache = Array.from(this.bytecodeCache.entries()).map(([expression, program]) => ({
+      expression,
+      program: serializeBytecode(program)
+    }));
+    return {
+      format: SNAPSHOT_FORMAT,
+      version: SNAPSHOT_VERSION,
+      engineVersion: ENGINE_VERSION,
+      locale: this.localeCode,
+      variables,
+      userFunctions,
+      lineCache,
+      bytecodeCache
+    };
   }
-};
-function createNode(lineId) {
-  return {
-    lineId,
-    size: 1,
-    priority: Math.random(),
-    left: null,
-    right: null
-  };
-}
-function updateSize(node) {
-  node.size = 1 + (node.left ? node.left.size : 0) + (node.right ? node.right.size : 0);
-}
-function merge(left, right) {
-  if (!left) return right;
-  if (!right) return left;
-  if (left.priority > right.priority) {
-    left.right = merge(left.right, right);
-    updateSize(left);
-    return left;
-  } else {
-    right.left = merge(left, right.left);
-    updateSize(right);
-    return right;
-  }
-}
-function split(node, index) {
-  if (!node) return [null, null];
-  const leftSize = node.left ? node.left.size : 0;
-  if (index <= leftSize) {
-    const [left, right] = split(node.left, index);
-    node.left = right;
-    updateSize(node);
-    return [left, node];
-  } else {
-    const [left, right] = split(node.right, index - leftSize - 1);
-    node.right = left;
-    updateSize(node);
-    return [node, right];
-  }
-}
-function collectInOrder(node) {
-  const result = [];
-  collect(node, result);
-  return result;
-}
-function collect(node, result) {
-  if (!node) return;
-  collect(node.left, result);
-  result.push(node.lineId);
-  collect(node.right, result);
-}
-function buildTreap(lineIds, start, end) {
-  if (start >= end) return null;
-  const mid = Math.floor((start + end) / 2);
-  const priority = pseudoRandom(mid);
-  const node = {
-    lineId: lineIds[mid],
-    size: end - start,
-    priority,
-    left: buildTreap(lineIds, start, mid),
-    right: buildTreap(lineIds, mid + 1, end)
-  };
-  return node;
-}
-function pseudoRandom(seed) {
-  let x = seed;
-  x = (x >> 16 ^ x) * 73244475;
-  x = (x >> 16 ^ x) * 73244475;
-  x = x >> 16 ^ x;
-  return x / 4294967295;
-}
-
-// src/engine/DocumentModel.ts
-var DocumentModel = class {
-  /**
-   * @param maxLines - Ceiling on the line count, defaulting to the engine's
-   * configured one. Every line costs a LineState with six arrays in it
-   * whatever the line says, so the cost of a document is its line count and
-   * nothing else bounds it: two hundred thousand lines of `1 + 1` exhausted
-   * the heap here, before a single expression had been looked at.
-   */
-  constructor(maxLines = DEFAULT_CONFIG.performance.maxDocumentLines) {
-    /** Persistent line ID → LineState. */
-    this.lines = /* @__PURE__ */ new Map();
-    /** Order-statistic treap representing the current document line order. */
-    this.orderTree = new SegmentTree();
-    /** Monotonically increasing counter for new line IDs. */
-    this.nextLineId = 1;
-    /**
-     * Lazy position cache: lineId → 1-based position.
-     * Built on first `getLinePosition()` call, invalidated on structural edits.
-     */
-    this._positionCache = null;
-    /**
-     * Line IDs currently marked dirty, maintained alongside every
-     * `state.dirty` mutation (in this class and in every other module that
-     * holds a direct `LineState` reference: ThreeTierEvaluator, PageManager).
-     * Lets {@link hasAnyDirtyLineBefore} answer "is anything before position
-     * X dirty" in O(d log N), d = current dirty count, typically tiny once
-     * a document has settled after its initial evaluation, instead of
-     * O(N log N), which used to mean every scroll event re-walked the WHOLE
-     * document via `getLineAt()` regardless of how little of it was actually
-     * dirty. Benchmarked: ~10.6ms per setViewport() call scrolled near the
-     * bottom of a 20k-line document before this fix.
-     */
-    this.dirtyLineIds = /* @__PURE__ */ new Set();
-    this.maxLines = maxLines;
-  }
-  // ── Initialization ──────────────────────────────────────────────────
   /**
-   * Initialize or replace the entire document from a text blob.
-   * Clears all existing state and assigns new persistent line IDs.
-   *
-   * @throws `DOCUMENT_TOO_LARGE` for a document past {@link maxLines}, before
-   * any of it is stored. Recoverable: nothing has been replaced yet, so the
-   * model still holds whatever it held.
-   */
-  setDocument(text) {
-    const lineCount = countLines(text, this.maxLines);
-    if (lineCount > this.maxLines) {
-      throw ErrorFactory.execution(
-        "DOCUMENT_TOO_LARGE",
-        `This document has more than ${this.maxLines.toLocaleString("en-US")} lines, which is the most the engine will hold at once`,
-        { maxLines: this.maxLines }
+   * Restore a snapshot produced by {@link ExpressionEngine.toJSON} onto a
+   * fresh engine.
+   *
+   * The version gate runs first: a snapshot whose {@link EngineSnapshot.format}
+   * or {@link EngineSnapshot.version} does not match this engine's reader is
+   * refused with {@link SnapshotErrorCodes.SNAPSHOT_VERSION_MISMATCH} rather
+   * than restored wrongly. The engine is then built with the snapshot's locale
+   * (unless overridden) and the given `packages`, and its variable table,
+   * user-function registry, line cache, dependency graph, and bytecode cache
+   * are rehydrated from the snapshot.
+   *
+   * @param snapshot - A snapshot object, typically straight from `JSON.parse`.
+   * @param options - Packages (must match those the snapshot was taken with),
+   *   plus optional config, diagnostic mode, and locale override. See
+   *   {@link EngineRestoreOptions}.
+   * @returns A ready engine that behaves as though it had evaluated the
+   *   original document.
+   * @throws {@link SnapshotErrorCodes.SNAPSHOT_VERSION_MISMATCH} for a missing
+   *   or mismatched envelope, and
+   *   {@link SnapshotErrorCodes.SNAPSHOT_MALFORMED} for internally
+   *   inconsistent contents.
+   */
+  static fromJSON(snapshot, options = {}) {
+    assertRestorable(snapshot);
+    const locale = options.locale ?? snapshot.locale ?? "en";
+    const engine = new _ExpressionEngine(locale, options.diagnosticMode ?? false, options.config, void 0, options.packages);
+    engine.restoreSnapshot(snapshot);
+    return engine;
+  }
+  /**
+   * Rehydrate this engine's state from a snapshot whose envelope has already
+   * been validated by {@link assertRestorable}. Instance-private, the public
+   * entry point is the static {@link ExpressionEngine.fromJSON}.
+   */
+  restoreSnapshot(snapshot) {
+    for (const [name, sv] of Object.entries(snapshot.variables)) {
+      this.vm.setVar(name, deserializeValue(sv));
+    }
+    for (const fn of snapshot.userFunctions) {
+      const def = deserializeUserFunction(fn);
+      this.vm.defineUserFunction(def.name, def.params, def.program);
+    }
+    for (const e of snapshot.lineCache) {
+      const entry = new LineCacheEntry(
+        deserializeValue(e.result),
+        deserializeBytecode(e.bytecode),
+        e.reads.slice(),
+        e.writeVar
       );
+      this.lineCache.set(e.line, entry, e.expression);
+      this.dag.registerLine(e.line, e.reads, e.writeVar ? [e.writeVar] : []);
     }
-    this.lines.clear();
-    this.orderTree.clear();
-    this._positionCache = null;
-    this.dirtyLineIds.clear();
-    this.nextLineId = 1;
-    const rawLines = text.split("\n");
-    const lineIds = new Array(rawLines.length);
-    for (let i = 0; i < rawLines.length; i++) {
-      const lineId = this.nextLineId++;
-      lineIds[i] = lineId;
-      this.lines.set(lineId, {
-        lineId,
-        textHash: djb2Hash(rawLines[i]),
-        text: rawLines[i],
-        expressions: [],
-        bytecodes: [],
-        reads: [],
-        writes: [],
-        results: [],
-        result: null,
-        dirty: true,
-        isVariableDef: false,
-        isEmpty: rawLines[i].trim().length === 0,
-        inlineSolveCount: 0
-      });
+    for (const { expression, program } of snapshot.bytecodeCache) {
+      this.bytecodeCache.set(expression, deserializeBytecode(program));
     }
-    this.orderTree.replaceAll(lineIds);
-    for (const id of lineIds) this.dirtyLineIds.add(id);
   }
-  // ── Structural edits ────────────────────────────────────────────────
+  //#endregion
+  //#region Public API, Incremental evaluation
   /**
-   * Apply one or more line-level changes to the document.
-   *
-   * **Precondition:** Changes must be **non-overlapping** in their line ranges.
-   * If two changes target the same or adjacent lines, the reverse-order
-   * processing may produce incorrect results because the first-applied
-   * change shifts the line numbers that the second change references.
-   *
-   * Changes are applied in **reverse order** (highest startLine first) so
-   * that earlier changes in the document don't shift the indices of later
-   * changes during processing.
-   *
-   * Returns both the newly inserted line IDs and the removed line IDs.
-   * Callers should use `removed` to clean up the dependency graph and
-   * other data structures keyed by lineId.
+   * Incrementally re-evaluate lines affected by a variable change.
+   * Walks the DAG from the changed variable to find exactly which lines
+   * need re-execution, no dirty-set indirection, no sorting guesswork.
+   * Uses Kahn's algorithm for topological ordering: producers always
+   * execute before consumers, regardless of document line order.
    */
-  applyChanges(changes) {
-    const inserted = [];
-    const removed = [];
-    const sorted = [...changes].sort((a, b) => b.startLine - a.startLine);
-    for (const change of sorted) {
-      const startIdx = change.startLine - 1;
-      const newIds = [];
-      for (const text of change.insertLines) {
-        const lineId = this.nextLineId++;
-        newIds.push(lineId);
-        inserted.push(lineId);
-        this.lines.set(lineId, {
-          lineId,
-          textHash: djb2Hash(text),
-          text,
-          expressions: [],
-          bytecodes: [],
-          reads: [],
-          writes: [],
-          results: [],
-          result: null,
-          dirty: true,
-          isVariableDef: false,
-          isEmpty: text.trim().length === 0,
-          inlineSolveCount: 0
-        });
+  evaluateIncremental(variable, newValue) {
+    const affectedLines = this.dag.getAffectedLinesInOrder(variable);
+    this.vm.setVar(variable, numberValue(newValue));
+    const updated = /* @__PURE__ */ new Map();
+    for (const lineNumber of affectedLines) {
+      const entry = this.lineCache.getEntryForLine(lineNumber);
+      if (!entry || entry.bytecode.opcodes.length === 0) continue;
+      const evalResult = this.executeRaw(entry.bytecode, lineNumber);
+      if (evalResult.type === "pending") {
+        void this.resolveAsync(evalResult);
+        continue;
       }
-      for (const id of newIds) this.dirtyLineIds.add(id);
-      const removedIds = this.orderTree.spliceAt(
-        startIdx,
-        change.deleteCount,
-        newIds
-      );
-      for (const id of removedIds) {
-        removed.push(id);
-        this.lines.delete(id);
-        this.dirtyLineIds.delete(id);
+      if (evalResult.type === "error") {
+        const value = errorValue(evalResult.error.code, evalResult.error.message);
+        updated.set(lineNumber, value);
+        entry.result = value;
+        continue;
       }
+      const result = evalResult.value;
+      updated.set(lineNumber, result);
+      entry.result = result;
     }
-    this._positionCache = null;
-    return { inserted, removed };
+    return updated;
   }
-  /**
-   * Insert new lines at the given 1-based position.
-   * Convenience wrapper around applyChanges.
-   */
-  insertLines(atLine, texts) {
-    const change = {
-      startLine: atLine,
-      deleteCount: 0,
-      insertLines: texts
-    };
-    const result = this.applyChanges([change]);
-    return result.inserted;
+  //#endregion
+};
+/** The most nesting {@link makeLineContext}'s `evaluateLineWithBinding` allows before refusing, so the bisection re-runs can never compound. */
+_ExpressionEngine.GOAL_SEEK_MAX_NESTING_DEPTH = 1;
+var ExpressionEngine = _ExpressionEngine;
+
+// src/workers/engine.worker.ts
+var engine_worker_default = (() => {
+  throw new Error("engine.worker.ts was not processed by esbuild-plugin-inline-worker, so worker offload is unavailable");
+});
+var compileEngine = null;
+function getCompileEngine() {
+  if (!compileEngine) {
+    compileEngine = new ExpressionEngine("en", false);
   }
-  /**
-   * Delete lines in the given 1-based range [startLine, endLine] inclusive.
-   * Convenience wrapper around applyChanges.
-   */
-  deleteLines(startLine, endLine) {
-    const change = {
-      startLine,
-      deleteCount: endLine - startLine + 1,
-      insertLines: []
-    };
-    const result = this.applyChanges([change]);
-    return result.removed;
+  return compileEngine;
+}
+var executeVm = null;
+function getExecuteVm() {
+  if (!executeVm) {
+    executeVm = createVM(sharedOpRegistry, 200, 5e4);
   }
-  /**
-   * Update the text of a single line in place.
-   * If the text hash differs, marks the line dirty and clears its
-   * bytecode/result so it gets re-evaluated.
-   *
-   * Returns true if the text actually changed (hash mismatch).
-   */
-  editLine(lineNumber, newText) {
-    const state = this.getLineAt(lineNumber);
-    if (!state) return false;
-    const newHash = djb2Hash(newText);
-    if (newHash === state.textHash) return false;
-    state.text = newText;
-    state.textHash = newHash;
-    state.expressions = [];
-    state.bytecodes = [];
-    state.results = [];
-    state.result = null;
-    state.inlineSolveCount = 0;
-    state.dirty = true;
-    this.dirtyLineIds.add(state.lineId);
-    state.isEmpty = newText.trim().length === 0;
-    return true;
+  return executeVm;
+}
+function compileOne(item) {
+  const base = {
+    lineId: item.lineId,
+    expression: item.expression,
+    compiledAgainstHash: item.textHash,
+    strings: [],
+    reads: [],
+    writes: [],
+    isVariableDef: false,
+    error: null
+  };
+  try {
+    const eng = getCompileEngine();
+    const { program, reads, writes } = eng.compileExpression(item.expression);
+    const isVariableDef = writes.length > 0;
+    const opcodes = program.opcodes;
+    const numbers = program.numbers;
+    const opcodesBuffer = opcodes.buffer.slice(
+      opcodes.byteOffset,
+      opcodes.byteOffset + opcodes.byteLength
+    );
+    const numbersBuffer = numbers.buffer.slice(
+      numbers.byteOffset,
+      numbers.byteOffset + numbers.byteLength
+    );
+    return {
+      ...base,
+      opcodesBuffer,
+      numbersBuffer,
+      opcodesLength: opcodes.length,
+      numbersLength: numbers.length,
+      strings: [...program.strings],
+      reads,
+      writes,
+      isVariableDef
+    };
+  } catch (e) {
+    return {
+      ...base,
+      opcodesBuffer: new ArrayBuffer(0),
+      numbersBuffer: new ArrayBuffer(0),
+      opcodesLength: 0,
+      numbersLength: 0,
+      error: e instanceof Error ? e.message : String(e)
+    };
   }
-  // ── Queries ─────────────────────────────────────────────────────────
-  /**
-   * Get the LineState at the given 1-based line position. O(1).
-   */
-  getLineAt(position) {
-    const idx = position - 1;
-    const lineId = this.orderTree.getAt(idx);
-    if (lineId === void 0) return void 0;
-    return this.lines.get(lineId);
+}
+function handleCompileBatch(msg) {
+  const results = [];
+  const transferList = [];
+  for (const item of msg.items) {
+    const result = compileOne(item);
+    results.push(result);
+    if (result.opcodesBuffer.byteLength > 0) transferList.push(result.opcodesBuffer);
+    if (result.numbersBuffer.byteLength > 0) transferList.push(result.numbersBuffer);
   }
-  /**
-   * Get the 1-based position of a line by its persistent ID.
-   * Returns -1 if the line ID is not in the document.
-   *
-   * Uses a lazy position cache: O(N) on first call after structural edit,
-   * O(1) on subsequent calls. The cache is invalidated by any structural edit.
-   */
-  getLinePosition(lineId) {
-    if (this._positionCache) {
-      return this._positionCache.get(lineId) ?? -1;
+  self.postMessage(
+    { id: msg.id, type: "COMPILE_RESULT", results },
+    transferList
+  );
+}
+function executeOne(item) {
+  const vmm = getExecuteVm();
+  vmm.reset();
+  const opcodes = new Uint8Array(item.opcodesBuffer, 0, item.opcodesLength);
+  const numbers = new Float64Array(item.numbersBuffer, 0, item.numbersLength);
+  const bytecode = { opcodes, numbers, strings: item.strings };
+  try {
+    const result = executeBytecode(bytecode, vmm);
+    if (result.type === "pending") {
+      return {
+        lineNumber: item.lineNumber,
+        valueType: 12 /* Pending */,
+        value: 0,
+        isPending: true,
+        queryKey: result.queryKey
+      };
     }
-    this._positionCache = /* @__PURE__ */ new Map();
-    let pos = 1;
-    for (const id of this.orderTree) {
-      this._positionCache.set(id, pos++);
+    if (result.type === "error") {
+      return {
+        lineNumber: item.lineNumber,
+        valueType: 13 /* Error */,
+        value: 0,
+        isPending: false,
+        unit: result.error.message
+      };
     }
-    return this._positionCache.get(lineId) ?? -1;
+    const val = result.value;
+    return {
+      lineNumber: item.lineNumber,
+      valueType: val.type,
+      value: typeof val.value === "number" ? val.value : typeof val.value === "bigint" ? Number(val.value) : 0,
+      unit: val.unit,
+      isPending: false
+    };
+  } catch {
+    return {
+      lineNumber: item.lineNumber,
+      valueType: 13 /* Error */,
+      value: 0,
+      isPending: false,
+      unit: "Worker execution failed"
+    };
   }
-  /**
-   * Get all LineState entries within the given viewport range (1-based, inclusive).
-   * Uses SegmentTree.getRange() for O(viewport + log N) collection instead of
-   * O(viewport × log N) per-line lookups.
-   */
-  getVisibleLines(startLine, endLine) {
-    const lineIds = this.orderTree.getRange(startLine - 1, endLine - 1);
-    const result = [];
-    for (const lineId of lineIds) {
-      const state = this.lines.get(lineId);
-      if (state) result.push(state);
-    }
-    return result;
+}
+function handleExecuteBatch(msg) {
+  const results = [];
+  for (const item of msg.items) {
+    results.push(executeOne(item));
   }
-  /**
-   * Get all LineState entries in order. Useful for batch processing.
-   */
-  getAllLines() {
-    return this.getVisibleLines(1, this.lineCount);
+  self.postMessage({
+    id: msg.id,
+    type: "EXECUTE_RESULT",
+    results
+  });
+}
+var inWorkerScope = typeof self !== "undefined" && typeof window === "undefined";
+var handleMessage = (event) => {
+  if (event.origin && self.location && event.origin !== self.location.origin) return;
+  const msg = event.data;
+  switch (msg.type) {
+    case "COMPILE_BATCH":
+      handleCompileBatch(msg);
+      break;
+    case "EXECUTE_BATCH":
+      handleExecuteBatch(msg);
+      break;
+    case "TERMINATE": {
+      if (compileEngine) {
+        compileEngine.clear();
+        compileEngine = null;
+      }
+      if (executeVm) {
+        executeVm.reset();
+        executeVm = null;
+      }
+      self.postMessage({
+        id: msg.id,
+        type: "COMPILE_RESULT",
+        results: []
+      });
+      break;
+    }
+    default: {
+      self.postMessage({
+        id: -1,
+        type: "COMPILE_RESULT",
+        results: [],
+        error: `Unknown message type: ${msg.type}`
+      });
+    }
   }
-  /**
-   * Get a LineState by its persistent line ID. O(1).
-   */
-  getLineById(lineId) {
-    return this.lines.get(lineId);
+};
+if (inWorkerScope) {
+  self.onmessage = handleMessage;
+}
+
+// src/engine/ExecutionPool.ts
+var WORKER_BATCH_TIMEOUT_MS = 3e4;
+var WORKER_OFFLOAD_THRESHOLD = 50;
+var ExecutionPool = class {
+  constructor(poolSize) {
+    this.workers = [];
+    this.nextWorker = 0;
+    this.nextId = 1;
+    this.pendingBatches = /* @__PURE__ */ new Map();
+    this.terminated = false;
+    // ── Public API ────────────────────────────────────────────────────────
+    /** Cached availability flag. Checked once; createExecutionWorker never called again. */
+    this._available = null;
+    this.poolSize = Math.min(poolSize ?? this.defaultPoolSize(), 4);
   }
-  /**
-   * Get all lines that are marked dirty.
-   */
-  getDirtyLines() {
-    const result = [];
-    for (const state of this.lines.values()) {
-      if (state.dirty) result.push(state);
+  defaultPoolSize() {
+    if (typeof navigator !== "undefined" && navigator.hardwareConcurrency) {
+      return Math.min(navigator.hardwareConcurrency, 4);
     }
-    return result;
+    return 2;
   }
   /**
-   * Whether any line before `position` (1-based, exclusive) is dirty.
-   *
-   * Used by ThreeTierEvaluator.setViewport() to decide whether cached
-   * checkpoint state might be stale and a full evaluate() (from line 1) is
-   * needed instead of the cheap viewport-only path.
-   *
-   * O(d log N) where d = current dirty line count via {@link dirtyLineIds},
-   * not O(N log N), a document that's mostly clean (the steady state after
-   * initial load) answers this in the cost of resolving a handful of
-   * lineIds to positions, not walking every line up to `position`.
+   * Whether worker-based execution is available.
+   * Returns false in Node.js / jsdom test environments where Worker
+   * may be polyfilled but execution workers aren't functional.
    */
-  hasAnyDirtyLineBefore(position) {
-    for (const lineId of this.dirtyLineIds) {
-      const pos = this.getLinePosition(lineId);
-      if (pos >= 1 && pos < position) return true;
+  isAvailable() {
+    if (this.terminated) return false;
+    if (this._available !== null) return this._available;
+    if (typeof Worker === "undefined") {
+      this._available = false;
+      return false;
     }
-    return false;
-  }
-  /**
-   * Whether any **variable-definition** line before `position` (1-based,
-   * exclusive) is dirty.
-   *
-   * Narrower than {@link hasAnyDirtyLineBefore}: `VMCheckpointer.snapshot()`
-   * only ever records state for lines with `writes.length > 0` (see
-   * VMCheckpoints.ts), so a dirty plain-expression line before the viewport
-   * cannot have invalidated any checkpoint, there's no checkpoint entry
-   * for it to invalidate. Only a dirty variable-def line can mean the VM
-   * state a checkpoint would restore is stale.
-   *
-   * This distinction matters because `PageManager.evictPageBytecode()`
-   * marks evicted non-variable-def lines dirty (so they get Tier 1 if
-   * scrolled back into view), and Tier 3's compile-only path never clears
-   * `dirty` for non-variable-def lines by design. Using the broader
-   * `hasAnyDirtyLineBefore` here meant scrolling far into a large,
-   * variable-def-free document would trip `setViewport()`'s fallback to
-   * `evaluate()` on every single call, evaluate() reprocesses the evicted
-   * lines via Tier 3, which recompiles their bytecode without clearing
-   * dirty, so the very next `maintainAfterEval()` re-evicts and re-dirties
-   * the same lines, forever re-triggering the fallback on an otherwise
-   * unchanged viewport.
-   */
-  hasAnyDirtyVariableDefLineBefore(position) {
-    for (const lineId of this.dirtyLineIds) {
-      const state = this.lines.get(lineId);
-      if (!state || !state.isVariableDef) continue;
-      const pos = this.getLinePosition(lineId);
-      if (pos >= 1 && pos < position) return true;
+    try {
+      const w = engine_worker_default();
+      w.terminate();
+      this._available = true;
+      return true;
+    } catch {
+      this._available = false;
+      return false;
     }
-    return false;
   }
-  /** Number of lines currently marked dirty. For diagnostics/tests. */
-  get dirtyCount() {
-    return this.dirtyLineIds.size;
-  }
-  // ── Thread-safety validation ────────────────────────────────────────
   /**
-   * Verify that bytecode compiled by a worker is still valid for this line.
+   * Execute a batch of line entries via the worker pool.
    *
-   * When Phase 5.2h sends compilation to a worker, the worker posts back
-   * `{lineId, bytecode, reads, writes, compiledAgainstHash}`. Between dispatch
-   * and response, the user may have edited the line. This method lets the
-   * main thread check whether the bytecode is still applicable.
+   * Takes ordered line numbers and their LineCache entries. Clones bytecode
+   * ArrayBuffers for transfer, dispatches to workers round-robin, and
+   * returns the serialized results (with 30s timeout fallback).
    *
-   * @returns true if the line still exists and its text hash matches.
-   */
-  isBytecodeValid(lineId, compiledAgainstHash) {
-    const state = this.lines.get(lineId);
-    return state !== void 0 && state.textHash === compiledAgainstHash;
-  }
-  // ── State mutations ─────────────────────────────────────────────────
-  /**
-   * Mark a line as clean (re-evaluated successfully).
+   * Falls back to undefined when workers are unavailable, caller should
+   * use the main-thread path.
+   *
+   * @returns ExecuteResult[] on success, undefined if workers unavailable.
    */
-  markClean(lineId) {
-    const state = this.lines.get(lineId);
-    if (state) {
-      state.dirty = false;
-      this.dirtyLineIds.delete(lineId);
+  executeBatch(orderedLineNumbers, entries) {
+    if (!this.isAvailable()) return void 0;
+    if (orderedLineNumbers.length === 0) return Promise.resolve([]);
+    this.ensureWorkers();
+    const items = [];
+    for (const lineNumber of orderedLineNumbers) {
+      const entry = entries.get(lineNumber);
+      if (!entry || entry.bytecode.opcodes.length === 0) continue;
+      const opcodes = entry.bytecode.opcodes;
+      const numbers = entry.bytecode.numbers;
+      const opcodesClone = opcodes.buffer.slice(
+        opcodes.byteOffset,
+        opcodes.byteOffset + opcodes.byteLength
+      );
+      const numbersClone = numbers.buffer.slice(
+        numbers.byteOffset,
+        numbers.byteOffset + numbers.byteLength
+      );
+      items.push({
+        lineNumber,
+        opcodesBuffer: opcodesClone,
+        numbersBuffer: numbersClone,
+        opcodesLength: opcodes.length,
+        numbersLength: numbers.length,
+        strings: [...entry.bytecode.strings]
+      });
     }
-  }
-  /**
-   * Mark a line as dirty (needs re-evaluation) by its 1-based position.
-   * Convenience for callers that have line numbers instead of line IDs.
-   */
-  markDirtyByLineNumber(lineNumber) {
-    const state = this.getLineAt(lineNumber);
-    if (state) {
-      state.dirty = true;
-      this.dirtyLineIds.add(state.lineId);
+    if (items.length === 0) return Promise.resolve([]);
+    const transferList = [];
+    for (const item of items) {
+      if (item.opcodesBuffer.byteLength > 0) transferList.push(item.opcodesBuffer);
+      if (item.numbersBuffer.byteLength > 0) transferList.push(item.numbersBuffer);
     }
+    const batchId = this.nextId++;
+    const worker = this.getNextWorker();
+    return new Promise((resolve) => {
+      const timeoutId = setTimeout(() => {
+        this.pendingBatches.delete(batchId);
+        resolve([]);
+      }, WORKER_BATCH_TIMEOUT_MS);
+      this.pendingBatches.set(batchId, {
+        id: batchId,
+        lineNumbers: orderedLineNumbers,
+        resolve: (results) => {
+          clearTimeout(timeoutId);
+          resolve(results);
+        }
+      });
+      worker.postMessage(
+        { type: "EXECUTE_BATCH", id: batchId, items },
+        transferList
+      );
+    });
   }
   /**
-   * Mark a line as dirty (needs re-evaluation).
+   * Clean up all workers and pending batches. Called on engine clear.
+   * Workers are recreated lazily on next dispatch.
    */
-  markDirty(lineId) {
-    const state = this.lines.get(lineId);
-    if (state) {
-      state.dirty = true;
-      this.dirtyLineIds.add(lineId);
+  clear() {
+    for (const [, batch] of this.pendingBatches) {
+      batch.resolve([]);
     }
-  }
-  /**
-   * Mark all lines as dirty (e.g., after plugin register/unregister).
-   */
-  invalidateAll() {
-    for (const state of this.lines.values()) {
-      state.dirty = true;
+    this.pendingBatches.clear();
+    for (const w of this.workers) {
+      w.terminate();
     }
-    this.dirtyLineIds = new Set(this.lines.keys());
-  }
-  /**
-   * Update a line's evaluation state after successful execution (Tier 1 / Tier 2).
-   *
-   * Sets results, bytecodes, reads, writes, and marks the line clean.
-   * Supports multi-expression lines (inline solves) via parallel arrays.
-   *
-   * @param lineId - Persistent line identifier.
-   * @param results - Evaluation result groups for each expression (in order). Each element is a Value[].
-   * @param bytecodes - Compiled bytecode for each expression (in order).
-   * @param expressions - Extracted expression strings (in order).
-   * @param reads - Aggregated read variables across all expressions.
-   * @param writes - Aggregated write variables across all expressions.
-   * @param isVariableDef - True if any expression defines a variable.
-   * @param inlineSolveCount - Number of inline solves (0 for full-line).
-   */
-  updateLineResult(lineId, results, bytecodes, expressions, reads, writes, isVariableDef, inlineSolveCount = 0) {
-    const state = this.lines.get(lineId);
-    if (!state) return;
-    state.results = results;
-    state.result = results[0]?.[0] ?? null;
-    state.bytecodes = bytecodes;
-    state.expressions = expressions;
-    state.reads = reads;
-    state.writes = writes;
-    state.isVariableDef = isVariableDef;
-    state.inlineSolveCount = inlineSolveCount;
-    state.dirty = false;
-    this.dirtyLineIds.delete(lineId);
+    this.workers = [];
+    this.nextWorker = 0;
   }
   /**
-   * Update a line's compile-only state (Tier 3: background compilation).
-   *
-   * Stores expressions, bytecodes, reads, and writes. Does NOT set results
-   * and does NOT mark the line clean, it still needs execution (Tier 1 or
-   * Tier 2) to produce results. This distinction allows the three-tier
-   * evaluation strategy: compile invisible lines in the background without
-   * executing them, then execute from cached bytecode when scrolled into view.
-   *
-   * @param lineId - Persistent line identifier.
-   * @param expressions - Extracted expression strings (in order).
-   * @param bytecodes - Compiled bytecode for each expression (in order).
-   * @param reads - Aggregated read variables across all expressions.
-   * @param writes - Aggregated write variables across all expressions.
-   * @param isVariableDef - True if any expression defines a variable.
-   * @param inlineSolveCount - Number of inline solves (0 for full-line).
+   * Full teardown. After destroy(), the pool is permanently unusable.
    */
-  updateLineCompiled(lineId, expressions, bytecodes, reads, writes, isVariableDef, inlineSolveCount = 0) {
-    const state = this.lines.get(lineId);
-    if (!state) return;
-    state.expressions = expressions;
-    state.bytecodes = bytecodes;
-    state.reads = reads;
-    state.writes = writes;
-    state.isVariableDef = isVariableDef;
-    state.inlineSolveCount = inlineSolveCount;
-  }
-  // ── Properties ──────────────────────────────────────────────────────
-  get lineCount() {
-    return this.orderTree.length;
-  }
-  get isEmpty() {
-    return this.orderTree.isEmpty;
+  destroy() {
+    this.terminated = true;
+    this.clear();
   }
-  /**
-   * Iterator over LineState in document order.
-   */
-  *[Symbol.iterator]() {
-    for (const lineId of this.orderTree) {
-      const state = this.lines.get(lineId);
-      if (state) yield state;
+  // ── Private ────────────────────────────────────────────────────────────
+  ensureWorkers() {
+    if (this.workers.length > 0) return;
+    for (let i = 0; i < this.poolSize; i++) {
+      const worker = engine_worker_default();
+      worker.onmessage = (event) => {
+        this.handleWorkerMessage(event.data);
+      };
+      worker.onerror = (err) => {
+        console.error(`[ExecutionPool] Worker ${i} error:`, err.message);
+        for (const [id, batch] of this.pendingBatches) {
+          batch.resolve([]);
+          this.pendingBatches.delete(id);
+        }
+      };
+      this.workers.push(worker);
     }
   }
-  // ── Lifecycle ───────────────────────────────────────────────────────
-  clear() {
-    this.lines.clear();
-    this.orderTree.clear();
-    this._positionCache = null;
-    this.nextLineId = 1;
+  getNextWorker() {
+    const w = this.workers[this.nextWorker];
+    this.nextWorker = (this.nextWorker + 1) % this.workers.length;
+    return w;
   }
-  /**
-   * Serialize the document model to a plain object for debugging.
-   */
-  toJSON() {
-    return {
-      lineCount: this.lineCount,
-      lines: this.getAllLines().map((s) => ({
-        lineId: s.lineId,
-        text: s.text.substring(0, 80),
-        // truncate for readability
-        textHash: s.textHash,
-        dirty: s.dirty,
-        isVariableDef: s.isVariableDef,
-        isEmpty: s.isEmpty,
-        hasBytecode: s.bytecodes.length > 0,
-        hasResult: s.results.length > 0,
-        inlineSolveCount: s.inlineSolveCount,
-        reads: s.reads,
-        writes: s.writes
-      }))
-    };
+  handleWorkerMessage(data) {
+    if (data.type !== "EXECUTE_RESULT") return;
+    const batch = this.pendingBatches.get(data.id);
+    if (!batch) return;
+    this.pendingBatches.delete(data.id);
+    batch.resolve(data.results);
   }
 };
-
-// src/engine/CompilationWorkerManager.ts
-var CompilationWorkerManager = class {
-  constructor() {
-    this.worker = null;
-    this.nextId = 1;
-    this.pending = /* @__PURE__ */ new Map();
-  }
-  /**
-   * Ensure the worker is started (lazy initialization).
-   * Uses esbuild-plugin-inline-worker to inline the worker as a blob URL.
-   */
-  ensureWorker() {
-    if (this.worker) return this.worker;
-    this.worker = engine_worker_default();
-    this.worker.onmessage = (event) => {
-      const data = event.data;
-      if (!data || data.type !== "COMPILE_RESULT") return;
-      const pending = this.pending.get(data.id);
-      if (!pending) return;
-      this.pending.delete(data.id);
-      const results = [];
-      for (const raw of data.results) {
-        results.push(this.reconstructResult(raw));
-      }
-      pending.resolve(results);
-    };
-    this.worker.onerror = (err) => {
-      for (const [id, pending] of this.pending) {
-        pending.reject(
-          new Error(`Compilation worker error: ${err.message}`)
-        );
-        this.pending.delete(id);
-      }
-    };
-    return this.worker;
+function reconstructValue(result) {
+  switch (result.valueType) {
+    case 0 /* Number */:
+      return numberValue(result.value);
+    case 1 /* Hex */:
+      return hexValue(result.value);
+    case 2 /* BigInt */:
+      return bigIntValue(BigInt(result.value));
+    case 3 /* String */:
+      return stringValue(String(result.value));
+    case 4 /* Datetime */:
+      return datetimeValue(result.value);
+    case 5 /* Percentage */:
+      return percentageValue(result.value);
+    case 6 /* Uom */:
+      return uomValue(result.value, result.unit ?? "");
+    case 7 /* Matrix */:
+      return numberValue(result.value);
+    case 10 /* Boolean */:
+      return boolValue(result.value !== 0);
+    case 12 /* Pending */:
+      return pendingValue(result.queryKey ?? "");
+    case 13 /* Error */:
+      return errorValue("WORKER_EXECUTION_ERROR", result.unit ?? "Unknown worker error");
+    default:
+      return numberValue(result.value);
   }
-  /**
-   * Batch-compile expressions in the worker.
-   *
-   * Sends a batch of { lineId, expression, textHash } to the worker,
-   * which compiles each and transfers bytecode ArrayBuffers back.
-   * Bytecode is reconstructed into BytecodeProgram objects.
-   *
-   * Results are returned in the same order as the input items.
-   *
-   * @param items Expressions to compile.
-   * @returns Compiled bytecode for each item (or error).
-   */
-  async compileBatch(items) {
-    if (items.length === 0) return [];
-    const worker = this.ensureWorker();
-    const id = this.nextId++;
-    return new Promise((resolve, reject) => {
-      this.pending.set(id, { resolve, reject });
-      worker.postMessage({
-        type: "COMPILE_BATCH",
-        id,
-        items
-      });
-    });
+}
+
+// src/engine/AsyncResolutionBatcher.ts
+var _AsyncResolutionBatcher = class _AsyncResolutionBatcher {
+  constructor(dag, lineCache, vm, highWaterMark = _AsyncResolutionBatcher.DEFAULT_HIGH_WATER_MARK) {
+    this.pending = [];
+    this.scheduled = false;
+    /** Set to true by clearPending(), flush() checks this to abort stale work. */
+    this.cleared = false;
+    /**
+     * Worker pool for offloading VM re-execution when the affected line
+     * count exceeds WORKER_OFFLOAD_THRESHOLD (50). Lazily created on
+     * first dispatch; cleared on clearAll().
+     */
+    this.executionPool = null;
+    /**
+     * Number of flushes actually dispatched to the worker pool (as opposed
+     * to falling back to the main thread because Worker is unavailable).
+     * Exposed via {@link workerOffloadCount} for the Workers diagnostic tab.
+     */
+    this.workerOffloadDispatchCount = 0;
+    /**
+     * Controller for the internal event stream. Set during stream
+     * initialization; cleared on stream cancellation or clearAll().
+     */
+    this._streamController = null;
+    /**
+     * Test-only synchronous capture array. When enabled (non-null), every
+     * event is synchronously pushed here in addition to the stream.
+     * Tests read from this array to avoid async stream reader timing issues.
+     */
+    this._testCaptures = null;
+    /**
+     * Called for each line whose result is patched after an async resolution,
+     * on both the main-thread and worker-pool paths.
+     *
+     * **A host that displays async results must set this.** It is the only
+     * mechanism that moves a resolved value out of the LineCache and into the
+     * host's own document state. The engine cannot do it itself: it does not own
+     * a document, the host does, and the batcher has no reference to one.
+     *
+     * Nullable rather than a constructor parameter because it is cleared by
+     * `clearAll()` and re-wired on re-subscribe, so it cannot be readonly. That
+     * makes it easy to miss, which is why {@link warnIfUnwired} exists: leaving
+     * it unset means async values resolve into the cache and are never shown,
+     * with nothing to indicate why. A host that genuinely does not want async
+     * results should not register async resolvers at all.
+     */
+    this.onLineResult = null;
+    /**
+     * Whether {@link warnIfUnwired} has already fired.
+     *
+     * Once per instance, not once per resolution. A document with fifty live
+     * data lines would otherwise produce fifty identical warnings on the first
+     * fetch, which is how a useful warning becomes noise people filter out.
+     */
+    this.warnedAboutMissingHook = false;
+    this.dag = dag;
+    this.lineCache = lineCache;
+    this.vm = vm;
+    this.highWaterMark = highWaterMark;
+    this._eventStream = this.createEventStream();
   }
   /**
-   * Store worker-compiled bytecode into the DocumentModel, with safety
-   * validation. Only stores bytecode for lines whose text has not changed
-   * since the compilation request was dispatched.
-   *
-   * Results for the same lineId are batched, all bytecodes from
-   * successful compilations are passed to updateLineCompiled in a single
-   * call. This supports multi-expression lines (inline solves).
+   * Warn once if an async result resolved with no {@link onLineResult} wired.
    *
-   * @param results Compiled results from the worker.
-   * @param doc The target document model.
-   * @returns Number of results successfully stored (passed safety check).
-   */
-  storeResults(results, doc) {
-    const byLineId = /* @__PURE__ */ new Map();
-    for (const result of results) {
-      if (result.error) continue;
-      const state = doc.getLineById(result.lineId);
-      if (!state) continue;
-      if (state.textHash !== result.compiledAgainstHash) continue;
-      let batch = byLineId.get(result.lineId);
-      if (!batch) {
-        batch = {
-          bytecodes: [],
-          reads: /* @__PURE__ */ new Set(),
-          writes: /* @__PURE__ */ new Set(),
-          isVariableDef: false,
-          expressions: state.expressions.length > 0 ? [...state.expressions] : [],
-          textHash: result.compiledAgainstHash
-        };
-        byLineId.set(result.lineId, batch);
-      }
-      batch.bytecodes.push(result.program);
-      for (const r of result.reads) batch.reads.add(r);
-      for (const w of result.writes) batch.writes.add(w);
-      if (result.isVariableDef) batch.isVariableDef = true;
-    }
-    let stored = 0;
-    for (const [lineId, batch] of byLineId) {
-      if (batch.bytecodes.length === 0) continue;
-      const state = doc.getLineById(lineId);
-      const inlineSolveCount = state?.inlineSolveCount ?? 0;
-      doc.updateLineCompiled(
-        lineId,
-        batch.expressions,
-        batch.bytecodes,
-        [...batch.reads],
-        [...batch.writes],
-        batch.isVariableDef,
-        inlineSolveCount
-      );
-      stored += batch.bytecodes.length;
-    }
-    return stored;
-  }
-  /**
-   * Terminate the worker and clean up.
+   * The failure this catches is silent by nature: the value arrives, the cache
+   * updates, and the line keeps showing pending forever. Without this a host
+   * author has no thread to pull on.
    */
-  terminate() {
-    if (this.worker) {
-      this.worker.terminate();
-      this.worker = null;
-      this.pending.clear();
-    }
+  warnIfUnwired() {
+    if (this.onLineResult || this.warnedAboutMissingHook) return;
+    this.warnedAboutMissingHook = true;
+    console.warn(
+      "[solve-engine] An async result resolved but AsyncResolutionBatcher.onLineResult is not set, so the value cannot reach your document and the line will keep showing as pending. Set it to mirror resolved values into your own state. This warning appears once per batcher."
+    );
   }
   /**
-   * Whether the worker is currently active.
+   * 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.
    */
-  get isActive() {
-    return this.worker !== null;
+  createEventStream() {
+    return new ReadableStream({
+      start: (controller) => {
+        this._streamController = controller;
+      },
+      cancel: () => {
+        this._streamController = null;
+      }
+    }, new CountQueuingStrategy({ highWaterMark: this.highWaterMark }));
   }
-  // ── Private helpers ────────────────────────────────────────────────
+  // ── Public API ────────────────────────────────────────────────────
   /**
-   * Reconstruct a BytecodeProgram from transferred ArrayBuffers.
+   * Add a resolved query key to the pending batch.
    *
-   * The transferred ArrayBuffers are zero-copy, we create TypedArray
-   * views directly over them. No data is copied or serialized.
+   * Called by ExpressionEngine.resolveAsync() after a promise resolves or errors.
+   * If this is the first entry in the current tick, schedules a microtask flush.
    */
-  reconstructResult(raw) {
-    if (raw.error) {
-      return {
-        lineId: raw.lineId,
-        compiledAgainstHash: raw.compiledAgainstHash,
-        program: { opcodes: new Uint8Array(0), numbers: new Float64Array(0), strings: [], hasAsync: false },
-        reads: [],
-        writes: [],
-        isVariableDef: false,
-        error: raw.error
-      };
+  add(entry) {
+    this.cleared = false;
+    for (const existing of this.pending) {
+      if (existing.packageId === entry.packageId && existing.queryKey === entry.queryKey) {
+        return;
+      }
     }
-    const opcodes = raw.opcodesLength > 0 ? new Uint8Array(raw.opcodesBuffer, 0, raw.opcodesLength) : new Uint8Array(0);
-    const numbers = raw.numbersLength > 0 ? new Float64Array(raw.numbersBuffer, 0, raw.numbersLength) : new Float64Array(0);
-    const program = {
-      opcodes,
-      numbers,
-      strings: raw.strings,
-      hasAsync: false
-    };
-    return {
-      lineId: raw.lineId,
-      compiledAgainstHash: raw.compiledAgainstHash,
-      program,
-      reads: raw.reads,
-      writes: raw.writes,
-      isVariableDef: raw.isVariableDef,
-      error: null
-    };
-  }
-};
-
-// src/engine/PageManager.ts
-var PAGE_SIZE = 128;
-var HOT_PAGE_RADIUS = 3;
-var WARM_PAGE_RADIUS = 6;
-var PRELOAD_PAGE_COUNT = 2;
-var COLD_EVICT_BUFFER = HOT_PAGE_RADIUS;
-var PageManager = class _PageManager {
-  constructor() {
-    /** Previous viewport for scroll direction detection. null = no previous viewport. */
-    this.lastViewportStart = null;
-    /** Saved scroll direction from the most recent maintainAfterEval call. */
-    this.savedDirection = null;
-    /** Per-page access counter for LRU tracking. */
-    this.pageAccess = /* @__PURE__ */ new Map();
-    /** Monotonically increasing access sequence number. */
-    this.accessSeq = 0;
-  }
-  // ── Static helpers ─────────────────────────────────────────────────
-  /** Get the page number for a 1-based line number (0-based page index). */
-  static pageForLine(lineNumber) {
-    return Math.floor((lineNumber - 1) / PAGE_SIZE);
-  }
-  /** Get the 1-based inclusive line range for a page. */
-  static pageRange(pageNum, docLineCount) {
-    return {
-      startLine: pageNum * PAGE_SIZE + 1,
-      endLine: Math.min((pageNum + 1) * PAGE_SIZE, docLineCount)
-    };
-  }
-  // ── Public API ─────────────────────────────────────────────────────
-  /**
-   * Detect scroll direction from viewport movement.
-   * Returns null on first call (no previous viewport) or no movement.
-   */
-  detectDirection(newViewport) {
-    if (this.lastViewportStart === null) return null;
-    if (newViewport.startLine > this.lastViewportStart) return "down";
-    if (newViewport.startLine < this.lastViewportStart) return "up";
-    return null;
-  }
-  /**
-   * Maintain page tiers after evaluation.
-   *
-   * 1. Records the new viewport position
-   * 2. Touches hot pages (viewport ± HOT_PAGE_RADIUS) for LRU
-   * 3. Evicts cold/warm pages based on distance from viewport
-   *
-   * Call this after every `evaluate()`, `setViewport()`, or `evaluateAll()`.
-   */
-  maintainAfterEval(viewport, doc) {
-    this.savedDirection = this.detectDirection(viewport);
-    this.lastViewportStart = viewport.startLine;
-    const docLineCount = doc.lineCount;
-    const viewportStartPage = _PageManager.pageForLine(viewport.startLine);
-    const viewportEndPage = _PageManager.pageForLine(viewport.endLine);
-    const lastPage = _PageManager.pageForLine(docLineCount);
-    const hotStart = Math.max(0, viewportStartPage - HOT_PAGE_RADIUS);
-    const hotEnd = Math.min(lastPage, viewportEndPage + HOT_PAGE_RADIUS);
-    const warmStart = Math.max(0, viewportStartPage - WARM_PAGE_RADIUS);
-    const warmEnd = Math.min(lastPage, viewportEndPage + WARM_PAGE_RADIUS);
-    for (let p = hotStart; p <= hotEnd; p++) {
-      this.touchPage(p);
-    }
-    for (let p = warmStart; p <= warmEnd; p++) {
-      if (p >= hotStart && p <= hotEnd) continue;
-      this.evictPageResults(p, doc, docLineCount);
-    }
-    const coldLeftEnd = warmStart - 1;
-    const coldLeftStart = Math.max(0, coldLeftEnd - COLD_EVICT_BUFFER + 1);
-    for (let p = coldLeftStart; p <= coldLeftEnd; p++) {
-      this.evictPageBytecode(p, doc, docLineCount);
-    }
-    const coldRightStart = warmEnd + 1;
-    const coldRightEnd = Math.min(lastPage, coldRightStart + COLD_EVICT_BUFFER - 1);
-    for (let p = coldRightStart; p <= coldRightEnd; p++) {
-      this.evictPageBytecode(p, doc, docLineCount);
+    this.pending.push(entry);
+    if (!this.scheduled) {
+      this.scheduled = true;
+      queueMicrotask(() => {
+        try {
+          this.flush();
+        } catch (e) {
+          const engineError = normalizeUnknownError(e);
+          console.error(`[AsyncResolutionBatcher] flush() failed unexpectedly \u2014 this should never happen; please report: ${engineError.format()}`);
+        }
+      });
     }
   }
   /**
-   * Get lines ahead of the viewport that should be pre-compiled.
+   * Get the native event stream for stream-based consumers.
    *
-   * Looks PRELOAD_PAGE_COUNT pages ahead of the current scroll direction.
-   * Only returns lines that are dirty, don't already have bytecode,
-   * and are not empty/markdown-only.
+   * Use this for backpressure, cancellation, or the ability
+   * to `pipeTo()` / `pipeThrough()` the event flow.
    *
-   * @param viewport The current viewport.
-   * @param doc The document model.
-   * @returns Items ready to send to the compilation worker.
-   */
-  getPreloadTargets(viewport, doc) {
-    const direction = this.savedDirection;
-    if (!direction) return [];
-    const items = [];
-    const viewportEndPage = _PageManager.pageForLine(viewport.endLine);
-    const viewportStartPage = _PageManager.pageForLine(viewport.startLine);
-    const lastPage = _PageManager.pageForLine(doc.lineCount);
-    const pages = [];
-    if (direction === "down") {
-      const startPage = viewportEndPage + HOT_PAGE_RADIUS + 1;
-      const endPage = Math.min(startPage + PRELOAD_PAGE_COUNT - 1, lastPage);
-      for (let p = startPage; p <= endPage && p <= lastPage; p++) {
-        pages.push(p);
-      }
-    } else {
-      const firstPreloadPage = viewportStartPage - HOT_PAGE_RADIUS - 1;
-      for (let p = firstPreloadPage; p > firstPreloadPage - PRELOAD_PAGE_COUNT && p >= 0; p--) {
-        pages.push(p);
-      }
-    }
-    for (const pageNum of pages) {
-      const range = _PageManager.pageRange(pageNum, doc.lineCount);
-      for (let pos = range.startLine; pos <= range.endLine; pos++) {
-        const state = doc.getLineAt(pos);
-        if (!state) continue;
-        if (!state.dirty) continue;
-        if (state.bytecodes.length > 0 && !state.isVariableDef) continue;
-        if (state.isEmpty) continue;
-        if (state.expressions.length > 0) {
-          for (const expression of state.expressions) {
-            if (!expression.trim()) continue;
-            items.push({
-              lineId: state.lineId,
-              expression,
-              textHash: state.textHash
-            });
-          }
-        } else {
-          const inlineSpans = sharedLexer.findInlineSolves(state.text);
-          if (inlineSpans.length > 0) {
-            for (const span of inlineSpans) {
-              if (!span.expression.trim()) continue;
-              items.push({
-                lineId: state.lineId,
-                expression: span.expression,
-                textHash: state.textHash
-              });
-            }
-          } else {
-            const expression = state.text.trim();
-            if (expression) {
-              items.push({
-                lineId: state.lineId,
-                expression,
-                textHash: state.textHash
-              });
-            }
-          }
-        }
-      }
-    }
-    return items;
-  }
-  /**
-   * Reset internal state (e.g., after document switch).
+   * @returns A {@link ReadableStream} that emits {@link AsyncResolutionEvent}
+   *          items as the batcher processes async resolutions.
    */
-  clear() {
-    this.pageAccess.clear();
-    this.accessSeq = 0;
-    this.lastViewportStart = null;
-    this.savedDirection = null;
+  getEventStream() {
+    return this._eventStream;
   }
-  // ── Private helpers ─────────────────────────────────────────────────
-  /** Record a page access with a monotonic sequence number. */
-  touchPage(pageNum) {
-    this.pageAccess.set(pageNum, ++this.accessSeq);
+  /** Number of resolutions currently queued for the next flush. */
+  get pendingCount() {
+    return this.pending.length;
   }
-  /**
-   * Evict results from all non-variable-def lines in a page.
-   * Bytecode is preserved so Tier 2 execution works on scroll-back.
-   */
-  evictPageResults(pageNum, doc, docLineCount) {
-    const range = _PageManager.pageRange(pageNum, docLineCount);
-    for (let pos = range.startLine; pos <= range.endLine; pos++) {
-      const state = doc.getLineAt(pos);
-      if (state && !state.isVariableDef && state.results.length > 0) {
-        state.results = [];
-        state.result = null;
-      }
+  /** Number of pending entries collapsed by (packageId, queryKey) deduplication. */
+  get dedupCount() {
+    const dedup = /* @__PURE__ */ new Set();
+    for (const entry of this.pending) {
+      dedup.add(`${entry.packageId}:${entry.queryKey}`);
     }
+    return Math.max(0, this.pending.length - dedup.size);
   }
   /**
-   * Evict bytecode + results from all non-variable-def lines in a page.
-   * Variable definition bytecode is **never** evicted, it forms the
-   * backbone of the DAG and VM checkpoints.
-   *
-   * Evicted lines are marked dirty so they get Tier 1 re-evaluation
-   * when scrolled back into view.
+   * Whether the internal event stream currently has an active reader.
+   * `1` if a consumer has called `getEventStream().getReader()` (or
+   * otherwise locked the stream) and not released it, `0` otherwise.
    */
-  evictPageBytecode(pageNum, doc, docLineCount) {
-    const range = _PageManager.pageRange(pageNum, docLineCount);
-    for (let pos = range.startLine; pos <= range.endLine; pos++) {
-      const state = doc.getLineAt(pos);
-      if (!state || state.isVariableDef) continue;
-      if (state.bytecodes.length > 0 || state.results.length > 0) {
-        state.bytecodes = [];
-        state.results = [];
-        state.result = null;
-        doc.markDirty(state.lineId);
-      }
-    }
+  get listenerCount() {
+    return this._eventStream.locked ? 1 : 0;
   }
-};
-
-// src/engine/ThreeTierEvaluator.ts
-var EvalTier = /* @__PURE__ */ ((EvalTier2) => {
-  EvalTier2[EvalTier2["Tier1"] = 1] = "Tier1";
-  EvalTier2[EvalTier2["Tier2"] = 2] = "Tier2";
-  EvalTier2[EvalTier2["Tier3"] = 3] = "Tier3";
-  EvalTier2[EvalTier2["Skipped"] = 0] = "Skipped";
-  return EvalTier2;
-})(EvalTier || {});
-var ThreeTierEvaluator = class {
-  /**
-   * @param doc The persistent document model.
-   * @param engine The expression engine (shared VM is accessed via engine.getVM()).
-   * @param checkpointer Optional VM state checkpointer. If provided, the evaluator
-   * will create checkpoints after variable-definition lines and support fast VM
-   * restoration via `restoreTo()`. If omitted, checkpointing is disabled.
-   */
-  constructor(doc, engine, checkpointer) {
-    this.compilationWorker = null;
-    /**
-     * Unsubscribe from sharedGlobalVariableStore, set in the constructor
-     * called from terminateWorker(). See the subscription itself below for
-     * why this only marks lines dirty and never re-evaluates synchronously.
-     */
-    this.globalUnsubscribe = null;
-    this.doc = doc;
-    this.engine = engine;
-    this.dag = engine.getDag();
-    this.checkpointer = checkpointer ?? null;
-    this.pageManager = new PageManager();
-    this.engine.setDocumentModel(this.doc);
-    this.globalUnsubscribe = sharedGlobalVariableStore.subscribe((name) => {
-      for (const lineNumber of this.dag.getAffectedLines(globalDagKey(name))) {
-        this.doc.markDirtyByLineNumber(lineNumber);
-      }
-    });
+  /** Number of flushes that were actually dispatched to the worker pool. */
+  get workerOffloadCount() {
+    return this.workerOffloadDispatchCount;
   }
-  /**
-   * Evaluate all lines needed to render the given viewport.
-   *
-   * Processes lines from 1 to `viewport.endLine` in document order.
-   * Dirty lines in the viewport get Tier-1 full pipeline; clean cached
-   * lines get Tier-2 bytecode execution. Lines after the viewport
-   * get Tier-3 compile-only (with variable-def execution).
-   *
-   * @returns Results for all processed lines, including tier metadata.
-   */
-  evaluate(viewport, signal) {
-    this.engine.setKeystrokeSignal(signal ?? null);
-    enableValueArena();
+  /** Remove all listeners and cancel pending batch. Called on engine clear. */
+  clearAll() {
+    this.pending = [];
+    this.scheduled = false;
+    this.cleared = true;
+    this._testCaptures = null;
+    this.onLineResult = null;
     try {
-      const lines = [];
-      const resultMap = /* @__PURE__ */ new Map();
-      const tierCounts = { tier1: 0, tier2: 0, tier3: 0, skipped: 0 };
-      const docEnd = this.doc.lineCount;
-      const evalEnd = Math.min(viewport.endLine, docEnd);
-      for (let pos = 1; pos <= evalEnd; pos++) {
-        const state = this.doc.getLineAt(pos);
-        if (!state) {
-          tierCounts.skipped++;
-          continue;
-        }
-        const inViewport = pos >= viewport.startLine && pos <= viewport.endLine;
-        const lineResult = this.evaluateSingleLine(state, pos, inViewport);
-        lines.push(lineResult);
-        if (lineResult.tier === 1 /* Tier1 */) tierCounts.tier1++;
-        else if (lineResult.tier === 2 /* Tier2 */) tierCounts.tier2++;
-        else if (lineResult.tier === 3 /* Tier3 */) tierCounts.tier3++;
-        else tierCounts.skipped++;
-        if (lineResult.results && inViewport) {
-          resultMap.set(pos, lineResult.results.flat());
-        }
-      }
-      this.pageManager.maintainAfterEval(viewport, this.doc);
-      return { lines, resultMap, tierCounts };
-    } finally {
-      this.engine.setKeystrokeSignal(null);
-      disableValueArena();
+      this._streamController?.close();
+    } catch {
     }
+    this._streamController = null;
+    this._eventStream = this.createEventStream();
+    if (this.executionPool) {
+      this.executionPool.clear();
+      this.executionPool = null;
+    }
+    this.workerOffloadDispatchCount = 0;
   }
+  // ── Private: flush ────────────────────────────────────────────────
   /**
-   * Background-compile invisible dirty lines beyond the viewport (Tier 3 only).
-   *
-   * Compiles expressions to discover reads/writes for the dependency graph
-   * without executing display-only expressions. Variable definitions are
-   * executed to maintain VM state for future Tier-2 executions.
-   *
-   * This is intended to be called after evaluate() so visible lines are
-   * rendered first, then background work fills in the dependency graph.
-   *
-   * **Phase 5.2h:** This synchronous method is retained for environments
-   * without Worker support. Prefer `dispatchBackgroundCompiles()` which
-   * offloads compilation to a Web Worker with Transferable bytecode.
-   */
-  backgroundCompile(viewport) {
-    const results = [];
-    const docEnd = this.doc.lineCount;
-    const startPos = viewport.endLine + 1;
-    for (let pos = startPos; pos <= docEnd; pos++) {
-      const state = this.doc.getLineAt(pos);
-      if (!state) continue;
-      if (!state.dirty) continue;
-      if (state.bytecodes.length > 0 && !state.isVariableDef) continue;
-      const lineResult = this.evaluateSingleLine(state, pos, false);
-      results.push(lineResult);
-    }
-    return results;
-  }
-  /**
-   * Dispatch background compilation to a Web Worker (Phase 5.2h).
-   *
-   * Collects invisible dirty lines beyond the viewport that need compilation,
-   * sends them to the compilation worker, and asynchronously stores the
-   * transferred bytecode in the DocumentModel when the worker responds.
-   *
-   * This is the non-blocking alternative to `backgroundCompile()`. The worker
-   * compiles expressions with Transferable ArrayBuffers (zero-copy postMessage),
-   * so bytecode appears on the main thread without serialization overhead.
-   *
-   * Lines that already have cached bytecode (from a previous worker pass or
-   * synchronous compile) are skipped, only truly uncompiled dirty lines are
-   * sent to the worker.
-   *
-   * **Usage:** Call after `evaluate()` so visible lines render first, then
-   * this fills the bytecode cache for future Tier-2 scrolls.
+   * Flush all pending resolutions in a single batched pass.
    *
-   * @param viewport The current visible range. Lines beyond viewport.endLine
-   * that are dirty and don't have bytecode are dispatched.
-   */
-  dispatchBackgroundCompiles(viewport) {
-    const items = this.collectInvisibleCompileTargets(viewport);
-    if (items.length === 0) return;
-    if (!this.compilationWorker) {
-      this.compilationWorker = new CompilationWorkerManager();
-    }
-    this.compilationWorker.compileBatch(items).then((results) => {
-      this.compilationWorker.storeResults(results, this.doc);
-    }).catch((_err) => {
-    });
-  }
-  /**
-   * Terminate the compilation worker if active, and unsubscribe from
-   * sharedGlobalVariableStore. Call this when the evaluator is no longer
-   * needed to clean up resources, every call site that retires a
-   * ThreeTierEvaluator (document switch, pane destroy()) already calls
-   * this unconditionally, so folding the global-store unsubscribe in here
-   * needs no new call sites anywhere.
+   * Called automatically via queueMicrotask. Never called directly.
    */
-  terminateWorker() {
-    if (this.compilationWorker) {
-      this.compilationWorker.terminate();
-      this.compilationWorker = null;
+  flush() {
+    this.scheduled = false;
+    if (this.cleared) return;
+    if (this.pending.length === 0) return;
+    const batch = this.pending;
+    this.pending = [];
+    const deduped = /* @__PURE__ */ new Map();
+    for (const entry of batch) {
+      const compositeKey = `${entry.packageId}:${entry.queryKey}`;
+      deduped.set(compositeKey, entry);
+    }
+    const errorEntries = [];
+    const okEntries = [];
+    for (const entry of deduped.values()) {
+      if (entry.isError) {
+        errorEntries.push(entry);
+      } else {
+        okEntries.push(entry);
+      }
     }
-    if (this.globalUnsubscribe) {
-      this.globalUnsubscribe();
-      this.globalUnsubscribe = null;
+    for (const entry of errorEntries) {
+      if (entry.signal.aborted) continue;
+      this.notifyListeners({
+        type: "error",
+        queryKey: entry.queryKey,
+        packageId: entry.packageId,
+        error: entry.error ?? new Error("Unknown async resolution error")
+      });
     }
-  }
-  /**
-   * Get the DocumentModel (read-only access for decoration building).
-   */
-  getDoc() {
-    return this.doc;
-  }
-  /**
-   * Evaluate all dirty lines in the document, regardless of viewport.
-   * Used for full re-evaluation after plugin register/unregister.
-   */
-  evaluateAll(signal) {
-    const viewport = { startLine: 1, endLine: this.doc.lineCount };
-    const result = this.evaluate(viewport, signal);
-    return result;
-  }
-  /**
-   * Zero-allocation viewport evaluation, the Phase 5.2e "holy grail."
-   *
-   * **Key insight:** When the user scrolls (viewport-only change, no edits),
-   * we don't need to re-evaluate from line 1. Instead:
-   *
-   * 1. Restore the VM to just before the viewport via the nearest checkpoint.
-   * 2. Evaluate ONLY the visible lines (Tier 2 for clean cached, Tier 1 for dirty).
-   * 3. Lines before the viewport are completely skipped, their state lives in
-   *    the VM checkpointer's prototypal chain.
-   *
-   * **Correctness guard:** If any variable-definition line before the viewport
-   * is dirty (e.g., the user edited a variable def that hasn't been
-   * re-evaluated yet), we clear stale checkpoints and fall back to `evaluate()`
-   * which processes from line 1 and rebuilds fresh checkpoints. This
-   * guarantees that stale checkpoints are never used as restoration targets.
-   * Only variable-def lines matter here, `VMCheckpointer.snapshot()` only
-   * records state for lines that write a variable, so a dirty plain-expression
-   * line before the viewport has no checkpoint to invalidate (see
-   * `DocumentModel.hasAnyDirtyVariableDefLineBefore()`).
-   *
-   * **Performance:** O(visible lines) instead of O(document length). Target:
-   * < 1ms for a typical ~30-line viewport, independent of document size.
-   *
-   * @param viewport The visible line range.
-   * @returns Results for visible lines only. Lines before the viewport are
-   * not included in `lines[]` or `resultMap`.
-   */
-  setViewport(viewport, signal) {
-    this.engine.setKeystrokeSignal(signal ?? null);
-    if (viewport.startLine > 1 && this.hasDirtyLinesBefore(viewport.startLine)) {
-      this.checkpointer?.clear();
-      return this.evaluate(viewport, signal);
-    }
-    this.pageManager.maintainAfterEval(viewport, this.doc);
-    this.preloadNextPages(viewport);
-    this.restoreTo(viewport.startLine - 1);
-    enableValueArena();
-    try {
-      const result = this.collectEvalResults(viewport.startLine, viewport.endLine);
-      return result;
-    } finally {
-      this.engine.setKeystrokeSignal(null);
-      disableValueArena();
+    const allAffected = /* @__PURE__ */ new Set();
+    const allQueryKeys = [];
+    const allEntries = [...okEntries, ...errorEntries];
+    for (const entry of allEntries) {
+      if (entry.signal.aborted) continue;
+      allQueryKeys.push(entry.queryKey);
+      const affected = this.dag.getAffectedLinesByDataSource(
+        entry.packageId,
+        [entry.queryKey]
+      );
+      for (const line of affected) {
+        allAffected.add(line);
+      }
+    }
+    if (allAffected.size === 0) {
+      this.notifyListeners({
+        type: "lines-updated",
+        lineNumbers: [],
+        affectedQueryKeys: allQueryKeys
+      });
+      return;
+    }
+    const ordered = this.topologicalSort(Array.from(allAffected));
+    if (ordered.length > WORKER_OFFLOAD_THRESHOLD) {
+      const entryMap = /* @__PURE__ */ new Map();
+      for (const lineNumber of ordered) {
+        entryMap.set(lineNumber, this.lineCache.getEntryForLine(lineNumber));
+      }
+      void this.reExecuteViaWorkerPool(ordered, entryMap, allQueryKeys).catch((e) => {
+        const engineError = normalizeUnknownError(e);
+        console.error(`[AsyncResolutionBatcher] reExecuteViaWorkerPool() failed unexpectedly: ${engineError.format()}`);
+      });
+      return;
     }
+    this.reExecuteMainThread(ordered, allQueryKeys);
   }
+  // ── Private: topological sort ─────────────────────────────────────
   /**
-   * Apply incremental line-level changes to the document model.
-   *
-   * **Phase 5.2f:** Replaces the O(N) `setDocument()` + full re-evaluation
-   * with O(changed) incremental updates. Key benefits:
-   *
-   * 1. Unchanged lines retain their persistent lineIds → bytecode survives
-   * 2. Only changed + DAG-downstream lines are marked dirty → Tier 1 re-evaluation
-   * 3. Clean lines in viewport use Tier 2 (cached bytecode execution)
-   * 4. Clean lines outside viewport are skipped entirely
-   *
-   * The DAG is fully cleared after propagation: shifted lines would have
-   * stale entries keyed by old line numbers, so the DAG is rebuilt from
-   * scratch during the subsequent `evaluate()` call.
-   *
-   * **Caller should follow up with `evaluate(viewport)`** to re-evaluate
-   * dirty lines from line 1 and rebuild the DAG + checkpoints.
+   * Topologically sort affected lines using Kahn's algorithm.
    *
-   * @param changes Line-level changes to apply. Must be non-overlapping.
-   * @returns Metadata about the applied changes.
+   * Lines that produce variables come before lines that consume them.
+   * This ensures correct evaluation order when multiple interdependent
+   * lines are affected by async resolution.
    */
-  applyTransaction(changes) {
-    const allWrites = /* @__PURE__ */ new Set();
-    for (const change of changes) {
-      for (let i = 0; i < change.deleteCount; i++) {
-        const lineNum = change.startLine + i;
-        const writes = this.dag.getWrites(lineNum);
-        for (const w of writes) {
-          allWrites.add(w);
-        }
-        this.dag.removeLine(lineNum);
-        this.engine.getLineCache().removeAllForLine(lineNum);
+  topologicalSort(lines) {
+    if (lines.length <= 1) return lines;
+    const inDegree = /* @__PURE__ */ new Map();
+    const adjacency = /* @__PURE__ */ new Map();
+    const producerOf = /* @__PURE__ */ new Map();
+    for (const line of lines) {
+      inDegree.set(line, 0);
+      adjacency.set(line, []);
+    }
+    for (const line of lines) {
+      const writes = this.dag.getWrites(line);
+      for (const w of writes) {
+        producerOf.set(w, line);
       }
     }
-    const downstreamLineIds = /* @__PURE__ */ new Set();
-    for (const writeVar of allWrites) {
-      const affected = this.dag.getAffectedLines(writeVar);
-      for (const lineNum of affected) {
-        const state = this.doc.getLineAt(lineNum);
-        if (state) {
-          downstreamLineIds.add(state.lineId);
+    for (const line of lines) {
+      const reads = this.dag.getDependencies(line);
+      for (const readVar of reads) {
+        const producer = producerOf.get(readVar);
+        if (producer !== void 0 && producer !== line) {
+          adjacency.get(producer).push(line);
+          inDegree.set(line, (inDegree.get(line) ?? 0) + 1);
         }
       }
     }
-    const result = this.doc.applyChanges(changes);
-    this.checkpointer?.clear();
-    for (const lineId of downstreamLineIds) {
-      this.doc.markDirty(lineId);
+    const queue = [];
+    for (const [line, degree] of inDegree) {
+      if (degree === 0) queue.push(line);
+    }
+    if (queue.length === 0 && lines.length > 0) {
+      return [...lines].sort((a, b) => a - b);
     }
-    this.dag.clear();
-    return {
-      inserted: result.inserted,
-      removed: result.removed
-    };
-  }
-  // ── Private helpers ─────────────────────────────────────────────────
-  /**
-   * Collect evaluation results for a contiguous range of lines.
-   *
-   * Used by both `evaluate()` (startLine=1) and `setViewport()` (any start).
-   * All lines in the range are treated as in-viewport (visible), callers that
-   * need the invisible/dirty → Tier 3 handling should use `evaluate()` instead.
-   *
-   * @param startLine First line to evaluate (1-based, inclusive).
-   * @param endLine Last line to evaluate (1-based, inclusive). Clamped to docEnd.
-   */
-  collectEvalResults(startLine, endLine) {
-    const lines = [];
-    const resultMap = /* @__PURE__ */ new Map();
-    const tierCounts = { tier1: 0, tier2: 0, tier3: 0, skipped: 0 };
-    const docEnd = this.doc.lineCount;
-    const evalEnd = Math.min(endLine, docEnd);
-    for (let pos = startLine; pos <= evalEnd; pos++) {
-      const state = this.doc.getLineAt(pos);
-      if (!state) continue;
-      const lineResult = this.evaluateSingleLine(state, pos, true);
-      lines.push(lineResult);
-      if (lineResult.tier === 1 /* Tier1 */) tierCounts.tier1++;
-      else if (lineResult.tier === 2 /* Tier2 */) tierCounts.tier2++;
-      else if (lineResult.tier === 3 /* Tier3 */) tierCounts.tier3++;
-      else tierCounts.skipped++;
-      if (lineResult.results) {
-        resultMap.set(pos, lineResult.results.flat());
-      }
-    }
-    return { lines, resultMap, tierCounts };
-  }
-  /**
-   * Check whether any **variable-definition** line before `position`
-   * (1-based, exclusive) is dirty.
-   *
-   * Used by `setViewport()` to decide whether to fall back to `evaluate()`:
-   * if a variable-def before the viewport is dirty, the checkpoint state
-   * `restoreTo()` would use may be stale and we need to reprocess from
-   * line 1 to rebuild checkpoints correctly.
-   *
-   * Deliberately narrower than `DocumentModel.hasAnyDirtyLineBefore()`:
-   * checkpoints only snapshot variable-def lines (see VMCheckpointer), so a
-   * dirty plain-expression line before the viewport can't have invalidated
-   * one, there's nothing checkpointed for it to invalidate. Using the
-   * broader check here previously caused a real perf bug: `PageManager`'s
-   * cold-page eviction marks evicted non-variable-def lines dirty, so
-   * scrolling far into a large, variable-def-free document would trip this
-   * guard, fall back to `evaluate()`, which recompiles those lines via
-   * Tier 3 (never clearing their dirty flag by design), causing the very
-   * next `maintainAfterEval()` to re-evict and re-dirty them, a
-   * self-sustaining loop that pinned every subsequent `setViewport()` call
-   * to the cost of a full re-evaluation instead of O(visible lines).
-   *
-   * Delegates to DocumentModel.hasAnyDirtyVariableDefLineBefore(), which
-   * tracks dirty lineIds incrementally instead of scanning every line up to
-   * `position` on every call. This used to be a real per-scroll cost
-   * (benchmarked at ~10ms scrolled near the bottom of a 20k-line document)
-   * since it fired on every viewport change, not just edits.
-   */
-  hasDirtyLinesBefore(position) {
-    return this.doc.hasAnyDirtyVariableDefLineBefore(position);
-  }
-  /**
-   * Evaluate a single line using the appropriate tier.
-   *
-   * Tier assignment logic:
-   * - Empty/markdown-only lines → skipped
-   * - Dirty + in-viewport → Tier 1 (full pipeline)
-   * - Dirty + not in viewport → Tier 3 (compile-only, execute variable defs)
-   * - Clean + has bytecode + in viewport → Tier 2 (execute from cache)
-   * - Clean + no bytecode → skipped (non-evaluable)
-   */
-  evaluateSingleLine(state, lineNumber, inViewport) {
-    const baseResult = {
-      lineId: state.lineId,
-      lineNumber
-    };
-    if (state.isEmpty || isEmptyLine(state.text)) {
-      state.isEmpty = true;
-      this.doc.markClean(state.lineId);
-      return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
-    }
-    const { expressions, inlineSolveCount } = this.extractExpressions(state);
-    if (expressions.length === 0) {
-      state.isEmpty = true;
-      this.doc.markClean(state.lineId);
-      return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
-    }
-    if (state.dirty) {
-      if (inViewport) {
-        return this.evaluateTier1(state, lineNumber, expressions, inlineSolveCount, baseResult);
-      } else {
-        if (state.bytecodes.length > 0 && state.bytecodes.length === expressions.length && !state.isVariableDef) {
-          return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
-        }
-        return this.evaluateTier3(state, lineNumber, expressions, inlineSolveCount, baseResult);
+    const ordered = [];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      ordered.push(current);
+      for (const downstream of adjacency.get(current) ?? []) {
+        const newDegree = (inDegree.get(downstream) ?? 1) - 1;
+        inDegree.set(downstream, newDegree);
+        if (newDegree === 0) queue.push(downstream);
       }
     }
-    if (inViewport && state.bytecodes.length > 0) {
-      return this.evaluateTier2(state, lineNumber, baseResult);
+    if (ordered.length < lines.length) {
+      const remaining = lines.filter((l) => !ordered.includes(l)).sort((a, b) => a - b);
+      ordered.push(...remaining);
     }
-    return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
+    return ordered;
   }
+  // ── Private: worker-pool re-execution ─────────────────────────────
   /**
-   * Tier 1: Full pipeline, lex, parse, compile, execute.
-   * Uses the engine's existing evaluateLine() which handles all pipeline
-   * stages including DAG updates and LineCache population.
+   * Offload VM re-execution to the worker pool for large batches.
+   *
+   * Called when ordered.length > WORKER_OFFLOAD_THRESHOLD (50).
+   * Clones bytecode ArrayBuffers, dispatches to workers, and asynchronously
+   * patches results back into LineCache before notifying listeners.
+   *
+   * Handles pending results: lines that return { type: 'pending' } from the
+   * worker are NOT marked as updated, the engine's resolveAsync will handle
+   * them when the async resolver completes.
    *
-   * Supports multiple expressions per line (inline solves). Evaluates each
-   * expression left-to-right through the engine so variable definitions in
-   * earlier solves update the VM state before later solves are evaluated.
-   * Reads/writes are aggregated across all expressions for the DAG.
+   * Safety: checks this.cleared before applying results, if the engine was
+   * cleared while the worker batch was in-flight, results are discarded.
    */
-  evaluateTier1(state, lineNumber, expressions, inlineSolveCount, baseResult) {
-    const allResults = [];
-    const allBytecodes = [];
-    const allReads = /* @__PURE__ */ new Set();
-    const allWrites = /* @__PURE__ */ new Set();
-    let hasVariableDef = false;
-    let lastValue = null;
-    let firstError = null;
-    let anyFailed = false;
-    let anyPending = false;
-    for (const expression of expressions) {
-      if (!expression.trim()) continue;
-      let value = null;
-      let entry;
-      try {
-        const evaluation = this.engine.evaluateLineDetailed(lineNumber, expression);
-        value = evaluation.values;
-        lastValue = value[0];
-        entry = this.engine.getLineCache().get(lineNumber, expression);
-      } catch (e) {
-        const errorMessage = e instanceof Error ? e.message : String(e);
-        if (!firstError) firstError = errorMessage;
-        anyFailed = true;
-        value = null;
-      }
-      if (value && value.some((v) => v.type === 12 /* Pending */)) {
-        anyPending = true;
-      }
-      if (value) {
-        allResults.push(value);
-      } else {
-        allResults.push([errorValue("eval_failed", firstError ?? "unknown error")]);
-      }
-      if (entry) {
-        allBytecodes.push(entry.bytecode);
-        for (const r of entry.readVariables) allReads.add(r);
-        if (entry.writeVariable) {
-          allWrites.add(entry.writeVariable);
-          hasVariableDef = true;
-        }
-      } else {
-        try {
-          const { program, reads: reads2, writes: writes2 } = this.engine.compileExpression(expression);
-          allBytecodes.push(program);
-          for (const r of reads2) allReads.add(r);
-          for (const w of writes2) allWrites.add(w);
-          if (writes2.length > 0) hasVariableDef = true;
-        } catch (compileErr) {
-          allBytecodes.push({ opcodes: new Uint8Array(0), numbers: new Float64Array(0), strings: [], hasAsync: false });
-          if (compileErr instanceof EngineError && compileErr.context) {
-            const errReads = compileErr.context.reads;
-            const errWrites = compileErr.context.writes;
-            if (Array.isArray(errReads)) for (const r of errReads) allReads.add(r);
-            if (Array.isArray(errWrites)) for (const w of errWrites) allWrites.add(w);
-          }
-        }
-      }
-    }
-    const reads = [...allReads];
-    const writes = [...allWrites];
-    if (anyFailed || anyPending) {
-      this.doc.updateLineCompiled(
-        state.lineId,
-        expressions,
-        allBytecodes,
-        reads,
-        writes,
-        hasVariableDef,
-        inlineSolveCount
-      );
-      state.results = allResults;
-      state.result = allResults[0]?.[0] ?? null;
-      state.inlineSolveCount = inlineSolveCount;
-      state.expressions = expressions;
-    } else {
-      this.doc.updateLineResult(
-        state.lineId,
-        allResults,
-        allBytecodes,
-        expressions,
-        reads,
-        writes,
-        hasVariableDef,
-        inlineSolveCount
-      );
+  async reExecuteViaWorkerPool(ordered, entryMap, allQueryKeys) {
+    if (!this.executionPool) {
+      this.executionPool = new ExecutionPool();
     }
-    this.dag.registerLine(lineNumber, reads, writes);
-    if (this.checkpointer && writes.length > 0 && !anyFailed && !anyPending) {
-      this.checkpointer.snapshot(lineNumber, state.lineId, writes);
+    const results = this.executionPool.executeBatch(ordered, entryMap);
+    if (!results) {
+      this.reExecuteMainThread(ordered, allQueryKeys, entryMap);
+      return;
     }
-    return {
-      ...baseResult,
-      tier: 1 /* Tier1 */,
-      result: lastValue,
-      results: allResults,
-      error: firstError
-    };
-  }
-  /**
-   * Tier 2: Execute from cached bytecode only.
-   * Skips lexing, parsing, and compiling, runs the pre-compiled bytecode
-   * against the engine's shared VM. Supports multiple bytecodes per line
-   * (inline solves), each is executed left-to-right so variable definitions
-   * in earlier bytecodes update the VM before later ones run.
-   * Assumes the VM already has correct variable state from preceding
-   * Tier-1 evaluations.
-   */
-  evaluateTier2(state, lineNumber, baseResult) {
-    if (state.bytecodes.length === 0) {
-      return { ...baseResult, tier: 0 /* Skipped */, result: null, error: null };
-    }
-    const results = [];
-    let lastValue = null;
-    let firstError = null;
-    let anyFailed = false;
-    for (const bytecode of state.bytecodes) {
-      if (bytecode.opcodes.length === 0) continue;
-      try {
-        const value = this.engine.executeCached(bytecode, lineNumber);
-        lastValue = value;
-        results.push([value]);
-      } catch (e) {
-        const errorMessage = e instanceof Error ? e.message : String(e);
-        if (!firstError) firstError = errorMessage;
-        anyFailed = true;
-        results.push([errorValue("exec_failed", errorMessage)]);
+    this.workerOffloadDispatchCount++;
+    const workerResults = await results;
+    if (this.cleared) return;
+    const updatedLineNumbers = [];
+    for (const wr of workerResults) {
+      const entry = entryMap.get(wr.lineNumber);
+      if (!entry) continue;
+      if (wr.isPending) {
+        continue;
       }
+      const value = reconstructValue(wr);
+      entry.result = value;
+      this.warnIfUnwired();
+      this.onLineResult?.(wr.lineNumber, value);
+      updatedLineNumbers.push(wr.lineNumber);
     }
-    this.dag.registerLine(lineNumber, state.reads, state.writes);
-    state.results = results;
-    state.result = results[0]?.[0] ?? null;
-    if (anyFailed) {
-      this.doc.markDirty(state.lineId);
+    if (this.cleared) return;
+    if (updatedLineNumbers.length > 0 || allQueryKeys.length > 0) {
+      this.notifyListeners({
+        type: "lines-updated",
+        lineNumbers: updatedLineNumbers,
+        affectedQueryKeys: allQueryKeys
+      });
     }
-    return { ...baseResult, tier: 2 /* Tier2 */, result: lastValue, results, error: firstError };
   }
+  // ── Private: main-thread re-execution ────────────────────────────
   /**
-   * Tier 3: Compile-only for invisible lines.
-   * Lex → Parse → Compile to discover reads/writes for the dependency graph.
-   * Executes the bytecode ONLY if the line defines a variable (isVariableDef
-   * or writes.length > 0), because variable assignments affect VM state
-   * that other lines depend on. Pure expression lines are compiled but NOT
-   * executed, saving CPU for large documents.
+   * Execute ordered lines on the main thread, update LineCache, and notify
+   * listeners. Returns the list of line numbers that actually changed.
    *
-   * Supports multiple expressions per line (inline solves). Each is compiled
-   * separately; variable-def expressions are also executed.
+   * Used by both flush() (≤50 lines) and reExecuteViaWorkerPool() (fallback
+   * when workers are unavailable). Extracted to avoid code duplication.
+   *
+   * **Per-line containment (fatal-bug fix)**: `executeBytecode()` used to
+   * run here with NO try/catch anywhere in this method's call chain, and
+   * this whole batch runs inside a bare `queueMicrotask` (see `add()`) with
+   * no surrounding try/catch at any caller either, so if any ONE line's
+   * cached bytecode threw (a stack/instruction-limit error, an undefined
+   * variable, a corrupted-bytecode `TypeError`), the `for` loop aborted
+   * immediately: every line scheduled AFTER the failure in this batch was
+   * silently never re-executed or notified even though nothing was wrong
+   * with them, every line BEFORE it had already had its `entry.result`
+   * mutated in-place but `notifyListeners()` was never reached (a silent
+   * `LineCache`/host desync), and, because a bare `queueMicrotask`
+   * callback has no caller to catch it, the exception was uncatchable:
+   * an `uncaughtException` that could crash the host process outright.
+   * (`__tests__/async/AsyncResolutionBatcher.spec.ts`'s topological-sort
+   * describe block used to have a test skipped specifically because of
+   * this. See that file, now un-skipped and rewritten.) Each line's
+   * execution is now its own try/catch: a failure is recorded as an
+   * `Error` `Value` for THAT line (still counted as "updated" so the host
+   * learns about it and stops showing a stale Pending state) and the loop
+   * continues, one line's failure can no longer take out its neighbors.
    */
-  evaluateTier3(state, lineNumber, expressions, inlineSolveCount, baseResult) {
-    const allBytecodes = [];
-    const allReads = /* @__PURE__ */ new Set();
-    const allWrites = /* @__PURE__ */ new Set();
-    let hasVariableDef = false;
-    let lastResult = null;
-    let firstError = null;
-    let anyFailed = false;
-    let anyPending = false;
-    for (const expression of expressions) {
-      if (!expression.trim()) continue;
+  reExecuteMainThread(ordered, allQueryKeys, entryMap) {
+    const updatedLineNumbers = [];
+    for (const lineNumber of ordered) {
+      const entry = entryMap ? entryMap.get(lineNumber) : this.lineCache.getEntryForLine(lineNumber);
+      if (!entry || entry.bytecode.opcodes.length === 0) continue;
+      const stackBefore = this.vm.getStack().length;
       try {
-        const { program, reads: reads2, writes: writes2 } = this.engine.compileExpression(expression);
-        allBytecodes.push(program);
-        for (const r of reads2) allReads.add(r);
-        for (const w of writes2) allWrites.add(w);
-        if (writes2.length > 0) hasVariableDef = true;
-        if (writes2.length > 0 && program.opcodes.length > 0) {
-          lastResult = this.engine.executeCached(program, lineNumber);
-          if (lastResult && lastResult.type === 12 /* Pending */) {
-            anyPending = true;
-          }
+        const result = executeBytecode(entry.bytecode, this.vm);
+        while (this.vm.getStack().length > stackBefore) {
+          this.vm.pop();
+        }
+        if (result.type === "value") {
+          entry.result = result.value;
+          this.warnIfUnwired();
+          this.onLineResult?.(lineNumber, result.value);
+          updatedLineNumbers.push(lineNumber);
+        } else if (result.type === "error") {
+          const value = errorValue(result.error.code, result.error.message);
+          entry.result = value;
+          this.warnIfUnwired();
+          this.warnIfUnwired();
+          this.onLineResult?.(lineNumber, value);
+          updatedLineNumbers.push(lineNumber);
         }
       } catch (e) {
-        const errorMessage = e instanceof Error ? e.message : String(e);
-        if (!firstError) firstError = errorMessage;
-        anyFailed = true;
-        allBytecodes.push({ opcodes: new Uint8Array(0), numbers: new Float64Array(0), strings: [], hasAsync: false });
-      }
-    }
-    const reads = [...allReads];
-    const writes = [...allWrites];
-    this.doc.updateLineCompiled(
-      state.lineId,
-      expressions,
-      allBytecodes,
-      reads,
-      writes,
-      hasVariableDef,
-      inlineSolveCount
-    );
-    this.dag.registerLine(lineNumber, reads, writes);
-    if (hasVariableDef && lastResult && !anyFailed && !anyPending) {
-      state.results = [[lastResult]];
-      state.result = lastResult;
-      this.doc.markClean(state.lineId);
-      if (this.checkpointer) {
-        this.checkpointer.snapshot(lineNumber, state.lineId, writes);
+        while (this.vm.getStack().length > stackBefore) {
+          this.vm.pop();
+        }
+        const engineError = normalizeUnknownError(e);
+        const value = errorValue(engineError.code, engineError.message);
+        entry.result = value;
+        this.warnIfUnwired();
+        this.onLineResult?.(lineNumber, value);
+        updatedLineNumbers.push(lineNumber);
       }
     }
-    return { ...baseResult, tier: 3 /* Tier3 */, result: lastResult, results: hasVariableDef && lastResult && !anyFailed && !anyPending ? [[lastResult]] : void 0, error: firstError };
-  }
-  // ── Public checkpoint API (used by Phase 5.2e setViewport) ──────
-  /**
-   * Restore the VM to the state at or just after the given line number.
-   *
-   * Finds the nearest checkpoint at or before `lineNumber` and replays
-   * all variable definitions from the checkpoint chain into the VM.
-   * After calling this, the VM is ready to evaluate lines starting at
-   * `lineNumber + 1` without re-evaluating all preceding lines.
-   *
-   * **Usage:** Phase 5.2e's `setViewport()` calls `restoreTo(viewport.startLine - 1)`
-   * before evaluating only the newly visible lines. This is the key to
-   * O(visible lines) scrolling.
-   *
-   * @param lineNumber The line number to restore to. Variables defined
-   * at lines ≤ this number will be available in the VM.
-   */
-  restoreTo(lineNumber) {
-    if (this.checkpointer) {
-      this.checkpointer.restoreTo(lineNumber);
+    if (updatedLineNumbers.length > 0 || allQueryKeys.length > 0) {
+      this.notifyListeners({
+        type: "lines-updated",
+        lineNumbers: updatedLineNumbers,
+        affectedQueryKeys: allQueryKeys
+      });
     }
+    return updatedLineNumbers;
   }
   /**
-   * Get the VM checkpointer, or null if checkpointing is disabled.
-   */
-  getCheckpointer() {
-    return this.checkpointer;
-  }
-  /**
-   * Get the PageManager (Phase 5.2g).
-   * Exposed for testing.
-   */
-  getPageManager() {
-    return this.pageManager;
-  }
-  // ── Phase 5.2g: Directional preloading ──────────────────────────
-  /**
-   * Preload the next 1–2 pages in the current scroll direction.
-   *
-   * Called during `setViewport()` (scroll-only path). Collects dirty
-   * uncompiled lines in pages just beyond the viewport and dispatches
-   * them to the background compilation worker so bytecode is ready
-   * before the user scrolls those lines into view.
-   */
-  preloadNextPages(viewport) {
-    const targets = this.pageManager.getPreloadTargets(viewport, this.doc);
-    if (targets.length === 0) return;
-    if (!this.compilationWorker) {
-      this.compilationWorker = new CompilationWorkerManager();
-    }
-    this.compilationWorker.compileBatch(targets).then((results) => {
-      this.compilationWorker.storeResults(results, this.doc);
-    }).catch((_err) => {
-    });
-  }
-  /**
-   * Collect invisible dirty lines that need background compilation.
-   *
-   * Iterates lines beyond `viewport.endLine`, filtering for:
-   * - Dirty lines (need re-compilation)
-   * - Non-empty, non-markdown lines
-   * - No existing bytecode (skip already-compiled Tier 3 lines)
+   * Notify all consumers of an async resolution event.
    *
-   * Returns CompileRequestItem[] suitable for CompilationWorkerManager.
+   * Enqueues the event into the internal {@link ReadableStream}.
+   * If the stream has been closed or errored (consumer cancelled),
+   * the enqueue silently fails (caught by try/catch).
    */
-  collectInvisibleCompileTargets(viewport) {
-    const items = [];
-    const docEnd = this.doc.lineCount;
-    const startPos = viewport.endLine + 1;
-    for (let pos = startPos; pos <= docEnd; pos++) {
-      const state = this.doc.getLineAt(pos);
-      if (!state) continue;
-      if (!state.dirty) continue;
-      if (state.bytecodes.length > 0 && !state.isVariableDef) continue;
-      if (state.isEmpty || isEmptyLine(state.text)) continue;
-      const { expressions } = this.extractExpressions(state);
-      if (expressions.length === 0) continue;
-      for (const expression of expressions) {
-        if (!expression.trim()) continue;
-        items.push({
-          lineId: state.lineId,
-          expression,
-          textHash: state.textHash
-        });
-      }
+  notifyListeners(event) {
+    if (this._testCaptures) {
+      this._testCaptures.push(event);
     }
-    return items;
-  }
-  /**
-   * Extract all evaluable expressions from a LineState.
-   *
-   * For full-line expressions: returns `{ expressions: [trimmedText], inlineSolveCount: 0 }`.
-   * For inline solve lines: returns `{ expressions: [...allSolves], inlineSolveCount: N }`.
-   * For pre-extracted (cached) expressions: returns the cached array.
-   *
-   * Inline solves are extracted left-to-right via the sharedLexer, so variable
-   * definitions in earlier solves (e.g., `s\`x = 5\` more text s\`x + 1\``)
-   * correctly update the VM state before later solves are evaluated.
-   */
-  extractExpressions(state) {
-    if (state.expressions.length > 0) {
-      return { expressions: state.expressions, inlineSolveCount: state.inlineSolveCount };
-    }
-    const trimmed = state.text.trim();
-    if (trimmed.length === 0) return { expressions: [], inlineSolveCount: 0 };
-    const inlineSpans = sharedLexer.findInlineSolves(state.text);
-    if (inlineSpans.length > 0) {
-      return {
-        expressions: inlineSpans.map((s) => s.expression),
-        inlineSolveCount: inlineSpans.length
-      };
+    if (this._streamController) {
+      try {
+        this._streamController.enqueue(event);
+      } catch {
+      }
     }
-    return { expressions: [trimmed], inlineSolveCount: 0 };
   }
 };
+// ── Web Streams API integration ──────────────────────────────────
+/**
+ * Default high-water mark for the internal event stream.
+ * Limits the internal buffer size before the stream signals to
+ * consumers that they need to catch up.
+ */
+_AsyncResolutionBatcher.DEFAULT_HIGH_WATER_MARK = 64;
+var AsyncResolutionBatcher = _AsyncResolutionBatcher;
 
-export { AsyncResolutionBatcher, DocumentModel, EvalTier, ExpressionEngine, ThreeTierEvaluator, assertEngineVersionCompatible, checkEngineVersionCompatibility, checkExpressionComplexity, checkExpressionLength, checkPackageCompatibility, extractReadsAndWrites, findInlineSolvesInLine, isEmptyLine };
-//# sourceMappingURL=chunk-V5PYO44Y.js.map
-//# sourceMappingURL=chunk-V5PYO44Y.js.map
+export { AsyncResolutionBatcher, ExpressionEngine, SNAPSHOT_FORMAT, SNAPSHOT_VERSION, SnapshotErrorCodes, assertEngineVersionCompatible, checkEngineVersionCompatibility, checkExpressionComplexity, checkExpressionLength, checkPackageCompatibility, engine_worker_default, extractReadsAndWrites, findInlineSolvesInLine, isEmptyLine };
+//# sourceMappingURL=chunk-JIPATHVY.js.map
+//# sourceMappingURL=chunk-JIPATHVY.js.map