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

package/dist/with-lookup/indexing/unique-constraints.d.ts

@@ -1,40 +1,115 @@
 /**
- * In-memory unique-constraint enforcement for eager-mode collections.
+ * Unique-constraint enforcement.
  *
  * Each `UniqueConstraintSet` holds one or more constraints, each covering
- * an ordered tuple of field names. On every `put()` the caller invokes
- * `check()` BEFORE the store write; on success it calls `upsert()` to
- * update the maps. `remove()` is called on `delete()`.
+ * an ordered tuple of field names (a one-field tuple is the ordinary
+ * single-field case; a multi-field tuple is a COMPOUND unique — uniqueness
+ * over the tuple, never over each component separately). On every `put()`
+ * the caller invokes `check()` BEFORE the store write; on success it calls
+ * `upsert()` to update the maps. `remove()` is called on `delete()`.
  *
  * Null-distinct semantics: if ANY constrained field is `null` or
  * `undefined` in the record, that record is exempt from the constraint —
- * `keyFor` returns `null` and the record is silently skipped.
+ * `keyOf` returns `null` and the record is silently skipped.
  * This matches standard SQL NULL-distinct behavior.
  *
- * Only used in eager mode (`prefetch !== false`). Lazy-mode collections
- * throw at registration instead (see Collection constructor).
+ * ## The three modes, and what each one actually promises (#1358)
+ *
+ * | mode | promise |
+ * |---|---|
+ * | eager (default) | PREVENTION, from the in-memory map built at hydration. |
+ * | lazy (`prefetch:false`) | PREVENTION, from a point lookup through the persisted `_idx/` mirror — see `checkUniqueOnPut` in `collection-facade.ts`. |
+ * | CRDT | **NO prevention.** DETECTION only, reported on `unique:violation`. |
+ * | tiered | PREVENTION across every tier whose DEK the writer holds. A tier the writer cannot read is outside the guarantee — see `checkUniqueAcrossTiers` in `with-audit/tiers/index.ts`. |
+ *
+ * ⚠️ **The CRDT row is a distributed-systems fact, not a missing feature.**
+ * Two replicas that are offline from each other can both accept the same
+ * "unique" value, and no local check can prevent that — the other replica's
+ * write does not exist anywhere this one can read. So a CRDT collection
+ * never refuses a duplicate; it keeps both records (as CRDT convergence
+ * requires) and reports the collision as a `UniqueConstraintError` on the
+ * `unique:violation` event, both when it is created and when a later
+ * session first sees the two records together. What is guaranteed is
+ * uniqueness within what this writer could see at write time, plus
+ * detection when the replicas meet. Do not write anything stronger than
+ * that into a doc, a type, or an error message.
+ *
+ * None of the four modes refuses the DECLARATION any more. Compound unique
+ * is supported in all of them (the key is the canonical tuple key in every
+ * case), so there is no undefined corner left where a declaration is
+ * accepted and quietly does nothing.
  */
+import { UniqueConstraintError } from '../../kernel/errors.js';
 import type { IndexDef } from './eager-indexes.js';
