@noy-db/hub 0.2.0-pre.5 → 0.2.0-pre.7

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, PeriodClosedError, RecordLockedError, FieldFrozenError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, PeriodClosedError, RecordLockedError, FieldFrozenError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, 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;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -646,6 +646,34 @@ Resolutions:
         this.side = opts.side;
       }
     };
+    CrossJoinTooLargeError = class extends NoydbError {
+      target;
+      expected;
+      limit;
+      constructor(opts) {
+        super(
+          "CROSS_JOIN_TOO_LARGE",
+          `crossJoin("${opts.target}"): would produce ${opts.expected} rows, exceeding the limit of ${opts.limit}. Narrow the left side with .where() first, or raise the ceiling with crossJoin("${opts.target}", { ..., maxRows: ${opts.expected} }).`
+        );
+        this.name = "CrossJoinTooLargeError";
+        this.target = opts.target;
+        this.expected = opts.expected;
+        this.limit = opts.limit;
+      }
+    };
+    CrossJoinSourceUnknownError = class extends NoydbError {
+      target;
+      leftCollection;
+      constructor(target, leftCollection) {
+        super(
+          "CROSS_JOIN_SOURCE_UNKNOWN",
+          `crossJoin("${target}"): collection "${target}" is not known in the vault (cross-joining from "${leftCollection}"). Make sure "${target}" is open in the same vault before executing this query.`
+        );
+        this.name = "CrossJoinSourceUnknownError";
+        this.target = target;
+        this.leftCollection = leftCollection;
+      }
+    };
     DanglingReferenceError = class extends NoydbError {
       field;
       target;
@@ -836,6 +864,17 @@ Resolutions:
         this.expected = expected;
       }
     };
+    SnapshotNotFoundError = class extends NoydbError {
+      version;
+      constructor(version) {
+        super(
+          "SNAPSHOT_NOT_FOUND",
+          `Snapshot not found: "${version}" does not exist in the snapshot store. It may have been pruned by the retention policy or deleted manually.`
+        );
+        this.name = "SnapshotNotFoundError";
+        this.version = version;
+      }
+    };
   }
 });
 
