solve-engine 1.0.0-beta.7 → 1.0.1

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

@@ -1,6 +1,6 @@
-import { B as BytecodeBuilder } from './BytecodeBuilder-3egMyuDi.cjs';
+import { B as BytecodeBuilder } from './BytecodeBuilder-B0xskcv5.cjs';
 import { T as Token } from './Token-BzG5G4ja.cjs';
-import { D as DiagnosticPipeline } from './pipeline-DPUQt7yL.cjs';
+import { D as DiagnosticPipeline } from './pipeline-BEb3hujr.cjs';
 
 /**
  * Dual-keyed ParseletRegistry, accepts both string token types and
@@ -44,13 +44,44 @@ declare class ParseletRegistry {
     registerPrefix(tokenType: string, parselet: PrefixParselet): void;
     /** Register an infix parselet for `tokenType`. See {@link registerPrefix} for the collision-warning behavior this mirrors. */
     registerInfix(tokenType: string, parselet: InfixParselet): void;
-    /** Iterate all registered prefix parselets for diagnostic display. */
+    /**
+     * Iterate all registered prefix parselets for diagnostic display.
+     *
+     * `PrefixParselet` declares no binding power, and this used to read a field
+     * of that name and report 0 for every one of them. 0 is not a neutral
+     * wrong answer: it is the value that means "not an operator, stop the
+     * expression", so a host drawing a table from this was told none of them
+     * bind at all. A prefix parselet in this parser has no per-parselet power
+     * to report, they all bind at the prefix level and each chooses for itself
+     * at what power to parse its own operand, so that level is what is
+     * reported. A parselet that does carry its own `bindingPower` still wins.
+     */
     getAllPrefix(): Array<{
         tokenType: string;
         bindingPower: number;
         category?: string;
     }>;
