solve-engine 1.0.0-beta.7 → 1.0.0

package/dist/{BytecodeBuilder-3egMyuDi.d.cts → BytecodeBuilder-B0xskcv5.d.cts}

@@ -87,7 +87,8 @@ declare enum OpCode {
     MAT_SLICE = 155,// (matrix, rowRange, colRange already on stack) -> sub-matrix via two Range values
     RANGE_NEW = 156,// (min, max already on stack) -> push a Range value `min:max`
     MAP_INVOKE = 157,// map(...) — see parser/BytecodeBuilder.ts's `anonymousBodies` side-table
-    REDUCE_INVOKE = 158
+    REDUCE_INVOKE = 158,// reduce(...) — same anonymousBodies mechanism as MAP_INVOKE
+    BIND_UNKNOWN = 159
 }
 /**
  * Gets the name of an OpCode as a string.

package/dist/{BytecodeBuilder-3egMyuDi.d.ts → BytecodeBuilder-B0xskcv5.d.ts}

@@ -87,7 +87,8 @@ declare enum OpCode {
     MAT_SLICE = 155,// (matrix, rowRange, colRange already on stack) -> sub-matrix via two Range values
     RANGE_NEW = 156,// (min, max already on stack) -> push a Range value `min:max`
     MAP_INVOKE = 157,// map(...) — see parser/BytecodeBuilder.ts's `anonymousBodies` side-table
-    REDUCE_INVOKE = 158
+    REDUCE_INVOKE = 158,// reduce(...) — same anonymousBodies mechanism as MAP_INVOKE
+    BIND_UNKNOWN = 159
 }
 /**
  * Gets the name of an OpCode as a string.

package/dist/{Configuration-fVpd-HC-.d.cts → Configuration-B-G5gTRn.d.cts}

@@ -27,29 +27,30 @@
  * (e.g., `today + 20 days`, `last monday`).
  */
 interface DateConfig {
-    /** Default offset in days for relative date calculations when no offset is specified */
-    readonly defaultOffsetDays: number;
-    /** Maximum allowed positive offset in years (safety limit) */
+    /**
+     * How far forward a date offset whose COST grows with the offset may reach,
+     * in years. Enforced by `vm/VM.ts`'s `addBusinessDays()`.
+     *
+     * Bounds the walk, not the calendar. Every other date offset in the engine
+     * is arithmetic on a Date field, so `today + 100000 days` costs exactly what
+     * one day costs and needs no ceiling; workdays are the one offset that has
+     * to step day by day, because which days are skipped depends on where each
+     * step lands. `today + 100000000 workdays` therefore froze the host for
+     * thirteen seconds inside a single ADD opcode (where `vm.maxInstructions`
+     * cannot see it) and then answered "Invalid Date", and a trillion never
+     * returned at all.
+     *
+     * Release hardening: this field was declared, documented as a "safety
+     * limit", and read nowhere, so it bounded nothing. A limit a host can
+     * configure and the engine ignores is worse than no limit, because it reads
+     * as protection that is not there.
+     */
     readonly maxOffsetYears: number;
-    /** Maximum allowed negative offset in years (safety limit) */
+    /** How far BACK the same walk may reach, in years, as a negative number. See {@link maxOffsetYears}. */
     readonly minOffsetYears: number;
     /** Default date string format for display (moment.js format string) */
     readonly defaultFormat: string;
 }
-/**
- * Dice-related configuration.
- * Controls dice expression evaluation (e.g., `roll(1, 100)`, `3d6`).
- */
-interface DiceConfig {
-    /** Default number of sides on a die when not specified */
-    readonly defaultSides: number;
-    /** Maximum allowed sides per die (prevents excessive allocation) */
-    readonly maxSides: number;
-    /** Maximum number of dice in a single roll expression */
-    readonly maxDice: number;
-    /** Default number of dice when not specified */
-    readonly defaultDice: number;
-}
 /**
  * Performance-related configuration.
  * Controls caching, timeouts, and processing limits to prevent runaway
@@ -67,12 +68,23 @@ interface PerformanceConfig {
      * size limit of its own.
      */
     readonly defaultCacheSize: number;
-    /** Maximum number of document lines processed in a single pass */
+    /**
+     * Maximum lines a document may have for the engine to process it in one
+     * pass. Enforced by `ExpressionEngine.parseDocument()` and by
+     * `engine/DocumentModel.ts`'s `setDocument()`, the two entry points that
+     * take a whole document.
+     *
+     * A document costs memory per line whatever each line says: a parsed line
+     * record, a cache entry, a dependency-graph node. Two hundred thousand
+     * lines of `1 + 1` therefore exhausted the heap and aborted the process
+     * before any per-line limit had anything to object to, which is the same
+     * shape of hole as an unbounded expression and needs the same kind of
+     * ceiling. Refusing the document names the limit; a host that genuinely has
+     * a larger one raises this field.
+     *
+     * Release hardening: declared and read nowhere until now.
+     */
     readonly maxDocumentLines: number;
