@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/store/index.d.cts

@@ -1,10 +1,12 @@
-import { aO as NoydbStore, cG as NoydbBundleStore } from '../types-DJG8HG6F.cjs';
-export { by as BUNDLE_STORE_POLICY, cb as INDEXED_STORE_POLICY, cZ as PullMode, c$ as PullPolicy, d1 as PushMode, d3 as PushPolicy, dE as SyncPolicy, dF as SyncScheduler, dG as SyncSchedulerStatus } from '../types-DJG8HG6F.cjs';
-export { au as StoreCapabilityError } from '../index-BMjrzNZr.cjs';
-import '../lazy-builder-C-rPfWG0.cjs';
-import '../predicate-Dnu81tsS.cjs';
-import '../strategy-DSTrsZ8t.cjs';
+import { aW as NoydbStore, aw as NoydbBundleStore } from '../types-DyOI6XZ_.cjs';
+export { bK as BUNDLE_STORE_POLICY, cJ as INDEXED_STORE_POLICY, dF as PullMode, dH as PullPolicy, dJ as PushMode, dL as PushPolicy, eA as SyncPolicy, eB as SyncScheduler, eC as SyncSchedulerStatus } from '../types-DyOI6XZ_.cjs';
+export { aA as StoreCapabilityError } from '../errors-Dkc_fi-S.cjs';
+import '../lazy-builder-eYZzLEL1.cjs';
+import '../predicate-BmhBSPCH.cjs';
+import '../strategy-WtB-jXYv.cjs';
 import '../strategy-BSxFXGzb.cjs';
+import '../index-BMmajblo.cjs';
+import '../index-tZqVB9g5.cjs';
 import '@noy-db/attestation';
 
 interface WrapBundleStoreOptions {
@@ -278,6 +280,13 @@ interface RoutedNoydbStore extends NoydbStore {
     resume(route: OverrideTarget): Promise<number>;
     /** Snapshot the current override/suspend state for diagnostics. */
     routeStatus(): RouteStatus;
+    /**
+     * Resolve the physical backend a vault id maps to via the geographic
+     * `vaultRoutes` prefix routing (collection-independent), falling back to
+     * the `default` store. Used by the federation data-residency guard (#271)
+     * to read the placement backend's `capabilities.region`.
+     */
+    resolveBackend(vaultId: string): NoydbStore;
 }
 /**
  * Create a store multiplexer that dispatches operations to different backends

package/dist/store/index.d.ts

@@ -1,10 +1,12 @@
-import { aO as NoydbStore, cG as NoydbBundleStore } from '../types-BoFFiskX.js';
-export { by as BUNDLE_STORE_POLICY, cb as INDEXED_STORE_POLICY, cZ as PullMode, c$ as PullPolicy, d1 as PushMode, d3 as PushPolicy, dE as SyncPolicy, dF as SyncScheduler, dG as SyncSchedulerStatus } from '../types-BoFFiskX.js';
-export { au as StoreCapabilityError } from '../index-BCKdioeh.js';
-import '../lazy-builder-Rpd-V3jP.js';
-import '../predicate-Dnu81tsS.js';
-import '../strategy-DSTrsZ8t.js';
+import { aW as NoydbStore, aw as NoydbBundleStore } from '../types-DLfWFr6U.js';
+export { bK as BUNDLE_STORE_POLICY, cJ as INDEXED_STORE_POLICY, dF as PullMode, dH as PullPolicy, dJ as PushMode, dL as PushPolicy, eA as SyncPolicy, eB as SyncScheduler, eC as SyncSchedulerStatus } from '../types-DLfWFr6U.js';
+export { aA as StoreCapabilityError } from '../errors-Dkc_fi-S.js';
+import '../lazy-builder-ChSqcF5t.js';
+import '../predicate-BmhBSPCH.js';
+import '../strategy-54eIwox5.js';
 import '../strategy-BSxFXGzb.js';
+import '../index-BMmajblo.js';
+import '../index-Bm9hIY7t.js';
 import '@noy-db/attestation';
 
 interface WrapBundleStoreOptions {
@@ -278,6 +280,13 @@ interface RoutedNoydbStore extends NoydbStore {
     resume(route: OverrideTarget): Promise<number>;
     /** Snapshot the current override/suspend state for diagnostics. */
     routeStatus(): RouteStatus;
+    /**
+     * Resolve the physical backend a vault id maps to via the geographic
+     * `vaultRoutes` prefix routing (collection-independent), falling back to
+     * the `default` store. Used by the federation data-residency guard (#271)
+     * to read the placement backend's `capabilities.region`.
+     */
+    resolveBackend(vaultId: string): NoydbStore;
 }
 /**
  * Create a store multiplexer that dispatches operations to different backends

package/dist/store/index.js

@@ -9,7 +9,7 @@ import {
   withRetry,
   wrapBundleStore,
   wrapStore
-} from "../chunk-MUWOSVEP.js";
+} from "../chunk-NSXNXLYM.js";
 import {
   BUNDLE_STORE_POLICY,
   INDEXED_STORE_POLICY,
@@ -17,7 +17,7 @@ import {
 } from "../chunk-2QR2PQTT.js";
 import {
   StoreCapabilityError
-} from "../chunk-W3XXT26A.js";
+} from "../chunk-OTWT6BAJ.js";
 export {
   BUNDLE_STORE_POLICY,
   INDEXED_STORE_POLICY,

package/dist/{strategy-DSTrsZ8t.d.ts → strategy-54eIwox5.d.ts}

@@ -1,3 +1,5 @@
+import { N as NoydbError } from './errors-Dkc_fi-S.js';
+
 /**
  * Aggregation reducers for the query DSL.
  *
@@ -57,6 +59,35 @@ interface Reducer<R, S = R> {
     remove?(state: S, record: unknown): S;
     /** Collapse the internal state into the user-visible result. */
     finalize(state: S): R;
