@noy-db/hub 0.4.0-pre.4 → 0.4.0-pre.6

package/dist/with-formula/derivations/dispatch.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Derivation dispatch, lifted out of the kernel spine (#842 part b).
+ *
+ * `Collection` carried ~380 lines of dispatch logic that belongs to the
+ * derivation service, not to the always-on kernel. These are free functions
+ * taking an explicit context so the spine keeps only a thin delegator.
+ *
+ * ## How the spine reaches this module
+ *
+ * By dynamic `import()`, never a static one. `check-architecture.mjs`'s
+ * `port-layering` check forbids the spine from statically importing a
+ * `with-*` service; `collection.ts` is grandfathered for ten
+ * `with-formula/*` specifiers, but that list is frozen per file and a new
+ * one is a violation. A dynamic import is the sanctioned S4 gate recipe, and
+ * it keeps this chunk out of the floor bundle for consumers who never fire a
+ * derivation.
+ *
+ * The `Collection` type reference below points back at the spine. That is
+ * inward (service → kernel) and so allowed, and it is TYPE-ONLY — erased at
+ * build, so no runtime cycle exists.
+ *
+ * @internal
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { TxContext } from '../../with-commit/tx/transaction.js';
+import type { DerivationRegistry } from './registry.js';
+import type { ReadOnlyVaultFacade } from '../../with-audit/guards/types.js';
+import type { Collection } from '../../kernel/collection.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { EncryptedEnvelope } from '../../kernel/types.js';
+import type { ledgerAuditHook, WaveContext } from '../../kernel/via/dispatch.js';
+/** The per-write dispatch context threaded into `putDerivedOutput`. */
+interface DispatchCtx {
+    emit: (e: string, p: unknown) => void;
+    source: {
+        readonly collection: string;
+        readonly id: string;
+    };
+    audit: ReturnType<typeof ledgerAuditHook>;
+}
+/**
+ * What the dispatchers need from the collection that owns them. Passing this
+ * explicitly is what lets the logic live outside the class.
+ */
+export interface DerivationDeleteCtx {
+    readonly derivationSource: {
+        registry(): DerivationRegistry;
+        getCollection(name: string): Collection<Record<string, unknown>>;
+        getActiveTxContext(): TxContext | null;
+        getReadOnlyFacade(): ReadOnlyVaultFacade;
+    };
+    /** The collection the delete happened in. */
+    readonly collectionName: string;
+    readonly adapter: NoydbStore;
+    readonly vault: string;
+    readonly getDEK: (collectionName: string) => Promise<EnclaveKey>;
+    readonly storeCiphertext: boolean;
+}
+/**
+ * Erase the derived rows a deleted source record fanned out to, and drop the
+ * fan-out sidecars that recorded them.
+ *
+ * @param eraseRecordShapeToo also erase same-id `shape: 'record'` outputs.
+ *   Restricted to a source-triggered strategy writing into a DIFFERENT
+ *   collection — the self-denorm case would re-delete the record just
+ *   tombstoned, and triggerBy/sibling strategies derive under a different id.
+ * @returns rows ACTUALLY deleted, not edges visited (#622).
+ */
+export declare function dispatchArrayDerivationsOnDelete(ctx: DerivationDeleteCtx, id: string, eraseRecordShapeToo?: boolean): Promise<number>;
+/** Adds what the on-write derivation dispatch needs beyond the delete path. */
+export interface DerivationDispatchCtx extends DerivationDeleteCtx {
+    /** Via pipeline, for decoding the stored form back to canonical money shape. */
+    readonly via: {
+        canonicalizeStored(r: Record<string, unknown>): Record<string, unknown>;
+    } | undefined;
+    /** Recompute a rollup aggregate onto a parent. Stays on the spine — it walks collections. */
+    readonly recomputeRollup: (spec: any, parentId: string, source: {
+        readonly collection: string;
+        readonly id: string;
+    }, wave?: WaveContext) => Promise<unknown>;
+    /** Builds the per-write dispatch context threaded into `putDerivedOutput`. */
+    readonly dispatchCtx: (source: {
+        readonly collection: string;
+        readonly id: string;
+    }) => DispatchCtx;
+    /** Registers a write on the active transaction for rollback. */
+    readonly trackPut: (txCtx: TxContext, collectionName: string, id: string, priorEnvelope: EncryptedEnvelope | null) => void;
+}
+/**
+ * Fire registered derivation strategies for this source collection.
+ *
+ * Eager mode runs `derive` inline and writes each output; lazy mode records a
+ * stale mark for cold-session recompute. Rollups are handled here rather than
+ * by the executor — a write to the child recomputes the parent aggregate, and
+ * a write to the parent recomputes its own.
+ */
+export declare function dispatchDerivations(ctx: DerivationDispatchCtx, id: string, record: Record<string, unknown>, version: number, wave?: WaveContext): Promise<void>;
+export {};

package/dist/with-formula/materialized-views/dispatch.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Materialized-view dispatch, lifted out of the kernel spine (#842 part b).
+ *
+ * Reached from `Collection` by dynamic `import()` only — `port-layering`
+ * forbids a static spine→`with-*` import, and rejects a type-only one too
+ * (it scans import statements, not their erasure). See
+ * `with-formula/derivations/dispatch.ts` for the same note.
+ *
+ * The `Collection` reference below is TYPE-ONLY and points inward
+ * (service → kernel), so it is both allowed and erased at build.
+ *
+ * @internal
+ */
+import type { TxContext } from '../../with-commit/tx/transaction.js';
+import type { Collection } from '../../kernel/collection.js';
+import type { ledgerAuditHook, WaveContext } from '../../kernel/via/dispatch.js';
+import type { MaterializedViewRegistry } from './registry.js';
+import type { MVQueryContext } from './types.js';
+/** The per-write dispatch context the MV executor threads through. */
+interface DispatchCtx {
+    emit: (e: string, p: unknown) => void;
+    source: {
+        readonly collection: string;
+        readonly id: string;
+    };
+    audit: ReturnType<typeof ledgerAuditHook>;
+}
+/** What the MV dispatchers need from the collection that owns them. */
+export interface MvDispatchCtx {
+    readonly materializedViewSource: {
+        registry(): MaterializedViewRegistry;
+        getCollection(name: string): Collection<any>;
+        getActiveTxContext(): TxContext | null;
+        getQueryContext(): MVQueryContext;
+    };
+    /** The collection the delete happened in. */
+    readonly collectionName: string;
+    /** Builds the per-write dispatch context the executor threads through. */
+    readonly dispatchCtx: (source: {
+        readonly collection: string;
+        readonly id: string;
+    }) => DispatchCtx;
+}
+/**
+ * Fire every MV whose dependency set includes this collection, on write.
+ *
+ * Skips entirely when the record being written is itself an MV-emitted row
+ * (it carries `_materializedFrom`) — a defensive guard against missed cycle
+ * detection.
+ *
+ * @param wave #638 Task 4 — the sync/cutover/restore dispatch wave. An eager
+ *   MV already refreshed in this wave is skipped, deduped per target on the
+ *   spec name.
+ */
+export declare function dispatchMaterializedViews(ctx: MvDispatchCtx, id: string, record: Record<string, unknown>, wave?: WaveContext): Promise<void>;
+/**
+ * Mirror of {@link dispatchMaterializedViews} for the delete/forget path. There is
+ * no `_materializedFrom` skip — the record is gone — and the `internal` gate
+ * at `_doDelete` is the recursion guard.
+ *
+ * @returns rows TOMBSTONED across every MV sourced here (#638 T6). Eager and
+ *   lazy/manual `invalidateMVAtRest` purges both contribute (#761 item 1,
+ *   previously eager-only): lazy persists a stale mark for cold-session
+ *   recompute, manual serves empty until `refreshView()`.
+ *   `residueUndecodable` / `residueDeclined` (#776/#785) carry
+ *   `outputCollection:id` entries whose ownership stamp `invalidateMVAtRest`
+ *   could not decode, respectively decoded and stamp-matched but declined to
+ *   erase — surfaced, not erased.
+ */
+export declare function dispatchMaterializedViewsOnDelete(ctx: MvDispatchCtx, id: string): Promise<{
+    deleted: number;
+    residueUndecodable: string[];
+    residueDeclined: string[];
+}>;
+export {};

package/dist/with-formula/materialized-views/types.d.ts

@@ -1,7 +1,7 @@
 import type { Query } from '../../kernel/query/builder.js';
 import type { Collection } from '../../kernel/collection.js';
-import type { AggregateSpec, Aggregation } from '../../with-lookup/aggregate/aggregation.js';
-import type { GroupedAggregation } from '../../with-lookup/aggregate/groupby.js';
+import type { ReduceSpec, Reduction } from '../../with-lookup/reduce/reduction.js';
+import type { GroupedReduction } from '../../with-lookup/reduce/groupby.js';
 import type { JoinStrategy } from '../../kernel/query/join.js';
 import type { MoneyDescriptor } from '../../via/money/descriptor.js';
 import type { I18nTextDescriptor } from '../../via/i18n/core.js';
@@ -207,7 +207,7 @@ export interface MaterializedViewStrategy<TRow extends Record<string, unknown>>
      * (multi-source UNION). Registration throws
      * `MaterializedViewConfigError` if both are set or neither is set.
      */
-    query?: (db: MVQueryContext) => Query<TRow> | Aggregation<TRow> | GroupedAggregation<TRow>;
+    query?: (db: MVQueryContext) => Query<TRow> | Reduction<TRow> | GroupedReduction<TRow>;
     /**
      * UNION-form sources: an explicit list of sibling collections
      * that contribute rows to a single MV. Each arm's `map` projects a
@@ -261,14 +261,14 @@ export interface MaterializedViewStrategy<TRow extends Record<string, unknown>>
      */
     groupBy?: string | ReadonlyArray<string>;
     /**
-     * Aggregation spec for UNION mode. Applied per-group after
+     * Reduction spec for UNION mode. Applied per-group after
      * {@link groupBy} buckets the concatenated mapped-row stream from
-     * {@link unionSources}. Same shape as the `AggregateSpec` passed to
+     * {@link unionSources}. Same shape as the `ReduceSpec` passed to
      * `Query.aggregate()`.
      *
      * UNION-mode only. Ignored if {@link query} is set.
      */
-    aggregate?: AggregateSpec;
+    aggregate?: ReduceSpec;
     /**
      * Money descriptors for the UNION-mode aggregate, keyed by the
      * OUTPUT/intermediate field name as it appears in the mapped row and
@@ -325,7 +325,7 @@ export interface MaterializedViewStrategy<TRow extends Record<string, unknown>>
     rowKey: (row: TRow) => string;
     /**
      * Explicit source collections. Required when `query()` returns
-     * an `Aggregation` or `GroupedAggregation` rather than a `Query<T>`
+     * an `Reduction` or `GroupedReduction` rather than a `Query<T>`
      * — the dependency analyzer can't introspect through `groupBy().aggregate()`
      * back to the source. Optional for plain `Query<T>` results — the
      * analyzer extracts dependencies automatically from the query plan.

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

@@ -25,3 +25,5 @@ export { PersistedCollectionIndex, IDX_PREFIX, COMPOSITE_DELIMITER, encodeIdxId,
 export type { OrderedEntry, IngestRow, PersistedIndexDef, } from './persisted-indexes.js';
 export { LazyQuery } from './lazy-builder.js';
 export type { LazyQuerySource, LazyOrderBy } from './lazy-builder.js';
+/** The un-opted-in stub for this service — exported so callers can compare against it (#844). */
+export { NO_INDEXING } from './strategy.js';

package/dist/with-lookup/{aggregate → reduce}/active.d.ts

@@ -1,26 +1,26 @@
 /**
- * Active aggregate strategy factory. Calling `withAggregate()` returns
- * an `AggregateStrategy` whose methods construct real `Aggregation` /
+ * Active aggregate strategy factory. Calling `withReduce()` returns
+ * an `ReduceStrategy` whose methods construct real `Reduction` /
  * `GroupedQuery` instances and run the streaming reducer protocol.
  *
- * This module is only reachable through the `@noy-db/hub/aggregate`
+ * This module is only reachable through the `@noy-db/hub/reduce`
  * subpath — a consumer that never imports the subpath ships none of
  * this (ESM tree-shaking + hub's `"sideEffects": false`).
  */
-import type { AggregateStrategy } from './strategy.js';
+import type { ReduceStrategy } from './strategy.js';
 /**
  * Build the default aggregate strategy. Pass into
- * `createNoydb({ aggregateStrategy: withAggregate() })` to light up
+ * `createNoydb({ reduceStrategy: withReduce() })` to light up
  * `.aggregate()` and `.groupBy()` on `Query` and `ScanBuilder`.
  *
  * @example
  * ```ts
  * import { createNoydb } from '@noy-db/hub'
- * import { withAggregate, sum, count } from '@noy-db/hub/aggregate'
+ * import { withReduce, sum, count } from '@noy-db/hub/reduce'
  *
  * const db = await createNoydb({
  *   store, user, secret,
- *   aggregateStrategy: withAggregate(),
+ *   reduceStrategy: withReduce(),
  * })
  *
  * const totals = invoices.query()
@@ -30,4 +30,4 @@ import type { AggregateStrategy } from './strategy.js';
  *   .run()
  * ```
  */
-export declare function withAggregate(): AggregateStrategy;
+export declare function withReduce(): ReduceStrategy;

package/dist/with-lookup/{aggregate → reduce}/groupby.d.ts

@@ -58,7 +58,7 @@
  * groupBy doesn't need its own seam for the moment, because it
  * delegates to the reducer protocol for all per-bucket state.
  */
-import type { AggregateSpec, AggregateResult, AggregationUpstream, LiveAggregation } from './aggregation.js';
+import type { ReduceSpec, ReduceResult, ReductionUpstream, LiveReduction } from './reduction.js';
 import type { ReducerBuilder } from './reducers.js';
 import type { MoneyDescriptor } from '../../via/money/descriptor.js';
 import type { ViaPipeline } from '../../kernel/via/pipeline.js';
@@ -78,7 +78,7 @@ export declare const GROUPBY_MAX_CARDINALITY = 100000;
  */
 export declare function resetGroupByWarnings(): void;
 /**
- * Result row shape for a grouped aggregation. Each row carries the
+ * Result row shape for a grouped reduction. Each row carries the
  * group key value under the grouping field name plus every reducer
  * output from the spec.
  *
@@ -116,7 +116,7 @@ export type GroupedRowN<F extends readonly string[], R> = {
  */
 declare abstract class GroupedQueryBase {
     protected readonly executeRecords: () => readonly unknown[];
-    protected readonly upstreams: readonly AggregationUpstream[];
+    protected readonly upstreams: readonly ReductionUpstream[];
     /**
      * Optional dict label resolver attached by the query builder when
      * the grouping field is a dictKey. Variadic groupings always pass
@@ -137,7 +137,7 @@ declare abstract class GroupedQueryBase {
      * `[field]`.
      */
     protected readonly fields: readonly string[];
-    constructor(executeRecords: () => readonly unknown[], fieldOrFields: string | readonly string[], upstreams: readonly AggregationUpstream[], 
+    constructor(executeRecords: () => readonly unknown[], fieldOrFields: string | readonly string[], upstreams: readonly ReductionUpstream[], 
     /**
      * Optional dict label resolver attached by the query builder when
      * the grouping field is a dictKey. Variadic groupings always pass
@@ -152,21 +152,21 @@ declare abstract class GroupedQueryBase {
      */
     via?: ViaPipeline | undefined);
     /** Apply Via-aware reducer rewriting (e.g. money) when the source declares one. */
-    protected wrapSpec<Spec extends AggregateSpec>(spec: Spec): Spec;
+    protected wrapSpec<Spec extends ReduceSpec>(spec: Spec): Spec;
 }
 /**
  * Chainable wrapper returned by `Query.groupBy(field)`. Terminates
- * with `.aggregate(spec)` which returns a `GroupedAggregation`.
+ * with `.aggregate(spec)` which returns a `GroupedReduction`.
  *
  * Kept minimal — the only operation on a grouped query is
- * aggregation. Ordering, limiting, and further filtering belong on
+ * 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.
  */
 export declare class GroupedQuery<T, F extends string, S extends keyof T = never, M extends keyof T & string = never> extends GroupedQueryBase {
     /**
-     * Build a grouped aggregation. Returns a `GroupedAggregation`
+     * Build a grouped reduction. Returns a `GroupedReduction`
      * 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.
@@ -178,8 +178,8 @@ export declare class GroupedQuery<T, F extends string, S extends keyof T = never
      * declared `moneyFields` (`M`) member return a `MoneyString`. The
      * bare-spec overload is preserved for backward compatibility.
      */
-    aggregate<Spec extends AggregateSpec>(spec: Spec): GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>>;
-    aggregate<Spec extends AggregateSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>>;
+    aggregate<Spec extends ReduceSpec>(spec: Spec): GroupedReduction<GroupedRow<F, ReduceResult<Spec>>>;
+    aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): GroupedReduction<GroupedRow<F, ReduceResult<Spec>>>;
 }
 /**
  * Variadic-keyed sibling of `GroupedQuery<T, F>`. Constructed by the
@@ -187,12 +187,12 @@ export declare class GroupedQuery<T, F extends string, S extends keyof T = never
  * identical — only the type-level result-row narrowing differs.
  */
 export declare class GroupedQueryN<T, F extends readonly string[], S extends keyof T = never, M extends keyof T & string = never> extends GroupedQueryBase {
-    aggregate<Spec extends AggregateSpec>(spec: Spec): GroupedAggregation<GroupedRowN<F, AggregateResult<Spec>>>;
-    aggregate<Spec extends AggregateSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): GroupedAggregation<GroupedRowN<F, AggregateResult<Spec>>>;
+    aggregate<Spec extends ReduceSpec>(spec: Spec): GroupedReduction<GroupedRowN<F, ReduceResult<Spec>>>;
+    aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): GroupedReduction<GroupedRowN<F, ReduceResult<Spec>>>;
 }
 /**
  * Execute the group-and-reduce pipeline. Pure function over a
- * record array and a spec — shared by `GroupedAggregation.run()`
+ * record array and a spec — shared by `GroupedReduction.run()`
  * and the live-mode refresh path. Exported for tests and for any
  * future `scan().groupBy().aggregate()` reuse.
  *
@@ -201,10 +201,10 @@ export declare class GroupedQueryN<T, F extends readonly string[], S extends key
  * bucket would be created — the consumer doesn't have to wait for
  * the full partition to materialize before the error fires.
  */
