@noy-db/hub 0.2.0-pre.13 → 0.2.0-pre.15

package/dist/bundle/index.cjs

@@ -31,7 +31,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/errors.ts
-var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, UnknownShardError, ShardProvisioningError, VaultTemplateNotFoundError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, UnknownShardError, ShardProvisioningError, CrossShardJoinError, VaultTemplateNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -746,6 +746,12 @@ Resolutions:
         this.vaultId = vaultId;
       }
     };
+    CrossShardJoinError = class extends NoydbError {
+      constructor(message) {
+        super("CROSS_SHARD_JOIN", message);
+        this.name = "CrossShardJoinError";
+      }
+    };
     VaultTemplateNotFoundError = class extends NoydbError {
       templateName;
       constructor(templateName) {
@@ -3888,6 +3894,115 @@ var init_descriptor = __esm({
   }
 });
 
+// src/money/paths.ts
+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 clone3 = { ...obj2 };
+    if (last) {
+      visit(clone3, seg.key);
+    } else {
+      clone3[seg.key] = transformAtMoneyPath(clone3[seg.key], path, segments, index + 1, visit, lenient);
+    }
+    return clone3;
+  }
+  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 clone2 = { ...obj };
+  for (const key of Object.keys(obj)) {
+    const v = clone2[key];
+    if (v === null || v === void 0) continue;
+    if (last) visit(clone2, key);
+    else clone2[key] = transformAtMoneyPath(v, path, segments, index + 1, visit, lenient);
+  }
+  return clone2;
+}
+var SEGMENT_RE, parseCache;
+var init_paths = __esm({
+  "src/money/paths.ts"() {
+    "use strict";
+    init_errors();
+    SEGMENT_RE = /^(\*|[^.[\]*]+)(\[\])?$/;
+    parseCache = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/money/normalize.ts
 function isMoneyValueObject(v) {
   return typeof v === "object" && v !== null && "currency" in v;
@@ -3900,33 +4015,68 @@ function quantizeAmount(field, input, scale, rounding) {
   }
   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) {
-  const out = { ...record };
-  for (const [field, desc] of Object.entries(moneyFields)) {
-    const raw = out[field];
-    if (raw === null || raw === void 0) continue;
-    if (desc.mode === "fixed") {
-      const currency2 = desc.fixedCurrency;
-      out[field] = quantizeAmount(field, raw, desc.scaleFor(currency2), desc.rounding);
+  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;
     }
-    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);
-    out[field] = { amount: quantizeAmount(field, amount, scale, desc.rounding), currency };
+    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;
 }
@@ -3939,33 +4089,70 @@ function formatCurrency(decimal, currency, scale, locale) {
   });
   return fmt.format(decimal);
 }
+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) {
-  const out = { ...record };
+  let out = { ...record };
   const format = locale !== "raw";
   const fmtLocale = typeof locale === "string" && locale !== "raw" ? locale : "en-US";
-  for (const [field, desc] of Object.entries(moneyFields)) {
-    const stored = out[field];
-    if (stored === null || stored === void 0) continue;
-    let currency;
-    let scaledIntString;
-    if (desc.mode === "fixed") {
-      if (typeof stored !== "string" && typeof stored !== "number") continue;
-      currency = desc.fixedCurrency;
-      scaledIntString = String(stored);
-    } else {
-      if (!isMoneyValueObject(stored)) continue;
-      const amount = stored.amount;
-      if (typeof stored.currency !== "string" || typeof amount !== "string" && typeof amount !== "number") continue;
-      currency = stored.currency;
-      scaledIntString = String(amount);
-    }
-    const scale = desc.scaleFor(currency);
-    const decimal = formatScaledInt(BigInt(scaledIntString), scale);
-    out[field] = desc.mode === "fixed" ? decimal : { amount: decimal, currency };
-    if (format) {
-      out[`${field}Formatted`] = formatCurrency(decimal, currency, scale, fmtLocale);
-      out[`${field}Number`] = Number(decimal);
+  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;
 }
@@ -3974,6 +4161,7 @@ var init_normalize = __esm({
     "use strict";
     init_fixed_point();
     init_descriptor();
+    init_paths();
   }
 });
 
@@ -4146,6 +4334,146 @@ var init_strategy3 = __esm({
   }
 });
 
