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

package/dist/chunk-AL6ML4LA.js

@@ -0,0 +1,1558 @@
+import {
+  NO_REDUCE
+} from "./chunk-3TDUWVWB.js";
+import {
+  gateTerminal
+} from "./chunk-FOEDQATO.js";
+import {
+  evaluateClause,
+  hasFnClause,
+  normalizeMatches,
+  normalizeSubqueryOperand
+} from "./chunk-5WWDGFOS.js";
+import {
+  isViaPrefixProbe
+} from "./chunk-SYNY3VB5.js";
+import {
+  CrossJoinSourceUnknownError,
+  FieldNotQueryableError,
+  QueryExtensionMissingError
+} from "./chunk-37EPTBBR.js";
+
+// src/kernel/query/internal/hooks.ts
+var installed;
+function installRelateHooks(hooks) {
+  installed = hooks;
+}
+function relateHooks() {
+  if (installed === void 0) {
+    throw new QueryExtensionMissingError("join", "@noy-db/hub/query/relate");
+  }
+  return installed;
+}
+
+// src/kernel/query/cursor.ts
+var CURSOR_VERSION = 1;
+function keysetShape(identity, orderBy) {
+  const spec = orderBy.map((o) => `${o.field}:${o.direction}:${o.by ?? "value"}`).join(",");
+  return `${identity ?? "(anonymous source)"}::${spec}`;
+}
+function encodeValue(v) {
+  if (v instanceof Date) return { $d: v.toISOString() };
+  if (typeof v === "number" || typeof v === "string" || typeof v === "boolean") return v;
+  return null;
+}
+function decodeValue(v) {
+  if (v !== null && typeof v === "object" && "$d" in v) {
+    return new Date(v.$d);
+  }
+  return v;
+}
+function toBase64(text) {
+  const bytes = new TextEncoder().encode(text);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+function fromBase64(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return new TextDecoder().decode(bytes);
+}
+function encodeCursor(cursor) {
+  return toBase64(
+    JSON.stringify({
+      v: CURSOR_VERSION,
+      k: cursor.shape,
+      s: cursor.values.map(encodeValue),
+      i: cursor.id
+    })
+  );
+}
+function decodeCursor(raw, expectedShape) {
+  let payload;
+  try {
+    payload = JSON.parse(fromBase64(raw));
+  } catch {
+    throw new Error(
+      `Query.after(): the value passed is not a valid keyset cursor. Pass back the \`nextCursor\` from a previous .page() call, verbatim.`
+    );
+  }
+  if (payload === null || typeof payload !== "object" || payload.v !== CURSOR_VERSION || typeof payload.k !== "string" || !Array.isArray(payload.s) || typeof payload.i !== "string") {
+    throw new Error(
+      `Query.after(): the value passed is not a valid keyset cursor (or was minted by an incompatible version). Pass back the \`nextCursor\` from a previous .page() call, verbatim.`
+    );
+  }
+  if (payload.k !== expectedShape) {
+    throw new Error(
+      `Query.after(): this cursor was minted for a different query shape. Cursor: "${payload.k}"; this query: "${expectedShape}". A keyset cursor is only valid for the same collection and the same orderBy(...) spec that produced it.`
+    );
+  }
+  return { shape: payload.k, values: payload.s.map(decodeValue), id: payload.i };
+}
+
+// src/kernel/query/builder.ts
+function splitAroundJoins(clauses, joins) {
+  if (joins.length === 0 || clauses.length === 0) return { preJoin: clauses, postJoin: [] };
+  return relateHooks().splitAroundJoins(clauses, joins);
+}
+function orderReferencesJoinAlias(orderBy, joins) {
+  if (joins.length === 0 || orderBy.length === 0) return false;
+  return relateHooks().orderReferencesJoinAlias(orderBy, joins);
+}
+function joinsDropLeftRows(joins) {
+  if (joins.length === 0) return false;
+  return relateHooks().joinsDropLeftRows(joins);
+}
+function applyJoins(rows, joins, context, locale) {
+  if (joins.length === 0) return [...rows];
+  return relateHooks().applyJoins(rows, joins, context, locale);
+}
+function applyCrossJoin(leftRel, clause, rightSource) {
+  return relateHooks().applyCrossJoin(leftRel, clause, rightSource);
+}
+var EMPTY_PLAN = {
+  clauses: [],
+  orderBy: [],
+  limit: void 0,
+  offset: 0,
+  after: void 0,
+  joins: []
+};
+var Query = class _Query {
+  source;
+  plan;
+  joinContext;
+  reduceStrategy;
+  predicates;
+  constructor(source, plan = EMPTY_PLAN, joinContext, reduceStrategy = NO_REDUCE, predicates) {
+    this.source = source;
+    this.plan = plan;
+    this.joinContext = joinContext;
+    this.reduceStrategy = reduceStrategy;
+    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 #1414 — clone this Query with the cold-collection gate REMOVED.
+   *
+   * For engine-internal readers only. The materialized-view engine reads its
+   * source collections through the public `collection.query()` on paths that
+   * are synchronous by construction (registration inspects the plan; the
+   * executor's row scan is called from inside a write commit), and it has
+   * always read whatever the in-memory cache held. Gating those would turn a
+   * pre-existing read into a throw for consumers who never asked a question —
+   * so this preserves that behaviour EXACTLY, and confines #1414's change to
+   * the surface a consumer or a guard actually calls.
+   *
+   * ⚠️ It does not make an unhydrated read correct — an MV computed over a
+   * cold source is the same defect wearing a different hat. That is tracked
+   * separately; do not reach for this to silence the gate in new code.
+   */
+  _ungated() {
+    if (this.source.hydration === void 0) return this;
+    const rest = { ...this.source };
+    delete rest.hydration;
+    return new _Query(rest, this.plan, this.joinContext, this.reduceStrategy, this.predicates);
+  }
+  /**
+   * @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.reduceStrategy,
+      predicates
+    );
+  }
+  /**
+   * @internal — the ids of records matching this query's plan,
+   * recovered by reference identity: `executePlanWithSource` returns the
+   * ORIGINAL snapshot record references (money-decode and joins are applied
+   * later, in `toArray`), so each matched record is found in the id-paired
+   * `snapshotEntries()` map. Used by `collection.retrieve({ within })`.
+   * Throws if the source is not collection-backed (no `snapshotEntries`).
+   */
+  _idArray() {
+    const entries = this.source.snapshotEntries?.();
+    if (entries === void 0) {
+      throw new Error(
+        "Query._idArray(): the query source has no snapshotEntries(); retrieve({ within }) requires a collection-backed query (collection.query())."
+      );
+    }
+    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+      throw new Error(
+        "Query._idArray(): retrieve({ within }) does not support crossJoin queries (cross-join produces new row objects, breaking id recovery). Use where/filter/and/or, or a projection .join()."
+      );
+    }
+    const refToId = /* @__PURE__ */ new Map();
+    for (const { id, record } of entries) refToId.set(record, id);
+    const matched = executePlanWithSource(this.source, this.plan, this.joinContext);
+    const ids = [];
+    for (const r of matched) {
+      const id = refToId.get(r);
+      if (id !== void 0) ids.push(id);
+    }
+    return ids;
+  }
+  /**
+   * The ids of the records this query matches (#1351) — the public spelling
+   * of {@link _idArray}, and the eager half of the subquery operand:
+   * `where(f, 'in', inner.ids())` and `where(f, 'in', inner)` build the SAME
+   * clause. Reach for the explicit form when you want to reuse the id set, or
+   * to see it.
+   *
+   * Requires a collection-backed query (`collection.query()`); a `crossJoin`
+   * plan is refused, because it produces new row objects and there is no id
+   * to recover.
+   *
+   * **Synchronous** (#1413) — returns `string[]`, not a promise; the cache it reads is
+   * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+   * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+   */
+  ids() {
+    const _h = this.source.hydration;
+    if (_h !== void 0 && !_h.isHydrated()) return gateTerminal(_h, "ids", () => this.ids());
+    return this._idArray();
+  }
+  /**
+   * @internal — the id-operand contract `normalizeSubqueryOperand()`
+   * (`predicate.ts`) duck-types when this Query is passed as the operand of
+   * `in`/`!in`. Separate from {@link ids} so the failure a subquery hits is
+   * phrased as a subquery failure rather than as a `retrieve({ within })` one.
+   */
+  _asIdOperand() {
+    if (this.source.snapshotEntries === void 0) {
+      throw new Error(
+        "where(..., 'in', <subquery>): the inner query's source is not collection-backed (no snapshotEntries()). Pass a query obtained from collection.query(), or pass a literal array of values."
+      );
+    }
+    return { ids: this._idArray(), from: this.source.identity ?? "(unnamed)" };
+  }
+  /**
+   * 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.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * Add a field comparison. Multiple where() calls are AND-combined.
+   *
+   * A declared money field compares in MAJOR units: the operand
+   * (`10000`, `'10000.00'`, or `{ amount, currency }` in multi mode) is
+   * quantized into stored scaled-int space at build time and evaluated
+   * BigInt-exact per record. A malformed operand or a string operator
+   * (`contains`/`startsWith`) throws here, at the call site.
+   *
+   * Consults the Via pipeline's posture before building a clause (#629
+   * Task 8): a field whose posture is `queryable: 'none'` (e.g. a
+   * `blobFields` slot) throws `FieldNotQueryableError` here, at the call
+   * site. Every other posture is unaffected — the existing per-binding
+   * `buildClause` machinery runs exactly as before.
+   */
+  where(field, op, value) {
+    const via = this.source.via;
+    if (via?.postureFor(field)?.queryable === "none") throw new FieldNotQueryableError(field);
+    const { op: sop, value: sval, subquery } = normalizeSubqueryOperand(op, value);
+    const { op: mop, value: mval } = normalizeMatches(sop, sval);
+    const viaClause = via?.buildClause(field, mop, mval);
+    const clause = viaClause ? {
+      type: "field",
+      field,
+      op: mop,
+      value: mval,
+      ...subquery ? { subquery } : {},
+      via: {
+        brand: viaClause.brand,
+        payload: viaClause.payload,
+        evaluate: (actual, evalOp) => via.evaluateClause(viaClause, actual, evalOp),
+        indexValue: via.indexProbe(viaClause, mop)
+      }
+    } : { type: "field", field, op: mop, value: mval, ...subquery ? { subquery } : {} };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * Logical OR group. Pass a callback that builds a sub-query.
+   * Each clause inside the callback is OR-combined; the group itself
+   * joins the parent plan with AND.
+   */
+  or(builder) {
+    const sub = builder(
+      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.reduceStrategy, this.predicates)
+    );
+    const group = {
+      type: "group",
+      op: "or",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, group] },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * Logical AND group. Same shape as `or()` but every clause inside the group
+   * must match. Useful for explicit grouping inside a larger OR.
+   */
+  and(builder) {
+    const sub = builder(
+      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.reduceStrategy, this.predicates)
+    );
+    const group = {
+      type: "group",
+      op: "and",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, group] },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /** Escape hatch: add an arbitrary predicate function. Not serializable. */
+  filter(fn) {
+    const clause = {
+      type: "filter",
+      fn
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * Sort by a field. Subsequent calls are tie-breakers. Pass
+   * `{ by: 'label' }` to sort a `dictKey`/`staticDict` field by its resolved
+   * label at the query locale instead of the stored code.
+   *
+   * Consults the Via pipeline's posture (#629 Task 8): a field whose posture
+   * is `queryable: 'none'` throws `FieldNotQueryableError` here, at the call
+   * site — same gate as `where()`.
+   */
+  orderBy(field, direction = "asc", opts) {
+    if (this.source.via?.postureFor(field)?.queryable === "none") throw new FieldNotQueryableError(field);
+    const entry = opts?.by === "label" ? { field, direction, by: "label" } : { field, direction };
+    return new _Query(
+      this.source,
+      { ...this.plan, orderBy: [...this.plan.orderBy, entry] },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /** Cap the result size. */
+  limit(n) {
+    return new _Query(
+      this.source,
+      { ...this.plan, limit: n },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * Resume strictly after the row an opaque keyset cursor names (#1346).
+   *
+   * ```ts
+   * const first = people.query().orderBy('name').limit(20).page()
+   * const next = people.query().orderBy('name').limit(20).after(first.nextCursor!).page()
+   * ```
+   *
+   * Unlike `offset(n)`, the window is anchored to a `(sortKey, id)` position,
+   * so a record inserted or deleted before it — including the cursor's own
+   * row — cannot re-serve or skip a record.
+   *
+   * The cursor is OPAQUE: pass back a `nextCursor` from `.page()` verbatim
+   * and do not parse it. It is validated when the query executes (not here —
+   * the sort spec it is bound to may still be added to the chain), and a
+   * cursor from a different collection or a different `orderBy(...)` spec is
+   * REFUSED rather than mis-paged.
+   *
+   * Requires at least one `orderBy(...)`, an id-paired (collection-backed)
+   * source, no join legs and no `offset()`; each is a loud error at execution.
+   */
+  after(cursor) {
+    if (typeof cursor !== "string" || cursor.length === 0) {
+      throw new Error("Query.after(): a cursor must be a non-empty string \u2014 pass back the `nextCursor` from .page().");
+    }
+    return new _Query(
+      this.source,
+      { ...this.plan, after: cursor },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /** Skip the first N matching records (after ordering). */
+  offset(n) {
+    return new _Query(
+      this.source,
+      { ...this.plan, offset: n },
+      this.joinContext,
+      this.reduceStrategy,
+      this.predicates
+    );
+  }
+  /**
+   * Resolve a `ref()`-declared foreign key and attach the right-side
+   * record under `opts.as`. — eager, single-FK, intra-
+   * vault joins.
+   *
+   * ```ts
+   * const rows = invoices.query()
+   *   .where('status', '==', 'open')
+   *   .join('clientId', { as: 'client' })
+   *   .toArray()
+   * // → [{ id, amount, client: { id, name, ... } }, ...]
+   * ```
+   *
+   * Preconditions:
+   *   - The Query must have a `joinContext` (constructed via
+   *     `Collection.query()`, not `new Query`).
+   *   - `field` must have a matching `refs: { [field]: ref('<target>') }`
+   *     declaration on the left collection.
+   *   - The target collection must be reachable via the vault
+   *     (either currently open or openable on demand).
+   *
+   * Strategy:
+   *   - Nested-loop against `lookupById` when the target source
+   *     provides it (the common path for Collection targets).
+   *   - Hash join otherwise, or when `{ strategy: 'hash' }` is
+   *     explicitly passed for test purposes.
+   *
+   * Ref-mode semantics on dangling refs (left record has a non-null
+   * FK value pointing at a right-side id that doesn't exist):
+   *   - `strict`  → throws `DanglingReferenceError` with the full
+   *     field / target / refId context.
+   *   - `warn`    → attaches `null` and emits a one-shot warning per
+   *     unique dangling pair.
+   *   - `cascade` → attaches `null` silently. Cascade is a
+   *     delete-time mode; dangling refs visible at read time are
+   *     either mid-flight cascades or pre-existing orphans, not a
+   *     DSL-level error.
+   *
+   * A left-side record whose FK field is `null` / `undefined` is NOT
+   * a dangling ref — it's "no reference at all", always allowed
+   * regardless of mode.
+   *
+   * The return type widens `T` with `Record<As, R | null>`. The `R`
+   * parameter is optional — supply it explicitly for type-checked
+   * access to the joined fields:
+   *
+   * ```ts
+   * invoices.query().join<'client', Client>('clientId', { as: 'client' })
+   * //                 ^^^^^^^^^^^^^^^^^^^ alias literal + right-side type
+   * ```
+   *
+   * Without the generic, the joined field is typed as `unknown`, which
+   * still works but requires a cast to access its properties.
+   *
+   * Joins stay intra-vault by construction — cross-vault
+   * correlation goes through `Noydb.queryAcross`, not
+   * `.join()`.
+   */
+  /**
+   * Execute the plan and return the matching records. When the plan
+   * carries any join legs, they are applied after `where` / `orderBy`
+   * / `limit` / `offset` narrow the left set — UNLESS a clause (#1030) or
+   * the ordering (#1337) addresses a join alias, in which case the legs run
+   * first and the sort/page observe the joined relation. See the `.join()`
+   * doc for the ordering rationale, and `.explain()` for which one a given
+   * plan gets.
+   *
+   * `opts.locale` resolves JOINED right-side i18n fields at the
+   * `join` layer to that locale; without it, the owning collection's default
+   * locale applies, and a locale-less query leaves joined i18n fields raw.
+   * (Left/base i18n fields are resolved by `get`/`list`, not here.)
+   *
+   * **Synchronous** (#1413) — returns `T[]`, not a promise; the cache it reads is
+   * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+   * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+   */
+  toArray(opts) {
+    const _h = this.source.hydration;
+    if (_h !== void 0 && !_h.isHydrated()) return gateTerminal(_h, "toArray", () => this.toArray(opts));
+    if (this.plan.after !== void 0) return this.executeKeyset(opts).rows;
+    const { preJoin, postJoin } = splitAroundJoins(this.plan.clauses, this.plan.joins);
+    const orderPostJoin = orderReferencesJoinAlias(this.plan.orderBy, this.plan.joins);
+    const innerDrops = joinsDropLeftRows(this.plan.joins);
+    if (postJoin.length === 0 && !orderPostJoin) {
+      const pagePlan = innerDrops ? { ...this.plan, offset: 0, limit: void 0 } : this.plan;
+      const base = this.decodeVia(
+        executePlanWithSource(this.source, pagePlan, this.joinContext, opts?.locale, this.aliasVia()),
+        opts?.locale
+      );
+      if (this.plan.joins.length === 0) return this.dressAliases(base);
+      const joined2 = applyJoins(base, this.plan.joins, this.requireJoinContext("toArray"), opts?.locale);
+      if (!innerDrops) return this.dressAliases(joined2);
+      const from = this.plan.offset;
+      return this.dressAliases(
+        this.plan.limit === void 0 ? joined2.slice(from) : joined2.slice(from, from + this.plan.limit)
+      );
+    }
+    const joinContext = this.requireJoinContext("toArray");
+    const narrowed = executePlanWithSource(
+      this.source,
+      { ...this.plan, clauses: preJoin, orderBy: [], limit: void 0, offset: 0 },
+      joinContext,
+      opts?.locale
+    );
+    const joined = applyJoins(narrowed, this.plan.joins, joinContext, opts?.locale);
+    const filtered = filterRecords(joined, postJoin, fnViewDecoder(this.source));
+    const paged = applyOrderAndPage(filtered, this.plan, this.source, joinContext, opts?.locale, this.aliasVia());
+    return this.dressAliases(this.decodeVia(paged, opts?.locale));
+  }
+  /**
+   * Apply each aliased side's OWN Via result decode, in place of the
+   * top-level decode that cannot reach it (#1289, and the fix for #1335).
+   *
+   * `decodeVia` keys by bare field name, so it dresses exactly the fields
+   * sitting at the top of the row. Everything a join puts under an alias —
+   * a `.join()`/`.rightJoin()` right record, a `.crossJoin()` right record,
+   * and BOTH sides of a `.crossJoinWith()` pair — is therefore invisible to
+   * it, and was served raw: a self cross-join returned `"10.00"` on the left
+   * and `"1000"` on the right of the same field (#1335).
+   *
+   * Runs LAST, after every filter, sort and page. That is deliberate: a
+   * `where()` operand is built in raw stored space, so dressing earlier would
+   * make a post-join predicate compare a decoded string against a raw one.
+   * Dressing is presentation; it belongs after the plan has finished.
+   *
+   * Each alias is decoded by the Via pipeline of the collection the record
+   * came FROM — money on the right side is the right side's declaration, not
+   * this collection's. A source that declares no result decode returns the
+   * record unchanged, so the whole pass is a no-op for the common query and
+   * is skipped entirely when the plan has no aliases.
+   */
+  dressAliases(rows) {
+    if (rows.length === 0) return rows;
+    const ctx = this.joinContext;
+    if (!ctx) return rows;
+    const targets = [];
+    const push = (path, collection) => {
+      const decode = ctx.resolveSource(collection)?.decodeResults;
+      if (decode) targets.push({ path, decode });
+    };
+    for (const clause of this.plan.clauses) {
+      if (clause.type !== "crossJoin") continue;
+      push(clause.as, clause.target);
+      if (clause.leftAs !== void 0) push(clause.leftAs, ctx.leftCollection);
+    }
+    for (const leg of this.plan.joins) {
+      if (leg.isDictJoin === true) continue;
+      push(leg.as, leg.target);
+    }
+    if (targets.length === 0) return rows;
+    return rows.map((row) => {
+      if (row === null || typeof row !== "object") return row;
+      let out;
+      for (const { path, decode } of targets) {
+        const value = row[path];
+        if (value === null || value === void 0 || typeof value !== "object") continue;
+        const dressed = decode(value);
+        if (dressed === value) continue;
+        out ??= { ...row };
+        out[path] = dressed;
+      }
+      return out ?? row;
+    });
+  }
+  /**
+   * Alias → the Via pipeline of the collection whose records sit under it
+   * (#1337). Every alias this plan can produce: a `.join()`/`.rightJoin()`
+   * leg, a `.crossJoin()` right side, and both sides of `.crossJoinWith()`.
+   *
+   * ⭐ **Ordering compares in RAW STORED SPACE, never in dressed space, and
+   * that is what forces this map to exist.** `dressAliases` runs LAST — after
+   * every filter, sort and page — because a `where` operand is built raw. So
+   * the sort sees money as its stored scaled integer, where a generic compare
+   * is lexical and gets `'9882'` vs `'10004'` backwards. The left side has
+   * always avoided that by asking `source.via.compareForOrder`; an aliased
+   * field needs the same question asked of the RIGHT side's pipeline, keyed
+   * by the field name WITHOUT the alias prefix (a pipeline covers bare field
+   * names — that is the whole of #1335's shape).
+   *
+   * Empty when no alias resolves a pipeline, in which case the comparator
+   * falls back to exactly what it did before.
+   */
+  aliasVia() {
+    const ctx = this.joinContext;
+    if (!ctx) return void 0;
+    const out = /* @__PURE__ */ new Map();
+    const push = (alias, collection) => {
+      const via = ctx.resolveSource(collection)?.via?.();
+      if (via) out.set(alias, via);
+    };
+    for (const clause of this.plan.clauses) {
+      if (clause.type !== "crossJoin") continue;
+      push(clause.as, clause.target);
+      if (clause.leftAs !== void 0) push(clause.leftAs, ctx.leftCollection);
+    }
+    for (const leg of this.plan.joins) {
+      if (leg.isDictJoin === true) continue;
+      push(leg.as, leg.target);
+    }
+    return out.size > 0 ? out : void 0;
+  }
+  /**
+   * Joins need a `JoinContext`. Unreachable in practice — `.join()` throws
+   * when one is missing — but belt-and-braces for a plan built through the
+   * raw `Query` constructor with joins pre-populated.
+   */
+  requireJoinContext(terminal) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.${terminal}(): plan carries ${this.plan.joins.length} join leg(s) but no JoinContext is attached. This usually means the Query was constructed via the raw Query constructor with a plan that had joins pre-populated. Use collection.query().join(...) instead.`
+      );
+    }
+    return this.joinContext;
+  }
+  /**
+   * Present this source's Via-covered fields on read, so `query().toArray()`
+   * agrees with `get()`/`list()` about what a record contains (#1416).
+   *
+   * ⛔ THIS USED TO RUN `decodeResults`, WHICH IS NOT THE SAME QUESTION. That
+   * hook is money's stored→canonical decode and nothing else, so a
+   * `computed({ mode: 'virtual' })` field read `undefined` on a query row while
+   * `get()` returned it — the same record with two shapes depending on which
+   * verb produced it, and a caller summing that field over a query result got
+   * `NaN` with no error. Reported at `receiptAmount get=84715.00 query=undefined`.
+   *
+   * The old doc comment defended the omission of money's `<field>Formatted` /
+   * `<field>Number` virtuals on the grounds that "the query layer carries no
+   * locale context", and that reasoning was right: fabricating a guessed-locale
+   * string here would make it-IT via `get()` disagree with en-US here. ⚠️ But
+   * the premise had gone stale — `toArray({ locale })` exists and threads its
+   * locale into `executePlanWithSource`, `applyJoins` and `applyOrderAndPage`.
+   * This was the one call site that never received it, which is also why joined
+   * ALIASES were dressed while the base row was not.
+   *
+   * So this presents at `'raw'`: values — money's canonical decode and every
+   * virtual computed field — while money's binding gates the locale-formatted
+   * virtuals on `locale !== 'raw'`, so nothing is guessed.
+   *
+   * ⛔ HONOURING `toArray({ locale })` HERE IS A SEPARATE CHANGE, and the
+   * obvious implementation is measurably wrong. Presenting twice — once raw for
+   * the plan, once at the locale for output — silently yields the RAW result:
+   *
+   *     presentSync(stored, raw)              -> { amount: "84715.00" }
+   *     presentSync(that,   'en-US')          -> { amount: "84715.00" }   <-- no siblings
+   *     presentSync(stored, 'en-US')          -> { amount: "84715.00",
+   *                                                amountFormatted: "THB 84,715.00", ... }
+   *
+   * because the second pass sees an already-decoded value and re-emits no
+   * siblings. So formatting has to happen in ONE pass at the final locale —
+   * and one of this method's call sites runs BEFORE the post-join filter,
+   * where a formatted value would change what a `where()` predicate compares
+   * against. That is the same rule `dressAliases` states: dressing is
+   * presentation and belongs after the plan has finished. Deciding it needs
+   * its own change; leaving `toArray({ locale })` inert for base rows is the
+   * status quo, not a new hole.
+   *
+   * ⚠️ SYNCHRONOUS, so it folds only the bindings that declared
+   * `presentIsSync` — money and computed. A collection also using i18n or
+   * lookup keeps those fields undressed here, exactly as today; `presentSync`
+   * reports them and `explain()` says so rather than leaving a silent hole.
+   * Making this complete would mean making `toArray()` async, which is the
+   * contract #1413 deliberately established.
+   */
+  decodeVia(records, locale) {
+    const via = this.source.via;
+    if (!via) return records;
+    const ctx = { locale: locale ?? "raw", layer: "read" };
+    return records.map((r) => via.presentSync(r, ctx).record);
+  }
+  /**
+   * Terminal sibling of `toArray()` that also returns the cursor for the next
+   * page (#1346): `{ rows, nextCursor }`, where `nextCursor` is `null` once
+   * the last page has been served.
+   *
+   * ```ts
+   * const { rows, nextCursor } = people.query().orderBy('name').limit(20).page()
+   * ```
+   *
+   * Without a sorted index this is still a scan with a keyset filter — stable,
+   * not fast. The fast path is a separate concern (#1344).
+   *
+   * Same requirements as `.after()`: at least one `orderBy(...)`, an id-paired
+   * (collection-backed) source, no join legs, no `offset()`.
+   *
+   * **Synchronous** (#1413) — returns `{ rows, nextCursor }`, not a promise; the cache it reads is
+   * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+   * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+   */
+  page(opts) {
+    const _h = this.source.hydration;
+    if (_h !== void 0 && !_h.isHydrated()) return gateTerminal(_h, "page", () => this.page(opts));
+    return this.executeKeyset(opts);
+  }
+  /**
+   * The keyset engine behind `page()` / `after()`.
+   *
+   * It deliberately does NOT reuse `applyOrderAndPage`: paging by keyset needs
+   * a TOTAL order (the id breaks ties that the ordinary sort leaves to input
+   * order) and needs the id alongside each row to mint the cursor. Both are
+   * properties of this path only, so the ordinary read path is untouched.
+   */
+  executeKeyset(opts) {
+    const plan = this.plan;
+    if (plan.orderBy.length === 0) {
+      throw new Error(
+        "Query.page()/after(): keyset pagination requires at least one orderBy(...) \u2014 a cursor names a position in a sort order, so there must be one to name."
+      );
+    }
+    if (plan.offset > 0) {
+      throw new Error(
+        "Query.page()/after(): offset() cannot be combined with a keyset cursor. They are two different pagination strategies \u2014 drop offset() and page with after(nextCursor)."
+      );
+    }
+    if (plan.joins.length > 0 || plan.clauses.some((c) => c.type === "crossJoin")) {
+      throw new Error(
+        "Query.page()/after(): keyset pagination does not support join legs or crossJoin (joined rows are new objects, so the record id the cursor needs is not recoverable). Page the left side, then join per page."
+      );
+    }
+    const source = this.source;
+    const snapshotEntries = source.snapshotEntries === void 0 ? void 0 : () => source.snapshotEntries();
+    if (snapshotEntries === void 0) {
+      throw new Error(
+        "Query.page()/after(): the query source has no snapshotEntries(); keyset pagination requires a collection-backed query (collection.query())."
+      );
+    }
+    const memoKey = keysetMemoKey(this.source, plan, opts?.locale);
+    const cached = memoKey === null ? void 0 : readKeysetMemo(memoKey);
+    let sorted;
+    let keyPlan;
+    if (cached) {
+      sorted = cached.sorted;
+      keyPlan = cached.keyPlan;
+    } else {
+      const refToId = /* @__PURE__ */ new Map();
+      for (const { id, record } of snapshotEntries()) refToId.set(record, id);
+      const matched = executePlanWithSource(
+        this.source,
+        { ...plan, orderBy: [], limit: void 0, offset: 0, after: void 0 },
+        this.joinContext,
+        opts?.locale
+      );
+      const labelMaps = buildOrderLabelMaps(plan.orderBy, this.joinContext, opts?.locale, this.source.via);
+      keyPlan = buildOrderKeyPlan(plan.orderBy, this.source.via, labelMaps);
+      sorted = matched.map((record) => ({ record, id: refToId.get(record) ?? "", key: orderKeyOf(keyPlan, record) })).sort((a, b) => compareOrderKeys(keyPlan, a.key, b.key) || compareIds(a.id, b.id));
+      if (memoKey !== null) writeKeysetMemo(memoKey, { sorted, keyPlan });
+    }
+    const shape = keysetShape(this.source.identity, plan.orderBy);
+    let start = 0;
+    if (plan.after !== void 0) {
+      const cursor = decodeCursor(plan.after, shape);
+      start = lowerBound(
+        sorted,
+        (r) => (compareOrderKeys(keyPlan, r.key, cursor.values) || compareIds(r.id, cursor.id)) > 0
+      );
+    }
+    const end = plan.limit === void 0 ? sorted.length : start + plan.limit;
+    const window = sorted.slice(start, end);
+    const last = window[window.length - 1];
+    const nextCursor = last !== void 0 && end < sorted.length ? encodeCursor({ shape, values: last.key, id: last.id }) : null;
+    return { rows: this.decodeVia(window.map((r) => r.record)), nextCursor };
+  }
+  /**
+   * Return the first matching record, or null. Joins are applied. `opts.locale`
+   * resolves joined i18n fields.
+   *
+   * **Synchronous** (#1413) — returns `T | null`, not a promise; the cache it reads is
+   * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+   * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+   */
+  first(opts) {
+    const _h = this.source.hydration;
+    if (_h !== void 0 && !_h.isHydrated()) return gateTerminal(_h, "first", () => this.first(opts));
+    const arr = this.limit(1).toArray(opts);
+    return arr[0] ?? null;
+  }
+  /**
+   * Return the number of matching records (after where/filter,
+   * before limit). **Joins are normally NOT applied** — count() reports the
+   * left-side cardinality, because joins are projection-only
+   * (they attach an aliased field; they never filter). Running joins
+   * here just to discard the aliases would be wasteful, and in strict
+   * mode it could throw `DanglingReferenceError` for a call whose
+   * intent is purely to count.
+   *
+   * The exception (#1030) is a `where` clause addressing a join alias. Then
+   * the legs must run, because the predicate is part of what is being
+   * counted — skipping them would report the unfiltered left cardinality.
+   * A strict-mode `DanglingReferenceError` becomes reachable from `count()`
+   * in exactly that case, which is acceptable: the caller asked to filter on
+   * the joined side, so they asked for the join.
+   *
+   * **Synchronous** (#1413) — returns `number`, not a promise; the cache it reads is
+   * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+   * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+   */
+  count() {
+    const _h = this.source.hydration;
+    if (_h !== void 0 && !_h.isHydrated()) return gateTerminal(_h, "count", () => this.count());
+    return this.matchedRecords("count").length;
+  }
+  /**
+   * The match set every reduce-shaped terminal reports over: `count()`,
+   * `distinct()`, and `exists()`'s non-short-circuit fallbacks.
+   *
+   * Extracted (#1347) rather than copied a third time, because "which records
+   * does this terminal see" is an INVARIANT across them — `distinct()`
+   * returning values `count()` never counted would be a bug nobody would look
+   * for. It is deliberately the `count()` pipeline: where/filter apply, joins
+   * apply only when a predicate addresses one (#1030), and orderBy/limit/offset
+   * do NOT — those describe a page, and a reduction is not paginated.
+   */
+  matchedRecords(terminal, forceJoins = false) {
+    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+      if (!this.joinContext) {
+        throw new Error(
+          `Query.${terminal}(): plan contains crossJoin clauses but no JoinContext is attached.`
+        );
+      }
+      return executeClausePipeline(this.source, this.plan.clauses, this.joinContext);
+    }
+    const { preJoin, postJoin } = splitAroundJoins(this.plan.clauses, this.plan.joins);
+    const { candidates, remainingClauses } = candidateRecords(this.source, preJoin);
+    const narrowed = remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(this.source));
+    const reshapes = this.plan.joins.some((leg) => leg.direction !== void 0 && leg.direction !== "left") || joinsDropLeftRows(this.plan.joins);
+    if (postJoin.length === 0 && !reshapes && !forceJoins) return narrowed;
+    const joined = applyJoins(narrowed, this.plan.joins, this.requireJoinContext(terminal));
+    return filterRecords(joined, postJoin, fnViewDecoder(this.source));
+  }
+  /**
+   * Whether ANY record matches (#1347) — `count() > 0` without paying for the
+   * records after the first.
+   *
+   * The saving is real rather than cosmetic: `count()` evaluates every
+   * remaining clause against every candidate, so a `.filter(fn)` over 10_000
+   * records calls `fn` 10_000 times to answer a yes/no question. This returns
+   * at the first hit, and `__tests__/query-distinct-exists.test.ts` witnesses
+   * that by COUNTING the predicate's invocations — a boolean assertion cannot
+   * tell a short-circuit from a full scan.
+   *
+   * Same match set as `count()`. Two shapes do NOT short-circuit and fall
+   * back to it, because both must materialize the relation before anything
+   * can be tested: a `crossJoin` expansion, and a `where` clause addressing a
+   * join alias (#1030). Both still answer correctly.
+   *
+   * **Synchronous** (#1413) — returns `boolean`, not a promise; the cache it reads is
+   * already decrypted. `await` is safe and is REQUIRED on an unhydrated collection
+   * (#1414); `.catch()` is not available. See the {@link Query} class doc.
+   */
+  exists() {
+    const _h = this.source.hydration;
+    if (_h !== void 0 && !_h.isHydrated()) return gateTerminal(_h, "exists", () => this.exists());
+    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+      return this.matchedRecords("exists").length > 0;
+    }
+    const { preJoin, postJoin } = splitAroundJoins(this.plan.clauses, this.plan.joins);
+    if (postJoin.length > 0 || joinsDropLeftRows(this.plan.joins)) {
+      return this.matchedRecords("exists").length > 0;
+    }
+    const { candidates, remainingClauses } = candidateRecords(this.source, preJoin);
+    if (remainingClauses.length === 0) return candidates.length > 0;
+    return anyMatches(candidates, remainingClauses, fnViewDecoder(this.source));
+  }
+  /**
+   * Return the plan as a JSON-friendly object. FilterClause entries are
+   * stripped (their `fn` cannot be serialized) and replaced with
+   * { type: 'filter', fn: '[function]' } so devtools can still see them.
+   */
+  toPlan() {
+    return serializePlan(this.plan);
+  }
+};
+var EXTENSION_METHODS = [
+  ["subscribe", "@noy-db/hub/query/live"],
+  ["live", "@noy-db/hub/query/live"],
+  ["aggregate", "@noy-db/hub/query/reduce"],
+  ["groupBy", "@noy-db/hub/query/reduce"],
+  ["window", "@noy-db/hub/query/reduce"],
+  ["distinct", "@noy-db/hub/query/reduce"],
+  ["join", "@noy-db/hub/query/relate"],
+  ["joinOn", "@noy-db/hub/query/relate"],
+  ["rightJoin", "@noy-db/hub/query/relate"],
+  ["fullOuterJoin", "@noy-db/hub/query/relate"],
+  ["crossJoin", "@noy-db/hub/query/relate"],
+  ["crossJoinWith", "@noy-db/hub/query/relate"],
+  ["traverse", "@noy-db/hub/query/relate"],
+  ["ancestorsOf", "@noy-db/hub/query/relate"],
+  ["descendantsOf", "@noy-db/hub/query/relate"],
+  ["explain", "@noy-db/hub/query/relate"]
+];
+for (const [method, subpath] of EXTENSION_METHODS) {
+  Object.defineProperty(Query.prototype, method, {
+    value: function extensionMissing() {
+      throw new QueryExtensionMissingError(method, subpath);
+    },
+    writable: true,
+    enumerable: false,
+    configurable: true
+  });
+}
+function executePlanWithSource(source, plan, joinContext, locale, aliasVia) {
+  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 ordered = orderedIndexRows(source, plan) ?? compoundOrderedRows(source, plan);
+    if (ordered) return ordered;
+    const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
+    result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
+  }
+  return applyOrderAndPage(result, plan, source, joinContext, locale, aliasVia);
+}
+function applyOrderAndPage(rows, plan, source, joinContext, locale, aliasVia) {
+  let result = rows;
+  if (plan.orderBy.length > 0) {
+    const labelMaps = buildOrderLabelMaps(plan.orderBy, joinContext, locale, source.via);
+    result = sortRecords(result, plan.orderBy, source.via, labelMaps, aliasVia);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+var RANGE_OPERATORS = /* @__PURE__ */ new Set(["<", "<=", ">", ">=", "between", "startsWith"]);
+function isRangeOperator(op) {
+  return RANGE_OPERATORS.has(op);
+}
+function orderedIndexRows(source, plan) {
+  const limit = plan.limit;
+  if (limit === void 0 || plan.clauses.length > 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 || !indexes.hasSorted(order.field)) return null;
+  const lookupById = (id) => source.lookupById?.(id);
+  if (viaOrdersField(source.via, order.field)) return null;
+  const snapshot = source.snapshot();
+  if (indexes.sortedSize(order.field) !== snapshot.length) return null;
+  const ids = indexes.orderedIds(order.field, order.direction);
+  if (!ids) return null;
+  const out = [];
+  for (let i = plan.offset; i < ids.length && out.length < limit; i++) {
+    const record = lookupById(ids[i]);
+    if (record !== void 0) out.push(record);
+  }
+  return out;
+}
+function viaOrdersField(via, field) {
+  return via !== void 0 && via.compareForOrder(field, "", "") !== void 0;
+}
+function indexableClauses(clauses) {
+  const eq = /* @__PURE__ */ new Map();
+  const ranges = /* @__PURE__ */ new Map();
+  for (let i = 0; i < clauses.length; i++) {
+    const clause = clauses[i];
+    if (clause.type !== "field" || clause.via !== void 0) continue;
+    if (clause.op === "==") {
+      if (!eq.has(clause.field)) eq.set(clause.field, { value: clause.value, at: i });
+    } else if (isRangeOperator(clause.op)) {
+      if (!ranges.has(clause.field)) ranges.set(clause.field, { op: clause.op, value: clause.value, at: i });
+    }
+  }
+  return { eq, ranges };
+}
+function pickCompound(indexes, clauses) {
+  const { eq, ranges } = indexableClauses(clauses);
+  if (eq.size === 0) return null;
+  let best = null;
+  for (const fields of indexes.compoundTuples()) {
+    const values = [];
+    const consumed = /* @__PURE__ */ new Set();
+    let depth = 0;
+    while (depth < fields.length) {
+      const hit = eq.get(fields[depth]);
+      if (!hit) break;
+      values.push(hit.value);
+      consumed.add(hit.at);
+      depth++;
+    }
+    if (depth === 0) continue;
+    let range;
+    if (depth < fields.length) {
+      const hit = ranges.get(fields[depth]);
+      if (hit) {
+        range = { op: hit.op, value: hit.value };
+        consumed.add(hit.at);
+      }
+    }
+    if (consumed.size < 2) continue;
+    if (!best || consumed.size > best.consumed.size) {
+      best = { fields, values, consumed, ...range ? { range } : {} };
+    }
+  }
+  return best;
+}
+function compoundCandidates(source, indexes, lookupById, clauses) {
+  const pick = pickCompound(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);
+  if (!ids) return null;
+  return { candidates: materializeIds(ids, lookupById), remainingClauses: clauses };
+}
+function compoundOrderedRows(source, plan) {
+  const limit = plan.limit;
+  if (limit === void 0 || plan.clauses.length === 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 { eq } = indexableClauses(plan.clauses);
+  if (eq.size !== plan.clauses.length) return null;
+  const match = pickCompoundOrder(indexes, eq, order.field);
+  if (!match) return null;
+  const snapshot = source.snapshot();
+  if (indexes.compoundSize(match.fields) !== snapshot.length) return null;
+  const ids = indexes.compoundOrderedIds(match.fields, match.values, order.direction);
+  if (!ids) return null;
+  const lookupById = (id) => source.lookupById?.(id);
+  const out = [];
+  let matched = 0;
+  for (let i = 0; i < ids.length && out.length < limit; i++) {
+    const record = lookupById(ids[i]);
+    if (record === void 0) continue;
+    let hit = true;
+    for (const clause of plan.clauses) {
+      if (!evaluateClause(record, clause)) {
+        hit = false;
+        break;
+      }
+    }
+    if (!hit) continue;
+    if (matched++ < plan.offset) continue;
+    out.push(record);
+  }
+  return out;
+}
+function pickCompoundOrder(indexes, eq, orderField) {
+  for (const fields of indexes.compoundTuples()) {
+    if (fields.length !== eq.size + 1) continue;
+    if (fields[fields.length - 1] !== orderField) continue;
+    const values = [];
+    for (let i = 0; i < fields.length - 1; i++) {
+      const hit = eq.get(fields[i]);
+      if (!hit) break;
+      values.push(hit.value);
+    }
+    if (values.length === fields.length - 1) return { fields, values };
+  }
+  return null;
+}
+function candidateRecords(source, clauses) {
+  const indexes = source.getIndexes?.();
+  if (!indexes || !source.lookupById || clauses.length === 0) {
+    return { candidates: source.snapshot(), remainingClauses: clauses };
+  }
+  const lookupById = (id) => source.lookupById?.(id);
+  const compound = compoundCandidates(source, indexes, lookupById, clauses);
+  if (compound) return compound;
+  const prefixed = prefixCandidates(indexes, lookupById, 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)) continue;
+    if (clause.via && clause.via.indexValue === void 0) continue;
+    const probeValue = clause.via ? clause.via.indexValue : clause.value;
+    let ids = null;
+    let exact = true;
+    if (clause.op === "==") {
+      ids = indexes.lookupEqual(clause.field, probeValue);
+      exact = false;
+    } else if (clause.op === "in" && Array.isArray(probeValue)) {
+      ids = indexes.lookupIn(clause.field, probeValue);
+      exact = false;
+    } else if (clause.via === void 0 && isRangeOperator(clause.op)) {
+      ids = indexes.lookupRange(clause.field, clause.op, clause.value);
+    }
+    if (ids !== null) {
+      const remaining = [];
+      for (let j = 0; j < clauses.length; j++) {
+        if (j !== i || !exact) remaining.push(clauses[j]);
+      }
+      return {
+        candidates: materializeIds(ids, lookupById),
+        remainingClauses: remaining
+      };
+    }
+  }
+  return { candidates: source.snapshot(), remainingClauses: clauses };
+}
+function prefixCandidates(indexes, lookupById, clauses) {
+  for (const clause of clauses) {
+    if (clause.type !== "field" || clause.via === void 0) continue;
+    const probe = clause.via.indexValue;
+    if (!isViaPrefixProbe(probe)) continue;
+    if (!indexes.hasSorted(clause.field)) continue;
+    const ids = /* @__PURE__ */ new Set();
+    for (const prefix of probe.prefixes) {
+      const hit = indexes.lookupRange(clause.field, "startsWith", prefix);
+      if (hit === null) return null;
+      for (const id of hit) ids.add(id);
+    }
+    return { candidates: materializeIds(ids, lookupById), remainingClauses: clauses };
+  }
+  return null;
+}
+function materializeIds(ids, lookupById) {
+  const out = [];
+  for (const id of ids) {
+    const record = lookupById(id);
+    if (record !== void 0) out.push(record);
+  }
+  return out;
+}
+function executePlan(records, plan) {
+  if (plan.clauses.some((c) => c.type === "crossJoin")) {
+    throw new Error(
+      `executePlan(): does not support crossJoin clauses. executePlan is a stateless pure function \u2014 it cannot resolve cross-join right-side collections. Use Query.toArray() (via collection.query()) instead.`
+    );
+  }
+  let result = filterRecords(records, plan.clauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function fnViewDecoder(source) {
+  const via = source.via;
+  if (!via || !via.hasResultDecode) return void 0;
+  return (r) => via.decodeResults(r);
+}
+function compileClause(clause) {
+  if (clause.type === "field" && clause.via === void 0 && !clause.field.includes(".")) {
+    const field = clause.field;
+    const value = clause.value;
+    if (clause.op === "==") {
+      return (r) => (r === null || r === void 0 ? void 0 : r[field]) === value;
+    }
+    if (clause.op === "in") {
+      const set = Array.isArray(value) ? new Set(value) : null;
+      if (set !== null) {
+        return (r) => set.has(r === null || r === void 0 ? void 0 : r[field]);
+      }
+      return () => false;
+    }
+  }
+  return (r, fnView) => evaluateClause(r, clause, fnView);
+}
+function filterRecords(records, clauses, decodeForFns) {
+  if (clauses.length === 0) return [...records];
+  const needsFnView = decodeForFns !== void 0 && hasFnClause(clauses);
+  const compiled = clauses.map(compileClause);
+  const out = [];
+  for (const r of records) {
+    const fnView = needsFnView ? decodeForFns(r) : void 0;
+    let matches = true;
+    for (const test of compiled) {
+      if (!test(r, fnView)) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) out.push(r);
+  }
+  return out;
+}
+function anyMatches(records, clauses, decodeForFns) {
+  if (clauses.length === 0) return records.length > 0;
+  const needsFnView = decodeForFns !== void 0 && hasFnClause(clauses);
+  for (const r of records) {
+    const fnView = needsFnView ? decodeForFns(r) : void 0;
+    let matches = true;
+    for (const clause of clauses) {
+      if (!evaluateClause(r, clause, fnView)) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) return true;
+  }
+  return false;
+}
+function executeClausePipeline(source, clauses, joinContext) {
+  let rel = [...source.snapshot()];
+  let filterBatch = [];
+  const decodeForFns = fnViewDecoder(source);
+  for (const clause of clauses) {
+    if (clause.type === "crossJoin") {
+      if (filterBatch.length > 0) {
+        rel = filterRecords(rel, filterBatch, decodeForFns);
+        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, decodeForFns);
+  }
+  return rel;
+}
+var KEYSET_MEMO_LIMIT = 8;
+var keysetMemo = /* @__PURE__ */ new Map();
+function readKeysetMemo(key) {
+  const hit = keysetMemo.get(key);
+  if (hit) {
+    keysetMemo.delete(key);
+    keysetMemo.set(key, hit);
+  }
+  return hit;
+}
+function writeKeysetMemo(key, entry) {
+  keysetMemo.set(key, entry);
+  while (keysetMemo.size > KEYSET_MEMO_LIMIT) {
+    const oldest = keysetMemo.keys().next();
+    if (oldest.done === true) break;
+    keysetMemo.delete(oldest.value);
+  }
+}
+function keysetMemoKey(source, plan, locale) {
+  const identity = source.identity;
+  const version = source.snapshotVersion?.();
+  if (identity === void 0 || version === void 0) return null;
+  const parts = [identity, String(version), locale ?? ""];
+  for (const clause of plan.clauses) {
+    if (clause.type !== "field") return null;
+    const value = fingerprintOperand(clause.value);
+    if (value === null) return null;
+    parts.push(`w:${clause.field}:${clause.op}:${value}`);
+  }
+  for (const o of plan.orderBy) parts.push(`o:${o.field}:${o.direction}:${o.by ?? "value"}`);
+  return parts.join("\0");
+}
+function fingerprintOperand(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (value instanceof Date) return `D${value.getTime()}`;
+  if (typeof value === "string") return `s${value}`;
+  if (typeof value === "number") return `n${value}`;
+  if (typeof value === "bigint") return `g${value}`;
+  if (typeof value === "boolean") return `b${value}`;
+  if (Array.isArray(value)) {
+    const each = value.map(fingerprintOperand);
+    if (each.some((e) => e === null)) return null;
+    return `[${each.join(",")}]`;
+  }
+  return null;
+}
+function lowerBound(arr, pred) {
+  let lo = 0;
+  let hi = arr.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (pred(arr[mid])) hi = mid;
+    else lo = mid + 1;
+  }
+  return lo;
+}
+function buildOrderKeyPlan(orderBy, via, labelMaps, aliasVia) {
+  return {
+    entries: orderBy.map(({ field, direction, by }) => {
+      const dot = field.indexOf(".");
+      const aliased = dot > 0 ? aliasVia?.get(field.slice(0, dot)) : void 0;
+      return {
+        field,
+        direction,
+        labelResolver: by === "label" ? labelMaps?.get(field) : void 0,
+        via: aliased ?? via,
+        viaField: aliased ? field.slice(dot + 1) : field
+      };
+    })
+  };
+}
+function orderKeyOf(plan, record) {
+  return plan.entries.map(({ field, labelResolver }) => {
+    const v = readField(record, field);
+    if (labelResolver) return (typeof v === "string" ? labelResolver(v) : void 0) ?? v;
+    return v;
+  });
+}
+function compareOrderKeys(plan, a, b) {
+  for (let i = 0; i < plan.entries.length; i++) {
+    const { direction, labelResolver, via, viaField } = plan.entries[i];
+    const av = a[i];
+    const bv = b[i];
+    const viaCmp = labelResolver ? void 0 : via?.compareForOrder(viaField, av, bv);
+    const cmp = viaCmp !== void 0 ? viaCmp : compareValues(av, bv);
+    if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
+  }
+  return 0;
+}
+function compareIds(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function sortRecords(records, orderBy, via, labelMaps, aliasVia) {
+  const plan = buildOrderKeyPlan(orderBy, via, labelMaps, aliasVia);
+  return [...records].sort(
+    (a, b) => compareOrderKeys(plan, orderKeyOf(plan, a), orderKeyOf(plan, b))
+  );
+}
+function buildOrderLabelMaps(orderBy, joinContext, locale, via) {
+  let maps;
+  for (const { field, by } of orderBy) {
+    if (by !== "label") continue;
+    const dictSource = joinContext?.resolveDictSource?.(field);
+    if (dictSource) {
+      const loc = locale ?? dictSource.displayLocale;
+      if (loc === void 0) continue;
+      const codeToLabel = /* @__PURE__ */ new Map();
+      for (const entry of dictSource.snapshot()) {
+        const k = entry["key"];
+        const labels = entry["labels"];
+        const label = labels?.[loc];
+        if (typeof k === "string" && typeof label === "string") codeToLabel.set(k, label);
+      }
+      ;
+      (maps ??= /* @__PURE__ */ new Map()).set(field, (code) => codeToLabel.get(code));
+      continue;
+    }
+    if (via) {
+      const cache = /* @__PURE__ */ new Map();
+      (maps ??= /* @__PURE__ */ new Map()).set(field, (code) => {
+        if (!cache.has(code)) cache.set(code, via.resolveOrderLabel(field, code, locale));
+        return cache.get(code);
+      });
+    }
+  }
+  return maps;
+}
+function readField(record, field) {
+  if (record === null || record === void 0) return void 0;
+  if (!field.includes(".")) {
+    return record[field];
+  }
+  const segments = field.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function compareValues(a, b) {
+  if (a === void 0 || a === null) return b === void 0 || b === null ? 0 : 1;
+  if (b === void 0 || b === null) return -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+  return 0;
+}
+function serializePlan(plan) {
+  return {
+    clauses: plan.clauses.map(serializeClause),
+    orderBy: plan.orderBy,
+    limit: plan.limit,
+    offset: plan.offset,
+    after: plan.after,
+    joins: plan.joins
+  };
+}
+function serializeClause(clause) {
+  if (clause.type === "filter") {
+    return { type: "filter", fn: "[function]" };
+  }
+  if (clause.type === "wherePredicate") {
+    return {
+      type: "wherePredicate",
+      name: clause.name,
+      ctx: clause.ctx,
+      predicateHash: clause.predicateHash,
+      ctxHash: clause.ctxHash,
+      fn: "[function]"
+    };
+  }
+  if (clause.type === "group") {
+    return {
+      type: "group",
+      op: clause.op,
+      clauses: clause.clauses.map(serializeClause)
+    };
+  }
+  if (clause.type === "crossJoin") {
+    return {
+      type: "crossJoin",
+      target: clause.target,
+      as: clause.as,
+      // Identity, not decoration: `leftAs` changes the SHAPE of every row
+      // (#1289), so two plans differing only in it are different queries.
+      // Omitted when unset so a `.crossJoin()` plan serializes exactly as it
+      // did before #1289 and no stored queryHash moves.
+      ...clause.leftAs !== void 0 && { leftAs: clause.leftAs },
+      on: clause.on ? "[function]" : void 0,
+      onPredicateName: clause.onPredicateName,
+      maxRows: clause.maxRows,
+      // Part of the identity, not decoration: `outer` changes which rows come
+      // back, so omitting it here would let an inner-mode plan be reused for an
+      // outer-mode query under the same hash (#1130).
+      outer: clause.outer
+    };
+  }
+  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 displayLocale = dictSource.displayLocale;
+  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 effLocale = locale || displayLocale;
+    if (!effLocale) return void 0;
+    const labels = dictMap.get(key);
+    if (!labels) return void 0;
+    if (labels[effLocale] !== void 0) return labels[effLocale];
+    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;
+  };
+}
+
+export {
+  installRelateHooks,
+  splitAroundJoins,
+  Query,
+  isRangeOperator,
+  viaOrdersField,
+  indexableClauses,
+  pickCompound,
+  pickCompoundOrder,
+  candidateRecords,
+  executePlan,
+  fnViewDecoder,
+  filterRecords,
+  executeClausePipeline,
+  buildOrderKeyPlan,
+  orderKeyOf,
+  compareOrderKeys,
+  sortRecords,
+  buildDictLabelResolver
+};
+//# sourceMappingURL=chunk-AL6ML4LA.js.map