@noy-db/hub 0.2.0-pre.9 → 0.3.0-pre.2

package/dist/query/index.cjs

@@ -1,2375 +0,0 @@
-"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,
-  CrossJoinSourceUnknownError: () => CrossJoinSourceUnknownError,
-  CrossJoinTooLargeError: () => CrossJoinTooLargeError,
-  DEFAULT_CROSS_JOIN_MAX_ROWS: () => DEFAULT_CROSS_JOIN_MAX_ROWS,
-  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,
-  GroupedQueryN: () => GroupedQueryN,
-  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 "wherePredicate":
-      return clause.fn(record, clause.ctx);
-    case "crossJoin":
-      throw new Error(
-        `evaluateClause: 'crossJoin' clauses are expansion primitives and are not evaluated per-record. This is a query planner routing error \u2014 crossJoin clauses must be extracted from the clause list before calling evaluateClause or filterRecords.`
-      );
-    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 CrossJoinTooLargeError = class extends NoydbError {
-  target;
-  expected;
-  limit;
-  constructor(opts) {
-    super(
-      "CROSS_JOIN_TOO_LARGE",
-      `crossJoin("${opts.target}"): would produce ${opts.expected} rows, exceeding the limit of ${opts.limit}. Narrow the left side with .where() first, or raise the ceiling with crossJoin("${opts.target}", { ..., maxRows: ${opts.expected} }).`
-    );
-    this.name = "CrossJoinTooLargeError";
-    this.target = opts.target;
-    this.expected = opts.expected;
-    this.limit = opts.limit;
-  }
-};
-var CrossJoinSourceUnknownError = class extends NoydbError {
-  target;
-  leftCollection;
-  constructor(target, leftCollection) {
-    super(
-      "CROSS_JOIN_SOURCE_UNKNOWN",
-      `crossJoin("${target}"): collection "${target}" is not known in the vault (cross-joining from "${leftCollection}"). Make sure "${target}" is open in the same vault before executing this query.`
-    );
-    this.name = "CrossJoinSourceUnknownError";
-    this.target = target;
-    this.leftCollection = leftCollection;
-  }
-};
-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;
-  },
-  groupByN() {
-    throw NOT_ENABLED;
-  },
-  scanAggregate() {
-    throw NOT_ENABLED;
-  }
-};
-
-// src/query/builder.ts
-var EMPTY_PLAN = {
-  clauses: [],
-  orderBy: [],
-  limit: void 0,
-  offset: 0,
-  joins: []
-};
-var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
-var Query = class _Query {
-  source;
-  plan;
-  joinContext;
-  aggregateStrategy;
-  predicates;
-  constructor(source, plan = EMPTY_PLAN, joinContext, aggregateStrategy = NO_AGGREGATE, predicates) {
-    this.source = source;
-    this.plan = plan;
-    this.joinContext = joinContext;
-    this.aggregateStrategy = aggregateStrategy;
-    this.predicates = predicates;
-  }
-  /**
-   * @internal — accessor for the materialized-view dependency
-   * analyzer. Not part of the public API; consumers should use the
-   * builder methods, not inspect the plan directly.
-   */
-  _plan() {
-    return this.plan;
-  }
-  /**
-   * @internal — accessor for the materialized-view dependency
-   * analyzer. Returns the join resolution context (or `undefined` for
-   * queries constructed without a Collection backing).
-   */
-  _joinContext() {
-    return this.joinContext;
-  }
-  /**
-   * @internal — clone this Query with a declared-predicate map
-   * attached. Used by the materialized-view registry to enable
-   * `.wherePredicate(name, ctx?)` for the MV's query callback.
-   * Consumers don't call this directly.
-   */
-  _withPredicates(predicates) {
-    return new _Query(
-      this.source,
-      this.plan,
-      this.joinContext,
-      this.aggregateStrategy,
-      predicates
-    );
-  }
-  /**
-   * Filter by a registered deterministic predicate. Requires
-   * the Query to have been augmented with a predicates map (typically
-   * via the materialized-view registry — bare Queries constructed
-   * outside an MV throw on `.wherePredicate()`).
-   *
-   * `ctx` is an optional opaque value passed verbatim to the predicate
-   * function. Both `predicateHash` (from the registration) and a
-   * canonical-JSON hash of `ctx` fold into the MV's `queryHash`, so
-   * either changing forces refresh on next visit.
-   */
-  wherePredicate(name, ctx) {
-    if (!this.predicates) {
-      throw new Error(
-        `.wherePredicate("${name}"): no predicates registered on this Query. Function-based predicates require the Query to be obtained from inside a materialized-view query() callback whose strategy declares \`predicates: { ${name}: { hash, fn } }\`.`
-      );
-    }
-    const decl = this.predicates.get(name);
-    if (!decl) {
-      throw new Error(
-        `.wherePredicate("${name}"): predicate not registered. Available: ${[...this.predicates.keys()].join(", ") || "(none)"}.`
-      );
-    }
-    const clause = {
-      type: "wherePredicate",
-      name,
-      ctx,
-      predicateHash: decl.hash,
-      ctxHash: canonicalCtxHash(ctx),
-      fn: decl.fn
-    };
-    return new _Query(
-      this.source,
-      { ...this.plan, clauses: [...this.plan.clauses, clause] },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /** 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,
-      this.predicates
-    );
-  }
-  /**
-   * 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, this.predicates)
-    );
-    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,
-      this.predicates
-    );
-  }
-  /**
-   * 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, this.predicates)
-    );
-    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,
-      this.predicates
-    );
-  }
-  /** 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,
-      this.predicates
-    );
-  }
-  /** 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,
-      this.predicates
-    );
-  }
-  /** Cap the result size. */
-  limit(n) {
-    return new _Query(
-      this.source,
-      { ...this.plan, limit: n },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /** Skip the first N matching records (after ordering). */
-  offset(n) {
-    return new _Query(
-      this.source,
-      { ...this.plan, offset: n },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /**
-   * 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,
-      this.predicates
-    );
-  }
-  /**
-   * Cartesian-product cross-join against `target` collection. Each result row
-   * carries the original `T` fields plus `result[as]` populated from every
-   * right-side row (or the filtered subset when `on:` is supplied).
-   *
-   * **Order matters:** `.where().crossJoin()` filters BEFORE expanding (cheaper);
-   * `.crossJoin().where('alias.field', ...)` filters AFTER (required when the
-   * where clause references the aliased fields).
-   *
-   * **Cost ceiling:** `CrossJoinTooLargeError` fires before allocation when
-   * `leftRows × rightRows` (or the cumulative lateral count) exceeds the limit.
-   * Default: 50,000 rows. Override per-clause with `{ maxRows: N }`.
-   *
-   * **`on:` shapes:**
-   *   - `on: (left) => TTarget[]`              — subset form (most efficient)
-   *   - `on: (left) => (right) => boolean`     — predicate form
-   *   - `on: { predicate: 'name' }`            — MV-safe, hash-tracked form
-   *     (requires the Query to have been augmented via `_withPredicates`)
-   *
-   * Requires a JoinContext (constructed via `collection.query()`).
-   */
-  crossJoin(target, opts) {
-    if (!this.joinContext) {
-      throw new Error(
-        `Query.crossJoin("${target}"): requires a join context. Use collection.query() to construct a cross-join-capable Query instead of the Query constructor directly.`
-      );
-    }
-    let onFn;
-    let onPredicateName;
-    if (opts.on !== void 0) {
-      if (typeof opts.on === "function") {
-        onFn = opts.on;
-        if (this.predicates) {
-          console.warn(
-            `Query.crossJoin("${target}", { on: callback }): inline on: callback inside a withMaterializedView query() disables queryHash drift detection for this cross-join. Use on: { predicate: '<name>' } to enable it.`
-          );
-        }
-      } else {
-        const predName = opts.on.predicate;
-        if (!this.predicates) {
-          throw new Error(
-            `Query.crossJoin("${target}", { on: { predicate: "${predName}" } }): the { predicate } form requires a predicates map. Use this form inside a withMaterializedView query() callback that declares predicates: { ${predName}: { hash, fn } }.`
-          );
-        }
-        const decl = this.predicates.get(predName);
-        if (!decl) {
-          throw new Error(
-            `Query.crossJoin("${target}"): predicate "${predName}" not registered. Available: ${[...this.predicates.keys()].join(", ") || "(none)"}.`
-          );
-        }
-        const as = opts.as;
-        const predicateFn = decl.fn;
-        onFn = (_left) => (right) => predicateFn({ ..._left, [as]: right });
-        onPredicateName = predName;
-      }
-    }
-    const clause = {
-      type: "crossJoin",
-      target,
-      as: opts.as,
-      ...onFn !== void 0 && { on: onFn },
-      ...onPredicateName !== void 0 && { onPredicateName },
-      ...opts.maxRows !== void 0 && { maxRows: opts.maxRows }
-    };
-    return new _Query(
-      this.source,
-      { ...this.plan, clauses: [...this.plan.clauses, clause] },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /**
-   * 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, this.joinContext);
-    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() {
-    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
-      if (!this.joinContext) {
-        throw new Error(
-          `Query.count(): plan contains crossJoin clauses but no JoinContext is attached.`
-        );
-      }
-      return executeClausePipeline(this.source, this.plan.clauses, this.joinContext).length;
-    }
-    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 joinCtx = this.joinContext;
-    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
-    const executeRecords = () => {
-      if (hasCrossJoins) {
-        if (!joinCtx) throw new Error("Query.aggregate(): crossJoin requires a join context");
-        return executeClausePipeline(source, clauses, joinCtx);
-      }
-      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);
-  }
-  groupBy(...fields) {
-    if (fields.length === 0) {
-      throw new Error(".groupBy() requires at least one field");
-    }
-    const source = this.source;
-    const clauses = this.plan.clauses;
-    const joinCtx = this.joinContext;
-    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
-    const executeRecords = () => {
-      if (hasCrossJoins) {
-        if (!joinCtx) throw new Error("Query.groupBy(): crossJoin requires a join context");
-        return executeClausePipeline(source, clauses, joinCtx);
-      }
-      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) });
-    }
-    if (fields.length === 1) {
-      const field = fields[0];
-      const dictLabelResolver = buildDictLabelResolver(this.joinContext, field);
-      return this.aggregateStrategy.groupBy(
-        executeRecords,
-        field,
-        upstreams,
-        dictLabelResolver
-      );
-    }
-    return this.aggregateStrategy.groupByN(
-      executeRecords,
-      fields,
-      upstreams
-    );
-  }
-  /**
-   * 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)
-          });
-        }
-      }
-    }
-    if (this.joinContext) {
-      const subscribedCross = /* @__PURE__ */ new Set();
-      for (const clause of this.plan.clauses) {
-        if (clause.type !== "crossJoin") continue;
-        if (subscribedCross.has(clause.target)) continue;
-        subscribedCross.add(clause.target);
-        const rightSource = this.joinContext.resolveSource(clause.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, joinContext) {
-  const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
-  let result;
-  if (hasCrossJoins) {
-    if (!joinContext) {
-      throw new Error(
-        `Query.toArray(): plan contains crossJoin clauses but no JoinContext is attached. Use collection.query() instead of new Query() for cross-join support.`
-      );
-    }
-    result = executeClausePipeline(source, plan.clauses, joinContext);
-  } else {
-    const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
-    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) {
-  if (plan.clauses.some((c) => c.type === "crossJoin")) {
-    throw new Error(
-      `executePlan(): does not support crossJoin clauses. executePlan is a stateless pure function \u2014 it cannot resolve cross-join right-side collections. Use Query.toArray() (via collection.query()) instead.`
-    );
-  }
-  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 executeClausePipeline(source, clauses, joinContext) {
-  let rel = [...source.snapshot()];
-  let filterBatch = [];
-  for (const clause of clauses) {
-    if (clause.type === "crossJoin") {
-      if (filterBatch.length > 0) {
-        rel = filterRecords(rel, filterBatch);
-        filterBatch = [];
-      }
-      const rightSource = joinContext.resolveSource(clause.target);
-      if (!rightSource) {
-        throw new CrossJoinSourceUnknownError(clause.target, joinContext.leftCollection);
-      }
-      rel = applyCrossJoin(rel, clause, rightSource);
-    } else {
-      filterBatch.push(clause);
-    }
-  }
-  if (filterBatch.length > 0) {
-    rel = filterRecords(rel, filterBatch);
-  }
-  return rel;
-}
-function applyCrossJoin(leftRel, clause, rightSource) {
-  const rightRows = rightSource.snapshot();
-  const maxRows = clause.maxRows ?? DEFAULT_CROSS_JOIN_MAX_ROWS;
-  const { as } = clause;
-  if (!clause.on) {
-    const product = leftRel.length * rightRows.length;
-    if (product > maxRows) {
-      throw new CrossJoinTooLargeError({ target: clause.target, expected: product, limit: maxRows });
-    }
-    const expanded2 = [];
-    for (const left of leftRel) {
-      const leftObj = left;
-      for (const right of rightRows) {
-        expanded2.push({ ...leftObj, [as]: right });
-      }
-    }
-    return expanded2;
-  }
-  const expanded = [];
-  let cumulative = 0;
-  for (const left of leftRel) {
-    const callbackResult = clause.on(left);
-    let filteredRight;
-    if (Array.isArray(callbackResult)) {
-      filteredRight = callbackResult;
-    } else {
-      filteredRight = rightRows.filter(
-        callbackResult
-      );
-    }
-    cumulative += filteredRight.length;
-    if (cumulative > maxRows) {
-      throw new CrossJoinTooLargeError({
-        target: clause.target,
-        expected: cumulative,
-        limit: maxRows
-      });
-    }
-    const leftObj = left;
-    for (const right of filteredRight) {
-      expanded.push({ ...leftObj, [as]: right });
-    }
-  }
-  return expanded;
-}
-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 === "wherePredicate") {
-    return {
-      type: "wherePredicate",
-      name: clause.name,
-      ctx: clause.ctx,
-      predicateHash: clause.predicateHash,
-      ctxHash: clause.ctxHash,
-      fn: "[function]"
-    };
-  }
-  if (clause.type === "group") {
-    return {
-      type: "group",
-      op: clause.op,
-      clauses: clause.clauses.map(serializeClause)
-    };
-  }
-  if (clause.type === "crossJoin") {
-    return {
-      type: "crossJoin",
-      target: clause.target,
-      as: clause.as,
-      on: clause.on ? "[function]" : void 0,
-      onPredicateName: clause.onPredicateName,
-      maxRows: clause.maxRows
-    };
-  }
-  return clause;
-}
-function canonicalCtxHash(ctx) {
-  if (ctx === void 0) return "";
-  const canonical = JSON.stringify(ctx, (_key, value) => {
-    if (value && typeof value === "object" && !Array.isArray(value)) {
-      const sorted = {};
-      for (const k of Object.keys(value).sort()) {
-        sorted[k] = value[k];
-      }
-      return sorted;
-    }
-    return value;
-  });
-  let h = 5381;
-  for (let i = 0; i < canonical.length; i++) {
-    h = (h << 5) + h ^ canonical.charCodeAt(i);
-  }
-  return (h >>> 0).toString(16).padStart(8, "0");
-}
-function buildDictLabelResolver(joinCtx, field) {
-  if (!joinCtx?.resolveDictSource) return void 0;
-  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;
-  };
-}
-
-// 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/canonical-key.ts
-function canonicalGroupKey(fields, row) {
-  const sorted = [...fields].sort();
-  const parts = [];
-  for (const name of sorted) {
-    const v = row[name];
-    const serialised = v === void 0 ? "undefined" : JSON.stringify(v);
-    parts.push(`${name}=${serialised}`);
-  }
-  return parts.join("|");
-}
-
-// src/aggregate/groupby.ts
-var GROUPBY_WARN_CARDINALITY = 1e4;
-var GROUPBY_MAX_CARDINALITY = 1e5;
-var warnedCardinalityFields = /* @__PURE__ */ new Set();
-function warnCardinalityApproaching(fields, observed) {
-  const key = JSON.stringify([...fields].sort());
-  if (warnedCardinalityFields.has(key)) return;
-  warnedCardinalityFields.add(key);
-  const label = `[${fields.join(", ")}]`;
-  console.warn(
-    `[noy-db] .groupBy(${label}) 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 GroupedQueryBase = class {
-  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver) {
-    this.executeRecords = executeRecords;
-    this.upstreams = upstreams;
-    this.dictLabelResolver = dictLabelResolver;
-    this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
-  }
-  executeRecords;
-  upstreams;
-  dictLabelResolver;
-  /**
-   * Field set this grouped query buckets on. Stored in declaration
-   * order — the same order is preserved on every result row by
-   * `groupAndReduce`. For the single-field constructor, this is
-   * `[field]`.
-   */
-  fields;
-};
-var GroupedQuery = class extends GroupedQueryBase {
-  /**
-   * 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.fields,
-      spec,
-      this.upstreams,
-      this.dictLabelResolver
-    );
-  }
-};
-var GroupedQueryN = class extends GroupedQueryBase {
-  aggregate(spec) {
-    return new GroupedAggregation(
-      this.executeRecords,
-      this.fields,
-      spec,
-      this.upstreams,
-      this.dictLabelResolver
-    );
-  }
-};
-function groupAndReduce(records, fieldOrFields, spec) {
-  const fields = typeof fieldOrFields === "string" ? [fieldOrFields] : fieldOrFields;
-  if (fields.length === 0) {
-    throw new Error(".groupBy() requires at least one field");
-  }
-  const buckets = /* @__PURE__ */ new Map();
-  const fieldLabel = fields.length === 1 ? fields[0] : `[${fields.join(", ")}]`;
-  for (const record of records) {
-    const keyValues = {};
-    for (const f of fields) {
-      keyValues[f] = readPath(record, f);
-    }
-    const dedupKey = canonicalGroupKey(fields, keyValues);
-    let bucket = buckets.get(dedupKey);
-    if (bucket === void 0) {
-      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {
-        throw new GroupCardinalityError(
-          fieldLabel,
-          buckets.size + 1,
-          GROUPBY_MAX_CARDINALITY
-        );
-      }
-      bucket = { keyValues, records: [] };
-      buckets.set(dedupKey, bucket);
-    }
-    bucket.records.push(record);
-  }
-  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
-    warnCardinalityApproaching(fields, buckets.size);
-  }
-  const reducerKeys = Object.keys(spec);
-  const out = [];
-  for (const bucket of buckets.values()) {
-    const state = {};
-    for (const rk of reducerKeys) {
-      state[rk] = spec[rk].init();
-    }
-    for (const record of bucket.records) {
-      for (const rk of reducerKeys) {
-        state[rk] = spec[rk].step(state[rk], record);
-      }
-    }
-    const row = {};
-    for (const f of fields) {
-      row[f] = bucket.keyValues[f];
-    }
-    for (const rk of reducerKeys) {
-      row[rk] = spec[rk].finalize(state[rk]);
-    }
-    out.push(row);
-  }
-  return out;
-}
-var GroupedAggregation = class {
-  constructor(executeRecords, fields, spec, upstreams, dictLabelResolver) {
-    this.executeRecords = executeRecords;
-    this.spec = spec;
-    this.upstreams = upstreams;
-    this.dictLabelResolver = dictLabelResolver;
-    this.fields = typeof fields === "string" ? [fields] : [...fields];
-  }
-  executeRecords;
-  spec;
-  upstreams;
-  dictLabelResolver;
-  fields;
-  /** Execute the query, group, reduce, and return an array of rows. */
-  run() {
-    return groupAndReduce(this.executeRecords(), this.fields, 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`.
-   *
-   * Dict-label resolution is single-field only — multi-key groupings
-   * do not produce a `<field>Label`. The resolver is only attached
-   * by the builder when `fields.length === 1`.
-   */
-  async runAsync(opts) {
-    const rows = groupAndReduce(this.executeRecords(), this.fields, this.spec);
-    if (!opts?.locale || !this.dictLabelResolver || this.fields.length !== 1) return rows;
-    const resolve = this.dictLabelResolver;
-    const locale = opts.locale;
-    const fallback = opts.fallback;
-    const field = this.fields[0];
-    const labelKey = `${field}Label`;
-    return Promise.all(
-      rows.map(async (row) => {
-        const key = row[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.fields, 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,
-  CrossJoinSourceUnknownError,
-  CrossJoinTooLargeError,
-  DEFAULT_CROSS_JOIN_MAX_ROWS,
-  DEFAULT_JOIN_MAX_ROWS,
-  DanglingReferenceError,
-  GROUPBY_MAX_CARDINALITY,
-  GROUPBY_WARN_CARDINALITY,
-  GroupCardinalityError,
-  GroupedAggregation,
-  GroupedQuery,
-  GroupedQueryN,
-  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