solve-engine 1.0.0-beta.6 → 1.0.0

package/dist/{ScopeManager-CKfQtl7l.d.cts → ScopeManager-B6GzdhVG.d.cts}

@@ -1,7 +1,7 @@
-import { V as Value } from './Value-KtAQNHur.cjs';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.cjs';
-import { E as EngineError } from './EngineError-DvPSnhZi.cjs';
-import { D as DiagnosticPipeline } from './pipeline-DPUQt7yL.cjs';
+import { V as Value } from './Value-CXJqDH9J.cjs';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-B0xskcv5.cjs';
+import { E as EngineError } from './EngineError-LU7W7AgI.cjs';
+import { D as DiagnosticPipeline } from './pipeline-BEb3hujr.cjs';
 import { VariableResolver } from './variables.cjs';
 
 /**
@@ -19,8 +19,27 @@ import { VariableResolver } from './variables.cjs';
  * @param maxFunctionRecursionDepth - Maximum nested user-defined-function
  *   calls (default 50). See the VM interface's `pushCallFrame` doc for why
  *   this exists as its own dedicated guard, separate from `maxInstructions`.
+ * @param maxCollectionSize - Maximum elements a Range or Matrix may be
+ *   expanded to by `map`/`reduce` (default 100000). Neither of the two
+ *   counters above can see that expansion, since it happens inside one
+ *   opcode and never touches the value stack.
+ * @param maxAllocatedElements - Maximum elements one evaluation may
+ *   materialise in TOTAL (default 2000000). The parameter above bounds one
+ *   collection; per-site bounds do not compose, and an operation whose result
+ *   is the product of two legal operands (a matrix multiply) is bounded by
+ *   neither. See `vm/AllocationBudget.ts`.
+ * @param maxFunctionCalls - Maximum user-defined-function calls one
+ *   evaluation may make in total (default 10000). `maxFunctionRecursionDepth`
+ *   above bounds how deep they nest and cannot see how many there are: a
+ *   doubling chain reaches two million calls at a depth of twenty-two.
+ * @param maxDateOffsetYears - How far forward `<date> + N workdays` may
+ *   reach, in years (default 100). The one date offset that walks rather than
+ *   computing, so the one that needs a ceiling. See `addBusinessDays()`.
+ * @param minDateOffsetYears - The same bound backwards, negative (default
+ *   -100).
+ * @param context - Registries belonging to the engine that created this VM.
  */
-declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, context?: EngineContext): VM;
+declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, maxCollectionSize?: number, maxAllocatedElements?: number, maxFunctionCalls?: number, maxDateOffsetYears?: number, minDateOffsetYears?: number, context?: EngineContext): VM;
 /**
  * Compiled bytecode ready for VM execution.
  *
@@ -310,7 +329,26 @@ declare class OpRegistry {
 interface VM {
     push(value: Value): void;
     pop(): Value;
+    /**
+     * Pop the top of the stack as a number.
+     *
+     * @throws `STACK_UNDERFLOW` (INTERNAL) if the stack is empty. Unlike
+     *   `pop()`, which answers an empty stack with `0`, this reports it: a
+     *   handler asking for a number has no way to tell that `0` from a real
+     *   one. Every Value converts, so there is no operand-type throw here.
+     */
     popNumber(): number;
+    /**
+     * Pop the top of the stack as a string, e.g. a unit name a handler's own
+     * bytecode pushed for it to read.
+     *
+     * @throws `STACK_UNDERFLOW` (INTERNAL) if the stack is empty, and
+     *   `MALFORMED_BYTECODE_OPERAND_TYPE` (VALIDATION, recoverable) if the
+     *   value on top is not a string. Both are structured `EngineError`s
+     *   naming this method, in place of the raw TypeError a bare `pop()!` and
+     *   a compile-time-only cast used to produce somewhere further along. A
+     *   handler that would rather branch than throw can `peek()` first.
+     */
     popString(): string;
     peek(): Value;
     getStack(): Value[];