+/**
+ * What this collection's write paths are allowed to promise.
+ *
+ * `'prevent'` — a colliding write throws `UniqueConstraintError` before it
+ * lands (eager, lazy and tiered collections).
+ * `'detect'` — a colliding write LANDS and is reported afterwards (CRDT).
+ * See the module doc for why CRDT cannot be `'prevent'`.
+ */
+export type UniqueEnforcement = 'prevent' | 'detect';
+/** How a detected-but-not-prevented collision is reported to the consumer. */
+export type UniqueViolationReporter = (error: UniqueConstraintError) => void;
 export declare class UniqueConstraintSet {
     private readonly collectionName;
+    /** See {@link UniqueEnforcement}. Defaults to prevention. */
+    readonly enforcement: UniqueEnforcement;
+    /** Fired for every collision this set observes but does NOT prevent. */
+    private readonly report;
     private readonly constraints;
-    constructor(collectionName: string, uniqueDefs: readonly (readonly string[])[]);
+    constructor(collectionName: string, uniqueDefs: readonly (readonly string[])[], 
+    /** See {@link UniqueEnforcement}. Defaults to prevention. */
+    enforcement?: UniqueEnforcement, 
+    /** Fired for every collision this set observes but does NOT prevent. */
+    report?: UniqueViolationReporter);
     get size(): number;
+    /** The declared field tuples, in declaration order. */
+    fieldTuples(): readonly (readonly string[])[];
     /**
      * Compute the canonical key for a record under a given constraint.
      * Returns `null` if any constrained field is `null` or `undefined`
      * (the record is exempt — no constraint is checked).
+     *
+     * Public because the tier scan (`with-audit/tiers/index.ts`) has to compute
+     * the same key for a record it decrypted under a tier DEK, which this class
+     * cannot reach — one key function, so the two paths cannot drift.
      */
-    private keyFor;
+    keyOf(fields: readonly string[], record: unknown): string | null;
+    /**
+     * Every constraint key `record` would occupy — the probe a checker outside
+     * this class (tiers, lazy) compares against its own candidates. Exempt
+     * (null-distinct) constraints are omitted, so an empty result means "this
+     * record is unconstrained" and the caller can skip its scan entirely.
+     */
+    probe(record: unknown): ReadonlyArray<{
+        readonly fields: readonly string[];
+        readonly key: string;
+    }>;
     /**
      * Throw `UniqueConstraintError` if writing `id` with `record` would
      * collide with a DIFFERENT existing record. Call BEFORE the store write.
+     *
+     * In `'detect'` mode this is a deliberate NO-OP: a CRDT collection must
+     * not refuse a write it has no authority to refuse (module doc). The
+     * collision is reported from {@link upsert} / {@link build} instead.
      */
     check(id: string, record: unknown): void;
+    /**
+     * The `UniqueConstraintError` a write of `id`/`record` would produce, or
+     * `null`. Never throws — the shared core of {@link check} (which throws it)
+     * and the detect path (which reports it).
+     */
+    collision(id: string, record: unknown): UniqueConstraintError | null;
     /**
      * Update the constraint maps after a successful write.
      * Pass `previous` when updating an existing record (so the old key
      * is removed first). Pass `null` or `undefined` for a fresh insert.
+     *
+     * In `'detect'` mode a collision observed here is REPORTED and the write
+     * still stands (both records are kept — see the module doc). In
+     * `'prevent'` mode `check()` already ran, so there is nothing to report.
      */
     upsert(id: string, record: unknown, previous?: unknown): void;
     /**
@@ -46,13 +121,18 @@ export declare class UniqueConstraintSet {
      * Rebuild all constraint maps from a full snapshot.
      * Called after hydration (ensureHydrated / hydrateFromSnapshot).
      *
-     * **Last-writer-wins**: this method does NOT validate pre-existing data
-     * for duplicates. If the store already contains two records sharing a
-     * constrained value (written before the unique index was declared), the
-     * last one processed wins the map slot and the duplicate is silently
-     * displaced — no error is thrown, and the earlier holder is evicted from
-     * the map. Callers retrofitting a unique index onto populated data should
-     * run a one-time uniqueness scan before relying on enforcement.
+     * **In `'prevent'` mode this is last-writer-wins**: it does NOT validate
+     * pre-existing data for duplicates. If the store already contains two
+     * records sharing a constrained value (written before the unique index was
+     * declared), the last one processed wins the map slot and the duplicate is
+     * silently displaced — no error is thrown, and the earlier holder is
+     * evicted from the map. Callers retrofitting a unique index onto populated
+     * data should run a one-time uniqueness scan before relying on enforcement.
+     *
+     * **In `'detect'` mode this is the MERGE POINT** — the moment a session
+     * that wrote neither record first sees them together (a CRDT replica
+     * opening a store its peer has written to). Every displaced holder is
+     * reported on `unique:violation` instead of being dropped in silence.
      */
     build(entries: Iterable<readonly [string, unknown]>): void;
 }
@@ -60,15 +140,18 @@ export declare class UniqueConstraintSet {
  * Build the `UniqueConstraintSet` for a collection from its `IndexDef[]`,
  * or return `null` when no `unique: true` index is declared.
  *
- * Unique enforcement is **eager-mode only**. If any `unique` index is
- * declared on a lazy (`prefetch:false`), CRDT, or tiered collection, this
- * throws `UnsupportedIndexOptionError` at registration rather than letting
- * those write paths (which bypass `check()`/`upsert()`) silently skip
- * enforcement. Kept out of the Collection constructor to keep that
- * always-on kernel file lean (kernel-surface invariant).
+ * `mode` selects the enforcement the collection's write paths can actually
+ * deliver (see the module doc's table). Nothing is refused here any more:
+ * before #1358 lazy, CRDT and tiered collections threw
+ * `UnsupportedIndexOptionError` at registration because their write paths
+ * bypassed `check()`/`upsert()`. Lazy and tiered now have real enforcement
+ * wired to those paths, and CRDT has honest detection.
+ *
+ * Kept out of the Collection constructor to keep that always-on kernel file
+ * lean (kernel-surface invariant).
  */
 export declare function buildUniqueConstraintSet(collectionName: string, indexes: readonly IndexDef[] | undefined, mode: {
     readonly lazy: boolean;
     readonly crdt: boolean;
     readonly tiered: boolean;
-}): UniqueConstraintSet | null;
+}, report?: UniqueViolationReporter): UniqueConstraintSet | null;

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