+    /**
+     * Combine two independent partial states into one (then `finalize` once).
+     * Optional. MUST be associative + commutative with `init()` as identity.
+     * Never merge finalized results — only states. Enables parallel /
+     * hierarchical aggregation (e.g. cross-shard or advisor→firm rollup).
+     */
+    merge?(a: S, b: S): S;
+    /**
+     * Identifying operation tag stamped by each built-in factory.
+     * Used by `summariseAggregateOp` in the introspection walker to
+     * render human-readable aggregate descriptors in `dumpSchema()`.
+     * Optional so third-party custom reducers are unaffected.
+     */
+    readonly op?: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    /**
+     * Field name for field-based reducers (`sum`, `avg`, `min`, `max`).
+     * Absent on `count` which aggregates over record count, not a field.
+     */
+    readonly field?: string;
+    /**
+     * Money-only: target currency for `sum` over a multi-currency money
+     * field. Consumed by `wrapMoneyReducers` to convert per-currency
+     * subtotals to one figure. Ignored for non-money fields.
+     */
+    readonly convertTo?: string;
+    /**
+     * Money-only: FX rate map (`'USD->EUR' → rate`) used with `convertTo`.
+     */
+    readonly fx?: Record<string, number | string>;
 }
 /**
  * Common options accepted by every reducer factory.
@@ -75,6 +106,13 @@ interface Reducer<R, S = R> {
 interface ReducerOptions<TSeed = unknown> {
     /**  constraint #2 — seed is plumbed through but unused in. */
     readonly seed?: TSeed;
+    /**
+     * Money-only (honored by `sum` over a multi-currency money field):
+     * convert per-currency subtotals to this currency for a single figure.
+     */
+    readonly convertTo?: string;
+    /** Money-only: FX rate map (`'USD->EUR' → rate`) used with `convertTo`. */
+    readonly fx?: Record<string, number | string>;
 }
 /**
  * Count the number of records that match the query. Ignores field
@@ -308,6 +346,391 @@ declare class Aggregation<R> {
  */
 declare function buildLiveAggregation<V>(recompute: () => V, upstreams: readonly AggregationUpstream[]): LiveAggregation<V>;
 
