@noy-db/hub 0.2.0-pre.23 → 0.2.0-pre.25

package/dist/{chunk-P65YMN5V.js → chunk-56ENKU46.js}

@@ -1,16 +1,13 @@
-import {
-  STATE_VAULT_NAME
-} from "./chunk-ZC7J6ZYV.js";
 import {
   resolveSchema
 } from "./chunk-EMIGCR7X.js";
 import {
   TxContext,
   revertExecuted
-} from "./chunk-IY24WS2P.js";
+} from "./chunk-EJJTUDNI.js";
 import {
   OverlayedCollection
-} from "./chunk-MBXKRHSS.js";
+} from "./chunk-YYTM4U4J.js";
 import {
   NO_AGGREGATE,
   Query,
@@ -20,39 +17,39 @@ import {
   decodeMoneyFields,
   quantizeMoneyFields,
   validateMoneyFieldPaths
-} from "./chunk-NV4IHBZS.js";
+} from "./chunk-PS6PSEZL.js";
 import {
   EXPORT_AUDIT_COLLECTION,
   createExportBlobsHandle,
   runCompaction
-} from "./chunk-2XA2ZML4.js";
+} from "./chunk-ZCBJIDT4.js";
 import {
   LazyQuery,
   decodeIdxId,
   encodeIdxId
-} from "./chunk-3HNKR65T.js";
+} from "./chunk-H4XFA2LM.js";
 import {
   canonicalGroupKey
-} from "./chunk-JYNH4FIM.js";
+} from "./chunk-C7UIT5XY.js";
 import {
   readPath
-} from "./chunk-U2XSUCDF.js";
+} from "./chunk-3BANVNDH.js";
 import {
   SCHEMAS_COLLECTION,
   loadPersistedSchema,
   resolveManagedSecret,
   savePersistedSchema,
   saveSealedPassphrase
-} from "./chunk-C6W5KVDV.js";
+} from "./chunk-YP2AYE5W.js";
 import {
   writeNoydbBundle
-} from "./chunk-WE2BUQD2.js";
+} from "./chunk-N4EXCKWP.js";
 import {
   loadPublicEnvelope,
   readPublicEnvelope,
   savePublicEnvelope,
   validatePublicEnvelopeInput
-} from "./chunk-JOK73NDT.js";
+} from "./chunk-HUXDQIVU.js";
 import {
   buildTombstone,
   isTombstone,
@@ -61,19 +58,19 @@ import {
   rewrapBodyToDek,
   rotateRecordCek,
   sealRecordToHost
-} from "./chunk-BZW5IL43.js";
+} from "./chunk-Y5CTT6K5.js";
 import {
   PERIODS_COLLECTION
-} from "./chunk-I3IYTUUI.js";
+} from "./chunk-FCIZXX56.js";
 import {
   isDictCollectionName,
   isStaticDictDescriptor
-} from "./chunk-O5XKZCUD.js";
+} from "./chunk-JJKXJAH2.js";
 import {
   getAtPath,
   resolvePolicy,
   setAtPathInPlace
-} from "./chunk-TNH5SLCD.js";
+} from "./chunk-KD253AI5.js";
 import {
   ManagedRecoveryNotEnrolledError,
   PolicyDeniedError,
@@ -95,11 +92,11 @@ import {
   saveShamirRecoveryEntries,
   updateAuthenticator,
   writeMagicLinkGrant
-} from "./chunk-HYJMAV53.js";
+} from "./chunk-2RHBFCWQ.js";
 import {
   assertTierAccess,
   dekKey
-} from "./chunk-F5GWNSE2.js";
+} from "./chunk-J73KU4AE.js";
 import {
   USER_ENVELOPE_COLLECTION,
   assertKeyringOpenAllowed,
@@ -124,7 +121,7 @@ import {
   rotateKeys,
   saveUserEnvelope,
   updateKeyringIdentity
-} from "./chunk-FRRJIUSI.js";
+} from "./chunk-UNBX2HMA.js";
 import {
   INDEXED_STORE_POLICY
 } from "./chunk-2QR2PQTT.js";
@@ -134,7 +131,7 @@ import {
 import {
   LEDGER_COLLECTION,
   LEDGER_DELTAS_COLLECTION
-} from "./chunk-JDCPRJVS.js";
+} from "./chunk-EYZJULEN.js";
 import {
   sha256Hex as sha256Hex2
 } from "./chunk-PDVP3C2I.js";
