@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/kernel/query/reduce/date-trunc.d.ts

@@ -0,0 +1,75 @@
+/** Calendar units `dateTrunc()` can bucket into. */
+export type DateTruncUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** Accepted week-start conventions. Default is `'monday'` (ISO-8601). */
+export type WeekStart = 'monday' | 'sunday';
+/**
+ * A derived group key: "bucket `field` to the start of its `unit`, in
+ * `timeZone`". Opaque to consumers — build it with {@link dateTrunc}.
+ */
+export interface DateTruncKey {
+    readonly __dateTrunc: true;
+    /** Source field (a `readPath` path — dots address nested values). */
+    readonly field: string;
+    readonly unit: DateTruncUnit;
+    /** IANA zone name. Always explicit; validated at construction. */
+    readonly timeZone: string;
+    readonly weekStartsOn: WeekStart;
+    /** Output key the bucket is stamped under on each result row. */
+    readonly as: string;
+}
+/** Either a plain field name or a derived calendar key. */
+export type GroupKey = string | DateTruncKey;
+export interface DateTruncOptions {
+    /**
+     * IANA timezone the calendar is read in — REQUIRED. See the module note:
+     * there is no safe default, so there is no default.
+     *
+     * It applies to values that ARE instants. A zoneless calendar string
+     * (`'2026-01-01'`, `'2026-01-01T08:30'`) has no instant to convert and is
+     * bucketed as written regardless of what is passed here (#1410).
+     */
+    timeZone: string;
+    /** Week-start convention for `unit: 'week'`. Default `'monday'`. */
+    weekStartsOn?: WeekStart;
+    /**
+     * Output key. Defaults to `<field>_<unit>` with dots flattened to
+     * underscores, so a nested source path cannot produce an output key that
+     * `readPath` would then re-interpret as a path.
+     */
+    as?: string;
+}
+/**
+ * Declare a calendar-bucketed group key. Composable with plain field names in
+ * a multi-key `.groupBy(...)`.
+ */
+export declare function dateTrunc(field: string, unit: DateTruncUnit, options: DateTruncOptions): DateTruncKey;
+/** Runtime discriminator — a `DateTruncKey` vs a plain field name. */
+export declare function isDateTruncKey(value: unknown): value is DateTruncKey;
+/** Output key a group key stamps on the result row. */
+export declare function groupKeyName(key: GroupKey): string;
+/**
+ * Source field a group key READS. Differs from {@link groupKeyName} only for a
+ * derived key — guards that ask "is this field stored?" want this one.
+ */
+export declare function groupKeySourceField(key: GroupKey): string;
+/**
+ * Canonical, stable description of a group key for hashing. Every parameter
+ * that changes which bucket a row lands in appears here, so declaring,
+ * removing, or re-parameterising a derived key bumps an MV's `queryHash`.
+ * Pipe-separated so a description can never be confused with the
+ * comma-separated field list it sits inside.
+ */
+export declare function describeGroupKey(key: GroupKey): string;
+/**
+ * Truncate one value to its bucket. `null` / `undefined` pass through
+ * unchanged so the existing null-vs-undefined bucket semantics of
+ * `groupAndReduce` still apply. Anything else that is not a timestamp is
+ * REFUSED rather than bucketed under a wrong-but-plausible key.
+ */
+export declare function truncateDate(value: unknown, key: DateTruncKey): string | null | undefined;
+/**
+ * Stamp each derived key's bucket onto a shallow copy of every row, so the
+ * downstream grouping pipeline sees an ordinary stored field. Input rows are
+ * never mutated.
+ */
+export declare function projectDateTruncKeys<R>(rows: readonly R[], keys: readonly DateTruncKey[]): R[];

