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

package/dist/with-formula/overlay-views/virtual-collection.d.ts

@@ -0,0 +1,90 @@
+import type { Collection } from '../../kernel/collection.js';
+import type { OverlayedViewStrategy } from './types.js';
+/**
+ * Virtual-collection proxy returned by `vault.collection(overlayName)`
+ * when `overlayName` is a registered `withOverlayedView`.
+ *
+ * Implements the core `Collection<T>`-shaped read/write surface with
+ * merge-on-read semantics:
+ *   - `get(id)`: overlay row wins iff `overlay[shadowField] === shadowValue`;
+ *     when `spec.mergeMode` is set, an intermediate status may instead pull
+ *     a declared subset of fields from the overlay over the base
+ *   - `list()` / `.query()`: union of ids, per-id merge applied
+ *   - `put(record)` / `put(id, record)`: routes to overlay; id derived
+ *     via the base MV's `rowKey` (validated on the two-arg form)
+ *   - `delete(id)`: removes the overlay row only; base stays
+ *
+ * Reactive APIs (`live`, `subscribe`, `query().live()`) are out of
+ * scope for this release and surface as "not yet implemented" — wired in a
+ * future sub-issue.
+ */
+export declare class OverlayedCollection<T extends Record<string, unknown> = any> {
+    private readonly spec;
+    private readonly baseCollection;
+    private readonly overlayCollection;
+    private readonly baseRowKey;
+    constructor(spec: OverlayedViewStrategy, baseCollection: Collection<T>, overlayCollection: Collection<T>, baseRowKey: ((row: Record<string, unknown>) => string) | undefined);
+    /**
+     * Convenience accessors for advanced callers that need to bypass the
+     * virtual layer (bulk imports, direct overlay queries). Mirrors the
+     * spec's "direct writes to the underlying overlay collection skip
+     * the validation" escape hatch.
+     */
+    readonly overlay: {
+        rowKey: (row: Record<string, unknown>) => string;
+    };
+    /** Get the merged row by id. */
+    get(id: string): Promise<T | null>;
+    /** List union of base + overlay ids, applying the merge per row. */
+    list(): Promise<T[]>;
+    /**
+     * Write to the overlay. Two forms:
+     * - `put(record)`: id is derived via the base MV's `rowKey(record)`.
+     *   Throws if the base isn't an MV.
+     * - `put(id, record)`: validates `id === rowKey(record)`; throws
+     *   `OverlayIdMismatchError` on mismatch.
+     */
+    put(idOrRecord: string | T, maybeRecord?: T): Promise<void>;
+    /**
+     * Remove the overlay row only. Idempotent (no-op on absent).
+     * The base row is untouched — if a base row exists for `id`,
+     * subsequent reads return it.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Merge a single id's overlay + base rows into the visible row.
+     *
+     * Priority (first match wins):
+     *  1. Binary shadow win — overlay present AND
+     *     `overlay[shadowField] === shadowValue` → return the overlay row
+     *     entirely. This stays FIRST so the original binary behaviour is
+     *     unchanged whether or not `mergeMode` is configured.
+     *  2. Field-level merge — overlay present, `mergeMode` configured,
+     *     and a rule whose `whenStatus` equals `overlay[shadowField]`.
+     *     The matched rule pulls its `overlayFields` (those present on
+     *     the overlay row) on top of the base row. With no base row, the
+     *     overlay row is returned as-is.
+     *  3. Fallback — return the base row (possibly `null`). An
+     *     overlay-only row that qualifies under neither (1) nor (2) and
+     *     has no base is therefore NOT surfaced.
+     */
+    private mergeRows;
+    /** @throws — chainable Query<T> over a virtual collection is deferred. */
+    query(): never;
+    /** @throws — change-stream subscription over a virtual collection is deferred. */
+    subscribe(): never;
+    /** @throws — live query over a virtual collection is deferred. */
+    live(): never;
+    /** @throws — async iteration over a virtual collection is deferred. */
+    scan(): never;
+    /** @throws — lazy-mode query is not applicable to virtual collections. */
+    lazyQuery(): never;
+    /** @throws — bulk-atomic put is deferred to a future MV sub-issue. */
+    putManyAtomic(): never;
+    /** @throws — bulk delete is deferred to a future MV sub-issue. */
+    deleteMany(): never;
+    /** @throws — `.first()` over a virtual collection is deferred. */
+    first(): never;
+    /** @throws — `.count()` over a virtual collection is deferred. */
+    count(): never;
+}