@@ -146,19 +143,20 @@ import {
   readDottedPath,
   rebuildSubjectIndex,
   removeSubjectRef
-} from "./chunk-CQYEDODS.js";
+} from "./chunk-TSUICI5N.js";
 import {
   NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION
-} from "./chunk-TA6HPKWQ.js";
+} from "./chunk-LR7CODVN.js";
 import {
   decrypt,
   encrypt,
   encryptDeterministic,
   sha256Hex,
   unwrapCek,
-  wrapCek
-} from "./chunk-37VGJM3T.js";
+  wrapCek,
+  wrapKey
+} from "./chunk-7JSP3E67.js";
 import {
   AlreadyElevatedError,
   AttestationError,
@@ -184,7 +182,6 @@ import {
   QuiesceTimeoutError,
   ReadOnlyError,
   ReservedCollectionNameError,
-  ReservedVaultNameError,
   SchemaFenceError,
   SchemaValidationError,
   SequenceContentionError,
@@ -197,9 +194,8 @@ import {
   UniqueConstraintError,
   UnknownDictCodeError,
   UnsupportedIndexOptionError,
-  ValidationError,
-  VaultTemplateNotFoundError
-} from "./chunk-OTWT6BAJ.js";
+  ValidationError
+} from "./chunk-DDOYOMAD.js";
 
 // src/policy/storage.ts
 var META_COLLECTION = "_meta";
@@ -913,7 +909,7 @@ async function resolveStaleOnRead(accessor, outputCollection, id) {
     }
     const sourceWithId = { ...source, id };
     if (DerivationExecutor === null) {
-      ({ DerivationExecutor } = await import("./executor-4IEW4KG5.js"));
+      ({ DerivationExecutor } = await import("./executor-VEZUBJNQ.js"));
     }
     const ctx = { vault: accessor.getReadOnlyFacade() };
     const result = await DerivationExecutor.run(spec, sourceWithId, 0, strategyHash, ctx);
@@ -1159,6 +1155,13 @@ var Collection = class {
    * flag) still decrypts CEK records.
    */
   perRecordCek;
+  /**
+   * Per-record provenance opt-in (`provenance: true`). When set, `put()` calls
+   * that supply a `source` option stamp `_source`/`_sourceTs` onto the
+   * unencrypted envelope metadata. Off by default — zero cost for collections
+   * that don't need lineage tracking (FR-5, #445).
+   */
+  provenance;
   /**
    * Session-scoped `(id) → CEK` cache for this collection. Lets updates
    * reuse a record's stable CEK and lets repeated reads skip the AES-KW
@@ -1318,6 +1321,7 @@ var Collection = class {
     }
     this.perRecordCek = opts.perRecordKeys === true;
     this.cekCache = this.perRecordCek ? new Lru({ maxRecords: 4096 }) : null;
+    this.provenance = opts.provenance === true;
     if (opts.crdt && opts.onRegisterConflictResolver) {
       const crdtMode = opts.crdt;
       const crdtResolver = async (id, local, remote) => {
@@ -1462,7 +1466,7 @@ var Collection = class {
       }
     }
     if (this.materializedViewSource !== void 0) {
-      const { resolveStaleMVOnRead } = await import("./stale-CPESGAPL.js");
+      const { resolveStaleMVOnRead } = await import("./stale-KKCHF2VB.js");
       await resolveStaleMVOnRead(this.materializedViewSource, this.name);
     }
     let record;
@@ -1505,6 +1509,33 @@ var Collection = class {
     if (json === null) return null;
     return JSON.parse(json);
   }
+  /**
+   * Read a record's unencrypted envelope metadata (version, timestamps,
+   * provenance) without decrypting the body.
+   *
+   * Returns `null` when no envelope exists for `id` (record absent or never
+   * written). Only `_source`/`_sourceTs` fields are populated when the
+   * collection was opened with `provenance: true` AND the record was written
+   * with a `source` option — but this method works on any collection because
+   * it reads the raw envelope directly.
+   *
+   * @returns `{ version, timestamp, by?, source?, sourceTs? }` or `null`.
+   *
+   * @example
+   * const meta = await clients.getMetadata('c1')
+   * if (meta) console.log(meta.source, meta.timestamp)
+   */
+  async getMetadata(id) {
+    const env = await this.adapter.get(this.vault, this.name, id);
+    if (!env) return null;
+    return {
+      version: env._v,
+      timestamp: env._ts,
+      ...env._by !== void 0 ? { by: env._by } : {},
+      ...env._source !== void 0 ? { source: env._source } : {},
+      ...env._sourceTs !== void 0 ? { sourceTs: env._sourceTs } : {}
+    };
+  }
   /**
    * Return a presence handle for this collection.
    *
@@ -1542,6 +1573,14 @@ var Collection = class {
    *                `reason` is stamped onto the resulting ledger entry
    *                so audit consumers can filter via
    *                `entries.filter(e => e.reason?.startsWith('import:'))`.
+   *                `source` is an opaque source id (e.g. `'crm-sync'`, `'firm-A'`)
+   *                stamped onto the envelope as `_source`/`_sourceTs` when
+   *                the collection has `provenance: true`. Ignored otherwise
+   *                (zero cost). (FR-5, #445)
+   *                `sourceTs` is an optional ISO-8601 origin timestamp override;
+   *                when supplied together with `source` on a provenance collection,
+   *                replaces the machine-stamped `now()` so re-merges preserve the
+   *                ORIGIN refresh time across vaults. (FR-4)
    */
   async put(id, record, options) {
     await this.schemaUpdateGate?.assertWritable();
@@ -1573,6 +1612,20 @@ var Collection = class {
       if (busAfterPut) await this.subsystemBus.dispatch("afterPut", event);
     }
   }
+  /**
+   * Validate a record against this collection's schema WITHOUT writing it.
+   * Returns the (possibly coerced) record on success; throws
+   * {@link SchemaValidationError} (direction: `'input'`) on violation.
+   * A no-op pass-through when no schema is declared.
+   *
+   * Used by FR-8 migrate-then-merge to pre-validate all staged records
+   * before `mergeDecryptedRecords` writes anything — so a failed upgrade
+   * never half-writes the receiver.
+   */
+  async validateInput(record) {
+    if (this.schema === void 0) return record;
+    return validateSchemaInput(this.schema, record, `validateInput(${this.name})`);
+  }
   /** @internal — true when hooks should fire for this write (handlers exist, not re-entrant). */
   #hooksActive() {
     return this.writeHooks !== void 0 && this.writeHooks.hasHandlers && !this.writeHooks.suppressed;
@@ -1730,7 +1783,7 @@ var Collection = class {
       }
       const version2 = existingVersion + 1;
       const cek2 = this.perRecordCek ? await this.resolveRecordCek(id) : void 0;
-      const envelope2 = await this.encryptJsonString(JSON.stringify(crdtState), version2, cek2);
+      const envelope2 = await this.encryptJsonString(JSON.stringify(crdtState), version2, cek2, options?.source, options?.sourceTs);
       await this.adapter.put(this.vault, this.name, id, envelope2);
       const resolvedRecord = this.crdtStrategy.resolveCrdtSnapshot(crdtState);
       const existingResolvedRecord = existingEnvelope ? await this.decryptRecord(existingEnvelope, { skipValidation: true }) : null;
@@ -1809,7 +1862,7 @@ var Collection = class {
         });
       }
     }
