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

package/dist/chunk-ZSX4S5XB.js

@@ -0,0 +1,1289 @@
+import {
+  DEFAULT_CROSS_JOIN_MAX_ROWS,
+  DEFAULT_JOIN_MAX_ROWS,
+  applyJoins,
+  bucketByRefKey,
+  coerceRefKey,
+  joinsDropLeftRows,
+  orderReferencesJoinAlias,
+  splitAroundJoins
+} from "./chunk-4I522ERM.js";
+import {
+  describeJoinOn,
+  joinOnDispatch,
+  normalizeJoinOn
+} from "./chunk-MKXXMNJH.js";
+import {
+  ScanBuilder
+} from "./chunk-F24ZZTHQ.js";
+import {
+  installMethods
+} from "./chunk-F6NCB7KT.js";
+import {
+  Query,
+  indexableClauses,
+  installRelateHooks,
+  isRangeOperator,
+  pickCompound,
+  pickCompoundOrder,
+  viaOrdersField
+} from "./chunk-7JE7BDYJ.js";
+import {
+  gateTerminal
+} from "./chunk-5O7D6ZTW.js";
+import {
+  readPath
+} from "./chunk-HLEK5VAN.js";
+import {
+  isViaPrefixProbe
+} from "./chunk-Z5HTYMMQ.js";
+import {
+  CrossJoinTooLargeError,
+  DanglingReferenceError,
+  RefNotDeclaredError,
+  TraversalCycleError
+} from "./chunk-244VXYPG.js";
+
+// src/kernel/query/relate/explain.ts
+var WARN_FRACTION = 0.8;
+function tupleSourceOf(indexes) {
+  return { compoundTuples: () => indexes.compoundTuples?.() ?? [] };
+}
+function indexDispatchFor(source, clauses) {
+  const indexes = source.getIndexes?.();
+  if (!indexes || !source.lookupById || clauses.length === 0) return null;
+  const compound = compoundDispatchFor(source, indexes, clauses);
+  if (compound) return compound;
+  const prefixed = prefixDispatchFor(indexes, clauses);
+  if (prefixed) return prefixed;
+  for (let i = 0; i < clauses.length; i++) {
+    const clause = clauses[i];
+    if (clause.type !== "field") continue;
+    if (!indexes.has(clause.field) && indexes.hasSorted?.(clause.field) !== true) continue;
+    if (clause.via && clause.via.indexValue === void 0) continue;
+    const probeValue = clause.via ? clause.via.indexValue : clause.value;
+    let ids = null;
+    let dispatch = "index:hash";
+    if (clause.op === "==") {
+      ids = indexes.lookupEqual(clause.field, probeValue);
+    } else if (clause.op === "in" && Array.isArray(probeValue)) {
+      ids = indexes.lookupIn(clause.field, probeValue);
+    } else if (clause.via === void 0 && isRangeOperator(clause.op)) {
+      ids = indexes.lookupRange?.(clause.field, clause.op, clause.value) ?? null;
+      dispatch = "index:range";
+    }
+    if (ids !== null) return { consumed: /* @__PURE__ */ new Map([[i, dispatch]]), rows: ids.size };
+  }
+  return null;
+}
+function prefixDispatchFor(indexes, clauses) {
+  for (let i = 0; i < clauses.length; i++) {
+    const clause = clauses[i];
+    if (clause.type !== "field" || clause.via === void 0) continue;
+    const probe = clause.via.indexValue;
+    if (!isViaPrefixProbe(probe)) continue;
+    if (indexes.hasSorted?.(clause.field) !== true) continue;
+    const ids = /* @__PURE__ */ new Set();
+    for (const prefix of probe.prefixes) {
+      const hit = indexes.lookupRange?.(clause.field, "startsWith", prefix) ?? null;
+      if (hit === null) return null;
+      for (const id of hit) ids.add(id);
+    }
+    return { consumed: /* @__PURE__ */ new Map([[i, "index:prefix"]]), rows: ids.size };
+  }
+  return null;
+}
+function compoundDispatchFor(source, indexes, clauses) {
+  const pick = pickCompound(tupleSourceOf(indexes), clauses);
+  if (!pick) return null;
+  if (indexes.compoundSize?.(pick.fields) !== source.snapshot().length) return null;
+  const ids = indexes.lookupCompound?.(pick.fields, pick.values, pick.range) ?? null;
+  if (!ids) return null;
+  const consumed = /* @__PURE__ */ new Map();
+  for (const at of pick.consumed) consumed.set(at, "index:compound");
+  return { consumed, rows: ids.size };
+}
+function orderedIndexPick(source, plan) {
+  const limit = plan.limit;
+  if (limit === void 0 || plan.orderBy.length !== 1) return null;
+  const [order] = plan.orderBy;
+  if (!order || order.by === "label") return null;
+  const indexes = source.getIndexes?.();
+  if (!indexes || !source.lookupById) return null;
+  if (viaOrdersField(source.via, order.field)) return null;
+  const snapshotRows = source.snapshot().length;
+  if (plan.clauses.length === 0) {
+    if (indexes.hasSorted?.(order.field) !== true) return null;
+    if (indexes.sortedSize?.(order.field) !== snapshotRows) return null;
+    const ids2 = indexes.orderedIds?.(order.field, order.direction) ?? null;
+    if (!ids2) return null;
+    return { rows: pageOf(ids2.length, plan.offset, limit), clauseDispatch: null, detail: `sorted index on "${order.field}"` };
+  }
+  const { eq } = indexableClauses(plan.clauses);
+  if (eq.size !== plan.clauses.length) return null;
+  const match = pickCompoundOrder(tupleSourceOf(indexes), eq, order.field);
+  if (!match) return null;
+  if (indexes.compoundSize?.(match.fields) !== snapshotRows) return null;
+  const ids = indexes.compoundOrderedIds?.(match.fields, match.values, order.direction) ?? null;
+  if (!ids) return null;
+  return {
+    rows: pageOf(ids.length, plan.offset, limit),
+    clauseDispatch: "index:compound",
+    detail: `compound index on (${match.fields.join(", ")})`
+  };
+}
+function pageOf(total, offset, limit) {
+  return Math.min(Math.max(0, total - offset), limit);
+}
+function isSupersetDispatch(dispatch, clause) {
+  if (dispatch === "index:prefix" || dispatch === "index:compound") return true;
+  if (dispatch !== "index:hash") return false;
+  return clause.type === "field" && (clause.op === "==" || clause.op === "in");
+}
+function describeClause(clause) {
+  switch (clause.type) {
+    case "field": {
+      const detail = clause.subquery !== void 0 ? `${clause.field} ${clause.op} subquery(${clause.subquery.from}) \u2192 ${clause.subquery.ids} ids` : `${clause.field} ${clause.op} ${formatValue(clause.value)}`;
+      return { op: "where", detail };
+    }
+    case "group":
+      return { op: "group", detail: `${clause.op} (${clause.clauses.length} clause${clause.clauses.length === 1 ? "" : "s"})` };
+    case "filter":
+      return { op: "filter", detail: "fn" };
+    case "wherePredicate":
+      return { op: "wherePredicate", detail: clause.name };
+    case "crossJoin":
+      return {
+        op: clause.leftAs === void 0 ? "crossJoin" : "crossJoinWith",
+        detail: (clause.leftAs === void 0 ? `${clause.as} x ${clause.target}` : `${clause.leftAs} x ${clause.as} (self ${clause.target})`) + `${clause.on ? " on fn" : ""}${clause.outer === true ? " outer" : ""}`
+      };
+  }
+}
+function formatValue(value) {
+  if (typeof value === "bigint") return `${value.toString()}n`;
+  try {
+    const json = JSON.stringify(value);
+    return json === void 0 ? String(value) : json;
+  } catch {
+    return "[unserializable]";
+  }
+}
+function referencedFields(plan) {
+  const out = [];
+  const walk = (clauses) => {
+    for (const c of clauses) {
+      if (c.type === "field") out.push(c.field);
+      else if (c.type === "group") walk(c.clauses);
+    }
+  };
+  walk(plan.clauses);
+  for (const o of plan.orderBy) out.push(o.field);
+  return [...new Set(out)];
+}
+function capStatus(observed, limit) {
+  if (observed > limit) return "exceeded";
+  if (observed > limit * WARN_FRACTION) return "warn";
+  return "ok";
+}
+function explainPlan(source, plan, joinContext) {
+  const nodes = [];
+  const caps = [];
+  const indexes = source.getIndexes?.() ?? null;
+  const indexedFields = indexes ? indexes.fields() : [];
+  const sourceRows = source.snapshot().length;
+  let rows = sourceRows;
+  const reducerRewrite = collectReducerRewrites(source.via, referencedFields(plan));
+  const sourceNotes = [];
+  const notHydrated = source.hydration?.isHydrated() === false;
+  if (notHydrated) {
+    sourceNotes.push(
+      "collection not hydrated \u2014 this plan's row estimates are not authoritative; call `await collection.list()` / `await collection.get(id)` first"
+    );
+  }
+  for (const r of reducerRewrite) {
+    sourceNotes.push(`reducer rewrite: ${r.brand}("${r.field}")`);
+  }
+  nodes.push({
+    op: "source",
+    dispatch: "source",
+    detail: notHydrated ? `snapshot (NOT HYDRATED \u2014 nothing has been read yet${indexedFields.length > 0 ? `; indexes: ${indexedFields.join(", ")}` : ""})` : indexedFields.length > 0 ? `snapshot (indexes: ${indexedFields.join(", ")})` : "snapshot (no indexes)",
+    estimatedRows: sourceRows,
+    notes: sourceNotes,
+    children: []
+  });
+  const hasCrossJoin = plan.clauses.some((c) => c.type === "crossJoin");
+  const { preJoin, postJoin } = splitAroundJoins(plan.clauses, plan.joins);
+  const orderPostJoin = orderReferencesJoinAlias(plan.orderBy, plan.joins);
+  const runsPostJoin = postJoin.length > 0 || orderPostJoin;
+  const innerSplit = !runsPostJoin && plan.joins.length > 0 && joinsDropLeftRows(plan.joins);
+  let ordered = null;
+  if (hasCrossJoin) {
+    for (const clause of plan.clauses) {
+      if (clause.type === "crossJoin") {
+        const rightRows = joinContext?.resolveSource(clause.target)?.snapshot().length;
+        const limit = clause.maxRows ?? DEFAULT_CROSS_JOIN_MAX_ROWS;
+        const product = rows !== void 0 && rightRows !== void 0 ? rows * rightRows : void 0;
+        const { op, detail } = describeClause(clause);
+        const notes = [
+          rightRows === void 0 ? "right side unresolved" : `right side ${rightRows} rows`,
+          `cap ${limit}`
+        ];
+        nodes.push({ op, dispatch: "crossJoin", detail, estimatedRows: product, notes, children: [] });
+        if (product !== void 0) {
+          caps.push({ name: `crossJoin:${clause.as}`, limit, observed: product, status: capStatus(product, limit) });
+        }
+        rows = product;
+      } else {
+        nodes.push(scanNode(clause, rows, ["index fast path unavailable: the plan carries a crossJoin"]));
+      }
+    }
+  } else {
+    ordered = runsPostJoin || innerSplit ? null : orderedIndexPick(source, plan);
+    const pick = ordered ? null : indexDispatchFor(source, preJoin);
+    if (ordered) rows = ordered.rows;
+    preJoin.forEach((clause, i) => {
+      const dispatch = ordered ? ordered.clauseDispatch : pick?.consumed.get(i) ?? null;
+      if (dispatch !== null) {
+        const { op, detail } = describeClause(clause);
+        if (pick) rows = pick.rows;
+        const notes = isSupersetDispatch(dispatch, clause) ? [`${dispatch === "index:prefix" ? "prefix cover" : "index match"} is a superset: the clause still filters the candidates exactly`] : [];
+        nodes.push({ op, dispatch, detail, estimatedRows: rows, notes, children: [] });
+        return;
+      }
+      nodes.push(scanNode(clause, rows, scanReason(clause, indexes, pick !== null)));
+    });
+  }
+  const emitJoins = () => {
+    for (const leg of plan.joins) {
+      nodes.push(joinNode(leg, joinContext, rows, caps));
+    }
+  };
+  if (runsPostJoin) {
+    emitJoins();
+    for (const clause of postJoin) {
+      nodes.push(scanNode(clause, rows, ["post-join: addresses a join alias, so no index can serve it"]));
+    }
+  }
+  const placement = plan.joins.length === 0 ? void 0 : runsPostJoin ? "post-join" : "pre-join";
+  if (plan.orderBy.length > 0) {
+    const orderNotes = placement ? [placement] : [];
+    if (ordered) orderNotes.push(`ordered index page off the ${ordered.detail}: no sort runs`);
+    nodes.push({
+      op: "orderBy",
+      dispatch: ordered ? "index:ordered" : "sort",
+      detail: plan.orderBy.map((o) => `${o.field} ${o.direction}${o.by === "label" ? " by label" : ""}`).join(", "),
+      estimatedRows: rows,
+      notes: orderNotes,
+      children: []
+    });
+  }
+  if (innerSplit) emitJoins();
+  if (plan.offset > 0 || plan.limit !== void 0) {
+    const afterOffset = rows === void 0 ? void 0 : Math.max(0, rows - plan.offset);
+    const paged = afterOffset === void 0 ? void 0 : plan.limit === void 0 ? afterOffset : Math.min(afterOffset, plan.limit);
+    nodes.push({
+      op: "page",
+      dispatch: "page",
+      detail: `offset=${plan.offset} limit=${plan.limit ?? "none"}`,
+      estimatedRows: paged,
+      notes: [
+        ...innerSplit ? ["post-join"] : placement ? [placement] : [],
+        ...ordered ? ["consumed by the ordered index walk; no rows are materialized past the page"] : []
+      ],
+      children: []
+    });
+    rows = paged;
+  }
+  if (!runsPostJoin && !innerSplit) emitJoins();
+  return { nodes, caps, reducerRewrite, text: renderExplainText(nodes) };
+}
+function scanReason(clause, indexes, indexAlreadyUsed) {
+  if (indexAlreadyUsed) {
+    const residual = "residual: an earlier clause is already index-served";
+    return clause.type === "field" && indexes !== null && !indexes.has(clause.field) ? [residual, `no index on "${clause.field}"`] : [residual];
+  }
+  if (clause.type !== "field") return [`${clause.type} clauses are never index-served`];
+  if (!indexes) return ["linear scan: no index store on this source"];
+  const sorted = indexes.hasSorted?.(clause.field) === true;
+  if (!indexes.has(clause.field) && !sorted) return [`linear scan: no index on "${clause.field}"`];
+  if (clause.op !== "==" && clause.op !== "in") {
+    if (!isRangeOperator(clause.op)) {
+      return [`linear scan: no index serves ${clause.op} on "${clause.field}"`];
+    }
+    if (!sorted) {
+      return [
+        `linear scan: the hash index on "${clause.field}" serves == and in only \u2014 declare a sorted index on it to serve ${clause.op}`
+      ];
+    }
+    if (clause.via !== void 0) {
+      return [`linear scan: "${clause.field}" is Via-covered, and a Via range operand is evaluated per record`];
+    }
+    return [`linear scan: the sorted index on "${clause.field}" could not order this operand`];
+  }
+  return [`linear scan: the index on "${clause.field}" could not serve this operand`];
+}
+function scanNode(clause, rows, notes) {
+  const { op, detail } = describeClause(clause);
+  return {
+    op,
+    dispatch: "scan",
+    detail,
+    estimatedRows: rows,
+    notes: [...notes, ...rows === void 0 ? [] : ["estimate is an upper bound"]],
+    children: clause.type === "group" ? clause.clauses.map((c) => scanNode(c, rows, ["inside a group: evaluated per record"])) : []
+  };
+}
+function joinNode(leg, joinContext, leftRows, caps) {
+  const right = leg.isDictJoin === true ? joinContext?.resolveDictSource?.(leg.field) : joinContext?.resolveSource(leg.target);
+  const rightRows = right?.snapshot().length;
+  const strategy = leg.strategy ?? (right?.lookupById ? "nested" : "hash");
+  const limit = leg.maxRows ?? DEFAULT_JOIN_MAX_ROWS;
+  const direction = leg.direction ?? "left";
+  const notes = [
+    rightRows === void 0 ? "right side unresolved" : `right side ${rightRows} rows`,
+    `cap ${limit}`,
+    `ref mode ${leg.mode}`
+  ];
+  if (direction !== "left") {
+    notes.push("reverse index over the left rows; right snapshot drives");
+  }
+  if (leg.inner === true) {
+    notes.push("inner: unmatched left rows are dropped, so the estimate is an upper bound");
+  }
+  if (leg.strategy !== void 0) notes.push("strategy overridden by the caller");
+  if (leftRows !== void 0) {
+    caps.push({ name: `join:${leg.as}:left`, limit, observed: leftRows, status: capStatus(leftRows, limit) });
+  }
+  if (rightRows !== void 0) {
+    caps.push({ name: `join:${leg.as}:right`, limit, observed: rightRows, status: capStatus(rightRows, limit) });
+  }
+  if (leg.on !== void 0) {
+    notes.splice(notes.findIndex((n) => n.startsWith("ref mode")), 1);
+    notes.push(
+      leg.on.kind === "composite" ? "declared composite `on`: one hash pass over the right snapshot, keyed on the field tuple" : "declared range `on`: the right snapshot is sorted once, then binary-searched per left row"
+    );
+    notes.push("many-to-many: one row per match, so the estimate is a lower bound and the output ceiling applies");
+    return {
+      op: "join",
+      dispatch: joinOnDispatch(leg.on),
+      detail: `${leg.as} <- ${describeJoinOn(leg.on)} (${leg.target})`,
+      estimatedRows: leftRows,
+      notes,
+      children: []
+    };
+  }
+  const label = direction === "left" ? "" : direction === "right" ? " right outer" : " full outer";
+  const estimatedRows = direction === "left" ? leftRows : leftRows === void 0 || rightRows === void 0 ? void 0 : leftRows + rightRows;
+  return {
+    op: "join",
+    dispatch: direction === "left" ? `join:${strategy}` : "join:reverse-index",
+    detail: `${leg.as} <- ${leg.field} (${leg.target})${label}`,
+    estimatedRows,
+    notes,
+    children: []
+  };
+}
+function collectReducerRewrites(via, fields) {
+  if (!via) return [];
+  const out = [];
+  for (const field of fields) {
+    for (const binding of via.bindings) {
+      if (binding.wrapReducers && binding.covers?.(field) === true) out.push({ brand: binding.brand, field });
+    }
+  }
+  return out;
+}
+function renderExplainText(nodes) {
+  const lines = [];
+  const walk = (ns, depth) => {
+    for (const n of ns) {
+      const rows = n.estimatedRows === void 0 ? "" : ` rows=${n.estimatedRows}`;
+      const notes = n.notes.length > 0 ? ` -- ${n.notes.join("; ")}` : "";
+      lines.push(`${"  ".repeat(depth)}${n.op} ${n.detail} [${n.dispatch}]${rows}${notes}`);
+      walk(n.children, depth + 1);
+    }
+  };
+  walk(nodes, 0);
+  return lines.join("\n");
+}
+
+// src/kernel/query/relate/traverse.ts
+function entriesOf(source) {
+  const paired = source.snapshotEntries?.();
+  if (paired !== void 0) return paired;
+  const out = [];
+  for (const record of source.snapshot()) {
+    const id = coerceRefKey(readPath(record, "id"));
+    if (id !== null) out.push({ id, record });
+  }
+  return out;
+}
+function runTraversal(source, field, seeds, opts) {
+  const { direction, maxDepth } = opts;
+  if (!Number.isInteger(maxDepth) || maxDepth < 0) {
+    throw new Error(
+      `.traverse("${field}"): maxDepth must be a non-negative integer, got ${String(maxDepth)}. It is required and has no default \u2014 an unbounded walk over a large collection is a denial of service against your own UI.`
+    );
+  }
+  const onCycle = opts.onCycle ?? "stop";
+  const entries = entriesOf(source);
+  const lookup = source.lookupById !== void 0 ? (id) => source.lookupById?.(id) : (() => {
+    const byId = new Map(entries.map((e) => [e.id, e.record]));
+    return (id) => byId.get(id);
+  })();
+  const children = direction === "down" ? bucketByRefKey(entries, (e) => readPath(e.record, field)) : void 0;
+  const emitted = /* @__PURE__ */ new Set();
+  const out = [];
+  let frontier = [];
+  for (const seedId of seeds) {
+    if (emitted.has(seedId)) continue;
+    const record = lookup(seedId);
+    if (record === void 0) continue;
+    emitted.add(seedId);
+    const node = { id: seedId, record, depth: 0, path: [seedId] };
+    out.push(node);
+    frontier.push(node);
+  }
+  for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+    const next = [];
+    for (const current of frontier) {
+      for (const { id, record } of neighboursOf(current, field, direction, lookup, children)) {
+        if (current.path.includes(id)) {
+          if (onCycle === "throw") {
+            throw new TraversalCycleError({ field, cycle: [...current.path, id] });
+          }
+          continue;
+        }
+        if (emitted.has(id)) continue;
+        emitted.add(id);
+        const node = { id, record, depth, path: [...current.path, id] };
+        out.push(node);
+        next.push(node);
+      }
+    }
+    frontier = next;
+  }
+  return out;
+}
+function neighboursOf(current, field, direction, lookup, children) {
+  if (direction === "down") return children?.get(current.id) ?? [];
+  const parentId = coerceRefKey(readPath(current.record, field));
+  if (parentId === null) return [];
+  const parent = lookup(parentId);
+  if (parent === void 0) return [];
+  return [{ id: parentId, record: parent }];
+}
+
+// src/kernel/query/relate/methods.ts
+var RelateMethods = class {
+  // The implementation signature spans both overloads: the alias is
+  // non-nullable only under `mode: 'inner'`, and TS needs a return type both
+  // published shapes are assignable to.
+  join(field, opts) {
+    return this.withJoinLeg(field, opts, "left");
+  }
+  joinOn(target, opts) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.joinOn() 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 on = normalizeJoinOn(opts.on, target);
+    const leg = {
+      // The driving left field. Not a ref — it exists so error messages and
+      // `explain()` have something to name, and it is derivable from `on`.
+      field: on.kind === "composite" ? on.pairs[0][0] : on.left,
+      as: opts.as,
+      target,
+      // There is no ref(), so there is no dangling-ref policy to apply.
+      // 'cascade' is the mode that attaches null silently, which is exactly
+      // the left-outer behaviour a declared join wants.
+      mode: "cascade",
+      strategy: void 0,
+      maxRows: opts.maxRows,
+      ...opts.mode === "inner" ? { inner: true } : {},
+      on,
+      partitionScope: "all"
+    };
+    return new Query(
+      this.source,
+      { ...this.plan, joins: [...this.plan.joins, leg] },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * RIGHT outer join (#1289): every record of the TARGET collection appears,
+   * including one no left row points at. The mirror of `.join()`, which is
+   * and always was the left outer join.
+   *
+   * ```ts
+   * invoices.query().rightJoin<'client', Client>('clientId', { as: 'client' })
+   * // → one row per invoice/client match, PLUS { client } for every client
+   * //   no invoice references. An invoice whose clientId matches nothing is
+   * //   dropped — that is what makes it a right join.
+   * ```
+   *
+   * **The row shape is not `T`.** A right-only row carries the alias and
+   * nothing else, so the left fields are typed `Partial<T>` — SQL's "the left
+   * columns are NULL" in an object language. Read them defensively; a row
+   * where `amount` is `undefined` is a real, correct result, not a bug.
+   *
+   * **Cost.** A forward leg follows the left row's FK and is O(1) per row. A
+   * right leg cannot: the rows it must produce are exactly the ones no FK
+   * names. It builds a reverse index — the left rows bucketed by FK value —
+   * and walks the right snapshot against it. That is one extra pass over the
+   * left set and one `Map` the size of the distinct FK values; both sides are
+   * fully materialized either way, and both row ceilings still apply.
+   *
+   * **Ordering.** Like `.join()`, legs run AFTER `orderBy`/`limit`/`offset`
+   * unless the ordering addresses the alias (#1337),
+   * so those narrow the LEFT side. Rows are emitted in right-snapshot order.
+   *
+   * A left row whose non-null FK resolves to nothing is dropped, but the
+   * ref-mode check still runs on it: `strict` still throws
+   * `DanglingReferenceError`. Corruption should not become invisible because
+   * the caller changed join direction.
+   */
+  rightJoin(field, opts) {
+    return this.withJoinLeg(field, opts, "right");
+  }
+  /**
+   * FULL outer join (#1289): the union of `.join()` and `.rightJoin()` —
+   * every left row, every right record, matched where they meet.
+   *
+   * ```ts
+   * invoices.query().fullOuterJoin<'client', Client>('clientId', { as: 'client' })
+   * // → matched rows, plus { client: null, ...invoice } for an unreferenced
+   * //   invoice, plus { client } for a client no invoice points at.
+   * ```
+   *
+   * The alias is `R | null` and the left fields are `Partial<T>`, because a
+   * row can be missing either side — never both. Same reverse index, same
+   * ordering and same ref-mode semantics as {@link rightJoin}; the only
+   * difference is that the unmatched LEFT rows are emitted (after the
+   * right-driven ones) instead of dropped.
+   */
+  fullOuterJoin(field, opts) {
+    return this.withJoinLeg(field, opts, "full");
+  }
+  /**
+   * The one place a `JoinLeg` is built. `.join()`, `.rightJoin()` and
+   * `.fullOuterJoin()` differ ONLY in `direction` and in the type they
+   * publish — keeping the plan-time validation (ref declared? dict join?
+   * join context?) in a single body is what stops the three from drifting on
+   * which errors they raise.
+   */
+  withJoinLeg(field, opts, direction) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.join() requires a join context (same for .rightJoin() and .fullOuterJoin()). 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 RefNotDeclaredError({
+        collection: this.joinContext.leftCollection,
+        field,
+        message: `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 directionField = direction === "left" ? {} : { direction };
+    const innerField = opts.mode === "inner" ? { inner: true } : {};
+    const leg = descriptor ? {
+      field,
+      as: opts.as,
+      target: descriptor.target,
+      mode: descriptor.mode,
+      strategy: opts.strategy,
+      maxRows: opts.maxRows,
+      ...directionField,
+      ...innerField,
+      // The partition seam — always 'all'. Do not remove, and do not
+      // populate without reading JoinLeg.partitionScope's two
+      // constraints (#1342): this value is inside every stored MV
+      // queryHash. Pinned by __tests__/query-partition-scope.test.ts.
+      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",
+      ...directionField,
+      ...innerField,
+      isDictJoin: true
+    };
+    return new Query(
+      this.source,
+      { ...this.plan, joins: [...this.plan.joins, leg] },
+      this.joinContext,
+      this.reduceStrategy,
+      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).
+   *
+   * **⚠️ INNER-join semantics — an empty right subset DROPS the left row.**
+   * Each left row is emitted once per matching right row, so when `on:`
+   * yields nothing the row vanishes with no error, no warning and no count
+   * mismatch. This bites hardest on a reverse FK, where `.join()` (which is
+   * forward-only, and already a genuine LEFT outer join) does not apply and
+   * `.crossJoin()` is the only tool. To keep the row, return a one-element
+   * array holding `null`:
+   *
+   * ```ts
+   * .crossJoin('clients', { as: 'client', on: (b) => byEntity.get(b.entityId) ?? [null] })
+   * //                                                                          ^^^^^^^^
+   * //                                              the ONLY thing preserving the row
+   * ```
+   *
+   * **Prefer `outer: true`**, which does exactly this and types the alias as
+   * `TTarget | null`:
+   *
+   * ```ts
+   * .crossJoin('clients', { as: 'client', outer: true, on: (b) => byEntity.get(b.entityId) ?? [] })
+   * ```
+   *
+   * The `?? [null]` form remains valid and is what `outer` does internally, but
+   * it is invisible intent: it types the alias as non-null while the row can
+   * hold null, and a later "simplification" that drops it silently
+   * reintroduces the row loss.
+   *
+   * **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 },
+      ...opts.outer === true && { outer: true }
+    };
+    return new Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * Self cross-join with BOTH sides aliased (#1289).
+   *
+   * ```ts
+   * const pairs = trades.query()
+   *   .crossJoinWith({ leftAs: 'a', rightAs: 'b', on: (t) => laterThan(t) })
+   *   .toArray()
+   * // → [{ a: Trade, b: Trade }, ...]  — no field at the top level
+   * ```
+   *
+   * `.crossJoin('trades', { as: 'other' })` can already pair a collection
+   * with itself, but only ASYMMETRICALLY: the left row's fields stay at the
+   * top level and only the right side gets a name. Every comparison then
+   * reads `r.amount` against `r.other.amount`, which is exactly the shape
+   * that makes an accidentally-transposed pair invisible.
+   *
+   * ⚠️ **The cost is not the join, it is the Via dressing.** Aliasing the
+   * left row moves every field off the top level, and the money / i18n /
+   * lookup pipeline keys by BARE FIELD NAME — so the plain top-level decode
+   * `toArray()` applies cannot see either side. Both aliases are therefore
+   * dressed explicitly, through the source's own Via result decode, before
+   * the rows are returned. Silently serving raw money under an alias is the
+   * failure this method exists to not have; `dressAliases` is where it is
+   * prevented and `__tests__/query-outer-join.test.ts` is what proves it.
+   *
+   * `on:` takes the same subset / predicate shapes as `.crossJoin()`, and the
+   * same `maxRows` ceiling applies to the product. The target is always this
+   * query's own collection — a cross-join against a DIFFERENT collection is
+   * `.crossJoin()`, which needs no left alias to stay unambiguous.
+   *
+   * The returned `Query` drops this query's schema / queryable / money field
+   * parameters. That is not laziness: those parameters name TOP-LEVEL fields,
+   * and after `crossJoinWith` there are no top-level fields — only the two
+   * aliases. Carrying them would let `where('amount', ...)` type-check on a
+   * row where `amount` does not exist.
+   */
+  crossJoinWith(opts) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.crossJoinWith(): requires a join context. Use collection.query() to construct a cross-join-capable Query instead of the Query constructor directly.`
+      );
+    }
+    if (opts.leftAs === opts.rightAs) {
+      throw new Error(
+        `Query.crossJoinWith({ leftAs: "${opts.leftAs}", rightAs: "${opts.rightAs}" }): the two aliases must differ \u2014 a self cross-join whose sides share a name would emit the right row under both and silently lose the left one.`
+      );
+    }
+    const built = this.crossJoin(this.joinContext.leftCollection, {
+      as: opts.rightAs,
+      ...opts.on !== void 0 && { on: opts.on },
+      ...opts.maxRows !== void 0 && { maxRows: opts.maxRows }
+    });
+    const plan = built._plan();
+    const last = plan.clauses[plan.clauses.length - 1];
+    const clauses = [...plan.clauses.slice(0, -1), { ...last, leftAs: opts.leftAs }];
+    return new Query(
+      this.source,
+      { ...plan, clauses },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * Describe how this plan WOULD run (#1348): the dispatch per clause
+   * (`index:hash` vs `scan`, and why), row estimates taken from real index
+   * cardinalities, join strategy and side sizes against the row ceiling,
+   * whether ordering/pagination lands pre- or post-join, and which
+   * cardinality caps are close to tripping. `.text` renders one line per
+   * node.
+   *
+   * ⛔ Purely observational — it probes index buckets and reads snapshot
+   * sizes, never executes the plan. A terminal returns the same thing
+   * whether or not `explain()` was called. See `query/explain.ts`.
+   */
+  explain() {
+    return explainPlan(this.source, this.plan, this.joinContext);
+  }
+  /**
+   * Recursive traversal over ONE declared, self-referencing `ref()` field
+   * (#1352) — the org-chart / bill-of-materials / parent-client shape that
+   * otherwise forces the consumer to hand-roll recursion.
+   *
+   * ```ts
+   * people.query().where('name', '==', 'Dana')
+   *   .traverse('parentId', { direction: 'up', maxDepth: 10 })
+   * // → [{ id: 'dana', record, depth: 0, path: ['dana'] },
+   * //    { id: 'bea',  record, depth: 1, path: ['dana', 'bea'] }, …]
+   * ```
+   *
+   * **A TERMINAL.** It returns rows, not a `Query`, so it composes with
+   * `where()` / `orderBy()` / `limit()` on the way IN, not on the way out.
+   *
+   * **Seeds are this query's matched records** — the clauses choose the roots
+   * of the walk, not which nodes the walk may pass through. A traversal from
+   * one seed is `ancestorsOf` / `descendantsOf` below.
+   *
+   * **`maxDepth` is required**, with no default: an unbounded walk over a
+   * large collection is a denial of service against your own UI, and a
+   * silent default would truncate a result without saying so.
+   *
+   * **Cycles terminate.** A parent chain can be circular through user error,
+   * and an unguarded BFS hangs the tab. The default `{ onCycle: 'stop' }`
+   * prunes a node the walk is already standing on; `'throw'` raises
+   * `TraversalCycleError` for hierarchies that are supposed to be acyclic.
+   *
+   * **A node is emitted once**, at its shallowest depth — so a diamond (two
+   * seeds converging on one ancestor) yields ONE row for that ancestor,
+   * carrying the path of whichever branch reached it first.
+   *
+   * **Declared refs only.** This is not a general graph engine: the field
+   * must carry a `ref()` whose target is this same collection.
+   *
+   * **Cost.** Every hop reads the vault's already-decrypted in-memory cache
+   * (`query()` is eager-mode only), so a depth-5 traversal costs
+   * `depth × frontier` Map lookups and ZERO additional decrypts — the
+   * AES-GCM work was paid once at `openVault()`. `direction: 'down'` adds one
+   * O(n) pass to build the reverse-FK index; `'up'` adds nothing.
+   *
+   * ⛔ **Not an `explain()` node.** `explain()` describes the plan, and a
+   * traversal is a terminal over the plan's result rather than a clause in
+   * it — the same reason `.window()` and #1336's post-group ops are absent.
+   * `explain()` on the seed query still describes how the SEEDS are found.
+   */
+  traverse(field, opts) {
+    this.assertSelfRef(field, "traverse");
+    const _h = this.source.hydration;
+    if (_h !== void 0 && !_h.isHydrated()) return gateTerminal(_h, "traverse", () => this.traverse(field, opts));
+    return this.runTraverse(field, this.ids(), opts);
+  }
+  /**
+   * `.traverse()` sugar: every ancestor of one record, that record included
+   * at `depth: 0`. See {@link traverse} for the full contract.
+   *
+   * Refused on a query that already carries clauses — the seed is named
+   * explicitly here, so a `where()` would silently do nothing. Use
+   * `.traverse()` when the seeds come from a query.
+   */
+  ancestorsOf(id, field, opts) {
+    return this.traverseFromId(id, field, "up", opts);
+  }
+  /**
+   * `.traverse()` sugar: every descendant of one record, that record included
+   * at `depth: 0`. See {@link traverse} for the full contract.
+   */
+  descendantsOf(id, field, opts) {
+    return this.traverseFromId(id, field, "down", opts);
+  }
+  traverseFromId(id, field, direction, opts) {
+    const _h = this.source.hydration;
+    if (_h !== void 0 && !_h.isHydrated()) return gateTerminal(_h, direction === "up" ? "ancestorsOf" : "descendantsOf", () => this.traverseFromId(id, field, direction, opts));
+    const sugar = direction === "up" ? "ancestorsOf" : "descendantsOf";
+    const plan = this.plan;
+    if (plan.clauses.length > 0 || plan.orderBy.length > 0 || plan.joins.length > 0 || plan.limit !== void 0 || plan.offset !== 0) {
+      throw new Error(
+        `Query.${sugar}("${id}"): this query already carries clauses, but ${sugar}() seeds from the id you passed \u2014 the clauses would silently do nothing. Use .traverse("${field}", { direction: '${direction}', \u2026 }), whose seeds ARE the query's matched records, or call ${sugar}() on a bare collection.query().`
+      );
+    }
+    this.assertSelfRef(field, sugar);
+    return this.runTraverse(field, [id], { ...opts, direction });
+  }
+  /**
+   * The one place a traversal runs. Both entry points share it so they cannot
+   * drift on Via decoding or on which source view the walk reads.
+   */
+  runTraverse(field, seeds, opts) {
+    const rows = runTraversal(this.source, field, seeds, opts);
+    return rows.map((row) => ({ ...row, record: this.decodeVia([row.record])[0] }));
+  }
+  /**
+   * Plan-time validation shared by `.traverse()` and its sugar: the field must
+   * carry a `ref()`, and that ref must point back at this same collection.
+   *
+   * The second half is what keeps this from becoming a general graph engine.
+   * A ref to ANOTHER collection has no second hop — the target's records do
+   * not carry this field — so a two-collection "traversal" is a `.join()`
+   * wearing the wrong name, and would walk exactly one level before stopping
+   * for reasons the caller could not see.
+   */
+  assertSelfRef(field, caller) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.${caller}(): requires a collection-backed query. Use collection.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);
+    if (!descriptor) {
+      throw new RefNotDeclaredError({
+        collection: this.joinContext.leftCollection,
+        field,
+        message: `Query.${caller}(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Traversal walks DECLARED refs only \u2014 add refs: { ${field}: ref('${this.joinContext.leftCollection}') } to the collection options, then retry.`
+      });
+    }
+    if (descriptor.target !== this.joinContext.leftCollection) {
+      throw new Error(
+        `Query.${caller}(): field "${field}" refs "${descriptor.target}", but traversal requires a self-referencing ref \u2014 one whose target is the collection being queried ("${this.joinContext.leftCollection}"). A ref across collections has no second hop; use .join("${field}", { as: \u2026 }) for that.`
+      );
+    }
+  }
+};
+function applyCrossJoin(leftRel, clause, rightSource) {
+  const rightRows = rightSource.snapshot();
+  const maxRows = clause.maxRows ?? DEFAULT_CROSS_JOIN_MAX_ROWS;
+  const { as } = clause;
+  const outer = clause.outer === true;
+  const { leftAs } = clause;
+  const emit = leftAs === void 0 ? (left, right) => ({ ...left, [as]: right }) : (left, right) => ({ [leftAs]: left, [as]: right });
+  if (!clause.on) {
+    const rightSide = outer && rightRows.length === 0 ? [null] : rightRows;
+    const product = leftRel.length * rightSide.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 rightSide) {
+        expanded2.push(emit(leftObj, 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
+      );
+    }
+    if (outer && filteredRight.length === 0) filteredRight = [null];
+    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(emit(leftObj, right));
+    }
+  }
+  return expanded;
+}
+
+// src/kernel/query/relate/scan-methods.ts
+var ScanRelateMethods = class {
+  /**
+   * 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.
+   *
+   * Every JoinLeg carries `partitionScope: 'all'`, plumbed through but never
+   * read. Same seam as the eager join — see {@link JoinLeg.partitionScope}.
+   */
+  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 RefNotDeclaredError({
+        collection: this.joinContext.leftCollection,
+        field,
+        message: `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,
+      // Always 'all', never read by the streaming executor. This is the
+      // path where partition pruning would actually pay (every listPage()
+      // page is decrypted) — and the path blocked on a store-contract
+      // change. See JoinLeg.partitionScope constraint 2 (#1342).
+      partitionScope: "all"
+    };
+    return new ScanBuilder(
+      this.pageProvider,
+      this.pageSize,
+      this.clauses,
+      [...this.joins, leg],
+      this.joinContext,
+      this.via
+    );
+  }
+  /**
+   * 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.
+   */
+  /**
+   * 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) {
+      if (leg.on !== void 0) {
+        throw new Error(
+          `ScanBuilder: the declared \`on\` join leg "${leg.as}" cannot stream \u2014 it emits one row per match, while scan() yields one row per stored record. Use collection.query().joinOn().`
+        );
+      }
+      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 = coerceRefKey(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 = coerceRefKey(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.
+   *
+   * Consults the Via pipeline's posture before reducing (#629 Task 8 review
+   * fix wave 1): a reducer over a field whose posture is `queryable: 'none'`
+   * throws `FieldNotQueryableError` here, metadata-only — via
+   * `ViaPipeline.refuseUnqueryableReducers`, NOT the full `wrapReducers`
+   * (which would also activate money's exact-reducer rewrite, a path this
+   * method has never run and must not start running as a side effect of
+   * this gate).
+   */
+  // `const` so an inline `[specA, specB]` infers as a TUPLE, not a `Spec[]` —
+  // that is what makes `const [a, b] = await …` land on the right shapes.
+};
+
+// src/kernel/query/relate/install.ts
+var done = false;
+function installRelate() {
+  if (done) return;
+  done = true;
+  installMethods(Query.prototype, RelateMethods);
+  installMethods(ScanBuilder.prototype, ScanRelateMethods);
+  installRelateHooks({
+    applyJoins,
+    splitAroundJoins,
+    orderReferencesJoinAlias,
+    joinsDropLeftRows,
+    applyCrossJoin
+  });
+}
+
+export {
+  explainPlan,
+  renderExplainText,
+  runTraversal,
+  installRelate
+};
+//# sourceMappingURL=chunk-ZSX4S5XB.js.map