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

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';

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

@@ -0,0 +1,257 @@
+/**
+ * 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.
+ */
+import type { MoneyString } from '../../via/money/branded.js';
+import type { QueryField } from '../../kernel/types.js';
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ *
+ * KNOWN LIMITATION (type imprecision): the declared result type is `number`,
+ * but when `field` is a **money** field the runtime returns a decimal *string*
+ * (e.g. `'0.30'`, or `{ EUR: '0.30' }` in multi-currency mode) — money sums are
+ * BigInt-exact in scaled space and never collapse to a float. The `number` type
+ * is therefore a lie for money fields; narrow the result yourself at the call
+ * site. A precise fix requires threading money-field declarations into the type
+ * system (tracked separately).
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function max(field: string, opts?: ReducerOptions<number>): Reducer<number | null, MinMaxState>;
+/**
+ * `sum()` for a **declared money field**, typed to match the runtime.
+ *
+ * `sum()` returns `Reducer<number>`, but `wrapMoneyReducers` (applied at
+ * `query.aggregate()` time, once `moneyFields` is known) rewrites any
+ * `sum`/`min`/`max` over a money field to a money reducer that finalizes to a
+ * `MoneyString` decimal — so the `number` type is a lie for money fields and
+ * consumers need a cast at every read site. `moneySum` is the same reducer with
+ * the correct `Reducer<MoneyString>` return type, so no read-site cast is
+ * needed. It is the caller's assertion that `field` is a money field; use plain
+ * `sum()` for non-money fields. (For a multi-currency money field WITHOUT
+ * `convertTo`, the runtime returns a per-currency `Record<string, MoneyString>`
+ * rather than a single `MoneyString` — pass `convertTo` to collapse to one
+ * currency, or read the map at the boundary.)
+ */
+export declare function moneySum(field: string, opts?: ReducerOptions<number>): Reducer<MoneyString>;
+/**
+ * `min()` for a declared money field, typed `Reducer<MoneyString | null>`
+ * (null on an empty result set in fixed-currency mode, mirroring `min()`). See
+ * {@link moneySum} for the late-binding rewrite. Note: `convertTo`/`fx` on
+ * `opts` have no effect on min/max (cross-currency min/max is unsupported — use
+ * {@link moneySum} for currency conversion). In multi-currency mode the runtime
+ * returns a per-currency map and an empty result is `{}` rather than `null`.
+ */
+export declare function moneyMin(field: string, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+/**
+ * `max()` for a declared money field, typed `Reducer<MoneyString | null>`
+ * (null on an empty result set in fixed-currency mode, mirroring `max()`). See
+ * {@link moneyMin} for the `convertTo`/`fx` and multi-currency caveats.
+ */
+export declare function moneyMax(field: string, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+/**
+ * Typed builder passed to the `aggregate(b => spec)` overload.
+ *
+ * Each field-taking method narrows `field` to `QueryField<T, S>`, which
+ * excludes any field listed in the collection's `sensitive` option at
+ * compile time. `count()` carries no field argument and is always allowed.
+ *
+ * The type parameters match the `Query<T, S>` they come from:
+ *   - `T` — the record type of the collection
+ *   - `S` — the union of sensitive field keys (defaults to `never`)
+ *
+ * ONE shared runtime instance (`reducerBuilder`) serves all `T`/`S`
+ * combinations — the field narrowing is type-only; the methods delegate
+ * directly to the standalone factories.
+ */
+export interface ReducerBuilder<T, S extends keyof T = never, M extends keyof T & string = never> {
+    count(opts?: ReducerOptions<number>): Reducer<number>;
+    sum<F extends QueryField<T, S>>(field: F, opts?: ReducerOptions<number>): [F] extends [M] ? Reducer<MoneyString> : Reducer<number>;
+    avg(field: QueryField<T, S>, opts?: ReducerOptions<{
+        sum: number;
+        count: number;
+    }>): ReturnType<typeof avg>;
+    min<F extends QueryField<T, S>>(field: F, opts?: ReducerOptions<number>): [F] extends [M] ? Reducer<MoneyString | null> : ReturnType<typeof min>;
+    max<F extends QueryField<T, S>>(field: F, opts?: ReducerOptions<number>): [F] extends [M] ? Reducer<MoneyString | null> : ReturnType<typeof max>;
+    moneySum(field: QueryField<T, S>, opts?: ReducerOptions<number>): Reducer<MoneyString>;
+    moneyMin(field: QueryField<T, S>, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+    moneyMax(field: QueryField<T, S>, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+}
+/**
+ * Shared runtime instance for the `aggregate(b => spec)` builder form.
+ *
+ * The field-narrowing to `QueryField<T, S>` is type-only — each method
+ * delegates directly to its standalone factory. A `(field: string) => R`
+ * factory is assignable to a `(field: QueryField<T,S>) => R` method by
+ * parameter-contravariance, so this single instance works for all `T`/`S`.
+ */
+export declare const reducerBuilder: ReducerBuilder<Record<string, unknown>>;
+export {};

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

@@ -0,0 +1,59 @@
+/**
+ * Strategy seam between the core Query / ScanBuilder chain and the
+ * optional aggregate / groupBy service. 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
+ */
+import type { Aggregation, AggregateSpec, AggregateResult, AggregationUpstream } from './aggregation.js';
+import type { GroupedQuery, GroupedQueryN } from './groupby.js';
+import type { ViaPipeline } from '../../kernel/via/pipeline.js';
+/**
+ * Seam interface. `@internal` — will promote to public only when the
+ * aggregate service is extracted into its own package.
+ *
+ * @internal
+ */
+export 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, S>` for `Query.groupBy(field)`. Same
+     * closure / upstream inputs as `aggregate` plus the group key field.
+     */
+    groupBy<T, F extends string, S extends keyof T = never, M extends keyof T & string = never>(executeRecords: () => readonly unknown[], field: F, upstreams: readonly AggregationUpstream[], dictLabelResolver?: (key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>, via?: ViaPipeline): GroupedQuery<T, F, S, M>;
+    /**
+     * Variadic-keyed sibling — builds a `GroupedQueryN<T, F, S>` 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[], S extends keyof T = never, M extends keyof T & string = never>(executeRecords: () => readonly unknown[], fields: F, upstreams: readonly AggregationUpstream[], via?: ViaPipeline): GroupedQueryN<T, F, S, M>;
+    /**
+     * 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>>;
+}
+/**
+ * No-aggregate stub. Every `.aggregate()` / `.groupBy()` / streaming
+ * `scan().aggregate()` call throws with a pointer at the subpath. The
+ * real `Aggregation` / `GroupedQuery` classes are never referenced at
+ * runtime, so the bundler drops the ~886 LOC.
+ *
+ * @internal
+ */
+export declare const NO_AGGREGATE: AggregateStrategy;

package/dist/with-lookup/embeddings/cosine.d.ts

@@ -0,0 +1,2 @@
+/** Cosine similarity in [-1,1]; 0 on zero-norm or length mismatch (no NaN). (L2) */
+export declare function cosine(a: Float32Array | number[], b: Float32Array | number[]): number;

package/dist/with-lookup/embeddings/descriptor.d.ts

@@ -0,0 +1,8 @@
+export interface EmbeddingDescriptor {
+    readonly source: string | readonly string[];
+    readonly encode: (text: string) => Promise<Float32Array>;
+    readonly dim: number;
+    readonly model: string;
+}
+/** Concatenate the record's source-field text (skips empties; supports nested/[]-wildcard paths). */
+export declare function embeddingSourceText(record: Record<string, unknown>, source: string | readonly string[]): string;

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

@@ -0,0 +1,4 @@
+export { cosine } from './cosine.js';
+export { embeddingSourceText, type EmbeddingDescriptor } from './descriptor.js';
+export { VectorSet, type StoredVector, type VectorHit } from './vector-set.js';
+export { encodeVecId } from './vec-id.js';