+// src/money/where.ts
+function isMoneyValueObject2(v) {
+  return typeof v === "object" && v !== null && "currency" in v;
+}
+function parseOperand(field, raw, desc) {
+  let amount;
+  let currency;
+  if (desc.mode === "fixed") {
+    currency = desc.fixedCurrency;
+    amount = raw;
+  } else if (isMoneyValueObject2(raw)) {
+    currency = String(raw.currency);
+    amount = raw.amount;
+  } else {
+    const sole = desc.soleCurrency();
+    if (sole === void 0) {
+      throw new MoneyUnsupportedError(
+        `where("${field}"): field is multi-currency \u2014 compare against { amount, currency }, not a bare amount`
+      );
+    }
+    currency = sole;
+    amount = raw;
+  }
+  if (typeof amount !== "number" && typeof amount !== "string") {
+    throw new MoneyUnsupportedError(
+      `where("${field}"): operand ${JSON.stringify(raw)} is not a money amount`
+    );
+  }
+  const r = parseToScaledInt(amount, desc.scaleFor(currency), desc.rounding);
+  if (!r.ok) {
+    throw new MoneyUnsupportedError(
+      `where("${field}"): operand ${JSON.stringify(amount)} is not a finite decimal`
+    );
+  }
+  return { scaled: r.value.toString(), currency };
+}
+function moneyFieldClause(field, op, value, desc) {
+  switch (op) {
+    case "==":
+    case "!=":
+    case "<":
+    case "<=":
+    case ">":
+    case ">=": {
+      const e = parseOperand(field, value, desc);
+      return withMoney(field, op, value, desc, [e]);
+    }
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) {
+        throw new MoneyUnsupportedError(`where("${field}"): 'between' needs a [lo, hi] tuple`);
+      }
+      const lo = parseOperand(field, value[0], desc);
+      const hi = parseOperand(field, value[1], desc);
+      if (lo.currency !== hi.currency) {
+        throw new MoneyUnsupportedError(
+          `where("${field}"): 'between' bounds mix currencies (${lo.currency} vs ${hi.currency})`
+        );
+      }
+      return withMoney(field, op, value, desc, [lo, hi]);
+    }
+    case "in": {
+      if (!Array.isArray(value)) {
+        throw new MoneyUnsupportedError(`where("${field}"): 'in' needs an array of amounts`);
+      }
+      return withMoney(field, op, value, desc, value.map((v) => parseOperand(field, v, desc)));
+    }
+    default:
+      throw new MoneyUnsupportedError(
+        `where("${field}"): operator '${op}' is not supported on a money field`
+      );
+  }
+}
+function withMoney(field, op, originalValue, desc, entries) {
+  const money = { mode: desc.mode, entries };
+  const value = desc.mode !== "fixed" ? originalValue : entries.length === 1 && op !== "in" && op !== "between" ? entries[0].scaled : entries.map((e) => e.scaled);
+  return { type: "field", field, op, value, money };
+}
+function readStored(actual, operand) {
+  let amount;
+  let currency;
+  if (operand.mode === "fixed") {
+    if (typeof actual !== "string" && typeof actual !== "number") return null;
+    amount = actual;
+    currency = operand.entries[0]?.currency ?? "";
+  } else {
+    if (!isMoneyValueObject2(actual)) return null;
+    if (typeof actual.currency !== "string") return null;
+    amount = actual.amount;
+    currency = actual.currency;
+  }
+  if (typeof amount !== "string" && typeof amount !== "number") return null;
+  try {
+    return { scaled: BigInt(amount).toString(), currency };
+  } catch {
+    return null;
+  }
+}
+function evaluateMoneyClause(actual, op, operand) {
+  const stored = readStored(actual, operand);
+  if (stored === null) return op === "!=";
+  const a = BigInt(stored.scaled);
+  if (op === "in") {
+    return operand.entries.some(
+      (e2) => e2.currency === stored.currency && BigInt(e2.scaled) === a
+    );
+  }
+  if (op === "between") {
+    const [lo, hi] = operand.entries;
+    if (!lo || !hi || lo.currency !== stored.currency) return false;
+    return a >= BigInt(lo.scaled) && a <= BigInt(hi.scaled);
+  }
+  const e = operand.entries[0];
+  if (!e) return false;
+  if (e.currency !== stored.currency) return op === "!=";
+  const b = BigInt(e.scaled);
+  switch (op) {
+    case "==":
+      return a === b;
+    case "!=":
+      return a !== b;
+    case "<":
+      return a < b;
+    case "<=":
+      return a <= b;
+    case ">":
+      return a > b;
+    case ">=":
+      return a >= b;
+    default:
+      return false;
+  }
+}
+var init_where = __esm({
+  "src/money/where.ts"() {
+    "use strict";
+    init_fixed_point();
+    init_descriptor();
+  }
+});
+
 // src/query/predicate.ts
 function readPath(record, path) {
   if (record === null || record === void 0) return void 0;
@@ -4163,6 +4491,7 @@ function readPath(record, path) {
 function evaluateFieldClause(record, clause) {
   const actual = readPath(record, clause.field);
   const { op, value } = clause;
+  if (clause.money) return evaluateMoneyClause(actual, op, clause.money);
   switch (op) {
     case "==":
       return actual === value;
@@ -4203,14 +4532,14 @@ function isComparable(a, b) {
   if (a instanceof Date && b instanceof Date) return true;
   return false;
 }
-function evaluateClause(record, clause) {
+function evaluateClause(record, clause, fnRecord) {
   switch (clause.type) {
     case "field":
       return evaluateFieldClause(record, clause);
     case "filter":
-      return clause.fn(record);
+      return clause.fn(fnRecord !== void 0 ? fnRecord : record);
     case "wherePredicate":
-      return clause.fn(record, clause.ctx);
+      return clause.fn(fnRecord !== void 0 ? fnRecord : record, clause.ctx);
     case "crossJoin":
       throw new Error(
         `evaluateClause: 'crossJoin' clauses are expansion primitives and are not evaluated per-record. This is a query planner routing error \u2014 crossJoin clauses must be extracted from the clause list before calling evaluateClause or filterRecords.`
@@ -4218,20 +4547,28 @@ function evaluateClause(record, clause) {
     case "group":
       if (clause.op === "and") {
         for (const child of clause.clauses) {
-          if (!evaluateClause(record, child)) return false;
+          if (!evaluateClause(record, child, fnRecord)) return false;
         }
         return true;
       } else {
         for (const child of clause.clauses) {
-          if (evaluateClause(record, child)) return true;
+          if (evaluateClause(record, child, fnRecord)) return true;
         }
         return false;
       }
   }
 }
+function hasFnClause(clauses) {
+  for (const c of clauses) {
+    if (c.type === "filter" || c.type === "wherePredicate") return true;
+    if (c.type === "group" && hasFnClause(c.clauses)) return true;
+  }
+  return false;
+}
 var init_predicate = __esm({
   "src/query/predicate.ts"() {
     "use strict";
+    init_where();
   }
 });
 
@@ -4692,7 +5029,7 @@ 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);
@@ -4715,6 +5052,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);
@@ -4742,13 +5080,20 @@ function materializeIds(ids, lookupById) {
   }
   return out;
 }
-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;
       }
@@ -4760,10 +5105,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);
@@ -4776,7 +5122,7 @@ function executeClausePipeline(source, clauses, joinContext) {
     }
   }
   if (filterBatch.length > 0) {
-    rel = filterRecords(rel, filterBatch);
+    rel = filterRecords(rel, filterBatch, decodeForFns);
   }
   return rel;
 }
