solve-engine 2.23.0 → 2.24.0

package/README.md

@@ -52,8 +52,14 @@ const value = engine.evaluateExpression("2 + 2 * 10");
 console.log(value.toNumber()); // 22
 ```
 
-`evaluateExpression` throws an `EngineError` (see `solve-engine/errors`) on a parse or
-evaluation failure, wrap calls with untrusted input in a `try`/`catch`.
+Two kinds of failure, deliberately different. A line the parser cannot read
+(`10 +`), or one that names a variable no line defined, throws an `EngineError`
+(see `solve-engine/errors`), so wrap calls on untrusted input in a `try`/`catch`.
+A line the engine can run but cannot answer (an impossible conversion, a rate it
+has no data for, a live value still loading) comes back as a `Value` whose
+`isError()` or `isPending()` says so, never as a throw, which is the right shape
+for input being typed one character at a time. Check `isFault()` before
+`toNumber()`: a faulted value reads as `0` through it.
 
 For line-oriented input (e.g. a document made of multiple expressions, some referencing
 variables defined on earlier lines), use `evaluateLine`/`parseDocument` instead, see the
@@ -104,13 +110,15 @@ they are:
 
 | Subpath | Purpose |
 |---|---|
-| `solve-engine` | Start here, `ExpressionEngine`, `createEngine`, `IEnginePackage`. |
+| `solve-engine` | Start here: `createEngine`, `ExpressionEngine`, `defineFunction`, `IEnginePackage`, and the result surface `Value`, `ValueType`, `formatValue`. |
 | `solve-engine/engine` | `ExpressionEngine` and its supporting types (`Explanation`, `EngineSnapshot`, etc.) directly, without the package-registration wrapper. |
-| `solve-engine/vm` | The bytecode VM: `Value`/`ValueType`, opcode dispatch, `allocatePluginFunctionIndex`. |
-| `solve-engine/format` | Turning a `Value` into a display string (numbers, dates, units, vectors, ...). |
+| `solve-engine/vm` | The bytecode VM: `Value`/`ValueType`, the value constructors, opcode dispatch. |
+| `solve-engine/format` | Turning a `Value` into a display string (numbers, dates, units, vectors, ...) and the formatting settings. |
 | `solve-engine/language` | Editor-agnostic language service: token categories, completions, highlighting. |
 | `solve-engine/packages` | The built-in packages (arithmetic, datetime, time, dice, uom, currency, vector, conditionals, converters, mathphrases, ...). |
-| `solve-engine/constants` | Engine configuration types and defaults (`EngineConfig`, `VMConfig`, ...). |
+| `solve-engine/constants` | Engine configuration types and defaults (`EngineConfig`, `VMConfig`, `NetworkConfig`, ...). |
+| `solve-engine/worker` | Off-main-thread evaluation: `createWorkerEngine`, `startWorkerRuntime`, the transports and the result DTOs. |
+| `solve-engine/testing` | A test kit for package authors: `createTestEngine`, `expectExpression`, `expectPackage`. |
 
 The following subpaths are **advanced-public**, everything a third-party package author
 needs to extend the engine, but with a looser stability contract than the tier above (these
@@ -132,32 +140,70 @@ Anything not listed above (`telemetry`, `cache`, `diagnostics`, `types`, `worker
 internal and not part of the package's public contract, it may change or disappear between
 minor versions without notice.
 
+## Adding a function
+
+The shortest way to teach the engine a new name is `defineFunction`: declare the
+name, the argument types and the return type, and get back a package that plugs
+in beside the built-ins. No parser, no bytecode.
+
+```typescript
+import { createEngine, defineFunction } from "solve-engine";
+
+const vat = defineFunction({
+  name: "vat",
+  args: [{ name: "amount", type: "number" }],
+  returns: "number",
+  call: (amount) => amount * 1.2,
+});
+
+const engine = createEngine({ extraPackages: [vat] });
+engine.evaluateExpression("vat(100)").toNumber(); // 120
+```
+
+Arguments are a fixed list of `number`, `string` or `boolean`, and `call` is
+synchronous; a mismatched call produces a structured error naming the argument.
+Anything beyond that shape (a unit-bearing argument, a phrase rather than a
+call, live data) is a package proper.
+
 ## Authoring a package
 
