@noy-db/hub 0.1.0-pre.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# @noy-db/hub
+
+> Zero-knowledge, offline-first, encrypted document store — core library.
+
+[![npm](https://img.shields.io/npm/v/@noy-db/hub.svg)](https://www.npmjs.com/package/@noy-db/hub)
+[![license](https://img.shields.io/npm/l/@noy-db/hub.svg)](https://github.com/vLannaAi/noy-db/blob/main/LICENSE)
+
+Part of [**noy-db**](https://github.com/vLannaAi/noy-db) — *"None Of Your Damn Business"*. This is the **core library** — install this first, then pair it with a storage backend.
+
+## Install
+
+Every noy-db app needs `@noy-db/hub` plus at least one storage backend (`to-*`). Everything else is optional.
+
+```bash
+pnpm add @noy-db/hub @noy-db/to-memory
+```
+
+### Pick a storage backend — [`@noy-db/to-*`](https://www.npmjs.com/search?q=%40noy-db%2Fto-)
+
+| Package | Use for |
+|---------|---------|
+| [`to-memory`](https://www.npmjs.com/package/@noy-db/to-memory) | Tests, prototypes, ephemeral data |
+| [`to-file`](https://www.npmjs.com/package/@noy-db/to-file) | Local disk, USB stick |
+| [`to-browser-idb`](https://www.npmjs.com/package/@noy-db/to-browser-idb) | Browser IndexedDB (atomic CAS) |
+| [`to-browser-local`](https://www.npmjs.com/package/@noy-db/to-browser-local) | Browser localStorage |
+| [`to-aws-dynamo`](https://www.npmjs.com/package/@noy-db/to-aws-dynamo) | DynamoDB single-table |
+| [`to-aws-s3`](https://www.npmjs.com/package/@noy-db/to-aws-s3) | S3 object store |
+| [`to-cloudflare-d1`](https://www.npmjs.com/package/@noy-db/to-cloudflare-d1) | Edge SQLite via Workers |
+| [`to-cloudflare-r2`](https://www.npmjs.com/package/@noy-db/to-cloudflare-r2) | Zero-egress object storage |
+| [`to-postgres`](https://www.npmjs.com/package/@noy-db/to-postgres) | PostgreSQL `jsonb` |
+| [`to-mysql`](https://www.npmjs.com/package/@noy-db/to-mysql) | MySQL / MariaDB `JSON` |
+| [`to-sqlite`](https://www.npmjs.com/package/@noy-db/to-sqlite) | better-sqlite3 / node:sqlite / bun:sqlite |
+| [`to-supabase`](https://www.npmjs.com/package/@noy-db/to-supabase) | Supabase Postgres + Storage |
+| [`to-turso`](https://www.npmjs.com/package/@noy-db/to-turso) | Hosted libSQL (replicated SQLite) |
+| [`to-webdav`](https://www.npmjs.com/package/@noy-db/to-webdav) | Nextcloud / ownCloud |
+| [`to-ssh`](https://www.npmjs.com/package/@noy-db/to-ssh) | Remote SFTP backend |
+| [`to-smb`](https://www.npmjs.com/package/@noy-db/to-smb) | Windows shares / NAS |
+| [`to-nfs`](https://www.npmjs.com/package/@noy-db/to-nfs) | NFS mounts |
+| [`to-icloud`](https://www.npmjs.com/package/@noy-db/to-icloud) | iCloud Drive (.icloud-aware) |
+| [`to-drive`](https://www.npmjs.com/package/@noy-db/to-drive) | Google Drive bundle |
+| [`to-meter`](https://www.npmjs.com/package/@noy-db/to-meter) | Wrap any store with metrics |
+| [`to-probe`](https://www.npmjs.com/package/@noy-db/to-probe) | Diagnostic suitability test |
+
+### Optional ecosystem
+
+- **Framework integrations** — [`@noy-db/in-*`](https://www.npmjs.com/search?q=%40noy-db%2Fin-): vue, pinia, nuxt, react, nextjs, svelte, solid, zustand, tanstack-query, tanstack-table, yjs, ai, rest.
+- **Authentication paths** — [`@noy-db/on-*`](https://www.npmjs.com/search?q=%40noy-db%2Fon-): webauthn, oidc, totp, email-otp, magic-link, recovery, shamir, pin, threat.
+- **Export formats** — [`@noy-db/as-*`](https://www.npmjs.com/search?q=%40noy-db%2Fas-): csv, json, ndjson, xml, sql, xlsx, blob, zip, noydb (encrypted bundle).
+- **Session-share transports** — [`@noy-db/by-*`](https://www.npmjs.com/search?q=%40noy-db%2Fby-): tabs (BroadcastChannel multi-tab), peer (WebRTC).
+- **CLI tooling** — [`@noy-db/cli`](https://www.npmjs.com/package/@noy-db/cli) (`noydb` binary; inspect/verify `.noydb` files), [`create-noy-db`](https://www.npmjs.com/package/create-noy-db) (`npm create noy-db` scaffolder).
+
+## Quick start
+
+```ts
+import { createNoydb } from '@noy-db/hub'
+import { memory } from '@noy-db/to-memory'
+
+type Invoice = { id: string; amount: number; customer: string }
+
+const db = await createNoydb({
+  store: memory(),
+  userId: 'alice',
+  passphrase: 'correct horse battery staple',
+})
+
+const acme = await db.openVault('acme')
+const invoices = acme.collection<Invoice>('invoices')
+
+await invoices.put('INV-001', { id: 'INV-001', amount: 8500, customer: 'ABC Trading' })
+const all = await invoices.list()
+```
+
+## What it does
+
+- **Zero-knowledge encryption** — AES-256-GCM + PBKDF2 (600K iterations) + AES-KW, all via Web Crypto API
+- **Per-collection keys** — one DEK per collection, wrapped with a per-user KEK
+- **Multi-user access control** — owner, admin, operator, viewer, client roles
+- **Offline-first sync** — push/pull with optimistic concurrency on encrypted envelopes
+- **Audit history** — full-copy snapshots with `history()`, `diff()`, `revert()`, `pruneHistory()`
+- **Zero runtime dependencies**
+
+## Cross-vault queries
+
+When a single principal holds grants across many vaults — multi-tenant apps, multi-project setups, multi-workspace tools — there are two APIs for enumerating and fanning out across them:
+
+### `db.listAccessibleVaults(options?)` — enumerate
+
+Returns every vault the calling principal can unwrap, optionally filtered by minimum role. The walk is bounded by the local keyring index — vaults where the user has no keyring file or where the passphrase doesn't unwrap are silently dropped from the result.
+
+```ts
+// All vaults I can unlock
+const all = await db.listAccessibleVaults()
+// → [{ id: 'T1', role: 'owner' }, { id: 'T7', role: 'admin' }, ...]
+
+// Only vaults where I'm at least admin
+const admin = await db.listAccessibleVaults({ minRole: 'admin' })
+```
+
+**Existence-leak guarantee.** The return value never reveals the existence of a vault the caller cannot unwrap. The store sees the enumeration call (it owns the storage), but downstream consumers of `listAccessibleVaults()` only see the filtered list.
+
+**Store capability.** Requires the optional `NoydbStore.listVaults()` method. The `@noy-db/to-memory` and `@noy-db/to-file` stores implement it; cloud stores (`@noy-db/to-aws-dynamo`, `@noy-db/to-aws-s3`) and `@noy-db/to-browser-idb` do not (cloud enumeration needs a GSI or list-bucket permission that has to be configured by the consumer). Calling `listAccessibleVaults()` against a store that doesn't implement `listVaults` throws `StoreCapabilityError`. Workaround: maintain the candidate list out of band and pass it directly to `queryAcross()`.
+
+### `db.queryAcross(ids, fn, options?)` — fan out
+
+Runs a per-vault callback against a list of vault ids and collects the results, tagged by vault. Per-vault errors do not abort the others — each result slot carries either `result` or `error`.
+
+```ts
+const accessible = await db.listAccessibleVaults({ minRole: 'admin' })
+
+const results = await db.queryAcross(
+  accessible.map((v) => v.id),
+  async (vault) => {
+    return vault.collection<Invoice>('invoices').query()
+      .where('month', '==', '2026-03')
+      .toArray()
+  },
+  { concurrency: 4 }, // default 1 — bump for cloud stores
+)
+// results: Array<{ vault, result?: Invoice[], error?: Error }>
+```
+
+**Composes with `exportStream()` for cross-vault plaintext export:**
+
+```ts
+await db.queryAcross(accessible.map((v) => v.id), async (vault) => {
+  const out: unknown[] = []
+  for await (const chunk of vault.exportStream()) out.push(chunk)
+  return out
+})
+```
+
+## Backup and export
+
+noy-db ships two distinct paths for getting data out of a vault. They are not interchangeable — use the one that matches your goal.
+
+### `vault.dump()` — encrypted backup (the default)
+
+Produces a tamper-evident encrypted JSON envelope. Records stay encrypted, the hash-chained ledger is included so the receiver can verify integrity end-to-end after `load()`, and the recipient must hold a valid keyring to read anything. **Use this for backup, transport between machines, or any scenario where the data must remain protected on disk.**
+
+```ts
+const backup = await acme.dump()                // string of encrypted JSON
+await fs.writeFile('./acme-backup.json', backup) // safe to store anywhere
+// later, on another machine:
+await otherAcme.load(backup)                    // verifies + restores
+```
+
+### `vault.exportStream()` and `vault.exportJSON()` — plaintext export
+
+⚠ **These methods decrypt your records and produce plaintext.**
+
+`exportStream()` is an authorization-aware async generator that yields per-collection chunks of decrypted records, with schema and ref metadata attached. `exportJSON()` is a five-line wrapper that serializes the stream to a single JSON string.
+
+Both methods are **ACL-scoped**: collections the calling principal cannot read are silently skipped. An operator with `{ invoices: 'rw' }` permissions on a five-collection vault exports only `invoices`, with no error on the others.
+
+```ts
+// Stream every collection the caller can read
+for await (const chunk of acme.exportStream()) {
+  console.log(chunk.collection, chunk.records.length)
+}
+
+// Or get a single JSON string
+const json = await acme.exportJSON()
+await fs.writeFile('./backup.json', json)
+```
+
+**Use only when:**
+- You are the authorized owner of the data, **and**
+- You have a legitimate downstream tool that requires plaintext, **and**
+- You have a documented plan for how the resulting plaintext will be protected and eventually destroyed.
+
+If your goal is encrypted backup or transport between noy-db instances, use **`vault.dump()`** instead.
+
+#### Why no built-in file path support
+
+Core has zero `node:` imports — it runs unchanged in browsers, Node, Bun, Deno, and edge runtimes. `exportJSON()` returns a `Promise<string>` so the consumer chooses any sink (`fs.writeFile`, `Blob` download, `fetch` upload, IndexedDB) and the destination decision stays explicit at the call site. This is also better for the security warning: there's no library function quietly writing plaintext somewhere.
+
+#### Other plaintext formats
+
+CSV, XML, xlsx, and the rest of the plaintext tier — plus encrypted `.noydb` bundles under the `as-noydb` encrypted tier — all live in the [`@noy-db/as-*`](https://www.npmjs.com/search?q=%40noy-db%2Fas-) family. Every invocation is gated by the two-tier authorization model (`canExportPlaintext` default off, `canExportBundle` default on for owner/admin) and lands in the audit ledger.
+
+## Status
+
+**Pre-release** (`0.1.0-pre.1`). API may change before `1.0`. Install from the `next` dist-tag:
+
+```bash
+pnpm add @noy-db/hub@next @noy-db/to-memory@next
+```
+
+## Documentation
+
+- Full docs: <https://github.com/vLannaAi/noy-db#readme>
+- Spec: <https://github.com/vLannaAi/noy-db/blob/main/SPEC.md>
+- Roadmap: <https://github.com/vLannaAi/noy-db/blob/main/ROADMAP.md>
+
+## License
+
+[MIT](./LICENSE) © vLannaAi

package/dist/aggregate/index.cjs

@@ -0,0 +1,476 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/aggregate/index.ts
+var aggregate_exports = {};
+__export(aggregate_exports, {
+  Aggregation: () => Aggregation,
+  GROUPBY_MAX_CARDINALITY: () => GROUPBY_MAX_CARDINALITY,
+  GROUPBY_WARN_CARDINALITY: () => GROUPBY_WARN_CARDINALITY,
+  GroupedAggregation: () => GroupedAggregation,
+  GroupedQuery: () => GroupedQuery,
+  avg: () => avg,
+  buildLiveAggregation: () => buildLiveAggregation,
+  count: () => count,
+  groupAndReduce: () => groupAndReduce,
+  max: () => max,
+  min: () => min,
+  reduceRecords: () => reduceRecords,
+  resetGroupByWarnings: () => resetGroupByWarnings,
+  sum: () => sum,
+  withAggregate: () => withAggregate
+});
+module.exports = __toCommonJS(aggregate_exports);
+
+// src/aggregate/aggregation.ts
+function reduceRecords(records, spec) {
+  const state = {};
+  for (const key of Object.keys(spec)) {
+    state[key] = spec[key].init();
+  }
+  for (const record of records) {
+    for (const key of Object.keys(spec)) {
+      state[key] = spec[key].step(state[key], record);
+    }
+  }
+  const result = {};
+  for (const key of Object.keys(spec)) {
+    result[key] = spec[key].finalize(state[key]);
+  }
+  return result;
+}
+var LiveAggregationImpl = class {
+  constructor(recompute, upstreams) {
+    this.recompute = recompute;
+    try {
+      this.value = recompute();
+      this.error = void 0;
+    } catch (err) {
+      this.value = void 0;
+      this.error = err;
+    }
+    for (const upstream of upstreams) {
+      const unsub = upstream.subscribe(() => this.refresh());
+      this.unsubscribes.push(unsub);
+    }
+  }
+  recompute;
+  value;
+  error;
+  listeners = /* @__PURE__ */ new Set();
+  unsubscribes = [];
+  stopped = false;
+  refresh() {
+    if (this.stopped) return;
+    try {
+      this.value = this.recompute();
+      this.error = void 0;
+    } catch (err) {
+      this.error = err;
+    }
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch (err) {
+        console.warn("[noy-db] LiveAggregation listener threw:", err);
+      }
+    }
+  }
+  subscribe(cb) {
+    if (this.stopped) {
+      return () => {
+      };
+    }
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    for (const unsub of this.unsubscribes) {
+      try {
+        unsub();
+      } catch (err) {
+        console.warn("[noy-db] LiveAggregation upstream unsubscribe threw:", err);
+      }
+    }
+    this.unsubscribes.length = 0;
+    this.listeners.clear();
+  }
+};
+var Aggregation = class {
+  constructor(executeRecords, spec, upstreams) {
+    this.executeRecords = executeRecords;
+    this.spec = spec;
+    this.upstreams = upstreams;
+  }
+  executeRecords;
+  spec;
+  upstreams;
+  /**
+   * Execute the query and reduce the results synchronously.
+   * Returns the reduced shape matching the spec — e.g. a spec of
+   * `{ total: sum('amount'), n: count() }` returns
+   * `{ total: number, n: number }`.
+   */
+  run() {
+    return reduceRecords(this.executeRecords(), this.spec);
+  }
+  /**
+   * Build a reactive `LiveAggregation<R>` that re-runs the reduction
+   * whenever any upstream source notifies of a change. The initial
+   * value is computed eagerly in the constructor, so consumers can
+   * read `live.value` immediately after calling `.live()`.
+   *
+   * Always call `live.stop()` when finished — it tears down the
+   * upstream subscriptions. Vue's `onUnmounted` is the canonical
+   * place.
+   *
+   * **Implementation note:** every upstream change triggers a full
+   * re-reduction. Incremental maintenance (O(1) per delta for
+   * sum/count/avg via the reducer protocol's `remove()` method) is a
+   * planned follow-up optimization — the protocol already supports
+   * it, but the executor doesn't drive it yet. Consumers get
+   * correct, reactive values today; future PRs can switch to
+   * delta-based maintenance without changing this API.
+   */
+  live() {
+    const recompute = () => reduceRecords(this.executeRecords(), this.spec);
+    return new LiveAggregationImpl(recompute, this.upstreams);
+  }
+};
+function buildLiveAggregation(recompute, upstreams) {
+  return new LiveAggregationImpl(recompute, upstreams);
+}
+
+// src/query/predicate.ts
+function readPath(record, path) {
+  if (record === null || record === void 0) return void 0;
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  const segments = path.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+
+// src/errors.ts
+var NoydbError = class extends Error {
+  /** Machine-readable error code. Stable across library versions. */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "NoydbError";
+    this.code = code;
+  }
+};
+var GroupCardinalityError = class extends NoydbError {
+  /** The field being grouped on. */
+  field;
+  /** Observed number of distinct groups at the moment the cap tripped. */
+  cardinality;
+  /** The cap that was exceeded. */
+  maxGroups;
+  constructor(field, cardinality, maxGroups) {
+    super(
+      "GROUP_CARDINALITY",
+      `.groupBy("${field}") produced ${cardinality} distinct groups, exceeding the ${maxGroups}-group ceiling. This is almost always a query mistake \u2014 grouping on a high-uniqueness field like "id" or "createdAt" produces one bucket per record. Narrow the query with .where() before grouping, or group on a lower-cardinality field (status, category, clientId). If you genuinely need high-cardinality grouping, file an issue with your use case.`
+    );
+    this.name = "GroupCardinalityError";
+    this.field = field;
+    this.cardinality = cardinality;
+    this.maxGroups = maxGroups;
+  }
+};
+
+// src/aggregate/groupby.ts
+var GROUPBY_WARN_CARDINALITY = 1e4;
+var GROUPBY_MAX_CARDINALITY = 1e5;
+var warnedCardinalityFields = /* @__PURE__ */ new Set();
+function warnCardinalityApproaching(field, observed) {
+  if (warnedCardinalityFields.has(field)) return;
+  warnedCardinalityFields.add(field);
+  console.warn(
+    `[noy-db] .groupBy("${field}") produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
+  );
+}
+function resetGroupByWarnings() {
+  warnedCardinalityFields.clear();
+}
+var GroupedQuery = class {
+  constructor(executeRecords, field, upstreams, dictLabelResolver) {
+    this.executeRecords = executeRecords;
+    this.field = field;
+    this.upstreams = upstreams;
+    this.dictLabelResolver = dictLabelResolver;
+  }
+  executeRecords;
+  field;
+  upstreams;
+  dictLabelResolver;
+  /**
+   * Build a grouped aggregation. Returns a `GroupedAggregation`
+   * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape
+   * as the non-grouped `.aggregate()` wrapper, just with an array
+   * result (one row per bucket) instead of a single reduced object.
+   */
+  aggregate(spec) {
+    return new GroupedAggregation(
+      this.executeRecords,
+      this.field,
+      spec,
+      this.upstreams,
+      this.dictLabelResolver
+    );
+  }
+};
+function groupAndReduce(records, field, spec) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const key = readPath(record, field);
+    let bucket = buckets.get(key);
+    if (bucket === void 0) {
+      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {
+        throw new GroupCardinalityError(
+          field,
+          buckets.size + 1,
+          GROUPBY_MAX_CARDINALITY
+        );
+      }
+      bucket = [];
+      buckets.set(key, bucket);
+    }
+    bucket.push(record);
+  }
+  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
+    warnCardinalityApproaching(field, buckets.size);
+  }
+  const keys = Object.keys(spec);
+  const out = [];
+  for (const [groupKey, bucketRecords] of buckets) {
+    const state = {};
+    for (const key of keys) {
+      state[key] = spec[key].init();
+    }
+    for (const record of bucketRecords) {
+      for (const key of keys) {
+        state[key] = spec[key].step(state[key], record);
+      }
+    }
+    const row = { [field]: groupKey };
+    for (const key of keys) {
+      row[key] = spec[key].finalize(state[key]);
+    }
+    out.push(row);
+  }
+  return out;
+}
+var GroupedAggregation = class {
+  constructor(executeRecords, field, spec, upstreams, dictLabelResolver) {
+    this.executeRecords = executeRecords;
+    this.field = field;
+    this.spec = spec;
+    this.upstreams = upstreams;
+    this.dictLabelResolver = dictLabelResolver;
+  }
+  executeRecords;
+  field;
+  spec;
+  upstreams;
+  dictLabelResolver;
+  /** Execute the query, group, reduce, and return an array of rows. */
+  run() {
+    return groupAndReduce(this.executeRecords(), this.field, this.spec);
+  }
+  /**
+   * Execute the query, group, reduce, and resolve `<field>Label` for
+   * each result row when the grouping field is a `dictKey` and a
+   * `locale` is provided. Returns `R[]` synchronously when
+   * no locale is specified (identical to `.run()`).
+   *
+   * The `<field>Label` field is appended to each row. Rows whose group
+   * key has no dictionary entry get `<field>Label: undefined`.
+   */
+  async runAsync(opts) {
+    const rows = groupAndReduce(this.executeRecords(), this.field, this.spec);
+    if (!opts?.locale || !this.dictLabelResolver) return rows;
+    const resolve = this.dictLabelResolver;
+    const locale = opts.locale;
+    const fallback = opts.fallback;
+    const labelKey = `${this.field}Label`;
+    return Promise.all(
+      rows.map(async (row) => {
+        const key = row[this.field];
+        if (typeof key !== "string") return row;
+        const label = await resolve(key, locale, fallback);
+        return { ...row, [labelKey]: label };
+      })
+    );
+  }
+  /**
+   * Build a reactive `LiveAggregation<R[]>` that re-runs the full
+   * group-and-reduce pipeline whenever any upstream source notifies
+   * of a change. Same error-isolation and idempotent-stop contract
+   * as `Aggregation.live()` — the implementation delegates to the
+   * same `LiveAggregationImpl` class by threading a fresh
+   * recompute closure through the existing constructor.
+   *
+   * uses naive full re-run on every change. Incremental
+   * per-bucket maintenance (apply `step` on inserted records,
+   * `remove` on deleted records, route by bucket key) is a future
+   * optimization — the reducer protocol admits it, but wiring
+   * delta-aware source subscriptions is a separate PR.
+   *
+   * Always call `live.stop()` when finished.
+   */
+  live() {
+    const recompute = () => groupAndReduce(this.executeRecords(), this.field, this.spec);
+    return buildLiveAggregation(recompute, this.upstreams);
+  }
+};
+
+// src/aggregate/active.ts
+function withAggregate() {
+  return {
+    aggregate(executeRecords, spec, upstreams) {
+      return new Aggregation(executeRecords, spec, upstreams);
+    },
+    groupBy(executeRecords, field, upstreams, dictLabelResolver) {
+      return new GroupedQuery(executeRecords, field, upstreams, dictLabelResolver);
+    },
+    async scanAggregate(iter, spec) {
+      const collected = [];
+      for await (const record of iter) collected.push(record);
+      return reduceRecords(collected, spec);
+    }
+  };
+}
+
+// src/aggregate/reducers.ts
+function count(opts) {
+  const _seed = opts?.seed;
+  void _seed;
+  return {
+    init: () => 0,
+    step: (state) => state + 1,
+    remove: (state) => state - 1,
+    finalize: (state) => state
+  };
+}
+function sum(field, opts) {
+  const _seed = opts?.seed;
+  void _seed;
+  return {
+    init: () => 0,
+    step: (state, record) => state + readNumber(record, field),
+    remove: (state, record) => state - readNumber(record, field),
+    finalize: (state) => state
+  };
+}
+function avg(field, opts) {
+  const _seed = opts?.seed;
+  void _seed;
+  return {
+    init: () => ({ sum: 0, count: 0 }),
+    step: (state, record) => ({
+      sum: state.sum + readNumber(record, field),
+      count: state.count + 1
+    }),
+    remove: (state, record) => ({
+      sum: state.sum - readNumber(record, field),
+      count: state.count - 1
+    }),
+    finalize: (state) => state.count === 0 ? null : state.sum / state.count
+  };
+}
+function pushValue(state, value) {
+  return { values: [...state.values, value] };
+}
+function removeValue(state, value) {
+  const idx = state.values.indexOf(value);
+  if (idx < 0) return state;
+  const next = state.values.slice();
+  next.splice(idx, 1);
+  return { values: next };
+}
+function min(field, opts) {
+  const _seed = opts?.seed;
+  void _seed;
+  return {
+    init: () => ({ values: [] }),
+    step: (state, record) => pushValue(state, readNumber(record, field)),
+    remove: (state, record) => removeValue(state, readNumber(record, field)),
+    finalize: (state) => {
+      if (state.values.length === 0) return null;
+      let out = state.values[0];
+      for (let i = 1; i < state.values.length; i++) {
+        const v = state.values[i];
+        if (v < out) out = v;
+      }
+      return out;
+    }
+  };
+}
+function max(field, opts) {
+  const _seed = opts?.seed;
+  void _seed;
+  return {
+    init: () => ({ values: [] }),
+    step: (state, record) => pushValue(state, readNumber(record, field)),
+    remove: (state, record) => removeValue(state, readNumber(record, field)),
+    finalize: (state) => {
+      if (state.values.length === 0) return null;
+      let out = state.values[0];
+      for (let i = 1; i < state.values.length; i++) {
+        const v = state.values[i];
+        if (v > out) out = v;
+      }
+      return out;
+    }
+  };
+}
+function readNumber(record, field) {
+  const value = readPath(record, field);
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Aggregation,
+  GROUPBY_MAX_CARDINALITY,
+  GROUPBY_WARN_CARDINALITY,
+  GroupedAggregation,
+  GroupedQuery,
+  avg,
+  buildLiveAggregation,
+  count,
+  groupAndReduce,
+  max,
+  min,
+  reduceRecords,
+  resetGroupByWarnings,
+  sum,
+  withAggregate
+});
+//# sourceMappingURL=index.cjs.map