@noy-db/hub 0.1.0-pre.10

package/dist/query/index.cjs

@@ -0,0 +1,1999 @@
+"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/query/index.ts
+var query_exports = {};
+__export(query_exports, {
+  Aggregation: () => Aggregation,
+  CollectionIndexes: () => CollectionIndexes,
+  DEFAULT_JOIN_MAX_ROWS: () => DEFAULT_JOIN_MAX_ROWS,
+  DanglingReferenceError: () => DanglingReferenceError,
+  GROUPBY_MAX_CARDINALITY: () => GROUPBY_MAX_CARDINALITY,
+  GROUPBY_WARN_CARDINALITY: () => GROUPBY_WARN_CARDINALITY,
+  GroupCardinalityError: () => GroupCardinalityError,
+  GroupedAggregation: () => GroupedAggregation,
+  GroupedQuery: () => GroupedQuery,
+  IndexRequiredError: () => IndexRequiredError,
+  IndexWriteFailureError: () => IndexWriteFailureError,
+  JoinTooLargeError: () => JoinTooLargeError,
+  Query: () => Query,
+  ScanBuilder: () => ScanBuilder,
+  applyJoins: () => applyJoins,
+  avg: () => avg,
+  buildLiveAggregation: () => buildLiveAggregation,
+  buildLiveQuery: () => buildLiveQuery,
+  count: () => count,
+  evaluateClause: () => evaluateClause,
+  evaluateFieldClause: () => evaluateFieldClause,
+  executePlan: () => executePlan,
+  groupAndReduce: () => groupAndReduce,
+  max: () => max,
+  min: () => min,
+  readPath: () => readPath,
+  reduceRecords: () => reduceRecords,
+  resetGroupByWarnings: () => resetGroupByWarnings,
+  resetJoinWarnings: () => resetJoinWarnings,
+  sum: () => sum
+});
+module.exports = __toCommonJS(query_exports);
+
+// 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;
+}
+function evaluateFieldClause(record, clause) {
+  const actual = readPath(record, clause.field);
+  const { op, value } = clause;
+  switch (op) {
+    case "==":
+      return actual === value;
+    case "!=":
+      return actual !== value;
+    case "<":
+      return isComparable(actual, value) && actual < value;
+    case "<=":
+      return isComparable(actual, value) && actual <= value;
+    case ">":
+      return isComparable(actual, value) && actual > value;
+    case ">=":
+      return isComparable(actual, value) && actual >= value;
+    case "in":
+      return Array.isArray(value) && value.includes(actual);
+    case "contains":
+      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
+      if (Array.isArray(actual)) return actual.includes(value);
+      return false;
+    case "startsWith":
+      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) return false;
+      const [lo, hi] = value;
+      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
+      return actual >= lo && actual <= hi;
+    }
+    default: {
+      const _exhaustive = op;
+      void _exhaustive;
+      return false;
+    }
+  }
+}
+function isComparable(a, b) {
+  if (typeof a === "number" && typeof b === "number") return true;
+  if (typeof a === "string" && typeof b === "string") return true;
+  if (a instanceof Date && b instanceof Date) return true;
+  return false;
+}
+function evaluateClause(record, clause) {
+  switch (clause.type) {
+    case "field":
+      return evaluateFieldClause(record, clause);
+    case "filter":
+      return clause.fn(record);
+    case "group":
+      if (clause.op === "and") {
+        for (const child of clause.clauses) {
+          if (!evaluateClause(record, child)) return false;
+        }
+        return true;
+      } else {
+        for (const child of clause.clauses) {
+          if (evaluateClause(record, child)) return true;
+        }
+        return false;
+      }
+  }
+}
+
+// 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;
+  }
+};
+var IndexRequiredError = class extends NoydbError {
+  collection;
+  touchedFields;
+  missingFields;
+  constructor(args) {
+    super(
+      "INDEX_REQUIRED",
+      `Collection "${args.collection}": query references unindexed fields in lazy mode (missing: ${args.missingFields.join(", ")}). Declare an index on each field, or use collection.scan() for non-indexed iteration.`
+    );
+    this.name = "IndexRequiredError";
+    this.collection = args.collection;
+    this.touchedFields = [...args.touchedFields];
+    this.missingFields = [...args.missingFields];
+  }
+};
+var IndexWriteFailureError = class extends NoydbError {
+  recordId;
+  field;
+  op;
+  cause;
+  constructor(args) {
+    super(
+      "INDEX_WRITE_FAILURE",
+      `Index side-car ${args.op} failed for field "${args.field}" on record "${args.recordId}"`
+    );
+    this.name = "IndexWriteFailureError";
+    this.recordId = args.recordId;
+    this.field = args.field;
+    this.op = args.op;
+    this.cause = args.cause;
+  }
+};
+var JoinTooLargeError = class extends NoydbError {
+  leftRows;
+  rightRows;
+  maxRows;
+  side;
+  constructor(opts) {
+    super("JOIN_TOO_LARGE", opts.message);
+    this.name = "JoinTooLargeError";
+    this.leftRows = opts.leftRows;
+    this.rightRows = opts.rightRows;
+    this.maxRows = opts.maxRows;
+    this.side = opts.side;
+  }
+};
+var DanglingReferenceError = class extends NoydbError {
+  field;
+  target;
+  refId;
+  constructor(opts) {
+    super("DANGLING_REFERENCE", opts.message);
+    this.name = "DanglingReferenceError";
+    this.field = opts.field;
+    this.target = opts.target;
+    this.refId = opts.refId;
+  }
+};
+
+// src/query/join.ts
+var DEFAULT_JOIN_MAX_ROWS = 5e4;
+var JOIN_WARN_FRACTION = 0.8;
+function coerceRefKey(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return null;
+}
+var warnedDanglingKeys = /* @__PURE__ */ new Set();
+function warnOnceDangling(field, target, refId) {
+  const key = `${field}\u2192${target}:${refId}`;
+  if (warnedDanglingKeys.has(key)) return;
+  warnedDanglingKeys.add(key);
+  console.warn(
+    `[noy-db] .join() encountered dangling ref in 'warn' mode: field "${field}" \u2192 "${target}:${refId}" not found. Attaching null.`
+  );
+}
+var warnedCeilingKeys = /* @__PURE__ */ new Set();
+function warnCeilingApproaching(target, side, rows, maxRows) {
+  const key = `${target}:${side}`;
+  if (warnedCeilingKeys.has(key)) return;
+  warnedCeilingKeys.add(key);
+  const pct = Math.round(rows / maxRows * 100);
+  console.warn(
+    `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ceiling for target "${target}" (${rows} rows). Streaming joins over scan() are not yet supported for collections that need to exceed this.`
+  );
+}
+function applyJoins(rows, joins, context) {
+  if (joins.length === 0) return [...rows];
+  let result = [...rows];
+  for (const leg of joins) {
+    result = applyOneJoin(result, leg, context);
+  }
+  return result;
+}
+function applyOneJoin(leftRows, leg, context) {
+  if (leg.isDictJoin) {
+    const dictSource = context.resolveDictSource?.(leg.field);
+    if (!dictSource) {
+      throw new Error(
+        `.join() field "${leg.field}" on "${context.leftCollection}" is declared as a dictKey join but the dict source could not be resolved. Ensure the dictionary has at least one entry.`
+      );
+    }
+    const out = [];
+    const snapshot = dictSource.snapshot();
+    const dictMap = /* @__PURE__ */ new Map();
+    for (const entry of snapshot) {
+      const k = readPath(entry, "key");
+      if (typeof k === "string") dictMap.set(k, entry);
+    }
+    for (const left of leftRows) {
+      const rawId = readPath(left, leg.field);
+      const key = coerceRefKey(rawId);
+      const dictEntry = key === null ? void 0 : dictMap.get(key);
+      out.push({ ...left, [leg.as]: dictEntry ?? null });
+    }
+    return out;
+  }
+  const source = context.resolveSource(leg.target);
+  if (!source) {
+    throw new Error(
+      `.join() cannot resolve target collection "${leg.target}" (referenced from field "${leg.field}" on "${context.leftCollection}"). Make sure the target collection has been opened via vault.collection() at least once before running the query.`
+    );
+  }
+  const maxRows = leg.maxRows ?? DEFAULT_JOIN_MAX_ROWS;
+  if (leftRows.length > maxRows) {
+    throw new JoinTooLargeError({
+      leftRows: leftRows.length,
+      rightRows: -1,
+      maxRows,
+      side: "left",
+      message: `.join() left side has ${leftRows.length} rows, exceeding the ${maxRows}-row ceiling for target "${leg.target}". Filter the left side further with where()/limit() before joining, or raise the ceiling via { maxRows }. Streaming joins over scan() are not yet supported.`
+    });
+  }
+  if (leftRows.length > maxRows * JOIN_WARN_FRACTION) {
+    warnCeilingApproaching(leg.target, "left", leftRows.length, maxRows);
+  }
+  const rightSnapshot = source.snapshot();
+  if (rightSnapshot.length > maxRows) {
+    throw new JoinTooLargeError({
+      leftRows: leftRows.length,
+      rightRows: rightSnapshot.length,
+      maxRows,
+      side: "right",
+      message: `.join() right side "${leg.target}" has ${rightSnapshot.length} rows, exceeding the ${maxRows}-row ceiling. Raise the ceiling via { maxRows } if the data genuinely fits in memory, or track  for streaming joins.`
+    });
+  }
+  if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {
+    warnCeilingApproaching(leg.target, "right", rightSnapshot.length, maxRows);
+  }
+  const strategy = leg.strategy ?? (source.lookupById ? "nested" : "hash");
+  if (strategy === "nested" && source.lookupById) {
+    const lookup = (id) => source.lookupById?.(id);
+    return nestedLoopJoin(leftRows, leg, lookup);
+  }
+  return hashJoin(leftRows, leg, rightSnapshot);
+}
+function nestedLoopJoin(leftRows, leg, lookupById) {
+  const out = [];
+  for (const left of leftRows) {
+    const rawId = readPath(left, leg.field);
+    const key = coerceRefKey(rawId);
+    const right = key === null ? void 0 : lookupById(key);
+    out.push(attachJoin(left, leg, right, rawId));
+  }
+  return out;
+}
+function hashJoin(leftRows, leg, rightSnapshot) {
+  const rightMap = /* @__PURE__ */ new Map();
+  for (const record of rightSnapshot) {
+    const rawId = readPath(record, "id");
+    const key = coerceRefKey(rawId);
+    if (key !== null) {
+      rightMap.set(key, record);
+    }
+  }
+  const out = [];
+  for (const left of leftRows) {
+    const rawId = readPath(left, leg.field);
+    const key = coerceRefKey(rawId);
+    const right = key === null ? void 0 : rightMap.get(key);
+    out.push(attachJoin(left, leg, right, rawId));
+  }
+  return out;
+}
+function attachJoin(left, leg, right, rawId) {
+  if (left === null || typeof left !== "object") {
+    return left;
+  }
+  const merged = { ...left };
+  const refKey = coerceRefKey(rawId);
+  if (right === void 0) {
+    if (refKey !== null && leg.mode === "strict") {
+      throw new DanglingReferenceError({
+        field: leg.field,
+        target: leg.target,
+        refId: refKey,
+        message: `.join() strict dangling: record references "${leg.target}:${refKey}" via field "${leg.field}", but no such record exists. Use ref() mode 'warn' or 'cascade' if dangling refs are acceptable, or run vault.checkIntegrity() to find and fix the orphans.`
+      });
+    }
+    if (refKey !== null && leg.mode === "warn") {
+      warnOnceDangling(leg.field, leg.target, refKey);
+    }
+    merged[leg.as] = null;
+  } else {
+    merged[leg.as] = right;
+  }
+  return merged;
+}
+function resetJoinWarnings() {
+  warnedDanglingKeys.clear();
+  warnedCeilingKeys.clear();
+}
+
+// src/query/live.ts
+function buildLiveQuery(recompute, upstreams) {
+  return new LiveQueryImpl(recompute, upstreams);
+}
+var LiveQueryImpl = class {
+  constructor(recompute, upstreams) {
+    this.recompute = recompute;
+    this.refresh();
+    for (const upstream of upstreams) {
+      try {
+        this.unsubs.push(upstream.subscribe(this.onUpstreamChange));
+      } catch (err) {
+        this._error = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+  }
+  recompute;
+  _value = [];
+  _error = null;
+  listeners = /* @__PURE__ */ new Set();
+  unsubs = [];
+  stopped = false;
+  get value() {
+    return this._value;
+  }
+  get error() {
+    return this._error;
+  }
+  /**
+   * Bound change handler — used as the callback passed to every
+   * upstream's subscribe. Bound via class field so the `this`
+   * context survives the indirect call from arbitrary upstreams.
+   */
+  onUpstreamChange = () => {
+    this.refresh();
+    for (const cb of this.listeners) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  };
+  refresh() {
+    if (this.stopped) return;
+    try {
+      this._value = this.recompute();
+      this._error = null;
+    } catch (err) {
+      this._error = err instanceof Error ? err : new Error(String(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.unsubs) {
+      try {
+        unsub();
+      } catch {
+      }
+    }
+    this.unsubs.length = 0;
+    this.listeners.clear();
+  }
+};
+
+// src/aggregate/strategy.ts
+var NOT_ENABLED = new Error(
+  'Aggregate / groupBy is not enabled on this Noydb instance. Import `{ withAggregate }` from "@noy-db/hub/aggregate" and pass it to `createNoydb({ aggregateStrategy: withAggregate() })`.'
+);
+var NO_AGGREGATE = {
+  aggregate() {
+    throw NOT_ENABLED;
+  },
+  groupBy() {
+    throw NOT_ENABLED;
+  },
+  scanAggregate() {
+    throw NOT_ENABLED;
+  }
+};
+
+// src/query/builder.ts
+var EMPTY_PLAN = {
+  clauses: [],
+  orderBy: [],
+  limit: void 0,
+  offset: 0,
+  joins: []
+};
+var Query = class _Query {
+  source;
+  plan;
+  joinContext;
+  aggregateStrategy;
+  constructor(source, plan = EMPTY_PLAN, joinContext, aggregateStrategy = NO_AGGREGATE) {
+    this.source = source;
+    this.plan = plan;
+    this.joinContext = joinContext;
+    this.aggregateStrategy = aggregateStrategy;
+  }
+  /** Add a field comparison. Multiple where() calls are AND-combined. */
+  where(field, op, value) {
+    const clause = { type: "field", field, op, value };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /**
+   * Logical OR group. Pass a callback that builds a sub-query.
+   * Each clause inside the callback is OR-combined; the group itself
+   * joins the parent plan with AND.
+   */
+  or(builder) {
+    const sub = builder(
+      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy)
+    );
+    const group = {
+      type: "group",
+      op: "or",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, group] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /**
+   * Logical AND group. Same shape as `or()` but every clause inside the group
+   * must match. Useful for explicit grouping inside a larger OR.
+   */
+  and(builder) {
+    const sub = builder(
+      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy)
+    );
+    const group = {
+      type: "group",
+      op: "and",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, group] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /** Escape hatch: add an arbitrary predicate function. Not serializable. */
+  filter(fn) {
+    const clause = {
+      type: "filter",
+      fn
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /** Sort by a field. Subsequent calls are tie-breakers. */
+  orderBy(field, direction = "asc") {
+    return new _Query(
+      this.source,
+      { ...this.plan, orderBy: [...this.plan.orderBy, { field, direction }] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /** Cap the result size. */
+  limit(n) {
+    return new _Query(
+      this.source,
+      { ...this.plan, limit: n },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /** Skip the first N matching records (after ordering). */
+  offset(n) {
+    return new _Query(
+      this.source,
+      { ...this.plan, offset: n },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /**
+   * Resolve a `ref()`-declared foreign key and attach the right-side
+   * record under `opts.as`. — eager, single-FK, intra-
+   * vault joins.
+   *
+   * ```ts
+   * const rows = invoices.query()
+   *   .where('status', '==', 'open')
+   *   .join('clientId', { as: 'client' })
+   *   .toArray()
+   * // → [{ id, amount, client: { id, name, ... } }, ...]
+   * ```
+   *
+   * Preconditions:
+   *   - The Query must have a `joinContext` (constructed via
+   *     `Collection.query()`, not `new Query`).
+   *   - `field` must have a matching `refs: { [field]: ref('<target>') }`
+   *     declaration on the left collection.
+   *   - The target collection must be reachable via the vault
+   *     (either currently open or openable on demand).
+   *
+   * Strategy:
+   *   - Nested-loop against `lookupById` when the target source
+   *     provides it (the common path for Collection targets).
+   *   - Hash join otherwise, or when `{ strategy: 'hash' }` is
+   *     explicitly passed for test purposes.
+   *
+   * Ref-mode semantics on dangling refs (left record has a non-null
+   * FK value pointing at a right-side id that doesn't exist):
+   *   - `strict`  → throws `DanglingReferenceError` with the full
+   *     field / target / refId context.
+   *   - `warn`    → attaches `null` and emits a one-shot warning per
+   *     unique dangling pair.
+   *   - `cascade` → attaches `null` silently. Cascade is a
+   *     delete-time mode; dangling refs visible at read time are
+   *     either mid-flight cascades or pre-existing orphans, not a
+   *     DSL-level error.
+   *
+   * A left-side record whose FK field is `null` / `undefined` is NOT
+   * a dangling ref — it's "no reference at all", always allowed
+   * regardless of mode.
+   *
+   * The return type widens `T` with `Record<As, R | null>`. The `R`
+   * parameter is optional — supply it explicitly for type-checked
+   * access to the joined fields:
+   *
+   * ```ts
+   * invoices.query().join<'client', Client>('clientId', { as: 'client' })
+   * //                 ^^^^^^^^^^^^^^^^^^^ alias literal + right-side type
+   * ```
+   *
+   * Without the generic, the joined field is typed as `unknown`, which
+   * still works but requires a cast to access its properties.
+   *
+   * Joins stay intra-vault by construction — cross-vault
+   * correlation goes through `Noydb.queryAcross`, not
+   * `.join()`.
+   */
+  join(field, opts) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.join() requires a join context. Use collection.query() to construct a join-capable Query instead of the Query constructor directly (the direct constructor is only used for tests with plain-object sources).`
+      );
+    }
+    const descriptor = this.joinContext.resolveRef(field);
+    const isDictJoinField = !descriptor && this.joinContext.resolveDictSource?.(field) != null;
+    if (!descriptor && !isDictJoinField) {
+      throw new Error(
+        `Query.join(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Add refs: { ${field}: ref('<target-collection>') } to the collection options, then retry. See the ref() docs for the full list of modes.`
+      );
+    }
+    const leg = descriptor ? {
+      field,
+      as: opts.as,
+      target: descriptor.target,
+      mode: descriptor.mode,
+      strategy: opts.strategy,
+      maxRows: opts.maxRows,
+      //  constraint #1 — always 'all' in. Do not remove.
+      partitionScope: "all"
+    } : {
+      // Dict join leg
+      field,
+      as: opts.as,
+      target: field,
+      // dict name = field name for dictKey
+      mode: "strict",
+      strategy: opts.strategy,
+      maxRows: opts.maxRows,
+      partitionScope: "all",
+      isDictJoin: true
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, joins: [...this.plan.joins, leg] },
+      this.joinContext,
+      this.aggregateStrategy
+    );
+  }
+  /**
+   * Execute the plan and return the matching records. When the plan
+   * carries any join legs, they are applied after `where` / `orderBy`
+   * / `limit` / `offset` narrow the left set. See the `.join()` doc
+   * for the ordering rationale.
+   */
+  toArray() {
+    const base = executePlanWithSource(this.source, this.plan);
+    if (this.plan.joins.length === 0) return base;
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.toArray(): plan carries ${this.plan.joins.length} join leg(s) but no JoinContext is attached. This usually means the Query was constructed via the raw Query constructor with a plan that had joins pre-populated. Use collection.query().join(...) instead.`
+      );
+    }
+    return applyJoins(base, this.plan.joins, this.joinContext);
+  }
+  /** Return the first matching record, or null. Joins are applied. */
+  first() {
+    const arr = this.limit(1).toArray();
+    return arr[0] ?? null;
+  }
+  /**
+   * Return the number of matching records (after where/filter,
+   * before limit). **Joins are NOT applied** — count() reports the
+   * left-side cardinality, because joins in are projection-only
+   * (they attach an aliased field; they never filter). Running joins
+   * here just to discard the aliases would be wasteful, and in strict
+   * mode it could throw `DanglingReferenceError` for a call whose
+   * intent is purely to count.
+   */
+  count() {
+    const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
+    if (remainingClauses.length === 0) return candidates.length;
+    return filterRecords(candidates, remainingClauses).length;
+  }
+  /**
+   * Reduce the matching records through a named set of reducers.
+   * the aggregation terminal.
+   *
+   * ```ts
+   * const { total, n, avgAmount } = invoices.query()
+   *   .where('status', '==', 'open')
+   *   .aggregate({
+   *     total:     sum('amount'),
+   *     n:         count(),
+   *     avgAmount: avg('amount'),
+   *   })
+   *   .run()
+   * ```
+   *
+   * Returns an `Aggregation<R>` wrapper with two terminals:
+   *   - `.run(): R` — synchronous one-shot reduction
+   *   - `.live(): LiveAggregation<R>` — reactive primitive that
+   *     re-runs the reduction whenever the source notifies of a
+   *     change. Always call `live.stop()` when finished.
+   *
+   * The reducer spec is bound here once and reused by both
+   * terminals — this is why `.aggregate()` returns a wrapper instead
+   * of being a direct terminal. Consumers who only need the static
+   * value read `.run()`; consumers wiring a reactive UI read
+   * `.live()`.
+   *
+   * Joins are intentionally NOT applied to aggregations in —
+   * the same logic as `.count()`. Joins in are projection-only
+   * (they attach an aliased field and never filter), so running
+   * them just to throw the aliases away would be wasteful. If you
+   * need a reducer that reads a joined field, open an issue —
+   * aggregations-across-joins is explicitly out of scope for v1.
+   *
+   * Every reducer factory accepts an optional `{ seed }` parameter
+   * that is plumbed through the protocol but unused by the
+   * executor — that's  constraint #2. When partition-aware
+   * aggregation lands, the seed will carry running state across
+   * partition boundaries without an API break.
+   */
+  aggregate(spec) {
+    const source = this.source;
+    const clauses = this.plan.clauses;
+    const executeRecords = () => {
+      const { candidates, remainingClauses } = candidateRecords(source, clauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
+    };
+    const upstreams = [];
+    if (source.subscribe) {
+      const subscribe = source.subscribe.bind(source);
+      upstreams.push({ subscribe: (cb) => subscribe(cb) });
+    }
+    return this.aggregateStrategy.aggregate(executeRecords, spec, upstreams);
+  }
+  /**
+   * Partition matching records into buckets keyed by a field, then
+   * terminate with `.aggregate(spec)` to compute per-bucket
+   * reducers..
+   *
+   * ```ts
+   * const byClient = invoices.query()
+   *   .where('status', '==', 'open')
+   *   .groupBy('clientId')
+   *   .aggregate({ total: sum('amount'), n: count() })
+   *   .run()
+   * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
+   * ```
+   *
+   * Result rows carry the group key value under the grouping field
+   * name plus every reducer output from the spec. Buckets are
+   * emitted in first-seen order — consumers who want a specific
+   * ordering should `.sort()` downstream.
+   *
+   * **Cardinality caps:** a one-shot warning fires at 10_000
+   * distinct groups; `GroupCardinalityError` throws at 100_000.
+   * Grouping on a high-uniqueness field like `id` or `createdAt` is
+   * almost always a query mistake — the error message names the
+   * field and observed cardinality and suggests narrowing with
+   * `.where()` first.
+   *
+   * **Null / undefined keys:** records with a missing or explicitly
+   * `null` group field get their own buckets. `Map`-based
+   * partitioning distinguishes `undefined` from `null`, so the two
+   * cases do NOT merge. Consumers who want them merged should
+   * coalesce upstream with `.filter()`.
+   *
+   * **Joins are not applied** — same rationale as `.count()` and
+   * `.aggregate()`. Joined fields in are projection-only, so
+   * running a join inside a grouping pipeline would be wasteful and
+   * could trigger `DanglingReferenceError` in strict mode for a
+   * call whose intent is purely to bucket-and-reduce. Grouping by
+   * a joined field is explicitly out of scope for — file an
+   * issue if a real consumer needs it.
+   *
+   * **Filter clauses (`.filter(fn)`):** grouped queries still
+   * support filter clauses in the underlying plan — they run in
+   * the same candidate/filter pipeline that `.aggregate()` uses.
+   * The performance caveat is the same: filter clauses cost O(N)
+   * per record and can't be index-accelerated.
+   */
+  groupBy(field) {
+    const source = this.source;
+    const clauses = this.plan.clauses;
+    const executeRecords = () => {
+      const { candidates, remainingClauses } = candidateRecords(source, clauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
+    };
+    const upstreams = [];
+    if (source.subscribe) {
+      const subscribe = source.subscribe.bind(source);
+      upstreams.push({ subscribe: (cb) => subscribe(cb) });
+    }
+    const joinCtx = this.joinContext;
+    const dictLabelResolver = joinCtx?.resolveDictSource ? (() => {
+      const dictSource = joinCtx.resolveDictSource(field);
+      if (!dictSource) return void 0;
+      const snapshot = dictSource.snapshot();
+      const dictMap = /* @__PURE__ */ new Map();
+      for (const entry of snapshot) {
+        const k = entry["key"];
+        const labels = entry["labels"];
+        if (typeof k === "string" && labels && typeof labels === "object") {
+          dictMap.set(k, labels);
+        }
+      }
+      return async (key, locale, fallback) => {
+        const labels = dictMap.get(key);
+        if (!labels) return void 0;
+        if (labels[locale] !== void 0) return labels[locale];
+        const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+        for (const fb of chain) {
+          if (fb === "any") {
+            const any = Object.values(labels)[0];
+            if (any !== void 0) return any;
+          } else if (labels[fb] !== void 0) {
+            return labels[fb];
+          }
+        }
+        return void 0;
+      };
+    })() : void 0;
+    return this.aggregateStrategy.groupBy(executeRecords, field, upstreams, dictLabelResolver);
+  }
+  /**
+   * Re-run the query whenever the source notifies of changes.
+   * Returns an unsubscribe function. The callback receives the latest result.
+   * Throws if the source does not support subscriptions.
+   *
+   * **For joined queries, prefer `.live()`** — `subscribe()`
+   * only re-fires on LEFT-side changes, so joined data can be
+   * stale if the right side mutates between emissions. `.live()`
+   * merges change streams from every join target.
+   */
+  subscribe(cb) {
+    if (!this.source.subscribe) {
+      throw new Error("Query source does not support subscriptions. Pass a source with a subscribe() method.");
+    }
+    cb(this.toArray());
+    return this.source.subscribe(() => cb(this.toArray()));
+  }
+  /**
+   * Reactive terminal — returns a `LiveQuery<T>` that re-runs the
+   * query and updates its `value` whenever any source feeding it
+   * mutates..
+   *
+   * For non-joined queries, `.live()` is a convenience over the
+   * existing `.subscribe()` callback shape: a hand-rolled reactive
+   * primitive with `value` / `error` fields and a `subscribe(cb)`
+   * notification channel. Frame-agnostic — Vue / React / Solid
+   * adapters wrap it in their own primitive.
+   *
+   * For joined queries, `.live()` additionally subscribes to every
+   * join target's change stream. Mutations on a right-side
+   * collection (insert / update / delete of a client referenced by
+   * an invoice) re-fire the live query and re-evaluate every
+   * dependent left row. Right-side targets are deduped by
+   * collection name, so a chain that joins the same target twice
+   * (e.g. billing client + shipping client → both 'clients') only
+   * subscribes once.
+   *
+   * **Ref-mode behavior on right-side disappearance** — matches the
+   * eager `.toArray()` contract from :
+   *   - `strict`  → re-run throws `DanglingReferenceError`. The
+   *     LiveQuery catches the throw, stores it in `live.error`, and
+   *     notifies listeners (the throw does NOT propagate out of
+   *     the source's change handler — that would tear down the
+   *     emitter). Consumers check `live.error` after each
+   *     notification and render an error state in the UI.
+   *   - `warn`    → joined value flips to `null`; the existing
+   *     warn-channel deduplication keeps repeated re-runs from
+   *     spamming the console.
+   *   - `cascade` → no special handling needed; the cascade-
+   *     delete mechanism propagates the right-side delete into the
+   *     left collection on the next tick, and the live query
+   *     naturally re-fires with the orphaned left rows gone.
+   *
+   * Always call `live.stop()` when finished — it tears down every
+   * upstream subscription. The Vue layer's `onUnmounted` hook
+   * should call `stop()` automatically; raw consumers must do it
+   * themselves.
+   *
+   * **Limitations:**
+   *   - No granular delta updates — the whole query re-runs on
+   *     every change.
+   *   - No microtask batching — bursty changes produce one re-run
+   *     per change.
+   *   - No re-planning under live mutations — the planner picks
+   *     once at subscription time and reuses the same plan.
+   *   - Streaming live joins are deferred.
+   */
+  live() {
+    const upstreams = [];
+    if (this.source.subscribe) {
+      const leftSubscribe = this.source.subscribe.bind(this.source);
+      upstreams.push({
+        subscribe: (cb) => leftSubscribe(cb)
+      });
+    }
+    if (this.plan.joins.length > 0 && this.joinContext) {
+      const subscribed = /* @__PURE__ */ new Set();
+      for (const leg of this.plan.joins) {
+        if (subscribed.has(leg.target)) continue;
+        subscribed.add(leg.target);
+        const rightSource = this.joinContext.resolveSource(leg.target);
+        if (rightSource?.subscribe) {
+          const rightSubscribe = rightSource.subscribe.bind(rightSource);
+          upstreams.push({
+            subscribe: (cb) => rightSubscribe(cb)
+          });
+        }
+      }
+    }
+    return buildLiveQuery(() => this.toArray(), upstreams);
+  }
+  /**
+   * Return the plan as a JSON-friendly object. FilterClause entries are
+   * stripped (their `fn` cannot be serialized) and replaced with
+   * { type: 'filter', fn: '[function]' } so devtools can still see them.
+   */
+  toPlan() {
+    return serializePlan(this.plan);
+  }
+};
+function executePlanWithSource(source, plan) {
+  const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
+  let result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function candidateRecords(source, clauses) {
+  const indexes = source.getIndexes?.();
+  if (!indexes || !source.lookupById || clauses.length === 0) {
+    return { candidates: source.snapshot(), remainingClauses: clauses };
+  }
+  const lookupById = (id) => source.lookupById?.(id);
+  for (let i = 0; i < clauses.length; i++) {
+    const clause = clauses[i];
+    if (clause.type !== "field") continue;
+    if (!indexes.has(clause.field)) continue;
+    let ids = null;
+    if (clause.op === "==") {
+      ids = indexes.lookupEqual(clause.field, clause.value);
+    } else if (clause.op === "in" && Array.isArray(clause.value)) {
+      ids = indexes.lookupIn(clause.field, clause.value);
+    }
+    if (ids !== null) {
+      const remaining = [];
+      for (let j = 0; j < clauses.length; j++) {
+        if (j !== i) remaining.push(clauses[j]);
+      }
+      return {
+        candidates: materializeIds(ids, lookupById),
+        remainingClauses: remaining
+      };
+    }
+  }
+  return { candidates: source.snapshot(), remainingClauses: clauses };
+}
+function materializeIds(ids, lookupById) {
+  const out = [];
+  for (const id of ids) {
+    const record = lookupById(id);
+    if (record !== void 0) out.push(record);
+  }
+  return out;
+}
+function executePlan(records, plan) {
+  let result = filterRecords(records, plan.clauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function filterRecords(records, clauses) {
+  if (clauses.length === 0) return [...records];
+  const out = [];
+  for (const r of records) {
+    let matches = true;
+    for (const clause of clauses) {
+      if (!evaluateClause(r, clause)) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) out.push(r);
+  }
+  return out;
+}
+function sortRecords(records, orderBy) {
+  return [...records].sort((a, b) => {
+    for (const { field, direction } of orderBy) {
+      const av = readField(a, field);
+      const bv = readField(b, field);
+      const cmp = compareValues(av, bv);
+      if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
+    }
+    return 0;
+  });
+}
+function readField(record, field) {
+  if (record === null || record === void 0) return void 0;
+  if (!field.includes(".")) {
+    return record[field];
+  }
+  const segments = field.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function compareValues(a, b) {
+  if (a === void 0 || a === null) return b === void 0 || b === null ? 0 : 1;
+  if (b === void 0 || b === null) return -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+  return 0;
+}
+function serializePlan(plan) {
+  return {
+    clauses: plan.clauses.map(serializeClause),
+    orderBy: plan.orderBy,
+    limit: plan.limit,
+    offset: plan.offset,
+    joins: plan.joins
+  };
+}
+function serializeClause(clause) {
+  if (clause.type === "filter") {
+    return { type: "filter", fn: "[function]" };
+  }
+  if (clause.type === "group") {
+    return {
+      type: "group",
+      op: clause.op,
+      clauses: clause.clauses.map(serializeClause)
+    };
+  }
+  return clause;
+}
+
+// src/indexing/eager-indexes.ts
+var CollectionIndexes = class {
+  indexes = /* @__PURE__ */ new Map();
+  /**
+   * Declare an index. Subsequent record additions are tracked under it.
+   * Calling this twice for the same field is a no-op (idempotent).
+   */
+  declare(field) {
+    if (this.indexes.has(field)) return;
+    this.indexes.set(field, { field, buckets: /* @__PURE__ */ new Map() });
+  }
+  /** True if the given field has a declared index. */
+  has(field) {
+    return this.indexes.has(field);
+  }
+  /** All declared field names, in declaration order. */
+  fields() {
+    return [...this.indexes.keys()];
+  }
+  /**
+   * Build all declared indexes from a snapshot of records.
+   * Called once per hydration. O(N × indexes.size).
+   */
+  build(records) {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+      for (const { id, record } of records) {
+        addToIndex(idx, id, record);
+      }
+    }
+  }
+  /**
+   * Insert or update a single record across all indexes.
+   * Called by `Collection.put()` after the encrypted write succeeds.
+   *
+   * If `previousRecord` is provided, the record is removed from any old
+   * buckets first — this is the update path. Pass `null` for fresh adds.
+   */
+  upsert(id, newRecord, previousRecord) {
+    if (this.indexes.size === 0) return;
+    if (previousRecord !== null) {
+      this.remove(id, previousRecord);
+    }
+    for (const idx of this.indexes.values()) {
+      addToIndex(idx, id, newRecord);
+    }
+  }
+  /**
+   * Remove a record from all indexes. Called by `Collection.delete()`
+   * (and as the first half of `upsert` for the update path).
+   */
+  remove(id, record) {
+    if (this.indexes.size === 0) return;
+    for (const idx of this.indexes.values()) {
+      removeFromIndex(idx, id, record);
+    }
+  }
+  /** Drop all index data. Called when the collection is invalidated. */
+  clear() {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+    }
+  }
+  /**
+   * Equality lookup: return the set of record ids whose `field` matches
+   * the given value. Returns `null` if no index covers the field — the
+   * caller should fall back to a linear scan.
+   *
+   * The returned Set is a reference to the index's internal storage —
+   * callers must NOT mutate it.
+   */
+  lookupEqual(field, value) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const key = stringifyKey(value);
+    return idx.buckets.get(key) ?? EMPTY_SET;
+  }
+  /**
+   * Set lookup: return the union of record ids whose `field` matches any
+   * of the given values. Returns `null` if no index covers the field.
+   */
+  lookupIn(field, values) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const out = /* @__PURE__ */ new Set();
+    for (const value of values) {
+      const key = stringifyKey(value);
+      const bucket = idx.buckets.get(key);
+      if (bucket) {
+        for (const id of bucket) out.add(id);
+      }
+    }
+    return out;
+  }
+};
+var EMPTY_SET = /* @__PURE__ */ new Set();
+function stringifyKey(value) {
+  if (value === null || value === void 0) return "\0NULL\0";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  return "\0OBJECT\0";
+}
+function addToIndex(idx, id, record) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = stringifyKey(value);
+  let bucket = idx.buckets.get(key);
+  if (!bucket) {
+    bucket = /* @__PURE__ */ new Set();
+    idx.buckets.set(key, bucket);
+  }
+  bucket.add(id);
+}
+function removeFromIndex(idx, id, record) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = stringifyKey(value);
+  const bucket = idx.buckets.get(key);
+  if (!bucket) return;
+  bucket.delete(id);
+  if (bucket.size === 0) idx.buckets.delete(key);
+}
+
+// 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;
+}
+
+// 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/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/query/scan-builder.ts
+var DEFAULT_SCAN_PAGE_SIZE = 100;
+var ScanBuilder = class _ScanBuilder {
+  pageProvider;
+  pageSize;
+  clauses;
+  /**
+   * Zero-or-more join legs to apply per record as the stream flows.
+   * Each leg attaches the resolved right-side record (or null) under
+   * its alias. — streaming joins.
+   *
+   * Joins are evaluated AFTER clauses, so a `where()` filtered-out
+   * record never triggers a right-side lookup. This is the same
+   * ordering as `Query.toArray()` (clauses first, joins after) and
+   * keeps the streaming path from doing wasted work.
+   */
+  joins;
+  /**
+   * Join resolution context. Required for `.join()` to translate a
+   * field name into a target collection + ref mode and to resolve
+   * the right-side `JoinableSource`. Optional because tests
+   * construct ScanBuilder directly with synthetic page providers
+   * that don't know about ref() — calling `.join()` without a
+   * context throws with an actionable error.
+   */
+  joinContext;
+  constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext) {
+    this.pageProvider = pageProvider;
+    this.pageSize = pageSize;
+    this.clauses = clauses;
+    this.joins = joins;
+    this.joinContext = joinContext;
+  }
+  /**
+   * Add a field comparison. Runs per record as the scan stream
+   * flows through, so non-matching records are dropped before they
+   * reach `.aggregate()` or the iteration consumer. Multiple
+   * `.where()` calls are AND-combined — same semantics as
+   * `Query.where()`.
+   *
+   * Clauses cannot use the secondary-index fast path here because
+   * the scan sources records from the adapter's paginator, not from
+   * the in-memory cache where indexes live. Index-accelerated scans
+   * are a future optimization — the current implementation
+   * evaluates clauses per record in O(1) per clause.
+   */
+  where(field, op, value) {
+    const clause = { type: "field", field, op, value };
+    return new _ScanBuilder(
+      this.pageProvider,
+      this.pageSize,
+      [...this.clauses, clause],
+      this.joins,
+      this.joinContext
+    );
+  }
+  /**
+   * Escape hatch: add an arbitrary predicate function. Same
+   * non-serializable caveat as `Query.filter()` — filter clauses
+   * don't round-trip through `toPlan()`. Prefer `.where()` when
+   * possible.
+   */
+  filter(fn) {
+    const clause = {
+      type: "filter",
+      fn
+    };
+    return new _ScanBuilder(
+      this.pageProvider,
+      this.pageSize,
+      [...this.clauses, clause],
+      this.joins,
+      this.joinContext
+    );
+  }
+  /**
+   * Resolve a `ref()`-declared foreign key per record as the scan
+   * stream flows, attaching the right-side record (or null) under
+   * `opts.as`. — streaming joins over `scan()`.
+   *
+   * ```ts
+   * for await (const inv of invoices.scan().join('clientId', { as: 'client' })) {
+   *   await processInvoice(inv) // inv.client is attached
+   * }
+   *
+   * // Or terminate with .aggregate() for streaming joined aggregation
+   * const { total } = await invoices.scan()
+   *   .where('status', '==', 'open')
+   *   .join('clientId', { as: 'client' })
+   *   .aggregate({ total: sum('amount') })
+   * ```
+   *
+   * **The key difference from eager `.join()`:** the LEFT
+   * side streams page-by-page from the adapter and is never
+   * materialized. Memory ceiling on the left is O(pageSize), not
+   * O(rowCount). This is what makes streaming joins suitable for
+   * collections that exceed the eager join's 50_000-row ceiling.
+   *
+   * **Right-side strategy** is auto-selected per leg:
+   *   - **Indexed** — right source exposes `lookupById`, so each
+   *     left row costs O(1). This is the common path for
+   *     Collection right sides, which back `lookupById` with a Map
+   *     lookup over the in-memory cache. The right collection must
+   *     be in eager mode (the same constraint as eager join's
+   *     `querySourceForJoin` from ).
+   *   - **Hash** — right source has only `snapshot()`. Build a
+   *     `Map<id, record>` once at iteration start, probe per left
+   *     row. Same correctness, same per-row cost as the indexed
+   *     path; the difference is the upfront cost of materializing
+   *     the right side once.
+   *
+   * Both strategies hold the right side in memory for the duration
+   * of the iteration. The "streaming" property applies to the LEFT
+   * side only — true left-and-right streaming joins (where neither
+   * side fits in memory) require a sort-merge join planner that's
+   * out of scope for.
+   *
+   * **Ref-mode semantics** match eager `.join()` exactly:
+   *   - `strict`  → throws `DanglingReferenceError` mid-stream
+   *     when a left record points at a non-existent right id.
+   *     The throw aborts the async iterator — consumers should
+   *     wrap the `for await` in try/catch if they want to recover.
+   *   - `warn`    → attaches `null` and emits a one-shot warning
+   *     per unique dangling pair (deduped via the same warn
+   *     channel as eager join).
+   *   - `cascade` → attaches `null` silently. A delete-time mode;
+   *     dangling refs at read time are mid-flight or pre-existing
+   *     orphans, not a DSL error.
+   *
+   * Left records with null/undefined FK values attach `null`
+   * regardless of mode — same "no reference at all" policy as
+   * eager join and write-time `enforceRefsOnPut`.
+   *
+   * **Multi-FK chaining** is supported via repeated `.join()`
+   * calls: each leg resolves an independent ref. Each leg
+   * independently picks its right-side strategy and applies its
+   * own ref mode.
+   *
+   * **Joins are NOT applied** to a `.aggregate()` terminal that
+   * doesn't reference joined fields — wait, that's not quite
+   * right. The streaming path actually DOES apply joins before
+   * `.aggregate()` because the join attaches a field that the
+   * spec might reference. Unlike `Query.aggregate()` (which skips
+   * joins entirely as a projection-only short-circuit), the
+   * streaming aggregation can't know whether the spec touches a
+   * joined field, so it always applies joins. Consumers who want
+   * unjoined streaming aggregation should leave `.join()` off the
+   * chain — the chain is composable for a reason.
+   *
+   *  constraint #1 — every JoinLeg carries `partitionScope:
+   * 'all'` plumbed through but never read by. Same seam as
+   * eager join.
+   */
+  join(field, opts) {
+    if (!this.joinContext) {
+      throw new Error(
+        `ScanBuilder.join() requires a join context. Use collection.scan() to construct a join-capable scan instead of the ScanBuilder constructor directly (the direct constructor is only used for tests with synthetic page providers).`
+      );
+    }
+    const descriptor = this.joinContext.resolveRef(field);
+    if (!descriptor) {
+      throw new Error(
+        `ScanBuilder.join(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Add refs: { ${field}: ref('<target-collection>') } to the collection options, then retry.`
+      );
+    }
+    const leg = {
+      field,
+      as: opts.as,
+      target: descriptor.target,
+      mode: descriptor.mode,
+      strategy: void 0,
+      maxRows: void 0,
+      //  constraint #1 — always 'all' in, never read by
+      // the streaming executor. partition-aware scan joins
+      // will populate this from where() predicates without
+      // changing the planner shape.
+      partitionScope: "all"
+    };
+    return new _ScanBuilder(
+      this.pageProvider,
+      this.pageSize,
+      this.clauses,
+      [...this.joins, leg],
+      this.joinContext
+    );
+  }
+  /**
+   * Iterate the scan as an async iterable. Walks the page
+   * provider's cursors forward until exhaustion, applying every
+   * clause per record — only matching records are yielded.
+   *
+   * Backward-compatible with the previous async-generator `scan()`
+   * return type for `for await … of` consumers.
+   */
+  async *[Symbol.asyncIterator]() {
+    const joinResolvers = this.joins.length === 0 ? null : this.buildJoinResolvers();
+    let page = await this.pageProvider.listPage({ limit: this.pageSize });
+    while (true) {
+      for (const record of page.items) {
+        if (!this.recordMatches(record)) continue;
+        if (joinResolvers === null) {
+          yield record;
+        } else {
+          let attached = record;
+          for (const resolver of joinResolvers) {
+            attached = this.applyOneJoinStreaming(attached, resolver);
+          }
+          yield attached;
+        }
+      }
+      if (page.nextCursor === null) return;
+      page = await this.pageProvider.listPage({
+        cursor: page.nextCursor,
+        limit: this.pageSize
+      });
+    }
+  }
+  /**
+   * Per-leg right-side resolution state. Built once at iteration
+   * start and reused for every left record. Two strategies:
+   *
+   *   - `lookupById`: present when the right source exposes the
+   *     hook directly (typical Collection right side). Per-row
+   *     cost is O(1).
+   *   - `hashByPrimaryKey`: built from `snapshot()` when no
+   *     lookupById. Per-row cost is O(1) after the upfront O(N)
+   *     materialization. Same as eager join's hash strategy.
+   *
+   * `warnedKeys` is the per-leg dedup set for ref-mode 'warn'. We
+   * key on `field→target:refId` so the same dangling pair only
+   * warns once per iteration. The dedup is per-iteration, not
+   * per-process — a long-running scan that re-iterates would warn
+   * again, which is the desired behavior (the data may have
+   * changed between iterations).
+   */
+  buildJoinResolvers() {
+    if (!this.joinContext) {
+      throw new Error(
+        `ScanBuilder iterator: ${this.joins.length} join leg(s) present but no JoinContext attached. Use collection.scan() to construct a join-capable scan.`
+      );
+    }
+    const resolvers = [];
+    for (const leg of this.joins) {
+      const source = this.joinContext.resolveSource(leg.target);
+      if (!source) {
+        throw new Error(
+          `ScanBuilder.join() cannot resolve target collection "${leg.target}" (referenced from field "${leg.field}" on "${this.joinContext.leftCollection}"). Make sure the target collection has been opened via vault.collection() at least once before iterating the scan.`
+        );
+      }
+      let lookupById = null;
+      let hashByPrimaryKey = null;
+      if (source.lookupById) {
+        const fn = source.lookupById.bind(source);
+        lookupById = (id) => fn(id);
+      } else {
+        const map = /* @__PURE__ */ new Map();
+        for (const record of source.snapshot()) {
+          const rawId = readPath(record, "id");
+          const key = coerceRefKey2(rawId);
+          if (key !== null) map.set(key, record);
+        }
+        hashByPrimaryKey = map;
+      }
+      resolvers.push({
+        leg,
+        source,
+        lookupById,
+        hashByPrimaryKey,
+        warnedKeys: /* @__PURE__ */ new Set()
+      });
+    }
+    return resolvers;
+  }
+  /**
+   * Resolve a single join leg for one left record and return the
+   * left record with the joined field attached under
+   * `leg.as`. Pure function over `(left, resolver)`; never
+   * mutates the input.
+   *
+   * Ref-mode dispatch matches eager `applyJoins` from :
+   *   - null/undefined FK → attach null silently (always allowed)
+   *   - dangling FK + strict → throw `DanglingReferenceError`
+   *   - dangling FK + warn → attach null, warn-once per pair
+   *   - dangling FK + cascade → attach null silently
+   */
+  applyOneJoinStreaming(left, resolver) {
+    if (left === null || typeof left !== "object") {
+      return left;
+    }
+    const { leg } = resolver;
+    const rawId = readPath(left, leg.field);
+    const refKey = coerceRefKey2(rawId);
+    let right = void 0;
+    if (refKey !== null) {
+      if (resolver.lookupById !== null) {
+        right = resolver.lookupById(refKey);
+      } else if (resolver.hashByPrimaryKey !== null) {
+        right = resolver.hashByPrimaryKey.get(refKey);
+      }
+    }
+    const merged = {
+      ...left
+    };
+    if (right === void 0) {
+      if (refKey !== null && leg.mode === "strict") {
+        throw new DanglingReferenceError({
+          field: leg.field,
+          target: leg.target,
+          refId: refKey,
+          message: `ScanBuilder.join() strict dangling: record references "${leg.target}:${refKey}" via field "${leg.field}", but no such record exists. Use ref() mode 'warn' or 'cascade' if dangling refs are acceptable, or run vault.checkIntegrity() to find and fix the orphans.`
+        });
+      }
+      if (refKey !== null && leg.mode === "warn") {
+        const dedupKey = `${leg.field}\u2192${leg.target}:${refKey}`;
+        if (!resolver.warnedKeys.has(dedupKey)) {
+          resolver.warnedKeys.add(dedupKey);
+          console.warn(
+            `[noy-db] ScanBuilder.join() encountered dangling ref in 'warn' mode: field "${leg.field}" \u2192 "${leg.target}:${refKey}" not found. Attaching null.`
+          );
+        }
+      }
+      merged[leg.as] = null;
+    } else {
+      merged[leg.as] = right;
+    }
+    return merged;
+  }
+  /**
+   * Reduce the scan stream through a named set of reducers and
+   * return the final aggregated shape.
+   *
+   * Memory is O(reducers): one mutable state slot per spec key.
+   * Records flow through the pipeline one at a time via
+   * `for await` and are discarded after their `step()` is applied
+   * — never collected into an array. This is the distinguishing
+   * property from `Query.aggregate()`, which materializes the full
+   * match set first.
+   *
+   * Reuses the same reducer protocol as `Query.aggregate()`,
+   * so `count()`, `sum(field)`, `avg(field)`, `min(field)`,
+   * `max(field)` all work unchanged. The `{ seed }` parameter
+   * plumbing from  constraint #2 is honored transparently — the
+   * factories ignore it in and the scan executor never
+   * touches the per-reducer state construction.
+   *
+   * **Returns a Promise**, unlike `Query.aggregate().run()` which
+   * is synchronous. The scan is inherently async because it walks
+   * adapter pages, so the terminal has to be too. Consumers
+   * destructure with await:
+   *
+   * ```ts
+   * const { total, n } = await invoices.scan()
+   *   .where('year', '==', 2025)
+   *   .aggregate({ total: sum('amount'), n: count() })
+   * ```
+   *
+   * **No `.live()` in.** `scan().aggregate().live()` would
+   * require reconciling an unbounded streaming iteration with a
+   * change-stream subscription — a design problem, not just a code
+   * one. Consumers with huge collections and live needs should
+   * narrow with `.where()` enough to fit in the 50k `query()`
+   * limit and use `query().aggregate().live()` instead.
+   */
+  async aggregate(spec) {
+    const keys = Object.keys(spec);
+    const state = {};
+    for (const key of keys) {
+      state[key] = spec[key].init();
+    }
+    for await (const record of this) {
+      for (const key of keys) {
+        state[key] = spec[key].step(state[key], record);
+      }
+    }
+    const result = {};
+    for (const key of keys) {
+      result[key] = spec[key].finalize(state[key]);
+    }
+    return result;
+  }
+  /**
+   * Evaluate the clause list against a single record. Linear in
+   * the clause count; short-circuits on first false. Clauses on a
+   * scan are always re-evaluated per record — no index-accelerated
+   * path, because the stream sources records from the adapter
+   * paginator, not from the in-memory cache where indexes live.
+   */
+  recordMatches(record) {
+    if (this.clauses.length === 0) return true;
+    for (const clause of this.clauses) {
+      if (!evaluateClause(record, clause)) return false;
+    }
+    return true;
+  }
+};
+function coerceRefKey2(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Aggregation,
+  CollectionIndexes,
+  DEFAULT_JOIN_MAX_ROWS,
+  DanglingReferenceError,
+  GROUPBY_MAX_CARDINALITY,
+  GROUPBY_WARN_CARDINALITY,
+  GroupCardinalityError,
+  GroupedAggregation,
+  GroupedQuery,
+  IndexRequiredError,
+  IndexWriteFailureError,
+  JoinTooLargeError,
+  Query,
+  ScanBuilder,
+  applyJoins,
+  avg,
+  buildLiveAggregation,
+  buildLiveQuery,
+  count,
+  evaluateClause,
+  evaluateFieldClause,
+  executePlan,
+  groupAndReduce,
+  max,
+  min,
+  readPath,
+  reduceRecords,
+  resetGroupByWarnings,
+  resetJoinWarnings,
+  sum
+});
+//# sourceMappingURL=index.cjs.map