+/**
+ * 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.
+ */
+type RoundingMode = 'half-up' | 'half-even' | 'half-down' | 'up' | 'down' | 'ceil' | 'floor';
+
+/**
+ * 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.
+ */
+
+interface MoneyOptionsFixed {
+    currency: string;
+    /** Override the ISO-4217 default scale (required for unlisted codes). */
+    scale?: number;
+    rounding?: RoundingMode;
+}
+interface MoneyOptionsMulti {
+    currencies: 'any' | readonly string[];
+    /** Per-currency scale overrides (required for unlisted codes). */
+    scaleOverrides?: Record<string, number>;
+    rounding?: RoundingMode;
+}
+type MoneyOptions = MoneyOptionsFixed | MoneyOptionsMulti;
+interface MoneyDescriptor {
+    readonly _noydbMoney: true;
+    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. */
+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. */
+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. */
+declare class MoneyUnsupportedError extends NoydbError {
+    readonly field: string;
+    constructor(field: string, message?: string);
+}
+/** Create a {@link MoneyDescriptor}. */
+declare function money(options: MoneyOptions): MoneyDescriptor;
+/** Runtime predicate for detecting a {@link MoneyDescriptor}. */
+declare function isMoneyDescriptor(x: unknown): x is MoneyDescriptor;
+
+/**
+ * Per-layer i18n resolution policy.
+ *
+ * `onMissing` governs what happens when a multilingual field is resolved
+ * to a target locale that is absent. It may be a single scalar policy or
+ * a per-layer map, so a field can be lenient at the app read boundary but
+ * strict inside a materialized view.
+ *
+ * Effective policy for layer `λ`:
+ *
+ * ```
+ * explicit(λ) = typeof onMissing === 'object' ? onMissing[λ] : undefined
+ * scalar      = typeof onMissing === 'string' ? onMissing : undefined
+ * policy(λ)   = explicit(λ) ?? layerDefault(λ) ?? scalar ?? 'throw'
+ * ```
+ *
+ * - `layerDefault('guard') = 'substitute'` — guards are lenient unless
+ *   EXPLICITLY overridden; they never inherit a scalar policy (a guard
+ *   reading a display value must not hard-fail on a missing locale).
+ * - every other layer has no default, so it inherits the scalar, else
+ *   falls back to `'throw'` (today's behavior — zero breaking change).
+ *
+ * @public
+ */
+type OnMissing = 'substitute' | 'null' | 'throw';
+/**
+ * The contexts in which a multilingual field is resolved. Each can carry
+ * its own `onMissing` policy.
+ *
+ * - `read`       — ordinary app reads (`get`/`list`/query projection).
+ * - `guard`      — a guard callback reading a value.
+ * - `join`       — a joined record expanded onto a row.
+ * - `mv`         — materialized-view input.
+ * - `derivation` — derivation input.
+ * - `export`     — bundle/public-envelope export.
+ */
+type Layer = 'read' | 'guard' | 'join' | 'mv' | 'derivation' | 'export';
+/** Field-level policy: a single scalar, or a per-layer map. */
+type OnMissingPolicy = OnMissing | Partial<Record<Layer, OnMissing>>;
+/**
+ * Resolve the effective `OnMissing` for a layer from a field's declared
+ * policy. See module docs for the resolution rule.
+ */
+declare function resolvePolicy(onMissing: OnMissingPolicy | undefined, layer: Layer): OnMissing;
+
+/**
+ * i18nText schema type —
+ *
+ * `i18nText({ languages, required })` creates a descriptor for a
+ * multi-language content field whose value is stored as a
+ * `{ [locale]: string }` map (e.g. `{ en: 'Consulting', th: 'ที่ปรึกษา' }`).
+ *
+ * On put, the descriptor validates that required languages are present.
+ * On read (when a `locale` option is passed), the map is collapsed to the
+ * caller's locale string via the fallback chain.
+ *
+ * Design decisions
+ * ────────────────
+ *
+ * **Descriptor pattern (not a Zod type).**
+ * `i18nText()` returns a plain descriptor object used in the collection's
+ * `i18nFields` option — same pattern as `ref()` / `dictKey()`. This keeps
+ * `@noy-db/core` at zero runtime dependencies and avoids Zod v3 field-type
+ * constraints. TypeScript inference is handled via the descriptor's type.
+ *
+ * **Enforcement at the collection boundary.**
+ * The `required` option is checked by `Collection.put()` via the compartment's
+ * registered `i18nFields`. Failed validation throws `MissingTranslationError`
+ * — a distinct class from `SchemaValidationError` so callers can tell
+ * "wrong shape" from "missing translations".
+ *
+ * **Resolution is post-decryption.**
+ * Locale resolution happens AFTER `decryptRecord()`, as a pure in-memory
+ * transform. No additional crypto work is needed. The resolved record is
+ * returned in place of the stored one, with i18nText fields replaced by
+ * their locale-resolved strings.
+ *
+ * **`locale: 'raw'`.**
+ * Passing `{ locale: 'raw' }` skips resolution and returns the full
+ * `{ [locale]: string }` map — useful for bilingual exports, admin UIs,
+ * and any context where all translations must be visible at once.
+ *
+ * **Out of scope.**
+ * Pluralization, RTL rendering, date/number formatting, per-locale CRDT
+ * merging.
+ */
+
+/** Flatten an intersection into a single object literal for nicer hovers. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The stored shape of a multilingual field, inferred from its `required`
+ * mode — so the compiler forces you to handle an absent optional locale
+ * (`string | undefined`) instead of silently yielding `undefined`.
+ *
+ * Mirrors `i18nText({ languages, required })`:
+ * - `'all'` (default) — every locale required: `{ th: string; en: string }`
+ * - `'any'`           — every locale optional: `{ th?: string; en?: string }`
+ *   (the "at least one present" guarantee is runtime-only — not expressible
+ *   in TypeScript — so each key is optional)
+ * - `readonly L[]`    — listed locales required, the rest optional:
+ *   `I18nMap<'th'|'en', ['th']>` → `{ th: string; en?: string }`
+ *
+ * @example
+ * ```ts
+ * type Lang = 'th' | 'en'
+ * interface Contact {
+ *   name: I18nMap<Lang, 'any'>      // { th?: string; en?: string }
+ *   legalName: I18nMap<Lang, ['th']> // { th: string; en?: string }
+ *   slug: I18nMap<Lang>             // { th: string; en: string }
+ * }
+ * ```
+ *
+ * @public
+ */
+type I18nMap<Langs extends string, Required extends 'all' | 'any' | readonly Langs[] = 'all'> = Required extends 'all' ? Record<Langs, string> : Required extends 'any' ? Partial<Record<Langs, string>> : Required extends readonly (infer R extends Langs)[] ? Prettify<Record<R, string> & Partial<Record<Exclude<Langs, R>, string>>> : never;
+/**
+ * Options for `i18nText()`.
+ *
+ * `languages` declares the full set of supported locales. `required`
+ * controls which must be present on every `put()`.
+ *
+ * `autoTranslate` is the per-field opt-in for the `plaintextTranslator`
+ * hook. When `true` and a `plaintextTranslator` is configured
+ * on `createNoydb()`, missing translations are generated before `put()`.
+ * Default: `false`.
+ */
+interface I18nTextOptions {
+    /** All supported locale codes (BCP 47). */
+    readonly languages: readonly string[];
+    /**
+     * Which locales must be present on every `put()`.
+     *
+     * - `'all'`       — every declared language must be present.
+     * - `'any'`       — at least one declared language must be present.
+     * - `string[]`    — listed locales are required; others are optional.
+     */
+    readonly required: 'all' | 'any' | readonly string[];
+    /**
+     * Per-field opt-in for the `plaintextTranslator` hook.
+     * When `true`, missing required translations are auto-generated
+     * before `put()` if a translator is configured. Default: `false`.
+     */
+    readonly autoTranslate?: boolean;
+    /**
+     * What to do when this field is resolved to a locale that is absent.
+     * A single policy, or a per-layer map (read/guard/join/mv/derivation/
+     * export). Default `'throw'` — today's behavior, zero breaking change.
+     * See {@link OnMissingPolicy}.
+     *
+     * NOTE (current wiring): ALL layers are enforced — `read` (`get`/`list`),
+     * `guard`, `derivation`, `mv`, `join`, `export`. Guard / derivation
+     * `ctx.vault` reads resolve under their own layer policy (`guard` defaults to
+     * the lenient `'substitute'`). The `mv` layer fires for materialized views
+     * that declare `{ i18nLocale, i18nFields }` — UNION (group-key i18n fields
+     * resolve before the unified-row bucketing) and query-form (resolved in
+     * `GroupedAggregation.run` before `groupAndReduce`); grouping a raw i18n field
+     * without a locale throws. The `join` layer resolves a joined right-side i18n
+     * field to the query locale (`toArray({ locale })` or the vault default; raw
+     * when locale-less). The `export` layer fires for
+     * `exportStream`/`exportJSON({ resolveLabels })` — records collapse to the
+     * export locale.
+     */
+    readonly onMissing?: OnMissingPolicy;
+    /**
+     * Ordered preferred-substitute locales used when `onMissing` resolves
+     * to `'substitute'` and the target locale is absent. `'any'` as an
+     * element means "first non-empty value". A caller-supplied `fallback`
+     * at read time takes precedence over this declared list.
+     */
+    readonly substitute?: readonly string[];
+    /**
+     * #285 smart-substitute. When `true`, a missing-locale `substitute` walk that
+     * misses the explicit chain prefers the available locale whose script is
+     * nearest the target (same script, then Latin) rather than an arbitrary value
+     * — e.g. a missing Thai label prefers another Thai (or Latin) translation over
+     * an unreadable script. Default `false` (legacy first-non-empty behavior).
+     */
+    readonly smartSubstitute?: boolean;
+    /**
+     * Per-locale script enforcement (write-time). `'auto'` infers the
+     * allowed Unicode scripts per locale (asymmetric Latin tolerance); an
+     * object overrides per slot. Absent ⇒ no check. See `./script.ts`.
+     */
+    readonly script?: 'auto' | Partial<Record<string, readonly string[]>>;
+    /**
+     * What to do when a slot's value contains characters outside its
+     * allowed script set. Default `'reject'`.
+     */
+    readonly onScriptViolation?: 'reject' | 'filter' | 'warn';
+}
+/**
+ * Descriptor returned by `i18nText()`. Attach to the collection's
+ * `i18nFields` option:
+ *
+ * ```ts
+ * const lineItems = company.collection<LineItem>('line-items', {
+ *   i18nFields: {
+ *     description: i18nText({ languages: ['en', 'th'], required: 'all' }),
+ *   },
+ * })
+ * ```
+ */
+interface I18nTextDescriptor {
+    readonly _noydbI18nText: true;
+    readonly options: I18nTextOptions;
+}
+/**
+ * Create an `I18nTextDescriptor` for a multi-language content field.
+ *
+ * @param options  Language list + enforcement mode.
+ *
+ * @example
+ * ```ts
+ * i18nText({ languages: ['en', 'th'], required: 'all' })
+ * i18nText({ languages: ['en', 'th'], required: ['th'], autoTranslate: true })
+ * ```
+ */
+declare function i18nText(options: I18nTextOptions): I18nTextDescriptor;
+/** Runtime predicate for detecting an `I18nTextDescriptor`. */
+declare function isI18nTextDescriptor(x: unknown): x is I18nTextDescriptor;
+/**
+ * Validate that a value is a valid `{ [locale]: string }` map and that
+ * all required locales are present. Throws `MissingTranslationError`
+ * when the required constraint is violated.
+ *
+ * Called by `Collection.put()` for each registered `i18nField`.
+ *
+ * @param value       The raw field value from the record being put.
+ * @param field       The field name (used in the thrown error message).
+ * @param descriptor  The `i18nText()` descriptor for this field.
+ */
+declare function validateI18nTextValue(value: unknown, field: string, descriptor: I18nTextDescriptor): void;
+/**
+ * Resolve an i18nText value (`{ [locale]: string }` map) to a string
+ * for the given locale.
+ *
+ * @param value    The stored locale map.
+ * @param locale   The requested locale code, or `'raw'` to return the map.
+ * @param fallback Single locale or ordered list; use `'any'` as the last
+ *                 element to fall back to any available translation.
+ * @param field    Field name used in `LocaleNotSpecifiedError` messages.
+ * @returns The resolved string, OR the original map when `locale === 'raw'`.
+ */
+/** Options for the policy-aware form of {@link resolveI18nText}. */
+interface ResolveI18nOptions {
+    /** Effective policy for the resolution layer. Default `'throw'`. */
+    readonly policy?: OnMissing;
+    /** Declared substitute chain; applied only under policy `'substitute'`. */
+    readonly substitute?: readonly string[];
+    /**
+     * #285 smart-substitute. When `true` and policy is `'substitute'`, after the
+     * explicit chain misses, pick the available locale whose script is nearest the
+     * target (same script first, then Latin's broad readability) instead of an
+     * arbitrary value. Default `false`.
+     */
+    readonly smartSubstitute?: boolean;
+}
+declare function resolveI18nText(value: Record<string, string>, locale: string, fallback?: string | readonly string[], field?: string): string | Record<string, string>;
+declare function resolveI18nText(value: Record<string, string>, locale: string, fallback: string | readonly string[] | undefined, field: string | undefined, opts: ResolveI18nOptions): string | Record<string, string> | null;
+/**
+ * Return all leaf values at `path`, expanding `[].` array wildcards.
+ *
+ * - `'name'`              → `[obj.name]`
+ * - `'address.lineOne'`   → `[obj.address.lineOne]`
+ * - `'contacts[].title'`  → `[obj.contacts[0].title, obj.contacts[1].title, …]`
+ *
+ * Returns an empty array when the path does not resolve (missing key,
+ * wrong type, etc.). Used by `enforceI18nOnPut` to validate nested fields.
+ */
+declare function getAtPath(obj: Record<string, unknown>, path: string): unknown[];
+/**
+ * Mutate `obj` in-place, setting `value` at the nested `path`.
+ * Supports dot notation (`'address.lineOne'`) but not array wildcards —
+ * auto-translate on `contacts[].title` style paths is not supported.
+ */
+declare function setAtPathInPlace(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Apply locale resolution to a single record, returning a new copy.
+ *
+ * For each field registered as an `i18nText` descriptor:
+ * - If `locale === 'raw'`, the field value is left as the stored map.
+ * - Otherwise, the field value is replaced with the resolved string.
+ *
+ * Field paths support dot notation (`'address.lineOne'`) and array
+ * wildcards (`'contacts[].title'`). Top-level fields work as before.
+ *
+ * @param record      The decrypted record.
+ * @param i18nFields  Map of field path → `I18nTextDescriptor`.
+ * @param locale      The requested locale (or `'raw'`).
+ * @param fallback    Fallback chain (optional).
+ * @param layer       Resolution layer (default `'read'`). Each field's
+ *                    `onMissing` policy is resolved for this layer, so the
+ *                    same record resolves leniently on a get but strictly
+ *                    inside an mv/derivation.
+ */
+declare function applyI18nLocale(record: Record<string, unknown>, i18nFields: Record<string, I18nTextDescriptor>, locale: string, fallback?: string | readonly string[], layer?: Layer): Record<string, unknown>;
+
 /**
  * Query DSL `.groupBy()` —.
  *
@@ -430,6 +853,12 @@ declare abstract class GroupedQueryBase {
      * for composite keys.
      */
     protected readonly dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined;
+    /**
+     * Money field descriptors for the backing collection — used to
+     * rewrite `sum`/`min`/`max` over money fields into exact BigInt
+     * reducers when `.aggregate(spec)` is terminated.
+     */
+    protected readonly moneyFields?: Record<string, MoneyDescriptor> | undefined;
     /**
      * Field set this grouped query buckets on. Stored in declaration
      * order — the same order is preserved on every result row by
@@ -444,7 +873,15 @@ declare abstract class GroupedQueryBase {
      * `undefined` — `<field>Label` projection has no meaningful shape
      * for composite keys.
      */
-    dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined);
+    dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined, 
+    /**
+     * Money field descriptors for the backing collection — used to
+     * rewrite `sum`/`min`/`max` over money fields into exact BigInt
+     * reducers when `.aggregate(spec)` is terminated.
+     */
+    moneyFields?: Record<string, MoneyDescriptor> | undefined);
+    /** Apply money-aware reducer rewriting when money fields are declared. */
+    protected wrapSpec<Spec extends AggregateSpec>(spec: Spec): Spec;
 }
 /**
  * Chainable wrapper returned by `Query.groupBy(field)`. Terminates
@@ -484,7 +921,7 @@ declare class GroupedQueryN<T, F extends readonly string[]> extends GroupedQuery
  * bucket would be created — the consumer doesn't have to wait for
  * the full partition to materialize before the error fires.
  */
