@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/{chunk-J4KLMEUL.js → chunk-NV4IHBZS.js}

@@ -1,11 +1,25 @@
 import {
+  wrapMoneyReducers
+} from "./chunk-JYNH4FIM.js";
+import {
+  MoneyPrecisionError,
   evaluateClause,
+  formatScaledInt,
+  hasFnClause,
+  moneyFieldClause,
+  parseToScaledInt,
   readPath
-} from "./chunk-MRIBLZL3.js";
+} from "./chunk-U2XSUCDF.js";
+import {
+  applyI18nLocale
+} from "./chunk-TNH5SLCD.js";
 import {
+  CrossJoinSourceUnknownError,
+  CrossJoinTooLargeError,
   DanglingReferenceError,
-  JoinTooLargeError
-} from "./chunk-W3XXT26A.js";
+  JoinTooLargeError,
+  ValidationError
+} from "./chunk-OTWT6BAJ.js";
 
 // src/query/join.ts
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
@@ -35,15 +49,15 @@ function warnCeilingApproaching(target, side, rows, maxRows) {
     `[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) {
+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);
+    result = applyOneJoin(result, leg, context, locale);
   }
   return result;
 }
-function applyOneJoin(leftRows, leg, context) {
+function applyOneJoin(leftRows, leg, context, locale) {
   if (leg.isDictJoin) {
     const dictSource = context.resolveDictSource?.(leg.field);
     if (!dictSource) {
@@ -98,24 +112,27 @@ function applyOneJoin(leftRows, leg, context) {
   if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {
     warnCeilingApproaching(leg.target, "right", rightSnapshot.length, maxRows);
   }
+  const effLocale = locale ?? context.defaultLocale;
+  const i18nResolve = effLocale !== void 0 && source.i18nFields !== void 0 ? (right) => right !== null && typeof right === "object" ? applyI18nLocale(right, source.i18nFields, effLocale, void 0, "join") : 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);
+    return nestedLoopJoin(leftRows, leg, lookup, i18nResolve);
   }
-  return hashJoin(leftRows, leg, rightSnapshot);
+  return hashJoin(leftRows, leg, rightSnapshot, i18nResolve);
 }
-function nestedLoopJoin(leftRows, leg, lookupById) {
+function nestedLoopJoin(leftRows, leg, lookupById, i18nResolve) {
   const out = [];
   for (const left of leftRows) {
     const rawId = readPath(left, leg.field);
     const key = coerceRefKey(rawId);
-    const right = key === null ? void 0 : lookupById(key);
+    let right = key === null ? void 0 : lookupById(key);
+    if (i18nResolve && right !== void 0) right = i18nResolve(right);
     out.push(attachJoin(left, leg, right, rawId));
   }
   return out;
 }
-function hashJoin(leftRows, leg, rightSnapshot) {
+function hashJoin(leftRows, leg, rightSnapshot, i18nResolve) {
   const rightMap = /* @__PURE__ */ new Map();
   for (const record of rightSnapshot) {
     const rawId = readPath(record, "id");
@@ -128,7 +145,8 @@ function hashJoin(leftRows, leg, rightSnapshot) {
   for (const left of leftRows) {
     const rawId = readPath(left, leg.field);
     const key = coerceRefKey(rawId);
-    const right = key === null ? void 0 : rightMap.get(key);
+    let right = key === null ? void 0 : rightMap.get(key);
+    if (i18nResolve && right !== void 0) right = i18nResolve(right);
     out.push(attachJoin(left, leg, right, rawId));
   }
   return out;
@@ -252,6 +270,277 @@ var NO_AGGREGATE = {
   }
 };
 
+// src/money/paths.ts
+var SEGMENT_RE = /^(\*|[^.[\]*]+)(\[\])?$/;
+var parseCache = /* @__PURE__ */ new Map();
+function parseMoneyPath(path) {
+  const cached = parseCache.get(path);
+  if (cached) return cached;
+  if (typeof path !== "string" || path.length === 0) {
+    throw new ValidationError("moneyFields: path must be a non-empty string");
+  }
+  const segments = [];
+  for (const part of path.split(".")) {
+    const m = SEGMENT_RE.exec(part);
+    if (!m) {
+      throw new ValidationError(
+        `moneyFields: invalid path "${path}" \u2014 segment "${part}" must be a key, "key[]", "*", or "*[]"`
+      );
+    }
+    const array = m[2] === "[]";
+    segments.push(
+      m[1] === "*" ? { kind: "wildcard", array } : { kind: "key", key: m[1], array }
+    );
+  }
+  parseCache.set(path, segments);
+  return segments;
+}
+function isSimpleMoneyPath(path) {
+  return !path.includes(".") && !path.includes("[") && !path.includes("*");
+}
+function validateMoneyFieldPaths(moneyFields) {
+  for (const path of Object.keys(moneyFields)) parseMoneyPath(path);
+}
+function transformAtMoneyPath(node, path, segments, index, visit, lenient) {
+  if (node === null || node === void 0) return node;
+  const seg = segments[index];
+  const last = index === segments.length - 1;
+  if (seg.kind === "key") {
+    if (typeof node !== "object" || Array.isArray(node)) {
+      if (lenient) return node;
+      throw new ValidationError(
+        `moneyFields: path "${path}" expected an object at segment "${seg.key}", got ${Array.isArray(node) ? "an array" : typeof node}`
+      );
+    }
+    const obj2 = node;
+    if (!(seg.key in obj2) || obj2[seg.key] === null || obj2[seg.key] === void 0) return node;
+    if (seg.array) {
+      const arr = obj2[seg.key];
+      if (!Array.isArray(arr)) {
+        if (lenient) return node;
+        throw new ValidationError(
+          `moneyFields: path "${path}" declares "${seg.key}[]" but the value is not an array`
+        );
+      }
+      const cloned = [...arr];
+      if (last) {
+        for (let i = 0; i < cloned.length; i++) visit(cloned, i);
+      } else {
+        for (let i = 0; i < cloned.length; i++) {
+          cloned[i] = transformAtMoneyPath(cloned[i], path, segments, index + 1, visit, lenient);
+        }
+      }
+      return { ...obj2, [seg.key]: cloned };
+    }
+    const clone2 = { ...obj2 };
+    if (last) {
+      visit(clone2, seg.key);
+    } else {
+      clone2[seg.key] = transformAtMoneyPath(clone2[seg.key], path, segments, index + 1, visit, lenient);
+    }
+    return clone2;
+  }
+  if (seg.array) {
+    if (!Array.isArray(node)) {
+      if (lenient) return node;
+      throw new ValidationError(`moneyFields: path "${path}" declares "*[]" but the value is not an array`);
+    }
+    const cloned = [...node];
+    if (last) {
+      for (let i = 0; i < cloned.length; i++) visit(cloned, i);
+    } else {
+      for (let i = 0; i < cloned.length; i++) {
+        cloned[i] = transformAtMoneyPath(cloned[i], path, segments, index + 1, visit, lenient);
+      }
+    }
+    return cloned;
+  }
+  if (typeof node !== "object" || Array.isArray(node)) {
+    if (lenient) return node;
+    throw new ValidationError(
+      `moneyFields: path "${path}" applies "*" to a non-object (${Array.isArray(node) ? 'array \u2014 use "*[]"' : typeof node})`
+    );
+  }
+  const obj = node;
+  const clone = { ...obj };
+  for (const key of Object.keys(obj)) {
+    const v = clone[key];
+    if (v === null || v === void 0) continue;
+    if (last) visit(clone, key);
+    else clone[key] = transformAtMoneyPath(v, path, segments, index + 1, visit, lenient);
+  }
+  return clone;
+}
+
+// src/money/normalize.ts
+function isMoneyValueObject(v) {
+  return typeof v === "object" && v !== null && "currency" in v;
+}
+function quantizeAmount(field, input, scale, rounding) {
+  const r = parseToScaledInt(input, scale, rounding);
+  if (!r.ok) {
+    if (r.reason === "precision") throw new MoneyPrecisionError(field, input, scale);
+    throw new TypeError(`money: field "${field}" value ${JSON.stringify(input)} is not a finite decimal`);
+  }
+  return r.value.toString();
+}
+function canonicalizeStoredMoney(record, moneyFields) {
+  if (record === null || record === void 0) return record;
+  if (!moneyFields || Object.keys(moneyFields).length === 0) return record;
+  return decodeMoneyFields(record, moneyFields, "raw");
+}
+function canonicalizeIncomingMoney(record, moneyFields) {
+  if (!moneyFields || Object.keys(moneyFields).length === 0) return record;
+  try {
+    return decodeMoneyFields(
+      quantizeMoneyFields(record, moneyFields),
+      moneyFields,
+      "raw"
+    );
+  } catch {
+    return record;
+  }
+}
+function quantizeValue(field, raw, desc) {
+  if (desc.mode === "fixed") {
+    const currency2 = desc.fixedCurrency;
+    return quantizeAmount(field, raw, desc.scaleFor(currency2), desc.rounding);
+  }
+  let amount;
+  let currency;
+  if (isMoneyValueObject(raw)) {
+    currency = String(raw.currency);
+    amount = raw.amount;
+  } else {
+    const sole = desc.soleCurrency();
+    if (sole === void 0) {
+      throw new TypeError(
+        `money: field "${field}" is multi-currency \u2014 write { amount, currency }, not a bare amount`
+      );
+    }
+    currency = sole;
+    amount = raw;
+  }
+  const scale = desc.scaleFor(currency);
+  return { amount: quantizeAmount(field, amount, scale, desc.rounding), currency };
+}
+function quantizeMoneyFields(record, moneyFields) {
+  let out = { ...record };
+  for (const [path, desc] of Object.entries(moneyFields)) {
+    if (isSimpleMoneyPath(path)) {
+      const raw = out[path];
+      if (raw === null || raw === void 0) continue;
+      out[path] = quantizeValue(path, raw, desc);
+      continue;
+    }
+    out = transformAtMoneyPath(
+      out,
+      path,
+      parseMoneyPath(path),
+      0,
+      (container, key) => {
+        const raw = container[key];
+        if (raw === null || raw === void 0) return;
+        container[key] = quantizeValue(path, raw, desc);
+      },
+      /* lenient */
+      false
+    );
+  }
+  return out;
+}
+function formatCurrency(decimal, currency, scale, locale) {
+  const fmt = new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency,
+    minimumFractionDigits: scale,
+    maximumFractionDigits: scale
+  });
+  return fmt.format(decimal);
+}
+function moneyScaledValue(stored, desc) {
+  let raw;
+  if (desc.mode === "fixed") {
+    raw = stored;
+  } else {
+    if (!isMoneyValueObject(stored)) return null;
+    raw = stored.amount;
+  }
+  if (typeof raw !== "string" && typeof raw !== "number") return null;
+  try {
+    return BigInt(String(raw));
+  } catch {
+    return null;
+  }
+}
+function decodeValue(stored, desc) {
+  let currency;
+  let scaledIntString;
+  if (desc.mode === "fixed") {
+    if (typeof stored !== "string" && typeof stored !== "number") return null;
+    currency = desc.fixedCurrency;
+    scaledIntString = String(stored);
+  } else {
+    if (!isMoneyValueObject(stored)) return null;
+    const amount = stored.amount;
+    if (typeof stored.currency !== "string" || typeof amount !== "string" && typeof amount !== "number") return null;
+    currency = stored.currency;
+    scaledIntString = String(amount);
+  }
+  const scale = desc.scaleFor(currency);
+  let decimal;
+  try {
+    decimal = formatScaledInt(BigInt(scaledIntString), scale);
+  } catch {
+    return null;
+  }
+  return {
+    decoded: desc.mode === "fixed" ? decimal : { amount: decimal, currency },
+    decimal,
+    currency,
+    scale
+  };
+}
+function decodeMoneyFields(record, moneyFields, locale) {
+  let out = { ...record };
+  const format = locale !== "raw";
+  const fmtLocale = typeof locale === "string" && locale !== "raw" ? locale : "en-US";
+  for (const [path, desc] of Object.entries(moneyFields)) {
+    if (isSimpleMoneyPath(path)) {
+      const stored = out[path];
+      if (stored === null || stored === void 0) continue;
+      const r = decodeValue(stored, desc);
+      if (r === null) continue;
+      out[path] = r.decoded;
+      if (format) {
+        out[`${path}Formatted`] = formatCurrency(r.decimal, r.currency, r.scale, fmtLocale);
+        out[`${path}Number`] = Number(r.decimal);
+      }
+      continue;
+    }
+    out = transformAtMoneyPath(
+      out,
+      path,
+      parseMoneyPath(path),
+      0,
+      (container, key) => {
+        const stored = container[key];
+        if (stored === null || stored === void 0) return;
+        const r = decodeValue(stored, desc);
+        if (r === null) return;
+        container[key] = r.decoded;
+        if (format && typeof key === "string" && !Array.isArray(container)) {
+          container[`${key}Formatted`] = formatCurrency(r.decimal, r.currency, r.scale, fmtLocale);
+          container[`${key}Number`] = Number(r.decimal);
+        }
+      },
+      /* lenient */
+      true
+    );
+  }
+  return out;
+}
+
 // src/query/builder.ts
 var EMPTY_PLAN = {
   clauses: [],
@@ -260,6 +549,7 @@ var EMPTY_PLAN = {
   offset: 0,
   joins: []
 };
+var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
 var Query = class _Query {
   source;
   plan;
@@ -292,7 +582,7 @@ var Query = class _Query {
   /**
    * @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 (#153).
+   * `.wherePredicate(name, ctx?)` for the MV's query callback.
    * Consumers don't call this directly.
    */
   _withPredicates(predicates) {
@@ -305,7 +595,7 @@ var Query = class _Query {
     );
   }
   /**
-   * Filter by a registered deterministic predicate (#153). Requires
+   * 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()`).
@@ -343,9 +633,18 @@ var Query = class _Query {
       this.predicates
     );
   }
