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

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

@@ -0,0 +1,153 @@
+/**
+ * Per-group incremental maintenance for `groupBy().aggregate().live()` —
+ * #1341's second half.
+ *
+ * #1341 shipped delta maintenance for `live()` and for the UNGROUPED
+ * `.aggregate().live()`: the match set is patched per change event instead of
+ * re-scanned. A grouped live query got none of it — every change re-ran the
+ * whole pipeline: scan N records, re-evaluate every clause, re-bucket the
+ * whole match set, and re-fold every bucket. This module closes that.
+ *
+ * ## What is maintained, and what is not
+ *
+ * Two layers, and only the outer one is new:
+ *
+ *   1. **The match set** is maintained by `LiveMaintainer` (the #1341 engine),
+ *      unchanged and un-forked. Membership and snapshot sequence are ITS
+ *      answers, delegated exactly as the ungrouped path delegates them.
+ *   2. **The buckets** are maintained here. A change reaches this layer as a
+ *      `PatchOutcome` — a record left the set, joined it, or both — and only
+ *      the one or two buckets it touches are marked dirty. A dirty bucket is
+ *      re-folded from its own records on the next read; every other bucket
+ *      serves the row it already computed.
+ *
+ * ⛔ **Reducer states are NOT patched, deliberately** — the same call the
+ * ungrouped path made. The reducer protocol carries an optional `remove()`,
+ * and inverting `sum`/`count`/`avg` per delta would make a change O(1) instead
+ * of O(bucket). It is not wired, because *inverting a float `sum` does not
+ * reproduce a re-run's answer*: `(a + b + c) - b !== a + c` in IEEE-754, so an
+ * inverted state would drift from the eager one and the equivalence property
+ * this module is built on would be false. `min`/`max` are not invertible at
+ * all. Re-folding a dirty bucket from its records is bit-identical to a
+ * re-run by construction, and still turns O(matches) per change into
+ * O(largest touched bucket).
+ *
+ * ## The correctness contract
+ *
+ * `rows()` must equal `groupAndReduce(<the eager record set>, fields, spec)`
+ * at every step. Four things buy that, and three of them are group membership
+ * transitions a naive per-group patch gets wrong:
+ *
+ *   - **Bucket CONTENTS.** A record's group key is read from the record, so a
+ *     write that CHANGES the key arrives here as `removed` + `inserted` with
+ *     the BEFORE record on one side and the AFTER record on the other. It
+ *     leaves the old bucket and joins the new one. Reading the key off the
+ *     after-state alone — the obvious shortcut — would leave a ghost row in
+ *     the old bucket forever.
+ *   - **Bucket DISAPPEARANCE.** A bucket that loses its last member is
+ *     deleted, not left empty: `groupAndReduce` never creates a bucket with no
+ *     records, so an empty bucket would emit a row that a re-run does not.
+ *   - **Bucket APPEARANCE, in the right PLACE.** Buckets are emitted in
+ *     first-seen order, which is the order of each bucket's MINIMUM snapshot
+ *     sequence — not the order buckets happened to be created in. Those differ
+ *     the moment a group key changes: with records at seq 0 (group A) and
+ *     seq 1 (group B), rewriting seq 0's key to C makes a re-run emit
+ *     `[C, B]`, while appending the new bucket would emit `[B, C]`. So each
+ *     bucket keeps its members ordered by sequence and the emission order is
+ *     recomputed from `members[0].seq` whenever a membership change could have
+ *     moved a minimum.
+ *   - **The key VALUES on the row** come from the bucket's first-seen record,
+ *     which is `members[0]` — re-read whenever the bucket changes, because the
+ *     first-seen record itself can leave.
+ *
+ * ## The fallback
+ *
+ * Anything not provably patchable rebuilds: a payload-less change event, a
+ * plan `canMaintainIncrementally()` refuses (the maintainer is then never
+ * built at all), a `LiveMaintainer` that rebuilt underneath us, an error
+ * thrown mid-patch, or an internal inconsistency this module refuses to paper
+ * over. `stats()` counts both paths so a test can assert WHICH one ran —
+ * without that, a fallback that silently swallowed every case would pass every
+ * behavioural test while delivering nothing.
+ */
+import type { GroupMaintenanceSource, SourceChange } from '../../kernel/query/live/incremental.js';
+import type { ReduceSpec } from './reduction.js';
+/** Counters exposed by {@link GroupedMaintainer.stats}. */
+export interface GroupMaintenanceStats {
+    /** Change events folded in as a patch. */
+    readonly patches: number;
+    /** Full rebuilds of the bucket map — the fallback path. */
+    readonly rebuilds: number;
+    /** Buckets re-folded. One per dirty bucket per read, plus one per bucket per rebuild. */
+    readonly bucketsReduced: number;
+    /** Records stepped through a reducer. The work a full re-run would do every time. */
+    readonly recordsFolded: number;
+}
+/** Everything the grouped maintainer needs, supplied by `GroupedReduction`. */
+export interface GroupedMaintainerConfig {
+    readonly source: GroupMaintenanceSource;
+    readonly fields: readonly string[];
+    readonly spec: ReduceSpec;
+}
+/**
+ * The maintained bucket map behind one grouped live reduction.
+ *
+ * Lifecycle mirrors `LiveMaintainer`: `attach()` when the subscription opens,
+ * `apply(change)` per upstream event, `rows()` to read, `detach()` on
+ * teardown. Before `attach()` (and after any fallback) `rows()` rebuilds from
+ * the snapshot, so a detached maintainer is simply an eager executor.
+ */
+export declare class GroupedMaintainer {
+    private readonly inner;
+    private readonly fields;
+    private readonly spec;
+    private readonly reducerKeys;
+    private readonly fieldLabel;
+    private readonly project;
+    private buckets;
+    /** Dedup keys in emission (first-seen) order. Recomputed when `orderDirty`. */
+    private order;
+    private orderDirty;
+    private stale;
+    private attached;
+    private patches;
+    private rebuilds;
+    private bucketsReduced;
+    private recordsFolded;
+    constructor(cfg: GroupedMaintainerConfig);
+    /**
+     * Start accepting deltas. Call in the SAME synchronous turn as the initial
+     * read — `LiveReduction` computes its first value in its constructor and
+     * subscribes immediately after, so attaching there is that turn.
+     */
+    attach(): void;
+    /** Stop accepting deltas; every later read rebuilds. */
+    detach(): void;
+    /** Force the next read to rebuild. */
+    invalidate(): void;
+    /** Patch/rebuild counters — the observable difference between the two paths. */
+    stats(): GroupMaintenanceStats;
+    /**
+     * Fold one upstream change into the maintained buckets.
+     *
+     * The match-set layer runs first and unconditionally — even when THIS layer
+     * is stale, keeping the inner maintainer current is what makes the rebuild
+     * below cost O(matches) instead of O(collection).
+     */
+    apply(change: SourceChange | undefined): void;
+    /** The current grouped rows — a fresh array on every call. */
+    rows(): unknown[];
+    /**
+     * Rebuild every bucket from the maintained match set. Equivalent to the
+     * eager path by construction: the inner maintainer hands back exactly the
+     * records `executeRecords()` would produce, in exactly that order, and
+     * `join()` below is the same bucketing loop `groupAndReduce` runs.
+     */
+    private rebuild;
+    /** A record left the match set, or left one group on its way to another. */
+    private leave;
+    /** A record joined the match set, or joined a new group. */
+    private join;
+    private reduce;
+    private dedupKey;
+}

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