-declare function groupAndReduce<R>(records: readonly unknown[], fieldOrFields: string | readonly string[], spec: AggregateSpec): R[];
+declare function groupAndReduce<R>(records: readonly unknown[], fieldOrFields: string | readonly string[], spec: AggregateSpec, moneyFields?: Record<string, MoneyDescriptor>): R[];
 /**
  * Grouped aggregation wrapper — the `.groupBy(field).aggregate(spec)`
  * terminal. Shape mirrors `Aggregation<R>` from aggregate.ts: two
@@ -511,8 +948,20 @@ declare class GroupedAggregation<R> {
      *. Present when the grouping field is a dictKey.
      */
     dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined);
-    /** Execute the query, group, reduce, and return an array of rows. */
-    run(): R[];
+    /**
+     * Execute the query, group, reduce, and return an array of rows.
+     *
+     * `opts` (#285 query-form MV grouping): when a `locale` + `i18nFields` are
+     * given, the declared group-key `i18nText` fields are resolved to that locale
+     * at the `mv` layer BEFORE bucketing — so an i18n group key is a stable string
+     * instead of a raw `{locale}` map. The MV executor passes the MV's
+     * `i18nLocale`/`i18nFields`; ordinary `.run()` callers pass nothing and are
+     * unaffected.
+     */
+    run(opts?: {
+        locale?: string;
+        i18nFields?: Record<string, I18nTextDescriptor>;
+    }): R[];
     /**
      * Execute the query, group, reduce, and resolve `<field>Label` for
      * each result row when the grouping field is a `dictKey` and a
@@ -582,14 +1031,14 @@ interface AggregateStrategy {
      * Build a `GroupedQuery<T, F>` for `Query.groupBy(field)`. Same
      * closure / upstream inputs as `aggregate` plus the group key field.
      */
