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

package/dist/Value-KtAQNHur.d.ts

@@ -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 };

package/dist/chunk-2RWAXT6O.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-2RWAXT6O.js.map
+//# sourceMappingURL=chunk-2RWAXT6O.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-2RWAXT6O.js"}