@noy-db/hub 0.2.0-pre.11 → 0.2.0-pre.12

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, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, 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;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, 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 init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -266,6 +266,28 @@ var init_errors = __esm({
         this.attempts = attempts;
       }
     };
+    SequenceContentionError = class extends NoydbError {
+      sequence;
+      attempts;
+      constructor(sequence, attempts) {
+        super(
+          "SEQUENCE_CONTENTION",
+          `vault.sequence("${sequence}").next(): failed to allocate after ${attempts} optimistic-CAS retries`
+        );
+        this.name = "SequenceContentionError";
+        this.sequence = sequence;
+        this.attempts = attempts;
+      }
+    };
+    SequenceOfflineError = class extends NoydbError {
+      constructor() {
+        super(
+          "SEQUENCE_OFFLINE",
+          "vault.sequence().next() requires an online CAS-capable store (capabilities.casAtomic). Gap-free numbering cannot be serialized offline."
+        );
+        this.name = "SequenceOfflineError";
+      }
+    };
     BundleVersionConflictError = class extends NoydbError {
       /** The bundle handle of the newer remote version that rejected the push. */
       remoteVersion;
@@ -679,6 +701,39 @@ Resolutions:
         this.expected = expected;
       }
     };
+    UnknownShardError = class extends NoydbError {
+      partitionKey;
+      constructor(partitionKey, groupName) {
+        super(
+          "SHARD_UNKNOWN",
+          `No shard for partition key "${partitionKey}" in vault group "${groupName}" and autoCreate is disabled. Call group.createShard(${JSON.stringify(partitionKey)}) first, or enable sharding.autoCreate.`
+        );
+        this.name = "UnknownShardError";
+        this.partitionKey = partitionKey;
+      }
+    };
+    ShardProvisioningError = class extends NoydbError {
+      vaultId;
+      constructor(vaultId, partitionKey) {
+        super(
+          "SHARD_PROVISIONING",
+          `Registry has a row for partition "${partitionKey}" (vault "${vaultId}") but that vault is not provisioned in the store. Refusing to recreate it \u2014 the registry and store have diverged. Investigate before retrying.`
+        );
+        this.name = "ShardProvisioningError";
+        this.vaultId = vaultId;
+      }
+    };
+    VaultTemplateNotFoundError = class extends NoydbError {
+      templateName;
+      constructor(templateName) {
+        super(
+          "VAULT_TEMPLATE_NOT_FOUND",
+          `No vault template registered under "${templateName}". Register it with db.withVaultTemplate(${JSON.stringify(templateName)}, { version, configure }) before opening the vault group.`
+        );
+        this.name = "VaultTemplateNotFoundError";
+        this.templateName = templateName;
+      }
+    };
   }
 });
 
@@ -3603,6 +3658,328 @@ var init_core = __esm({
   }
 });
 
