@noy-db/hub 0.2.0-pre.6 → 0.2.0-pre.8

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, ScriptViolationError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, SnapshotNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -564,6 +564,27 @@ Resolutions:
         this.field = field;
       }
     };
+    ScriptViolationError = class extends NoydbError {
+      /** The field whose value violated its script constraint. */
+      field;
+      /** The locale slot (e.g. `'en'`) that was checked. */
+      locale;
+      /** The Unicode scripts allowed for this slot. */
+      expected;
+      /** A short sample of the offending characters, for diagnostics. */
+      sample;
+      constructor(field, locale, expected, sample, message) {
+        super(
+          "SCRIPT_VIOLATION",
+          message ?? `Field "${field}" slot "${locale}" expects script(s) [${expected.join(", ")}] but contains disallowed character(s): "${sample}".`
+        );
+        this.name = "ScriptViolationError";
+        this.field = field;
+        this.locale = locale;
+        this.expected = expected;
+        this.sample = sample;
+      }
+    };
     TranslatorNotConfiguredError = class extends NoydbError {
       /** The field that requested auto-translation. */
       field;
@@ -646,6 +667,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 +885,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 +2291,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 +2864,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 +2884,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 +4023,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,
@@ -4052,9 +4136,11 @@ __export(src_exports, {
   SchemaLockedError: () => SchemaLockedError,
   SchemaUpdateError: () => SchemaUpdateError,
   SchemaValidationError: () => SchemaValidationError,
+  ScriptViolationError: () => ScriptViolationError,
   SessionExpiredError: () => SessionExpiredError,
   SessionNotFoundError: () => SessionNotFoundError,
   SessionPolicyError: () => SessionPolicyError,
+  SnapshotNotFoundError: () => SnapshotNotFoundError,
   StoreCapabilityError: () => StoreCapabilityError,
   SyncEngine: () => SyncEngine,
   SyncScheduler: () => SyncScheduler,
@@ -4126,6 +4212,7 @@ __export(src_exports, {
   enableDevUnlock: () => enableDevUnlock,
   encryptBytes: () => encryptBytes,
   encryptDeterministic: () => encryptDeterministic,
+  enforceScript: () => enforceScript,
   enrollAuthenticator: () => enrollAuthenticator,
   envelopePayloadHash: () => envelopePayloadHash,
   estimateEntropy: () => estimateEntropy,
@@ -4146,6 +4233,7 @@ __export(src_exports, {
   hasRecoveryEnrolled: () => hasRecoveryEnrolled,
   hashEntry: () => hashEntry,
   i18nText: () => i18nText,
+  inferScripts: () => inferScripts,
   isDevUnlockActive: () => isDevUnlockActive,
   isDictCollectionName: () => isDictCollectionName,
   isDictKeyDescriptor: () => isDictKeyDescriptor,
@@ -4206,6 +4294,7 @@ __export(src_exports, {
   resetJoinWarnings: () => resetJoinWarnings,
   resolveCrdtSnapshot: () => resolveCrdtSnapshot,
   resolveI18nText: () => resolveI18nText,
+  resolvePolicy: () => resolvePolicy,
   resolvePublicEnvelopeSchema: () => resolveSchema,
   resolveSession: () => resolveSession,
   revokeAllSessions: () => revokeAllSessions,
@@ -6223,6 +6312,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]);
@@ -9679,6 +9769,16 @@ var NO_CRDT = {
 
 // src/i18n/core.ts
 init_errors();
+
+// src/i18n/policy.ts
+function resolvePolicy(onMissing, layer) {
+  const explicit = onMissing && typeof onMissing === "object" ? onMissing[layer] : void 0;
+  const scalar = typeof onMissing === "string" ? onMissing : void 0;
+  const layerDefault = layer === "guard" ? "substitute" : void 0;
+  return explicit ?? layerDefault ?? scalar ?? "throw";
+}
+
+// src/i18n/core.ts
 function i18nText(options) {
   return { _noydbI18nText: true, options };
 }
@@ -9741,7 +9841,21 @@ function validateI18nTextValue(value, field, descriptor) {
     }
   }
 }
-function resolveI18nText(value, locale, fallback, field) {
+function toChain(fallback) {
+  return Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+}
+function pickFromChain(value, chain) {
+  for (const fb of chain) {
+    if (fb === "any") {
+      const any = Object.values(value).find((v) => v !== "");
+      if (any !== void 0) return any;
+    } else if (value[fb] !== void 0 && value[fb] !== "") {
+      return value[fb];
+    }
+  }
+  return void 0;
+}
+function resolveI18nText(value, locale, fallback, field, opts) {
   if (locale === "raw") {
     return value;
   }
@@ -9751,19 +9865,21 @@ function resolveI18nText(value, locale, fallback, field) {
   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];
-    }
+  const policy = opts?.policy ?? "throw";
+  const callerChain = toChain(fallback);
+  const callerHit = pickFromChain(value, callerChain);
+  if (callerHit !== void 0) return callerHit;
+  if (policy === "substitute") {
+    const subHit = pickFromChain(value, toChain(opts?.substitute));
+    if (subHit !== void 0) return subHit;
+  }
+  if (policy === "throw") {
+    throw new LocaleNotSpecifiedError(
+      field ?? "<unknown>",
+      `No translation available for locale "${locale}"` + (callerChain.length > 0 ? ` or fallback chain [${callerChain.join(", ")}]` : "") + "."
+    );
   }
-  throw new LocaleNotSpecifiedError(
-    field ?? "<unknown>",
-    `No translation available for locale "${locale}"` + (chain.length > 0 ? ` or fallback chain [${chain.join(", ")}]` : "") + "."
-  );
+  return null;
 }
 function getAtPath(obj, path) {
   const arrayIdx = path.indexOf("[].");
@@ -9800,7 +9916,7 @@ function setAtPathInPlace(obj, path, value) {
   }
   obj[path] = value;
 }
-function applyAtPath(obj, path, locale, fallback) {
+function applyAtPath(obj, path, locale, fallback, opts) {
   const arrayIdx = path.indexOf("[].");
   if (arrayIdx !== -1) {
     const arrayKey = path.slice(0, arrayIdx);
@@ -9811,7 +9927,7 @@ function applyAtPath(obj, path, locale, fallback) {
       ...obj,
       [arrayKey]: arr.map((item) => {
         if (!item || typeof item !== "object" || Array.isArray(item)) return item;
-        return applyAtPath(item, restPath, locale, fallback);
+        return applyAtPath(item, restPath, locale, fallback, opts);
       })
     };
   }
@@ -9823,7 +9939,7 @@ function applyAtPath(obj, path, locale, fallback) {
     if (!nested || typeof nested !== "object" || Array.isArray(nested)) return obj;
     return {
       ...obj,
-      [head]: applyAtPath(nested, rest, locale, fallback)
+      [head]: applyAtPath(nested, rest, locale, fallback, opts)
     };
   }
   const raw = obj[path];
@@ -9831,15 +9947,20 @@ function applyAtPath(obj, path, locale, fallback) {
   if (typeof raw !== "object" || Array.isArray(raw)) return obj;
   return {
     ...obj,
-    [path]: resolveI18nText(raw, locale, fallback, path)
+    [path]: resolveI18nText(raw, locale, fallback, path, opts)
   };
 }
-function applyI18nLocale(record, i18nFields, locale, fallback) {
+function applyI18nLocale(record, i18nFields, locale, fallback, layer = "read") {
   const fieldNames = Object.keys(i18nFields);
   if (fieldNames.length === 0) return record;
   let result = record;
-  for (const field of fieldNames) {
-    result = applyAtPath(result, field, locale, fallback);
+  for (const [field, descriptor] of Object.entries(i18nFields)) {
+    const { onMissing, substitute } = descriptor.options;
+    const opts = {
+      policy: resolvePolicy(onMissing, layer),
+      ...substitute !== void 0 ? { substitute } : {}
+    };
+    result = applyAtPath(result, field, locale, fallback, opts);
   }
   return result;
 }
@@ -9857,6 +9978,9 @@ var NO_I18N = {
   validateI18nTextValue() {
     throw notEnabled("i18nText field validation");
   },
+  enforceScript(value) {
+    return { value, warnings: [] };
+  },
   buildDictionaryHandle() {
     throw notEnabled("vault.dictionary()");
   }
@@ -10065,6 +10189,9 @@ function resetJoinWarnings() {
   warnedCeilingKeys.clear();
 }
 
+// src/query/builder.ts
+init_errors();
+
 // src/query/live.ts
 function buildLiveQuery(recompute, upstreams) {
   return new LiveQueryImpl(recompute, upstreams);
@@ -10163,6 +10290,7 @@ var EMPTY_PLAN = {
   offset: 0,
   joins: []
 };
+var DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
 var Query = class _Query {
   source;
   plan;
@@ -10444,6 +10572,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`
@@ -10451,7 +10651,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(
@@ -10475,6 +10675,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;
@@ -10522,7 +10730,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);
     };
@@ -10539,7 +10753,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);
     };
@@ -10653,6 +10873,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);
   }
   /**
@@ -10664,9 +10899,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);
   }
@@ -10716,6 +10962,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);
@@ -10743,6 +10994,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) {
@@ -10805,6 +11124,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) {
@@ -12841,6 +13170,22 @@ var Collection = class {
         setAtPathInPlace(obj, field, translated);
       }
     }
+    if (this.i18nFields) {
+      const obj = record;
+      for (const [field, descriptor] of Object.entries(this.i18nFields)) {
+        if (!descriptor.options.script) continue;
+        for (const leaf of getAtPath(obj, field)) {
+          if (!leaf || typeof leaf !== "object" || Array.isArray(leaf)) continue;
+          const leafMap = leaf;
+          const { value: cleaned } = this.i18nStrategy.enforceScript(
+            leafMap,
+            field,
+            descriptor
+          );
+          if (cleaned !== leafMap) Object.assign(leafMap, cleaned);
+        }
+      }
+    }
     if (this.i18nPutValidator !== void 0) {
       this.i18nPutValidator(record);
     }
@@ -14283,17 +14628,52 @@ var Collection = class {
     }
     if (hasDict && this.dictKeyFields && this.dictLabelResolver && locale !== "raw") {
       const withLabels = { ...result };
+      const resolver = this.dictLabelResolver;
       for (const [field, desc] of Object.entries(this.dictKeyFields)) {
-        const key = result[field];
-        if (typeof key !== "string") continue;
-        const label = await this.dictLabelResolver(
-          desc.name,
-          key,
-          locale,
-          localeOpts?.fallback
-        );
-        if (label !== void 0) {
-          withLabels[`${field}Label`] = label;
+        const policy = desc.onMissing ? resolvePolicy(desc.onMissing, "read") : "null";
+        const fallback = policy === "substitute" ? localeOpts?.fallback ?? desc.substitute : localeOpts?.fallback;
+        const resolveKey = async (key) => {
+          const label = await resolver(desc.name, key, locale, fallback);
+          if (label === void 0) {
+            if (policy === "throw") {
+              throw new LocaleNotSpecifiedError(
+                field,
+                `dictKey "${field}": no label for key "${key}" in locale "${locale}".`
+              );
+            }
+            return null;
+          }
+          return label;
+        };
+        if (field.includes("[].")) {
+          const parts = field.split("[].");
+          const arrayKey = parts[0];
+          const leaf = parts[1];
+          if (!leaf || leaf.includes(".")) continue;
+          const arr = withLabels[arrayKey];
+          if (!Array.isArray(arr)) continue;
+          const labelKey = `${leaf}Label`;
+          withLabels[arrayKey] = await Promise.all(
+            arr.map(async (el) => {
+              if (!el || typeof el !== "object" || Array.isArray(el)) return el;
+              const k = el[leaf];
+              if (typeof k !== "string") return el;
+              return { ...el, [labelKey]: await resolveKey(k) };
+            })
+          );
+          continue;
+        }
+        const val = result[field];
+        if (Array.isArray(val)) {
+          withLabels[`${field}Label`] = await Promise.all(
+            val.map(async (k) => ({
+              key: k,
+              label: typeof k === "string" ? await resolveKey(k) : null
+            }))
+          );
+        } else if (typeof val === "string") {
+          const label = await resolveKey(val);
+          if (label !== null) withLabels[`${field}Label`] = label;
         }
       }
       result = withLabels;
@@ -15168,8 +15548,14 @@ function dictCollectionName(dictionaryName) {
 function isDictCollectionName(name) {
   return name.startsWith(DICT_COLLECTION_PREFIX);
 }
-function dictKey(name, keys) {
-  return { _noydbDictKey: true, name, keys };
+function dictKey(name, keys, opts) {
+  return {
+    _noydbDictKey: true,
+    name,
+    keys,
+    ...opts?.onMissing !== void 0 ? { onMissing: opts.onMissing } : {},
+    ...opts?.substitute !== void 0 ? { substitute: opts.substitute } : {}
+  };
 }
 function isDictKeyDescriptor(x) {
   return typeof x === "object" && x !== null && x._noydbDictKey === true;
@@ -19464,16 +19850,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;
   }
 };
 
@@ -19816,6 +20218,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
@@ -19840,6 +20243,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);
@@ -21826,6 +22230,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;
@@ -22792,6 +23235,139 @@ function withOverlayedView(spec) {
 // src/index.ts
 init_errors();
 init_errors();
+
+// src/i18n/script.ts
+init_errors();
+var LATIN_BASE = /* @__PURE__ */ new Set([
+  "en",
+  "fr",
+  "de",
+  "es",
+  "it",
+  "pt",
+  "nl",
+  "sv",
+  "no",
+  "da",
+  "fi",
+  "is",
+  "pl",
+  "cs",
+  "sk",
+  "hu",
+  "ro",
+  "hr",
+  "sl",
+  "et",
+  "lv",
+  "lt",
+  "tr",
+  "vi",
+  "id",
+  "ms",
+  "tl",
+  "sw",
+  "af",
+  "ca",
+  "gl",
+  "eu",
+  "cy",
+  "ga"
+]);
+var SCRIPT_TABLE = {
+  th: ["Thai"],
+  ko: ["Hangul", "Han"],
+  ja: ["Han", "Hiragana", "Katakana"],
+  zh: ["Han"],
+  ar: ["Arabic"],
+  fa: ["Arabic"],
+  ur: ["Arabic"],
+  ru: ["Cyrillic"],
+  uk: ["Cyrillic"],
+  bg: ["Cyrillic"],
+  sr: ["Cyrillic"],
+  he: ["Hebrew"],
+  el: ["Greek"],
+  hi: ["Devanagari"],
+  ta: ["Tamil"],
+  km: ["Khmer"],
+  lo: ["Lao"],
+  my: ["Myanmar"]
+};
+var SUBTAG_SCRIPTS = {
+  Latn: ["Latin"],
+  Cyrl: ["Cyrillic", "Latin"],
+  Hans: ["Han", "Latin"],
+  Hant: ["Han", "Latin"],
+  Thai: ["Thai", "Latin"],
+  Arab: ["Arabic", "Latin"]
+};
+function inferScripts(locale) {
+  const parts = locale.split("-");
+  const subtag = parts.find((t) => /^[A-Z][a-z]{3}$/.test(t));
+  if (subtag && SUBTAG_SCRIPTS[subtag]) return SUBTAG_SCRIPTS[subtag];
+  const base = (parts[0] ?? "").toLowerCase();
+  if (LATIN_BASE.has(base)) return ["Latin"];
+  const primary = SCRIPT_TABLE[base];
+  if (primary) return [...primary, "Latin"];
+  return ["Latin"];
+}
+function allowedFor(descriptor, locale) {
+  const script = descriptor.options.script;
+  if (script && script !== "auto") {
+    const explicit = script[locale];
+    if (explicit) return explicit;
+  }
+  return inferScripts(locale);
+}
+var BASELINE = String.raw`\p{White_Space}\p{Script=Common}\p{Script=Inherited}\p{Mark}`;
+function fullMatcher(scripts) {
+  const cls = scripts.map((s) => `\\p{Script=${s}}`).join("");
+  return new RegExp(`^[${BASELINE}${cls}]*$`, "u");
+}
+function charMatcher(scripts) {
+  const cls = scripts.map((s) => `\\p{Script=${s}}`).join("");
+  return new RegExp(`[${BASELINE}${cls}]`, "u");
+}
+function offendingSample(str, scripts) {
+  const ok = charMatcher(scripts);
+  const bad = [];
+  for (const ch of str) {
+    if (!ok.test(ch)) bad.push(ch);
+    if (bad.length >= 8) break;
+  }
+  return bad.join("");
+}
+function stripDisallowed(str, scripts) {
+  const ok = charMatcher(scripts);
+  let out = "";
+  for (const ch of str) if (ok.test(ch)) out += ch;
+  return out;
+}
+function enforceScript(value, field, descriptor) {
+  const opt = descriptor.options;
+  if (!opt.script) return { value, warnings: [] };
+  const mode = opt.onScriptViolation ?? "reject";
+  const warnings = [];
+  let out = value;
+  for (const [locale, raw] of Object.entries(value)) {
+    if (typeof raw !== "string") continue;
+    const allowed = allowedFor(descriptor, locale);
+    if (fullMatcher(allowed).test(raw)) continue;
+    const sample = offendingSample(raw, allowed);
+    if (mode === "reject") {
+      throw new ScriptViolationError(field, locale, allowed, sample);
+    }
+    warnings.push({ field, locale, expected: allowed, sample });
+    if (mode === "filter") {
+      if (out === value) out = { ...value };
+      out[locale] = stripDisallowed(raw, allowed);
+    }
+  }
+  return { value: out, warnings };
+}
+
+// src/index.ts
 init_errors();
 
 // src/team/sync-credentials.ts
@@ -23440,7 +24016,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,
@@ -23550,9 +24129,11 @@ function shortJSON(value) {
   SchemaLockedError,
   SchemaUpdateError,
   SchemaValidationError,
+  ScriptViolationError,
   SessionExpiredError,
   SessionNotFoundError,
   SessionPolicyError,
+  SnapshotNotFoundError,
   StoreCapabilityError,
   SyncEngine,
   SyncScheduler,
@@ -23624,6 +24205,7 @@ function shortJSON(value) {
   enableDevUnlock,
   encryptBytes,
   encryptDeterministic,
+  enforceScript,
   enrollAuthenticator,
   envelopePayloadHash,
   estimateEntropy,
@@ -23644,6 +24226,7 @@ function shortJSON(value) {
   hasRecoveryEnrolled,
   hashEntry,
   i18nText,
+  inferScripts,
   isDevUnlockActive,
   isDictCollectionName,
   isDictKeyDescriptor,
@@ -23704,6 +24287,7 @@ function shortJSON(value) {
   resetJoinWarnings,
   resolveCrdtSnapshot,
   resolveI18nText,
+  resolvePolicy,
   resolvePublicEnvelopeSchema,
   resolveSession,
   revokeAllSessions,