@@ -4957,6 +5303,7 @@ var init_builder = __esm({
     init_strategy4();
     init_money_reducer();
     init_normalize();
+    init_where();
     EMPTY_PLAN = {
       clauses: [],
       orderBy: [],
@@ -5048,9 +5395,18 @@ var init_builder = __esm({
           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] },
@@ -5376,7 +5732,7 @@ var init_builder = __esm({
         }
         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.
@@ -5433,7 +5789,7 @@ var init_builder = __esm({
             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) {
@@ -5456,7 +5812,7 @@ var init_builder = __esm({
             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) {
@@ -5729,6 +6085,7 @@ var init_scan_builder = __esm({
     init_predicate();
     init_errors();
     init_normalize();
+    init_where();
     DEFAULT_SCAN_PAGE_SIZE = 100;
     ScanBuilder = class _ScanBuilder {
       pageProvider;
@@ -5792,7 +6149,8 @@ var init_scan_builder = __esm({
        * 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,
@@ -6138,8 +6496,9 @@ var init_scan_builder = __esm({
        */
       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;
       }
@@ -7680,6 +8039,7 @@ var init_collection = __esm({
     init_strategy();
     init_core();
     init_normalize();
+    init_paths();
     init_computed();
     init_strategy2();
     init_policy();
@@ -8002,6 +8362,7 @@ var init_collection = __esm({
         this.joinResolver = opts.joinResolver;
         this.i18nFields = opts.i18nFields;
         this.dictKeyFields = opts.dictKeyFields;
+        if (opts.moneyFields) validateMoneyFieldPaths(opts.moneyFields);
         this.moneyFields = opts.moneyFields;
         this.computed = opts.computed;
         this.dictLabelResolver = opts.dictLabelResolver;
@@ -8135,7 +8496,9 @@ var init_collection = __esm({
        * declaration; this reconciles that ordering. First-wins. Not public.
        */
       _applyMoneyFields(moneyFields) {
-        if (this.moneyFields === void 0) this.moneyFields = moneyFields;
+        if (this.moneyFields !== void 0) return;
+        validateMoneyFieldPaths(moneyFields);
+        this.moneyFields = moneyFields;
       }
       /** @internal — attach computed fields post-construction. See {@link _applyMoneyFields}. */
       _applyComputed(computed) {
@@ -8302,6 +8665,7 @@ var init_collection = __esm({
         if (!hasWritePermission(this.keyring, this.name)) {
           throw new ReadOnlyError();
         }
+        record = canonicalizeIncomingMoney(record, this.moneyFields);
         if (this.subsystemBus?.hasGateHandlers("beforePut")) {
           const existingEnv = await this.adapter.get(this.vault, this.name, id);
           let existingRecord = null;
@@ -8318,7 +8682,7 @@ var init_collection = __esm({
             collection: this.name,
             docId: id,
             incoming: record,
-            existing: existingRecord,
+            existing: canonicalizeStoredMoney(existingRecord, this.moneyFields),
             existingVersion: existingEnv?._v ?? 0,
             existingTs: existingEnv?._ts,
             userId: this.keyring.userId,
@@ -8587,7 +8951,7 @@ var init_collection = __esm({
        */
       async dispatchDerivations(id, record, version) {
         if (this.derivationSource === void 0) return;
-        const incoming = record;
+        const incoming = canonicalizeStoredMoney(record, this.moneyFields);
         if (incoming && typeof incoming === "object" && "_derivedFrom" in incoming) return;
         const registry = this.derivationSource.registry();
         const strategies = registry.strategiesForSource(this.name);
@@ -8820,7 +9184,7 @@ var init_collection = __esm({
               vault: this.vault,
               collection: this.name,
               docId: id,
-              existing: existingRecord,
+              existing: canonicalizeStoredMoney(existingRecord, this.moneyFields),
               existingVersion: existingEnv._v,
               existingTs: existingEnv._ts,
               internal,
@@ -17203,6 +17567,54 @@ var init_classify_skip = __esm({
   }
 });
 
+// src/federation/cross-shard-join.ts
+function coerceKey(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return null;
+}
+function warnOnceBroadcastMiss(field, as, key) {
+  const dedup = `${field}\u2192${as}:${key}`;
+  if (warnedBroadcastKeys.has(dedup)) return;
+  warnedBroadcastKeys.add(dedup);
+  console.warn(
+    `[noy-db] broadcastJoin: no "${as}" dimension row for ${field}="${key}". Attaching null. Use mode: 'cascade' to silence.`
+  );
+}
+async function applyBroadcastLegs(rows, legs) {
+  if (legs.length === 0) return [...rows];
+  const indexes = [];
+  for (const leg of legs) {
+    const map = /* @__PURE__ */ new Map();
+    for (const rec of await leg.from.list()) {
+      const k = coerceKey(readPath(rec, leg.on));
+      if (k !== null && !map.has(k)) map.set(k, rec);
+    }
+    indexes.push({ leg, map });
+  }
+  return rows.map((row) => {
+    const out = { ...row };
+    for (const { leg, map } of indexes) {
+      const key = coerceKey(readPath(row, leg.field));
+      const match = key === null ? null : map.get(key) ?? null;
+      if (match === null && leg.mode === "warn") {
+        warnOnceBroadcastMiss(leg.field, leg.as, key ?? "<null>");
+      }
+      out[leg.as] = match;
+    }
+    return out;
+  });
+}
+var warnedBroadcastKeys;
+var init_cross_shard_join = __esm({
+  "src/federation/cross-shard-join.ts"() {
+    "use strict";
+    init_predicate();
+    warnedBroadcastKeys = /* @__PURE__ */ new Set();
+  }
+});
+
 // src/federation/cross-vault-live.ts
 var CrossVaultLive;
 var init_cross_vault_live = __esm({
@@ -17431,6 +17843,7 @@ var init_vault_group = __esm({
     init_errors();
     init_constants2();
     init_classify_skip();
+    init_cross_shard_join();
     init_cross_vault_live();
     init_aggregate_across();
     SHARD_SEPARATOR = "--";
@@ -17594,31 +18007,89 @@ var init_vault_group = __esm({
       }
     };
     ShardedQuery = class _ShardedQuery {
-      constructor(group, collectionName, clauses) {
+      constructor(group, collectionName, clauses, coPartitionedLegs = [], broadcastLegs = []) {
         this.group = group;
         this.collectionName = collectionName;
         this.clauses = clauses;
+        this.coPartitionedLegs = coPartitionedLegs;
+        this.broadcastLegs = broadcastLegs;
       }
       group;
       collectionName;
       clauses;
+      coPartitionedLegs;
+      broadcastLegs;
       where(field, op, value) {
-        return new _ShardedQuery(this.group, this.collectionName, [
-          ...this.clauses,
-          { field, op, value }
-        ]);
+        return new _ShardedQuery(
+          this.group,
+          this.collectionName,
+          [...this.clauses, { field, op, value }],
+          this.coPartitionedLegs,
+          this.broadcastLegs
+        );
+      }
+      /** Co-partitioned join: each shard joins its own same-vault right collection (resolved via ref()), then union. */
+      crossShardJoin(field, opts) {
+        const leg = { field, as: opts.as, maxRows: opts.maxRows, strategy: opts.strategy };
+        return new _ShardedQuery(
+          this.group,
+          this.collectionName,
+          this.clauses,
+          [...this.coPartitionedLegs, leg],
+          this.broadcastLegs
+        );
+      }
+      /** Broadcast dimension join: enrich every merged row from a single shared collection. */
+      broadcastJoin(field, opts) {
+        const leg = {
+          field,
+          as: opts.as,
+          from: opts.from,
+          on: opts.on ?? "id",
+          mode: opts.mode ?? "warn"
+        };
+        return new _ShardedQuery(
+          this.group,
+          this.collectionName,
+          this.clauses,
+          this.coPartitionedLegs,
+          [...this.broadcastLegs, leg]
+        );
       }
       /** @internal — fan out the where-filtered records across eligible shards. */
       async fanoutRecords(options = {}) {
         const { eligible, skipped } = await this.group.resolveEligible(options);
+        const probeRow = eligible[0];
+        if (this.coPartitionedLegs.length > 0 && probeRow) {
+          const probe = await this.group.openShard(probeRow.partitionKey);
+          this.group.template.configure(probe);
+          for (const leg of this.coPartitionedLegs) {
+            if (!probe.resolveRef(this.collectionName, leg.field)) {
+              throw new CrossShardJoinError(
+                `crossShardJoin("${leg.field}"): no ref() declared for "${leg.field}" on collection "${this.collectionName}" in template "${this.group.sharding.vaultTemplate}". Add refs: { ${leg.field}: ref('<target>') } to the template's collection options.`
+              );
+            }
+          }
+        }
         const across = await this.group.db.queryAcross(
           eligible.map((r) => r.vaultId),
           async (vault) => {
             this.group.template.configure(vault);
             const coll = vault.collection(this.collectionName);
             await coll.list();
+            for (const leg of this.coPartitionedLegs) {
+              const desc = vault.resolveRef(this.collectionName, leg.field);
+              if (desc) await vault.collection(desc.target).list();
+            }
             let q = coll.query();
             for (const c of this.clauses) q = q.where(c.field, c.op, c.value);
+            for (const leg of this.coPartitionedLegs) {
+              q = q.join(leg.field, {
+                as: leg.as,
+                ...leg.maxRows !== void 0 ? { maxRows: leg.maxRows } : {},
+                ...leg.strategy ? { strategy: leg.strategy } : {}
+              });
+            }
             return q.toArray();
           },
           { concurrency: options.concurrency ?? 1, create: false }
@@ -17630,10 +18101,11 @@ var init_vault_group = __esm({
         }
         return { records: results, skippedVaults: skipped };
       }
-      /** Fan out across eligible shards and merge results. */
+      /** Fan out across eligible shards, merge, then apply any broadcast dimension legs. */
       async toArray(options = {}) {
         const { records, skippedVaults } = await this.fanoutRecords(options);
-        return { results: records, skippedVaults };
+        const results = await applyBroadcastLegs(records, this.broadcastLegs);
+        return { results, skippedVaults };
       }
       /** @internal — build the change-subscription + relevance binding for this query's group+collection. */
       liveBinding() {
@@ -17647,8 +18119,17 @@ var init_vault_group = __esm({
           isRelevant: (e) => e.collection === collectionName && e.vault.startsWith(`${group.name}--`)
         };
       }
+      /** @internal — joined queries don't support reactive/aggregate surfaces in v1. */
+      assertNoJoinLegs(surface) {
+        if (this.coPartitionedLegs.length || this.broadcastLegs.length) {
+          throw new CrossShardJoinError(
+            `${surface}() is not supported on a ShardedQuery with crossShardJoin/broadcastJoin legs in v1. Use toArray() for joined cross-shard queries.`
+          );
+        }
+      }
       /** Returns a reactive cross-shard live query — a facade over CrossVaultLive. */
       live(options = {}) {
+        this.assertNoJoinLegs("live");
         const bind = this.liveBinding();
         const core = new CrossVaultLive({
           ...bind,
@@ -17676,10 +18157,12 @@ var init_vault_group = __esm({
       }
       /** One-shot distributed aggregate — central reduce over all shard records. */
       aggregate(spec) {
+        this.assertNoJoinLegs("aggregate");
         return new CrossVaultAggregation(this, spec, this.liveBinding());
       }
       /** Begin a grouped cross-shard aggregate. */
       groupBy(field) {
+        this.assertNoJoinLegs("groupBy");
         return new ShardedGroupedQuery(this, field);
       }
     };