-    const envelope = await this.encryptRecord(record, version, cek);
+    const envelope = await this.encryptRecord(record, version, cek, options?.source, options?.sourceTs);
     await this.adapter.put(this.vault, this.name, id, envelope);
     if (this.ledger) {
       const appendInput = {
@@ -1872,7 +1925,7 @@ var Collection = class {
       if (mode === "eager") {
         if (executor === null) {
           ;
-          ({ MaterializedViewExecutor: executor } = await import("./executor-KYJCJCIN.js"));
+          ({ MaterializedViewExecutor: executor } = await import("./executor-BIW4FT5R.js"));
         }
         await executor.refresh(reg, {
           getCollection: (name) => this.materializedViewSource.getCollection(name),
@@ -1881,7 +1934,7 @@ var Collection = class {
         });
       } else if (mode === "lazy") {
         if (staleHelpers === null) {
-          staleHelpers = await import("./stale-CPESGAPL.js");
+          staleHelpers = await import("./stale-KKCHF2VB.js");
         }
         staleHelpers.markMVStale(registry, reg.spec.name);
       }
@@ -2055,7 +2108,7 @@ var Collection = class {
         continue;
       }
       if (DerivationExecutor === null) {
-        ({ DerivationExecutor } = await import("./executor-4IEW4KG5.js"));
+        ({ DerivationExecutor } = await import("./executor-VEZUBJNQ.js"));
       }
       for (const run of runs) {
         const ctx = { vault: this.derivationSource.getReadOnlyFacade() };
@@ -2074,7 +2127,7 @@ var Collection = class {
           const outputCollection = this.derivationSource.getCollection(outSpec.collection);
           const txCtx = this.derivationSource.getActiveTxContext();
           if (out.kind === "array") {
-            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-YXNAEZ33.js");
+            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-ZQT4Y7PF.js");
             const prior = await loadFanoutSidecar(
               this.adapter,
               this.vault,
@@ -2102,7 +2155,7 @@ var Collection = class {
                   priorEnvelope
                 });
               }
-              await outputCollection.put(entry.key, entry.value);
+              await outputCollection.put(entry.key, entry.value, { source: "derived" });
             }
             await saveFanoutSidecar(this.adapter, this.vault, {
               source: spec.source,
@@ -2135,7 +2188,7 @@ var Collection = class {
                 priorEnvelope: prior
               });
             }
-            await outputCollection.put(run.runId, patched);
+            await outputCollection.put(run.runId, patched, { source: "derived" });
             continue;
           }
           if (txCtx !== null) {
@@ -2150,7 +2203,7 @@ var Collection = class {
               priorEnvelope: prior
             });
           }
-          await outputCollection.put(run.runId, out.value);
+          await outputCollection.put(run.runId, out.value, { source: "derived" });
         }
       }
     }
