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

package/dist/aggregate/index.cjs

@@ -162,31 +162,156 @@ function buildLiveAggregation(recompute, upstreams) {
   return new LiveAggregationImpl(recompute, upstreams);
 }
 
-// src/query/predicate.ts
-function readPath(record, path) {
-  if (record === null || record === void 0) return void 0;
-  if (!path.includes(".")) {
-    return record[path];
+// src/money/fixed-point.ts
+function expandExponent(s) {
+  const m = /^([+-]?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)$/.exec(s);
+  if (!m) return s;
+  const sign = m[1] === "-" ? "-" : "";
+  const intp = m[2];
+  const frac = m[3] ?? "";
+  const exp = Number(m[4]);
+  const digits = intp + frac;
+  const pointPos = intp.length + exp;
+  let body;
+  if (pointPos <= 0) {
+    body = "0." + "0".repeat(-pointPos) + digits;
+  } else if (pointPos >= digits.length) {
+    body = digits + "0".repeat(pointPos - digits.length);
+  } else {
+    body = digits.slice(0, pointPos) + "." + digits.slice(pointPos);
   }
-  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 sign + body;
+}
+function toCanonicalDecimalString(input) {
+  let s;
+  if (typeof input === "number") {
+    if (!Number.isFinite(input)) return null;
+    s = String(input);
+  } else {
+    s = input.trim();
   }
-  return cursor;
+  s = expandExponent(s);
+  if (s.startsWith("+")) s = s.slice(1);
+  if (!/^-?(\d+(\.\d*)?|\.\d+)$/.test(s)) return null;
+  return s;
 }
-
-// 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}`);
+function shouldRoundUp(negative, lastKeptDigit, firstDiscarded, hasMoreNonZeroAfterFirst, mode) {
+  switch (mode) {
+    case "up":
+      return true;
+    case "down":
+      return false;
+    case "ceil":
+      return !negative;
+    case "floor":
+      return negative;
+    case "half-up":
+      return firstDiscarded >= 5;
+    case "half-down":
+      return firstDiscarded > 5 || firstDiscarded === 5 && hasMoreNonZeroAfterFirst;
+    case "half-even":
+      if (firstDiscarded > 5) return true;
+      if (firstDiscarded < 5) return false;
+      return hasMoreNonZeroAfterFirst || lastKeptDigit % 2 === 1;
   }
-  return parts.join("|");
+}
+function parseToScaledInt(input, scale, rounding) {
+  const canonical = toCanonicalDecimalString(input);
+  if (canonical === null) return { ok: false, reason: "nonfinite" };
+  const negative = canonical.startsWith("-");
+  const unsigned = negative ? canonical.slice(1) : canonical;
+  const dot = unsigned.indexOf(".");
+  const intPart = dot === -1 ? unsigned : unsigned.slice(0, dot);
+  const fracPart = dot === -1 ? "" : unsigned.slice(dot + 1);
+  const intDigits = intPart === "" ? "0" : intPart;
+  if (fracPart.length <= scale) {
+    const keep2 = fracPart.padEnd(scale, "0");
+    const magnitude2 = BigInt(intDigits + keep2);
+    return { ok: true, value: negative && magnitude2 !== 0n ? -magnitude2 : magnitude2 };
+  }
+  const keep = fracPart.slice(0, scale);
+  const tail = fracPart.slice(scale);
+  const magnitudeDigits = intDigits + keep;
+  let magnitude = BigInt(magnitudeDigits);
+  if (/^0+$/.test(tail)) {
+    return { ok: true, value: negative && magnitude !== 0n ? -magnitude : magnitude };
+  }
+  if (rounding === void 0) return { ok: false, reason: "precision" };
+  const lastKeptDigit = Number(magnitudeDigits[magnitudeDigits.length - 1]);
+  const firstDiscarded = Number(tail[0]);
+  const hasMoreNonZeroAfterFirst = /[1-9]/.test(tail.slice(1));
+  if (shouldRoundUp(negative, lastKeptDigit, firstDiscarded, hasMoreNonZeroAfterFirst, rounding)) {
+    magnitude += 1n;
+  }
+  return { ok: true, value: negative && magnitude !== 0n ? -magnitude : magnitude };
+}
+function formatScaledInt(value, scale) {
+  const negative = value < 0n;
+  const abs = (negative ? -value : value).toString();
+  if (scale === 0) return (negative ? "-" : "") + abs;
+  const padded = abs.padStart(scale + 1, "0");
+  const cut = padded.length - scale;
+  const intPart = padded.slice(0, cut);
+  const fracPart = padded.slice(cut);
+  return (negative ? "-" : "") + intPart + "." + fracPart;
+}
+
+// src/money/iso4217.ts
+var MINOR_UNITS = {
+  // 2-decimal majors
+  EUR: 2,
+  USD: 2,
+  GBP: 2,
+  CHF: 2,
+  CAD: 2,
+  AUD: 2,
+  NZD: 2,
+  SGD: 2,
+  HKD: 2,
+  CNY: 2,
+  INR: 2,
+  BRL: 2,
+  MXN: 2,
+  ZAR: 2,
+  RUB: 2,
+  TRY: 2,
+  PLN: 2,
+  SEK: 2,
+  NOK: 2,
+  DKK: 2,
+  CZK: 2,
+  HUF: 2,
+  RON: 2,
+  ILS: 2,
+  THB: 2,
+  PHP: 2,
+  MYR: 2,
+  IDR: 2,
+  AED: 2,
+  SAR: 2,
+  QAR: 2,
+  EGP: 2,
+  // 0-decimal
+  JPY: 0,
+  KRW: 0,
+  ISK: 0,
+  CLP: 0,
+  VND: 0,
+  XOF: 0,
+  XAF: 0,
+  PYG: 0,
+  // 3-decimal
+  BHD: 3,
+  KWD: 3,
+  OMR: 3,
+  TND: 3,
+  JOD: 3,
+  IQD: 3,
+  LYD: 3
+};
+function scaleForCurrency(code) {
+  const v = MINOR_UNITS[code];
+  return v === void 0 ? null : v;
 }
 
 // src/errors.ts
@@ -217,6 +342,435 @@ var GroupCardinalityError = class extends NoydbError {
     this.maxGroups = maxGroups;
   }
 };
+var LocaleNotSpecifiedError = class extends NoydbError {
+  /** The field name that required a locale. */
+  field;
+  constructor(field, message) {
+    super(
+      "LOCALE_NOT_SPECIFIED",
+      message ?? `Cannot read i18nText field "${field}" without a locale. Pass { locale } to get()/list()/query() or set a default via openVault(name, { locale }).`
+    );
+    this.name = "LocaleNotSpecifiedError";
+    this.field = field;
+  }
+};
+
+// src/money/descriptor.ts
+var MoneyUnsupportedError = class extends NoydbError {
+  constructor(field, message) {
+    super(
+      "MONEY_UNSUPPORTED",
+      message ?? `money: operation is not supported on field "${field}" \u2014 use sum() and count() and divide at the boundary`
+    );
+    this.field = field;
+    this.name = "MoneyUnsupportedError";
+  }
+  field;
+};
+
+// 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;
+}
+
+// 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/money/money-reducer.ts
+function toScaledIntFromAny(v, scale) {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number") {
+    const r = parseToScaledInt(v, scale);
+    return r.ok ? r.value : null;
+  }
+  if (typeof v === "string") {
+    if (!v.includes(".")) {
+      try {
+        return BigInt(v);
+      } catch {
+        return null;
+      }
+    }
+    const r = parseToScaledInt(v, scale);
+    return r.ok ? r.value : null;
+  }
+  return null;
+}
+function readMoney(record, field, desc) {
+  const raw = readPath(record, field);
+  if (raw === null || raw === void 0) return null;
+  if (desc.mode === "fixed") {
+    const cur = desc.fixedCurrency;
+    const value2 = toScaledIntFromAny(raw, desc.scaleFor(cur));
+    return value2 === null ? null : { currency: cur, value: value2 };
+  }
+  if (typeof raw !== "object") return null;
+  const o = raw;
+  if (typeof o.currency !== "string") return null;
+  const scale = desc.allows(o.currency) ? desc.scaleFor(o.currency) : 0;
+  const value = toScaledIntFromAny(o.amount, scale);
+  return value === null ? null : { currency: o.currency, value };
+}
+function targetScaleFor(desc, currency) {
+  if (desc.allows(currency)) return desc.scaleFor(currency);
+  const s = scaleForCurrency(currency);
+  if (s === null) {
+    throw new Error(`money: cannot determine scale for conversion target "${currency}"`);
+  }
+  return s;
+}
+function parseRate(rate) {
+  const s = String(rate).trim();
+  const neg = s.startsWith("-");
+  const body = neg ? s.slice(1) : s;
+  const dot = body.indexOf(".");
+  const intPart = dot === -1 ? body : body.slice(0, dot);
+  const fracPart = dot === -1 ? "" : body.slice(dot + 1);
+  const int = BigInt((intPart === "" ? "0" : intPart) + fracPart);
+  return { int: neg ? -int : int, scale: fracPart.length };
+}
+function divRoundHalfEven(n, d) {
+  const q = n / d;
+  const r = n % d;
+  const twiceR = (r < 0n ? -r : r) * 2n;
+  if (twiceR < d) return q;
+  if (twiceR > d) return q + (n < 0n ? -1n : 1n);
+  return q % 2n === 0n ? q : q + (n < 0n ? -1n : 1n);
+}
+function convertScaled(value, srcScale, rate, targetScale) {
+  const { int: rateInt, scale: rateScale } = parseRate(rate);
+  const product = value * rateInt;
+  const curScale = srcScale + rateScale;
+  if (curScale === targetScale) return product;
+  if (curScale < targetScale) return product * 10n ** BigInt(targetScale - curScale);
+  return divRoundHalfEven(product, 10n ** BigInt(curScale - targetScale));
+}
+function finalizeSum(state, desc, convertTo, fx) {
+  if (convertTo !== void 0) {
+    if (fx === void 0) {
+      throw new Error(`money: sum convertTo "${convertTo}" requires an fx rate map`);
+    }
+    const targetScale = targetScaleFor(desc, convertTo);
+    let total = 0n;
+    for (const [cur, v] of state) {
+      if (cur === convertTo) {
+        total += convertScaled(v, desc.scaleFor(cur), 1, targetScale);
+        continue;
+      }
+      const rate = fx[`${cur}->${convertTo}`];
+      if (rate === void 0) {
+        throw new Error(`money: no fx rate for "${cur}->${convertTo}"`);
+      }
+      total += convertScaled(v, desc.scaleFor(cur), rate, targetScale);
+    }
+    return formatScaledInt(total, targetScale);
+  }
+  if (desc.mode === "fixed") {
+    const cur = desc.fixedCurrency;
+    return formatScaledInt(state.get(cur) ?? 0n, desc.scaleFor(cur));
+  }
+  const out = {};
+  for (const [cur, v] of state) out[cur] = formatScaledInt(v, desc.scaleFor(cur));
+  return out;
+}
+function moneySumReducer(field, desc, convertTo, fx) {
+  return {
+    op: "sum",
+    field,
+    init: () => /* @__PURE__ */ new Map(),
+    step: (state, record) => {
+      const m = readMoney(record, field, desc);
+      if (m) state.set(m.currency, (state.get(m.currency) ?? 0n) + m.value);
+      return state;
+    },
+    remove: (state, record) => {
+      const m = readMoney(record, field, desc);
+      if (m) state.set(m.currency, (state.get(m.currency) ?? 0n) - m.value);
+      return state;
+    },
+    finalize: (state) => finalizeSum(state, desc, convertTo, fx)
+  };
+}
+function extremum(values, op) {
+  let out = values[0];
+  for (let i = 1; i < values.length; i++) {
+    const v = values[i];
+    if (op === "min" ? v < out : v > out) out = v;
+  }
+  return out;
+}
+function moneyMinMaxReducer(op, field, desc) {
+  return {
+    op,
+    field,
+    init: () => /* @__PURE__ */ new Map(),
+    step: (state, record) => {
+      const m = readMoney(record, field, desc);
+      if (m) {
+        const arr = state.get(m.currency);
+        if (arr) arr.push(m.value);
+        else state.set(m.currency, [m.value]);
+      }
+      return state;
+    },
+    remove: (state, record) => {
+      const m = readMoney(record, field, desc);
+      if (m) {
+        const arr = state.get(m.currency);
+        if (arr) {
+          const idx = arr.indexOf(m.value);
+          if (idx >= 0) arr.splice(idx, 1);
+        }
+      }
+      return state;
+    },
+    finalize: (state) => {
+      if (desc.mode === "fixed") {
+        const cur = desc.fixedCurrency;
+        const arr = state.get(cur);
+        if (!arr || arr.length === 0) return null;
+        return formatScaledInt(extremum(arr, op), desc.scaleFor(cur));
+      }
+      const out = {};
+      for (const [cur, arr] of state) {
+        if (arr.length > 0) out[cur] = formatScaledInt(extremum(arr, op), desc.scaleFor(cur));
+      }
+      return out;
+    }
+  };
+}
+function wrapMoneyReducers(spec, moneyFields) {
+  let changed = false;
+  const out = {};
+  for (const [key, reducer] of Object.entries(spec)) {
+    const field = reducer.field;
+    const desc = field ? moneyFields[field] : void 0;
+    if (desc && reducer.op === "avg") {
+      throw new MoneyUnsupportedError(
+        field,
+        `avg() is not supported on money field "${field}" in v1 \u2014 use sum() and count() and divide at the boundary.`
+      );
+    }
+    if (desc && (reducer.op === "sum" || reducer.op === "min" || reducer.op === "max")) {
+      changed = true;
+      out[key] = reducer.op === "sum" ? moneySumReducer(field, desc, reducer.convertTo, reducer.fx) : moneyMinMaxReducer(reducer.op, field, desc);
+    } else {
+      out[key] = reducer;
+    }
+  }
+  return changed ? out : spec;
+}
+
+// src/i18n/policy.ts
+function resolvePolicy(onMissing, layer) {
+  const explicit = onMissing && typeof onMissing === "object" ? onMissing[layer] : void 0;
+  const scalar = typeof onMissing === "string" ? onMissing : void 0;
+  const layerDefault = layer === "guard" ? "substitute" : void 0;
+  return explicit ?? layerDefault ?? scalar ?? "throw";
+}
+
+// src/i18n/script.ts
+var LATIN_BASE = /* @__PURE__ */ new Set([
+  "en",
+  "fr",
+  "de",
+  "es",
+  "it",
+  "pt",
+  "nl",
+  "sv",
+  "no",
+  "da",
+  "fi",
+  "is",
+  "pl",
+  "cs",
+  "sk",
+  "hu",
+  "ro",
+  "hr",
+  "sl",
+  "et",
+  "lv",
+  "lt",
+  "tr",
+  "vi",
+  "id",
+  "ms",
+  "tl",
+  "sw",
+  "af",
+  "ca",
+  "gl",
+  "eu",
+  "cy",
+  "ga"
+]);
+var SCRIPT_TABLE = {
+  th: ["Thai"],
+  ko: ["Hangul", "Han"],
+  ja: ["Han", "Hiragana", "Katakana"],
+  zh: ["Han"],
+  ar: ["Arabic"],
+  fa: ["Arabic"],
+  ur: ["Arabic"],
+  ru: ["Cyrillic"],
+  uk: ["Cyrillic"],
+  bg: ["Cyrillic"],
+  sr: ["Cyrillic"],
+  he: ["Hebrew"],
+  el: ["Greek"],
+  hi: ["Devanagari"],
+  ta: ["Tamil"],
+  km: ["Khmer"],
+  lo: ["Lao"],
+  my: ["Myanmar"]
+};
+var SUBTAG_SCRIPTS = {
+  Latn: ["Latin"],
+  Cyrl: ["Cyrillic", "Latin"],
+  Hans: ["Han", "Latin"],
+  Hant: ["Han", "Latin"],
+  Thai: ["Thai", "Latin"],
+  Arab: ["Arabic", "Latin"]
+};
+function inferScripts(locale) {
+  const parts = locale.split("-");
+  const subtag = parts.find((t) => /^[A-Z][a-z]{3}$/.test(t));
+  if (subtag && SUBTAG_SCRIPTS[subtag]) return SUBTAG_SCRIPTS[subtag];
+  const base = (parts[0] ?? "").toLowerCase();
+  if (LATIN_BASE.has(base)) return ["Latin"];
+  const primary = SCRIPT_TABLE[base];
+  if (primary) return [...primary, "Latin"];
+  return ["Latin"];
+}
+var BASELINE = String.raw`\p{White_Space}\p{Script=Common}\p{Script=Inherited}\p{Mark}`;
+
+// src/i18n/core.ts
+function toChain(fallback) {
+  return Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+}
+function pickFromChain(value, chain) {
+  for (const fb of chain) {
+    if (fb === "any") {
+      const any = Object.values(value).find((v) => v !== "");
+      if (any !== void 0) return any;
+    } else if (value[fb] !== void 0 && value[fb] !== "") {
+      return value[fb];
+    }
+  }
+  return void 0;
+}
+function resolveI18nText(value, locale, fallback, field, opts) {
+  if (locale === "raw") {
+    return value;
+  }
+  if (!locale) {
+    throw new LocaleNotSpecifiedError(field ?? "<unknown>");
+  }
+  if (value[locale] !== void 0 && value[locale] !== "") {
+    return value[locale];
+  }
+  const policy = opts?.policy ?? "throw";
+  const callerChain = toChain(fallback);
+  const callerHit = pickFromChain(value, callerChain);
+  if (callerHit !== void 0) return callerHit;
+  if (policy === "substitute") {
+    const subHit = pickFromChain(value, toChain(opts?.substitute));
+    if (subHit !== void 0) return subHit;
+    if (opts?.smartSubstitute) {
+      const smartHit = pickNearestScript(value, locale);
+      if (smartHit !== void 0) return smartHit;
+    }
+  }
+  if (policy === "throw") {
+    throw new LocaleNotSpecifiedError(
+      field ?? "<unknown>",
+      `No translation available for locale "${locale}"` + (callerChain.length > 0 ? ` or fallback chain [${callerChain.join(", ")}]` : "") + "."
+    );
+  }
+  return null;
+}
+function pickNearestScript(value, target) {
+  const targetScript = inferScripts(target)[0] ?? "Latin";
+  let best;
+  for (const [loc, v] of Object.entries(value)) {
+    if (typeof v !== "string" || v === "") continue;
+    const s = inferScripts(loc)[0] ?? "Latin";
+    const score = s === targetScript ? 0 : s === "Latin" ? 1 : 2;
+    if (best === void 0 || score < best.score) best = { score, v };
+    if (score === 0) break;
+  }
+  return best?.v;
+}
+function applyAtPath(obj, path, locale, fallback, opts) {
+  const arrayIdx = path.indexOf("[].");
+  if (arrayIdx !== -1) {
+    const arrayKey = path.slice(0, arrayIdx);
+    const restPath = path.slice(arrayIdx + 3);
+    const arr = obj[arrayKey];
+    if (!Array.isArray(arr)) return obj;
+    return {
+      ...obj,
+      [arrayKey]: arr.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+        return applyAtPath(item, restPath, locale, fallback, opts);
+      })
+    };
+  }
+  const dotIdx = path.indexOf(".");
+  if (dotIdx !== -1) {
+    const head = path.slice(0, dotIdx);
+    const rest = path.slice(dotIdx + 1);
+    const nested = obj[head];
+    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return obj;
+    return {
+      ...obj,
+      [head]: applyAtPath(nested, rest, locale, fallback, opts)
+    };
+  }
+  const raw = obj[path];
+  if (raw === void 0 || raw === null) return obj;
+  if (typeof raw !== "object" || Array.isArray(raw)) return obj;
+  return {
+    ...obj,
+    [path]: resolveI18nText(raw, locale, fallback, path, opts)
+  };
+}
+function applyI18nLocale(record, i18nFields, locale, fallback, layer = "read") {
+  const fieldNames = Object.keys(i18nFields);
+  if (fieldNames.length === 0) return record;
+  let result = record;
+  for (const [field, descriptor] of Object.entries(i18nFields)) {
+    const { onMissing, substitute, smartSubstitute } = descriptor.options;
+    const opts = {
+      policy: resolvePolicy(onMissing, layer),
+      ...substitute !== void 0 ? { substitute } : {},
+      ...smartSubstitute ? { smartSubstitute } : {}
+    };
+    result = applyAtPath(result, field, locale, fallback, opts);
+  }
+  return result;
+}
 
 // src/aggregate/groupby.ts
 var GROUPBY_WARN_CARDINALITY = 1e4;
