solve-engine 1.0.1 → 1.1.0

package/dist/lexer.js

@@ -1,11 +1,11 @@
-export { Lexer, LexerState, buildTokenLookup, sharedLexer } from './chunk-5F4C26RU.js';
-import './chunk-AJA6LUI7.js';
-export { ExpressionLexer, LexerToken } from './chunk-QY25VWBF.js';
-export { TokenTypes, registerAllTokenTypes, registerTokenType, tokenTypeId, tokenTypeName } from './chunk-VB37OC6I.js';
+export { Lexer, LexerState, buildTokenLookup, sharedLexer } from './chunk-OADDUPT3.js';
+import './chunk-UO6BUV6K.js';
+export { ExpressionLexer, LexerToken } from './chunk-GQMUHVE3.js';
+export { TokenTypes, registerAllTokenTypes, registerTokenType, tokenTypeId, tokenTypeName } from './chunk-4D6NIHE2.js';
 import './chunk-XBTEO4OB.js';
 export { knownUnits } from './chunk-SBUFNJVE.js';
 import './chunk-V4XG5QF6.js';
-import './chunk-3D7V24DG.js';
+import './chunk-ERCOHGXD.js';
 import './chunk-YLJ4XMA6.js';
 //# sourceMappingURL=lexer.js.map
 //# sourceMappingURL=lexer.js.map

package/dist/normalizer.cjs

@@ -1,40 +1,40 @@
 'use strict';
 
 require('./chunk-NGBBNL4K.cjs');
-var chunkBHTNFEGZ_cjs = require('./chunk-BHTNFEGZ.cjs');
-require('./chunk-YWQ6V4ZN.cjs');
-require('./chunk-5LI5EPGJ.cjs');
+var chunkC75AFGVD_cjs = require('./chunk-C75AFGVD.cjs');
+require('./chunk-YTIYVHL7.cjs');
+require('./chunk-QFTDTX6K.cjs');
 require('./chunk-OUHT5Z36.cjs');
 require('./chunk-AQNHHJMJ.cjs');
 require('./chunk-AMOJYLG2.cjs');
-require('./chunk-5KMIY374.cjs');
+require('./chunk-B4HBEFTB.cjs');
 require('./chunk-B7LXJ6LC.cjs');
 
 
 
 Object.defineProperty(exports, "BUILTIN_PHRASES", {
   enumerable: true,
-  get: function () { return chunkBHTNFEGZ_cjs.BUILTIN_PHRASES; }
+  get: function () { return chunkC75AFGVD_cjs.BUILTIN_PHRASES; }
 });
 Object.defineProperty(exports, "PhraseTrie", {
   enumerable: true,
-  get: function () { return chunkBHTNFEGZ_cjs.PhraseTrie; }
+  get: function () { return chunkC75AFGVD_cjs.PhraseTrie; }
 });
 Object.defineProperty(exports, "TokenNormalizer", {
   enumerable: true,
-  get: function () { return chunkBHTNFEGZ_cjs.TokenNormalizer; }
+  get: function () { return chunkC75AFGVD_cjs.TokenNormalizer; }
 });
 Object.defineProperty(exports, "createBuiltinNormalizerRules", {
   enumerable: true,
-  get: function () { return chunkBHTNFEGZ_cjs.createBuiltinNormalizerRules; }
+  get: function () { return chunkC75AFGVD_cjs.createBuiltinNormalizerRules; }
 });
 Object.defineProperty(exports, "createFusedToken", {
   enumerable: true,
-  get: function () { return chunkBHTNFEGZ_cjs.createFusedToken; }
+  get: function () { return chunkC75AFGVD_cjs.createFusedToken; }
 });
 Object.defineProperty(exports, "implicitMultiplyRule", {
   enumerable: true,
-  get: function () { return chunkBHTNFEGZ_cjs.implicitMultiplyRule; }
+  get: function () { return chunkC75AFGVD_cjs.implicitMultiplyRule; }
 });
 //# sourceMappingURL=normalizer.cjs.map
 //# sourceMappingURL=normalizer.cjs.map

package/dist/normalizer.d.cts

@@ -1,6 +1,6 @@
-import { N as NormalizerMatch, a as NormalizerRule } from './TokenNormalizer-DGVa24Q-.cjs';
-export { b as NormalizerOptions, T as TokenFusion, c as TokenNormalizer, d as createFusedToken } from './TokenNormalizer-DGVa24Q-.cjs';
-import { T as Token } from './Token-BzG5G4ja.cjs';
+import { N as NormalizerMatch, a as NormalizerRule } from './TokenNormalizer-DRc1Js1V.cjs';
+export { b as NormalizerOptions, T as TokenFusion, c as TokenNormalizer, d as createFusedToken } from './TokenNormalizer-DRc1Js1V.cjs';
+import { T as Token } from './Token-B1hdkedD.cjs';
 
 /**
  * PhraseTrie, optimized word-level trie for multi-word phrase fusion.

package/dist/normalizer.d.ts

@@ -1,6 +1,6 @@
-import { N as NormalizerMatch, a as NormalizerRule } from './TokenNormalizer-t_GotBxr.js';
-export { b as NormalizerOptions, T as TokenFusion, c as TokenNormalizer, d as createFusedToken } from './TokenNormalizer-t_GotBxr.js';
-import { T as Token } from './Token-BzG5G4ja.js';
+import { N as NormalizerMatch, a as NormalizerRule } from './TokenNormalizer-C6VzZgHa.js';
+export { b as NormalizerOptions, T as TokenFusion, c as TokenNormalizer, d as createFusedToken } from './TokenNormalizer-C6VzZgHa.js';
+import { T as Token } from './Token-B1hdkedD.js';
 
 /**
  * PhraseTrie, optimized word-level trie for multi-word phrase fusion.

package/dist/normalizer.js

@@ -1,11 +1,11 @@
 import './chunk-2RWAXT6O.js';
-export { BUILTIN_PHRASES, PhraseTrie, TokenNormalizer, createBuiltinNormalizerRules, createFusedToken, implicitMultiplyRule } from './chunk-YPPPYLSR.js';
-import './chunk-QY25VWBF.js';
-import './chunk-VB37OC6I.js';
+export { BUILTIN_PHRASES, PhraseTrie, TokenNormalizer, createBuiltinNormalizerRules, createFusedToken, implicitMultiplyRule } from './chunk-JJIXHXFQ.js';
+import './chunk-GQMUHVE3.js';
+import './chunk-4D6NIHE2.js';
 import './chunk-XBTEO4OB.js';
 import './chunk-SBUFNJVE.js';
 import './chunk-V4XG5QF6.js';
-import './chunk-3D7V24DG.js';
+import './chunk-ERCOHGXD.js';
 import './chunk-YLJ4XMA6.js';
 //# sourceMappingURL=normalizer.js.map
 //# sourceMappingURL=normalizer.js.map

package/dist/packages.cjs

@@ -1,120 +1,129 @@
 'use strict';
 
-var chunk3AFRJYP4_cjs = require('./chunk-3AFRJYP4.cjs');
-require('./chunk-PA4VC73I.cjs');
-require('./chunk-BHTNFEGZ.cjs');
+var chunkOTN6SZOD_cjs = require('./chunk-OTN6SZOD.cjs');
+require('./chunk-J45BCEZ4.cjs');
+require('./chunk-C75AFGVD.cjs');
 require('./chunk-ADBA3XBE.cjs');
-require('./chunk-4B2CNWQU.cjs');
+require('./chunk-SSV46KFA.cjs');
 require('./chunk-Z2XP767T.cjs');
-require('./chunk-6WFMPTGB.cjs');
+require('./chunk-7ZX6B7SY.cjs');
 require('./chunk-FEAIOR7N.cjs');
-require('./chunk-A2N2GFCG.cjs');
-require('./chunk-6KFYJ6TD.cjs');
+require('./chunk-ZVTWQLK4.cjs');
+require('./chunk-XIYYHA65.cjs');
 require('./chunk-VEKIWQ3F.cjs');
-require('./chunk-UM6BVY2S.cjs');
-require('./chunk-JMXUNXQS.cjs');
-require('./chunk-PFUESQTW.cjs');
-require('./chunk-YWQ6V4ZN.cjs');
-require('./chunk-5LI5EPGJ.cjs');
+require('./chunk-ALYRJ72W.cjs');
+require('./chunk-HIQ5HSZL.cjs');
+require('./chunk-2TZKENDH.cjs');
+require('./chunk-EJ3ILXX6.cjs');
+require('./chunk-YTIYVHL7.cjs');
+require('./chunk-QFTDTX6K.cjs');
 require('./chunk-OUHT5Z36.cjs');
 require('./chunk-AQNHHJMJ.cjs');
 require('./chunk-AMOJYLG2.cjs');
-require('./chunk-5KMIY374.cjs');
+require('./chunk-B4HBEFTB.cjs');
 require('./chunk-B7LXJ6LC.cjs');
 
 
 
 Object.defineProperty(exports, "ARITHMETIC_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.ARITHMETIC_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.ARITHMETIC_PACKAGE; }
 });
 Object.defineProperty(exports, "BIGINT_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.BIGINT_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.BIGINT_PACKAGE; }
 });
 Object.defineProperty(exports, "BUILTIN_PACKAGES", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.BUILTIN_PACKAGES; }
+  get: function () { return chunkOTN6SZOD_cjs.BUILTIN_PACKAGES; }
 });
 Object.defineProperty(exports, "CONDITIONALS_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.CONDITIONALS_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.CONDITIONALS_PACKAGE; }
 });
 Object.defineProperty(exports, "CONVERTERS_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.CONVERTERS_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.CONVERTERS_PACKAGE; }
 });
 Object.defineProperty(exports, "CURRENCY_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.CURRENCY_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.CURRENCY_PACKAGE; }
 });
 Object.defineProperty(exports, "DATETIME_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.DATETIME_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.DATETIME_PACKAGE; }
 });
 Object.defineProperty(exports, "DICE_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.DICE_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.DICE_PACKAGE; }
 });
 Object.defineProperty(exports, "FINANCE_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.FINANCE_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.FINANCE_PACKAGE; }
 });
 Object.defineProperty(exports, "FUNCTION_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.FUNCTION_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.FUNCTION_PACKAGE; }
 });
 Object.defineProperty(exports, "LINES_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.LINES_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.LINES_PACKAGE; }
 });
 Object.defineProperty(exports, "MAPREDUCE_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.MAPREDUCE_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.MAPREDUCE_PACKAGE; }
 });
 Object.defineProperty(exports, "MATHPHRASES_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.MATHPHRASES_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.MATHPHRASES_PACKAGE; }
 });
 Object.defineProperty(exports, "MATRIX_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.MATRIX_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.MATRIX_PACKAGE; }
 });
 Object.defineProperty(exports, "PERCENTAGE_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.PERCENTAGE_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.PERCENTAGE_PACKAGE; }
 });
 Object.defineProperty(exports, "SYMBOLIC_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.SYMBOLIC_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.SYMBOLIC_PACKAGE; }
+});
+Object.defineProperty(exports, "TABLES_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkOTN6SZOD_cjs.TABLES_PACKAGE; }
 });
 Object.defineProperty(exports, "TIME_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.TIME_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.TIME_PACKAGE; }
 });
 Object.defineProperty(exports, "UOM_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.UOM_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.UOM_PACKAGE; }
 });
 Object.defineProperty(exports, "VARIABLES_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.VARIABLES_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.VARIABLES_PACKAGE; }
 });
 Object.defineProperty(exports, "VECTOR_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.VECTOR_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.VECTOR_PACKAGE; }
 });
 Object.defineProperty(exports, "WEATHER_PACKAGE", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.WEATHER_PACKAGE; }
+  get: function () { return chunkOTN6SZOD_cjs.WEATHER_PACKAGE; }
+});
+Object.defineProperty(exports, "createCurrencyPackage", {
+  enumerable: true,
+  get: function () { return chunkOTN6SZOD_cjs.createCurrencyPackage; }
 });
 Object.defineProperty(exports, "createKnowledgePackage", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.createKnowledgePackage; }
+  get: function () { return chunkOTN6SZOD_cjs.createKnowledgePackage; }
 });
 Object.defineProperty(exports, "createStocksPackage", {
   enumerable: true,
-  get: function () { return chunk3AFRJYP4_cjs.createStocksPackage; }
+  get: function () { return chunkOTN6SZOD_cjs.createStocksPackage; }
 });
 //# sourceMappingURL=packages.cjs.map
 //# sourceMappingURL=packages.cjs.map

package/dist/packages.d.cts

@@ -1,17 +1,17 @@
-import { I as IEnginePackage } from './PackageRegistry-B37mRvvz.cjs';
-import './Parselet-DuI1Pjiq.cjs';
-import './BytecodeBuilder-B0xskcv5.cjs';
-import './Token-BzG5G4ja.cjs';
-import './pipeline-BEb3hujr.cjs';
-import './Value-CXJqDH9J.cjs';
+import { I as IEnginePackage } from './PackageRegistry-BHWJP83F.cjs';
+import './Parselet-BHcgK9S7.cjs';
+import './BytecodeBuilder-Bp9xeTmX.cjs';
+import './Token-B1hdkedD.cjs';
+import './pipeline-CtfJtPQc.cjs';
+import './Value-BUi1RA3S.cjs';
 import './variables.cjs';
-import './Lexer-D78E2yDW.cjs';
+import './Lexer-BOs7euZe.cjs';
 import './resolvers.cjs';
 import '@tanstack/query-core';
-import './TokenNormalizer-DGVa24Q-.cjs';
-import './ScopeManager-B6GzdhVG.cjs';
-import './EngineError-LU7W7AgI.cjs';
-import './Configuration-B-G5gTRn.cjs';
+import './TokenNormalizer-DRc1Js1V.cjs';
+import './ScopeManager-8vf02dwj.cjs';
+import './EngineError-B61GS1jp.cjs';
+import './Configuration-C9W8tJv_.cjs';
 
 /** Core arithmetic: numbers, `()` grouping, `pi`/`e` constants, `+ - * / % ^`, bitwise `<< >> & | ^`, and their `*_by` word forms. */
 declare const ARITHMETIC_PACKAGE: IEnginePackage;
@@ -27,6 +27,12 @@ declare const ARITHMETIC_PACKAGE: IEnginePackage;
  * variable-name-collision reason "total"/"average"/etc. are fused
  * elsewhere in this codebase, "what" is common enough to be worth
  * protecting as a `:variableName`.
+ *
+ * Successive change is `120 up 10% then down 10%` (118.80, not 120),
+ * `50 up 20%`, `80 down 15%` and the repeat form `100 up 10% three times`.
+ * `up`/`down` are retyped from a bare IDENT only when a percentage follows
+ * (percentUpDownNormalizerRule), so prose keeps the words. See
+ * UpDownParselet.ts.
  */
 declare const PERCENTAGE_PACKAGE: IEnginePackage;
 
@@ -46,6 +52,16 @@ declare const FUNCTION_PACKAGE: IEnginePackage;
  *   arithmetic, special-cased in `vm/VM.ts`'s ADD/SUB dispatch for the
  *   `workday`/`workdays` UNIT (see `lexer/units.ts`) since business-day
  *   math needs actual weekend-skipping, not a linear ms conversion.
+ * - `N working/business days after|from|before <date>`, the natural-language
+ *   spelling of the same offset (`5 working days after 20 Dec`,
+ *   `3 business days from today`). Fused as INFIX phrase tokens
+ *   (`WORKDAYS_AFTER`/`WORKDAYS_BEFORE`) since the count is the left operand;
+ *   emits `DATE_WORKDAY_OFFSET`, which walks the very same `addBusinessDays()`
+ *   as `<date> + N workdays`. See `WorkdayOffsetParselet.ts`.
+ * - `working/business days between <date> and <date>`, the COUNT of working
+ *   days in the inclusive window (`working days between 1 Jan and 31 Jan`), the
+ *   working-day sibling of `<unit> between` below. Emits
+ *   `DATE_WORKDAYS_BETWEEN`. See `WorkdaysBetweenParselet.ts`.
  * - `<amount>/workday x <duration>`, a Rate, exactly like `$99/week`
  *   already works, using `uom/UomConverter.ts`'s workday<->day shim so
  *   `getMeasure()`/`convertUnit()` treat "workday" as a Time-measure unit
