solve-engine 2.23.0 → 2.25.0

package/dist/{Lexer-CCHFDcgP.d.cts → Lexer-aB95pjoX.d.cts}

@@ -1,4 +1,5 @@
 import { T as Token } from './Token-CbP_OutD.cjs';
+import { E as EngineError } from './EngineError-fR1K1rvx.cjs';
 
 /** Trie node for multi-word phrase matching. */
 interface PhraseNode {
@@ -101,6 +102,14 @@ interface ScanLineResult {
     tokens: Token[];
     /** Inline solve spans found in this line (empty if none). */
     inlineSolves: InlineSolveSpan[];
+    /**
+     * The structured error the tokeniser raised on this line, if it raised one
+     * (an unterminated string literal is the one it can raise today). The line
+     * carries no tokens then, and the rest of the document is unaffected: a
+     * half-typed quote used to escape {@link ExpressionLexer.scanDocument} as
+     * a throw and take every other line's result down with it.
+     */
+    error?: EngineError;
 }
 /**
  * A token, as the lexer produces it.
@@ -208,16 +217,6 @@ interface LexerVocabulary {
  */
 declare class ExpressionLexer {
     private static readonly CHAR_CLASS;
-    /**
-     * Configured TokenLookup from TokenClassRegistry. When set, replaces
-     * the internal keyword map and unit set with registry-built equivalents.
-     * Enables data-driven keyword/unit registration across locale keywords,
-     * provider keywords, and plugins.
-     *
-     * Set at construction time via the constructor parameter. Plugin-registered
-     * keywords/units (via registerVocabulary()) are checked alongside
-     * the configuredLookup, neither source is bypassed.
-     */ private configuredLookup;
     private input;
     private pos;
     private len;
@@ -227,7 +226,16 @@ declare class ExpressionLexer {
     private keywordMap;
     private mergedKeywords;
     private mergedUnits;
-    private pluginKeywordMap;
+    /**
+     * Who registered each plugin keyword, unit and two-character operator, in
+     * registration order. Two packages may claim the same word (the
+     * compatibility index warns, and the last registered wins, as before); the
+     * owner lists make unregistration exact, so removing one package hands the
+     * word back to the other rather than deleting it for both.
+     */
+    private pluginKeywordOwners;
+    private pluginUnitOwners;
+    private pluginOperatorOwners;
     private pluginOperators;
     private pluginUnits;
     private hasPluginOps;
@@ -235,7 +243,7 @@ declare class ExpressionLexer {
     private locale;
     /**
      * Inline solve spans collected during the most recent tokenization pass.
-     * Populated by [Symbol.iterator]() and consumed by scanDocument().
+     * Populated by tokenizeInto() and consumed by scanDocument().
      */
     _inlineSolveSpans: InlineSolveSpan[];
     private pluginRawLinePatterns;
@@ -260,7 +268,14 @@ declare class ExpressionLexer {
     private matchRawLine;
     /** Rebuild merged keyword and unit collections after plugin registration. */
     private rebuildMergedUnits;
-    constructor(localeCode?: string, lookup?: TokenLookup);
+    /**
+     * @param localeCode - Locale whose keyword table seeds the lexer.
+     * @param _lookup - Ignored. The lexer built its keyword, unit and phrase
+     *   tables from the locale and the registered packages and never read the
+     *   lookup it was handed; the parameter stays so existing callers compile.
+     *   @deprecated Removed in 3.0.
+     */
+    constructor(localeCode?: string, _lookup?: TokenLookup);
     /**
      * Register a plugin to extend the lexer with custom tokens.
      *
@@ -276,6 +291,10 @@ declare class ExpressionLexer {
      * that conflicts with a built-in one.
      */
     registerVocabulary(plugin: LexerVocabulary): void;
+    /** Record `owner`'s claim on `key`. The newest claim is the one in force. */
+    private claim;
+    /** Drop `owner`'s claim on `key`, and return the claim now in force, if any is left. */
+    private release;
     /**
      * Unregister a plugin, removing its custom tokens from the lexer.
      *
@@ -307,9 +326,9 @@ declare class ExpressionLexer {
      *   lines that classifyLine() marks as having inline solves.
      *
      * Tokenization is scoped to each line by temporarily restricting
-     * `this.len` to the line end position, so the [Symbol.iterator]
-     * generator naturally stops at the line boundary. After tokenization,
-     * `this.len` is restored and `this.pos` advances past the newline.
+     * `this.len` to the line end position, so tokenizeInto() naturally
+     * stops at the line boundary. After tokenization, `this.len` is
+     * restored and `this.pos` advances past the newline.
      *
      * @param text The full document text (with newlines).
      * @returns Array of ScanLineResult, one per line, in document order.
@@ -318,9 +337,7 @@ declare class ExpressionLexer {
     /**
      * Tokenize an expression string into an array of Tokens.
      *
-     * Delegates to the lazy [Symbol.iterator]() generator and collects all
-     * yielded tokens via Array.from(). For memory-sensitive use cases, prefer
-     * iterating the lexer directly with for...of to avoid array allocation.
+     * Runs {@link tokenizeInto} into a fresh array.
      *
      * Optimizations:
      *  - CHAR_CLASS jump table (Uint8Array) → switch on small integers
@@ -332,20 +349,31 @@ declare class ExpressionLexer {
      */
     tokenizeAll(): Token[];
     /**
-     * Lazy token-by-token generator. Yields each token without allocating an
-     * intermediate Token[] array. Supports for...of and spread usage.
+     * Scan the current input and append every token to `out`.
+     *
+     * This is the scanner itself: {@link tokenizeAll} and the iterator are
+     * thin wrappers over it. It pushes into an array the caller owns rather
+     * than yielding, because a generator paid a resume per token and
+     * `Array.from` a second pass on top, and because a caller that catches a
+     * tokeniser fault (highlighting a line with an unterminated quote) still
+     * holds the tokens read before it.
      *
-     * Usage:
-     *   for (const t of lexer) { ... }  // lazy, no array allocation
-     *   const tokens = [...lexer];       // materializes via spread
-     *   const tokens = lexer.tokenizeAll(); // materializes via Array.from()
+     * IMPORTANT: `this.len` is read ONCE on entry (const len = this.len).
+     * `scanDocument()` relies on this to scope a pass to a single line by
+     * restricting `this.len` to the line end before calling. Do not re-read
+     * `this.len` mid-loop without also updating `scanDocument()`.
      *
-     * IMPORTANT: This generator captures `this.len` ONCE at creation time
-     * (const len = this.len). `scanDocument()` relies on this behavior to
-     * scope tokenization to a single line by temporarily restricting
-     * `this.len` to the line end position before creating the iterator.
-     * Do NOT refactor to re-read `this.len` mid-loop without also updating
-     * `scanDocument()`.
+     * @param out - The array to append to. Left as it was if the input is empty.
+     */
+    tokenizeInto(out: Token[]): void;
+    /**
+     * Iterate the tokens of the current input.
+     *
+     * Runs {@link tokenizeInto} first, so the tokens are the same as before,
+     * but a fault part way through the line is thrown from the first
+     * `next()` rather than at the token it occurred on. A caller that wants
+     * the tokens read before a fault calls {@link tokenizeInto} with its own
+     * array.
      */
     [Symbol.iterator](): Generator<Token, void, undefined>;
     /**
@@ -456,6 +484,27 @@ declare class ExpressionLexer {
      * `#12345` (length 5), `#ff0000zz` (trailing word) do not.
      */
     private matchHexColourEnd;
+    /**
+     * Whether an inline-solve opener (`s` + backtick) occurs in `[from, end)`.
+     *
+     * Bounded by hand rather than written as `input.indexOf("s\`", from)`. This
+     * used to be the `indexOf` form with an `idx < end` check afterwards, which
+     * is correct but not bounded: when {@link scanDocument} is classifying,
+     * `this.input` is the whole document, so a line with no marker scanned to
+     * the END OF THE DOCUMENT before the check could reject the hit. Every line
+     * paid for every line after it, and a whole-document parse was quadratic in
+     * line count (measured at 28.9 us per line at 10,000 lines against 10.1 us
+     * at 1,000, and two thirds of the parse's self time in a profile). A prose
+     * document with many candidate `s` characters was worse still. The
+     * wikilink close in {@link indexOfWithin} had the same shape.
+     */
+    private hasInlineSolveWithin;
+    /**
+     * `input.indexOf(needle, from)` restricted to `[from, end)`, returning -1
+     * when the needle does not occur wholly before `end`. See
+     * {@link hasInlineSolveWithin} for why the plain `indexOf` was not enough.
+     */
+    private indexOfWithin;
     private classifyFromPositions;
     /**
      * Classify a single line of markdown text.
@@ -530,11 +579,11 @@ declare class Lexer {
     private tokenIdx;
     /**
      * @param localeCode - Locale code (e.g., "en", "de"). Defaults to "en".
-     * @param tokenLookup - Optional TokenLookup from TokenClassRegistry.
-     *   When provided, configures ExpressionLexer to use registry-built
-     *   keyword/unit/phrase lookups instead of internal instance maps.
+     * @param _tokenLookup - Ignored. The lexer never read the lookup it was
+     *   handed; the parameter stays so existing callers compile.
+     *   @deprecated Removed in 3.0.
      */
-    constructor(localeCode?: string, tokenLookup?: TokenLookup);
+    constructor(localeCode?: string, _tokenLookup?: TokenLookup);
     reset(input: string, state?: LexerState): void;
     /**
      * Classify a single line of markdown text (Phase B).

package/dist/{PackageCompatibility-BGXSFuL9.d.ts → PackageCompatibility-BludTs7v.d.ts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-BRoVOYzg.js';
+import { I as IEnginePackage } from './PackageRegistry-DT-x32OM.js';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageCompatibility-BZCqaTOO.d.cts → PackageCompatibility-CUVg8tmt.d.cts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-rMGnTh7W.cjs';
+import { I as IEnginePackage } from './PackageRegistry-Dvn4i2QK.cjs';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageRegistry-BRoVOYzg.d.ts → PackageRegistry-DT-x32OM.d.ts}

@@ -1,15 +1,15 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-B-WyUtX4.js';
-import { V as Value, b as ValueType } from './Value-DCTqTSeP.js';
-import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-CqagTewQ.js';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-DqTbbtWA.js';
+import { V as Value, a as ValueType } from './Value-Ds3Gy07C.js';
+import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-Bmctxl0n.js';
 import { IAsyncResolver } from './resolvers.js';
-import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-OTPS0Otq.js';
-import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-gB9UengK.js';
-import { a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.js';
+import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-CLBtiE8M.js';
+import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-B636am7Y.js';
+import { a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.js';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-DTk7I7hZ.js';
-import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-QIT4iD8f.js';
+import { E as EngineError } from './EngineError-fR1K1rvx.js';
+import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-DTqGLPsV.js';
 import { T as Token } from './Token-CbP_OutD.js';
-import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-BGQn-cJ8.js';
+import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-DnzYPmoK.js';
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -728,9 +728,10 @@ declare class AsyncResolutionBatcher {
      * Nullable rather than a constructor parameter because it is cleared by
      * `clearAll()` and re-wired on re-subscribe, so it cannot be readonly. That
      * makes it easy to miss, which is why {@link warnIfUnwired} exists: leaving
-     * it unset means async values resolve into the cache and are never shown,
-     * with nothing to indicate why. A host that genuinely does not want async
-     * results should not register async resolvers at all.
+     * it unset, with nobody reading {@link getEventStream} either, means async
+     * values resolve into the cache and are never shown, with nothing to
+     * indicate why. A host that genuinely does not want async results should
+     * not register async resolvers at all.
      */
     onLineResult: ((lineNumber: number, value: Value) => void) | null;
     /**
@@ -742,11 +743,15 @@ declare class AsyncResolutionBatcher {
      */
     private warnedAboutMissingHook;
     /**
-     * Warn once if an async result resolved with no {@link onLineResult} wired.
+     * Warn once if an async result resolved with nobody to receive it: no
+     * {@link onLineResult} wired and no reader on {@link getEventStream}.
      *
      * The failure this catches is silent by nature: the value arrives, the cache
      * updates, and the line keeps showing pending forever. Without this a host
-     * author has no thread to pull on.
+     * author has no thread to pull on. A host reading the event stream is not
+     * in that position: the stream is the documented way to learn which lines
+     * to re-evaluate, and this used to warn at it anyway, telling it to set a
+     * hook it did not need.
      */
     private warnIfUnwired;
     /** High-water mark used when (re)creating the event stream. */
@@ -1635,6 +1640,13 @@ declare class ExpressionEngine {
      * every `name(` call word instead of one rule per package.
      */
     private callFusions;
+    /**
+     * Which packages claim each call-fusion word, in registration order. The
+     * newest claim is the one {@link callFusions} holds; removing a package
+     * hands the word back to the previous claimant rather than deleting it
+     * for both.
+     */
+    private callFusionOwners;
     /**
      * Incremental index behind the package-compatibility check. Kept in step
      * with {@link registeredPackages} so each `registerPackage` costs O(that
@@ -1801,6 +1813,45 @@ declare class ExpressionEngine {
     /** TanStack Query client, injected into resolvers for cache reads/writes. */
     readonly queryClient: QueryClient;
     private bytecodeCache;
+    /**
+     * What the front half of the pipeline produced for a cached program: the
+     * normalised tokens the program was compiled from and the reads and
+     * writes extracted from them. Keyed like {@link bytecodeCache} and kept
+     * in step with it (same eviction, same clears), so a hit here means a hit
+     * there.
+     *
+     * A bytecode-cache hit used to pay for the whole front half anyway: the
+     * length check, lexing, normalising, the complexity score, the three
+     * effectful-grammar tries and the reads/writes extraction all ran before
+     * `bytecodeCache.get`, and on a cache-hit evaluation of an ordinary line
+     * lexing and normalising were about two fifths of the cost. Everything
+     * the later stages read from the front half is remembered here instead,
+     * so a hit skips straight to the async preflight and the VM. Entries
+     * restored from a snapshot carry a program but no front half; the first
+     * evaluation after a restore runs the full front half once and fills it.
+     * The memory is a few hundred bytes per cached expression, bounded by the
+     * same `defaultCacheSize` as the programs.
+     */
+    private compiledFrontHalf;
+    /**
+     * Expressions whose last parse threw, with what the front half produced
+     * for them. A line that does not parse is the ordinary state of a line
+     * being typed, and every re-evaluation of the document lexed, normalised
+     * and re-parsed it, paying for the throw each time. The entry is used
+     * only after the effectful-grammar tries, which still run because they
+     * read the VM (a stored equation, a running total), so nothing that
+     * depends on document state is skipped: only the pure front half and the
+     * parse that is known to fail. The error object is the one first thrown,
+     * so its timestamp is the first failure's. Cleared with the compiled
+     * caches, because the vocabulary and parselet changes that would change
+     * a program can change whether a line parses at all. Bounded by the same
+     * `defaultCacheSize` as the programs.
+     */
+    private failedParses;
+    /** Whether `expression` can be answered without lexing or normalising: both compiled caches hold it, or its parse is known to fail. */
+    private frontHalfCached;
+    /** Drop every cached program, its front half and every remembered parse failure. Every invalidation goes through here so the three cannot drift. */
+    private clearCompiledCache;
     /**
      * Insert into the bytecode cache, evicting the oldest entry when full.
      *
@@ -1813,6 +1864,8 @@ declare class ExpressionEngine {
      * the bytecode-cache benefit on re-evaluation regardless of config.
      */
     private cacheBytecode;
+    /** Remember a parse failure, evicting the oldest when full: bounded like the program cache. */
+    private rememberFailedParse;
     private pluginFunctionIndexByName;
     private builderPool;
     private builderPoolIndex;

package/dist/{PackageRegistry-rMGnTh7W.d.cts → PackageRegistry-Dvn4i2QK.d.cts}

@@ -1,15 +1,15 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-Bkbp9CKD.cjs';
-import { V as Value, b as ValueType } from './Value-DCTqTSeP.cjs';
-import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-CCHFDcgP.cjs';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-BawfGuTF.cjs';
+import { V as Value, a as ValueType } from './Value-Ds3Gy07C.cjs';
+import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-aB95pjoX.cjs';
 import { IAsyncResolver } from './resolvers.cjs';
-import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-MXaKLJ_m.cjs';
-import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-bCYewWVt.cjs';
-import { a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.cjs';
+import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-CjTDmHgB.cjs';
+import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-CdwX0VTw.cjs';
+import { a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.cjs';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-DTk7I7hZ.cjs';
-import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-B4wf3M1h.cjs';
+import { E as EngineError } from './EngineError-fR1K1rvx.cjs';
+import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-69q2tsLE.cjs';
 import { T as Token } from './Token-CbP_OutD.cjs';
-import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-BGQn-cJ8.cjs';
+import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-DnzYPmoK.cjs';
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -728,9 +728,10 @@ declare class AsyncResolutionBatcher {
      * Nullable rather than a constructor parameter because it is cleared by
      * `clearAll()` and re-wired on re-subscribe, so it cannot be readonly. That
      * makes it easy to miss, which is why {@link warnIfUnwired} exists: leaving
-     * it unset means async values resolve into the cache and are never shown,
-     * with nothing to indicate why. A host that genuinely does not want async
-     * results should not register async resolvers at all.
+     * it unset, with nobody reading {@link getEventStream} either, means async
+     * values resolve into the cache and are never shown, with nothing to
+     * indicate why. A host that genuinely does not want async results should
+     * not register async resolvers at all.
      */
     onLineResult: ((lineNumber: number, value: Value) => void) | null;
     /**
@@ -742,11 +743,15 @@ declare class AsyncResolutionBatcher {
      */
     private warnedAboutMissingHook;
     /**
-     * Warn once if an async result resolved with no {@link onLineResult} wired.
+     * Warn once if an async result resolved with nobody to receive it: no
+     * {@link onLineResult} wired and no reader on {@link getEventStream}.
      *
      * The failure this catches is silent by nature: the value arrives, the cache
      * updates, and the line keeps showing pending forever. Without this a host
-     * author has no thread to pull on.
+     * author has no thread to pull on. A host reading the event stream is not
+     * in that position: the stream is the documented way to learn which lines
+     * to re-evaluate, and this used to warn at it anyway, telling it to set a
+     * hook it did not need.
      */
     private warnIfUnwired;
     /** High-water mark used when (re)creating the event stream. */
@@ -1635,6 +1640,13 @@ declare class ExpressionEngine {
      * every `name(` call word instead of one rule per package.
      */
     private callFusions;
+    /**
+     * Which packages claim each call-fusion word, in registration order. The
+     * newest claim is the one {@link callFusions} holds; removing a package
+     * hands the word back to the previous claimant rather than deleting it
+     * for both.
+     */
+    private callFusionOwners;
     /**
      * Incremental index behind the package-compatibility check. Kept in step
      * with {@link registeredPackages} so each `registerPackage` costs O(that
@@ -1801,6 +1813,45 @@ declare class ExpressionEngine {
     /** TanStack Query client, injected into resolvers for cache reads/writes. */
     readonly queryClient: QueryClient;
     private bytecodeCache;
+    /**
+     * What the front half of the pipeline produced for a cached program: the
+     * normalised tokens the program was compiled from and the reads and
+     * writes extracted from them. Keyed like {@link bytecodeCache} and kept
+     * in step with it (same eviction, same clears), so a hit here means a hit
+     * there.
+     *
+     * A bytecode-cache hit used to pay for the whole front half anyway: the
+     * length check, lexing, normalising, the complexity score, the three
+     * effectful-grammar tries and the reads/writes extraction all ran before
+     * `bytecodeCache.get`, and on a cache-hit evaluation of an ordinary line
+     * lexing and normalising were about two fifths of the cost. Everything
+     * the later stages read from the front half is remembered here instead,
+     * so a hit skips straight to the async preflight and the VM. Entries
+     * restored from a snapshot carry a program but no front half; the first
+     * evaluation after a restore runs the full front half once and fills it.
+     * The memory is a few hundred bytes per cached expression, bounded by the
+     * same `defaultCacheSize` as the programs.
+     */
+    private compiledFrontHalf;
+    /**
+     * Expressions whose last parse threw, with what the front half produced
+     * for them. A line that does not parse is the ordinary state of a line
+     * being typed, and every re-evaluation of the document lexed, normalised
+     * and re-parsed it, paying for the throw each time. The entry is used
+     * only after the effectful-grammar tries, which still run because they
+     * read the VM (a stored equation, a running total), so nothing that
+     * depends on document state is skipped: only the pure front half and the
+     * parse that is known to fail. The error object is the one first thrown,
+     * so its timestamp is the first failure's. Cleared with the compiled
+     * caches, because the vocabulary and parselet changes that would change
+     * a program can change whether a line parses at all. Bounded by the same
+     * `defaultCacheSize` as the programs.
+     */
+    private failedParses;
+    /** Whether `expression` can be answered without lexing or normalising: both compiled caches hold it, or its parse is known to fail. */
+    private frontHalfCached;
+    /** Drop every cached program, its front half and every remembered parse failure. Every invalidation goes through here so the three cannot drift. */
+    private clearCompiledCache;
     /**
      * Insert into the bytecode cache, evicting the oldest entry when full.
      *
@@ -1813,6 +1864,8 @@ declare class ExpressionEngine {
      * the bytecode-cache benefit on re-evaluation regardless of config.
      */
     private cacheBytecode;
+    /** Remember a parse failure, evicting the oldest when full: bounded like the program cache. */
+    private rememberFailedParse;
     private pluginFunctionIndexByName;
     private builderPool;
     private builderPoolIndex;

package/dist/{Parselet-Bkbp9CKD.d.cts → Parselet-BawfGuTF.d.cts}

@@ -1,6 +1,6 @@
-import { B as BytecodeBuilder } from './BytecodeBuilder-aqVa7Plx.cjs';
+import { B as BytecodeBuilder } from './BytecodeBuilder-DSWKZi4f.cjs';
 import { T as Token } from './Token-CbP_OutD.cjs';
-import { D as DiagnosticPipeline } from './pipeline-B4wf3M1h.cjs';
+import { D as DiagnosticPipeline } from './pipeline-69q2tsLE.cjs';
 
 /**
  * Dual-keyed ParseletRegistry, accepts both string token types and
@@ -222,6 +222,8 @@ declare class PrecedenceParser {
      * @param _builder - accepted for parselet API compatibility; always uses `this.builder`.
      */
     parseExpression(minBp?: number, _builder?: BytecodeBuilder): void;
+    /** The prefix and infix loop of {@link parseExpression}, run with the depth already counted and the builder in place. */
+    private parseExpressionBody;
     /**
      * Parse a prefix token. Built-in tokens (NUMBER, IDENT, LPAREN, etc.) are
      * handled inline with zero registry lookup. Everything else falls through
@@ -300,6 +302,10 @@ declare class PrecedenceParser {
     private consumeParamName;
     private parseUserFunctionDefinition;
     private parseUserFunctionCall;
+    /** The source span of `token`: where an editor underlines the error. */
+    private spanOf;
+    /** An empty span just after the last token: where a line that stops short is pointed at. */
+    private spanAtEnd;
     consume(expectedType?: string): Token;
     match(expectedType: string): boolean;
     peek(): Token | undefined;

package/dist/{Parselet-B-WyUtX4.d.ts → Parselet-DqTbbtWA.d.ts}

@@ -1,6 +1,6 @@
-import { B as BytecodeBuilder } from './BytecodeBuilder-aqVa7Plx.js';
+import { B as BytecodeBuilder } from './BytecodeBuilder-DSWKZi4f.js';
 import { T as Token } from './Token-CbP_OutD.js';
-import { D as DiagnosticPipeline } from './pipeline-QIT4iD8f.js';
+import { D as DiagnosticPipeline } from './pipeline-DTqGLPsV.js';
 
 /**
  * Dual-keyed ParseletRegistry, accepts both string token types and
@@ -222,6 +222,8 @@ declare class PrecedenceParser {
      * @param _builder - accepted for parselet API compatibility; always uses `this.builder`.
      */
     parseExpression(minBp?: number, _builder?: BytecodeBuilder): void;
+    /** The prefix and infix loop of {@link parseExpression}, run with the depth already counted and the builder in place. */
+    private parseExpressionBody;
     /**
      * Parse a prefix token. Built-in tokens (NUMBER, IDENT, LPAREN, etc.) are
      * handled inline with zero registry lookup. Everything else falls through
@@ -300,6 +302,10 @@ declare class PrecedenceParser {
     private consumeParamName;
     private parseUserFunctionDefinition;
     private parseUserFunctionCall;
+    /** The source span of `token`: where an editor underlines the error. */
+    private spanOf;
+    /** An empty span just after the last token: where a line that stops short is pointed at. */
+    private spanAtEnd;
     consume(expectedType?: string): Token;
     match(expectedType: string): boolean;
     peek(): Token | undefined;

package/dist/{ScopeManager-gB9UengK.d.ts → ScopeManager-B636am7Y.d.ts}

@@ -1,7 +1,7 @@
-import { V as Value } from './Value-DCTqTSeP.js';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.js';
-import { E as EngineError } from './EngineError-DTk7I7hZ.js';
-import { D as DiagnosticPipeline } from './pipeline-QIT4iD8f.js';
+import { V as Value } from './Value-Ds3Gy07C.js';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.js';
+import { E as EngineError } from './EngineError-fR1K1rvx.js';
+import { D as DiagnosticPipeline } from './pipeline-DTqGLPsV.js';
 
 /**
  * Create a new VM instance with the given opcode registry and configurable limits.
@@ -76,6 +76,13 @@ interface Bytecode {
 interface LineExecutionContext {
     /** 1-based current line number, or -1 when there is no real document (see class doc above). */
     lineIndex: number;
+    /**
+     * Whether this engine may fetch live data (`network.enabled`). A plugin
+     * function that reads a resolver's cache uses it to say "live data is
+     * switched off" when the cache is empty, rather than the "not preflighted"
+     * message that describes a different fault. Absent means enabled.
+     */
+    networkEnabled?: boolean;
     /** Look up another line's cached result by 1-based line number. `undefined` = not evaluated yet (or out of range), distinct from a line that evaluated to an actual `undefined`-like Value, which can't happen (every Value type has a concrete representation). */
     getLineResult?: (lineNumber: number) => Value | undefined;
     /** Whether line `lineNumber` is a blank line or a `#` heading, the stopping condition for "total above"/"sum above"/"average above" aggregation. */
@@ -250,6 +257,17 @@ interface EngineContext {
      * nowhere.
      */
     readonly pluginFunctionOwners: Record<number, string>;
+    /**
+     * Whether this engine may fetch live data, from `network.enabled` in the
+     * engine's configuration.
+     *
+     * Lives on the context rather than only on the engine because the VM is
+     * where a plugin function's promise is first seen and where a currency
+     * conversion discovers it has no rate. Both need to answer "live data is
+     * switched off" rather than "no rate available" or "result discarded", and
+     * the context is the one object every VM already holds.
+     */
+    readonly networkEnabled: boolean;
 }
 
 /**
@@ -356,15 +374,28 @@ declare class OpRegistry {
  * and abort signal management for async cancellation.
  */
 interface VM {
+    /**
+     * Push a value.
+     *
+     * @throws `STACK_LIMIT_EXCEEDED` (EXECUTION) when the stack is already at
+     *   `maxStackDepth`. It used to drop the value silently, so a handler's
+     *   result vanished and the next opcode read whatever lay beneath.
+     */
     push(value: Value): void;
+    /**
+     * Pop the top of the stack.
+     *
+     * @throws `STACK_UNDERFLOW` (INTERNAL) if the stack is empty. It used to
+     *   answer with a plain `0`, which is indistinguishable from a real zero
+     *   and turned a mismatched push/pop count into a wrong number.
+     */
     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.
+     * @throws `STACK_UNDERFLOW` (INTERNAL) if the stack is empty, exactly as
+     *   `pop()` does. Every Value converts, so there is no operand-type throw
+     *   here.
      */
     popNumber(): number;
     /**