@noy-db/hub 0.3.0-pre.8 → 0.3.0

package/dist/via/money/branded.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Branded money output type.
+ *
+ * The decoded read shape of a money field is an exact decimal STRING
+ * (`'10000.00'`) — but a hand-written schema types it `string | number`,
+ * which is honest about the input side and unhelpful on the output
+ * side: every read site hand-coerces, and a missed coercion passes
+ * typecheck silently (then surfaces as a runtime template warning, or
+ * worse, as `'10000.00' * 100` arithmetic).
+ *
+ * {@link MoneyString} is the output-side brand: a `string` that has
+ * been through noy-db's decode (or {@link asMoney}'s guard). Branding
+ * is type-level only — zero runtime cost on the read path.
+ *
+ * ## Wiring the brand through a validator (the input/output asymmetry)
+ *
+ * Keep the permissive `string | number` on the INPUT side so write
+ * sites are untouched, and brand the OUTPUT side. With Zod:
+ *
+ * ```ts
+ * import type { MoneyString } from '@noy-db/hub'
+ *
+ * const moneyValue = z.union([z.number(), z.string()]) as unknown as
+ *   z.ZodType<MoneyString, z.ZodTypeDef, string | number>
+ *
+ * const Invoice = z.object({ id: z.string(), total: moneyValue })
+ * type InvoiceOut = z.output<typeof Invoice> // total: MoneyString
+ * type InvoiceIn  = z.input<typeof Invoice>  // total: string | number
+ * ```
+ *
+ * The cast is sound for fields declared in `moneyFields`: reads pass
+ * through `decodeMoneyFields`, which always produces the canonical
+ * decimal string.
+ */
+declare const MONEY_BRAND: unique symbol;
+/**
+ * An exact decimal string produced by noy-db's money decode
+ * (`'10000.00'`). The brand exists only at the type level — at runtime
+ * a `MoneyString` is a plain string.
+ */
+export type MoneyString = string & {
+    readonly [MONEY_BRAND]: true;
+};
+/**
+ * Runtime-guarded cast to {@link MoneyString}. Accepts a decimal string
+ * or a number, returns the canonical decimal string branded — throws
+ * `MoneyUnsupportedError` on anything non-finite / non-decimal. Use at
+ * trust boundaries (deserialized JSON, route params); values read
+ * through `get()`/`list()` are already canonical.
+ */
+export declare function asMoney(value: string | number): MoneyString;
+/** Type guard: is `value` a decimal string acceptable as money? */
+export declare function isMoneyString(value: unknown): value is MoneyString;
+/**
+ * The ONE sanctioned escape hatch to a JS `number` — explicit because
+ * the conversion is lossy past 2^53. For display math and chart axes;
+ * never feed the result back into stored amounts (use `mulRate` /
+ * `allocate` for exact arithmetic).
+ */
+export declare function moneyNumber(value: MoneyString | string | number): number;
+export {};

