solve-engine 1.0.1 → 1.1.0

package/dist/{PackageRegistry-DCUEzbQt.d.ts → PackageRegistry-_8rDlvxI.d.ts}

@@ -1,16 +1,16 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-BaySkMV3.js';
-import { V as Value } from './Value-CXJqDH9J.js';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-BBT8riYh.js';
+import { V as Value, b as ValueType } from './Value-BUi1RA3S.js';
 import { IVariableSource } from './variables.js';
-import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-BN5mt30n.js';
+import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-CSI_lwbW.js';
 import { IAsyncResolver } from './resolvers.js';
-import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-t_GotBxr.js';
-import { a as DependencyGraph, V as VM, D as DagSnapshot, b as EngineContext, S as ScopeManager, L as LineExecutionContext } from './ScopeManager-udv4Twwq.js';
-import { a as BytecodeProgram } from './BytecodeBuilder-B0xskcv5.js';
+import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-C6VzZgHa.js';
+import { a as DependencyGraph, V as VM, D as DagSnapshot, b as EngineContext, S as ScopeManager, L as LineExecutionContext } from './ScopeManager-CxA24W5n.js';
+import { a as BytecodeProgram } from './BytecodeBuilder-Bp9xeTmX.js';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-LU7W7AgI.js';
-import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-B6k5lCB7.js';
-import { T as Token } from './Token-BzG5G4ja.js';
-import { D as DEFAULT_CONFIG, E as EngineConfig } from './Configuration-B-G5gTRn.js';
+import { E as EngineError } from './EngineError-B61GS1jp.js';
+import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-DCd5M6Gk.js';
+import { T as Token } from './Token-B1hdkedD.js';
+import { D as DEFAULT_CONFIG, E as EngineConfig } from './Configuration-C9W8tJv_.js';
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -73,6 +73,18 @@ declare class LineCache {
      * Iterate all cache entries for diagnostics/debugging.
      */
     forEach(callback: (key: string, entry: LineCacheEntry) => void): void;
+    /**
+     * 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.
+     */
+    snapshotEntries(): {
+        line: number;
+        expression: string;
+        entry: LineCacheEntry;
+    }[];
     /**
      * Get all entry keys.
      */
@@ -416,6 +428,195 @@ declare class DocumentModel {
     toJSON(): object;
 }
 
+/**
+ * Serialise and restore the state a session accumulates in memory.
+ *
+ * An engine builds up three things while it evaluates a document: named
+ * variables, user-defined functions, and a per-line result/bytecode cache.
+ * All three live only in memory, so a host that wants to persist a session,
+ * warm-start a process, or move a document between contexts has to re-evaluate
+ * the whole thing from scratch. This module turns that state into a plain,
+ * JSON-safe object (see {@link EngineSnapshot}) and back again, so the host can
+ * store it and rehydrate an engine that behaves as though it had evaluated the
+ * document itself.
+ *
+ * What is deliberately NOT carried:
+ * - Resolved async values (weather, stocks, currency, any package that fetches).
+ *   Those are point-in-time and must be re-fetched, not restored stale, so the
+ *   snapshot omits every line and variable backed by an async resolver. See
+ *   {@link ExpressionEngine.toJSON}, which filters them out before this module
+ *   ever sees them.
+ * - Package-contributed state (a package's own caches or globals). Core state
+ *   only for now; a package opt-in is a follow-up. See the guide.
+ *
+ * JSON safety is the load-bearing contract here. `JSON.stringify` cannot encode
+ * a `bigint` (it throws) and turns `NaN`/`Infinity` into `null` (a silent
+ * corruption), and typed arrays round-trip as sparse objects rather than
+ * arrays. Every value that crosses this boundary therefore goes through
+ * {@link encodeNumber} (non-finite numbers become sentinel strings) or is
+ * written as a decimal string (every `bigint`), and typed arrays are copied to
+ * plain arrays. A snapshot produced here survives `JSON.stringify` followed by
+ * `JSON.parse` unchanged.
+ */
+
+/**
+ * The magic string every snapshot carries, so a host handing `fromJSON` an
+ * arbitrary object (a config file, a different tool's export) is refused with a
+ * clear error rather than half-restored. See {@link assertRestorable}.
+ */
+declare const SNAPSHOT_FORMAT: "solve-engine/snapshot";
+/**
+ * The snapshot layout version, bumped whenever the serialised shape changes in
+ * a way an older reader cannot understand. `fromJSON` accepts only the exact
+ * version it was built for and refuses anything else with a coded error, which
+ * is the whole point of the field: a snapshot taken by a future (or older)
+ * engine is rejected loudly instead of being restored wrongly. This is separate
+ * from the engine's own semver (recorded alongside it as {@link
+ * EngineSnapshot.engineVersion} for diagnostics), because the serialised shape
+ * and the published API version do not have to move together.
+ */
+declare const SNAPSHOT_VERSION: 1;
+/**
+ * A number as it appears in a snapshot: an ordinary JSON number when finite, or
+ * a sentinel string when not. `JSON.stringify` writes `NaN`/`Infinity`/
+ * `-Infinity` as `null`, which would silently turn a real `1/0` into an absent
+ * value on the way back, so the three non-finite doubles are named instead.
+ */
+type SerializedNumber = number | "NaN" | "Infinity" | "-Infinity";
+/** {@link DecimalData} with its `bigint` coefficient written as a decimal string. */
+interface SerializedDecimal {
+    coef: string;
+    scale: number;
+}
+/** {@link Rational} with both `bigint` components written as decimal strings. */
+interface SerializedRational {
+    n: string;
+    d: string;
+}
+/**
+ * A {@link Value} in JSON-safe form, discriminated by its {@link ValueType}
+ * on the `t` field. Only the types a session can leave in a variable, a
+ * function result, or a cached line are represented; {@link ValueType.Pending}
+ * is filtered out upstream (an in-flight async result), and
+ * {@link ValueType.Symbolic} plus symbolic matrix cells are refused with a
+ * clear error (deferred, see the module doc).
+ */
+type SerializedValue = {
+    t: ValueType.Number;
+    v: SerializedNumber;
+    exact?: SerializedDecimal;
+    rational?: SerializedRational;
+} | {
+    t: ValueType.Hex;
+    v: SerializedNumber | string;
+    big?: boolean;
+    base?: string;
+} | {
+    t: ValueType.BigInt;
+    v: string;
+} | {
+    t: ValueType.String;
+    v: string;
+} | {
+    t: ValueType.Datetime;
+    v: SerializedNumber;
+} | {
+    t: ValueType.Percentage;
+    v: SerializedNumber;
+} | {
+    t: ValueType.Uom;
+    v: SerializedNumber;
+    unit: string;
+    exact?: SerializedDecimal;
+} | {
+    t: ValueType.Matrix;
+    rows: number;
+    cols: number;
+    data: (SerializedNumber | boolean)[];
+} | {
+    t: ValueType.Range;
+    min: SerializedNumber;
+    max: SerializedNumber;
+} | {
+    t: ValueType.Boolean;
+    v: boolean;
+} | {
+    t: ValueType.Error;
+    code: string;
+    message: string;
+};
+/** A {@link BytecodeProgram} with its typed arrays copied to plain arrays and non-finite constants named. */
+interface SerializedBytecode {
+    opcodes: number[];
+    numbers: SerializedNumber[];
+    strings: string[];
+    hasAsync: boolean;
+    constants?: [number, number][];
+    userFunctionBodies?: SerializedUserFunction[];
+    anonymousBodies?: SerializedAnonymousBody[];
+}
+/** A {@link UserFunctionDef}: name, parameter names, and the body compiled to its own program. */
+interface SerializedUserFunction {
+    name: string;
+    params: string[];
+    program: SerializedBytecode;
+}
+/** An {@link AnonymousBodyDef}: a `map`/`reduce` inline transform body, a user function minus the name. */
+interface SerializedAnonymousBody {
+    params: string[];
+    program: SerializedBytecode;
+}
+/** One cached line: the result, the compiled program, and the reads/writes the dependency graph needs. */
+interface SerializedLineCacheEntry {
+    line: number;
+    /** The expression text this entry is keyed under, or "" for an expressionless entry. Mirrors `LineCache`'s own two-level key. */
+    expression: string;
+    result: SerializedValue;
+    bytecode: SerializedBytecode;
+    reads: string[];
+    writeVar: string | null;
+}
+/**
+ * A complete, JSON-safe snapshot of an engine's session state.
+ *
+ * Produced by {@link ExpressionEngine.toJSON} and consumed by
+ * {@link ExpressionEngine.fromJSON}. Safe to `JSON.stringify`, store, and
+ * `JSON.parse` back into `fromJSON`.
+ */
+interface EngineSnapshot {
+    /** Always {@link SNAPSHOT_FORMAT}. Identifies the object as a snapshot before anything reads deeper. */
+    format: typeof SNAPSHOT_FORMAT;
+    /** The serialised-shape version, {@link SNAPSHOT_VERSION} at write time. `fromJSON` refuses any other value. */
+    version: number;
+    /** The engine's semver at write time, for diagnostics and forward compatibility decisions. Not itself a gate. */
+    engineVersion: string;
+    /** The locale the snapshot was taken under, so `fromJSON` can rebuild a matching lexer when the caller does not override it. */
+    locale: string;
+    /** Named variables, by name. Async-backed and in-flight variables are omitted (see the module doc). */
+    variables: Record<string, SerializedValue>;
+    /** User-defined functions (`f(x) = ...`). */
+    userFunctions: SerializedUserFunction[];
+    /** Cached lines, minus any backed by an async resolver. */
+    lineCache: SerializedLineCacheEntry[];
+    /** The expression-keyed bytecode cache, a pure recompilation cache, carried so a warm start skips re-parsing unchanged expressions. */
+    bytecodeCache: {
+        expression: string;
+        program: SerializedBytecode;
+    }[];
+}
+/**
+ * The coded errors this module and `fromJSON` raise. Registered in
+ * `errors/ErrorCode.ts` so the catalog test can see them.
+ */
+declare const SnapshotErrorCodes: {
+    /** The object handed to `fromJSON` is not a snapshot at all, or its version does not match this engine's reader. */
+    readonly SNAPSHOT_VERSION_MISMATCH: "SNAPSHOT_VERSION_MISMATCH";
+    /** A snapshot with the right envelope but internally inconsistent contents (a bad number sentinel, a missing field). */
+    readonly SNAPSHOT_MALFORMED: "SNAPSHOT_MALFORMED";
+    /** A value the snapshot format cannot yet represent (a symbolic expression, a symbolic matrix cell). Deferred, see the module doc. */
+    readonly SNAPSHOT_UNSUPPORTED_VALUE: "SNAPSHOT_UNSUPPORTED_VALUE";
+};
+
 /** Emitted when one or more lines have updated results after async resolution. */
 interface LinesUpdatedEvent {
     type: "lines-updated";
@@ -787,6 +988,42 @@ interface UnifiedParsingOptions {
     includeDiagnostics?: boolean;
 }
 
+/**
+ * One line of a derivation: a readable account of a single operation and the
+ * value it arrives at.
+ *
+ * `description` is prose for the person reading the note, not developer
+ * diagnostics ("80 less 20%", "64 plus 20%"), and `value` is that step's
+ * intermediate result, the same {@link Value} the engine would produce for it.
+ */
+interface ExplanationStep {
+    /** A short, human-readable account of the operation, e.g. "80 less 20%". */
+    readonly description: string;
+    /** The value this step arrives at. */
+    readonly value: Value;
+}
+/**
+ * A worked-through derivation of how a line reached its answer.
+ *
+ * `steps` is ordered the way the engine evaluates the line: an operand appears
+ * before the operation that consumes it, and each step's left-hand side is the
+ * running value carried down from the steps above it. `result` is the final
+ * value and is identical to what {@link ExpressionEngine.evaluateExpression}
+ * returns for the same line.
+ *
+ * A line with nothing to break down (a bare literal, or a construct this slice
+ * does not derive yet) returns an empty `steps` array with `result` set, rather
+ * than an error: the answer is still reported, just without a derivation.
+ */
+interface Explanation {
+    /** The expression as given. */
+    readonly expression: string;
+    /** The ordered derivation, one entry per operation, in evaluation order. */
+    readonly steps: ExplanationStep[];
+    /** The final value, identical to the engine's own answer for the line. */
+    readonly result: Value;
+}
+
 /**
  * DiagnosticPipelineResult, structured pipeline data contract.
  *
@@ -1198,6 +1435,31 @@ interface CheckpointSnapshot {
     variableCount: number;
 }
 
+/**
+ * Options for {@link ExpressionEngine.fromJSON}, restoring a snapshot onto a
+ * fresh engine.
+ */
+interface EngineRestoreOptions {
+    /**
+     * Packages to register on the restored engine. This MUST be the same set
+     * the snapshot was taken with: a snapshot carries compiled bytecode whose
+     * plugin-function indices and parselet-produced opcodes only line up
+     * against the packages that were present when it was written. Defaults to
+     * {@link BUILTIN_PACKAGES}, exactly like the constructor's own `packages`
+     * parameter, so a host using the default package set needs to pass nothing.
+     */
+    packages?: IEnginePackage[];
+    /** Config overrides, merged over `DEFAULT_CONFIG`, as in the constructor. */
+    config?: Partial<typeof DEFAULT_CONFIG>;
+    /** Turn on the diagnostic pipeline, as in the constructor's `diagnosticMode`. */
+    diagnosticMode?: boolean;
+    /**
+     * Override the locale the snapshot recorded. Rarely needed: the snapshot's
+     * own {@link EngineSnapshot.locale} is used by default, so a restored engine
+     * lexes the way the one that produced it did.
+     */
+    locale?: string;
+}
 /**
  * Return type of {@link evaluateLine} and {@link evaluateExpression}.
  *
@@ -1313,6 +1575,27 @@ declare class ExpressionEngine {
      * lifecycle itself.
      */
     private documentModel;
+    /**
+     * 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`.
+     */
+    private goalSeekDepth;
+    /** The most nesting {@link makeLineContext}'s `evaluateLineWithBinding` allows before refusing, so the bisection re-runs can never compound. */
+    private static readonly GOAL_SEEK_MAX_NESTING_DEPTH;
+    /**
+     * 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.
+     */
+    private batchScanResults;
+    private batchParsedLines;
     /**
      * Called once by `ThreeTierEvaluator`'s constructor. Not part of the
      * public evaluate-a-document contract, purely internal wiring so
@@ -1328,6 +1611,27 @@ declare class ExpressionEngine {
      * and return a clear error, never assume line 0 exists.
      */
     private makeLineContext;
+    /**
+     * 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.
+     */
+    private evaluateLineWithBinding;
     /**
      * Package-contributed completion candidates (`IEnginePackage.completionItems`),
      * keyed by package name, engine-instance-local, not a shared registry
@@ -1354,6 +1658,14 @@ declare class ExpressionEngine {
     private batcher;
     /** Post-lexer token normalizer for phrase fusion, implicit multiply, etc. */
     private normalizer;
+    /**
+     * 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.
+     */
+    private readonly userUnits;
     /** TanStack Query client, injected into resolvers for cache reads/writes. */
     readonly queryClient: QueryClient;
     private bytecodeCache;
@@ -1656,6 +1968,31 @@ declare class ExpressionEngine {
      * 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.
+     */
+    private tryDefineUserUnit;
     private trySymbolicGrammar;
     /**
      * Stores a general scalar equation (`x^2 - 4 = 0`) keyed by its unknown, or
@@ -2108,6 +2445,44 @@ declare class ExpressionEngine {
      * Returns the Value result. Throws on error.
      */
     evaluateExpression(expression: string): EvalResults;
+    /**
+     * 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: string): Explanation;
+    /**
+     * 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.
+     */
+    private evaluateIsolated;
     /**
      * Compile-only path: lex → parse → bytecode, without execution.
      *
@@ -2199,6 +2574,69 @@ declare class ExpressionEngine {
      */
     evaluateNumber(expression: string): number;
     clear(): void;
+    /**
+     * 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).
+     */
+    toJSON(): EngineSnapshot;
+    /**
+     * 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: EngineSnapshot, options?: EngineRestoreOptions): ExpressionEngine;
+    /**
+     * 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}.
+     */
+    private restoreSnapshot;
     /**
      * Incrementally re-evaluate lines affected by a variable change.
      * Walks the DAG from the changed variable to find exactly which lines
@@ -2681,4 +3119,4 @@ declare class PackageRegistry implements IPackageRegistry {
  */
 declare const packageRegistry: PackageRegistry;
 
-export { type ApplyChangesResult as A, type BatcherMetrics as B, type CacheSnapshot as C, DocumentModel as D, type EvalResults as E, type IEnginePackage as I, type LineEvaluation as L, PackageRegistry as P, type SemanticToken as S, type ViewportRange as V, ExpressionEngine as a, type IPackageRegistry as b, type LineChange as c, type InlineSolvePosition as d, type AsyncCachePackageInfo as e, type AsyncErrorEvent as f, AsyncResolutionBatcher as g, type AsyncResolutionEvent as h, type BytecodeCacheEntry as i, type CheckpointSnapshot as j, type LineCacheEntryInfo as k, type LineState as l, type LinesUpdatedEvent as m, type CompletionItem as n, LanguageService as o, packageRegistry as p, type LanguageServiceOptions as q };
+export { type ApplyChangesResult as A, type BatcherMetrics as B, type CacheSnapshot as C, DocumentModel as D, ExpressionEngine as E, type LineState as F, type LinesUpdatedEvent as G, type CompletionItem as H, type IEnginePackage as I, LanguageService as J, type LanguageServiceOptions as K, type LineEvaluation as L, type SemanticToken as M, type ParsedLine as N, type ParsingResult as O, PackageRegistry as P, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineRestoreOptions as a, type EngineSnapshot as b, type EvalResults as c, type Explanation as d, type ExplanationStep as e, type IPackageRegistry as f, SNAPSHOT_VERSION as g, type SerializedAnonymousBody as h, type SerializedBytecode as i, type SerializedDecimal as j, type SerializedLineCacheEntry as k, type SerializedNumber as l, type SerializedRational as m, type SerializedUserFunction as n, type SerializedValue as o, SnapshotErrorCodes as p, packageRegistry as q, type LineChange as r, type InlineSolvePosition as s, type AsyncCachePackageInfo as t, type AsyncErrorEvent as u, AsyncResolutionBatcher as v, type AsyncResolutionEvent as w, type BytecodeCacheEntry as x, type CheckpointSnapshot as y, type LineCacheEntryInfo as z };

package/dist/{Parselet-BaySkMV3.d.ts → Parselet-BBT8riYh.d.ts}

@@ -1,6 +1,6 @@
-import { B as BytecodeBuilder } from './BytecodeBuilder-B0xskcv5.js';
-import { T as Token } from './Token-BzG5G4ja.js';
-import { D as DiagnosticPipeline } from './pipeline-B6k5lCB7.js';
+import { B as BytecodeBuilder } from './BytecodeBuilder-Bp9xeTmX.js';
+import { T as Token } from './Token-B1hdkedD.js';
+import { D as DiagnosticPipeline } from './pipeline-DCd5M6Gk.js';
 
 /**
  * Dual-keyed ParseletRegistry, accepts both string token types and
@@ -148,6 +148,15 @@ declare class PrecedenceParser {
     private diagnosticPipeline;
     private currentExpression;
     private localeCode;
+    /**
+     * The binding power the current infix parselet is being invoked at, i.e. the
+     * `minBp` of the expression it sits inside. Set immediately before each Tier-2
+     * parselet runs. A parselet that decides whether to swallow a following
+     * loose operator (UomLiteralParselet with a trailing `in`/`to`) reads this to
+     * respect precedence it cannot otherwise see: `120 km / 2 hours in kph` must
+     * group as `(120 km / 2 hours) in kph`, not `120 km / (2 hours in kph)`.
+     */
+    infixMinBindingPower: number;
     /**
      * Static binding power table, built once at module load, shared across all instances.
      * Index = tokenTypeId, value = binding power (0 = not a built-in infix).

package/dist/{Parselet-DuI1Pjiq.d.cts → Parselet-BHcgK9S7.d.cts}

@@ -1,6 +1,6 @@
-import { B as BytecodeBuilder } from './BytecodeBuilder-B0xskcv5.cjs';
-import { T as Token } from './Token-BzG5G4ja.cjs';
-import { D as DiagnosticPipeline } from './pipeline-BEb3hujr.cjs';
+import { B as BytecodeBuilder } from './BytecodeBuilder-Bp9xeTmX.cjs';
+import { T as Token } from './Token-B1hdkedD.cjs';
+import { D as DiagnosticPipeline } from './pipeline-CtfJtPQc.cjs';
 
 /**
  * Dual-keyed ParseletRegistry, accepts both string token types and
@@ -148,6 +148,15 @@ declare class PrecedenceParser {
     private diagnosticPipeline;
     private currentExpression;
     private localeCode;
+    /**
+     * The binding power the current infix parselet is being invoked at, i.e. the
+     * `minBp` of the expression it sits inside. Set immediately before each Tier-2
+     * parselet runs. A parselet that decides whether to swallow a following
+     * loose operator (UomLiteralParselet with a trailing `in`/`to`) reads this to
+     * respect precedence it cannot otherwise see: `120 km / 2 hours in kph` must
+     * group as `(120 km / 2 hours) in kph`, not `120 km / (2 hours in kph)`.
+     */
+    infixMinBindingPower: number;
     /**
      * Static binding power table, built once at module load, shared across all instances.
      * Index = tokenTypeId, value = binding power (0 = not a built-in infix).