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

package/dist/{chunk-2GLDA55J.js → chunk-UIU2THRG.js}

@@ -1,15 +1,28 @@
 import {
+  reducerBuilder,
+  wrapMoneyReducers
+} from "./chunk-LV7M27WM.js";
+import {
+  MoneyPrecisionError,
   evaluateClause,
+  formatScaledInt,
+  hasFnClause,
+  moneyFieldClause,
+  parseToScaledInt,
   readPath
-} from "./chunk-TV3YZ35S.js";
+} from "./chunk-M2YKN37S.js";
+import {
+  applyI18nLocale
+} from "./chunk-5LUY7UTV.js";
 import {
   CrossJoinSourceUnknownError,
   CrossJoinTooLargeError,
   DanglingReferenceError,
-  JoinTooLargeError
-} from "./chunk-B6PB7JLN.js";
+  JoinTooLargeError,
+  ValidationError
+} from "./chunk-ZYUC53LT.js";
 
-// src/query/join.ts
+// src/kernel/query/join.ts
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
 var JOIN_WARN_FRACTION = 0.8;
 function coerceRefKey(value) {
@@ -37,15 +50,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) {
@@ -100,24 +113,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");
@@ -130,7 +146,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;
@@ -164,7 +181,7 @@ function resetJoinWarnings() {
   warnedCeilingKeys.clear();
 }
 
-// src/query/live.ts
+// src/kernel/query/live.ts
 function buildLiveQuery(recompute, upstreams) {
   return new LiveQueryImpl(recompute, upstreams);
 }
@@ -235,7 +252,7 @@ var LiveQueryImpl = class {
   }
 };
 
-// src/aggregate/strategy.ts
+// src/with-lookup/aggregate/strategy.ts
 var NOT_ENABLED = new Error(
   'Aggregate / groupBy is not enabled on this Noydb instance. Import `{ withAggregate }` from "@noy-db/hub/aggregate" and pass it to `createNoydb({ aggregateStrategy: withAggregate() })`.'
 );
@@ -254,7 +271,278 @@ var NO_AGGREGATE = {
   }
 };
 
-// src/query/builder.ts
+// src/with-shape/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/with-shape/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/kernel/query/builder.ts
 var EMPTY_PLAN = {
   clauses: [],
   orderBy: [],
@@ -307,6 +595,36 @@ var Query = class _Query {
       predicates
     );
   }