-  /** Add a field comparison. Multiple where() calls are AND-combined. */
+  /**
+   * Add a field comparison. Multiple where() calls are AND-combined.
+   *
+   * A declared money field compares in MAJOR units (#336): 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.
+   */
   where(field, op, value) {
-    const clause = { type: "field", field, op, value };
+    const desc = this.source.moneyFields?.[field];
+    const clause = desc ? moneyFieldClause(field, op, value, desc) : { type: "field", field, op, value };
     return new _Query(
       this.source,
       { ...this.plan, clauses: [...this.plan.clauses, clause] },
@@ -411,11 +710,16 @@ var Query = class _Query {
       this.predicates
     );
   }
-  /** Sort by a field. Subsequent calls are tie-breakers. */
-  orderBy(field, direction = "asc") {
+  /**
+   * 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 (#285).
+   */
+  orderBy(field, direction = "asc", opts) {
+    const entry = opts?.by === "label" ? { field, direction, by: "label" } : { field, direction };
     return new _Query(
       this.source,
-      { ...this.plan, orderBy: [...this.plan.orderBy, { field, direction }] },
+      { ...this.plan, orderBy: [...this.plan.orderBy, entry] },
       this.joinContext,
       this.aggregateStrategy,
       this.predicates
@@ -541,25 +845,119 @@ var Query = class _Query {
       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` (#285 §3) 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() {
-    const base = executePlanWithSource(this.source, this.plan);
+  toArray(opts) {
+    const base = this.decodeMoney(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);
+    return applyJoins(base, this.plan.joins, this.joinContext, opts?.locale);
   }
-  /** Return the first matching record, or null. Joins are applied. */
-  first() {
-    const arr = this.limit(1).toArray();
+  /**
+   * Decode this source's money fields on read (stored scaled-int → canonical
+   * decimal), so `query().toArray()` agrees with `get()`/`sum()` on the value.
+   * No-op when the source declares no money fields.
+   *
+   * The query layer carries no locale context, so we decode with `'raw'` —
+   * canonical decimal, WITHOUT fabricating locale-formatted `<field>Formatted`
+   * / `<field>Number` virtuals. Producing a guessed-locale string here would
+   * just reintroduce #322's "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.
+   */
+  decodeMoney(records) {
+    const moneyFields = this.source.moneyFields;
+    if (!moneyFields || Object.keys(moneyFields).length === 0) return records;
+    return records.map((r) => decodeMoneyFields(r, moneyFields, "raw"));
+  }
+  /** Return the first matching record, or null. Joins are applied. `opts.locale` resolves joined i18n fields (#285 §3). */
+  first(opts) {
+    const arr = this.limit(1).toArray(opts);
     return arr[0] ?? null;
   }
   /**
@@ -572,9 +970,17 @@ var Query = class _Query {
    * intent is purely to count.
    */
   count() {
+    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+      if (!this.joinContext) {
+        throw new Error(
+          `Query.count(): plan contains crossJoin clauses but no JoinContext is attached.`
+        );
+      }
+      return executeClausePipeline(this.source, this.plan.clauses, this.joinContext).length;
+    }
     const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
     if (remainingClauses.length === 0) return candidates.length;
-    return filterRecords(candidates, remainingClauses).length;
+    return filterRecords(candidates, remainingClauses, fnViewDecoder(this.source)).length;
   }
   /**
    * Reduce the matching records through a named set of reducers.
@@ -617,11 +1023,21 @@ var Query = class _Query {
    * partition boundaries without an API break.
    */
   aggregate(spec) {
+    const moneyFields = this.source.moneyFields;
+    if (moneyFields) {
+      spec = wrapMoneyReducers(spec, moneyFields);
+    }
     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);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
     };
     const upstreams = [];
     if (source.subscribe) {
@@ -636,9 +1052,15 @@ var Query = class _Query {
     }
     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);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
     };
     const upstreams = [];
     if (source.subscribe) {
@@ -652,13 +1074,15 @@ var Query = class _Query {
         executeRecords,
         field,
         upstreams,
-        dictLabelResolver
+        dictLabelResolver,
+        this.source.moneyFields
       );
     }
     return this.aggregateStrategy.groupByN(
       executeRecords,
       fields,
-      upstreams
+      upstreams,
+      this.source.moneyFields
     );
   }
   /**
@@ -750,6 +1174,21 @@ var Query = class _Query {
         }
       }
     }
+    if (this.joinContext) {
+      const subscribedCross = /* @__PURE__ */ new Set();
+      for (const clause of this.plan.clauses) {
+        if (clause.type !== "crossJoin") continue;
+        if (subscribedCross.has(clause.target)) continue;
+        subscribedCross.add(clause.target);
+        const rightSource = this.joinContext.resolveSource(clause.target);
+        if (rightSource?.subscribe) {
+          const rightSubscribe = rightSource.subscribe.bind(rightSource);
+          upstreams.push({
+            subscribe: (cb) => rightSubscribe(cb)
+          });
+        }
+      }
+    }
     return buildLiveQuery(() => this.toArray(), upstreams);
   }
   /**
@@ -761,11 +1200,23 @@ var Query = class _Query {
     return serializePlan(this.plan);
   }
 };
-function executePlanWithSource(source, plan) {
-  const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
-  let result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+function executePlanWithSource(source, plan, joinContext, 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) {
-    result = sortRecords(result, plan.orderBy);
+    const labelMaps = buildOrderLabelMaps(plan.orderBy, joinContext, locale);
+    result = sortRecords(result, plan.orderBy, source.moneyFields, labelMaps);
   }
   if (plan.offset > 0) {
     result = result.slice(plan.offset);
@@ -785,6 +1236,7 @@ function candidateRecords(source, clauses) {
     const clause = clauses[i];
     if (clause.type !== "field") continue;
     if (!indexes.has(clause.field)) continue;
+    if (clause.money?.mode === "multi") continue;
     let ids = null;
     if (clause.op === "==") {
       ids = indexes.lookupEqual(clause.field, clause.value);
@@ -813,6 +1265,11 @@ function materializeIds(ids, lookupById) {
   return out;
 }
 function executePlan(records, plan) {
+  if (plan.clauses.some((c) => c.type === "crossJoin")) {
+    throw new Error(
+      `executePlan(): does not support crossJoin clauses. executePlan is a stateless pure function \u2014 it cannot resolve cross-join right-side collections. Use Query.toArray() (via collection.query()) instead.`
+    );
+  }
   let result = filterRecords(records, plan.clauses);
   if (plan.orderBy.length > 0) {
     result = sortRecords(result, plan.orderBy);
@@ -825,13 +1282,20 @@ function executePlan(records, plan) {
   }
   return result;
 }
-function filterRecords(records, clauses) {
+function fnViewDecoder(source) {
+  const mf = source.moneyFields;
+  if (!mf || Object.keys(mf).length === 0) return void 0;
+  return (r) => decodeMoneyFields(r, mf, "raw");
+}
+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)) {
+      if (!evaluateClause(r, clause, fnView)) {
         matches = false;
         break;
       }
@@ -840,17 +1304,124 @@ function filterRecords(records, clauses) {
   }
   return out;
 }
-function sortRecords(records, orderBy) {
+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, moneyFields, labelMaps) {
   return [...records].sort((a, b) => {
-    for (const { field, direction } of orderBy) {
-      const av = readField(a, field);
-      const bv = readField(b, field);
-      const cmp = compareValues(av, bv);
+    for (const { field, direction, by } of orderBy) {
+      let av = readField(a, field);
+      let bv = readField(b, field);
+      const labelMap = by === "label" ? labelMaps?.get(field) : void 0;
+      if (labelMap) {
+        av = (typeof av === "string" ? labelMap.get(av) : void 0) ?? av;
+        bv = (typeof bv === "string" ? labelMap.get(bv) : void 0) ?? bv;
+        const cmp2 = compareValues(av, bv);
+        if (cmp2 !== 0) return direction === "asc" ? cmp2 : -cmp2;
+        continue;
+      }
+      const desc = moneyFields?.[field];
+      const cmp = desc ? compareMoney(av, bv, desc) : compareValues(av, bv);
       if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
     }
     return 0;
   });
 }
+function buildOrderLabelMaps(orderBy, joinContext, locale) {
+  if (!joinContext?.resolveDictSource) return void 0;
+  const resolveDict = joinContext.resolveDictSource.bind(joinContext);
+  let maps;
+  for (const { field, by } of orderBy) {
+    if (by !== "label") continue;
+    const dictSource = resolveDict(field);
+    if (!dictSource) continue;
+    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, codeToLabel);
+  }
+  return maps;
+}
+function compareMoney(a, b, desc) {
+  const av = moneyScaledValue(a, desc);
+  const bv = moneyScaledValue(b, desc);
+  if (av === null) return bv === null ? 0 : 1;
+  if (bv === null) return -1;
+  return av < bv ? -1 : av > bv ? 1 : 0;
+}
 function readField(record, field) {
   if (record === null || record === void 0) return void 0;
   if (!field.includes(".")) {
@@ -902,6 +1473,16 @@ function serializeClause(clause) {
       clauses: clause.clauses.map(serializeClause)
     };
   }
+  if (clause.type === "crossJoin") {
+    return {
+      type: "crossJoin",
+      target: clause.target,
+      as: clause.as,
+      on: clause.on ? "[function]" : void 0,
+      onPredicateName: clause.onPredicateName,
+      maxRows: clause.maxRows
+    };
+  }
   return clause;
 }
 function canonicalCtxHash(ctx) {
@@ -927,6 +1508,7 @@ function buildDictLabelResolver(joinCtx, field) {
   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"];
@@ -936,9 +1518,11 @@ function buildDictLabelResolver(joinCtx, field) {
     }
   }
   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[locale] !== void 0) return labels[locale];
+    if (labels[effLocale] !== void 0) return labels[effLocale];
     const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
     for (const fb of chain) {
       if (fb === "any") {
@@ -978,12 +1562,29 @@ var ScanBuilder = class _ScanBuilder {
    * context throws with an actionable error.
    */
   joinContext;
-  constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext) {
+  /**
+   * Money field descriptors for the backing collection. When present, yielded
+   * records are decoded (stored scaled-int → canonical decimal) so `scan()`
+   * agrees with `get()`/`list()`/`query().toArray()` — #322. Decoded with
+   * `'raw'` (canonical decimal, no locale-formatted virtuals) since the scan
+   * stream carries no locale context, mirroring `Query.toArray()`.
+   */
+  moneyFields;
+  constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext, moneyFields) {
     this.pageProvider = pageProvider;
     this.pageSize = pageSize;
     this.clauses = clauses;
     this.joins = joins;
     this.joinContext = joinContext;
+    this.moneyFields = moneyFields;
+  }
+  /**
+   * Decode this scan's money fields on a record (stored scaled-int → canonical
+   * decimal). No-op when no money fields are declared. See {@link moneyFields}.
+   */
+  decodeMoney(record) {
+    if (!this.moneyFields || Object.keys(this.moneyFields).length === 0) return record;
+    return decodeMoneyFields(record, this.moneyFields, "raw");
   }
   /**
    * Add a field comparison. Runs per record as the scan stream
@@ -999,13 +1600,15 @@ var ScanBuilder = class _ScanBuilder {
    * evaluates clauses per record in O(1) per clause.
    */
   where(field, op, value) {
-    const clause = { type: "field", field, op, value };
+    const desc = this.moneyFields?.[field];
+    const clause = desc ? moneyFieldClause(field, op, value, desc) : { type: "field", field, op, value };
     return new _ScanBuilder(
       this.pageProvider,
       this.pageSize,
       [...this.clauses, clause],
       this.joins,
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -1024,7 +1627,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       [...this.clauses, clause],
       this.joins,
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -1135,7 +1739,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       this.clauses,
       [...this.joins, leg],
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -1152,10 +1757,11 @@ var ScanBuilder = class _ScanBuilder {
     while (true) {
       for (const record of page.items) {
         if (!this.recordMatches(record)) continue;
+        const decoded = this.decodeMoney(record);
         if (joinResolvers === null) {
-          yield record;
+          yield decoded;
         } else {
-          let attached = record;
+          let attached = decoded;
           for (const resolver of joinResolvers) {
             attached = this.applyOneJoinStreaming(attached, resolver);
           }
@@ -1341,8 +1947,9 @@ var ScanBuilder = class _ScanBuilder {
    */
   recordMatches(record) {
     if (this.clauses.length === 0) return true;
+    const fnView = this.moneyFields && Object.keys(this.moneyFields).length > 0 && hasFnClause(this.clauses) ? this.decodeMoney(record) : void 0;
     for (const clause of this.clauses) {
-      if (!evaluateClause(record, clause)) return false;
+      if (!evaluateClause(record, clause, fnView)) return false;
     }
     return true;
   }
@@ -1355,13 +1962,19 @@ function coerceRefKey2(value) {
 }
 
 export {
+  validateMoneyFieldPaths,
+  canonicalizeStoredMoney,
+  canonicalizeIncomingMoney,
+  quantizeMoneyFields,
+  decodeMoneyFields,
   DEFAULT_JOIN_MAX_ROWS,
   applyJoins,
   resetJoinWarnings,
   buildLiveQuery,
   NO_AGGREGATE,
+  DEFAULT_CROSS_JOIN_MAX_ROWS,
   Query,
   executePlan,
   ScanBuilder
 };
-//# sourceMappingURL=chunk-J4KLMEUL.js.map
+//# sourceMappingURL=chunk-NV4IHBZS.js.map