@noy-db/hub 0.2.0-pre.16 → 0.2.0-pre.18

package/dist/strategy-Diwh5lzS.d.ts

@@ -0,0 +1,739 @@
+import { N as NoydbError } from './errors-DUTlAt3Y.js';
+
+/**
+ * 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;
+
+/**
+ * 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. */
+    run(): 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, MoneyUnsupportedError as B, isMoneyDescriptor as C, money as D, GROUPBY_MAX_CARDINALITY as G, type LiveAggregation as L, MoneyCurrencyError as M, 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, type RoundingMode as u, type MoneyDescriptor as v, type MoneyOptions as w, type MoneyOptionsFixed as x, type MoneyOptionsMulti as y, MoneyPrecisionError as z };