solve-engine 1.0.0-beta.6 → 1.0.0

package/dist/vm.cjs

@@ -1,17 +1,17 @@
 'use strict';
 
-var chunkQDMPOAI7_cjs = require('./chunk-QDMPOAI7.cjs');
+var chunkHDP7VK3C_cjs = require('./chunk-HDP7VK3C.cjs');
 require('./chunk-47LRVGOT.cjs');
-var chunkBXKJLM5R_cjs = require('./chunk-BXKJLM5R.cjs');
+var chunk6WFMPTGB_cjs = require('./chunk-6WFMPTGB.cjs');
 require('./chunk-FEAIOR7N.cjs');
-require('./chunk-2MV4HBKC.cjs');
-require('./chunk-MZOVP3WI.cjs');
+require('./chunk-A2N2GFCG.cjs');
+require('./chunk-6KFYJ6TD.cjs');
 require('./chunk-VEKIWQ3F.cjs');
-require('./chunk-4CVLFLOB.cjs');
-var chunkOC6LTXYS_cjs = require('./chunk-OC6LTXYS.cjs');
-require('./chunk-NJTXJ5AG.cjs');
-require('./chunk-MBNQVDVC.cjs');
-require('./chunk-M4N5GA5Z.cjs');
+require('./chunk-UM6BVY2S.cjs');
+var chunkJMXUNXQS_cjs = require('./chunk-JMXUNXQS.cjs');
+require('./chunk-PFUESQTW.cjs');
+require('./chunk-AMOJYLG2.cjs');
+require('./chunk-5KMIY374.cjs');
 require('./chunk-B7LXJ6LC.cjs');
 
 // src/vm/VMCheckpoints.ts
@@ -193,91 +193,103 @@ var VMCheckpointer = class {
 
 Object.defineProperty(exports, "DependencyGraph", {
   enumerable: true,
-  get: function () { return chunkQDMPOAI7_cjs.DependencyGraph; }
+  get: function () { return chunkHDP7VK3C_cjs.DependencyGraph; }
 });
 Object.defineProperty(exports, "ScopeManager", {
   enumerable: true,
-  get: function () { return chunkQDMPOAI7_cjs.ScopeManager; }
+  get: function () { return chunkHDP7VK3C_cjs.ScopeManager; }
 });
 Object.defineProperty(exports, "createVM", {
   enumerable: true,
-  get: function () { return chunkQDMPOAI7_cjs.createVM; }
+  get: function () { return chunkHDP7VK3C_cjs.createVM; }
 });
 Object.defineProperty(exports, "executeBytecode", {
   enumerable: true,
-  get: function () { return chunkQDMPOAI7_cjs.executeBytecode; }
+  get: function () { return chunkHDP7VK3C_cjs.executeBytecode; }
 });
 Object.defineProperty(exports, "OpRegistry", {
   enumerable: true,
-  get: function () { return chunkBXKJLM5R_cjs.OpRegistry; }
+  get: function () { return chunk6WFMPTGB_cjs.OpRegistry; }
 });
 Object.defineProperty(exports, "allocatePluginFunctionIndex", {
   enumerable: true,
-  get: function () { return chunkBXKJLM5R_cjs.allocatePluginFunctionIndex; }
+  get: function () { return chunk6WFMPTGB_cjs.allocatePluginFunctionIndex; }
 });
 Object.defineProperty(exports, "binaryOp", {
   enumerable: true,
-  get: function () { return chunkBXKJLM5R_cjs.binaryOp; }
+  get: function () { return chunk6WFMPTGB_cjs.binaryOp; }
 });
 Object.defineProperty(exports, "builtinFunctions", {
   enumerable: true,
-  get: function () { return chunkBXKJLM5R_cjs.builtinFunctions; }
+  get: function () { return chunk6WFMPTGB_cjs.builtinFunctions; }
 });
 Object.defineProperty(exports, "pluginFunctionRegistry", {
   enumerable: true,
-  get: function () { return chunkBXKJLM5R_cjs.pluginFunctionRegistry; }
+  get: function () { return chunk6WFMPTGB_cjs.pluginFunctionRegistry; }
 });
 Object.defineProperty(exports, "sharedOpRegistry", {
   enumerable: true,
-  get: function () { return chunkBXKJLM5R_cjs.sharedOpRegistry; }
+  get: function () { return chunk6WFMPTGB_cjs.sharedOpRegistry; }
 });
 Object.defineProperty(exports, "unifyUom", {
   enumerable: true,
-  get: function () { return chunkBXKJLM5R_cjs.unifyUom; }
+  get: function () { return chunk6WFMPTGB_cjs.unifyUom; }
 });
 Object.defineProperty(exports, "Value", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.Value; }
+  get: function () { return chunkJMXUNXQS_cjs.Value; }
 });
 Object.defineProperty(exports, "ValueType", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.ValueType; }
+  get: function () { return chunkJMXUNXQS_cjs.ValueType; }
 });
 Object.defineProperty(exports, "bigIntValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.bigIntValue; }
+  get: function () { return chunkJMXUNXQS_cjs.bigIntValue; }
+});
+Object.defineProperty(exports, "chargeAllocation", {
+  enumerable: true,
+  get: function () { return chunkJMXUNXQS_cjs.chargeAllocation; }
+});
+Object.defineProperty(exports, "checkAllocation", {
+  enumerable: true,
+  get: function () { return chunkJMXUNXQS_cjs.checkAllocation; }
+});
+Object.defineProperty(exports, "checkedArray", {
+  enumerable: true,
+  get: function () { return chunkJMXUNXQS_cjs.checkedArray; }
 });
 Object.defineProperty(exports, "colVectorValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.colVectorValue; }
+  get: function () { return chunkJMXUNXQS_cjs.colVectorValue; }
 });
 Object.defineProperty(exports, "hexValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.hexValue; }
+  get: function () { return chunkJMXUNXQS_cjs.hexValue; }
 });
 Object.defineProperty(exports, "matrixValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.matrixValue; }
+  get: function () { return chunkJMXUNXQS_cjs.matrixValue; }
 });
 Object.defineProperty(exports, "numberValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.numberValue; }
+  get: function () { return chunkJMXUNXQS_cjs.numberValue; }
 });
 Object.defineProperty(exports, "rangeValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.rangeValue; }
+  get: function () { return chunkJMXUNXQS_cjs.rangeValue; }
 });
 Object.defineProperty(exports, "rowVectorValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.rowVectorValue; }
+  get: function () { return chunkJMXUNXQS_cjs.rowVectorValue; }
 });
 Object.defineProperty(exports, "stringValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.stringValue; }
+  get: function () { return chunkJMXUNXQS_cjs.stringValue; }
 });
 Object.defineProperty(exports, "uomValue", {
   enumerable: true,
-  get: function () { return chunkOC6LTXYS_cjs.uomValue; }
+  get: function () { return chunkJMXUNXQS_cjs.uomValue; }
 });
 exports.VMCheckpointer = VMCheckpointer;
 //# sourceMappingURL=vm.cjs.map

package/dist/vm.d.cts

@@ -1,13 +1,109 @@
-import { P as PluginFunctionHandler } from './ScopeManager-CKfQtl7l.cjs';
-export { B as Bytecode, D as DependencyGraph, E as ExpressionRecord, O as OpRegistry, S as ScopeManager, V as VM, c as createVM, e as executeBytecode, s as sharedOpRegistry } from './ScopeManager-CKfQtl7l.cjs';
-import { V as Value } from './Value-KtAQNHur.cjs';
-export { M as MatrixData, a as MatrixEntry, R as RangeData, b as ValueType, c as bigIntValue, d as colVectorValue, h as hexValue, m as matrixValue, n as numberValue, r as rangeValue, e as rowVectorValue, s as stringValue, u as uomValue } from './Value-KtAQNHur.cjs';
-export { V as VMCheckpoint, a as VMCheckpointer } from './VMCheckpoints-CqFuLwrT.cjs';
-import './BytecodeBuilder-3egMyuDi.cjs';
-import './EngineError-DvPSnhZi.cjs';
-import './pipeline-DPUQt7yL.cjs';
+import { P as PluginFunctionHandler } from './ScopeManager-B6GzdhVG.cjs';
+export { B as Bytecode, a as DependencyGraph, E as ExpressionRecord, O as OpRegistry, S as ScopeManager, V as VM, c as createVM, e as executeBytecode, s as sharedOpRegistry } from './ScopeManager-B6GzdhVG.cjs';
+import { V as Value } from './Value-CXJqDH9J.cjs';
+export { M as MatrixData, a as MatrixEntry, R as RangeData, b as ValueType, c as bigIntValue, d as colVectorValue, h as hexValue, m as matrixValue, n as numberValue, r as rangeValue, e as rowVectorValue, s as stringValue, u as uomValue } from './Value-CXJqDH9J.cjs';
+export { a as VMCheckpoint, V as VMCheckpointer } from './VMCheckpoints-DwLjivM7.cjs';
+import './BytecodeBuilder-B0xskcv5.cjs';
+import './EngineError-LU7W7AgI.cjs';
+import './pipeline-BEb3hujr.cjs';
 import './variables.cjs';
 
+/**
+ * The ceiling on how much memory one evaluation is allowed to ask for.
+ *
+ * The VM's other two counters bound how many opcodes run and how deep the value
+ * stack gets, and both are checked BETWEEN opcodes. That leaves a hole the size
+ * of a single opcode: whatever one opcode allocates in a loop of its own is
+ * invisible to both, so twenty-four characters of input (`map(10*x,
+ * 0:2000000000)`) could allocate until V8 aborted the process, which no
+ * `try`/`catch` in the host can contain. Per-site caps close one hole each and
+ * do not compose: two collections that are individually legal are legal
+ * together, and an operation whose result is the PRODUCT of two legal inputs (a
+ * matrix multiply) is bounded by neither of them.
+ *
+ * This is the counter that composes. Everything an evaluation materialises is
+ * charged against one running tally, so the bound is on the total rather than
+ * on any single step, and a new opcode inherits it by allocating through
+ * {@link chargedArray} or by building a Value through a constructor that
+ * already charges ({@link matrixValue}).
+ *
+ * The tally is module state rather than something threaded through every
+ * signature. `executeBytecode()` opens an evaluation and every charge inside
+ * that window lands on it, which is what lets a helper five call levels down
+ * (`vm/MatrixOps.ts`'s `collectionToValues()`) charge without the four frames
+ * in between passing a parameter along, and what keeps a charge down to an add
+ * and a compare. This mirrors the value arena in `vm/Value.ts`, which is
+ * ambient for the same reason and rests on the same fact: `executeBytecode()`
+ * is synchronous, so exactly one evaluation is ever in flight in a realm.
+ *
+ * An "element" is one thing a user's input caused to exist: a `Value` in an
+ * expanded collection, a cell in a matrix. They are counted rather than
+ * measured in bytes, because a count is the quantity every call site already
+ * has in hand before it allocates, and asking V8 how big something is costs
+ * more than the allocation being guarded.
+ *
+ * A second tally lives here for the same structural reason and not because it
+ * counts the same thing: {@link chargeFunctionCall} bounds how many
+ * user-defined-function calls one evaluation may make in total. Surviving
+ * reentry is the whole property both need, and this module is where reentry is
+ * already tracked.
+ *
+ * @module AllocationBudget
+ */
+
+/**
+ * Record elements materialised by the evaluation in flight.
+ *
+ * Each thing is charged exactly once, where it comes into existence: a matrix
+ * in `matrixValue()`, an expanded collection where it is expanded. A site that
+ * knows a size in advance and whose result will be charged on birth uses
+ * {@link checkAllocation} instead, so that refusing early does not mean
+ * counting twice.
+ *
+ * Outside an evaluation this is a plain no-op rather than an error:
+ * `matrixValue()` and the `vm/MatrixOps.ts` helpers are exported and get called
+ * by tests, by the formatter and by hosts with no evaluation in flight, and
+ * none of those is user input being executed.
+ *
+ * @param count - How many elements now exist.
+ * @param what - What they are, in the plural and in a user's words ("matrix
+ * cells", "collection elements"). Quoted verbatim in the error, so it should
+ * name the thing rather than the code that makes it.
+ * @throws `ALLOCATION_LIMIT_EXCEEDED` when this evaluation has had enough.
+ * Recoverable: it describes this expression, not the engine.
+ */
+declare function chargeAllocation(count: number, what: string): void;
+/**
+ * Refuse an allocation this evaluation cannot afford, without recording it.
+ *
+ * For the sites that know how big a result will be BEFORE building it and whose
+ * result is charged later, when it is born. A matrix product is the case that
+ * matters: its size is the product of two operands that are each affordable, so
+ * it has to be refused from the shapes alone, before `matrixMultiply()` takes
+ * the memory. Charging here as well as at birth would bill every matrix twice
+ * and halve the ceiling the host asked for.
+ *
+ * @param count - How many elements the result would have.
+ * @param what - What they are, in the plural. See {@link chargeAllocation}.
+ * @throws `ALLOCATION_LIMIT_EXCEEDED` when the evaluation could not afford them.
+ */
+declare function checkAllocation(count: number, what: string): void;
+/**
+ * Check that an array is affordable, then allocate it.
+ *
+ * The intended way to build any user-sized array inside the VM whose contents
+ * end up inside a Value that charges on birth, so that "ask before you take" is
+ * a property of the allocator rather than something each new opcode has to be
+ * told.
+ *
+ * @param count - Element count, checked before a single element exists.
+ * @param what - What the elements are, in the plural. See {@link chargeAllocation}.
+ * @returns An empty array of that length.
+ * @throws `ALLOCATION_LIMIT_EXCEEDED` before allocating anything, when the
+ * evaluation cannot afford it.
+ */
+declare function checkedArray<T>(count: number, what: string): T[];
+
 /**
  * Registry of built-in mathematical functions.
  * Indexed by the number pushed as an operand of OpCode.CALL_BUILTIN.
@@ -65,4 +161,4 @@ declare function unifyUom(l: Value, r: Value): {
  */
 declare function binaryOp(l: Value, r: Value, op: (a: number, b: number) => number, bigOp?: (a: bigint, b: bigint) => bigint, symbolicOp?: "add" | "sub" | "mul" | "div"): Value;
 