package/dist/with-formula/overlay-views/with-overlayed-view.d.ts

@@ -0,0 +1,9 @@
+import type { OverlayedViewStrategy, OverlayedViewStrategyHandle } from './types.js';
+/**
+ * Register a read-shadow overlay: bind an MV-owned base collection to
+ * a user-writable overlay so consumers can express operator-editable
+ * lifecycles as one declarative block.
+ *
+ * See docs/superpowers/specs/2026-05-20-dim14-mv-v2-design.md.
+ */
+export declare function withOverlayedView(spec: OverlayedViewStrategy): OverlayedViewStrategyHandle;

package/dist/with-lookup/aggregate/active.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Active aggregate strategy factory. Calling `withAggregate()` returns
+ * an `AggregateStrategy` whose methods construct real `Aggregation` /
+ * `GroupedQuery` instances and run the streaming reducer protocol.
+ *
+ * This module is only reachable through the `@noy-db/hub/aggregate`
+ * subpath — a consumer that never imports the subpath ships none of
+ * this (ESM tree-shaking + hub's `"sideEffects": false`).
+ */
+import type { AggregateStrategy } from './strategy.js';
+/**
+ * Build the default aggregate strategy. Pass into
+ * `createNoydb({ aggregateStrategy: withAggregate() })` to light up
+ * `.aggregate()` and `.groupBy()` on `Query` and `ScanBuilder`.
+ *
+ * @example
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withAggregate, sum, count } from '@noy-db/hub/aggregate'
+ *
+ * const db = await createNoydb({
+ *   store, user, secret,
+ *   aggregateStrategy: withAggregate(),
+ * })
+ *
+ * const totals = invoices.query()
+ *   .where('status', '==', 'paid')
+ *   .groupBy('clientId')
+ *   .aggregate({ amount: sum('amount'), n: count() })
+ *   .run()
+ * ```
+ */
+export declare function withAggregate(): AggregateStrategy;

package/dist/with-lookup/aggregate/aggregation.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+import type { Reducer } from './reducers.js';
+/**
+ * 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'),
+ * }
+ * ```
+ */
+export 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`.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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()`.
+ */
+export declare function buildLiveAggregation<V>(recompute: () => V, upstreams: readonly AggregationUpstream[]): LiveAggregation<V>;

package/dist/with-lookup/aggregate/canonical-key.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonicalise a group-key tuple to a stable string for dedup hashing.
+ *
+ * Sorts field names lexicographically before serialising, so that
+ * `.groupBy('a', 'b')` and `.groupBy('b', 'a')` produce identical
+ * keys for the same logical group. Values are JSON-stringified;
+ * `undefined` and `null` are distinguished (matching the Map-key
+ * semantics in `groupAndReduce`).
+ *
+ * NOT part of the public API. Used by:
+ *   - `groupAndReduce` for the dedup Map's key
+ *   - `materialized-views/query-hash` for UNION MV cross-arm row-key dedup (PR 2)
+ *
+ * Pure: same input → same output, no side effects.
+ */
+export declare function canonicalGroupKey(fields: readonly string[], row: Record<string, unknown>): string;

package/dist/with-lookup/aggregate/groupby.d.ts

@@ -0,0 +1,280 @@
+/**
+ * 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.
+ */
+import type { AggregateSpec, AggregateResult, AggregationUpstream, LiveAggregation } from './aggregation.js';
+import type { ReducerBuilder } from './reducers.js';
+import type { MoneyDescriptor } from '../../via/money/descriptor.js';
+import type { ViaPipeline } from '../../kernel/via/pipeline.js';
+import { type I18nTextDescriptor } from '../../via/i18n/core.js';
+/**
+ * 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.
+ */
+export declare const GROUPBY_WARN_CARDINALITY = 10000;
+export 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`.
+ */
+export 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`.
+ */
+export 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.
+ */
+export 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;
+    /**
+     * The backing collection's compiled Via pipeline — used to rewrite
+     * `sum`/`min`/`max` over Via-covered fields (e.g. money) into exact
+     * BigInt reducers when `.aggregate(spec)` is terminated.
+     */
+    protected readonly via?: ViaPipeline | 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, 
+    /**
+     * The backing collection's compiled Via pipeline — used to rewrite
+     * `sum`/`min`/`max` over Via-covered fields (e.g. money) into exact
+     * BigInt reducers when `.aggregate(spec)` is terminated.
+     */
+    via?: ViaPipeline | undefined);
+    /** Apply Via-aware reducer rewriting (e.g. money) when the source declares one. */
+    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.
+ */
+export declare class GroupedQuery<T, F extends string, S extends keyof T = never, M extends keyof T & string = never> 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.
+     *
+     * The builder overload `aggregate(b => spec)` types `b` as
+     * `ReducerBuilder<T, S, M>`, so field-taking reducers (`sum`, `avg`,
+     * `min`, `max`) refuse any field listed in the collection's
+     * `sensitive` option at compile time, and `sum`/`min`/`max` over a
+     * declared `moneyFields` (`M`) member return a `MoneyString`. The
+     * bare-spec overload is preserved for backward compatibility.
+     */
+    aggregate<Spec extends AggregateSpec>(spec: Spec): GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>>;
+    aggregate<Spec extends AggregateSpec>(build: (b: ReducerBuilder<T, S, M>) => 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.
+ */
+export declare class GroupedQueryN<T, F extends readonly string[], S extends keyof T = never, M extends keyof T & string = never> extends GroupedQueryBase {
+    aggregate<Spec extends AggregateSpec>(spec: Spec): GroupedAggregation<GroupedRowN<F, AggregateResult<Spec>>>;
+    aggregate<Spec extends AggregateSpec>(build: (b: ReducerBuilder<T, S, M>) => 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.
+ */
+export 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.
+ */
+export 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` (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[]>;
+}
+export {};

package/dist/with-lookup/aggregate/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @noy-db/hub/aggregate — opt-in aggregation + groupBy service.
+ *
+ * @category capability
+ *
+ * Groups every file whose reason-for-existing is record reduction:
+ *   - `aggregation` (`Aggregation<R>`, `reduceRecords`, `buildLiveAggregation`)
+ *   - `groupby` (`GroupedQuery`, `GroupedAggregation`, cardinality guards)
+ *   - `reducers` (`count`, `sum`, `avg`, `min`, `max` factories)
+ *
+ * The root barrel (`@noy-db/hub`) and the `@noy-db/hub/query` subpath
+ * continue to re-export the same symbols for backward compatibility
+ * with consumers written before the relocation. New code should
+ * prefer this subpath.
+ */
+export { withAggregate } from './active.js';
+export type { AggregateStrategy } from './strategy.js';
+export { Aggregation, reduceRecords, buildLiveAggregation } from './aggregation.js';
+export type { AggregateSpec, AggregateResult, AggregationUpstream, LiveAggregation, } from './aggregation.js';
+export { GroupedQuery, GroupedQueryN, GroupedAggregation, groupAndReduce, resetGroupByWarnings, GROUPBY_WARN_CARDINALITY, GROUPBY_MAX_CARDINALITY, } from './groupby.js';
+export type { GroupedRow, GroupedRowN } from './groupby.js';
+export { count, sum, avg, min, max, moneySum, moneyMin, moneyMax, reducerBuilder } from './reducers.js';
+export type { Reducer, ReducerOptions, ReducerBuilder } from './reducers.js';