@@ -2437,7 +2490,7 @@ var Collection = class {
       for (const [outputKey, outSpec] of Object.entries(spec.outputs)) {
         if (outSpec.shape !== "array") continue;
         if (helpers === null) {
-          helpers = await import("./fanout-sidecar-YXNAEZ33.js");
+          helpers = await import("./fanout-sidecar-ZQT4Y7PF.js");
         }
         const sidecar = await helpers.loadFanoutSidecar(
           this.adapter,
@@ -2477,7 +2530,7 @@ var Collection = class {
       if (mode === "eager") {
         if (executor === null) {
           ;
-          ({ MaterializedViewExecutor: executor } = await import("./executor-KYJCJCIN.js"));
+          ({ MaterializedViewExecutor: executor } = await import("./executor-BIW4FT5R.js"));
         }
         await executor.refresh(reg, {
           getCollection: (name) => this.materializedViewSource.getCollection(name),
@@ -2486,7 +2539,7 @@ var Collection = class {
         });
       } else if (mode === "lazy") {
         if (staleHelpers === null) {
-          staleHelpers = await import("./stale-CPESGAPL.js");
+          staleHelpers = await import("./stale-KKCHF2VB.js");
         }
         staleHelpers.markMVStale(registry, reg.spec.name);
       }
@@ -2509,7 +2562,7 @@ var Collection = class {
       );
     }
     if (this.materializedViewSource !== void 0) {
-      const { resolveStaleMVOnRead } = await import("./stale-CPESGAPL.js");
+      const { resolveStaleMVOnRead } = await import("./stale-KKCHF2VB.js");
       await resolveStaleMVOnRead(this.materializedViewSource, this.name);
     }
     await this.ensureHydrated();
@@ -3813,7 +3866,7 @@ var Collection = class {
    * (see {@link encryptRecord}). Rejects `_`-prefixed record fields, which
    * would collide with the reserved metadata namespace.
    */
-  buildDebugEnvelope(record, version) {
+  buildDebugEnvelope(record, version, source, sourceTs) {
     const rec = record;
     for (const key of Object.keys(rec)) {
       if (key.startsWith("_")) throw new DebugReservedFieldError(this.name, key);
@@ -3826,11 +3879,13 @@ var Collection = class {
       _data: "",
       _by: this.keyring.userId,
       _debug: NOYDB_FORMAT_VERSION,
+      ...this.provenance && source !== void 0 ? { _source: source, _sourceTs: sourceTs ?? (/* @__PURE__ */ new Date()).toISOString() } : {},
       ...rec
     };
   }
-  async encryptJsonString(json, version, cek) {
+  async encryptJsonString(json, version, cek, source, sourceTs) {
     const by = this.keyring.userId;
+    const provenanceFields = this.provenance && source !== void 0 ? { _source: source, _sourceTs: sourceTs ?? (/* @__PURE__ */ new Date()).toISOString() } : {};
     if (!this.encrypted) {
       return {
         _noydb: NOYDB_FORMAT_VERSION,
@@ -3838,7 +3893,8 @@ var Collection = class {
         _ts: (/* @__PURE__ */ new Date()).toISOString(),
         _iv: "",
         _data: json,
-        _by: by
+        _by: by,
+        ...provenanceFields
       };
     }
     const dek = await this.getDEK(this.name);
@@ -3852,7 +3908,8 @@ var Collection = class {
         _iv: iv2,
         _data: data2,
         _by: by,
-        _cek: wrapped
+        _cek: wrapped,
+        ...provenanceFields
       };
     }
     const { iv, data } = await encrypt(json, dek);
@@ -3862,14 +3919,15 @@ var Collection = class {
       _ts: (/* @__PURE__ */ new Date()).toISOString(),
       _iv: iv,
       _data: data,
-      _by: by
+      _by: by,
+      ...provenanceFields
     };
   }
-  async encryptRecord(record, version, cek) {
+  async encryptRecord(record, version, cek, source, sourceTs) {
     if (!this.encrypted && this.keyring.debugPlaintext === true && !this.name.startsWith("_")) {
-      return this.buildDebugEnvelope(record, version);
+      return this.buildDebugEnvelope(record, version, source, sourceTs);
     }
-    const base = await this.encryptJsonString(JSON.stringify(record), version, cek);
+    const base = await this.encryptJsonString(JSON.stringify(record), version, cek, source, sourceTs);
     if (!this.deterministicFields || !this.encrypted) return base;
     const dek = await this.getDEK(this.name);
     const rec = record;
@@ -4003,7 +4061,8 @@ var Collection = class {
       _iv: iv,
       _data: data,
       _by: this.keyring.userId,
-      ...tier > 0 && { _tier: tier }
+      ...tier > 0 && { _tier: tier },
+      ...this.provenance && opts?.source !== void 0 ? { _source: opts.source, _sourceTs: opts.sourceTs ?? (/* @__PURE__ */ new Date()).toISOString() } : {}
     };
     await this.adapter.put(this.vault, this.name, id, envelope);
     if (tier > 0) {
@@ -4341,43 +4400,49 @@ function randomId() {
   const b = globalThis.crypto.getRandomValues(new Uint8Array(12));
   return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
 }
-async function freezeAndDeleteClosure(vault, collections, opts) {
+async function freezeSnapshotOnly(vault, collections, opts) {
   const { name: vaultName, adapter } = vault._introspectState();
   const closure = [];
   for (const c of collections) {
     for (const id of await adapter.list(vaultName, c)) closure.push({ collection: c, id });
   }
-  let snapshot;
-  if (opts.disposition === "freeze") {
-    const withdrawalId = opts.withdrawalId ?? `wd-${randomId()}`;
-    const snap = {};
-    for (const { collection, id } of closure) {
-      const env = await adapter.get(vaultName, collection, id);
-      if (env) (snap[collection] ??= {})[id] = env;
-    }
-    const frozenAt = (/* @__PURE__ */ new Date()).toISOString();
-    const body = JSON.stringify({ withdrawalId, frozenAt, by: opts.actorUserId, collections: snap });
-    const sha = await sha256Hex(ENC.encode(body));
-    await adapter.put(
-      vaultName,
-      FROZEN_SNAPSHOTS_COLLECTION,
-      withdrawalId,
-      { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: frozenAt, _iv: "", _data: body, _by: opts.actorUserId },
-      0
-    );
-    await vault._getLedgerOrNull()?.append({
-      op: "lifecycle",
-      collection: "",
-      id: "",
-      version: 0,
-      actor: opts.actorUserId,
-      payloadHash: "",
-      reason: `withdrawal-frozen-snapshot:${withdrawalId}:${sha}`
-    });
-    snapshot = { withdrawalId, sha256: sha, recordCount: closure.length, frozenAt };
-  }
+  const withdrawalId = opts.withdrawalId ?? `wd-${randomId()}`;
+  const snap = {};
   for (const { collection, id } of closure) {
-    await vault.collection(collection).delete(id);
+    const env = await adapter.get(vaultName, collection, id);
+    if (env) (snap[collection] ??= {})[id] = env;
+  }
+  const frozenAt = (/* @__PURE__ */ new Date()).toISOString();
+  const body = JSON.stringify({ withdrawalId, frozenAt, by: opts.actorUserId, collections: snap });
+  const sha = await sha256Hex(ENC.encode(body));
+  await adapter.put(
+    vaultName,
+    FROZEN_SNAPSHOTS_COLLECTION,
+    withdrawalId,
+    { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: frozenAt, _iv: "", _data: body, _by: opts.actorUserId },
+    0
+  );
+  await vault._getLedgerOrNull()?.append({
+    op: "lifecycle",
+    collection: "",
+    id: "",
+    version: 0,
+    actor: opts.actorUserId,
+    payloadHash: "",
+    reason: `withdrawal-frozen-snapshot:${withdrawalId}:${sha}`
+  });
+  return { withdrawalId, sha256: sha, recordCount: closure.length, frozenAt };
+}
+async function freezeAndDeleteClosure(vault, collections, opts) {
+  const snapshot = opts.disposition === "freeze" ? await freezeSnapshotOnly(vault, collections, {
+    actorUserId: opts.actorUserId,
+    ...opts.withdrawalId ? { withdrawalId: opts.withdrawalId } : {}
+  }) : void 0;
+  const { name: vaultName, adapter } = vault._introspectState();
+  for (const c of collections) {
+    for (const id of await adapter.list(vaultName, c)) {
+      await vault.collection(c).delete(id);
+    }
   }
   return snapshot;
 }
@@ -4389,6 +4454,11 @@ async function withdrawAccessibleData(vault, opts) {
       "unilateralWithdrawal is the scoped self-service path; an owner/admin should use extractPartition"
     );
   }
+  if (keyring.role === "custodian") {
+    throw new ReadOnlyError(
+      "a custodian cannot destructively withdraw/sever; use vault.custody.liberate for an audited ownership claim"
+    );
+  }
   if (keyring.role === "client" || keyring.role === "viewer") {
     throw new ReadOnlyError(
       "read-only role cannot self-serve a destructive withdrawal \u2014 use requestWithdrawal (two-party)"
@@ -5578,6 +5648,148 @@ function isPlainObject(x) {
   return proto === Object.prototype || proto === null;
 }
 
+// src/custody/index.ts
+var CustodyApi = class {
+  constructor(_grantCustodian, _revokeCustodian, _liberate) {
+    this._grantCustodian = _grantCustodian;
+    this._revokeCustodian = _revokeCustodian;
+    this._liberate = _liberate;
+  }
+  _grantCustodian;
+  _revokeCustodian;
+  _liberate;
+  /**
+   * Owner-only: grant the FR-6 `custodian` role. The custodian operates every
+   * collection (rw + access) but is provably unable to grant / revoke / rotate /
+   * extract-and-sever. Defended in depth (gate + owner-only role check) inside
+   * the injected `Noydb.grantCustodian`.
+   */
+  async grantCustodian(options, factors) {
+    return this._grantCustodian(options, factors);
+  }
+  /** Owner-only: revoke a custodian. */
+  async revokeCustodian(options, factors) {
+    return this._revokeCustodian(options, factors);
+  }
+  /**
+   * Custodian-only: the audited claim of ownership over a sealed-owner (Deed)
+   * vault. Mints a DISTINCT new owner re-wrapping the incumbent DEKs under a
+   * fresh KEK (the latent owner is never impersonated), ledger-audited. See
+   * {@link liberateVault}.
+   */
+  async liberate(opts) {
+    return this._liberate(opts);
+  }
+};
+
+// src/team/deed.ts
+var DEED_RECORD_ID = "deed";
+async function createDeedOwner(store, vault, ownerUserId, sealing) {
+  const passphrase = await resolveManagedSecret(store, vault, sealing);
+  const keyring = await createOwnerKeyring(store, vault, ownerUserId, passphrase);
+  await saveDeedMarker(store, vault, {
+    ownerUserId,
+    sealedUnder: sealing.id,
+    latent: true,
+    issuedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  return keyring;
+}
+async function loadDeedMarker(store, vault) {
+  const envelope = await store.get(vault, "_meta", DEED_RECORD_ID);
+  if (!envelope) return null;
+  let payload;
+  try {
+    payload = JSON.parse(envelope._data);
+  } catch {
+    return null;
+  }
+  if (typeof payload !== "object" || payload === null) return null;
+  const r = payload;
+  if (r._noydb_deed !== 1) return null;
+  if (typeof r.ownerUserId !== "string" || typeof r.sealedUnder !== "string" || r.latent !== true || typeof r.issuedAt !== "string") {
+    return null;
+  }
+  const marker = {
+    ownerUserId: r.ownerUserId,
+    sealedUnder: r.sealedUnder,
+    latent: true,
+    issuedAt: r.issuedAt,
+    ...typeof r.liberatedAt === "string" ? { liberatedAt: r.liberatedAt } : {}
+  };
+  return marker;
+}
+async function isDeedVault(store, vault) {
+  return await loadDeedMarker(store, vault) !== null;
+}
+async function saveDeedMarker(store, vault, marker) {
+  const persisted = { _noydb_deed: 1, ...marker };
+  const prior = await store.get(vault, "_meta", DEED_RECORD_ID);
+  const env = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: (prior?._v ?? 0) + 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    // AES-GCM bypassed — the marker is plaintext audit metadata.
+    _iv: "",
+    _data: JSON.stringify(persisted)
+  };
+  await store.put(vault, "_meta", DEED_RECORD_ID, env);
+}
+
+// src/custody/liberate.ts
+async function liberateVault(vault, opts) {
+  await vault.noydb.checkGate(vault.name, "liberate-vault", opts.factors);
+  const { name: vaultName, adapter, keyring } = vault._introspectState();
+  if (keyring.role !== "custodian") {
+    throw new PermissionDeniedError(
+      "liberation is claimed only by the custodian (the de-facto authority holding the DEKs)"
+    );
+  }
+  const existing = await adapter.get(vaultName, "_keyring", opts.newOwnerId);
+  if (existing) {
+    throw new PermissionDeniedError(
+      `liberateVault: newOwnerId "${opts.newOwnerId}" already exists as a principal; choose a fresh id (liberation mints a distinct owner, it never overwrites an existing keyring)`
+    );
+  }
+  const collections = await listOperationalCollections(vault);
+  const snapshot = await freezeSnapshotOnly(vault, collections, { actorUserId: keyring.userId });
+  const newOwner = await createOwnerKeyring(adapter, vaultName, opts.newOwnerId, opts.newOwnerPassphrase);
+  if (!newOwner.kek) {
+    throw new PermissionDeniedError(
+      `new owner keyring for "${opts.newOwnerId}" has no KEK to re-wrap the incumbent DEKs under`
+    );
+  }
+  const env = await adapter.get(vaultName, "_keyring", opts.newOwnerId);
+  if (!env) {
+    throw new PermissionDeniedError(`new owner keyring for "${opts.newOwnerId}" did not persist`);
+  }
+  const keyringFile = JSON.parse(env._data);
+  const mergedDeks = { ...keyringFile.deks };
+  for (const [collection, dek] of keyring.deks) {
+    mergedDeks[collection] = await wrapKey(dek, newOwner.kek);
+  }
+  const mergedFile = { ...keyringFile, deks: mergedDeks };
+  await adapter.put(vaultName, "_keyring", opts.newOwnerId, { ...env, _data: JSON.stringify(mergedFile) });
+  await vault._getLedgerOrNull()?.append({
+    op: "lifecycle",
+    collection: "",
+    id: "",
+    version: 0,
+    actor: opts.newOwnerId,
+    payloadHash: "",
+    reason: `liberation-claimed:${opts.newOwnerId}:${opts.legalBasis}`
+  });
+  const marker = await loadDeedMarker(adapter, vaultName);
+  if (marker) {
+    await saveDeedMarker(adapter, vaultName, { ...marker, liberatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+  return { snapshot };
+}
+async function listOperationalCollections(vault) {
+  const { keyring } = vault._introspectState();
+  return [...keyring.deks.keys()].filter((c) => !c.startsWith("_"));
+}
+
 // src/persisted-schemas/canonicalize.ts
 function canonicalize(value) {
   if (value === null || typeof value !== "object") {
@@ -6360,6 +6572,18 @@ var Vault = class {
    * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md
    */
   user;
+  /**
+   * FR-6 custody API — the sovereign-custody surface, mirroring `vault.user.*`.
+   *
+   * - `grantCustodian(opts)` / `revokeCustodian(opts)` — owner-only: mint /
+   *   remove a `custodian` who operates the vault fully but can never grant /
+   *   rotate / sever / extract.
+   * - `liberate(opts)` — custodian-only: the audited claim of ownership over a
+   *   sealed-owner (Deed) vault (mints a DISTINCT new owner; ledger-audited).
+   *
+   * @see docs/superpowers/specs/2026-06-17-fr6-deed-custodian-liberate-design.md
+   */
+  custody;
   /**
    * Optional callback that re-derives an UnlockedKeyring from the
    * adapter using the active user's passphrase. Called by `load()`
@@ -6570,6 +6794,11 @@ var Vault = class {
       (requestId, opts2) => approveWithdrawal(this, requestId, opts2),
       (requestId, opts2) => rejectWithdrawal(this, requestId, opts2)
     );
+    this.custody = new CustodyApi(
+      (options, factors) => this.noydb.grantCustodian(this.name, options, factors),
+      (options, factors) => this.noydb.revokeCustodian(this.name, options, factors),
+      (opts2) => liberateVault(this, opts2)
+    );
   }
   /**
    * Construct (or reconstruct) the lazy DEK resolver. Captures the
@@ -6797,6 +7026,7 @@ var Vault = class {
         }
         collOpts.perRecordKeys = true;
       }
+      if (options?.provenance !== void 0) collOpts.provenance = options.provenance;
       if (options?.tiers !== void 0) collOpts.tiers = options.tiers;
       if (options?.tierMode !== void 0) collOpts.tierMode = options.tierMode;
       collOpts.onCrossTierAccess = (event) => this.emitCrossTier(event);
@@ -7481,12 +7711,12 @@ var Vault = class {
     if (!fieldSchema) {
       throw new AttestationError(`issueAttestation: collection '${collectionName}' has no attestation field-schema. Declare it via vault.collection('${collectionName}', { attestation: { fields: [...] } }).`);
     }
-    const { issueAttestationCore } = await import("./issue-JXC6T2QR.js");
+    const { issueAttestationCore } = await import("./issue-LEBPVF3Y.js");
     const out = await issueAttestationCore(this.makeIssueContext(), { collection: collectionName, id, fieldSchema });
     return { docId: out.docId, qr: out.qr, keyId: out.keyId, publicKeyB64: out.publicKeyB64 };
   }
   async getDocumentSigningPublicKey() {
-    const { loadSigner, loadOrCreateSigner } = await import("./signer-I6YARZQA.js");
+    const { loadSigner, loadOrCreateSigner } = await import("./signer-NEQPCHMW.js");
     const existing = await loadSigner(this.adapter, this.name, this.getDEK);
     if (existing) return { keyId: existing.keyId, publicKeyB64: existing.publicKeyB64 };
     if (this.keyring.role !== "owner") {
@@ -7512,19 +7742,19 @@ var Vault = class {
     };
   }
   async revokeAttestation(docId) {
-    const { revokeDocCore } = await import("./revoke-5IEK22KT.js");
+    const { revokeDocCore } = await import("./revoke-P5D3UTRX.js");
     await revokeDocCore(this.makeRevokeContext(), docId);
   }
   async unrevokeAttestation(docId) {
-    const { unrevokeDocCore } = await import("./revoke-5IEK22KT.js");
+    const { unrevokeDocCore } = await import("./revoke-P5D3UTRX.js");
     await unrevokeDocCore(this.makeRevokeContext(), docId);
   }
   async getRevokedDocIds() {
-    const { getRevokedDocIdsCore } = await import("./revoke-5IEK22KT.js");
+    const { getRevokedDocIdsCore } = await import("./revoke-P5D3UTRX.js");
     return getRevokedDocIdsCore(this.makeRevokeContext());
   }
   async publishRevocationList() {
-    const { publishRevocationListCore } = await import("./revoke-5IEK22KT.js");
+    const { publishRevocationListCore } = await import("./revoke-P5D3UTRX.js");
     return publishRevocationListCore(this.makeRevokeContext());
   }
   makeRevokeContext() {
@@ -8183,7 +8413,7 @@ var Vault = class {
   async _initDerivations(handles) {
     if (handles.length === 0) return;
     const [{ DerivationRegistry }, { ReadOnlyVaultFacade }] = await Promise.all([
-      import("./registry-ATRHOG5B.js"),
+      import("./registry-CMEVTOCN.js"),
       import("./read-only-facade-EX6WZZBP.js")
     ]);
     const registry = new DerivationRegistry();
@@ -8214,7 +8444,7 @@ var Vault = class {
    */
   async _initMaterializedViews(handles) {
     if (handles.length === 0) return;
-    const { MaterializedViewRegistry } = await import("./registry-NWHOLD5M.js");
+    const { MaterializedViewRegistry } = await import("./registry-OUZ3VBZA.js");
     const registry = new MaterializedViewRegistry();
     this.materializedViewRegistry = registry;
     const db = this;
@@ -8238,7 +8468,7 @@ var Vault = class {
    */
   async _initOverlayedViews(handles) {
     if (handles.length === 0) return;
-    const { OverlayedViewRegistry } = await import("./registry-LEHB26TY.js");
+    const { OverlayedViewRegistry } = await import("./registry-XUBRO5JJ.js");
     const registry = new OverlayedViewRegistry();
     const mvRegistry = this.materializedViewRegistry;
     const overlayNames = /* @__PURE__ */ new Set();
@@ -8285,13 +8515,13 @@ var Vault = class {
     if (!reg) {
       throw new Error(`refreshView: no MV registered with name "${name}"`);
     }
-    const { MaterializedViewExecutor } = await import("./executor-KYJCJCIN.js");
+    const { MaterializedViewExecutor } = await import("./executor-BIW4FT5R.js");
     const result = await MaterializedViewExecutor.refresh(reg, {
       getCollection: (n) => this.collection(n),
       getActiveTxContext: () => this.noydb._activeTxContextOrNull,
       getQueryContext: () => this
     });
-    const { clearMVStale } = await import("./stale-CPESGAPL.js");
+    const { clearMVStale } = await import("./stale-KKCHF2VB.js");
     clearMVStale(registry, name);
     return result;
   }
@@ -8307,7 +8537,7 @@ var Vault = class {
     if (registry === null) return { derived: 0, failed: 0 };
     const strategies = registry.strategiesForSource(sourceCollection);
     if (strategies.length === 0) return { derived: 0, failed: 0 };
-    const { DerivationExecutor } = await import("./executor-4IEW4KG5.js");
+    const { DerivationExecutor } = await import("./executor-VEZUBJNQ.js");
     const sourceColl = this.collection(sourceCollection);
     const records = await sourceColl.list();
     const ctx = { vault: this.derivationFacade ?? new (await import("./read-only-facade-EX6WZZBP.js")).ReadOnlyVaultFacade(this, "derivation") };
@@ -8332,7 +8562,7 @@ var Vault = class {
           if (!outSpec) continue;
           const outputColl = this.collection(outSpec.collection);
           if (out.kind === "array") {
-            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-YXNAEZ33.js");
+            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-ZQT4Y7PF.js");
             const prior = await loadFanoutSidecar(this.adapter, this.name, spec.source, id, key);
             const prevKeys = new Set(prior?.keys ?? []);
             const newKeysList = out.entries.map((e) => e.key);
@@ -8554,7 +8784,7 @@ var Vault = class {
    * collection.
    */
   async delegate(opts) {
-    const { issueDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-DP4COTXB.js");
+    const { issueDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-4JSMM6BB.js");
     if (!this.keyring.kek) {
       throw new ValidationError(
         "issueDelegation: keyring.kek is null \u2014 issuing a delegation requires a tier-1 unlock. Re-authenticate at tier 1 (passphrase) first."
@@ -8576,7 +8806,7 @@ var Vault = class {
    * if the id does not exist.
    */
   async revokeDelegation(id) {
-    const { revokeDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-DP4COTXB.js");
+    const { revokeDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-4JSMM6BB.js");
     await revokeDelegation(this.adapter, this.name, id);
     void DELEGATIONS_COLLECTION;
   }
@@ -8619,7 +8849,7 @@ var Vault = class {
     if (this.activeElevation) {
       throw new AlreadyElevatedError(this.activeElevation.tier);
     }
-    if (this.keyring.role !== "owner" && this.keyring.role !== "admin") {
+    if (this.keyring.role !== "owner" && this.keyring.role !== "admin" && this.keyring.role !== "custodian") {
       const suffix = `#${tier}`;
       let found = false;
       for (const k of this.keyring.deks.keys()) {
@@ -9046,7 +9276,7 @@ var Vault = class {
    * @see docs/subsystems/public-envelope.md
    */
   async getPublicEnvelope(opts = {}) {
-    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-5XRTUNKF.js");
+    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-DBKJEBBF.js");
     return readPublicEnvelope2(this.adapter, this.name, opts);
   }
   /**
@@ -10563,6 +10793,12 @@ var ROLE_RANK = {
   client: 1,
   viewer: 2,
   operator: 3,
+  // FR-6: custodian is operationally admin-rank (rw + access on every
+  // collection) — it ranks alongside admin for "how much can this
+  // principal see/operate." It is NOT above admin, and explicitly below
+  // owner: a custodian can never grant/revoke/rotate/sever (those are
+  // owner meta-capabilities), so it must not outrank or equal the owner.
+  custodian: 4,
   admin: 4,
   owner: 5
 };
@@ -10624,7 +10860,6 @@ var Noydb = class {
   writeRelay;
   /** Per-vault policy enforcers. */
   policyEnforcers = /* @__PURE__ */ new Map();
-  vaultTemplates = /* @__PURE__ */ new Map();
   txStrategy;
   forgetStrategy;
   sessionStrategy;
@@ -10755,7 +10990,7 @@ var Noydb = class {
       if (!facade) return;
       const ctx = { existing, vault: facade, userId: e.userId, role: e.role };
       await registry.runChecks(e.collection, incoming, ctx);
-      const { GuardExecutor } = await import("./executor-W7VIBOBZ.js");
+      const { GuardExecutor } = await import("./executor-3SVNESQ3.js");
       for (const g of guards) {
         await GuardExecutor.checkFrozenFields(g, e.docId, existing, incoming, e.computedFieldNames);
       }
@@ -11074,6 +11309,37 @@ var Noydb = class {
     const keyring = await this.getKeyringInternal(vault);
     await revoke(this.options.store, vault, keyring, options);
   }
+  /**
+   * Grant the FR-6 `custodian` role to a user (owner-only custody API).
+   *
+   * A custodian operates every collection (rw + access) but is provably
+   * unable to grant / revoke / rotate / extract-and-sever. Only the Deed
+   * owner may mint one. Defended in depth: the `grant-custodian` gate
+   * (fail-closed) AND an explicit `keyring.role !== 'owner'` check — the
+   * gate enforces host policy, the role check enforces the cryptographic
+   * owner-only invariant even if a host mis-configures the gate.
+   */
+  async grantCustodian(vault, options, factors) {
+    this.checkPolicyOperation(vault, "grant");
+    await this.checkGate(vault, "grant-custodian", factors);
+    const keyring = await this.getKeyringInternal(vault);
+    if (keyring.role !== "owner") throw new PermissionDeniedError("only the Deed owner can grant a custodian");
+    await grant(this.options.store, vault, keyring, { ...options, role: "custodian" });
+  }
+  /**
+   * Revoke a custodian (owner-only custody API).
+   *
+   * Mirrors {@link revoke} but pins the caller to the Deed owner: defended
+   * in depth by the `revoke-user` gate AND an explicit `keyring.role !==
+   * 'owner'` check, so an admin cannot unwind a custodianship.
+   */
+  async revokeCustodian(vault, options, factors) {
+    this.checkPolicyOperation(vault, "revoke");
+    await this.checkGate(vault, "revoke-user", factors);
+    const keyring = await this.getKeyringInternal(vault);
+    if (keyring.role !== "owner") throw new PermissionDeniedError("only the Deed owner can revoke a custodian");
+    await revoke(this.options.store, vault, keyring, options);
+  }
   /**
    * Mutate post-grant identity fields on an existing keyring — `role`,
    * `displayName`, and/or `permissions`. Pure plaintext-header rewrite:
@@ -11343,52 +11609,12 @@ var Noydb = class {
     return results;
   }
   /**
-   * Register a shard schema blueprint. `createShard` / `openVaultGroup`
-   * stamp shards from the named template. See the MVF design spec.
+   * @internal True once `close()` has been called. Read by outward
+   * orchestration frameworks whose entry points can't see the private
+   * `closed` field.
    */
-  withVaultTemplate(name, template) {
-    this.vaultTemplates.set(name, template);
-  }
-  /**
-   * Open a VaultGroup — transparent routing over per-partition shard
-   * vaults, with shard discovery backed by the supplied `vault-registry`
-   * collection.
-   */
-  async openVaultGroup(name, opts) {
-    if (this.closed) throw new ValidationError("Instance is closed");
-    if (name === STATE_VAULT_NAME) throw new ReservedVaultNameError(name);
-    const template = this.vaultTemplates.get(opts.sharding.vaultTemplate);
-    if (!template) throw new VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
-    const { VaultGroup } = await import("./vault-group-BB246VIM.js");
-    const { StateManagementVault } = await import("./state-vault-JR3CFGNP.js");
-    const stateVault = opts.registry ? void 0 : await StateManagementVault.open(this);
-    const registry = opts.registry ?? stateVault.registry;
-    const group = new VaultGroup(this, name, registry, opts.sharding, template, opts.migrateOnOpen ?? false);
-    if (stateVault) {
-      group._attachStateVault(stateVault);
-      await stateVault.recordManifest(opts.sharding.vaultTemplate, template);
-      try {
-        await stateVault.appendEvent({
-          type: "manifest-recorded",
-          group: name,
-          templateName: opts.sharding.vaultTemplate,
-          version: template.version
-        });
-        await stateVault.appendEvent({ type: "group-opened", group: name });
-      } catch {
-      }
-    }
-    return group;
-  }
-  /**
-   * Open the reserved StateManagement control-plane vault (registry +
-   * schema-manifest + deployment-events). Lazy-loaded so the federation
-   * chunk stays out of the core graph until used.
-   */
-  async openStateManagementVault() {
-    if (this.closed) throw new ValidationError("Instance is closed");
-    const { StateManagementVault } = await import("./state-vault-JR3CFGNP.js");
-    return StateManagementVault.open(this);
+  get isClosed() {
+    return this.closed;
   }
   /**
    * @internal — true when an encrypted shard vault is provisioned
@@ -12909,22 +13135,6 @@ export {
   listWithdrawalRequests,
   approveWithdrawal,
   rejectWithdrawal,
-  validateSchemaInput,
-  validateSchemaOutput,
-  isZodSchema,
-  derivePersistedSchema,
-  persistSchemaIfNeeded,
-  isRefArray,
-  RefIntegrityError,
-  RefScopeError,
-  ref,
-  refArray,
-  RefRegistry,
-  isLinkCollectionName,
-  LinkEndpointError,
-  LinkIntegrityError,
-  QuickUnlockStore,
-  UserApi,
   META_COLLECTION,
   POLICY_RECORD_ID,
   loadVaultPolicy,
@@ -12935,14 +13145,36 @@ export {
   describeAllUsersAuth,
   ComputedFieldError,
   evalComputedFields,
+  validateSchemaInput,
+  validateSchemaOutput,
   tokenize,
   Lru,
   parseBytes,
   estimateRecordBytes,
   Collection,
+  isRefArray,
+  RefIntegrityError,
+  RefScopeError,
+  ref,
+  refArray,
+  RefRegistry,
+  isLinkCollectionName,
+  LinkEndpointError,
+  LinkIntegrityError,
+  UserApi,
+  CustodyApi,
+  DEED_RECORD_ID,
+  createDeedOwner,
+  loadDeedMarker,
+  isDeedVault,
+  liberateVault,
+  isZodSchema,
+  derivePersistedSchema,
+  persistSchemaIfNeeded,
   Vault,
   ELEVATION_AUDIT_COLLECTION,
   ElevatedHandle,
+  QuickUnlockStore,
   PERSONAL_POLICY,
   STRICT_POLICY,
   mergePolicy,
@@ -12952,4 +13184,4 @@ export {
   Noydb,
   createNoydb
 };
-//# sourceMappingURL=chunk-P65YMN5V.js.map
+//# sourceMappingURL=chunk-56ENKU46.js.map