-export { Value, allocatePluginFunctionIndex, binaryOp, builtinFunctions, pluginFunctionRegistry, unifyUom };
+export { Value, allocatePluginFunctionIndex, binaryOp, builtinFunctions, chargeAllocation, checkAllocation, checkedArray, pluginFunctionRegistry, unifyUom };

package/dist/vm.d.ts

@@ -1,13 +1,109 @@
-import { P as PluginFunctionHandler } from './ScopeManager-B5k0nk05.js';
-export { B as Bytecode, D as DependencyGraph, E as ExpressionRecord, O as OpRegistry, S as ScopeManager, V as VM, c as createVM, e as executeBytecode, s as sharedOpRegistry } from './ScopeManager-B5k0nk05.js';
-import { V as Value } from './Value-KtAQNHur.js';
-export { M as MatrixData, a as MatrixEntry, R as RangeData, b as ValueType, c as bigIntValue, d as colVectorValue, h as hexValue, m as matrixValue, n as numberValue, r as rangeValue, e as rowVectorValue, s as stringValue, u as uomValue } from './Value-KtAQNHur.js';
-export { V as VMCheckpoint, a as VMCheckpointer } from './VMCheckpoints-BmDwIXgK.js';
-import './BytecodeBuilder-3egMyuDi.js';
-import './EngineError-DvPSnhZi.js';
-import './pipeline-CrsRPmsv.js';
+import { P as PluginFunctionHandler } from './ScopeManager-udv4Twwq.js';
+export { B as Bytecode, a as DependencyGraph, E as ExpressionRecord, O as OpRegistry, S as ScopeManager, V as VM, c as createVM, e as executeBytecode, s as sharedOpRegistry } from './ScopeManager-udv4Twwq.js';
+import { V as Value } from './Value-CXJqDH9J.js';
+export { M as MatrixData, a as MatrixEntry, R as RangeData, b as ValueType, c as bigIntValue, d as colVectorValue, h as hexValue, m as matrixValue, n as numberValue, r as rangeValue, e as rowVectorValue, s as stringValue, u as uomValue } from './Value-CXJqDH9J.js';
+export { a as VMCheckpoint, V as VMCheckpointer } from './VMCheckpoints-BiaIlOOY.js';
+import './BytecodeBuilder-B0xskcv5.js';
+import './EngineError-LU7W7AgI.js';
+import './pipeline-B6k5lCB7.js';
 import './variables.js';
 
+/**
+ * The ceiling on how much memory one evaluation is allowed to ask for.
+ *
+ * The VM's other two counters bound how many opcodes run and how deep the value
+ * stack gets, and both are checked BETWEEN opcodes. That leaves a hole the size
+ * of a single opcode: whatever one opcode allocates in a loop of its own is
+ * invisible to both, so twenty-four characters of input (`map(10*x,
+ * 0:2000000000)`) could allocate until V8 aborted the process, which no
+ * `try`/`catch` in the host can contain. Per-site caps close one hole each and
+ * do not compose: two collections that are individually legal are legal
+ * together, and an operation whose result is the PRODUCT of two legal inputs (a
+ * matrix multiply) is bounded by neither of them.
+ *
+ * This is the counter that composes. Everything an evaluation materialises is
+ * charged against one running tally, so the bound is on the total rather than
+ * on any single step, and a new opcode inherits it by allocating through
+ * {@link chargedArray} or by building a Value through a constructor that
+ * already charges ({@link matrixValue}).
+ *
+ * The tally is module state rather than something threaded through every
+ * signature. `executeBytecode()` opens an evaluation and every charge inside
+ * that window lands on it, which is what lets a helper five call levels down
+ * (`vm/MatrixOps.ts`'s `collectionToValues()`) charge without the four frames
+ * in between passing a parameter along, and what keeps a charge down to an add
+ * and a compare. This mirrors the value arena in `vm/Value.ts`, which is
+ * ambient for the same reason and rests on the same fact: `executeBytecode()`
+ * is synchronous, so exactly one evaluation is ever in flight in a realm.
+ *
+ * An "element" is one thing a user's input caused to exist: a `Value` in an
+ * expanded collection, a cell in a matrix. They are counted rather than
+ * measured in bytes, because a count is the quantity every call site already
+ * has in hand before it allocates, and asking V8 how big something is costs
+ * more than the allocation being guarded.
+ *
+ * A second tally lives here for the same structural reason and not because it
+ * counts the same thing: {@link chargeFunctionCall} bounds how many
+ * user-defined-function calls one evaluation may make in total. Surviving
+ * reentry is the whole property both need, and this module is where reentry is
+ * already tracked.
+ *
+ * @module AllocationBudget
+ */
+
+/**
+ * Record elements materialised by the evaluation in flight.
+ *
+ * Each thing is charged exactly once, where it comes into existence: a matrix
+ * in `matrixValue()`, an expanded collection where it is expanded. A site that
+ * knows a size in advance and whose result will be charged on birth uses
+ * {@link checkAllocation} instead, so that refusing early does not mean
+ * counting twice.
+ *
+ * Outside an evaluation this is a plain no-op rather than an error:
+ * `matrixValue()` and the `vm/MatrixOps.ts` helpers are exported and get called
+ * by tests, by the formatter and by hosts with no evaluation in flight, and
+ * none of those is user input being executed.
+ *
+ * @param count - How many elements now exist.
+ * @param what - What they are, in the plural and in a user's words ("matrix
+ * cells", "collection elements"). Quoted verbatim in the error, so it should
+ * name the thing rather than the code that makes it.
+ * @throws `ALLOCATION_LIMIT_EXCEEDED` when this evaluation has had enough.
+ * Recoverable: it describes this expression, not the engine.
+ */
+declare function chargeAllocation(count: number, what: string): void;
+/**
+ * Refuse an allocation this evaluation cannot afford, without recording it.
+ *
+ * For the sites that know how big a result will be BEFORE building it and whose
+ * result is charged later, when it is born. A matrix product is the case that
+ * matters: its size is the product of two operands that are each affordable, so
+ * it has to be refused from the shapes alone, before `matrixMultiply()` takes
+ * the memory. Charging here as well as at birth would bill every matrix twice
+ * and halve the ceiling the host asked for.
+ *
+ * @param count - How many elements the result would have.
+ * @param what - What they are, in the plural. See {@link chargeAllocation}.
+ * @throws `ALLOCATION_LIMIT_EXCEEDED` when the evaluation could not afford them.
+ */
+declare function checkAllocation(count: number, what: string): void;
+/**
+ * Check that an array is affordable, then allocate it.
+ *
+ * The intended way to build any user-sized array inside the VM whose contents
+ * end up inside a Value that charges on birth, so that "ask before you take" is
+ * a property of the allocator rather than something each new opcode has to be
+ * told.
+ *
+ * @param count - Element count, checked before a single element exists.
+ * @param what - What the elements are, in the plural. See {@link chargeAllocation}.
+ * @returns An empty array of that length.
+ * @throws `ALLOCATION_LIMIT_EXCEEDED` before allocating anything, when the
+ * evaluation cannot afford it.
+ */
+declare function checkedArray<T>(count: number, what: string): T[];
+
 /**
  * Registry of built-in mathematical functions.
  * Indexed by the number pushed as an operand of OpCode.CALL_BUILTIN.
@@ -65,4 +161,4 @@ declare function unifyUom(l: Value, r: Value): {
  */
 declare function binaryOp(l: Value, r: Value, op: (a: number, b: number) => number, bigOp?: (a: bigint, b: bigint) => bigint, symbolicOp?: "add" | "sub" | "mul" | "div"): Value;
 
