@noy-db/hub 0.1.0-pre.14 → 0.1.0-pre.16

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
@@ -18,6 +20,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/types.ts
@@ -36,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, GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, BundleIntegrityError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, 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, GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -423,6 +433,26 @@ var init_errors = __esm({
         this.name = "BundleIntegrityError";
       }
     };
+    BundleSealMismatchError = class extends NoydbError {
+      userId;
+      pid;
+      constructor(userId, pid) {
+        super(
+          "BUNDLE_SEAL_MISMATCH",
+          `bundle carries sealed passphrase for user "${userId}" under provider "${pid}", but no registered provider matches that pid.
+
+Resolutions:
+  1. Configure a provider matching the pid and retry import.
+  2. Pass \`attemptUnsealAcrossProviders: true\` to try each registered
+     provider regardless of pid (extra credential prompts may surface).
+  3. Inspect the bundle without unsealing \u2014 pass no \`sealingProviders\`
+     to receive the sealed entries unmodified for offline analysis.`
+        );
+        this.name = "BundleSealMismatchError";
+        this.userId = userId;
+        this.pid = pid;
+      }
+    };
     ReservedCollectionNameError = class extends NoydbError {
       /** The rejected collection name. */
       collectionName;
@@ -651,6 +681,21 @@ var init_errors = __esm({
         this.outputKey = outputKey;
       }
     };
+    DerivationCapExceededError = class extends NoydbError {
+      outputKey;
+      returned;
+      maxFanout;
+      constructor(outputKey, returned, maxFanout) {
+        super(
+          "DERIVATION_CAP_EXCEEDED",
+          `Derivation array output "${outputKey}" returned ${returned} rows, exceeding maxFanout=${maxFanout}. Raise \`maxFanout\` on the OutputSpec if this fanout is intended (the cap exists to keep dispatch cost bounded).`
+        );
+        this.name = "DerivationCapExceededError";
+        this.outputKey = outputKey;
+        this.returned = returned;
+        this.maxFanout = maxFanout;
+      }
+    };
     MaterializedViewCycleError = class extends NoydbError {
       path;
       constructor(path) {
@@ -690,6 +735,15 @@ var init_errors = __esm({
         this.limit = limit;
       }
     };
+    MaterializedViewConfigError = class extends NoydbError {
+      constructor(message) {
+        super(
+          "MATERIALIZED_VIEW_CONFIG",
+          `[noy-db] withMaterializedView: ${message}`
+        );
+        this.name = "MaterializedViewConfigError";
+      }
+    };
     OverlayBaseIsVirtualError = class extends NoydbError {
       overlayName;
       base;
@@ -1666,7 +1720,8 @@ var init_store = __esm({
         const entry = {
           ...entryBase,
           ...deltaHash !== void 0 ? { deltaHash } : {},
-          ...input.amendment !== void 0 ? { amendment: input.amendment } : {}
+          ...input.amendment !== void 0 ? { amendment: input.amendment } : {},
+          ...input.reason !== void 0 ? { reason: input.reason } : {}
         };
         const envelope = await this.encryptEntry(entry);
         await this.adapter.put(
@@ -2069,6 +2124,428 @@ var init_tiers = __esm({
   }
 });
 
+// src/query/predicate.ts
+function readPath(record, path) {
+  if (record === null || record === void 0) return void 0;
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  const segments = path.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function evaluateFieldClause(record, clause) {
+  const actual = readPath(record, clause.field);
+  const { op, value } = clause;
+  switch (op) {
+    case "==":
+      return actual === value;
+    case "!=":
+      return actual !== value;
+    case "<":
+      return isComparable(actual, value) && actual < value;
+    case "<=":
+      return isComparable(actual, value) && actual <= value;
+    case ">":
+      return isComparable(actual, value) && actual > value;
+    case ">=":
+      return isComparable(actual, value) && actual >= value;
+    case "in":
+      return Array.isArray(value) && value.includes(actual);
+    case "contains":
+      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
+      if (Array.isArray(actual)) return actual.includes(value);
+      return false;
+    case "startsWith":
+      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) return false;
+      const [lo, hi] = value;
+      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
+      return actual >= lo && actual <= hi;
+    }
+    default: {
+      const _exhaustive = op;
+      void _exhaustive;
+      return false;
+    }
+  }
+}
+function isComparable(a, b) {
+  if (typeof a === "number" && typeof b === "number") return true;
+  if (typeof a === "string" && typeof b === "string") return true;
+  if (a instanceof Date && b instanceof Date) return true;
+  return false;
+}
+function evaluateClause(record, clause) {
+  switch (clause.type) {
+    case "field":
+      return evaluateFieldClause(record, clause);
+    case "filter":
+      return clause.fn(record);
+    case "wherePredicate":
+      return clause.fn(record, clause.ctx);
+    case "group":
+      if (clause.op === "and") {
+        for (const child of clause.clauses) {
+          if (!evaluateClause(record, child)) return false;
+        }
+        return true;
+      } else {
+        for (const child of clause.clauses) {
+          if (evaluateClause(record, child)) return true;
+        }
+        return false;
+      }
+  }
+}
+var init_predicate = __esm({
+  "src/query/predicate.ts"() {
+    "use strict";
+  }
+});
+
+// src/aggregate/aggregation.ts
+function reduceRecords(records, spec) {
+  const state = {};
+  for (const key of Object.keys(spec)) {
+    state[key] = spec[key].init();
+  }
+  for (const record of records) {
+    for (const key of Object.keys(spec)) {
+      state[key] = spec[key].step(state[key], record);
+    }
+  }
+  const result = {};
+  for (const key of Object.keys(spec)) {
+    result[key] = spec[key].finalize(state[key]);
+  }
+  return result;
+}
+function buildLiveAggregation(recompute, upstreams) {
+  return new LiveAggregationImpl(recompute, upstreams);
+}
+var LiveAggregationImpl, Aggregation;
+var init_aggregation = __esm({
+  "src/aggregate/aggregation.ts"() {
+    "use strict";
+    LiveAggregationImpl = class {
+      constructor(recompute, upstreams) {
+        this.recompute = recompute;
+        try {
+          this.value = recompute();
+          this.error = void 0;
+        } catch (err) {
+          this.value = void 0;
+          this.error = err;
+        }
+        for (const upstream of upstreams) {
+          const unsub = upstream.subscribe(() => this.refresh());
+          this.unsubscribes.push(unsub);
+        }
+      }
+      recompute;
+      value;
+      error;
+      listeners = /* @__PURE__ */ new Set();
+      unsubscribes = [];
+      stopped = false;
+      refresh() {
+        if (this.stopped) return;
+        try {
+          this.value = this.recompute();
+          this.error = void 0;
+        } catch (err) {
+          this.error = err;
+        }
+        for (const listener of this.listeners) {
+          try {
+            listener();
+          } catch (err) {
+            console.warn("[noy-db] LiveAggregation listener threw:", err);
+          }
+        }
+      }
+      subscribe(cb) {
+        if (this.stopped) {
+          return () => {
+          };
+        }
+        this.listeners.add(cb);
+        return () => {
+          this.listeners.delete(cb);
+        };
+      }
+      stop() {
+        if (this.stopped) return;
+        this.stopped = true;
+        for (const unsub of this.unsubscribes) {
+          try {
+            unsub();
+          } catch (err) {
+            console.warn("[noy-db] LiveAggregation upstream unsubscribe threw:", err);
+          }
+        }
+        this.unsubscribes.length = 0;
+        this.listeners.clear();
+      }
+    };
+    Aggregation = class {
+      constructor(executeRecords, spec, upstreams) {
+        this.executeRecords = executeRecords;
+        this.spec = spec;
+        this.upstreams = upstreams;
+      }
+      executeRecords;
+      spec;
+      upstreams;
+      /**
+       * Execute the query and reduce the results synchronously.
+       * Returns the reduced shape matching the spec — e.g. a spec of
+       * `{ total: sum('amount'), n: count() }` returns
+       * `{ total: number, n: number }`.
+       */
+      run() {
+        return reduceRecords(this.executeRecords(), this.spec);
+      }
+      /**
+       * Build a reactive `LiveAggregation<R>` that re-runs the reduction
+       * whenever any upstream source notifies of a change. The initial
+       * value is computed eagerly in the constructor, so consumers can
+       * read `live.value` immediately after calling `.live()`.
+       *
+       * Always call `live.stop()` when finished — it tears down the
+       * upstream subscriptions. Vue's `onUnmounted` is the canonical
+       * place.
+       *
+       * **Implementation note:** every upstream change triggers a full
+       * re-reduction. Incremental maintenance (O(1) per delta for
+       * sum/count/avg via the reducer protocol's `remove()` method) is a
+       * planned follow-up optimization — the protocol already supports
+       * it, but the executor doesn't drive it yet. Consumers get
+       * correct, reactive values today; future PRs can switch to
+       * delta-based maintenance without changing this API.
+       */
+      live() {
+        const recompute = () => reduceRecords(this.executeRecords(), this.spec);
+        return new LiveAggregationImpl(recompute, this.upstreams);
+      }
+    };
+  }
+});
+
+// src/aggregate/canonical-key.ts
+function canonicalGroupKey(fields, row) {
+  const sorted = [...fields].sort();
+  const parts = [];
+  for (const name of sorted) {
+    const v = row[name];
+    const serialised = v === void 0 ? "undefined" : JSON.stringify(v);
+    parts.push(`${name}=${serialised}`);
+  }
+  return parts.join("|");
+}
+var init_canonical_key = __esm({
+  "src/aggregate/canonical-key.ts"() {
+    "use strict";
+  }
+});
+
+// src/aggregate/groupby.ts
+function warnCardinalityApproaching(fields, observed) {
+  const key = JSON.stringify([...fields].sort());
+  if (warnedCardinalityFields.has(key)) return;
+  warnedCardinalityFields.add(key);
+  const label = `[${fields.join(", ")}]`;
+  console.warn(
+    `[noy-db] .groupBy(${label}) produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
+  );
+}
+function groupAndReduce(records, fieldOrFields, spec) {
+  const fields = typeof fieldOrFields === "string" ? [fieldOrFields] : fieldOrFields;
+  if (fields.length === 0) {
+    throw new Error(".groupBy() requires at least one field");
+  }
+  const buckets = /* @__PURE__ */ new Map();
+  const fieldLabel = fields.length === 1 ? fields[0] : `[${fields.join(", ")}]`;
+  for (const record of records) {
+    const keyValues = {};
+    for (const f of fields) {
+      keyValues[f] = readPath(record, f);
+    }
+    const dedupKey = canonicalGroupKey(fields, keyValues);
+    let bucket = buckets.get(dedupKey);
+    if (bucket === void 0) {
+      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {
+        throw new GroupCardinalityError(
+          fieldLabel,
+          buckets.size + 1,
+          GROUPBY_MAX_CARDINALITY
+        );
+      }
+      bucket = { keyValues, records: [] };
+      buckets.set(dedupKey, bucket);
+    }
+    bucket.records.push(record);
+  }
+  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
+    warnCardinalityApproaching(fields, buckets.size);
+  }
+  const reducerKeys = Object.keys(spec);
+  const out = [];
+  for (const bucket of buckets.values()) {
+    const state = {};
+    for (const rk of reducerKeys) {
+      state[rk] = spec[rk].init();
+    }
+    for (const record of bucket.records) {
+      for (const rk of reducerKeys) {
+        state[rk] = spec[rk].step(state[rk], record);
+      }
+    }
+    const row = {};
+    for (const f of fields) {
+      row[f] = bucket.keyValues[f];
+    }
+    for (const rk of reducerKeys) {
+      row[rk] = spec[rk].finalize(state[rk]);
+    }
+    out.push(row);
+  }
+  return out;
+}
+var GROUPBY_WARN_CARDINALITY, GROUPBY_MAX_CARDINALITY, warnedCardinalityFields, GroupedQueryBase, GroupedQuery, GroupedQueryN, GroupedAggregation;
+var init_groupby = __esm({
+  "src/aggregate/groupby.ts"() {
+    "use strict";
+    init_predicate();
+    init_aggregation();
+    init_canonical_key();
+    init_errors();
+    GROUPBY_WARN_CARDINALITY = 1e4;
+    GROUPBY_MAX_CARDINALITY = 1e5;
+    warnedCardinalityFields = /* @__PURE__ */ new Set();
+    GroupedQueryBase = class {
+      constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver) {
+        this.executeRecords = executeRecords;
+        this.upstreams = upstreams;
+        this.dictLabelResolver = dictLabelResolver;
+        this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
+      }
+      executeRecords;
+      upstreams;
+      dictLabelResolver;
+      /**
+       * Field set this grouped query buckets on. Stored in declaration
+       * order — the same order is preserved on every result row by
+       * `groupAndReduce`. For the single-field constructor, this is
+       * `[field]`.
+       */
+      fields;
+    };
+    GroupedQuery = class extends GroupedQueryBase {
+      /**
+       * Build a grouped aggregation. Returns a `GroupedAggregation`
+       * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape
+       * as the non-grouped `.aggregate()` wrapper, just with an array
+       * result (one row per bucket) instead of a single reduced object.
+       */
+      aggregate(spec) {
+        return new GroupedAggregation(
+          this.executeRecords,
+          this.fields,
+          spec,
+          this.upstreams,
+          this.dictLabelResolver
+        );
+      }
+    };
+    GroupedQueryN = class extends GroupedQueryBase {
+      aggregate(spec) {
+        return new GroupedAggregation(
+          this.executeRecords,
+          this.fields,
+          spec,
+          this.upstreams,
+          this.dictLabelResolver
+        );
+      }
+    };
+    GroupedAggregation = class {
+      constructor(executeRecords, fields, spec, upstreams, dictLabelResolver) {
+        this.executeRecords = executeRecords;
+        this.spec = spec;
+        this.upstreams = upstreams;
+        this.dictLabelResolver = dictLabelResolver;
+        this.fields = typeof fields === "string" ? [fields] : [...fields];
+      }
+      executeRecords;
+      spec;
+      upstreams;
+      dictLabelResolver;
+      fields;
+      /** Execute the query, group, reduce, and return an array of rows. */
+      run() {
+        return groupAndReduce(this.executeRecords(), this.fields, this.spec);
+      }
+      /**
+       * Execute the query, group, reduce, and resolve `<field>Label` for
+       * each result row when the grouping field is a `dictKey` and a
+       * `locale` is provided. Returns `R[]` synchronously when
+       * no locale is specified (identical to `.run()`).
+       *
+       * The `<field>Label` field is appended to each row. Rows whose group
+       * key has no dictionary entry get `<field>Label: undefined`.
+       *
+       * Dict-label resolution is single-field only — multi-key groupings
+       * do not produce a `<field>Label`. The resolver is only attached
+       * by the builder when `fields.length === 1`.
+       */
+      async runAsync(opts) {
+        const rows = groupAndReduce(this.executeRecords(), this.fields, this.spec);
+        if (!opts?.locale || !this.dictLabelResolver || this.fields.length !== 1) return rows;
+        const resolve = this.dictLabelResolver;
+        const locale = opts.locale;
+        const fallback = opts.fallback;
+        const field = this.fields[0];
+        const labelKey = `${field}Label`;
+        return Promise.all(
+          rows.map(async (row) => {
+            const key = row[field];
+            if (typeof key !== "string") return row;
+            const label = await resolve(key, locale, fallback);
+            return { ...row, [labelKey]: label };
+          })
+        );
+      }
+      /**
+       * Build a reactive `LiveAggregation<R[]>` that re-runs the full
+       * group-and-reduce pipeline whenever any upstream source notifies
+       * of a change. Same error-isolation and idempotent-stop contract
+       * as `Aggregation.live()` — the implementation delegates to the
+       * same `LiveAggregationImpl` class by threading a fresh
+       * recompute closure through the existing constructor.
+       *
+       * uses naive full re-run on every change. Incremental
+       * per-bucket maintenance (apply `step` on inserted records,
+       * `remove` on deleted records, route by bucket key) is a future
+       * optimization — the reducer protocol admits it, but wiring
+       * delta-aware source subscriptions is a separate PR.
+       *
+       * Always call `live.stop()` when finished.
+       */
+      live() {
+        const recompute = () => groupAndReduce(this.executeRecords(), this.fields, this.spec);
+        return buildLiveAggregation(recompute, this.upstreams);
+      }
+    };
+  }
+});
+
 // src/guards/executor.ts
 var executor_exports = {};
 __export(executor_exports, {
@@ -2168,6 +2645,7 @@ var init_executor2 = __esm({
         } catch (err) {
           for (const key of Object.keys(strategy.outputs)) {
             outputs[key] = {
+              kind: "failed",
               value: {},
               ok: false,
               error: err instanceof Error ? err : new Error(String(err))
@@ -2186,9 +2664,64 @@ var init_executor2 = __esm({
           const outSpec = strategy.outputs[key];
           if (!outSpec) continue;
           const value = derived[key];
+          if (outSpec.shape === "array") {
+            if (value === void 0 || value === null) {
+              outputs[key] = { kind: "array", ok: true, entries: [] };
+              continue;
+            }
+            if (!Array.isArray(value)) {
+              throw new DerivationOutputShapeError(
+                key,
+                `shape 'array' expects an array, got ${typeof value}`
+              );
+            }
+            const maxFanout = outSpec.maxFanout ?? 64;
+            if (value.length > maxFanout) {
+              throw new DerivationCapExceededError(key, value.length, maxFanout);
+            }
+            const entries = [];
+            const seenKeys = /* @__PURE__ */ new Set();
+            for (let i = 0; i < value.length; i++) {
+              const row = value[i];
+              if (row === null || typeof row !== "object") {
+                throw new DerivationOutputShapeError(
+                  key,
+                  `array member at index ${i} must be a non-null object (got ${row === null ? "null" : typeof row})`
+                );
+              }
+              let derivedKey;
+              try {
+                derivedKey = outSpec.key(row);
+              } catch (err) {
+                throw new DerivationOutputShapeError(
+                  key,
+                  `key extractor threw on array member at index ${i}: ` + (err instanceof Error ? err.message : String(err))
+                );
+              }
+              if (typeof derivedKey !== "string" || derivedKey.length === 0) {
+                throw new DerivationOutputShapeError(
+                  key,
+                  `key extractor returned ${typeof derivedKey === "string" ? "empty string" : typeof derivedKey} at index ${i}; expected non-empty string`
+                );
+              }
+              if (seenKeys.has(derivedKey)) {
+                throw new DerivationOutputShapeError(
+                  key,
+                  `duplicate key "${derivedKey}" in array output (index ${i}); each derived row must have a unique key within a single derive() invocation`
+                );
+              }
+              seenKeys.add(derivedKey);
+              entries.push({
+                key: derivedKey,
+                value: { ...row, _derivedFrom: meta }
+              });
+            }
+            outputs[key] = { kind: "array", ok: true, entries };
+            continue;
+          }
           if (value === void 0 || value === null) {
             if (outSpec.optional === true) {
-              outputs[key] = { value: {}, ok: true, skipped: true };
+              outputs[key] = { kind: "record", value: {}, ok: true, skipped: true };
               continue;
             }
             throw new DerivationOutputShapeError(
@@ -2203,6 +2736,7 @@ var init_executor2 = __esm({
             );
           }
           outputs[key] = {
+            kind: "record",
             value: { ...value, _derivedFrom: meta },
             ok: true
           };
@@ -2246,6 +2780,12 @@ function summarizeQueryPlan(query) {
     joins: plan.joins.map((j) => ({ field: j.field, as: j.as, target: j.target, mode: j.mode }))
   });
 }
+function summarizeUnionPlan(spec) {
+  const arms = (spec.unionSources ?? []).map((s) => s.collection).join(",");
+  const groupBy = Array.isArray(spec.groupBy) ? [...spec.groupBy].sort().join(",") : typeof spec.groupBy === "string" ? spec.groupBy : "";
+  const aggKeys = spec.aggregate ? Object.keys(spec.aggregate).sort().join(",") : "";
+  return `union(${arms})|groupBy(${groupBy})|aggregate(${aggKeys})`;
+}
 var init_dependency_analyzer = __esm({
   "src/materialized-views/dependency-analyzer.ts"() {
     "use strict";
@@ -2365,27 +2905,34 @@ var init_registry = __esm({
        */
       async register(spec, db, options) {
         const dbForQuery = spec.predicates ? wrapDbWithPredicates(db, spec.predicates) : db;
-        const q = spec.query(dbForQuery);
-        const qAny = q;
-        const isQuery = typeof qAny._plan === "function";
         let dependencies;
         let queryPlanSummary;
-        if (isQuery) {
-          dependencies = analyzeDependencies(q);
-          queryPlanSummary = summarizeQueryPlan(q);
-          const predicateRefs = extractPredicateRefs(qAny._plan());
-          if (predicateRefs.length > 0) {
-            queryPlanSummary = JSON.stringify({ plan: queryPlanSummary, predicates: predicateRefs });
-          }
-          if (spec.sources) for (const s of spec.sources) dependencies.add(s);
+        let qAny = null;
+        let isQuery = false;
+        if (spec.unionSources) {
+          dependencies = new Set(spec.unionSources.map((s) => s.collection));
+          queryPlanSummary = summarizeUnionPlan(spec);
         } else {
-          if (!spec.sources || spec.sources.length === 0) {
-            throw new Error(
-              `withMaterializedView "${spec.name}": query() returned an aggregate (Aggregation or GroupedAggregation) but no \`sources\` field is declared. The dependency analyzer cannot walk through groupBy().aggregate() back to the source \u2014 declare sources: [...] explicitly.`
-            );
+          const q = spec.query(dbForQuery);
+          qAny = q;
+          isQuery = typeof qAny._plan === "function";
+          if (isQuery) {
+            dependencies = analyzeDependencies(q);
+            queryPlanSummary = summarizeQueryPlan(q);
+            const predicateRefs = extractPredicateRefs(qAny._plan());
+            if (predicateRefs.length > 0) {
+              queryPlanSummary = JSON.stringify({ plan: queryPlanSummary, predicates: predicateRefs });
+            }
+            if (spec.sources) for (const s of spec.sources) dependencies.add(s);
+          } else {
+            if (!spec.sources || spec.sources.length === 0) {
+              throw new Error(
+                `withMaterializedView "${spec.name}": query() returned an aggregate (Aggregation or GroupedAggregation) but no \`sources\` field is declared. The dependency analyzer cannot walk through groupBy().aggregate() back to the source \u2014 declare sources: [...] explicitly.`
+              );
+            }
+            dependencies = new Set(spec.sources);
+            queryPlanSummary = JSON.stringify({ aggregate: true, sources: [...spec.sources].sort() });
           }
-          dependencies = new Set(spec.sources);
-          queryPlanSummary = JSON.stringify({ aggregate: true, sources: [...spec.sources].sort() });
         }
         if (options?.knownCollections) {
           for (const dep of dependencies) {
@@ -2514,6 +3061,27 @@ async function materializeQueryResult(q, mvName) {
     `MV "${mvName}": query() must return a Query<T>, Aggregation, or GroupedAggregation. Got something without a .toArray() or .run() terminal.`
   );
 }
+async function materializeUnionResult(spec, db) {
+  const unified = [];
+  for (const arm of spec.unionSources) {
+    const coll = db.collection(arm.collection);
+    const sourceRows = coll.query().toArray();
+    for (const r of sourceRows) {
+      unified.push(arm.map(r));
+    }
+  }
+  if (!spec.groupBy) return unified;
+  const groupFields = typeof spec.groupBy === "string" ? [spec.groupBy] : spec.groupBy;
+  if (!spec.aggregate) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const row of unified) {
+      const k = canonicalGroupKey(groupFields, row);
+      if (!seen.has(k)) seen.set(k, row);
+    }
+    return [...seen.values()];
+  }
+  return groupAndReduce(unified, groupFields, spec.aggregate);
+}
 async function listOutputIds(outputColl) {
   const cAny = outputColl;
   const adapter = cAny.adapter;
@@ -2533,6 +3101,8 @@ var init_executor3 = __esm({
     "use strict";
     init_errors();
     init_registry();
+    init_groupby();
+    init_canonical_key();
     DEFAULT_MAX_ROWS = 1e5;
     MaterializedViewExecutor = {
       async refresh(reg, accessor) {
@@ -2543,8 +3113,13 @@ var init_executor3 = __esm({
         const strict = spec.strict ?? false;
         const baseCtx = accessor.getQueryContext();
         const ctxForQuery = spec.predicates ? wrapDbWithPredicates(baseCtx, spec.predicates) : baseCtx;
-        const q = spec.query(ctxForQuery);
-        const rows = await materializeQueryResult(q, spec.name);
+        let rows;
+        if (spec.unionSources) {
+          rows = await materializeUnionResult(spec, ctxForQuery);
+        } else {
+          const q = spec.query(ctxForQuery);
+          rows = await materializeQueryResult(q, spec.name);
+        }
         if (rows.length > maxRows) {
           throw new MaterializedViewTooLargeError(spec.name, rows.length, maxRows);
         }
@@ -2669,8 +3244,62 @@ var init_stale = __esm({
   }
 });
 
-// src/guards/registry.ts
-var registry_exports2 = {};
+// src/derivations/fanout-sidecar.ts
+var fanout_sidecar_exports = {};
+__export(fanout_sidecar_exports, {
+  deleteFanoutSidecar: () => deleteFanoutSidecar,
+  loadFanoutSidecar: () => loadFanoutSidecar,
+  saveFanoutSidecar: () => saveFanoutSidecar
+});
+function recordId(source, sourceId, outputKey) {
+  return `derivations-fanout/${source}/${sourceId}/${outputKey}`;
+}
+async function loadFanoutSidecar(store, vault, source, sourceId, outputKey) {
+  const envelope = await store.get(vault, "_meta", recordId(source, sourceId, outputKey));
+  if (!envelope) return void 0;
+  try {
+    const parsed = JSON.parse(envelope._data);
+    if (parsed._noydb_fanout !== 1) return void 0;
+    if (!Array.isArray(parsed.keys)) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function saveFanoutSidecar(store, vault, payload) {
+  const doc = {
+    _noydb_fanout: 1,
+    source: payload.source,
+    sourceId: payload.sourceId,
+    outputKey: payload.outputKey,
+    outputCollection: payload.outputCollection,
+    keys: payload.keys,
+    emittedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const id = recordId(payload.source, payload.sourceId, payload.outputKey);
+  const prior = await store.get(vault, "_meta", id);
+  const envelope = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: (prior?._v ?? 0) + 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    // AES-GCM bypassed — sidecar is system metadata, no user data inside.
+    _iv: "",
+    _data: JSON.stringify(doc)
+  };
+  await store.put(vault, "_meta", id, envelope);
+}
+async function deleteFanoutSidecar(store, vault, source, sourceId, outputKey) {
+  await store.delete(vault, "_meta", recordId(source, sourceId, outputKey));
+}
+var init_fanout_sidecar = __esm({
+  "src/derivations/fanout-sidecar.ts"() {
+    "use strict";
+    init_types();
+  }
+});
+
+// src/guards/registry.ts
+var registry_exports2 = {};
 __export(registry_exports2, {
   GuardRegistry: () => GuardRegistry
 });
@@ -3076,6 +3705,7 @@ __export(src_exports, {
   BackupLedgerError: () => BackupLedgerError,
   BlobSet: () => BlobSet,
   BundleIntegrityError: () => BundleIntegrityError,
+  BundleSealMismatchError: () => BundleSealMismatchError,
   BundleVersionConflictError: () => BundleVersionConflictError,
   CONSENT_AUDIT_COLLECTION: () => CONSENT_AUDIT_COLLECTION,
   Collection: () => Collection,
@@ -3093,6 +3723,7 @@ __export(src_exports, {
   DanglingReferenceError: () => DanglingReferenceError,
   DecryptionError: () => DecryptionError,
   DelegationTargetMissingError: () => DelegationTargetMissingError,
+  DerivationCapExceededError: () => DerivationCapExceededError,
   DerivationCycleError: () => DerivationCycleError,
   DerivationDepthError: () => DerivationDepthError,
   DerivationOutputShapeError: () => DerivationOutputShapeError,
@@ -3112,6 +3743,7 @@ __export(src_exports, {
   GroupCardinalityError: () => GroupCardinalityError,
   GroupedAggregation: () => GroupedAggregation,
   GroupedQuery: () => GroupedQuery,
+  GroupedQueryN: () => GroupedQueryN,
   INDEXED_STORE_POLICY: () => INDEXED_STORE_POLICY,
   ImportCapabilityError: () => ImportCapabilityError,
   IndexRequiredError: () => IndexRequiredError,
@@ -3131,9 +3763,12 @@ __export(src_exports, {
   MAGIC_LINK_GRANTS_COLLECTION: () => MAGIC_LINK_GRANTS_COLLECTION,
   MAGIC_LINK_KEK_INFO_PREFIX: () => MAGIC_LINK_KEK_INFO_PREFIX,
   META_COLLECTION: () => META_COLLECTION2,
+  ManagedRecoveryNotEnrolledError: () => ManagedRecoveryNotEnrolledError,
+  MaterializedViewConfigError: () => MaterializedViewConfigError,
   MaterializedViewCycleError: () => MaterializedViewCycleError,
   MaterializedViewSourceUnknownError: () => MaterializedViewSourceUnknownError,
   MaterializedViewTooLargeError: () => MaterializedViewTooLargeError,
+  MemorySealingKeyProvider: () => MemorySealingKeyProvider,
   MissingTranslationError: () => MissingTranslationError,
   NOYDB_BACKUP_VERSION: () => NOYDB_BACKUP_VERSION,
   NOYDB_BUNDLE_FORMAT_VERSION: () => NOYDB_BUNDLE_FORMAT_VERSION,
@@ -3175,6 +3810,8 @@ __export(src_exports, {
   RefRegistry: () => RefRegistry,
   RefScopeError: () => RefScopeError,
   ReservedCollectionNameError: () => ReservedCollectionNameError,
+  SCHEMAS_COLLECTION: () => SCHEMAS_COLLECTION,
+  SEALED_PASSPHRASE_RECORD_ID: () => SEALED_PASSPHRASE_RECORD_ID,
   STRICT_POLICY: () => STRICT_POLICY,
   SYNC_CREDENTIALS_COLLECTION: () => SYNC_CREDENTIALS_COLLECTION,
   ScanBuilder: () => ScanBuilder,
@@ -3226,6 +3863,7 @@ __export(src_exports, {
   createSession: () => createSession,
   createStore: () => createStore,
   credentialStatus: () => credentialStatus,
+  decodeShareBase32: () => import_on_shamir2.decodeShareBase32,
   decryptBytes: () => decryptBytes,
   decryptDeterministic: () => decryptDeterministic,
   dekKey: () => dekKey,
@@ -3233,6 +3871,7 @@ __export(src_exports, {
   deleteUserEnvelope: () => deleteUserEnvelope,
   deleteUserVisibility: () => deleteUserVisibility,
   deriveMagicLinkContentKey: () => deriveMagicLinkContentKey,
+  derivePersistedSchema: () => derivePersistedSchema,
   derivePresenceKey: () => derivePresenceKey,
   describeAllUsersAuth: () => describeAllUsersAuth,
   describeAuthConfig: () => describeAuthConfig,
@@ -3247,6 +3886,7 @@ __export(src_exports, {
   diffVault: () => diffVault,
   effectiveClearance: () => effectiveClearance,
   enableDevUnlock: () => enableDevUnlock,
+  encodeShareBase32: () => import_on_shamir2.encodeShareBase32,
   encryptBytes: () => encryptBytes,
   encryptDeterministic: () => encryptDeterministic,
   enrollAuthenticator: () => enrollAuthenticator,
@@ -3278,6 +3918,7 @@ __export(src_exports, {
   isPublicEnvelope: () => isPublicEnvelope,
   isSessionAlive: () => isSessionAlive,
   isULID: () => isULID,
+  isZodSchema: () => isZodSchema,
   issueDelegation: () => issueDelegation,
   keyringRecoverPassphrase: () => recoverPassphrase,
   keyringRotatePassphrase: () => rotatePassphrase,
@@ -3289,7 +3930,10 @@ __export(src_exports, {
   loadActiveDelegations: () => loadActiveDelegations,
   loadDevUnlock: () => loadDevUnlock,
   loadPaperRecoveryEntries: () => loadPaperRecoveryEntries,
+  loadPersistedSchema: () => loadPersistedSchema,
   loadPublicEnvelope: () => loadPublicEnvelope,
+  loadSealedPassphrase: () => loadSealedPassphrase,
+  loadShamirRecoveryEntries: () => loadShamirRecoveryEntries,
   loadUserEnvelope: () => loadUserEnvelope,
   loadVaultPolicy: () => loadVaultPolicy,
   magicLinkGrantRecordId: () => magicLinkGrantRecordId,
@@ -3298,11 +3942,14 @@ __export(src_exports, {
   mergePolicy: () => mergePolicy,
   min: () => min,
   mintPaperRecoveryEntry: () => mintPaperRecoveryEntry,
+  mintShamirRecoveryEntry: () => mintShamirRecoveryEntry,
   mintWrappedDeksBlob: () => mintWrappedDeksBlob,
   paddedIndex: () => paddedIndex,
   parseBytes: () => parseBytes,
   parseIndex: () => parseIndex,
+  parseSealedEnvelope: () => parseSealedEnvelope,
   persistDirectoryConfig: () => persistDirectoryConfig,
+  persistSchemaIfNeeded: () => persistSchemaIfNeeded,
   persistUserVisibility: () => persistUserVisibility,
   putCredential: () => putCredential,
   readDirectoryConfig: () => readDirectoryConfig,
@@ -3330,13 +3977,17 @@ __export(src_exports, {
   routeStore: () => routeStore,
   runTransaction: () => runTransaction,
   savePaperRecoveryEntries: () => savePaperRecoveryEntries,
+  savePersistedSchema: () => savePersistedSchema,
   savePublicEnvelope: () => savePublicEnvelope,
+  saveSealedPassphrase: () => saveSealedPassphrase,
+  saveShamirRecoveryEntries: () => saveShamirRecoveryEntries,
   saveUserEnvelope: () => saveUserEnvelope,
   saveVaultPolicy: () => saveVaultPolicy,
   sha256Hex: () => sha256Hex3,
   sum: () => sum,
   unwrapDeksFromBlob: () => unwrapDeksFromBlob,
   unwrapDeksFromPaperEntry: () => unwrapDeksFromPaperEntry,
+  unwrapDeksFromShamirEntry: () => unwrapDeksFromShamirEntry,
   unwrapMagicLinkGrant: () => unwrapMagicLinkGrant,
   validateI18nTextValue: () => validateI18nTextValue,
   validatePassphrase: () => validatePassphrase,
@@ -5228,7 +5879,8 @@ var ALLOWED_HEADER_KEYS = /* @__PURE__ */ new Set([
   "handle",
   "bodyBytes",
   "bodySha256",
-  "publicEnvelope"
+  "publicEnvelope",
+  "autoUnlock"
 ]);
 function validateBundleHeader(parsed) {
   if (parsed === null || typeof parsed !== "object") {
@@ -5283,6 +5935,14 @@ function validateBundleHeader(parsed) {
       );
     }
   }
+  if (h["autoUnlock"] !== void 0) {
+    if (h["autoUnlock"] !== "unsealed" && h["autoUnlock"] !== "sealed") {
+      const got = typeof h["autoUnlock"] === "string" ? `"${h["autoUnlock"]}"` : typeof h["autoUnlock"];
+      throw new Error(
+        `.noydb bundle header.autoUnlock must be 'unsealed' or 'sealed' when present, got ${got}.`
+      );
+    }
+  }
 }
 function encodeBundleHeader(header) {
   validateBundleHeader(header);
@@ -5291,7 +5951,8 @@ function encodeBundleHeader(header) {
     handle: header.handle,
     bodyBytes: header.bodyBytes,
     bodySha256: header.bodySha256,
-    ...header.publicEnvelope !== void 0 ? { publicEnvelope: header.publicEnvelope } : {}
+    ...header.publicEnvelope !== void 0 ? { publicEnvelope: header.publicEnvelope } : {},
+    ...header.autoUnlock !== void 0 ? { autoUnlock: header.autoUnlock } : {}
   });
   return new TextEncoder().encode(json);
 }
@@ -5328,6 +5989,167 @@ function hasNoydbBundleMagic(bytes) {
 // src/bundle/bundle.ts
 init_errors();
 init_storage();
+function validateAutoUnlockOptions(opts) {
+  if (opts.autoPassphrases !== void 0 && opts.sealedPassphrases !== void 0) {
+    throw new ValidationError(
+      "writeNoydbBundle: `autoPassphrases` and `sealedPassphrases` are mutually exclusive. Choose one or the other."
+    );
+  }
+  if (opts.autoPassphrases !== void 0) {
+    if (opts.autoPassphrases.policy !== "public-by-design") {
+      throw new ValidationError(
+        'writeNoydbBundle: `autoPassphrases` requires `policy: "public-by-design"`. This is an explicit opt-in marker \u2014 bundling plaintext credentials is safe only when those credentials are intended to be public (demo data, sample vaults). For production credentials, use `sealedPassphrases` instead.'
+      );
+    }
+    const userCount = Object.keys(opts.autoPassphrases.perUser).length;
+    if (userCount === 0) {
+      throw new ValidationError(
+        "writeNoydbBundle: `autoPassphrases.perUser` must have at least one entry."
+      );
+    }
+    return "unsealed";
+  }
+  if (opts.sealedPassphrases !== void 0) {
+    if (opts.sealedPassphrases.mode !== "self-target") {
+      throw new ValidationError(
+        `writeNoydbBundle: \`sealedPassphrases.mode\` must be 'self-target' in slice 1 (got '${opts.sealedPassphrases.mode}'). Recipient-target sealing via the RecipientSealer interface is deferred per foundation \xA711.4.`
+      );
+    }
+    if (opts.sealedPassphrases.provider === void 0) {
+      throw new ValidationError(
+        "writeNoydbBundle: `sealedPassphrases.provider` is required (a `SealingKeyProvider`)."
+      );
+    }
+    const userCount = Object.keys(opts.sealedPassphrases.perUser).length;
+    if (userCount === 0) {
+      throw new ValidationError(
+        "writeNoydbBundle: `sealedPassphrases.perUser` must have at least one entry."
+      );
+    }
+    return "sealed";
+  }
+  return null;
+}
+async function buildAutoUnlockWrapper(dumpJson, opts) {
+  if (opts.autoPassphrases !== void 0) {
+    return {
+      _noydb_bundle_body: 1,
+      dump: dumpJson,
+      _autoUnlock: {
+        kind: "unsealed",
+        perUser: { ...opts.autoPassphrases.perUser }
+      }
+    };
+  }
+  if (opts.sealedPassphrases === void 0) {
+    throw new Error("unreachable \u2014 validation should have caught this");
+  }
+  const { provider, perUser } = opts.sealedPassphrases;
+  const sealedPerUser = {};
+  const encoder = new TextEncoder();
+  for (const [userId, passphrase] of Object.entries(perUser)) {
+    const sealed = await provider.seal(encoder.encode(passphrase));
+    sealedPerUser[userId] = {
+      pid: provider.id,
+      sealed: bytesToBase64(sealed),
+      alg: "aes-256-gcm"
+    };
+  }
+  return {
+    _noydb_bundle_body: 1,
+    dump: dumpJson,
+    _autoUnlock: { kind: "sealed", perUser: sealedPerUser }
+  };
+}
+function parseAutoUnlockBody(bodyString) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyString);
+  } catch (err) {
+    throw new BundleIntegrityError(
+      "header declared autoUnlock but body could not be parsed as JSON wrapper: " + (err instanceof Error ? err.message : String(err))
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new BundleIntegrityError("autoUnlock body is not a JSON object");
+  }
+  const obj = parsed;
+  if (obj["_noydb_bundle_body"] !== 1) {
+    throw new BundleIntegrityError(
+      "autoUnlock body missing `_noydb_bundle_body: 1` discriminator"
+    );
+  }
+  if (typeof obj["dump"] !== "string") {
+    throw new BundleIntegrityError("autoUnlock body must carry a string `dump` field");
+  }
+  const blob = obj["_autoUnlock"];
+  if (typeof blob !== "object" || blob === null) {
+    throw new BundleIntegrityError("autoUnlock body missing `_autoUnlock` blob");
+  }
+  const blobObj = blob;
+  const kind = blobObj["kind"];
+  if (kind !== "unsealed" && kind !== "sealed") {
+    throw new BundleIntegrityError(
+      `autoUnlock blob has invalid kind ${String(kind)}; expected 'unsealed' or 'sealed'`
+    );
+  }
+  return {
+    dump: obj["dump"],
+    blob
+  };
+}
+async function resolveAutoUnlock(blob, opts) {
+  if (blob.kind === "unsealed") {
+    return { kind: "unsealed", perUser: { ...blob.perUser } };
+  }
+  if (opts.sealingProviders === void 0 || opts.sealingProviders.length === 0) {
+    const passthrough = {};
+    for (const [userId, entry] of Object.entries(blob.perUser)) {
+      passthrough[userId] = entry.sealed;
+    }
+    return { kind: "sealed", perUser: passthrough };
+  }
+  const providersByPid = /* @__PURE__ */ new Map();
+  for (const p of opts.sealingProviders) providersByPid.set(p.id, p);
+  const decoder = new TextDecoder();
+  const unsealedMap = {};
+  for (const [userId, entry] of Object.entries(blob.perUser)) {
+    const provider = providersByPid.get(entry.pid);
+    if (provider === void 0) {
+      if (opts.attemptUnsealAcrossProviders === true) {
+        let opened = null;
+        for (const candidate of opts.sealingProviders) {
+          try {
+            const plaintextBytes2 = await candidate.unseal(base64ToBytes(entry.sealed));
+            opened = decoder.decode(plaintextBytes2);
+            break;
+          } catch {
+          }
+        }
+        if (opened === null) {
+          throw new BundleSealMismatchError(userId, entry.pid);
+        }
+        unsealedMap[userId] = opened;
+        continue;
+      }
+      throw new BundleSealMismatchError(userId, entry.pid);
+    }
+    const plaintextBytes = await provider.unseal(base64ToBytes(entry.sealed));
+    unsealedMap[userId] = decoder.decode(plaintextBytes);
+  }
+  return { kind: "sealed", perUser: unsealedMap };
+}
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
 var cachedBrotliSupport = null;
 function supportsBrotliCompression() {
   if (cachedBrotliSupport !== null) return cachedBrotliSupport;
@@ -5483,12 +6305,14 @@ async function writeNoydbBundle(vault, opts = {}) {
       "writeNoydbBundle: pass either exportPassphrase or recipients, not both"
     );
   }
+  const autoUnlockMode = validateAutoUnlockOptions(opts);
   const handle = await vault.getBundleHandle();
   const dumpJson = await vault.dump();
   const rekeyed = await applyRecipientRewrap(vault, dumpJson, opts);
   const plainFiltered = await applyPlaintextFilters(vault, rekeyed, opts);
   const filtered = applySliceFilters(plainFiltered, opts);
-  const dumpBytes = new TextEncoder().encode(filtered);
+  const bodyJsonStr = autoUnlockMode === null ? filtered : JSON.stringify(await buildAutoUnlockWrapper(filtered, opts));
+  const dumpBytes = new TextEncoder().encode(bodyJsonStr);
   const { format, streamFormat } = selectCompression(opts.compression);
   const body = streamFormat === null ? dumpBytes : await pumpThroughStream(dumpBytes, new CompressionStream(streamFormat));
   const bodySha256 = await sha256Hex2(body);
@@ -5498,7 +6322,8 @@ async function writeNoydbBundle(vault, opts = {}) {
     handle,
     bodyBytes: body.length,
     bodySha256,
-    ...publicEnvelope !== void 0 ? { publicEnvelope } : {}
+    ...publicEnvelope !== void 0 ? { publicEnvelope } : {},
+    ...autoUnlockMode !== null ? { autoUnlock: autoUnlockMode } : {}
   };
   const headerBytes = encodeBundleHeader(header);
   const prefix = new Uint8Array(NOYDB_BUNDLE_PREFIX_BYTES);
@@ -5551,7 +6376,7 @@ function readNoydbBundlePublicEnvelope(bytes, opts = {}) {
     ...env.description !== void 0 ? { description: pickLocale(env.description, opts.locale, env.defaultLocale) } : {}
   };
 }
-async function readNoydbBundle(bytes) {
+async function readNoydbBundle(bytes, opts = {}) {
   const { header, bodyOffset, algo } = parsePrefixAndHeader(bytes);
   const body = bytes.slice(bodyOffset);
   if (body.length !== header.bodyBytes) {
@@ -5578,8 +6403,13 @@ async function readNoydbBundle(bytes) {
       );
     }
   }
-  const dumpJson = new TextDecoder("utf-8", { fatal: true }).decode(dumpBytes);
-  return { header, dumpJson };
+  const bodyString = new TextDecoder("utf-8", { fatal: true }).decode(dumpBytes);
+  if (header.autoUnlock === void 0) {
+    return { header, dumpJson: bodyString };
+  }
+  const { dump, blob } = parseAutoUnlockBody(bodyString);
+  const autoUnlock = await resolveAutoUnlock(blob, opts);
+  return { header, dumpJson: dump, autoUnlock };
 }
 
 // src/index.ts
@@ -5624,17 +6454,123 @@ function formatPath(path) {
   ).join(".");
 }
 
+// src/persisted-schemas/canonicalize.ts
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalize).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  const parts = keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]));
+  return "{" + parts.join(",") + "}";
+}
+
+// src/persisted-schemas/derive.ts
+init_crypto();
+function isZodSchema(value) {
+  if (value === null || typeof value !== "object") return false;
+  const def = value._def;
+  if (!def || typeof def !== "object") return false;
+  return typeof def.typeName === "string" && def.typeName.startsWith("Zod");
+}
+function detectKind(validator) {
+  if (isZodSchema(validator)) return "Zod";
+  return "Unknown";
+}
+async function loadZodConverter() {
+  try {
+    const mod = await import("zod-to-json-schema");
+    if (!mod.zodToJsonSchema) {
+      throw new Error("zod-to-json-schema export missing");
+    }
+    return mod.zodToJsonSchema;
+  } catch (err) {
+    throw new Error(
+      `persistJsonSchema requires the optional peer-dep \`zod-to-json-schema\`. Install it: \`pnpm add zod-to-json-schema\` (or npm/yarn equivalent). Original error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function derivePersistedSchema(validator) {
+  const kind = detectKind(validator);
+  const derivedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (kind === "Zod") {
+    const convert = await loadZodConverter();
+    const jsonSchema = convert(validator);
+    const canonical = canonicalize(jsonSchema);
+    const hash = await sha256Hex(new TextEncoder().encode(canonical));
+    return { _noydb_schema: 1, kind, jsonSchema, hash, derivedAt };
+  }
+  return {
+    _noydb_schema: 1,
+    kind,
+    jsonSchema: null,
+    hash: null,
+    reason: `derivation not yet supported for kind=${kind} (v0 supports Zod only)`,
+    derivedAt
+  };
+}
+
+// src/persisted-schemas/storage.ts
+init_crypto();
+init_types();
+var SCHEMAS_COLLECTION = "_schemas";
+async function loadPersistedSchema(store, vault, collection, dek) {
+  const envelope = await store.get(vault, SCHEMAS_COLLECTION, collection);
+  if (!envelope) return void 0;
+  try {
+    const plaintext = await decrypt(envelope._iv, envelope._data, dek);
+    const parsed = JSON.parse(plaintext);
+    if (parsed._noydb_schema !== 1) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function savePersistedSchema(store, vault, collection, dek, payload) {
+  const json = JSON.stringify(payload);
+  const { iv, data } = await encrypt(json, dek);
+  const prior = await store.get(vault, SCHEMAS_COLLECTION, collection);
+  const env = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: (prior?._v ?? 0) + 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: iv,
+    _data: data
+  };
+  await store.put(vault, SCHEMAS_COLLECTION, collection, env);
+}
+
+// src/persisted-schemas/register.ts
+async function persistSchemaIfNeeded(opts) {
+  const fresh = await derivePersistedSchema(opts.validator);
+  const stored = await loadPersistedSchema(opts.store, opts.vault, opts.collectionName, opts.dek);
+  if (stored && isEquivalent(stored, fresh)) {
+    return { written: false, skipped: true, envelope: stored };
+  }
+  await savePersistedSchema(opts.store, opts.vault, opts.collectionName, opts.dek, fresh);
+  return { written: true, skipped: false, envelope: fresh };
+}
+function isEquivalent(a, b) {
+  if (a.kind !== b.kind) return false;
+  if (a.hash && b.hash) return a.hash === b.hash;
+  if (a.hash === null && b.hash === null) return true;
+  return false;
+}
+
 // src/history/history.ts
 var HISTORY_COLLECTION = "_history";
-function matchesPrefix(id, collection, recordId) {
-  if (recordId) {
-    return id.startsWith(`${collection}:${recordId}:`);
+function matchesPrefix(id, collection, recordId2) {
+  if (recordId2) {
+    return id.startsWith(`${collection}:${recordId2}:`);
   }
   return id.startsWith(`${collection}:`);
 }
-async function getHistory(adapter, vault, collection, recordId, options) {
+async function getHistory(adapter, vault, collection, recordId2, options) {
   const allIds = await adapter.list(vault, HISTORY_COLLECTION);
-  const matchingIds = allIds.filter((id) => matchesPrefix(id, collection, recordId)).sort().reverse();
+  const matchingIds = allIds.filter((id) => matchesPrefix(id, collection, recordId2)).sort().reverse();
   const entries = [];
   for (const id of matchingIds) {
     const envelope = await adapter.get(vault, HISTORY_COLLECTION, id);
@@ -6967,6 +7903,17 @@ var RecoveryNotEnrolledError = class extends NoydbError {
     this.name = "RecoveryNotEnrolledError";
   }
 };
+var ManagedRecoveryNotEnrolledError = class extends NoydbError {
+  vault;
+  constructor(vault) {
+    super(
+      "MANAGED_RECOVERY_NOT_ENROLLED",
+      `Managed-mode vault "${vault}" requires at least one strong recovery profile (Shamir today; multi-channel / admin-mediated when they ship). Paper alone is NOT strong under managed mode \u2014 losing the paper sheet would mean losing every record permanently. Bootstrap with \`db.openVaultAndEnrollRecovery("${vault}", { recovery: [{ profile: "shamir", k: 2, n: 3 }] })\`, or call \`db.enrollRecovery(vault, { profile: "shamir", k, n })\` separately, then re-attempt \`openVault\`.`
+    );
+    this.name = "ManagedRecoveryNotEnrolledError";
+    this.vault = vault;
+  }
+};
 var RecoveryProfileNotImplementedError = class extends NoydbError {
   profile;
   tracking;
@@ -6996,7 +7943,7 @@ async function mintWrappedDeksBlob(deks, credential) {
   const exported = {};
   for (const [coll, dek] of deks) {
     const raw = await subtle2.exportKey("raw", dek);
-    exported[coll] = bytesToBase64(new Uint8Array(raw));
+    exported[coll] = bytesToBase642(new Uint8Array(raw));
   }
   const plaintext = new TextEncoder().encode(JSON.stringify({ deks: exported }));
   const ciphertext = await subtle2.encrypt(
@@ -7005,22 +7952,22 @@ async function mintWrappedDeksBlob(deks, credential) {
     plaintext
   );
   return {
-    salt: bytesToBase64(salt),
-    iv: bytesToBase64(iv),
-    wrappedDeks: bytesToBase64(new Uint8Array(ciphertext))
+    salt: bytesToBase642(salt),
+    iv: bytesToBase642(iv),
+    wrappedDeks: bytesToBase642(new Uint8Array(ciphertext))
   };
 }
 async function unwrapDeksFromBlob(blob, credential) {
-  const wrappingKey = await deriveWrappingKey(credential, base64ToBytes(blob.salt));
+  const wrappingKey = await deriveWrappingKey(credential, base64ToBytes2(blob.salt));
   const plaintext = await subtle2.decrypt(
-    { name: "AES-GCM", iv: base64ToBytes(blob.iv) },
+    { name: "AES-GCM", iv: base64ToBytes2(blob.iv) },
     wrappingKey,
-    base64ToBytes(blob.wrappedDeks)
+    base64ToBytes2(blob.wrappedDeks)
   );
   const parsed = JSON.parse(new TextDecoder().decode(plaintext));
   const deks = /* @__PURE__ */ new Map();
   for (const [coll, b64] of Object.entries(parsed.deks)) {
-    const raw = base64ToBytes(b64);
+    const raw = base64ToBytes2(b64);
     const key = await subtle2.importKey(
       "raw",
       raw,
@@ -7053,12 +8000,12 @@ async function deriveWrappingKey(credential, salt) {
     ["encrypt", "decrypt"]
   );
 }
-function bytesToBase64(b) {
+function bytesToBase642(b) {
   let s = "";
   for (const x of b) s += String.fromCharCode(x);
   return btoa(s);
 }
-function base64ToBytes(b64) {
+function base64ToBytes2(b64) {
   const s = atob(b64);
   const out = new Uint8Array(s.length);
   for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
@@ -7066,6 +8013,8 @@ function base64ToBytes(b64) {
 }
 
 // src/team/recovery.ts
+var import_on_shamir = require("@noy-db/on-shamir");
+var import_on_shamir2 = require("@noy-db/on-shamir");
 var PAPER_DOC_ID = "recovery-paper";
 async function loadPaperRecoveryEntries(store, vault) {
   const env = await store.get(vault, "_meta", PAPER_DOC_ID);
@@ -7100,7 +8049,81 @@ async function burnPaperRecoveryEntry(store, vault, codeId) {
 }
 async function hasRecoveryEnrolled(store, vault) {
   const paper = await loadPaperRecoveryEntries(store, vault);
-  return paper.length > 0;
+  if (paper.length > 0) return true;
+  const shamir = await loadShamirRecoveryEntries(store, vault);
+  return shamir.length > 0;
+}
+async function hasStrongRecoveryEnrolled(store, vault) {
+  const shamir = await loadShamirRecoveryEntries(store, vault);
+  return shamir.length > 0;
+}
+var SHAMIR_DOC_ID = "recovery-shamir";
+async function loadShamirRecoveryEntries(store, vault) {
+  const env = await store.get(vault, "_meta", SHAMIR_DOC_ID);
+  if (!env) return [];
+  try {
+    const doc = JSON.parse(env._data);
+    if (doc.profile !== "shamir" || !Array.isArray(doc.entries)) return [];
+    return doc.entries;
+  } catch {
+    return [];
+  }
+}
+async function saveShamirRecoveryEntries(store, vault, entries) {
+  const doc = {
+    _noydb_recovery: 1,
+    profile: "shamir",
+    entries
+  };
+  const envelope = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify(doc)
+  };
+  await store.put(vault, "_meta", SHAMIR_DOC_ID, envelope);
+}
+async function mintShamirRecoveryEntry(deks, entryId, k, n, label) {
+  const recoverySecret = crypto.getRandomValues(new Uint8Array(32));
+  try {
+    const credential = bytesToBase643(recoverySecret);
+    const blob = await mintWrappedDeksBlob(deks, credential);
+    const shares = (0, import_on_shamir.splitSecret)(recoverySecret, k, n);
+    const shareStrings = shares.map(import_on_shamir.encodeShareBase32);
+    const xCoords = shares.map((s) => s.x);
+    const entry = {
+      ...blob,
+      entryId,
+      k,
+      n,
+      xCoords,
+      enrolledAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...label !== void 0 && { label }
+    };
+    return { entry, shareStrings };
+  } finally {
+    recoverySecret.fill(0);
+  }
+}
+async function unwrapDeksFromShamirEntry(entry, shares) {
+  if (shares.length < entry.k) {
+    throw new Error(
+      `Insufficient shares: this Shamir entry needs ${entry.k} of ${entry.n}, but ${shares.length} were provided.`
+    );
+  }
+  const secret = (0, import_on_shamir.combineSecret)(shares);
+  try {
+    const credential = bytesToBase643(secret);
+    return await unwrapDeksFromBlob(entry, credential);
+  } finally {
+    secret.fill(0);
+  }
+}
+function bytesToBase643(b) {
+  let s = "";
+  for (const x of b) s += String.fromCharCode(x);
+  return btoa(s);
 }
 async function mintPaperRecoveryEntry(deks, code, codeId) {
   const blob = await mintWrappedDeksBlob(deks, code);
@@ -7115,6 +8138,7 @@ async function unwrapDeksFromPaperEntry(entry, code) {
 }
 
 // src/team/rotate-recover.ts
+var import_on_shamir3 = require("@noy-db/on-shamir");
 init_errors();
 async function rotatePassphrase(store, vault, userId, input) {
   if (!input.allowWeakPassphrase) {
@@ -7213,13 +8237,16 @@ async function recoverPassphrase(store, vault, userId, input) {
     assertStrongPassphrase(input.newPassphrase, input.passphrasePolicy);
   }
   const profile = input.recoveryProof.profile;
-  if (profile !== "paper") {
-    throw new RecoveryProfileNotImplementedError(
-      profile,
-      "https://github.com/vLannaAi/noy-db/issues/10"
-    );
+  if (profile === "paper") {
+    return recoverViaPaperCode(store, vault, userId, input);
   }
-  return recoverViaPaperCode(store, vault, userId, input);
+  if (profile === "shamir") {
+    return recoverViaShamir(store, vault, userId, input);
+  }
+  throw new RecoveryProfileNotImplementedError(
+    profile,
+    "https://github.com/vLannaAi/noy-db/issues/196"
+  );
 }
 async function recoverViaPaperCode(store, vault, userId, input) {
   if (input.recoveryProof.profile !== "paper") throw new Error("unreachable");
@@ -7285,6 +8312,99 @@ async function recoverViaPaperCode(store, vault, userId, input) {
 function normalizePaperCode(input) {
   return input.toUpperCase().replace(/[\s\-_]/g, "");
 }
+async function recoverViaShamir(store, vault, userId, input) {
+  if (input.recoveryProof.profile !== "shamir") throw new Error("unreachable");
+  const { entryId: requestedEntryId, shares: shareStrings } = input.recoveryProof.payload;
+  if (shareStrings.length === 0) {
+    throw new ValidationError(
+      "Shamir recovery requires at least one share; received an empty array."
+    );
+  }
+  const env = await store.get(vault, "_keyring", userId);
+  if (!env) {
+    throw new NoAccessError(`No keyring found for user "${userId}" in vault "${vault}".`);
+  }
+  const file = JSON.parse(env._data);
+  let decodedShares;
+  try {
+    decodedShares = shareStrings.map((s) => (0, import_on_shamir3.decodeShareBase32)(s));
+  } catch (err) {
+    throw new ValidationError(
+      "One or more Shamir shares could not be decoded. They may be malformed, truncated, or from an incompatible version. Original error: " + (err instanceof Error ? err.message : String(err))
+    );
+  }
+  const allEntries = await loadShamirRecoveryEntries(store, vault);
+  if (allEntries.length === 0) {
+    throw new NoAccessError(
+      `No Shamir-recovery entries enrolled for vault "${vault}". Enroll via \`db.enrollRecovery({ profile: "shamir", k, n })\` before relying on recovery.`
+    );
+  }
+  let candidates;
+  if (requestedEntryId !== void 0) {
+    candidates = allEntries.filter((e) => e.entryId === requestedEntryId);
+    if (candidates.length === 0) {
+      throw new NoAccessError(
+        `No Shamir-recovery entry with entryId="${requestedEntryId}" found in vault "${vault}". Available entries: ` + allEntries.map((e) => `"${e.entryId}"`).join(", ")
+      );
+    }
+  } else {
+    candidates = allEntries;
+  }
+  let recoveredDeks;
+  for (const entry of candidates) {
+    const xCoordSet = new Set(entry.xCoords);
+    const matchingShares = decodedShares.filter((s) => xCoordSet.has(s.x));
+    if (matchingShares.length < entry.k) {
+      continue;
+    }
+    try {
+      const deks = await unwrapDeksFromShamirEntry(entry, matchingShares);
+      recoveredDeks = deks;
+      break;
+    } catch {
+    }
+  }
+  if (!recoveredDeks) {
+    const minK = Math.min(...candidates.map((e) => e.k));
+    if (decodedShares.length < minK) {
+      throw new InvalidKeyError(
+        `Insufficient Shamir shares to combine: the smallest enrolled threshold is ${minK}, but only ${decodedShares.length} share${decodedShares.length === 1 ? " was" : "s were"} provided.`
+      );
+    }
+    throw new InvalidKeyError(
+      "Shamir shares do not match any enrolled entry. Possible causes: shares were tampered with, came from a different enrollment, or the entry was rotated after these shares were distributed."
+    );
+  }
+  const newSalt = generateSalt();
+  const newKek = await deriveKey(input.newPassphrase, newSalt);
+  const wrappedDeks = {};
+  for (const [coll, dek] of recoveredDeks) {
+    wrappedDeks[coll] = await wrapKey(dek, newKek);
+  }
+  const canary = await mintKeyringCanary(newKek);
+  const next = {
+    ...file,
+    _noydb_keyring: NOYDB_KEYRING_VERSION,
+    deks: wrappedDeks,
+    salt: bufferToBase64(newSalt),
+    authenticators: [],
+    // tier-2 slots wrap old KEK, drop them on recovery
+    canary
+  };
+  await writeKeyringFile2(store, vault, userId, next);
+  return {
+    userId: file.user_id,
+    displayName: file.display_name,
+    role: file.role,
+    permissions: file.permissions,
+    deks: recoveredDeks,
+    kek: newKek,
+    salt: newSalt,
+    authenticators: [],
+    ...file.export_capability !== void 0 && { exportCapability: file.export_capability },
+    ...file.import_capability !== void 0 && { importCapability: file.import_capability }
+  };
+}
 async function writeKeyringFile2(store, vault, userId, file) {
   const envelope = {
     _noydb: 1,
@@ -7722,6 +8842,134 @@ function sanitizeId(s) {
   return s.replace(/[^a-zA-Z0-9]/g, "_");
 }
 
+// src/team/managed-passphrase.ts
+init_types();
+var MemorySealingKeyProvider = class {
+  id;
+  fingerprint;
+  keyBytes;
+  constructor(opts) {
+    this.id = opts.id;
+    const encoded = new TextEncoder().encode(opts.id);
+    let h = 0;
+    for (let i = 0; i < encoded.length; i++) {
+      h = h * 31 + encoded[i] >>> 0;
+    }
+    this.fingerprint = new Uint8Array([
+      h >>> 24 & 255,
+      h >>> 16 & 255,
+      h >>> 8 & 255,
+      h & 255
+    ]);
+    this.keyBytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+      this.keyBytes[i] = this.fingerprint[i % 4] ^ i * 17;
+    }
+  }
+  async seal(passphrase) {
+    const out = new Uint8Array(4 + passphrase.length);
+    out.set(this.fingerprint, 0);
+    for (let i = 0; i < passphrase.length; i++) {
+      out[4 + i] = passphrase[i] ^ this.keyBytes[i % 16];
+    }
+    return out;
+  }
+  async unseal(sealed) {
+    if (sealed.length < 4) {
+      throw new Error("MemorySealingKeyProvider: sealed input too short");
+    }
+    for (let i = 0; i < 4; i++) {
+      if (sealed[i] !== this.fingerprint[i]) {
+        throw new Error(
+          `MemorySealingKeyProvider("${this.id}"): provider-id mismatch on unseal (sealed bytes were produced by a different provider)`
+        );
+      }
+    }
+    const body = sealed.subarray(4);
+    const out = new Uint8Array(body.length);
+    for (let i = 0; i < body.length; i++) {
+      out[i] = body[i] ^ this.keyBytes[i % 16];
+    }
+    return out;
+  }
+};
+var SEALED_PASSPHRASE_RECORD_ID = "sealed-passphrase";
+function bytesToBase644(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+function base64ToBytes3(b64) {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function parseSealedEnvelope(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const r = raw;
+  if (r._noydb_sealed !== 1) return void 0;
+  if (r.v === 1 && typeof r.pid === "string" && typeof r.payload === "string") {
+    return {
+      _noydb_sealed: 1,
+      providerId: r.pid,
+      sealed: base64ToBytes3(r.payload)
+    };
+  }
+  if (typeof r.providerId === "string" && typeof r.sealed === "string") {
+    return {
+      _noydb_sealed: 1,
+      providerId: r.providerId,
+      sealed: base64ToBytes3(r.sealed)
+    };
+  }
+  return void 0;
+}
+async function saveSealedPassphrase(store, vault, payload) {
+  const persisted = {
+    v: 1,
+    _noydb_sealed: 1,
+    pid: payload.providerId,
+    payload: bytesToBase644(payload.sealed)
+  };
+  const prior = await store.get(vault, "_meta", SEALED_PASSPHRASE_RECORD_ID);
+  const env = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: (prior?._v ?? 0) + 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    // AES-GCM bypassed — the sealing layer is the security boundary.
+    _iv: "",
+    _data: JSON.stringify(persisted)
+  };
+  await store.put(vault, "_meta", SEALED_PASSPHRASE_RECORD_ID, env);
+}
+async function loadSealedPassphrase(store, vault) {
+  const envelope = await store.get(vault, "_meta", SEALED_PASSPHRASE_RECORD_ID);
+  if (!envelope) return void 0;
+  try {
+    return parseSealedEnvelope(JSON.parse(envelope._data));
+  } catch {
+    return void 0;
+  }
+}
+async function resolveManagedSecret(store, vault, provider) {
+  const existing = await loadSealedPassphrase(store, vault);
+  if (existing) {
+    if (existing.providerId !== provider.id) {
+      throw new Error(
+        `Managed-mode vault "${vault}" was sealed under provider id "${existing.providerId}" but the current SealingKeyProvider is "${provider.id}". Pass the same provider that originally enrolled the vault, or treat this as a fresh enrollment and clear \`_meta/sealed-passphrase\` first.`
+      );
+    }
+    const plaintext = await provider.unseal(existing.sealed);
+    return bytesToBase644(plaintext);
+  }
+  const random = new Uint8Array(32);
+  globalThis.crypto.getRandomValues(random);
+  const sealed = await provider.seal(random);
+  await saveSealedPassphrase(store, vault, { providerId: provider.id, sealed });
+  return bytesToBase644(random);
+}
+
 // src/team/peer-recover.ts
 init_types();
 init_crypto();
@@ -7856,116 +9104,40 @@ function notEnabled2(op) {
 var NO_HISTORY = {
   async saveHistory() {
   },
-  async getHistoryEntries() {
-    throw notEnabled2("collection.history()");
-  },
-  async getVersionEnvelope() {
-    throw notEnabled2("collection.getVersion()");
-  },
-  async pruneHistory() {
-    return 0;
-  },
-  async clearHistory() {
-    return 0;
-  },
-  async envelopePayloadHash() {
-    return "";
-  },
-  computePatch() {
-    return [];
-  },
-  diff() {
-    throw notEnabled2("collection.diff()");
-  },
-  buildLedger() {
-    return null;
-  },
-  buildVaultInstant() {
-    throw notEnabled2("vault.at() / vault.timeMachine()");
-  }
-};
-
-// src/query/predicate.ts
-function readPath(record, path) {
-  if (record === null || record === void 0) return void 0;
-  if (!path.includes(".")) {
-    return record[path];
-  }
-  const segments = path.split(".");
-  let cursor = record;
-  for (const segment of segments) {
-    if (cursor === null || cursor === void 0) return void 0;
-    cursor = cursor[segment];
-  }
-  return cursor;
-}
-function evaluateFieldClause(record, clause) {
-  const actual = readPath(record, clause.field);
-  const { op, value } = clause;
-  switch (op) {
-    case "==":
-      return actual === value;
-    case "!=":
-      return actual !== value;
-    case "<":
-      return isComparable(actual, value) && actual < value;
-    case "<=":
-      return isComparable(actual, value) && actual <= value;
-    case ">":
-      return isComparable(actual, value) && actual > value;
-    case ">=":
-      return isComparable(actual, value) && actual >= value;
-    case "in":
-      return Array.isArray(value) && value.includes(actual);
-    case "contains":
-      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
-      if (Array.isArray(actual)) return actual.includes(value);
-      return false;
-    case "startsWith":
-      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
-    case "between": {
-      if (!Array.isArray(value) || value.length !== 2) return false;
-      const [lo, hi] = value;
-      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
-      return actual >= lo && actual <= hi;
-    }
-    default: {
-      const _exhaustive = op;
-      void _exhaustive;
-      return false;
-    }
-  }
-}
-function isComparable(a, b) {
-  if (typeof a === "number" && typeof b === "number") return true;
-  if (typeof a === "string" && typeof b === "string") return true;
-  if (a instanceof Date && b instanceof Date) return true;
-  return false;
-}
-function evaluateClause(record, clause) {
-  switch (clause.type) {
-    case "field":
-      return evaluateFieldClause(record, clause);
-    case "filter":
-      return clause.fn(record);
-    case "wherePredicate":
-      return clause.fn(record, clause.ctx);
-    case "group":
-      if (clause.op === "and") {
-        for (const child of clause.clauses) {
-          if (!evaluateClause(record, child)) return false;
-        }
-        return true;
-      } else {
-        for (const child of clause.clauses) {
-          if (evaluateClause(record, child)) return true;
-        }
-        return false;
-      }
+  async getHistoryEntries() {
+    throw notEnabled2("collection.history()");
+  },
+  async getVersionEnvelope() {
+    throw notEnabled2("collection.getVersion()");
+  },
+  async pruneHistory() {
+    return 0;
+  },
+  async clearHistory() {
+    return 0;
+  },
+  async envelopePayloadHash() {
+    return "";
+  },
+  computePatch() {
+    return [];
+  },
+  diff() {
+    throw notEnabled2("collection.diff()");
+  },
+  buildLedger() {
+    return null;
+  },
+  buildVaultInstant() {
+    throw notEnabled2("vault.at() / vault.timeMachine()");
   }
-}
+};
+
+// src/query/builder.ts
+init_predicate();
 
 // src/query/join.ts
+init_predicate();
 init_errors();
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
 var JOIN_WARN_FRACTION = 0.8;
@@ -8203,6 +9375,9 @@ var NO_AGGREGATE = {
   groupBy() {
     throw NOT_ENABLED2;
   },
+  groupByN() {
+    throw NOT_ENABLED2;
+  },
   scanAggregate() {
     throw NOT_ENABLED2;
   }
@@ -8586,53 +9761,10 @@ var Query = class _Query {
     }
     return this.aggregateStrategy.aggregate(executeRecords, spec, upstreams);
   }
-  /**
-   * Partition matching records into buckets keyed by a field, then
-   * terminate with `.aggregate(spec)` to compute per-bucket
-   * reducers..
-   *
-   * ```ts
-   * const byClient = invoices.query()
-   *   .where('status', '==', 'open')
-   *   .groupBy('clientId')
-   *   .aggregate({ total: sum('amount'), n: count() })
-   *   .run()
-   * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
-   * ```
-   *
-   * Result rows carry the group key value under the grouping field
-   * name plus every reducer output from the spec. Buckets are
-   * emitted in first-seen order — consumers who want a specific
-   * ordering should `.sort()` downstream.
-   *
-   * **Cardinality caps:** a one-shot warning fires at 10_000
-   * distinct groups; `GroupCardinalityError` throws at 100_000.
-   * Grouping on a high-uniqueness field like `id` or `createdAt` is
-   * almost always a query mistake — the error message names the
-   * field and observed cardinality and suggests narrowing with
-   * `.where()` first.
-   *
-   * **Null / undefined keys:** records with a missing or explicitly
-   * `null` group field get their own buckets. `Map`-based
-   * partitioning distinguishes `undefined` from `null`, so the two
-   * cases do NOT merge. Consumers who want them merged should
-   * coalesce upstream with `.filter()`.
-   *
-   * **Joins are not applied** — same rationale as `.count()` and
-   * `.aggregate()`. Joined fields in are projection-only, so
-   * running a join inside a grouping pipeline would be wasteful and
-   * could trigger `DanglingReferenceError` in strict mode for a
-   * call whose intent is purely to bucket-and-reduce. Grouping by
-   * a joined field is explicitly out of scope for — file an
-   * issue if a real consumer needs it.
-   *
-   * **Filter clauses (`.filter(fn)`):** grouped queries still
-   * support filter clauses in the underlying plan — they run in
-   * the same candidate/filter pipeline that `.aggregate()` uses.
-   * The performance caveat is the same: filter clauses cost O(N)
-   * per record and can't be index-accelerated.
-   */
-  groupBy(field) {
+  groupBy(...fields) {
+    if (fields.length === 0) {
+      throw new Error(".groupBy() requires at least one field");
+    }
     const source = this.source;
     const clauses = this.plan.clauses;
     const executeRecords = () => {
@@ -8644,36 +9776,21 @@ var Query = class _Query {
       const subscribe = source.subscribe.bind(source);
       upstreams.push({ subscribe: (cb) => subscribe(cb) });
     }
-    const joinCtx = this.joinContext;
-    const dictLabelResolver = joinCtx?.resolveDictSource ? (() => {
-      const dictSource = joinCtx.resolveDictSource(field);
-      if (!dictSource) return void 0;
-      const snapshot = dictSource.snapshot();
-      const dictMap = /* @__PURE__ */ new Map();
-      for (const entry of snapshot) {
-        const k = entry["key"];
-        const labels = entry["labels"];
-        if (typeof k === "string" && labels && typeof labels === "object") {
-          dictMap.set(k, labels);
-        }
-      }
-      return async (key, locale, fallback) => {
-        const labels = dictMap.get(key);
-        if (!labels) return void 0;
-        if (labels[locale] !== void 0) return labels[locale];
-        const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
-        for (const fb of chain) {
-          if (fb === "any") {
-            const any = Object.values(labels)[0];
-            if (any !== void 0) return any;
-          } else if (labels[fb] !== void 0) {
-            return labels[fb];
-          }
-        }
-        return void 0;
-      };
-    })() : void 0;
-    return this.aggregateStrategy.groupBy(executeRecords, field, upstreams, dictLabelResolver);
+    if (fields.length === 1) {
+      const field = fields[0];
+      const dictLabelResolver = buildDictLabelResolver(this.joinContext, field);
+      return this.aggregateStrategy.groupBy(
+        executeRecords,
+        field,
+        upstreams,
+        dictLabelResolver
+      );
+    }
+    return this.aggregateStrategy.groupByN(
+      executeRecords,
+      fields,
+      upstreams
+    );
   }
   /**
    * Re-run the query whenever the source notifies of changes.
@@ -8936,8 +10053,41 @@ function canonicalCtxHash(ctx) {
   }
   return (h >>> 0).toString(16).padStart(8, "0");
 }
+function buildDictLabelResolver(joinCtx, field) {
+  if (!joinCtx?.resolveDictSource) return void 0;
+  const dictSource = joinCtx.resolveDictSource(field);
+  if (!dictSource) return void 0;
+  const snapshot = dictSource.snapshot();
+  const dictMap = /* @__PURE__ */ new Map();
+  for (const entry of snapshot) {
+    const k = entry["key"];
+    const labels = entry["labels"];
+    if (typeof k === "string" && labels && typeof labels === "object") {
+      dictMap.set(k, labels);
+    }
+  }
+  return async (key, locale, fallback) => {
+    const labels = dictMap.get(key);
+    if (!labels) return void 0;
+    if (labels[locale] !== void 0) return labels[locale];
+    const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+    for (const fb of chain) {
+      if (fb === "any") {
+        const any = Object.values(labels)[0];
+        if (any !== void 0) return any;
+      } else if (labels[fb] !== void 0) {
+        return labels[fb];
+      }
+    }
+    return void 0;
+  };
+}
+
+// src/query/index.ts
+init_predicate();
 
 // src/indexing/eager-indexes.ts
+init_predicate();
 var CollectionIndexes = class {
   indexes = /* @__PURE__ */ new Map();
   /**
@@ -9062,6 +10212,7 @@ function removeFromIndex(idx, id, record) {
 }
 
 // src/aggregate/reducers.ts
+init_predicate();
 function count(opts) {
   const _seed = opts?.seed;
   void _seed;
@@ -9149,274 +10300,12 @@ function readNumber(record, field) {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
-// src/aggregate/aggregation.ts
-function reduceRecords(records, spec) {
-  const state = {};
-  for (const key of Object.keys(spec)) {
-    state[key] = spec[key].init();
-  }
-  for (const record of records) {
-    for (const key of Object.keys(spec)) {
-      state[key] = spec[key].step(state[key], record);
-    }
-  }
-  const result = {};
-  for (const key of Object.keys(spec)) {
-    result[key] = spec[key].finalize(state[key]);
-  }
-  return result;
-}
-var LiveAggregationImpl = class {
-  constructor(recompute, upstreams) {
-    this.recompute = recompute;
-    try {
-      this.value = recompute();
-      this.error = void 0;
-    } catch (err) {
-      this.value = void 0;
-      this.error = err;
-    }
-    for (const upstream of upstreams) {
-      const unsub = upstream.subscribe(() => this.refresh());
-      this.unsubscribes.push(unsub);
-    }
-  }
-  recompute;
-  value;
-  error;
-  listeners = /* @__PURE__ */ new Set();
-  unsubscribes = [];
-  stopped = false;
-  refresh() {
-    if (this.stopped) return;
-    try {
-      this.value = this.recompute();
-      this.error = void 0;
-    } catch (err) {
-      this.error = err;
-    }
-    for (const listener of this.listeners) {
-      try {
-        listener();
-      } catch (err) {
-        console.warn("[noy-db] LiveAggregation listener threw:", err);
-      }
-    }
-  }
-  subscribe(cb) {
-    if (this.stopped) {
-      return () => {
-      };
-    }
-    this.listeners.add(cb);
-    return () => {
-      this.listeners.delete(cb);
-    };
-  }
-  stop() {
-    if (this.stopped) return;
-    this.stopped = true;
-    for (const unsub of this.unsubscribes) {
-      try {
-        unsub();
-      } catch (err) {
-        console.warn("[noy-db] LiveAggregation upstream unsubscribe threw:", err);
-      }
-    }
-    this.unsubscribes.length = 0;
-    this.listeners.clear();
-  }
-};
-var Aggregation = class {
-  constructor(executeRecords, spec, upstreams) {
-    this.executeRecords = executeRecords;
-    this.spec = spec;
-    this.upstreams = upstreams;
-  }
-  executeRecords;
-  spec;
-  upstreams;
-  /**
-   * Execute the query and reduce the results synchronously.
-   * Returns the reduced shape matching the spec — e.g. a spec of
-   * `{ total: sum('amount'), n: count() }` returns
-   * `{ total: number, n: number }`.
-   */
-  run() {
-    return reduceRecords(this.executeRecords(), this.spec);
-  }
-  /**
-   * Build a reactive `LiveAggregation<R>` that re-runs the reduction
-   * whenever any upstream source notifies of a change. The initial
-   * value is computed eagerly in the constructor, so consumers can
-   * read `live.value` immediately after calling `.live()`.
-   *
-   * Always call `live.stop()` when finished — it tears down the
-   * upstream subscriptions. Vue's `onUnmounted` is the canonical
-   * place.
-   *
-   * **Implementation note:** every upstream change triggers a full
-   * re-reduction. Incremental maintenance (O(1) per delta for
-   * sum/count/avg via the reducer protocol's `remove()` method) is a
-   * planned follow-up optimization — the protocol already supports
-   * it, but the executor doesn't drive it yet. Consumers get
-   * correct, reactive values today; future PRs can switch to
-   * delta-based maintenance without changing this API.
-   */
-  live() {
-    const recompute = () => reduceRecords(this.executeRecords(), this.spec);
-    return new LiveAggregationImpl(recompute, this.upstreams);
-  }
-};
-function buildLiveAggregation(recompute, upstreams) {
-  return new LiveAggregationImpl(recompute, upstreams);
-}
-
-// src/aggregate/groupby.ts
-init_errors();
-var GROUPBY_WARN_CARDINALITY = 1e4;
-var GROUPBY_MAX_CARDINALITY = 1e5;
-var warnedCardinalityFields = /* @__PURE__ */ new Set();
-function warnCardinalityApproaching(field, observed) {
-  if (warnedCardinalityFields.has(field)) return;
-  warnedCardinalityFields.add(field);
-  console.warn(
-    `[noy-db] .groupBy("${field}") produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
-  );
-}
-var GroupedQuery = class {
-  constructor(executeRecords, field, upstreams, dictLabelResolver) {
-    this.executeRecords = executeRecords;
-    this.field = field;
-    this.upstreams = upstreams;
-    this.dictLabelResolver = dictLabelResolver;
-  }
-  executeRecords;
-  field;
-  upstreams;
-  dictLabelResolver;
-  /**
-   * Build a grouped aggregation. Returns a `GroupedAggregation`
-   * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape
-   * as the non-grouped `.aggregate()` wrapper, just with an array
-   * result (one row per bucket) instead of a single reduced object.
-   */
-  aggregate(spec) {
-    return new GroupedAggregation(
-      this.executeRecords,
-      this.field,
-      spec,
-      this.upstreams,
-      this.dictLabelResolver
-    );
-  }
-};
-function groupAndReduce(records, field, spec) {
-  const buckets = /* @__PURE__ */ new Map();
-  for (const record of records) {
-    const key = readPath(record, field);
-    let bucket = buckets.get(key);
-    if (bucket === void 0) {
-      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {
-        throw new GroupCardinalityError(
-          field,
-          buckets.size + 1,
-          GROUPBY_MAX_CARDINALITY
-        );
-      }
-      bucket = [];
-      buckets.set(key, bucket);
-    }
-    bucket.push(record);
-  }
-  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
-    warnCardinalityApproaching(field, buckets.size);
-  }
-  const keys = Object.keys(spec);
-  const out = [];
-  for (const [groupKey, bucketRecords] of buckets) {
-    const state = {};
-    for (const key of keys) {
-      state[key] = spec[key].init();
-    }
-    for (const record of bucketRecords) {
-      for (const key of keys) {
-        state[key] = spec[key].step(state[key], record);
-      }
-    }
-    const row = { [field]: groupKey };
-    for (const key of keys) {
-      row[key] = spec[key].finalize(state[key]);
-    }
-    out.push(row);
-  }
-  return out;
-}
-var GroupedAggregation = class {
-  constructor(executeRecords, field, spec, upstreams, dictLabelResolver) {
-    this.executeRecords = executeRecords;
-    this.field = field;
-    this.spec = spec;
-    this.upstreams = upstreams;
-    this.dictLabelResolver = dictLabelResolver;
-  }
-  executeRecords;
-  field;
-  spec;
-  upstreams;
-  dictLabelResolver;
-  /** Execute the query, group, reduce, and return an array of rows. */
-  run() {
-    return groupAndReduce(this.executeRecords(), this.field, this.spec);
-  }
-  /**
-   * Execute the query, group, reduce, and resolve `<field>Label` for
-   * each result row when the grouping field is a `dictKey` and a
-   * `locale` is provided. Returns `R[]` synchronously when
-   * no locale is specified (identical to `.run()`).
-   *
-   * The `<field>Label` field is appended to each row. Rows whose group
-   * key has no dictionary entry get `<field>Label: undefined`.
-   */
-  async runAsync(opts) {
-    const rows = groupAndReduce(this.executeRecords(), this.field, this.spec);
-    if (!opts?.locale || !this.dictLabelResolver) return rows;
-    const resolve = this.dictLabelResolver;
-    const locale = opts.locale;
-    const fallback = opts.fallback;
-    const labelKey = `${this.field}Label`;
-    return Promise.all(
-      rows.map(async (row) => {
-        const key = row[this.field];
-        if (typeof key !== "string") return row;
-        const label = await resolve(key, locale, fallback);
-        return { ...row, [labelKey]: label };
-      })
-    );
-  }
-  /**
-   * Build a reactive `LiveAggregation<R[]>` that re-runs the full
-   * group-and-reduce pipeline whenever any upstream source notifies
-   * of a change. Same error-isolation and idempotent-stop contract
-   * as `Aggregation.live()` — the implementation delegates to the
-   * same `LiveAggregationImpl` class by threading a fresh
-   * recompute closure through the existing constructor.
-   *
-   * uses naive full re-run on every change. Incremental
-   * per-bucket maintenance (apply `step` on inserted records,
-   * `remove` on deleted records, route by bucket key) is a future
-   * optimization — the reducer protocol admits it, but wiring
-   * delta-aware source subscriptions is a separate PR.
-   *
-   * Always call `live.stop()` when finished.
-   */
-  live() {
-    const recompute = () => groupAndReduce(this.executeRecords(), this.field, this.spec);
-    return buildLiveAggregation(recompute, this.upstreams);
-  }
-};
+// src/query/index.ts
+init_aggregation();
+init_groupby();
 
 // src/query/scan-builder.ts
+init_predicate();
 init_errors();
 var DEFAULT_SCAN_PAGE_SIZE = 100;
 var ScanBuilder = class _ScanBuilder {
@@ -9821,8 +10710,8 @@ function coerceRefKey2(value) {
 
 // src/indexing/persisted-indexes.ts
 var IDX_PREFIX = "_idx/";
-function encodeIdxId(field, recordId) {
-  return `${IDX_PREFIX}${field}/${recordId}`;
+function encodeIdxId(field, recordId2) {
+  return `${IDX_PREFIX}${field}/${recordId2}`;
 }
 function decodeIdxId(id) {
   if (!id.startsWith(IDX_PREFIX)) return null;
@@ -9830,12 +10719,13 @@ function decodeIdxId(id) {
   const firstSlash = rest.indexOf("/");
   if (firstSlash <= 0) return null;
   const field = rest.slice(0, firstSlash);
-  const recordId = rest.slice(firstSlash + 1);
-  if (recordId.length === 0) return null;
-  return { field, recordId };
+  const recordId2 = rest.slice(firstSlash + 1);
+  if (recordId2.length === 0) return null;
+  return { field, recordId: recordId2 };
 }
 
 // src/indexing/lazy-builder.ts
+init_predicate();
 init_errors();
 var EMPTY_PLAN2 = {
   clauses: [],
@@ -10305,6 +11195,7 @@ var TxCollection = class {
       record
     };
     if (options?.expectedVersion !== void 0) op.expectedVersion = options.expectedVersion;
+    if (options?.reason !== void 0) op.reason = options.reason;
     this._ctx._ops.push(op);
   }
   /**
@@ -10373,7 +11264,7 @@ async function runTransaction(db, fn, options) {
         const prior = priorEnvelopes.get(key) ?? null;
         ctx._executed.push({ op, priorEnvelope: prior });
         if (op.type === "put") {
-          await coll.put(op.id, op.record);
+          await coll.put(op.id, op.record, op.reason !== void 0 ? { reason: op.reason } : void 0);
         } else {
           await coll.delete(op.id);
         }
@@ -10515,8 +11406,8 @@ async function resolveStaleOnRead(accessor, outputCollection, id) {
     for (const key of Object.keys(spec.outputs)) {
       const out = result.outputs[key];
       if (!out) continue;
-      if (!out.ok) {
-        const err = out.error ?? new Error(`derivation output "${key}" failed`);
+      if (out.kind === "failed") {
+        const err = out.error;
         if (spec.strict) {
           throw err;
         }
@@ -10526,6 +11417,12 @@ async function resolveStaleOnRead(accessor, outputCollection, id) {
         );
         continue;
       }
+      if (out.kind === "array") {
+        console.warn(
+          `[derivation] unexpected array-shape output "${key}" in lazy resolve path; array-shape derivations require lifecycle: "eager" (#200 slice 1).`
+        );
+        continue;
+      }
       const outSpec = spec.outputs[key];
       if (!outSpec) continue;
       const outputColl = accessor.getCollection(outSpec.collection);
@@ -11054,8 +11951,18 @@ var Collection = class {
     if (opts?.pollIntervalMs !== void 0) presenceOpts.pollIntervalMs = opts.pollIntervalMs;
     return this.syncStrategy.buildPresence(presenceOpts);
   }
-  /** Create or update a record. */
-  async put(id, record) {
+  /**
+   * Create or update a record.
+   *
+   * @param id      Record identifier.
+   * @param record  The record body (validated by the collection's schema
+   *                if one was attached at `vault.collection(...)` time).
+   * @param options Optional metadata for audit + import workflows.
+   *                `reason` is stamped onto the resulting ledger entry
+   *                (see #1) so audit consumers can filter via
+   *                `entries.filter(e => e.reason?.startsWith('import:'))`.
+   */
+  async put(id, record, options) {
     if (!hasWritePermission(this.keyring, this.name)) {
       throw new ReadOnlyError();
     }
@@ -11199,6 +12106,7 @@ var Collection = class {
           payloadHash: await this.historyStrategy.envelopePayloadHash(envelope2)
         };
         if (existingResolved) appendInput.delta = this.historyStrategy.computePatch(resolvedRecord, existingResolved.record);
+        if (options?.reason !== void 0) appendInput.reason = options.reason;
         await this.ledger.append(appendInput);
       }
       if (this.lazy && this.lru) {
@@ -11264,6 +12172,7 @@ var Collection = class {
       if (existing) {
         appendInput.delta = this.historyStrategy.computePatch(record, existing.record);
       }
+      if (options?.reason !== void 0) appendInput.reason = options.reason;
       await this.ledger.append(appendInput);
     }
     if (this.lazy && this.lru) {
@@ -11357,8 +12266,8 @@ var Collection = class {
         for (const key of Object.keys(spec.outputs)) {
           const out = result.outputs[key];
           if (!out) continue;
-          if (!out.ok) {
-            const err = out.error ?? new Error(`derivation output "${key}" failed`);
+          if (out.kind === "failed") {
+            const err = out.error;
             if (spec.strict) throw err;
             console.warn(`[derivation] output "${key}" for source "${spec.source}" id="${id}" failed:`, err);
             continue;
@@ -11367,6 +12276,46 @@ var Collection = class {
           if (!outSpec) continue;
           const outputCollection = this.derivationSource.getCollection(outSpec.collection);
           const txCtx = this.derivationSource.getActiveTxContext();
+          if (out.kind === "array") {
+            const { loadFanoutSidecar: loadFanoutSidecar2, saveFanoutSidecar: saveFanoutSidecar2 } = await Promise.resolve().then(() => (init_fanout_sidecar(), fanout_sidecar_exports));
+            const prior = await loadFanoutSidecar2(
+              this.adapter,
+              this.vault,
+              spec.source,
+              id,
+              key
+            );
+            const prevKeys = new Set(prior?.keys ?? []);
+            const newKeysList = out.entries.map((e) => e.key);
+            const newKeysSet = new Set(newKeysList);
+            for (const k of prevKeys) {
+              if (newKeysSet.has(k)) continue;
+              await outputCollection._internalDelete(k, txCtx);
+            }
+            for (const entry of out.entries) {
+              if (txCtx !== null) {
+                const priorEnvelope = await this.adapter.get(this.vault, outSpec.collection, entry.key);
+                txCtx._executed.push({
+                  op: {
+                    type: "put",
+                    vaultName: this.vault,
+                    collectionName: outSpec.collection,
+                    id: entry.key
+                  },
+                  priorEnvelope
+                });
+              }
+              await outputCollection.put(entry.key, entry.value);
+            }
+            await saveFanoutSidecar2(this.adapter, this.vault, {
+              source: spec.source,
+              sourceId: id,
+              outputKey: key,
+              outputCollection: outSpec.collection,
+              keys: newKeysList
+            });
+            continue;
+          }
           if (out.skipped === true) {
             await outputCollection._internalDelete(id, txCtx);
             continue;
@@ -11557,6 +12506,87 @@ var Collection = class {
       action: "delete"
     });
     await this.onAccess?.("delete", id);
+    if (!internal) {
+      await this.dispatchMaterializedViewsOnDelete(id);
+      await this.dispatchArrayDerivationsOnDelete(id);
+    }
+  }
+  /**
+   * Cascade deletes of array-shape derived rows when a source row is
+   * deleted (#200). Reads each registered strategy's fanout sidecar
+   * for this source id, deletes every listed derived row, then
+   * deletes the sidecar itself.
+   *
+   * Record-shape derivations are skipped — see _doDelete's comment
+   * for why the asymmetry is correct.
+   *
+   * @internal
+   */
+  async dispatchArrayDerivationsOnDelete(id) {
+    if (this.derivationSource === void 0) return;
+    const registry = this.derivationSource.registry();
+    const strategies = registry.strategiesForSource(this.name);
+    if (strategies.length === 0) return;
+    let helpers = null;
+    const txCtx = this.derivationSource.getActiveTxContext();
+    for (const { spec } of strategies) {
+      for (const [outputKey, outSpec] of Object.entries(spec.outputs)) {
+        if (outSpec.shape !== "array") continue;
+        if (helpers === null) {
+          helpers = await Promise.resolve().then(() => (init_fanout_sidecar(), fanout_sidecar_exports));
+        }
+        const sidecar = await helpers.loadFanoutSidecar(
+          this.adapter,
+          this.vault,
+          spec.source,
+          id,
+          outputKey
+        );
+        if (!sidecar) continue;
+        const outputCollection = this.derivationSource.getCollection(outSpec.collection);
+        for (const derivedId of sidecar.keys) {
+          await outputCollection._internalDelete(derivedId, txCtx);
+        }
+        await helpers.deleteFanoutSidecar(this.adapter, this.vault, spec.source, id, outputKey);
+      }
+    }
+  }
+  /**
+   * Mirror of {@link dispatchMaterializedViews} for the delete path
+   * (#181). No record content is available (it's gone), so the
+   * `_materializedFrom` skip used by the put-side dispatch doesn't
+   * apply here — instead, the recursion guard is the `internal` gate
+   * at the `_doDelete` call site above.
+   *
+   * @internal
+   */
+  async dispatchMaterializedViewsOnDelete(id) {
+    void id;
+    if (this.materializedViewSource === void 0) return;
+    const registry = this.materializedViewSource.registry();
+    const mvs = registry.mvsForSource(this.name);
+    if (mvs.length === 0) return;
+    let executor = null;
+    let staleHelpers = null;
+    for (const reg of mvs) {
+      const mode = reg.spec.refresh;
+      if (mode === "eager") {
+        if (executor === null) {
+          ;
+          ({ MaterializedViewExecutor: executor } = await Promise.resolve().then(() => (init_executor3(), executor_exports3)));
+        }
+        await executor.refresh(reg, {
+          getCollection: (name) => this.materializedViewSource.getCollection(name),
+          getActiveTxContext: () => this.materializedViewSource.getActiveTxContext(),
+          getQueryContext: () => this.materializedViewSource.getQueryContext()
+        });
+      } else if (mode === "lazy") {
+        if (staleHelpers === null) {
+          staleHelpers = await Promise.resolve().then(() => (init_stale(), stale_exports));
+        }
+        staleHelpers.markMVStale(registry, reg.spec.name);
+      }
+    }
   }
   /**
    * List all records in the collection.
@@ -12220,11 +13250,11 @@ var Collection = class {
       }
     }
     persisted.clear();
-    for (const recordId of canonicalIds) {
-      const envelope = await this.adapter.get(this.vault, this.name, recordId);
+    for (const recordId2 of canonicalIds) {
+      const envelope = await this.adapter.get(this.vault, this.name, recordId2);
       if (!envelope) continue;
       const record = await this.decryptRecord(envelope, { skipValidation: true });
-      await this.maintainPersistedIndexesOnPut(recordId, record, null, envelope._v);
+      await this.maintainPersistedIndexesOnPut(recordId2, record, null, envelope._v);
     }
     this.persistedIndexesLoaded = true;
   }
@@ -13771,13 +14801,13 @@ async function runCompaction(ctx, options = {}) {
     collectionsWithPolicy += 1;
     byCollection[collectionName] = { records: 0, evicted: 0 };
     const ids = await ctx.listRecords(collectionName);
-    for (const recordId of ids) {
+    for (const recordId2 of ids) {
       if (evicted >= maxEvictions) break outer;
-      const record = await ctx.getRecord(collectionName, recordId).catch(() => null);
+      const record = await ctx.getRecord(collectionName, recordId2).catch(() => null);
       if (record === null) continue;
       records += 1;
       byCollection[collectionName].records += 1;
-      const slots = await ctx.listSlots(collectionName, recordId).catch(() => []);
+      const slots = await ctx.listSlots(collectionName, recordId2).catch(() => []);
       for (const slot of slots) {
         if (evicted >= maxEvictions) break outer;
         const policy = config[slot.name];
@@ -13785,11 +14815,11 @@ async function runCompaction(ctx, options = {}) {
         const reason = evaluatePolicy(policy, record, slot, now);
         if (!reason) continue;
         if (!dryRun) {
-          await ctx.deleteSlot(collectionName, recordId, slot.name);
+          await ctx.deleteSlot(collectionName, recordId2, slot.name);
           await writeAuditEntry(ctx, {
-            id: generateEvictionId(collectionName, recordId, slot.name),
+            id: generateEvictionId(collectionName, recordId2, slot.name),
             collection: collectionName,
-            recordId,
+            recordId: recordId2,
             slotName: slot.name,
             blobHash: slot.eTag,
             reason,
@@ -13833,11 +14863,11 @@ function evaluatePolicy(policy, record, slot, now) {
   if (predicateTriggered) return "predicate";
   return null;
 }
-function generateEvictionId(collection, recordId, slotName) {
+function generateEvictionId(collection, recordId2, slotName) {
   const rand = globalThis.crypto.getRandomValues(new Uint8Array(8));
   let suffix = "";
   for (const b of rand) suffix += b.toString(16).padStart(2, "0");
-  return `${collection}__${recordId}__${slotName}__${suffix}`;
+  return `${collection}__${recordId2}__${slotName}__${suffix}`;
 }
 async function writeAuditEntry(ctx, entry) {
   const json = JSON.stringify(entry);
@@ -13888,7 +14918,7 @@ async function deriveMagicLinkContentKey(serverSecret, token, vault) {
     ["encrypt", "decrypt"]
   );
 }
-async function writeMagicLinkGrant(store, vault, grantor, contentKey, grantKek, recordId, opts) {
+async function writeMagicLinkGrant(store, vault, grantor, contentKey, grantKek, recordId2, opts) {
   const collectionName = opts.collection ?? null;
   const sourceKey = collectionName ? dekKey(collectionName, opts.tier) : `__any#${opts.tier}`;
   const sourceDek = grantor.deks.get(sourceKey);
@@ -13901,7 +14931,7 @@ async function writeMagicLinkGrant(store, vault, grantor, contentKey, grantKek,
   const until = typeof opts.until === "string" ? opts.until : opts.until.toISOString();
   const createdAt = (/* @__PURE__ */ new Date()).toISOString();
   const payload = {
-    id: recordId,
+    id: recordId2,
     toUser: opts.toUser,
     fromUser: grantor.userId,
     tier: opts.tier,
@@ -13921,11 +14951,11 @@ async function writeMagicLinkGrant(store, vault, grantor, contentKey, grantKek,
     _data: data,
     _by: grantor.userId
   };
-  await store.put(vault, MAGIC_LINK_GRANTS_COLLECTION, recordId, envelope);
-  return { recordId, payload };
+  await store.put(vault, MAGIC_LINK_GRANTS_COLLECTION, recordId2, envelope);
+  return { recordId: recordId2, payload };
 }
-async function readMagicLinkGrantRecord(store, vault, contentKey, recordId) {
-  const env = await store.get(vault, MAGIC_LINK_GRANTS_COLLECTION, recordId);
+async function readMagicLinkGrantRecord(store, vault, contentKey, recordId2) {
+  const env = await store.get(vault, MAGIC_LINK_GRANTS_COLLECTION, recordId2);
   if (!env) return null;
   try {
     const json = await decrypt(env._iv, env._data, contentKey);
@@ -13962,6 +14992,248 @@ function isMagicLinkGrantExpired(payload, now = /* @__PURE__ */ new Date()) {
   return payload.until <= now.toISOString();
 }
 
+// src/introspection/fields.ts
+function jsonSchemaType(node) {
+  if (Array.isArray(node.type)) {
+    const non = node.type.filter((t) => t !== "null");
+    return non[0] ?? "opaque";
+  }
+  if (node.enum && Array.isArray(node.enum)) return "enum";
+  if (typeof node.type === "string") return node.type;
+  return "opaque";
+}
+function constraintsFor(node) {
+  const out = {};
+  if (node.enum) out.values = node.enum;
+  if (node.minLength !== void 0) out.minLength = node.minLength;
+  if (node.maxLength !== void 0) out.maxLength = node.maxLength;
+  if (node.pattern !== void 0) out.pattern = node.pattern;
+  if (node.format !== void 0) out.format = node.format;
+  if (node.minimum !== void 0) out.minimum = node.minimum;
+  if (node.maximum !== void 0) out.maximum = node.maximum;
+  if (node.exclusiveMinimum !== void 0) out.gt = node.exclusiveMinimum;
+  if (node.exclusiveMaximum !== void 0) out.lt = node.exclusiveMaximum;
+  return Object.keys(out).length === 0 ? void 0 : out;
+}
+function jsonSchemaToFields(jsonSchema, source, refs) {
+  if (!jsonSchema || typeof jsonSchema !== "object") return {};
+  const root = jsonSchema;
+  if (!root.properties || typeof root.properties !== "object") return {};
+  const required = new Set(Array.isArray(root.required) ? root.required : []);
+  const out = {};
+  for (const [name, node] of Object.entries(root.properties)) {
+    const descriptor = {
+      type: jsonSchemaType(node),
+      source,
+      ...required.has(name) ? {} : { optional: true },
+      ...refs?.[name] ? { references: `${refs[name].target}.id` } : {}
+    };
+    const constraints = constraintsFor(node);
+    if (constraints) descriptor.constraints = constraints;
+    out[name] = descriptor;
+  }
+  return out;
+}
+
+// src/introspection/walk.ts
+var INTERNAL_PREFIX = "_";
+var KNOWN_INTERNAL_NAMES = ["_keyring", "_ledger", "_meta", "_schemas", "_deltas"];
+async function dumpVaultSchema(vault, opts) {
+  const state = vault._introspectState();
+  const sampleSize = opts.sampleSize ?? 50;
+  const withStats = opts.withStats === true;
+  const cacheNames = [...state.collectionCache.keys()];
+  const storageNames = (await safeListAllCollections(state.adapter, state.name)).filter((n) => !n.startsWith(INTERNAL_PREFIX));
+  const allNames = Array.from(/* @__PURE__ */ new Set([...cacheNames, ...storageNames])).sort();
+  const collections = {};
+  for (const name of allNames) {
+    collections[name] = await describeCollection(state, name, sampleSize, withStats);
+  }
+  const materializedViews = describeMVs(state.mvRegistry);
+  const overlayViews = describeOverlays(state.overlayRegistry);
+  const derivations = describeDerivations(state.derivationRegistry);
+  let internal;
+  if (withStats) {
+    internal = {};
+    for (const name of KNOWN_INTERNAL_NAMES) {
+      const stats = await statsForCollection(state.adapter, state.name, name);
+      if (stats.records > 0) {
+        internal[name] = { records: stats.records, bytes: stats.bytes };
+      }
+    }
+  }
+  const snap = {
+    _noydb_snapshot: 1,
+    vault: state.name,
+    emittedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    subsystems: state.subsystems,
+    collections,
+    materializedViews,
+    overlayViews,
+    derivations,
+    ...internal !== void 0 ? { internal } : {}
+  };
+  return snap;
+}
+async function safeListAllCollections(adapter, vault) {
+  try {
+    const snap = await adapter.loadAll(vault);
+    return Object.keys(snap);
+  } catch {
+    return [];
+  }
+}
+async function describeCollection(state, collectionName, sampleSize, withStats) {
+  let fields = {};
+  let validator;
+  const refsRaw = state.refRegistry.getOutbound(collectionName);
+  const refs = {};
+  for (const [name, desc] of Object.entries(refsRaw)) {
+    refs[name] = { target: desc.target, mode: desc.mode };
+  }
+  try {
+    const dek = await state.getDEK(collectionName);
+    const persisted = await loadPersistedSchema(state.adapter, state.name, collectionName, dek);
+    if (persisted) {
+      validator = { kind: persisted.kind, source: "persisted" };
+      if (persisted.jsonSchema) {
+        fields = jsonSchemaToFields(persisted.jsonSchema, "persisted", refsRaw);
+      }
+    }
+  } catch {
+  }
+  if (!validator) {
+    const coll = state.collectionCache.get(collectionName);
+    const schema = coll?.getSchema();
+    if (schema) {
+      try {
+        const derived = await derivePersistedSchema(schema);
+        validator = { kind: derived.kind, source: "live-validator" };
+        if (derived.jsonSchema) {
+          fields = jsonSchemaToFields(derived.jsonSchema, "live-validator", refsRaw);
+        }
+      } catch {
+      }
+    }
+  }
+  if (Object.keys(fields).length === 0 && sampleSize > 0) {
+  }
+  const descriptor = {
+    fields,
+    indexes: [],
+    refs,
+    ...validator ? { validator } : {}
+  };
+  if (withStats) {
+    const stats = await statsForCollection(state.adapter, state.name, collectionName);
+    descriptor.stats = stats;
+  }
+  return descriptor;
+}
+async function statsForCollection(adapter, vault, collection) {
+  const ids = await adapter.list(vault, collection);
+  if (ids.length === 0) {
+    return { records: 0, bytes: 0, bytesAvg: 0, bytesMin: 0, bytesMax: 0, oldest: "", newest: "" };
+  }
+  let total = 0;
+  let min2 = Number.POSITIVE_INFINITY;
+  let max2 = 0;
+  let oldest = "\uFFFF";
+  let newest = "";
+  for (const id of ids) {
+    const env = await adapter.get(vault, collection, id);
+    if (!env) continue;
+    const size = env._data.length;
+    total += size;
+    if (size < min2) min2 = size;
+    if (size > max2) max2 = size;
+    if (env._ts < oldest) oldest = env._ts;
+    if (env._ts > newest) newest = env._ts;
+  }
+  return {
+    records: ids.length,
+    bytes: total,
+    bytesAvg: Math.round(total / ids.length),
+    bytesMin: min2 === Number.POSITIVE_INFINITY ? 0 : min2,
+    bytesMax: max2,
+    oldest: oldest === "\uFFFF" ? "" : oldest,
+    newest
+  };
+}
+function describeMVs(registry) {
+  if (!registry || typeof registry !== "object") return {};
+  const items = listFromRegistry(registry);
+  const out = {};
+  for (const item of items) {
+    const reg = item;
+    const spec = reg.spec;
+    if (!spec?.name) continue;
+    const sources = spec.unionSources ? spec.unionSources.map((u) => u.collection) : reg.dependencies ? [...reg.dependencies].sort() : [];
+    const groupBy = spec.groupBy ? Array.isArray(spec.groupBy) ? [...spec.groupBy] : [spec.groupBy] : void 0;
+    const aggregate = spec.aggregate ? Object.fromEntries(
+      Object.entries(spec.aggregate).map(([k, v]) => [k, summariseAggregateOp(v)])
+    ) : void 0;
+    out[spec.name] = {
+      sources,
+      ...groupBy ? { groupBy } : {},
+      ...aggregate ? { aggregate } : {},
+      refresh: spec.refresh ?? "eager"
+    };
+  }
+  return out;
+}
+function describeOverlays(registry) {
+  if (!registry || typeof registry !== "object") return {};
+  const specs = listFromRegistry(registry);
+  const out = {};
+  for (const spec of specs) {
+    const s = spec;
+    if (!s.name || !s.base || !s.overlay) continue;
+    out[s.name] = { base: s.base, overlay: s.overlay };
+  }
+  return out;
+}
+function describeDerivations(registry) {
+  if (!registry || typeof registry !== "object") return {};
+  const specs = listFromRegistry(registry);
+  const out = {};
+  for (const spec of specs) {
+    const s = spec;
+    if (!s.name) continue;
+    out[s.name] = {
+      source: s.source ?? "",
+      outputs: s.outputs ?? []
+    };
+  }
+  return out;
+}
+function listFromRegistry(reg) {
+  for (const method of ["all", "list", "specs", "values"]) {
+    const fn = reg[method];
+    if (typeof fn === "function") {
+      try {
+        const out = fn.call(reg);
+        if (Array.isArray(out)) return out;
+        if (out && typeof out.values === "function") {
+          return [...out.values()];
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return [];
+}
+function summariseAggregateOp(value) {
+  if (value && typeof value === "object") {
+    const op = value.op ?? value.kind;
+    const field = value.field;
+    if (op && field) return `${op}(${field})`;
+    if (op) return op;
+  }
+  return String(value);
+}
+
 // src/vault.ts
 var Vault = class {
   adapter;
@@ -14085,6 +15357,16 @@ var Vault = class {
    * docstring.
    */
   ledgerStore = null;
+  /**
+   * Background writes for persisted-schema envelopes (#schema-dump v0
+   * slice 1). One promise per `collection({ persistJsonSchema: true })`
+   * registration that actually fired a derive call. Fire-and-forget
+   * from the collection factory; tests await
+   * {@link _drainPendingSchemaWrites} before asserting on storage.
+   * Production code does not need to drain — the writes are
+   * idempotent fingerprints, not correctness invariants.
+   */
+  _pendingSchemaWrites = [];
   /**
    * Per-vault foreign-key reference registry. Collections
    * register their `refs` option here on construction; the
@@ -14364,9 +15646,39 @@ var Vault = class {
       }
       coll = new Collection(collOpts);
       this.collectionCache.set(collectionName, coll);
+      if (options?.persistJsonSchema === true && options.schema !== void 0) {
+        const validator = options.schema;
+        const work = (async () => {
+          try {
+            const dek = await this.getDEK(collectionName);
+            await persistSchemaIfNeeded({
+              store: this.adapter,
+              vault: this.name,
+              collectionName,
+              validator,
+              dek
+            });
+          } catch (err) {
+            console.warn(
+              `[noy-db] persisted-schema write failed for "${collectionName}": ` + (err instanceof Error ? err.message : String(err))
+            );
+          }
+        })();
+        this._pendingSchemaWrites.push(work);
+      }
     }
     return coll;
   }
+  /**
+   * Await all background persisted-schema writes triggered by
+   * `collection({ persistJsonSchema: true })` calls on this vault.
+   * Used in tests; production code does not need to call this.
+   */
+  async _drainPendingSchemaWrites() {
+    const pending = this._pendingSchemaWrites;
+    this._pendingSchemaWrites = [];
+    await Promise.allSettled(pending);
+  }
   /**
    * Validate i18nText fields on a `put()`. Called by Collection just
    * before the adapter write, after schema validation. Throws
@@ -14961,7 +16273,6 @@ var Vault = class {
    * accessor `_getReadOnlyFacade()` (called from the tx amendment
    * runner) stays synchronous.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async _initGuards(handles) {
     if (handles.length === 0) return;
     const [{ GuardRegistry: GuardRegistry2 }, { ReadOnlyVaultFacade: ReadOnlyVaultFacade2 }] = await Promise.all([
@@ -15134,17 +16445,41 @@ var Vault = class {
         let anyFailed = false;
         for (const key of Object.keys(spec.outputs)) {
           const out = result.outputs[key];
-          if (!out || !out.ok) {
+          if (!out) continue;
+          if (out.kind === "failed") {
             anyFailed = true;
             continue;
           }
           const outSpec = spec.outputs[key];
           if (!outSpec) continue;
+          const outputColl = this.collection(outSpec.collection);
+          if (out.kind === "array") {
+            const { loadFanoutSidecar: loadFanoutSidecar2, saveFanoutSidecar: saveFanoutSidecar2 } = await Promise.resolve().then(() => (init_fanout_sidecar(), fanout_sidecar_exports));
+            const prior = await loadFanoutSidecar2(this.adapter, this.name, spec.source, id, key);
+            const prevKeys = new Set(prior?.keys ?? []);
+            const newKeysList = out.entries.map((e) => e.key);
+            const newKeysSet = new Set(newKeysList);
+            for (const k of prevKeys) {
+              if (newKeysSet.has(k)) continue;
+              await outputColl._internalDelete(k);
+            }
+            for (const entry of out.entries) {
+              await outputColl.put(entry.key, entry.value);
+            }
+            await saveFanoutSidecar2(this.adapter, this.name, {
+              source: spec.source,
+              sourceId: id,
+              outputKey: key,
+              outputCollection: outSpec.collection,
+              keys: newKeysList
+            });
+            continue;
+          }
           if (out.skipped === true) {
-            await this.collection(outSpec.collection)._internalDelete(id);
+            await outputColl._internalDelete(id);
             continue;
           }
-          await this.collection(outSpec.collection).put(id, out.value);
+          await outputColl.put(id, out.value);
         }
         if (anyFailed) failed++;
         else derived++;
@@ -15296,7 +16631,7 @@ var Vault = class {
    *
    * @internal
    */
-  async _logConsent(op, collection, recordId) {
+  async _logConsent(op, collection, recordId2) {
     const ctx = this.consentContext;
     if (!ctx) return;
     await this.consentStrategy.write(
@@ -15309,7 +16644,7 @@ var Vault = class {
         consentHash: ctx.consentHash,
         op,
         collection,
-        recordId
+        recordId: recordId2
       },
       this.getDEK
     );
@@ -15492,14 +16827,14 @@ var Vault = class {
    * the HKDF derivation, record-id composition, and batch logic so the
    * grantor doesn't touch this method directly.
    */
-  async writeMagicLinkGrant(contentKey, grantKek, recordId, opts) {
+  async writeMagicLinkGrant(contentKey, grantKek, recordId2, opts) {
     return writeMagicLinkGrant(
       this.adapter,
       this.name,
       this.keyring,
       contentKey,
       grantKek,
-      recordId,
+      recordId2,
       opts
     );
   }
@@ -15690,6 +17025,54 @@ var Vault = class {
     const snapshot = await this.adapter.loadAll(this.name);
     return Object.keys(snapshot);
   }
+  /**
+   * Emit a structured introspection snapshot of this vault — vault name,
+   * subsystem opt-in matrix, collections + their fields, materialized
+   * views, overlay views, derivations. With `withStats: true`, walks
+   * every collection's envelopes to compute record counts, byte totals,
+   * and oldest/newest timestamps.
+   *
+   * Consumed by the `noydb describe` CLI to produce human-readable
+   * audit YAML/JSON from a `.noydb` bundle.
+   *
+   * Field provenance:
+   *   - `persisted`: read from `_schemas/<col>` envelope (Route B opt-in)
+   *   - `live-validator`: derived in-process from a Zod schema attached
+   *     to the live `Collection`
+   *   - `sampled`: inferred from decrypted records (deferred to a follow-up)
+   *   - `unknown`: no schema info available
+   *
+   * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+   */
+  async dumpSchema(opts = {}) {
+    return dumpVaultSchema(this, opts);
+  }
+  /**
+   * Internal accessor for {@link dumpVaultSchema}. Exposes the structural
+   * state the walker needs (collection cache, registries, ref registry,
+   * adapter) without widening the public Vault surface.
+   *
+   * @internal
+   */
+  _introspectState() {
+    return {
+      name: this.name,
+      adapter: this.adapter,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      collectionCache: this.collectionCache,
+      refRegistry: this.refRegistry,
+      getDEK: this.getDEK,
+      subsystems: {
+        guards: this.guardRegistry !== null,
+        derivations: this.derivationRegistry !== null,
+        materializedViews: this.materializedViewRegistry !== null,
+        overlayViews: this.overlayedViewRegistry !== null
+      },
+      mvRegistry: this.materializedViewRegistry,
+      overlayRegistry: this.overlayedViewRegistry,
+      derivationRegistry: this.derivationRegistry
+    };
+  }
   /**
    * Return the stable opaque bundle handle for this vault,
    * generating and persisting a fresh ULID on first call.
@@ -15790,7 +17173,7 @@ var Vault = class {
       }
     }
     const internalSnapshot = {};
-    for (const internalName of [LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION]) {
+    for (const internalName of [LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, SCHEMAS_COLLECTION]) {
       const ids = await this.adapter.list(this.name, internalName);
       if (ids.length === 0) continue;
       const records = {};
@@ -16362,6 +17745,10 @@ var PERSONAL_POLICY = Object.freeze({
       minTier: 1,
       enabled: true
     },
+    // rotate-recovery (#121): deliberate paper-sheet regeneration
+    // when the user remembers their passphrase. PERSONAL matches the
+    // pre-#121 low-level flow's bar — knowing the passphrase is enough.
+    "rotate-recovery": { minTier: 1 },
     "enroll-authenticator": { minTier: 1 },
     "remove-authenticator": { minTier: 1 },
     // update-authenticator: meta-only mutation (slot rename, label
@@ -16421,6 +17808,14 @@ var STRICT_POLICY = Object.freeze({
       minTier: 1,
       enabled: true
     },
+    // rotate-recovery (#121): STRICT requires an off-device factor —
+    // rotating recovery is an off-site-trust event; a stolen unlocked
+    // laptop must not be able to silently mint a new sheet for the
+    // attacker. Matches the `peer-recover-user` STRICT default.
+    "rotate-recovery": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp", "webauthn-roaming"] }]
+    },
     "enroll-authenticator": {
       minTier: 1,
       factors: [{ anyOf: ["totp", "email-otp"] }]
@@ -16609,6 +18004,14 @@ var Noydb = class {
    * `_meta/policy` load; replaced by `db.updatePolicy()`.
    */
   policyCache = /* @__PURE__ */ new Map();
+  /**
+   * One-shot bypass for the managed-mode strong-recovery check (#195).
+   * Set true by {@link openVaultAndEnrollRecovery} for the duration of
+   * the bootstrap window so the keyring can be created before the
+   * strong recovery is enrolled. Always cleared (try/finally).
+   * @internal
+   */
+  _skipNextManagedRecoveryCheck = false;
   /** Per-vault tier-3 (PIN / quick-resume) state — issue #11. */
   quickUnlock = new QuickUnlockStore();
   /**
@@ -17525,30 +18928,51 @@ var Noydb = class {
     });
   }
   /** Read or persist the vault policy at `_meta/policy` on first open. */
-  async bootstrapPolicy(vault) {
+  async bootstrapPolicy(vault, opts) {
     const onDisk = await loadVaultPolicy(this.options.store, vault);
     if (onDisk) {
       this.policyCache.set(vault, onDisk);
-      await this.assertRecoveryEnrolled(vault, onDisk);
+      await this.assertRecoveryEnrolled(vault, onDisk, opts);
       return;
     }
     const initial = this.options.policy ? mergePolicy(PERSONAL_POLICY, this.options.policy) : PERSONAL_POLICY;
     await saveVaultPolicy(this.options.store, vault, initial);
     this.policyCache.set(vault, initial);
-    await this.assertRecoveryEnrolled(vault, initial);
+    await this.assertRecoveryEnrolled(vault, initial, opts);
   }
   /**
-   * Throw {@link RecoveryNotEnrolledError} when the developer
-   * explicitly opts into strict mandatory-recovery enforcement
-   * (`createNoydb({ requireRecovery: true })`) and no recovery
-   * entries are persisted.
+   * Throw {@link RecoveryNotEnrolledError} or
+   * {@link ManagedRecoveryNotEnrolledError} when recovery enrollment
+   * is missing.
+   *
+   * Two enforcement modes:
+   *
+   * 1. **Managed-mode mandatory strong-recovery (#195).** When
+   *    `passphraseMode === 'managed'`, the vault MUST have at least
+   *    one **strong** recovery profile (Shamir today). Paper alone is
+   *    rejected because under managed mode the user has no memorized
+   *    passphrase, so losing the paper sheet = losing every record.
+   *    This check is unconditional — independent of `requireRecovery`
+   *    and the `recover-passphrase` gate.
+   *
+   * 2. **Opt-in strict mandatory-recovery.** When
+   *    `requireRecovery: true` is set on createNoydb (and the gate is
+   *    not explicitly disabled), require ANY recovery profile (paper
+   *    or shamir). This is the v0.x default-off behavior; v1.0 may
+   *    flip it default-on.
    *
-   * The default behavior is lenient — `recover-passphrase` is enabled
-   * in `PERSONAL_POLICY` but the hub does not block vault open on
-   * missing enrollment. v1.0 will flip the default to strict; for now,
-   * apps that want the spec-mandated check turn it on per-vault.
+   * The managed-mode check fires from {@link bootstrapPolicy} unless
+   * the `skipManagedCheck` flag is set (used by
+   * {@link openVaultAndEnrollRecovery} to allow atomic create-and-enroll).
    */
-  async assertRecoveryEnrolled(vault, policy) {
+  async assertRecoveryEnrolled(vault, policy, opts) {
+    const skipManaged = (opts?.skipManagedCheck ?? false) || this._skipNextManagedRecoveryCheck;
+    if (this.options.passphraseMode === "managed" && !skipManaged) {
+      const enrolled2 = await hasStrongRecoveryEnrolled(this.options.store, vault);
+      if (!enrolled2) {
+        throw new ManagedRecoveryNotEnrolledError(vault);
+      }
+    }
     if (this.options.requireRecovery !== true) return;
     const gate = policy.gates["recover-passphrase"];
     if (gate?.enabled === false) return;
@@ -17827,6 +19251,14 @@ var Noydb = class {
    * @throws `InvalidKeyError` when `oldPassphrase` is wrong.
    */
   async rotatePassphrase(vault, input, factors) {
+    if (this.options.passphraseMode === "managed") {
+      throw new PolicyDeniedError(
+        "rotate-passphrase",
+        "disabled",
+        { minTier: 1, enabled: false },
+        "Managed-passphrase mode (#14): the passphrase is hub-generated and sealed under the SealingKeyProvider \u2014 there is no plaintext to rotate. Use the recovery flow (follow-up issue) to mint a fresh sealed passphrase."
+      );
+    }
     await this.checkGate(vault, "rotate-passphrase", factors);
     const userId = this.options.user;
     const next = await rotatePassphrase(this.options.store, vault, userId, input);
@@ -17863,6 +19295,254 @@ var Noydb = class {
     await savePaperRecoveryEntries(this.options.store, vault, newEntries);
     return { newCodes: codes };
   }
+  /**
+   * Deliberate paper-recovery-code regeneration (#121). User knows their
+   * passphrase but wants a fresh sheet — they lost the printout or
+   * suspect compromise of the off-site copy.
+   *
+   * Symmetric to {@link rotatePassphrase} for the recovery profile:
+   * gated, audit-trackable, ergonomic. Replaces (not appends) the
+   * paper sheet under `_meta/recovery-paper` in a single envelope `put`.
+   *
+   * Gated by the `rotate-recovery` policy gate:
+   *   - PERSONAL_POLICY: `{ minTier: 1 }` — knowing the passphrase
+   *     suffices, matching the pre-#121 low-level flow's bar.
+   *   - STRICT_POLICY: `{ minTier: 1, factors: [{ anyOf: ['totp',
+   *     'email-otp', 'webauthn-roaming'] }] }` — rotation is an
+   *     off-site-trust event; require an off-device factor so a
+   *     stolen unlocked laptop cannot silently mint a sheet for the
+   *     attacker.
+   *
+   * Defaults `count` to the existing sheet size so consumers aren't
+   * surprised by a different code count. Explicit `count` overrides.
+   *
+   * @throws {@link RecoveryProfileNotImplementedError} when `profile`
+   *         is anything other than `'paper'` (v1 dispatch limit).
+   * @throws {@link PolicyDeniedError} when the gate denies (missing
+   *         factor, tier mismatch, ...).
+   * @throws on missing paper sheet — "nothing to rotate" surfaces as
+   *         an error rather than silently minting an entire new sheet.
+   *
+   * @example Default count + show-once UI
+   * ```ts
+   * const { newCodes } = await db.rotateRecovery('acme', { profile: 'paper' })
+   * showCodesToUser(newCodes)
+   * ```
+   *
+   * @example STRICT-policy site with TOTP factor proof
+   * ```ts
+   * await db.rotateRecovery(
+   *   'acme',
+   *   { profile: 'paper', count: 10 },
+   *   { factors: [{ kind: 'totp', proof: '123456' }] },
+   * )
+   * ```
+   */
+  async rotateRecovery(vault, options, factors) {
+    if (options.profile === "paper") {
+      return this.rotateRecoveryPaper(vault, options, factors);
+    }
+    if (options.profile === "shamir") {
+      return this.rotateRecoveryShamir(vault, options, factors);
+    }
+    throw new RecoveryProfileNotImplementedError(
+      options.profile,
+      "#196"
+    );
+  }
+  async rotateRecoveryPaper(vault, options, factors) {
+    await this.checkGate(vault, "rotate-recovery", factors);
+    const existing = await loadPaperRecoveryEntries(this.options.store, vault);
+    if (existing.length === 0) {
+      throw new Error(
+        `db.rotateRecovery: no recovery codes are enrolled for vault "${vault}". Call db.enrollRecovery({ profile: 'paper', entries }) first; rotateRecovery replaces an existing sheet rather than minting one from scratch.`
+      );
+    }
+    const keyring = await this.getKeyring(vault);
+    const codeGen = options.codeGenerator ?? generateULID;
+    const count2 = options.count ?? existing.length;
+    const codes = [];
+    const newEntries = [];
+    for (let i = 0; i < count2; i++) {
+      const rawCode = codeGen();
+      const entry = await mintPaperRecoveryEntry(keyring.deks, rawCode, generateULID());
+      codes.push(rawCode);
+      newEntries.push(entry);
+    }
+    await savePaperRecoveryEntries(this.options.store, vault, newEntries);
+    return { newCodes: codes, entryId: "paper-batch" };
+  }
+  async rotateRecoveryShamir(vault, options, factors) {
+    await this.checkGate(vault, "rotate-recovery", factors);
+    const existing = await loadShamirRecoveryEntries(this.options.store, vault);
+    if (existing.length === 0) {
+      throw new Error(
+        `db.rotateRecovery: no Shamir recovery entry is enrolled for vault "${vault}". Call db.enrollRecovery({ profile: 'shamir', k, n }) first; rotateRecovery replaces an existing entry rather than minting one from scratch.`
+      );
+    }
+    let targetEntryId;
+    if (options.entryId !== void 0) {
+      const found = existing.find((e) => e.entryId === options.entryId);
+      if (!found) {
+        throw new Error(
+          `db.rotateRecovery: no Shamir entry with entryId="${options.entryId}" found in vault "${vault}". Available: ${existing.map((e) => `"${e.entryId}"`).join(", ")}.`
+        );
+      }
+      targetEntryId = options.entryId;
+    } else {
+      if (existing.length > 1) {
+        throw new Error(
+          `db.rotateRecovery: vault "${vault}" has ${existing.length} Shamir entries enrolled (${existing.map((e) => `"${e.entryId}"`).join(", ")}). Pass \`entryId\` to disambiguate which one to rotate; ambiguous rotation would risk replacing the wrong entry.`
+        );
+      }
+      targetEntryId = existing[0].entryId;
+    }
+    const keyring = await this.getKeyring(vault);
+    const { entry, shareStrings } = await mintShamirRecoveryEntry(
+      keyring.deks,
+      targetEntryId,
+      options.k,
+      options.n,
+      options.label
+    );
+    const next = existing.filter((e) => e.entryId !== targetEntryId).concat(entry);
+    await saveShamirRecoveryEntries(this.options.store, vault, next);
+    return { newShares: shareStrings, entryId: targetEntryId };
+  }
+  /**
+   * **Atomic create-and-enroll for managed-mode vaults (#195).**
+   *
+   * Bootstraps a managed-mode vault and enrolls strong recovery in
+   * a single ceremony. Under `passphraseMode: 'managed'`, every
+   * `openVault` call requires a strong recovery profile (Shamir
+   * today) to be enrolled — otherwise it throws
+   * {@link ManagedRecoveryNotEnrolledError}. This method bypasses
+   * the check temporarily so the keyring can be created, enrolls
+   * the supplied recovery profile(s), then returns the vault.
+   *
+   * For Shamir enrollments, the show-once share strings come back
+   * in `recoveryEnrollments[i].shares`. The hub never retains them
+   * — the caller MUST display them to the user (once) before any
+   * subsequent operation.
+   *
+   * Paper alone is NOT a strong profile under managed mode; passing
+   * `{ profile: 'paper', ... }` without an accompanying shamir entry
+   * is rejected at validation time.
+   *
+   * ```ts
+   * const db = await createNoydb({
+   *   store, user: 'alice',
+   *   passphraseMode: 'managed',
+   *   sealingKey: macosKeychainSealingProvider({ ... }),
+   * })
+   *
+   * const { vault, recoveryEnrollments } = await db.openVaultAndEnrollRecovery('acme', {
+   *   recovery: [{ profile: 'shamir', k: 2, n: 3 }],
+   * })
+   * for (const r of recoveryEnrollments) {
+   *   if (r.shares) showSharesToUser(r.shares)  // ONCE
+   * }
+   * ```
+   *
+   * @throws ValidationError if recovery is empty, or contains no
+   *   strong profile under managed mode.
+   */
+  async openVaultAndEnrollRecovery(vault, opts) {
+    if (opts.recovery.length === 0) {
+      throw new ValidationError(
+        "openVaultAndEnrollRecovery: at least one recovery enrollment is required."
+      );
+    }
+    if (this.options.passphraseMode === "managed") {
+      const hasStrong = opts.recovery.some((r) => r.profile === "shamir");
+      if (!hasStrong) {
+        throw new ValidationError(
+          'openVaultAndEnrollRecovery: managed-mode vaults require at least one strong recovery profile in the `recovery` array. Paper alone is not strong under managed mode (no user passphrase to fall back on). Include { profile: "shamir", k, n } in `recovery`.'
+        );
+      }
+    }
+    this._skipNextManagedRecoveryCheck = true;
+    let vaultHandle;
+    try {
+      vaultHandle = await this.openVault(vault, opts.locale !== void 0 ? { locale: opts.locale } : void 0);
+    } finally {
+      this._skipNextManagedRecoveryCheck = false;
+    }
+    const recoveryEnrollments = [];
+    for (const enrollment of opts.recovery) {
+      recoveryEnrollments.push(await this.enrollRecovery(vault, enrollment));
+    }
+    if (this.options.passphraseMode === "managed") {
+      const policy = this.policyCache.get(vault);
+      if (policy) {
+        await this.assertRecoveryEnrolled(vault, policy);
+      }
+    }
+    return { vault: vaultHandle, recoveryEnrollments };
+  }
+  /**
+   * **Recovery flow under managed-passphrase mode (#195).**
+   *
+   * Replaces the sealed passphrase of a managed-mode vault with a
+   * fresh 256-bit random, sealed under the configured
+   * `SealingKeyProvider`. The user never sees the new passphrase.
+   *
+   * Internally:
+   *   1. Verify the recovery proof (Shamir today) and unwrap the
+   *      DEK set.
+   *   2. Mint a fresh 256-bit random as the new effective passphrase.
+   *   3. Rewrap the DEK set under a fresh KEK derived from the new
+   *      passphrase (via the existing `recoverPassphrase` path).
+   *   4. Seal the random bytes under the provider and overwrite
+   *      `_meta/sealed-passphrase`.
+   *   5. Drop the keyring cache so the next operation re-derives.
+   *
+   * The vault's strong-recovery enrollment is preserved across
+   * recovery (Shamir entries are not burned on use — see #196).
+   *
+   * @throws ValidationError if the Noydb instance is not in managed mode.
+   */
+  async recoverManagedPassphrase(vault, options) {
+    if (this.options.passphraseMode !== "managed") {
+      throw new ValidationError(
+        "recoverManagedPassphrase: this method only applies to vaults opened in managed-passphrase mode. For standard mode, use db.recoverPassphrase."
+      );
+    }
+    const provider = this.options.sealingKey;
+    if (!provider) {
+      throw new ValidationError(
+        'recoverManagedPassphrase: createNoydb({ passphraseMode: "managed" }) requires `sealingKey` to be supplied; without it the new sealed passphrase cannot be persisted.'
+      );
+    }
+    const randomBytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(randomBytes);
+    let binary = "";
+    for (let i = 0; i < randomBytes.length; i++) binary += String.fromCharCode(randomBytes[i]);
+    const newPassphrase = btoa(binary);
+    try {
+      const sealed = await provider.seal(randomBytes);
+      await recoverPassphrase(
+        this.options.store,
+        vault,
+        this.options.user,
+        {
+          newPassphrase,
+          recoveryProof: options.recoveryProof,
+          // The new passphrase IS 256 bits of random; policy gates on
+          // length/entropy don't apply.
+          allowWeakPassphrase: true,
+          ...options.passphrasePolicy !== void 0 ? { passphrasePolicy: options.passphrasePolicy } : {}
+        }
+      );
+      await saveSealedPassphrase(this.options.store, vault, {
+        providerId: provider.id,
+        sealed
+      });
+    } finally {
+      randomBytes.fill(0);
+    }
+    this.keyringCache.delete(vault);
+  }
   /**
    * Atomic peer-recovery — re-wraps an EXISTING user's keyring under
    * a fresh temp passphrase in a single store write. Closes #34's
@@ -17946,21 +19626,39 @@ var Noydb = class {
    * ```
    */
   async enrollRecovery(vault, enrollment) {
-    if (enrollment.profile !== "paper") {
-      throw new ValidationError(
-        `enrollRecovery: only 'paper' is implemented in v0.1.0-pre.5. Profile '${enrollment.profile}' is tracked under issue #10.`
+    if (enrollment.profile === "paper") {
+      const existing = await loadPaperRecoveryEntries(this.options.store, vault);
+      await savePaperRecoveryEntries(this.options.store, vault, [
+        ...existing,
+        ...enrollment.entries
+      ]);
+      return { entryId: "paper-batch" };
+    }
+    if (enrollment.profile === "shamir") {
+      const keyring = await this.getKeyring(vault);
+      const entryId = enrollment.entryId ?? generateULID();
+      const { entry, shareStrings } = await mintShamirRecoveryEntry(
+        keyring.deks,
+        entryId,
+        enrollment.k,
+        enrollment.n,
+        enrollment.label
       );
+      const existing = await loadShamirRecoveryEntries(this.options.store, vault);
+      const next = existing.filter((e) => e.entryId !== entryId).concat(entry);
+      await saveShamirRecoveryEntries(this.options.store, vault, next);
+      return { entryId, shares: shareStrings };
     }
-    const existing = await loadPaperRecoveryEntries(this.options.store, vault);
-    await savePaperRecoveryEntries(this.options.store, vault, [
-      ...existing,
-      ...enrollment.entries
-    ]);
+    throw new RecoveryProfileNotImplementedError(
+      enrollment.profile,
+      "#196"
+    );
   }
-  /** Read the persisted paper-recovery entries. Used by `describeAuthConfig` (#13). */
+  /** Read the persisted recovery entries (paper + Shamir). Used by `describeAuthConfig` (#13). */
   async listRecoveryEntries(vault) {
     const paper = await loadPaperRecoveryEntries(this.options.store, vault);
-    return { paper };
+    const shamir = await loadShamirRecoveryEntries(this.options.store, vault);
+    return { paper, shamir };
   }
   // ─── Tier-3 enroll / unlock (issue #11) ────────────────────────
   /**
@@ -18062,20 +19760,36 @@ var Noydb = class {
       this.keyringCache.set(vault, keyring2);
       return keyring2;
     }
-    if (!this.options.secret) {
+    let effectiveSecret;
+    if (this.options.passphraseMode === "managed") {
+      effectiveSecret = await resolveManagedSecret(
+        this.options.store,
+        vault,
+        this.options.sealingKey
+      );
+    } else {
+      effectiveSecret = this.options.secret;
+    }
+    if (!effectiveSecret) {
       throw new ValidationError("A secret (passphrase) or getKeyring callback is required when encryption is enabled");
     }
     let keyring;
     try {
-      keyring = await loadKeyring(this.options.store, vault, this.options.user, this.options.secret);
+      keyring = await loadKeyring(this.options.store, vault, this.options.user, effectiveSecret);
     } catch (err) {
       if (err instanceof NoAccessError) {
         keyring = await createOwnerKeyring(
           this.options.store,
           vault,
           this.options.user,
-          this.options.secret,
-          { validate: this.options.validatePassphrase === true }
+          effectiveSecret,
+          {
+            // Managed mode generates 256-bit base64 strings that don't satisfy
+            // the human-passphrase strength rules (no spaces, no "words").
+            // Skip validation in managed mode — the entropy floor is already
+            // 256 bits by construction.
+            validate: this.options.passphraseMode === "managed" ? false : this.options.validatePassphrase === true
+          }
         );
       } else if (err instanceof InvalidKeyError && this.options.onInvalidKey === "reset") {
         await this.options.store.delete(vault, "_keyring", this.options.user);
@@ -18083,8 +19797,10 @@ var Noydb = class {
           this.options.store,
           vault,
           this.options.user,
-          this.options.secret,
-          { validate: this.options.validatePassphrase === true }
+          effectiveSecret,
+          {
+            validate: this.options.passphraseMode === "managed" ? false : this.options.validatePassphrase === true
+          }
         );
       } else {
         throw err;
@@ -18096,10 +19812,28 @@ var Noydb = class {
 };
 async function createNoydb(options) {
   const encrypted = options.encrypt !== false;
+  const managed = options.passphraseMode === "managed";
   if (options.secret && options.getKeyring) {
     throw new ValidationError("Provide either `secret` or `getKeyring`, not both");
   }
-  if (encrypted && !options.secret && !options.getKeyring) {
+  if (managed) {
+    if (options.secret) {
+      throw new ValidationError(
+        '`passphraseMode: "managed"` is mutually exclusive with `secret` \u2014 managed mode generates the passphrase itself. Drop `secret`.'
+      );
+    }
+    if (options.getKeyring) {
+      throw new ValidationError(
+        '`passphraseMode: "managed"` is mutually exclusive with `getKeyring` \u2014 a custom unlock callback would bypass the sealing flow. Drop `getKeyring`.'
+      );
+    }
+    if (!options.sealingKey) {
+      throw new ValidationError(
+        '`passphraseMode: "managed"` requires `sealingKey: SealingKeyProvider` (see @noy-db/seal-macos-keychain / @noy-db/seal-aws-kms / etc.).'
+      );
+    }
+  }
+  if (encrypted && !managed && !options.secret && !options.getKeyring) {
     throw new ValidationError("A secret (passphrase) or getKeyring callback is required when encryption is enabled");
   }
   return new Noydb(options);
@@ -18900,6 +20634,28 @@ function withDerivation(spec) {
   if (typeof spec.derive !== "function") {
     throw new ValidationError("withDerivation: derive must be a function");
   }
+  const lifecycleMode = typeof spec.lifecycle === "string" ? spec.lifecycle : spec.lifecycle.mode;
+  for (const [outputKey, outputSpec] of Object.entries(spec.outputs)) {
+    if (outputSpec.shape === "array") {
+      if (lifecycleMode !== "eager") {
+        throw new ValidationError(
+          `withDerivation: shape 'array' supports lifecycle 'eager' only in this release (#200 slice 1). Output "${outputKey}" declared lifecycle '${lifecycleMode}'. Switch to \`lifecycle: "eager"\` or use shape: "record".`
+        );
+      }
+      if (typeof outputSpec.key !== "function") {
+        throw new ValidationError(
+          `withDerivation: shape 'array' output "${outputKey}" requires \`key: (out) => string\`.`
+        );
+      }
+      if (outputSpec.maxFanout !== void 0) {
+        if (!Number.isInteger(outputSpec.maxFanout) || outputSpec.maxFanout < 1) {
+          throw new ValidationError(
+            `withDerivation: maxFanout for output "${outputKey}" must be a positive integer (got ${String(outputSpec.maxFanout)}).`
+          );
+        }
+      }
+    }
+  }
   return {
     __noydb_strategy: "derivation",
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -18916,9 +20672,60 @@ function withMaterializedView(spec) {
   if (!spec.name || spec.name.length === 0) {
     throw new ValidationError("withMaterializedView: name is required");
   }
-  if (typeof spec.query !== "function") {
+  if (spec.query && spec.unionSources) {
+    throw new MaterializedViewConfigError(
+      "query and unionSources are mutually exclusive \u2014 pick one"
+    );
+  }
+  if (!spec.query && !spec.unionSources) {
+    throw new MaterializedViewConfigError(
+      "strategy must declare either query or unionSources"
+    );
+  }
+  if (spec.query !== void 0 && typeof spec.query !== "function") {
     throw new ValidationError("withMaterializedView: query must be a function returning a Query<T>");
   }
+  if (spec.unionSources) {
+    if (spec.unionSources.length < 2) {
+      throw new MaterializedViewConfigError(
+        "unionSources requires at least 2 source collections"
+      );
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const s of spec.unionSources) {
+      if (typeof s?.collection !== "string" || s.collection.length === 0) {
+        throw new MaterializedViewConfigError(
+          "each unionSources entry must declare a non-empty `collection` string"
+        );
+      }
+      if (typeof s.map !== "function") {
+        throw new MaterializedViewConfigError(
+          `unionSources entry for "${s.collection}" is missing a \`map\` function`
+        );
+      }
+      if (seen.has(s.collection)) {
+        throw new MaterializedViewConfigError(
+          `unionSources must reference distinct collections (duplicate: "${s.collection}")`
+        );
+      }
+      seen.add(s.collection);
+    }
+    if (Array.isArray(spec.groupBy) && spec.groupBy.length === 0) {
+      throw new MaterializedViewConfigError(
+        `withMaterializedView "${spec.name}": groupBy must not be an empty array \u2014 omit it or provide at least one field name`
+      );
+    }
+    if (spec.aggregate && !spec.groupBy) {
+      throw new MaterializedViewConfigError(
+        `withMaterializedView "${spec.name}": UNION strategy with aggregate requires groupBy \u2014 use groupBy to declare the bucketing keys, or remove aggregate for a pure dedup MV`
+      );
+    }
+    if (spec.predicates) {
+      throw new MaterializedViewConfigError(
+        `withMaterializedView "${spec.name}": predicates are not supported on UNION strategies \u2014 UNION mode does not use a Query<T> chain, so .wherePredicate() cannot fire. Use the query() form, or open an issue if per-arm predicates are needed`
+      );
+    }
+  }
   if (typeof spec.rowKey !== "function") {
     throw new ValidationError("withMaterializedView: rowKey is required (no default; see spec \xA7 Type surface)");
   }
@@ -19715,6 +21522,7 @@ function shortJSON(value) {
   BackupLedgerError,
   BlobSet,
   BundleIntegrityError,
+  BundleSealMismatchError,
   BundleVersionConflictError,
   CONSENT_AUDIT_COLLECTION,
   Collection,
@@ -19732,6 +21540,7 @@ function shortJSON(value) {
   DanglingReferenceError,
   DecryptionError,
   DelegationTargetMissingError,
+  DerivationCapExceededError,
   DerivationCycleError,
   DerivationDepthError,
   DerivationOutputShapeError,
@@ -19751,6 +21560,7 @@ function shortJSON(value) {
   GroupCardinalityError,
   GroupedAggregation,
   GroupedQuery,
+  GroupedQueryN,
   INDEXED_STORE_POLICY,
   ImportCapabilityError,
   IndexRequiredError,
@@ -19770,9 +21580,12 @@ function shortJSON(value) {
   MAGIC_LINK_GRANTS_COLLECTION,
   MAGIC_LINK_KEK_INFO_PREFIX,
   META_COLLECTION,
+  ManagedRecoveryNotEnrolledError,
+  MaterializedViewConfigError,
   MaterializedViewCycleError,
   MaterializedViewSourceUnknownError,
   MaterializedViewTooLargeError,
+  MemorySealingKeyProvider,
   MissingTranslationError,
   NOYDB_BACKUP_VERSION,
   NOYDB_BUNDLE_FORMAT_VERSION,
@@ -19814,6 +21627,8 @@ function shortJSON(value) {
   RefRegistry,
   RefScopeError,
   ReservedCollectionNameError,
+  SCHEMAS_COLLECTION,
+  SEALED_PASSPHRASE_RECORD_ID,
   STRICT_POLICY,
   SYNC_CREDENTIALS_COLLECTION,
   ScanBuilder,
@@ -19865,6 +21680,7 @@ function shortJSON(value) {
   createSession,
   createStore,
   credentialStatus,
+  decodeShareBase32,
   decryptBytes,
   decryptDeterministic,
   dekKey,
@@ -19872,6 +21688,7 @@ function shortJSON(value) {
   deleteUserEnvelope,
   deleteUserVisibility,
   deriveMagicLinkContentKey,
+  derivePersistedSchema,
   derivePresenceKey,
   describeAllUsersAuth,
   describeAuthConfig,
@@ -19886,6 +21703,7 @@ function shortJSON(value) {
   diffVault,
   effectiveClearance,
   enableDevUnlock,
+  encodeShareBase32,
   encryptBytes,
   encryptDeterministic,
   enrollAuthenticator,
@@ -19917,6 +21735,7 @@ function shortJSON(value) {
   isPublicEnvelope,
   isSessionAlive,
   isULID,
+  isZodSchema,
   issueDelegation,
   keyringRecoverPassphrase,
   keyringRotatePassphrase,
@@ -19928,7 +21747,10 @@ function shortJSON(value) {
   loadActiveDelegations,
   loadDevUnlock,
   loadPaperRecoveryEntries,
+  loadPersistedSchema,
   loadPublicEnvelope,
+  loadSealedPassphrase,
+  loadShamirRecoveryEntries,
   loadUserEnvelope,
   loadVaultPolicy,
   magicLinkGrantRecordId,
@@ -19937,11 +21759,14 @@ function shortJSON(value) {
   mergePolicy,
   min,
   mintPaperRecoveryEntry,
+  mintShamirRecoveryEntry,
   mintWrappedDeksBlob,
   paddedIndex,
   parseBytes,
   parseIndex,
+  parseSealedEnvelope,
   persistDirectoryConfig,
+  persistSchemaIfNeeded,
   persistUserVisibility,
   putCredential,
   readDirectoryConfig,
@@ -19969,13 +21794,17 @@ function shortJSON(value) {
   routeStore,
   runTransaction,
   savePaperRecoveryEntries,
+  savePersistedSchema,
   savePublicEnvelope,
+  saveSealedPassphrase,
+  saveShamirRecoveryEntries,
   saveUserEnvelope,
   saveVaultPolicy,
   sha256Hex,
   sum,
   unwrapDeksFromBlob,
   unwrapDeksFromPaperEntry,
+  unwrapDeksFromShamirEntry,
   unwrapMagicLinkGrant,
   validateI18nTextValue,
   validatePassphrase,