-    /** Iterate all registered infix parselets for diagnostic display. */
+    /**
+     * Iterate all registered infix parselets for diagnostic display.
+     *
+     * The field an `InfixParselet` actually declares is `bindingPower`. This
+     * used to read `leftBindingPower` and `rightBindingPower`, which no
+     * parselet in this codebase declares, so both reads were `undefined`, both
+     * fell to the `?? 0` default, and the public `getParseletRegistry()`
+     * reported a binding power of 0 for every one of the ~60 infix operators.
+     * A host building a precedence table from it was told `*` and `+` bind
+     * equally, and that neither binds at all.
+     *
+     * The left/right split: `bindingPower` is the LEFT power, and the right is
+     * one higher. That is the standard encoding for a left-associative
+     * operator, and it is what the parser itself does, see
+     * `PrecedenceParser.parseExpression()`'s `bp + 1` for the right operand.
+     * Every operator is reported that way, `^` included. Associativity is not
+     * something a parselet declares, it is a property of how each one calls
+     * `parseExpression`, so this API cannot report it without a new field on
+     * the interface. See {@link ParseletBindingPowers} for why scraping a
+     * plausible-looking one off the parselet is worse than not reporting it.
+     */
     getAllInfix(): Array<{
         tokenType: string;
         leftBindingPower: number;
@@ -137,6 +168,7 @@ declare class PrecedenceParser {
     private static readonly CARET_ID;
     private static readonly LSHIFT_ID;
     private static readonly RSHIFT_ID;
+    private static readonly URSHIFT_ID;
     private static readonly BIT_AND_ID;
     private static readonly BIT_OR_ID;
     private static readonly BIT_XOR_ID;
@@ -170,7 +202,7 @@ declare class PrecedenceParser {
      *
      * @param minBp - minimum binding power (precedence climbing threshold).
      *   For left-associative operators, the recursive call uses `bp + 1`.
-     *   For right-associative operators (^), it uses `bp`.
+     *   For right-associative operators (^), it uses `bp - 1`.
      * @param _builder - accepted for parselet API compatibility; always uses `this.builder`.
      */
     parseExpression(minBp?: number, _builder?: BytecodeBuilder): void;

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. */

package/dist/{chunk-35IWNZPJ.cjs → chunk-2XLQPQKI.cjs}

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkM4N5GA5Z_cjs = require('./chunk-M4N5GA5Z.cjs');
+var chunk5KMIY374_cjs = require('./chunk-5KMIY374.cjs');
 
 // package.json
-var version = "1.0.0-beta.7";
+var version = "1.0.1";
 
 // src/constants/version.ts
 var ENGINE_VERSION = version;
@@ -11,25 +11,31 @@ var ENGINE_VERSION = version;
 // src/constants/Configuration.ts
 var DEFAULT_CONFIG = {
   date: {
-    defaultOffsetDays: 0,
+    // A century of workdays is about 26,000 steps, which is microseconds,
+    // and past any offset a person means. The walk is what these bound; see
+    // DateConfig above for why no other date offset needs a ceiling.
     maxOffsetYears: 100,
     minOffsetYears: -100,
     defaultFormat: "YYYY-MM-DD"
   },
-  dice: {
-    defaultSides: 6,
-    maxSides: 1e3,
-    maxDice: 100,
-    defaultDice: 1
-  },
   performance: {
     // Preserves the effective cache size the hardcoded (now-removed)
     // BYTECODE_CACHE_MAX_ENTRIES constant had, so wiring this field up
     // doesn't silently shrink the default cache for existing consumers.
     defaultCacheSize: 2e3,
-    maxDocumentLines: 1e4,
-    parseTimeoutMs: 5e3,
-    executionTimeoutMs: 1e4
+    // Raised from the 10,000 this field was declared with, which was never
+    // enforced and turned out to be under what this engine already supports:
+    // its paging design is tested against a 20,000-line document
+    // (`engine/PageManager.ts` and its spec) and its throughput benchmark
+    // parses a 50,000-line one. Twice the largest of those, and the same
+    // number `ConfigManager.validate()` already refuses to go above.
+    //
+    // Measured under a 256MB heap: setting a 100,000-line document costs
+    // 64MB, evaluating every line of a 20,000-line one costs 106MB, and
+    // 200,000 lines aborts the process before a single expression is looked
+    // at. A host with a small heap should lower this; the ceiling is here to
+    // stop the size that cannot work anywhere.
+    maxDocumentLines: 1e5
   },
   validation: {
     maxExpressionLength: 2e3,
@@ -39,7 +45,22 @@ var DEFAULT_CONFIG = {
   },
   vm: {
     maxStackDepth: 200,
-    maxInstructions: 5e4
+    maxInstructions: 5e4,
+    // Two orders of magnitude above anything a person types by hand (the
+    // longest range in the test suite is 1000 elements) and small enough
+    // that expanding it is measured in milliseconds rather than in whether
+    // the host survives.
+    maxCollectionSize: 1e5,
+    // Twenty times the single-collection ceiling above, so an expression may
+    // legitimately handle a number of large collections, and two hundred
+    // times below the allocation that took the process down.
+    maxAllocatedElements: 2e6,
+    // Six hundred times the largest call count any test or example makes
+    // (five levels of composition is sixteen calls), and small enough that
+    // the calls it does allow cost single-digit megabytes rather than the
+    // heap. A document that needs more than ten thousand calls on one line
+    // is doing something a calculator was not built for.
+    maxFunctionCalls: 1e4
   },
   worker: {
     maxConcurrentWorkers: 4,
@@ -55,7 +76,6 @@ var DEFAULT_CONFIG = {
 function mergeEngineConfig(base, override) {
   return {
     date: { ...base.date, ...override.date },
-    dice: { ...base.dice, ...override.dice },
     performance: { ...base.performance, ...override.performance },
     validation: { ...base.validation, ...override.validation },
     vm: { ...base.vm, ...override.vm },
@@ -80,7 +100,7 @@ var ConfigManager = class {
       if (current && typeof current === "object" && key in current) {
         current = current[key];
       } else {
-        throw chunkM4N5GA5Z_cjs.ErrorFactory.config(
+        throw chunk5KMIY374_cjs.ErrorFactory.config(
           "CONFIG_PATH_NOT_FOUND",
           `Configuration path not found: ${path}`,
           { path }
@@ -98,7 +118,7 @@ var ConfigManager = class {
   set(path, value) {
     const keys = path.split(".");
     if (keys.length < 2) {
-      throw chunkM4N5GA5Z_cjs.ErrorFactory.config(
+      throw chunk5KMIY374_cjs.ErrorFactory.config(
         "INVALID_CONFIG_PATH",
         `Invalid path: ${path}. Must be in format 'section.property'`,
         { path }
@@ -107,7 +127,7 @@ var ConfigManager = class {
     const section = keys[0];
     const property = keys[1];
     if (!(section in this.config)) {
-      throw chunkM4N5GA5Z_cjs.ErrorFactory.config(
+      throw chunk5KMIY374_cjs.ErrorFactory.config(
         "CONFIG_SECTION_NOT_FOUND",
         `Configuration section not found: ${section}`,
         { section, path }
@@ -117,7 +137,7 @@ var ConfigManager = class {
     if (sectionConfig && typeof sectionConfig === "object") {
       sectionConfig[property] = value;
     } else {
-      throw chunkM4N5GA5Z_cjs.ErrorFactory.config(
+      throw chunk5KMIY374_cjs.ErrorFactory.config(
         "CONFIG_PROPERTY_NOT_FOUND",
         `Configuration property not found: ${path}`,
         { path }
@@ -125,10 +145,15 @@ var ConfigManager = class {
     }
   }
   /**
-   * Get complete configuration
+   * Get complete configuration.
+   *
+   * A detached copy, section objects included. A top-level spread would hand
+   * the caller this manager's own section objects, so `getConfig().vm.x = 1`
+   * would be an undeclared back door into {@link set}, bypassing its path
+   * validation and reaching every later {@link get}.
    */
   getConfig() {
-    return { ...this.config };
+    return mergeEngineConfig(this.config, {});
   }
   /**
    * Update multiple configuration values
@@ -137,10 +162,19 @@ var ConfigManager = class {
     this.config = mergeEngineConfig(this.config, config);
   }
   /**
-   * Reset to default configuration
+   * Reset to default configuration.
+   *
+   * Goes through {@link mergeEngineConfig} for the same reason the constructor
+   * does. A top-level `{ ...DEFAULT_CONFIG }` copies the six section
+   * references, not the sections, so after a reset this manager's
+   * `performance` object WAS `DEFAULT_CONFIG.performance` and the next
+   * `set('performance.x', ...)` wrote into the module constant. That constant
+   * is what every `ExpressionEngine` is built from, so one manager's reset
+   * could change the cache size, instruction ceiling or allocation budget of
+   * every engine constructed later in the process.
    */
   reset() {
-    this.config = { ...DEFAULT_CONFIG };
+    this.config = mergeEngineConfig(DEFAULT_CONFIG, {});
   }
   /**
    * Validate configuration values
@@ -153,9 +187,6 @@ var ConfigManager = class {
     if (this.config.date.maxOffsetYears > 1e3) {
       errors.push("maxOffsetYears cannot exceed 1000");
     }
-    if (this.config.dice.maxSides > 1e4) {
-      errors.push("maxSides cannot exceed 10,000");
-    }
     return {
       valid: errors.length === 0,
       error: errors.join("; "),
@@ -168,5 +199,5 @@ exports.ConfigManager = ConfigManager;
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 exports.ENGINE_VERSION = ENGINE_VERSION;
 exports.mergeEngineConfig = mergeEngineConfig;
-//# sourceMappingURL=chunk-35IWNZPJ.cjs.map
-//# sourceMappingURL=chunk-35IWNZPJ.cjs.map
+//# sourceMappingURL=chunk-2XLQPQKI.cjs.map
+//# sourceMappingURL=chunk-2XLQPQKI.cjs.map

package/dist/chunk-2XLQPQKI.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../package.json","../src/constants/version.ts","../src/constants/Configuration.ts"],"names":["ErrorFactory"],"mappings":";;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,cAAA,GAAyB;;;ACsO/B,IAAM,cAAA,GAA+B;AAAA,EACzC,IAAA,EAAM;AAAA;AAAA;AAAA;AAAA,IAIJ,cAAA,EAAgB,GAAA;AAAA,IAChB,cAAA,EAAgB,IAAA;AAAA,IAChB,aAAA,EAAe;AAAA,GACjB;AAAA,EACA,WAAA,EAAa;AAAA;AAAA;AAAA;AAAA,IAIX,gBAAA,EAAkB,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAalB,gBAAA,EAAkB;AAAA,GACpB;AAAA,EACC,UAAA,EAAY;AAAA,IACV,mBAAA,EAAqB,GAAA;AAAA,IACrB,aAAA,EAAe,GAAA;AAAA,IACf,eAAA,EAAiB,EAAA;AAAA,IACjB,iBAAA,EAAmB;AAAA,GACrB;AAAA,EACA,EAAA,EAAI;AAAA,IACF,aAAA,EAAe,GAAA;AAAA,IACf,eAAA,EAAiB,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAKjB,iBAAA,EAAmB,GAAA;AAAA;AAAA;AAAA;AAAA,IAInB,oBAAA,EAAsB,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMtB,gBAAA,EAAkB;AAAA,GACpB;AAAA,EACA,MAAA,EAAQ;AAAA,IACN,oBAAA,EAAsB,CAAA;AAAA,IACtB,aAAA,EAAe,GAAA;AAAA,IACf,UAAA,EAAY,CAAA;AAAA,IACZ,aAAA,EAAe;AAAA,GACjB;AAAA,EACA,UAAA,EAAY;AAAA,IACV,OAAA,EAAS,KAAA;AAAA,IACT,cAAA,EAAgB;AAAA;AAEpB;AAiBK,SAAS,iBAAA,CACd,MACA,QAAA,EACc;AACd,EAAA,OAAO;AAAA,IACL,MAAM,EAAE,GAAG,KAAK,IAAA,EAAM,GAAG,SAAS,IAAA,EAAK;AAAA,IACvC,aAAa,EAAE,GAAG,KAAK,WAAA,EAAa,GAAG,SAAS,WAAA,EAAY;AAAA,IAC5D,YAAY,EAAE,GAAG,KAAK,UAAA,EAAY,GAAG,SAAS,UAAA,EAAW;AAAA,IACzD,IAAI,EAAE,GAAG,KAAK,EAAA,EAAI,GAAG,SAAS,EAAA,EAAG;AAAA,IACjC,QAAQ,EAAE,GAAG,KAAK,MAAA,EAAQ,GAAG,SAAS,MAAA,EAAO;AAAA,IAC7C,YAAY,EAAE,GAAG,KAAK,UAAA,EAAY,GAAG,SAAS,UAAA;AAAW,GAC3D;AACF;AAYO,IAAM,gBAAN,MAAoB;AAAA,EAGzB,WAAA,CAAY,MAAA,GAAgC,EAAC,EAAG;AAC9C,IAAA,IAAA,CAAK,MAAA,GAAS,iBAAA,CAAkB,cAAA,EAAgB,MAAM,CAAA;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAO,IAAA,EAAiB;AACtB,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA;AAC3B,IAAA,IAAI,UAAmB,IAAA,CAAK,MAAA;AAE5B,IAAA,KAAA,MAAW,OAAO,IAAA,EAAM;AACtB,MAAA,IAAI,OAAA,IAAW,OAAO,OAAA,KAAY,QAAA,IAAY,OAAO,OAAA,EAAS;AAC5D,QAAA,OAAA,GAAW,QAAoC,GAAG,CAAA;AAAA,MACpD,CAAA,MAAO;AACL,QAAA,MAAMA,8BAAA,CAAa,MAAA;AAAA,UACjB,uBAAA;AAAA,UACA,iCAAiC,IAAI,CAAA,CAAA;AAAA,UACrC,EAAE,IAAA;AAAK,SACT;AAAA,MACF;AAAA,IACF;AAEA,IAAA,OAAO,OAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,GAAA,CAAO,MAAc,KAAA,EAAgB;AACnC,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA;AAC3B,IAAA,IAAI,IAAA,CAAK,SAAS,CAAA,EAAG;AACnB,MAAA,MAAMA,8BAAA,CAAa,MAAA;AAAA,QACjB,qBAAA;AAAA,QACA,iBAAiB,IAAI,CAAA,sCAAA,CAAA;AAAA,QACrB,EAAE,IAAA;AAAK,OACT;AAAA,IACF;AAEA,IAAA,MAAM,OAAA,GAAU,KAAK,CAAC,CAAA;AACtB,IAAA,MAAM,QAAA,GAAW,KAAK,CAAC,CAAA;AAEvB,IAAA,IAAI,EAAE,OAAA,IAAW,IAAA,CAAK,MAAA,CAAA,EAAS;AAC7B,MAAA,MAAMA,8BAAA,CAAa,MAAA;AAAA,QACjB,0BAAA;AAAA,QACA,oCAAoC,OAAO,CAAA,CAAA;AAAA,QAC3C,EAAE,SAAS,IAAA;AAAK,OAClB;AAAA,IACF;AAEA,IAAA,MAAM,aAAA,GAAgB,IAAA,CAAK,MAAA,CAAO,OAA6B,CAAA;AAC/D,IAAA,IAAI,aAAA,IAAiB,OAAO,aAAA,KAAkB,QAAA,EAAU;AACtD,MAAC,aAAA,CAAqD,QAAQ,CAAA,GAAI,KAAA;AAAA,IACpE,CAAA,MAAO;AACL,MAAA,MAAMA,8BAAA,CAAa,MAAA;AAAA,QACjB,2BAAA;AAAA,QACA,qCAAqC,IAAI,CAAA,CAAA;AAAA,QACzC,EAAE,IAAA;AAAK,OACT;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,SAAA,GAA0B;AACxB,IAAA,OAAO,iBAAA,CAAkB,IAAA,CAAK,MAAA,EAAQ,EAAE,CAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,MAAA,EAAqC;AAC1C,IAAA,IAAA,CAAK,MAAA,GAAS,iBAAA,CAAkB,IAAA,CAAK,MAAA,EAAQ,MAAM,CAAA;AAAA,EACrD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,KAAA,GAAc;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,iBAAA,CAAkB,cAAA,EAAgB,EAAE,CAAA;AAAA,EACpD;AAAA;AAAA;AAAA;AAAA,EAKA,QAAA,GAA6B;AAC3B,IAAA,MAAM,SAAmB,EAAC;AAG1B,IAAA,IAAI,IAAA,CAAK,MAAA,CAAO,WAAA,CAAY,gBAAA,GAAmB,GAAA,EAAQ;AACrD,MAAA,MAAA,CAAO,KAAK,wCAAwC,CAAA;AAAA,IACtD;AAGA,IAAA,IAAI,IAAA,CAAK,MAAA,CAAO,IAAA,CAAK,cAAA,GAAiB,GAAA,EAAM;AAC1C,MAAA,MAAA,CAAO,KAAK,mCAAmC,CAAA;AAAA,IACjD;AAEA,IAAA,OAAO;AAAA,MACL,KAAA,EAAO,OAAO,MAAA,KAAW,CAAA;AAAA,MACzB,KAAA,EAAO,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA;AAAA,MACvB,UAAU;AAAC,KACb;AAAA,EACF;AACF","file":"chunk-2XLQPQKI.cjs","sourcesContent":["{\n  \"name\": \"solve-engine\",\n  \"version\": \"1.0.1\",\n  \"description\": \"An embeddable expression engine for natural-language calculations: units, currencies, percentages, dates and matrices, with the parsing and evaluation plumbing already built.\",\n  \"keywords\": [\n    \"expression-evaluator\",\n    \"calculator\",\n    \"bytecode-vm\",\n    \"parser\",\n    \"lexer\",\n    \"dsl\",\n    \"markdown\",\n    \"obsidian\"\n  ],\n  \"license\": \"MIT\",\n  \"author\": \"Liam Riddell\",\n  \"homepage\": \"https://liamriddell.github.io/solve-engine/\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/LiamRiddell/solve-engine.git\",\n    \"directory\": \"packages/engine\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/LiamRiddell/solve-engine/issues\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"type\": \"module\",\n  \"engines\": {\n    \"node\": \">=22\"\n  },\n  \"files\": [\n    \"dist\",\n    \"LICENSE\"\n  ],\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"import\": {\n        \"types\": \"./dist/index.d.ts\",\n        \"default\": \"./dist/index.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/index.d.cts\",\n        \"default\": \"./dist/index.cjs\"\n      }\n    },\n    \"./engine\": {\n      \"import\": {\n        \"types\": \"./dist/engine.d.ts\",\n        \"default\": \"./dist/engine.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/engine.d.cts\",\n        \"default\": \"./dist/engine.cjs\"\n      }\n    },\n    \"./vm\": {\n      \"import\": {\n        \"types\": \"./dist/vm.d.ts\",\n        \"default\": \"./dist/vm.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/vm.d.cts\",\n        \"default\": \"./dist/vm.cjs\"\n      }\n    },\n    \"./format\": {\n      \"import\": {\n        \"types\": \"./dist/format.d.ts\",\n        \"default\": \"./dist/format.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/format.d.cts\",\n        \"default\": \"./dist/format.cjs\"\n      }\n    },\n    \"./language\": {\n      \"import\": {\n        \"types\": \"./dist/language.d.ts\",\n        \"default\": \"./dist/language.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/language.d.cts\",\n        \"default\": \"./dist/language.cjs\"\n      }\n    },\n    \"./packages\": {\n      \"import\": {\n        \"types\": \"./dist/packages.d.ts\",\n        \"default\": \"./dist/packages.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/packages.d.cts\",\n        \"default\": \"./dist/packages.cjs\"\n      }\n    },\n    \"./constants\": {\n      \"import\": {\n        \"types\": \"./dist/constants.d.ts\",\n        \"default\": \"./dist/constants.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/constants.d.cts\",\n        \"default\": \"./dist/constants.cjs\"\n      }\n    },\n    \"./lexer\": {\n      \"import\": {\n        \"types\": \"./dist/lexer.d.ts\",\n        \"default\": \"./dist/lexer.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/lexer.d.cts\",\n        \"default\": \"./dist/lexer.cjs\"\n      }\n    },\n    \"./parser\": {\n      \"import\": {\n        \"types\": \"./dist/parser.d.ts\",\n        \"default\": \"./dist/parser.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/parser.d.cts\",\n        \"default\": \"./dist/parser.cjs\"\n      }\n    },\n    \"./normalizer\": {\n      \"import\": {\n        \"types\": \"./dist/normalizer.d.ts\",\n        \"default\": \"./dist/normalizer.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/normalizer.d.cts\",\n        \"default\": \"./dist/normalizer.cjs\"\n      }\n    },\n    \"./variables\": {\n      \"import\": {\n        \"types\": \"./dist/variables.d.ts\",\n        \"default\": \"./dist/variables.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/variables.d.cts\",\n        \"default\": \"./dist/variables.cjs\"\n      }\n    },\n    \"./resolvers\": {\n      \"import\": {\n        \"types\": \"./dist/resolvers.d.ts\",\n        \"default\": \"./dist/resolvers.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/resolvers.d.cts\",\n        \"default\": \"./dist/resolvers.cjs\"\n      }\n    },\n    \"./errors\": {\n      \"import\": {\n        \"types\": \"./dist/errors.d.ts\",\n        \"default\": \"./dist/errors.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/errors.d.cts\",\n        \"default\": \"./dist/errors.cjs\"\n      }\n    },\n    \"./utilities\": {\n      \"import\": {\n        \"types\": \"./dist/utilities.d.ts\",\n        \"default\": \"./dist/utilities.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/utilities.d.cts\",\n        \"default\": \"./dist/utilities.cjs\"\n      }\n    },\n    \"./uom\": {\n      \"import\": {\n        \"types\": \"./dist/uom.d.ts\",\n        \"default\": \"./dist/uom.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/uom.d.cts\",\n        \"default\": \"./dist/uom.cjs\"\n      }\n    },\n    \"./services\": {\n      \"import\": {\n        \"types\": \"./dist/services.d.ts\",\n        \"default\": \"./dist/services.js\"\n      },\n      \"require\": {\n        \"types\": \"./dist/services.d.cts\",\n        \"default\": \"./dist/services.cjs\"\n      }\n    }\n  },\n  \"scripts\": {\n    \"build\": \"tsup\",\n    \"prepublishOnly\": \"npm run build && node ../../scripts/assert-publishable.mjs .\",\n    \"dev\": \"tsup --watch\",\n    \"test\": \"jest --config jest.config.cjs --no-coverage\",\n    \"typecheck\": \"tsgo --noEmit --skipLibCheck\",\n    \"typecheck:tsc\": \"tsc --noEmit --skipLibCheck\"\n  },\n  \"dependencies\": {\n    \"@tanstack/query-core\": \"^5.100.10\"\n  },\n  \"devDependencies\": {\n    \"@jest/globals\": \"^30.4.1\",\n    \"@types/node\": \"^26.2.0\",\n    \"@types/semver\": \"^7.5.0\",\n    \"convert\": \"^7.0.0\",\n    \"jest\": \"^30.4.2\",\n    \"semver\": \"^7.6.0\",\n    \"ts-jest\": \"^29.4.12\",\n    \"tsup\": \"8.5.1\",\n    \"typescript\": \"5.9.3\"\n  },\n  \"//sideEffects\": \"Load-bearing claim, not boilerplate. tsup's splitting emits bare chunk imports at the top of dist/index.js, and this field tells Rollup, webpack and Vite they may delete them, which esbuild reports as [ignored-bare-import] once per import during `npm run size`. The engine does have module-level work to lose: registerAllTokenTypes(), _PrecedenceParser.BP_TABLE and its cached token ids, and several process-wide registries. It is safe because every chunk doing that work is also imported for its bindings somewhere, so no bundler can drop it. That is a property of how tsup currently splits the code rather than a design guarantee, so `npm run smoke:bundled` (scripts/check-tree-shaking.mjs) proves it on every run of `npm run verify` instead of assuming it, and its header explains the two fixes if it ever stops holding.\",\n  \"sideEffects\": false\n}\n","/**\n * The running engine's own semver version, sourced directly from this\n * package's package.json so it can never drift from what's actually\n * published. Exists so IEnginePackage.engineVersion range checks\n * (api/EngineVersionCompatibility.ts) have something real to check\n * against.\n */\nimport { version } from \"../../package.json\";\n\n/**\n * The running engine's version, taken from package.json.\n *\n * What a package's `engineVersion` range is checked against at registration.\n * A prerelease is compared by its coerced release version, so a 1.0.0 beta\n * satisfies `^1.0.0`. See `api/EngineVersionCompatibility.ts`.\n */\nexport const ENGINE_VERSION: string = version;\n","/**\n * Configuration Module for solve-js Engine\n * \n * This module provides the **single source of truth** for all engine configuration.\n * Every configurable aspect of the engine, from safety limits and performance\n * budgets to VM constraints and worker pool sizing, is defined here.\n * \n * ### Design principles\n * \n * 1. **Engine owns its config.** The engine defines its own config shape and defaults.\n *    Consumers (e.g., the Obsidian plugin) pass partial overrides; all unspecified\n *    fields fall back to `DEFAULT_CONFIG`.\n * \n * 2. **Self-documenting.** Every interface and field has descriptive JSDoc so the\n *    config is understandable at a glance, whether you're using the engine as an\n *    npm package or reading the source.\n * \n * 3. **Minimal consumer knowledge.** Consumers only need to pass `Partial<EngineConfig>`.\n *    They don't need to replicate the full config shape, just the fields they\n *    want to override.\n * \n * @module Configuration\n */\n\nimport { ErrorFactory } from \"@solve-js/errors/UnifiedErrorFramework\";\n\n/**\n * Date-related configuration.\n * Controls the bounds and formatting for date/time expression evaluation\n * (e.g., `today + 20 days`, `last monday`).\n */\nexport interface DateConfig {\n  /**\n   * How far forward a date offset whose COST grows with the offset may reach,\n   * in years. Enforced by `vm/VM.ts`'s `addBusinessDays()`.\n   *\n   * Bounds the walk, not the calendar. Every other date offset in the engine\n   * is arithmetic on a Date field, so `today + 100000 days` costs exactly what\n   * one day costs and needs no ceiling; workdays are the one offset that has\n   * to step day by day, because which days are skipped depends on where each\n   * step lands. `today + 100000000 workdays` therefore froze the host for\n   * thirteen seconds inside a single ADD opcode (where `vm.maxInstructions`\n   * cannot see it) and then answered \"Invalid Date\", and a trillion never\n   * returned at all.\n   *\n   * Release hardening: this field was declared, documented as a \"safety\n   * limit\", and read nowhere, so it bounded nothing. A limit a host can\n   * configure and the engine ignores is worse than no limit, because it reads\n   * as protection that is not there.\n   */\n  readonly maxOffsetYears: number;\n  /** How far BACK the same walk may reach, in years, as a negative number. See {@link maxOffsetYears}. */\n  readonly minOffsetYears: number;\n  /** Default date string format for display (moment.js format string) */\n  readonly defaultFormat: string;\n}\n\n/**\n * Performance-related configuration.\n * Controls caching, timeouts, and processing limits to prevent runaway\n * resource consumption on large documents.\n */\nexport interface PerformanceConfig {\n  /**\n   * Maximum number of entries in {@link ExpressionEngine}'s bytecode cache\n   * (per-instance, keyed by expression text) before the oldest entry is\n   * evicted. Raise this for documents with many distinct expressions if\n   * repeated re-evaluation (e.g. scrolling) is re-parsing instead of\n   * hitting cache, bug fix (release hardening pass): this field used to\n   * be read nowhere; the cache size was a hardcoded, unconfigurable\n   * constant. Note this does NOT bound {@link LineCache}, which has no\n   * size limit of its own.\n   */\n  readonly defaultCacheSize: number;\n  /**\n   * Maximum lines a document may have for the engine to process it in one\n   * pass. Enforced by `ExpressionEngine.parseDocument()` and by\n   * `engine/DocumentModel.ts`'s `setDocument()`, the two entry points that\n   * take a whole document.\n   *\n   * A document costs memory per line whatever each line says: a parsed line\n   * record, a cache entry, a dependency-graph node. Two hundred thousand\n   * lines of `1 + 1` therefore exhausted the heap and aborted the process\n   * before any per-line limit had anything to object to, which is the same\n   * shape of hole as an unbounded expression and needs the same kind of\n   * ceiling. Refusing the document names the limit; a host that genuinely has\n   * a larger one raises this field.\n   *\n   * Release hardening: declared and read nowhere until now.\n   */\n  readonly maxDocumentLines: number;\n}\n\n/**\n * Validation / safety-limit configuration.\n * Protects against runaway expressions that could cause excessive memory use\n * or stack overflow. These limits are checked during lexing and parsing.\n */\n/** Bounds on untrusted input: expression length and nesting depth. */\nexport interface ValidationConfig {\n  /** Maximum expression length in characters. Prevents excessively long strings from entering the pipeline. */\n  readonly maxExpressionLength: number;\n  /** Maximum expression complexity score (`tokens + functionCalls×5 + nestingDepth×10`). Protects against deeply nested or combinatorially complex expressions. */\n  readonly maxComplexity: number;\n  /** Maximum parentheses nesting depth. Prevents stack overflow in the recursive-descent parser. */\n  readonly maxNestingDepth: number;\n  /**\n   * Auto-balance unmatched parentheses by appending missing closing parens\n   * or prepending missing opening parens. When disabled, unbalanced expressions\n   * cause parse errors instead of being silently corrected.\n   *\n   * Disabled by default for strict parsing. Enable for forgiving user input\n   * (e.g., chat-style calculators where users often omit closing parens).\n   * Has zero overhead when disabled, the O(n) paren-count scan is skipped.\n   */\n  readonly autoBalanceParens: boolean;\n}\n\n/**\n * Worker pool configuration.\n * Controls the parallel execution workers used for batch evaluation.\n */\nexport interface WorkerConfig {\n  /** Maximum number of concurrent Web Workers allowed */\n  readonly maxConcurrentWorkers: number;\n  /** Time (ms) a worker stays alive while idle before being terminated */\n  readonly idleTimeoutMs: number;\n  /** Maximum retry attempts for a failed worker operation */\n  readonly maxRetries: number;\n  /** Base backoff delay (ms) between retries (exponential backoff applied on top) */\n  readonly baseBackoffMs: number;\n}  /**\n   * Diagnostic / telemetry configuration.\n   * Controls the diagnostic event pipeline for profiling and debugging.\n   * All diagnostics are disabled by default for maximum production performance.\n   */\n  export interface DiagnosticConfig {\n    /** Master switch: enable the diagnostic pipeline (collectors receive events for all pipeline stages) */\n    readonly enabled: boolean;\n    /** Enable VM trace mode, emits per-opcode execution events (very verbose; disables some optimizations) */\n    readonly vmTraceEnabled: boolean;\n  }\n\n  /**\n   * Virtual Machine configuration.\n   * Controls the internal bytecode VM that executes compiled expressions.\n   */\n  export interface VMConfig {\n    /** Maximum stack depth (value slots) for VM execution, prevents stack overflow in recursive/pratt-parser generated bytecode */\n    readonly maxStackDepth: number;\n    /** Maximum opcodes executed per expression, halts runaway infinite loops */\n    readonly maxInstructions: number;\n    /**\n     * Maximum elements a collection may be expanded to before `map`/`reduce`/\n     * `sum`/`prod` will iterate it.\n     *\n     * A Range is stored as its two bounds and costs nothing until something\n     * materializes it, at which point it becomes one Value per element. Twenty\n     * characters (`sum(x, 1:100000000)`) therefore asked for a hundred million\n     * of them, and neither `maxInstructions` nor `maxStackDepth` could see it:\n     * the expansion happens inside a single opcode, so the instruction counter\n     * is never consulted while it runs, and the elements never reach the value\n     * stack. V8 aborted the whole process with \"Reached heap limit\", which a\n     * host embedding the engine cannot catch.\n     */\n    readonly maxCollectionSize: number;\n    /**\n     * Maximum elements (collection Values, matrix cells) one evaluation may\n     * materialize in total.\n     *\n     * `maxCollectionSize` above bounds a single collection. This bounds the sum\n     * of everything an expression asks for, which is a different question and\n     * the one that actually protects the host: two collections that are\n     * individually legal are legal together, and an operation whose result is\n     * the PRODUCT of two legal operands is bounded by neither of them. A matrix\n     * multiply is exactly that shape, so three lines within every other limit\n     * (`:a = map(1*x, 0:20000)`, `:b = transpose(a)`, `b * a`) asked for four\n     * hundred million cells and aborted the process.\n     *\n     * Counted in elements rather than bytes, because a count is what a call\n     * site has before it allocates. An element is 8 bytes as a numeric matrix\n     * cell and closer to a hundred as a full Value, so the default is worth\n     * roughly 16 MB of matrix or 200 MB of expanded collection: far past any\n     * document and far short of what an editor cannot survive.\n     */\n    readonly maxAllocatedElements: number;\n    /**\n     * Maximum user-defined-function calls one evaluation may make in TOTAL,\n     * however deeply or widely they nest.\n     *\n     * `maxFunctionRecursionDepth` bounds how DEEP calls nest and cannot see\n     * how MANY there are, and those are different numbers. Twenty-two lines of\n     * `f(n)(v) = f(n-1)(v) + f(n-1)(v)` reach a depth of only 22 against a\n     * limit of 50, and make 2,097,152 calls doing it: a fatal heap abort in\n     * under a second. `maxInstructions` cannot bound it either, because\n     * `executeBytecode()` re-enters itself per call and each reentrant call\n     * gets its OWN instruction count, so recursion refreshes its allowance on\n     * the way in. This is the tally that does not refresh; see\n     * `vm/AllocationBudget.ts`, which holds it for the same reason it holds\n     * the element tally.\n     *\n     * Counted in calls rather than in the instructions they run, because the\n     * call is the thing that multiplies: every call allocates a frame, its\n     * arguments and its result whatever its body says.\n     */\n    readonly maxFunctionCalls: number;\n  }\n\n/**\n * Complete engine configuration.\n *\n * Every field has a default in `DEFAULT_CONFIG`. To customize, pass a\n * `Partial<EngineConfig>` when constructing `ExpressionEngine`. Only the\n * sections/fields you supply are overridden; all others use their defaults.\n *\n * @example\n * ```typescript\n * import { ExpressionEngine } from \"solve-js\";\n *\n * const engine = new ExpressionEngine(\"en\", false, {\n *   validation: {\n *     maxExpressionLength: 1000,\n *     maxComplexity: 200,\n *   },\n *   // date, performance, vm, worker, diagnostic all use defaults\n * });\n * ```\n */\nexport interface EngineConfig {\n    /** Date/time expression evaluation bounds and formatting */\n    readonly date: DateConfig;\n    /** Performance budgets and cache sizing */\n    readonly performance: PerformanceConfig;\n    /** Safety limits for expression complexity */\n    readonly validation: ValidationConfig;\n    /** Internal bytecode VM configuration */\n    readonly vm: VMConfig;\n    /** Parallel worker pool configuration */\n    readonly worker: WorkerConfig;\n    /** Diagnostic pipeline configuration */\n    readonly diagnostic: DiagnosticConfig;\n  }\n\n/**\n * Default configuration values\n */\nexport const DEFAULT_CONFIG: EngineConfig = {\n   date: {\n     // A century of workdays is about 26,000 steps, which is microseconds,\n     // and past any offset a person means. The walk is what these bound; see\n     // DateConfig above for why no other date offset needs a ceiling.\n     maxOffsetYears: 100,\n     minOffsetYears: -100,\n     defaultFormat: 'YYYY-MM-DD'\n   },\n   performance: {\n     // Preserves the effective cache size the hardcoded (now-removed)\n     // BYTECODE_CACHE_MAX_ENTRIES constant had, so wiring this field up\n     // doesn't silently shrink the default cache for existing consumers.\n     defaultCacheSize: 2000,\n     // Raised from the 10,000 this field was declared with, which was never\n     // enforced and turned out to be under what this engine already supports:\n     // its paging design is tested against a 20,000-line document\n     // (`engine/PageManager.ts` and its spec) and its throughput benchmark\n     // parses a 50,000-line one. Twice the largest of those, and the same\n     // number `ConfigManager.validate()` already refuses to go above.\n     //\n     // Measured under a 256MB heap: setting a 100,000-line document costs\n     // 64MB, evaluating every line of a 20,000-line one costs 106MB, and\n     // 200,000 lines aborts the process before a single expression is looked\n     // at. A host with a small heap should lower this; the ceiling is here to\n     // stop the size that cannot work anywhere.\n     maxDocumentLines: 100000,\n   },\n    validation: {\n      maxExpressionLength: 2000,\n      maxComplexity: 500,\n      maxNestingDepth: 50,\n      autoBalanceParens: false,\n    },\n    vm: {\n      maxStackDepth: 200,\n      maxInstructions: 50000,\n      // Two orders of magnitude above anything a person types by hand (the\n      // longest range in the test suite is 1000 elements) and small enough\n      // that expanding it is measured in milliseconds rather than in whether\n      // the host survives.\n      maxCollectionSize: 100000,\n      // Twenty times the single-collection ceiling above, so an expression may\n      // legitimately handle a number of large collections, and two hundred\n      // times below the allocation that took the process down.\n      maxAllocatedElements: 2000000,\n      // Six hundred times the largest call count any test or example makes\n      // (five levels of composition is sixteen calls), and small enough that\n      // the calls it does allow cost single-digit megabytes rather than the\n      // heap. A document that needs more than ten thousand calls on one line\n      // is doing something a calculator was not built for.\n      maxFunctionCalls: 10000,\n    },\n    worker: {\n      maxConcurrentWorkers: 4,\n      idleTimeoutMs: 30000,\n      maxRetries: 3,\n      baseBackoffMs: 1000,\n    },\n    diagnostic: {\n      enabled: false,\n      vmTraceEnabled: false,\n    },\n  };\n\n/**\n * Merge a partial config override onto a base `EngineConfig`, section by\n * section, `{ ...base.section, ...override.section }` for each of the 7\n * top-level sections, not a single top-level spread.\n *\n * A shallow `{ ...base, ...override }` at the TOP level replaces an entire\n * section wholesale the moment a caller overrides even one field in it\n * (e.g. `{ performance: { defaultCacheSize: 500 } }` would silently drop\n * every other `performance.*` field back to `undefined`, not to its\n * default). This function exists specifically so every config consumer\n * shares one correct merge instead of each hand-rolling (and risking) its\n * own. `ConfigManager` and `ExpressionEngine` both call this rather than\n * either duplicating the section list or instantiating a whole\n * `ConfigManager` just to reuse its private merge logic.\n */\nexport function mergeEngineConfig(\n  base: EngineConfig,\n  override: Partial<EngineConfig>\n): EngineConfig {\n  return {\n    date: { ...base.date, ...override.date },\n    performance: { ...base.performance, ...override.performance },\n    validation: { ...base.validation, ...override.validation },\n    vm: { ...base.vm, ...override.vm },\n    worker: { ...base.worker, ...override.worker },\n    diagnostic: { ...base.diagnostic, ...override.diagnostic },\n  };\n}\n\n/**\n * Configuration manager for engine settings\n *\n * @example\n * ```typescript\n * const configManager = new ConfigManager();\n * configManager.set('performance.defaultCacheSize', 2000);\n * const cacheSize = configManager.get('performance.defaultCacheSize');\n * ```\n */\nexport class ConfigManager {\n  private config: EngineConfig;\n\n  constructor(config: Partial<EngineConfig> = {}) {\n    this.config = mergeEngineConfig(DEFAULT_CONFIG, config);\n  }\n\n  /**\n   * Get configuration value by path\n   * \n   * @param path - Dot-notation path to config value\n   * @returns Configuration value\n   */\n  get<T>(path: string): T {\n    const keys = path.split('.');\n    let current: unknown = this.config;\n\n    for (const key of keys) {\n      if (current && typeof current === 'object' && key in current) {\n        current = (current as Record<string, unknown>)[key];\n      } else {\n        throw ErrorFactory.config(\n          \"CONFIG_PATH_NOT_FOUND\",\n          `Configuration path not found: ${path}`,\n          { path }\n        );\n      }\n    }\n\n    return current as T;\n  }\n\n  /**\n   * Set configuration value by path\n   * \n   * @param path - Dot-notation path to config value\n   * @param value - New value\n   */\n  set<T>(path: string, value: T): void {\n    const keys = path.split('.');\n    if (keys.length < 2) {\n      throw ErrorFactory.config(\n        \"INVALID_CONFIG_PATH\",\n        `Invalid path: ${path}. Must be in format 'section.property'`,\n        { path }\n      );\n    }\n    \n    const section = keys[0];\n    const property = keys[1];\n    \n    if (!(section in this.config)) {\n      throw ErrorFactory.config(\n        \"CONFIG_SECTION_NOT_FOUND\",\n        `Configuration section not found: ${section}`,\n        { section, path }\n      );\n    }\n    \n    const sectionConfig = this.config[section as keyof EngineConfig];\n    if (sectionConfig && typeof sectionConfig === 'object') {\n      (sectionConfig as unknown as Record<string, unknown>)[property] = value;\n    } else {\n      throw ErrorFactory.config(\n        \"CONFIG_PROPERTY_NOT_FOUND\",\n        `Configuration property not found: ${path}`,\n        { path }\n      );\n    }\n  }\n\n  /**\n   * Get complete configuration.\n   *\n   * A detached copy, section objects included. A top-level spread would hand\n   * the caller this manager's own section objects, so `getConfig().vm.x = 1`\n   * would be an undeclared back door into {@link set}, bypassing its path\n   * validation and reaching every later {@link get}.\n   */\n  getConfig(): EngineConfig {\n    return mergeEngineConfig(this.config, {});\n  }\n\n  /**\n   * Update multiple configuration values\n   */\n  update(config: Partial<EngineConfig>): void {\n    this.config = mergeEngineConfig(this.config, config);\n  }\n\n  /**\n   * Reset to default configuration.\n   *\n   * Goes through {@link mergeEngineConfig} for the same reason the constructor\n   * does. A top-level `{ ...DEFAULT_CONFIG }` copies the six section\n   * references, not the sections, so after a reset this manager's\n   * `performance` object WAS `DEFAULT_CONFIG.performance` and the next\n   * `set('performance.x', ...)` wrote into the module constant. That constant\n   * is what every `ExpressionEngine` is built from, so one manager's reset\n   * could change the cache size, instruction ceiling or allocation budget of\n   * every engine constructed later in the process.\n   */\n  reset(): void {\n    this.config = mergeEngineConfig(DEFAULT_CONFIG, {});\n  }\n\n  /**\n   * Validate configuration values\n   */\n  validate(): ValidationResult {\n    const errors: string[] = [];\n\n    // Validate performance config\n    if (this.config.performance.maxDocumentLines > 100000) {\n      errors.push('maxDocumentLines cannot exceed 100,000');\n    }\n\n    // Validate date config\n    if (this.config.date.maxOffsetYears > 1000) {\n      errors.push('maxOffsetYears cannot exceed 1000');\n    }\n\n    return {\n      valid: errors.length === 0,\n      error: errors.join('; '),\n      warnings: []\n    };\n  }\n}\n\n/**\n * Result type for {@link ConfigManager.validate}.\n */\nexport interface ValidationResult {\n  valid: boolean;\n  error?: string;\n  warnings?: string[];\n}\n\n"]}