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

package/dist/index.cjs

@@ -46,7 +46,7 @@ var init_types = __esm({
 });
 
 // src/errors.ts
-var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, PeriodClosedError, RecordLockedError, FieldFrozenError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, ScriptViolationError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, SnapshotNotFoundError, UnknownShardError, ShardProvisioningError, VaultTemplateNotFoundError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, PeriodClosedError, RecordLockedError, FieldFrozenError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, ScriptViolationError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, SnapshotNotFoundError, UnknownShardError, ShardProvisioningError, CrossShardJoinError, VaultTemplateNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -988,6 +988,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) {
@@ -2391,6 +2397,30 @@ function parseToScaledInt(input, scale, rounding) {
   }
   return { ok: true, value: negative && magnitude !== 0n ? -magnitude : magnitude };
 }
+function decimalScaleOf(input) {
+  const s = toCanonicalDecimalString(input);
+  if (s === null) return null;
+  const dot = s.indexOf(".");
+  return dot === -1 ? 0 : s.length - dot - 1;
+}
+function rescaleScaledInt(value, fromScale, toScale, rounding = "half-up") {
+  if (toScale >= fromScale) return value * 10n ** BigInt(toScale - fromScale);
+  const drop = fromScale - toScale;
+  const negative = value < 0n;
+  const absStr = (negative ? -value : value).toString().padStart(drop + 1, "0");
+  const keptStr = absStr.slice(0, absStr.length - drop);
+  const tail = absStr.slice(absStr.length - drop);
+  let magnitude = BigInt(keptStr);
+  if (!/^0+$/.test(tail)) {
+    const lastKeptDigit = Number(keptStr[keptStr.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 negative && magnitude !== 0n ? -magnitude : magnitude;
+}
 function formatScaledInt(value, scale) {
   const negative = value < 0n;
   const abs = (negative ? -value : value).toString();
@@ -2610,6 +2640,146 @@ var init_tiers = __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 money2 = { 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: money2 };
+}
+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;
@@ -2627,6 +2797,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;
@@ -2667,14 +2838,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.`
@@ -2682,20 +2853,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();
   }
 });
 
@@ -4619,6 +4798,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({
@@ -4847,6 +5074,7 @@ var init_vault_group = __esm({
     init_errors();
     init_constants();
     init_classify_skip();
+    init_cross_shard_join();
     init_cross_vault_live();
     init_aggregate_across();
     SHARD_SEPARATOR = "--";
@@ -5010,31 +5238,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 }
@@ -5046,10 +5332,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() {
@@ -5063,8 +5350,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,
@@ -5092,10 +5388,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);
       }
     };
@@ -5452,9 +5750,11 @@ __export(src_exports, {
   WeakPassphraseError: () => WeakPassphraseError,
   activeSessionCount: () => activeSessionCount,
   additiveOnly: () => additiveOnly,
+  allocate: () => allocate,
   applyI18nLocale: () => applyI18nLocale,
   applyJoins: () => applyJoins,
   applyPatch: () => applyPatch,
+  asMoney: () => asMoney,
   assertStrongPassphrase: () => assertStrongPassphrase,
   assertTierAccess: () => assertTierAccess,
   avg: () => avg,
@@ -5531,6 +5831,7 @@ __export(src_exports, {
   isI18nTextDescriptor: () => isI18nTextDescriptor,
   isMagicLinkGrantExpired: () => isMagicLinkGrantExpired,
   isMoneyDescriptor: () => isMoneyDescriptor,
+  isMoneyString: () => isMoneyString,
   isPreCompressed: () => isPreCompressed,
   isPublicEnvelope: () => isPublicEnvelope,
   isSessionAlive: () => isSessionAlive,
@@ -5563,6 +5864,8 @@ __export(src_exports, {
   mintShamirRecoveryEntry: () => mintShamirRecoveryEntry,
   mintWrappedDeksBlob: () => mintWrappedDeksBlob,
   money: () => money,
+  moneyNumber: () => moneyNumber,
+  mulRate: () => mulRate,
   paddedIndex: () => paddedIndex,
   parseBytes: () => parseBytes,
   parseIndex: () => parseIndex,
@@ -11454,6 +11757,111 @@ function applyI18nLocale(record, i18nFields, locale, fallback, layer = "read") {
 // src/money/normalize.ts
 init_fixed_point();
 init_descriptor();
+
+// src/money/paths.ts
+init_errors();
+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 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;
+}
+
+// src/money/normalize.ts
 function isMoneyValueObject(v) {
   return typeof v === "object" && v !== null && "currency" in v;
 }
@@ -11465,33 +11873,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;
 }
@@ -11504,33 +11947,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;
 }
@@ -11883,6 +12363,7 @@ var NO_AGGREGATE = {
 
 // src/query/builder.ts
 init_money_reducer();
+init_where();
 var EMPTY_PLAN = {
   clauses: [],
   orderBy: [],
@@ -11974,9 +12455,18 @@ var Query = class _Query {
       this.predicates
     );
   }
-  /** Add a field comparison. Multiple where() calls are AND-combined. */
+  /**
+   * Add a field comparison. Multiple where() calls are AND-combined.
+   *
+   * A declared money field compares in MAJOR units (#336): the operand
+   * (`10000`, `'10000.00'`, or `{ amount, currency }` in multi mode) is
+   * quantized into stored scaled-int space at build time and evaluated
+   * BigInt-exact per record. A malformed operand or a string operator
+   * (`contains`/`startsWith`) throws here, at the call site.
+   */
   where(field, op, value) {
-    const clause = { type: "field", field, op, value };
+    const desc = this.source.moneyFields?.[field];
+    const clause = desc ? moneyFieldClause(field, op, value, desc) : { type: "field", field, op, value };
     return new _Query(
       this.source,
       { ...this.plan, clauses: [...this.plan.clauses, clause] },
@@ -12302,7 +12792,7 @@ 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.
@@ -12359,7 +12849,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) {
@@ -12382,7 +12872,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) {
@@ -12534,7 +13024,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);
@@ -12557,6 +13047,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);
@@ -12602,13 +13093,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;
       }
@@ -12620,10 +13118,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);
@@ -12636,7 +13135,7 @@ function executeClausePipeline(source, clauses, joinContext) {
     }
   }
   if (filterBatch.length > 0) {
-    rel = filterRecords(rel, filterBatch);
+    rel = filterRecords(rel, filterBatch, decodeForFns);
   }
   return rel;
 }
@@ -13054,6 +13553,7 @@ init_groupby();
 // src/query/scan-builder.ts
 init_predicate();
 init_errors();
+init_where();
 var DEFAULT_SCAN_PAGE_SIZE = 100;
 var ScanBuilder = class _ScanBuilder {
   pageProvider;
@@ -13117,7 +13617,8 @@ 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,
@@ -13463,8 +13964,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;
   }
@@ -14628,6 +15130,7 @@ var Collection = class {
     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;
@@ -14761,7 +15264,9 @@ var Collection = class {
    * 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) {
@@ -14928,6 +15433,7 @@ var Collection = class {
     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;
@@ -14944,7 +15450,7 @@ var Collection = class {
         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,
@@ -15213,7 +15719,7 @@ var Collection = class {
    */
   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);
@@ -15446,7 +15952,7 @@ var Collection = class {
           vault: this.vault,
           collection: this.name,
           docId: id,
-          existing: existingRecord,
+          existing: canonicalizeStoredMoney(existingRecord, this.moneyFields),
           existingVersion: existingEnv._v,
           existingTs: existingEnv._ts,
           internal,
@@ -25643,9 +26149,9 @@ function withMaterializedView(spec) {
     throw new ValidationError("withMaterializedView: query must be a function returning a Query<T>");
   }
   if (spec.unionSources) {
-    if (spec.unionSources.length < 2) {
+    if (spec.unionSources.length < 1) {
       throw new MaterializedViewConfigError(
-        "unionSources requires at least 2 source collections"
+        "unionSources requires at least 1 source collection"
       );
     }
     const seen = /* @__PURE__ */ new Set();
@@ -25737,6 +26243,117 @@ init_errors();
 init_descriptor();
 init_iso4217();
 
+// src/money/arith.ts
+init_fixed_point();
+init_descriptor();
+function parseAmount(label, amount, scale, rounding) {
+  const r = parseToScaledInt(amount, scale, rounding);
+  if (!r.ok) {
+    throw new MoneyUnsupportedError(
+      r.reason === "precision" ? `${label}: amount ${JSON.stringify(amount)} has more precision than scale ${scale} and no rounding mode is configured` : `${label}: amount ${JSON.stringify(amount)} is not a finite decimal`
+    );
+  }
+  return r.value;
+}
+function resolveScale(label, amount, explicit) {
+  if (explicit !== void 0) {
+    if (!Number.isInteger(explicit) || explicit < 0) {
+      throw new MoneyUnsupportedError(`${label}: scale must be a non-negative integer`);
+    }
+    return explicit;
+  }
+  const inferred = decimalScaleOf(amount);
+  if (inferred === null) {
+    throw new MoneyUnsupportedError(`${label}: amount ${JSON.stringify(amount)} is not a finite decimal`);
+  }
+  return inferred;
+}
+function mulRate(amount, rate, opts = {}) {
+  const scale = resolveScale("mulRate", amount, opts.scale);
+  const rounding = opts.rounding ?? "half-up";
+  const a = parseAmount("mulRate", amount, scale, rounding);
+  const rateScale = decimalScaleOf(rate);
+  if (rateScale === null) {
+    throw new MoneyUnsupportedError(`mulRate: rate ${JSON.stringify(rate)} is not a finite decimal`);
+  }
+  const r = parseToScaledInt(rate, rateScale);
+  if (!r.ok) {
+    throw new MoneyUnsupportedError(`mulRate: rate ${JSON.stringify(rate)} is not a finite decimal`);
+  }
+  const product = a * r.value;
+  return formatScaledInt(rescaleScaledInt(product, scale + rateScale, scale, rounding), scale);
+}
+function allocate(amount, weights, opts = {}) {
+  if (weights.length === 0) {
+    throw new MoneyUnsupportedError("allocate: weights must not be empty");
+  }
+  const scale = resolveScale("allocate", amount, opts.scale);
+  const a = parseAmount("allocate", amount, scale);
+  let weightScale = 0;
+  for (const w of weights) {
+    const s = decimalScaleOf(w);
+    if (s === null) {
+      throw new MoneyUnsupportedError(`allocate: weight ${JSON.stringify(w)} is not a finite decimal`);
+    }
+    if (s > weightScale) weightScale = s;
+  }
+  const scaledWeights = weights.map((w) => {
+    const r = parseToScaledInt(w, weightScale);
+    if (!r.ok || r.value < 0n) {
+      throw new MoneyUnsupportedError(`allocate: weight ${JSON.stringify(w)} must be a non-negative decimal`);
+    }
+    return r.value;
+  });
+  const sumW = scaledWeights.reduce((acc, w) => acc + w, 0n);
+  if (sumW === 0n) {
+    throw new MoneyUnsupportedError("allocate: weights must not all be zero");
+  }
+  const negative = a < 0n;
+  const mag = negative ? -a : a;
+  const base = [];
+  const remainders = [];
+  let distributed = 0n;
+  for (let i = 0; i < scaledWeights.length; i++) {
+    const product = mag * scaledWeights[i];
+    const share = product / sumW;
+    base.push(share);
+    distributed += share;
+    remainders.push({ index: i, rem: product % sumW });
+  }
+  let leftover = mag - distributed;
+  remainders.sort((x, y) => y.rem > x.rem ? 1 : y.rem < x.rem ? -1 : x.index - y.index);
+  for (const { index } of remainders) {
+    if (leftover === 0n) break;
+    base[index] = base[index] + 1n;
+    leftover -= 1n;
+  }
+  return base.map((p) => formatScaledInt(negative && p !== 0n ? -p : p, scale));
+}
+
+// src/money/branded.ts
+init_fixed_point();
+init_descriptor();
+function asMoney(value) {
+  if (!isMoneyLike(value)) {
+    throw new MoneyUnsupportedError(`asMoney: ${JSON.stringify(value)} is not a finite decimal`);
+  }
+  return String(value).trim();
+}
+function isMoneyString(value) {
+  return typeof value === "string" && isMoneyLike(value);
+}
+function moneyNumber(value) {
+  if (!isMoneyLike(value)) {
+    throw new MoneyUnsupportedError(`moneyNumber: ${JSON.stringify(value)} is not a finite decimal`);
+  }
+  return Number(value);
+}
+function isMoneyLike(value) {
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "string") return false;
+  return decimalScaleOf(value) !== null;
+}
+
 // src/i18n/script.ts
 init_errors();
 var LATIN_BASE = /* @__PURE__ */ new Set([
@@ -26679,9 +27296,11 @@ function shortJSON(value) {
   WeakPassphraseError,
   activeSessionCount,
   additiveOnly,
+  allocate,
   applyI18nLocale,
   applyJoins,
   applyPatch,
+  asMoney,
   assertStrongPassphrase,
   assertTierAccess,
   avg,
@@ -26758,6 +27377,7 @@ function shortJSON(value) {
   isI18nTextDescriptor,
   isMagicLinkGrantExpired,
   isMoneyDescriptor,
+  isMoneyString,
   isPreCompressed,
   isPublicEnvelope,
   isSessionAlive,
@@ -26790,6 +27410,8 @@ function shortJSON(value) {
   mintShamirRecoveryEntry,
   mintWrappedDeksBlob,
   money,
+  moneyNumber,
+  mulRate,
   paddedIndex,
   parseBytes,
   parseIndex,