@noy-db/hub 0.1.0-pre.9 → 0.2.0-pre.10

package/dist/query/index.cjs

@@ -22,11 +22,20 @@ 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,
@@ -111,6 +120,12 @@ function evaluateClause(record, clause) {
       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) {
@@ -154,6 +169,38 @@ var GroupCardinalityError = class extends NoydbError {
     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;
@@ -168,6 +215,34 @@ var JoinTooLargeError = class extends NoydbError {
     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;
@@ -418,6 +493,9 @@ var NO_AGGREGATE = {
   groupBy() {
     throw NOT_ENABLED;
   },
+  groupByN() {
+    throw NOT_ENABLED;
+  },
   scanAggregate() {
     throw NOT_ENABLED;
   }
@@ -431,16 +509,89 @@ var EMPTY_PLAN = {
   offset: 0,
   joins: []
 };
+var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
 var Query = class _Query {
   source;
   plan;
   joinContext;
   aggregateStrategy;
-  constructor(source, plan = EMPTY_PLAN, joinContext, aggregateStrategy = NO_AGGREGATE) {
+  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) {
@@ -449,7 +600,8 @@ var Query = class _Query {
       this.source,
       { ...this.plan, clauses: [...this.plan.clauses, clause] },
       this.joinContext,
-      this.aggregateStrategy
+      this.aggregateStrategy,
+      this.predicates
     );
   }
   /**
@@ -459,7 +611,7 @@ var Query = class _Query {
    */
   or(builder) {
     const sub = builder(
-      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy)
+      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy, this.predicates)
     );
     const group = {
       type: "group",
@@ -470,7 +622,8 @@ var Query = class _Query {
       this.source,
       { ...this.plan, clauses: [...this.plan.clauses, group] },
       this.joinContext,
-      this.aggregateStrategy
+      this.aggregateStrategy,
+      this.predicates
     );
   }
   /**
@@ -479,7 +632,7 @@ var Query = class _Query {
    */
   and(builder) {
     const sub = builder(
-      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy)
+      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy, this.predicates)
     );
     const group = {
       type: "group",
@@ -490,7 +643,8 @@ var Query = class _Query {
       this.source,
       { ...this.plan, clauses: [...this.plan.clauses, group] },
       this.joinContext,
-      this.aggregateStrategy
+      this.aggregateStrategy,
+      this.predicates
     );
   }
   /** Escape hatch: add an arbitrary predicate function. Not serializable. */
@@ -503,7 +657,8 @@ var Query = class _Query {
       this.source,
       { ...this.plan, clauses: [...this.plan.clauses, clause] },
       this.joinContext,
-      this.aggregateStrategy
+      this.aggregateStrategy,
+      this.predicates
     );
   }
   /** Sort by a field. Subsequent calls are tie-breakers. */
@@ -512,7 +667,8 @@ var Query = class _Query {
       this.source,
       { ...this.plan, orderBy: [...this.plan.orderBy, { field, direction }] },
       this.joinContext,
-      this.aggregateStrategy
+      this.aggregateStrategy,
+      this.predicates
     );
   }
   /** Cap the result size. */
@@ -521,7 +677,8 @@ var Query = class _Query {
       this.source,
       { ...this.plan, limit: n },
       this.joinContext,
-      this.aggregateStrategy
+      this.aggregateStrategy,
+      this.predicates
     );
   }
   /** Skip the first N matching records (after ordering). */