+  /**
+   * @internal — the ids of records matching this query's plan,
+   * recovered by reference identity: `executePlanWithSource` returns the
+   * ORIGINAL snapshot record references (money-decode and joins are applied
+   * later, in `toArray`), so each matched record is found in the id-paired
+   * `snapshotEntries()` map. Used by `collection.retrieve({ within })`.
+   * Throws if the source is not collection-backed (no `snapshotEntries`).
+   */
+  _idArray() {
+    const entries = this.source.snapshotEntries?.();
+    if (entries === void 0) {
+      throw new Error(
+        "Query._idArray(): the query source has no snapshotEntries(); retrieve({ within }) requires a collection-backed query (collection.query())."
+      );
+    }
+    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+      throw new Error(
+        "Query._idArray(): retrieve({ within }) does not support crossJoin queries (cross-join produces new row objects, breaking id recovery). Use where/filter/and/or, or a projection .join()."
+      );
+    }
+    const refToId = /* @__PURE__ */ new Map();
+    for (const { id, record } of entries) refToId.set(record, id);
+    const matched = executePlanWithSource(this.source, this.plan, this.joinContext);
+    const ids = [];
+    for (const r of matched) {
+      const id = refToId.get(r);
+      if (id !== void 0) ids.push(id);
+    }
+    return ids;
+  }
   /**
    * Filter by a registered deterministic predicate. Requires
    * the Query to have been augmented with a predicates map (typically
@@ -346,9 +664,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: 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] },
@@ -414,11 +741,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.
+   */
+  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
@@ -621,20 +953,42 @@ var Query = class _Query {
    * carries any join legs, they are applied after `where` / `orderBy`
    * / `limit` / `offset` narrow the left set. See the `.join()` doc
    * for the ordering rationale.
+   *
+   * `opts.locale` resolves JOINED right-side i18n fields at the
+   * `join` layer to that locale; without it, the owning collection's default
+   * locale applies, and a locale-less query leaves joined i18n fields raw.
+   * (Left/base i18n fields are resolved by `get`/`list`, not here.)
    */
-  toArray() {
-    const base = executePlanWithSource(this.source, this.plan, this.joinContext);
+  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
+   * reintroduce a "two read paths disagree" failure on the virtual
+   * field (e.g. it-IT via `get()` vs en-US here). Consumers who need formatted
+   * money read through `get()`/`list()` with a locale.
+   */
+  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. */
+  first(opts) {
+    const arr = this.limit(1).toArray(opts);
     return arr[0] ?? null;
   }
   /**
@@ -657,49 +1011,14 @@ var Query = class _Query {
     }
     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.
-   * the aggregation terminal.
-   *
-   * ```ts
-   * const { total, n, avgAmount } = invoices.query()
-   *   .where('status', '==', 'open')
-   *   .aggregate({
-   *     total:     sum('amount'),
-   *     n:         count(),
-   *     avgAmount: avg('amount'),
-   *   })
-   *   .run()
-   * ```
-   *
-   * Returns an `Aggregation<R>` wrapper with two terminals:
-   *   - `.run(): R` — synchronous one-shot reduction
-   *   - `.live(): LiveAggregation<R>` — reactive primitive that
-   *     re-runs the reduction whenever the source notifies of a
-   *     change. Always call `live.stop()` when finished.
-   *
-   * The reducer spec is bound here once and reused by both
-   * terminals — this is why `.aggregate()` returns a wrapper instead
-   * of being a direct terminal. Consumers who only need the static
-   * value read `.run()`; consumers wiring a reactive UI read
-   * `.live()`.
-   *
-   * Joins are intentionally NOT applied to aggregations in —
-   * the same logic as `.count()`. Joins in are projection-only
-   * (they attach an aliased field and never filter), so running
-   * them just to throw the aliases away would be wasteful. If you
-   * need a reducer that reads a joined field, open an issue —
-   * aggregations-across-joins is explicitly out of scope for v1.
-   *
-   * Every reducer factory accepts an optional `{ seed }` parameter
-   * that is plumbed through the protocol but unused by the
-   * executor — that's  constraint #2. When partition-aware
-   * aggregation lands, the seed will carry running state across
-   * partition boundaries without an API break.
-   */
-  aggregate(spec) {
+  aggregate(specOrBuild) {
+    let spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
+    const moneyFields = this.source.moneyFields;
+    if (moneyFields) {
+      spec = wrapMoneyReducers(spec, moneyFields);
+    }
     const source = this.source;
     const clauses = this.plan.clauses;
     const joinCtx = this.joinContext;
@@ -710,7 +1029,7 @@ var Query = class _Query {
         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) {
@@ -733,7 +1052,7 @@ var Query = class _Query {
         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) {
@@ -747,13 +1066,15 @@ var Query = class _Query {
         executeRecords,
         field,
         upstreams,
-        dictLabelResolver
+        dictLabelResolver,
+        this.source.moneyFields
       );
     }
     return this.aggregateStrategy.groupByN(
       executeRecords,
       fields,
-      upstreams
+      upstreams,
+      this.source.moneyFields
     );
   }
   /**
@@ -871,7 +1192,7 @@ var Query = class _Query {
     return serializePlan(this.plan);
   }
 };
-function executePlanWithSource(source, plan, joinContext) {
+function executePlanWithSource(source, plan, joinContext, locale) {
   const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
   let result;
   if (hasCrossJoins) {
@@ -883,10 +1204,11 @@ function executePlanWithSource(source, plan, joinContext) {
     result = executeClausePipeline(source, plan.clauses, joinContext);
   } else {
     const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
-    result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+    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);
@@ -906,6 +1228,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);
@@ -951,13 +1274,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;
       }
@@ -969,10 +1299,11 @@ function filterRecords(records, clauses) {
 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);
+        rel = filterRecords(rel, filterBatch, decodeForFns);
         filterBatch = [];
       }
       const rightSource = joinContext.resolveSource(clause.target);
@@ -985,7 +1316,7 @@ function executeClausePipeline(source, clauses, joinContext) {
     }
   }
   if (filterBatch.length > 0) {
-    rel = filterRecords(rel, filterBatch);
+    rel = filterRecords(rel, filterBatch, decodeForFns);
   }
   return rel;
 }
@@ -1034,17 +1365,55 @@ function applyCrossJoin(leftRel, clause, rightSource) {
   }
   return expanded;
 }
-function sortRecords(records, orderBy) {
+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(".")) {
@@ -1131,6 +1500,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"];
@@ -1140,9 +1510,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") {
@@ -1156,7 +1528,7 @@ function buildDictLabelResolver(joinCtx, field) {
   };
 }
 
-// src/query/scan-builder.ts
+// src/kernel/query/scan-builder.ts
 var DEFAULT_SCAN_PAGE_SIZE = 100;
 var ScanBuilder = class _ScanBuilder {
   pageProvider;
@@ -1182,12 +1554,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()`. 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
@@ -1203,13 +1592,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
     );
   }
   /**
@@ -1228,7 +1619,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       [...this.clauses, clause],
       this.joins,
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -1339,7 +1731,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       this.clauses,
       [...this.joins, leg],
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -1356,10 +1749,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);
           }
@@ -1483,43 +1877,8 @@ var ScanBuilder = class _ScanBuilder {
     }
     return merged;
   }
-  /**
-   * Reduce the scan stream through a named set of reducers and
-   * return the final aggregated shape.
-   *
-   * Memory is O(reducers): one mutable state slot per spec key.
-   * Records flow through the pipeline one at a time via
-   * `for await` and are discarded after their `step()` is applied
-   * — never collected into an array. This is the distinguishing
-   * property from `Query.aggregate()`, which materializes the full
-   * match set first.
-   *
-   * Reuses the same reducer protocol as `Query.aggregate()`,
-   * so `count()`, `sum(field)`, `avg(field)`, `min(field)`,
-   * `max(field)` all work unchanged. The `{ seed }` parameter
-   * plumbing from  constraint #2 is honored transparently — the
-   * factories ignore it in and the scan executor never
-   * touches the per-reducer state construction.
-   *
-   * **Returns a Promise**, unlike `Query.aggregate().run()` which
-   * is synchronous. The scan is inherently async because it walks
-   * adapter pages, so the terminal has to be too. Consumers
-   * destructure with await:
-   *
-   * ```ts
-   * const { total, n } = await invoices.scan()
-   *   .where('year', '==', 2025)
-   *   .aggregate({ total: sum('amount'), n: count() })
-   * ```
-   *
-   * **No `.live()` in.** `scan().aggregate().live()` would
-   * require reconciling an unbounded streaming iteration with a
-   * change-stream subscription — a design problem, not just a code
-   * one. Consumers with huge collections and live needs should
-   * narrow with `.where()` enough to fit in the 50k `query()`
-   * limit and use `query().aggregate().live()` instead.
-   */
-  async aggregate(spec) {
+  async aggregate(specOrBuild) {
+    const spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
     const keys = Object.keys(spec);
     const state = {};
     for (const key of keys) {
@@ -1545,8 +1904,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;
   }
@@ -1559,6 +1919,11 @@ function coerceRefKey2(value) {
 }
 
 export {
+  validateMoneyFieldPaths,
+  canonicalizeStoredMoney,
+  canonicalizeIncomingMoney,
+  quantizeMoneyFields,
+  decodeMoneyFields,
   DEFAULT_JOIN_MAX_ROWS,
   applyJoins,
   resetJoinWarnings,
@@ -1569,4 +1934,4 @@ export {
   executePlan,
   ScanBuilder
 };
-//# sourceMappingURL=chunk-2GLDA55J.js.map
+//# sourceMappingURL=chunk-UIU2THRG.js.map