@@ -7,27 +7,5 @@
  * subpath — a consumer that never imports the subpath ships none of
  * this (ESM tree-shaking + hub's `"sideEffects": false`).
  */
-import type { ReduceStrategy } from './strategy.js';
-/**
- * Build the default aggregate strategy. Pass into
- * `createNoydb({ reduceStrategy: withReduce() })` to light up
- * `.aggregate()` and `.groupBy()` on `Query` and `ScanBuilder`.
- *
- * @example
- * ```ts
- * import { createNoydb } from '@noy-db/hub'
- * import { withReduce, sum, count } from '@noy-db/hub/reduce'
- *
- * const db = await createNoydb({
- *   store, user, secret,
- *   reduceStrategy: withReduce(),
- * })
- *
- * const totals = invoices.query()
- *   .where('status', '==', 'paid')
- *   .groupBy('clientId')
- *   .aggregate({ amount: sum('amount'), n: count() })
- *   .run()
- * ```
- */
-export declare function withReduce(): ReduceStrategy;
+import type { ReduceOptions, ReduceStrategy } from './strategy.js';
+export declare function withReduce(opts?: ReduceOptions): ReduceStrategy;

package/dist/with-lookup/reduce/group-core.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The parts of `.groupBy()` that BOTH the eager pipeline and the incremental
+ * one need — the cardinality guards and the per-bucket fold.
+ *
+ * ⭐ It exists for one reason: `groupby.ts` (eager) and `incremental-group.ts`
+ * (delta-maintained) must produce byte-identical rows, and the cheapest way to
+ * guarantee that is for them to share the CODE rather than agree by
+ * convention. Putting it here also breaks what would otherwise be an import
+ * cycle between those two files.
+ *
+ * @internal — `groupby.ts` re-exports the public names, so the module graph
+ * below this file is invisible to consumers.
+ */
+import type { ReduceSpec } from './reduction.js';
+/**
+ * Cardinality thresholds for `.groupBy()`. The warn threshold gives
+ * consumers a heads-up before the hard error; the cap is a fixed
+ * constant (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;
+export declare function warnCardinalityApproaching(fields: readonly string[], observed: number): void;
+/**
+ * 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;
+/** The label a cardinality error names — `"k"` single-key, `[a, b]` multi. */
+export declare function groupFieldLabel(fields: readonly string[]): string;
+/**
+ * Reduce ONE bucket into its output row: the group keys stamped first in
+ * declaration order, then every reducer's finalized value.
+ *
+ * ⭐ The single definition of a grouped row. `groupAndReduce` calls it once per
+ * bucket over the whole record set; the incremental maintainer calls it for
+ * the buckets a delta touched and reuses the cached row for the rest. Because
+ * the fold is `init → step* → finalize` over the SAME records in the SAME
+ * order, an incrementally produced row is not merely equal to a re-run's — it
+ * is the identical computation.
+ */
+export declare function reduceGroupRow<R>(fields: readonly string[], keyValues: Record<string, unknown>, records: readonly unknown[], spec: ReduceSpec, reducerKeys: readonly string[]): R;

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

@@ -37,11 +37,13 @@
  * 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.
+ * **Live mode:** `.groupBy().aggregate().live()` maintains its buckets
+ * incrementally (#1341, grouped half). A change event patches the match set
+ * and then re-folds only the one or two buckets it touched; every other bucket
+ * serves the row it already computed. See `incremental-group.ts` — including
+ * why reducer states are re-folded rather than inverted through the protocol's
+ * `remove()` hook. A plan `canMaintainIncrementally()` refuses, and any
+ * notification arriving without a delta, still re-runs the whole pipeline.
  *
  * **Type-level stable-key narrowing:** when
  * `dictKey` lands, `groupBy<DictField>()` will narrow the group key
@@ -60,23 +62,18 @@
  */
 import type { ReduceSpec, ReduceResult, ReductionUpstream, LiveReduction } from './reduction.js';
 import type { ReducerBuilder } from './reducers.js';
+import type { GroupMaintenanceStats } from './incremental-group.js';
+import type { GroupMaintenanceSource } from '../../kernel/query/live/incremental.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.
+ * The cardinality guards and the warning-reset hook live in `group-core.ts`
+ * — shared verbatim with the incremental maintainer so the eager and
+ * delta-maintained paths cannot enforce different caps — and are re-exported
+ * here so every existing import site is unchanged.
  */
-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;
+export { GROUPBY_WARN_CARDINALITY, GROUPBY_MAX_CARDINALITY, resetGroupByWarnings, } from './group-core.js';
 /**
  * Result row shape for a grouped reduction. Each row carries the
  * group key value under the grouping field name plus every reducer
@@ -130,6 +127,12 @@ declare abstract class GroupedQueryBase {
      * BigInt reducers when `.aggregate(spec)` is terminated.
      */
     protected readonly via?: ViaPipeline | undefined;
+    /**
+     * The #1341 delta-maintenance seam, supplied by `Query.groupBy()` when the
+     * plan admits incremental maintenance and withheld when it does not.
+     * `undefined` is the pre-#1341 behaviour: `.live()` re-runs in full.
+     */
+    protected readonly maintenance?: GroupMaintenanceSource | undefined;
     /**
      * Field set this grouped query buckets on. Stored in declaration
      * order — the same order is preserved on every result row by
@@ -150,7 +153,13 @@ declare abstract class GroupedQueryBase {
      * `sum`/`min`/`max` over Via-covered fields (e.g. money) into exact
      * BigInt reducers when `.aggregate(spec)` is terminated.
      */
-    via?: ViaPipeline | undefined);
+    via?: ViaPipeline | undefined, 
+    /**
+     * The #1341 delta-maintenance seam, supplied by `Query.groupBy()` when the
+     * plan admits incremental maintenance and withheld when it does not.
+     * `undefined` is the pre-#1341 behaviour: `.live()` re-runs in full.
+     */
+    maintenance?: GroupMaintenanceSource | undefined);
     /** Apply Via-aware reducer rewriting (e.g. money) when the source declares one. */
     protected wrapSpec<Spec extends ReduceSpec>(spec: Spec): Spec;
 }