@@ -64,8 +80,9 @@ declare const FUNCTION_PACKAGE: IEnginePackage;
  *   leading `how many` is accepted for it and for `until`/`since`, see
  *   `BetweenUnitNormalizerRule.ts`.
  * - `<date> is a weekend` / `is a workday`, postfix predicates, see
- *   `DayTypePredicateParselet.ts`. Mon-Fri only, matching the workday
- *   scope decision below.
+ *   `DayTypePredicateParselet.ts`. Mon-Fri only: these answer the week's
+ *   SHAPE (is this a weekday), which the holiday calendar deliberately does
+ *   not touch, see the scope note below.
  * - `current timestamp` / `<date/time> to timestamp` / `<ISO8601 string
  *   or unix timestamp> to date`. See `CurrentTimestampParselet.ts` /
  *   `ToTimestampParselet.ts` / `ToDateParselet.ts` and
@@ -89,16 +106,22 @@ declare const FUNCTION_PACKAGE: IEnginePackage;
  *   feature across two packages for a marginal "which package owns the
  *   converter-name list" tidiness gain.
  *
- * SCOPE DECISION (workdays, both the count and the date-arithmetic forms):
- * plain Mon-Fri business-day math, with NO public-holiday exclusion.
- * SoulverCore's own workday calculations auto-exclude public holidays via
- * a live-updating, region-configurable holiday database, picking which
- * holidays/region and keeping such a database current is real, separate
- * scope this pass deliberately does not take on (see `vm/VM.ts`'s
- * `addBusinessDays()` doc comment for the fuller version of this note,
- * matching this session's established pattern of documenting a scoped-down
- * simplification rather than silently pretending to support something it
- * doesn't, e.g. Finance's "no hardcoded tax rate" decision).
+ * SCOPE DECISION (holidays): the business-day WALK and COUNT (the offset forms,
+ * `between`, and `<date> + N workdays`) skip weekends always, and public
+ * holidays too when the host configures a calendar via `date.holidays` (see
+ * `constants/Configuration.ts` and `vm/HolidayCalendar.ts`). No calendar means
+ * weekends-only, the honest default: the engine excludes exactly the days it
+ * can prove are non-working. Picking a region's holidays and keeping them
+ * current is the host's to own, the same "bring your own data source" shape
+ * stocks and weather use, so this package never guesses a holiday the caller
+ * did not supply.
+ *
+ * Two workday features stay weekends-only by design, and say so: `workdays in
+ * <duration>` (a deterministic ratio with no anchor date, so no calendar to
+ * consult, see `WorkdaysInParselet.ts`) and the `is a weekend`/`is a workday`
+ * predicates (which report the week's Mon-Fri shape, a different question from
+ * "is this a working day here"). See `vm/VM.ts`'s `addBusinessDays()` for the
+ * walk's side of this.
  */
 declare const DATETIME_PACKAGE: IEnginePackage;
 