package/dist/via/money/descriptor.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The `money()` field descriptor — a branded schema-layer descriptor, a
+ * sibling of `i18nText()` / `dictKey()`. It owns currency, scale, and
+ * rounding policy for a field; the pure arithmetic lives in
+ * {@link ./fixed-point} and default scale resolution in
+ * {@link ./iso4217}.
+ *
+ * Two modes:
+ *   - **fixed**  `money({ currency: 'EUR' })` — one currency for the
+ *     field; the value stores a bare scaled-integer string.
+ *   - **multi**  `money({ currencies: 'any' | [...] })` — currency travels
+ *     per record; the value stores `{ amount, currency }`.
+ *
+ * `currency` and `currencies` are mutually exclusive.
+ */
+import type { RoundingMode } from './fixed-point.js';
+import { NoydbError } from '../../kernel/errors.js';
+export interface MoneyOptionsFixed {
+    currency: string;
+    /** Override the ISO-4217 default scale (required for unlisted codes). */
+    scale?: number;
+    rounding?: RoundingMode;
+}
+export interface MoneyOptionsMulti {
+    currencies: 'any' | readonly string[];
+    /** Per-currency scale overrides (required for unlisted codes). */
+    scaleOverrides?: Record<string, number>;
+    rounding?: RoundingMode;
+}
+export type MoneyOptions = MoneyOptionsFixed | MoneyOptionsMulti;
+export interface MoneyDescriptor {
+    readonly _noydbMoney: true;
+    /** Via port brand marker — lets a `MoneyDescriptor` satisfy the kernel's opaque `ViaDescriptor`. */
+    readonly _viaBrand: 'money';
+    readonly mode: 'fixed' | 'multi';
+    readonly options: MoneyOptions;
+    readonly rounding: RoundingMode | undefined;
+    /** The currency for fixed mode; `undefined` in multi mode. */
+    readonly fixedCurrency: string | undefined;
+    /** Resolve the scale for a currency, throwing if not allowed / unknown. */
+    scaleFor(currency: string): number;
+    /** Whether this descriptor permits the given currency. */
+    allows(currency: string): boolean;
+    /**
+     * The single currency this descriptor implies, if any — fixed mode, or
+     * multi mode with exactly one allow-listed currency. Lets a multi field
+     * accept a bare amount unambiguously. `undefined` otherwise.
+     */
+    soleCurrency(): string | undefined;
+}
+/** Raised when a written value carries more precision than `scale` allows. */
+export declare class MoneyPrecisionError extends NoydbError {
+    readonly field: string;
+    readonly value: unknown;
+    readonly scale: number;
+    constructor(field: string, value: unknown, scale: number);
+}
+/** Raised when a currency is disallowed or has no resolvable scale. */
+export declare class MoneyCurrencyError extends NoydbError {
+    readonly currency: string;
+    readonly reason: 'not-allowed' | 'unknown-scale';
+    readonly field?: string | undefined;
+    constructor(currency: string, reason: 'not-allowed' | 'unknown-scale', field?: string | undefined);
+}
+/** Raised when an aggregate operation is not supported on a money field. */
+export declare class MoneyUnsupportedError extends NoydbError {
+    readonly field: string;
+    constructor(field: string, message?: string);
+}
+/** Create a {@link MoneyDescriptor}. */
+export declare function money(options: MoneyOptions): MoneyDescriptor;
+/** Runtime predicate for detecting a {@link MoneyDescriptor}. */
+export declare function isMoneyDescriptor(x: unknown): x is MoneyDescriptor;

package/dist/via/money/fixed-point.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure fixed-point decimal core for the money descriptor.
+ *
+ * All conversion goes decimal-string ⇄ scaled `BigInt`. There is no
+ * floating-point arithmetic anywhere: a value like `123.45` becomes
+ * `12345n` purely by string manipulation, never by `value * 100` (which
+ * would reintroduce the very drift money() exists to eliminate). BigInt
+ * has no magnitude ceiling, so values past `Number.MAX_SAFE_INTEGER`
+ * stay exact end-to-end.
+ *
+ * This module knows nothing about currencies, descriptors, or storage —
+ * it is the isolated, exhaustively-tested arithmetic kernel.
+ */
+export type RoundingMode = 'half-up' | 'half-even' | 'half-down' | 'up' | 'down' | 'ceil' | 'floor';
+export type ParseResult = {
+    ok: true;
+    value: bigint;
+} | {
+    ok: false;
+    reason: 'precision' | 'nonfinite';
+};
+/**
+ * Parse a decimal (`number | string`) into a scaled `BigInt` at the
+ * given scale. When the input carries more fractional precision than
+ * `scale`:
+ *   - `rounding` omitted ⇒ `{ ok: false, reason: 'precision' }`
+ *   - `rounding` set ⇒ the tail is rounded per the mode.
+ * Non-finite / unparseable input ⇒ `{ ok: false, reason: 'nonfinite' }`.
+ */
+export declare function parseToScaledInt(input: number | string, scale: number, rounding?: RoundingMode): ParseResult;
+/**
+ * Number of fractional digits in the canonical decimal rendering of
+ * `input` (`'123.45'` → 2, `100` → 0, `'1e-7'` → 7), or `null` when the
+ * input is non-finite / not a decimal. Used to infer the working scale
+ * of arithmetic helpers from their canonical-string inputs.
+ */
+export declare function decimalScaleOf(input: number | string): number | null;
+/**
+ * Re-scale a scaled `BigInt` from `fromScale` to `toScale`. Scaling up
+ * is exact (append zeros); scaling down rounds the discarded tail per
+ * `rounding`. The rounding decision reuses the same kernel as
+ * {@link parseToScaledInt}, so `rescaleScaledInt(parse('1.005', 3), 3, 2)`
+ * and `parse('1.005', 2, mode)` agree for every mode.
+ */
+export declare function rescaleScaledInt(value: bigint, fromScale: number, toScale: number, rounding?: RoundingMode): bigint;
+/**
+ * Render a scaled `BigInt` back to its canonical decimal string at the
+ * given scale. `(12345n, 2)` → `'123.45'`; `(5n, 0)` → `'5'`;
+ * `(-1n, 2)` → `'-0.01'`. Exact for any magnitude.
+ */
+export declare function formatScaledInt(value: bigint, scale: number): string;

