@noy-db/hub 0.1.0-pre.3

package/dist/strategy-BSxFXGzb.d.ts

@@ -0,0 +1,110 @@
+/**
+ * CRDT state types, merge logic, and build helpers.
+ * per-collection CRDT mode: 'lww-map' | 'rga' | 'yjs'
+ *
+ * The encrypted envelope wraps the CRDT state (not the resolved snapshot).
+ * Adapters only ever see ciphertext. `collection.get(id)` returns the
+ * resolved snapshot; `collection.getRaw(id)` returns the full CRDT state.
+ */
+/** Per-collection CRDT mode. */
+type CrdtMode = 'lww-map' | 'rga' | 'yjs';
+/**
+ * Per-field last-write-wins registers.
+ * Each field carries its latest value and the ISO timestamp of the last write.
+ * Merge: for each field, keep the entry with the lexicographically higher `ts`.
+ */
+interface LwwMapState {
+    readonly _crdt: 'lww-map';
+    readonly fields: Record<string, {
+        readonly v: unknown;
+        readonly ts: string;
+    }>;
+}
+/**
+ * Simplified Replicated Growable Array.
+ * Items are assigned stable NID (noy-db id) strings on first insertion.
+ * Deleted items are tracked as tombstones so concurrent removals commute.
+ *
+ * The resolved snapshot is the ordered list of non-tombstoned `v` values.
+ */
+interface RgaState {
+    readonly _crdt: 'rga';
+    readonly items: ReadonlyArray<{
+        readonly nid: string;
+        readonly v: unknown;
+    }>;
+    readonly tombstones: readonly string[];
+}
+/**
+ * Yjs binary state marker. `update` is base64(Y.encodeStateAsUpdate()).
+ * Core stores and retrieves the blob opaquely. `@noy-db/yjs` is responsible
+ * for encoding, decoding, and merging via `Y.mergeUpdates`.
+ * Core falls back to last-write-wins (higher `_v`) for conflict resolution.
+ */
+interface YjsState {
+    readonly _crdt: 'yjs';
+    /** base64-encoded Y.encodeStateAsUpdate() bytes. */
+    readonly update: string;
+}
+type CrdtState = LwwMapState | RgaState | YjsState;
+/**
+ * Resolve a CRDT state into the end-user record snapshot.
+ *
+ * - `lww-map` → `Record<string, unknown>` (field values extracted from registers)
+ * - `rga`     → `unknown[]` (non-tombstoned items in insertion order)
+ * - `yjs`     → `string` (base64 update blob; use @noy-db/yjs for a Y.Doc)
+ */
+declare function resolveCrdtSnapshot(state: CrdtState): unknown;
+/**
+ * Merge two CRDT states produced by concurrent writes.
+ * Called by the collection-level conflict resolver registered with SyncEngine.
+ *
+ * For `yjs`: core cannot merge Yjs without importing the `yjs` package.
+ * The caller must handle that case by falling back to the higher-`_v` envelope.
+ */
+declare function mergeCrdtStates(a: CrdtState, b: CrdtState): CrdtState;
+/**
+ * Build (or update) an lww-map state from a new record.
+ *
+ * All fields in the new record win at timestamp `now`.
+ * Fields present in the existing state but absent from the new record
+ * are preserved (they were written by another device).
+ */
+declare function buildLwwMapState(record: Record<string, unknown>, existing: LwwMapState | undefined, now: string): LwwMapState;
+/**
+ * Build (or update) an RGA state from a new array.
+ *
+ * Existing items are matched to new elements by deep-equality of their `v`.
+ * Unmatched existing items are tombstoned. New elements that have no existing
+ * match get a fresh NID via `generateNid()`.
+ */
+declare function buildRgaState(arr: unknown[], existing: RgaState | undefined, generateNid: () => string): RgaState;
+
+/**
+ * Strategy seam between core Collection and the optional CRDT
+ * subsystem. Core imports `CrdtStrategy` as a TYPE-ONLY symbol and
+ * `NO_CRDT` as a minimal runtime stub.
+ *
+ * The state-construction / merge / snapshot-resolution helpers —
+ * `buildLwwMapState`, `buildRgaState`, `mergeCrdtStates`,
+ * `resolveCrdtSnapshot` — are only reachable from `withCrdt()` in
+ * `./active.ts`, which is only exported through the `@noy-db/hub/crdt`
+ * subpath. Consumers without CRDT mode configured never pull the
+ * ~221 LOC into their bundle.
+ *
+ * @internal
+ */
+
+/**
+ * Seam interface. `@internal`.
+ *
+ * @internal
+ */
+interface CrdtStrategy {
+    buildLwwMapState(record: Record<string, unknown>, previous: LwwMapState | undefined, now: string): LwwMapState;
+    buildRgaState(items: readonly unknown[], previous: RgaState | undefined, idGen: () => string): RgaState;
+    mergeCrdtStates(local: CrdtState, remote: CrdtState): CrdtState;
+    resolveCrdtSnapshot(state: CrdtState): unknown;
+}
+
+export { type CrdtStrategy as C, type LwwMapState as L, type RgaState as R, type YjsState as Y, type CrdtMode as a, type CrdtState as b, buildLwwMapState as c, buildRgaState as d, mergeCrdtStates as m, resolveCrdtSnapshot as r };

package/dist/strategy-D-SrOLCl.d.cts

@@ -0,0 +1,548 @@
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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>;
+
+/**
+ * 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;
+/**
+ * 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> {
+    private readonly executeRecords;
+    private readonly field;
+    private readonly upstreams;
+    /**
+     * Optional dict label resolver attached by the query builder when
+     * the grouping field is a dictKey.
+     */
+    private readonly dictLabelResolver?;
+    constructor(executeRecords: () => readonly unknown[], field: F, upstreams: readonly AggregationUpstream[], 
+    /**
+     * Optional dict label resolver attached by the query builder when
+     * the grouping field is a dictKey.
+     */
+    dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined);
+    /**
+     * 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>>>;
+}
+/**
+ * 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[], field: string, spec: AggregateSpec): 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 field;
+    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?;
+    constructor(executeRecords: () => readonly unknown[], field: 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`.
+     */
+    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>): GroupedQuery<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, GROUPBY_MAX_CARDINALITY as G, type LiveAggregation as L, 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, type GroupedRow as h, type ReducerOptions as i, avg as j, buildLiveAggregation as k, count as l, groupAndReduce as m, max as n, min as o, resetGroupByWarnings as p, reduceRecords as r, sum as s };