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

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, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, 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, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, 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 init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -403,6 +403,18 @@ Resolutions:
         this.collectionName = collectionName;
       }
     };
+    LocaleNotSpecifiedError = class extends NoydbError {
+      /** The field name that required a locale. */
+      field;
+      constructor(field, message) {
+        super(
+          "LOCALE_NOT_SPECIFIED",
+          message ?? `Cannot read i18nText field "${field}" without a locale. Pass { locale } to get()/list()/query() or set a default via openVault(name, { locale }).`
+        );
+        this.name = "LocaleNotSpecifiedError";
+        this.field = field;
+      }
+    };
     TranslatorNotConfiguredError = class extends NoydbError {
       /** The field that requested auto-translation. */
       field;
@@ -476,6 +488,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;
@@ -3471,6 +3511,19 @@ var init_strategy = __esm({
   }
 });
 
+// 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";
+}
+var init_policy = __esm({
+  "src/i18n/policy.ts"() {
+    "use strict";
+  }
+});
+
 // src/i18n/core.ts
 function getAtPath(obj, path) {
   const arrayIdx = path.indexOf("[].");
@@ -3530,6 +3583,9 @@ var init_strategy2 = __esm({
       validateI18nTextValue() {
         throw notEnabled("i18nText field validation");
       },
+      enforceScript(value) {
+        return { value, warnings: [] };
+      },
       buildDictionaryHandle() {
         throw notEnabled("vault.dictionary()");
       }
@@ -3709,6 +3765,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) {
@@ -3991,9 +4051,20 @@ var init_strategy4 = __esm({
 });
 
 // src/query/builder.ts
-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);
   }
@@ -4057,6 +4128,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) {
@@ -4119,6 +4258,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) {
@@ -4168,12 +4317,13 @@ function buildDictLabelResolver(joinCtx, field) {
     return void 0;
   };
 }
-var EMPTY_PLAN, Query;
+var EMPTY_PLAN, DEFAULT_CROSS_JOIN_MAX_ROWS, Query;
 var init_builder = __esm({
   "src/query/builder.ts"() {
     "use strict";
     init_predicate();
     init_join();
+    init_errors();
     init_live();
     init_strategy4();
     EMPTY_PLAN = {
@@ -4183,6 +4333,7 @@ var init_builder = __esm({
       offset: 0,
       joins: []
     };
+    DEFAULT_CROSS_JOIN_MAX_ROWS = 5e4;
     Query = class _Query {
       source;
       plan;
@@ -4464,6 +4615,78 @@ var init_builder = __esm({
           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`
@@ -4471,7 +4694,7 @@ var init_builder = __esm({
        * 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(
@@ -4495,6 +4718,14 @@ var init_builder = __esm({
        * 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;
@@ -4542,7 +4773,13 @@ var init_builder = __esm({
       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);
         };
@@ -4559,7 +4796,13 @@ var init_builder = __esm({
         }
         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);
         };
@@ -4673,6 +4916,21 @@ var init_builder = __esm({
             }
           }
         }
+        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);
       }
       /**
@@ -5560,7 +5818,7 @@ function estimateRecordBytes(record) {
   }
 }
 var UNITS;
-var init_policy = __esm({
+var init_policy2 = __esm({
   "src/cache/policy.ts"() {
     "use strict";
     UNITS = {
@@ -5579,7 +5837,7 @@ var init_cache = __esm({
   "src/cache/index.ts"() {
     "use strict";
     init_lru();
-    init_policy();
+    init_policy2();
   }
 });
 
@@ -5992,6 +6250,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;
 }
@@ -6007,7 +6270,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,
@@ -6586,6 +6861,7 @@ var init_collection = __esm({
     init_strategy();
     init_core();
     init_strategy2();
+    init_policy();
     init_crypto();
     init_errors();
     init_tiers();
@@ -7225,6 +7501,22 @@ var init_collection = __esm({
             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);
         }
@@ -8667,17 +8959,52 @@ var init_collection = __esm({
         }
         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;
@@ -14832,20 +15159,42 @@ var init_unlock_state = __esm({
   }
 });
 
-// src/tx/strategy.ts
-var NOT_ENABLED5, NO_TX;
+// src/snapshots/strategy.ts
+var NOT_ENABLED5, NO_SNAPSHOTS;
 var init_strategy10 = __esm({
-  "src/tx/strategy.ts"() {
+  "src/snapshots/strategy.ts"() {
     "use strict";
     NOT_ENABLED5 = new Error(
+      'Snapshots require the snapshot strategy. Import `{ withSnapshots }` from "@noy-db/hub/snapshots" and pass it to `createNoydb({ snapshotStrategy: withSnapshots({ store }) })`.'
+    );
+    NO_SNAPSHOTS = {
+      async snapshot() {
+        throw NOT_ENABLED5;
+      },
+      async listSnapshots() {
+        throw NOT_ENABLED5;
+      },
+      async restoreSnapshot() {
+        throw NOT_ENABLED5;
+      }
+    };
+  }
+});
+
+// src/tx/strategy.ts
+var NOT_ENABLED6, NO_TX;
+var init_strategy11 = __esm({
+  "src/tx/strategy.ts"() {
+    "use strict";
+    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() })`.'
     );
     NO_TX = {
       async runTransaction() {
-        throw NOT_ENABLED5;
+        throw NOT_ENABLED6;
       },
       async runDryRun() {
-        throw NOT_ENABLED5;
+        throw NOT_ENABLED6;
       }
     };
   }
@@ -14870,7 +15219,7 @@ function notEnabled4(op) {
   );
 }
 var NO_SESSION;
-var init_strategy11 = __esm({
+var init_strategy12 = __esm({
   "src/session/strategy.ts"() {
     "use strict";
     NO_SESSION = {
@@ -15143,7 +15492,7 @@ var init_engine = __esm({
 });
 
 // src/policy/index.ts
-var init_policy2 = __esm({
+var init_policy3 = __esm({
   "src/policy/index.ts"() {
     "use strict";
     init_presets();
@@ -15306,11 +15655,12 @@ var init_noydb = __esm({
     init_authenticators();
     init_unlock_state();
     init_sync_strategy();
-    init_transaction();
     init_strategy10();
-    init_sync_policy();
+    init_transaction();
     init_strategy11();
-    init_policy2();
+    init_sync_policy();
+    init_strategy12();
+    init_policy3();
     ROLE_RANK = {
       client: 1,
       viewer: 2,
@@ -15366,6 +15716,7 @@ var init_noydb = __esm({
       txStrategy;
       sessionStrategy;
       syncStrategy;
+      snapshotStrategy;
       /**
        * Currently-running multi-record transaction, set by
        * `runTransaction` at the start of Phase 2 (commit) and cleared in
@@ -15390,6 +15741,7 @@ var init_noydb = __esm({
         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);
@@ -17376,6 +17728,45 @@ var init_noydb = __esm({
         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);
+      }
     };
   }
 });