-    groupBy<T, F extends string>(executeRecords: () => readonly unknown[], field: F, upstreams: readonly AggregationUpstream[], dictLabelResolver?: (key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>): GroupedQuery<T, F>;
+    groupBy<T, F extends string>(executeRecords: () => readonly unknown[], field: F, upstreams: readonly AggregationUpstream[], dictLabelResolver?: (key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>, moneyFields?: Record<string, MoneyDescriptor>): GroupedQuery<T, F>;
     /**
      * Variadic-keyed sibling — builds a `GroupedQueryN<T, F>` for
      * `Query.groupBy(...fields)`. No dictLabelResolver — `<field>Label`
      * projection only applies to single-field groupings, which dispatch
      * through `groupBy` above.
      */
-    groupByN<T, F extends readonly string[]>(executeRecords: () => readonly unknown[], fields: F, upstreams: readonly AggregationUpstream[]): GroupedQueryN<T, F>;
+    groupByN<T, F extends readonly string[]>(executeRecords: () => readonly unknown[], fields: F, upstreams: readonly AggregationUpstream[], moneyFields?: Record<string, MoneyDescriptor>): GroupedQueryN<T, F>;
     /**
      * Terminal streaming aggregator for `ScanBuilder.aggregate(spec)`.
      * Takes an async iterable of decrypted records + the spec and
@@ -598,4 +1047,4 @@ interface AggregateStrategy {
     scanAggregate<Spec extends AggregateSpec>(iter: AsyncIterable<unknown>, spec: Spec): Promise<AggregateResult<Spec>>;
 }
 
-export { type AggregateStrategy as A, GROUPBY_MAX_CARDINALITY as G, type LiveAggregation as L, type Reducer as R, type AggregateResult as a, type AggregateSpec as b, Aggregation as c, type AggregationUpstream as d, GROUPBY_WARN_CARDINALITY as e, GroupedAggregation as f, GroupedQuery as g, GroupedQueryN as h, type GroupedRow as i, type GroupedRowN as j, type ReducerOptions as k, avg as l, buildLiveAggregation as m, count as n, groupAndReduce as o, max as p, min as q, reduceRecords as r, resetGroupByWarnings as s, sum as t };
+export { type AggregateStrategy as A, count as B, groupAndReduce as C, max as D, min as E, reduceRecords as F, GROUPBY_MAX_CARDINALITY as G, resetGroupByWarnings as H, type I18nMap as I, sum as J, type RoundingMode as K, type Layer as L, MoneyCurrencyError as M, type MoneyDescriptor as N, type OnMissing as O, type MoneyOptions as P, type MoneyOptionsFixed as Q, type ResolveI18nOptions as R, type MoneyOptionsMulti as S, MoneyPrecisionError as T, MoneyUnsupportedError as U, isMoneyDescriptor as V, money as W, type I18nTextDescriptor as a, type I18nTextOptions as b, type OnMissingPolicy as c, applyI18nLocale as d, isI18nTextDescriptor as e, resolvePolicy as f, getAtPath as g, type AggregateResult as h, i18nText as i, type AggregateSpec as j, Aggregation as k, type AggregationUpstream as l, GROUPBY_WARN_CARDINALITY as m, GroupedAggregation as n, GroupedQuery as o, GroupedQueryN as p, type GroupedRow as q, resolveI18nText as r, setAtPathInPlace as s, type GroupedRowN as t, type LiveAggregation as u, validateI18nTextValue as v, type Reducer as w, type ReducerOptions as x, avg as y, buildLiveAggregation as z };