solve-engine 1.0.0-beta.7 → 1.0.1

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

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

package/dist/{Lexer-W9MBOP0V.d.ts → Lexer-BN5mt30n.d.ts}

@@ -364,6 +364,22 @@ declare class ExpressionLexer {
     private tokenizeOperator;
     /**
      * Reads a double-quoted string literal. Supports backslash escapes.
+     *
+     * `text` is the raw source slice, quotes included, because that is what
+     * `offset` + `text.length` has to span for a host to underline the literal.
+     * `value` is the PAYLOAD, quotes excluded, because that is what
+     * `PUSH_STRING` puts into the Value.
+     *
+     * The two used to be the same string. `"abc"` carried the five characters
+     * `"abc"` as its value, which was invisible on screen (the formatter prints
+     * the payload raw and the retained quotes landed where a display would have
+     * put them back) and not invisible anywhere else: `parseFloat('"5"')` is NaN
+     * whatever the digits say, so `"5" + 5` answered 5.
+     *
+     * An unterminated literal is an error rather than a string that happens to
+     * reach the end of the line. It used to return what it had, so `"abc` and
+     * `"abc"` were indistinguishable by payload once the quotes were stripped,
+     * which is the other half of why they are stripped here rather than later.
      */
     private tokenizeString;
     /**

package/dist/{Lexer-Cfm79Dak.d.cts → Lexer-D78E2yDW.d.cts}

@@ -364,6 +364,22 @@ declare class ExpressionLexer {
     private tokenizeOperator;
     /**
      * Reads a double-quoted string literal. Supports backslash escapes.
+     *
+     * `text` is the raw source slice, quotes included, because that is what
+     * `offset` + `text.length` has to span for a host to underline the literal.
+     * `value` is the PAYLOAD, quotes excluded, because that is what
+     * `PUSH_STRING` puts into the Value.
+     *
+     * The two used to be the same string. `"abc"` carried the five characters
+     * `"abc"` as its value, which was invisible on screen (the formatter prints
+     * the payload raw and the retained quotes landed where a display would have
+     * put them back) and not invisible anywhere else: `parseFloat('"5"')` is NaN
+     * whatever the digits say, so `"5" + 5` answered 5.
+     *
+     * An unterminated literal is an error rather than a string that happens to
+     * reach the end of the line. It used to return what it had, so `"abc` and
+     * `"abc"` were indistinguishable by payload once the quotes were stripped,
+     * which is the other half of why they are stripped here rather than later.
      */
     private tokenizeString;
     /**

package/dist/{PackageRegistry-pHtKythi.d.cts → PackageRegistry-B37mRvvz.d.cts}

@@ -1,16 +1,16 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-Cu0bLSis.cjs';
-import { V as Value } from './Value-KtAQNHur.cjs';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-DuI1Pjiq.cjs';
+import { V as Value } from './Value-CXJqDH9J.cjs';
 import { IVariableSource } from './variables.cjs';
-import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-Cfm79Dak.cjs';
+import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-D78E2yDW.cjs';
 import { IAsyncResolver } from './resolvers.cjs';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-DGVa24Q-.cjs';
-import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, L as LineExecutionContext } from './ScopeManager-CKfQtl7l.cjs';
-import { a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.cjs';
+import { a as DependencyGraph, V as VM, D as DagSnapshot, b as EngineContext, S as ScopeManager, L as LineExecutionContext } from './ScopeManager-B6GzdhVG.cjs';
+import { a as BytecodeProgram } from './BytecodeBuilder-B0xskcv5.cjs';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-DvPSnhZi.cjs';
-import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-DPUQt7yL.cjs';
+import { E as EngineError } from './EngineError-LU7W7AgI.cjs';
+import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-BEb3hujr.cjs';
 import { T as Token } from './Token-BzG5G4ja.cjs';
-import { D as DEFAULT_CONFIG, E as EngineConfig } from './Configuration-fVpd-HC-.cjs';
+import { D as DEFAULT_CONFIG, E as EngineConfig } from './Configuration-B-G5gTRn.cjs';
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -213,9 +213,28 @@ declare class DocumentModel {
      * bottom of a 20k-line document before this fix.
      */
     private dirtyLineIds;
+    /**
+     * Most lines this model will hold. See `constants/Configuration.ts`'s
+     * `performance.maxDocumentLines`, which is where the default comes from and
+     * which a host raises through its engine config; a host that builds a
+     * DocumentModel directly passes it here instead.
+     */
+    private readonly maxLines;
+    /**
+     * @param maxLines - Ceiling on the line count, defaulting to the engine's
+     * configured one. Every line costs a LineState with six arrays in it
+     * whatever the line says, so the cost of a document is its line count and
+     * nothing else bounds it: two hundred thousand lines of `1 + 1` exhausted
+     * the heap here, before a single expression had been looked at.
+     */
+    constructor(maxLines?: number);
     /**
      * Initialize or replace the entire document from a text blob.
      * Clears all existing state and assigns new persistent line IDs.
+     *
+     * @throws `DOCUMENT_TOO_LARGE` for a document past {@link maxLines}, before
+     * any of it is stored. Recoverable: nothing has been replaced yet, so the
+     * model still holds whatever it held.
      */
     setDocument(text: string): void;
     /**
@@ -1407,9 +1426,17 @@ declare class ExpressionEngine {
      * own contract). This engine-instance-local registration is reversed
      * here too, even though it isn't a "shared" registry, so a package's
      * lexer and highlighting contributions clean up together rather than
-     * only half-reversing on unregister. Per-engine parselets/phrases are
-     * still left in place: they live in this engine's isolated registries
-     * and are discarded with the engine instance.
+     * only half-reversing on unregister. Normalizer rules are reversed here
+     * for the same reason: they are per-engine, but they live in an ARRAY the
+     * normalizer walks at every token position, so re-registering a package
+     * appended a second copy of every rule and lexing got slower with every
+     * register/unregister cycle.
+     *
+     * Per-engine parselets and phrases are still left in place: a parselet
+     * lives in this engine's isolated registry and a phrase goes into a
+     * text-keyed trie where registering the same phrase twice is the same as
+     * registering it once, so neither accumulates and both are discarded with
+     * the engine instance.
      *
      * Clears the bytecode cache, removing handlers changes what compiled
      * bytecode is valid.
@@ -1527,6 +1554,12 @@ declare class ExpressionEngine {
      * parseExpression(). Abstracts the API difference between the two parsers:
      * - PrecedenceParser:  parser.setBuilder(builder); parser.parseExpression(0)
      * - RD:                parser.builder = builder; parser.parseExpression(0)
+     *
+     * @param allowLabelFallback - Whether a line that does not parse whole may
+     * be retried as "<label>: <expression>". True for a real line, false for
+     * the retries that fallback makes itself, which is what stops it costing
+     * exponential time; see the loop below, and the comment on its recursive
+     * call for the measurement.
      */
     private parseExpression;
     /**
@@ -1548,9 +1581,17 @@ declare class ExpressionEngine {
      * (a bare assignment's RHS, and an equation's own RHS at solve time)
      *, every one of these needs forward-tolerant reads of not-yet-defined
      * names, which ordinary evaluation deliberately never allows.
+     *
+     * `lineNumber` is the 1-based document line this program belongs to, so
+     * the RHS still receives a {@link makeLineContext}, a bare assignment's
+     * right-hand side (`total = prev`, `x = line2`) can therefore read
+     * cross-line results exactly as a bare expression line does. Defaults to
+     * `-1` (the "no real document" sentinel) for the expression-level and
+     * `=>`-without-a-document callers, which naturally yields the same
+     * `LINE_REF_NO_DOCUMENT` a single-expression eval already returns.
      */
     private executeSymbolicTolerant;
-    /** Compiles and executes `tokens` in symbolic-tolerant mode, the "just simplify this" `=>` fallback when there's no stored equation to solve. */
+    /** Compiles and executes `tokens` in symbolic-tolerant mode, the "just simplify this" `=>` fallback when there's no stored equation to solve. `lineNumber` (1-based, `-1` outside a document) is forwarded so a bare assignment's RHS can resolve cross-line references. */
     private simplifySymbolically;
     /**
      * Parses a bare (colon-less) equation's left-hand side, `factor1 *
@@ -2111,8 +2152,23 @@ declare class ExpressionEngine {
      * goes through the parser's own throw/catch inside prepareExpression()
      * unavoidable without restructuring the parser's failure signaling, which
      * is out of scope here.
+     *
+     * The "non-throwing" in the first line is a contract callers rely on, not
+     * a description of the happy path, so it is enforced here rather than left
+     * to every stage below agreeing to return its errors. It had been left to
+     * them, and they did not all agree: the lexer throws on an unterminated
+     * string (`"`), and the symbolic grammar threw on an assignment whose
+     * right-hand side is still empty (`total =`). LanguageService calls this
+     * per visible line per keystroke, so both reached CodeMirror's transaction
+     * dispatch and broke the editor on input that is merely half-typed.
+     *
+     * A catch costs nothing on the path that does not throw, so the "no" answer
+     * this method exists to make cheap stays cheap. Anything that does throw
+     * was already paying for the Error it constructed.
      */
     tryCompileExpression(expression: string): boolean;
+    /** The body of {@link tryCompileExpression}, which owns the contract. */
+    private tryCompileExpressionUnguarded;
     /**
      * Execute pre-compiled bytecode against the engine's shared VM.
      * Used by Tier 2 (scroll into view) to re-execute cached bytecode
@@ -2270,7 +2326,7 @@ declare class LanguageService {
      * highlighted the obvious way.
      *
      * A token the normalizer left alone still describes its own text, so its
-     * span is `offset` to `offset + value.length`, exactly as before.
+     * span is `offset` to `offset + text.length`, exactly as before.
      *
      * A FUSED token does not. `10 frames` becomes a FRAME_COUNT whose value is
      * `10`, and a timecode becomes a token whose value is a comma-separated

package/dist/{PackageRegistry-CjDt-Jy_.d.ts → PackageRegistry-DCUEzbQt.d.ts}

@@ -1,16 +1,16 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-DEdF9I7n.js';
-import { V as Value } from './Value-KtAQNHur.js';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-BaySkMV3.js';
+import { V as Value } from './Value-CXJqDH9J.js';
 import { IVariableSource } from './variables.js';
-import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-W9MBOP0V.js';
+import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-BN5mt30n.js';
 import { IAsyncResolver } from './resolvers.js';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-t_GotBxr.js';
-import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, L as LineExecutionContext } from './ScopeManager-B5k0nk05.js';
-import { a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.js';
+import { a as DependencyGraph, V as VM, D as DagSnapshot, b as EngineContext, S as ScopeManager, L as LineExecutionContext } from './ScopeManager-udv4Twwq.js';
+import { a as BytecodeProgram } from './BytecodeBuilder-B0xskcv5.js';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-DvPSnhZi.js';
-import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-CrsRPmsv.js';
+import { E as EngineError } from './EngineError-LU7W7AgI.js';
+import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-B6k5lCB7.js';
 import { T as Token } from './Token-BzG5G4ja.js';
-import { D as DEFAULT_CONFIG, E as EngineConfig } from './Configuration-fVpd-HC-.js';
+import { D as DEFAULT_CONFIG, E as EngineConfig } from './Configuration-B-G5gTRn.js';
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -213,9 +213,28 @@ declare class DocumentModel {
      * bottom of a 20k-line document before this fix.
      */
     private dirtyLineIds;
+    /**
+     * Most lines this model will hold. See `constants/Configuration.ts`'s
+     * `performance.maxDocumentLines`, which is where the default comes from and
+     * which a host raises through its engine config; a host that builds a
+     * DocumentModel directly passes it here instead.
+     */
+    private readonly maxLines;
+    /**
+     * @param maxLines - Ceiling on the line count, defaulting to the engine's
+     * configured one. Every line costs a LineState with six arrays in it
+     * whatever the line says, so the cost of a document is its line count and
+     * nothing else bounds it: two hundred thousand lines of `1 + 1` exhausted
+     * the heap here, before a single expression had been looked at.
+     */
+    constructor(maxLines?: number);
     /**
      * Initialize or replace the entire document from a text blob.
      * Clears all existing state and assigns new persistent line IDs.
+     *
+     * @throws `DOCUMENT_TOO_LARGE` for a document past {@link maxLines}, before
+     * any of it is stored. Recoverable: nothing has been replaced yet, so the
+     * model still holds whatever it held.
      */
     setDocument(text: string): void;
     /**
@@ -1407,9 +1426,17 @@ declare class ExpressionEngine {
      * own contract). This engine-instance-local registration is reversed
      * here too, even though it isn't a "shared" registry, so a package's
      * lexer and highlighting contributions clean up together rather than
-     * only half-reversing on unregister. Per-engine parselets/phrases are
-     * still left in place: they live in this engine's isolated registries
-     * and are discarded with the engine instance.
+     * only half-reversing on unregister. Normalizer rules are reversed here
+     * for the same reason: they are per-engine, but they live in an ARRAY the
+     * normalizer walks at every token position, so re-registering a package
+     * appended a second copy of every rule and lexing got slower with every
+     * register/unregister cycle.
+     *
+     * Per-engine parselets and phrases are still left in place: a parselet
+     * lives in this engine's isolated registry and a phrase goes into a
+     * text-keyed trie where registering the same phrase twice is the same as
+     * registering it once, so neither accumulates and both are discarded with
+     * the engine instance.
      *
      * Clears the bytecode cache, removing handlers changes what compiled
      * bytecode is valid.
@@ -1527,6 +1554,12 @@ declare class ExpressionEngine {
      * parseExpression(). Abstracts the API difference between the two parsers:
      * - PrecedenceParser:  parser.setBuilder(builder); parser.parseExpression(0)
      * - RD:                parser.builder = builder; parser.parseExpression(0)
+     *
+     * @param allowLabelFallback - Whether a line that does not parse whole may
+     * be retried as "<label>: <expression>". True for a real line, false for
+     * the retries that fallback makes itself, which is what stops it costing
+     * exponential time; see the loop below, and the comment on its recursive
+     * call for the measurement.
      */
     private parseExpression;
     /**
@@ -1548,9 +1581,17 @@ declare class ExpressionEngine {
      * (a bare assignment's RHS, and an equation's own RHS at solve time)
      *, every one of these needs forward-tolerant reads of not-yet-defined
      * names, which ordinary evaluation deliberately never allows.
+     *
+     * `lineNumber` is the 1-based document line this program belongs to, so
+     * the RHS still receives a {@link makeLineContext}, a bare assignment's
+     * right-hand side (`total = prev`, `x = line2`) can therefore read
+     * cross-line results exactly as a bare expression line does. Defaults to
+     * `-1` (the "no real document" sentinel) for the expression-level and
+     * `=>`-without-a-document callers, which naturally yields the same
+     * `LINE_REF_NO_DOCUMENT` a single-expression eval already returns.
      */
     private executeSymbolicTolerant;
-    /** Compiles and executes `tokens` in symbolic-tolerant mode, the "just simplify this" `=>` fallback when there's no stored equation to solve. */
+    /** Compiles and executes `tokens` in symbolic-tolerant mode, the "just simplify this" `=>` fallback when there's no stored equation to solve. `lineNumber` (1-based, `-1` outside a document) is forwarded so a bare assignment's RHS can resolve cross-line references. */
     private simplifySymbolically;
     /**
      * Parses a bare (colon-less) equation's left-hand side, `factor1 *
@@ -2111,8 +2152,23 @@ declare class ExpressionEngine {
      * goes through the parser's own throw/catch inside prepareExpression()
      * unavoidable without restructuring the parser's failure signaling, which
      * is out of scope here.
+     *
+     * The "non-throwing" in the first line is a contract callers rely on, not
+     * a description of the happy path, so it is enforced here rather than left
+     * to every stage below agreeing to return its errors. It had been left to
+     * them, and they did not all agree: the lexer throws on an unterminated
+     * string (`"`), and the symbolic grammar threw on an assignment whose
+     * right-hand side is still empty (`total =`). LanguageService calls this
+     * per visible line per keystroke, so both reached CodeMirror's transaction
+     * dispatch and broke the editor on input that is merely half-typed.
+     *
+     * A catch costs nothing on the path that does not throw, so the "no" answer
+     * this method exists to make cheap stays cheap. Anything that does throw
+     * was already paying for the Error it constructed.
      */
     tryCompileExpression(expression: string): boolean;
+    /** The body of {@link tryCompileExpression}, which owns the contract. */
+    private tryCompileExpressionUnguarded;
     /**
      * Execute pre-compiled bytecode against the engine's shared VM.
      * Used by Tier 2 (scroll into view) to re-execute cached bytecode
@@ -2270,7 +2326,7 @@ declare class LanguageService {
      * highlighted the obvious way.
      *
      * A token the normalizer left alone still describes its own text, so its
-     * span is `offset` to `offset + value.length`, exactly as before.
+     * span is `offset` to `offset + text.length`, exactly as before.
      *
      * A FUSED token does not. `10 frames` becomes a FRAME_COUNT whose value is
      * `10`, and a timecode becomes a token whose value is a comma-separated

package/dist/{Parselet-DEdF9I7n.d.ts → Parselet-BaySkMV3.d.ts}

@@ -1,6 +1,6 @@
-import { B as BytecodeBuilder } from './BytecodeBuilder-3egMyuDi.js';
+import { B as BytecodeBuilder } from './BytecodeBuilder-B0xskcv5.js';
 import { T as Token } from './Token-BzG5G4ja.js';
-import { D as DiagnosticPipeline } from './pipeline-CrsRPmsv.js';
+import { D as DiagnosticPipeline } from './pipeline-B6k5lCB7.js';
 
 /**
  * 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;