@@ -6,7 +6,8 @@
  * Groups every file whose reason-for-existing is record reduction:
  *   - `reduction` (`Reduction<R>`, `reduceRecords`, `buildLiveReduction`)
  *   - `groupby` (`GroupedQuery`, `GroupedReduction`, cardinality guards)
- *   - `reducers` (`count`, `sum`, `avg`, `min`, `max` factories)
+ *   - `reducers` (`count`, `countDistinct`, `sum`, `avg`, `min`, `max` factories,
+ *     plus the statistical five — `median`, `percentile`, `variance`, `stddev`, `mode`)
  *
  * The root barrel (`@noy-db/hub`) and the `@noy-db/hub/query` subpath
  * continue to re-export the same symbols for backward compatibility
@@ -14,13 +15,31 @@
  * prefer this subpath.
  */
 export { withReduce } from './active.js';
-export type { ReduceStrategy } from './strategy.js';
+export type { ReduceStrategy, ReduceOptions } from './strategy.js';
 export { Reduction, reduceRecords, buildLiveReduction } from './reduction.js';
 export type { ReduceSpec, ReduceResult, ReductionUpstream, LiveReduction, } from './reduction.js';
 export { GroupedQuery, GroupedQueryN, GroupedReduction, 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';
+export type { GroupedRow, GroupedRowN, LiveGroupedReduction } from './groupby.js';
+/**
+ * #1341 (grouped half) — per-group delta maintenance for
+ * `.groupBy().aggregate().live()`. `GroupedMaintainer` is exported so the
+ * engine can be driven (and its fallback observed) directly; ordinary
+ * consumers reach it through `LiveGroupedReduction.maintenanceStats()`.
+ */
+export { GroupedMaintainer } from './incremental-group.js';
+export type { GroupMaintenanceStats, GroupedMaintainerConfig } from './incremental-group.js';
+export { count, countDistinct, sum, avg, min, max, moneySum, moneyMin, moneyMax, reducerBuilder, bindDistinctReducers } from './reducers.js';
+export type { Reducer, ReducerOptions, ReducerBuilder, CountDistinctState } from './reducers.js';
+/** The statistical reducers (#1353) and the money variants of the two quantile ones. */
+export { median, percentile, variance, stddev, mode, moneyMedian, moneyPercentile } from './reducers.js';
+/**
+ * States and option bags named by the signatures directly above (#843a) — a
+ * caller must be able to annotate `variance()`'s state or pass
+ * `{ approx: true }` without reaching past the subpath.
+ */
+export type { WelfordState, DispersionOptions, PercentileOptions, QuantileState, ExactQuantileState, TDigestState, Centroid, ModeState, } from './reducers.js';
+export { withWindow, rowNumber, rank, lag, lead, runningSum, runningMoneySum, applyWindow, WindowedQuery, WindowSelection, } from './window.js';
+export type { WindowFactory, WindowSpec, WindowOrderInput, WindowFn, WindowSelectSpec, WindowRow, } from './window.js';
 /** The un-opted-in stub for this service — exported so callers can compare against it (#844). */
 export { NO_REDUCE } from './strategy.js';
 /**
@@ -32,3 +51,5 @@ export { NO_REDUCE } from './strategy.js';
 export type { MinMaxState } from './reducers.js';
 export type { MoneyString } from '../../via/money/branded.js';
 export type { MoneyDescriptor } from '../../via/money/descriptor.js';
+/** Named by `bindDistinctReducers`'s signature (#1347) — see #843a above. */
+export type { BucketKeyCanonicalizer } from '../../kernel/query/distinct-key.js';

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

@@ -23,6 +23,7 @@
  * `remove` per delta), without blocking the simpler "full re-run on
  * source change" that ships.
  */