-A **package** (`IEnginePackage`) is a plain data descriptor bundling everything needed to
-extend the engine with a new domain: custom tokens, parselets, VM opcode handlers, and
-optional async resolvers. See
-[`solve-engine/api`'s `IEnginePackage`](https://github.com/LiamRiddell/solve-engine/blob/main/packages/engine/src/api/PackageRegistry.ts) for the full field list
-with inline documentation and examples for each field.
+A **package** (`IEnginePackage`) is a plain data descriptor bundling everything
+needed to extend the engine with a new domain: token vocabulary, normaliser
+rules, parselets, plugin functions, `as` converters, completions, and optional
+async resolvers. The [package author guides](https://liamriddell.github.io/solve-engine/packages/authoring-a-package/)
+walk through each extension point; [`IEnginePackage`](https://github.com/LiamRiddell/solve-engine/blob/main/packages/engine/src/api/PackageRegistry.ts)
+carries the full field list with inline documentation.
 
-Minimal shape:
+Minimal shape, a keyword that calls a function:
 
 ```typescript
-import { allocatePluginFunctionIndex } from "solve-engine/vm";
 import type { IEnginePackage } from "solve-engine";
-
-const MY_FN_IDX = allocatePluginFunctionIndex();
+import type { PrefixParselet } from "solve-engine/parser";
+import { stringValue } from "solve-engine/vm";
+
+const reverseParselet: PrefixParselet = {
+  category: "Text",
+  parse(parser, _token, builder) {
+    parser.consume("LPAREN");
+    parser.parseExpression(0, builder);
+    parser.consume("RPAREN");
+    // By name; the engine assigns the index when the package registers.
+    builder.emitPluginCall("reverse", 1);
+  },
+};
 
 export const MY_PACKAGE: IEnginePackage = {
-  name: "MyPackage",
-  // engineVersion: "^0.1.0", // optional, see below
-  prefixParselets: [{ tokenType: "MY_FUNC", parselet: new MyParselet() }],
-  pluginFunctions: [{ index: MY_FN_IDX, handler: (args) => /* ... */ }],
+  name: "my-package",
+  // engineVersion: "^2.0.0", // optional, see below
+  lexerVocabulary: { keywords: { reverse: "REVERSE_FN" } },
+  prefixParselets: { REVERSE_FN: reverseParselet },
+  pluginFunctions: { reverse: ([text]) => stringValue([...String(text.value)].reverse().join("")) },
 };
 ```
 
-Register it either as one of the packages passed to the `ExpressionEngine` constructor, or
-at runtime via `ExpressionEngine.registerPackage()` / `unregisterPackage()`.
+Register it as one of the packages passed to the `ExpressionEngine` constructor
+(or `createEngine`'s `extraPackages`), or at runtime via
+`ExpressionEngine.registerPackage()` / `unregisterPackage()`.
 
 ### Declaring engine-version compatibility
 
@@ -210,17 +256,21 @@ published package, see `files` in `package.json`, only `dist/` ships):
 
 ## Known limitations
 
-**Cross-instance isolation is partial.** Plugin functions and the opcode registry are
-now owned per `ExpressionEngine`, so two engines with different package sets no longer
-interfere across those. The lexer and the currency exchange rates
-are still module-level singletons, so full isolation between two engines in one process
-cannot yet be assumed. Tracked as "L1, EngineContext"; three of its five migrations have
-landed and the remaining two are a prerequisite for 1.0.0 proper.
-
-**Async results need a host hook.** `AsyncResolutionBatcher.onLineResult` is the only
-mechanism that patches a resolved async value back into the document model, and it is not
-wired inside the package. A host that does not supply it gets async values that never
-resolve, with no error to explain why.
+**Exchange rates are shared across engines, by design.** Plugin functions, the
+opcode registry and the lexer are owned per `ExpressionEngine`, so two engines
+with different package sets do not interfere. The currency rate cache is the one
+deliberate exception: rates are market data with a fifteen-minute freshness
+window, and two engines in one process fetching the same pair separately could
+disagree about it. A host that primes rates (`currencyExchangeService.primeRates`)
+primes them for every engine in the process.
+
+**A live value reaches the document only through the event stream.** When a
+fetch lands, the engine does not push the new value at you; it emits a
+`lines-updated` event on `engine.getEventStream()` naming the lines to
+re-evaluate. A host that reads neither that stream nor sets
+`AsyncResolutionBatcher.onLineResult` sees the line stay pending, and a warning
+says so once. The [async guide](https://liamriddell.github.io/solve-engine/guide/async-and-live-data/)
+shows the loop.
 
 ## Development
 

package/dist/{Configuration-BGQn-cJ8.d.cts → Configuration-DnzYPmoK.d.cts}

@@ -207,6 +207,37 @@ interface BackgroundRefreshConfig {
     /** Master switch. When false, no timers run and every value refreshes only on re-evaluation. */
     readonly enabled: boolean;
 }
+/**
+ * Whether the engine may reach the network at all.
+ *
+ * On by default, which is the historic behaviour: a city name or a currency
+ * pair in a line fetches live data from a public endpoint as soon as the
+ * line evaluates. A host embedding the engine somewhere that must not make
+ * outbound requests (an offline document, a sandboxed evaluation, a tenant
+ * with egress rules) switches it off here and gets the same engine with no
+ * egress: every live-data form answers with a `NETWORK_DISABLED` error
+ * naming the setting, instead of a request.
+ *
+ * The gate closes before any request is made. It stops every async
+ * resolver a package registers (weather, currency, stocks, crypto,
+ * knowledge, and any host-supplied one) unless the resolver declares
+ * itself `local` (it reads engine state, never a network; the engine's own
+ * global-variable resolver is the one built-in case). It also refuses the
+ * result of a plugin function that returns a promise. That last case is a
+ * boundary rather than a guarantee: such a function has already run by the
+ * time the engine sees the promise, so a package that fetches inside a
+ * plugin function rather than through an async resolver may still have
+ * started its request. The documented shape for live data is the resolver
+ * (`createQueryResolver`), which this gate stops cold.
+ *
+ * Rates a host primes by hand (`currencyExchangeService.primeRates`) keep
+ * working with the network off, which is what an offline host with its own
+ * rate table wants.
+ */
+interface NetworkConfig {
+    /** Master switch. When false, no async resolver runs and no live value is fetched. */
+    readonly enabled: boolean;
+}
 /**
  * Virtual Machine configuration.
  * Controls the internal bytecode VM that executes compiled expressions.
@@ -321,6 +352,8 @@ interface EngineConfig {
     readonly diagnostic: DiagnosticConfig;
     /** Proactive background refresh of live async values */
     readonly backgroundRefresh: BackgroundRefreshConfig;
+    /** Whether live data may be fetched at all. See {@link NetworkConfig}. */
+    readonly network: NetworkConfig;
 }
 /**
  * A partial {@link EngineConfig} override, one section at a time.

package/dist/{Configuration-BGQn-cJ8.d.ts → Configuration-DnzYPmoK.d.ts}

@@ -207,6 +207,37 @@ interface BackgroundRefreshConfig {
     /** Master switch. When false, no timers run and every value refreshes only on re-evaluation. */
     readonly enabled: boolean;
 }
+/**
+ * Whether the engine may reach the network at all.
+ *
+ * On by default, which is the historic behaviour: a city name or a currency
+ * pair in a line fetches live data from a public endpoint as soon as the
+ * line evaluates. A host embedding the engine somewhere that must not make
+ * outbound requests (an offline document, a sandboxed evaluation, a tenant
+ * with egress rules) switches it off here and gets the same engine with no
+ * egress: every live-data form answers with a `NETWORK_DISABLED` error
+ * naming the setting, instead of a request.
+ *
+ * The gate closes before any request is made. It stops every async
+ * resolver a package registers (weather, currency, stocks, crypto,
+ * knowledge, and any host-supplied one) unless the resolver declares
+ * itself `local` (it reads engine state, never a network; the engine's own
+ * global-variable resolver is the one built-in case). It also refuses the
+ * result of a plugin function that returns a promise. That last case is a
+ * boundary rather than a guarantee: such a function has already run by the
+ * time the engine sees the promise, so a package that fetches inside a
+ * plugin function rather than through an async resolver may still have
+ * started its request. The documented shape for live data is the resolver
+ * (`createQueryResolver`), which this gate stops cold.
+ *
+ * Rates a host primes by hand (`currencyExchangeService.primeRates`) keep
+ * working with the network off, which is what an offline host with its own
+ * rate table wants.
+ */
+interface NetworkConfig {
+    /** Master switch. When false, no async resolver runs and no live value is fetched. */
+    readonly enabled: boolean;
+}
 /**
  * Virtual Machine configuration.
  * Controls the internal bytecode VM that executes compiled expressions.
@@ -321,6 +352,8 @@ interface EngineConfig {
     readonly diagnostic: DiagnosticConfig;
     /** Proactive background refresh of live async values */
     readonly backgroundRefresh: BackgroundRefreshConfig;
+    /** Whether live data may be fetched at all. See {@link NetworkConfig}. */
+    readonly network: NetworkConfig;
 }
 /**
  * A partial {@link EngineConfig} override, one section at a time.

package/dist/{EngineError-DTk7I7hZ.d.cts → EngineError-D1kXsjIj.d.cts}

@@ -103,6 +103,8 @@ declare const CoreErrorCodes: {
     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";
+    /** `CALL_BUILTIN` naming an index no builtin is registered at. It used to pop its arguments and push nothing, so the opcode after it read a neighbour's operand as its own; now an Error value on the stack, the shape `map`/`reduce` already used for the same fault. Bytecode-level, so unreachable from source without a compiler or snapshot fault. */
+    readonly UNKNOWN_BUILTIN_FUNCTION: "UNKNOWN_BUILTIN_FUNCTION";
     /** 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. */
@@ -164,6 +166,8 @@ declare const CoreErrorCodes: {
     readonly UNKNOWN_SAVINGS_PERIOD: "UNKNOWN_SAVINGS_PERIOD";
     /** 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";
+    /** A live-data form evaluated on an engine whose host switched the network off (`network.enabled: false`, see `constants/Configuration.ts`'s `NetworkConfig`). A recoverable Error value, raised by the VM for a currency conversion with no primed rate and for a plugin function that returned a promise, and by `createQueryResolver`'s plugin function when its preflight was skipped. Names the setting, so the reader knows it is policy rather than an outage. */
+    readonly NETWORK_DISABLED: "NETWORK_DISABLED";
     /** `fromJSON()` handed an object that is not a snapshot at all, or whose serialised-shape version does not match this engine's reader. The versioning gate that refuses an incompatible snapshot clearly rather than restoring it wrongly. See `engine/EngineSnapshot.ts`'s `assertRestorable()`. */
     readonly SNAPSHOT_VERSION_MISMATCH: "SNAPSHOT_VERSION_MISMATCH";
     /** A snapshot with the right envelope but internally inconsistent contents (an unrecognised number sentinel, an unknown value tag). Distinct from a version mismatch: the format is right, the payload is not. */

package/dist/{EngineError-DTk7I7hZ.d.ts → EngineError-D1kXsjIj.d.ts}

@@ -103,6 +103,8 @@ declare const CoreErrorCodes: {
     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";
+    /** `CALL_BUILTIN` naming an index no builtin is registered at. It used to pop its arguments and push nothing, so the opcode after it read a neighbour's operand as its own; now an Error value on the stack, the shape `map`/`reduce` already used for the same fault. Bytecode-level, so unreachable from source without a compiler or snapshot fault. */
+    readonly UNKNOWN_BUILTIN_FUNCTION: "UNKNOWN_BUILTIN_FUNCTION";
     /** 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. */
@@ -164,6 +166,8 @@ declare const CoreErrorCodes: {
     readonly UNKNOWN_SAVINGS_PERIOD: "UNKNOWN_SAVINGS_PERIOD";
     /** 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";
+    /** A live-data form evaluated on an engine whose host switched the network off (`network.enabled: false`, see `constants/Configuration.ts`'s `NetworkConfig`). A recoverable Error value, raised by the VM for a currency conversion with no primed rate and for a plugin function that returned a promise, and by `createQueryResolver`'s plugin function when its preflight was skipped. Names the setting, so the reader knows it is policy rather than an outage. */
+    readonly NETWORK_DISABLED: "NETWORK_DISABLED";
     /** `fromJSON()` handed an object that is not a snapshot at all, or whose serialised-shape version does not match this engine's reader. The versioning gate that refuses an incompatible snapshot clearly rather than restoring it wrongly. See `engine/EngineSnapshot.ts`'s `assertRestorable()`. */
     readonly SNAPSHOT_VERSION_MISMATCH: "SNAPSHOT_VERSION_MISMATCH";
     /** A snapshot with the right envelope but internally inconsistent contents (an unrecognised number sentinel, an unknown value tag). Distinct from a version mismatch: the format is right, the payload is not. */

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

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

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

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

package/dist/{PackageRegistry-rMGnTh7W.d.cts → PackageRegistry-B9-7fJGH.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 { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-4oH5OuRt.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-CCHFDcgP.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 { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-DrXB3Nvm.cjs';
 import { a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.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-D1kXsjIj.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. */

package/dist/{PackageRegistry-BRoVOYzg.d.ts → PackageRegistry-CDEgfhT_.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 { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-BwDqKFfK.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-CqagTewQ.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 { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-BQBhlDAu.js';
 import { a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.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-D1kXsjIj.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. */

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

@@ -1,6 +1,6 @@
 import { B as BytecodeBuilder } from './BytecodeBuilder-aqVa7Plx.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

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

@@ -1,6 +1,6 @@
 import { B as BytecodeBuilder } from './BytecodeBuilder-aqVa7Plx.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

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

@@ -1,7 +1,7 @@
-import { V as Value } from './Value-DCTqTSeP.js';
+import { V as Value } from './Value-Ds3Gy07C.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 { E as EngineError } from './EngineError-D1kXsjIj.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;
     /**

package/dist/{ScopeManager-bCYewWVt.d.cts → ScopeManager-DrXB3Nvm.d.cts}

@@ -1,7 +1,7 @@
-import { V as Value } from './Value-DCTqTSeP.cjs';
+import { V as Value } from './Value-Ds3Gy07C.cjs';
 import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.cjs';
-import { E as EngineError } from './EngineError-DTk7I7hZ.cjs';
-import { D as DiagnosticPipeline } from './pipeline-B4wf3M1h.cjs';
+import { E as EngineError } from './EngineError-D1kXsjIj.cjs';
+import { D as DiagnosticPipeline } from './pipeline-69q2tsLE.cjs';
 
 /**
  * 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;
     /**

package/dist/{VMCheckpoints-DGar9Yg8.d.cts → VMCheckpoints-BK32PTl2.d.cts}

@@ -1,5 +1,5 @@
-import { V as Value } from './Value-DCTqTSeP.cjs';
-import { V as VM } from './ScopeManager-bCYewWVt.cjs';
+import { V as Value } from './Value-Ds3Gy07C.cjs';
+import { V as VM } from './ScopeManager-DrXB3Nvm.cjs';
 import { U as UserFunctionDef } from './BytecodeBuilder-aqVa7Plx.cjs';
 
 /**

package/dist/{VMCheckpoints-BDRY1Kx8.d.ts → VMCheckpoints-C5jC92o3.d.ts}

@@ -1,5 +1,5 @@
-import { V as Value } from './Value-DCTqTSeP.js';
-import { V as VM } from './ScopeManager-gB9UengK.js';
+import { V as Value } from './Value-Ds3Gy07C.js';
+import { V as VM } from './ScopeManager-BQBhlDAu.js';
 import { U as UserFunctionDef } from './BytecodeBuilder-aqVa7Plx.js';
 
 /**

package/dist/{Value-DCTqTSeP.d.cts → Value-Ds3Gy07C.d.cts}

@@ -533,4 +533,4 @@ declare function colVectorValue(data: readonly number[]): Value;
 /** Create a Range value, a first-class integer range `min:max`, both bounds inclusive. */
 declare function rangeValue(min: number, max: number): Value;
 
-export { type ColourData as C, type IpCidrData as I, type MatrixData as M, type RangeData as R, type SplitData as S, Value as V, type MatrixEntry as a, ValueType as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, type ChartData as f, type SymbolicNode as g, hexValue as h, type ColourFormat as i, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };
+export { type ColourData as C, type IpCidrData as I, type MatrixData as M, type RangeData as R, type SplitData as S, Value as V, ValueType as a, type MatrixEntry as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, type ChartData as f, type SymbolicNode as g, hexValue as h, type ColourFormat as i, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };

package/dist/{Value-DCTqTSeP.d.ts → Value-Ds3Gy07C.d.ts}

@@ -533,4 +533,4 @@ declare function colVectorValue(data: readonly number[]): Value;
 /** Create a Range value, a first-class integer range `min:max`, both bounds inclusive. */
 declare function rangeValue(min: number, max: number): Value;
 
-export { type ColourData as C, type IpCidrData as I, type MatrixData as M, type RangeData as R, type SplitData as S, Value as V, type MatrixEntry as a, ValueType as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, type ChartData as f, type SymbolicNode as g, hexValue as h, type ColourFormat as i, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };
+export { type ColourData as C, type IpCidrData as I, type MatrixData as M, type RangeData as R, type SplitData as S, Value as V, ValueType as a, type MatrixEntry as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, type ChartData as f, type SymbolicNode as g, hexValue as h, type ColourFormat as i, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };