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

package/dist/chunk-A5BDDEXK.js

@@ -0,0 +1,1537 @@
+import {
+  applyJoins
+} from "./chunk-RA5VTXXG.js";
+import {
+  reducerBuilder
+} from "./chunk-TAGR72IR.js";
+import {
+  evaluateClause,
+  hasFnClause,
+  readPath
+} from "./chunk-IGJCYUT5.js";
+import {
+  CrossJoinSourceUnknownError,
+  CrossJoinTooLargeError,
+  DanglingReferenceError,
+  FieldNotQueryableError
+} from "./chunk-W2OG6JOL.js";
+
+// 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),
+        indexValue: via.indexProbe(viaClause, op)
+      }
+    } : { 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 && clause.via.indexValue === void 0) continue;
+    const probeValue = clause.via ? clause.via.indexValue : clause.value;
+    let ids = null;
+    if (clause.op === "==") {
+      ids = indexes.lookupEqual(clause.field, probeValue);
+    } else if (clause.op === "in" && Array.isArray(probeValue)) {
+      ids = indexes.lookupIn(clause.field, probeValue);
+    }
+    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 = coerceRefKey(rawId);
+          if (key !== null) map.set(key, record);
+        }
+        hashByPrimaryKey = map;
+      }
+      resolvers.push({
+        leg,
+        source,
+        lookupById,
+        hashByPrimaryKey,
+        warnedKeys: /* @__PURE__ */ new Set()
+      });
+    }
+    return resolvers;
+  }
+  /**
+   * Resolve a single join leg for one left record and return the
+   * left record with the joined field attached under
+   * `leg.as`. Pure function over `(left, resolver)`; never
+   * mutates the input.
+   *
+   * Ref-mode dispatch matches eager `applyJoins` from :
+   *   - null/undefined FK → attach null silently (always allowed)
+   *   - dangling FK + strict → throw `DanglingReferenceError`
+   *   - dangling FK + warn → attach null, warn-once per pair
+   *   - dangling FK + cascade → attach null silently
+   */
+  applyOneJoinStreaming(left, resolver) {
+    if (left === null || typeof left !== "object") {
+      return left;
+    }
+    const { leg } = resolver;
+    const rawId = readPath(left, leg.field);
+    const refKey = coerceRefKey(rawId);
+    let right = void 0;
+    if (refKey !== null) {
+      if (resolver.lookupById !== null) {
+        right = resolver.lookupById(refKey);
+      } else if (resolver.hashByPrimaryKey !== null) {
+        right = resolver.hashByPrimaryKey.get(refKey);
+      }
+    }
+    const merged = {
+      ...left
+    };
+    if (right === void 0) {
+      if (refKey !== null && leg.mode === "strict") {
+        throw new DanglingReferenceError({
+          field: leg.field,
+          target: leg.target,
+          refId: refKey,
+          message: `ScanBuilder.join() strict dangling: record references "${leg.target}:${refKey}" via field "${leg.field}", but no such record exists. Use ref() mode 'warn' or 'cascade' if dangling refs are acceptable, or run vault.checkIntegrity() to find and fix the orphans.`
+        });
+      }
+      if (refKey !== null && leg.mode === "warn") {
+        const dedupKey = `${leg.field}\u2192${leg.target}:${refKey}`;
+        if (!resolver.warnedKeys.has(dedupKey)) {
+          resolver.warnedKeys.add(dedupKey);
+          console.warn(
+            `[noy-db] ScanBuilder.join() encountered dangling ref in 'warn' mode: field "${leg.field}" \u2192 "${leg.target}:${refKey}" not found. Attaching null.`
+          );
+        }
+      }
+      merged[leg.as] = null;
+    } else {
+      merged[leg.as] = right;
+    }
+    return merged;
+  }
+  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 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;
+}
+
+export {
+  buildLiveQuery,
+  NO_AGGREGATE,
+  DEFAULT_CROSS_JOIN_MAX_ROWS,
+  Query,
+  executePlan,
+  ScanBuilder
+};
+//# sourceMappingURL=chunk-A5BDDEXK.js.map