-export declare function groupAndReduce<R>(records: readonly unknown[], fieldOrFields: string | readonly string[], spec: AggregateSpec, moneyFields?: Record<string, MoneyDescriptor>): R[];
+export declare function groupAndReduce<R>(records: readonly unknown[], fieldOrFields: string | readonly string[], spec: ReduceSpec, moneyFields?: Record<string, MoneyDescriptor>): R[];
 /**
- * Grouped aggregation wrapper — the `.groupBy(field).aggregate(spec)`
- * terminal. Shape mirrors `Aggregation<R>` from aggregate.ts: two
+ * Grouped reduction wrapper — the `.groupBy(field).aggregate(spec)`
+ * terminal. Shape mirrors `Reduction<R>` from aggregate.ts: two
  * terminals (`.run()` and `.live()`), spec bound at construction
  * time, upstreams collected for live mode.
  *
@@ -212,7 +212,7 @@ export declare function groupAndReduce<R>(records: readonly unknown[], fieldOrFi
  * grouped row), and the terminals return `R[]` — one row per
  * bucket.
  */
-export declare class GroupedAggregation<R> {
+export declare class GroupedReduction<R> {
     private readonly executeRecords;
     private readonly spec;
     private readonly upstreams;
@@ -222,7 +222,7 @@ export declare class GroupedAggregation<R> {
      */
     private readonly dictLabelResolver?;
     private readonly fields;
-    constructor(executeRecords: () => readonly unknown[], fields: string | readonly string[], spec: AggregateSpec, upstreams: readonly AggregationUpstream[], 
+    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.
@@ -260,10 +260,10 @@ export declare class GroupedAggregation<R> {
         fallback?: string | readonly string[];
     }): Promise<R[]>;
     /**
-     * Build a reactive `LiveAggregation<R[]>` that re-runs the full
+     * 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 `Aggregation.live()` — the implementation delegates to the
+     * as `Reduction.live()` — the implementation delegates to the
      * same `LiveAggregationImpl` class by threading a fresh
      * recompute closure through the existing constructor.
      *
@@ -275,6 +275,6 @@ export declare class GroupedAggregation<R> {
      *
      * Always call `live.stop()` when finished.
      */
-    live(): LiveAggregation<R[]>;
+    live(): LiveReduction<R[]>;
 }
 export {};

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

@@ -0,0 +1,34 @@
+/**
+ * @noy-db/hub/reduce — opt-in reduction + groupBy service.
+ *
+ * @category capability
+ *
+ * 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)
+ *
+ * The root barrel (`@noy-db/hub`) and the `@noy-db/hub/query` subpath
+ * continue to re-export the same symbols for backward compatibility
+ * with consumers written before the relocation. New code should
+ * prefer this subpath.
+ */
+export { withReduce } from './active.js';
+export type { ReduceStrategy } 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';
+/** The un-opted-in stub for this service — exported so callers can compare against it (#844). */
+export { NO_REDUCE } from './strategy.js';
+/**
+ * Types named by this entry's own signatures (#843a). `min`/`max` return a
+ * `MinMaxState`, and the money reducers speak `MoneyString`; both must be
+ * nameable from the entry that exports the functions, or a caller can invoke
+ * them and cannot annotate the result.
+ */
+export type { MinMaxState } from './reducers.js';
+export type { MoneyString } from '../../via/money/branded.js';
+export type { MoneyDescriptor } from '../../via/money/descriptor.js';

package/dist/with-lookup/{aggregate → reduce}/reducers.d.ts

@@ -1,12 +1,12 @@
 /**
- * Aggregation reducers for the query DSL.
+ * Reduction 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
+ * half of  constraint #2. When partition-aware reduction
  * lands, the seed carries the previous partition's running total into
  * the next partition without requiring a protocol change.
  *
@@ -19,7 +19,7 @@
  * 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
+ * optimization (delta-aware `LiveReduction` applies `step` or
  * `remove` per delta), without blocking the simpler "full re-run on
  * source change" that ships.
  */
@@ -30,19 +30,19 @@ import type { QueryField } from '../../kernel/types.js';
  * `.aggregate()` spec.
  *
  * Type parameters:
- *   - `R` — user-visible result type (what the aggregation returns
+ *   - `R` — user-visible result type (what the reduction 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()`
+ * called once per reduction run to build the initial state; `step()`
  * folds a record into the state; `remove()` (optional) un-folds a
  * record, enabling incremental live maintenance; `finalize()` reads
  * the final answer out of the state at the end of the run.
  */
 export interface Reducer<R, S = R> {
-    /** Build the initial state for a fresh aggregation run. */
+    /** Build the initial state for a fresh reduction run. */
     init(): S;
     /** Fold a record into the state. Returns the new state. */
     step(state: S, record: unknown): S;
@@ -63,7 +63,7 @@ export interface Reducer<R, S = R> {
      * Combine two independent partial states into one (then `finalize` once).
      * Optional. MUST be associative + commutative with `init()` as identity.
      * Never merge finalized results — only states. Enables parallel /
-     * hierarchical aggregation (e.g. cross-shard or advisor→firm rollup).
+     * hierarchical reduction (e.g. cross-shard or advisor→firm rollup).
      */
     merge?(a: S, b: S): S;
     /**
@@ -94,10 +94,10 @@ export interface Reducer<R, S = R> {
  *
  * `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
+ * #2 (partition-aware reduction seam). In, partitioned
+ * reductions 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.
+ * without re-reducing closed partitions.
  *
  * always uses `init()` with the factory's zero value, regardless
  * of whether `seed` was passed. Do not remove the parameter — that's

package/dist/with-lookup/{aggregate/aggregation.d.ts → reduce/reduction.d.ts}

@@ -1,13 +1,13 @@
 /**
  * Aggregate execution — the runtime behind `Query.aggregate()`.
  *
- * takes an `AggregateSpec` (a record of named reducers
+ * takes an `ReduceSpec` (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
+ *   - `.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()`)
@@ -15,7 +15,7 @@
  *     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
+ * The `Reduction<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
@@ -39,9 +39,9 @@ import type { Reducer } from './reducers.js';
  * }
  * ```
  */
-export type AggregateSpec = Readonly<Record<string, Reducer<unknown, unknown>>>;
+export type ReduceSpec = Readonly<Record<string, Reducer<unknown, unknown>>>;
 /**
- * Map an `AggregateSpec` to its reduced result shape — each key
+ * Map an `ReduceSpec` 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 }`.
@@ -50,26 +50,26 @@ export type AggregateSpec = Readonly<Record<string, Reducer<unknown, unknown>>>;
  * each `Reducer<R, _>`. The `infer` captures the user-visible result
  * type, discarding the internal state type `S`.
  */
-export type AggregateResult<Spec extends AggregateSpec> = {
+export type ReduceResult<Spec extends ReduceSpec> = {
     [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.
+ * Called by `Reduction.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.
  */
-export declare function reduceRecords<Spec extends AggregateSpec>(records: readonly unknown[], spec: Spec): AggregateResult<Spec>;
+export declare function reduceRecords<Spec extends ReduceSpec>(records: readonly unknown[], spec: Spec): ReduceResult<Spec>;
 /**
- * A minimal reactive primitive for aggregation results.
+ * A minimal reactive primitive for reduction 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
+ * their own primitive. Intentionally NOT a Promise — reductions
  * have a well-defined "current value" at every instant, and the
  * reactive consumer wants to read that value synchronously.
  *
@@ -86,7 +86,7 @@ export declare function reduceRecords<Spec extends AggregateSpec>(records: reado
  * Always call `stop()` when done; Vue's `onUnmounted` is the
  * canonical place. Raw consumers must do it themselves.
  */
-export interface LiveAggregation<R> {
+export interface LiveReduction<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. */
@@ -97,14 +97,14 @@ export interface LiveAggregation<R> {
     stop(): void;
 }
 /**
- * Upstream change-notification hook for live aggregation.
+ * Upstream change-notification hook for live reduction.
  *
  * 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
+ * function. The `Reduction` wrapper collects upstreams from the
  * query's source and wires them into a single re-run trigger.
  */
-export interface AggregationUpstream {
+export interface ReductionUpstream {
     subscribe(cb: () => void): () => void;
 }
 /**
@@ -120,14 +120,14 @@ export interface AggregationUpstream {
  * `.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
+ * (`reduceRun` / `reduceLive`) that would be harder to
  * discover.
  */
-export declare class Aggregation<R> {
+export declare class Reduction<R> {
     private readonly executeRecords;
     private readonly spec;
     private readonly upstreams;
-    constructor(executeRecords: () => readonly unknown[], spec: AggregateSpec, upstreams: readonly AggregationUpstream[]);
+    constructor(executeRecords: () => readonly unknown[], spec: ReduceSpec, upstreams: readonly ReductionUpstream[]);
     /**
      * Execute the query and reduce the results synchronously.
      * Returns the reduced shape matching the spec — e.g. a spec of
@@ -136,7 +136,7 @@ export declare class Aggregation<R> {
      */
     run(): R;
     /**
-     * Build a reactive `LiveAggregation<R>` that re-runs the reduction
+     * Build a reactive `LiveReduction<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()`.
@@ -153,14 +153,14 @@ export declare class Aggregation<R> {
      * correct, reactive values today; future PRs can switch to
      * delta-based maintenance without changing this API.
      */
-    live(): LiveAggregation<R>;
+    live(): LiveReduction<R>;
 }
 /**
- * Build a `LiveAggregation<V>` from a recompute closure and a list
+ * Build a `LiveReduction<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()`.
  */
-export declare function buildLiveAggregation<V>(recompute: () => V, upstreams: readonly AggregationUpstream[]): LiveAggregation<V>;
+export declare function buildLiveReduction<V>(recompute: () => V, upstreams: readonly ReductionUpstream[]): LiveReduction<V>;