-export { Value, allocatePluginFunctionIndex, binaryOp, builtinFunctions, pluginFunctionRegistry, unifyUom };
+export { Value, allocatePluginFunctionIndex, binaryOp, builtinFunctions, chargeAllocation, checkAllocation, checkedArray, pluginFunctionRegistry, unifyUom };

package/dist/vm.js

@@ -1,15 +1,15 @@
-export { DependencyGraph, ScopeManager, createVM, executeBytecode } from './chunk-BAMZT3GL.js';
+export { DependencyGraph, ScopeManager, createVM, executeBytecode } from './chunk-5WVP4YHP.js';
 import './chunk-G535KJEG.js';
-export { OpRegistry, allocatePluginFunctionIndex, binaryOp, builtinFunctions, pluginFunctionRegistry, sharedOpRegistry, unifyUom } from './chunk-MVBEL57Q.js';
+export { OpRegistry, allocatePluginFunctionIndex, binaryOp, builtinFunctions, pluginFunctionRegistry, sharedOpRegistry, unifyUom } from './chunk-Y7FT4IQT.js';
 import './chunk-GCM5JHMX.js';
-import './chunk-UKPGSAZW.js';
-import './chunk-75JP4BZX.js';
+import './chunk-TMA4RCEN.js';
+import './chunk-UQ3UIZJC.js';
 import './chunk-Z4X2RWOF.js';
-import './chunk-CYFK5SY2.js';
-export { Value, ValueType, bigIntValue, colVectorValue, hexValue, matrixValue, numberValue, rangeValue, rowVectorValue, stringValue, uomValue } from './chunk-BVAR5J2F.js';
-import './chunk-WC5FFSHB.js';
-import './chunk-PCPX42KL.js';
-import './chunk-6RDSQURE.js';
+import './chunk-O3ANBHSA.js';
+export { Value, ValueType, bigIntValue, chargeAllocation, checkAllocation, checkedArray, colVectorValue, hexValue, matrixValue, numberValue, rangeValue, rowVectorValue, stringValue, uomValue } from './chunk-GQCOSXMG.js';
+import './chunk-R3PY4G7J.js';
+import './chunk-V4XG5QF6.js';
+import './chunk-3D7V24DG.js';
 import './chunk-YLJ4XMA6.js';
 
 // src/vm/VMCheckpoints.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "solve-engine",