-    /** Maximum time (ms) allowed for parsing a single expression before timeout */
-    readonly parseTimeoutMs: number;
-    /** Maximum time (ms) allowed for executing a single expression before timeout */
-    readonly executionTimeoutMs: number;
 }
 /**
  * Validation / safety-limit configuration.
@@ -131,6 +143,60 @@ interface VMConfig {
     readonly maxStackDepth: number;
     /** Maximum opcodes executed per expression, halts runaway infinite loops */
     readonly maxInstructions: number;
+    /**
+     * Maximum elements a collection may be expanded to before `map`/`reduce`/
+     * `sum`/`prod` will iterate it.
+     *
+     * A Range is stored as its two bounds and costs nothing until something
+     * materializes it, at which point it becomes one Value per element. Twenty
+     * characters (`sum(x, 1:100000000)`) therefore asked for a hundred million
+     * of them, and neither `maxInstructions` nor `maxStackDepth` could see it:
+     * the expansion happens inside a single opcode, so the instruction counter
+     * is never consulted while it runs, and the elements never reach the value
+     * stack. V8 aborted the whole process with "Reached heap limit", which a
+     * host embedding the engine cannot catch.
+     */
+    readonly maxCollectionSize: number;
+    /**
+     * Maximum elements (collection Values, matrix cells) one evaluation may
+     * materialize in total.
+     *
+     * `maxCollectionSize` above bounds a single collection. This bounds the sum
+     * of everything an expression asks for, which is a different question and
+     * the one that actually protects the host: two collections that are
+     * individually legal are legal together, and an operation whose result is
+     * the PRODUCT of two legal operands is bounded by neither of them. A matrix
+     * multiply is exactly that shape, so three lines within every other limit
+     * (`:a = map(1*x, 0:20000)`, `:b = transpose(a)`, `b * a`) asked for four
+     * hundred million cells and aborted the process.
+     *
+     * Counted in elements rather than bytes, because a count is what a call
+     * site has before it allocates. An element is 8 bytes as a numeric matrix
+     * cell and closer to a hundred as a full Value, so the default is worth
+     * roughly 16 MB of matrix or 200 MB of expanded collection: far past any
+     * document and far short of what an editor cannot survive.
+     */
+    readonly maxAllocatedElements: number;
+    /**
+     * Maximum user-defined-function calls one evaluation may make in TOTAL,
+     * however deeply or widely they nest.
+     *
+     * `maxFunctionRecursionDepth` bounds how DEEP calls nest and cannot see
+     * how MANY there are, and those are different numbers. Twenty-two lines of
+     * `f(n)(v) = f(n-1)(v) + f(n-1)(v)` reach a depth of only 22 against a
+     * limit of 50, and make 2,097,152 calls doing it: a fatal heap abort in
+     * under a second. `maxInstructions` cannot bound it either, because
+     * `executeBytecode()` re-enters itself per call and each reentrant call
+     * gets its OWN instruction count, so recursion refreshes its allowance on
+     * the way in. This is the tally that does not refresh; see
+     * `vm/AllocationBudget.ts`, which holds it for the same reason it holds
+     * the element tally.
+     *
+     * Counted in calls rather than in the instructions they run, because the
+     * call is the thing that multiplies: every call allocates a frame, its
+     * arguments and its result whatever its body says.
+     */
+    readonly maxFunctionCalls: number;
 }
 /**
  * Complete engine configuration.
@@ -148,15 +214,13 @@ interface VMConfig {
  *     maxExpressionLength: 1000,
  *     maxComplexity: 200,
  *   },
- *   // date, dice, performance, vm, worker, diagnostic all use defaults
+ *   // date, performance, vm, worker, diagnostic all use defaults
  * });
  * ```
  */
 interface EngineConfig {
     /** Date/time expression evaluation bounds and formatting */
     readonly date: DateConfig;
-    /** Dice roll expression controls */
-    readonly dice: DiceConfig;
     /** Performance budgets and cache sizing */
     readonly performance: PerformanceConfig;
     /** Safety limits for expression complexity */
@@ -200,7 +264,12 @@ declare class ConfigManager {
      */
     set<T>(path: string, value: T): void;
     /**
-     * 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(): EngineConfig;
     /**
@@ -208,7 +277,16 @@ declare class ConfigManager {
      */
     update(config: Partial<EngineConfig>): void;
     /**
-     * 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(): void;
     /**
@@ -225,4 +303,4 @@ interface ValidationResult {
     warnings?: string[];
 }
 
-export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type DiceConfig as c, type ValidationConfig as d, type ValidationResult as e };
+export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type ValidationConfig as c, type ValidationResult as d };

package/dist/{Configuration-fVpd-HC-.d.ts → Configuration-B-G5gTRn.d.ts}

@@ -27,29 +27,30 @@
  * (e.g., `today + 20 days`, `last monday`).
  */
 interface DateConfig {
-    /** Default offset in days for relative date calculations when no offset is specified */
-    readonly defaultOffsetDays: number;
-    /** Maximum allowed positive offset in years (safety limit) */
+    /**
+     * How far forward a date offset whose COST grows with the offset may reach,
+     * in years. Enforced by `vm/VM.ts`'s `addBusinessDays()`.
+     *
+     * Bounds the walk, not the calendar. Every other date offset in the engine
+     * is arithmetic on a Date field, so `today + 100000 days` costs exactly what
+     * one day costs and needs no ceiling; workdays are the one offset that has
+     * to step day by day, because which days are skipped depends on where each
+     * step lands. `today + 100000000 workdays` therefore froze the host for
+     * thirteen seconds inside a single ADD opcode (where `vm.maxInstructions`
+     * cannot see it) and then answered "Invalid Date", and a trillion never
+     * returned at all.
+     *
+     * Release hardening: this field was declared, documented as a "safety
+     * limit", and read nowhere, so it bounded nothing. A limit a host can
+     * configure and the engine ignores is worse than no limit, because it reads
+     * as protection that is not there.
+     */
     readonly maxOffsetYears: number;
-    /** Maximum allowed negative offset in years (safety limit) */
+    /** How far BACK the same walk may reach, in years, as a negative number. See {@link maxOffsetYears}. */
     readonly minOffsetYears: number;
     /** Default date string format for display (moment.js format string) */
     readonly defaultFormat: string;
 }
-/**
- * Dice-related configuration.
- * Controls dice expression evaluation (e.g., `roll(1, 100)`, `3d6`).
- */
-interface DiceConfig {
-    /** Default number of sides on a die when not specified */
-    readonly defaultSides: number;
-    /** Maximum allowed sides per die (prevents excessive allocation) */
-    readonly maxSides: number;
-    /** Maximum number of dice in a single roll expression */
-    readonly maxDice: number;
-    /** Default number of dice when not specified */
-    readonly defaultDice: number;
-}
 /**
  * Performance-related configuration.
  * Controls caching, timeouts, and processing limits to prevent runaway
@@ -67,12 +68,23 @@ interface PerformanceConfig {
      * size limit of its own.
      */
     readonly defaultCacheSize: number;
-    /** Maximum number of document lines processed in a single pass */
+    /**
+     * Maximum lines a document may have for the engine to process it in one
+     * pass. Enforced by `ExpressionEngine.parseDocument()` and by
+     * `engine/DocumentModel.ts`'s `setDocument()`, the two entry points that
+     * take a whole document.
+     *
+     * A document costs memory per line whatever each line says: a parsed line
+     * record, a cache entry, a dependency-graph node. Two hundred thousand
+     * lines of `1 + 1` therefore exhausted the heap and aborted the process
+     * before any per-line limit had anything to object to, which is the same
+     * shape of hole as an unbounded expression and needs the same kind of
+     * ceiling. Refusing the document names the limit; a host that genuinely has
+     * a larger one raises this field.
+     *
+     * Release hardening: declared and read nowhere until now.
+     */
     readonly maxDocumentLines: number;
-    /** Maximum time (ms) allowed for parsing a single expression before timeout */
-    readonly parseTimeoutMs: number;
-    /** Maximum time (ms) allowed for executing a single expression before timeout */
-    readonly executionTimeoutMs: number;
 }
 /**
  * Validation / safety-limit configuration.
@@ -131,6 +143,60 @@ interface VMConfig {
     readonly maxStackDepth: number;
     /** Maximum opcodes executed per expression, halts runaway infinite loops */
     readonly maxInstructions: number;
+    /**
+     * Maximum elements a collection may be expanded to before `map`/`reduce`/
+     * `sum`/`prod` will iterate it.
+     *
+     * A Range is stored as its two bounds and costs nothing until something
+     * materializes it, at which point it becomes one Value per element. Twenty
+     * characters (`sum(x, 1:100000000)`) therefore asked for a hundred million
+     * of them, and neither `maxInstructions` nor `maxStackDepth` could see it:
+     * the expansion happens inside a single opcode, so the instruction counter
+     * is never consulted while it runs, and the elements never reach the value
+     * stack. V8 aborted the whole process with "Reached heap limit", which a
+     * host embedding the engine cannot catch.
+     */
+    readonly maxCollectionSize: number;
+    /**
+     * Maximum elements (collection Values, matrix cells) one evaluation may
+     * materialize in total.
+     *
+     * `maxCollectionSize` above bounds a single collection. This bounds the sum
+     * of everything an expression asks for, which is a different question and
+     * the one that actually protects the host: two collections that are
+     * individually legal are legal together, and an operation whose result is
+     * the PRODUCT of two legal operands is bounded by neither of them. A matrix
+     * multiply is exactly that shape, so three lines within every other limit
+     * (`:a = map(1*x, 0:20000)`, `:b = transpose(a)`, `b * a`) asked for four
+     * hundred million cells and aborted the process.
+     *
+     * Counted in elements rather than bytes, because a count is what a call
+     * site has before it allocates. An element is 8 bytes as a numeric matrix
+     * cell and closer to a hundred as a full Value, so the default is worth
+     * roughly 16 MB of matrix or 200 MB of expanded collection: far past any
+     * document and far short of what an editor cannot survive.
+     */
+    readonly maxAllocatedElements: number;
+    /**
+     * Maximum user-defined-function calls one evaluation may make in TOTAL,
+     * however deeply or widely they nest.
+     *
+     * `maxFunctionRecursionDepth` bounds how DEEP calls nest and cannot see
+     * how MANY there are, and those are different numbers. Twenty-two lines of
+     * `f(n)(v) = f(n-1)(v) + f(n-1)(v)` reach a depth of only 22 against a
+     * limit of 50, and make 2,097,152 calls doing it: a fatal heap abort in
+     * under a second. `maxInstructions` cannot bound it either, because
+     * `executeBytecode()` re-enters itself per call and each reentrant call
+     * gets its OWN instruction count, so recursion refreshes its allowance on
+     * the way in. This is the tally that does not refresh; see
+     * `vm/AllocationBudget.ts`, which holds it for the same reason it holds
+     * the element tally.
+     *
+     * Counted in calls rather than in the instructions they run, because the
+     * call is the thing that multiplies: every call allocates a frame, its
+     * arguments and its result whatever its body says.
+     */
+    readonly maxFunctionCalls: number;
 }
 /**
  * Complete engine configuration.
@@ -148,15 +214,13 @@ interface VMConfig {
  *     maxExpressionLength: 1000,
  *     maxComplexity: 200,
  *   },
- *   // date, dice, performance, vm, worker, diagnostic all use defaults
+ *   // date, performance, vm, worker, diagnostic all use defaults
  * });
  * ```
  */
 interface EngineConfig {
     /** Date/time expression evaluation bounds and formatting */
     readonly date: DateConfig;
-    /** Dice roll expression controls */
-    readonly dice: DiceConfig;
     /** Performance budgets and cache sizing */
     readonly performance: PerformanceConfig;
     /** Safety limits for expression complexity */
@@ -200,7 +264,12 @@ declare class ConfigManager {
      */
     set<T>(path: string, value: T): void;
     /**
-     * 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(): EngineConfig;
     /**
@@ -208,7 +277,16 @@ declare class ConfigManager {
      */
     update(config: Partial<EngineConfig>): void;
     /**
-     * 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(): void;
     /**
@@ -225,4 +303,4 @@ interface ValidationResult {
     warnings?: string[];
 }
 
-export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type DiceConfig as c, type ValidationConfig as d, type ValidationResult as e };
+export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type ValidationConfig as c, type ValidationResult as d };

package/dist/{EngineError-DvPSnhZi.d.cts → EngineError-LU7W7AgI.d.cts}

@@ -28,6 +28,8 @@
  */
 declare const CoreErrorCodes: {
     readonly INVALID_NUMBER_LITERAL: "INVALID_NUMBER_LITERAL";
+    /** A `"` that never meets its closing partner (`lexer/ExpressionLexer.ts`'s `tokenizeString()`). Previously the tokenizer ran off the end of the input and returned what it had, so `"abc` lexed to an ordinary String and an unterminated literal was indistinguishable from a terminated one. */
+    readonly UNTERMINATED_STRING: "UNTERMINATED_STRING";
     readonly NO_PREFIX_PARSELET: "NO_PREFIX_PARSELET";
     readonly UNEXPECTED_END_OF_INPUT: "UNEXPECTED_END_OF_INPUT";
     readonly UNEXPECTED_TOKEN_TYPE: "UNEXPECTED_TOKEN_TYPE";
@@ -53,7 +55,9 @@ declare const CoreErrorCodes: {
     readonly EVALUATION_ERROR: "EVALUATION_ERROR";
     readonly INSTRUCTION_LIMIT_EXCEEDED: "INSTRUCTION_LIMIT_EXCEEDED";
     readonly STACK_LIMIT_EXCEEDED: "STACK_LIMIT_EXCEEDED";
-    /** New this phase. See `VM.ts`'s `safePop()`: a stack-underflow (corrupted bytecode, a buggy plugin) is now a controlled EngineError instead of a raw TypeError. Always `recoverable: false` (internal invariant violation). */
+    /** One evaluation asking for more elements (collection Values, matrix cells) than `vm.maxAllocatedElements` allows. The counter the two limits above cannot be: both are checked between opcodes, so neither can see what a single opcode allocates inside a loop of its own. See `vm/AllocationBudget.ts`. Recoverable, since it describes this expression rather than the engine. */
+    readonly ALLOCATION_LIMIT_EXCEEDED: "ALLOCATION_LIMIT_EXCEEDED";
+    /** New this phase. See `VM.ts`'s `safePop()`: a stack-underflow (corrupted bytecode, a buggy plugin) is now a controlled EngineError instead of a raw TypeError. Category INTERNAL, since it is an engine or plugin fault rather than a typed line, but recoverable: it happened on one line and the engine is still usable. */
     readonly STACK_UNDERFLOW: "STACK_UNDERFLOW";
     readonly UNDEFINED_VARIABLE: "UNDEFINED_VARIABLE";
     /** New this phase, the Tier-2/`LOAD_GLOBAL_VAR` hardening: a global variable read before its async preflight resolved, surfaced as a controlled error instead of pushing `undefined`. */
@@ -64,15 +68,43 @@ declare const CoreErrorCodes: {
     /** User-defined-function call/definition errors (`CALL_USER_FUNCTION`/`DEFINE_USER_FUNCTION` opcodes), calling a name with no matching definition, calling with the wrong argument count, and the deliberate v1 restriction that a function body can't itself contain async work. */
     readonly UNDEFINED_FUNCTION: "UNDEFINED_FUNCTION";
     readonly FUNCTION_ARITY_MISMATCH: "FUNCTION_ARITY_MISMATCH";
+    /** The same mistake against a BUILT-IN rather than a user-defined function (`sqrt()`, `atan2(1)`, `sqrt(1,2,3)`). Separate from `FUNCTION_ARITY_MISMATCH` above because the two are raised by different opcodes and a host may want to word them differently. Checked at the `CALL_BUILTIN` dispatch against `vm/VMBuiltinArity.ts`; recoverable, since it is a typo in the line, not an engine fault. */
+    readonly BUILTIN_ARITY_MISMATCH: "BUILTIN_ARITY_MISMATCH";
     readonly USER_FUNCTION_ASYNC_UNSUPPORTED: "USER_FUNCTION_ASYNC_UNSUPPORTED";
     /** A map/reduce transform body (inline expression or user-defined function) calling an async plugin. Same v1 scope restriction as `USER_FUNCTION_ASYNC_UNSUPPORTED` above, enforced both at parse time (`MAP_REDUCE_TRANSFORM_MUST_BE_SYNCHRONOUS`, packages/mapreduce/) and as a defense-in-depth runtime backstop here. */
     readonly MAP_REDUCE_ASYNC_UNSUPPORTED: "MAP_REDUCE_ASYNC_UNSUPPORTED";
+    /** An algebra verb's expression argument (`BIND_UNKNOWN`'s body) calling an async plugin. Same v1 scope restriction as the two above, and likewise refused at parse time first (`SYMBOLIC_ARGUMENT_MUST_BE_SYNCHRONOUS`, packages/symbolic/). */
+    readonly SYMBOLIC_ASYNC_UNSUPPORTED: "SYMBOLIC_ASYNC_UNSUPPORTED";
     /** `pushCallFrame()`'s recursion guard, a nested `CALL_USER_FUNCTION` re-enters `executeBytecode()`, so `maxInstructions` alone can't catch e.g. `f(x) = f(x)`; this is the dedicated backstop. `recoverable: true` (the default for `.execution()`), ordinary user-written infinite recursion, not an engine bug; the guard exists precisely so it surfaces as a clear error instead of overflowing the native call stack uncatchably. */
     readonly FUNCTION_RECURSION_LIMIT_EXCEEDED: "FUNCTION_RECURSION_LIMIT_EXCEEDED";
+    /** The companion to the code above, and the half it could never see: how MANY user-defined-function calls one evaluation makes, rather than how deeply they nest. A twenty-two-line doubling chain nests twenty-two deep (legal) and makes two million calls (a fatal heap abort). Counted in `vm/AllocationBudget.ts`, because the tally has to survive `executeBytecode()` re-entering itself. Recoverable. */
+    readonly FUNCTION_CALL_LIMIT_EXCEEDED: "FUNCTION_CALL_LIMIT_EXCEEDED";
+    /** A `<date> + N workdays` offset outside `date.maxOffsetYears`/`minOffsetYears`. Workdays are the one date offset that walks the calendar a day at a time, so the one whose cost is the offset; every other one moves a Date field once. Recoverable. */
+    readonly DATE_OFFSET_LIMIT_EXCEEDED: "DATE_OFFSET_LIMIT_EXCEEDED";
+    /** A `<<`/`>>` with a bigint operand whose exact result would pass `MAX_EXACT_SHIFT_BITS`, whichever operand is the bigint. Both spellings refuse as of 1.0.0: a bigint on the left used to fall through to `x * 2^n` in doubles and report a 19,870-digit integer as Infinity. See `vm/VM.ts`'s `bigIntShift()`. Recoverable. */
+    readonly BIGINT_SHIFT_LIMIT_EXCEEDED: "BIGINT_SHIFT_LIMIT_EXCEEDED";
+    /** The same ceiling for `^`, the operator it was written for: `2n ^ 100000` asks for the same 100,001-bit integer `1n << 100000` does, so the two spellings answer the same way. Also new in 1.0.0, and for the same reason: this used to fall through to the double path and answer Infinity. A fractional or negative exponent (`4n ^ 0.5`, `2n ^ -1`) has no exact answer to bound and still uses the double path. See `vm/VM.ts`'s `MAX_EXACT_POW_BITS`. Recoverable. */
+    readonly BIGINT_POW_LIMIT_EXCEEDED: "BIGINT_POW_LIMIT_EXCEEDED";
+    /** An operand with no whole-number form (a fraction, an infinity, a NaN) meeting a bigint: `1n + 0.5`, `1n & 1.5`, `5n/pi`. `BigInt()` answers those with a raw RangeError, which the VM relabelled UNEXPECTED_ERROR, so a typo in the line was reported as an engine fault. Recoverable; see `vm/VMConversion.ts`'s `toBigIntOperand()`. */
+    readonly BIGINT_INEXACT_OPERAND: "BIGINT_INEXACT_OPERAND";
+    /** `10n / 0n` and `10n mod 0n`. Deliberately NOT what `1 / 0` does, which is Infinity: a bigint division is exact integer division (`7n / 2n` is 3n), and integer division by zero has no answer, exactly as it has none in C, Java, Python or JavaScript's own BigInt. Previously V8's own RangeError, relabelled UNEXPECTED_ERROR. Recoverable; see `vm/VMConversion.ts`'s `bigIntDivisionByZero()`. */
+    readonly BIGINT_DIVISION_BY_ZERO: "BIGINT_DIVISION_BY_ZERO";
     /** `DEFINE_USER_FUNCTION`'s body-index lookup failing, a compiler/VM invariant violation (the opcode stream referenced a `userFunctionBodies` slot that doesn't exist), never a user-input error. */
     readonly INTERNAL_MISSING_FUNCTION_BODY: "INTERNAL_MISSING_FUNCTION_BODY";
     /** `MAP_INVOKE`/`REDUCE_INVOKE`'s anonymous-body-index lookup failing. Same class as `INTERNAL_MISSING_FUNCTION_BODY` above, for the `anonymousBodies` side-table instead of `userFunctionBodies`. */
     readonly INTERNAL_MISSING_ANONYMOUS_BODY: "INTERNAL_MISSING_ANONYMOUS_BODY";
+    /** An operand byte read past the end of the stream: the program ends in the middle of an instruction. */
+    readonly MALFORMED_BYTECODE_TRUNCATED: "MALFORMED_BYTECODE_TRUNCATED";
+    /** A constant-pool operand indexing a `numbers`/`strings` entry that does not exist, or that is not of the pool's type. */
+    readonly MALFORMED_BYTECODE_CONSTANT_INDEX: "MALFORMED_BYTECODE_CONSTANT_INDEX";
+    /** A unit or converter name read off the value stack that is not a string. Distinct from the pool case above: the operand is a Value another opcode pushed, not a pool entry. */
+    readonly MALFORMED_BYTECODE_OPERAND_TYPE: "MALFORMED_BYTECODE_OPERAND_TYPE";
+    /** `MAP_INVOKE`/`REDUCE_INVOKE` carrying a body kind other than 0/1/2. Used to fall through every arm with no body and recurse into `executeBytecode(undefined)`. */
+    readonly MALFORMED_BYTECODE_BODY_KIND: "MALFORMED_BYTECODE_BODY_KIND";
+    /** A `PUSH_BIGINT` pool entry that is not a whole number, e.g. `"1.000"`. `BigInt()` answers that with a raw SyntaxError. */
+    readonly MALFORMED_BYTECODE_BIGINT_LITERAL: "MALFORMED_BYTECODE_BIGINT_LITERAL";
+    /** `executeBytecode()` called with something that is not a runnable program at all. Checked before the destructure that used to throw outside the function's own try/catch. */
+    readonly MALFORMED_BYTECODE_PROGRAM: "MALFORMED_BYTECODE_PROGRAM";
     /** A coefficient grew past `RATIONAL_MAX_BITS`, e.g. repeated exact elimination multiplying denominators together. */
     readonly SYMBOLIC_RATIONAL_OVERFLOW: "SYMBOLIC_RATIONAL_OVERFLOW";
     /** `NaN` or `±Infinity` reaching a symbolic expression, neither of which has an exact rational value. */
@@ -87,6 +119,8 @@ declare const CoreErrorCodes: {
     readonly SYMBOLIC_FACTOR_LIMIT_EXCEEDED: "SYMBOLIC_FACTOR_LIMIT_EXCEEDED";
     /** An equation outside what the solver attempts: not a polynomial, above the degree ceiling, or non-linear in the unknown while another unknown is present. */
     readonly SYMBOLIC_SOLVE_UNSUPPORTED: "SYMBOLIC_SOLVE_UNSUPPORTED";
+    /** Some but not all of an equation's roots were found. Reported rather than returned, because a partial list of roots looks exactly like a complete one. */
+    readonly SYMBOLIC_SOLVE_INCOMPLETE: "SYMBOLIC_SOLVE_INCOMPLETE";
     /** `solve`'s second argument not being a bare name. */
     readonly SOLVE_REQUIRES_VARIABLE_NAME: "SOLVE_REQUIRES_VARIABLE_NAME";
     /** A derivative order outside 0..`DERIVATIVE_MAX_ORDER`. */
@@ -105,11 +139,15 @@ declare const CoreErrorCodes: {
     readonly INTERNAL_RATIONAL_PARSE: "INTERNAL_RATIONAL_PARSE";
     readonly EXPRESSION_TOO_LONG: "EXPRESSION_TOO_LONG";
     readonly EXPRESSION_TOO_COMPLEX: "EXPRESSION_TOO_COMPLEX";
+    /** A document with more lines than `performance.maxDocumentLines`. The per-line limits above bound what one line may ask for and say nothing about how many lines there are; two hundred thousand of `1 + 1` exhausted the heap on the line records alone. Recoverable. */
+    readonly DOCUMENT_TOO_LARGE: "DOCUMENT_TOO_LARGE";
     readonly NORMALIZED_TOKEN_LIMIT_EXCEEDED: "NORMALIZED_TOKEN_LIMIT_EXCEEDED";
     /** `"=>"` with nothing before it, needs an expression or variable name to solve/simplify. */
     readonly THEREFORE_REQUIRES_EXPRESSION: "THEREFORE_REQUIRES_EXPRESSION";
     /** A `"=>"`-triggered expression called an async plugin (weather/stocks/currency). Same v1 scope restriction as user-function/map-reduce bodies. */
     readonly THEREFORE_ASYNC_UNSUPPORTED: "THEREFORE_ASYNC_UNSUPPORTED";
+    /** Colon-separated numbers that are not a time any clock can show ("24:00", "9:60", "100:5"). Raised by the labeled-line fallback, which used to answer them with whatever stood after the colon. */
+    readonly INVALID_TIME_LITERAL: "INVALID_TIME_LITERAL";
     readonly CONFIG_PATH_NOT_FOUND: "CONFIG_PATH_NOT_FOUND";
     readonly INVALID_CONFIG_PATH: "INVALID_CONFIG_PATH";
     readonly CONFIG_SECTION_NOT_FOUND: "CONFIG_SECTION_NOT_FOUND";
@@ -192,20 +230,29 @@ interface EngineErrorInit {
     /** An actionable, worked-example fix, e.g. `e.g. "weather in London"`. Mirrors this codebase's best existing messages (`WEATHER_EXPECTED_CITY`, `AS_CONVERTER_EXPECTED_NAME`). */
     suggestion?: string;
     /**
-     * `true` (the default) for every EXPECTED failure mode of user input or
-     * environment, bad syntax, an unknown variable/function, a safety limit
-     * exceeded, an external API being down. `false` is reserved for genuine
-     * ENGINE-INTERNAL invariant violations (corrupted bytecode, a stack
-     * underflow from a buggy plugin, an "impossible" state)
-     * `ErrorFactory.internal()`/`.config()` default to `false`, every other
-     * factory method defaults to `true`.
+     * Whether this engine instance is still usable. `true` for everything that
+     * went wrong on ONE line, whether the line's fault (bad syntax, an unknown
+     * variable, a safety limit exceeded), the environment's (an external API
+     * down), or the engine's own (corrupted bytecode, a stack underflow from a
+     * buggy plugin). `false` is for the far rarer case where there is no working
+     * engine to go on with: a configuration or package-registration failure,
+     * which is what `ErrorFactory.config()` is for and the only factory method
+     * that still defaults to it.
      *
-     * This does NOT gate "does evaluation of the rest of the document
-     * continue", with this engine's per-line containment, it always does
-     * even for a `recoverable: false` error (see `ARCHITECTURE.md`'s
-     * async-batcher/Tier-2 hardening notes). It gates MESSAGE FRAMING and
-     * telemetry: "fix your syntax" vs. "this is an engine bug, worth
-     * reporting". See `EngineError.isFatal()`.
+     * The category answers a different question, and the two used to be answered
+     * as one. Category INTERNAL says whose fault this is, the engine's, worth
+     * reporting as a bug. `recoverable` says whether the host may carry on, and
+     * after an internal slip on one line it may:
+     * `__tests__/hardening/RobustnessEngineLifecycle.spec.ts` alternates a
+     * throwing line with a good one five hundred times and every answer stays
+     * correct. Reporting that as `isFatal()` told a host the opposite, and a host
+     * that honours the name would tear a document down over one bad line.
+     *
+     * This has never gated "does evaluation of the rest of the document
+     * continue"; with this engine's per-line containment it always does, even for
+     * a `recoverable: false` error (see `ARCHITECTURE.md`'s async-batcher/Tier-2
+     * hardening notes). It gates what a host is TOLD. See
+     * {@link EngineError.isFatal}.
      */
     recoverable?: boolean;
     /** Character-offset span into the source expression, when available. Not yet threaded through every call site, populate opportunistically, don't block on retrofitting every existing throw site. */
@@ -281,10 +328,23 @@ declare class ErrorFactory {
     static execution(init: EngineErrorInit): EngineError;
     static external(code: string, message: string, context?: Record<string, unknown>): EngineError;
     static external(init: EngineErrorInit): EngineError;
-    /** Defaults `recoverable: false`, reserve for genuine engine-internal invariant violations, not user-input errors. */
+    /**
+     * Reserve for genuine engine-internal invariant violations (corrupted
+     * bytecode, a stack underflow from a buggy plugin, an "impossible" state),
+     * not for user-input errors: the category is a bug report.
+     *
+     * Defaults `recoverable: true` all the same, because every one of these sites
+     * is an invariant that failed on ONE line and none of them leaves the engine
+     * unusable. This used to default to `false`, which conflated "the engine's
+     * fault" with "the engine is finished" and told a host to tear a document
+     * down over a line it could simply have shown an error against. A site that
+     * has looked at its own case and concluded the instance really is gone can
+     * still pass `recoverable: false` explicitly. See {@link
+     * EngineErrorInit.recoverable}.
+     */
     static internal(code: string, message: string, context?: Record<string, unknown>): EngineError;
     static internal(init: EngineErrorInit): EngineError;
-    /** Defaults `recoverable: false`, a bad config is an environment-setup problem, not a per-line user-input error. */
+    /** Defaults `recoverable: false`, and is now the only method that does: a configuration or package-registration failure is the one class that leaves no working engine to carry on with, rather than one bad line in a document. */
     static config(code: string, message: string, context?: Record<string, unknown>): EngineError;
     static config(init: EngineErrorInit): EngineError;
 }
@@ -298,6 +358,26 @@ declare class ErrorFactory {
  * per-line containment) so a raw `TypeError` from a genuine engine bug
  * still surfaces as a structured, catalogued error instead of an opaque
  * uncaught exception.
+ *
+ * Both branches state RECOVERABLE explicitly, while keeping the INTERNAL
+ * category. The two fields answer different questions and were previously
+ * answering the same one:
+ *
+ *   category INTERNAL  whose fault is this? The engine's. Worth reporting.
+ *   recoverable        is this engine instance still usable? Yes.
+ *
+ * Everything reaching here is by definition something the engine did not
+ * anticipate on ONE line, and per-line containment means the next line
+ * evaluates normally, which `__tests__/hardening/RobustnessEngineLifecycle`
+ * demonstrates over hundreds of alternating failure/success pairs. Reporting
+ * that as `isFatal()` told a host the opposite, and a host that honours the
+ * name would tear a document down over a single bad line. The "this is an
+ * engine bug rather than your syntax" signal a caller wants for telemetry is
+ * the CATEGORY, which is unchanged.
+ *
+ * The flag is written out here rather than inherited from
+ * `ErrorFactory.internal()`, which now defaults the same way, so that this
+ * function's contract survives a future change to that default.
  */
 declare function normalizeUnknownError(error: unknown): EngineError;