@@ -159,10 +168,13 @@ declare abstract class GroupedQueryBase {
  * with `.aggregate(spec)` which returns a `GroupedReduction`.
  *
  * Kept minimal — the only operation on a grouped query is
- * reduction. 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.
+ * reduction. Ordering, limiting and further filtering of the
+ * REDUCED rows live one step further along the chain, on the
+ * `GroupedReduction` that `.aggregate()` returns (`.having()`,
+ * `.orderBy()`, `.limit()` — #1336); ordering and limiting of the
+ * SOURCE RECORDS stays on the underlying `Query`, before
+ * `.groupBy()`. The two are different operations and neither
+ * substitutes for the other.
  */
 export declare class GroupedQuery<T, F extends string, S extends keyof T = never, M extends keyof T & string = never> extends GroupedQueryBase {
     /**
@@ -202,6 +214,45 @@ export declare class GroupedQueryN<T, F extends readonly string[], S extends key
  * the full partition to materialize before the error fires.
  */
 export declare function groupAndReduce<R>(records: readonly unknown[], fieldOrFields: string | readonly string[], spec: ReduceSpec, moneyFields?: Record<string, MoneyDescriptor>): R[];
+/**
+ * The post-group stage (#1336): `having` predicates, an ordering spec over the
+ * reduced rows, and a row cap. Immutable — every builder method returns a new
+ * `GroupedReduction` carrying a new `PostGroup`.
+ *
+ * @internal — not exported; `GroupedReduction`'s public signatures name only
+ * inline function/union types, so no consumer needs this shape.
+ */
+interface PostGroup {
+    readonly having: readonly ((row: unknown) => boolean)[];
+    readonly orderBy: readonly {
+        readonly key: string;
+        readonly direction: 'asc' | 'desc';
+    }[];
+    readonly limit: number | undefined;
+}
+/**
+ * Compare two REDUCED values for post-group ordering.
+ *
+ * Deliberately NOT the row-pipeline comparator in `kernel/query/builder.ts`,
+ * and one rule apart from it: when both sides are strings that are plain
+ * decimal numerals, they compare by MAGNITUDE. That rule exists for exactly
+ * one reason — a money `sum` finalizes to an exact decimal string, and lexical
+ * order gets it wrong in the ordinary case (`'9882.00' > '10004.00'`). The
+ * pre-group path solves the same problem by asking the Via pipeline
+ * (`compareForOrder`), which cannot serve here: it reads the STORED
+ * scaled-integer form, and a reduced value is already decoded to decimal.
+ *
+ * The divergence is confined to a surface introduced by #1336 — no pre-group
+ * ordering changes — and it only reaches values that are numerals end to end,
+ * so a group key like `'c1'` still sorts lexically.
+ * ⭐ SHARED, not private: `.window()`'s in-partition ordering (#1349) faces the
+ * identical exposure over the identical values — its rows are decoded, so a
+ * money field is a decimal string there too — and imports this rather than
+ * growing a second rule that could drift from it.
+ *
+ * @internal
+ */
+export declare function compareReduced(a: unknown, b: unknown): number;
 /**
  * Grouped reduction wrapper — the `.groupBy(field).aggregate(spec)`
  * terminal. Shape mirrors `Reduction<R>` from aggregate.ts: two
@@ -211,7 +262,39 @@ export declare function groupAndReduce<R>(records: readonly unknown[], fieldOrFi
  * The generic `R` is the per-row result shape (i.e. a single
  * grouped row), and the terminals return `R[]` — one row per
  * bucket.
+ *
+ * `.having()` / `.orderBy()` / `.limit()` (#1336) post-process that array.
+ * ⛔ **They do not appear in `Query.explain()` (#1348), and that is not an
+ * omission.** `explain()` is a terminal on `Query`; `.groupBy()` leaves
+ * `Query` for `GroupedQuery` and then `GroupedReduction`, so by the time these
+ * three are reachable there is no `explain()` in the chain to add a node to.
+ * Adding one would mean putting `explain()` on `GroupedReduction` — a new
+ * surface, and a plan for a stage with nothing to choose: `having`/`orderBy`/
+ * `limit` here have exactly one dispatch (a filter, a stable sort, a slice)
+ * over rows already in memory. File an issue if a real consumer wants it.
+ * ⚠️ They are POST-processing, never a memory optimization: the group pass has
+ * already built and reduced every bucket by the time a `having` predicate is
+ * called, so `GROUPBY_WARN_CARDINALITY` / `GROUPBY_MAX_CARDINALITY` see the
+ * UNFILTERED bucket count and `having` cannot buy headroom under them. Narrow
+ * with `.where()` before `.groupBy()` for that.
  */
+/**
+ * What `GroupedReduction.live()` returns: a `LiveReduction` plus one window
+ * onto how it is being kept up to date (#1341).
+ */
+export interface LiveGroupedReduction<R> extends LiveReduction<R> {
+    /**
+     * Delta-maintenance counters for this live reduction, or `undefined` when
+     * the plan was refused and every change re-runs the whole grouping.
+     *
+     * `patches` counts change events folded in per group; `rebuilds` counts
+     * falls back to a full bucket rebuild. A live reduction that reports a
+     * maintainer but never patches is a live reduction whose fallback is
+     * swallowing everything — which is exactly the failure this exists to make
+     * visible.
+     */
+    maintenanceStats(): GroupMaintenanceStats | undefined;
+}
 export declare class GroupedReduction<R> {
     private readonly executeRecords;
     private readonly spec;
@@ -221,13 +304,79 @@ export declare class GroupedReduction<R> {
      *. Present when the grouping field is a dictKey.
      */
     private readonly dictLabelResolver?;
+    /**
+     * The post-group stage (#1336). Optional and defaulted so every existing
+     * construction site — `GroupedQuery.aggregate()`, `GroupedQueryN`, the MV
+     * executor — is unchanged.
+     */
+    private readonly post;
+    /**
+     * The #1341 delta-maintenance seam (see `GroupedQueryBase`). Present only
+     * for a plan `canMaintainIncrementally()` admits.
+     */
+    private readonly maintenance?;
     private readonly fields;
     constructor(executeRecords: () => readonly unknown[], fields: string | readonly string[], spec: ReduceSpec, upstreams: readonly ReductionUpstream[], 
     /**
      * 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);
+    dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined, 
+    /**
+     * The post-group stage (#1336). Optional and defaulted so every existing
+     * construction site — `GroupedQuery.aggregate()`, `GroupedQueryN`, the MV
+     * executor — is unchanged.
+     */
+    post?: PostGroup, 
+    /**
+     * The #1341 delta-maintenance seam (see `GroupedQueryBase`). Present only
+     * for a plan `canMaintainIncrementally()` admits.
+     */
+    maintenance?: GroupMaintenanceSource | undefined);
+    /** Clone with a replaced post-group stage. */
+    private withPost;
+    /**
+     * Keep only the reduced rows a predicate accepts — SQL's `HAVING` (#1336).
+     *
+     * ```ts
+     * invoices.query()
+     *   .groupBy('clientId')
+     *   .aggregate({ total: sum('amount') })
+     *   .having(r => (r.total as number) > 10_000)
+     *   .orderBy('total', 'desc')
+     *   .limit(20)
+     *   .run()
+     * ```
+     *
+     * The predicate sees the WHOLE reduced row — group keys (including a
+     * `dateTrunc()`-derived one) and reducer outputs alike — with each value in
+     * its exact reduced form: a money `sum` arrives as its canonical decimal
+     * string (`'10004.00'`), never as a locale-formatted label, so comparing on
+     * it is exact. Successive calls AND.
+     *
+     * ⚠️ Not a memory optimization. See the class docs — the buckets exist
+     * already; `having` only decides what is returned.
+     */
+    having(predicate: (row: R) => boolean): GroupedReduction<R>;
+    /**
+     * Order the REDUCED rows by one of their keys (#1336). Successive calls are
+     * tie-breakers; the sort is stable, so bucket first-seen order breaks a
+     * final tie.
+     *
+     * ⭐ Distinguished from `Query.orderBy()` by POSITION, not by name: this one
+     * exists only after `.aggregate()` and sorts result rows by a reduced key or
+     * a group key; `Query.orderBy()` exists only before `.groupBy()` and sorts
+     * SOURCE RECORDS, which (via `.limit()`) changes which records are grouped
+     * at all. Both may appear in one chain and they do not interfere.
+     */
+    orderBy(key: string, direction?: 'asc' | 'desc'): GroupedReduction<R>;
+    /**
+     * Cap the number of reduced rows returned (#1336) — applied AFTER `having`
+     * and `orderBy`, so `.orderBy('total', 'desc').limit(20)` is a top-20.
+     *
+     * A later call replaces an earlier one.
+     */
+    limit(n: number): GroupedReduction<R>;
     /**
      * Execute the query, group, reduce, and return an array of rows.
      *
@@ -260,21 +409,31 @@ export declare class GroupedReduction<R> {
         fallback?: string | readonly string[];
     }): Promise<R[]>;
     /**
-     * Build a reactive `LiveReduction<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 `Reduction.live()` — the implementation delegates to the
-     * same `LiveAggregationImpl` class by threading a fresh
-     * recompute closure through the existing constructor.
+     * Build a reactive `LiveReduction<R[]>` that updates whenever any upstream
+     * source notifies of a change. Same error-isolation and idempotent-stop
+     * contract as `Reduction.live()` — the implementation delegates to the same
+     * `LiveAggregationImpl` class by threading a fresh recompute closure through
+     * the existing constructor.
+     *
+     * **Incremental per-group maintenance (#1341, grouped half).** When
+     * `Query.groupBy()` supplied a maintenance seam — a plan
+     * `canMaintainIncrementally()` admits, over a source that can hand back a
+     * snapshot and an id lookup — a change no longer re-runs the pipeline. The
+     * delta patches the match set, then patches the ONE OR TWO buckets it
+     * touches; every other bucket serves the row it already computed. See
+     * `incremental-group.ts` for the correctness argument, including the three
+     * membership transitions (a record changing group, a group emptying, a group
+     * appearing) that a naive per-group patch gets wrong.
+     *
+     * Every other plan, and every notification that arrives without a delta,
+     * re-runs the whole grouping exactly as before. Either way the emitted rows
+     * are identical to `.run()`'s.
      *
-     * 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.
+     * ⚠️ `.run()` is deliberately NOT served from the maintained state: it is a
+     * one-shot terminal that may be called long after a `.live()` was stopped,
+     * and reading the snapshot is the only answer that cannot be stale.
      *
      * Always call `live.stop()` when finished.
      */
-    live(): LiveReduction<R[]>;
+    live(): LiveGroupedReduction<R[]>;
 }
-export {};