solve-engine 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/VMCheckpoints-CqFuLwrT.d.cts

@@ -0,0 +1,171 @@
+import { V as Value } from './Value-KtAQNHur.cjs';
+import { V as VM } from './ScopeManager-CKfQtl7l.cjs';
+import { U as UserFunctionDef } from './BytecodeBuilder-3egMyuDi.cjs';
+
+/**
+ * A point-in-time snapshot of VM variable state.
+ *
+ * Uses **prototypal inheritance** for memory efficiency: each checkpoint's
+ * `variables` object has its parent checkpoint's `variables` as its
+ * `__proto__`. This means a `getVar("x")` lookup walks the prototype chain
+ * until it finds `x`, and only variables that CHANGED at this checkpoint
+ * consume heap space. Unchanged variables are inherited from the parent.
+ *
+ * ```text
+ * Checkpoint 0 (root):  {}                        // empty scope
+ * Checkpoint 1 (:x=5):  { x: 5 }    __proto__ → 0
+ * Checkpoint 2 (:y=8):  { y: 8 }    __proto__ → 1
+ * Checkpoint 3 (:x=3):  { x: 3 }    __proto__ → 2   // shadows x=5
+ * ```
+ *
+ * To look up `x` at checkpoint 3: find own `x=3` → done.
+ * To look up `y` at checkpoint 3: not own → walk proto to checkpoint 2 → `y=8`.
+ * To look up `z` at checkpoint 3: not found anywhere → undefined.
+ *
+ * **Memory:** O(number of variable definitions) heap, independent of
+ * document length. Typical Obsidian documents have < 100 variable defs,
+ * so total checkpoint heap is < 10 KB.
+ */
+interface VMCheckpoint {
+    /** 1-based line number where this checkpoint was created. */
+    lineNumber: number;
+    /** Persistent line ID from DocumentModel. */
+    lineId: number;
+    /**
+     * Variable name → Value at this checkpoint.
+     * Own properties are variables set/updated at this line.
+     * The prototype chain provides inherited variables from parent checkpoints.
+     */
+    variables: Record<string, Value>;
+    /**
+     * User-defined-function name → definition at this checkpoint. SEPARATE
+     * from `variables` above (not prototypally chained the same way
+     * `restoreTo()` replays every checkpoint in the chain in order, so a
+     * later redefinition of the same function name naturally overwrites an
+     * earlier one during replay, without needing its own prototype walk).
+     *
+     * Without this field, a function definition's checkpoint entry would be
+     * SILENTLY LOST: `snapshot()` used to call `vm.getVar(name)` for every
+     * written name, which returns `undefined` for a function name (function
+     * defs live in `vm.userFunctions`, not the flat variable store), and a
+     * `val !== undefined` guard silently skipped it. A scroll-triggered
+     * `restoreTo()` would then reset the VM and replay only `variables`,
+     * making a function defined above the new viewport vanish (calling it
+     * would throw `UNDEFINED_FUNCTION`) even though the document still
+     * shows its definition line as clean/cached.
+     */
+    functions: Record<string, UserFunctionDef>;
+    /** Parent checkpoint (closer to document start), or null for root. */
+    parent: VMCheckpoint | null;
+}
+/**
+ * Manages VM state checkpoints for the three-tier evaluation strategy.
+ *
+ * **Checkpoint creation:** After a variable-definition line executes
+ * (Tier 1 or Tier 3), `snapshot()` records the current values of the
+ * written variables. The checkpoint is linked via prototypal inheritance
+ * to the previous checkpoint, so only changed variables consume memory.
+ *
+ * **Checkpoint restoration:** Before evaluating a viewport whose start line
+ * is not line 1, `restoreTo(lineNumber)` resets the VM and replays all
+ * variable definitions up to and including that line. This avoids
+ * re-evaluating the entire document from line 1 on every scroll.
+ *
+ * **Thread safety:** Checkpoints are created synchronously on the main
+ * thread during evaluation. They are immutable after creation (Value is
+ * an immutable type), so no synchronization is needed.
+ *
+ * **Integration with Phase 5.2e:** `setViewport()` will use `getNearestCheckpoint()`
+ * to find the checkpoint just before the new viewport start, then call
+ * `restoreTo()` to set up the VM before evaluating only the visible lines.
+ * This is the key to O(visible lines) scrolling instead of O(document).
+ */
+declare class VMCheckpointer {
+    /** Ordered array of checkpoints (ascending lineNumber). */
+    private checkpoints;
+    /** The VM instance whose variables are snapshotted/restored. */
+    private vm;
+    constructor(vm: VM);
+    /**
+     * Create a checkpoint at the current line, recording the VM values of
+     * the specified variables.
+     *
+     * Uses prototypal inheritance: `Object.create(parent.variables)` so
+     * that inherited variable lookups fall through to previous checkpoints
+     * without copying all variables into each checkpoint.
+     *
+     * @param lineNumber 1-based line position.
+     * @param lineId Persistent line ID from DocumentModel.
+     * @param variableNames Names of variables that were written at this line.
+     * @returns The new checkpoint, or null if no variable names provided.
+     */
+    snapshot(lineNumber: number, lineId: number, variableNames: string[]): VMCheckpoint | null;
+    /**
+     * Restore the VM to the state at or just after the given line number.
+     *
+     * Finds the nearest checkpoint whose `lineNumber <= targetLineNumber`,
+     * then replays all variable definitions from root → that checkpoint
+     * into the VM via `setVar()`. The VM's stack is also reset.
+     *
+     * If no checkpoint exists at or before the target line, the VM is
+     * fully reset (empty scope, empty stack).
+     *
+     * **Performance:** O(number of checkpoints × variables per checkpoint).
+     * With prototypal inheritance, `Object.keys()` on each checkpoint
+     * returns only the variables that were set at that checkpoint (not
+     * inherited ones), so the total work is O(total variable definitions
+     * in the document), which is < 100 for typical Obsidian documents.
+     *
+     * @param lineNumber Target 1-based line number. The VM will have the
+     * state that existed AFTER evaluating lines up to `lineNumber`.
+     */
+    restoreTo(lineNumber: number): void;
+    /**
+     * Find the nearest checkpoint at or before the given line number.
+     *
+     * Uses linear scan (checkpoints are sorted by lineNumber and the list
+     * is short, typically < 20 for Obsidian documents). Can be upgraded
+     * to binary search if needed for documents with 1000+ variable defs.
+     *
+     * @returns The nearest checkpoint, or null if none exists before the line.
+     */
+    getNearestCheckpoint(lineNumber: number): VMCheckpoint | null;
+    /**
+     * Get a specific checkpoint by its line number.
+     * @returns The checkpoint, or undefined if not found.
+     */
+    getCheckpointAt(lineNumber: number): VMCheckpoint | undefined;
+    /**
+     * Get the entire checkpoint chain from root to the last checkpoint.
+     * Useful for debugging and serialization.
+     */
+    getAllCheckpoints(): readonly VMCheckpoint[];
+    /**
+     * Look up a variable's value through the checkpoint chain.
+     *
+     * Walks the prototype chain starting from the most recent checkpoint,
+     * looking for the variable name as an own property. This is O(depth)
+     * where depth is the number of checkpoints since the variable was
+     * last set.
+     *
+     * **Note:** This queries the checkpointer's snapshot, not the VM.
+     * The VM may have been modified since the last snapshot (e.g., by
+     * Tier 2 execution of non-variable-def lines that don't create checkpoints).
+     *
+     * @returns The Value, or undefined if the variable was never set.
+     */
+    lookupVariable(name: string): Value | undefined;
+    /**
+     * Clear all checkpoints. The underlying VM is NOT reset, call
+     * `vm.reset()` separately if needed.
+     */
+    clear(): void;
+    /** Number of checkpoints stored. */
+    get count(): number;
+    /** Returns true if no checkpoints have been created. */
+    get isEmpty(): boolean;
+    /** The associated VM instance. */
+    get vmInstance(): VM;
+}
+
+export { type VMCheckpoint as V, VMCheckpointer as a };