@@ -530,7 +687,8 @@ var Query = class _Query {
       this.source,
       { ...this.plan, offset: n },
       this.joinContext,
-      this.aggregateStrategy
+      this.aggregateStrategy,
+      this.predicates
     );
   }
   /**
@@ -629,7 +787,80 @@ var Query = class _Query {
       this.source,
       { ...this.plan, joins: [...this.plan.joins, leg] },
       this.joinContext,
-      this.aggregateStrategy
+      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
     );
   }
   /**
@@ -639,7 +870,7 @@ var Query = class _Query {
    * for the ordering rationale.
    */
   toArray() {
-    const base = executePlanWithSource(this.source, this.plan);
+    const base = executePlanWithSource(this.source, this.plan, this.joinContext);
     if (this.plan.joins.length === 0) return base;
     if (!this.joinContext) {
       throw new Error(
@@ -663,6 +894,14 @@ var Query = class _Query {
    * 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;
@@ -710,7 +949,13 @@ var Query = class _Query {
   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);
     };
@@ -721,56 +966,19 @@ var Query = class _Query {
     }
     return this.aggregateStrategy.aggregate(executeRecords, spec, upstreams);
   }
-  /**
-   * Partition matching records into buckets keyed by a field, then
-   * terminate with `.aggregate(spec)` to compute per-bucket
-   * reducers..
-   *
-   * ```ts
-   * const byClient = invoices.query()
-   *   .where('status', '==', 'open')
-   *   .groupBy('clientId')
-   *   .aggregate({ total: sum('amount'), n: count() })
-   *   .run()
-   * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
-   * ```
-   *
-   * Result rows carry the group key value under the grouping field
-   * name plus every reducer output from the spec. Buckets are
-   * emitted in first-seen order — consumers who want a specific
-   * ordering should `.sort()` downstream.
-   *
-   * **Cardinality caps:** a one-shot warning fires at 10_000
-   * distinct groups; `GroupCardinalityError` throws at 100_000.
-   * Grouping on a high-uniqueness field like `id` or `createdAt` is
-   * almost always a query mistake — the error message names the
-   * field and observed cardinality and suggests narrowing with
-   * `.where()` first.
-   *
-   * **Null / undefined keys:** records with a missing or explicitly
-   * `null` group field get their own buckets. `Map`-based
-   * partitioning distinguishes `undefined` from `null`, so the two
-   * cases do NOT merge. Consumers who want them merged should
-   * coalesce upstream with `.filter()`.
-   *
-   * **Joins are not applied** — same rationale as `.count()` and
-   * `.aggregate()`. Joined fields in are projection-only, so
-   * running a join inside a grouping pipeline would be wasteful and
-   * could trigger `DanglingReferenceError` in strict mode for a
-   * call whose intent is purely to bucket-and-reduce. Grouping by
-   * a joined field is explicitly out of scope for — file an
-   * issue if a real consumer needs it.
-   *
-   * **Filter clauses (`.filter(fn)`):** grouped queries still
-   * support filter clauses in the underlying plan — they run in
-   * the same candidate/filter pipeline that `.aggregate()` uses.
-   * The performance caveat is the same: filter clauses cost O(N)
-   * per record and can't be index-accelerated.
-   */
-  groupBy(field) {
+  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);
     };
@@ -779,36 +987,21 @@ var Query = class _Query {
       const subscribe = source.subscribe.bind(source);
       upstreams.push({ subscribe: (cb) => subscribe(cb) });
     }
-    const joinCtx = this.joinContext;
-    const dictLabelResolver = joinCtx?.resolveDictSource ? (() => {
-      const dictSource = joinCtx.resolveDictSource(field);
-      if (!dictSource) return void 0;
-      const snapshot = dictSource.snapshot();
-      const dictMap = /* @__PURE__ */ new Map();
-      for (const entry of snapshot) {
-        const k = entry["key"];
-        const labels = entry["labels"];
-        if (typeof k === "string" && labels && typeof labels === "object") {
-          dictMap.set(k, labels);
-        }
-      }
-      return async (key, locale, fallback) => {
-        const labels = dictMap.get(key);
-        if (!labels) return void 0;
-        if (labels[locale] !== void 0) return labels[locale];
-        const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
-        for (const fb of chain) {
-          if (fb === "any") {
-            const any = Object.values(labels)[0];
-            if (any !== void 0) return any;
-          } else if (labels[fb] !== void 0) {
-            return labels[fb];
-          }
-        }
-        return void 0;
-      };
-    })() : void 0;
-    return this.aggregateStrategy.groupBy(executeRecords, field, upstreams, dictLabelResolver);
+    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.
@@ -899,6 +1092,21 @@ var Query = class _Query {
         }
       }
     }