@@ -2231,6 +2270,10 @@ function evaluateClause(record, clause) {
       return clause.fn(record);
     case "wherePredicate":
       return clause.fn(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.`
+      );
     case "group":
       if (clause.op === "and") {
         for (const child of clause.clauses) {
@@ -2800,6 +2843,11 @@ function analyzeDependencies(query) {
   for (const leg of plan.joins) {
     deps.add(leg.target);
   }
+  for (const clause of plan.clauses) {
+    if (clause.type === "crossJoin") {
+      deps.add(clause.target);
+    }
+  }
   walkClausesForJoins(plan, deps, ctx);
   return deps;
 }
@@ -2815,7 +2863,19 @@ function summarizeQueryPlan(query) {
   const ctx = query._joinContext();
   return JSON.stringify({
     root: ctx?.leftCollection ?? null,
-    clauses: plan.clauses,
+    clauses: plan.clauses.map((c) => {
+      if (c.type === "crossJoin") {
+        return {
+          type: "crossJoin",
+          target: c.target,
+          as: c.as,
+          // Inline on: callback: use sentinel — drift detection disabled for this MV
+          onPredicateName: c.onPredicateName ?? (c.on ? "[inline]" : null),
+          maxRows: c.maxRows ?? null
+        };
+      }
+      return c;
+    }),
     orderBy: plan.orderBy,
     limit: plan.limit ?? null,
     offset: plan.offset,
@@ -3942,7 +4002,10 @@ __export(src_exports, {
   CollectionIndexes: () => CollectionIndexes,
   CollectionInstant: () => CollectionInstant,
   ConflictError: () => ConflictError,
+  CrossJoinSourceUnknownError: () => CrossJoinSourceUnknownError,
+  CrossJoinTooLargeError: () => CrossJoinTooLargeError,
   DEFAULT_CHUNK_SIZE: () => DEFAULT_CHUNK_SIZE,
+  DEFAULT_CROSS_JOIN_MAX_ROWS: () => DEFAULT_CROSS_JOIN_MAX_ROWS,
   DEFAULT_FRESHNESS_MS: () => DEFAULT_FRESHNESS_MS,
   DEFAULT_JOIN_MAX_ROWS: () => DEFAULT_JOIN_MAX_ROWS,
   DEFAULT_PUBLIC_ENVELOPE_SCHEMA: () => DEFAULT_PUBLIC_ENVELOPE_SCHEMA,
@@ -4055,6 +4118,7 @@ __export(src_exports, {
   SessionExpiredError: () => SessionExpiredError,
   SessionNotFoundError: () => SessionNotFoundError,
   SessionPolicyError: () => SessionPolicyError,
+  SnapshotNotFoundError: () => SnapshotNotFoundError,
   StoreCapabilityError: () => StoreCapabilityError,
   SyncEngine: () => SyncEngine,
   SyncScheduler: () => SyncScheduler,
@@ -6223,6 +6287,7 @@ function withHealthCheck(opts = {}) {
 
 // src/index.ts
 init_errors();
+init_errors();
 
 // src/bundle/format.ts
 var NOYDB_BUNDLE_MAGIC = new Uint8Array([78, 68, 66, 49]);
@@ -9677,6 +9742,173 @@ var NO_CRDT = {
   }
 };
 
+// src/i18n/core.ts
+init_errors();
+function i18nText(options) {
+  return { _noydbI18nText: true, options };
+}
+function isI18nTextDescriptor(x) {
+  return typeof x === "object" && x !== null && x._noydbI18nText === true;
+}
+function validateI18nTextValue(value, field, descriptor) {
+  const { options } = descriptor;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new MissingTranslationError(
+      field,
+      options.languages,
+      `Field "${field}" must be a { [locale]: string } map, got ${typeof value}.`
+    );
+  }
+  const map = value;
+  for (const [locale, v] of Object.entries(map)) {
+    if (typeof v !== "string") {
+      throw new MissingTranslationError(
+        field,
+        [locale],
+        `Field "${field}": locale "${locale}" must be a string, got ${typeof v}.`
+      );
+    }
+  }
+  const { required } = options;
+  if (required === "all") {
+    const missing = options.languages.filter(
+      (lang) => !(lang in map) || map[lang] === ""
+    );
+    if (missing.length > 0) {
+      throw new MissingTranslationError(
+        field,
+        missing,
+        `Field "${field}" requires all declared languages. Missing: ${missing.join(", ")}.`
+      );
+    }
+  } else if (required === "any") {
+    const present = options.languages.some(
+      (lang) => lang in map && map[lang] !== ""
+    );
+    if (!present) {
+      throw new MissingTranslationError(
+        field,
+        options.languages,
+        `Field "${field}" requires at least one declared language. None present.`
+      );
+    }
+  } else {
+    const requiredList = required;
+    const missing = requiredList.filter(
+      (lang) => !(lang in map) || map[lang] === ""
+    );
+    if (missing.length > 0) {
+      throw new MissingTranslationError(
+        field,
+        missing,
+        `Field "${field}" requires: ${requiredList.join(", ")}. Missing: ${missing.join(", ")}.`
+      );
+    }
+  }
+}
+function resolveI18nText(value, locale, fallback, field) {
+  if (locale === "raw") {
+    return value;
+  }
+  if (!locale) {
+    throw new LocaleNotSpecifiedError(field ?? "<unknown>");
+  }
+  if (value[locale] !== void 0 && value[locale] !== "") {
+    return value[locale];
+  }
+  const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+  for (const fb of chain) {
+    if (fb === "any") {
+      const any = Object.values(value).find((v) => v !== "");
+      if (any !== void 0) return any;
+    } else if (value[fb] !== void 0 && value[fb] !== "") {
+      return value[fb];
+    }
+  }
+  throw new LocaleNotSpecifiedError(
+    field ?? "<unknown>",
+    `No translation available for locale "${locale}"` + (chain.length > 0 ? ` or fallback chain [${chain.join(", ")}]` : "") + "."
+  );
+}
+function getAtPath(obj, path) {
+  const arrayIdx = path.indexOf("[].");
+  if (arrayIdx !== -1) {
+    const arrayKey = path.slice(0, arrayIdx);
+    const restPath = path.slice(arrayIdx + 3);
+    const arr = obj[arrayKey];
+    if (!Array.isArray(arr)) return [];
+    return arr.flatMap((item) => {
+      if (!item || typeof item !== "object" || Array.isArray(item)) return [];
+      return getAtPath(item, restPath);
+    });
+  }
+  const dotIdx = path.indexOf(".");
+  if (dotIdx !== -1) {
+    const head = path.slice(0, dotIdx);
+    const rest = path.slice(dotIdx + 1);
+    const nested = obj[head];
+    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return [];
+    return getAtPath(nested, rest);
+  }
+  const val = obj[path];
+  return val !== void 0 ? [val] : [];
+}
+function setAtPathInPlace(obj, path, value) {
+  const dotIdx = path.indexOf(".");
+  if (dotIdx !== -1) {
+    const head = path.slice(0, dotIdx);
+    const rest = path.slice(dotIdx + 1);
+    const nested = obj[head];
+    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return;
+    setAtPathInPlace(nested, rest, value);
+    return;
+  }
+  obj[path] = value;
+}
+function applyAtPath(obj, path, locale, fallback) {
+  const arrayIdx = path.indexOf("[].");
+  if (arrayIdx !== -1) {
+    const arrayKey = path.slice(0, arrayIdx);
+    const restPath = path.slice(arrayIdx + 3);
+    const arr = obj[arrayKey];
+    if (!Array.isArray(arr)) return obj;
+    return {
+      ...obj,
+      [arrayKey]: arr.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+        return applyAtPath(item, restPath, locale, fallback);
+      })
+    };
+  }
+  const dotIdx = path.indexOf(".");
+  if (dotIdx !== -1) {
+    const head = path.slice(0, dotIdx);
+    const rest = path.slice(dotIdx + 1);
+    const nested = obj[head];
+    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return obj;
+    return {
+      ...obj,
+      [head]: applyAtPath(nested, rest, locale, fallback)
+    };
+  }
+  const raw = obj[path];
+  if (raw === void 0 || raw === null) return obj;
+  if (typeof raw !== "object" || Array.isArray(raw)) return obj;
+  return {
+    ...obj,
+    [path]: resolveI18nText(raw, locale, fallback, path)
+  };
+}
+function applyI18nLocale(record, i18nFields, locale, fallback) {
+  const fieldNames = Object.keys(i18nFields);
+  if (fieldNames.length === 0) return record;
+  let result = record;
+  for (const field of fieldNames) {
+    result = applyAtPath(result, field, locale, fallback);
+  }
+  return result;
+}
+
 // src/i18n/strategy.ts
 function notEnabled(op) {
   return new Error(
@@ -9898,6 +10130,9 @@ function resetJoinWarnings() {
   warnedCeilingKeys.clear();
 }
 
+// src/query/builder.ts
+init_errors();
+
 // src/query/live.ts
 function buildLiveQuery(recompute, upstreams) {
   return new LiveQueryImpl(recompute, upstreams);
@@ -9996,6 +10231,7 @@ var EMPTY_PLAN = {
   offset: 0,
   joins: []
 };
+var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
 var Query = class _Query {
   source;
   plan;
@@ -10277,6 +10513,78 @@ var Query = class _Query {
       this.predicates
     );
   }
+  /**
+   * Cartesian-product cross-join against `target` collection. Each result row
+   * carries the original `T` fields plus `result[as]` populated from every
+   * right-side row (or the filtered subset when `on:` is supplied).
+   *
+   * **Order matters:** `.where().crossJoin()` filters BEFORE expanding (cheaper);
+   * `.crossJoin().where('alias.field', ...)` filters AFTER (required when the
+   * where clause references the aliased fields).
+   *
+   * **Cost ceiling:** `CrossJoinTooLargeError` fires before allocation when
+   * `leftRows × rightRows` (or the cumulative lateral count) exceeds the limit.
+   * Default: 50,000 rows. Override per-clause with `{ maxRows: N }`.
+   *
+   * **`on:` shapes:**
+   *   - `on: (left) => TTarget[]`              — subset form (most efficient)
+   *   - `on: (left) => (right) => boolean`     — predicate form
+   *   - `on: { predicate: 'name' }`            — MV-safe, hash-tracked form
+   *     (requires the Query to have been augmented via `_withPredicates`)
+   *
+   * Requires a JoinContext (constructed via `collection.query()`).
+   */
+  crossJoin(target, opts) {
+    if (!this.joinContext) {
+      throw new Error(
+        `Query.crossJoin("${target}"): requires a join context. Use collection.query() to construct a cross-join-capable Query instead of the Query constructor directly.`
+      );
+    }
+    let onFn;
+    let onPredicateName;
+    if (opts.on !== void 0) {
+      if (typeof opts.on === "function") {
+        onFn = opts.on;
+        if (this.predicates) {
+          console.warn(
+            `Query.crossJoin("${target}", { on: callback }): inline on: callback inside a withMaterializedView query() disables queryHash drift detection for this cross-join. Use on: { predicate: '<name>' } to enable it.`
+          );
+        }
+      } else {
+        const predName = opts.on.predicate;
+        if (!this.predicates) {
+          throw new Error(
+            `Query.crossJoin("${target}", { on: { predicate: "${predName}" } }): the { predicate } form requires a predicates map. Use this form inside a withMaterializedView query() callback that declares predicates: { ${predName}: { hash, fn } }.`
+          );
+        }
+        const decl = this.predicates.get(predName);
+        if (!decl) {
+          throw new Error(
+            `Query.crossJoin("${target}"): predicate "${predName}" not registered. Available: ${[...this.predicates.keys()].join(", ") || "(none)"}.`
+          );
+        }
+        const as = opts.as;
+        const predicateFn = decl.fn;
+        onFn = (_left) => (right) => predicateFn({ ..._left, [as]: right });
+        onPredicateName = predName;
+      }
+    }
+    const clause = {
+      type: "crossJoin",
+      target,
+      as: opts.as,
+      ...onFn !== void 0 && { on: onFn },
+      ...onPredicateName !== void 0 && { onPredicateName },
+      ...opts.maxRows !== void 0 && { maxRows: opts.maxRows }
+    };
+    return new _Query(
+      this.source,
+      { ...this.plan, clauses: [...this.plan.clauses, clause] },
+      this.joinContext,
+      this.aggregateStrategy,
+      this.predicates
+    );
+  }
   /**
    * Execute the plan and return the matching records. When the plan
    * carries any join legs, they are applied after `where` / `orderBy`
@@ -10284,7 +10592,7 @@ var Query = class _Query {
    * for the ordering rationale.
    */
   toArray() {
-    const base = executePlanWithSource(this.source, this.plan);
+    const base = executePlanWithSource(this.source, this.plan, this.joinContext);
     if (this.plan.joins.length === 0) return base;
     if (!this.joinContext) {
       throw new Error(
@@ -10308,6 +10616,14 @@ var Query = class _Query {
    * intent is purely to count.
    */
   count() {
+    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+      if (!this.joinContext) {
+        throw new Error(
+          `Query.count(): plan contains crossJoin clauses but no JoinContext is attached.`
+        );
+      }
+      return executeClausePipeline(this.source, this.plan.clauses, this.joinContext).length;
+    }
     const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
     if (remainingClauses.length === 0) return candidates.length;
     return filterRecords(candidates, remainingClauses).length;
@@ -10355,7 +10671,13 @@ var Query = class _Query {
   aggregate(spec) {
     const source = this.source;
     const clauses = this.plan.clauses;
+    const joinCtx = this.joinContext;
+    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
     const executeRecords = () => {
+      if (hasCrossJoins) {
+        if (!joinCtx) throw new Error("Query.aggregate(): crossJoin requires a join context");
+        return executeClausePipeline(source, clauses, joinCtx);
+      }
       const { candidates, remainingClauses } = candidateRecords(source, clauses);
       return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
     };
@@ -10372,7 +10694,13 @@ var Query = class _Query {
     }
     const source = this.source;
     const clauses = this.plan.clauses;
+    const joinCtx = this.joinContext;
+    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
     const executeRecords = () => {
+      if (hasCrossJoins) {
+        if (!joinCtx) throw new Error("Query.groupBy(): crossJoin requires a join context");
+        return executeClausePipeline(source, clauses, joinCtx);
+      }
       const { candidates, remainingClauses } = candidateRecords(source, clauses);
       return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
     };
@@ -10486,6 +10814,21 @@ var Query = class _Query {
         }
       }
     }
+    if (this.joinContext) {
+      const subscribedCross = /* @__PURE__ */ new Set();
+      for (const clause of this.plan.clauses) {
+        if (clause.type !== "crossJoin") continue;
+        if (subscribedCross.has(clause.target)) continue;
+        subscribedCross.add(clause.target);
+        const rightSource = this.joinContext.resolveSource(clause.target);
+        if (rightSource?.subscribe) {
+          const rightSubscribe = rightSource.subscribe.bind(rightSource);
+          upstreams.push({
+            subscribe: (cb) => rightSubscribe(cb)
+          });
+        }
+      }
+    }
     return buildLiveQuery(() => this.toArray(), upstreams);
   }
   /**
@@ -10497,9 +10840,20 @@ var Query = class _Query {
     return serializePlan(this.plan);
   }
 };
-function executePlanWithSource(source, plan) {
-  const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
-  let result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+function executePlanWithSource(source, plan, joinContext) {
+  const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
+  let result;
+  if (hasCrossJoins) {
+    if (!joinContext) {
+      throw new Error(
+        `Query.toArray(): plan contains crossJoin clauses but no JoinContext is attached. Use collection.query() instead of new Query() for cross-join support.`
+      );
+    }
+    result = executeClausePipeline(source, plan.clauses, joinContext);
+  } else {
+    const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
+    result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+  }
   if (plan.orderBy.length > 0) {
     result = sortRecords(result, plan.orderBy);
   }
@@ -10549,6 +10903,11 @@ function materializeIds(ids, lookupById) {
   return out;
 }
 function executePlan(records, plan) {
+  if (plan.clauses.some((c) => c.type === "crossJoin")) {
+    throw new Error(
+      `executePlan(): does not support crossJoin clauses. executePlan is a stateless pure function \u2014 it cannot resolve cross-join right-side collections. Use Query.toArray() (via collection.query()) instead.`
+    );
+  }
   let result = filterRecords(records, plan.clauses);
   if (plan.orderBy.length > 0) {
     result = sortRecords(result, plan.orderBy);
@@ -10576,6 +10935,74 @@ function filterRecords(records, clauses) {
   }
   return out;
 }
+function executeClausePipeline(source, clauses, joinContext) {
+  let rel = [...source.snapshot()];
+  let filterBatch = [];
+  for (const clause of clauses) {
+    if (clause.type === "crossJoin") {
+      if (filterBatch.length > 0) {
+        rel = filterRecords(rel, filterBatch);
+        filterBatch = [];
+      }
+      const rightSource = joinContext.resolveSource(clause.target);
+      if (!rightSource) {
+        throw new CrossJoinSourceUnknownError(clause.target, joinContext.leftCollection);
+      }
+      rel = applyCrossJoin(rel, clause, rightSource);
+    } else {
+      filterBatch.push(clause);
+    }
+  }
+  if (filterBatch.length > 0) {
+    rel = filterRecords(rel, filterBatch);
+  }
+  return rel;
+}
+function applyCrossJoin(leftRel, clause, rightSource) {
+  const rightRows = rightSource.snapshot();
+  const maxRows = clause.maxRows ?? DEFAULT_CROSS_JOIN_MAX_ROWS;
+  const { as } = clause;
+  if (!clause.on) {
+    const product = leftRel.length * rightRows.length;
+    if (product > maxRows) {
+      throw new CrossJoinTooLargeError({ target: clause.target, expected: product, limit: maxRows });
+    }
+    const expanded2 = [];
+    for (const left of leftRel) {
+      const leftObj = left;
+      for (const right of rightRows) {
+        expanded2.push({ ...leftObj, [as]: right });
+      }
+    }
+    return expanded2;
+  }
+  const expanded = [];
+  let cumulative = 0;
+  for (const left of leftRel) {
+    const callbackResult = clause.on(left);
+    let filteredRight;
+    if (Array.isArray(callbackResult)) {
+      filteredRight = callbackResult;
+    } else {
+      filteredRight = rightRows.filter(
+        callbackResult
+      );
+    }
+    cumulative += filteredRight.length;
+    if (cumulative > maxRows) {
+      throw new CrossJoinTooLargeError({
+        target: clause.target,
+        expected: cumulative,
+        limit: maxRows
+      });
+    }
+    const leftObj = left;
+    for (const right of filteredRight) {
+      expanded.push({ ...leftObj, [as]: right });
+    }
+  }
+  return expanded;
+}
 function sortRecords(records, orderBy) {
   return [...records].sort((a, b) => {
     for (const { field, direction } of orderBy) {
@@ -10638,6 +11065,16 @@ function serializeClause(clause) {
       clauses: clause.clauses.map(serializeClause)
     };
   }
+  if (clause.type === "crossJoin") {
+    return {
+      type: "crossJoin",
+      target: clause.target,
+      as: clause.as,
+      on: clause.on ? "[function]" : void 0,
+      onPredicateName: clause.onPredicateName,
+      maxRows: clause.maxRows
+    };
+  }
   return clause;
 }
 function canonicalCtxHash(ctx) {
@@ -12645,7 +13082,9 @@ var Collection = class {
       const obj = record;
       for (const [field, descriptor] of Object.entries(this.i18nFields)) {
         if (!descriptor.options.autoTranslate) continue;
-        const value = obj[field];
+        const leafValues = getAtPath(obj, field);
+        if (leafValues.length !== 1) continue;
+        const value = leafValues[0];
         if (!value || typeof value !== "object" || Array.isArray(value)) continue;
         const map = value;
         const { languages, required } = descriptor.options;
@@ -12669,8 +13108,7 @@ var Collection = class {
             this.name
           );
         }
-        ;
-        record[field] = translated;
+        setAtPathInPlace(obj, field, translated);
       }
     }
     if (this.i18nPutValidator !== void 0) {
@@ -16736,9 +17174,11 @@ var Vault = class {
     if (!record || typeof record !== "object") return;
     const obj = record;
     for (const [field, descriptor] of Object.entries(i18nFields)) {
-      const value = obj[field];
-      if (value === void 0 || value === null) continue;
-      this.i18nStrategy.validateI18nTextValue(value, field, descriptor);
+      const values = getAtPath(obj, field);
+      for (const value of values) {
+        if (value === void 0 || value === null) continue;
+        this.i18nStrategy.validateI18nTextValue(value, field, descriptor);
+      }
     }
   }
   /**
@@ -19294,16 +19734,32 @@ function isTabWriteMsg(x) {
   return o["kind"] === "tab-write" && typeof o["writerId"] === "string" && typeof o["vault"] === "string" && typeof o["collection"] === "string" && typeof o["docId"] === "string" && (o["action"] === "put" || o["action"] === "delete") && typeof o["baseV"] === "number" && typeof o["v"] === "number";
 }
 
-// src/tx/strategy.ts
+// src/snapshots/strategy.ts
 var NOT_ENABLED5 = new Error(
+  'Snapshots require the snapshot strategy. Import `{ withSnapshots }` from "@noy-db/hub/snapshots" and pass it to `createNoydb({ snapshotStrategy: withSnapshots({ store }) })`.'
+);
+var NO_SNAPSHOTS = {
+  async snapshot() {
+    throw NOT_ENABLED5;
+  },
+  async listSnapshots() {
+    throw NOT_ENABLED5;
+  },
+  async restoreSnapshot() {
+    throw NOT_ENABLED5;
+  }
+};
+
+// src/tx/strategy.ts
+var NOT_ENABLED6 = new Error(
   'Multi-record transactions require the tx strategy. Import `{ withTransactions }` from "@noy-db/hub/tx" and pass it to `createNoydb({ txStrategy: withTransactions() })`.'
 );
 var NO_TX = {
   async runTransaction() {
-    throw NOT_ENABLED5;
+    throw NOT_ENABLED6;
   },
   async runDryRun() {
-    throw NOT_ENABLED5;
+    throw NOT_ENABLED6;
   }
 };
 
@@ -19646,6 +20102,7 @@ var Noydb = class {
   txStrategy;
   sessionStrategy;
   syncStrategy;
+  snapshotStrategy;
   /**
    * Currently-running multi-record transaction, set by
    * `runTransaction` at the start of Phase 2 (commit) and cleared in
@@ -19670,6 +20127,7 @@ var Noydb = class {
     this.txStrategy = options.txStrategy ?? NO_TX;
     this.sessionStrategy = options.sessionStrategy ?? NO_SESSION;
     this.syncStrategy = options.syncStrategy ?? NO_SYNC;
+    this.snapshotStrategy = options.snapshotStrategy ?? NO_SNAPSHOTS;
     this.publicEnvelopeSchema = resolveSchema(options.publicEnvelope);
     if (options.sessionPolicy) {
       this.sessionStrategy.validateSessionPolicy(options.sessionPolicy);
@@ -21656,6 +22114,45 @@ var Noydb = class {
     this.keyringCache.set(vault, keyring);
     return keyring;
   }
+  /**
+   * Take an on-demand checkpoint of the given vault.
+   * Requires `snapshotStrategy: withSnapshots({ store })` in `createNoydb`.
+   * @throws ValidationError when the vault is not open
+   */
+  async snapshot(vault, opts) {
+    if (this.closed) throw new ValidationError("Instance is closed");
+    const v = this.vaultCache.get(vault);
+    if (!v) {
+      throw new ValidationError(
+        `Vault "${vault}" is not open. Call openVault() first.`
+      );
+    }
+    return this.snapshotStrategy.snapshot(v, this.options.user, opts);
+  }
+  /**
+   * List all snapshots for the given vault, newest first.
+   * Reads only the sidecar index — does not download snapshot bytes.
+   */
+  async listSnapshots(vault) {
+    if (this.closed) throw new ValidationError("Instance is closed");
+    return this.snapshotStrategy.listSnapshots(vault);
+  }
+  /**
+   * Restore the vault to a previously snapshotted state.
+   * Runs `verifyBackupIntegrity()` automatically on restore.
+   * @throws SnapshotNotFoundError when `version` doesn't exist in the store
+   * @throws ValidationError when the vault is not open
+   */
+  async restoreSnapshot(vault, version) {
+    if (this.closed) throw new ValidationError("Instance is closed");
+    const v = this.vaultCache.get(vault);
+    if (!v) {
+      throw new ValidationError(
+        `Vault "${vault}" is not open. Call openVault() first.`
+      );
+    }
+    return this.snapshotStrategy.restoreSnapshot(v, version);
+  }
 };
 async function createNoydb(options) {
   const encrypted = options.encrypt !== false;
@@ -22622,114 +23119,6 @@ function withOverlayedView(spec) {
 // src/index.ts
 init_errors();
 init_errors();
-
-// src/i18n/core.ts
-init_errors();
-function i18nText(options) {
-  return { _noydbI18nText: true, options };
-}
-function isI18nTextDescriptor(x) {
-  return typeof x === "object" && x !== null && x._noydbI18nText === true;
-}
-function validateI18nTextValue(value, field, descriptor) {
-  const { options } = descriptor;
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new MissingTranslationError(
-      field,
-      options.languages,
-      `Field "${field}" must be a { [locale]: string } map, got ${typeof value}.`
-    );
-  }
-  const map = value;
-  for (const [locale, v] of Object.entries(map)) {
-    if (typeof v !== "string") {
-      throw new MissingTranslationError(
-        field,
-        [locale],
-        `Field "${field}": locale "${locale}" must be a string, got ${typeof v}.`
-      );
-    }
-  }
-  const { required } = options;
-  if (required === "all") {
-    const missing = options.languages.filter(
-      (lang) => !(lang in map) || map[lang] === ""
-    );
-    if (missing.length > 0) {
-      throw new MissingTranslationError(
-        field,
-        missing,
-        `Field "${field}" requires all declared languages. Missing: ${missing.join(", ")}.`
-      );
-    }
-  } else if (required === "any") {
-    const present = options.languages.some(
-      (lang) => lang in map && map[lang] !== ""
-    );
-    if (!present) {
-      throw new MissingTranslationError(
-        field,
-        options.languages,
-        `Field "${field}" requires at least one declared language. None present.`
-      );
-    }
-  } else {
-    const requiredList = required;
-    const missing = requiredList.filter(
-      (lang) => !(lang in map) || map[lang] === ""
-    );
-    if (missing.length > 0) {
-      throw new MissingTranslationError(
-        field,
-        missing,
-        `Field "${field}" requires: ${requiredList.join(", ")}. Missing: ${missing.join(", ")}.`
-      );
-    }
-  }
-}
-function resolveI18nText(value, locale, fallback, field) {
-  if (locale === "raw") {
-    return value;
-  }
-  if (!locale) {
-    throw new LocaleNotSpecifiedError(field ?? "<unknown>");
-  }
-  if (value[locale] !== void 0 && value[locale] !== "") {
-    return value[locale];
-  }
-  const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
-  for (const fb of chain) {
-    if (fb === "any") {
-      const any = Object.values(value).find((v) => v !== "");
-      if (any !== void 0) return any;
-    } else if (value[fb] !== void 0 && value[fb] !== "") {
-      return value[fb];
-    }
-  }
-  throw new LocaleNotSpecifiedError(
-    field ?? "<unknown>",
-    `No translation available for locale "${locale}"` + (chain.length > 0 ? ` or fallback chain [${chain.join(", ")}]` : "") + "."
-  );
-}
-function applyI18nLocale(record, i18nFields, locale, fallback) {
-  const fieldNames = Object.keys(i18nFields);
-  if (fieldNames.length === 0) return record;
-  const result = { ...record };
-  for (const field of fieldNames) {
-    const raw = result[field];
-    if (raw === void 0 || raw === null) continue;
-    if (typeof raw !== "object" || Array.isArray(raw)) continue;
-    result[field] = resolveI18nText(
-      raw,
-      locale,
-      fallback,
-      field
-    );
-  }
-  return result;
-}
-
-// src/index.ts
 init_errors();
 
 // src/team/sync-credentials.ts
@@ -23378,7 +23767,10 @@ function shortJSON(value) {
   CollectionIndexes,
   CollectionInstant,
   ConflictError,
+  CrossJoinSourceUnknownError,
+  CrossJoinTooLargeError,
   DEFAULT_CHUNK_SIZE,
+  DEFAULT_CROSS_JOIN_MAX_ROWS,
   DEFAULT_FRESHNESS_MS,
   DEFAULT_JOIN_MAX_ROWS,
   DEFAULT_PUBLIC_ENVELOPE_SCHEMA,
@@ -23491,6 +23883,7 @@ function shortJSON(value) {
   SessionExpiredError,
   SessionNotFoundError,
   SessionPolicyError,
+  SnapshotNotFoundError,
   StoreCapabilityError,
   SyncEngine,
   SyncScheduler,