+import { type BucketKeyCanonicalizer } from '../../kernel/query/distinct-key.js';
 import type { MoneyString } from '../../via/money/branded.js';
 import type { QueryField } from '../../kernel/types.js';
 /**
@@ -72,7 +73,7 @@ export interface Reducer<R, S = R> {
      * render human-readable aggregate descriptors in `dumpSchema()`.
      * Optional so third-party custom reducers are unaffected.
      */
-    readonly op?: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    readonly op?: 'count' | 'countDistinct' | 'sum' | 'avg' | 'min' | 'max' | 'median' | 'percentile' | 'variance' | 'stddev' | 'mode';
     /**
      * Field name for field-based reducers (`sum`, `avg`, `min`, `max`).
      * Absent on `count` which aggregates over record count, not a field.
@@ -88,6 +89,19 @@ export interface Reducer<R, S = R> {
      * Money-only: FX rate map (`'USD->EUR' → rate`) used with `convertTo`.
      */
     readonly fx?: Record<string, number | string>;
+    /**
+     * Quantile reducers only (#1353): the probability in `[0, 1]`. Carried as
+     * metadata so `wrapMoneyReducers` can rebuild the reducer on the exact
+     * BigInt path — a rewrite that must reproduce the SAME p, not guess one.
+     * `median` stamps `0.5`.
+     */
+    readonly p?: number;
+    /**
+     * `percentile` only (#1353): `true` when the reducer is the bounded-memory
+     * t-digest rather than the exact O(n) one. Read by `wrapMoneyReducers`,
+     * which refuses it over a money field — a t-digest is a float structure.
+     */
+    readonly approx?: boolean;
 }
 /**
  * Common options accepted by every reducer factory.
@@ -120,6 +134,47 @@ export interface ReducerOptions<TSeed = unknown> {
  * the number of non-null field values in any column.
  */
 export declare function count(opts?: ReducerOptions<number>): Reducer<number>;