package/dist/Value-KtAQNHur.d.cts

@@ -0,0 +1,295 @@
+/**
+ * Exact rational arithmetic over `bigint`, the coefficient type for every
+ * part of the symbolic algebra system.
+ *
+ * A computer-algebra system cannot work in IEEE doubles. Factoring
+ * `x^2 - x/3 - 2/3` needs `1/3` to stay `1/3` rather than becoming
+ * `0.3333333333333333`, and the rational-root theorem tests candidate roots
+ * by exact division, where a rounding error is indistinguishable from a
+ * genuine root. Every coefficient in `SymbolicNode`, `Polynomial`, `Factor`
+ * and `Solve` is a Rational for that reason.
+ *
+ * Values are always normalized on construction (`d > 0n`, `gcd(|n|, d) === 1n`,
+ * zero is exactly `0n/1n`), so structural equality on the `{n, d}` pair is
+ * mathematical equality, and the pair can be used directly as a cache key.
+ *
+ * A Rational holds two `bigint`s. Structured clone, which is what the
+ * playground's `postMessage` uses to ship a `SymbolicNode` to the VM trace
+ * view, handles bigint correctly. `JSON.stringify` does not: it throws
+ * `TypeError: Do not know how to serialize a BigInt`. Do not introduce a JSON
+ * round-trip anywhere a Rational can reach.
+ */
+/**
+ * An exact rational number.
+ *
+ * Always normalized, see this module's own doc comment for the invariant.
+ * Construct via {@link rational} or {@link rationalFromNumber} rather than as
+ * an object literal, which would bypass normalization.
+ */
+interface Rational {
+    /** Signed numerator. Carries the sign of the whole value. */
+    readonly n: bigint;
+    /** Denominator, always strictly positive. */
+    readonly d: bigint;
+}
+
+/**
+ * Exact complex arithmetic over the Gaussian rationals.
+ *
+ * Both components are {@link Rational}, so this is exact in the same sense the
+ * rest of the system is: `(1+2i)/(3-4i)` has an exact answer and gets it,
+ * rather than a pair of doubles that are nearly right. That matters most where
+ * a complex value has to be recognised as zero, which is how a cubic's
+ * *casus irreducibilis* is detected and how a conjugate pair cancels.
+ *
+ * ## Why the number tower stops here
+ *
+ * Real values stay {@link Rational} throughout. A complex value only appears
+ * when something genuinely produces one: a negative discriminant, a square root
+ * of a negative number, or an explicit `i`. That keeps every real-only path
+ * paying nothing for complex support, and it keeps `factor` and `solve` working
+ * over the rationals by default, which is what a CAS is expected to do.
+ *
+ * A complex whose imaginary part is zero is collapsed back to a real constant
+ * at the boundary, so `(1+i)*(1-i)` reads as `2` rather than `2+0i`.
+ */
+
+/**
+ * An exact complex number, `re + im * i`, with both parts rational.
+ *
+ * Construct through {@link complex} rather than as an object literal, so the
+ * real-collapse convention below stays consistent.
+ */
+interface Complex {
+    /** Real part. */
+    readonly re: Rational;
+    /** Imaginary part. Zero means this value is really a real number. */
+    readonly im: Rational;
+}
+
+/**
+ * The symbolic expression tree: an algebraic formula over free variables,
+ * rather than a concrete number.
+ *
+ * This is the data type the whole symbolic algebra system manipulates. It is
+ * deliberately a plain discriminated union of immutable object literals, not a
+ * class hierarchy, so a node can cross the worker boundary by structured clone
+ * (see `diagnostics/events.ts`, which carries these in its VM trace payload)
+ * and so pattern matching in the simplifier stays exhaustive under the
+ * compiler's own checking.
+ *
+ * Two variants exist here that the original bounded simplifier did not have,
+ * and they are what unlocks the rest of the system:
+ *
+ * - `pow` gives exponentiation a representation. Without it `x^2` had nowhere
+ *   to go, and `OpCode.EXP` fell through to `Math.pow(0, 2)` because
+ *   `Value.toNumber()` reports `0` for a symbolic operand, so `x^2 + 3x + 2`
+ *   silently evaluated to `3x+2`. Polynomials, derivatives and roots all need it.
+ * - `call` gives function application a representation, so `sqrt(x)` and
+ *   `sin(x)` carry through a symbolic expression instead of collapsing to
+ *   `sqrt(0)`.
+ *
+ * Coefficients are exact rationals, never doubles. See `Rational.ts` for why.
+ */
+
+/**
+ * A symbolic (algebraic) expression tree.
+ *
+ * Build nodes through the constructor functions in this module rather than as
+ * object literals, so constants normalize consistently.
+ */
+type SymbolicNode = {
+    kind: "const";
+    value: Rational;
+} | {
+    kind: "complex";
+    value: Complex;
+} | {
+    kind: "var";
+    name: string;
+} | {
+    kind: "add";
+    left: SymbolicNode;
+    right: SymbolicNode;
+} | {
+    kind: "sub";
+    left: SymbolicNode;
+    right: SymbolicNode;
+} | {
+    kind: "mul";
+    left: SymbolicNode;
+    right: SymbolicNode;
+} | {
+    kind: "div";
+    left: SymbolicNode;
+    right: SymbolicNode;
+} | {
+    kind: "neg";
+    operand: SymbolicNode;
+} | {
+    kind: "pow";
+    base: SymbolicNode;
+    exponent: SymbolicNode;
+} | {
+    kind: "call";
+    name: string;
+    args: readonly SymbolicNode[];
+};
+
+/**
+ * A single matrix cell. `boolean` covers element-wise comparison results
+ * (`[1,6;3,8] < [5,2;7,4]` produces a Matrix of booleans, not numbers). A
+ * `SymbolicNode` cell is a free-variable algebraic entry, e.g. `s =
+ * [sx,0,0;0,sy,0;0,0,1]` where `sx`/`sy` are never assigned, so those
+ * cells store a real `SymbolicNode` (a bare `var` node initially) rather
+ * than degrading to `0`. See `MatrixOps.ts`'s `entryToSymbolic()`/
+ * `symbolicToEntry()` for the two-way conversion every symbolic-aware
+ * matrix op (multiply, inverse, determinant) uses.
+ */
+type MatrixEntry = number | boolean | SymbolicNode;
+/**
+ * A general rows×cols matrix, a vector is just a 1×N (row) or N×1 (column)
+ * matrix. `data` is COLUMN-MAJOR (`data[row + col*rows]`), matching the
+ * spec's own `a[index]` column-major indexing semantics directly (no
+ * translation needed for single-index reads). `hasSymbolic` lets every
+ * numeric matrix op fast-path the all-numeric case with one boolean check,
+ * mirroring `binaryOp()`'s existing Number+Number fast path, computed by
+ * `matrixValue()` itself (true the moment any cell is a `SymbolicNode`
+ * object rather than a plain number/boolean), not something callers set
+ * by hand.
+ */
+interface MatrixData {
+    readonly rows: number;
+    readonly cols: number;
+    readonly data: readonly MatrixEntry[];
+    readonly hasSymbolic: boolean;
+}
+/** A first-class integer range `min:max`, both bounds inclusive. */
+interface RangeData {
+    readonly min: number;
+    readonly max: number;
+}
+/**
+ * Discriminated union tag for {@link Value} objects.
+ *
+ * Determines the runtime type of a Value and how its `value` field should
+ * be interpreted. Used by the VM for type-aware dispatch in arithmetic,
+ * comparison, and conversion operations.
+ */
+declare enum ValueType {
+    /** Plain 64-bit floating point number (IEEE 754 double) */
+    Number = 0,
+    Hex = 1,
+    BigInt = 2,
+    String = 3,
+    Datetime = 4,
+    Percentage = 5,
+    Uom = 6,
+    /** General rows×cols matrix (a vector is a 1×N or N×1 matrix). Value is {@link MatrixData}. */
+    Matrix = 7,
+    /** A first-class integer range `min:max`, both inclusive. Value is {@link RangeData}. */
+    Range = 8,
+    /** A symbolic/algebraic expression tree (free-variable formula, not a concrete number). Value is a `SymbolicNode` (`@solve-js/symbolic`). */
+    Symbolic = 9,
+    /** Boolean true/false. Value is `boolean`. */
+    Boolean = 10,
+    /** Unit of measurement token (lexer only, not a runtime value). */
+    Unit = 11,
+    /** Async result pending resolution. Value stores the queryKey string. */
+    Pending = 12,
+    /** Plugin-raised error propagated through the DAG. Value stores error code, unit stores message. */
+    Error = 13
+}
+/**
+ * Universal runtime value for the solve-js VM.
+ *
+ * Carries a {@link ValueType} discriminant, a polymorphic `value` payload,
+ * and an optional `unit` string (for UoM values). Treated as immutable after
+ * construction, the arena reuses objects internally via `recycle()`, but
+ * external code should never mutate Value fields.
+ *
+ * A cached `_cachedNumber` avoids repeated `toNumber()` computation on
+ * hot paths (ADD/SUB/MUL in the VM dispatch loop).
+ */
+declare class Value {
+    private _cachedNumber;
+    type: ValueType;
+    value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode;
+    unit?: string;
+    /** Set by async resolvers when a fetch timed out, the result is a fallback (typically 0). */
+    timedOut?: boolean;
+    constructor(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode, unit?: string);
+    /**
+     * Phase 5.3: Reset all fields for arena reuse.
+     * Called by ValueArena.acquire(), zero allocation, just field assignment.
+     */
+    recycle(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode, unit?: string): void;
+    isNumber(): this is Value & {
+        value: number;
+    };
+    isHex(): this is Value & {
+        value: number;
+    };
+    isBigInt(): this is Value & {
+        value: bigint;
+    };
+    isString(): this is Value & {
+        value: string;
+    };
+    isMatrix(): this is Value & {
+        value: MatrixData;
+    };
+    /** A Matrix shaped like a vector, 1×N (row) or N×1 (column). */
+    isVectorShape(): boolean;
+    isRange(): this is Value & {
+        value: RangeData;
+    };
+    isSymbolic(): this is Value & {
+        value: SymbolicNode;
+    };
+    toNumber(): number;
+    isNaN(): boolean;
+}
+/**
+ * Create a Number-typed Value. Uses the arena when active for zero-allocation.
+ * This is the most common factory, over 90% of all Value creations.
+ */
+declare function numberValue(n: number): Value;
+/** Which base a {@link ValueType.Hex} value is displayed in. */
+type DisplayBase = "hex" | "bin" | "oct";
+/**
+ * Create a Hex-typed Value: a **number** that displays in another base.
+ *
+ * The type is numeric on purpose, and that is the whole point of it. A base is
+ * a way of writing a quantity, not a different kind of quantity, so `0xFF + 1`
+ * has to be 256. Returning a string instead makes it 1, because a string reads
+ * as zero in arithmetic, and nothing about that failure is visible at the point
+ * of use.
+ *
+ * @param n - The number itself, in full precision.
+ * @param base - How to display it, defaulting to hexadecimal. Carried in the
+ * `unit` slot, which is free for this type.
+ */
+declare function hexValue(n: number, base?: DisplayBase): Value;
+/** Create a BigInt-typed Value (arbitrary-precision integer). */
+declare function bigIntValue(n: bigint): Value;
+/** Create a String-typed Value. */
+declare function stringValue(s: string): Value;
+/** Create a Unit-of-Measurement Value (typed number with unit annotation). */
+declare function uomValue(n: number, unit: string): Value;
+/**
+ * Create a Matrix value from an explicit shape + column-major data array.
+ * `data.length` must equal `rows*cols`, callers building a matrix from
+ * row-major source syntax (e.g. the `[1,2;3,4]` literal) must transpose
+ * into column-major order before calling this; see `MatrixOps.ts`'s
+ * `rowMajorToColumnMajor()`.
+ */
+declare function matrixValue(rows: number, cols: number, data: readonly MatrixEntry[]): Value;
+/** A 1×N row-vector Matrix, row-major and column-major storage are identical for a single row. */
+declare function rowVectorValue(data: readonly number[]): Value;
+/** An N×1 column-vector Matrix, row-major and column-major storage are identical for a single column. */
+declare function colVectorValue(data: readonly number[]): Value;
+/** Create a Range value, a first-class integer range `min:max`, both bounds inclusive. */
+declare function rangeValue(min: number, max: number): Value;
+
+export { type MatrixData as M, type RangeData as R, type SymbolicNode as S, Value as V, type MatrixEntry as a, ValueType as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, hexValue as h, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };