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

package/dist/uom.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"uom.cjs"}

package/dist/uom.d.cts

@@ -0,0 +1,224 @@
+import { QueryClient } from '@tanstack/query-core';
+import { T as Token } from './Token-0jpvUdPY.cjs';
+import { a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.cjs';
+import { IAsyncResolver, AsyncCheckResult } from './resolvers.cjs';
+import './Value-KtAQNHur.cjs';
+
+/**
+ * Caches exchange rates fetched from an external source.
+ *
+ * Rates are global market data rather than per-engine configuration, which is
+ * why one instance is shared. Two engines with private copies would fetch the
+ * same endpoint twice and could disagree about one pair at one moment. See
+ * `engine/EngineContext.ts`.
+ */
+declare class CurrencyExchangeService {
+    /**
+     * Live rate tables cached from successful getRate() fetches, keyed by
+     * uppercase base currency. Each table holds every rate the API returned
+     * for that base (plus the base itself at 1), so any pair whose two codes
+     * appear in one fresh table can be served synchronously, including
+     * cross pairs via triangulation (EUR→GBP through a USD-base table).
+     * Stale tables are ignored, not evicted; the next successful fetch for
+     * the same base overwrites them.
+     */
+    private baseTables;
+    /**
+     * How long a fetched rate may be served synchronously by getRateSync().
+     * Beyond this window callers fall through to the async path (expression
+     * shows Pending until the fetch lands).
+     */
+    private static readonly RATE_FRESHNESS_MS;
+    /**
+     * Ticker → CoinGecko coin id, for the cryptocurrencies `isCurrency()`
+     * recognizes. Frankfurter (the fiat rate source below) is ECB reference
+     * rates only and has no concept of BTC/ETH/etc, routing a crypto code
+     * through it as `base=BTC` fails outright, which is why crypto pairs
+     * previously never resolved (see CurrencyAsyncResolver/VM.ts's ADD
+     * handling for the two bugs that let that failure pass silently instead
+     * of surfacing as a real fetch).
+     */
+    private static readonly CRYPTO_IDS;
+    private isCryptoCode;
+    constructor();
+    /**
+     * Timeout (ms) for currency exchange rate fetches.
+     *
+     * If the frankfurter API doesn't respond within this window, the fetch
+     * is aborted, preventing indefinite "Pending" states in the playground
+     * and Obsidian plugin when the exchange rate API is unreachable.
+     */
+    private static readonly FETCH_TIMEOUT_MS;
+    /**
+     * Fetch the live exchange rate for converting 1 unit of `from` into `to`.
+     *
+     * Routes cryptocurrency codes (see {@link CRYPTO_IDS}) to CoinGecko and
+     * everything else to Frankfurter (ECB reference rates, fiat-only). On
+     * success, caches the whole returned rate table for `from` so subsequent
+     * lookups, including cross-pairs via triangulation, can be served
+     * synchronously by {@link getRateSync} within the freshness window.
+     *
+     * @throws If the currency code is unrecognized or the fetch fails/times out.
+     */
+    getRate(from: string, to: string, signal?: AbortSignal): Promise<number>;
+    /**
+     * Crypto rate fetch, routed through CoinGecko's no-auth simple-price
+     * endpoint instead of Frankfurter (fiat-only, has no BTC/ETH concept).
+     * Handles all three combinations, crypto→crypto, crypto→fiat
+     * fiat→crypto, via prices denominated in USD (or the target fiat
+     * directly, which CoinGecko's `vs_currencies` also accepts), then
+     * caches the result as a same-shaped base table so getRateSync /
+     * convertSync keep working unchanged for crypto pairs too.
+     */
+    private getCryptoRate;
+    private fetchCoinGeckoPrices;
+    /**
+     * Seed a base rate table without a network fetch.
+     *
+     * Intended for tests and for future user-provided offline rates
+     * production live data always comes from {@link getRate}. Seeded rates
+     * obey the same freshness window as fetched ones.
+     *
+     * @param base - Base currency code (e.g. "USD").
+     * @param rates - Map of currency code → rate relative to the base.
+     */
+    primeRates(base: string, rates: Record<string, number>): void;
+    /**
+     * Drop every cached/primed rate table.
+     *
+     * Mainly for test isolation: {@link sharedCurrencyExchange} is a
+     * module-level singleton, so a rate primed or fetched by one test can
+     * silently leak into a later test in the same file. Also usable in
+     * production if a caller ever wants to force a full re-fetch.
+     */
+    clearRates(): void;
+    /**
+     * Synchronous rate lookup: `1` for same-currency pairs, a cached LIVE
+     * rate if one was fetched within {@link RATE_FRESHNESS_MS}, otherwise
+     * `null`, callers fall through to the async fetch path and the
+     * expression shows Pending until real data arrives.
+     *
+     * There is deliberately no hardcoded fallback table: a stale made-up
+     * rate presented as a real conversion is worse than a Pending state.
+     */
+    getRateSync(from: string, to: string): number | null;
+    /** Convert `value` from `from` to `to` using a freshly-fetched live rate (see {@link getRate}). */
+    convert(value: number, from: string, to: string): Promise<number>;
+    /**
+     * Get all currently cached fresh rates, keyed "FROM:TO".
+     * @returns Snapshot of fresh live rates, or null when none are cached.
+     */
+    getAllRates(): Record<string, number> | null;
+    /**
+     * Check whether any fresh live rates are currently cached.
+     */
+    hasRates(): boolean;
+    /**
+     * Synchronous conversion using cached rates only
+     * Returns null if rate not in cache
+     */
+    convertSync(value: number, from: string, to: string): number | null;
+    /**
+     * Check whether `code` is a recognized currency code (fiat or the
+     * cryptocurrencies in {@link CRYPTO_IDS}), a fixed allowlist, not a
+     * live lookup against any API.
+     */
+    isCurrency(code: string): boolean;
+}
+/** The shared rate cache. See {@link CurrencyExchangeService} for why it is shared. */
+declare const currencyExchangeService: CurrencyExchangeService;
+/** Alias for {@link currencyExchangeService}, kept for older imports. */
+declare const sharedCurrencyExchange: CurrencyExchangeService;
+
+/**
+ * Currency async resolver, bridges CurrencyExchangeService to the
+ * IAsyncResolver interface for the Suspense architecture.
+ *
+ * Uses TanStack Query (injected via queryClient) as the single cache layer.
+ */
+
+/**
+ * Fetches exchange rates before the VM runs, so a conversion has real numbers.
+ *
+ * Until rates arrive the line evaluates to a pending value rather than a
+ * guessed one, and re-evaluates when they land.
+ */
+declare class CurrencyAsyncResolver implements IAsyncResolver {
+    readonly namespace = "currency";
+    private exchange;
+    constructor(exchange?: CurrencyExchangeService);
+    preflight(_tokens: Token[], bytecode: BytecodeProgram, packageId: string, signal: AbortSignal, queryClient: QueryClient): AsyncCheckResult | null;
+    destroy(): void;
+}
+
+/**
+ * Validate `unit` against the known unit table.
+ *
+ * @returns `unit` unchanged in all cases. This does NOT normalize casing
+ *   or aliasing (units are strictly case-sensitive, see the module note
+ *   above). A unit the table doesn't recognize is still
+ *   returned as-is (not thrown), so callers must not assume a returned
+ *   string is actually convertible, check with {@link isConvertibleUnit}
+ *   or {@link canConvert} first if that matters.
+ *
+ * Kept as an identity function purely for API compatibility. It used to guard
+ * a validity cache, which existed because validating a unit meant a
+ * throw/catch round trip through the old dependency. Validation is now a Map
+ * lookup, so the cache cost more than it saved: worse, it was capped at 1000
+ * entries against a 1456-unit table, so any sweep over the full vocabulary
+ * (which is exactly what LanguageService does to build completions) evicted
+ * on almost every call. That one change took the full-table sweep from 7.7ms
+ * to under 20us.
+ */
+declare function resolveUnit(unit: string): string;
+/**
+ * Get the measure/dimension kind for `unit` (e.g. `"length"`, `"mass"`,
+ * `"temperature"`), used to check whether two units are even in the same
+ * dimension before attempting a conversion.
+ *
+ * @returns `undefined` if `unit` isn't recognized, rather than throwing.
+ */
+declare function getMeasure(unit: string): string | undefined;
+/**
+ * Check whether `from` can be converted to `to`. Same unit, or same
+ * measure kind (length, mass, ...) and the underlying tables accept the pair.
+ * Never throws; returns `false` on any failure.
+ */
+declare function canConvert(from: string, to: string): boolean;
+/**
+ * Convert `value` from unit `from` to unit `to`.
+ *
+ * Does not validate that the conversion is possible, callers should check
+ * with {@link canConvert} first if `from`/`to` aren't already known-good.
+ *
+ * THROWS a RangeError for an unknown unit or a cross-measure pair. `VM.ts`'s
+ * `extractDurationMs()` depends on that, see {@link convertRaw}.
+ *
+ * This used to memoize a per-pair conversion factor in an LFU cache. The cache
+ * is gone: computing the factor is now two Map reads, while the cache cost a
+ * template-string key allocation on every call plus the LFU's own frequency
+ * bookkeeping, so it was slower than the work it avoided. Removing it is
+ * bit-exact, not merely close: the cache stored `convertRaw(1, f, t)`, which is
+ * exactly `fromRatio / toRatio`, and then multiplied, which is the identical
+ * expression `convertRaw(value, f, t)` evaluates. It also deleted the special
+ * case that existed only to keep offset-based temperature pairs out of a
+ * factor cache.
+ */
+declare function convertUnit(value: number, from: string, to: string): number;
+/** Check whether `unit` is a unit the conversion tables recognize. Never throws. */
+declare function isConvertibleUnit(unit: string): boolean;
+/**
+ * Convert `value` (in `unit`) to whichever unit of the same measure gives
+ * the most human-readable magnitude, e.g. 1500 metres becomes 1.5 km. Falls
+ * back to returning `value`/`unit` unchanged if `unit` isn't recognized,
+ * which is what every extended unit and workday does.
+ *
+ * Note the chosen unit is drawn from the best-unit lists, which are not
+ * restricted to spellings the lexer accepts: 0.5 l reports "mL".
+ */
+declare function getBestUnit(value: number, unit: string): {
+    value: number;
+    unit: string;
+};
+
+export { CurrencyAsyncResolver, CurrencyExchangeService, canConvert, convertUnit, currencyExchangeService, getBestUnit, getMeasure, isConvertibleUnit, resolveUnit, sharedCurrencyExchange };

package/dist/uom.d.ts

@@ -0,0 +1,224 @@
+import { QueryClient } from '@tanstack/query-core';
+import { T as Token } from './Token-0jpvUdPY.js';
+import { a as BytecodeProgram } from './BytecodeBuilder-3egMyuDi.js';
+import { IAsyncResolver, AsyncCheckResult } from './resolvers.js';
+import './Value-KtAQNHur.js';
+
+/**
+ * Caches exchange rates fetched from an external source.
+ *
+ * Rates are global market data rather than per-engine configuration, which is
+ * why one instance is shared. Two engines with private copies would fetch the
+ * same endpoint twice and could disagree about one pair at one moment. See
+ * `engine/EngineContext.ts`.
+ */
+declare class CurrencyExchangeService {
+    /**
+     * Live rate tables cached from successful getRate() fetches, keyed by
+     * uppercase base currency. Each table holds every rate the API returned
+     * for that base (plus the base itself at 1), so any pair whose two codes
+     * appear in one fresh table can be served synchronously, including
+     * cross pairs via triangulation (EUR→GBP through a USD-base table).
+     * Stale tables are ignored, not evicted; the next successful fetch for
+     * the same base overwrites them.
+     */
+    private baseTables;
+    /**
+     * How long a fetched rate may be served synchronously by getRateSync().
+     * Beyond this window callers fall through to the async path (expression
+     * shows Pending until the fetch lands).
+     */
+    private static readonly RATE_FRESHNESS_MS;
+    /**
+     * Ticker → CoinGecko coin id, for the cryptocurrencies `isCurrency()`
+     * recognizes. Frankfurter (the fiat rate source below) is ECB reference
+     * rates only and has no concept of BTC/ETH/etc, routing a crypto code
+     * through it as `base=BTC` fails outright, which is why crypto pairs
+     * previously never resolved (see CurrencyAsyncResolver/VM.ts's ADD
+     * handling for the two bugs that let that failure pass silently instead
+     * of surfacing as a real fetch).
+     */
+    private static readonly CRYPTO_IDS;
+    private isCryptoCode;
+    constructor();
+    /**
+     * Timeout (ms) for currency exchange rate fetches.
+     *
+     * If the frankfurter API doesn't respond within this window, the fetch
+     * is aborted, preventing indefinite "Pending" states in the playground
+     * and Obsidian plugin when the exchange rate API is unreachable.
+     */
+    private static readonly FETCH_TIMEOUT_MS;
+    /**
+     * Fetch the live exchange rate for converting 1 unit of `from` into `to`.
+     *
+     * Routes cryptocurrency codes (see {@link CRYPTO_IDS}) to CoinGecko and
+     * everything else to Frankfurter (ECB reference rates, fiat-only). On
+     * success, caches the whole returned rate table for `from` so subsequent
+     * lookups, including cross-pairs via triangulation, can be served
+     * synchronously by {@link getRateSync} within the freshness window.
+     *
+     * @throws If the currency code is unrecognized or the fetch fails/times out.
+     */
+    getRate(from: string, to: string, signal?: AbortSignal): Promise<number>;
+    /**
+     * Crypto rate fetch, routed through CoinGecko's no-auth simple-price
+     * endpoint instead of Frankfurter (fiat-only, has no BTC/ETH concept).
+     * Handles all three combinations, crypto→crypto, crypto→fiat
+     * fiat→crypto, via prices denominated in USD (or the target fiat
+     * directly, which CoinGecko's `vs_currencies` also accepts), then
+     * caches the result as a same-shaped base table so getRateSync /
+     * convertSync keep working unchanged for crypto pairs too.
+     */
+    private getCryptoRate;
+    private fetchCoinGeckoPrices;
+    /**
+     * Seed a base rate table without a network fetch.
+     *
+     * Intended for tests and for future user-provided offline rates
+     * production live data always comes from {@link getRate}. Seeded rates
+     * obey the same freshness window as fetched ones.
+     *
+     * @param base - Base currency code (e.g. "USD").
+     * @param rates - Map of currency code → rate relative to the base.
+     */
+    primeRates(base: string, rates: Record<string, number>): void;
+    /**
+     * Drop every cached/primed rate table.
+     *
+     * Mainly for test isolation: {@link sharedCurrencyExchange} is a
+     * module-level singleton, so a rate primed or fetched by one test can
+     * silently leak into a later test in the same file. Also usable in
+     * production if a caller ever wants to force a full re-fetch.
+     */
+    clearRates(): void;
+    /**
+     * Synchronous rate lookup: `1` for same-currency pairs, a cached LIVE
+     * rate if one was fetched within {@link RATE_FRESHNESS_MS}, otherwise
+     * `null`, callers fall through to the async fetch path and the
+     * expression shows Pending until real data arrives.
+     *
+     * There is deliberately no hardcoded fallback table: a stale made-up
+     * rate presented as a real conversion is worse than a Pending state.
+     */
+    getRateSync(from: string, to: string): number | null;
+    /** Convert `value` from `from` to `to` using a freshly-fetched live rate (see {@link getRate}). */
+    convert(value: number, from: string, to: string): Promise<number>;
+    /**
+     * Get all currently cached fresh rates, keyed "FROM:TO".
+     * @returns Snapshot of fresh live rates, or null when none are cached.
+     */
+    getAllRates(): Record<string, number> | null;
+    /**
+     * Check whether any fresh live rates are currently cached.
+     */
+    hasRates(): boolean;
+    /**
+     * Synchronous conversion using cached rates only
+     * Returns null if rate not in cache
+     */
+    convertSync(value: number, from: string, to: string): number | null;
+    /**
+     * Check whether `code` is a recognized currency code (fiat or the
+     * cryptocurrencies in {@link CRYPTO_IDS}), a fixed allowlist, not a
+     * live lookup against any API.
+     */
+    isCurrency(code: string): boolean;
+}
+/** The shared rate cache. See {@link CurrencyExchangeService} for why it is shared. */
+declare const currencyExchangeService: CurrencyExchangeService;
+/** Alias for {@link currencyExchangeService}, kept for older imports. */
+declare const sharedCurrencyExchange: CurrencyExchangeService;
+
+/**
+ * Currency async resolver, bridges CurrencyExchangeService to the
+ * IAsyncResolver interface for the Suspense architecture.
+ *
+ * Uses TanStack Query (injected via queryClient) as the single cache layer.
+ */
+
+/**
+ * Fetches exchange rates before the VM runs, so a conversion has real numbers.
+ *
+ * Until rates arrive the line evaluates to a pending value rather than a
+ * guessed one, and re-evaluates when they land.
+ */
+declare class CurrencyAsyncResolver implements IAsyncResolver {
+    readonly namespace = "currency";
+    private exchange;
+    constructor(exchange?: CurrencyExchangeService);
+    preflight(_tokens: Token[], bytecode: BytecodeProgram, packageId: string, signal: AbortSignal, queryClient: QueryClient): AsyncCheckResult | null;
+    destroy(): void;
+}
+
+/**
+ * Validate `unit` against the known unit table.
+ *
+ * @returns `unit` unchanged in all cases. This does NOT normalize casing
+ *   or aliasing (units are strictly case-sensitive, see the module note
+ *   above). A unit the table doesn't recognize is still
+ *   returned as-is (not thrown), so callers must not assume a returned
+ *   string is actually convertible, check with {@link isConvertibleUnit}
+ *   or {@link canConvert} first if that matters.
+ *
+ * Kept as an identity function purely for API compatibility. It used to guard
+ * a validity cache, which existed because validating a unit meant a
+ * throw/catch round trip through the old dependency. Validation is now a Map
+ * lookup, so the cache cost more than it saved: worse, it was capped at 1000
+ * entries against a 1456-unit table, so any sweep over the full vocabulary
+ * (which is exactly what LanguageService does to build completions) evicted
+ * on almost every call. That one change took the full-table sweep from 7.7ms
+ * to under 20us.
+ */
+declare function resolveUnit(unit: string): string;
+/**
+ * Get the measure/dimension kind for `unit` (e.g. `"length"`, `"mass"`,
+ * `"temperature"`), used to check whether two units are even in the same
+ * dimension before attempting a conversion.
+ *
+ * @returns `undefined` if `unit` isn't recognized, rather than throwing.
+ */
+declare function getMeasure(unit: string): string | undefined;
+/**
+ * Check whether `from` can be converted to `to`. Same unit, or same
+ * measure kind (length, mass, ...) and the underlying tables accept the pair.
+ * Never throws; returns `false` on any failure.
+ */
+declare function canConvert(from: string, to: string): boolean;
+/**
+ * Convert `value` from unit `from` to unit `to`.
+ *
+ * Does not validate that the conversion is possible, callers should check
+ * with {@link canConvert} first if `from`/`to` aren't already known-good.
+ *
+ * THROWS a RangeError for an unknown unit or a cross-measure pair. `VM.ts`'s
+ * `extractDurationMs()` depends on that, see {@link convertRaw}.
+ *
+ * This used to memoize a per-pair conversion factor in an LFU cache. The cache
+ * is gone: computing the factor is now two Map reads, while the cache cost a
+ * template-string key allocation on every call plus the LFU's own frequency
+ * bookkeeping, so it was slower than the work it avoided. Removing it is
+ * bit-exact, not merely close: the cache stored `convertRaw(1, f, t)`, which is
+ * exactly `fromRatio / toRatio`, and then multiplied, which is the identical
+ * expression `convertRaw(value, f, t)` evaluates. It also deleted the special
+ * case that existed only to keep offset-based temperature pairs out of a
+ * factor cache.
+ */
+declare function convertUnit(value: number, from: string, to: string): number;
+/** Check whether `unit` is a unit the conversion tables recognize. Never throws. */
+declare function isConvertibleUnit(unit: string): boolean;
+/**
+ * Convert `value` (in `unit`) to whichever unit of the same measure gives
+ * the most human-readable magnitude, e.g. 1500 metres becomes 1.5 km. Falls
+ * back to returning `value`/`unit` unchanged if `unit` isn't recognized,
+ * which is what every extended unit and workday does.
+ *
+ * Note the chosen unit is drawn from the best-unit lists, which are not
+ * restricted to spellings the lexer accepts: 0.5 l reports "mL".
+ */
+declare function getBestUnit(value: number, unit: string): {
+    value: number;
+    unit: string;
+};
+
+export { CurrencyAsyncResolver, CurrencyExchangeService, canConvert, convertUnit, currencyExchangeService, getBestUnit, getMeasure, isConvertibleUnit, resolveUnit, sharedCurrencyExchange };

package/dist/uom.js

@@ -0,0 +1,11 @@
+export { CurrencyAsyncResolver } from './chunk-EPOXXJBK.js';
+export { CurrencyExchangeService, currencyExchangeService, sharedCurrencyExchange } from './chunk-DM3LMRBC.js';
+import './chunk-75JP4BZX.js';
+import './chunk-Z4X2RWOF.js';
+import './chunk-BVAR5J2F.js';
+export { canConvert, convertUnit, getBestUnit, getMeasure, isConvertibleUnit, resolveUnit } from './chunk-NH2O2AUR.js';
+import './chunk-4MG4XKO2.js';
+import './chunk-6RDSQURE.js';
+import './chunk-YLJ4XMA6.js';
+//# sourceMappingURL=uom.js.map
+//# sourceMappingURL=uom.js.map

package/dist/uom.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"uom.js"}

package/dist/utilities.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+var chunk5X2PTP6F_cjs = require('./chunk-5X2PTP6F.cjs');
+var chunkCCJPSHGI_cjs = require('./chunk-CCJPSHGI.cjs');
+var chunkN5YFR4UP_cjs = require('./chunk-N5YFR4UP.cjs');
+var chunkVEKIWQ3F_cjs = require('./chunk-VEKIWQ3F.cjs');
+require('./chunk-B7LXJ6LC.cjs');
+
+
+
+Object.defineProperty(exports, "abortLogger", {
+  enumerable: true,
+  get: function () { return chunk5X2PTP6F_cjs.abortLogger; }
+});
+Object.defineProperty(exports, "djb2Hash", {
+  enumerable: true,
+  get: function () { return chunk5X2PTP6F_cjs.djb2Hash; }
+});
+Object.defineProperty(exports, "autoFormatIntegerOrFloat", {
+  enumerable: true,
+  get: function () { return chunkCCJPSHGI_cjs.autoFormatIntegerOrFloat; }
+});
+Object.defineProperty(exports, "stripQuotes", {
+  enumerable: true,
+  get: function () { return chunkN5YFR4UP_cjs.stripQuotes; }
+});
+Object.defineProperty(exports, "createTimeoutSignal", {
+  enumerable: true,
+  get: function () { return chunkVEKIWQ3F_cjs.createTimeoutSignal; }
+});
+//# sourceMappingURL=utilities.cjs.map
+//# sourceMappingURL=utilities.cjs.map

package/dist/utilities.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"utilities.cjs"}

package/dist/utilities.d.cts

@@ -0,0 +1,113 @@
+/**
+ * Fast, non-cryptographic string hashing utilities.
+ *
+ * djb2 is chosen for its speed, simplicity, and excellent distribution
+ * for short strings (typical line lengths in markdown documents).
+ * It produces a 32-bit unsigned integer hash.
+ */
+/**
+ * djb2 string hash, fast, simple, good distribution.
+ * Used for O(1) line text change detection in DocumentModel.
+ */
+declare function djb2Hash(str: string): number;
+
+/**
+ * Format `number` for display, branching on whether it's a whole number:
+ * integers are always rendered with zero decimal places (never padded to
+ * `decimalPlaces`), while non-integers are rendered with up to
+ * `decimalPlaces` fractional digits. `includeThousandSeparators` controls
+ * whether groups are separated (e.g. `"1,234"`) per `numberLocale`.
+ *
+ * @param number - The value to format.
+ * @param decimalPlaces - Max fractional digits for non-integer values (default 2).
+ * @param includeThousandSeparators - Whether to group digits (default false).
+ * @param numberLocale - `Intl`/`toLocaleString` locale to format with (default "en-US").
+ */
+declare function autoFormatIntegerOrFloat(number: number, decimalPlaces?: number, includeThousandSeparators?: boolean, numberLocale?: string): string;
+
+/**
+ * Strips a single layer of matching double quotes from a string, if present.
+ * Returns the input unchanged if it isn't fully wrapped in quotes.
+ *
+ * Used for STRING token values, which the lexer emits with their surrounding
+ * `"..."` quotes still attached.
+ */
+declare function stripQuotes(value: string): string;
+
+/**
+ * Multiplex an optional caller AbortSignal with a hard timeout into a single
+ * AbortSignal suitable for fetch().
+ *
+ * Implemented manually rather than with AbortSignal.any()/AbortSignal.timeout()
+ * (Chrome 116+) to stay compatible with the TypeScript lib targets used by
+ * this project.
+ *
+ * Handles the already-aborted caller: addEventListener("abort", …) on a signal
+ * that has already fired never invokes the listener, so without the upfront
+ * `aborted` check the fetch would proceed even though the caller cancelled.
+ */
+declare function createTimeoutSignal(callerSignal: AbortSignal | undefined, timeoutMs: number, label: string): {
+    signal: AbortSignal;
+    cleanup: () => void;
+};
+
+/**
+ * Records abort-signal lifecycle for debugging cancellation.
+ *
+ * Keystroke cancellation is hard to reason about after the fact, because the
+ * evidence is gone by the time anything looks wrong. This keeps it.
+ */
+declare const abortLogger: {
+    /** Whether debug logging is currently active. */
+    readonly enabled: boolean;
+    /**
+     * Log creation of the keystroke-level AbortController.
+     * Called in the plugin constructor and on each new keystroke.
+     */
+    keystrokeCreated(): void;
+    /**
+     * Log abortion of the keystroke-level AbortController.
+     * @param reason Why the keystroke was aborted (e.g. "New keystroke",
+     *   "Document switch", "Plugin destroyed").
+     */
+    keystrokeAborted(reason: string): void;
+    /**
+     * Log creation of a local AbortController that is linked to the
+     * keystroke signal.
+     * @param source Which code path created the controller
+     *   (e.g. "executeAndStore", "executeRaw", "preflight", "vm").
+     */
+    localControllerCreated(source: string): void;
+    /**
+     * Log that a local AbortController was linked to the keystroke signal.
+     * When the keystroke signal is aborted, this local controller will
+     * be aborted automatically.
+     * @param source The code path that created the controller.
+     */
+    signalLinked(source: string): void;
+    /**
+     * Log that a local AbortController's listener was removed from the
+     * keystroke signal (cleanup).
+     * @param source The code path.
+     */
+    signalUnlinked(source: string): void;
+    /**
+     * Log that the keystroke signal was propagated INTO the engine.
+     * @param isAborted Whether the signal was already aborted when set.
+     */
+    keystrokeSignalSet(isAborted: boolean): void;
+    /**
+     * Log that the keystroke signal was CLEARED from the engine
+     * (typically in the evaluator's finally block).
+     */
+    keystrokeSignalCleared(): void;
+    /**
+     * Log that a stale async result was discarded because its signal
+     * was aborted.
+     * @param queryKey The cache key for the discarded result.
+     * @param context Additional context (e.g. "after await", "after error").
+     */
+    staleDataDiscarded(queryKey: string, context: string): void;
+};
+
+export { abortLogger, autoFormatIntegerOrFloat, createTimeoutSignal, djb2Hash, stripQuotes };