+    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);
   }
   /**
@@ -910,9 +1118,20 @@ var Query = class _Query {
     return serializePlan(this.plan);
   }
 };
-function executePlanWithSource(source, plan) {
-  const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
-  let result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+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);
   }
@@ -962,6 +1181,11 @@ function materializeIds(ids, lookupById) {
   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);
@@ -989,6 +1213,74 @@ function filterRecords(records, clauses) {
   }
   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) {
@@ -1034,6 +1326,16 @@ 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",
@@ -1041,8 +1343,65 @@ function serializeClause(clause) {
       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 {
@@ -1173,6 +1532,7 @@ function count(opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "count",
     init: () => 0,
     step: (state) => state + 1,
     remove: (state) => state - 1,
@@ -1183,6 +1543,8 @@ function sum(field, opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "sum",
+    field,
     init: () => 0,
     step: (state, record) => state + readNumber(record, field),
     remove: (state, record) => state - readNumber(record, field),
@@ -1193,6 +1555,8 @@ function avg(field, opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "avg",
+    field,
     init: () => ({ sum: 0, count: 0 }),
     step: (state, record) => ({
       sum: state.sum + readNumber(record, field),
@@ -1219,6 +1583,8 @@ function min(field, opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "min",
+    field,
     init: () => ({ values: [] }),
     step: (state, record) => pushValue(state, readNumber(record, field)),
     remove: (state, record) => removeValue(state, readNumber(record, field)),
@@ -1237,6 +1603,8 @@ function max(field, opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "max",
+    field,
     init: () => ({ values: [] }),
     step: (state, record) => pushValue(state, readNumber(record, field)),
     remove: (state, record) => removeValue(state, readNumber(record, field)),
@@ -1379,31 +1747,53 @@ 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(field, observed) {
-  if (warnedCardinalityFields.has(field)) return;
-  warnedCardinalityFields.add(field);
+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("${field}") produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
+    `[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 GroupedQuery = class {
-  constructor(executeRecords, field, upstreams, dictLabelResolver) {
+var GroupedQueryBase = class {
+  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver) {
     this.executeRecords = executeRecords;
-    this.field = field;
     this.upstreams = upstreams;
     this.dictLabelResolver = dictLabelResolver;
+    this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
   }
   executeRecords;
-  field;
   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
@@ -1413,70 +1803,93 @@ var GroupedQuery = class {
   aggregate(spec) {
     return new GroupedAggregation(
       this.executeRecords,
-      this.field,
+      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, field, spec) {
+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 key = readPath(record, field);
-    let bucket = buckets.get(key);
+    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(
-          field,
+          fieldLabel,
           buckets.size + 1,
           GROUPBY_MAX_CARDINALITY
         );
       }
-      bucket = [];
-      buckets.set(key, bucket);
+      bucket = { keyValues, records: [] };
+      buckets.set(dedupKey, bucket);
     }
-    bucket.push(record);
+    bucket.records.push(record);
   }
   if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
-    warnCardinalityApproaching(field, buckets.size);
+    warnCardinalityApproaching(fields, buckets.size);
   }
-  const keys = Object.keys(spec);
+  const reducerKeys = Object.keys(spec);
   const out = [];
-  for (const [groupKey, bucketRecords] of buckets) {
+  for (const bucket of buckets.values()) {
     const state = {};
-    for (const key of keys) {
-      state[key] = spec[key].init();
+    for (const rk of reducerKeys) {
+      state[rk] = spec[rk].init();
     }
-    for (const record of bucketRecords) {
-      for (const key of keys) {
-        state[key] = spec[key].step(state[key], record);
+    for (const record of bucket.records) {
+      for (const rk of reducerKeys) {
+        state[rk] = spec[rk].step(state[rk], record);
       }
     }
-    const row = { [field]: groupKey };
-    for (const key of keys) {
-      row[key] = spec[key].finalize(state[key]);
+    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, field, spec, upstreams, dictLabelResolver) {
+  constructor(executeRecords, fields, spec, upstreams, dictLabelResolver) {
     this.executeRecords = executeRecords;
-    this.field = field;
     this.spec = spec;
     this.upstreams = upstreams;
     this.dictLabelResolver = dictLabelResolver;
+    this.fields = typeof fields === "string" ? [fields] : [...fields];
   }
   executeRecords;
-  field;
   spec;
   upstreams;
   dictLabelResolver;
+  fields;
   /** Execute the query, group, reduce, and return an array of rows. */
   run() {
-    return groupAndReduce(this.executeRecords(), this.field, this.spec);
+    return groupAndReduce(this.executeRecords(), this.fields, this.spec);
   }
   /**
    * Execute the query, group, reduce, and resolve `<field>Label` for
@@ -1486,17 +1899,22 @@ var GroupedAggregation = class {
    *
    * 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.field, this.spec);
-    if (!opts?.locale || !this.dictLabelResolver) return rows;
+    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 labelKey = `${this.field}Label`;
+    const field = this.fields[0];
+    const labelKey = `${field}Label`;
     return Promise.all(
       rows.map(async (row) => {
-        const key = row[this.field];
+        const key = row[field];
         if (typeof key !== "string") return row;
         const label = await resolve(key, locale, fallback);
         return { ...row, [labelKey]: label };
@@ -1520,7 +1938,7 @@ var GroupedAggregation = class {
    * Always call `live.stop()` when finished.
    */
   live() {
-    const recompute = () => groupAndReduce(this.executeRecords(), this.field, this.spec);
+    const recompute = () => groupAndReduce(this.executeRecords(), this.fields, this.spec);
     return buildLiveAggregation(recompute, this.upstreams);
   }
 };
@@ -1930,11 +2348,20 @@ function coerceRefKey2(value) {
 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,