package/dist/via/money/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@noy-db/hub` money service — the `money()` field descriptor for
+ * currency-safe, exact decimal storage, formatting, and aggregation.
+ *
+ * @see ./descriptor for the public `money()` factory.
+ */
+export { money, isMoneyDescriptor, MoneyPrecisionError, MoneyCurrencyError, MoneyUnsupportedError } from './descriptor.js';
+export type { MoneyDescriptor, MoneyOptions, MoneyOptionsFixed, MoneyOptionsMulti, } from './descriptor.js';
+export type { RoundingMode } from './fixed-point.js';
+export { scaleForCurrency } from './iso4217.js';
+export type { FxRates } from './money-reducer.js';
+export { mulRate, allocate } from './arith.js';
+export type { MulRateOptions, AllocateOptions } from './arith.js';
+export { asMoney, isMoneyString, moneyNumber } from './branded.js';
+export type { MoneyString } from './branded.js';

package/dist/via/money/iso4217.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Return the ISO-4217 minor-unit scale for a currency code, or `null`
+ * when the code is not in the known set (caller must supply an explicit
+ * scale).
+ */
+export declare function scaleForCurrency(code: string): number | null;

package/dist/via/money/money-reducer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Money-aware aggregation: exact `sum` / `min` / `max` over money
+ * fields.
+ *
+ * The generic reducers (`aggregate/reducers.ts`) read a field via
+ * `readNumber`, which coerces a string (the stored scaled-integer form
+ * of money, e.g. `'12345'`) to `0` — so an un-wrapped money `sum` would
+ * silently return zero. {@link wrapMoneyReducers} rewrites any `sum` /
+ * `min` / `max` over a declared money field into a reducer that
+ * accumulates per-currency `BigInt` totals of the stored integers, so
+ * the result is exact for any magnitude (past `Number.MAX_SAFE_INTEGER`
+ * included).
+ *
+ * Results are currency-aware and never silently mix currencies:
+ *   - **fixed** mode → a single exact decimal string.
+ *   - **multi** mode → an exact `Record<currency, string>` map.
+ *   - **`sum` with `convertTo` + `fx`** → a single exact string, with
+ *     each currency converted via BigInt arithmetic (no float).
+ *
+ * `remove()` is implemented for every money reducer so they participate
+ * in incremental live-aggregation and materialized-view maintenance
+ * exactly like the generic reducers they replace.
+ */
+import type { MoneyDescriptor } from './descriptor.js';
+import type { AggregateSpec } from '../../with-lookup/aggregate/aggregation.js';
+export type FxRates = Record<string, number | string>;
+/**
+ * Rewrite any `sum` / `min` / `max` reducer over a declared money field
+ * into its exact BigInt money-aware equivalent. Other reducers (and
+ * reducers over non-money fields) pass through unchanged. Returns a new
+ * spec; the input is not mutated.
+ */
+export declare function wrapMoneyReducers(spec: AggregateSpec, moneyFields: Record<string, MoneyDescriptor>): AggregateSpec;

package/dist/via/money/normalize.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Write-side and read-side normalization for money fields.
+ *
+ * - **Write** ({@link quantizeMoneyFields}): user input (`number | string`,
+ *   or `{ amount, currency }` in multi mode) → the canonical *stored*
+ *   form — a scaled-integer **digit string** (`'12345'`), or
+ *   `{ amount: '12345', currency: 'EUR' }` in multi mode. A JSON number
+ *   would truncate past 2^53, so the integer is always stored as a string.
+ * - **Read** ({@link decodeMoneyFields}): stored form → an exact decimal
+ *   string (`'123.45'`) plus, when formatting is requested, the virtual
+ *   `<field>Formatted` (locale currency string) and `<field>Number`
+ *   (convenience JS number, explicitly lossy past 2^53).
+ *
+ * Both return a shallow clone; neither mutates the input record.
+ */
+import { type MoneyDescriptor } from './descriptor.js';
+/**
+ * Canonicalize a STORED-form record's money fields for an internal
+ * callback boundary. Gate handlers (guard `check` /
+ * `frozenFields` / `onDelete`, period guard, amendment invariants) and
+ * derivation `derive(source, ctx)` callbacks are user-facing: they must
+ * see the same decoded canonical decimal that `get()` returns — the
+ * scaled-int storage form never escapes. Decoded with `'raw'` (no
+ * `<field>Formatted`/`<field>Number` virtuals): these boundaries carry
+ * no locale, and fabricating one would re-create a two-read-paths
+ * skew inside comparisons.
+ */
+export declare function canonicalizeStoredMoney(record: unknown, moneyFields: Record<string, MoneyDescriptor> | undefined): unknown;
+/**
+ * Canonicalize an INCOMING record's money fields at the top of the
+ * write pipeline. Raw user input (pre-quantize) may hold a
+ * number (`10000`), a major-unit string (`'10000.00'`), or a spread of
+ * an already-decoded read. Quantize→decode folds all three to the
+ * canonical decimal string, so gate handlers, computed-field
+ * callbacks, and schema validation all see the `get()` shape — and
+ * freeze-style guards comparing `incoming[f]` vs `existing[f]` see
+ * equal values for an unchanged field. Best-effort: input that fails
+ * to quantize passes through unchanged — the write path quantizes
+ * again after validation and surfaces the real
+ * `MoneyPrecisionError`/`TypeError`.
+ */
+export declare function canonicalizeIncomingMoney(record: unknown, moneyFields: Record<string, MoneyDescriptor> | undefined): unknown;
+/**
+ * Convert money fields in `record` from user input to their canonical
+ * stored form. Returns a shallow clone (deep along declared nested
+ * paths). A nested path whose declared shape disagrees with the
+ * data throws: writing through would store an un-quantized amount.
+ */
+export declare function quantizeMoneyFields<T extends Record<string, unknown>>(record: T, moneyFields: Record<string, MoneyDescriptor>): T;
+/**
+ * The stored scaled-integer value of a money field as a `BigInt`, for
+ * exact numeric comparison (e.g. `orderBy` / sorting), or `null` when the
+ * stored value is missing/malformed. Mirrors the stored form `decodeValue`
+ * reads: a bare scaled-int (fixed mode) or `{ amount, currency }`
+ * (multi-currency). Comparison is in scaled space and is exact within a
+ * single currency/scale (the `where` / `sum` BigInt model); across
+ * currencies of different scales the raw scaled comparison is best-effort.
+ */
+export declare function moneyScaledValue(stored: unknown, desc: MoneyDescriptor): bigint | null;
+/**
+ * The `ViaBinding.canonicalizeIndexKey` implementation for money (#672) —
+ * bucket an eager index's money field entries by the BigInt-normalized
+ * scaled-int string, not the raw stored bytes, so a pre-declaration /
+ * non-canonical value (e.g. `'0100'`) lands under the SAME key a canonical
+ * write produces (`'100'`). Only FIXED-mode declared money fields
+ * participate — multi-mode stores `{ amount, currency }`, which has no
+ * single bucketable scalar (mirrors `moneyIndexProbe`'s fixed-only gate,
+ * `via/money/where.ts`). `undefined` when `field` isn't a declared
+ * fixed-mode money field, or the stored value doesn't parse — in both
+ * cases the caller falls back to the raw stringified bucket, which is
+ * exactly what the scan (`evaluateMoneyClause`) also treats as a
+ * non-match, preserving fast-path/scan parity.
+ */
+export declare function canonicalizeMoneyIndexKey(field: string, rawValue: unknown, moneyFields: Record<string, MoneyDescriptor>): string | undefined;
+/**
+ * money's `presentLate` hook (#669) — for each field in `virtualMoney` (money ∩
+ * virtual-mode computed on the SAME field), quantize the computed fn's fresh
+ * MAJOR-UNITS output to the descriptor's scale (with its declared rounding)
+ * and present it EXACTLY like a stored money field: the exact decimal string
+ * (via {@link formatScaledInt}), plus `<field>Formatted`/`<field>Number` when
+ * `locale !== 'raw'`. NEVER the scaled-int decode {@link decodeMoneyFields}
+ * runs for a genuinely-stored value — that would misread a virtual field's
+ * raw major-unit `21` as 21 SCALED units (`'0.21'`, the #665 corruption this
+ * must not reintroduce). Runs AFTER computed's `present()` (the pipeline's
+ * `presentLate` fold point, `kernel/via/pipeline.ts`), so `record[field]`
+ * already holds the fn's fresh output by the time this runs.
+ *
+ * Absent/null value → left untouched (nothing to dress). Unparseable value
+ * (fails `parseToScaledInt` — e.g. excess precision with no declared
+ * rounding) → left RAW, no throw: read-time dressing must never brick a
+ * read. Fixed-mode fields only — a virtual field's computed output has no
+ * natural `{ amount, currency }` shape to parse for multi-currency mode.
+ */
+export declare function presentVirtualMoneyFields<T extends Record<string, unknown>>(record: T, moneyFields: Record<string, MoneyDescriptor>, virtualMoney: ReadonlySet<string>, locale: string | undefined): T;
+/**
+ * Convert money fields in `record` from stored form to the read shape:
+ * an exact decimal string, plus `<field>Formatted` / `<field>Number`
+ * virtuals when `locale !== 'raw'`. Returns a shallow clone (deep along
+ * declared nested paths; virtuals land as siblings inside the
+ * nested container, e.g. each `lineItems[]` element gains
+ * `amountFormatted`, except for values held directly in arrays where a
+ * scalar has no sibling slot). The decode walk is LENIENT: stored data
+ * predating a declaration change must stay readable.
+ */
+export declare function decodeMoneyFields<T extends Record<string, unknown>>(record: T, moneyFields: Record<string, MoneyDescriptor>, locale: string | undefined): T;

package/dist/via/money/paths.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Nested-path support for `moneyFields` declarations.
+ *
+ * A descriptor map key is a PATH, not just a top-level field name:
+ *
+ * - `'total'`                      — top-level scalar (the original form)
+ * - `'billing.monthlyServiceFee'`  — nested object member
+ * - `'lineItems[].amount'`         — member of every element of an array
+ * - `'summary.*'`                  — every value of a record/map object
+ * - `'income[].taxWithheld'`, `'byMonth.*.amount'` — segments compose
+ *
+ * Paths are parsed ONCE, at collection registration, and a syntactically
+ * invalid declaration throws there — loudly, at setup time. (The
+ * historical failure mode this kills: a declared-but-unreachable path
+ * that was silently ignored, leaving the field un-quantized — a latent
+ * 100× bug.) A path that doesn't match a given record at write time is
+ * NOT an error — optional fields and empty arrays are legitimate — but
+ * a path segment that hits a value of the WRONG SHAPE (`[]` on a
+ * non-array, `.*` on a non-object) throws, because that means the
+ * declaration and the data model disagree.
+ */
+export type MoneyPathSegment = {
+    readonly kind: 'key';
+    readonly key: string;
+    readonly array: boolean;
+} | {
+    readonly kind: 'wildcard';
+    readonly array: boolean;
+};
+/**
+ * Parse a moneyFields path into segments. Throws `ValidationError` on
+ * bad syntax. Results are memoized — the same declared paths are walked
+ * on every write/read.
+ */
+export declare function parseMoneyPath(path: string): readonly MoneyPathSegment[];
+/** True when the path is a plain top-level field name (the fast path). */
+export declare function isSimpleMoneyPath(path: string): boolean;
+/**
+ * Validate every declared path's syntax. Call at collection
+ * registration so typos throw at setup, not silently no-op per write.
+ */
+export declare function validateMoneyFieldPaths(moneyFields: Record<string, unknown>): void;
+/**
+ * The leaf visitor: receives the (already-cloned) container holding the
+ * money value and the key/index of that value. Mutating the container
+ * is safe — every container on a matched path is a fresh clone.
+ */
+export type MoneyLeafVisitor = (container: Record<string, unknown> | unknown[], key: string | number) => void;
+/**
+ * Walk `node` along `segments`, copy-on-write-cloning every container on
+ * a matched path, and call `visit` at each leaf position. Returns the
+ * (possibly new) node; unmatched paths return the input untouched.
+ *
+ * Shape mismatches (`[]` on a non-array, `*` on a non-object) THROW on
+ * the write path — the declaration and the data model disagree, and
+ * writing through would store an un-quantized amount. On the READ path
+ * pass `lenient: true` instead: stored data predating a declaration
+ * change must stay readable, so a mismatched node is returned untouched
+ * (mirrors the defensive `continue` the flat decoder always had).
+ */
+export declare function transformAtMoneyPath(node: unknown, path: string, segments: readonly MoneyPathSegment[], index: number, visit: MoneyLeafVisitor, lenient: boolean): unknown;

package/dist/via/money/where.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Money-aware `where()` comparison.
+ *
+ * Query clauses evaluate against RAW stored records — money decode
+ * happens on output only — so a money field's stored form is a
+ * scaled-integer digit string (`'1000000'`) while the caller naturally
+ * writes the operand in major units (`10000`, `'10000.00'`). Without a
+ * rewrite the comparison is silently wrong by the scale factor, and a
+ * string-vs-number comparison is excluded by `isComparable` anyway.
+ *
+ * Two halves:
+ *
+ * - {@link moneyFieldClause} runs at QUERY BUILD time: it quantizes the
+ *   caller's major-unit operand into stored scaled-int space via the
+ *   same `parseToScaledInt` path as writes, so a malformed operand
+ *   throws at `.where()` — not silently filters everything out.
+ * - {@link evaluateMoneyClause} runs per record and compares
+ *   `BigInt`-exact in scaled space (exact past 2^53, like the rest of
+ *   the money service).
+ *
+ * Currency semantics (multi mode): an operand carries one currency —
+ * explicit via `{ amount, currency }`, or the descriptor's sole allowed
+ * currency for a bare amount. A record in a DIFFERENT currency has no
+ * defined order against the operand: it matches `!=` and nothing else.
+ */
+import { type MoneyDescriptor } from './descriptor.js';
+import type { Operator } from '../../kernel/query/predicate.js';
+/** One quantized operand value: scaled digit string + its currency. */
+interface MoneyOperandEntry {
+    readonly scaled: string;
+    readonly currency: string;
+}
+/**
+ * The opaque `via` clause payload for a `where()` over a declared money
+ * field (see `ViaBinding.buildClause` in kernel/via/index.ts). `entries` holds
+ * one element for comparison ops, two for `between` (lo, hi — same
+ * currency), N for `in`.
+ */
+export interface MoneyWhereOperand {
+    readonly mode: 'fixed' | 'multi';
+    readonly entries: ReadonlyArray<MoneyOperandEntry>;
+}
+/**
+ * Build the `via` clause payload ({@link MoneyWhereOperand}) for a
+ * `where()` over a declared money field — the `ViaBinding.buildClause`
+ * implementation for money. The operand is quantized into stored
+ * scaled-int space NOW — build time — so typos throw at the call site.
+ */
+export declare function moneyFieldClause(field: string, op: Operator, value: unknown, desc: MoneyDescriptor): MoneyWhereOperand;
+/**
+ * The `via` index-probe operand for a `where()` over a declared money
+ * field (see `ViaBinding.indexProbe` in kernel/via/index.ts) — the STORED-form
+ * value `CollectionIndexes.lookupEqual`/`lookupIn` (`with-lookup/indexing/
+ * eager-indexes.ts`) can bucket directly.
+ *
+ * Only FIXED-mode `==`/`in` are sound:
+ * - fixed-mode stores a bare scaled-int digit string (no currency
+ *   component), and `entries[i].scaled` is built by {@link parseOperand}
+ *   via the exact same `parseToScaledInt(...).value.toString()` path
+ *   `quantizeMoneyFields` (`via-money/normalize.ts#quantizeAmount`) uses
+ *   to produce the STORED value — so the two strings are byte-identical
+ *   by construction, and `stringifyKey` (which passes a string through
+ *   unchanged) buckets them the same way.
+ * - multi-mode stores `{ amount, currency }` — the index would stringify
+ *   that object to its no-match `'\0OBJECT\0'` sentinel — so multi-mode
+ *   always returns `undefined` (no sound probe).
+ * - every op besides `==`/`in` (range comparisons, `between`) has no
+ *   single stored-form value the hash index can serve, so they return
+ *   `undefined` too — the caller falls back to a scan.
+ *
+ * MIXED-ERA DATA (#672, fixed — including the #672 review's C1 finding): a
+ * record whose stored value predates the field's `money()` declaration, or
+ * otherwise bypassed `quantizeMoneyFields`, may hold a NON-canonical scaled
+ * string (e.g. `'0100'` instead of `'100'`). `CollectionIndexes` no longer
+ * buckets it under that raw string verbatim at ANY bucket-mutation site —
+ * `build`, `upsert`, and `remove` all consult the same registered
+ * canonicalizer (`ViaPipeline.canonicalizeIndexKey`; money's implementation:
+ * `canonicalizeMoneyIndexKey`, `via/money/normalize.ts`), which re-parses the
+ * stored value the same way the scan's `evaluateMoneyClause`/`readStored`
+ * does (`BigInt(actual).toString()`). So the legacy record lands in the SAME
+ * bucket a canonical write produces, an `==`/`in` probe for `'100'` finds it,
+ * and — because add and remove now agree on that bucket — a later `put()`
+ * (update) or `delete()` of that same legacy record cleans up the correct
+ * bucket instead of stranding the id under a bucket the removal could never
+ * reach. The two-string byte-identity argument above still explains WHY a
+ * canonical write's probe hits directly (no canonicalization needed for the
+ * common case); this note covers the pre-declaration tail.
+ *
+ * Boundary — CLOSED for the index layer (#677): LAZY mode's
+ * `PersistedCollectionIndex` (`with-lookup/indexing/persisted-indexes.ts`)
+ * now consults the SAME `ViaPipeline.canonicalizeIndexKey` at every
+ * bucket-mutation site (`ingest`/`upsert`/`remove`) as `CollectionIndexes`
+ * does, and its query path (`with-lookup/indexing/lazy-builder.ts`'s
+ * `resolveCandidateIds()`) canonicalizes the `==`/`in` probe value before
+ * calling `lookupEqual`/`lookupIn` — mirroring `candidateRecords()` above
+ * resolving `indexValue` before its own `lookupEqual`/`lookupIn` call. A
+ * lazy-mode mixed-era record's bucket and a canonicalized probe now agree,
+ * the same as eager mode.
+ *
+ * Residual boundary CLOSED by #684: `LazyQuery.where()` now builds
+ * `clause.via` exactly like `Query.where()`/`ScanBuilder.where()` do, and
+ * `LazyQuery`'s post-filter (`lazy-builder.ts`'s `toArray()`) runs it
+ * against the RAW record (a dedicated raw-fetch seam on `Collection`, split
+ * out of `get()`) instead of the DECODED one — `clause.via.evaluate` (this
+ * file's {@link evaluateMoneyClause}) now sees the same stored-form
+ * operand/actual-value space eager's `filterRecords` does, at any `scale`.
+ * Only survivors are decoded (`present()`) on the way out. Money RANGE
+ * clauses additionally route around `PersistedCollectionIndex.lookupRange`
+ * (raw/typed, wrong space for scaled-int money) — `resolveCandidateIds()`
+ * enumerates the field's indexed ids instead and lets this now-via-aware
+ * post-filter apply the correct BigInt-exact comparison. `lazyQuery().
+ * where()` on a money field now agrees with `scan().where()` /
+ * `query().where()` at every `scale` — for `.where()` results specifically.
+ * `orderBy` ordering is a separate, still-open lazy-vs-eager divergence,
+ * tracked in #695.
+ */
+export declare function moneyIndexProbe(op: Operator, payload: MoneyWhereOperand): unknown | undefined;
+/**
+ * Per-record evaluation of a money clause: BigInt-exact comparison in
+ * scaled-integer space. `actual` is the RAW stored field value.
+ *
+ * Missing/malformed stored values and cross-currency comparisons match
+ * `!=` only — consistent with the generic clause semantics where an
+ * absent field is "not equal" and has no defined order.
+ */
+export declare function evaluateMoneyClause(actual: unknown, op: Operator, operand: MoneyWhereOperand): boolean;
+export {};