solve-engine 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/packages.d.cts

@@ -0,0 +1,691 @@
+import { I as IEnginePackage } from './PackageRegistry-D-Tv_7ca.cjs';
+import './Parselet-CK8cQu2a.cjs';
+import './BytecodeBuilder-3egMyuDi.cjs';
+import './Token-0jpvUdPY.cjs';
+import './pipeline-DPUQt7yL.cjs';
+import './Value-KtAQNHur.cjs';
+import './variables.cjs';
+import './Lexer-BJdhlnej.cjs';
+import './resolvers.cjs';
+import '@tanstack/query-core';
+import './NormalizerRule-BrVoVjmP.cjs';
+import './ScopeManager-CKfQtl7l.cjs';
+import './EngineError-DvPSnhZi.cjs';
+import './Configuration-fVpd-HC-.cjs';
+
+/** Core arithmetic: numbers, `()` grouping, `pi`/`e` constants, `+ - * / % ^`, bitwise `<< >> & | ^`, and their `*_by` word forms. */
+declare const ARITHMETIC_PACKAGE: IEnginePackage;
+
+/**
+ * Percentage syntax: `50%`, `50% of 200`, `100 to 150` (percentage change),
+ * `increase 100 by 10%`/`decrease 100 by 10%` (prefix form), the
+ * `100 increase by 10%`/`100 decrease by 10%` infix form (fused from the
+ * "increase by"/"decrease by" phrases by the built-in normalizer. See
+ * BuiltinNormalizerRules.BUILTIN_PHRASES), and `5% of what is 6` (solve
+ * for the base value. See OfWhatIsParselet.ts's doc comment). "of what
+ * is" is phrase-fused (not a bare "what" keyword) for the same
+ * variable-name-collision reason "total"/"average"/etc. are fused
+ * elsewhere in this codebase, "what" is common enough to be worth
+ * protecting as a `:variableName`.
+ */
+declare const PERCENTAGE_PACKAGE: IEnginePackage;
+
+/** Built-in function call syntax, e.g. `sqrt(2)`, `sin(pi)`, dispatches recognized function names to CALL_BUILTIN opcodes. */
+declare const FUNCTION_PACKAGE: IEnginePackage;
+
+/**
+ * Date/time keywords: `now`, `today`, `tomorrow`, `yesterday`,
+ * `next <Weekday>`/`last <Weekday>`, `<unit> until <Datetime>`/`<unit> since <Datetime>`.
+ * Uses the datetime arithmetic opcodes (`DATE_ADD`/`DATE_SUB`/`DATE_NEXT_WEEKDAY`/`DATE_LAST_WEEKDAY`)
+ * plus the shared UoM conversion opcode (`UOM_CONVERT_IN`) for until/since.
+ *
+ * Also: workdays/weekdays and timestamps/ISO8601
+ *
+ * - `workdays in <duration>`. See `WorkdaysInParselet.ts`.
+ * - `<date> + N workdays` / `<date> - N workdays`, plain "+"/"-"
+ *   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.
+ * - `<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
+ *   (5 workdays == 7 calendar days). See that file's doc comment. The
+ *   bare-denominator syntax `$500/workday` (no explicit "1") additionally
+ *   needs `workdayRateDenominatorNormalizerRule`. See its doc comment.
+ * - `day of the week on <date>` / `weekday on <date>`, and the
+ *   natural-question forms over the same three date fields
+ *   `what day is it`, `what day is it on <date>`, `what day is it in
+ *   <duration>`, and the `month`/`week` equivalents. All one parselet, see
+ *   `DateFieldQueryParselet.ts`. The same fields are also available
+ *   composably as `<date> as weekday` / `as month` / `as week` via
+ *   `asConverters` below.
+ * - `<unit> between <date> and <date>`, the two-explicit-endpoints
+ *   sibling of `until`/`since`, see `DurationBetweenParselet.ts`. A
+ *   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.
+ * - `current timestamp` / `<date/time> to timestamp` / `<ISO8601 string
+ *   or unix timestamp> to date`. See `CurrentTimestampParselet.ts` /
+ *   `ToTimestampParselet.ts` / `ToDateParselet.ts` and
+ *   `DatetimeTimestampPluginFunctions.ts`.
+ * - Bare numeric date literals, `25/12/2023` (European DD/MM/YYYY)
+ *   `12-25-2023` (US MM-DD-YYYY), `2023-12-25` (ISO YYYY-MM-DD), and
+ *   `25.12.2023` (dot-separated DD.MM.YYYY), fused into a single
+ *   `DATETIME_LITERAL` token by `dateLiteralNormalizerRule()` and pushed by
+ *   `DateLiteralParselet`. Ported from the sibling `feat/safety-limits-datetime-literals`
+ *   branch referenced in `Iso8601.ts`'s and the Stocks package's
+ *   `DatePhrase.ts`'s doc comments. This is that work, now merged.
+ * - `<date/time> as iso8601`, registered below via `asConverters`
+ *   (the `Converters` package's `<expr> as <type>` extension point, see
+ *   `api/PackageRegistry.ts`'s doc comment) rather than a new opcode or a
+ *   `Converters`-package-owned built-in name: `asConverters` already
+ *   exists precisely for a third-party/domain package to contribute a
+ *   new `as <name>` target without touching `AsConverterParselet.ts` or
+ *   `OpCode.ts` at all, and "iso8601" is inherently a datetime-package
+ *   concept (needs `Iso8601.ts`'s formatting, which already lives here)
+ *   simpler to keep it self-contained in this package than to split the
+ *   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).
+ */
+declare const DATETIME_PACKAGE: IEnginePackage;
+
+/**
+ * Clock-time-of-day arithmetic: `9:00am`, `16:00`, `4pm` (anchored to
+ * today's calendar date), `7:30 to 20:45` / `4pm to 3am` interval
+ * durations (midnight-rollover aware), `30 fps` frame-rate literals (a
+ * `Rate` value. See `vm/Value.ts`), and `03:04:05` / `00:00:01.5`
+ * lap-time/stopwatch-split durations (two colons, vs clock-time's one).
+ * Distinct from the Datetime package's calendar-date arithmetic. See
+ * `packages/time/` vs `packages/datetime/`.
+ *
+ * Full HH:MM:SS:FF video-timecode literal parsing + fps-aware carry
+ * arithmetic: `01:02:03:04 at 30 fps` / `... @ 30 fps` (a `Uom(totalFrames,
+ * "timecode@<fps>")` value. See `vm/Value.ts`'s timecode section)
+ * `timecode + N frames` / `+ <duration>` / `+ timecode` (sum) / `-
+ * timecode` (difference), all special-cased in `vm/VM.ts`'s ADD/SUB
+ * dispatch (`combineTimecode()`), plus `timecode in frames` and the
+ * reverse `<N> frames @ <fps>` -> `HH:MM:SS:FF` string conversion (see
+ * `parselets/VideoTimecodeParselet.ts`/`FrameCountParselet.ts` and
+ * `timecode/TimecodeMath.ts`). `30 fps × <duration>` frame-count math
+ * (below) composes with this unchanged, the fps literal itself is
+ * unaffected by any of the above. Likewise, pretty-printing a duration
+ * back as `"3 hours 15 min"` (`as timespan`) or `"03:04:05"` (`as
+ * laptime`) is a `converters` package (Phase 1c) concern. This package
+ * only produces the underlying `Uom` values.
+ *
+ * Also: timezone conversion (`6pm Sydney in Chicago`), current
+ * time/date-in-a-zone queries (`time in Paris`, `date in Vancouver`), and
+ * zone-offset deltas (`time difference between Seattle and Moscow`). See
+ * `timezones/CityZones.ts`/`ZoneMath.ts`. Built entirely on native
+ * `Intl.DateTimeFormat`/IANA data, no external dependency. Results are
+ * `String` values (formatted, human-readable), not `Datetime`. This
+ * engine's `Datetime` representation is a bare epoch-ms number with no
+ * zone tag, so there's no way to represent "this instant, but interpreted
+ * through zone X" as anything other than a pre-formatted string; see
+ * `ZoneMath.ts`'s doc comment.
+ *
+ * SCOPE DECISION: the alternate phrasing `<City> time` (e.g. "Tokyo
+ * time", city first) is deliberately NOT implemented, it would need
+ * "time" registered as a keyword reachable from a BARE city identifier's
+ * infix position, and "time" is exactly the kind of common noun this
+ * session found real trouble with (see MathPhrasesPackage.ts's "total"
+ * regression note). `time in <city>` covers the same need unambiguously.
+ */
+declare const TIME_PACKAGE: IEnginePackage;
+
+/** `roll(min, max)`, returns a random integer in the inclusive `[min, max]` range. */
+declare const DICE_PACKAGE: IEnginePackage;
+
+/** Variable read/write: `:name = expr` to define, `name` to read, plus `global :name` for a document-spanning variable backed by the {@link GlobalVariableStore} instead of local VM scope. */
+declare const VARIABLES_PACKAGE: IEnginePackage;
+
+/**
+ * Units of measurement: `10 km`, `10 km to miles`, `convert 10 km to miles`,
+ * `cm to ?` (conversion-possibilities query). See {@link CURRENCY_PACKAGE}
+ * for money, which is a separate package.
+ *
+ * Also cooking/baking mass<->volume conversion (e.g. "300g butter in
+ * cups", "10 cups olive oil in grams"). See
+ * `parselets/CookingConversionParselet.ts`,
+ * `normalizer/IngredientNameNormalizerRule.ts`, and
+ * `data/IngredientDensities.ts` (the bundled, clearly-labeled-approximate
+ * ingredient-density table and its scope/accuracy doc comment) for the
+ * full design, including why US Customary is the only volume-unit
+ * convention supported so far.
+ */
+declare const UOM_PACKAGE: IEnginePackage;
+
+/**
+ * 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.
+ */
+declare const CURRENCY_PACKAGE: IEnginePackage;
+
+/**
+ * Vector literals `vec2(x, y)`/`vec3(x, y, z)`/`vec4(x, y, z, w)` plus float
+ * literals, legacy construction sugar kept working after the Calca-parity
+ * Matrix rewrite; each just builds a 1xN row-vector `ValueType.Matrix` via
+ * `OpCode.MAT_NEW` (see vm/MatrixOps.ts). The bracket literal `[x, y, z]`
+ * (packages/matrix/) is the primary, Calca-parity construction syntax going
+ * forward.
+ */
+declare const VECTOR_PACKAGE: IEnginePackage;
+
+/**
+ * Matrix literals `[1, 2; 3, 4]` and indexing `a[i]`/`a[row, col]`
+ * Calca-parity general matrix support (a vector is just a 1xN or Nx1
+ * matrix). See `vm/Value.ts`'s `MatrixData` and `vm/MatrixOps.ts`'s shared
+ * column-major storage helpers.
+ *
+ * `LBRACKET` is registered in BOTH prefix and infix slots, separate
+ * registry lookups keyed on parse position, not a collision: a literal
+ * opens in prefix position (right after `=`, `(`, an operator, ...) and an
+ * index opens in infix/postfix position, right after any value-producing
+ * expression.
+ */
+declare const MATRIX_PACKAGE: IEnginePackage;
+
+/**
+ * `map`/`reduce`/`sum`/`prod`, Calca-parity collection transforms over a
+ * Matrix or a bare Range. See `MapReduceShared.ts` for the shared
+ * transform-disambiguation/collection-parsing logic, and `vm/VM.ts`'s
+ * `MAP_INVOKE`/`REDUCE_INVOKE` opcode handlers for the runtime semantics.
+ *
+ * `map`/`reduce`/`sum`/`prod` are NOT bare keywordMap entries. See
+ * `MapReduceCallNormalizerRule.ts`, which fuses them into their own token
+ * types only when immediately followed by `(`, so `:map = [...]` etc.
+ * keep working as ordinary variable names.
+ */
+declare const MAPREDUCE_PACKAGE: IEnginePackage;
+
+/**
+ * Symbolic algebra verbs: multiplying out, and (in later phases) factoring,
+ * solving and calculus.
+ *
+ * The algebra itself lives in `symbolic/`, which is pure mathematics over the
+ * expression tree. This package is only the grammar surface: which words become
+ * which tokens, and which parselet emits which builtin call.
+ *
+ * None of these words is a bare `keywordMap` entry. See
+ * `normalizer/SymbolicCallNormalizerRule.ts` for why that matters.
+ */
+declare const SYMBOLIC_PACKAGE: IEnginePackage;
+
+/** Arbitrary-precision integer literals (suffixed, e.g. `123n`) that overflow a normal `number` without losing precision. */
+declare const BIGINT_PACKAGE: IEnginePackage;
+
+/**
+ * Comparisons (`==`, `!=`, `<`, `>`, `<=`, `>=`), boolean logic (`true`/
+ * `false`, `and`/`or`/`&&`/`||`), and `if <cond> then <val> else <val>`
+ * eager-ternary conditionals.
+ *
+ * The `and`/`or` split is deliberate, not an oversight: "and" already
+ * lexes as `PLUS` (a pre-existing arithmetic word-synonym, `en.ts`:
+ * `and: "PLUS"`), a Tier-1 hardcoded infix operator no registry-based
+ * parselet can intercept, `OpCode.ADD`'s own VM handler special-cases
+ * `Boolean && Boolean` instead (see `vm/VM.ts`). "or"/"&&"/"||" have no
+ * such collision and are handled normally here via `LogicalParselet`.
+ *
+ * KNOWN LIMITATION: because "and" is pinned to `PLUS`'s Tier-1 binding
+ * power (`Sum`, tighter than comparisons), an unparenthesized `X >= Y and
+ * Z < W` does NOT parse as `(X >= Y) and (Z < W)`, "and"'s fixed
+ * precedence grabs a comparison operand instead. Use `&&` (correct,
+ * dedicated `LogicalAnd` precedence, looser than comparisons) for that
+ * pattern, or wrap each side in parens if "and" is preferred:
+ * `(X >= Y) and (Z < W)`. "and" alone (no comparisons in the same
+ * unparenthesized expression) works fine, e.g. `discount and hasCoupon`.
+ *
+ * SCOPE DECISION: SoulverCore-style postfix `Y if X` / `Y unless X` (a
+ * ternary with no explicit else-branch) is deliberately NOT implemented.
+ * This VM's `Value` has no "empty"/"void" representation for the
+ * false-branch case (every expression must produce a concrete typed
+ * result), building it properly would mean adding a new sentinel
+ * `ValueType` and deciding how every consumer (formatting, DAG
+ * propagation, UOM/arithmetic ops) treats it, which is a bigger call than
+ * this package should make implicitly. `if X then Y else Z` (both
+ * branches required) covers the same need unambiguously today.
+ */
+declare const CONDITIONALS_PACKAGE: IEnginePackage;
+
+/**
+ * The general `<expr> as <type>` conversion/display mechanism, one
+ * unifying grammar point rather than N unrelated per-type features.
+ *
+ * Ships the built-in set immediately usable (see `BUILTIN_CONVERTERS` in
+ * `AsConverterParselet.ts`): `as %`/`as percent`, `as decimal`/`as dec`/
+ * `as number`, `as fraction`, `as multiplier`, `as sci`, `as hex`/
+ * `as binary`/`as octal`.
+ *
+ * This is also the other clearly SDK-shaped piece from the SoulverCore
+ * feature-parity work (alongside `PhrasePattern`/`createQueryResolver`):
+ * `IEnginePackage.asConverters` (see `api/PackageRegistry.ts`) lets a
+ * third-party package contribute its own `as <name>` target without
+ * touching this package at all, resolved at VM-execution time via
+ * `OpCode.CALL_AS_CONVERTER` against `vm/VMBuiltins.ts`'s
+ * `asConverterRegistry`.
+ *
+ * SCOPE DECISION: no `as x` alias for `as multiplier`, "x" is too likely
+ * to collide with ordinary variable names (algebraic use, `x = 5`) to
+ * justify claiming it as a global keyword for one converter's sake.
+ */
+declare const CONVERTERS_PACKAGE: IEnginePackage;
+
+/**
+ * Phrase-grammar math functions: `average/median/total/count of X, Y, Z`,
+ * `larger/smaller of X and Y`, `half of X`, `midpoint between X and Y`,
+ * `random number between X and Y`, `clamp X between Y and Z`, and the
+ * unit-aware proportion form `A is to B as C is to what`.
+ *
+ * TRIGGER-WORD COLLISION DESIGN NOTE (real regression found and fixed
+ * during development): "average", "total", "count", "larger", "smaller",
+ * "half", and "midpoint" are all common, natural variable names (a
+ * shipped playground example uses `:total = :afterDiscount + :tax`).
+ * This codebase has a tested, intentional policy that a colon-prefixed
+ * variable name can't be a keyword-shaped word (see VariableParselet.ts's
+ * doc comment and its "reserved-keyword regression" test), so claiming
+ * any of those as a BARE global keyword would have permanently broken
+ * `:total = ...`-style usage, which is exactly what happened on the first
+ * pass of this package.
+ *
+ * The fix: fuse the full two-word phrase ("average of", "total of",
+ * "half of", "midpoint between", ...) into its own token via the
+ * `phrases` field below, instead of claiming the leading word alone. The
+ * bare word then never becomes its own token type, it stays a plain
+ * IDENT (usable as a variable) unless immediately followed by its
+ * qualifying keyword. `clamp` is the one exception, kept as a bare
+ * keyword: "clamp X between Y and Z" has the value X sitting between the
+ * trigger and "between"/"from", so the two words aren't adjacent and
+ * can't be phrase-fused. Same accepted risk profile as this codebase's
+ * existing bare "between"/"from"/"next"/"last"/"best" keywords.
+ *
+ * Most of the fused-trigger parselets are hand-written rather than built
+ * on `PhrasePattern`, for a related reason: once the leading keyword is
+ * fused away into the trigger token itself, the next thing in each
+ * grammar is an `expr` (the value), not a keyword, `definePhrasePattern`
+ * requires every alternative to start with a keyword slot. See
+ * `ClampParselet.ts`'s doc comment for the same structural point.
+ * `random number between X and Y` and `A is to B as C is to what` are the
+ * two exceptions that still have a genuine keyword after their own fused
+ * trigger ("between"/"as"), so `RandomNumberParselet` stays
+ * PhrasePattern-based.
+ */
+declare const MATHPHRASES_PACKAGE: IEnginePackage;
+
+/**
+ * Money & finance phrase grammar: compound interest / investment growth,
+ * mortgage/loan repayment (standard amortization formula), sales tax/VAT
+ * add-and-remove, and CPI-based inflation-adjusted value. SoulverCore-
+ * inspired syntax where it could be confirmed (see each parselet's doc
+ * comment for exact worked examples and any deliberate deviations);
+ * function-call forms (`compoundInterest(...)`, `monthlyPayment(...)`,
+ * `taxAdd(...)`, `inflationAdjust(...)`, ...) are registered separately,
+ * in FUNCTION_PACKAGE's shared FUNC dispatch (see
+ * `packages/function/parselets/FunctionCallParselet.ts`'s
+ * `builtinNameToIndex` map) rather than here.
+ *
+ * TRIGGER-WORD COLLISION DESIGN NOTE (same regression class documented in
+ * MathPhrasesPackage.ts, and explicitly called out for this package
+ * up-front): "interest", "tax", "principal", "payment", "rate", "balance",
+ * "what", "worth", "value" are all common, plausible variable names, a
+ * shipped playground example already uses `:tax` (`:total = :subtotal +
+ * :tax`, see MathPhrasesPackage.ts's doc comment). None of those words are
+ * bare keywords anywhere in this package. Every trigger is either:
+ *  - a full phrase fused via `phrases` below ("interest on", "tax on",
+ *    "monthly repayment on", "what is", "what was", "value of", "worth
+ *    in", ...), so the leading word alone never becomes its own token
+ *    type and stays usable as `:interest`/`:tax`/`:what`/`:value`/etc., or
+ *  - a genuine preposition ("over", "at") with near-zero plausibility as a
+ *    variable name, the same accepted-risk category as this codebase's
+ *    existing bare "between"/"from"/"next"/"last"/"best" keywords (see
+ *    Token.ts's OVER/RATE_AT doc comment).
+ *
+ * Inflation-adjusted value (extends this package, see
+ * `parselets/InflationQueryParselet.ts`/`InflationFutureValueParselet.ts`/
+ * `InYearDollarsParselet.ts` and `data/CpiTable.ts` for the bundled,
+ * clearly-labeled-approximate CPI-U table and its doc comment on
+ * vintage/accuracy) was the one topic explicitly deferred from this
+ * package's original scope, now implemented.
+ */
+declare const FINANCE_PACKAGE: IEnginePackage;
+
+/**
+ * Weather lookups through Open-Meteo, a keyless public endpoint.
+ *
+ * The one built-in package that reaches the network. It needs no configuration,
+ * which is why it can be a default where stocks and knowledge cannot, but a
+ * host wanting no outbound traffic should assemble its own package list rather
+ * than using {@link BUILTIN_PACKAGES}.
+ */
+declare const WEATHER_PACKAGE: IEnginePackage;
+
+/**
+ * Current conditions for one place, as returned by Open-Meteo.
+ *
+ * Temperatures are Celsius at this layer; conversion to the display unit
+ * happens later, so the shape stays independent of formatting settings.
+ */
+interface CityWeather {
+    /** The resolved place name Open-Meteo matched, e.g. "London" for input "london". */
+    resolvedName: string;
+    /** WMO weather code. See WmoWeatherCodes.ts. */
+    weatherCode: number;
+    /** Human-readable description derived from weatherCode, e.g. "overcast". */
+    description: string;
+    /** Current temperature, Celsius. */
+    temperature: number;
+    /** "Feels like" temperature, Celsius. */
+    apparentTemperature: number;
+    /** Today's forecast high, Celsius. */
+    high: number;
+    /** Today's forecast low, Celsius. */
+    low: number;
+}
+
+/** The 5 SoulverCore-documented weather query kinds, encoded as the first
+ * segment of the query string this package's single async resolver caches
+ * on (see WeatherPackage.ts's `WEATHER_FN_IDX` / `createQueryResolver` call
+ *, one resolver, one plugin function, kind+city both folded into the
+ * query string it scans for). */
+type WeatherQueryKind = "current" | "temperature" | "feelslike" | "high" | "low";
+
+/** A current stock quote, as returned by a host-supplied `fetchQuote`. */
+interface StockQuote {
+    /** Current price, in `currency` (default "USD"). */
+    price: number;
+    /** ISO 4217 currency code. Defaults to "USD" if omitted. */
+    currency?: string;
+}
+/** A historical stock quote for one calendar date, as returned by a host-supplied `fetchHistoricalQuote`. */
+interface StockHistoricalQuote {
+    /** Closing price on the requested date, in `currency` (default "USD"). */
+    close: number;
+    /** Trading volume (share count) on the requested date, if available. */
+    volume?: number;
+    /** ISO 4217 currency code. Defaults to "USD" if omitted. */
+    currency?: string;
+}
+/**
+ * Configuration for {@link createStocksPackage}. See `StocksPackage.ts`'s
+ * module doc for the full "bring your own data source" rationale.
+ */
+interface StocksPackageConfig {
+    /**
+     * Fetch the current quote for `ticker` (already upper-cased). Required
+     * for `stock(TICKER)` / `N stock(TICKER)` to return real data, when
+     * omitted, those expressions resolve to an honest
+     * `STOCKS_NOT_CONFIGURED` error `Value`, never a faked/zero price.
+     */
+    fetchQuote?: (ticker: string, signal: AbortSignal) => Promise<StockQuote>;
+    /**
+     * Fetch a historical quote for `ticker` on `isoDate` (`YYYY-MM-DD`).
+     * Required for the `on <date>` / `close on <date>` / `volume on <date>`
+     * forms, when omitted, those expressions resolve to an honest
+     * `STOCKS_NOT_CONFIGURED` error `Value`.
+     */
+    fetchHistoricalQuote?: (ticker: string, isoDate: string, signal: AbortSignal) => Promise<StockHistoricalQuote>;
+    /**
+     * Enable the bare-ticker grammar (`AAPL` alone, no `stock(...)`
+     * wrapper) for the small bundled allow-list in `MajorTickers.ts`.
+     * Default `false`, a bare all-caps word is genuinely ambiguous with a
+     * variable name (`:AAPL = 5`), so this is opt-in even though the
+     * package itself is already opt-in. The `stock(TICKER)` function-call
+     * form works regardless of this setting and is the only ALWAYS-
+     * reachable syntax. See StocksPackage.ts's module doc.
+     */
+    enableBareTickerRecognition?: boolean;
+    /**
+     * TanStack Query staleTime for CURRENT-price lookups, in ms. Default 60s
+     *, intraday quotes move continuously, so a short stale window keeps
+     * re-evaluation reasonably fresh without re-fetching on every keystroke.
+     */
+    staleTimeMs?: number;
+    /**
+     * TanStack Query staleTime for HISTORICAL (`on <date>`) lookups, in ms.
+     * Default 30 days, a closing price for a specific past date is
+     * immutable, so this is set long purely to avoid pointless repeat
+     * fetches, not because the data could go stale.
+     */
+    historicalStaleTimeMs?: number;
+}
+
+/**
+ * Live stock prices, `stock(TICKER)`, `stock(TICKER) on <date>`
+ * `stock(TICKER) close on <date>`, `stock(TICKER) volume on <date>`, plus
+ * an opt-in bare-ticker form (`AAPL`, `AAPL on April 12, 2005`, ...).
+ *
+ * **Why a factory, not a constant `STOCKS_PACKAGE` export**: unlike
+ * Weather's Open-Meteo, there is no free/keyless stock-quote API, every
+ * option surveyed (Alpha Vantage, Finnhub, Twelve Data, IEX Cloud, ...)
+ * requires the HOST application to sign up for its own API key. Baking in
+ * a specific paid provider (or worse, a hardcoded key) would either not
+ * work out of the box for most hosts or silently commit them to a vendor
+ * choice they didn't make. Instead this package is an extension point
+ * "packages are our approach, we're providing an SDK", a host supplies
+ * `fetchQuote`/`fetchHistoricalQuote` (backed by whichever provider and
+ * key THEY have) via {@link createStocksPackage}'s `config` argument. No
+ * config -> every stock expression resolves to a clearly-worded
+ * `STOCKS_NOT_CONFIGURED` error `Value`, never a faked or zero price (see
+ * `packages/finance/parselets/SalesTaxParselet.ts`'s doc comment for the
+ * same "never guess a number the caller didn't provide" principle applied
+ * to a different package).
+ *
+ * **Not a member of `BUILTIN_PACKAGES`** (see `packages/builtins.ts`)
+ * unconfigured, this package does nothing useful, exactly like
+ * `examples/osrs` is deliberately excluded from the built-in set. A host
+ * that wants it calls `createStocksPackage({ fetchQuote, ... })` and adds
+ * the result to their `ExpressionEngine`'s `packages` array themselves.
+ *
+ * **Ticker recognition**: the function-call form `stock(TICKER)` is the
+ * PRIMARY, always-reachable syntax, a bare all-caps word ("AAPL") is
+ * genuinely ambiguous with a variable name (`:AAPL = 5` is a reasonable
+ * thing to write), so it is never claimed unconditionally. The bare form
+ * is available only via `config.enableBareTickerRecognition`, gated to a
+ * small bundled allow-list of major tickers (`MajorTickers.ts`). See
+ * `normalizer/StockTickerNormalizerRule.ts`'s doc comment for the full
+ * reasoning, mirroring `time/timezones/CityZones.ts`'s known-table
+ * mitigation for the same class of ambiguity.
+ *
+ * **Two separate async resolvers** (`stocks-current`/`stocks-historical`,
+ * two distinct `CALL_PLUGIN` indices) rather than one shared one, unlike
+ * Weather's single shared resolver, current-price and historical-close
+ * lookups warrant genuinely different `staleTimeMs` (a live quote goes
+ * stale in seconds; a historical close for a fixed past date never goes
+ * stale at all), and `createQueryResolver` bakes `staleTimeMs` into the
+ * resolver instance, not the per-call query.
+ */
+declare function createStocksPackage(config?: StocksPackageConfig): IEnginePackage;
+
+/**
+ * Configuration for {@link createKnowledgePackage}. See
+ * `KnowledgePackage.ts`'s module doc for the "bring your own answer
+ * engine" rationale (same pluggable-provider approach as `packages/stocks`).
+ */
+interface KnowledgePackageConfig {
+    /**
+     * Answer a free-text query verbatim (e.g. "distance to the moon",
+     * captured from `distance to the moon = ?`) and return a plain-text
+     * answer string. Required for `<query> = ?` to return real data, when
+     * omitted, that expression resolves to an honest `KNOWLEDGE_NOT_CONFIGURED`
+     * error `Value`, never a hallucinated/guessed answer.
+     */
+    answerQuery?: (query: string, signal: AbortSignal) => Promise<string>;
+    /**
+     * TanStack Query staleTime for answered queries, in ms. Default 5
+     * minutes (matches `createQueryResolver`'s own default), most
+     * knowledge-style facts ("distance to the moon") don't change
+     * meaningfully within a session, but a short-ish default avoids
+     * treating a genuinely time-sensitive answer (e.g. "population of
+     * Tokyo = ?") as permanently fixed.
+     */
+    staleTimeMs?: number;
+}
+
+/**
+ * Knowledge-assistant queries, open-ended questions answered by a
+ * host-supplied provider. Two supported surface forms, both producing the
+ * exact same `KNOWLEDGE_QUERY` token/behavior (see the two
+ * `rawLinePatterns` entries below):
+ *
+ * - **`search: <query>` / `ask: <query>` / `google: <query>`** (preferred,
+ *   added this iteration), a clear, self-documenting leading verb, e.g.
+ *   `search: distance to the moon`. Reads like an instruction, not a
+ *   cryptic punctuation puzzle.
+ * - **`<query> = ?`** (the original form, kept for Calca-style
+ *   compatibility. see the internal parity notes)
+ *   e.g. `distance to the moon = ?`. Less discoverable (a bare trailing
+ *   `= ?` doesn't read as "ask a question" the way a leading verb does),
+ *   but harmless to keep alongside the clearer form. This package has no
+ *   opinion about which one a host's users end up preferring.
+ *
+ * SoulverCore's own version of this feature calls out to Wolfram|Alpha;
+ * there is no free equivalent of comparable quality, so. Same
+ * pluggable-provider approach as `packages/stocks`, a host supplies
+ * `answerQuery` via {@link createKnowledgePackage}'s `config` argument. No
+ * config -> every query resolves to a clearly-worded
+ * `KNOWLEDGE_NOT_CONFIGURED` error `Value`, never a hallucinated/guessed
+ * answer.
+ *
+ * **Not a member of `BUILTIN_PACKAGES`**, unconfigured, this package does
+ * nothing useful, exactly like `packages/stocks` and `examples/osrs`.
+ *
+ * ## Why this package is architecturally different from every other one
+ *
+ * Every other package in this codebase (including its sibling
+ * `weather`/`stocks`) is "structured syntax evaluates to a value", the
+ * grammar is known in advance, and the lexer/parser tokenize it like any
+ * other expression. This package's grammar is "arbitrary free text,
+ * terminated (or introduced) by a fixed marker, gets shipped to an
+ * external function verbatim", `distance to the moon` is not valid Solve
+ * syntax (it would never parse as arithmetic), so it can't be
+ * tokenized-then-parsed the normal way at all.
+ *
+ * The fix lives one layer below the parser: `ExpressionLexer.ts` gained a
+ * new, generic extension point, `LexerVocabulary.rawLinePatterns` (see
+ * its doc comment there for the full design). A `rawLinePatterns` rule
+ * tests the RAW line text, before any per-character tokenization, and
+ * if it matches, the whole line becomes ONE synthetic token whose value
+ * is the matched capture group, verbatim. This package is that
+ * mechanism's reference/motivating use.
+ *
+ * **Why `search:`/`ask:`/`google:` require a literal trailing colon, not
+ * just a following space**: without it, `search 5` (a line reading the
+ * plain variable `search`, legitimately assignable via `:search = 5`
+ * since these are ordinary lowercase words, not reserved, followed by
+ * what would otherwise be implicit-multiply-adjacent text) would be
+ * silently hijacked into a knowledge query for `"5"` instead of failing
+ * or reading the variable. Requiring `:` immediately after the keyword
+ * (`search:`, not `search `) is not valid syntax ANYWHERE else in this
+ * grammar, so it introduces zero ambiguity with a real `:name = value`
+ * variable of the same name. See the regression test guarding this
+ * exact scenario.
+ *
+ * No existing Solve syntax uses a bare `= ?` marker either (the
+ * codebase's other "possibilities" feature, `cm to ?`, is a different
+ * token shape, `TO QUESTION`, not `EQUALS QUESTION`. See
+ * `packages/uom/normalizer/PossibilitiesNormalizerRule.ts`), so neither
+ * form claims any ambiguity with existing grammar; both only activate for
+ * lines a host has opted into via this package in the first place.
+ */
+declare function createKnowledgePackage(config?: KnowledgePackageConfig): IEnginePackage;
+
+/**
+ * Cross-line data access, reading another line's cached result from
+ * inside an expression. Confirmed by FOUR independent competitor apps
+ * wanting the exact same underlying capability (Numi's `prev`, Notes
+ * Calculator's `line<N>`, Numbr's `sum`/`total`-to-header, NumPad's
+ * `line<N>` plus range aggregation). See the internal parity notes'
+ * "Confirmed engine limitations" item 1, now closed.
+ *
+ * Built entirely on `vm/VM.ts`'s `LineExecutionContext`, threaded
+ * optionally through `CALL_PLUGIN`, every handler here explicitly checks
+ * for `Pending`/`Error`/unevaluated lines before doing arithmetic (see
+ * `LinesPluginFunctions.ts`'s module doc) rather than silently coercing
+ * via `.toNumber()` (which returns `0` for both `Pending` and `Error`).
+ *
+ * Trigger-word collision decisions (this codebase's established
+ * phrase-fusion-vs-bare-keyword policy, see `ARCHITECTURE.md` §5.1):
+ * - `prev`, bare keyword (nothing to phrase-fuse against, same shape as
+ *   `clamp`). Accepted risk.
+ * - `line1`/`line 1`, normalizer-fused into `LINE_REF`, never claims
+ *   bare `line` as a keyword (`:line = 5` stays untouched). The `l1`/`l 1`
+ *   short alias documented by some competitors is deliberately NOT
+ *   implemented in this pass, `l` is too common a variable name; ship
+ *   `line<N>` first, add a narrower `l<N>` form later if real usage wants
+ *   it.
+ * - `sum(`/`total(`/`average(`, normalizer-fused ONLY when immediately
+ *   followed by `LPAREN`, so `:sum = 100` and MathPhrases' existing
+ *   `"total of X, Y"` phrase (no paren after "of") are both unaffected.
+ * - "aggregate everything above until a blank line/heading"
+ *   phrase-fused as `"total above"`/`"sum above"`/`"average above"`
+ *   (deliberately NOT Numi/Numbr's bare `total`/`sum` wording, that's
+ *   exactly the bare-keyword collision class this codebase already
+ *   regressed on once, see `MathPhrasesPackage.ts`'s "total" note).
+ */
+declare const LINES_PACKAGE: IEnginePackage;
+
+/**
+ * Built-in packages.
+ *
+ * Each domain is a self-contained package (its own directory, its own
+ * `{Domain}Package.ts` defining an IEnginePackage, its own `index.ts`
+ * barrel), the same shape as third-party packages such as the OSRS
+ * example in `src/solve-js/examples/osrs/`. This file's only job is to
+ * assemble them into BUILTIN_PACKAGES; it re-exports each named package
+ * too, since existing call sites import them directly from here.
+ *
+ * This enables:
+ * - Selective disable of built-in packages
+ * - External packages to replace/extend built-in ones
+ */
+
+/**
+ * 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
+ * registering them by default would only produce NOT_CONFIGURED results.
+ *
+ * Pass a filtered copy to the {@link ExpressionEngine} constructor to opt out
+ * of a feature, or add to it to register your own alongside the built-ins.
+ */
+declare const BUILTIN_PACKAGES: IEnginePackage[];
+
+/** A 2-component vector value, as produced by `vec2(x, y)`. */
+interface IVector2 {
+    x: number;
+    y: number;
+}
+
+/** A 3-component vector value, as produced by `vec3(x, y, z)`. */
+interface IVector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/** A 4-component vector value, as produced by `vec4(x, y, z, w)`. */
+interface IVector4 {
+    x: number;
+    y: number;
+    z: number;
+    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 };