@noy-db/hub 0.2.0-pre.30 → 0.2.0-pre.31

package/dist/strategy-mJExw4LQ.d.cts

@@ -1,1069 +0,0 @@
-import { N as NoydbError } from './errors-BAWO5Z5a.cjs';
-
-/**
- * Aggregation reducers for the query DSL.
- *
- * the reducer protocol plus five built-in factories
- * (`count`, `sum`, `avg`, `min`, `max`) consumed by `Query.aggregate()`
- * and, in the future, `Scan.aggregate()`. Every factory accepts
- * an optional `{ seed }` parameter that is plumbed through the
- * protocol but unused by the executor — that's the load-bearing
- * half of  constraint #2. When partition-aware aggregation
- * lands, the seed carries the previous partition's running total into
- * the next partition without requiring a protocol change.
- *
- * Reducers are intentionally generic over their internal state type
- * `S` so compound reducers (avg keeps `{sum, count}`, min/max keep a
- * value bag) can model internal bookkeeping without leaking the
- * implementation through the accumulator's public shape. `finalize`
- * collapses `S` back into the user-visible `R`.
- *
- * Reducers are pure data — `init` / `step` / `finalize` / optional
- * `remove` are stateless functions that receive and return `S`. This
- * is the shape that admits O(1) incremental maintenance in a future
- * optimization (delta-aware `LiveAggregation` applies `step` or
- * `remove` per delta), without blocking the simpler "full re-run on
- * source change" that ships.
- */
-/**
- * A single reducer: factory-produced, ready to plug into an
- * `.aggregate()` spec.
- *
- * Type parameters:
- *   - `R` — user-visible result type (what the aggregation returns
- *     for this slot, e.g. `number` for `sum()`)
- *   - `S` — internal state type, defaults to `R` for simple reducers
- *     that don't need compound bookkeeping
- *
- * A reducer is stateless: every method is pure over `S`. `init()` is
- * called once per aggregation run to build the initial state; `step()`
- * folds a record into the state; `remove()` (optional) un-folds a
- * record, enabling incremental live maintenance; `finalize()` reads
- * the final answer out of the state at the end of the run.
- */
-interface Reducer<R, S = R> {
-    /** Build the initial state for a fresh aggregation run. */
-    init(): S;
-    /** Fold a record into the state. Returns the new state. */
-    step(state: S, record: unknown): S;
-    /**
-     * Un-fold a record from the state. Returns the new state.
-     *
-     * Optional — reducers without `remove` cannot be maintained
-     * incrementally and must be re-run from scratch when the underlying
-     * record set changes. `sum`, `count`, `avg` implement `remove` in
-     * O(1); `min` and `max` implement it in O(N) worst case (when the
-     * extremum itself is removed and the next extremum must be
-     * recomputed from the remaining contributing values).
-     */
-    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.
- *
- * `seed` — optional initial value for the internal state. **Unused by
- * the executor**, plumbed through the protocol for  constraint
- * #2 (partition-aware aggregation seam). In, partitioned
- * aggregations will pass the previous partition's carry as `seed` so
- * a long time series can be rolled forward one partition at a time
- * without re-aggregating closed partitions.
- *
- * always uses `init()` with the factory's zero value, regardless
- * of whether `seed` was passed. Do not remove the parameter — that's
- * the whole point of having it exist now.
- */
-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
- * values entirely — the count is over the number of records, not over
- * the number of non-null field values in any column.
- */
-declare function count(opts?: ReducerOptions<number>): Reducer<number>;
-/**
- * Sum a numeric field across all matching records. Non-number values
- * at the field path are coerced to 0 — consumers who want a different
- * behavior (throw, skip, treat as NaN) should filter upstream via
- * `.where()` or write a custom reducer.
- */
-declare function sum(field: string, opts?: ReducerOptions<number>): Reducer<number>;
-/**
- * Arithmetic mean of a numeric field across all matching records.
- *
- * Returns `null` for an empty result set (zero records is not a
- * well-defined denominator — returning NaN would poison downstream
- * arithmetic, and throwing would force every consumer to wrap in
- * try/catch just to handle "no matches"). Consumers who want an
- * explicit zero should coalesce with `?? 0`.
- *
- * Internal state is `{sum, count}` so the running average can be
- * maintained incrementally — on each delta, both fields update in
- * O(1) and `finalize` divides. Directly storing `avg` as state would
- * not admit incremental removal without also tracking count.
- */
-declare function avg(field: string, opts?: ReducerOptions<{
-    sum: number;
-    count: number;
-}>): Reducer<number | null, {
-    sum: number;
-    count: number;
-}>;
-interface MinMaxState {
-    /**
-     * Multiset of contributing field values. Stored as a plain array
-     * because we need to support `remove` and a plain array gives us
-     * O(1) push + O(N) worst-case removal — which matches the
-     * documented min/max removal complexity. A sorted structure would
-     * let us drop the O(N) rescan but adds complexity that doesn't
-     * need; consumers hitting the O(N) ceiling should file an issue.
-     */
-    readonly values: number[];
-}
-/**
- * Smallest numeric value of a field across all matching records.
- * Returns `null` for an empty result set. See `avg()` for the
- * reasoning on `null` vs NaN vs throwing.
- *
- * Incremental complexity: O(1) for `step`, O(N) worst case for
- * `remove` when the current minimum is removed (the state holds the
- * full multiset of contributing values and `finalize` scans for the
- * new minimum). Consumers with very large result sets and frequent
- * removals of the current extremum should either accept the cost or
- * wait for a future optimization.
- */
-declare function min(field: string, opts?: ReducerOptions<number>): Reducer<number | null, MinMaxState>;
-/**
- * Largest numeric value of a field across all matching records.
- * Mirror of `min()` — see that doc for semantics, null-on-empty
- * behavior, and the O(N) removal caveat.
- */
-declare function max(field: string, opts?: ReducerOptions<number>): Reducer<number | null, MinMaxState>;
-
-/**
- * Aggregate execution — the runtime behind `Query.aggregate()`.
- *
- * takes an `AggregateSpec` (a record of named reducers
- * built from `reducers.ts`) and runs every reducer over the records
- * produced by the underlying query. Two terminal surfaces:
- *
- *   - `.run(): R` — synchronous one-shot reduction. Matches the
- *     existing `Query.toArray()` / `.first()` / `.count()` style.
- *   - `.live(): LiveAggregation<R>` — reactive primitive that
- *     re-runs the reduction whenever the query's source notifies of
- *     a change. uses naive full re-run; incremental delta
- *     maintenance is admitted by the reducer protocol (`remove()`)
- *     but not wired to the executor yet — a follow-up optimization
- *     can switch from full re-run to delta-based without breaking
- *     the public API. Consumers get correct, reactive values today.
- *
- * The `Aggregation<R>` wrapper is deliberately tiny — it exists so
- * `.aggregate(spec)` can be chained with either `.run()` or `.live()`
- * without the builder needing two separate terminal methods. It
- * holds the closure over the query execution (produces the current
- * matching record set) and the spec, and stitches them together in
- * either mode.
- *
- * This file depends ONLY on `reducers.ts` — it has no knowledge of
- * the `Query` class. Tests can therefore exercise the reduction
- * surface with plain record arrays, without spinning up a Collection.
- */
-
-/**
- * A named set of reducers, keyed by output field name. Each key
- * becomes a field on the aggregated result.
- *
- * ```ts
- * const spec = {
- *   total: sum('amount'),
- *   n:     count(),
- *   avgAmount: avg('amount'),
- * }
- * ```
- */
-type AggregateSpec = Readonly<Record<string, Reducer<unknown, unknown>>>;
-/**
- * Map an `AggregateSpec` to its reduced result shape — each key
- * carries the finalized result type from its reducer. A spec built
- * from `{ total: sum('amount'), n: count() }` yields a result of
- * `{ total: number, n: number }`.
- *
- * This uses a mapped type with a conditional to extract `R` from
- * each `Reducer<R, _>`. The `infer` captures the user-visible result
- * type, discarding the internal state type `S`.
- */
-type AggregateResult<Spec extends AggregateSpec> = {
-    [K in keyof Spec]: Spec[K] extends Reducer<infer R, unknown> ? R : never;
-};
-/**
- * Pure reduction over a record array. Runs every reducer's
- * `init → step* → finalize` pipeline exactly once over the records.
- *
- * Called by `Aggregation.run()` and by the live-mode refresh path.
- * Exported for tests and for future `scan().aggregate()` reuse
- * — the streaming path will call the same reducer protocol with a
- * per-page loop instead of a single array.
- */
-declare function reduceRecords<Spec extends AggregateSpec>(records: readonly unknown[], spec: Spec): AggregateResult<Spec>;
-/**
- * A minimal reactive primitive for aggregation results.
- *
- * Same spirit as the `LiveQuery` in : frame-agnostic, a plain
- * object with `value` / `error` fields and a `subscribe(cb)`
- * notification channel that Vue / React / Solid adapters wrap in
- * their own primitive. Intentionally NOT a Promise — aggregations
- * have a well-defined "current value" at every instant, and the
- * reactive consumer wants to read that value synchronously.
- *
- * Error semantics mirror `LiveQuery`: if a re-run throws, the
- * previous successful `value` is preserved and the error is stored
- * in `error` so consumers can render an error state without losing
- * the last-known-good result. The throw does NOT propagate out of
- * the source's change handler (which would tear down the upstream
- * emitter).
- *
- * `stop()` tears down the upstream subscription. It is idempotent —
- * calling it multiple times is safe — and subscribe calls after
- * stop are no-ops (they immediately return a no-op unsubscribe).
- * Always call `stop()` when done; Vue's `onUnmounted` is the
- * canonical place. Raw consumers must do it themselves.
- */
-interface LiveAggregation<R> {
-    /** Current reduced value. Undefined only if the first compute threw. */
-    readonly value: R | undefined;
-    /** Last execution error, if any. Cleared on the next successful run. */
-    readonly error: unknown;
-    /** Notify on every recomputation (success or error). Returns unsubscribe. */
-    subscribe(cb: () => void): () => void;
-    /** Tear down the upstream subscription. Idempotent. */
-    stop(): void;
-}
-/**
- * Upstream change-notification hook for live aggregation.
- *
- * Matches the shape that `QuerySource.subscribe` already uses — a
- * single method that accepts a callback and returns an unsubscribe
- * function. The `Aggregation` wrapper collects upstreams from the
- * query's source and wires them into a single re-run trigger.
- */
-interface AggregationUpstream {
-    subscribe(cb: () => void): () => void;
-}
-/**
- * Chainable wrapper returned by `Query.aggregate(spec)`. Holds the
- * execute-records closure and the spec; terminal methods (`run`,
- * `live`) stitch them together in either mode.
- *
- * Why a wrapper instead of two terminal methods on `Query` directly?
- *
- * The `.aggregate(spec)` call is where the spec is bound — both
- * `.run()` and `.live()` need the same spec, and the consumer's
- * fluent style is `query.where(...).aggregate(spec).run()` or
- * `.aggregate(spec).live()`. Wrapping lets the spec be named once
- * and reused for either terminal, and keeps the `Query` class
- * from growing a pair of near-duplicate method overloads
- * (`aggregateRun` / `aggregateLive`) that would be harder to
- * discover.
- */
-declare class Aggregation<R> {
-    private readonly executeRecords;
-    private readonly spec;
-    private readonly upstreams;
-    constructor(executeRecords: () => readonly unknown[], spec: AggregateSpec, upstreams: readonly AggregationUpstream[]);
-    /**
-     * Execute the query and reduce the results synchronously.
-     * Returns the reduced shape matching the spec — e.g. a spec of
-     * `{ total: sum('amount'), n: count() }` returns
-     * `{ total: number, n: number }`.
-     */
-    run(): R;
-    /**
-     * Build a reactive `LiveAggregation<R>` that re-runs the reduction
-     * whenever any upstream source notifies of a change. The initial
-     * value is computed eagerly in the constructor, so consumers can
-     * read `live.value` immediately after calling `.live()`.
-     *
-     * Always call `live.stop()` when finished — it tears down the
-     * upstream subscriptions. Vue's `onUnmounted` is the canonical
-     * place.
-     *
-     * **Implementation note:** every upstream change triggers a full
-     * re-reduction. Incremental maintenance (O(1) per delta for
-     * sum/count/avg via the reducer protocol's `remove()` method) is a
-     * planned follow-up optimization — the protocol already supports
-     * it, but the executor doesn't drive it yet. Consumers get
-     * correct, reactive values today; future PRs can switch to
-     * delta-based maintenance without changing this API.
-     */
-    live(): LiveAggregation<R>;
-}
-/**
- * Build a `LiveAggregation<V>` from a recompute closure and a list
- * of upstreams. Exposed so sibling files in the query DSL
- * (currently `groupby.ts`) can reuse the reactive primitive
- * without reaching into `LiveAggregationImpl` directly. This keeps
- * the implementation class private while still allowing planned
- * composition with `.groupBy().aggregate().live()`.
- */
-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';
-    /**
-     * #435 v1.x — eager-fill empty locale slots from the substitute chain at
-     * write time, recording provenance in the internal `_i18nFilled` marker.
-     * Mutually exclusive with an EXPLICIT `'throw'` onMissing policy (densify
-     * fills every hole, so a throw would be unreachable). Without an explicit
-     * `substitute`, fills from `'any'` (first non-empty). Default absent.
-     */
-    readonly densifyOnWrite?: boolean;
-}
-/**
- * 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>;
-/**
- * Remove the internal densify provenance marker (`_i18nFilled`) from a
- * read-facing record (#435). NON-mutating: returns the same object when the
- * marker is absent, otherwise a shallow copy without the marker.
- *
- * MUST be applied on every user-facing read return — even locale-less ones,
- * which bypass {@link applyI18nLocale}. MUST NOT be applied on the internal
- * prior-read path (decryptRecord / resolveDensifyPrior), where densify needs
- * the marker.
- */
-declare function stripI18nFilled<T extends Record<string, unknown>>(record: T): T;
-
-/**
- * Query DSL `.groupBy()` —.
- *
- * Chains after `.where()` / `.filter()` / `.or()` / `.and()` on a
- * Query and before a reducer spec, so consumers can compute
- * per-bucket aggregates without folding in userland:
- *
- * ```ts
- * const byClient = invoices.query()
- *   .where('status', '==', 'open')
- *   .groupBy('clientId')
- *   .aggregate({ total: sum('amount'), n: count() })
- *   .run()
- * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
- * ```
- *
- * Execution pipeline:
- *
- *   1. Run the query's where/filter clauses (same candidate /
- *      filter pipeline as `.aggregate()` directly on Query).
- *   2. Partition the matching records into buckets keyed by
- *      `readPath(record, field)`. JS `Map` preserves insertion
- *      order, so the first-seen key for a bucket determines its
- *      position in the result array — consumers who want a
- *      specific ordering should `.sort()` downstream.
- *   3. Enforce cardinality: warn once per field at 10% of the cap
- *      (10_000 buckets), throw `GroupCardinalityError` at 100% of
- *      the cap (100_000 buckets).
- *   4. For each bucket, build a per-group reducer state and
- *      step every record in the bucket through it.
- *   5. Emit one result row per bucket, shaped as
- *      `{ [field]: key, ...reduced }`.
- *
- * **Null / undefined keys:** `Map` distinguishes `null` from
- * `undefined`, so records with a missing group field get their own
- * bucket, and records with an explicit `null` value get a separate
- * bucket from that. Consumers who want them merged can coalesce
- * upstream with `.filter()`.
- *
- * **Live mode:** `.groupBy().aggregate().live()` re-runs the full
- * grouping pipeline on every source change. Per-bucket incremental
- * delta maintenance is a future optimization — the reducer
- * protocol's `remove()` hook admits it, but ships naive
- * re-grouping for simplicity.
- *
- * **Type-level stable-key narrowing:** when
- * `dictKey` lands, `groupBy<DictField>()` will narrow the group key
- * type to the stable dictionary key rather than the resolved locale
- * label. That prevents grouping by the locale-resolved label,
- * which would produce different buckets per reader. types the
- * key as `unknown` at the result shape; the dictKey narrowing
- * layers on top without an API break.
- *
- * Partition-awareness seam: when partitioned collections land,
- * per-partition grouping will need to merge sub-results across
- * partitions. The reducer protocol's `{ seed }` parameter
- * (already plumbed through in `reducers.ts`) is the mechanism —
- * groupBy doesn't need its own seam for the moment, because it
- * delegates to the reducer protocol for all per-bucket state.
- */
-
-/**
- * Cardinality thresholds for `.groupBy()`. The warn threshold gives
- * consumers a heads-up before the hard error; the cap is a fixed
- * constant in (not overridable). A `{ maxGroups }` override
- * can be added later without a break if a real consumer asks.
- */
-declare const GROUPBY_WARN_CARDINALITY = 10000;
-declare const GROUPBY_MAX_CARDINALITY = 100000;
-/**
- * Test-only: clear the per-field cardinality warning dedup between
- * tests. Production code never calls this — matching the
- * `resetJoinWarnings` pattern in `join.ts`.
- */
-declare function resetGroupByWarnings(): void;
-/**
- * Result row shape for a grouped aggregation. Each row carries the
- * group key value under the grouping field name plus every reducer
- * output from the spec.
- *
- * types the group key as `unknown` at the result shape — the
- * runtime read via `readPath` can return any value, and narrowing
- * to a specific type would require the caller to assert at the
- * call site. `dictKey` narrowing layers on top of this by
- * adding an overload that constrains `F` when the grouping field
- * is a `dictKey`.
- */
-type GroupedRow<F extends string, R> = {
-    [K in F]: unknown;
-} & R;
-/**
- * Multi-key variant — result-row shape for variadic
- * `.groupBy(...fields)`. Every grouped field name appears on the row
- * (typed as `unknown` for the same reason as `GroupedRow`), plus the
- * reducer outputs from the spec.
- */
-type GroupedRowN<F extends readonly string[], R> = {
-    [K in F[number]]: unknown;
-} & R;
-/**
- * Shared base class for the chainable grouped-query wrappers. Holds
- * the constructor + protected fields that both single-key
- * `GroupedQuery<T, F>` and variadic `GroupedQueryN<T, F>` need; each
- * subclass only overrides `aggregate()` with its own result-row
- * generic.
- *
- * Not exported — implementation detail. Adding `.having()` /
- * `.live()` / `.orderByGroup()` etc. in the future lands here once
- * and both subclasses pick it up automatically.
- *
- * @internal
- */
-declare abstract class GroupedQueryBase {
-    protected readonly executeRecords: () => readonly unknown[];
-    protected readonly upstreams: readonly AggregationUpstream[];
-    /**
-     * Optional dict label resolver attached by the query builder when
-     * the grouping field is a dictKey. Variadic groupings always pass
-     * `undefined` — `<field>Label` projection has no meaningful shape
-     * 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
-     * `groupAndReduce`. For the single-field constructor, this is
-     * `[field]`.
-     */
-    protected readonly fields: readonly string[];
-    constructor(executeRecords: () => readonly unknown[], fieldOrFields: string | readonly string[], upstreams: readonly AggregationUpstream[], 
-    /**
-     * Optional dict label resolver attached by the query builder when
-     * the grouping field is a dictKey. Variadic groupings always pass
-     * `undefined` — `<field>Label` projection has no meaningful shape
-     * for composite keys.
-     */
-    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
- * with `.aggregate(spec)` which returns a `GroupedAggregation`.
- *
- * Kept minimal — the only operation on a grouped query is
- * aggregation. Ordering, limiting, and further filtering belong on
- * the underlying `Query` before `.groupBy()` is called; applying
- * them post-group would be a different operation (`having` /
- * `groupOrderBy`), out of scope for.
- */
-declare class GroupedQuery<T, F extends string> extends GroupedQueryBase {
-    /**
-     * Build a grouped aggregation. Returns a `GroupedAggregation`
-     * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape
-     * as the non-grouped `.aggregate()` wrapper, just with an array
-     * result (one row per bucket) instead of a single reduced object.
-     */
-    aggregate<Spec extends AggregateSpec>(spec: Spec): GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>>;
-}
-/**
- * Variadic-keyed sibling of `GroupedQuery<T, F>`. Constructed by the
- * multi-arg `Query.groupBy(...fields)` overload. The runtime shape is
- * identical — only the type-level result-row narrowing differs.
- */
-declare class GroupedQueryN<T, F extends readonly string[]> extends GroupedQueryBase {
-    aggregate<Spec extends AggregateSpec>(spec: Spec): GroupedAggregation<GroupedRowN<F, AggregateResult<Spec>>>;
-}
-/**
- * Execute the group-and-reduce pipeline. Pure function over a
- * record array and a spec — shared by `GroupedAggregation.run()`
- * and the live-mode refresh path. Exported for tests and for any
- * future `scan().groupBy().aggregate()` reuse.
- *
- * Enforces the cardinality cap incrementally during the partition
- * loop, so a runaway grouping throws at the moment the 100_001st
- * 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, moneyFields?: Record<string, MoneyDescriptor>): R[];
-/**
- * Grouped aggregation wrapper — the `.groupBy(field).aggregate(spec)`
- * terminal. Shape mirrors `Aggregation<R>` from aggregate.ts: two
- * terminals (`.run()` and `.live()`), spec bound at construction
- * time, upstreams collected for live mode.
- *
- * The generic `R` is the per-row result shape (i.e. a single
- * grouped row), and the terminals return `R[]` — one row per
- * bucket.
- */
-declare class GroupedAggregation<R> {
-    private readonly executeRecords;
-    private readonly spec;
-    private readonly upstreams;
-    /**
-     * Optional dict label resolver for `<field>Label` projection
-     *. Present when the grouping field is a dictKey.
-     */
-    private readonly dictLabelResolver?;
-    private readonly fields;
-    constructor(executeRecords: () => readonly unknown[], fields: string | readonly string[], spec: AggregateSpec, upstreams: readonly AggregationUpstream[], 
-    /**
-     * Optional dict label resolver for `<field>Label` projection
-     *. 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.
-     *
-     * `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
-     * `locale` is provided. Returns `R[]` synchronously when
-     * no locale is specified (identical to `.run()`).
-     *
-     * The `<field>Label` field is appended to each row. Rows whose group
-     * key has no dictionary entry get `<field>Label: undefined`.
-     *
-     * Dict-label resolution is single-field only — multi-key groupings
-     * do not produce a `<field>Label`. The resolver is only attached
-     * by the builder when `fields.length === 1`.
-     */
-    runAsync(opts?: {
-        locale?: string;
-        fallback?: string | readonly string[];
-    }): Promise<R[]>;
-    /**
-     * Build a reactive `LiveAggregation<R[]>` that re-runs the full
-     * group-and-reduce pipeline whenever any upstream source notifies
-     * of a change. Same error-isolation and idempotent-stop contract
-     * as `Aggregation.live()` — the implementation delegates to the
-     * same `LiveAggregationImpl` class by threading a fresh
-     * recompute closure through the existing constructor.
-     *
-     * uses naive full re-run on every change. Incremental
-     * per-bucket maintenance (apply `step` on inserted records,
-     * `remove` on deleted records, route by bucket key) is a future
-     * optimization — the reducer protocol admits it, but wiring
-     * delta-aware source subscriptions is a separate PR.
-     *
-     * Always call `live.stop()` when finished.
-     */
-    live(): LiveAggregation<R[]>;
-}
-
-/**
- * Strategy seam between the core Query / ScanBuilder chain and the
- * optional aggregate / groupBy subsystem. Core imports
- * `AggregateStrategy` as a TYPE-ONLY symbol and `NO_AGGREGATE` as a
- * tiny runtime stub.
- *
- * The heavy machinery — `Aggregation`, `GroupedQuery`, the
- * reducer-step logic — is only reachable from `withAggregate()` in
- * `./active.ts`, which is only exported through the
- * `@noy-db/hub/aggregate` subpath. Consumers that don't import the
- * subpath ship none of the ~886 LOC.
- *
- * @internal
- */
-
-/**
- * Seam interface. `@internal` — will promote to public only when the
- * aggregate subsystem is extracted into its own package.
- *
- * @internal
- */
-interface AggregateStrategy {
-    /**
-     * Build an `Aggregation<R>` for `Query.aggregate(spec)`. `executeRecords`
-     * is a closure that produces the matching record set when the
-     * aggregation runs. NO_AGGREGATE throws; the active strategy
-     * constructs a real `Aggregation`.
-     */
-    aggregate<Spec extends AggregateSpec>(executeRecords: () => readonly unknown[], spec: Spec, upstreams: readonly AggregationUpstream[]): Aggregation<AggregateResult<Spec>>;
-    /**
-     * 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>, 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[], moneyFields?: Record<string, MoneyDescriptor>): GroupedQueryN<T, F>;
-    /**
-     * Terminal streaming aggregator for `ScanBuilder.aggregate(spec)`.
-     * Takes an async iterable of decrypted records + the spec and
-     * returns the reduced result.
-     */
-    scanAggregate<Spec extends AggregateSpec>(iter: AsyncIterable<unknown>, spec: Spec): Promise<AggregateResult<Spec>>;
-}
-
-export { type AggregateStrategy as A, buildLiveAggregation as B, count as C, groupAndReduce as D, max as E, min as F, GROUPBY_MAX_CARDINALITY as G, reduceRecords as H, type I18nMap as I, resetGroupByWarnings as J, sum as K, type Layer as L, type RoundingMode as M, MoneyCurrencyError as N, type OnMissing as O, type MoneyDescriptor as P, type MoneyOptions as Q, type ResolveI18nOptions as R, type MoneyOptionsFixed as S, type MoneyOptionsMulti as T, MoneyPrecisionError as U, MoneyUnsupportedError as V, isMoneyDescriptor as W, money as X, type I18nTextDescriptor as a, type I18nTextOptions as b, type OnMissingPolicy as c, applyI18nLocale as d, isI18nTextDescriptor as e, resolvePolicy as f, getAtPath as g, stripI18nFilled as h, i18nText as i, type AggregateResult as j, type AggregateSpec as k, Aggregation as l, type AggregationUpstream as m, GROUPBY_WARN_CARDINALITY as n, GroupedAggregation as o, GroupedQuery as p, GroupedQueryN as q, resolveI18nText as r, setAtPathInPlace as s, type GroupedRow as t, type GroupedRowN as u, validateI18nTextValue as v, type LiveAggregation as w, type Reducer as x, type ReducerOptions as y, avg as z };