@@ -360,8 +398,39 @@ interface VM {
     getScalarEquation(variable: string): ScalarEquationDef | undefined;
     hasScalarEquation(variable: string): boolean;
     reset(): void;
+    /** The innermost call frame's bindings, or `undefined` when no call is in progress. Read-only, for building a frame that extends the current one rather than replacing it (see `BIND_UNKNOWN`'s handler). */
+    getCallFrame(): ReadonlyMap<string, Value> | undefined;
     getMaxInstructions(): number;
     getMaxStackDepth(): number;
+    /** Maximum elements a Range or Matrix may be expanded to by `map`/`reduce`. See `constants/Configuration.ts`'s `maxCollectionSize`. */
+    getMaxCollectionSize(): number;
+    /**
+     * Maximum elements (collection Values, matrix cells) one evaluation may
+     * materialise in total.
+     *
+     * The bound the two limits above cannot be. Both are checked between
+     * opcodes, so neither sees what one opcode allocates inside a loop of its
+     * own, and `getMaxCollectionSize()` bounds one collection without bounding
+     * the total. See `vm/AllocationBudget.ts` for the counter this configures
+     * and for why charging goes through that module rather than through the VM.
+     */
+    getMaxAllocatedElements(): number;
+    /**
+     * Maximum user-defined-function calls one evaluation may make in total.
+     *
+     * `maxFunctionRecursionDepth` (see `pushCallFrame` above) bounds how DEEP
+     * calls nest; this bounds how MANY there are, which is a different number
+     * and the one a doubling chain runs away with: twenty-two lines of
+     * `f(v) = g(v) + g(v)` reach two million calls at a depth of twenty-two.
+     * Held by `vm/AllocationBudget.ts` rather than counted here, because it has
+     * to survive `executeBytecode()` re-entering itself, exactly like the
+     * element tally and unlike `maxInstructions`.
+     */
+    getMaxFunctionCalls(): number;
+    /** How far forward `<date> + N workdays` may reach, in years. The one date offset that walks the calendar rather than computing, so the one with a ceiling. See `constants/Configuration.ts`'s `date.maxOffsetYears`. */
+    getMaxDateOffsetYears(): number;
+    /** The same bound backwards, as a negative number of years. */
+    getMinDateOffsetYears(): number;
     getInstructionCount(): number;
     incrementInstructions(n: number): void;
     /** Active AbortSignal for the current expression evaluation. Checked before cache writes. */
@@ -556,4 +625,4 @@ declare class ScopeManager {
     clear(): void;
 }
 
-export { type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, type LineExecutionContext as L, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, type DagSnapshot as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };
+export { type Bytecode as B, type DagSnapshot as D, type ExpressionRecord as E, type LineExecutionContext as L, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, DependencyGraph as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };

package/dist/{ScopeManager-B5k0nk05.d.ts → ScopeManager-udv4Twwq.d.ts}

@@ -1,7 +1,7 @@
-import { V as Value } from './Value-KtAQNHur.js';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.js';
-import { E as EngineError } from './EngineError-DvPSnhZi.js';
-import { D as DiagnosticPipeline } from './pipeline-CrsRPmsv.js';
+import { V as Value } from './Value-CXJqDH9J.js';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-B0xskcv5.js';
+import { E as EngineError } from './EngineError-LU7W7AgI.js';
+import { D as DiagnosticPipeline } from './pipeline-B6k5lCB7.js';
 import { VariableResolver } from './variables.js';
 
 /**
@@ -19,8 +19,27 @@ import { VariableResolver } from './variables.js';
  * @param maxFunctionRecursionDepth - Maximum nested user-defined-function
  *   calls (default 50). See the VM interface's `pushCallFrame` doc for why
  *   this exists as its own dedicated guard, separate from `maxInstructions`.
+ * @param maxCollectionSize - Maximum elements a Range or Matrix may be
+ *   expanded to by `map`/`reduce` (default 100000). Neither of the two
+ *   counters above can see that expansion, since it happens inside one
+ *   opcode and never touches the value stack.
+ * @param maxAllocatedElements - Maximum elements one evaluation may
+ *   materialise in TOTAL (default 2000000). The parameter above bounds one
+ *   collection; per-site bounds do not compose, and an operation whose result
+ *   is the product of two legal operands (a matrix multiply) is bounded by
+ *   neither. See `vm/AllocationBudget.ts`.
+ * @param maxFunctionCalls - Maximum user-defined-function calls one
+ *   evaluation may make in total (default 10000). `maxFunctionRecursionDepth`
+ *   above bounds how deep they nest and cannot see how many there are: a
+ *   doubling chain reaches two million calls at a depth of twenty-two.
+ * @param maxDateOffsetYears - How far forward `<date> + N workdays` may
+ *   reach, in years (default 100). The one date offset that walks rather than
+ *   computing, so the one that needs a ceiling. See `addBusinessDays()`.
+ * @param minDateOffsetYears - The same bound backwards, negative (default
+ *   -100).
+ * @param context - Registries belonging to the engine that created this VM.
  */
-declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, context?: EngineContext): VM;
+declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, maxCollectionSize?: number, maxAllocatedElements?: number, maxFunctionCalls?: number, maxDateOffsetYears?: number, minDateOffsetYears?: number, context?: EngineContext): VM;
 /**
  * Compiled bytecode ready for VM execution.
  *
@@ -310,7 +329,26 @@ declare class OpRegistry {
 interface VM {
     push(value: Value): void;
     pop(): Value;
+    /**
+     * Pop the top of the stack as a number.
+     *
+     * @throws `STACK_UNDERFLOW` (INTERNAL) if the stack is empty. Unlike
+     *   `pop()`, which answers an empty stack with `0`, this reports it: a
+     *   handler asking for a number has no way to tell that `0` from a real
+     *   one. Every Value converts, so there is no operand-type throw here.
+     */
     popNumber(): number;