+/**
+ * Multiset state behind {@link countDistinct}: canonical distinct key →
+ * how many records currently contribute it. The COUNT, not a bare Set, is
+ * what makes `remove()` correct — dropping one of three records holding
+ * `'c1'` must not drop `'c1'` from the distinct set.
+ */
+export interface CountDistinctState {
+    readonly counts: ReadonlyMap<string, number>;
+}
+/**
+ * Number of DISTINCT non-nullish values of `field` across matching records
+ * (#1347) — `COUNT(DISTINCT field)`.
+ *
+ * Distinctness is decided on the canonical index key, not on the stored
+ * string and not on any formatted rendering, so a money field's `'0100'` and
+ * `'100'` count once; see `kernel/query/distinct-key.ts` for why, and for why
+ * nullish values are excluded rather than counted as a value of their own.
+ *
+ * The canonicalizer is bound LATE, by {@link bindDistinctReducers}, at the
+ * same two points `wrapReducers` runs — a bare `countDistinct('amount')` in a
+ * spec has no way to know which collection it will be reduced against, so a
+ * constructor argument would be a footgun. Unbound, it falls back to the raw
+ * stringified key, which is exactly what a non-Via field wants.
+ *
+ * Incremental complexity: O(1) `step` and `remove`, O(1) `finalize`.
+ */
+export declare function countDistinct(field: string, opts?: ReducerOptions<number> & {
+    readonly canonicalize?: BucketKeyCanonicalizer;
+}): Reducer<number, CountDistinctState>;
+/**
+ * Rebind every `countDistinct` reducer in a spec to a Via canonicalizer.
+ *
+ * Called wherever `ViaPipeline.wrapReducers` is called — the two are the same
+ * seam, kept separate only because `wrapReducers` folds over BINDINGS (money
+ * rewriting its own `sum`) while this one is brand-agnostic: any binding that
+ * canonicalizes an index key canonicalizes a distinct key, by definition.
+ *
+ * Returns the spec unchanged when there is nothing to bind, so the common
+ * path allocates nothing.
+ */
+export declare function bindDistinctReducers<Spec>(spec: Spec, via: BucketKeyCanonicalizer | undefined): Spec;
 /**
  * Sum a numeric field across all matching records. Non-number values
  * at the field path are coerced to 0 — consumers who want a different
@@ -186,6 +241,169 @@ export declare function min(field: string, opts?: ReducerOptions<number>): Reduc
  * behavior, and the O(N) removal caveat.
  */
 export declare function max(field: string, opts?: ReducerOptions<number>): Reducer<number | null, MinMaxState>;