-  "version": "1.0.0-beta.6",
-  "description": "The expression evaluation engine behind Solve — lexer, parser, bytecode VM, and an extensible package system.",
+  "version": "1.0.0",
+  "description": "An embeddable expression engine for natural-language calculations: units, currencies, percentages, dates and matrices, with the parsing and evaluation plumbing already built.",
   "keywords": [
     "expression-evaluator",
     "calculator",
@@ -212,7 +212,7 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@types/semver": "^7.5.0",
     "convert": "^7.0.0",
     "jest": "^30.4.2",

package/dist/chunk-2CS6OMZK.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/lexer/LexerState.ts","../src/lexer/Lexer.ts","../src/lexer/TokenClassRegistry.ts","../src/lexer/tokenRegistration.ts"],"names":["LexerState"],"mappings":"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","file":"chunk-2CS6OMZK.js","sourcesContent":["/**\n * Lexer state machine modes.\n * - Main: document-level scanning with markdown classification\n * - Inline: expression embedded in markdown inline solve (`s\\`...\\``)\n * - String: inside a double-quoted string literal\n */\nexport enum LexerState {\n\tMain = \"main\",\n\tInline = \"inline\",\n\tString = \"string\",\n}\n","import { ExpressionLexer, LineClassification, LexerVocabulary, type ScanLineResult } from \"./ExpressionLexer\";\nimport { Token } from \"@solve-js/lexer/Token\";\nimport { LexerState } from \"@solve-js/lexer/LexerState\";\nimport { getTokenCategory } from \"@solve-js/language/TokenCategoryMap\";\nimport type { TokenCategory } from \"@solve-js/language/TokenCategory\";\nimport type { TokenLookup } from \"@solve-js/lexer/TokenClassRegistry\";\n\n/**\n * Public tokenizer wrapper around {@link ExpressionLexer}.\n *\n * `ExpressionLexer` does the actual character-by-character scanning;\n * `Lexer` adds a materialized-token-array streaming interface\n * (`next()`/`peek()`) plus line-classification state (`reset()`) so\n * callers can iterate a line's tokens without re-scanning on each peek.\n *\n * Each `ExpressionEngine` instance owns its own `Lexer`, and packages\n * extend it via {@link registerVocabulary} (keywords, operators, units)\n * see `IEnginePackage.lexerVocabulary`.\n */\nexport class Lexer {\n  /** Expression-mode lexer (Phase A: V8-optimized, replaces moo) */\n  private expressionLexer: ExpressionLexer;\n  private currentState: LexerState = LexerState.Main;\n  private peekedToken: Token | undefined;\n  private hasPeeked = false;\n\n  // Materialized token array from the last reset() call, used for\n  // next()/peek() streaming access.\n  private tokens: Token[] = [];\n  private tokenIdx: number = 0;\n\n  /**\n   * @param localeCode - Locale code (e.g., \"en\", \"de\"). Defaults to \"en\".\n   * @param tokenLookup - Optional TokenLookup from TokenClassRegistry.\n   *   When provided, configures ExpressionLexer to use registry-built\n   *   keyword/unit/phrase lookups instead of internal instance maps.\n   */\n  constructor(localeCode = \"en\", tokenLookup?: TokenLookup) {\n    // Pass the lookup directly to ExpressionLexer's constructor, it's an\n    // instance field now, not a static. Each Lexer instance gets its own\n    // isolated lookup, preventing cross-instance corruption.\n    this.expressionLexer = new ExpressionLexer(localeCode, tokenLookup);\n  }\n\n  reset(input: string, state?: LexerState): void {\n    const newState = state ?? LexerState.Main;\n    this.currentState = newState;\n    this.hasPeeked = false;\n    this.peekedToken = undefined;\n\n    // Phase B: Main state classifies the line with the markdown scanner.\n    // Skip lines (headings, fences, HRs, etc.) produce empty token arrays.\n    // Expression lines and lines with inline solves are tokenized normally.\n    if (newState === LexerState.Main) {\n      const classification = this.expressionLexer.classifyLine(input);\n      if (classification.skip) {\n        this.tokens = [];\n        this.tokenIdx = 0;\n        return;\n      }\n      // Expression line or markdown line with inline solves, tokenize.\n      this.expressionLexer.reset(input);\n      this.tokens = this.expressionLexer.tokenizeAll();\n      this.tokenIdx = 0;\n    } else {\n      // Non-main states (Inline, String), expression tokenization.\n      this.expressionLexer.reset(input);\n      this.tokens = this.expressionLexer.tokenizeAll();\n      this.tokenIdx = 0;\n    }\n  }\n\n  /**\n   * Classify a single line of markdown text (Phase B).\n   * Delegates to the ExpressionLexer's character-by-character scanner.\n   */\n  classifyLine(lineText: string): LineClassification {\n    return this.expressionLexer.classifyLine(lineText);\n  }\n\n  /**\n   * Find all inline solve markers in a line (Phase B).\n   * Delegates to the ExpressionLexer's character-by-character scanner.\n   */\n  findInlineSolves(lineText: string) {\n    return this.expressionLexer.findInlineSolves(lineText);\n  }\n\n  /**\n   * Every keyword this lexer currently recognizes (locale + plugin-contributed),\n   * mapped to the token type it lexes to. Delegates to the ExpressionLexer.\n   */\n  getKeywords(): Record<string, string> {\n    return this.expressionLexer.getKeywords();\n  }\n\n  next(): Token | undefined {\n    if (this.hasPeeked) {\n      this.hasPeeked = false;\n      return this.peekedToken;\n    }\n    // Materialized token array (ExpressionLexer path).\n    if (this.tokenIdx < this.tokens.length) {\n      return this.tokens[this.tokenIdx++];\n    }\n    return undefined;\n  }\n\n  peek(): Token | undefined {\n    if (this.hasPeeked) return this.peekedToken;\n    this.peekedToken = this.next();\n    this.hasPeeked = true;\n    return this.peekedToken;\n  }\n\n  [Symbol.iterator](): Iterator<Token> {\n    return this.tokens[Symbol.iterator]();\n  }\n\n  /**\n   * Register a plugin to extend the lexer with custom tokens.\n   * Delegates to the underlying ExpressionLexer.\n   *\n   * @see LexerVocabulary for the supported extension points.\n   */\n  registerVocabulary(plugin: LexerVocabulary): void {\n    this.expressionLexer.registerVocabulary(plugin);\n  }\n\n  /**\n   * Unregister a plugin, removing its custom tokens from the lexer.\n   * Delegates to the underlying ExpressionLexer.\n   */\n  unregisterVocabulary(plugin: LexerVocabulary): void {\n    this.expressionLexer.unregisterVocabulary(plugin);\n  }\n\n  /**\n   * Reset the lexer for expression-only text, skips the classifyLine()\n   * overhead in reset() for callers that already know the input is an\n   * evaluable expression (e.g., after isEmptyLine() confirmed non-skip).\n   */\n  resetExpression(input: string): void {\n    this.currentState = LexerState.Main;\n    this.hasPeeked = false;\n    this.peekedToken = undefined;\n    this.expressionLexer.reset(input);\n    this.tokens = this.expressionLexer.tokenizeAll();\n    this.tokenIdx = 0;\n  }\n\n  /**\n   * Scan a full document in one pass, classifying each line and\n   * tokenizing non-skipped lines. Delegates to ExpressionLexer.\n   *\n   * @returns ScanLineResult[], one per line, with classification + tokens.\n   */\n  scanDocument(text: string): ScanLineResult[] {\n    return this.expressionLexer.scanDocument(text);\n  }\n\n  getState(): LexerState {\n    return this.currentState;\n  }\n\n  setState(state: LexerState): void {\n    this.currentState = state;\n  }\n\n  getHighlightTokens(lineText: string): {type: string; value: string; offset: number; col: number; length: number; category: TokenCategory | undefined}[] {\n    const classification = this.expressionLexer.classifyLine(lineText);\n\n    // For blockquote lines, strip the \"> \" prefix and tokenize the expression content.\n    // This lets expressions inside blockquotes (e.g., \"> 1 + 2\") get syntax highlighted\n    // while pure structural lines (headings, code fences) remain unhighlighted.\n    if (classification.skip && lineText.startsWith(\"> \")) {\n      return this.collectHighlightTokens(lineText.slice(2));\n    }\n\n    if (classification.skip) {\n      return [];\n    }\n\n    return this.collectHighlightTokens(lineText);\n  }\n\n  /**\n   * The same tokens {@link getHighlightTokens} reduces, before reduction.\n   *\n   * Exists because normalization operates on tokens, not on the flattened\n   * shape, and a consumer that wants phrase-fused highlighting has to run the\n   * normalizer between the two. See `LanguageService.getSemanticTokens`.\n   *\n   * @param lineText - One line of source.\n   * @returns Every token on the line that is worth painting, unreduced.\n   */\n  getHighlightTokenObjects(lineText: string): Token[] {\n    const classification = this.expressionLexer.classifyLine(lineText);\n    if (classification.skip && lineText.startsWith(\"> \")) {\n      return this.collectTokenObjects(lineText.slice(2));\n    }\n    if (classification.skip) return [];\n    return this.collectTokenObjects(lineText);\n  }\n\n  private collectTokenObjects(lineText: string): Token[] {\n    this.resetExpression(lineText);\n    const result: Token[] = [];\n    for (const token of this) {\n      if (token.type === \"WS\" || token.type === \"NEWLINE\") continue;\n      if (token.type.startsWith(\"MD_\")) continue;\n      if (token.type === \"INLINE_SOLVE_START\" || token.type === \"BACKTICK_CLOSE\") continue;\n      result.push(token);\n    }\n    return result;\n  }\n\n  private collectHighlightTokens(lineText: string): {type: string; value: string; offset: number; col: number; length: number; category: TokenCategory | undefined}[] {\n    return this.collectTokenObjects(lineText).map(token => ({\n      type: token.type,\n      value: token.value,\n      offset: token.offset,\n      col: token.col,\n      length: token.value.length,\n      category: getTokenCategory(token.type),\n    }));\n  }\n}\n\n/**\n * A lexer for operations that do not depend on registered vocabulary.\n *\n * Line classification and inline-solve detection read characters looking for\n * headings, comment markers, fences and backtick spans, and never consult the\n * keyword, unit or operator tables. Every lexer therefore returns the same\n * answer, so the callers that have no engine to ask can use this one. Checked\n * by `__tests__/lexer/LineClassificationIsVocabularyIndependent.spec.ts`.\n *\n * Do not tokenize with this. An engine's own lexer carries the vocabulary its\n * packages registered; this one carries none.\n */\nexport const sharedLexer = new Lexer(\"en\", undefined);","/**\n * TokenClass, Plugin-extensible keyword registration for the Lexer.\n *\n * Providers call `registry.register(tokenClass)` to teach the lexer about\n * their keywords. The registry merges locale keywords, provider keywords,\n * phrase mappings, and unit names into an optimized TokenLookup structure\n * consumed by the Lexer.\n *\n * @example\n * registry.register({\n *   tokenType: 'CARET',\n *   keywords: {},\n *   phrases: { 'to the power of': true, 'power of': true },\n *   priority: 10,\n *   description: 'Exponentiation operators (x^y)',\n * });\n */\nexport interface TokenClass {\n  /** The token type string produced by the lexer (e.g., \"FUNC\", \"PI\", \"CARET\").\n   *  Must match a token type that a ParseletRegistry has a parselet for. */\n  tokenType: string;\n\n  /** Single-word keywords (case-insensitive). The lexer lowercases input\n   *  before lookup, so these should be lowercase. Example:\n   *  { sqrt: true, abs: true, sin: true, cos: true } for tokenType \"FUNC\" */\n  keywords: Record<string, boolean>;\n\n  /** Multi-word phrases (case-insensitive). Matched by the built-in PhraseMatcher\n   *  via the phrase trie. Example:\n   *  { \"to the power of\": true, \"power of\": true } for tokenType \"CARET\" */\n  phrases?: Record<string, boolean>;\n\n  /** Priority for conflict resolution. When two TokenClasses register\n   *  the same keyword, the higher-priority class wins. Locale keywords\n   *  have priority 0 (set via setLocale). Providers should use\n   *  priority >= 10 to override locale defaults. Default: 0 */\n  priority?: number;\n\n  /** Human-readable description for debugging and introspection */\n  description?: string;\n}\n\n// ── Phrase Trie ──────────────────────────────────────────────────────────────\n\n/** Trie node for multi-word phrase matching. */\nexport interface PhraseNode {\n  /** Complete phrase token type (null = intermediate node) */\n  type?: string;\n  children: Map<string, PhraseNode>;\n}\n\n// ── TokenLookup, Optimized lookup structure for the Lexer ──────────────────\n\n/**\n * The optimized lookup structure built by TokenClassRegistry.build().\n * Consumed by the Lexer for O(1) keyword → token type lookups and\n * O(word-count) phrase matching.\n */\nexport interface TokenLookup {\n  /** Lowercase keyword → token type. O(1) Map lookup. */\n  keywordToType: Map<string, string>;\n\n  /** Phrase trie for multi-word matching. Root node with children maps.\n   *  Null if no phrases registered. */\n  phraseTrie: PhraseNode | null;\n\n  /** Set of lowercase first-words of all registered phrases.\n   *  Used by the lexer to emit IDENT (not a phrase keyword) for words\n   *  that start multi-word phrases, deferring to the PhraseMatcher.\n   *\n   *  Example: \"to\" is in phraseStartWords because \"to the power of\" is a phrase.\n   *  When the lexer sees \"to\", it emits IDENT and lets the phrase matcher\n   *  combine \"to the power of\" into a single CARET token.\n   *\n   *  This prevents plugins from accidentally overriding phrase-start words.\n   */\n  phraseStartWords: Set<string>;\n\n  /** Case-sensitive unit names for UNIT fallback after keyword lookup fails. */\n  unitNames: ReadonlySet<string>;\n}\n\n// ── TokenClassRegistry ───────────────────────────────────────────────────────\n\n/**\n * Central registry for keyword→token-type mappings.\n *\n * Providers register TokenClasses; locales provide keyword maps;\n * units provide a name set. `build()` merges all sources into an\n * optimized TokenLookup consumed by the Lexer.\n *\n * Merge order (later overrides earlier):\n *   1. Locale keywords (priority 0)\n *   2. Provider keywords (sorted by priority ascending, higher priority wins)\n *\n * Unit names are stored separately (checked AFTER keyword lookup fails).\n * Phrases are stored in a trie for O(phrase-length) matching.\n */\nexport class TokenClassRegistry {\n  private classes: TokenClass[] = [];\n  private localeKeywordMap: Record<string, string> | null = null;\n  private localePhraseMap: Record<string, string> | null = null;\n  private unitNames: ReadonlySet<string> | null = null;\n\n  /**\n   * Register a provider's TokenClass. Must be called BEFORE build().\n   * Can be called multiple times to add more entries.\n   *\n   * Built-in token types CANNOT be overridden, throws a EngineError\n   * if the TokenClass attempts to register a keyword that conflicts\n   * with an already-registered token type.\n   */\n  register(tokenClass: TokenClass): void {\n    this.classes.push(tokenClass);\n  }\n\n  /**\n   * Unregister all TokenClasses for a given token type.\n   * Useful for plugin unload. Requires rebuild() to take effect.\n   */\n  unregister(tokenType: string): void {\n    this.classes = this.classes.filter(c => c.tokenType !== tokenType);\n  }\n\n  /**\n   * Set the locale's keyword→type map and optional phrase map.\n   * Called on locale change. Priority 0 (cannot override providers with higher priority).\n   */\n  setLocale(keywordMap: Record<string, string>, phraseMap?: Record<string, string>): void {\n    this.localeKeywordMap = keywordMap;\n    this.localePhraseMap = phraseMap ?? null;\n  }\n\n  /**\n   * Set the unit name set. Called when unit list changes.\n   * Units are stored separately (checked AFTER keyword lookup fails).\n   *\n   * Takes a ReadonlySet because the caller's set is derived from the\n   * conversion tables and must not be mutated; this class only ever reads it.\n   */\n  setUnits(unitNames: ReadonlySet<string>): void {\n    this.unitNames = unitNames;\n  }\n\n  /**\n   * Build the optimized TokenLookup from all registered sources.\n   *\n   * Merge order (later overrides earlier):\n   *   1. Locale keywords (priority 0)\n   *   2. Provider classes (sorted by priority ascending)\n   *\n   * Returns a frozen TokenLookup that the Lexer consumes.\n   * Call build() again after register()/setLocale()/setUnits() changes.\n   */\n  build(): TokenLookup {\n    const keywordToType = new Map<string, string>();\n\n    // Layer 1: Locale keywords (priority 0, lowest)\n    if (this.localeKeywordMap) {\n      for (const [keyword, tokenType] of Object.entries(this.localeKeywordMap)) {\n        keywordToType.set(keyword.toLowerCase(), tokenType);\n      }\n    }\n\n    // Layer 2: Provider keywords (sorted by priority ascending, higher wins)\n    const sorted = [...this.classes].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));\n    for (const tc of sorted) {\n      for (const keyword of Object.keys(tc.keywords)) {\n        keywordToType.set(keyword.toLowerCase(), tc.tokenType);\n      }\n    }\n\n    // Build phrase trie from locale + provider phrases\n    const phraseTrie = this.buildPhraseTrie();\n\n    // Build phraseStartWords set (first word of every phrase)\n    const phraseStartWords = this.buildPhraseStartWords();\n\n    return {\n      keywordToType,\n      phraseTrie,\n      phraseStartWords,\n      unitNames: this.unitNames ?? new Set(),\n    };\n  }\n\n  // ── Private helpers ─────────────────────────────────────────────────────\n\n  private buildPhraseTrie(): PhraseNode | null {\n    const root: PhraseNode = { children: new Map() };\n\n    // Layer 1: Locale phrases\n    if (this.localePhraseMap) {\n      for (const [phrase, tokenType] of Object.entries(this.localePhraseMap)) {\n        this.insertPhrase(root, phrase.toLowerCase(), tokenType);\n      }\n    }\n\n    // Layer 2: Provider phrases\n    for (const tc of this.classes) {\n      if (!tc.phrases) continue;\n      for (const phrase of Object.keys(tc.phrases)) {\n        this.insertPhrase(root, phrase.toLowerCase(), tc.tokenType);\n      }\n    }\n\n    return root.children.size > 0 ? root : null;\n  }\n\n  private insertPhrase(root: PhraseNode, phrase: string, tokenType: string): void {\n    const words = phrase.split(' ');\n    let node = root;\n    for (const word of words) {\n      if (!node.children.has(word)) {\n        node.children.set(word, { children: new Map() });\n      }\n      node = node.children.get(word)!;\n    }\n    // Only set type if not already set, first-registered (locale) wins\n    if (!node.type) {\n      node.type = tokenType;\n    }\n  }\n\n  private buildPhraseStartWords(): Set<string> {\n    const startWords = new Set<string>();\n\n    // Locale phrase first words\n    if (this.localePhraseMap) {\n      for (const phrase of Object.keys(this.localePhraseMap)) {\n        const first = phrase.split(' ')[0].toLowerCase();\n        startWords.add(first);\n      }\n    }\n\n    // Provider phrase first words\n    for (const tc of this.classes) {\n      if (!tc.phrases) continue;\n      for (const phrase of Object.keys(tc.phrases)) {\n        const first = phrase.split(' ')[0].toLowerCase();\n        startWords.add(first);\n      }\n    }\n\n    return startWords;\n  }\n}","/**\n * tokenRegistration.ts, Bootstrap for building TokenLookup from locale, units, and phrases.\n *\n * This module centralizes the assembly of the TokenLookup consumed by ExpressionLexer.\n * It merges:\n *   1. Locale keywords (from ILocale.keywordMap)\n *   2. Built-in phrase patterns (to the power of, increase by, etc.)\n *   3. Known unit names (from units.ts)\n *\n * The resulting TokenLookup is frozen and passed to ExpressionLexer.configuredLookup\n * at construction time, enabling data-driven keyword/unit/phrase resolution.\n */\nimport { TokenClassRegistry } from '@solve-js/lexer/TokenClassRegistry';\nimport type { TokenLookup } from '@solve-js/lexer/TokenClassRegistry';\nimport { getLocale, type ILocale } from '@solve-js/constants/locales';\nimport { knownUnits } from '@solve-js/lexer/units';\n\n// ── Built-in phrase map ───────────────────────────────────────────────────\n// These are the multi-word expressions handled as compound tokens.\n// Matched by the PhraseMatcher (trie-based) in ExpressionLexer.tryMatchPhrase().\nconst BUILTIN_PHRASES: Record<string, string> = {\n  'to the power of': 'CARET',\n  'power of': 'CARET',\n  'increase by': 'INCREASE_BY',\n  'decrease by': 'DECREASE_BY',\n  'times by': 'TIMES_BY',\n  'multiply by': 'MULTIPLY_BY',\n  'multiplied by': 'MULTIPLY_BY',\n  'divide by': 'DIVIDE_BY',\n};\n\n/**\n * Build a TokenLookup from locale keywords, known units, and built-in phrases.\n *\n * Merge order (later overrides earlier):\n *   1. Locale keywords (priority 0, lowest, can be overridden by providers)\n *   2. Built-in phrases (via locale phraseMap)\n *   3. Known units (checked AFTER keyword lookup fails, via unitNames set)\n *\n * The resulting TokenLookup replaces the internal keyword map, unit set,\n * phrase trie, and phraseStartWords in ExpressionLexer when set via\n * ExpressionLexer.configuredLookup.\n *\n * @param localeCode - The locale code (e.g., \"en\", \"de\"). Defaults to \"en\".\n * @returns A frozen TokenLookup ready for consumption by the lexer.\n */\nexport function buildTokenLookup(localeCode = 'en'): TokenLookup {\n  const locale: ILocale = getLocale(localeCode);\n  const registry = new TokenClassRegistry();\n\n  // Layer 1: Locale keywords (priority 0, lowest)\n  registry.setLocale(locale.keywordMap, BUILTIN_PHRASES);\n\n  // Layer 2: Known units (checked after keyword lookup)\n  registry.setUnits(knownUnits);\n\n  // Build and return the lookup\n  return registry.build();\n}\n"]}

