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

package/dist/chunk-7HAPHVRJ.js

@@ -1,1695 +0,0 @@
-import {
-  reducerBuilder
-} from "./chunk-2XE6LIXT.js";
-import {
-  evaluateClause,
-  hasFnClause,
-  readPath
-} from "./chunk-KCG3BHFG.js";
-import {
-  CrossJoinSourceUnknownError,
-  CrossJoinTooLargeError,
-  DanglingReferenceError,
-  FieldNotQueryableError,
-  JoinTooLargeError
-} from "./chunk-CU62BBRB.js";
-
-// src/kernel/query/join.ts
-var DEFAULT_JOIN_MAX_ROWS = 5e4;
-var JOIN_WARN_FRACTION = 0.8;
-function coerceRefKey(value) {
-  if (value === null || value === void 0) return null;
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "bigint") return String(value);
-  return null;
-}
-var warnedDanglingKeys = /* @__PURE__ */ new Set();
-function warnOnceDangling(field, target, refId) {
-  const key = `${field}\u2192${target}:${refId}`;
-  if (warnedDanglingKeys.has(key)) return;
-  warnedDanglingKeys.add(key);
-  console.warn(
-    `[noy-db] .join() encountered dangling ref in 'warn' mode: field "${field}" \u2192 "${target}:${refId}" not found. Attaching null.`
-  );
-}
-var warnedCeilingKeys = /* @__PURE__ */ new Set();
-function warnCeilingApproaching(target, side, rows, maxRows) {
-  const key = `${target}:${side}`;
-  if (warnedCeilingKeys.has(key)) return;
-  warnedCeilingKeys.add(key);
-  const pct = Math.round(rows / maxRows * 100);
-  console.warn(
-    `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ceiling for target "${target}" (${rows} rows). Streaming joins over scan() are not yet supported for collections that need to exceed this.`
-  );
-}
-function applyJoins(rows, joins, context, locale) {
-  if (joins.length === 0) return [...rows];
-  let result = [...rows];
-  for (const leg of joins) {
-    result = applyOneJoin(result, leg, context, locale);
-  }
-  return result;
-}
-function applyOneJoin(leftRows, leg, context, locale) {
-  if (leg.isDictJoin) {
-    const dictSource = context.resolveDictSource?.(leg.field);
-    if (!dictSource) {
-      throw new Error(
-        `.join() field "${leg.field}" on "${context.leftCollection}" is declared as a dictKey join but the dict source could not be resolved. Ensure the dictionary has at least one entry.`
-      );
-    }
-    const out = [];
-    const snapshot = dictSource.snapshot();
-    const dictMap = /* @__PURE__ */ new Map();
-    for (const entry of snapshot) {
-      const k = readPath(entry, "key");
-      if (typeof k === "string") dictMap.set(k, entry);
-    }
-    for (const left of leftRows) {
-      const rawId = readPath(left, leg.field);
-      const key = coerceRefKey(rawId);
-      const dictEntry = key === null ? void 0 : dictMap.get(key);
-      out.push({ ...left, [leg.as]: dictEntry ?? null });
-    }
-    return out;
-  }
-  const source = context.resolveSource(leg.target);
-  if (!source) {
-    throw new Error(
-      `.join() cannot resolve target collection "${leg.target}" (referenced from field "${leg.field}" on "${context.leftCollection}"). Make sure the target collection has been opened via vault.collection() at least once before running the query.`
-    );
-  }
-  const maxRows = leg.maxRows ?? DEFAULT_JOIN_MAX_ROWS;
-  if (leftRows.length > maxRows) {
-    throw new JoinTooLargeError({
-      leftRows: leftRows.length,
-      rightRows: -1,
-      maxRows,
-      side: "left",
-      message: `.join() left side has ${leftRows.length} rows, exceeding the ${maxRows}-row ceiling for target "${leg.target}". Filter the left side further with where()/limit() before joining, or raise the ceiling via { maxRows }. Streaming joins over scan() are not yet supported.`
-    });
-  }
-  if (leftRows.length > maxRows * JOIN_WARN_FRACTION) {
-    warnCeilingApproaching(leg.target, "left", leftRows.length, maxRows);
-  }
-  const rightSnapshot = source.snapshot();
-  if (rightSnapshot.length > maxRows) {
-    throw new JoinTooLargeError({
-      leftRows: leftRows.length,
-      rightRows: rightSnapshot.length,
-      maxRows,
-      side: "right",
-      message: `.join() right side "${leg.target}" has ${rightSnapshot.length} rows, exceeding the ${maxRows}-row ceiling. Raise the ceiling via { maxRows } if the data genuinely fits in memory, or track  for streaming joins.`
-    });
-  }
-  if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {
-    warnCeilingApproaching(leg.target, "right", rightSnapshot.length, maxRows);
-  }
-  const effLocale = locale ?? context.defaultLocale;
-  const presentResolve = effLocale !== void 0 && source.presentForJoin !== void 0 ? (right) => right !== null && typeof right === "object" ? source.presentForJoin(right, effLocale) : right : void 0;
-  const strategy = leg.strategy ?? (source.lookupById ? "nested" : "hash");
-  if (strategy === "nested" && source.lookupById) {
-    const lookup = (id) => source.lookupById?.(id);
-    return nestedLoopJoin(leftRows, leg, lookup, presentResolve);
-  }
-  return hashJoin(leftRows, leg, rightSnapshot, presentResolve);
-}
-function nestedLoopJoin(leftRows, leg, lookupById, presentResolve) {
-  const out = [];
-  for (const left of leftRows) {
-    const rawId = readPath(left, leg.field);
-    const key = coerceRefKey(rawId);
-    let right = key === null ? void 0 : lookupById(key);
-    if (presentResolve && right !== void 0) right = presentResolve(right);
-    out.push(attachJoin(left, leg, right, rawId));
-  }
-  return out;
-}
-function hashJoin(leftRows, leg, rightSnapshot, presentResolve) {
-  const rightMap = /* @__PURE__ */ new Map();
-  for (const record of rightSnapshot) {
-    const rawId = readPath(record, "id");
-    const key = coerceRefKey(rawId);
-    if (key !== null) {
-      rightMap.set(key, record);
-    }
-  }
-  const out = [];
-  for (const left of leftRows) {
-    const rawId = readPath(left, leg.field);
-    const key = coerceRefKey(rawId);
-    let right = key === null ? void 0 : rightMap.get(key);
-    if (presentResolve && right !== void 0) right = presentResolve(right);
-    out.push(attachJoin(left, leg, right, rawId));
-  }
-  return out;
-}
-function attachJoin(left, leg, right, rawId) {
-  if (left === null || typeof left !== "object") {
-    return left;
-  }
-  const merged = { ...left };
-  const refKey = coerceRefKey(rawId);
-  if (right === void 0) {
-    if (refKey !== null && leg.mode === "strict") {
-      throw new DanglingReferenceError({
-        field: leg.field,
-        target: leg.target,
-        refId: refKey,
-        message: `.join() strict dangling: record references "${leg.target}:${refKey}" via field "${leg.field}", but no such record exists. Use ref() mode 'warn' or 'cascade' if dangling refs are acceptable, or run vault.checkIntegrity() to find and fix the orphans.`
-      });
-    }
-    if (refKey !== null && leg.mode === "warn") {
-      warnOnceDangling(leg.field, leg.target, refKey);
-    }
-    merged[leg.as] = null;
-  } else {
-    merged[leg.as] = right;
-  }
-  return merged;
-}
-function resetJoinWarnings() {
-  warnedDanglingKeys.clear();
-  warnedCeilingKeys.clear();
-}
-
-// src/kernel/query/live.ts
-function buildLiveQuery(recompute, upstreams) {
-  return new LiveQueryImpl(recompute, upstreams);
-}
-var LiveQueryImpl = class {
-  constructor(recompute, upstreams) {
-    this.recompute = recompute;
-    this.refresh();
-    for (const upstream of upstreams) {
-      try {
-        this.unsubs.push(upstream.subscribe(this.onUpstreamChange));
-      } catch (err) {
-        this._error = err instanceof Error ? err : new Error(String(err));
-      }
-    }
-  }
-  recompute;
-  _value = [];
-  _error = null;
-  listeners = /* @__PURE__ */ new Set();
-  unsubs = [];
-  stopped = false;
-  get value() {
-    return this._value;
-  }
-  get error() {
-    return this._error;
-  }
-  /**
-   * Bound change handler — used as the callback passed to every
-   * upstream's subscribe. Bound via class field so the `this`
-   * context survives the indirect call from arbitrary upstreams.
-   */
-  onUpstreamChange = () => {
-    this.refresh();
-    for (const cb of this.listeners) {
-      try {
-        cb();
-      } catch {
-      }
-    }
-  };
-  refresh() {
-    if (this.stopped) return;
-    try {
-      this._value = this.recompute();
-      this._error = null;
-    } catch (err) {
-      this._error = err instanceof Error ? err : new Error(String(err));
-    }
-  }
-  subscribe(cb) {
-    if (this.stopped) return () => {
-    };
-    this.listeners.add(cb);
-    return () => this.listeners.delete(cb);
-  }
-  stop() {
-    if (this.stopped) return;
-    this.stopped = true;
-    for (const unsub of this.unsubs) {
-      try {
-        unsub();
-      } catch {
-      }
-    }
-    this.unsubs.length = 0;
-    this.listeners.clear();
-  }
-};
-
-// src/with-lookup/aggregate/strategy.ts
-var NOT_ENABLED = new Error(
-  'Aggregate / groupBy is not enabled on this Noydb instance. Import `{ withAggregate }` from "@noy-db/hub/aggregate" and pass it to `createNoydb({ aggregateStrategy: withAggregate() })`.'
-);
-var NO_AGGREGATE = {
-  aggregate() {
-    throw NOT_ENABLED;
-  },
-  groupBy() {
-    throw NOT_ENABLED;
-  },
-  groupByN() {
-    throw NOT_ENABLED;
-  },
-  scanAggregate() {
-    throw NOT_ENABLED;
-  }
-};
-
-// src/kernel/query/builder.ts
-var EMPTY_PLAN = {
-  clauses: [],
-  orderBy: [],
-  limit: void 0,
-  offset: 0,
-  joins: []
-};
-var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
-var Query = class _Query {
-  source;
-  plan;
-  joinContext;
-  aggregateStrategy;
-  predicates;
-  constructor(source, plan = EMPTY_PLAN, joinContext, aggregateStrategy = NO_AGGREGATE, predicates) {
-    this.source = source;
-    this.plan = plan;
-    this.joinContext = joinContext;
-    this.aggregateStrategy = aggregateStrategy;
-    this.predicates = predicates;
-  }
-  /**
-   * @internal — accessor for the materialized-view dependency
-   * analyzer. Not part of the public API; consumers should use the
-   * builder methods, not inspect the plan directly.
-   */
-  _plan() {
-    return this.plan;
-  }
-  /**
-   * @internal — accessor for the materialized-view dependency
-   * analyzer. Returns the join resolution context (or `undefined` for
-   * queries constructed without a Collection backing).
-   */
-  _joinContext() {
-    return this.joinContext;
-  }
-  /**
-   * @internal — clone this Query with a declared-predicate map
-   * attached. Used by the materialized-view registry to enable
-   * `.wherePredicate(name, ctx?)` for the MV's query callback.
-   * Consumers don't call this directly.
-   */
-  _withPredicates(predicates) {
-    return new _Query(
-      this.source,
-      this.plan,
-      this.joinContext,
-      this.aggregateStrategy,
-      predicates
-    );
-  }
-  /**
-   * @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;
-  }
-  /**
-   * 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.
-   *
-   * 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 viaClause = via?.buildClause(field, op, value);
-    const clause = viaClause ? {
-      type: "field",
-      field,
-      op,
-      value,
-      via: {
-        brand: viaClause.brand,
-        payload: viaClause.payload,
-        evaluate: (actual, evalOp) => via.evaluateClause(viaClause, actual, evalOp)
-      }
-    } : { type: "field", field, op, value };
-    return new _Query(
-      this.source,
-      { ...this.plan, clauses: [...this.plan.clauses, clause] },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /**
-   * Logical OR group. Pass a callback that builds a sub-query.
-   * Each clause inside the callback is OR-combined; the group itself
-   * joins the parent plan with AND.
-   */
-  or(builder) {
-    const sub = builder(
-      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy, this.predicates)
-    );
-    const group = {
-      type: "group",
-      op: "or",
-      clauses: sub.plan.clauses
-    };
-    return new _Query(
-      this.source,
-      { ...this.plan, clauses: [...this.plan.clauses, group] },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /**
-   * Logical AND group. Same shape as `or()` but every clause inside the group
-   * must match. Useful for explicit grouping inside a larger OR.
-   */
-  and(builder) {
-    const sub = builder(
-      new _Query(this.source, EMPTY_PLAN, this.joinContext, this.aggregateStrategy, this.predicates)
-    );
-    const group = {
-      type: "group",
-      op: "and",
-      clauses: sub.plan.clauses
-    };
-    return new _Query(
-      this.source,
-      { ...this.plan, clauses: [...this.plan.clauses, group] },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /** Escape hatch: add an arbitrary predicate function. Not serializable. */
-  filter(fn) {
-    const clause = {
-      type: "filter",
-      fn
-    };
-    return new _Query(
-      this.source,
-      { ...this.plan, clauses: [...this.plan.clauses, clause] },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /**
-   * Sort by a field. Subsequent calls are tie-breakers. 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.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /** Cap the result size. */
-  limit(n) {
-    return new _Query(
-      this.source,
-      { ...this.plan, limit: n },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /** Skip the first N matching records (after ordering). */
-  offset(n) {
-    return new _Query(
-      this.source,
-      { ...this.plan, offset: n },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /**
-   * Resolve a `ref()`-declared foreign key and attach the right-side
-   * record under `opts.as`. — eager, single-FK, intra-
-   * vault joins.
-   *
-   * ```ts
-   * const rows = invoices.query()
-   *   .where('status', '==', 'open')
-   *   .join('clientId', { as: 'client' })
-   *   .toArray()
-   * // → [{ id, amount, client: { id, name, ... } }, ...]
-   * ```
-   *
-   * Preconditions:
-   *   - The Query must have a `joinContext` (constructed via
-   *     `Collection.query()`, not `new Query`).
-   *   - `field` must have a matching `refs: { [field]: ref('<target>') }`
-   *     declaration on the left collection.
-   *   - The target collection must be reachable via the vault
-   *     (either currently open or openable on demand).
-   *
-   * Strategy:
-   *   - Nested-loop against `lookupById` when the target source
-   *     provides it (the common path for Collection targets).
-   *   - Hash join otherwise, or when `{ strategy: 'hash' }` is
-   *     explicitly passed for test purposes.
-   *
-   * Ref-mode semantics on dangling refs (left record has a non-null
-   * FK value pointing at a right-side id that doesn't exist):
-   *   - `strict`  → throws `DanglingReferenceError` with the full
-   *     field / target / refId context.
-   *   - `warn`    → attaches `null` and emits a one-shot warning per
-   *     unique dangling pair.
-   *   - `cascade` → attaches `null` silently. Cascade is a
-   *     delete-time mode; dangling refs visible at read time are
-   *     either mid-flight cascades or pre-existing orphans, not a
-   *     DSL-level error.
-   *
-   * A left-side record whose FK field is `null` / `undefined` is NOT
-   * a dangling ref — it's "no reference at all", always allowed
-   * regardless of mode.
-   *
-   * The return type widens `T` with `Record<As, R | null>`. The `R`
-   * parameter is optional — supply it explicitly for type-checked
-   * access to the joined fields:
-   *
-   * ```ts
-   * invoices.query().join<'client', Client>('clientId', { as: 'client' })
-   * //                 ^^^^^^^^^^^^^^^^^^^ alias literal + right-side type
-   * ```
-   *
-   * Without the generic, the joined field is typed as `unknown`, which
-   * still works but requires a cast to access its properties.
-   *
-   * Joins stay intra-vault by construction — cross-vault
-   * correlation goes through `Noydb.queryAcross`, not
-   * `.join()`.
-   */
-  join(field, opts) {
-    if (!this.joinContext) {
-      throw new Error(
-        `Query.join() requires a join context. Use collection.query() to construct a join-capable Query instead of the Query constructor directly (the direct constructor is only used for tests with plain-object sources).`
-      );
-    }
-    const descriptor = this.joinContext.resolveRef(field);
-    const isDictJoinField = !descriptor && this.joinContext.resolveDictSource?.(field) != null;
-    if (!descriptor && !isDictJoinField) {
-      throw new Error(
-        `Query.join(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Add refs: { ${field}: ref('<target-collection>') } to the collection options, then retry. See the ref() docs for the full list of modes.`
-      );
-    }
-    const leg = descriptor ? {
-      field,
-      as: opts.as,
-      target: descriptor.target,
-      mode: descriptor.mode,
-      strategy: opts.strategy,
-      maxRows: opts.maxRows,
-      //  constraint #1 — always 'all' in. Do not remove.
-      partitionScope: "all"
-    } : {
-      // Dict join leg
-      field,
-      as: opts.as,
-      target: field,
-      // dict name = field name for dictKey
-      mode: "strict",
-      strategy: opts.strategy,
-      maxRows: opts.maxRows,
-      partitionScope: "all",
-      isDictJoin: true
-    };
-    return new _Query(
-      this.source,
-      { ...this.plan, joins: [...this.plan.joins, leg] },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /**
-   * Cartesian-product cross-join against `target` collection. Each result row
-   * carries the original `T` fields plus `result[as]` populated from every
-   * right-side row (or the filtered subset when `on:` is supplied).
-   *
-   * **Order matters:** `.where().crossJoin()` filters BEFORE expanding (cheaper);
-   * `.crossJoin().where('alias.field', ...)` filters AFTER (required when the
-   * where clause references the aliased fields).
-   *
-   * **Cost ceiling:** `CrossJoinTooLargeError` fires before allocation when
-   * `leftRows × rightRows` (or the cumulative lateral count) exceeds the limit.
-   * Default: 50,000 rows. Override per-clause with `{ maxRows: N }`.
-   *
-   * **`on:` shapes:**
-   *   - `on: (left) => TTarget[]`              — subset form (most efficient)
-   *   - `on: (left) => (right) => boolean`     — predicate form
-   *   - `on: { predicate: 'name' }`            — MV-safe, hash-tracked form
-   *     (requires the Query to have been augmented via `_withPredicates`)
-   *
-   * Requires a JoinContext (constructed via `collection.query()`).
-   */
-  crossJoin(target, opts) {
-    if (!this.joinContext) {
-      throw new Error(
-        `Query.crossJoin("${target}"): requires a join context. Use collection.query() to construct a cross-join-capable Query instead of the Query constructor directly.`
-      );
-    }
-    let onFn;
-    let onPredicateName;
-    if (opts.on !== void 0) {
-      if (typeof opts.on === "function") {
-        onFn = opts.on;
-        if (this.predicates) {
-          console.warn(
-            `Query.crossJoin("${target}", { on: callback }): inline on: callback inside a withMaterializedView query() disables queryHash drift detection for this cross-join. Use on: { predicate: '<name>' } to enable it.`
-          );
-        }
-      } else {
-        const predName = opts.on.predicate;
-        if (!this.predicates) {
-          throw new Error(
-            `Query.crossJoin("${target}", { on: { predicate: "${predName}" } }): the { predicate } form requires a predicates map. Use this form inside a withMaterializedView query() callback that declares predicates: { ${predName}: { hash, fn } }.`
-          );
-        }
-        const decl = this.predicates.get(predName);
-        if (!decl) {
-          throw new Error(
-            `Query.crossJoin("${target}"): predicate "${predName}" not registered. Available: ${[...this.predicates.keys()].join(", ") || "(none)"}.`
-          );
-        }
-        const as = opts.as;
-        const predicateFn = decl.fn;
-        onFn = (_left) => (right) => predicateFn({ ..._left, [as]: right });
-        onPredicateName = predName;
-      }
-    }
-    const clause = {
-      type: "crossJoin",
-      target,
-      as: opts.as,
-      ...onFn !== void 0 && { on: onFn },
-      ...onPredicateName !== void 0 && { onPredicateName },
-      ...opts.maxRows !== void 0 && { maxRows: opts.maxRows }
-    };
-    return new _Query(
-      this.source,
-      { ...this.plan, clauses: [...this.plan.clauses, clause] },
-      this.joinContext,
-      this.aggregateStrategy,
-      this.predicates
-    );
-  }
-  /**
-   * Execute the plan and return the matching records. When the plan
-   * carries any join legs, they are applied after `where` / `orderBy`
-   * / `limit` / `offset` narrow the left set. See the `.join()` doc
-   * for the ordering rationale.
-   *
-   * `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.)
-   */
-  toArray(opts) {
-    const base = this.decodeVia(executePlanWithSource(this.source, this.plan, this.joinContext, opts?.locale));
-    if (this.plan.joins.length === 0) return base;
-    if (!this.joinContext) {
-      throw new Error(
-        `Query.toArray(): plan carries ${this.plan.joins.length} join leg(s) but no JoinContext is attached. This usually means the Query was constructed via the raw Query constructor with a plan that had joins pre-populated. Use collection.query().join(...) instead.`
-      );
-    }
-    return applyJoins(base, this.plan.joins, this.joinContext, opts?.locale);
-  }
-  /**
-   * Decode this source's Via-covered fields on read (e.g. money: stored
-   * scaled-int → canonical decimal), so `query().toArray()` agrees with
-   * `get()`/`sum()` on the value. No-op when the source's Via pipeline
-   * declares no result decode.
-   *
-   * The query layer carries no locale context, so money decodes with
-   * `'raw'` — canonical decimal, WITHOUT fabricating locale-formatted
-   * `<field>Formatted` / `<field>Number` virtuals. Producing a
-   * guessed-locale string here would reintroduce a "two read paths
-   * disagree" failure on the virtual field (e.g. it-IT via `get()` vs
-   * en-US here). Consumers who need formatted money read through
-   * `get()`/`list()` with a locale.
-   */
-  decodeVia(records) {
-    const via = this.source.via;
-    if (!via || !via.hasResultDecode) return records;
-    return records.map((r) => via.decodeResults(r));
-  }
-  /** Return the first matching record, or null. Joins are applied. `opts.locale` resolves joined i18n fields. */
-  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 NOT applied** — count() reports the
-   * left-side cardinality, because joins in are projection-only
-   * (they attach an aliased field; they never filter). Running joins
-   * here just to discard the aliases would be wasteful, and in strict
-   * mode it could throw `DanglingReferenceError` for a call whose
-   * intent is purely to count.
-   */
-  count() {
-    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
-      if (!this.joinContext) {
-        throw new Error(
-          `Query.count(): plan contains crossJoin clauses but no JoinContext is attached.`
-        );
-      }
-      return executeClausePipeline(this.source, this.plan.clauses, this.joinContext).length;
-    }
-    const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
-    if (remainingClauses.length === 0) return candidates.length;
-    return filterRecords(candidates, remainingClauses, fnViewDecoder(this.source)).length;
-  }
-  aggregate(specOrBuild) {
-    let spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
-    spec = this.source.via?.wrapReducers(spec) ?? 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, fnViewDecoder(source));
-    };
-    const upstreams = [];
-    if (source.subscribe) {
-      const subscribe = source.subscribe.bind(source);
-      upstreams.push({ subscribe: (cb) => subscribe(cb) });
-    }
-    return this.aggregateStrategy.aggregate(executeRecords, spec, upstreams);
-  }
-  groupBy(...fields) {
-    if (fields.length === 0) {
-      throw new Error(".groupBy() requires at least one field");
-    }
-    const source = this.source;
-    const clauses = this.plan.clauses;
-    const joinCtx = this.joinContext;
-    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
-    const executeRecords = () => {
-      if (hasCrossJoins) {
-        if (!joinCtx) throw new Error("Query.groupBy(): crossJoin requires a join context");
-        return executeClausePipeline(source, clauses, joinCtx);
-      }
-      const { candidates, remainingClauses } = candidateRecords(source, clauses);
-      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
-    };
-    const upstreams = [];
-    if (source.subscribe) {
-      const subscribe = source.subscribe.bind(source);
-      upstreams.push({ subscribe: (cb) => subscribe(cb) });
-    }
-    if (fields.length === 1) {
-      const field = fields[0];
-      const dictLabelResolver = buildDictLabelResolver(this.joinContext, field);
-      return this.aggregateStrategy.groupBy(
-        executeRecords,
-        field,
-        upstreams,
-        dictLabelResolver,
-        this.source.via
-      );
-    }
-    return this.aggregateStrategy.groupByN(
-      executeRecords,
-      fields,
-      upstreams,
-      this.source.via
-    );
-  }
-  /**
-   * Re-run the query whenever the source notifies of changes.
-   * Returns an unsubscribe function. The callback receives the latest result.
-   * Throws if the source does not support subscriptions.
-   *
-   * **For joined queries, prefer `.live()`** — `subscribe()`
-   * only re-fires on LEFT-side changes, so joined data can be
-   * stale if the right side mutates between emissions. `.live()`
-   * merges change streams from every join target.
-   */
-  subscribe(cb) {
-    if (!this.source.subscribe) {
-      throw new Error("Query source does not support subscriptions. Pass a source with a subscribe() method.");
-    }
-    cb(this.toArray());
-    return this.source.subscribe(() => cb(this.toArray()));
-  }
-  /**
-   * Reactive terminal — returns a `LiveQuery<T>` that re-runs the
-   * query and updates its `value` whenever any source feeding it
-   * mutates..
-   *
-   * For non-joined queries, `.live()` is a convenience over the
-   * existing `.subscribe()` callback shape: a hand-rolled reactive
-   * primitive with `value` / `error` fields and a `subscribe(cb)`
-   * notification channel. Frame-agnostic — Vue / React / Solid
-   * adapters wrap it in their own primitive.
-   *
-   * For joined queries, `.live()` additionally subscribes to every
-   * join target's change stream. Mutations on a right-side
-   * collection (insert / update / delete of a client referenced by
-   * an invoice) re-fire the live query and re-evaluate every
-   * dependent left row. Right-side targets are deduped by
-   * collection name, so a chain that joins the same target twice
-   * (e.g. billing client + shipping client → both 'clients') only
-   * subscribes once.
-   *
-   * **Ref-mode behavior on right-side disappearance** — matches the
-   * eager `.toArray()` contract from :
-   *   - `strict`  → re-run throws `DanglingReferenceError`. The
-   *     LiveQuery catches the throw, stores it in `live.error`, and
-   *     notifies listeners (the throw does NOT propagate out of
-   *     the source's change handler — that would tear down the
-   *     emitter). Consumers check `live.error` after each
-   *     notification and render an error state in the UI.
-   *   - `warn`    → joined value flips to `null`; the existing
-   *     warn-channel deduplication keeps repeated re-runs from
-   *     spamming the console.
-   *   - `cascade` → no special handling needed; the cascade-
-   *     delete mechanism propagates the right-side delete into the
-   *     left collection on the next tick, and the live query
-   *     naturally re-fires with the orphaned left rows gone.
-   *
-   * Always call `live.stop()` when finished — it tears down every
-   * upstream subscription. The Vue layer's `onUnmounted` hook
-   * should call `stop()` automatically; raw consumers must do it
-   * themselves.
-   *
-   * **Limitations:**
-   *   - No granular delta updates — the whole query re-runs on
-   *     every change.
-   *   - No microtask batching — bursty changes produce one re-run
-   *     per change.
-   *   - No re-planning under live mutations — the planner picks
-   *     once at subscription time and reuses the same plan.
-   *   - Streaming live joins are deferred.
-   */
-  live() {
-    const upstreams = [];
-    if (this.source.subscribe) {
-      const leftSubscribe = this.source.subscribe.bind(this.source);
-      upstreams.push({
-        subscribe: (cb) => leftSubscribe(cb)
-      });
-    }
-    if (this.plan.joins.length > 0 && this.joinContext) {
-      const subscribed = /* @__PURE__ */ new Set();
-      for (const leg of this.plan.joins) {
-        if (subscribed.has(leg.target)) continue;
-        subscribed.add(leg.target);
-        const rightSource = this.joinContext.resolveSource(leg.target);
-        if (rightSource?.subscribe) {
-          const rightSubscribe = rightSource.subscribe.bind(rightSource);
-          upstreams.push({
-            subscribe: (cb) => rightSubscribe(cb)
-          });
-        }
-      }
-    }
-    if (this.joinContext) {
-      const subscribedCross = /* @__PURE__ */ new Set();
-      for (const clause of this.plan.clauses) {
-        if (clause.type !== "crossJoin") continue;
-        if (subscribedCross.has(clause.target)) continue;
-        subscribedCross.add(clause.target);
-        const rightSource = this.joinContext.resolveSource(clause.target);
-        if (rightSource?.subscribe) {
-          const rightSubscribe = rightSource.subscribe.bind(rightSource);
-          upstreams.push({
-            subscribe: (cb) => rightSubscribe(cb)
-          });
-        }
-      }
-    }
-    return buildLiveQuery(() => this.toArray(), upstreams);
-  }
-  /**
-   * Return the plan as a JSON-friendly object. FilterClause entries are
-   * stripped (their `fn` cannot be serialized) and replaced with
-   * { type: 'filter', fn: '[function]' } so devtools can still see them.
-   */
-  toPlan() {
-    return serializePlan(this.plan);
-  }
-};
-function executePlanWithSource(source, plan, joinContext, locale) {
-  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, fnViewDecoder(source));
-  }
-  if (plan.orderBy.length > 0) {
-    const labelMaps = buildOrderLabelMaps(plan.orderBy, joinContext, locale, source.via);
-    result = sortRecords(result, plan.orderBy, source.via, labelMaps);
-  }
-  if (plan.offset > 0) {
-    result = result.slice(plan.offset);
-  }
-  if (plan.limit !== void 0) {
-    result = result.slice(0, plan.limit);
-  }
-  return result;
-}
-function candidateRecords(source, clauses) {
-  const indexes = source.getIndexes?.();
-  if (!indexes || !source.lookupById || clauses.length === 0) {
-    return { candidates: source.snapshot(), remainingClauses: clauses };
-  }
-  const lookupById = (id) => source.lookupById?.(id);
-  for (let i = 0; i < clauses.length; i++) {
-    const clause = clauses[i];
-    if (clause.type !== "field") continue;
-    if (!indexes.has(clause.field)) continue;
-    if (clause.via) continue;
-    let ids = null;
-    if (clause.op === "==") {
-      ids = indexes.lookupEqual(clause.field, clause.value);
-    } else if (clause.op === "in" && Array.isArray(clause.value)) {
-      ids = indexes.lookupIn(clause.field, clause.value);
-    }
-    if (ids !== null) {
-      const remaining = [];
-      for (let j = 0; j < clauses.length; j++) {
-        if (j !== i) remaining.push(clauses[j]);
-      }
-      return {
-        candidates: materializeIds(ids, lookupById),
-        remainingClauses: remaining
-      };
-    }
-  }
-  return { candidates: source.snapshot(), remainingClauses: clauses };
-}
-function materializeIds(ids, lookupById) {
-  const out = [];
-  for (const id of ids) {
-    const record = lookupById(id);
-    if (record !== void 0) out.push(record);
-  }
-  return out;
-}
-function executePlan(records, plan) {
-  if (plan.clauses.some((c) => c.type === "crossJoin")) {
-    throw new Error(
-      `executePlan(): does not support crossJoin clauses. executePlan is a stateless pure function \u2014 it cannot resolve cross-join right-side collections. Use Query.toArray() (via collection.query()) instead.`
-    );
-  }
-  let result = filterRecords(records, plan.clauses);
-  if (plan.orderBy.length > 0) {
-    result = sortRecords(result, plan.orderBy);
-  }
-  if (plan.offset > 0) {
-    result = result.slice(plan.offset);
-  }
-  if (plan.limit !== void 0) {
-    result = result.slice(0, plan.limit);
-  }
-  return result;
-}
-function fnViewDecoder(source) {
-  const via = source.via;
-  if (!via || !via.hasResultDecode) return void 0;
-  return (r) => via.decodeResults(r);
-}
-function filterRecords(records, clauses, decodeForFns) {
-  if (clauses.length === 0) return [...records];
-  const needsFnView = decodeForFns !== void 0 && hasFnClause(clauses);
-  const out = [];
-  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) out.push(r);
-  }
-  return out;
-}
-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;
-}
-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, via, labelMaps) {
-  return [...records].sort((a, b) => {
-    for (const { field, direction, by } of orderBy) {
-      let av = readField(a, field);
-      let bv = readField(b, field);
-      const labelResolver = by === "label" ? labelMaps?.get(field) : void 0;
-      if (labelResolver) {
-        av = (typeof av === "string" ? labelResolver(av) : void 0) ?? av;
-        bv = (typeof bv === "string" ? labelResolver(bv) : void 0) ?? bv;
-        const cmp2 = compareValues(av, bv);
-        if (cmp2 !== 0) return direction === "asc" ? cmp2 : -cmp2;
-        continue;
-      }
-      const viaCmp = via?.compareForOrder(field, av, bv);
-      const cmp = viaCmp !== void 0 ? viaCmp : compareValues(av, bv);
-      if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
-    }
-    return 0;
-  });
-}
-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,
-    joins: plan.joins
-  };
-}
-function serializeClause(clause) {
-  if (clause.type === "filter") {
-    return { type: "filter", fn: "[function]" };
-  }
-  if (clause.type === "wherePredicate") {
-    return {
-      type: "wherePredicate",
-      name: clause.name,
-      ctx: clause.ctx,
-      predicateHash: clause.predicateHash,
-      ctxHash: clause.ctxHash,
-      fn: "[function]"
-    };
-  }
-  if (clause.type === "group") {
-    return {
-      type: "group",
-      op: clause.op,
-      clauses: clause.clauses.map(serializeClause)
-    };
-  }
-  if (clause.type === "crossJoin") {
-    return {
-      type: "crossJoin",
-      target: clause.target,
-      as: clause.as,
-      on: clause.on ? "[function]" : void 0,
-      onPredicateName: clause.onPredicateName,
-      maxRows: clause.maxRows
-    };
-  }
-  return clause;
-}
-function canonicalCtxHash(ctx) {
-  if (ctx === void 0) return "";
-  const canonical = JSON.stringify(ctx, (_key, value) => {
-    if (value && typeof value === "object" && !Array.isArray(value)) {
-      const sorted = {};
-      for (const k of Object.keys(value).sort()) {
-        sorted[k] = value[k];
-      }
-      return sorted;
-    }
-    return value;
-  });
-  let h = 5381;
-  for (let i = 0; i < canonical.length; i++) {
-    h = (h << 5) + h ^ canonical.charCodeAt(i);
-  }
-  return (h >>> 0).toString(16).padStart(8, "0");
-}
-function buildDictLabelResolver(joinCtx, field) {
-  if (!joinCtx?.resolveDictSource) return void 0;
-  const dictSource = joinCtx.resolveDictSource(field);
-  if (!dictSource) return void 0;
-  const snapshot = dictSource.snapshot();
-  const 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;
-  };
-}
-
-// src/kernel/query/scan-builder.ts
-var DEFAULT_SCAN_PAGE_SIZE = 100;
-var ScanBuilder = class _ScanBuilder {
-  pageProvider;
-  pageSize;
-  clauses;
-  /**
-   * Zero-or-more join legs to apply per record as the stream flows.
-   * Each leg attaches the resolved right-side record (or null) under
-   * its alias. — streaming joins.
-   *
-   * Joins are evaluated AFTER clauses, so a `where()` filtered-out
-   * record never triggers a right-side lookup. This is the same
-   * ordering as `Query.toArray()` (clauses first, joins after) and
-   * keeps the streaming path from doing wasted work.
-   */
-  joins;
-  /**
-   * Join resolution context. Required for `.join()` to translate a
-   * field name into a target collection + ref mode and to resolve
-   * the right-side `JoinableSource`. Optional because tests
-   * construct ScanBuilder directly with synthetic page providers
-   * that don't know about ref() — calling `.join()` without a
-   * context throws with an actionable error.
-   */
-  joinContext;
-  /**
-   * The backing collection's compiled Via pipeline (money now; more Via
-   * features later). When it declares a result decode, yielded records
-   * are decoded (e.g. money: stored scaled-int → canonical decimal) so
-   * `scan()` agrees with `get()`/`list()`/`query().toArray()`. Decoded
-   * with `'raw'` (canonical decimal, no locale-formatted virtuals) since
-   * the scan stream carries no locale context, mirroring `Query.toArray()`.
-   */
-  via;
-  constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext, via) {
-    this.pageProvider = pageProvider;
-    this.pageSize = pageSize;
-    this.clauses = clauses;
-    this.joins = joins;
-    this.joinContext = joinContext;
-    this.via = via;
-  }
-  /**
-   * Decode this scan's Via-covered fields on a record (e.g. money: stored
-   * scaled-int → canonical decimal). No-op when the Via pipeline declares
-   * no result decode. See {@link via}.
-   */
-  decodeVia(record) {
-    if (!this.via || !this.via.hasResultDecode) return record;
-    return this.via.decodeResults(record);
-  }
-  /**
-   * Add a field comparison. Runs per record as the scan stream
-   * flows through, so non-matching records are dropped before they
-   * reach `.aggregate()` or the iteration consumer. Multiple
-   * `.where()` calls are AND-combined — same semantics as
-   * `Query.where()`.
-   *
-   * Clauses cannot use the secondary-index fast path here because
-   * the scan sources records from the adapter's paginator, not from
-   * the in-memory cache where indexes live. Index-accelerated scans
-   * are a future optimization — the current implementation
-   * evaluates clauses per record in O(1) per clause.
-   *
-   * Consults the Via pipeline's posture before building a clause (#629
-   * Task 8): a field whose posture is `queryable: 'none'` throws
-   * `FieldNotQueryableError` here, at the call site — same gate as
-   * `Query.where()`.
-   */
-  where(field, op, value) {
-    const via = this.via;
-    if (via?.postureFor(field)?.queryable === "none") throw new FieldNotQueryableError(field);
-    const viaClause = via?.buildClause(field, op, value);
-    const clause = viaClause ? {
-      type: "field",
-      field,
-      op,
-      value,
-      via: {
-        brand: viaClause.brand,
-        payload: viaClause.payload,
-        evaluate: (actual, evalOp) => via.evaluateClause(viaClause, actual, evalOp)
-      }
-    } : { type: "field", field, op, value };
-    return new _ScanBuilder(
-      this.pageProvider,
-      this.pageSize,
-      [...this.clauses, clause],
-      this.joins,
-      this.joinContext,
-      this.via
-    );
-  }
-  /**
-   * Escape hatch: add an arbitrary predicate function. Same
-   * non-serializable caveat as `Query.filter()` — filter clauses
-   * don't round-trip through `toPlan()`. Prefer `.where()` when
-   * possible.
-   */
-  filter(fn) {
-    const clause = {
-      type: "filter",
-      fn
-    };
-    return new _ScanBuilder(
-      this.pageProvider,
-      this.pageSize,
-      [...this.clauses, clause],
-      this.joins,
-      this.joinContext,
-      this.via
-    );
-  }
-  /**
-   * Resolve a `ref()`-declared foreign key per record as the scan
-   * stream flows, attaching the right-side record (or null) under
-   * `opts.as`. — streaming joins over `scan()`.
-   *
-   * ```ts
-   * for await (const inv of invoices.scan().join('clientId', { as: 'client' })) {
-   *   await processInvoice(inv) // inv.client is attached
-   * }
-   *
-   * // Or terminate with .aggregate() for streaming joined aggregation
-   * const { total } = await invoices.scan()
-   *   .where('status', '==', 'open')
-   *   .join('clientId', { as: 'client' })
-   *   .aggregate({ total: sum('amount') })
-   * ```
-   *
-   * **The key difference from eager `.join()`:** the LEFT
-   * side streams page-by-page from the adapter and is never
-   * materialized. Memory ceiling on the left is O(pageSize), not
-   * O(rowCount). This is what makes streaming joins suitable for
-   * collections that exceed the eager join's 50_000-row ceiling.
-   *
-   * **Right-side strategy** is auto-selected per leg:
-   *   - **Indexed** — right source exposes `lookupById`, so each
-   *     left row costs O(1). This is the common path for
-   *     Collection right sides, which back `lookupById` with a Map
-   *     lookup over the in-memory cache. The right collection must
-   *     be in eager mode (the same constraint as eager join's
-   *     `querySourceForJoin` from ).
-   *   - **Hash** — right source has only `snapshot()`. Build a
-   *     `Map<id, record>` once at iteration start, probe per left
-   *     row. Same correctness, same per-row cost as the indexed
-   *     path; the difference is the upfront cost of materializing
-   *     the right side once.
-   *
-   * Both strategies hold the right side in memory for the duration
-   * of the iteration. The "streaming" property applies to the LEFT
-   * side only — true left-and-right streaming joins (where neither
-   * side fits in memory) require a sort-merge join planner that's
-   * out of scope for.
-   *
-   * **Ref-mode semantics** match eager `.join()` exactly:
-   *   - `strict`  → throws `DanglingReferenceError` mid-stream
-   *     when a left record points at a non-existent right id.
-   *     The throw aborts the async iterator — consumers should
-   *     wrap the `for await` in try/catch if they want to recover.
-   *   - `warn`    → attaches `null` and emits a one-shot warning
-   *     per unique dangling pair (deduped via the same warn
-   *     channel as eager join).
-   *   - `cascade` → attaches `null` silently. A delete-time mode;
-   *     dangling refs at read time are mid-flight or pre-existing
-   *     orphans, not a DSL error.
-   *
-   * Left records with null/undefined FK values attach `null`
-   * regardless of mode — same "no reference at all" policy as
-   * eager join and write-time `enforceRefsOnPut`.
-   *
-   * **Multi-FK chaining** is supported via repeated `.join()`
-   * calls: each leg resolves an independent ref. Each leg
-   * independently picks its right-side strategy and applies its
-   * own ref mode.
-   *
-   * **Joins are NOT applied** to a `.aggregate()` terminal that
-   * doesn't reference joined fields — wait, that's not quite
-   * right. The streaming path actually DOES apply joins before
-   * `.aggregate()` because the join attaches a field that the
-   * spec might reference. Unlike `Query.aggregate()` (which skips
-   * joins entirely as a projection-only short-circuit), the
-   * streaming aggregation can't know whether the spec touches a
-   * joined field, so it always applies joins. Consumers who want
-   * unjoined streaming aggregation should leave `.join()` off the
-   * chain — the chain is composable for a reason.
-   *
-   *  constraint #1 — every JoinLeg carries `partitionScope:
-   * 'all'` plumbed through but never read by. Same seam as
-   * eager join.
-   */
-  join(field, opts) {
-    if (!this.joinContext) {
-      throw new Error(
-        `ScanBuilder.join() requires a join context. Use collection.scan() to construct a join-capable scan instead of the ScanBuilder constructor directly (the direct constructor is only used for tests with synthetic page providers).`
-      );
-    }
-    const descriptor = this.joinContext.resolveRef(field);
-    if (!descriptor) {
-      throw new Error(
-        `ScanBuilder.join(): no ref() declared for field "${field}" on collection "${this.joinContext.leftCollection}". Add refs: { ${field}: ref('<target-collection>') } to the collection options, then retry.`
-      );
-    }
-    const leg = {
-      field,
-      as: opts.as,
-      target: descriptor.target,
-      mode: descriptor.mode,
-      strategy: void 0,
-      maxRows: void 0,
-      //  constraint #1 — always 'all' in, never read by
-      // the streaming executor. partition-aware scan joins
-      // will populate this from where() predicates without
-      // changing the planner shape.
-      partitionScope: "all"
-    };
-    return new _ScanBuilder(
-      this.pageProvider,
-      this.pageSize,
-      this.clauses,
-      [...this.joins, leg],
-      this.joinContext,
-      this.via
-    );
-  }
-  /**
-   * Iterate the scan as an async iterable. Walks the page
-   * provider's cursors forward until exhaustion, applying every
-   * clause per record — only matching records are yielded.
-   *
-   * Backward-compatible with the previous async-generator `scan()`
-   * return type for `for await … of` consumers.
-   */
-  async *[Symbol.asyncIterator]() {
-    const joinResolvers = this.joins.length === 0 ? null : this.buildJoinResolvers();
-    let page = await this.pageProvider.listPage({ limit: this.pageSize });
-    while (true) {
-      for (const record of page.items) {
-        if (!this.recordMatches(record)) continue;
-        const decoded = this.decodeVia(record);
-        if (joinResolvers === null) {
-          yield decoded;
-        } else {
-          let attached = decoded;
-          for (const resolver of joinResolvers) {
-            attached = this.applyOneJoinStreaming(attached, resolver);
-          }
-          yield attached;
-        }
-      }
-      if (page.nextCursor === null) return;
-      page = await this.pageProvider.listPage({
-        cursor: page.nextCursor,
-        limit: this.pageSize
-      });
-    }
-  }
-  /**
-   * Per-leg right-side resolution state. Built once at iteration
-   * start and reused for every left record. Two strategies:
-   *
-   *   - `lookupById`: present when the right source exposes the
-   *     hook directly (typical Collection right side). Per-row
-   *     cost is O(1).
-   *   - `hashByPrimaryKey`: built from `snapshot()` when no
-   *     lookupById. Per-row cost is O(1) after the upfront O(N)
-   *     materialization. Same as eager join's hash strategy.
-   *
-   * `warnedKeys` is the per-leg dedup set for ref-mode 'warn'. We
-   * key on `field→target:refId` so the same dangling pair only
-   * warns once per iteration. The dedup is per-iteration, not
-   * per-process — a long-running scan that re-iterates would warn
-   * again, which is the desired behavior (the data may have
-   * changed between iterations).
-   */
-  buildJoinResolvers() {
-    if (!this.joinContext) {
-      throw new Error(
-        `ScanBuilder iterator: ${this.joins.length} join leg(s) present but no JoinContext attached. Use collection.scan() to construct a join-capable scan.`
-      );
-    }
-    const resolvers = [];
-    for (const leg of this.joins) {
-      const source = this.joinContext.resolveSource(leg.target);
-      if (!source) {
-        throw new Error(
-          `ScanBuilder.join() cannot resolve target collection "${leg.target}" (referenced from field "${leg.field}" on "${this.joinContext.leftCollection}"). Make sure the target collection has been opened via vault.collection() at least once before iterating the scan.`
-        );
-      }
-      let lookupById = null;
-      let hashByPrimaryKey = null;
-      if (source.lookupById) {
-        const fn = source.lookupById.bind(source);
-        lookupById = (id) => fn(id);
-      } else {
-        const map = /* @__PURE__ */ new Map();
-        for (const record of source.snapshot()) {
-          const rawId = readPath(record, "id");
-          const key = coerceRefKey2(rawId);
-          if (key !== null) map.set(key, record);
-        }
-        hashByPrimaryKey = map;
-      }
-      resolvers.push({
-        leg,
-        source,
-        lookupById,
-        hashByPrimaryKey,
-        warnedKeys: /* @__PURE__ */ new Set()
-      });
-    }
-    return resolvers;
-  }
-  /**
-   * Resolve a single join leg for one left record and return the
-   * left record with the joined field attached under
-   * `leg.as`. Pure function over `(left, resolver)`; never
-   * mutates the input.
-   *
-   * Ref-mode dispatch matches eager `applyJoins` from :
-   *   - null/undefined FK → attach null silently (always allowed)
-   *   - dangling FK + strict → throw `DanglingReferenceError`
-   *   - dangling FK + warn → attach null, warn-once per pair
-   *   - dangling FK + cascade → attach null silently
-   */
-  applyOneJoinStreaming(left, resolver) {
-    if (left === null || typeof left !== "object") {
-      return left;
-    }
-    const { leg } = resolver;
-    const rawId = readPath(left, leg.field);
-    const refKey = coerceRefKey2(rawId);
-    let right = void 0;
-    if (refKey !== null) {
-      if (resolver.lookupById !== null) {
-        right = resolver.lookupById(refKey);
-      } else if (resolver.hashByPrimaryKey !== null) {
-        right = resolver.hashByPrimaryKey.get(refKey);
-      }
-    }
-    const merged = {
-      ...left
-    };
-    if (right === void 0) {
-      if (refKey !== null && leg.mode === "strict") {
-        throw new DanglingReferenceError({
-          field: leg.field,
-          target: leg.target,
-          refId: refKey,
-          message: `ScanBuilder.join() strict dangling: record references "${leg.target}:${refKey}" via field "${leg.field}", but no such record exists. Use ref() mode 'warn' or 'cascade' if dangling refs are acceptable, or run vault.checkIntegrity() to find and fix the orphans.`
-        });
-      }
-      if (refKey !== null && leg.mode === "warn") {
-        const dedupKey = `${leg.field}\u2192${leg.target}:${refKey}`;
-        if (!resolver.warnedKeys.has(dedupKey)) {
-          resolver.warnedKeys.add(dedupKey);
-          console.warn(
-            `[noy-db] ScanBuilder.join() encountered dangling ref in 'warn' mode: field "${leg.field}" \u2192 "${leg.target}:${refKey}" not found. Attaching null.`
-          );
-        }
-      }
-      merged[leg.as] = null;
-    } else {
-      merged[leg.as] = right;
-    }
-    return merged;
-  }
-  async aggregate(specOrBuild) {
-    const spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
-    this.via?.refuseUnqueryableReducers(spec);
-    const keys = Object.keys(spec);
-    const state = {};
-    for (const key of keys) {
-      state[key] = spec[key].init();
-    }
-    for await (const record of this) {
-      for (const key of keys) {
-        state[key] = spec[key].step(state[key], record);
-      }
-    }
-    const result = {};
-    for (const key of keys) {
-      result[key] = spec[key].finalize(state[key]);
-    }
-    return result;
-  }
-  /**
-   * Evaluate the clause list against a single record. Linear in
-   * the clause count; short-circuits on first false. Clauses on a
-   * scan are always re-evaluated per record — no index-accelerated
-   * path, because the stream sources records from the adapter
-   * paginator, not from the in-memory cache where indexes live.
-   */
-  recordMatches(record) {
-    if (this.clauses.length === 0) return true;
-    const fnView = this.via?.hasResultDecode && hasFnClause(this.clauses) ? this.decodeVia(record) : void 0;
-    for (const clause of this.clauses) {
-      if (!evaluateClause(record, clause, fnView)) return false;
-    }
-    return true;
-  }
-};
-function coerceRefKey2(value) {
-  if (value === null || value === void 0) return null;
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "bigint") return String(value);
-  return null;
-}
-
-export {
-  DEFAULT_JOIN_MAX_ROWS,
-  applyJoins,
-  resetJoinWarnings,
-  buildLiveQuery,
-  NO_AGGREGATE,
-  DEFAULT_CROSS_JOIN_MAX_ROWS,
-  Query,
-  executePlan,
-  ScanBuilder
-};
-//# sourceMappingURL=chunk-7HAPHVRJ.js.map