+// 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);
+  }
+  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();
+  }
+  s = expandExponent(s);
+  if (s.startsWith("+")) s = s.slice(1);
+  if (!/^-?(\d+(\.\d*)?|\.\d+)$/.test(s)) return null;
+  return s;
+}
+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;
+  }
+}
+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;
+}
+var init_fixed_point = __esm({
+  "src/money/fixed-point.ts"() {
+    "use strict";
+  }
+});
+
+// src/money/iso4217.ts
+function scaleForCurrency(code) {
+  const v = MINOR_UNITS[code];
+  return v === void 0 ? null : v;
+}
+var MINOR_UNITS;
+var init_iso4217 = __esm({
+  "src/money/iso4217.ts"() {
+    "use strict";
+    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
+    };
+  }
+});
+
+// src/money/descriptor.ts
+var MoneyPrecisionError, MoneyUnsupportedError;
+var init_descriptor = __esm({
+  "src/money/descriptor.ts"() {
+    "use strict";
+    init_errors();
+    MoneyPrecisionError = class extends NoydbError {
+      constructor(field, value, scale) {
+        super(
+          "MONEY_PRECISION",
+          `money: value ${JSON.stringify(value)} for field "${field}" exceeds scale ${scale} and no rounding mode is configured`
+        );
+        this.field = field;
+        this.value = value;
+        this.scale = scale;
+        this.name = "MoneyPrecisionError";
+      }
+      field;
+      value;
+      scale;
+    };
+    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/money/normalize.ts
+function isMoneyValueObject(v) {
+  return typeof v === "object" && v !== null && "currency" in v;
+}
+function quantizeAmount(field, input, scale, rounding) {
+  const r = parseToScaledInt(input, scale, rounding);
+  if (!r.ok) {
+    if (r.reason === "precision") throw new MoneyPrecisionError(field, input, scale);
+    throw new TypeError(`money: field "${field}" value ${JSON.stringify(input)} is not a finite decimal`);
+  }
+  return r.value.toString();
+}
+function 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);
+      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 };
+  }
+  return out;
+}
+function formatCurrency(decimal, currency, scale, locale) {
+  const fmt = new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency,
+    minimumFractionDigits: scale,
+    maximumFractionDigits: scale
+  });
+  return fmt.format(decimal);
+}
+function decodeMoneyFields(record, moneyFields, locale) {
+  const 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);
+    }
+  }
+  return out;
+}
+var init_normalize = __esm({
+  "src/money/normalize.ts"() {
+    "use strict";
+    init_fixed_point();
+    init_descriptor();
+  }
+});
+
+// src/computed/index.ts
+function evalComputedFields(record, computed, id) {
+  const out = { ...record };
+  for (const [field, fn] of Object.entries(computed)) {
+    try {
+      out[field] = fn(out);
+    } catch (cause) {
+      throw new ComputedFieldError(field, id, cause);
+    }
+  }
+  return out;
+}
+var ComputedFieldError;
+var init_computed = __esm({
+  "src/computed/index.ts"() {
+    "use strict";
+    init_errors();
+    ComputedFieldError = class extends NoydbError {
+      constructor(field, id, cause) {
+        super(
+          "COMPUTED_FIELD",
+          `computed field "${field}" threw for record "${id}": ` + (cause instanceof Error ? cause.message : String(cause))
+        );
+        this.field = field;
+        this.id = id;
+        this.cause = cause;
+        this.name = "ComputedFieldError";
+      }
+      field;
+      id;
+      cause;
+    };
+  }
+});
+
 // src/i18n/strategy.ts
 function notEnabled(op) {
   return new Error(
@@ -4087,6 +4464,189 @@ var init_strategy4 = __esm({
   }
 });
 
+// src/money/money-reducer.ts
+function toScaledInt(v) {
+  if (typeof v === "string" || typeof v === "number" || typeof v === "bigint") {
+    try {
+      return BigInt(v);
+    } catch {
+      return 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 value2 = toScaledInt(raw);
+    return value2 === null ? null : { currency: desc.fixedCurrency, value: value2 };
+  }
+  if (typeof raw !== "object") return null;
+  const o = raw;
+  if (typeof o.currency !== "string") return null;
+  const value = toScaledInt(o.amount);
+  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;
+}
+var init_money_reducer = __esm({
+  "src/money/money-reducer.ts"() {
+    "use strict";
+    init_predicate();
+    init_fixed_point();
+    init_iso4217();
+    init_descriptor();
+  }
+});
+
 // src/query/builder.ts
 function executePlanWithSource(source, plan, joinContext) {
   const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
@@ -4363,6 +4923,7 @@ var init_builder = __esm({
     init_errors();
     init_live();
     init_strategy4();
+    init_money_reducer();
     EMPTY_PLAN = {
       clauses: [],
       orderBy: [],
@@ -4808,6 +5369,10 @@ var init_builder = __esm({
        * partition boundaries without an API break.
        */
       aggregate(spec) {
+        const moneyFields = this.source.moneyFields;
+        if (moneyFields) {
+          spec = wrapMoneyReducers(spec, moneyFields);
+        }
         const source = this.source;
         const clauses = this.plan.clauses;
         const joinCtx = this.joinContext;
@@ -4855,13 +5420,15 @@ var init_builder = __esm({
             executeRecords,
             field,
             upstreams,
-            dictLabelResolver
+            dictLabelResolver,
+            this.source.moneyFields
           );
         }
         return this.aggregateStrategy.groupByN(
           executeRecords,
           fields,
-          upstreams
+          upstreams,
+          this.source.moneyFields
         );
       }
       /**
@@ -4982,6 +5549,29 @@ var init_builder = __esm({
   }
 });
 
+// src/aggregate/aggregation.ts
+function reduceRecords(records, spec) {
+  const state = {};
+  for (const key of Object.keys(spec)) {
+    state[key] = spec[key].init();
+  }
+  for (const record of records) {
+    for (const key of Object.keys(spec)) {
+      state[key] = spec[key].step(state[key], record);
+    }
+  }
+  const result = {};
+  for (const key of Object.keys(spec)) {
+    result[key] = spec[key].finalize(state[key]);
+  }
+  return result;
+}
+var init_aggregation = __esm({
+  "src/aggregate/aggregation.ts"() {
+    "use strict";
+  }
+});
+
 // src/aggregate/canonical-key.ts
 function canonicalGroupKey(fields, row) {
   const sorted = [...fields].sort();
@@ -7017,6 +7607,8 @@ var init_collection = __esm({
     init_types();
     init_strategy();
     init_core();
+    init_normalize();
+    init_computed();
     init_strategy2();
     init_policy();
     init_crypto();
@@ -7185,6 +7777,18 @@ var init_collection = __esm({
        * fields when a locale is requested.
        */
       dictKeyFields;
+      /**
+       * Money field descriptors keyed by field path. Declared via the
+       * `moneyFields` collection option: `put()` quantizes to a scaled-int
+       * string, `get()`/`list()` decode back. Mutable so {@link _applyMoneyFields}
+       * can attach descriptors to a collection MV-analysis pre-created.
+       */
+      moneyFields;
+      /**
+       * Computed scalar fields, evaluated first on every `put()`. Mutable for
+       * the same MV-pre-creation reconcile as {@link moneyFields}.
+       */
+      computed;
       /**
        * Async callback provided by the Vault that resolves a dict key
        * to its label for a given locale. Used by the locale-read path for
@@ -7326,6 +7930,8 @@ var init_collection = __esm({
         this.joinResolver = opts.joinResolver;
         this.i18nFields = opts.i18nFields;
         this.dictKeyFields = opts.dictKeyFields;
+        this.moneyFields = opts.moneyFields;
+        this.computed = opts.computed;
         this.dictLabelResolver = opts.dictLabelResolver;
         this.i18nPutValidator = opts.i18nPutValidator;
         this.autoTranslateHook = opts.autoTranslateHook;
@@ -7450,6 +8056,19 @@ var init_collection = __esm({
       getSchema() {
         return this.schema;
       }
+      /**
+       * @internal — attach money descriptors post-construction. MV dependency
+       * analysis auto-creates a source collection (without options) during
+       * `openVault`, before the user's `collection(name, { moneyFields })`
+       * declaration; this reconciles that ordering. First-wins. Not public.
+       */
+      _applyMoneyFields(moneyFields) {
+        if (this.moneyFields === void 0) this.moneyFields = moneyFields;
+      }
+      /** @internal — attach computed fields post-construction. See {@link _applyMoneyFields}. */
+      _applyComputed(computed) {
+        if (this.computed === void 0) this.computed = computed;
+      }
       /**
        * Get a single record by ID.
        *
@@ -7621,7 +8240,7 @@ var init_collection = __esm({
               existingRecord = null;
             }
           }
-          await this.subsystemBus.dispatchGate("beforePut", {
+          const gateEvent = {
             op: existingEnv ? "update" : "create",
             vault: this.vault,
             collection: this.name,
@@ -7631,12 +8250,20 @@ var init_collection = __esm({
             existingVersion: existingEnv?._v ?? 0,
             existingTs: existingEnv?._ts,
             userId: this.keyring.userId,
-            role: this.keyring.role
-          });
+            role: this.keyring.role,
+            ...this.computed !== void 0 ? { computedFieldNames: new Set(Object.keys(this.computed)) } : {}
+          };
+          await this.subsystemBus.dispatchGate("beforePut", gateEvent);
+        }
+        if (this.computed !== void 0) {
+          record = evalComputedFields(record, this.computed, id);
         }
         if (this.schema !== void 0) {
           record = await validateSchemaInput(this.schema, record, `put(${id})`);
         }
+        if (this.moneyFields) {
+          record = quantizeMoneyFields(record, this.moneyFields);
+        }
         if (this.i18nFields) {
           const obj = record;
           for (const [field, descriptor] of Object.entries(this.i18nFields)) {
@@ -8458,7 +9085,8 @@ var init_collection = __esm({
           // fields. The Query builder consults these when present and falls
           // back to a linear scan otherwise.
           getIndexes: () => this.getIndexes(),
-          lookupById: (id) => this.cache.get(id)?.record
+          lookupById: (id) => this.cache.get(id)?.record,
+          ...this.moneyFields ? { moneyFields: this.moneyFields } : {}
         };
         const resolver = this.joinResolver;
         const leftCollection = this.name;
@@ -9140,10 +9768,14 @@ var init_collection = __esm({
       async applyLocaleToRecord(record, localeOpts) {
         const hasI18n = this.i18nFields && Object.keys(this.i18nFields).length > 0;
         const hasDict = this.dictKeyFields && Object.keys(this.dictKeyFields).length > 0;
-        if (!hasI18n && !hasDict) return record;
+        const hasMoney = this.moneyFields && Object.keys(this.moneyFields).length > 0;
+        if (!hasI18n && !hasDict && !hasMoney) return record;
         const locale = localeOpts?.locale ?? this.defaultLocale;
-        if (!locale) return record;
         let result = record;
+        if (hasMoney && this.moneyFields) {
+          result = decodeMoneyFields(result, this.moneyFields, typeof locale === "string" ? locale : void 0);
+        }
+        if (!locale) return result;
         if (hasI18n && this.i18nFields) {
           result = this.i18nStrategy.applyI18nLocale(result, this.i18nFields, locale, localeOpts?.fallback);
         }
@@ -9982,6 +10614,182 @@ var init_virtual_collection = __esm({
   }
 });
 
+// src/archive/engine.ts
+function isHeld(policy, record) {
+  if (!policy.legalHold) return false;
+  try {
+    return policy.legalHold(record);
+  } catch {
+    return true;
+  }
+}
+async function runArchive(ctx, options = {}) {
+  const maxArchives = options.maxArchives ?? Infinity;
+  const dryRun = options.dryRun === true;
+  let archived = 0;
+  let held = 0;
+  let scanned = 0;
+  const byCollection = {};
+  outer: for (const collection of ctx.collectionsWithPolicy()) {
+    const policy = ctx.getPolicy(collection);
+    if (!policy) continue;
+    byCollection[collection] = { archived: 0, held: 0 };
+    for (const id of await ctx.listRecordIds(collection)) {
+      if (archived >= maxArchives) break outer;
+      const record = await ctx.getRecord(collection, id).catch(() => null);
+      if (record === null) continue;
+      scanned += 1;
+      let eligible = false;
+      try {
+        eligible = policy.archiveWhen(record);
+      } catch {
+        eligible = false;
+      }
+      if (!eligible) continue;
+      if (isHeld(policy, record)) {
+        held += 1;
+        byCollection[collection].held += 1;
+        continue;
+      }
+      if (!dryRun) {
+        const env = await ctx.getEnvelope(collection, id);
+        if (!env) continue;
+        await ctx.archiveStore.put(ctx.vaultId, collection, id, env);
+        await ctx.removeFromPrimary(collection, id);
+      }
+      archived += 1;
+      byCollection[collection].archived += 1;
+    }
+  }
+  return { archived, held, scanned, byCollection };
+}
+async function runRestore(ctx, collection, id) {
+  const env = await ctx.archiveStore.get(ctx.vaultId, collection, id);
+  if (!env) return false;
+  await ctx.restoreToPrimary(collection, id, env);
+  await ctx.archiveStore.delete(ctx.vaultId, collection, id);
+  return true;
+}
+async function runListArchived(ctx, collection) {
+  const collections = collection ? [collection] : ctx.collectionsWithPolicy();
+  const out = [];
+  for (const c of collections) {
+    const ids = await ctx.archiveStore.list(ctx.vaultId, c);
+    for (const id of ids) out.push({ collection: c, id });
+  }
+  return out;
+}
+var init_engine = __esm({
+  "src/archive/engine.ts"() {
+    "use strict";
+  }
+});
+
+// src/archive/index.ts
+var init_archive = __esm({
+  "src/archive/index.ts"() {
+    "use strict";
+    init_engine();
+  }
+});
+
+// src/sequence/index.ts
+async function sleepBackoff2(attempt) {
+  const ceil = Math.min(2 ** attempt, 32);
+  const ms = Math.floor(Math.random() * ceil);
+  await new Promise((r) => setTimeout(r, ms));
+}
+var SEQUENCE_COLLECTION, MAX_NEXT_ATTEMPTS, SequenceStore;
+var init_sequence = __esm({
+  "src/sequence/index.ts"() {
+    "use strict";
+    init_types();
+    init_crypto();
+    init_errors();
+    SEQUENCE_COLLECTION = "_sequences";
+    MAX_NEXT_ATTEMPTS = 16;
+    SequenceStore = class {
+      adapter;
+      vault;
+      encrypted;
+      getDEK;
+      actor;
+      /**
+       * Memoized DEK promise. The `_sequences` collection DEK is created on
+       * first access; without sharing one promise, a burst of concurrent
+       * `next()` calls would each trigger DEK creation and diverge (one
+       * writer's ciphertext unreadable by another). One shared promise → one
+       * DEK.
+       */
+      dekPromise = null;
+      constructor(opts) {
+        this.adapter = opts.adapter;
+        this.vault = opts.vault;
+        this.encrypted = opts.encrypted;
+        this.getDEK = opts.getDEK;
+        this.actor = opts.actor;
+      }
+      /** A handle bound to one sequence name. */
+      handle(name) {
+        return {
+          next: () => this.next(name),
+          peek: () => this.peek(name)
+        };
+      }
+      assertOnline() {
+        if (this.adapter.capabilities?.casAtomic !== true) {
+          throw new SequenceOfflineError();
+        }
+      }
+      dek() {
+        if (!this.dekPromise) this.dekPromise = this.getDEK(SEQUENCE_COLLECTION);
+        return this.dekPromise;
+      }
+      async read(name) {
+        const env = await this.adapter.get(this.vault, SEQUENCE_COLLECTION, name);
+        if (!env) return { env: null, value: 0 };
+        const json = this.encrypted ? await decrypt(env._iv, env._data, await this.dek()) : env._data;
+        const state = JSON.parse(json);
+        return { env, value: state.value };
+      }
+      async encryptState(state, version) {
+        const json = JSON.stringify(state);
+        if (!this.encrypted) {
+          return { _noydb: NOYDB_FORMAT_VERSION, _v: version, _ts: (/* @__PURE__ */ new Date()).toISOString(), _iv: "", _data: json, _by: this.actor };
+        }
+        const { iv, data } = await encrypt(json, await this.dek());
+        return { _noydb: NOYDB_FORMAT_VERSION, _v: version, _ts: (/* @__PURE__ */ new Date()).toISOString(), _iv: iv, _data: data, _by: this.actor };
+      }
+      async peek(name) {
+        return (await this.read(name)).value;
+      }
+      async next(name) {
+        this.assertOnline();
+        let lastConflict;
+        for (let attempt = 0; attempt < MAX_NEXT_ATTEMPTS; attempt++) {
+          const { env, value } = await this.read(name);
+          const nextValue = value + 1;
+          const expectedVersion = env?._v ?? 0;
+          const envelope = await this.encryptState({ value: nextValue }, expectedVersion + 1);
+          try {
+            await this.adapter.put(this.vault, SEQUENCE_COLLECTION, name, envelope, expectedVersion);
+            return nextValue;
+          } catch (err) {
+            if (err instanceof ConflictError) {
+              lastConflict = err;
+              if (attempt < MAX_NEXT_ATTEMPTS - 1) await sleepBackoff2(attempt);
+              continue;
+            }
+            throw err;
+          }
+        }
+        void lastConflict;
+        throw new SequenceContentionError(name, MAX_NEXT_ATTEMPTS);
+      }
+    };
+  }
+});
+
 // src/shadow/strategy.ts
 var NOT_ENABLED3, NO_SHADOW;
 var init_strategy7 = __esm({
@@ -10274,6 +11082,7 @@ async function runCompaction(ctx, options = {}) {
   let evicted = 0;
   let records = 0;
   let auditEntries = 0;
+  let held = 0;
   let collectionsWithPolicy = 0;
   outer: for (const collectionName of allCollections) {
     if (collectionName.startsWith("_")) continue;
@@ -10297,6 +11106,10 @@ async function runCompaction(ctx, options = {}) {
         if (!policy) continue;
         const reason = evaluatePolicy(policy, record, slot, now);
         if (!reason) continue;
+        if (isHeld2(policy, record, now)) {
+          held += 1;
+          continue;
+        }
         if (!dryRun) {
           await ctx.deleteSlot(collectionName, recordId2, slot.name);
           await writeAuditEntry(ctx, {
@@ -10321,9 +11134,32 @@ async function runCompaction(ctx, options = {}) {
     records,
     collections: collectionsWithPolicy,
     auditEntries,
+    held,
     byCollection
   };
 }
+function isHeld2(policy, record, now) {
+  if (policy.legalHold) {
+    try {
+      if (policy.legalHold(record)) return true;
+    } catch {
+      return true;
+    }
+  }
+  if (policy.retainUntil) {
+    try {
+      const until = policy.retainUntil(record);
+      if (until !== null && until !== void 0) {
+        const t = until instanceof Date ? until.getTime() : typeof until === "number" ? until : Date.parse(String(until));
+        if (!Number.isFinite(t)) return true;
+        if (t > now.getTime()) return true;
+      }
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
 function evaluatePolicy(policy, record, slot, now) {
   let ttlTriggered = false;
   let predicateTriggered = false;
@@ -12081,6 +12917,8 @@ var init_vault = __esm({
     init_keyring();
     init_errors();
     init_errors();
+    init_archive();
+    init_sequence();
     init_constants();
     init_entry();
     init_strategy3();
@@ -12139,6 +12977,10 @@ var init_vault = __esm({
        * call throws with a pointer at `@noy-db/hub/blobs`.
        */
       blobStrategy;
+      /** Cold-storage archival strategy (the archive target store). */
+      archiveStrategy;
+      /** Per-collection record archival policies. Indexed by collection name. */
+      archiveRegistry = /* @__PURE__ */ new Map();
       indexStrategy;
       aggregateStrategy;
       crdtStrategy;
@@ -12242,6 +13084,8 @@ var init_vault = __esm({
        * docstring.
        */
       ledgerStore = null;
+      /** Lazily-built atomic-sequence store. See {@link sequence}. */
+      sequenceStore = null;
       /**
        * Background writes for persisted-schema envelopes (#schema-dump v0
        * slice 1). One promise per `collection({ persistJsonSchema: true })`
@@ -12343,6 +13187,7 @@ var init_vault = __esm({
         this.onRegisterConflictResolver = opts.onRegisterConflictResolver;
         this.syncAdapter = opts.syncAdapter;
         this.blobStrategy = opts.blobStrategy;
+        this.archiveStrategy = opts.archiveStrategy;
         this.indexStrategy = opts.indexStrategy;
         this.aggregateStrategy = opts.aggregateStrategy;
         this.crdtStrategy = opts.crdtStrategy;
@@ -12405,8 +13250,9 @@ var init_vault = __esm({
        *. `put()` validates keys against the declared set; reads
        *   with `{ locale }` add `<field>Label` virtual fields.
        *
-       * Throws `ReservedCollectionNameError` for names starting with `_dict_`.
-       * Use `vault.dictionary(name)` to access dictionary collections.
+       * Throws `ReservedCollectionNameError` for names starting with `_dict_` or
+       * equal to `_sequences`. Use `vault.dictionary(name)` for dict collections
+       * and `vault.sequence(name)` for sequence counters.
        *
        * Lazy mode + indexes is rejected at construction time — see the
        * Collection constructor for the rationale.
@@ -12425,7 +13271,16 @@ var init_vault = __esm({
         if (isDictCollectionName(collectionName)) {
           throw new ReservedCollectionNameError(collectionName);
         }
+        if (collectionName === SEQUENCE_COLLECTION) {
+          throw new ReservedCollectionNameError(collectionName);
+        }
         let coll = this.collectionCache.get(collectionName);
+        if (coll && options?.moneyFields) {
+          coll._applyMoneyFields(options.moneyFields);
+        }
+        if (coll && options?.computed) {
+          coll._applyComputed(options.computed);
+        }
         if (!coll) {
           if (options?.refs) {
             this.refRegistry.register(collectionName, options.refs);
@@ -12436,6 +13291,9 @@ var init_vault = __esm({
           if (options?.blobFields) {
             this.blobFieldsRegistry.set(collectionName, options.blobFields);
           }
+          if (options?.archive) {
+            this.archiveRegistry.set(collectionName, options.archive);
+          }
           if (options?.attestation !== void 0) {
             this.attestationRegistry.set(collectionName, options.attestation);
           }
@@ -12551,6 +13409,8 @@ var init_vault = __esm({
           collOpts.onCrossTierAccess = (event) => this.emitCrossTier(event);
           if (this.syncAdapter !== void 0) collOpts.syncAdapter = this.syncAdapter;
           if (options?.i18nFields !== void 0) collOpts.i18nFields = options.i18nFields;
+          if (options?.moneyFields !== void 0) collOpts.moneyFields = options.moneyFields;
+          if (options?.computed !== void 0) collOpts.computed = options.computed;
           if (options?.dictKeyFields !== void 0) {
             collOpts.dictLabelResolver = async (dictName, key, locale, fallback) => {
               const handle = this.dictionary(dictName);
@@ -12970,6 +13830,33 @@ var init_vault = __esm({
        * await vault.compact({ maxEvictions: 1000 })             // cap batch
        * ```
        */
+      /**
+       * Atomic, gap-free numbering. `vault.sequence('invoice-2026').next()`
+       * returns 1, 2, 3, … with no gaps or duplicates under concurrency, via
+       * an optimistic-CAS counter at `_sequences/<name>`. Each name is an
+       * independent sequence.
+       *
+       * **Online-only:** `next()` throws `SequenceOfflineError` unless the
+       * store advertises `capabilities.casAtomic` — gap-free numbering cannot
+       * be serialized by an offline / non-CAS writer.
+       *
+       * ```ts
+       * const n = await vault.sequence('invoice-2026').next()   // 1, then 2, …
+       * const cur = await vault.sequence('invoice-2026').peek()  // current value, no allocation
+       * ```
+       */
+      sequence(name) {
+        if (!this.sequenceStore) {
+          this.sequenceStore = new SequenceStore({
+            adapter: this.adapter,
+            vault: this.name,
+            encrypted: this.encrypted,
+            getDEK: this.getDEK,
+            actor: this.keyring.userId
+          });
+        }
+        return this.sequenceStore.handle(name);
+      }
       async compact(options = {}) {
         return runCompaction({
           adapter: this.adapter,
@@ -12994,6 +13881,48 @@ var init_vault = __esm({
           }
         }, options);
       }
+      /**
+       * Sweep records eligible by their collection's `archive` policy into the
+       * cold archive store. Relocation is envelope-level (no re-encryption) and
+       * bypasses guards + materialized-view dispatch, so issued/immutable
+       * records over a sealed period can be archived without recomputing
+       * finalized aggregates. A `legalHold` predicate blocks archival.
+       * Requires `archiveStrategy: withArchive({ store })` in `createNoydb`.
+       */
+      async archive(options = {}) {
+        return runArchive(this._archiveContext(), options);
+      }
+      /** Relocate one archived record back to the primary store. Returns false if it was not archived. */
+      async restore(collection, id) {
+        return runRestore(this._archiveContext(), collection, id);
+      }
+      /** List archived record ids for a collection (or all collections with an archive policy). */
+      async listArchived(collection) {
+        return runListArchived(this._archiveContext(), collection);
+      }
+      _archiveContext() {
+        const strategy = this.archiveStrategy;
+        if (!strategy) {
+          throw new Error(
+            "vault.archive/restore/listArchived require `archiveStrategy: withArchive({ store })` in createNoydb"
+          );
+        }
+        const archiveStore = strategy.store;
+        return {
+          vaultId: this.name,
+          archiveStore,
+          collectionsWithPolicy: () => [...this.archiveRegistry.keys()],
+          getPolicy: (c) => this.archiveRegistry.get(c) ?? null,
+          listRecordIds: (c) => this.adapter.list(this.name, c),
+          getRecord: async (c, id) => await this.collection(c).get(id, { locale: "raw" }),
+          getEnvelope: (c, id) => this.adapter.get(this.name, c, id),
+          removeFromPrimary: (c, id) => this.collection(c)._internalDelete(id),
+          restoreToPrimary: async (c, id, env) => {
+            await this.adapter.put(this.name, c, id, env);
+            await this.collection(c)._invalidateCacheEntry(id);
+          }
+        };
+      }
       exportBlobs(options = {}) {
         this.assertCanExport("plaintext", "blob");
         return createExportBlobsHandle(
@@ -14255,7 +15184,7 @@ var init_vault = __esm({
           }
         }
         const internalSnapshot = {};
-        for (const internalName of [LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, SCHEMAS_COLLECTION]) {
+        for (const internalName of [LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, SCHEMAS_COLLECTION, SEQUENCE_COLLECTION]) {
           const ids = await this.adapter.list(this.name, internalName);
           if (ids.length === 0) continue;
           const records = {};
@@ -15870,7 +16799,7 @@ function deny(gate, reason, required) {
   return new PolicyDeniedError(gate, reason, required);
 }
 var DEFAULT_FRESHNESS_MS;
-var init_engine = __esm({
+var init_engine2 = __esm({
   "src/policy/engine.ts"() {
     "use strict";
     init_errors2();
@@ -15883,7 +16812,7 @@ var init_policy3 = __esm({
   "src/policy/index.ts"() {
     "use strict";
     init_presets();
-    init_engine();
+    init_engine2();
     init_storage5();
   }
 });
@@ -15927,14 +16856,21 @@ var init_executor3 = __esm({
        * Compare existing vs incoming for each `frozenFields.fields` entry
        * when `frozenFields.when(existing)` is true. Throws
        * `FieldFrozenError` listing every changed frozen field.
+       *
+       * @param skipFields — field names that are schema-owned computed fields.
+       *   These are excluded from the comparison because `incoming` carries the
+       *   raw user input (computed fields not yet evaluated), so comparing
+       *   `existing[field]` vs `incoming[field]` would always look like a
+       *   change even when the computed result is unchanged.
        */
-      async checkFrozenFields(guard, id, existing, incoming) {
+      async checkFrozenFields(guard, id, existing, incoming, skipFields) {
         const ff = guard.frozenFields;
         if (!ff) return;
         if (existing === null) return;
         if (!ff.when(existing)) return;
         const changed = [];
         for (const f of ff.fields) {
+          if (skipFields?.has(String(f))) continue;
           if (existing[f] !== incoming[f]) {
             if (!deepEqual(existing[f], incoming[f])) changed.push(String(f));
           }
@@ -15963,6 +16899,476 @@ var init_executor3 = __esm({
   }
 });
 
+// src/federation/classify-skip.ts
+function classifyShardSkip(err) {
+  return err instanceof NoAccessError ? "no-grant" : "error";
+}
+var init_classify_skip = __esm({
+  "src/federation/classify-skip.ts"() {
+    "use strict";
+    init_errors();
+  }
+});
+
+// src/federation/cross-vault-live.ts
+var CrossVaultLive;
+var init_cross_vault_live = __esm({
+  "src/federation/cross-vault-live.ts"() {
+    "use strict";
+    CrossVaultLive = class {
+      snapshot;
+      error = null;
+      ready;
+      subs = /* @__PURE__ */ new Set();
+      unsubChange;
+      opts;
+      stopped = false;
+      computing = false;
+      dirty = false;
+      scheduled = false;
+      timer = null;
+      resolveReady;
+      settledOnce = false;
+      constructor(opts) {
+        this.opts = opts;
+        this.snapshot = opts.initialSnapshot;
+        this.ready = new Promise((res) => {
+          this.resolveReady = res;
+        });
+        this.unsubChange = opts.subscribeToChanges((e) => {
+          if (this.stopped || !opts.isRelevant(e)) return;
+          this.schedule();
+        });
+        this.schedule();
+      }
+      subscribe(cb) {
+        if (this.stopped) return () => {
+        };
+        this.subs.add(cb);
+        return () => this.subs.delete(cb);
+      }
+      stop() {
+        if (this.stopped) return;
+        this.stopped = true;
+        this.unsubChange();
+        if (this.timer !== null) clearTimeout(this.timer);
+        this.subs.clear();
+        if (!this.settledOnce) this.resolveReady();
+      }
+      schedule() {
+        if (this.stopped) return;
+        if (this.computing) {
+          this.dirty = true;
+          return;
+        }
+        if (this.scheduled) return;
+        this.scheduled = true;
+        const run = () => {
+          this.scheduled = false;
+          void this.runCompute();
+        };
+        const ms = this.opts.debounceMs ?? 0;
+        if (ms > 0) this.timer = setTimeout(run, ms);
+        else queueMicrotask(run);
+      }
+      async runCompute() {
+        if (this.stopped) return;
+        this.computing = true;
+        this.dirty = false;
+        try {
+          const next = await this.opts.compute();
+          if (this.stopped) return;
+          this.snapshot = next;
+          this.error = null;
+        } catch (err) {
+          if (this.stopped) return;
+          this.error = err instanceof Error ? err : new Error(String(err));
+        } finally {
+          this.computing = false;
+          if (!this.stopped) {
+            if (!this.settledOnce) {
+              this.settledOnce = true;
+              this.resolveReady();
+            }
+            for (const cb of this.subs) cb();
+            if (this.dirty) this.schedule();
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/federation/aggregate-across.ts
+var CrossVaultAggregation, CrossVaultGroupedAggregation;
+var init_aggregate_across = __esm({
+  "src/federation/aggregate-across.ts"() {
+    "use strict";
+    init_aggregation();
+    init_groupby();
+    init_cross_vault_live();
+    CrossVaultAggregation = class {
+      constructor(src, spec, bind) {
+        this.src = src;
+        this.spec = spec;
+        this.bind = bind;
+      }
+      src;
+      spec;
+      bind;
+      async run(options = {}) {
+        const { records, skippedVaults } = await this.src.fanoutRecords(options);
+        return { result: reduceRecords(records, this.spec), skippedVaults };
+      }
+      live(options = {}) {
+        if (!this.bind) throw new Error("CrossVaultAggregation: live() requires a LiveBinding \u2014 use ShardedQuery.aggregate()");
+        const spec = this.spec;
+        const src = this.src;
+        const core = new CrossVaultLive({
+          subscribeToChanges: this.bind.subscribeToChanges,
+          isRelevant: this.bind.isRelevant,
+          compute: async () => {
+            const { records, skippedVaults } = await src.fanoutRecords(options);
+            return { value: reduceRecords(records, spec), skipped: skippedVaults };
+          },
+          initialSnapshot: { value: void 0, skipped: [] },
+          ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
+        });
+        return {
+          get value() {
+            return core.snapshot.value;
+          },
+          get skippedVaults() {
+            return core.snapshot.skipped;
+          },
+          get error() {
+            return core.error;
+          },
+          ready: core.ready,
+          subscribe: (cb) => core.subscribe(cb),
+          stop: () => core.stop()
+        };
+      }
+    };
+    CrossVaultGroupedAggregation = class {
+      constructor(src, field, spec, bind) {
+        this.src = src;
+        this.field = field;
+        this.spec = spec;
+        this.bind = bind;
+      }
+      src;
+      field;
+      spec;
+      bind;
+      async run(options = {}) {
+        const { records, skippedVaults } = await this.src.fanoutRecords(options);
+        return {
+          results: groupAndReduce(records, this.field, this.spec),
+          skippedVaults
+        };
+      }
+      live(options = {}) {
+        if (!this.bind) throw new Error("CrossVaultGroupedAggregation: live() requires a LiveBinding \u2014 use ShardedQuery.groupBy().aggregate()");
+        const field = this.field;
+        const spec = this.spec;
+        const src = this.src;
+        const core = new CrossVaultLive({
+          subscribeToChanges: this.bind.subscribeToChanges,
+          isRelevant: this.bind.isRelevant,
+          compute: async () => {
+            const { records, skippedVaults } = await src.fanoutRecords(options);
+            return {
+              records: groupAndReduce(records, field, spec),
+              skipped: skippedVaults
+            };
+          },
+          initialSnapshot: { records: [], skipped: [] },
+          ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
+        });
+        return {
+          get value() {
+            return core.snapshot.records;
+          },
+          get skippedVaults() {
+            return core.snapshot.skipped;
+          },
+          get error() {
+            return core.error;
+          },
+          ready: core.ready,
+          subscribe: (cb) => core.subscribe(cb),
+          stop: () => core.stop()
+        };
+      }
+    };
+  }
+});
+
+// src/federation/vault-group.ts
+var vault_group_exports = {};
+__export(vault_group_exports, {
+  ShardedCollection: () => ShardedCollection,
+  ShardedGroupedQuery: () => ShardedGroupedQuery,
+  ShardedQuery: () => ShardedQuery,
+  VaultGroup: () => VaultGroup
+});
+function assertSafePartitionKey(partitionKey) {
+  if (partitionKey.length === 0) {
+    throw new ValidationError("partitionKey must be a non-empty string");
+  }
+  if (!SAFE_PARTITION_KEY.test(partitionKey)) {
+    throw new ValidationError(
+      `partitionKey "${partitionKey}" contains characters outside [A-Za-z0-9._-]. Map your records to a store-safe key in sharding.keyOf.`
+    );
+  }
+  if (partitionKey.includes(SHARD_SEPARATOR)) {
+    throw new ValidationError(
+      `partitionKey "${partitionKey}" must not contain "--" \u2014 it is reserved as the shard vault-id separator and would risk shard-id collisions.`
+    );
+  }
+}
+var SHARD_SEPARATOR, SAFE_PARTITION_KEY, VaultGroup, ShardedCollection, ShardedQuery, ShardedGroupedQuery;
+var init_vault_group = __esm({
+  "src/federation/vault-group.ts"() {
+    "use strict";
+    init_errors();
+    init_classify_skip();
+    init_cross_vault_live();
+    init_aggregate_across();
+    SHARD_SEPARATOR = "--";
+    SAFE_PARTITION_KEY = /^[A-Za-z0-9._-]+$/;
+    VaultGroup = class {
+      constructor(db, name, registry, sharding, template) {
+        this.db = db;
+        this.name = name;
+        this.registry = registry;
+        this.sharding = sharding;
+        this.template = template;
+        if (name.includes(SHARD_SEPARATOR)) {
+          throw new ValidationError(
+            `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
+          );
+        }
+      }
+      db;
+      name;
+      registry;
+      sharding;
+      template;
+      /** Deterministic vault name for a partition key, namespaced by the group. */
+      shardVaultId(partitionKey) {
+        assertSafePartitionKey(partitionKey);
+        return `${this.name}${SHARD_SEPARATOR}${partitionKey}`;
+      }
+      /** All registry rows (hydrates the registry collection first). */
+      async allRows() {
+        await this.registry.list();
+        return this.registry.query().toArray();
+      }
+      /** Open an existing shard and apply the template. */
+      async openShard(partitionKey) {
+        const vault = await this.db.openVault(this.shardVaultId(partitionKey), { create: false });
+        this.template.configure(vault);
+        return vault;
+      }
+      /**
+       * Idempotently provision a shard for `partitionKey`. Returns the
+       * configured vault handle.
+       *
+       * - row + vault present → no-op, return handle
+       * - row present, vault gone → ShardProvisioningError
+       * - row absent (vault present or not) → open-or-create, configure, write row
+       */
+      async createShard(partitionKey) {
+        const vaultId = this.shardVaultId(partitionKey);
+        const row = await this.registry.get(partitionKey);
+        const provisioned = await this.db._shardVaultProvisioned(vaultId);
+        if (row && !provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
+        if (row && provisioned) return this.openShard(partitionKey);
+        const vault = await this.db.openVault(vaultId);
+        this.template.configure(vault);
+        await this.registry.put(partitionKey, {
+          vaultId,
+          partitionKey,
+          templateName: this.sharding.vaultTemplate,
+          schemaVersion: this.template.version,
+          createdAt: Date.now()
+        });
+        return vault;
+      }
+      /**
+       * Drill down to a single shard's full Collection API. Throws if the shard is unknown.
+       * Also throws ShardProvisioningError if the registry row exists but the vault has been deleted
+       * (registry/store divergence).
+       */
+      async shard(partitionKey) {
+        const vaultId = this.shardVaultId(partitionKey);
+        const row = await this.registry.get(partitionKey);
+        if (!row) throw new UnknownShardError(partitionKey, this.name);
+        const provisioned = await this.db._shardVaultProvisioned(vaultId);
+        if (!provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
+        return this.openShard(partitionKey);
+      }
+      /** A sharded view over one logical collection across all shards. */
+      collection(collectionName) {
+        return new ShardedCollection(this, collectionName);
+      }
+      /** @internal — eligible (openable-candidate) rows + drift/divergence skips. */
+      async resolveEligible(options = {}) {
+        const rows = await this.allRows();
+        const skipped = [];
+        const versionOk = [];
+        for (const row of rows) {
+          if (options.minVersion !== void 0 && row.schemaVersion < options.minVersion) {
+            skipped.push({ vaultId: row.vaultId, reason: "schema-drift" });
+          } else versionOk.push(row);
+        }
+        const provisioned = await Promise.all(versionOk.map((r) => this.db._shardVaultProvisioned(r.vaultId)));
+        const eligible = [];
+        versionOk.forEach((row, i) => {
+          if (provisioned[i]) eligible.push(row);
+          else skipped.push({ vaultId: row.vaultId, reason: "error", error: new ShardProvisioningError(row.vaultId, row.partitionKey) });
+        });
+        return { eligible, skipped };
+      }
+    };
+    ShardedCollection = class {
+      constructor(group, collectionName) {
+        this.group = group;
+        this.collectionName = collectionName;
+      }
+      group;
+      collectionName;
+      /** Route a write to the shard owning `keyOf(record)`. */
+      async put(id, record) {
+        const key = this.group.sharding.keyOf(record);
+        const row = await this.group.registry.get(key);
+        let vault;
+        if (!row) {
+          if (this.group.sharding.autoCreate === false) {
+            throw new UnknownShardError(key, this.group.name);
+          }
+          vault = await this.group.createShard(key);
+        } else {
+          vault = await this.group.openShard(key);
+        }
+        await vault.collection(this.collectionName).put(id, record);
+      }
+      /** Begin a cross-shard fan-out query. */
+      query() {
+        return new ShardedQuery(this.group, this.collectionName, []);
+      }
+    };
+    ShardedQuery = class _ShardedQuery {
+      constructor(group, collectionName, clauses) {
+        this.group = group;
+        this.collectionName = collectionName;
+        this.clauses = clauses;
+      }
+      group;
+      collectionName;
+      clauses;
+      where(field, op, value) {
+        return new _ShardedQuery(this.group, this.collectionName, [
+          ...this.clauses,
+          { field, op, value }
+        ]);
+      }
+      /** @internal — fan out the where-filtered records across eligible shards. */
+      async fanoutRecords(options = {}) {
+        const { eligible, skipped } = await this.group.resolveEligible(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();
+            let q = coll.query();
+            for (const c of this.clauses) q = q.where(c.field, c.op, c.value);
+            return q.toArray();
+          },
+          { concurrency: options.concurrency ?? 1, create: false }
+        );
+        const results = [];
+        for (const r of across) {
+          if (r.error) skipped.push({ vaultId: r.vault, reason: classifyShardSkip(r.error), error: r.error });
+          else for (const item of r.result) results.push(item);
+        }
+        return { records: results, skippedVaults: skipped };
+      }
+      /** Fan out across eligible shards and merge results. */
+      async toArray(options = {}) {
+        const { records, skippedVaults } = await this.fanoutRecords(options);
+        return { results: records, skippedVaults };
+      }
+      /** @internal — build the change-subscription + relevance binding for this query's group+collection. */
+      liveBinding() {
+        const group = this.group;
+        const collectionName = this.collectionName;
+        return {
+          subscribeToChanges: (h) => {
+            group.db.on("change", h);
+            return () => group.db.off("change", h);
+          },
+          isRelevant: (e) => e.collection === collectionName && e.vault.startsWith(`${group.name}--`)
+        };
+      }
+      /** Returns a reactive cross-shard live query — a facade over CrossVaultLive. */
+      live(options = {}) {
+        const bind = this.liveBinding();
+        const core = new CrossVaultLive({
+          ...bind,
+          compute: async () => {
+            const { records, skippedVaults } = await this.fanoutRecords(options);
+            return { records, skipped: skippedVaults };
+          },
+          initialSnapshot: { records: [], skipped: [] },
+          ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
+        });
+        return {
+          get value() {
+            return core.snapshot.records;
+          },
+          get skippedVaults() {
+            return core.snapshot.skipped;
+          },
+          get error() {
+            return core.error;
+          },
+          ready: core.ready,
+          subscribe: (cb) => core.subscribe(cb),
+          stop: () => core.stop()
+        };
+      }
+      /** One-shot distributed aggregate — central reduce over all shard records. */
+      aggregate(spec) {
+        return new CrossVaultAggregation(this, spec, this.liveBinding());
+      }
+      /** Begin a grouped cross-shard aggregate. */
+      groupBy(field) {
+        return new ShardedGroupedQuery(this, field);
+      }
+    };
+    ShardedGroupedQuery = class {
+      constructor(query, field) {
+        this.query = query;
+        this.field = field;
+      }
+      query;
+      field;
+      aggregate(spec) {
+        return new CrossVaultGroupedAggregation(
+          { fanoutRecords: (o) => this.query.fanoutRecords(o) },
+          this.field,
+          spec,
+          this.query.liveBinding()
+        );
+      }
+    };
+  }
+});
+
 // src/noydb.ts
 var noydb_exports = {};
 __export(noydb_exports, {
@@ -16101,6 +17507,7 @@ var init_noydb = __esm({
       writeRelay;
       /** Per-vault policy enforcers. */
       policyEnforcers = /* @__PURE__ */ new Map();
+      vaultTemplates = /* @__PURE__ */ new Map();
       txStrategy;
       sessionStrategy;
       syncStrategy;
@@ -16170,7 +17577,7 @@ var init_noydb = __esm({
           await registry.runChecks(e.collection, incoming, ctx);
           const { GuardExecutor: GuardExecutor2 } = await Promise.resolve().then(() => (init_executor3(), executor_exports3));
           for (const g of guards) {
-            await GuardExecutor2.checkFrozenFields(g, e.docId, existing, incoming);
+            await GuardExecutor2.checkFrozenFields(g, e.docId, existing, incoming, e.computedFieldNames);
           }
         });
         this.subsystemBus.registerGate("beforeDelete", async (e) => {
@@ -16349,6 +17756,7 @@ var init_noydb = __esm({
           syncAdapter: targets.length > 0 ? targets[0].store : void 0,
           historyConfig: this.options.history,
           ...this.options.blobStrategy !== void 0 ? { blobStrategy: this.options.blobStrategy } : {},
+          ...this.options.archiveStrategy !== void 0 ? { archiveStrategy: this.options.archiveStrategy } : {},
           ...this.options.indexStrategy !== void 0 ? { indexStrategy: this.options.indexStrategy } : {},
           ...this.options.aggregateStrategy !== void 0 ? { aggregateStrategy: this.options.aggregateStrategy } : {},
           ...this.options.crdtStrategy !== void 0 ? { crdtStrategy: this.options.crdtStrategy } : {},
@@ -16402,6 +17810,7 @@ var init_noydb = __esm({
             emitter: this.emitter,
             historyConfig: this.options.history,
             ...this.options.blobStrategy !== void 0 ? { blobStrategy: this.options.blobStrategy } : {},
+            ...this.options.archiveStrategy !== void 0 ? { archiveStrategy: this.options.archiveStrategy } : {},
             ...this.options.indexStrategy !== void 0 ? { indexStrategy: this.options.indexStrategy } : {},
             ...this.options.aggregateStrategy !== void 0 ? { aggregateStrategy: this.options.aggregateStrategy } : {},
             ...this.options.crdtStrategy !== void 0 ? { crdtStrategy: this.options.crdtStrategy } : {},
@@ -16430,6 +17839,7 @@ var init_noydb = __esm({
           encrypted: true,
           historyConfig: this.options.history,
           ...this.options.blobStrategy !== void 0 ? { blobStrategy: this.options.blobStrategy } : {},
+          ...this.options.archiveStrategy !== void 0 ? { archiveStrategy: this.options.archiveStrategy } : {},
           ...this.options.indexStrategy !== void 0 ? { indexStrategy: this.options.indexStrategy } : {},
           ...this.options.aggregateStrategy !== void 0 ? { aggregateStrategy: this.options.aggregateStrategy } : {},
           ...this.options.crdtStrategy !== void 0 ? { crdtStrategy: this.options.crdtStrategy } : {},
@@ -16744,6 +18154,32 @@ var init_noydb = __esm({
         }
         return results;
       }
+      /**
+       * Register a shard schema blueprint. `createShard` / `openVaultGroup`
+       * stamp shards from the named template. See the MVF design spec.
+       */
+      withVaultTemplate(name, template) {
+        this.vaultTemplates.set(name, template);
+      }
+      /**
+       * Open a VaultGroup — transparent routing over per-partition shard
+       * vaults, with shard discovery backed by the supplied `vault-registry`
+       * collection.
+       */
+      async openVaultGroup(name, opts) {
+        if (this.closed) throw new ValidationError("Instance is closed");
+        const template = this.vaultTemplates.get(opts.sharding.vaultTemplate);
+        if (!template) throw new VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
+        const { VaultGroup: VaultGroup2 } = await Promise.resolve().then(() => (init_vault_group(), vault_group_exports));
+        return new VaultGroup2(this, name, opts.registry, opts.sharding, template);
+      }
+      /**
+       * @internal — true when an encrypted shard vault is provisioned
+       * (its keyring exists in the store).
+       */
+      async _shardVaultProvisioned(vaultId) {
+        return (await this.options.store.list(vaultId, "_keyring")).length > 0;
+      }
       /**
        * Change the current user's passphrase for a vault.
        *