@@ -168,13 +191,62 @@ declare const VARIABLES_PACKAGE: IEnginePackage;
  */
 declare const UOM_PACKAGE: IEnginePackage;
 
+/**
+ * Resolve one historical exchange rate: the value of 1 unit of `from` in `to`
+ * on `isoDate` (`YYYY-MM-DD`). Supplied by the host, backed by whichever
+ * provider and key THEY have. Receives an `AbortSignal` that fires on caller
+ * cancellation or the fetch timeout, pass it to `fetch()`.
+ */
+type HistoricalRateProvider = (from: string, to: string, isoDate: string, signal: AbortSignal) => Promise<number>;
+
+/**
+ * Configuration for {@link createCurrencyPackage}.
+ *
+ * Live conversion (`100 USD in GBP`) needs no configuration, it is backed by
+ * the built-in Frankfurter/CoinGecko fetch and works out of the box. Only the
+ * historical form (`100 USD in GBP on <date>`) needs a host-supplied data
+ * source, since no free keyless historical-FX endpoint exists to bake in. See
+ * `uom/HistoricalCurrency.ts`'s module doc.
+ */
+interface CurrencyPackageConfig {
+    /**
+     * Resolve the exchange rate for one currency pair on one past date, backed
+     * by whichever provider and key the host has. Required for
+     * `<money> in <currency> on <date>` to return real data, when omitted, that
+     * form resolves to an honest `HISTORICAL_RATES_NOT_CONFIGURED` error `Value`
+     * rather than falling back to today's rate.
+     */
+    historicalRateProvider?: HistoricalRateProvider;
+}
+
 /**
  * Currency: `$10`, `£10`, `€10`, `¥10`, `₽10`, `₩10`, `₹10`, `₺10`, `₴10`,
- * `₪10`, `₫10`, `₦10`, `₱10`, `10 USD in GBP`, and word forms like
- * `10 euros`/`10 dollars` (see `uom/CurrencyAliases.ts` for the full
- * symbol/word alias tables and the ambiguity decisions behind them)
- * rates are fetched asynchronously (via {@link CurrencyAsyncResolver}) and
- * the expression shows Pending until they resolve.
+ * `₪10`, `₫10`, `₦10`, `₱10`, `10 USD in GBP`, `100 USD in GBP on 2024-01-15`,
+ * and word forms like `10 euros`/`10 dollars` (see `uom/CurrencyAliases.ts` for
+ * the full symbol/word alias tables and the ambiguity decisions behind them).
+ *
+ * Live rates are fetched asynchronously (via {@link CurrencyAsyncResolver}) and
+ * the expression shows Pending until they resolve. The dated `on <date>` form
+ * resolves through a HOST-SUPPLIED {@link CurrencyPackageConfig.historicalRateProvider}
+ * instead, unconfigured, it reports `HISTORICAL_RATES_NOT_CONFIGURED` plainly
+ * rather than drifting to today's rate (see `uom/HistoricalCurrency.ts`).
+ *
+ * **A factory, but still a default builtin.** Unlike stocks (no free provider,
+ * so excluded from `BUILTIN_PACKAGES`), the LIVE half of currency needs no
+ * configuration, so {@link CURRENCY_PACKAGE} = `createCurrencyPackage()` ships
+ * as a default. The historical resolver is registered either way, so the
+ * grammar always recognises `on <date>` and answers the not-configured case
+ * honestly; supplying a provider is what turns that error into a real rate. A
+ * host wanting historical conversion calls `createCurrencyPackage({ historicalRateProvider })`
+ * and swaps the result in for the default in its `packages` array.
+ */
+declare function createCurrencyPackage(config?: CurrencyPackageConfig): IEnginePackage;
+/**
+ * The default currency package, live rates configured, historical rates NOT.
+ *
+ * Kept as a named constant so existing imports and {@link BUILTIN_PACKAGES}
+ * keep working unchanged, a host wanting historical conversion builds its own
+ * via {@link createCurrencyPackage} and substitutes it in.
  */
 declare const CURRENCY_PACKAGE: IEnginePackage;
 
@@ -640,6 +712,38 @@ declare function createKnowledgePackage(config?: KnowledgePackageConfig): IEngin
  */
 declare const LINES_PACKAGE: IEnginePackage;
 
+/**
+ * Read a markdown table's column as data: `sum of column "cost" in table
+ * above`, `average of column "cost" above`.
+ *
+ * A markdown table is the one block the evaluator classifies and then skips,
+ * so a note can hold a table of numbers and none of them can be totalled from
+ * where they sit. This package addresses the nearest table above the query
+ * line, names one of its columns, and reduces that column's numeric cells,
+ * reusing the same cross-line plumbing the lines package built for `total
+ * above` (a per-line `LineExecutionContext`, extended with `getLineText` so
+ * the skipped table rows can be read back from source).
+ *
+ * Trigger-word collision policy (this codebase's phrase-fusion rule, see
+ * `MathPhrasesPackage.ts`): the whole verb-and-noun is phrase-fused, never the
+ * bare verb. `average of` is already fused to `AVERAGE_OF` by the math-phrases
+ * package; registering the longer `average of column` in the same phrase trie
+ * wins by longest-match, so plain `average of 1, 2, 3` is untouched while
+ * `average of column "x"` routes here. `sum of` is claimed by no one, so
+ * `sum of column` fuses cleanly. Synonyms (`total`->sum, `mean`->average)
+ * share a token type and parselet, matching how the lines package treats
+ * `sum`/`total` as one.
+ *
+ * Decisions worth stating (also in the docs and changeset):
+ * - Addressing: nearest table above only. An explicit table label is deferred.
+ * - Non-numeric cells: skipped, not an error, so a stray label or a blank cell
+ *   does not break an otherwise-numeric column. A column with no numbers at all
+ *   is a clear error (except `count`, which is then zero).
+ * - Currency and units in cells: not read yet. A cell carrying a `$` or a unit
+ *   is treated as non-numeric and skipped. Plain numbers first, on purpose.
+ */
+declare const TABLES_PACKAGE: IEnginePackage;
+
 /**
  * Built-in packages.
  *
@@ -658,8 +762,8 @@ declare const LINES_PACKAGE: IEnginePackage;
 /**
  * The packages an engine registers when the caller names none.
  *
- * Twenty of the twenty-two. Stocks and knowledge are excluded because both
- * need a host-supplied data source and do nothing useful without one, so
+ * Twenty-four of the twenty-six. Stocks and knowledge are excluded because
+ * both need a host-supplied data source and do nothing useful without one, so
  * registering them by default would only produce NOT_CONFIGURED results.
  *
  * Pass a filtered copy to the {@link ExpressionEngine} constructor to opt out
@@ -688,4 +792,4 @@ interface IVector4 {
     w: number;
 }
 
-export { ARITHMETIC_PACKAGE, BIGINT_PACKAGE, BUILTIN_PACKAGES, CONDITIONALS_PACKAGE, CONVERTERS_PACKAGE, CURRENCY_PACKAGE, type CityWeather, DATETIME_PACKAGE, DICE_PACKAGE, FINANCE_PACKAGE, FUNCTION_PACKAGE, type IVector2, type IVector3, type IVector4, type KnowledgePackageConfig, LINES_PACKAGE, MAPREDUCE_PACKAGE, MATHPHRASES_PACKAGE, MATRIX_PACKAGE, PERCENTAGE_PACKAGE, SYMBOLIC_PACKAGE, type StockHistoricalQuote, type StockQuote, type StocksPackageConfig, TIME_PACKAGE, UOM_PACKAGE, VARIABLES_PACKAGE, VECTOR_PACKAGE, WEATHER_PACKAGE, type WeatherQueryKind, createKnowledgePackage, createStocksPackage };
+export { ARITHMETIC_PACKAGE, BIGINT_PACKAGE, BUILTIN_PACKAGES, CONDITIONALS_PACKAGE, CONVERTERS_PACKAGE, CURRENCY_PACKAGE, type CityWeather, type CurrencyPackageConfig, DATETIME_PACKAGE, DICE_PACKAGE, FINANCE_PACKAGE, FUNCTION_PACKAGE, type HistoricalRateProvider, type IVector2, type IVector3, type IVector4, type KnowledgePackageConfig, LINES_PACKAGE, MAPREDUCE_PACKAGE, MATHPHRASES_PACKAGE, MATRIX_PACKAGE, PERCENTAGE_PACKAGE, SYMBOLIC_PACKAGE, type StockHistoricalQuote, type StockQuote, type StocksPackageConfig, TABLES_PACKAGE, TIME_PACKAGE, UOM_PACKAGE, VARIABLES_PACKAGE, VECTOR_PACKAGE, WEATHER_PACKAGE, type WeatherQueryKind, createCurrencyPackage, createKnowledgePackage, createStocksPackage };