+/**
+ * ⚠️ MEMORY, stated once for the whole section.
+ *
+ * `variance` / `stddev` are **streaming** — three numbers of state regardless
+ * of how many records pass through, so they are free in a `.groupBy()` and
+ * free as a running window aggregate (#1349).
+ *
+ * `median`, `percentile` (exact) and `mode` are **O(n) per group**: the first
+ * two keep every contributing value, `mode` keeps one entry per distinct value.
+ * Multiplied by the `GROUPBY_MAX_CARDINALITY` ceiling (100,000 groups) that is
+ * the one place in the reduce vocabulary where a legal query can exhaust
+ * memory, so it is not "free like `sum`". Two ways out, in order of preference:
+ * narrow with `.where()` before grouping, or pass
+ * `percentile(field, p, { approx: true })` for the bounded-memory t-digest —
+ * O(compression) state per group instead of O(n), at a small, measured error.
+ *
+ * Unlike `count` / `sum` / `min` / `max`, whose states are copied on every
+ * `step`, the reducers in this section MUTATE their state in place and return
+ * it (the shape `via/money/money-reducer.ts` already uses). Copy-on-write here
+ * would make a median over a group quadratic in the group size, which is a
+ * worse bug than the inconsistency. States are built fresh by `init()` on every
+ * reduction run and never shared, so the mutation is not observable — except
+ * through `merge`, which therefore always returns a NEW state.
+ */
+/**
+ * Welford state behind {@link variance} and {@link stddev}.
+ *
+ * `m2` is the running sum of squared deviations **from the running mean**, not
+ * a sum of squares — that is the entire point. The textbook one-pass identity
+ * `(Σx² − (Σx)²/n)` subtracts two enormous nearly-equal numbers, and on an
+ * accounting column (invoice totals clustered around a large figure) the
+ * cancellation eats every significant digit: four totals just over 1e9 with a
+ * true sample variance of 30 come back as **−170.67**, so `stddev` is `NaN`.
+ * Welford never forms the large intermediate.
+ */
+export interface WelfordState {
+    /** Number of contributing records. */
+    readonly n: number;
+    /** Running arithmetic mean. */
+    readonly mean: number;
+    /** Running sum of squared deviations from `mean`. */
+    readonly m2: number;
+}
+/** Options for {@link variance} / {@link stddev}. */
+export interface DispersionOptions extends ReducerOptions<WelfordState> {
+    /**
+     * `true` → **population** dispersion (÷ n). Default `false` → **sample**
+     * dispersion (÷ n−1), which is Postgres's `var_samp` / `stddev_samp`, the
+     * unqualified spelling in every SQL dialect this library is measured
+     * against.
+     *
+     * The divisor is not cosmetic and the wrong one is a silently wrong answer,
+     * so the two disagree loudly at n = 1: sample is `null` (n−1 = 0 is not a
+     * denominator), population is `0`.
+     */
+    readonly population?: boolean;
+}
+/**
+ * Variance of a numeric field — **sample (n−1) by default**, `{ population:
+ * true }` for the n divisor. See {@link DispersionOptions}.
+ *
+ * Streaming (Welford): O(1) state, O(1) `step`, O(1) `remove`, associative
+ * `merge`. Safe as a running window aggregate.
+ *
+ * `null` for an empty result set, and `null` for a single record in sample
+ * mode (population mode returns `0`) — see `avg()` for why null rather than
+ * `NaN` or a throw.
+ *
+ * ⛔ Not available over a declared money field: dispersion is inherently a
+ * float computation, so `wrapMoneyReducers` refuses rather than let
+ * `readNumber` read a scaled-integer string as `0`.
+ */
+export declare function variance(field: string, opts?: DispersionOptions): Reducer<number | null, WelfordState>;
+/**
+ * Standard deviation of a numeric field — the square root of {@link variance},
+ * with the same divisor rule, the same empty/single-element answers, the same
+ * streaming Welford state, and the same money refusal.
+ */
+export declare function stddev(field: string, opts?: DispersionOptions): Reducer<number | null, WelfordState>;
+/**
+ * Exact quantile state: every contributing value, unsorted (sorting happens
+ * once, in `finalize`, on a copy — so a running window aggregate does not
+ * disturb the multiset it is still being appended to).
+ */
+export interface ExactQuantileState {
+    readonly kind: 'exact';
+    readonly values: number[];
+}
+/** One t-digest centroid: a weighted summary of `count` nearby values. */
+export interface Centroid {
+    readonly mean: number;
+    readonly count: number;
+}
+/**
+ * t-digest state: compressed centroids plus a small unmerged buffer.
+ *
+ * Implemented here rather than taken from npm — `hub/src/**` adds no
+ * dependency, and this one is ~60 lines.
+ */
+export interface TDigestState {
+    readonly kind: 'tdigest';
+    centroids: Centroid[];
+    buffer: number[];
+    n: number;
+}
+/** State of {@link median} / {@link percentile}; the arm depends on `approx`. */
+export type QuantileState = ExactQuantileState | TDigestState;
+/** Options for {@link percentile}. */
+export interface PercentileOptions extends ReducerOptions<number> {
+    /**
+     * `true` → bounded-memory t-digest instead of keeping every value. O(1)-ish
+     * state per group, at a small error (under 1% of the value range at every
+     * quantile on a 10k uniform scan, exact at p = 0 and p = 1).
+     *
+     * The trade is real: an approximate reducer cannot `remove()`, so it does
+     * not participate in incremental live maintenance, and it is refused over a
+     * money field.
+     */
+    readonly approx?: boolean;
+}
+/**
+ * Median of a numeric field — exactly `percentile(field, 0.5)`, and therefore
+ * **`percentile_cont`**: an even-sized input INTERPOLATES (`[1,2,3,4]` → `2.5`)
+ * rather than picking a member. See {@link quantileOf} for why only the
+ * interpolating definition ships.
+ *
+ * `null` on an empty result set. O(n) memory per group — read the memory note
+ * at the top of this section before using it under `.groupBy()`.
+ *
+ * Over a declared money field the reducer is rewritten onto the exact BigInt
+ * path; {@link moneyMedian} is the same call with the honest return type.
+ */
+export declare function median(field: string, opts?: ReducerOptions<number>): Reducer<number | null, QuantileState>;
+/**
+ * The `p` quantile of a numeric field, `p ∈ [0, 1]`, by the **`percentile_cont`
+ * (interpolating)** definition — `percentile(f, 0.9)` over `1..10` is `9.1`,
+ * not `9`. `p = 0` is the minimum and `p = 1` the maximum, exactly.
+ *
+ * Throws for a `p` outside `[0, 1]` or a non-finite one, at construction time.
+ *
+ * Exact by default and O(n) per group; pass `{ approx: true }` for the
+ * bounded-memory t-digest (see {@link PercentileOptions}).
+ */
+export declare function percentile(field: string, p: number, opts?: PercentileOptions): Reducer<number | null, QuantileState>;
+/** Frequency table behind {@link mode}: value → how many records hold it. */
+export interface ModeState {
+    readonly counts: Map<number, number>;
+}
+/**
+ * Most frequent value of a numeric field.
+ *
+ * **Tie rule: the LOWEST value wins.** Two values with equal frequency is the
+ * common case on real data, not an edge case, and the alternatives are worse:
+ * "first seen" makes the answer depend on store iteration order (so the same
+ * query answers differently after a compaction, and `merge` stops being
+ * commutative), and "all of them" changes the result TYPE based on the data.
+ * Lowest-wins is total, order-independent, and mergeable.
+ *
+ * `null` on an empty result set. O(distinct values) memory per group.
+ *
+ * ⛔ Numeric only, and not available over a declared money field.
+ */
+export declare function mode(field: string, opts?: ReducerOptions<number>): Reducer<number | null, ModeState>;
 /**
  * `sum()` for a **declared money field**, typed to match the runtime.
  *
@@ -217,6 +435,34 @@ export declare function moneyMin(field: string, opts?: ReducerOptions<number>):
  * {@link moneyMin} for the `convertTo`/`fx` and multi-currency caveats.
  */
 export declare function moneyMax(field: string, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+/**
+ * `median()` for a **declared money field**, typed `Reducer<MoneyString | null>`.
+ *
+ * Same late-binding rewrite as {@link moneySum}: `wrapMoneyReducers` swaps in a
+ * reducer that keeps the stored scaled integers as `bigint`s and interpolates
+ * the two middle values IN SCALED SPACE with half-even rounding — the money
+ * module's rounding everywhere else. Nothing round-trips through a float, so
+ * the answer is exact past `Number.MAX_SAFE_INTEGER`, where two distinct cent
+ * amounts stop being distinct numbers at all.
+ *
+ * An even-sized input can therefore land on a half unit (`0.10` and `0.15` →
+ * `12.5` cents): that is the one place money median rounds, and it rounds
+ * half-to-even (`0.12`), never away from zero.
+ *
+ * In multi-currency mode the runtime returns a per-currency map, as `moneyMin`
+ * does; an empty result is `null` in fixed mode and `{}` in multi.
+ */
+export declare function moneyMedian(field: string, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+/**
+ * `percentile()` for a declared money field — see {@link moneyMedian} for the
+ * exactness and rounding contract, which is the same code path (`median` is
+ * `p = 0.5`). The interpolation weight is taken from `p`'s DECIMAL spelling as
+ * an exact rational, so `p = 0.9` is `9/10`, not the float nearest to it.
+ *
+ * There is deliberately no `approx` here: the t-digest is a float structure and
+ * `wrapMoneyReducers` refuses it over a money field.
+ */
+export declare function moneyPercentile(field: string, p: number, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
 /**
  * Typed builder passed to the `aggregate(b => spec)` overload.
  *
@@ -234,6 +480,7 @@ export declare function moneyMax(field: string, opts?: ReducerOptions<number>):
  */
 export interface ReducerBuilder<T, S extends keyof T = never, M extends keyof T & string = never> {
     count(opts?: ReducerOptions<number>): Reducer<number>;
+    countDistinct(field: QueryField<T, S>, opts?: ReducerOptions<number>): Reducer<number, CountDistinctState>;
     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;
@@ -241,9 +488,16 @@ export interface ReducerBuilder<T, S extends keyof T = never, M extends keyof T
     }>): 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>;
+    median<F extends QueryField<T, S>>(field: F, opts?: ReducerOptions<number>): [F] extends [M] ? Reducer<MoneyString | null> : ReturnType<typeof median>;
+    percentile<F extends QueryField<T, S>>(field: F, p: number, opts?: PercentileOptions): [F] extends [M] ? Reducer<MoneyString | null> : ReturnType<typeof percentile>;
+    variance(field: QueryField<T, S>, opts?: DispersionOptions): ReturnType<typeof variance>;
+    stddev(field: QueryField<T, S>, opts?: DispersionOptions): ReturnType<typeof stddev>;
+    mode(field: QueryField<T, S>, opts?: ReducerOptions<number>): ReturnType<typeof mode>;
     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>;
+    moneyMedian(field: QueryField<T, S>, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+    moneyPercentile(field: QueryField<T, S>, p: number, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
 }
 /**
  * Shared runtime instance for the `aggregate(b => spec)` builder form.

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

@@ -9,11 +9,20 @@
  *     existing `Query.toArray()` / `.first()` / `.count()` style.
  *   - `.live(): LiveReduction<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.
+ *     a change. Since #1341 the RECORD SET it reduces is maintained
+ *     incrementally upstream (see `kernel/query/live/incremental.ts`), so a
+ *     change costs one predicate evaluation instead of a full scan — but
+ *     the reducers themselves still run a complete `init → step* →
+ *     finalize` fold over that set. Driving `remove()` per delta (the
+ *     reducer protocol admits it) would make a change O(1) rather than
+ *     O(matches); it is deliberately NOT wired, because folding the same
+ *     array a re-run would fold makes the incremental value bit-identical
+ *     to the eager one, while inverting a float `sum` does not.
+ *
+ * `GroupedReduction.live()` goes one step further (#1341, grouped half): its
+ * BUCKETS are maintained too, so a change re-folds only the groups it touched.
+ * See `incremental-group.ts`. The reasoning above is why neither path inverts
+ * a reducer state.
  *
  * The `Reduction<R>` wrapper is deliberately tiny — it exists so
  * `.aggregate(spec)` can be chained with either `.run()` or `.live()`
@@ -27,6 +36,8 @@
  * surface with plain record arrays, without spinning up a Collection.
  */
 import type { Reducer } from './reducers.js';
+import type { SourceChange } from '../../kernel/query/live/incremental.js';
+import type { HydrationGate } from '../../kernel/query/hydration.js';
 /**
  * A named set of reducers, keyed by output field name. Each key
  * becomes a field on the aggregated result.
@@ -105,7 +116,14 @@ export interface LiveReduction<R> {
  * query's source and wires them into a single re-run trigger.
  */
 export interface ReductionUpstream {
-    subscribe(cb: () => void): () => void;
+    /**
+     * `cb` MAY be handed the delta that caused the notification (#1341), which
+     * is what lets `GroupedReduction.live()` patch the buckets a change touches
+     * instead of re-grouping. Calling it with NO argument is always valid and
+     * always correct — it means "something changed, I can't say what", and every
+     * consumer answers that with a full re-run.
+     */
+    subscribe(cb: (change?: SourceChange) => void): () => void;
 }
 /**
  * Chainable wrapper returned by `Query.aggregate(spec)`. Holds the
@@ -127,7 +145,21 @@ export declare class Reduction<R> {
     private readonly executeRecords;
     private readonly spec;
     private readonly upstreams;
-    constructor(executeRecords: () => readonly unknown[], spec: ReduceSpec, upstreams: readonly ReductionUpstream[]);
+    /**
+     * #1414 — the backing collection's cold gate, when the reduction came
+     * from a collection-backed query. `run()` is SYNCHRONOUS, so a reduction
+     * over a never-loaded collection used to answer `0` / `null` with total
+     * confidence — the shape a guard's Σ-over-siblings invariant takes.
+     */
+    private readonly gate?;
+    constructor(executeRecords: () => readonly unknown[], spec: ReduceSpec, upstreams: readonly ReductionUpstream[], 
+    /**
+     * #1414 — the backing collection's cold gate, when the reduction came
+     * from a collection-backed query. `run()` is SYNCHRONOUS, so a reduction
+     * over a never-loaded collection used to answer `0` / `null` with total
+     * confidence — the shape a guard's Σ-over-siblings invariant takes.
+     */
+    gate?: HydrationGate | undefined);
     /**
      * Execute the query and reduce the results synchronously.
      * Returns the reduced shape matching the spec — e.g. a spec of
@@ -146,12 +178,11 @@ export declare class Reduction<R> {
      * 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.
+     * re-reduction over the matching records — but since #1341 that record
+     * set is itself maintained per delta rather than re-scanned, so the cost
+     * is O(matches) rather than O(collection). Reducer-level `remove()`
+     * (O(1) per delta for sum/count/avg) remains unwired; see the file
+     * docstring for why folding beats inverting here.
      */
     live(): LiveReduction<R>;
 }