package/dist/kernel/query/reduce/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@noy-db/hub/query/reduce` — **the Reduce group of the query DSL.**
+ *
+ * ```ts
+ * import '@noy-db/hub/query/reduce'   // once, in your app's entry
+ *
+ * invoices.query()
+ *   .where('status', '==', 'paid')
+ *   .groupBy(dateTrunc('date', 'month'))
+ *   .aggregate({ total: sum('amount') })
+ * ```
+ *
+ * ⭐ **Imported for its side effect** — it patches `aggregate`, `groupBy`,
+ * `window` and `distinct` onto `Query.prototype` AND onto
+ * `ScanBuilder.prototype`, and merges their types into both. See
+ * `../relate/index.ts` for the full note on `package.json`'s `sideEffects`.
+ *
+ * ⚠️ **The methods, not the ENGINE.** `withReduce()` (`@noy-db/hub/reduce`) is
+ * still the strategy that makes them do anything: without it the chain
+ * compiles, the method exists, and the call throws the "aggregate is not
+ * enabled" error from `NO_REDUCE`. Two different opt-ins, deliberately — one
+ * decides whether the code ships, the other whether the service is on.
+ */
+import type { ReduceSurface } from './methods.js';
+import type { ScanReduceSurface } from './scan-methods.js';
+declare module '../builder.js' {
+    interface Query<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> extends ReduceSurface<T, S, Q, M> {
+    }
+}
+declare module '../scan-builder.js' {
+    interface ScanBuilder<T, S extends keyof T = never, M extends keyof T & string = never> extends ScanReduceSurface<T, S, M> {
+    }
+}
+export { dateTrunc, isDateTruncKey, truncateDate } from './date-trunc.js';
+export type { DateTruncKey, DateTruncUnit, DateTruncOptions, WeekStart, GroupKey } from './date-trunc.js';
+export { GroupCardinalityError } from '../../errors.js';

package/dist/kernel/query/reduce/install.d.ts

@@ -0,0 +1,2 @@
+/** Idempotent: the root barrel and the subpath entry both call it. */
+export declare function installReduce(): void;

package/dist/kernel/query/reduce/methods.d.ts

@@ -0,0 +1,259 @@
+/**
+ * #1458 — **Reduce**: a fold over a result set.
+ *
+ * `aggregate` · `groupBy` · `window` · `distinct`
+ *
+ * Bodies moved out of `kernel/query/builder.ts` unchanged; see
+ * `../relate/methods.ts` for why `this.plan` still resolves.
+ *
+ * ⚠️ This group depends on TWO others, and both edges are real rather than
+ * tidyable:
+ *   - **Live**, for `incrementalMaintainer` — a live reduction maintains its
+ *     state through Live's maintainer (see `../internal/maintenance.ts`);
+ *   - **Relate**, for `reduceViaFor` / `refuseAliasReduceVia` — a reducer over
+ *     a JOIN ALIAS has to resolve the right side's Via pipeline, and refusing
+ *     it correctly is #1338's whole subject.
+ * Neither is a layering accident: both are what "reduce over a joined, live
+ * result" means.
+ */
+import type { DeclaredPredicate, InternalSource, QueryPlan } from '../builder.js';
+import type { QueryField } from '../../types.js';
+import type { ViaPipeline } from '../../via/pipeline.js';
+import type { JoinContext } from '../relate/join.js';
+import type { DateTruncKey } from './date-trunc.js';
+import type { LiveMaintainer, GroupMaintenanceSource } from '../live/incremental.js';
+import type { ReduceSpec, ReduceResult, Reduction } from '../../../with-lookup/reduce/reduction.js';
+import type { ReducerBuilder } from '../../../with-lookup/reduce/reducers.js';
+import type { GroupedQuery, GroupedQueryN } from '../../../with-lookup/reduce/groupby.js';
+import type { ReduceStrategy, WindowSpec, WindowedQuery } from '../../../with-lookup/reduce/strategy.js';
+/** @internal — the mixin whose prototype `./index.ts` copies onto `Query`. */
+export declare class ReduceMethods<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> {
+    protected readonly source: InternalSource;
+    protected readonly plan: QueryPlan;
+    protected readonly joinContext: JoinContext | undefined;
+    protected readonly reduceStrategy: ReduceStrategy;
+    protected readonly predicates: ReadonlyMap<string, DeclaredPredicate> | undefined;
+    protected matchedRecords: (terminal: string, forceJoins?: boolean) => readonly unknown[];
+    protected decodeVia: (records: readonly unknown[], locale?: string) => unknown[];
+    protected aliasVia: () => ReadonlyMap<string, ViaPipeline> | undefined;
+    protected incrementalMaintainer: (mode: 'rows' | 'records') => LiveMaintainer | undefined;
+    protected groupMaintenance: (derived: readonly DateTruncKey[]) => GroupMaintenanceSource | undefined;
+    toArray: (opts?: {
+        locale?: string;
+    }) => T[];
+    /**
+     * The right-side change streams a joined query has to merge (#1338), deduped
+     * by target the way `live()` does — a chain joining the same collection
+     * twice must not double-fire. Extracted so a joined REDUCTION and a joined
+     * live query cannot disagree on what "the sources of this result" means.
+     */
+    private rightSideUpstreams;
+    /**
+     * Every alias this plan can produce, pipeline or not (#1338).
+     *
+     * `aliasVia()` above holds only the aliases whose collection compiles a Via
+     * pipeline; refusal has to know about ALL of them, or an aliased reducer
+     * over a plain right-side collection stays silent.
+     */
+    private aliasNames;
+    /** Is `field` rooted at an alias this plan produces? */
+    private addressesAlias;
+    /**
+     * The distinct values of `field` across the match set (#1347) — the
+     * declarative form of `new Set(q.toArray().map(r => r[field]))`, which is
+     * what consumers write today and which is wrong in two ways this is not.
+     *
+     * **Distinctness is decided on the canonical index key, not on the value
+     * you get back.** For a Via-covered field that is the difference between a
+     * right answer and a plausible one: money stores a scaled integer, and a
+     * row written before the field was declared can spell it non-canonically
+     * (`'0100'` for `'100'`). Deduping the stored strings reports two values
+     * where there is one; deduping the FORMATTED strings makes the answer
+     * depend on a locale this layer does not have (`'10.00'` vs `'10,00'`).
+     * See `distinct-key.ts`. The values RETURNED are the decoded ones, so they
+     * match what `toArray()` hands back for the same field.
+     *
+     * **Nullish values are excluded** — `null`/`undefined`/missing is the
+     * absence of a value, not a distinct one. That is also the only choice
+     * under which the index-backed and scanned paths can agree, since the hash
+     * index does not hold nullish keys; see `distinctKeyOf`.
+     *
+     * Same match set as `count()`: where/filter apply, orderBy/limit/offset do
+     * not. Values come back in first-encountered order.
+     *
+     * ⭐ INDEX-BACKED when the field carries a hash index AND the plan narrows
+     * nothing — the buckets ARE the distinct key set, so the answer costs
+     * O(distinct values) instead of O(records) and never decrypts a snapshot.
+     * The guard is deliberately all-or-nothing: with a where clause the whole
+     * collection's buckets are not the answer, and intersecting a candidate id
+     * set with every bucket would cost more than the scan it replaced.
+     *
+     * ⛔ THE RETURN TYPE IS `(T & Record<F, unknown>)[F][]`, NOT
+     * `F extends keyof T ? T[F][] : unknown[]` — and it must stay that way. The
+     * conditional form reads better and type-checks at every call site, but a
+     * DEFERRED conditional over `T` makes TypeScript give up relating
+     * `Query<T>` to `Query<unknown>`, which makes `Collection<T>` invariant in
+     * `T`, which breaks `vault.ts`'s `Map<string, Collection<unknown>>` cache
+     * with four errors that name neither this method nor this file. The
+     * intersection form resolves to the same thing (`T[F]` for a literal key,
+     * `unknown` for a `string`-typed one) and stays covariant.
+     */
+    distinct<F extends QueryField<T, S>>(field: F): (T & Record<F, unknown>)[F][];
+    /**
+     * Reduce the matching records through a named set of reducers.
+     * the aggregation terminal.
+     *
+     * ```ts
+     * const { total, n, avgAmount } = invoices.query()
+     *   .where('status', '==', 'open')
+     *   .aggregate({
+     *     total:     sum('amount'),
+     *     n:         count(),
+     *     avgAmount: avg('amount'),
+     *   })
+     *   .run()
+     * ```
+     *
+     * Returns an `Reduction<R>` wrapper with two terminals:
+     *   - `.run(): R` — synchronous one-shot reduction
+     *   - `.live(): LiveReduction<R>` — reactive primitive that
+     *     re-runs the reduction whenever the source notifies of a
+     *     change. Always call `live.stop()` when finished.
+     *
+     * The reducer spec is bound here once and reused by both
+     * terminals — this is why `.aggregate()` returns a wrapper instead
+     * of being a direct terminal. Consumers who only need the static
+     * value read `.run()`; consumers wiring a reactive UI read
+     * `.live()`.
+     *
+     * Joins are NOT applied by default — the same logic as `.count()`. A leg is
+     * projection-only, so running one just to throw the alias away would be
+     * wasteful. ⭐ **The exception is a reducer that ADDRESSES an alias**
+     * (#1338): then the joined relation IS what is being reduced, so the legs
+     * run and the reducer is rewritten by the right collection's own Via
+     * pipeline — money stays exact, and the right side's `queryable: 'none'`
+     * posture refuses a field it would refuse locally. A live joined
+     * aggregation also merges every right-side change stream, so it does not
+     * quietly stop updating when the right side moves.
+     *
+     * Every reducer factory accepts an optional `{ seed }` parameter
+     * that is plumbed through the protocol but unused by the
+     * executor — that's  constraint #2. When partition-aware
+     * aggregation lands, the seed will carry running state across
+     * partition boundaries without an API break.
+     *
+     * KNOWN GAP (sealed fields, bare-spec form): `where`/`orderBy`/`groupBy`
+     * refuse a `sensitive` field at compile time, but a reducer over a sensitive
+     * field in the BARE-SPEC form (e.g. `aggregate({ x: sum('ssn') })`) is NOT
+     * refused — the reducer factories (`sum`/`min`/`max`/…) are standalone
+     * `(field: string)` functions with no collection-type context. This form is
+     * preserved as-is for backward compatibility.
+     *
+     * The BUILDER form closes this gap: `aggregate(b => ({ x: b.sum('field') }))`
+     * types the builder's field parameter as `QueryField<T, S>`, refusing any
+     * `sensitive` field at compile time. Use the builder form for new code that
+     * aggregates over a collection with sensitive fields.
+     *
+     */
+    aggregate<Spec extends ReduceSpec>(spec: Spec): Reduction<ReduceResult<Spec>>;
+    aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): Reduction<ReduceResult<Spec>>;
+    /**
+     * Partition matching records into buckets keyed by a field, then
+     * terminate with `.aggregate(spec)` to compute per-bucket
+     * reducers..
+     *
+     * ```ts
+     * const byClient = invoices.query()
+     *   .where('status', '==', 'open')
+     *   .groupBy('clientId')
+     *   .aggregate({ total: sum('amount'), n: count() })
+     *   .run()
+     * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
+     * ```
+     *
+     * Result rows carry the group key value under the grouping field
+     * name plus every reducer output from the spec. Buckets are
+     * emitted in first-seen order — consumers who want a specific
+     * ordering should `.sort()` downstream.
+     *
+     * **Cardinality caps:** a one-shot warning fires at 10_000
+     * distinct groups; `GroupCardinalityError` throws at 100_000.
+     * Grouping on a high-uniqueness field like `id` or `createdAt` is
+     * almost always a query mistake — the error message names the
+     * field and observed cardinality and suggests narrowing with
+     * `.where()` first.
+     *
+     * **Null / undefined keys:** records with a missing or explicitly
+     * `null` group field get their own buckets. `Map`-based
+     * partitioning distinguishes `undefined` from `null`, so the two
+     * cases do NOT merge. Consumers who want them merged should
+     * coalesce upstream with `.filter()`.
+     *
+     * **Joins are not applied unless the GROUP KEY addresses an alias** (#1338).
+     * For a left-side key the old rationale still holds — a leg is
+     * projection-only, so running one inside a grouping pipeline would be
+     * wasteful and could trigger `DanglingReferenceError` in strict mode for a
+     * call whose intent is purely to bucket-and-reduce. For an aliased key
+     * (`groupBy('client.region')`, the accounting-report shape) the legs run and
+     * the buckets are the joined relation's: the key is stamped under its DOTTED
+     * path (`row['client.region']`), and a left row whose right side is absent
+     * reads `undefined` and lands in the undefined bucket — the same bucket a
+     * missing left-side key gets, and still distinct from an explicit `null`.
+     *
+     * ⚠️ The decision is taken from the KEY, because the reducer spec arrives a
+     * call later. A reducer over an alias under a LEFT key is therefore REFUSED
+     * rather than folded as `undefined` — group by the alias, or aggregate
+     * without grouping.
+     *
+     * **Filter clauses (`.filter(fn)`):** grouped queries still
+     * support filter clauses in the underlying plan — they run in
+     * the same candidate/filter pipeline that `.aggregate()` uses.
+     * The performance caveat is the same: filter clauses cost O(N)
+     * per record and can't be index-accelerated.
+     */
+    groupBy<F extends QueryField<T, S>>(field: F): GroupedQuery<T, F, S, M>;
+    groupBy<F extends readonly [QueryField<T, S>, QueryField<T, S>, ...QueryField<T, S>[]]>(...fields: F): GroupedQueryN<T, F, S, M>;
+    groupBy(key: DateTruncKey): GroupedQuery<T, string, S, M>;
+    groupBy(...keys: readonly [
+        QueryField<T, S> | DateTruncKey,
+        QueryField<T, S> | DateTruncKey,
+        ...(QueryField<T, S> | DateTruncKey)[]
+    ]): GroupedQueryN<T, readonly string[], S, M>;
+    /**
+     * SQL window functions over the query's result rows (#1349) — terminate with
+     * `.select(spec)`.
+     *
+     * ```ts
+     * invoices.query()
+     *   .where('status', '==', 'open')
+     *   .window({ partitionBy: 'clientId', orderBy: 'date' })
+     *   .select({ balance: runningSum('amount'), prev: lag('amount', 1), n: rowNumber() })
+     *   .run()
+     * ```
+     *
+     * ⭐ Distinguished from `.groupBy()` by ARITY, not by capability: grouping
+     * emits one row per bucket and drops the source rows; a window keeps EVERY
+     * row and attaches per-row values computed over its partition.
+     *
+     * **The record set is `toArray()`'s** — the full pipeline, including joins,
+     * `orderBy`, `offset`/`limit` and the Via decode. That differs deliberately
+     * from `.groupBy()`, which reads the candidate/filter pipeline only: a
+     * window returns ROWS, so the query's own ordering and paging are exactly
+     * what decides which rows there are and how they are presented. `orderBy`
+     * inside the window decides only how a partition is WALKED.
+     *
+     * **Frame:** `rows unbounded preceding → current row`, and only that in v1.
+     *
+     * `partitionBy` / `orderBy` accept a `dateTrunc()` key (#1350) alongside
+     * plain field names; the derived bucket is used for partitioning and is not
+     * stamped on the output row. A sealed (`sensitive`) field is refused at
+     * compile time, same as `.groupBy()`.
+     *
+     * ⛔ **Not an `explain()` node.** `explain()` is a terminal on `Query`;
+     * `.window()` leaves `Query` for `WindowedQuery`, so there is nothing past
+     * here to add a node to — the same reason #1336's post-group ops are absent.
+     */
+    window(spec: WindowSpec<QueryField<T, S>>): WindowedQuery<T>;
+}
+/** The public Reduce surface — merged into `Query` by `./index.ts`. */
+export type ReduceSurface<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> = Pick<ReduceMethods<T, S, Q, M>, 'aggregate' | 'groupBy' | 'window' | 'distinct'>;

package/dist/kernel/query/reduce/scan-methods.d.ts

@@ -0,0 +1,121 @@
+/**
+ * #1458 — the **Reduce** half of `ScanBuilder`.
+ *
+ * `aggregate` · `groupBy` · the grouped-scan handle they return.
+ *
+ * See `../relate/scan-methods.ts` for why `ScanBuilder` is split at all.
+ *
+ * ⭐ **The streaming memory property travels with the code.**
+ * `scan().aggregate()` is O(reducers), not O(records) — it steps every reducer
+ * per record and never collects the stream — and `groupBy().aggregate()` is
+ * O(groups). That is a code-level invariant visible in the bodies below, so
+ * moving them wholesale is what preserves it; re-expressing them over the
+ * eager reducers would have quietly turned an unbounded scan into an array.
+ */
+import type { MultiReduceResult, ScanPageProvider } from '../scan-builder.js';
+import type { QueryField } from '../../types.js';
+import type { Clause } from '../predicate.js';
+import type { ViaPipeline } from '../../via/pipeline.js';
+import type { JoinContext, JoinLeg } from '../relate/join.js';
+import type { ReducerBuilder } from '../../../with-lookup/reduce/reducers.js';
+import type { ReduceSpec, ReduceResult } from '../../../with-lookup/reduce/reduction.js';
+import type { DateTruncKey } from './date-trunc.js';
+/** @internal — the mixin whose prototype `./index.ts` copies onto `ScanBuilder`. */
+export declare class ScanReduceMethods<T, S extends keyof T = never, M extends keyof T & string = never> {
+    protected readonly pageProvider: ScanPageProvider<T>;
+    protected readonly pageSize: number;
+    protected readonly clauses: readonly Clause[];
+    protected readonly joins: readonly JoinLeg[];
+    protected readonly joinContext: JoinContext | undefined;
+    protected readonly via: ViaPipeline | undefined;
+    protected decodeVia: (record: T) => T;
+    protected recordMatches: (record: T, clauses?: readonly Clause[]) => boolean;
+    [Symbol.asyncIterator]: () => AsyncIterator<T>;
+    aggregate<const Specs extends readonly ReduceSpec[]>(specs: Specs): Promise<MultiReduceResult<Specs>>;
+    aggregate<Spec extends ReduceSpec>(spec: Spec): Promise<ReduceResult<Spec>>;
+    aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): Promise<ReduceResult<Spec>>;
+    /**
+     * The multi-spec `.aggregate([specA, specB, …])` executor (#1340).
+     *
+     * One iteration of the scan, `Σ|spec|` reducer states — memory stays
+     * O(reducers) exactly as the single-spec terminal's does, with the sum taken
+     * across specs instead of within one. Every spec's state is stepped from the
+     * SAME yielded record, so the page provider is read once per page.
+     *
+     * Semantics per spec are identical to the single-spec form, deliberately:
+     * the posture gate is `refuseUnqueryableReducers` (metadata only), NOT the
+     * full `wrapReducers` — so `aggregate([a, b])` returns exactly what
+     * `aggregate(a)` and `aggregate(b)` return, and the array form is a pure
+     * cost optimisation with no behavioural delta to reason about. (The grouped
+     * scan path DOES wrap — it has to agree with the eager grouped path, which
+     * wraps. See `scan-groupby.ts`.)
+     */
+    private aggregateMany;
+    /**
+     * Group the scan stream and reduce each group — `#1340`.
+     *
+     * ```ts
+     * const byClient = await invoices.scan()
+     *   .where('status', '==', 'open')
+     *   .groupBy('clientId', { maxGroups: 5_000 })
+     *   .aggregate({ total: sum('amount'), n: count() })
+     * ```
+     *
+     * ⚠️ **This is the one scan terminal whose memory is NOT O(pageSize).** It
+     * holds one reducer state per group, which is why the budget is explicit:
+     * `maxGroups` defaults to the eager path's 100_000-group ceiling and is
+     * REFUSED — never truncated — the moment a scan would exceed it. Price the
+     * budget before raising it: an exact `median`/`percentile`, a `mode` or a
+     * `countDistinct` holds O(values) per group, so an unbounded scan wants
+     * `{ approx: true }` on the quantiles. Full rationale in `scan-groupby.ts`.
+     *
+     * The key may be a field name or a `dateTrunc()` derived calendar key (the
+     * monthly-rollup shape); grouping BY a `sensitive` field is refused at
+     * compile time, same as `Query.groupBy()`.
+     */
+    groupBy<F extends QueryField<T, S>>(field: F, opts?: {
+        maxGroups?: number;
+    }): ScanGroupedScan<T, F, S, M>;
+    groupBy(key: DateTruncKey, opts?: {
+        maxGroups?: number;
+    }): ScanGroupedScan<T, string, S, M>;
+}
+/** The public Reduce surface of `ScanBuilder` — merged by `./index.ts`. */
+export type ScanReduceSurface<T, S extends keyof T = never, M extends keyof T & string = never> = Pick<ScanReduceMethods<T, S, M>, 'aggregate' | 'groupBy'>;
+/**
+ * Default group ceiling — the same constant the eager `.groupBy()` enforces.
+ * Duplicated as a literal rather than imported from
+ * `with-lookup/reduce/groupby.ts` on purpose: that module carries the eager
+ * `groupAndReduce` + `GroupedReduction` classes, and the always-on kernel must
+ * not pull them in to read one number. The pairing is asserted by a test.
+ */
+export declare const SCAN_GROUPBY_DEFAULT_MAX_GROUPS = 100000;
+/** Group-key result-row shape: the key under its own name, plus the reducers. */
+export type ScanGroupedRow<F extends string, R> = {
+    [K in F]: unknown;
+} & R;
+/**
+ * Chainable wrapper returned by `ScanBuilder.groupBy()`. The only operation on
+ * it is `.aggregate()` — same minimal shape as `GroupedQuery`.
+ */
+export declare class ScanGroupedScan<T, F extends string, S extends keyof T = never, M extends keyof T & string = never> {
+    private readonly stream;
+    private readonly key;
+    private readonly maxGroups;
+    private readonly via;
+    constructor(stream: AsyncIterable<T>, key: string | DateTruncKey, maxGroups: number, via: ViaPipeline | undefined);
+    /**
+     * Fold the scan into one row per group. Resolves to `R[]`, ordered by each
+     * group's FIRST-SEEN position in the stream (`Map` insertion order), which
+     * is the same ordering rule the eager path documents.
+     *
+     * ```ts
+     * const byMonth = await invoices.scan()
+     *   .where('status', '==', 'paid')
+     *   .groupBy(dateTrunc('closedAt', 'month', { as: 'month', timeZone: 'UTC' }), { maxGroups: 240 })
+     *   .aggregate({ total: sum('amount'), n: count() })
+     * ```
+     */
+    aggregate<Spec extends ReduceSpec>(spec: Spec): Promise<ScanGroupedRow<F, ReduceResult<Spec>>[]>;
+    aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): Promise<ScanGroupedRow<F, ReduceResult<Spec>>[]>;
+}