package/dist/chunk-4AVD7NZW.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/parser/OperandWidth.ts","../src/uom/CurrencyResolver.ts"],"names":["currencyExchangeService","numberValue"],"mappings":"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","file":"chunk-4AVD7NZW.cjs","sourcesContent":["/**\n * How many operand bytes follow each opcode, and how to step over one.\n *\n * Anything walking a bytecode stream without executing it needs this: the\n * resolver preflight scanners look for specific opcodes and must skip past\n * everything else without mistaking an operand byte for an instruction.\n *\n * It used to be a hand-copied switch in each of those scanners. They had\n * already drifted: two counted `CALL_PLUGIN` as three bytes wide and the third\n * omitted it from that arm, so a stream containing one desynchronised there and\n * every opcode after it was read at the wrong offset. Adding an opcode meant\n * remembering every copy, and nothing checked that you had.\n *\n * `__tests__/parser/OperandWidth.spec.ts` asserts every opcode has a width, so\n * a new one fails a test rather than silently defaulting to zero operands.\n */\n\nimport { OpCode } from \"@solve-js/parser/OpCode\";\n\n/**\n * Opcodes taking one operand byte.\n *\n * A constant-pool index, or a variable-name index.\n */\nconst ONE_OPERAND: readonly OpCode[] = [\n\tOpCode.PUSH_NUMBER,\n\tOpCode.PUSH_BIGINT,\n\tOpCode.PUSH_HEX,\n\tOpCode.PUSH_STRING,\n\tOpCode.PUSH_BOOLEAN,\n\tOpCode.LOAD_VAR,\n\tOpCode.STORE_VAR,\n\tOpCode.LOAD_GLOBAL_VAR,\n\tOpCode.STORE_GLOBAL_VAR,\n\tOpCode.DEFINE_USER_FUNCTION,\n];\n\n/**\n * Opcodes taking two operand bytes.\n *\n * A callable index plus an argument count, or a matrix's row and column counts.\n */\nconst TWO_OPERANDS: readonly OpCode[] = [\n\tOpCode.CALL_PLUGIN,\n\tOpCode.CALL_BUILTIN,\n\tOpCode.CALL_USER_FUNCTION,\n\tOpCode.MAT_NEW,\n];\n\n/**\n * Opcodes taking three operand bytes.\n *\n * The map and reduce invocations, which carry a body index alongside their\n * other operands.\n */\nconst THREE_OPERANDS: readonly OpCode[] = [OpCode.MAP_INVOKE, OpCode.REDUCE_INVOKE];\n\n/**\n * Operand byte count for every opcode, indexed by opcode value.\n *\n * A dense array rather than a map, because the preflight scanners run on every\n * keystroke and this is read once per instruction.\n */\nexport const OPERAND_BYTES: readonly number[] = (() => {\n\tconst widths = new Array<number>(256).fill(0);\n\tfor (const op of ONE_OPERAND) widths[op] = 1;\n\tfor (const op of TWO_OPERANDS) widths[op] = 2;\n\tfor (const op of THREE_OPERANDS) widths[op] = 3;\n\treturn widths;\n})();\n\n/**\n * Every opcode that takes at least one operand.\n *\n * Exported so a test can assert the table stays complete as opcodes are added.\n */\nexport const OPCODES_WITH_OPERANDS: readonly OpCode[] = [\n\t...ONE_OPERAND,\n\t...TWO_OPERANDS,\n\t...THREE_OPERANDS,\n];\n\n/**\n * Offset of the instruction after the one at `index`.\n *\n * @param opcodes - The bytecode stream.\n * @param index - Offset of an opcode, not of an operand byte. Passing an\n * operand offset yields nonsense, which is the failure mode this exists to\n * prevent: a caller stepping by hand and getting one width wrong reads the rest\n * of the stream misaligned.\n * @returns Offset of the next opcode. May be past the end when the instruction\n * at `index` is the last one, so callers loop while it is under `opcodes.length`.\n */\nexport function nextInstruction(opcodes: Uint8Array, index: number): number {\n\treturn index + 1 + (OPERAND_BYTES[opcodes[index]] ?? 0);\n}\n","/**\n * Currency async resolver, bridges CurrencyExchangeService to the\n * IAsyncResolver interface for the Suspense architecture.\n *\n * Uses TanStack Query (injected via queryClient) as the single cache layer.\n */\nimport type { QueryClient } from \"@tanstack/query-core\";\nimport type { Token } from \"@solve-js/lexer\";\nimport type { BytecodeProgram } from \"@solve-js/parser/BytecodeBuilder\";\nimport { OpCode } from \"@solve-js/parser/OpCode\";\nimport { numberValue } from \"@solve-js/vm/Value\";\nimport {\n\tcurrencyExchangeService,\n\tCurrencyExchangeService,\n} from \"@solve-js/uom/CurrencyExchange\";\nimport type { IAsyncResolver, AsyncCheckResult } from \"@solve-js/resolvers/ResolverRegistry\";\nimport { nextInstruction } from \"@solve-js/parser/OperandWidth\";\n\nconst CURRENCY_NS = \"currency\";\n\n/**\n * Fetches exchange rates before the VM runs, so a conversion has real numbers.\n *\n * Until rates arrive the line evaluates to a pending value rather than a\n * guessed one, and re-evaluates when they land.\n */\nexport class CurrencyAsyncResolver implements IAsyncResolver {\n\treadonly namespace = CURRENCY_NS;\n\n\tprivate exchange: CurrencyExchangeService;\n\n\tconstructor(exchange?: CurrencyExchangeService) {\n\t\tthis.exchange = exchange ?? currencyExchangeService;\n\t}\n\n\tpreflight(_tokens: Token[], bytecode: BytecodeProgram, packageId: string, signal: AbortSignal, queryClient: QueryClient): AsyncCheckResult | null {\n\t\tconst { opcodes, strings } = bytecode;\n\t\tconst len = opcodes.length;\n\t\tlet i = 0;\n\n\t\tlet lastStrIdx = -1;\n\t\tlet prevStrIdx = -1;\n\n\t\twhile (i < len) {\n\t\t\tconst op = opcodes[i] as OpCode;\n\n\t\t\tif (op === OpCode.PUSH_STRING) {\n\t\t\t\tprevStrIdx = lastStrIdx;\n\t\t\t\tlastStrIdx = opcodes[i + 1];\n\t\t\t}\n\n\t\t\t// Explicit \"X to Y\"/\"X in Y\" conversions (UOM_CONVERT_IN/_TO) are\n\t\t\t// the obvious case, but arithmetic directly on two differently-\n\t\t\t// denominated currency literals, \"0.01 BTC + 1 ETH\", needs the\n\t\t\t// exact same preflight fetch and previously never got it: this\n\t\t\t// scanner only looked for the CONVERT opcodes, so ADD/SUB/MUL/DIV\n\t\t\t// between two currency UOMs skipped preflight entirely, ran with\n\t\t\t// no cached rate, and fell through to the VM's silent-wrong-math\n\t\t\t// fallback instead of ever reaching a network fetch.\n\t\t\tconst isCurrencyCombiningOp =\n\t\t\t\top === OpCode.UOM_CONVERT_IN || op === OpCode.UOM_CONVERT_TO ||\n\t\t\t\top === OpCode.ADD || op === OpCode.SUB || op === OpCode.MUL || op === OpCode.DIV;\n\t\t\tif (isCurrencyCombiningOp) {\n\t\t\t\tif (prevStrIdx >= 0 && lastStrIdx >= 0) {\n\t\t\t\t\tconst fromUnit = strings[prevStrIdx];\n\t\t\t\t\tconst toUnit = strings[lastStrIdx];\n\n\t\t\t\t\tif (\n\t\t\t\t\t\tthis.exchange.isCurrency(fromUnit) &&\n\t\t\t\t\t\tthis.exchange.isCurrency(toUnit) &&\n\t\t\t\t\t\tfromUnit.toUpperCase() !== toUnit.toUpperCase()\n\t\t\t\t\t) {\n\t\t\t\t\t\tconst syncRate = this.exchange.getRateSync(fromUnit, toUnit);\n\t\t\t\t\t\tif (syncRate === null) {\n\t\t\t\t\t\t\tconst fromUpper = fromUnit.toUpperCase();\n\t\t\t\t\t\t\tconst toUpper = toUnit.toUpperCase();\n\n\t\t\t\t\t\t\t// Check TanStack Query cache\n\t\t\t\t\t\t\tconst cacheKey = [CURRENCY_NS, fromUpper, toUpper];\n\t\t\t\t\t\t\tif (queryClient.getQueryData(cacheKey) !== undefined) {\n\t\t\t\t\t\t\t\ti++;\n\t\t\t\t\t\t\t\tcontinue;\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\t// Fetch via TanStack Query (dedup + retry automatic)\n\t\t\t\t\t\t\tconst resolver = queryClient.fetchQuery({\n\t\t\t\t\t\t\t\tqueryKey: cacheKey,\n\t\t\t\t\t\t\t\tqueryFn: ({ signal: qSignal }) => {\n\t\t\t\t\t\t\t\t\treturn this.exchange.getRate(fromUnit, toUnit, qSignal).then((rate) => numberValue(rate));\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\tstaleTime: 5 * 60 * 1000,\n\t\t\t\t\t\t\t});\n\n\t\t\t\t\t\t\treturn { queryKey: cacheKey.join(\":\"), resolver, packageId, signal, metadata: { fromUnit, toUnit } };\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Step over this instruction and its operands. Shared table, because\n\t\t\t// three hand-copied versions of this had already drifted.\n\t\t\ti = nextInstruction(opcodes, i);\n\t\t}\n\n\t\treturn null;\n\t}\n\n\tdestroy(): void {\n\t\t// Cache cleared by ResolverRegistry.unregister() via removeQueries({ queryKey: [\"currency\"] })\n\t}\n}\n"]}