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

package/dist/bundle/index.cjs

@@ -203,7 +203,7 @@ var init_format = __esm({
 });
 
 // src/errors.ts
-var NoydbError, DebugPlaintextError, DebugReservedFieldError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, UnknownShardError, ShardProvisioningError, DataResidencyError, CrossShardJoinError, VaultTemplateNotFoundError, ForgetStrategyNotConfiguredError, RecordCekNotFoundError;
+var NoydbError, DebugPlaintextError, DebugReservedFieldError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, ForgetStrategyNotConfiguredError, RecordCekNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -342,18 +342,6 @@ var init_errors = __esm({
         this.offendingCollection = offendingCollection;
       }
     };
-    ReservedVaultNameError = class extends NoydbError {
-      /** The rejected vault name. */
-      vaultName;
-      constructor(vaultName) {
-        super(
-          "RESERVED_VAULT_NAME",
-          `"${vaultName}" is a reserved internal vault name and cannot be used as a group name or partition key`
-        );
-        this.name = "ReservedVaultNameError";
-        this.vaultName = vaultName;
-      }
-    };
     FieldFrozenError = class extends NoydbError {
       collection;
       id;
@@ -941,60 +929,6 @@ Resolutions:
         this.expected = expected;
       }
     };
-    UnknownShardError = class extends NoydbError {
-      partitionKey;
-      constructor(partitionKey, groupName) {
-        super(
-          "SHARD_UNKNOWN",
-          `No shard for partition key "${partitionKey}" in vault group "${groupName}" and autoCreate is disabled. Call group.createShard(${JSON.stringify(partitionKey)}) first, or enable sharding.autoCreate.`
-        );
-        this.name = "UnknownShardError";
-        this.partitionKey = partitionKey;
-      }
-    };
-    ShardProvisioningError = class extends NoydbError {
-      vaultId;
-      constructor(vaultId, partitionKey) {
-        super(
-          "SHARD_PROVISIONING",
-          `Registry has a row for partition "${partitionKey}" (vault "${vaultId}") but that vault is not provisioned in the store. Refusing to recreate it \u2014 the registry and store have diverged. Investigate before retrying.`
-        );
-        this.name = "ShardProvisioningError";
-        this.vaultId = vaultId;
-      }
-    };
-    DataResidencyError = class extends NoydbError {
-      vaultId;
-      requiredRegion;
-      backendRegion;
-      constructor(vaultId, requiredRegion, backendRegion) {
-        super(
-          "DATA_RESIDENCY",
-          `Shard "${vaultId}" requires region "${requiredRegion}" but its placement backend declares region ${backendRegion === void 0 ? "(none)" : `"${backendRegion}"`}. Refusing to provision \u2014 route this shard to a region-correct backend via routeStore({ vaultRoutes }) (e.g. a region-encoded partition key) before retrying.`
-        );
-        this.name = "DataResidencyError";
-        this.vaultId = vaultId;
-        this.requiredRegion = requiredRegion;
-        this.backendRegion = backendRegion;
-      }
-    };
-    CrossShardJoinError = class extends NoydbError {
-      constructor(message) {
-        super("CROSS_SHARD_JOIN", message);
-        this.name = "CrossShardJoinError";
-      }
-    };
-    VaultTemplateNotFoundError = class extends NoydbError {
-      templateName;
-      constructor(templateName) {
-        super(
-          "VAULT_TEMPLATE_NOT_FOUND",
-          `No vault template registered under "${templateName}". Register it with db.withVaultTemplate(${JSON.stringify(templateName)}, { version, configure }) before opening the vault group.`
-        );
-        this.name = "VaultTemplateNotFoundError";
-        this.templateName = templateName;
-      }
-    };
     ForgetStrategyNotConfiguredError = class extends NoydbError {
       constructor(message = 'vault.forget() requires a forget strategy. Pass `forgetStrategy: withForgetCascade({ subjects: { <collection>: <subjectField> } })` from "@noy-db/hub/forget" to createNoydb().') {
         super("FORGET_NOT_CONFIGURED", message);
@@ -2518,12 +2452,14 @@ var init_user_envelope = __esm({
 // src/team/keyring.ts
 function canGrant(callerRole, targetRole) {
   if (callerRole === "owner") return true;
+  if (callerRole === "custodian") return false;
   if (callerRole === "admin") return ADMIN_GRANTABLE_TARGETS.includes(targetRole);
   return false;
 }
 function canRevoke(callerRole, targetRole) {
   if (targetRole === "owner") return false;
   if (callerRole === "owner") return true;
+  if (callerRole === "custodian") return false;
   if (callerRole === "admin") return ADMIN_GRANTABLE_TARGETS.includes(targetRole);
   return false;
 }
@@ -2687,7 +2623,7 @@ async function grant(adapter, vault, callerKeyring, options) {
       wrappedDeks[collName] = await wrapKey(dek, newKek);
     }
   }
-  if (options.role === "owner" || options.role === "admin" || options.role === "viewer") {
+  if (options.role === "owner" || options.role === "admin" || options.role === "custodian" || options.role === "viewer") {
     for (const [collName, dek] of callerKeyring.deks) {
       if (!(collName in wrappedDeks)) {
         wrappedDeks[collName] = await wrapKey(dek, newKek);
@@ -2835,6 +2771,11 @@ async function updateKeyringIdentity(adapter, vault, callerKeyring, options) {
   await writeKeyringFile(adapter, vault, options.userId, next);
 }
 async function rotateKeys(adapter, vault, callerKeyring, collections) {
+  if (callerKeyring.role === "custodian") {
+    throw new PermissionDeniedError(
+      "custodian cannot rotate keys (FR-6: re-key is an owner-only meta-capability; use the Deed owner)"
+    );
+  }
   const newDeks = /* @__PURE__ */ new Map();
   for (const collName of collections) {
     newDeks.set(collName, await generateDEK());
@@ -2944,7 +2885,7 @@ async function buildRecipientKeyringFile(callerKeyring, recipient) {
       wrappedDeks[collName] = await wrapKey(dek, newKek);
     }
   }
-  if (role === "owner" || role === "admin" || role === "viewer") {
+  if (role === "owner" || role === "admin" || role === "custodian" || role === "viewer") {
     for (const [collName, dek] of callerKeyring.deks) {
       if (!(collName in wrappedDeks)) {
         wrappedDeks[collName] = await wrapKey(dek, newKek);
@@ -3018,12 +2959,13 @@ async function ensureCollectionDEK(adapter, vault, keyring) {
   };
 }
 function hasWritePermission(keyring, collectionName) {
-  if (keyring.role === "owner" || keyring.role === "admin") return true;
+  if (keyring.role === "owner" || keyring.role === "admin" || keyring.role === "custodian") return true;
   if (keyring.role === "viewer" || keyring.role === "client") return false;
   return keyring.permissions[collectionName] === "rw";
 }
 function hasAccess(keyring, collectionName) {
-  if (keyring.role === "owner" || keyring.role === "admin" || keyring.role === "viewer") return true;
+  if (keyring.role === "owner" || keyring.role === "admin" || keyring.role === "custodian" || keyring.role === "viewer")
+    return true;
   return collectionName in keyring.permissions;
 }
 async function persistKeyring(adapter, vault, keyring) {
@@ -3075,7 +3017,7 @@ function hasImportCapability(keyring, tier, format) {
   return cap?.bundle === true;
 }
 function resolvePermissions(role, explicit) {
-  if (role === "owner" || role === "admin" || role === "viewer") return {};
+  if (role === "owner" || role === "admin" || role === "custodian" || role === "viewer") return {};
   return explicit ?? {};
 }
 async function writeKeyringFile(adapter, vault, userId, keyringFile) {
@@ -3781,15 +3723,6 @@ var init_store = __esm({
   }
 });
 
-// src/federation/constants.ts
-var STATE_VAULT_NAME;
-var init_constants2 = __esm({
-  "src/federation/constants.ts"() {
-    "use strict";
-    STATE_VAULT_NAME = "__noydb_state__";
-  }
-});
-
 // src/policy/errors.ts
 var PolicyDeniedError, RecoveryNotEnrolledError, ManagedRecoveryNotEnrolledError, RecoveryProfileNotImplementedError;
 var init_errors2 = __esm({
@@ -4992,10 +4925,10 @@ function shouldRoundUp(negative, lastKeptDigit, firstDiscarded, hasMoreNonZeroAf
   }
 }
 function parseToScaledInt(input, scale, rounding) {
-  const canonical2 = toCanonicalDecimalString(input);
-  if (canonical2 === null) return { ok: false, reason: "nonfinite" };
-  const negative = canonical2.startsWith("-");
-  const unsigned = negative ? canonical2.slice(1) : canonical2;
+  const canonical = toCanonicalDecimalString(input);
+  if (canonical === null) return { ok: false, reason: "nonfinite" };
+  const negative = canonical.startsWith("-");
+  const unsigned = negative ? canonical.slice(1) : canonical;
   const dot = unsigned.indexOf(".");
   const intPart = dot === -1 ? unsigned : unsigned.slice(0, dot);
   const fracPart = dot === -1 ? "" : unsigned.slice(dot + 1);
@@ -5491,7 +5424,7 @@ function dekKey(collection, tier) {
 }
 function assertTierAccess(keyring, collection, tier) {
   if (tier <= 0) return;
-  if (keyring.role === "owner" || keyring.role === "admin") return;
+  if (keyring.role === "owner" || keyring.role === "admin" || keyring.role === "custodian") return;
   if (!keyring.deks.has(dekKey(collection, tier))) {
     throw new TierNotGrantedError(collection, tier);
   }
@@ -6562,7 +6495,7 @@ function serializeClause(clause) {
 }
 function canonicalCtxHash(ctx) {
   if (ctx === void 0) return "";
-  const canonical2 = JSON.stringify(ctx, (_key, value) => {
+  const canonical = JSON.stringify(ctx, (_key, value) => {
     if (value && typeof value === "object" && !Array.isArray(value)) {
       const sorted = {};
       for (const k of Object.keys(value).sort()) {
@@ -6573,8 +6506,8 @@ function canonicalCtxHash(ctx) {
     return value;
   });
   let h = 5381;
-  for (let i = 0; i < canonical2.length; i++) {
-    h = (h << 5) + h ^ canonical2.charCodeAt(i);
+  for (let i = 0; i < canonical.length; i++) {
+    h = (h << 5) + h ^ canonical.charCodeAt(i);
   }
   return (h >>> 0).toString(16).padStart(8, "0");
 }
@@ -7283,29 +7216,6 @@ var init_builder = __esm({
   }
 });
 
-// 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 init_aggregation = __esm({
-  "src/aggregate/aggregation.ts"() {
-    "use strict";
-  }
-});
-
 // src/aggregate/canonical-key.ts
 function canonicalGroupKey(fields, row) {
   const sorted = [...fields].sort();
@@ -8534,7 +8444,7 @@ var init_transaction = __esm({
         const v = this._db.vault(name);
         if (this._amendment && !this._amendmentVaults.has(name)) {
           const role = v.role;
-          if (role !== "admin" && role !== "owner") {
+          if (role !== "admin" && role !== "owner" && role !== "custodian") {
             throw new AmendmentForbiddenError(v.userId, role);
           }
           const reg = v._getGuardRegistry();
@@ -8904,12 +8814,12 @@ var init_dependency_analyzer = __esm({
 
 // src/materialized-views/query-hash.ts
 async function computeQueryHash(mvName, dependencies, queryPlanSummary) {
-  const canonical2 = JSON.stringify({
+  const canonical = JSON.stringify({
     mvName,
     dependencies: [...dependencies].sort(),
     queryPlanSummary
   });
-  const bytes = new TextEncoder().encode(canonical2);
+  const bytes = new TextEncoder().encode(canonical);
   const digest = await crypto.subtle.digest("SHA-256", bytes);
   return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -9722,6 +9632,13 @@ var init_collection = __esm({
        * 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
@@ -9881,6 +9798,7 @@ var init_collection = __esm({
         }
         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) => {
@@ -10068,6 +9986,33 @@ var init_collection = __esm({
         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.
        *
@@ -10105,6 +10050,14 @@ var init_collection = __esm({
        *                `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();
@@ -10136,6 +10089,20 @@ var init_collection = __esm({
           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;
@@ -10293,7 +10260,7 @@ var init_collection = __esm({
           }
           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;
@@ -10372,7 +10339,7 @@ var init_collection = __esm({
             });
           }
         }
-        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 = {
@@ -10665,7 +10632,7 @@ var init_collection = __esm({
                       priorEnvelope
                     });
                   }
-                  await outputCollection.put(entry.key, entry.value);
+                  await outputCollection.put(entry.key, entry.value, { source: "derived" });
                 }
                 await saveFanoutSidecar2(this.adapter, this.vault, {
                   source: spec.source,
@@ -10698,7 +10665,7 @@ var init_collection = __esm({
                     priorEnvelope: prior
                   });
                 }
-                await outputCollection.put(run.runId, patched);
+                await outputCollection.put(run.runId, patched, { source: "derived" });
                 continue;
               }
               if (txCtx !== null) {
@@ -10713,7 +10680,7 @@ var init_collection = __esm({
                   priorEnvelope: prior
                 });
               }
-              await outputCollection.put(run.runId, out.value);
+              await outputCollection.put(run.runId, out.value, { source: "derived" });
             }
           }
         }
@@ -12376,7 +12343,7 @@ var init_collection = __esm({
        * (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);
@@ -12389,11 +12356,13 @@ var init_collection = __esm({
           _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,
@@ -12401,7 +12370,8 @@ var init_collection = __esm({
             _ts: (/* @__PURE__ */ new Date()).toISOString(),
             _iv: "",
             _data: json,
-            _by: by
+            _by: by,
+            ...provenanceFields
           };
         }
         const dek = await this.getDEK(this.name);
@@ -12415,7 +12385,8 @@ var init_collection = __esm({
             _iv: iv2,
             _data: data2,
             _by: by,
-            _cek: wrapped
+            _cek: wrapped,
+            ...provenanceFields
           };
         }
         const { iv, data } = await encrypt(json, dek);
@@ -12425,14 +12396,15 @@ var init_collection = __esm({
           _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;
@@ -12566,7 +12538,8 @@ var init_collection = __esm({
           _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) {
@@ -12873,43 +12846,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 sha256Hex2(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 sha256Hex2(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;
 }
@@ -12921,6 +12900,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)"
@@ -14819,6 +14803,157 @@ var init_api = __esm({
   }
 });
 
+// src/custody/index.ts
+var CustodyApi;
+var init_custody = __esm({
+  "src/custody/index.ts"() {
+    "use strict";
+    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
+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 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);
+}
+var DEED_RECORD_ID;
+var init_deed = __esm({
+  "src/team/deed.ts"() {
+    "use strict";
+    init_types();
+    DEED_RECORD_ID = "deed";
+  }
+});
+
+// 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("_"));
+}
+var init_liberate = __esm({
+  "src/custody/liberate.ts"() {
+    "use strict";
+    init_errors();
+    init_crypto();
+    init_keyring();
+    init_withdraw_accessible();
+    init_deed();
+  }
+});
+
 // src/persisted-schemas/canonicalize.ts
 function canonicalize(value) {
   if (value === null || typeof value !== "object") {
@@ -14868,8 +15003,8 @@ async function derivePersistedSchema(validator) {
   if (kind === "Zod") {
     const convert = await loadZodConverter();
     const jsonSchema = convert(validator);
-    const canonical2 = canonicalize(jsonSchema);
-    const hash = await sha256Hex2(new TextEncoder().encode(canonical2));
+    const canonical = canonicalize(jsonSchema);
+    const hash = await sha256Hex2(new TextEncoder().encode(canonical));
     return { _noydb_schema: 1, kind, jsonSchema, hash, derivedAt };
   }
   return {
@@ -15912,7 +16047,7 @@ var init_read_only_facade = __esm({
 
 // src/derivations/strategy-hash.ts
 async function computeStrategyHash(source, outputKeys, derive, sources) {
-  const canonical2 = JSON.stringify({
+  const canonical = JSON.stringify({
     source,
     outputs: [...outputKeys].sort(),
     derive: derive.toString(),
@@ -15921,7 +16056,7 @@ async function computeStrategyHash(source, outputKeys, derive, sources) {
     // so strategies without siblings keep their existing hash.
     ...sources?.length ? { sources: [...sources].sort() } : {}
   });
-  const bytes = new TextEncoder().encode(canonical2);
+  const bytes = new TextEncoder().encode(canonical);
   const digest = await crypto.subtle.digest("SHA-256", bytes);
   return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -16254,6 +16389,8 @@ var init_vault = __esm({
     init_blob_compaction();
     init_magic_link_grant();
     init_api();
+    init_custody();
+    init_liberate();
     init_register();
     init_gate();
     init_fence_controller();
@@ -16361,6 +16498,18 @@ var init_vault = __esm({
        * @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()`
@@ -16571,6 +16720,11 @@ var init_vault = __esm({
           (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
@@ -16798,6 +16952,7 @@ var init_vault = __esm({
             }
             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);
@@ -18620,7 +18775,7 @@ var init_vault = __esm({
         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()) {
@@ -20822,997 +20977,6 @@ var init_executor3 = __esm({
   }
 });
 
-// src/federation/schema-manifest.ts
-function captureBlueprint(configure) {
-  const recorded = [];
-  const collectionStub = new Proxy(
-    {},
-    {
-      get: () => () => collectionStub
-    }
-  );
-  const proxy = new Proxy(
-    {},
-    {
-      get: (_t, prop) => {
-        if (prop === "collection") {
-          return (name, opts) => {
-            recorded.push({
-              name,
-              indexes: opts?.indexes ?? [],
-              persistJsonSchema: !!opts?.persistJsonSchema
-            });
-            return collectionStub;
-          };
-        }
-        return () => proxy;
-      }
-    }
-  );
-  configure(proxy);
-  const sorted = [...recorded].sort((a, b) => a.name.localeCompare(b.name));
-  const indexes = {};
-  const persistJsonSchema = [];
-  for (const c of sorted) {
-    indexes[c.name] = c.indexes;
-    if (c.persistJsonSchema) persistJsonSchema.push(c.name);
-  }
-  return {
-    // `persistJsonSchema` is already name-sorted: it is populated while
-    // iterating `sorted` (collections in name order).
-    collections: sorted.map((c) => c.name),
-    indexes,
-    persistJsonSchema
-  };
-}
-function canonical(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  const obj = value;
-  const keys = Object.keys(obj).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
-}
-async function fingerprintBlueprint(bp) {
-  return sha256Hex2(new TextEncoder().encode(canonical(bp)));
-}
-var init_schema_manifest = __esm({
-  "src/federation/schema-manifest.ts"() {
-    "use strict";
-    init_crypto();
-  }
-});
-
-// src/federation/state-vault.ts
-var state_vault_exports = {};
-__export(state_vault_exports, {
-  STATE_VAULT_NAME: () => STATE_VAULT_NAME,
-  StateManagementVault: () => StateManagementVault
-});
-var REGISTRY, MANIFEST, EVENTS, MIGRATION_STATUS, StateManagementVault;
-var init_state_vault = __esm({
-  "src/federation/state-vault.ts"() {
-    "use strict";
-    init_schema_manifest();
-    init_constants2();
-    init_ulid();
-    init_constants2();
-    REGISTRY = "vaultRegistry";
-    MANIFEST = "schemaManifest";
-    EVENTS = "deploymentEvents";
-    MIGRATION_STATUS = "migrationStatus";
-    StateManagementVault = class _StateManagementVault {
-      constructor(registry, schemaManifest, events, migrationStatus) {
-        this.registry = registry;
-        this.schemaManifest = schemaManifest;
-        this.#events = events;
-        this.#migrationStatus = migrationStatus;
-      }
-      registry;
-      schemaManifest;
-      /**
-       * The append-only deployment-events log is kept truly private so the raw
-       * mutable Collection is never surfaced — events may only be written via
-       * `appendEvent` and read via `queryEvents`. (`registry` and
-       * `schemaManifest` are deliberately public: consumers read and write them.)
-       */
-      #events;
-      /** Per-shard fleet-migration progress (#271). Surfaced via typed methods only. */
-      #migrationStatus;
-      /** Idempotently open the reserved state vault and bind the control-plane collections. */
-      static async open(db) {
-        const vault = await db.openVault(STATE_VAULT_NAME);
-        return new _StateManagementVault(
-          vault.collection(REGISTRY),
-          vault.collection(MANIFEST),
-          vault.collection(EVENTS),
-          vault.collection(MIGRATION_STATUS)
-        );
-      }
-      /** Read one shard's migration status (or null). */
-      async getMigrationStatus(vaultId) {
-        return this.#migrationStatus.get(vaultId);
-      }
-      /** All migration-status rows (hydrates first). */
-      async listMigrationStatus() {
-        await this.#migrationStatus.list();
-        return this.#migrationStatus.query().toArray();
-      }
-      /** Upsert one shard's migration status (keyed by vaultId). */
-      async upsertMigrationStatus(row) {
-        await this.#migrationStatus.put(row.vaultId, row);
-      }
-      /** Read-only query over the append-only deployment-events log. */
-      queryEvents() {
-        return this.#events.query();
-      }
-      /**
-       * Append a deployment event with a fresh unique (ULID) id. This is the
-       * only write path to the events log; no update/delete is exposed.
-       * Callers should treat failures as non-fatal — this method does not
-       * swallow errors, so wrap the call site in try/catch where appropriate.
-       */
-      async appendEvent(event) {
-        const ts = event.ts ?? Date.now();
-        const id = generateULID();
-        await this.#events.put(id, { ...event, id, ts });
-      }
-      /**
-       * Ensure a manifest row exists for `(templateName, template.version)`.
-       * Safe to call repeatedly: the `fingerprint` is a deterministic hash of
-       * the template's declared shape (stable across calls), though each call
-       * refreshes `recordedAt`.
-       */
-      async recordManifest(templateName, template) {
-        const bp = captureBlueprint(template.configure);
-        const fingerprint = await fingerprintBlueprint(bp);
-        await this.schemaManifest.put(`${templateName}:${template.version}`, {
-          templateName,
-          version: template.version,
-          collections: bp.collections,
-          indexes: bp.indexes,
-          persistJsonSchema: bp.persistJsonSchema,
-          fingerprint,
-          recordedAt: Date.now()
-        });
-        return fingerprint;
-      }
-      /**
-       * True when `template`'s current declared shape does not match the recorded
-       * manifest for `(templateName, template.version)`. Because shards carry no
-       * schema state independent of their template, this catches "a template's
-       * shape changed without bumping `version`" — not independent per-shard drift.
-       * A missing manifest is treated as drift (nothing to verify against).
-       */
-      async detectDrift(templateName, template) {
-        const row = await this.schemaManifest.get(`${templateName}:${template.version}`);
-        if (!row) return true;
-        const current = await fingerprintBlueprint(captureBlueprint(template.configure));
-        return current !== row.fingerprint;
-      }
-    };
-  }
-});
-
-// src/federation/classify-skip.ts
-function classifyShardSkip(err) {
-  return err instanceof NoAccessError ? "no-grant" : "error";
-}
-var init_classify_skip = __esm({
-  "src/federation/classify-skip.ts"() {
-    "use strict";
-    init_errors();
-  }
-});
-
-// src/federation/cross-shard-join.ts
-function coerceKey(value) {
-  if (value === null || value === void 0) return null;
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "bigint") return String(value);
-  return null;
-}
-function warnOnceBroadcastMiss(field, as, key) {
-  const dedup = `${field}\u2192${as}:${key}`;
-  if (warnedBroadcastKeys.has(dedup)) return;
-  warnedBroadcastKeys.add(dedup);
-  console.warn(
-    `[noy-db] broadcastJoin: no "${as}" dimension row for ${field}="${key}". Attaching null. Use mode: 'cascade' to silence.`
-  );
-}
-async function applyBroadcastLegs(rows, legs) {
-  if (legs.length === 0) return [...rows];
-  const indexes = [];
-  for (const leg of legs) {
-    const map = /* @__PURE__ */ new Map();
-    for (const rec of await leg.from.list()) {
-      const k = coerceKey(readPath(rec, leg.on));
-      if (k !== null && !map.has(k)) map.set(k, rec);
-    }
-    indexes.push({ leg, map });
-  }
-  return rows.map((row) => {
-    const out = { ...row };
-    for (const { leg, map } of indexes) {
-      const key = coerceKey(readPath(row, leg.field));
-      const match = key === null ? null : map.get(key) ?? null;
-      if (match === null && leg.mode === "warn") {
-        warnOnceBroadcastMiss(leg.field, leg.as, key ?? "<null>");
-      }
-      out[leg.as] = match;
-    }
-    return out;
-  });
-}
-var warnedBroadcastKeys;
-var init_cross_shard_join = __esm({
-  "src/federation/cross-shard-join.ts"() {
-    "use strict";
-    init_predicate();
-    warnedBroadcastKeys = /* @__PURE__ */ new Set();
-  }
-});
-
-// src/federation/cross-vault-live.ts
-var CrossVaultLive;
-var init_cross_vault_live = __esm({
-  "src/federation/cross-vault-live.ts"() {
-    "use strict";
-    CrossVaultLive = class {
-      snapshot;
-      error = null;
-      ready;
-      subs = /* @__PURE__ */ new Set();
-      unsubChange;
-      opts;
-      stopped = false;
-      computing = false;
-      dirty = false;
-      scheduled = false;
-      timer = null;
-      resolveReady;
-      settledOnce = false;
-      constructor(opts) {
-        this.opts = opts;
-        this.snapshot = opts.initialSnapshot;
-        this.ready = new Promise((res) => {
-          this.resolveReady = res;
-        });
-        this.unsubChange = opts.subscribeToChanges((e) => {
-          if (this.stopped || !opts.isRelevant(e)) return;
-          this.schedule();
-        });
-        this.schedule();
-      }
-      subscribe(cb) {
-        if (this.stopped) return () => {
-        };
-        this.subs.add(cb);
-        return () => this.subs.delete(cb);
-      }
-      stop() {
-        if (this.stopped) return;
-        this.stopped = true;
-        this.unsubChange();
-        if (this.timer !== null) clearTimeout(this.timer);
-        this.subs.clear();
-        if (!this.settledOnce) this.resolveReady();
-      }
-      schedule() {
-        if (this.stopped) return;
-        if (this.computing) {
-          this.dirty = true;
-          return;
-        }
-        if (this.scheduled) return;
-        this.scheduled = true;
-        const run = () => {
-          this.scheduled = false;
-          void this.runCompute();
-        };
-        const ms = this.opts.debounceMs ?? 0;
-        if (ms > 0) this.timer = setTimeout(run, ms);
-        else queueMicrotask(run);
-      }
-      async runCompute() {
-        if (this.stopped) return;
-        this.computing = true;
-        this.dirty = false;
-        try {
-          const next = await this.opts.compute();
-          if (this.stopped) return;
-          this.snapshot = next;
-          this.error = null;
-        } catch (err) {
-          if (this.stopped) return;
-          this.error = err instanceof Error ? err : new Error(String(err));
-        } finally {
-          this.computing = false;
-          if (!this.stopped) {
-            if (!this.settledOnce) {
-              this.settledOnce = true;
-              this.resolveReady();
-            }
-            for (const cb of this.subs) cb();
-            if (this.dirty) this.schedule();
-          }
-        }
-      }
-    };
-  }
-});
-
-// src/federation/aggregate-across.ts
-var CrossVaultAggregation, CrossVaultGroupedAggregation;
-var init_aggregate_across = __esm({
-  "src/federation/aggregate-across.ts"() {
-    "use strict";
-    init_aggregation();
-    init_groupby();
-    init_cross_vault_live();
-    CrossVaultAggregation = class {
-      constructor(src, spec, bind) {
-        this.src = src;
-        this.spec = spec;
-        this.bind = bind;
-      }
-      src;
-      spec;
-      bind;
-      async run(options = {}) {
-        const { records, skippedVaults } = await this.src.fanoutRecords(options);
-        return { result: reduceRecords(records, this.spec), skippedVaults };
-      }
-      live(options = {}) {
-        if (!this.bind) throw new Error("CrossVaultAggregation: live() requires a LiveBinding \u2014 use ShardedQuery.aggregate()");
-        const spec = this.spec;
-        const src = this.src;
-        const core = new CrossVaultLive({
-          subscribeToChanges: this.bind.subscribeToChanges,
-          isRelevant: this.bind.isRelevant,
-          compute: async () => {
-            const { records, skippedVaults } = await src.fanoutRecords(options);
-            return { value: reduceRecords(records, spec), skipped: skippedVaults };
-          },
-          initialSnapshot: { value: void 0, skipped: [] },
-          ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
-        });
-        return {
-          get value() {
-            return core.snapshot.value;
-          },
-          get skippedVaults() {
-            return core.snapshot.skipped;
-          },
-          get error() {
-            return core.error;
-          },
-          ready: core.ready,
-          subscribe: (cb) => core.subscribe(cb),
-          stop: () => core.stop()
-        };
-      }
-    };
-    CrossVaultGroupedAggregation = class {
-      constructor(src, field, spec, bind) {
-        this.src = src;
-        this.field = field;
-        this.spec = spec;
-        this.bind = bind;
-      }
-      src;
-      field;
-      spec;
-      bind;
-      async run(options = {}) {
-        const { records, skippedVaults } = await this.src.fanoutRecords(options);
-        return {
-          results: groupAndReduce(records, this.field, this.spec),
-          skippedVaults
-        };
-      }
-      live(options = {}) {
-        if (!this.bind) throw new Error("CrossVaultGroupedAggregation: live() requires a LiveBinding \u2014 use ShardedQuery.groupBy().aggregate()");
-        const field = this.field;
-        const spec = this.spec;
-        const src = this.src;
-        const core = new CrossVaultLive({
-          subscribeToChanges: this.bind.subscribeToChanges,
-          isRelevant: this.bind.isRelevant,
-          compute: async () => {
-            const { records, skippedVaults } = await src.fanoutRecords(options);
-            return {
-              records: groupAndReduce(records, field, spec),
-              skipped: skippedVaults
-            };
-          },
-          initialSnapshot: { records: [], skipped: [] },
-          ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
-        });
-        return {
-          get value() {
-            return core.snapshot.records;
-          },
-          get skippedVaults() {
-            return core.snapshot.skipped;
-          },
-          get error() {
-            return core.error;
-          },
-          ready: core.ready,
-          subscribe: (cb) => core.subscribe(cb),
-          stop: () => core.stop()
-        };
-      }
-    };
-  }
-});
-
-// src/federation/vault-group.ts
-var vault_group_exports = {};
-__export(vault_group_exports, {
-  ShardedCollection: () => ShardedCollection,
-  ShardedGroupedQuery: () => ShardedGroupedQuery,
-  ShardedQuery: () => ShardedQuery,
-  VaultGroup: () => VaultGroup
-});
-function assertSafePartitionKey(partitionKey) {
-  if (partitionKey.length === 0) {
-    throw new ValidationError("partitionKey must be a non-empty string");
-  }
-  if (partitionKey === STATE_VAULT_NAME) {
-    throw new ReservedVaultNameError(partitionKey);
-  }
-  if (!SAFE_PARTITION_KEY.test(partitionKey)) {
-    throw new ValidationError(
-      `partitionKey "${partitionKey}" contains characters outside [A-Za-z0-9._-]. Map your records to a store-safe key in sharding.keyOf.`
-    );
-  }
-  if (partitionKey.includes(SHARD_SEPARATOR)) {
-    throw new ValidationError(
-      `partitionKey "${partitionKey}" must not contain "--" \u2014 it is reserved as the shard vault-id separator and would risk shard-id collisions.`
-    );
-  }
-}
-var SHARD_SEPARATOR, SAFE_PARTITION_KEY, VaultGroup, ShardedCollection, ShardedQuery, ShardedGroupedQuery;
-var init_vault_group = __esm({
-  "src/federation/vault-group.ts"() {
-    "use strict";
-    init_state_vault();
-    init_errors();
-    init_constants2();
-    init_classify_skip();
-    init_cross_shard_join();
-    init_cross_vault_live();
-    init_aggregate_across();
-    SHARD_SEPARATOR = "--";
-    SAFE_PARTITION_KEY = /^[A-Za-z0-9._-]+$/;
-    VaultGroup = class {
-      constructor(db, name, registry, sharding, template, migrateOnOpen = false) {
-        this.db = db;
-        this.name = name;
-        this.registry = registry;
-        this.sharding = sharding;
-        this.template = template;
-        this.migrateOnOpen = migrateOnOpen;
-        if (name.includes(SHARD_SEPARATOR)) {
-          throw new ValidationError(
-            `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
-          );
-        }
-      }
-      db;
-      name;
-      registry;
-      sharding;
-      template;
-      migrateOnOpen;
-      /** @internal — set when the group is managed (no explicit registry). */
-      stateVault;
-      /** @internal */
-      _attachStateVault(sv) {
-        this.stateVault = sv;
-      }
-      /** Deterministic vault name for a partition key, namespaced by the group. */
-      shardVaultId(partitionKey) {
-        assertSafePartitionKey(partitionKey);
-        return `${this.name}${SHARD_SEPARATOR}${partitionKey}`;
-      }
-      /**
-       * @internal — group-qualified registry record key (avoids cross-group key
-       * collisions). Identical to the shard vault id by design — the registry row
-       * for a shard is keyed by that shard's vault id — so it delegates to
-       * `shardVaultId`, reusing its partition-key validation.
-       */
-      registryId(partitionKey) {
-        return this.shardVaultId(partitionKey);
-      }
-      /**
-       * Registry rows for THIS group (hydrates the registry collection first).
-       * The registry may be shared across groups (the auto-wired StateManagement
-       * vault holds one `vaultRegistry` for the whole instance), so rows are
-       * filtered by `group` — without this, a group's fan-out reads would leak
-       * across into other groups' shards. Mirrors the `${group}--` scoping that
-       * `liveBinding().isRelevant` already applies to the reactive path.
-       */
-      async allRows() {
-        await this.registry.list();
-        const rows = this.registry.query().toArray();
-        return rows.filter((r) => r.group === this.name);
-      }
-      /**
-       * Open an existing shard and apply the template. When `migrateOnOpen` is set
-       * (#271) and the shard's registry version is behind the template, its cutover
-       * runs inline first — so a behind shard never surfaces a stale handle.
-       */
-      async openShard(partitionKey) {
-        if (this.migrateOnOpen) {
-          const row = await this.registry.get(this.registryId(partitionKey));
-          if (row && row.schemaVersion < this.template.version) {
-            await this.migrateShard(partitionKey);
-          }
-        }
-        return this._openShardRaw(partitionKey);
-      }
-      /** @internal — open + configure with no migrate-on-open hook (used by the migration path itself to avoid recursion). */
-      async _openShardRaw(partitionKey) {
-        const vault = await this.db.openVault(this.shardVaultId(partitionKey), { create: false });
-        this.template.configure(vault);
-        return vault;
-      }
-      /**
-       * Idempotently provision a shard for `partitionKey`. Returns the
-       * configured vault handle.
-       *
-       * - row + vault present → no-op, return handle
-       * - row present, vault gone → ShardProvisioningError
-       * - row absent (vault present or not) → open-or-create, configure, write row
-       *
-       * When `region` is given (the routing `put` passes `sharding.regionOf(record)`),
-       * the candidate backend's `capabilities.region` must match or this throws
-       * `DataResidencyError` BEFORE provisioning (#271 data-residency guard).
-       */
-      async createShard(partitionKey, region) {
-        const vaultId = this.shardVaultId(partitionKey);
-        const row = await this.registry.get(this.registryId(partitionKey));
-        const provisioned = await this.db._shardVaultProvisioned(vaultId);
-        if (row && !provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
-        if (row && provisioned) return this.openShard(partitionKey);
-        if (region !== void 0) {
-          const backendRegion = this.db._resolveBackend(vaultId).capabilities?.region;
-          if (backendRegion !== region) throw new DataResidencyError(vaultId, region, backendRegion);
-        }
-        const vault = await this.db.openVault(vaultId);
-        this.template.configure(vault);
-        await this.registry.put(this.registryId(partitionKey), {
-          vaultId,
-          partitionKey,
-          templateName: this.sharding.vaultTemplate,
-          schemaVersion: this.template.version,
-          createdAt: Date.now(),
-          group: this.name
-        });
-        if (this.stateVault) {
-          try {
-            await this.stateVault.appendEvent({
-              type: "shard-created",
-              group: this.name,
-              vaultId,
-              templateName: this.sharding.vaultTemplate,
-              version: this.template.version
-            });
-          } catch {
-          }
-        }
-        return vault;
-      }
-      /**
-       * Drill down to a single shard's full Collection API. Throws if the shard is unknown.
-       * Also throws ShardProvisioningError if the registry row exists but the vault has been deleted
-       * (registry/store divergence).
-       */
-      async shard(partitionKey) {
-        const vaultId = this.shardVaultId(partitionKey);
-        const row = await this.registry.get(this.registryId(partitionKey));
-        if (!row) throw new UnknownShardError(partitionKey, this.name);
-        const provisioned = await this.db._shardVaultProvisioned(vaultId);
-        if (!provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
-        return this.openShard(partitionKey);
-      }
-      /** A sharded view over one logical collection across all shards. */
-      collection(collectionName) {
-        return new ShardedCollection(this, collectionName);
-      }
-      /** @internal — eligible (openable-candidate) rows + drift/divergence skips. */
-      async resolveEligible(options = {}) {
-        const rows = await this.allRows();
-        const skipped = [];
-        const versionOk = [];
-        for (const row of rows) {
-          if (options.minVersion !== void 0 && row.schemaVersion < options.minVersion) {
-            skipped.push({ vaultId: row.vaultId, reason: "schema-drift" });
-          } else versionOk.push(row);
-        }
-        const provisioned = await Promise.all(versionOk.map((r) => this.db._shardVaultProvisioned(r.vaultId)));
-        const eligible = [];
-        versionOk.forEach((row, i) => {
-          if (provisioned[i]) eligible.push(row);
-          else skipped.push({ vaultId: row.vaultId, reason: "error", error: new ShardProvisioningError(row.vaultId, row.partitionKey) });
-        });
-        return { eligible, skipped };
-      }
-      /** @internal — registered push-model cross-vault derivations (#271 Insight Vault). */
-      crossVaultDerivations = [];
-      /**
-       * Register a push-model cross-vault derivation — the Insight Vault pattern
-       * (#271, Layer 4). Drive it with {@link refreshInsights}.
-       *
-       * For each shard, `derive(records, ctx)` runs on that shard's `source`
-       * records and its return value is written into the analytics
-       * (`target.vault` / `target.collection`) vault, keyed by partition key —
-       * one summary row per shard. The derivation runs in-process under THIS
-       * group's `Noydb` (which already holds both the shard and Insight Vault
-       * keyrings); the shard's decrypted records are reduced to a summary that is
-       * re-encrypted under the Insight Vault's own DEK, so no shard ciphertext
-       * crosses a DEK boundary.
-       *
-       * **Zero-knowledge note:** the Insight Vault backend sees aggregated
-       * structure (totals, counts, timestamps) drawn from many shards — a weaker
-       * ZK profile than the per-shard vaults. Opt-in; keep summaries to aggregate
-       * scalars (no embeddings / no raw records).
-       *
-       * v1 is explicit-refresh (no write-path push); call `refreshInsights()`
-       * after a batch of writes, or on a schedule.
-       *
-       * The `target.vault` must NOT be the group itself or one of its shards —
-       * a summary writing back into client-shard data would breach the Insight
-       * Vault's separate-DEK-boundary contract. Such a target throws a
-       * `ValidationError` at registration (#271 Insight-write isolation).
-       */
-      withCrossVaultDerivation(spec) {
-        const target = spec.target.vault;
-        if (target === this.name || target.startsWith(`${this.name}${SHARD_SEPARATOR}`)) {
-          throw new ValidationError(
-            `withCrossVaultDerivation: target.vault "${target}" is the "${this.name}" group itself or one of its shards \u2014 an Insight summary must target a SEPARATE analytics vault, never write back into client-shard data (it would breach the per-shard DEK boundary). Use a distinct vault name.`
-          );
-        }
-        this.crossVaultDerivations.push(spec);
-      }
-      /**
-       * Run every registered {@link withCrossVaultDerivation}: read each eligible
-       * shard's source records, derive a per-shard summary, and write it into the
-       * Insight Vault keyed by partition key. Shards behind `minVersion`,
-       * unprovisioned, or whose read errors are reported in `skippedVaults` and
-       * are not written (a stale summary is never left behind for a failed shard).
-       */
-      async refreshInsights(options = {}) {
-        if (this.crossVaultDerivations.length === 0) return { written: 0, skippedVaults: [] };
-        const { eligible, skipped } = await this.resolveEligible(
-          options.minVersion !== void 0 ? { minVersion: options.minVersion } : {}
-        );
-        let written = 0;
-        for (const spec of this.crossVaultDerivations) {
-          const results = await this.db.queryAcross(
-            eligible.map((r) => r.vaultId),
-            async (vault) => {
-              this.template.configure(vault);
-              return vault.collection(spec.source).list();
-            },
-            { create: false, ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {} }
-          );
-          const insight = await this.db.openVault(spec.target.vault);
-          const out = insight.collection(spec.target.collection);
-          for (let i = 0; i < eligible.length; i++) {
-            const row = eligible[i];
-            const res = results[i];
-            if (!res || res.result === void 0) {
-              skipped.push({ vaultId: row.vaultId, reason: "error", ...res?.error ? { error: res.error } : {} });
-              continue;
-            }
-            const ctx = {
-              vaultId: row.vaultId,
-              partitionKey: row.partitionKey,
-              schemaVersion: row.schemaVersion
-            };
-            const summary = spec.derive(res.result, ctx);
-            await out.put(row.partitionKey, summary);
-            written++;
-          }
-        }
-        return { written, skippedVaults: skipped };
-      }
-      /** @internal — the control-plane vault for migration status; lazily opened. */
-      async ensureStateVault() {
-        if (!this.stateVault) this.stateVault = await StateManagementVault.open(this.db);
-        return this.stateVault;
-      }
-      /**
-       * Migrate ONE shard to the template's current version (#271 fleet runner,
-       * per-shard step). Opens the shard (applying the template, which arms the
-       * M12 cutover), drains schema-write detection, runs `vault.runSchemaCutover()`
-       * (the per-vault drain-barrier-transform protocol), then advances the
-       * registry row's `schemaVersion` and records `migration-status`. A shard
-       * already at the template version is a no-op (`status: 'done'`, migrated 0).
-       * Never throws on a cutover failure — it records `status: 'failed'` and
-       * returns the row, so a fleet run continues past a bad shard.
-       */
-      async migrateShard(partitionKey) {
-        const vaultId = this.shardVaultId(partitionKey);
-        const row = await this.registry.get(this.registryId(partitionKey));
-        if (!row) throw new UnknownShardError(partitionKey, this.name);
-        const target = this.template.version;
-        const sv = await this.ensureStateVault();
-        const base = { vaultId, group: this.name, currentVersion: row.schemaVersion, targetVersion: target };
-        if (row.schemaVersion >= target) {
-          const done = { ...base, status: "done", migrated: 0, finishedAt: Date.now() };
-          await sv.upsertMigrationStatus(done);
-          return done;
-        }
-        await sv.upsertMigrationStatus({ ...base, status: "running", startedAt: Date.now() });
-        try {
-          await sv.appendEvent({ type: "migration-started", group: this.name, vaultId, version: target });
-        } catch {
-        }
-        try {
-          const vault = await this._openShardRaw(partitionKey);
-          await vault._drainPendingSchemaWrites();
-          const { migrated } = await vault.runSchemaCutover();
-          await this.registry.put(this.registryId(partitionKey), { ...row, schemaVersion: target });
-          const done = { ...base, currentVersion: target, status: "done", migrated, finishedAt: Date.now() };
-          await sv.upsertMigrationStatus(done);
-          try {
-            await sv.appendEvent({ type: "migration-completed", group: this.name, vaultId, version: target });
-          } catch {
-          }
-          return done;
-        } catch (err) {
-          const error = err instanceof Error ? err.message : String(err);
-          const failed = { ...base, status: "failed", error, finishedAt: Date.now() };
-          await sv.upsertMigrationStatus(failed);
-          try {
-            await sv.appendEvent({ type: "migration-failed", group: this.name, vaultId, version: target, detail: error });
-          } catch {
-          }
-          return failed;
-        }
-      }
-      /**
-       * Active batch runner (#271): migrate every shard behind the template version
-       * to it, in controlled batches. **Resumable + crash-safe** — shards already at
-       * the target are skipped (the registry version is the source of truth), so a
-       * re-run after a crash only picks up the unfinished + previously-failed shards.
-       *
-       * - `cohort` — restrict to these partition keys (the staged / canary rollout:
-       *   migrate a small cohort, verify the Insight Vault, then run the rest).
-       * - `batchSize` — max shards migrated concurrently per batch (back-pressure).
-       *   Default 4. Batches run sequentially; shards within a batch run in parallel.
-       */
-      async migrateFleet(options = {}) {
-        const target = this.template.version;
-        const rows = await this.allRows();
-        const cohort = options.cohort;
-        const todo = rows.filter(
-          (r) => r.schemaVersion < target && (cohort === void 0 || cohort.includes(r.partitionKey))
-        );
-        const batchSize = Math.max(1, options.batchSize ?? 4);
-        const migrated = [];
-        const failed = [];
-        for (let i = 0; i < todo.length; i += batchSize) {
-          const batch = todo.slice(i, i + batchSize);
-          const settled = await Promise.all(batch.map((r) => this.migrateShard(r.partitionKey)));
-          for (const res of settled) {
-            if (res.status === "done") migrated.push(res.vaultId);
-            else failed.push({ vaultId: res.vaultId, error: res.error ?? "unknown" });
-          }
-        }
-        return { target, migrated, failed };
-      }
-    };
-    ShardedCollection = class {
-      constructor(group, collectionName) {
-        this.group = group;
-        this.collectionName = collectionName;
-      }
-      group;
-      collectionName;
-      /** Route a write to the shard owning `keyOf(record)`. */
-      async put(id, record) {
-        const key = this.group.sharding.keyOf(record);
-        const row = await this.group.registry.get(this.group.registryId(key));
-        let vault;
-        if (!row) {
-          if (this.group.sharding.autoCreate === false) {
-            throw new UnknownShardError(key, this.group.name);
-          }
-          vault = await this.group.createShard(key, this.group.sharding.regionOf?.(record));
-        } else {
-          vault = await this.group.openShard(key);
-        }
-        await vault.collection(this.collectionName).put(id, record);
-      }
-      /** Begin a cross-shard fan-out query. */
-      query() {
-        return new ShardedQuery(this.group, this.collectionName, []);
-      }
-    };
-    ShardedQuery = class _ShardedQuery {
-      constructor(group, collectionName, clauses, coPartitionedLegs = [], broadcastLegs = []) {
-        this.group = group;
-        this.collectionName = collectionName;
-        this.clauses = clauses;
-        this.coPartitionedLegs = coPartitionedLegs;
-        this.broadcastLegs = broadcastLegs;
-      }
-      group;
-      collectionName;
-      clauses;
-      coPartitionedLegs;
-      broadcastLegs;
-      where(field, op, value) {
-        return new _ShardedQuery(
-          this.group,
-          this.collectionName,
-          [...this.clauses, { field, op, value }],
-          this.coPartitionedLegs,
-          this.broadcastLegs
-        );
-      }
-      /** Co-partitioned join: each shard joins its own same-vault right collection (resolved via ref()), then union. */
-      crossShardJoin(field, opts) {
-        const leg = { field, as: opts.as, maxRows: opts.maxRows, strategy: opts.strategy };
-        return new _ShardedQuery(
-          this.group,
-          this.collectionName,
-          this.clauses,
-          [...this.coPartitionedLegs, leg],
-          this.broadcastLegs
-        );
-      }
-      /** Broadcast dimension join: enrich every merged row from a single shared collection. */
-      broadcastJoin(field, opts) {
-        const leg = {
-          field,
-          as: opts.as,
-          from: opts.from,
-          on: opts.on ?? "id",
-          mode: opts.mode ?? "warn"
-        };
-        return new _ShardedQuery(
-          this.group,
-          this.collectionName,
-          this.clauses,
-          this.coPartitionedLegs,
-          [...this.broadcastLegs, leg]
-        );
-      }
-      /** @internal — fan out the where-filtered records across eligible shards. */
-      async fanoutRecords(options = {}) {
-        const { eligible, skipped } = await this.group.resolveEligible(options);
-        const probeRow = eligible[0];
-        if (this.coPartitionedLegs.length > 0 && probeRow) {
-          const probe = await this.group.openShard(probeRow.partitionKey);
-          this.group.template.configure(probe);
-          for (const leg of this.coPartitionedLegs) {
-            if (!probe.resolveRef(this.collectionName, leg.field)) {
-              throw new CrossShardJoinError(
-                `crossShardJoin("${leg.field}"): no ref() declared for "${leg.field}" on collection "${this.collectionName}" in template "${this.group.sharding.vaultTemplate}". Add refs: { ${leg.field}: ref('<target>') } to the template's collection options.`
-              );
-            }
-          }
-        }
-        const across = await this.group.db.queryAcross(
-          eligible.map((r) => r.vaultId),
-          async (vault) => {
-            this.group.template.configure(vault);
-            const coll = vault.collection(this.collectionName);
-            await coll.list();
-            for (const leg of this.coPartitionedLegs) {
-              const desc = vault.resolveRef(this.collectionName, leg.field);
-              if (desc) await vault.collection(desc.target).list();
-            }
-            let q = coll.query();
-            for (const c of this.clauses) q = q.where(c.field, c.op, c.value);
-            for (const leg of this.coPartitionedLegs) {
-              q = q.join(leg.field, {
-                as: leg.as,
-                ...leg.maxRows !== void 0 ? { maxRows: leg.maxRows } : {},
-                ...leg.strategy ? { strategy: leg.strategy } : {}
-              });
-            }
-            return q.toArray();
-          },
-          { concurrency: options.concurrency ?? 1, create: false }
-        );
-        const results = [];
-        for (const r of across) {
-          if (r.error) skipped.push({ vaultId: r.vault, reason: classifyShardSkip(r.error), error: r.error });
-          else for (const item of r.result) results.push(item);
-        }
-        return { records: results, skippedVaults: skipped };
-      }
-      /** Fan out across eligible shards, merge, then apply any broadcast dimension legs. */
-      async toArray(options = {}) {
-        const { records, skippedVaults } = await this.fanoutRecords(options);
-        const results = await applyBroadcastLegs(records, this.broadcastLegs);
-        return { results, skippedVaults };
-      }
-      /** @internal — build the change-subscription + relevance binding for this query's group+collection. */
-      liveBinding() {
-        const group = this.group;
-        const collectionName = this.collectionName;
-        return {
-          subscribeToChanges: (h) => {
-            group.db.on("change", h);
-            return () => group.db.off("change", h);
-          },
-          isRelevant: (e) => e.collection === collectionName && e.vault.startsWith(`${group.name}--`)
-        };
-      }
-      /** @internal — joined queries don't support reactive/aggregate surfaces in v1. */
-      assertNoJoinLegs(surface) {
-        if (this.coPartitionedLegs.length || this.broadcastLegs.length) {
-          throw new CrossShardJoinError(
-            `${surface}() is not supported on a ShardedQuery with crossShardJoin/broadcastJoin legs in v1. Use toArray() for joined cross-shard queries.`
-          );
-        }
-      }
-      /** Returns a reactive cross-shard live query — a facade over CrossVaultLive. */
-      live(options = {}) {
-        this.assertNoJoinLegs("live");
-        const bind = this.liveBinding();
-        const core = new CrossVaultLive({
-          ...bind,
-          compute: async () => {
-            const { records, skippedVaults } = await this.fanoutRecords(options);
-            return { records, skipped: skippedVaults };
-          },
-          initialSnapshot: { records: [], skipped: [] },
-          ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
-        });
-        return {
-          get value() {
-            return core.snapshot.records;
-          },
-          get skippedVaults() {
-            return core.snapshot.skipped;
-          },
-          get error() {
-            return core.error;
-          },
-          ready: core.ready,
-          subscribe: (cb) => core.subscribe(cb),
-          stop: () => core.stop()
-        };
-      }
-      /** One-shot distributed aggregate — central reduce over all shard records. */
-      aggregate(spec) {
-        this.assertNoJoinLegs("aggregate");
-        return new CrossVaultAggregation(this, spec, this.liveBinding());
-      }
-      /** Begin a grouped cross-shard aggregate. */
-      groupBy(field) {
-        this.assertNoJoinLegs("groupBy");
-        return new ShardedGroupedQuery(this, field);
-      }
-    };
-    ShardedGroupedQuery = class {
-      constructor(query, field) {
-        this.query = query;
-        this.field = field;
-      }
-      query;
-      field;
-      aggregate(spec) {
-        return new CrossVaultGroupedAggregation(
-          { fanoutRecords: (o) => this.query.fanoutRecords(o) },
-          this.field,
-          spec,
-          this.query.liveBinding()
-        );
-      }
-    };
-  }
-});
-
 // src/noydb.ts
 var noydb_exports = {};
 __export(noydb_exports, {
@@ -21873,7 +21037,6 @@ var init_noydb = __esm({
   "src/noydb.ts"() {
     "use strict";
     init_errors();
-    init_constants2();
     init_storage3();
     init_rotate_recover();
     init_peer_recover();
@@ -21907,6 +21070,12 @@ var init_noydb = __esm({
       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
     };
@@ -21955,7 +21124,6 @@ var init_noydb = __esm({
       writeRelay;
       /** Per-vault policy enforcers. */
       policyEnforcers = /* @__PURE__ */ new Map();
-      vaultTemplates = /* @__PURE__ */ new Map();
       txStrategy;
       forgetStrategy;
       sessionStrategy;
@@ -22405,6 +21573,37 @@ var init_noydb = __esm({
         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:
@@ -22674,52 +21873,12 @@ var init_noydb = __esm({
         return results;
       }
       /**
-       * Register a shard schema blueprint. `createShard` / `openVaultGroup`
-       * stamp shards from the named template. See the MVF design spec.
-       */
-      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: VaultGroup2 } = await Promise.resolve().then(() => (init_vault_group(), vault_group_exports));
-        const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
-        const stateVault = opts.registry ? void 0 : await StateManagementVault2.open(this);
-        const registry = opts.registry ?? stateVault.registry;
-        const group = new VaultGroup2(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.
+       * @internal True once `close()` has been called. Read by outward
+       * orchestration frameworks whose entry points can't see the private
+       * `closed` field.
        */
-      async openStateManagementVault() {
-        if (this.closed) throw new ValidationError("Instance is closed");
-        const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
-        return StateManagementVault2.open(this);
+      get isClosed() {
+        return this.closed;
       }
       /**
        * @internal — true when an encrypted shard vault is provisioned
@@ -24215,6 +23374,7 @@ __export(bundle_exports, {
   TransferSealError: () => TransferSealError,
   adoptPartition: () => adoptPartition,
   createOwnerOnAdoptedPartition: () => createOwnerOnAdoptedPartition,
+  decryptExtractedPartition: () => decryptExtractedPartition,
   describeExtraction: () => describeExtraction,
   encodeBundleHeader: () => encodeBundleHeader,
   extractPartition: () => extractPartition,
@@ -24388,7 +23548,7 @@ init_constants();
 init_entry();
 init_hash();
 init_bundle();
-async function reKeyClosure(vault, closure) {
+async function reKeyClosure(vault, closure, fieldProjection) {
   const { name: vaultName, adapter, getDEK } = vault._introspectState();
   const collections = {};
   const deks = /* @__PURE__ */ new Map();
@@ -24397,29 +23557,40 @@ async function reKeyClosure(vault, closure) {
     const destDek = await generateDEK();
     deks.set(collectionName, destDek);
     const out = {};
+    const projList = fieldProjection?.[collectionName];
+    const proj = projList ? new Set(projList) : void 0;
+    const project = (plaintext) => {
+      if (!proj) return plaintext;
+      const rec = JSON.parse(plaintext);
+      const kept = {};
+      if ("id" in rec) kept["id"] = rec["id"];
+      for (const f of proj) if (f in rec) kept[f] = rec[f];
+      return JSON.stringify(kept);
+    };
     for (const id of ids) {
       const env = await adapter.get(vaultName, collectionName, id);
       if (!env) continue;
       if (env._cek !== void 0) {
         const cek = await unwrapCek(env._cek, srcDek);
         const plaintext2 = await decrypt(env._iv, env._data, cek);
-        const { iv: iv2, data: data2 } = await encrypt(plaintext2, cek);
+        const { iv: iv2, data: data2 } = await encrypt(project(plaintext2), cek);
         const wrapped = await wrapCek(cek, destDek);
         out[id] = { ...env, _iv: iv2, _data: data2, _cek: wrapped };
         continue;
       }
       const plaintext = await decrypt(env._iv, env._data, srcDek);
-      const { iv, data } = await encrypt(plaintext, destDek);
+      const { iv, data } = await encrypt(project(plaintext), destDek);
       out[id] = { ...env, _iv: iv, _data: data };
     }
     collections[collectionName] = out;
   }
   return { collections, deks };
 }
-async function reKeySchemas(vault, closure, destDeks) {
+async function reKeySchemas(vault, closure, destDeks, fieldProjection) {
   const { name: vaultName, adapter, getDEK } = vault._introspectState();
   const out = {};
   for (const collectionName of closure.keys()) {
+    if (fieldProjection?.[collectionName]) continue;
     const env = await adapter.get(vaultName, SCHEMAS_COLLECTION, collectionName);
     if (!env) continue;
     const destDek = destDeks.get(collectionName);
@@ -24511,6 +23682,11 @@ async function sealDeks(deks) {
   };
 }
 async function extractPartition(vault, opts) {
+  if (vault.role === "custodian") {
+    throw new PartitionExtractionError(
+      "extractPartition is owner-only; a custodian cannot extract-and-sever (FR-6: producing a re-keyed standalone partition is an ownership operation; use the Deed owner)."
+    );
+  }
   if (vault.role !== "owner") {
     throw new PartitionExtractionError(
       `extractPartition requires the 'owner' role on the source vault; caller is '${vault.role}'. Producing a re-keyed standalone partition is an ownership operation.`
@@ -24518,7 +23694,7 @@ async function extractPartition(vault, opts) {
   }
   if (opts.carrySchemas) await vault._drainPendingSchemaWrites();
   const { closure } = await walkClosure(vault, opts);
-  const { collections, deks } = await reKeyClosure(vault, closure);
+  const { collections, deks } = await reKeyClosure(vault, closure, opts.fieldProjection);
   let ledgerHead;
   let ledgerEntries;
   if (opts.carryLedger && vault._getLedgerOrNull() !== null) {
@@ -24530,7 +23706,7 @@ async function extractPartition(vault, opts) {
       deks.set(LEDGER_COLLECTION, ledgerDek);
     }
   }
-  const internalSchemas = opts.carrySchemas ? await reKeySchemas(vault, closure, deks) : {};
+  const internalSchemas = opts.carrySchemas ? await reKeySchemas(vault, closure, deks, opts.fieldProjection) : {};
   const internal = {};
   if (Object.keys(internalSchemas).length > 0) internal[SCHEMAS_COLLECTION] = internalSchemas;
   if (ledgerEntries) internal[LEDGER_COLLECTION] = ledgerEntries;
@@ -24745,6 +23921,41 @@ async function createOwnerOnAdoptedPartition(store, vaultName, opts) {
   return { vaultName, userId };
 }
 
+// src/bundle/decrypt-partition.ts
+init_crypto();
+init_record_keys();
+init_bundle();
+async function decryptExtractedPartition(bundleBytes, transferKey) {
+  const header = readNoydbBundleHeader(bundleBytes);
+  if (header.bundleKind !== "extracted-partition" || header.transferSeal === void 0) {
+    throw new Error("decryptExtractedPartition: bundle is not an extracted-partition.");
+  }
+  const { dumpJson } = await readNoydbBundle(bundleBytes);
+  const { dump, seal } = parseExtractedPartitionBody(dumpJson);
+  const deks = await unsealDeks(seal, transferKey);
+  const backup = JSON.parse(dump);
+  const out = {};
+  for (const [collection, byId] of Object.entries(backup.collections)) {
+    const dek = deks.get(collection);
+    if (dek === void 0) continue;
+    const recs = [];
+    for (const [id, env] of Object.entries(byId)) {
+      const plaintext = env._cek !== void 0 ? await decrypt(env._iv, env._data, await unwrapCek(env._cek, dek)) : await decrypt(env._iv, env._data, dek);
+      const body = JSON.parse(plaintext);
+      recs.push({
+        id,
+        record: { ...body, id },
+        ts: env._ts,
+        version: env._v,
+        ...env._source !== void 0 ? { source: env._source } : {},
+        ...env._sourceTs !== void 0 ? { sourceTs: env._sourceTs } : {}
+      });
+    }
+    out[collection] = recs;
+  }
+  return out;
+}
+
 // src/bundle/index.ts
 init_errors();
 init_errors();
@@ -24768,6 +23979,7 @@ init_errors();
   TransferSealError,
   adoptPartition,
   createOwnerOnAdoptedPartition,
+  decryptExtractedPartition,
   describeExtraction,
   encodeBundleHeader,
   extractPartition,