+    /**
+     * Pop the top of the stack as a string, e.g. a unit name a handler's own
+     * bytecode pushed for it to read.
+     *
+     * @throws `STACK_UNDERFLOW` (INTERNAL) if the stack is empty, and
+     *   `MALFORMED_BYTECODE_OPERAND_TYPE` (VALIDATION, recoverable) if the
+     *   value on top is not a string. Both are structured `EngineError`s
+     *   naming this method, in place of the raw TypeError a bare `pop()!` and
+     *   a compile-time-only cast used to produce somewhere further along. A
+     *   handler that would rather branch than throw can `peek()` first.
+     */
     popString(): string;
     peek(): Value;
     getStack(): Value[];
@@ -360,8 +398,39 @@ interface VM {
     getScalarEquation(variable: string): ScalarEquationDef | undefined;
     hasScalarEquation(variable: string): boolean;
     reset(): void;
+    /** The innermost call frame's bindings, or `undefined` when no call is in progress. Read-only, for building a frame that extends the current one rather than replacing it (see `BIND_UNKNOWN`'s handler). */
+    getCallFrame(): ReadonlyMap<string, Value> | undefined;
     getMaxInstructions(): number;
     getMaxStackDepth(): number;
+    /** Maximum elements a Range or Matrix may be expanded to by `map`/`reduce`. See `constants/Configuration.ts`'s `maxCollectionSize`. */
+    getMaxCollectionSize(): number;
+    /**
+     * Maximum elements (collection Values, matrix cells) one evaluation may
+     * materialise in total.
+     *
+     * The bound the two limits above cannot be. Both are checked between
+     * opcodes, so neither sees what one opcode allocates inside a loop of its
+     * own, and `getMaxCollectionSize()` bounds one collection without bounding
+     * the total. See `vm/AllocationBudget.ts` for the counter this configures
+     * and for why charging goes through that module rather than through the VM.
+     */
+    getMaxAllocatedElements(): number;
+    /**
+     * Maximum user-defined-function calls one evaluation may make in total.
+     *
+     * `maxFunctionRecursionDepth` (see `pushCallFrame` above) bounds how DEEP
+     * calls nest; this bounds how MANY there are, which is a different number
+     * and the one a doubling chain runs away with: twenty-two lines of
+     * `f(v) = g(v) + g(v)` reach two million calls at a depth of twenty-two.
+     * Held by `vm/AllocationBudget.ts` rather than counted here, because it has
+     * to survive `executeBytecode()` re-entering itself, exactly like the
+     * element tally and unlike `maxInstructions`.
+     */
+    getMaxFunctionCalls(): number;
+    /** How far forward `<date> + N workdays` may reach, in years. The one date offset that walks the calendar rather than computing, so the one with a ceiling. See `constants/Configuration.ts`'s `date.maxOffsetYears`. */
+    getMaxDateOffsetYears(): number;
+    /** The same bound backwards, as a negative number of years. */
+    getMinDateOffsetYears(): number;
     getInstructionCount(): number;
     incrementInstructions(n: number): void;
     /** Active AbortSignal for the current expression evaluation. Checked before cache writes. */
@@ -556,4 +625,4 @@ declare class ScopeManager {
     clear(): void;
 }
 
-export { type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, type LineExecutionContext as L, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, type DagSnapshot as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };
+export { type Bytecode as B, type DagSnapshot as D, type ExpressionRecord as E, type LineExecutionContext as L, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, DependencyGraph as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };

package/dist/{VMCheckpoints-BmDwIXgK.d.ts → VMCheckpoints-BiaIlOOY.d.ts}

@@ -1,6 +1,6 @@
-import { V as Value } from './Value-KtAQNHur.js';
-import { V as VM } from './ScopeManager-B5k0nk05.js';
-import { U as UserFunctionDef } from './BytecodeBuilder-3egMyuDi.js';
+import { V as Value } from './Value-CXJqDH9J.js';
+import { V as VM } from './ScopeManager-udv4Twwq.js';
+import { U as UserFunctionDef } from './BytecodeBuilder-B0xskcv5.js';
 
 /**
  * A point-in-time snapshot of VM variable state.
@@ -168,4 +168,4 @@ declare class VMCheckpointer {
     get vmInstance(): VM;
 }
 
-export { type VMCheckpoint as V, VMCheckpointer as a };
+export { VMCheckpointer as V, type VMCheckpoint as a };

package/dist/{VMCheckpoints-CqFuLwrT.d.cts → VMCheckpoints-DwLjivM7.d.cts}

@@ -1,6 +1,6 @@
-import { V as Value } from './Value-KtAQNHur.cjs';
-import { V as VM } from './ScopeManager-CKfQtl7l.cjs';
-import { U as UserFunctionDef } from './BytecodeBuilder-3egMyuDi.cjs';
+import { V as Value } from './Value-CXJqDH9J.cjs';
+import { V as VM } from './ScopeManager-B6GzdhVG.cjs';
+import { U as UserFunctionDef } from './BytecodeBuilder-B0xskcv5.cjs';
 
 /**
  * A point-in-time snapshot of VM variable state.
@@ -168,4 +168,4 @@ declare class VMCheckpointer {
     get vmInstance(): VM;
 }
 
-export { type VMCheckpoint as V, VMCheckpointer as a };
+export { VMCheckpointer as V, type VMCheckpoint as a };

package/dist/{Value-KtAQNHur.d.cts → Value-CXJqDH9J.d.cts}

@@ -266,11 +266,14 @@ type DisplayBase = "hex" | "bin" | "oct";
  * 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 n - The number itself, in full precision. A `bigint` is accepted for
+ * the same reason the type is numeric at all: `12345678901234567890n as hex`
+ * has an exact answer, and forcing it through a double first rendered
+ * 0xAB54A98CEB1F0800 for a value ending 0AD2.
  * @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;
+declare function hexValue(n: number | bigint, base?: DisplayBase): Value;
 /** Create a BigInt-typed Value (arbitrary-precision integer). */
 declare function bigIntValue(n: bigint): Value;
 /** Create a String-typed Value. */

package/dist/{Value-KtAQNHur.d.ts → Value-CXJqDH9J.d.ts}

@@ -266,11 +266,14 @@ type DisplayBase = "hex" | "bin" | "oct";
  * 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 n - The number itself, in full precision. A `bigint` is accepted for
+ * the same reason the type is numeric at all: `12345678901234567890n as hex`
+ * has an exact answer, and forcing it through a double first rendered
+ * 0xAB54A98CEB1F0800 for a value ending 0AD2.
  * @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;
+declare function hexValue(n: number | bigint, base?: DisplayBase): Value;
 /** Create a BigInt-typed Value (arbitrary-precision integer). */
 declare function bigIntValue(n: bigint): Value;
 /** Create a String-typed Value. */