@noy-db/hub 0.2.0-pre.3 → 0.2.0-pre.31

package/dist/{query/index.cjs → chunk-QGBBQKDS.js}

@@ -1,225 +1,25 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/query/index.ts
-var query_exports = {};
-__export(query_exports, {
-  Aggregation: () => Aggregation,
-  CollectionIndexes: () => CollectionIndexes,
-  DEFAULT_JOIN_MAX_ROWS: () => DEFAULT_JOIN_MAX_ROWS,
-  DanglingReferenceError: () => DanglingReferenceError,
-  GROUPBY_MAX_CARDINALITY: () => GROUPBY_MAX_CARDINALITY,
-  GROUPBY_WARN_CARDINALITY: () => GROUPBY_WARN_CARDINALITY,
-  GroupCardinalityError: () => GroupCardinalityError,
-  GroupedAggregation: () => GroupedAggregation,
-  GroupedQuery: () => GroupedQuery,
-  GroupedQueryN: () => GroupedQueryN,
-  IndexRequiredError: () => IndexRequiredError,
-  IndexWriteFailureError: () => IndexWriteFailureError,
-  JoinTooLargeError: () => JoinTooLargeError,
-  Query: () => Query,
-  ScanBuilder: () => ScanBuilder,
-  applyJoins: () => applyJoins,
-  avg: () => avg,
-  buildLiveAggregation: () => buildLiveAggregation,
-  buildLiveQuery: () => buildLiveQuery,
-  count: () => count,
-  evaluateClause: () => evaluateClause,
-  evaluateFieldClause: () => evaluateFieldClause,
-  executePlan: () => executePlan,
-  groupAndReduce: () => groupAndReduce,
-  max: () => max,
-  min: () => min,
-  readPath: () => readPath,
-  reduceRecords: () => reduceRecords,
-  resetGroupByWarnings: () => resetGroupByWarnings,
-  resetJoinWarnings: () => resetJoinWarnings,
-  sum: () => sum
-});
-module.exports = __toCommonJS(query_exports);
-
-// src/query/predicate.ts
-function readPath(record, path) {
-  if (record === null || record === void 0) return void 0;
-  if (!path.includes(".")) {
-    return record[path];
-  }
-  const segments = path.split(".");
-  let cursor = record;
-  for (const segment of segments) {
-    if (cursor === null || cursor === void 0) return void 0;
-    cursor = cursor[segment];
-  }
-  return cursor;
-}
-function evaluateFieldClause(record, clause) {
-  const actual = readPath(record, clause.field);
-  const { op, value } = clause;
-  switch (op) {
-    case "==":
-      return actual === value;
-    case "!=":
-      return actual !== value;
-    case "<":
-      return isComparable(actual, value) && actual < value;
-    case "<=":
-      return isComparable(actual, value) && actual <= value;
-    case ">":
-      return isComparable(actual, value) && actual > value;
-    case ">=":
-      return isComparable(actual, value) && actual >= value;
-    case "in":
-      return Array.isArray(value) && value.includes(actual);
-    case "contains":
-      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
-      if (Array.isArray(actual)) return actual.includes(value);
-      return false;
-    case "startsWith":
-      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
-    case "between": {
-      if (!Array.isArray(value) || value.length !== 2) return false;
-      const [lo, hi] = value;
-      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
-      return actual >= lo && actual <= hi;
-    }
-    default: {
-      const _exhaustive = op;
-      void _exhaustive;
-      return false;
-    }
-  }
-}
-function isComparable(a, b) {
-  if (typeof a === "number" && typeof b === "number") return true;
-  if (typeof a === "string" && typeof b === "string") return true;
-  if (a instanceof Date && b instanceof Date) return true;
-  return false;
-}
-function evaluateClause(record, clause) {
-  switch (clause.type) {
-    case "field":
-      return evaluateFieldClause(record, clause);
-    case "filter":
-      return clause.fn(record);
-    case "wherePredicate":
-      return clause.fn(record, clause.ctx);
-    case "group":
-      if (clause.op === "and") {
-        for (const child of clause.clauses) {
-          if (!evaluateClause(record, child)) return false;
-        }
-        return true;
-      } else {
-        for (const child of clause.clauses) {
-          if (evaluateClause(record, child)) return true;
-        }
-        return false;
-      }
-  }
-}
-
-// src/errors.ts
-var NoydbError = class extends Error {
-  /** Machine-readable error code. Stable across library versions. */
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "NoydbError";
-    this.code = code;
-  }
-};
-var GroupCardinalityError = class extends NoydbError {
-  /** The field being grouped on. */
-  field;
-  /** Observed number of distinct groups at the moment the cap tripped. */
-  cardinality;
-  /** The cap that was exceeded. */
-  maxGroups;
-  constructor(field, cardinality, maxGroups) {
-    super(
-      "GROUP_CARDINALITY",
-      `.groupBy("${field}") produced ${cardinality} distinct groups, exceeding the ${maxGroups}-group ceiling. This is almost always a query mistake \u2014 grouping on a high-uniqueness field like "id" or "createdAt" produces one bucket per record. Narrow the query with .where() before grouping, or group on a lower-cardinality field (status, category, clientId). If you genuinely need high-cardinality grouping, file an issue with your use case.`
-    );
-    this.name = "GroupCardinalityError";
-    this.field = field;
-    this.cardinality = cardinality;
-    this.maxGroups = maxGroups;
-  }
-};
-var IndexRequiredError = class extends NoydbError {
-  collection;
-  touchedFields;
-  missingFields;
-  constructor(args) {
-    super(
-      "INDEX_REQUIRED",
-      `Collection "${args.collection}": query references unindexed fields in lazy mode (missing: ${args.missingFields.join(", ")}). Declare an index on each field, or use collection.scan() for non-indexed iteration.`
-    );
-    this.name = "IndexRequiredError";
-    this.collection = args.collection;
-    this.touchedFields = [...args.touchedFields];
-    this.missingFields = [...args.missingFields];
-  }
-};
-var IndexWriteFailureError = class extends NoydbError {
-  recordId;
-  field;
-  op;
-  cause;
-  constructor(args) {
-    super(
-      "INDEX_WRITE_FAILURE",
-      `Index side-car ${args.op} failed for field "${args.field}" on record "${args.recordId}"`
-    );
-    this.name = "IndexWriteFailureError";
-    this.recordId = args.recordId;
-    this.field = args.field;
-    this.op = args.op;
-    this.cause = args.cause;
-  }
-};
-var JoinTooLargeError = class extends NoydbError {
-  leftRows;
-  rightRows;
-  maxRows;
-  side;
-  constructor(opts) {
-    super("JOIN_TOO_LARGE", opts.message);
-    this.name = "JoinTooLargeError";
-    this.leftRows = opts.leftRows;
-    this.rightRows = opts.rightRows;
-    this.maxRows = opts.maxRows;
-    this.side = opts.side;
-  }
-};
-var DanglingReferenceError = class extends NoydbError {
-  field;
-  target;
-  refId;
-  constructor(opts) {
-    super("DANGLING_REFERENCE", opts.message);
-    this.name = "DanglingReferenceError";
-    this.field = opts.field;
-    this.target = opts.target;
-    this.refId = opts.refId;
-  }
-};
+import {
+  wrapMoneyReducers
+} from "./chunk-K6NVSHAH.js";
+import {
+  MoneyPrecisionError,
+  evaluateClause,
+  formatScaledInt,
+  hasFnClause,
+  moneyFieldClause,
+  parseToScaledInt,
+  readPath
+} from "./chunk-KJ3K5VZM.js";
+import {
+  applyI18nLocale
+} from "./chunk-QXWJQ7UU.js";
+import {
+  CrossJoinSourceUnknownError,
+  CrossJoinTooLargeError,
+  DanglingReferenceError,
+  JoinTooLargeError,
+  ValidationError
+} from "./chunk-JZ5DS4DP.js";
 
 // src/query/join.ts
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
@@ -249,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) {
@@ -312,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");
@@ -342,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;
@@ -466,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: [],
@@ -474,6 +549,7 @@ var EMPTY_PLAN = {
   offset: 0,
   joins: []
 };
+var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
 var Query = class _Query {
   source;
   plan;
@@ -506,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) {
@@ -519,7 +595,37 @@ var Query = class _Query {
     );
   }
   /**
-   * Filter by a registered deterministic predicate (#153). Requires
+   * @internal — #308 L3. 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()`).
@@ -557,9 +663,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] },
@@ -625,11 +740,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
@@ -755,25 +875,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;
   }
   /**
@@ -786,9 +1000,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.
@@ -831,11 +1053,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) {
@@ -850,9 +1082,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) {
@@ -866,13 +1104,15 @@ var Query = class _Query {
         executeRecords,
         field,
         upstreams,
-        dictLabelResolver
+        dictLabelResolver,
+        this.source.moneyFields
       );
     }
     return this.aggregateStrategy.groupByN(
       executeRecords,
       fields,
-      upstreams
+      upstreams,
+      this.source.moneyFields
     );
   }
   /**
@@ -964,6 +1204,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);
   }
   /**
@@ -975,11 +1230,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);
@@ -999,6 +1266,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);
@@ -1027,6 +1295,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);
@@ -1039,13 +1312,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;
       }
@@ -1054,17 +1334,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(".")) {
@@ -1116,6 +1503,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) {
@@ -1141,6 +1538,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"];
@@ -1150,9 +1548,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") {
@@ -1166,537 +1566,6 @@ function buildDictLabelResolver(joinCtx, field) {
   };
 }
 
-// src/indexing/eager-indexes.ts
-var CollectionIndexes = class {
-  indexes = /* @__PURE__ */ new Map();
-  /**
-   * Declare an index. Subsequent record additions are tracked under it.
-   * Calling this twice for the same field is a no-op (idempotent).
-   */
-  declare(field) {
-    if (this.indexes.has(field)) return;
-    this.indexes.set(field, { field, buckets: /* @__PURE__ */ new Map() });
-  }
-  /** True if the given field has a declared index. */
-  has(field) {
-    return this.indexes.has(field);
-  }
-  /** All declared field names, in declaration order. */
-  fields() {
-    return [...this.indexes.keys()];
-  }
-  /**
-   * Build all declared indexes from a snapshot of records.
-   * Called once per hydration. O(N × indexes.size).
-   */
-  build(records) {
-    for (const idx of this.indexes.values()) {
-      idx.buckets.clear();
-      for (const { id, record } of records) {
-        addToIndex(idx, id, record);
-      }
-    }
-  }
-  /**
-   * Insert or update a single record across all indexes.
-   * Called by `Collection.put()` after the encrypted write succeeds.
-   *
-   * If `previousRecord` is provided, the record is removed from any old
-   * buckets first — this is the update path. Pass `null` for fresh adds.
-   */
-  upsert(id, newRecord, previousRecord) {
-    if (this.indexes.size === 0) return;
-    if (previousRecord !== null) {
-      this.remove(id, previousRecord);
-    }
-    for (const idx of this.indexes.values()) {
-      addToIndex(idx, id, newRecord);
-    }
-  }
-  /**
-   * Remove a record from all indexes. Called by `Collection.delete()`
-   * (and as the first half of `upsert` for the update path).
-   */
-  remove(id, record) {
-    if (this.indexes.size === 0) return;
-    for (const idx of this.indexes.values()) {
-      removeFromIndex(idx, id, record);
-    }
-  }
-  /** Drop all index data. Called when the collection is invalidated. */
-  clear() {
-    for (const idx of this.indexes.values()) {
-      idx.buckets.clear();
-    }
-  }
-  /**
-   * Equality lookup: return the set of record ids whose `field` matches
-   * the given value. Returns `null` if no index covers the field — the
-   * caller should fall back to a linear scan.
-   *
-   * The returned Set is a reference to the index's internal storage —
-   * callers must NOT mutate it.
-   */
-  lookupEqual(field, value) {
-    const idx = this.indexes.get(field);
-    if (!idx) return null;
-    const key = stringifyKey(value);
-    return idx.buckets.get(key) ?? EMPTY_SET;
-  }
-  /**
-   * Set lookup: return the union of record ids whose `field` matches any
-   * of the given values. Returns `null` if no index covers the field.
-   */
-  lookupIn(field, values) {
-    const idx = this.indexes.get(field);
-    if (!idx) return null;
-    const out = /* @__PURE__ */ new Set();
-    for (const value of values) {
-      const key = stringifyKey(value);
-      const bucket = idx.buckets.get(key);
-      if (bucket) {
-        for (const id of bucket) out.add(id);
-      }
-    }
-    return out;
-  }
-};
-var EMPTY_SET = /* @__PURE__ */ new Set();
-function stringifyKey(value) {
-  if (value === null || value === void 0) return "\0NULL\0";
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "boolean") return String(value);
-  if (value instanceof Date) return value.toISOString();
-  return "\0OBJECT\0";
-}
-function addToIndex(idx, id, record) {
-  const value = readPath(record, idx.field);
-  if (value === null || value === void 0) return;
-  const key = stringifyKey(value);
-  let bucket = idx.buckets.get(key);
-  if (!bucket) {
-    bucket = /* @__PURE__ */ new Set();
-    idx.buckets.set(key, bucket);
-  }
-  bucket.add(id);
-}
-function removeFromIndex(idx, id, record) {
-  const value = readPath(record, idx.field);
-  if (value === null || value === void 0) return;
-  const key = stringifyKey(value);
-  const bucket = idx.buckets.get(key);
-  if (!bucket) return;
-  bucket.delete(id);
-  if (bucket.size === 0) idx.buckets.delete(key);
-}
-
-// src/aggregate/reducers.ts
-function count(opts) {
-  const _seed = opts?.seed;
-  void _seed;
-  return {
-    init: () => 0,
-    step: (state) => state + 1,
-    remove: (state) => state - 1,
-    finalize: (state) => state
-  };
-}
-function sum(field, opts) {
-  const _seed = opts?.seed;
-  void _seed;
-  return {
-    init: () => 0,
-    step: (state, record) => state + readNumber(record, field),
-    remove: (state, record) => state - readNumber(record, field),
-    finalize: (state) => state
-  };
-}
-function avg(field, opts) {
-  const _seed = opts?.seed;
-  void _seed;
-  return {
-    init: () => ({ sum: 0, count: 0 }),
-    step: (state, record) => ({
-      sum: state.sum + readNumber(record, field),
-      count: state.count + 1
-    }),
-    remove: (state, record) => ({
-      sum: state.sum - readNumber(record, field),
-      count: state.count - 1
-    }),
-    finalize: (state) => state.count === 0 ? null : state.sum / state.count
-  };
-}
-function pushValue(state, value) {
-  return { values: [...state.values, value] };
-}
-function removeValue(state, value) {
-  const idx = state.values.indexOf(value);
-  if (idx < 0) return state;
-  const next = state.values.slice();
-  next.splice(idx, 1);
-  return { values: next };
-}
-function min(field, opts) {
-  const _seed = opts?.seed;
-  void _seed;
-  return {
-    init: () => ({ values: [] }),
-    step: (state, record) => pushValue(state, readNumber(record, field)),
-    remove: (state, record) => removeValue(state, readNumber(record, field)),
-    finalize: (state) => {
-      if (state.values.length === 0) return null;
-      let out = state.values[0];
-      for (let i = 1; i < state.values.length; i++) {
-        const v = state.values[i];
-        if (v < out) out = v;
-      }
-      return out;
-    }
-  };
-}
-function max(field, opts) {
-  const _seed = opts?.seed;
-  void _seed;
-  return {
-    init: () => ({ values: [] }),
-    step: (state, record) => pushValue(state, readNumber(record, field)),
-    remove: (state, record) => removeValue(state, readNumber(record, field)),
-    finalize: (state) => {
-      if (state.values.length === 0) return null;
-      let out = state.values[0];
-      for (let i = 1; i < state.values.length; i++) {
-        const v = state.values[i];
-        if (v > out) out = v;
-      }
-      return out;
-    }
-  };
-}
-function readNumber(record, field) {
-  const value = readPath(record, field);
-  return typeof value === "number" && Number.isFinite(value) ? value : 0;
-}
-
-// src/aggregate/aggregation.ts
-function reduceRecords(records, spec) {
-  const state = {};
-  for (const key of Object.keys(spec)) {
-    state[key] = spec[key].init();
-  }
-  for (const record of records) {
-    for (const key of Object.keys(spec)) {
-      state[key] = spec[key].step(state[key], record);
-    }
-  }
-  const result = {};
-  for (const key of Object.keys(spec)) {
-    result[key] = spec[key].finalize(state[key]);
-  }
-  return result;
-}
-var LiveAggregationImpl = class {
-  constructor(recompute, upstreams) {
-    this.recompute = recompute;
-    try {
-      this.value = recompute();
-      this.error = void 0;
-    } catch (err) {
-      this.value = void 0;
-      this.error = err;
-    }
-    for (const upstream of upstreams) {
-      const unsub = upstream.subscribe(() => this.refresh());
-      this.unsubscribes.push(unsub);
-    }
-  }
-  recompute;
-  value;
-  error;
-  listeners = /* @__PURE__ */ new Set();
-  unsubscribes = [];
-  stopped = false;
-  refresh() {
-    if (this.stopped) return;
-    try {
-      this.value = this.recompute();
-      this.error = void 0;
-    } catch (err) {
-      this.error = err;
-    }
-    for (const listener of this.listeners) {
-      try {
-        listener();
-      } catch (err) {
-        console.warn("[noy-db] LiveAggregation listener threw:", 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.unsubscribes) {
-      try {
-        unsub();
-      } catch (err) {
-        console.warn("[noy-db] LiveAggregation upstream unsubscribe threw:", err);
-      }
-    }
-    this.unsubscribes.length = 0;
-    this.listeners.clear();
-  }
-};
-var Aggregation = class {
-  constructor(executeRecords, spec, upstreams) {
-    this.executeRecords = executeRecords;
-    this.spec = spec;
-    this.upstreams = upstreams;
-  }
-  executeRecords;
-  spec;
-  upstreams;
-  /**
-   * Execute the query and reduce the results synchronously.
-   * Returns the reduced shape matching the spec — e.g. a spec of
-   * `{ total: sum('amount'), n: count() }` returns
-   * `{ total: number, n: number }`.
-   */
-  run() {
-    return reduceRecords(this.executeRecords(), this.spec);
-  }
-  /**
-   * Build a reactive `LiveAggregation<R>` that re-runs the reduction
-   * whenever any upstream source notifies of a change. The initial
-   * value is computed eagerly in the constructor, so consumers can
-   * read `live.value` immediately after calling `.live()`.
-   *
-   * Always call `live.stop()` when finished — it tears down the
-   * upstream subscriptions. Vue's `onUnmounted` is the canonical
-   * place.
-   *
-   * **Implementation note:** every upstream change triggers a full
-   * re-reduction. Incremental maintenance (O(1) per delta for
-   * sum/count/avg via the reducer protocol's `remove()` method) is a
-   * planned follow-up optimization — the protocol already supports
-   * it, but the executor doesn't drive it yet. Consumers get
-   * correct, reactive values today; future PRs can switch to
-   * delta-based maintenance without changing this API.
-   */
-  live() {
-    const recompute = () => reduceRecords(this.executeRecords(), this.spec);
-    return new LiveAggregationImpl(recompute, this.upstreams);
-  }
-};
-function buildLiveAggregation(recompute, upstreams) {
-  return new LiveAggregationImpl(recompute, upstreams);
-}
-
-// src/aggregate/canonical-key.ts
-function canonicalGroupKey(fields, row) {
-  const sorted = [...fields].sort();
-  const parts = [];
-  for (const name of sorted) {
-    const v = row[name];
-    const serialised = v === void 0 ? "undefined" : JSON.stringify(v);
-    parts.push(`${name}=${serialised}`);
-  }
-  return parts.join("|");
-}
-
-// src/aggregate/groupby.ts
-var GROUPBY_WARN_CARDINALITY = 1e4;
-var GROUPBY_MAX_CARDINALITY = 1e5;
-var warnedCardinalityFields = /* @__PURE__ */ new Set();
-function warnCardinalityApproaching(fields, observed) {
-  const key = JSON.stringify([...fields].sort());
-  if (warnedCardinalityFields.has(key)) return;
-  warnedCardinalityFields.add(key);
-  const label = `[${fields.join(", ")}]`;
-  console.warn(
-    `[noy-db] .groupBy(${label}) produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
-  );
-}
-function resetGroupByWarnings() {
-  warnedCardinalityFields.clear();
-}
-var GroupedQueryBase = class {
-  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver) {
-    this.executeRecords = executeRecords;
-    this.upstreams = upstreams;
-    this.dictLabelResolver = dictLabelResolver;
-    this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
-  }
-  executeRecords;
-  upstreams;
-  dictLabelResolver;
-  /**
-   * Field set this grouped query buckets on. Stored in declaration
-   * order — the same order is preserved on every result row by
-   * `groupAndReduce`. For the single-field constructor, this is
-   * `[field]`.
-   */
-  fields;
-};
-var GroupedQuery = class extends GroupedQueryBase {
-  /**
-   * Build a grouped aggregation. Returns a `GroupedAggregation`
-   * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape
-   * as the non-grouped `.aggregate()` wrapper, just with an array
-   * result (one row per bucket) instead of a single reduced object.
-   */
-  aggregate(spec) {
-    return new GroupedAggregation(
-      this.executeRecords,
-      this.fields,
-      spec,
-      this.upstreams,
-      this.dictLabelResolver
-    );
-  }
-};
-var GroupedQueryN = class extends GroupedQueryBase {
-  aggregate(spec) {
-    return new GroupedAggregation(
-      this.executeRecords,
-      this.fields,
-      spec,
-      this.upstreams,
-      this.dictLabelResolver
-    );
-  }
-};
-function groupAndReduce(records, fieldOrFields, spec) {
-  const fields = typeof fieldOrFields === "string" ? [fieldOrFields] : fieldOrFields;
-  if (fields.length === 0) {
-    throw new Error(".groupBy() requires at least one field");
-  }
-  const buckets = /* @__PURE__ */ new Map();
-  const fieldLabel = fields.length === 1 ? fields[0] : `[${fields.join(", ")}]`;
-  for (const record of records) {
-    const keyValues = {};
-    for (const f of fields) {
-      keyValues[f] = readPath(record, f);
-    }
-    const dedupKey = canonicalGroupKey(fields, keyValues);
-    let bucket = buckets.get(dedupKey);
-    if (bucket === void 0) {
-      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {
-        throw new GroupCardinalityError(
-          fieldLabel,
-          buckets.size + 1,
-          GROUPBY_MAX_CARDINALITY
-        );
-      }
-      bucket = { keyValues, records: [] };
-      buckets.set(dedupKey, bucket);
-    }
-    bucket.records.push(record);
-  }
-  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
-    warnCardinalityApproaching(fields, buckets.size);
-  }
-  const reducerKeys = Object.keys(spec);
-  const out = [];
-  for (const bucket of buckets.values()) {
-    const state = {};
-    for (const rk of reducerKeys) {
-      state[rk] = spec[rk].init();
-    }
-    for (const record of bucket.records) {
-      for (const rk of reducerKeys) {
-        state[rk] = spec[rk].step(state[rk], record);
-      }
-    }
-    const row = {};
-    for (const f of fields) {
-      row[f] = bucket.keyValues[f];
-    }
-    for (const rk of reducerKeys) {
-      row[rk] = spec[rk].finalize(state[rk]);
-    }
-    out.push(row);
-  }
-  return out;
-}
-var GroupedAggregation = class {
-  constructor(executeRecords, fields, spec, upstreams, dictLabelResolver) {
-    this.executeRecords = executeRecords;
-    this.spec = spec;
-    this.upstreams = upstreams;
-    this.dictLabelResolver = dictLabelResolver;
-    this.fields = typeof fields === "string" ? [fields] : [...fields];
-  }
-  executeRecords;
-  spec;
-  upstreams;
-  dictLabelResolver;
-  fields;
-  /** Execute the query, group, reduce, and return an array of rows. */
-  run() {
-    return groupAndReduce(this.executeRecords(), this.fields, this.spec);
-  }
-  /**
-   * Execute the query, group, reduce, and resolve `<field>Label` for
-   * each result row when the grouping field is a `dictKey` and a
-   * `locale` is provided. Returns `R[]` synchronously when
-   * no locale is specified (identical to `.run()`).
-   *
-   * The `<field>Label` field is appended to each row. Rows whose group
-   * key has no dictionary entry get `<field>Label: undefined`.
-   *
-   * Dict-label resolution is single-field only — multi-key groupings
-   * do not produce a `<field>Label`. The resolver is only attached
-   * by the builder when `fields.length === 1`.
-   */
-  async runAsync(opts) {
-    const rows = groupAndReduce(this.executeRecords(), this.fields, this.spec);
-    if (!opts?.locale || !this.dictLabelResolver || this.fields.length !== 1) return rows;
-    const resolve = this.dictLabelResolver;
-    const locale = opts.locale;
-    const fallback = opts.fallback;
-    const field = this.fields[0];
-    const labelKey = `${field}Label`;
-    return Promise.all(
-      rows.map(async (row) => {
-        const key = row[field];
-        if (typeof key !== "string") return row;
-        const label = await resolve(key, locale, fallback);
-        return { ...row, [labelKey]: label };
-      })
-    );
-  }
-  /**
-   * Build a reactive `LiveAggregation<R[]>` that re-runs the full
-   * group-and-reduce pipeline whenever any upstream source notifies
-   * of a change. Same error-isolation and idempotent-stop contract
-   * as `Aggregation.live()` — the implementation delegates to the
-   * same `LiveAggregationImpl` class by threading a fresh
-   * recompute closure through the existing constructor.
-   *
-   * uses naive full re-run on every change. Incremental
-   * per-bucket maintenance (apply `step` on inserted records,
-   * `remove` on deleted records, route by bucket key) is a future
-   * optimization — the reducer protocol admits it, but wiring
-   * delta-aware source subscriptions is a separate PR.
-   *
-   * Always call `live.stop()` when finished.
-   */
-  live() {
-    const recompute = () => groupAndReduce(this.executeRecords(), this.fields, this.spec);
-    return buildLiveAggregation(recompute, this.upstreams);
-  }
-};
-
 // src/query/scan-builder.ts
 var DEFAULT_SCAN_PAGE_SIZE = 100;
 var ScanBuilder = class _ScanBuilder {
@@ -1723,12 +1592,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
@@ -1744,13 +1630,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
     );
   }
   /**
@@ -1769,7 +1657,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       [...this.clauses, clause],
       this.joins,
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -1880,7 +1769,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       this.clauses,
       [...this.joins, leg],
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -1897,10 +1787,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);
           }
@@ -2086,8 +1977,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;
   }
@@ -2098,38 +1990,21 @@ function coerceRefKey2(value) {
   if (typeof value === "number" || typeof value === "bigint") return String(value);
   return null;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  Aggregation,
-  CollectionIndexes,
+
+export {
+  validateMoneyFieldPaths,
+  canonicalizeStoredMoney,
+  canonicalizeIncomingMoney,
+  quantizeMoneyFields,
+  decodeMoneyFields,
   DEFAULT_JOIN_MAX_ROWS,
-  DanglingReferenceError,
-  GROUPBY_MAX_CARDINALITY,
-  GROUPBY_WARN_CARDINALITY,
-  GroupCardinalityError,
-  GroupedAggregation,
-  GroupedQuery,
-  GroupedQueryN,
-  IndexRequiredError,
-  IndexWriteFailureError,
-  JoinTooLargeError,
-  Query,
-  ScanBuilder,
   applyJoins,
-  avg,
-  buildLiveAggregation,
+  resetJoinWarnings,
   buildLiveQuery,
-  count,
-  evaluateClause,
-  evaluateFieldClause,
+  NO_AGGREGATE,
+  DEFAULT_CROSS_JOIN_MAX_ROWS,
+  Query,
   executePlan,
-  groupAndReduce,
-  max,
-  min,
-  readPath,
-  reduceRecords,
-  resetGroupByWarnings,
-  resetJoinWarnings,
-  sum
-});
-//# sourceMappingURL=index.cjs.map
+  ScanBuilder
+};
+//# sourceMappingURL=chunk-QGBBQKDS.js.map