@@ -235,15 +789,17 @@ function resetGroupByWarnings() {
   warnedCardinalityFields.clear();
 }
 var GroupedQueryBase = class {
-  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver) {
+  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver, moneyFields) {
     this.executeRecords = executeRecords;
     this.upstreams = upstreams;
     this.dictLabelResolver = dictLabelResolver;
+    this.moneyFields = moneyFields;
     this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
   }
   executeRecords;
   upstreams;
   dictLabelResolver;
+  moneyFields;
   /**
    * Field set this grouped query buckets on. Stored in declaration
    * order — the same order is preserved on every result row by
@@ -251,6 +807,10 @@ var GroupedQueryBase = class {
    * `[field]`.
    */
   fields;
+  /** Apply money-aware reducer rewriting when money fields are declared. */
+  wrapSpec(spec) {
+    return this.moneyFields ? wrapMoneyReducers(spec, this.moneyFields) : spec;
+  }
 };
 var GroupedQuery = class extends GroupedQueryBase {
   /**
@@ -263,7 +823,7 @@ var GroupedQuery = class extends GroupedQueryBase {
     return new GroupedAggregation(
       this.executeRecords,
       this.fields,
-      spec,
+      this.wrapSpec(spec),
       this.upstreams,
       this.dictLabelResolver
     );
@@ -274,17 +834,20 @@ var GroupedQueryN = class extends GroupedQueryBase {
     return new GroupedAggregation(
       this.executeRecords,
       this.fields,
-      spec,
+      this.wrapSpec(spec),
       this.upstreams,
       this.dictLabelResolver
     );
   }
 };
-function groupAndReduce(records, fieldOrFields, spec) {
+function groupAndReduce(records, fieldOrFields, spec, moneyFields) {
   const fields = typeof fieldOrFields === "string" ? [fieldOrFields] : fieldOrFields;
   if (fields.length === 0) {
     throw new Error(".groupBy() requires at least one field");
   }
+  if (moneyFields) {
+    spec = wrapMoneyReducers(spec, moneyFields);
+  }
   const buckets = /* @__PURE__ */ new Map();
   const fieldLabel = fields.length === 1 ? fields[0] : `[${fields.join(", ")}]`;
   for (const record of records) {
@@ -346,9 +909,29 @@ var GroupedAggregation = class {
   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 return an array of rows.
+   *
+   * `opts` (#285 query-form MV grouping): when a `locale` + `i18nFields` are
+   * given, the declared group-key `i18nText` fields are resolved to that locale
+   * at the `mv` layer BEFORE bucketing — so an i18n group key is a stable string
+   * instead of a raw `{locale}` map. The MV executor passes the MV's
+   * `i18nLocale`/`i18nFields`; ordinary `.run()` callers pass nothing and are
+   * unaffected.
+   */
+  run(opts) {
+    let records = this.executeRecords();
+    if (opts?.locale !== void 0 && opts.i18nFields !== void 0) {
+      const groupI18n = {};
+      for (const f of this.fields) {
+        const d = opts.i18nFields[f];
+        if (d !== void 0) groupI18n[f] = d;
+      }
+      if (Object.keys(groupI18n).length > 0) {
+        records = records.map((r) => applyI18nLocale(r, groupI18n, opts.locale, void 0, "mv"));
+      }
+    }
+    return groupAndReduce(records, this.fields, this.spec);
   }
   /**
    * Execute the query, group, reduce, and resolve `<field>Label` for
@@ -408,11 +991,11 @@ function withAggregate() {
     aggregate(executeRecords, spec, upstreams) {
       return new Aggregation(executeRecords, spec, upstreams);
     },
-    groupBy(executeRecords, field, upstreams, dictLabelResolver) {
-      return new GroupedQuery(executeRecords, field, upstreams, dictLabelResolver);
+    groupBy(executeRecords, field, upstreams, dictLabelResolver, moneyFields) {
+      return new GroupedQuery(executeRecords, field, upstreams, dictLabelResolver, moneyFields);
     },
-    groupByN(executeRecords, fields, upstreams) {
-      return new GroupedQueryN(executeRecords, fields, upstreams);
+    groupByN(executeRecords, fields, upstreams, moneyFields) {
+      return new GroupedQueryN(executeRecords, fields, upstreams, void 0, moneyFields);
     },
     async scanAggregate(iter, spec) {
       const collected = [];
@@ -427,26 +1010,37 @@ function count(opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "count",
     init: () => 0,
     step: (state) => state + 1,
     remove: (state) => state - 1,
-    finalize: (state) => state
+    finalize: (state) => state,
+    merge: (a, b) => a + b
   };
 }
 function sum(field, opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "sum",
+    field,
+    // Money-only metadata, read by `wrapMoneyReducers`. No effect on a
+    // generic numeric sum.
+    ...opts?.convertTo !== void 0 ? { convertTo: opts.convertTo } : {},
+    ...opts?.fx !== void 0 ? { fx: opts.fx } : {},
     init: () => 0,
     step: (state, record) => state + readNumber(record, field),
     remove: (state, record) => state - readNumber(record, field),
-    finalize: (state) => state
+    finalize: (state) => state,
+    merge: (a, b) => a + b
   };
 }
 function avg(field, opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "avg",
+    field,
     init: () => ({ sum: 0, count: 0 }),
     step: (state, record) => ({
       sum: state.sum + readNumber(record, field),
@@ -456,7 +1050,8 @@ function avg(field, opts) {
       sum: state.sum - readNumber(record, field),
       count: state.count - 1
     }),
-    finalize: (state) => state.count === 0 ? null : state.sum / state.count
+    finalize: (state) => state.count === 0 ? null : state.sum / state.count,
+    merge: (a, b) => ({ sum: a.sum + b.sum, count: a.count + b.count })
   };
 }
 function pushValue(state, value) {
@@ -473,6 +1068,8 @@ function min(field, opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "min",
+    field,
     init: () => ({ values: [] }),
     step: (state, record) => pushValue(state, readNumber(record, field)),
     remove: (state, record) => removeValue(state, readNumber(record, field)),
@@ -484,13 +1081,16 @@ function min(field, opts) {
         if (v < out) out = v;
       }
       return out;
-    }
+    },
+    merge: (a, b) => ({ values: [...a.values, ...b.values] })
   };
 }
 function max(field, opts) {
   const _seed = opts?.seed;
   void _seed;
   return {
+    op: "max",
+    field,
     init: () => ({ values: [] }),
     step: (state, record) => pushValue(state, readNumber(record, field)),
     remove: (state, record) => removeValue(state, readNumber(record, field)),
@@ -502,11 +1102,17 @@ function max(field, opts) {
         if (v > out) out = v;
       }
       return out;
-    }
+    },
+    merge: (a, b) => ({ values: [...a.values, ...b.values] })
   };
 }
 function readNumber(record, field) {
   const value = readPath(record, field);
+  if (typeof value === "object" && value !== null && "amount" in value && "currency" in value) {
+    throw new Error(
+      `aggregate: field "${field}" holds a money value but was not money-aware \u2014 declare it in the collection's moneyFields so sum/min/max stay exact`
+    );
+  }
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 // Annotate the CommonJS export names for ESM import in node: