@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.3

package/dist/{chunk-E535SAN4.js → chunk-T6HQMVML.js}

@@ -4,34 +4,34 @@ import {
 import {
   TxContext,
   revertExecuted
-} from "./chunk-3Z2TPHC4.js";
+} from "./chunk-GVXBHCZ2.js";
 import {
   OverlayedCollection
-} from "./chunk-YTXSFG3C.js";
+} from "./chunk-NGSPBLLE.js";
 import {
   LazyQuery,
   decodeIdxId,
   encodeIdxId
-} from "./chunk-7BRE6EUA.js";
+} from "./chunk-WRLHNG6H.js";
 import {
   SCHEMAS_COLLECTION,
   loadPersistedSchema,
   resolveManagedSecret,
   savePersistedSchema,
   saveSealedPassphrase
-} from "./chunk-UND4XIB6.js";
+} from "./chunk-4X2S7PBF.js";
 import {
   loadPublicEnvelope,
   readPublicEnvelope,
   savePublicEnvelope,
   validatePublicEnvelopeInput
-} from "./chunk-243PNUA6.js";
+} from "./chunk-FS7A4XNF.js";
 import {
   PERIODS_COLLECTION
-} from "./chunk-QPEXPHJR.js";
+} from "./chunk-GAUBWHAF.js";
 import {
   isDictCollectionName
-} from "./chunk-LRAZDV5X.js";
+} from "./chunk-KMI2NBBF.js";
 import {
   ManagedRecoveryNotEnrolledError,
   PolicyDeniedError,
@@ -53,11 +53,11 @@ import {
   saveShamirRecoveryEntries,
   updateAuthenticator,
   writeMagicLinkGrant
-} from "./chunk-EUYOGYGV.js";
+} from "./chunk-2EYC3WDT.js";
 import {
   assertTierAccess,
   dekKey
-} from "./chunk-7BUTTVMR.js";
+} from "./chunk-6S3LLAQ5.js";
 import {
   USER_ENVELOPE_COLLECTION,
   buildRecipientKeyringFile,
@@ -81,7 +81,7 @@ import {
   rotateKeys,
   saveUserEnvelope,
   updateKeyringIdentity
-} from "./chunk-Q6W2CMEJ.js";
+} from "./chunk-TLFUDXVV.js";
 import {
   INDEXED_STORE_POLICY
 } from "./chunk-2QR2PQTT.js";
@@ -91,30 +91,30 @@ import {
 import {
   LEDGER_COLLECTION,
   LEDGER_DELTAS_COLLECTION
-} from "./chunk-7Z23ZFLV.js";
+} from "./chunk-74JEQFMT.js";
 import {
   sha256Hex as sha256Hex2
-} from "./chunk-XG3PTSCD.js";
+} from "./chunk-NCO2JGKK.js";
 import {
   NO_AGGREGATE,
   Query,
   ScanBuilder
-} from "./chunk-J4KLMEUL.js";
+} from "./chunk-4UBOTYP5.js";
 import {
   EXPORT_AUDIT_COLLECTION,
   createExportBlobsHandle,
   runCompaction
-} from "./chunk-PFSNOPBQ.js";
+} from "./chunk-LOL725S4.js";
 import {
   NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION
-} from "./chunk-YS3POABP.js";
+} from "./chunk-FXQYZNOW.js";
 import {
   decrypt,
   encrypt,
   encryptDeterministic,
   sha256Hex
-} from "./chunk-2PAQNPE3.js";
+} from "./chunk-UOF74WQY.js";
 import {
   AlreadyElevatedError,
   AttestationError,
@@ -127,18 +127,21 @@ import {
   IndexWriteFailureError,
   InvalidKeyError,
   KeyringCorruptError,
+  MigrationRequiredError,
   NoAccessError,
   NoydbError,
   PermissionDeniedError,
+  QuiesceTimeoutError,
   ReadOnlyError,
   ReservedCollectionNameError,
+  SchemaFenceError,
   SchemaValidationError,
   StoreCapabilityError,
   TierDemoteDeniedError,
   TierNotGrantedError,
   TranslatorNotConfiguredError,
   ValidationError
-} from "./chunk-W3XXT26A.js";
+} from "./chunk-YDLAFP36.js";
 
 // src/policy/storage.ts
 var META_COLLECTION = "_meta";
@@ -641,7 +644,7 @@ async function resolveStaleOnRead(accessor, outputCollection, id) {
     }
     const sourceWithId = { ...source, id };
     if (DerivationExecutor === null) {
-      ({ DerivationExecutor } = await import("./executor-HLXFXNFM.js"));
+      ({ DerivationExecutor } = await import("./executor-GFZFDQXV.js"));
     }
     const ctx = { vault: accessor.getReadOnlyFacade() };
     const result = await DerivationExecutor.run(spec, sourceWithId, 0, strategyHash, ctx);
@@ -695,6 +698,11 @@ var Collection = class {
   keyring;
   encrypted;
   emitter;
+  writeQueue;
+  schemaUpdateGate;
+  schemaFence;
+  writeHooks;
+  activeTxId;
   getDEK;
   onDirty;
   historyConfig;
@@ -969,6 +977,11 @@ var Collection = class {
     this.keyring = opts.keyring;
     this.encrypted = opts.encrypted;
     this.emitter = opts.emitter;
+    this.writeQueue = opts.writeQueue;
+    this.schemaUpdateGate = opts.schemaUpdateGate;
+    this.schemaFence = opts.schemaFence;
+    this.writeHooks = opts.writeHooks;
+    this.activeTxId = opts.activeTxId;
     this.blobStrategy = opts.blobStrategy ?? NO_BLOBS;
     this.aggregateStrategy = opts.aggregateStrategy ?? NO_AGGREGATE;
     this.crdtStrategy = opts.crdtStrategy ?? NO_CRDT;
@@ -1127,7 +1140,7 @@ var Collection = class {
       }
     }
     if (this.materializedViewSource !== void 0) {
-      const { resolveStaleMVOnRead } = await import("./stale-OTOF3FH7.js");
+      const { resolveStaleMVOnRead } = await import("./stale-PAGCS4K5.js");
       await resolveStaleMVOnRead(this.materializedViewSource, this.name);
     }
     let record;
@@ -1194,7 +1207,8 @@ var Collection = class {
     return this.syncStrategy.buildPresence(presenceOpts);
   }
   /**
-   * Create or update a record.
+   * Create or update a record. Runs inside the hub's write-queue tracker
+   * (#227) so `hub.writeQueue.pending` reflects this write.
    *
    * @param id      Record identifier.
    * @param record  The record body (validated by the collection's schema
@@ -1205,6 +1219,59 @@ var Collection = class {
    *                `entries.filter(e => e.reason?.startsWith('import:'))`.
    */
   async put(id, record, options) {
+    await this.schemaUpdateGate?.assertWritable();
+    await this.schemaFence?.assertWritable(this.name);
+    let event;
+    if (this.#hooksActive()) {
+      const prior = await this.#priorForHook(id);
+      event = {
+        op: prior.record === null ? "create" : "update",
+        vault: this.vault,
+        collection: this.name,
+        docId: id,
+        before: prior.record,
+        after: record,
+        userId: this.keyring.userId,
+        timestamp: Date.now(),
+        txId: this.#txIdForHook(),
+        baseVersion: prior.version,
+        version: prior.version + 1
+      };
+      await this.writeHooks.runBefore(event);
+    }
+    if (this.writeQueue) await this.writeQueue.track(() => this.putInternal(id, record, options));
+    else await this.putInternal(id, record, options);
+    if (event) await this.writeHooks.runAfter(event);
+  }
+  /** @internal #230 — 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;
+  }
+  /**
+   * @internal #230/#228c — resolve the prior record for a hook's `before` and
+   * its version. Critically, this uses the SAME basis `putInternal` writes from
+   * (the in-memory cache in eager mode; lru-then-adapter in lazy) — NOT a fresh
+   * store read — so `baseVersion`/`version` match the version actually written.
+   * A separate store read would diverge once another tab has advanced the shared
+   * store past this tab's cache, breaking #228c conflict detection.
+   */
+  async #priorForHook(id) {
+    if (this.lazy && this.lru) {
+      const cached2 = this.lru.get(id);
+      if (cached2) return { record: cached2.record, version: cached2.version };
+      const env = await this.adapter.get(this.vault, this.name, id);
+      if (!env) return { record: null, version: 0 };
+      return { record: await this.decryptRecord(env, { skipValidation: true }), version: env._v };
+    }
+    await this.ensureHydrated();
+    const cached = this.cache.get(id);
+    return cached ? { record: cached.record, version: cached.version } : { record: null, version: 0 };
+  }
+  #txIdForHook() {
+    return this.activeTxId?.() ?? generateULID();
+  }
+  /** @internal Untracked put body — call {@link put}, not this. */
+  async putInternal(id, record, options) {
     if (!hasWritePermission(this.keyring, this.name)) {
       throw new ReadOnlyError();
     }
@@ -1233,7 +1300,7 @@ var Collection = class {
           registry.collectChange(this.name, id, existingRecord, incomingRecord, vBefore, vBefore + 1);
         } else {
           await registry.runChecks(this.name, incomingRecord, ctx);
-          const { GuardExecutor } = await import("./executor-HN6YBHZ5.js");
+          const { GuardExecutor } = await import("./executor-BZKFZVRC.js");
           for (const g of guards) {
             await GuardExecutor.checkFrozenFields(g, id, existingRecord, incomingRecord);
           }
@@ -1462,7 +1529,7 @@ var Collection = class {
       if (mode === "eager") {
         if (executor === null) {
           ;
-          ({ MaterializedViewExecutor: executor } = await import("./executor-AS2IDHKZ.js"));
+          ({ MaterializedViewExecutor: executor } = await import("./executor-KT2IOZVP.js"));
         }
         await executor.refresh(reg, {
           getCollection: (name) => this.materializedViewSource.getCollection(name),
@@ -1471,7 +1538,7 @@ var Collection = class {
         });
       } else if (mode === "lazy") {
         if (staleHelpers === null) {
-          staleHelpers = await import("./stale-OTOF3FH7.js");
+          staleHelpers = await import("./stale-PAGCS4K5.js");
         }
         staleHelpers.markMVStale(registry, reg.spec.name);
       }
@@ -1500,7 +1567,7 @@ var Collection = class {
       const mode = typeof spec.lifecycle === "string" ? spec.lifecycle : spec.lifecycle.mode;
       if (mode === "eager") {
         if (DerivationExecutor === null) {
-          ({ DerivationExecutor } = await import("./executor-HLXFXNFM.js"));
+          ({ DerivationExecutor } = await import("./executor-GFZFDQXV.js"));
         }
         const sourceWithId = { ...incoming, id };
         const ctx = { vault: this.derivationSource.getReadOnlyFacade() };
@@ -1519,7 +1586,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-VJ52RIEY.js");
+            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-NRBWSLRK.js");
             const prior = await loadFanoutSidecar(
               this.adapter,
               this.vault,
@@ -1581,8 +1648,71 @@ var Collection = class {
       }
     }
   }
-  /** Delete a record by ID. */
+  /**
+   * Delete a record by ID. Runs inside the hub's write-queue tracker
+   * (#227) so `hub.writeQueue.pending` reflects this write.
+   */
   async delete(id) {
+    await this.schemaUpdateGate?.assertWritable();
+    await this.schemaFence?.assertWritable(this.name);
+    let event;
+    if (this.#hooksActive()) {
+      const prior = await this.#priorForHook(id);
+      event = {
+        op: "delete",
+        vault: this.vault,
+        collection: this.name,
+        docId: id,
+        before: prior.record,
+        after: null,
+        userId: this.keyring.userId,
+        timestamp: Date.now(),
+        txId: this.#txIdForHook(),
+        baseVersion: prior.version,
+        version: prior.version + 1
+      };
+      await this.writeHooks.runBefore(event);
+    }
+    if (this.writeQueue) await this.writeQueue.track(() => this.deleteInternal(id));
+    else await this.deleteInternal(id);
+    if (event) await this.writeHooks.runAfter(event);
+  }
+  /**
+   * @internal #232 — bulk-rewrite every record through a cutover transform.
+   * Raw adapter path (bypasses the write gate + guards — the transform is
+   * trusted and runs only during the `migrating` phase). Bumps each
+   * record's `_v` and appends a ledger `op:'migration'` entry.
+   */
+  async _applyCutoverTransform(transform) {
+    const ids = await this.adapter.list(this.vault, this.name);
+    let count = 0;
+    for (const id of ids) {
+      const env = await this.adapter.get(this.vault, this.name, id);
+      if (!env) continue;
+      const record = await this.decryptRecord(env, { skipValidation: true });
+      const next = transform(record);
+      const nextVersion = (env._v ?? 0) + 1;
+      const newEnv = await this.encryptRecord(next, nextVersion);
+      await this.adapter.put(this.vault, this.name, id, newEnv);
+      await this._invalidateCacheEntry(id);
+      if (this.ledger) {
+        await this.ledger.append({
+          op: "migration",
+          collection: this.name,
+          id,
+          version: nextVersion,
+          actor: this.keyring.userId,
+          payloadHash: "",
+          reason: "schema:coordinated-cutover"
+        }).catch(() => {
+        });
+      }
+      count++;
+    }
+    return count;
+  }
+  /** @internal Untracked delete body — call {@link delete}, not this. */
+  async deleteInternal(id) {
     await this._doDelete(id, false);
   }
   /**
@@ -1775,7 +1905,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-VJ52RIEY.js");
+          helpers = await import("./fanout-sidecar-NRBWSLRK.js");
         }
         const sidecar = await helpers.loadFanoutSidecar(
           this.adapter,
@@ -1815,7 +1945,7 @@ var Collection = class {
       if (mode === "eager") {
         if (executor === null) {
           ;
-          ({ MaterializedViewExecutor: executor } = await import("./executor-AS2IDHKZ.js"));
+          ({ MaterializedViewExecutor: executor } = await import("./executor-KT2IOZVP.js"));
         }
         await executor.refresh(reg, {
           getCollection: (name) => this.materializedViewSource.getCollection(name),
@@ -1824,7 +1954,7 @@ var Collection = class {
         });
       } else if (mode === "lazy") {
         if (staleHelpers === null) {
-          staleHelpers = await import("./stale-OTOF3FH7.js");
+          staleHelpers = await import("./stale-PAGCS4K5.js");
         }
         staleHelpers.markMVStale(registry, reg.spec.name);
       }
@@ -1847,7 +1977,7 @@ var Collection = class {
       );
     }
     if (this.materializedViewSource !== void 0) {
-      const { resolveStaleMVOnRead } = await import("./stale-OTOF3FH7.js");
+      const { resolveStaleMVOnRead } = await import("./stale-PAGCS4K5.js");
       await resolveStaleMVOnRead(this.materializedViewSource, this.name);
     }
     await this.ensureHydrated();
@@ -2405,6 +2535,21 @@ var Collection = class {
     this.cache.set(id, { record, version: envelope._v });
     this.indexes?.upsert(id, record, previous ? previous.record : null);
   }
+  /**
+   * #228b — apply a peer tab's committed write to THIS tab's in-memory view:
+   * re-read the (already-persisted) envelope from the shared store + refresh
+   * cache/indexes, then emit a `change` event so reactive consumers re-render.
+   * Never writes to the store and never fires write hooks, so it cannot loop.
+   */
+  async _applyRemoteChange(id, action) {
+    await this._invalidateCacheEntry(id);
+    this.emitter.emit("change", { vault: this.vault, collection: this.name, id, action });
+  }
+  /** @internal #228c — the current in-memory record without a store read (for conflict capture). */
+  _peekCached(id) {
+    const entry = this.lazy && this.lru ? this.lru.get(id) : this.cache.get(id);
+    return entry ? entry.record : null;
+  }
   async ensureHydrated() {
     if (this.hydrated) return;
     const ids = await this.adapter.list(this.vault, this.name);
@@ -3802,15 +3947,68 @@ async function derivePersistedSchema(validator) {
   };
 }
 
+// src/schema-update/delta.ts
+function computeSchemaDelta(stored, fresh, collection) {
+  const a = stored;
+  const b = fresh;
+  const aProps = a.properties ?? {};
+  const bProps = b.properties ?? {};
+  const aReq = new Set(a.required ?? []);
+  const bReq = new Set(b.required ?? []);
+  const aKeys = Object.keys(aProps);
+  const bKeys = Object.keys(bProps);
+  const added = bKeys.filter((k) => !(k in aProps));
+  const removed = aKeys.filter((k) => !(k in bProps));
+  const changed = [];
+  for (const k of bKeys) {
+    if (!(k in aProps)) continue;
+    const shapeChanged = canonicalize(aProps[k]) !== canonicalize(bProps[k]);
+    const requiredChanged = aReq.has(k) !== bReq.has(k);
+    if (shapeChanged || requiredChanged) {
+      changed.push({ field: k, requiredChanged, shapeChanged });
+    }
+  }
+  let kind;
+  if (added.length === 0 && removed.length === 0 && changed.length === 0) {
+    kind = "none";
+  } else if (removed.length === 0 && changed.length === 0 && added.every((k) => !bReq.has(k))) {
+    kind = "additive";
+  } else {
+    kind = "non-additive";
+  }
+  return { collection, kind, added, removed, changed };
+}
+
+// src/schema-update/dispatch.ts
+async function evaluateStrategies(delta, strategies, ctx) {
+  for (const strategy of strategies) {
+    const decision = await strategy.onSchemaDelta(delta, ctx);
+    if (decision.action !== "allow") return decision;
+  }
+  return { action: "allow" };
+}
+
 // src/persisted-schemas/register.ts
 async function persistSchemaIfNeeded(opts) {
   const fresh = await derivePersistedSchema(opts.validator);
   const stored = await loadPersistedSchema(opts.store, opts.vault, opts.collectionName, opts.dek);
   if (stored && isEquivalent(stored, fresh)) {
-    return { written: false, skipped: true, envelope: stored };
+    return { written: false, skipped: true, envelope: stored, decision: { action: "allow" } };
+  }
+  let decision = { action: "allow" };
+  const strategies = opts.strategies ?? [];
+  if (stored && strategies.length > 0 && stored.kind === fresh.kind && isPlainObject2(stored.jsonSchema) && isPlainObject2(fresh.jsonSchema)) {
+    const delta = computeSchemaDelta(stored.jsonSchema, fresh.jsonSchema, opts.collectionName);
+    decision = await evaluateStrategies(delta, strategies, { collection: opts.collectionName });
+  }
+  if (decision.action !== "allow") {
+    return { written: false, skipped: false, envelope: stored ?? fresh, decision };
   }
   await savePersistedSchema(opts.store, opts.vault, opts.collectionName, opts.dek, fresh);
-  return { written: true, skipped: false, envelope: fresh };
+  return { written: true, skipped: false, envelope: fresh, decision };
+}
+function isPlainObject2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 function isEquivalent(a, b) {
   if (a.kind !== b.kind) return false;
@@ -3819,6 +4017,254 @@ function isEquivalent(a, b) {
   return false;
 }
 
+// src/schema-update/gate.ts
+var SchemaUpdateGate = class {
+  #decision;
+  constructor(decision) {
+    this.#decision = decision.catch(() => null);
+  }
+  async assertWritable() {
+    const decision = await this.#decision;
+    if (decision && decision.action === "reject") {
+      throw decision.error;
+    }
+  }
+};
+
+// src/schema-update/fence.ts
+var FENCE_RECORD_ID = "schema-fence";
+var META_COLLECTION2 = "_meta";
+var DEFAULT_FENCE = { currentSchemaVersion: 0, fenceState: "normal" };
+async function loadFence(store, vault) {
+  const envelope = await store.get(vault, META_COLLECTION2, FENCE_RECORD_ID);
+  if (!envelope) return DEFAULT_FENCE;
+  try {
+    const parsed = JSON.parse(envelope._data);
+    if (!isFenceDoc(parsed)) return DEFAULT_FENCE;
+    return parsed;
+  } catch {
+    return DEFAULT_FENCE;
+  }
+}
+async function saveFence(store, vault, fence) {
+  const envelope = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify(fence)
+  };
+  await store.put(vault, META_COLLECTION2, FENCE_RECORD_ID, envelope);
+}
+function isFenceDoc(x) {
+  if (x === null || typeof x !== "object") return false;
+  const o = x;
+  return typeof o["currentSchemaVersion"] === "number" && (o["fenceState"] === "normal" || o["fenceState"] === "draining" || o["fenceState"] === "migrating" || o["fenceState"] === "complete");
+}
+
+// src/schema-update/client-registry.ts
+var META_COLLECTION3 = "_meta";
+var CLIENT_PREFIX = "schema-fence:client:";
+async function writeClientDoc(store, vault, clientId, doc) {
+  const envelope = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify({ clientId, ...doc })
+  };
+  await store.put(vault, META_COLLECTION3, `${CLIENT_PREFIX}${clientId}`, envelope);
+}
+async function listClientDocs(store, vault) {
+  const ids = await store.list(vault, META_COLLECTION3);
+  const out = [];
+  for (const id of ids) {
+    if (!id.startsWith(CLIENT_PREFIX)) continue;
+    const env = await store.get(vault, META_COLLECTION3, id);
+    if (!env) continue;
+    try {
+      const parsed = JSON.parse(env._data);
+      if (isClientDoc(parsed)) out.push(parsed);
+    } catch {
+    }
+  }
+  return out;
+}
+async function activeQuiesced(store, vault, opts) {
+  const docs = await listClientDocs(store, vault);
+  const active = docs.filter(
+    (d) => d.lastSeen >= opts.now - opts.staleMs && d.clientId !== opts.excludeClientId
+  );
+  return active.every((d) => d.quiescedAtVersion === opts.generation);
+}
+function isClientDoc(x) {
+  if (x === null || typeof x !== "object") return false;
+  const o = x;
+  return typeof o["clientId"] === "string" && typeof o["lastSeen"] === "number" && (o["quiescedAtVersion"] === null || typeof o["quiescedAtVersion"] === "number");
+}
+
+// src/schema-update/fence-controller.ts
+var SchemaFenceController = class {
+  #store;
+  #vault;
+  #onFlush;
+  #clientId;
+  #now;
+  #staleMs;
+  #quiesceTimeoutMs;
+  #emit;
+  #snapshot = 0;
+  #pending = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    this.#store = opts.store;
+    this.#vault = opts.vault;
+    this.#onFlush = opts.onFlush;
+    this.#clientId = opts.clientId ?? "migrator";
+    this.#now = opts.now ?? (() => Date.now());
+    this.#staleMs = opts.staleMs ?? 3e4;
+    this.#quiesceTimeoutMs = opts.quiesceTimeoutMs ?? 6e4;
+    this.#emit = opts.emit ?? (() => {
+    });
+  }
+  /** Capture the generation snapshot at vault-open. */
+  async init() {
+    this.#snapshot = (await loadFence(this.#store, this.#vault)).currentSchemaVersion;
+  }
+  /** Record a per-collection pending cutover (from a registration `cutover` decision). */
+  registerPendingCutover(collection, transform) {
+    this.#pending.set(collection, transform);
+  }
+  /** Write-path gate. Throws when behind, fenced, or this collection is cutover-pending. */
+  async assertWritable(collection) {
+    const fence = await loadFence(this.#store, this.#vault);
+    if (fence.currentSchemaVersion > this.#snapshot) {
+      throw new MigrationRequiredError(
+        `Vault "${this.#vault}" advanced to schema generation ${fence.currentSchemaVersion} (this client opened at ${this.#snapshot}). Reload to continue.`
+      );
+    }
+    if (fence.fenceState === "draining" || fence.fenceState === "migrating") {
+      throw new SchemaFenceError(`Vault "${this.#vault}" is mid-cutover (${fence.fenceState}); writes are paused.`);
+    }
+    if (this.#pending.has(collection)) {
+      throw new SchemaFenceError(
+        `Collection "${collection}" has a pending schema cutover; run vault.runSchemaCutover() before writing.`
+      );
+    }
+  }
+  /**
+   * Admin trigger. Drain → wait for the active set to quiesce (or time out)
+   * → migrate each pending transform → bump → complete → normal. The
+   * migrator excludes itself from the barrier (it drained synchronously
+   * here). `onPoll` (tests) advances other clients between barrier checks;
+   * production falls back to a short real delay.
+   */
+  async runCutover(run, opts) {
+    if (this.#pending.size === 0) return { migrated: 0 };
+    const base = await loadFence(this.#store, this.#vault);
+    const generation = base.currentSchemaVersion;
+    await this.#setState(generation, "draining");
+    await this.#onFlush();
+    const deadline = this.#now() + this.#quiesceTimeoutMs;
+    while (!await activeQuiesced(this.#store, this.#vault, {
+      generation,
+      now: this.#now(),
+      staleMs: this.#staleMs,
+      excludeClientId: this.#clientId
+    })) {
+      if (this.#now() >= deadline) {
+        throw new QuiesceTimeoutError(
+          `Cutover on "${this.#vault}" timed out waiting for clients to quiesce at generation ${generation}.`
+        );
+      }
+      await (opts?.onPoll ? opts.onPoll() : delay(50));
+    }
+    await this.#setState(generation, "migrating");
+    let migrated = 0;
+    for (const [collection, transform] of this.#pending) {
+      await run(collection, transform);
+      migrated++;
+    }
+    const nextVersion = generation + 1;
+    await this.#setState(nextVersion, "complete");
+    this.#pending.clear();
+    await this.#setState(nextVersion, "normal");
+    this.#snapshot = nextVersion;
+    return { migrated };
+  }
+  /** Recover a stuck drain: reset fenceState to normal at the current version (no bump). */
+  async abort() {
+    const fence = await loadFence(this.#store, this.#vault);
+    await this.#setState(fence.currentSchemaVersion, "normal");
+  }
+  async #setState(currentSchemaVersion, fenceState) {
+    await saveFence(this.#store, this.#vault, { currentSchemaVersion, fenceState });
+    this.#emit({ currentSchemaVersion, fenceState });
+  }
+};
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/schema-update/fence-watcher.ts
+var FenceWatcher = class {
+  #store;
+  #vault;
+  #clientId;
+  #onFlush;
+  #now;
+  #emit;
+  #lastState = null;
+  #quiescedAtVersion = null;
+  #timer;
+  constructor(opts) {
+    this.#store = opts.store;
+    this.#vault = opts.vault;
+    this.#clientId = opts.clientId;
+    this.#onFlush = opts.onFlush;
+    this.#now = opts.now ?? (() => Date.now());
+    this.#emit = opts.emit ?? (() => {
+    });
+  }
+  /** Publish liveness (and the current ack) without changing quiesce state. */
+  async beat() {
+    await writeClientDoc(this.#store, this.#vault, this.#clientId, {
+      lastSeen: this.#now(),
+      quiescedAtVersion: this.#quiescedAtVersion
+    });
+  }
+  /** Poll the fence; quiesce on draining; emit on transitions. */
+  async check() {
+    const fence = await loadFence(this.#store, this.#vault);
+    if (fence.fenceState !== this.#lastState) {
+      this.#lastState = fence.fenceState;
+      this.#emit({ currentSchemaVersion: fence.currentSchemaVersion, fenceState: fence.fenceState });
+    }
+    if (fence.fenceState === "draining" && this.#quiescedAtVersion !== fence.currentSchemaVersion) {
+      await this.#onFlush();
+      this.#quiescedAtVersion = fence.currentSchemaVersion;
+      await this.beat();
+    }
+    if (fence.fenceState === "normal") {
+      this.#quiescedAtVersion = null;
+    }
+  }
+  start(intervalMs) {
+    if (this.#timer) return;
+    this.#timer = setInterval(() => {
+      void this.beat();
+      void this.check();
+    }, intervalMs);
+    const timer = this.#timer;
+    if (typeof timer.unref === "function") timer.unref();
+  }
+  stop() {
+    if (this.#timer) {
+      clearInterval(this.#timer);
+      this.#timer = void 0;
+    }
+  }
+};
+
 // src/introspection/fields.ts
 function jsonSchemaType(node) {
   if (Array.isArray(node.type)) {
@@ -4165,6 +4611,13 @@ var Vault = class {
    */
   reloadKeyring;
   collectionCache = /* @__PURE__ */ new Map();
+  /** #232 — vault-level schema cutover fence/controller. */
+  schemaFence;
+  /** #232 — per-client heartbeat/watcher; started lazily on cutover registration. */
+  #fenceWatcher;
+  #fenceCoordinationStarted = false;
+  /** #229 — per-collection registered schema-update strategy names. */
+  #schemaUpdateNames = /* @__PURE__ */ new Map();
   /**
    * per-collection `blobFields` retention/TTL config.
    * Populated on `collection({ blobFields })` and read by
@@ -4280,6 +4733,13 @@ var Vault = class {
     this.noydb = opts.noydb;
     this.keyring = opts.keyring;
     this.encrypted = opts.encrypted;
+    this.schemaFence = new SchemaFenceController({
+      store: this.adapter,
+      vault: this.name,
+      onFlush: () => this.noydb._writeQueueTracker.onFlush(),
+      clientId: this.noydb._clientId,
+      emit: (e) => this.emitter.emit("schema:fence-changed", { vault: this.name, ...e })
+    });
     this.emitter = opts.emitter;
     this.onDirty = opts.onDirty;
     this.onRegisterConflictResolver = opts.onRegisterConflictResolver;
@@ -4388,6 +4848,35 @@ var Vault = class {
         }
         this.dictKeyFieldRegistry.set(collectionName, dictFieldMap);
       }
+      if ((options?.schemaUpdate?.length ?? 0) > 0) {
+        this.#schemaUpdateNames.set(collectionName, (options.schemaUpdate ?? []).map((s) => s.name));
+      }
+      let schemaUpdateGate;
+      if (options?.persistJsonSchema === true && options.schema !== void 0 && (options.schemaUpdate?.length ?? 0) > 0) {
+        const validator = options.schema;
+        const strategies = options.schemaUpdate ?? [];
+        const work = (async () => {
+          const dek = await this.getDEK(collectionName);
+          const result = await persistSchemaIfNeeded({
+            store: this.adapter,
+            vault: this.name,
+            collectionName,
+            validator,
+            dek,
+            strategies
+          });
+          const decision = result.decision ?? { action: "allow" };
+          if (decision.action === "cutover") {
+            this.schemaFence.registerPendingCutover(collectionName, decision.transform);
+            this._ensureFenceCoordination();
+          }
+          return decision;
+        })();
+        this._pendingSchemaWrites.push(work.then(() => {
+        }, () => {
+        }));
+        schemaUpdateGate = new SchemaUpdateGate(work);
+      }
       const collOpts = {
         adapter: this.adapter,
         vault: this.name,
@@ -4395,6 +4884,11 @@ var Vault = class {
         keyring: this.keyring,
         encrypted: this.encrypted,
         emitter: this.emitter,
+        writeQueue: this.noydb._writeQueueTracker,
+        writeHooks: this.noydb._writeHooks,
+        activeTxId: () => this.noydb._activeTxContextOrNull?.txId ?? null,
+        schemaUpdateGate,
+        schemaFence: this.schemaFence,
         getDEK: this.getDEK,
         onDirty: this.onDirty,
         historyConfig: this.historyConfig,
@@ -4481,7 +4975,7 @@ var Vault = class {
       }
       coll = new Collection(collOpts);
       this.collectionCache.set(collectionName, coll);
-      if (options?.persistJsonSchema === true && options.schema !== void 0) {
+      if (options?.persistJsonSchema === true && options.schema !== void 0 && (options.schemaUpdate?.length ?? 0) === 0) {
         const validator = options.schema;
         const work = (async () => {
           try {
@@ -4514,6 +5008,87 @@ var Vault = class {
     this._pendingSchemaWrites = [];
     await Promise.allSettled(pending);
   }
+  /**
+   * Run a coordinated schema cutover (#232). Drains pending writes, waits
+   * for the active client set to quiesce (the ack-barrier), applies every
+   * pending collection transform in bulk, bumps the vault schema generation,
+   * and clears the fence. Returns the count of collections migrated.
+   * `opts.onPoll` (tests) advances other clients between barrier checks.
+   */
+  async runSchemaCutover(opts) {
+    return this.schemaFence.runCutover(
+      (collectionName, transform) => this.#runCutoverTransform(collectionName, transform),
+      opts
+    );
+  }
+  async #runCutoverTransform(collectionName, transform) {
+    const coll = this.collectionCache.get(collectionName);
+    if (!coll) return;
+    await coll._applyCutoverTransform(transform);
+  }
+  /**
+   * #228b — refresh a loaded collection's view of one document from a peer
+   * tab's broadcast. No-op when the collection isn't loaded in this tab
+   * (it will read fresh on next open). Mirrors #runCutoverTransform's guard.
+   */
+  async _applyRemoteWrite(collectionName, docId, action) {
+    const coll = this.collectionCache.get(collectionName);
+    if (!coll) return;
+    await coll._applyRemoteChange(docId, action);
+  }
+  /**
+   * #228c — for a detected conflict: capture this tab's clobbered record,
+   * read the common ancestor from history, converge the cache to the store's
+   * authoritative value (the (b) re-read), and return all three for the
+   * WriteConflict payload. Returns null when the collection isn't loaded.
+   */
+  async _captureAndConverge(collectionName, docId, action, baseV) {
+    const coll = this.collectionCache.get(collectionName);
+    if (!coll) return null;
+    const local = coll._peekCached(docId);
+    let base = null;
+    try {
+      base = await coll.getVersion(docId, baseV);
+    } catch {
+      base = null;
+    }
+    await coll._applyRemoteChange(docId, action);
+    const remote = await coll.get(docId);
+    return { local, remote, base };
+  }
+  /** Recover a stuck cutover fence (#232) — reset to normal without bumping. */
+  async abortSchemaCutover() {
+    await this.schemaFence.abort();
+  }
+  /** Current schema-cutover fence state for this vault (#232/#233). Thin live read. */
+  async schemaFenceState() {
+    return loadFence(this.adapter, this.name);
+  }
+  /** @internal Start the per-client heartbeat + fence watcher once a cutover is registered (#232). */
+  _ensureFenceCoordination() {
+    if (this.#fenceCoordinationStarted) return;
+    this.#fenceCoordinationStarted = true;
+    this.#fenceWatcher = new FenceWatcher({
+      store: this.adapter,
+      vault: this.name,
+      clientId: this.noydb._clientId,
+      onFlush: () => this.noydb._writeQueueTracker.onFlush(),
+      emit: (e) => this.emitter.emit("schema:fence-changed", { vault: this.name, ...e })
+    });
+    this.#fenceWatcher.start(2e3);
+  }
+  /** @internal Stop the heartbeat/watcher (vault lock/close). */
+  _stopFenceCoordination() {
+    this.#fenceWatcher?.stop();
+    this.#fenceWatcher = void 0;
+    this.#fenceCoordinationStarted = false;
+  }
+  /** @internal Drive one heartbeat + watch cycle deterministically (tests). */
+  async _fenceTick() {
+    this._ensureFenceCoordination();
+    await this.#fenceWatcher.beat();
+    await this.#fenceWatcher.check();
+  }
   /**
    * Validate i18nText fields on a `put()`. Called by Collection just
    * before the adapter write, after schema validation. Throws
@@ -4839,12 +5414,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-ORP37MVW.js");
+    const { issueAttestationCore } = await import("./issue-BAJ7ZB4S.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-GRI5TZKH.js");
+    const { loadSigner, loadOrCreateSigner } = await import("./signer-M4K5HBLD.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") {
@@ -4870,19 +5445,19 @@ var Vault = class {
     };
   }
   async revokeAttestation(docId) {
-    const { revokeDocCore } = await import("./revoke-KY2GB4KP.js");
+    const { revokeDocCore } = await import("./revoke-7JOVLZFD.js");
     await revokeDocCore(this.makeRevokeContext(), docId);
   }
   async unrevokeAttestation(docId) {
-    const { unrevokeDocCore } = await import("./revoke-KY2GB4KP.js");
+    const { unrevokeDocCore } = await import("./revoke-7JOVLZFD.js");
     await unrevokeDocCore(this.makeRevokeContext(), docId);
   }
   async getRevokedDocIds() {
-    const { getRevokedDocIdsCore } = await import("./revoke-KY2GB4KP.js");
+    const { getRevokedDocIdsCore } = await import("./revoke-7JOVLZFD.js");
     return getRevokedDocIdsCore(this.makeRevokeContext());
   }
   async publishRevocationList() {
-    const { publishRevocationListCore } = await import("./revoke-KY2GB4KP.js");
+    const { publishRevocationListCore } = await import("./revoke-7JOVLZFD.js");
     return publishRevocationListCore(this.makeRevokeContext());
   }
   makeRevokeContext() {
@@ -5171,7 +5746,7 @@ var Vault = class {
   async _initGuards(handles) {
     if (handles.length === 0) return;
     const [{ GuardRegistry }, { ReadOnlyVaultFacade }] = await Promise.all([
-      import("./registry-RFGGMVNJ.js"),
+      import("./registry-2IEARCGT.js"),
       import("./read-only-facade-ITU6L7BL.js")
     ]);
     const registry = new GuardRegistry();
@@ -5200,7 +5775,7 @@ var Vault = class {
   async _initDerivations(handles) {
     if (handles.length === 0) return;
     const [{ DerivationRegistry }, { ReadOnlyVaultFacade }] = await Promise.all([
-      import("./registry-PSIPG2QR.js"),
+      import("./registry-EMGLZGR6.js"),
       import("./read-only-facade-ITU6L7BL.js")
     ]);
     const registry = new DerivationRegistry();
@@ -5231,7 +5806,7 @@ var Vault = class {
    */
   async _initMaterializedViews(handles) {
     if (handles.length === 0) return;
-    const { MaterializedViewRegistry } = await import("./registry-3ALP62P6.js");
+    const { MaterializedViewRegistry } = await import("./registry-CDHASH73.js");
     const registry = new MaterializedViewRegistry();
     this.materializedViewRegistry = registry;
     const db = this;
@@ -5255,7 +5830,7 @@ var Vault = class {
    */
   async _initOverlayedViews(handles) {
     if (handles.length === 0) return;
-    const { OverlayedViewRegistry } = await import("./registry-7HE6VJGC.js");
+    const { OverlayedViewRegistry } = await import("./registry-NQALYR77.js");
     const registry = new OverlayedViewRegistry();
     const mvRegistry = this.materializedViewRegistry;
     const overlayNames = /* @__PURE__ */ new Set();
@@ -5302,13 +5877,13 @@ var Vault = class {
     if (!reg) {
       throw new Error(`refreshView: no MV registered with name "${name}"`);
     }
-    const { MaterializedViewExecutor } = await import("./executor-AS2IDHKZ.js");
+    const { MaterializedViewExecutor } = await import("./executor-KT2IOZVP.js");
     const result = await MaterializedViewExecutor.refresh(reg, {
       getCollection: (n) => this.collection(n),
       getActiveTxContext: () => this.noydb._activeTxContextOrNull,
       getQueryContext: () => this
     });
-    const { clearMVStale } = await import("./stale-OTOF3FH7.js");
+    const { clearMVStale } = await import("./stale-PAGCS4K5.js");
     clearMVStale(registry, name);
     return result;
   }
@@ -5324,7 +5899,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-HLXFXNFM.js");
+    const { DerivationExecutor } = await import("./executor-GFZFDQXV.js");
     const sourceColl = this.collection(sourceCollection);
     const records = await sourceColl.list();
     const ctx = { vault: this.readOnlyFacade ?? new (await import("./read-only-facade-ITU6L7BL.js")).ReadOnlyVaultFacade(this) };
@@ -5349,7 +5924,7 @@ var Vault = class {
           if (!outSpec) continue;
           const outputColl = this.collection(outSpec.collection);
           if (out.kind === "array") {
-            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-VJ52RIEY.js");
+            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-NRBWSLRK.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);
@@ -5573,7 +6148,7 @@ var Vault = class {
    * collection.
    */
   async delegate(opts) {
-    const { issueDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-QYXZW25W.js");
+    const { issueDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-QSC7G5QC.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."
@@ -5595,7 +6170,7 @@ var Vault = class {
    * if the id does not exist.
    */
   async revokeDelegation(id) {
-    const { revokeDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-QYXZW25W.js");
+    const { revokeDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-QSC7G5QC.js");
     await revokeDelegation(this.adapter, this.name, id);
     void DELEGATIONS_COLLECTION;
   }
@@ -5942,6 +6517,27 @@ var Vault = class {
   async dumpSchema(opts = {}) {
     return dumpVaultSchema(this, opts);
   }
+  /**
+   * Lightweight read of the vault's registered schema (#229): collections
+   * (+ doc counts), guards, materialized views, schema-update strategies,
+   * and the unlocked user's grants. Cheap — one `adapter.list` per
+   * collection, no decryption. For a full snapshot + stats use dumpSchema().
+   * Post-unlock by construction (a Vault only exists with an unlocked keyring).
+   */
+  async introspect() {
+    const byCol = (a, b) => a.collection.localeCompare(b.collection);
+    const names = [.../* @__PURE__ */ new Set([...this.collectionCache.keys(), ...await this.collections()])].filter((n) => !n.startsWith("_")).sort((a, b) => a.localeCompare(b));
+    const collections = [];
+    for (const name of names) {
+      const ids = await this.adapter.list(this.name, name);
+      collections.push({ name, docCount: ids.length });
+    }
+    const guards = (this._getGuardRegistry()?.summary() ?? []).slice().sort(byCol);
+    const materializedViews = (this._getMaterializedViewRegistry()?.all() ?? []).map((mv) => ({ name: mv.spec.name, sourceCollections: [...mv.dependencies].sort() })).sort((a, b) => a.name.localeCompare(b.name));
+    const schemaUpdate = [...this.#schemaUpdateNames.entries()].map(([collection, strategies]) => ({ collection, strategies })).sort(byCol);
+    const grants = [...this.keyring.deks.keys()].filter((collection) => !collection.startsWith("_")).map((collection) => ({ collection, permission: this.keyring.permissions[collection] ?? "rw" })).sort(byCol);
+    return { collections, guards, materializedViews, schemaUpdate, grants };
+  }
   /**
    * Internal accessor for {@link dumpVaultSchema}. Exposes the structural
    * state the walker needs (collection cache, registries, ref registry,
@@ -6043,7 +6639,7 @@ var Vault = class {
    * @see docs/subsystems/public-envelope.md
    */
   async getPublicEnvelope(opts = {}) {
-    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-U3CMEOMV.js");
+    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-OHQ5UZFM.js");
     return readPublicEnvelope2(this.adapter, this.name, opts);
   }
   /**
@@ -6581,6 +7177,387 @@ var NoydbEventEmitter = class {
   }
 };
 
+// src/write-queue.ts
+var WriteQueueTracker = class {
+  #depth = 0;
+  #error = null;
+  #changeHandlers = /* @__PURE__ */ new Set();
+  #flushWaiters = [];
+  get pending() {
+    return this.#depth > 0;
+  }
+  get depth() {
+    return this.#depth;
+  }
+  /** Mark one write as started. */
+  begin() {
+    this.#depth++;
+    this.#emitChange();
+  }
+  /** Mark one write as finished. Pass the error if it failed. */
+  settle(error) {
+    this.#depth = Math.max(0, this.#depth - 1);
+    if (error) this.#error = error;
+    this.#emitChange();
+    if (this.#depth === 0) this.#drainFlush();
+  }
+  onChange(handler) {
+    this.#changeHandlers.add(handler);
+    return () => {
+      this.#changeHandlers.delete(handler);
+    };
+  }
+  onFlush() {
+    if (this.#depth === 0) {
+      const error = this.#error;
+      this.#error = null;
+      return error ? Promise.reject(error) : Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      this.#flushWaiters.push({ resolve, reject });
+    });
+  }
+  /**
+   * Run `fn` as a tracked write: depth++ on entry, depth-- on settle
+   * (success or failure). The fn's resolved value is returned; a thrown
+   * error is re-thrown after the queue is decremented.
+   */
+  async track(fn) {
+    this.begin();
+    try {
+      const value = await fn();
+      this.settle();
+      return value;
+    } catch (error) {
+      this.settle(error);
+      throw error;
+    }
+  }
+  #emitChange() {
+    for (const handler of this.#changeHandlers) handler();
+  }
+  #drainFlush() {
+    const waiters = this.#flushWaiters;
+    this.#flushWaiters = [];
+    const error = this.#error;
+    this.#error = null;
+    for (const waiter of waiters) {
+      if (error) waiter.reject(error);
+      else waiter.resolve();
+    }
+  }
+};
+
+// src/write-hooks.ts
+var WriteHookRegistry = class {
+  #before = [];
+  #after = [];
+  #suppressed = false;
+  /** True while handlers are running — used by the write path to skip nested firing. */
+  get suppressed() {
+    return this.#suppressed;
+  }
+  /** True when any hook is registered (cheap gate for the write path). */
+  get hasHandlers() {
+    return this.#before.length > 0 || this.#after.length > 0;
+  }
+  onBeforeWrite(handler) {
+    this.#before.push(handler);
+    return () => {
+      const i = this.#before.indexOf(handler);
+      if (i >= 0) this.#before.splice(i, 1);
+    };
+  }
+  onAfterWrite(handler) {
+    this.#after.push(handler);
+    return () => {
+      const i = this.#after.indexOf(handler);
+      if (i >= 0) this.#after.splice(i, 1);
+    };
+  }
+  /** Run before-hooks (awaited, in order). A throw propagates and aborts the write. */
+  async runBefore(event) {
+    if (this.#before.length === 0) return;
+    this.#suppressed = true;
+    try {
+      for (const h of this.#before.slice()) await h(event);
+    } finally {
+      this.#suppressed = false;
+    }
+  }
+  /** Run after-hooks (awaited, in order). Per-handler errors are warned, not thrown. */
+  async runAfter(event) {
+    if (this.#after.length === 0) return;
+    this.#suppressed = true;
+    try {
+      for (const h of this.#after.slice()) {
+        try {
+          await h(event);
+        } catch (err) {
+          console.warn(
+            `[noy-db] onAfterWrite handler failed for ${event.collection}/${event.docId}: ` + (err instanceof Error ? err.message : String(err))
+          );
+        }
+      }
+    } finally {
+      this.#suppressed = false;
+    }
+  }
+};
+
+// src/tab-coordination.ts
+var TabCoordinator = class {
+  tabId;
+  role = "unknown";
+  #lockManager;
+  #channel;
+  #lockName;
+  #heartbeatMs;
+  #staleMs;
+  #now;
+  #peers = /* @__PURE__ */ new Map();
+  #roleHandlers = /* @__PURE__ */ new Set();
+  #tabsHandlers = /* @__PURE__ */ new Set();
+  #ac;
+  #releaseLock;
+  #unsub;
+  #closeUnsub;
+  #timer;
+  #ownsChannel;
+  #started = false;
+  #disposed = false;
+  #lastTabsSig = "";
+  constructor(opts = {}) {
+    this.tabId = opts.tabId ?? `tab-${Math.trunc((opts.now ?? (() => 0))())}-${cheapRand()}`;
+    this.#lockManager = opts.lockManager;
+    this.#channel = opts.channel;
+    this.#lockName = opts.lockName ?? "noydb:tab-primary";
+    this.#heartbeatMs = opts.heartbeatMs ?? 2e3;
+    this.#staleMs = opts.staleMs ?? 6e3;
+    this.#now = opts.now ?? (() => Date.now());
+    this.#ownsChannel = opts.closeChannelOnDispose ?? false;
+  }
+  start() {
+    if (this.#disposed || this.#started) return;
+    this.#started = true;
+    if (this.#channel) {
+      this.#unsub = this.#channel.on("message", (p) => this.#onMessage(p));
+      this.#closeUnsub = this.#channel.on("close", () => this.#onChannelClose());
+      this.#beat();
+      this.#timer = setInterval(() => this.#tick(), this.#heartbeatMs);
+      const t = this.#timer;
+      if (typeof t.unref === "function") t.unref();
+    }
+    if (this.#lockManager) {
+      this.#ac = new AbortController();
+      this.#setRole("secondary");
+      void this.#lockManager.request(this.#lockName, { mode: "exclusive", signal: this.#ac.signal }, () => {
+        this.#setRole("primary");
+        return new Promise((resolve) => {
+          this.#releaseLock = resolve;
+        });
+      }).catch(() => {
+      });
+    }
+  }
+  activeTabs() {
+    if (!this.#channel) return [];
+    const cutoff = this.#now() - this.#staleMs;
+    const self = { tabId: this.tabId, lastSeen: this.#now(), role: this.role };
+    const out = [self, ...[...this.#peers.values()].filter((p) => p.lastSeen >= cutoff)];
+    return out.sort((a, b) => a.tabId.localeCompare(b.tabId));
+  }
+  onTabRoleChange(fn) {
+    this.#roleHandlers.add(fn);
+    return () => this.#roleHandlers.delete(fn);
+  }
+  onActiveTabsChange(fn) {
+    this.#tabsHandlers.add(fn);
+    return () => this.#tabsHandlers.delete(fn);
+  }
+  dispose() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.#releaseLock?.();
+    this.#ac?.abort();
+    if (this.#timer) {
+      clearInterval(this.#timer);
+      this.#timer = void 0;
+    }
+    this.#unsub?.();
+    this.#closeUnsub?.();
+    if (this.#ownsChannel) this.#channel?.close();
+    this.#setRole("unknown");
+  }
+  /** @internal test seam — broadcast one heartbeat now. */
+  _beat() {
+    this.#beat();
+  }
+  #tick() {
+    this.#prune();
+    this.#emitTabs();
+    this.#beat();
+  }
+  #beat() {
+    if (this.#disposed) return;
+    if (!this.#channel || !this.#channel.isOpen) return;
+    const msg = { kind: "tab-presence", tabId: this.tabId, lastSeen: this.#now(), role: this.role };
+    this.#channel.send(JSON.stringify(msg));
+  }
+  #onChannelClose() {
+    if (this.#timer) {
+      clearInterval(this.#timer);
+      this.#timer = void 0;
+    }
+    this.#setRole("unknown");
+  }
+  #onMessage(payload) {
+    let msg;
+    try {
+      msg = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    if (!isPresenceMsg(msg) || msg.tabId === this.tabId) return;
+    this.#peers.set(msg.tabId, { tabId: msg.tabId, lastSeen: msg.lastSeen, role: msg.role });
+    this.#prune();
+    this.#emitTabs();
+  }
+  #prune() {
+    const cutoff = this.#now() - this.#staleMs;
+    for (const [id, p] of this.#peers) if (p.lastSeen < cutoff) this.#peers.delete(id);
+  }
+  #setRole(role) {
+    if (this.role === role) return;
+    this.role = role;
+    for (const h of this.#roleHandlers) h(role);
+    this.#beat();
+    this.#emitTabs();
+  }
+  #emitTabs() {
+    const tabs = this.activeTabs();
+    const sig = tabs.map((t) => `${t.tabId}:${t.role}`).join("|");
+    if (sig === this.#lastTabsSig) return;
+    this.#lastTabsSig = sig;
+    for (const h of this.#tabsHandlers) h(tabs);
+  }
+};
+function isPresenceMsg(x) {
+  if (x === null || typeof x !== "object") return false;
+  const o = x;
+  return o["kind"] === "tab-presence" && typeof o["tabId"] === "string" && typeof o["lastSeen"] === "number" && (o["role"] === "primary" || o["role"] === "secondary" || o["role"] === "unknown");
+}
+function cheapRand() {
+  const g = globalThis;
+  return g.crypto?.randomUUID ? g.crypto.randomUUID().slice(0, 8) : "anon";
+}
+function defaultLockManager() {
+  const nav = globalThis.navigator;
+  return nav?.locks;
+}
+function defaultChannel(name = "noydb:tabs") {
+  if (typeof globalThis.window === "undefined") return void 0;
+  const Bc = globalThis.BroadcastChannel;
+  if (!Bc) return void 0;
+  const bc = new Bc(name);
+  const msgListeners = /* @__PURE__ */ new Set();
+  bc.onmessage = (e) => {
+    for (const l of msgListeners) l(String(e.data));
+  };
+  return {
+    isOpen: true,
+    send(payload) {
+      bc.postMessage(payload);
+    },
+    on(event, listener) {
+      if (event === "message") {
+        const l = listener;
+        msgListeners.add(l);
+        return () => msgListeners.delete(l);
+      }
+      return () => {
+      };
+    },
+    close() {
+      msgListeners.clear();
+      bc.close();
+    }
+  };
+}
+
+// src/tab-write-relay.ts
+var CrossTabWriteRelay = class {
+  #channel;
+  #writerId;
+  #subscribeAfterWrite;
+  #applyRemoteWrite;
+  #reportConflict;
+  #ledger = /* @__PURE__ */ new Map();
+  #ownsChannel;
+  #unsubMsg;
+  #unsubWrite;
+  #started = false;
+  #disposed = false;
+  constructor(opts) {
+    this.#channel = opts.channel;
+    this.#writerId = opts.writerId;
+    this.#subscribeAfterWrite = opts.subscribeAfterWrite;
+    this.#applyRemoteWrite = opts.applyRemoteWrite;
+    this.#reportConflict = opts.reportConflict;
+    this.#ownsChannel = opts.closeChannelOnDispose ?? false;
+  }
+  start() {
+    if (this.#started || this.#disposed) return;
+    this.#started = true;
+    this.#unsubMsg = this.#channel.on("message", (p) => this.#onMessage(p));
+    this.#unsubWrite = this.#subscribeAfterWrite((e) => this.#onLocalWrite(e));
+  }
+  dispose() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.#unsubWrite?.();
+    this.#unsubMsg?.();
+    if (this.#ownsChannel) this.#channel.close();
+  }
+  #onLocalWrite(e) {
+    if (this.#disposed || !this.#channel.isOpen) return;
+    this.#ledger.set(ledgerKey(e.vault, e.collection, e.docId), e.version);
+    const action = e.op === "delete" ? "delete" : "put";
+    const msg = { kind: "tab-write", writerId: this.#writerId, vault: e.vault, collection: e.collection, docId: e.docId, action, baseV: e.baseVersion, v: e.version };
+    this.#channel.send(JSON.stringify(msg));
+  }
+  #onMessage(payload) {
+    if (this.#disposed) return;
+    let msg;
+    try {
+      msg = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    if (!isTabWriteMsg(msg) || msg.writerId === this.#writerId) return;
+    const key = ledgerKey(msg.vault, msg.collection, msg.docId);
+    const ownV = this.#ledger.get(key);
+    if (ownV !== void 0 && msg.baseV < ownV && this.#reportConflict) {
+      void Promise.resolve(this.#reportConflict(msg.vault, msg.collection, msg.docId, msg.action, msg.baseV, msg.v, ownV)).catch((err) => {
+        console.warn(`[noy-db] cross-tab conflict report failed for ${msg.collection}/${msg.docId}: ` + (err instanceof Error ? err.message : String(err)));
+      });
+      return;
+    }
+    if (ownV !== void 0 && msg.baseV >= ownV) this.#ledger.set(key, msg.v);
+    void Promise.resolve(this.#applyRemoteWrite(msg.vault, msg.collection, msg.docId, msg.action)).catch((err) => {
+      console.warn(`[noy-db] cross-tab apply failed for ${msg.collection}/${msg.docId}: ` + (err instanceof Error ? err.message : String(err)));
+    });
+  }
+};
+function ledgerKey(vault, collection, docId) {
+  return `${vault}\0${collection}\0${docId}`;
+}
+function isTabWriteMsg(x) {
+  if (x === null || typeof x !== "object") return false;
+  const o = x;
+  return o["kind"] === "tab-write" && typeof o["writerId"] === "string" && typeof o["vault"] === "string" && typeof o["collection"] === "string" && typeof o["docId"] === "string" && (o["action"] === "put" || o["action"] === "delete") && typeof o["baseV"] === "number" && typeof o["v"] === "number";
+}
+
 // src/session/unlock-state.ts
 var QuickUnlockStore = class {
   states = /* @__PURE__ */ new Map();
@@ -6629,6 +7606,9 @@ var NOT_ENABLED4 = new Error(
 var NO_TX = {
   async runTransaction() {
     throw NOT_ENABLED4;
+  },
+  async runDryRun() {
+    throw NOT_ENABLED4;
   }
 };
 
@@ -6926,6 +7906,9 @@ function createPlaintextKeyring(userId) {
 var Noydb = class {
   options;
   emitter = new NoydbEventEmitter();
+  writeQueueTracker = new WriteQueueTracker();
+  writeHooks = new WriteHookRegistry();
+  clientId = generateULID();
   vaultCache = /* @__PURE__ */ new Map();
   keyringCache = /* @__PURE__ */ new Map();
   syncEngines = /* @__PURE__ */ new Map();
@@ -6958,6 +7941,10 @@ var Noydb = class {
   publicEnvelopeSchema;
   closed = false;
   sessionTimer = null;
+  /** Same-device multi-tab coordinator (#228); created on `enableTabCoordination()`. */
+  tabCoordinator;
+  /** Cross-tab write relay (#228b); created on `enableTabCoordination()`. */
+  writeRelay;
   /** Per-vault policy enforcers. */
   policyEnforcers = /* @__PURE__ */ new Map();
   txStrategy;
@@ -7150,6 +8137,7 @@ var Noydb = class {
     await comp._initDerivations(this.options.derivationStrategies ?? []);
     await comp._initMaterializedViews(this.options.materializedViewStrategies ?? []);
     await comp._initOverlayedViews(this.options.overlayedViewStrategies ?? []);
+    await comp.schemaFence.init();
     this.vaultCache.set(name, comp);
     return comp;
   }
@@ -7577,6 +8565,14 @@ var Noydb = class {
     if (typeof arg === "function") {
       return this.txStrategy.runTransaction(this, arg);
     }
+    if (typeof arg === "object" && arg !== null && arg.dryRun === true) {
+      if (typeof maybeFn !== "function") {
+        throw new ValidationError(
+          "db.transaction({ dryRun: true }, fn) requires the callback as the second argument."
+        );
+      }
+      return this.txStrategy.runDryRun(this, maybeFn);
+    }
     if (typeof arg === "object" && arg !== null && arg.amendment === true) {
       if (typeof maybeFn !== "function") {
         throw new ValidationError(
@@ -7689,6 +8685,133 @@ var Noydb = class {
   off(event, handler) {
     this.emitter.off(event, handler);
   }
+  /**
+   * Observable write-queue for this hub instance. Reflects outstanding
+   * in-flight writes across all collections. See {@link WriteQueue}.
+   *
+   * @example
+   * window.addEventListener('beforeunload', (e) => {
+   *   if (db.writeQueue.pending) { e.preventDefault(); e.returnValue = '' }
+   * })
+   */
+  get writeQueue() {
+    return this.writeQueueTracker;
+  }
+  /**
+   * @internal Mutable tracker behind {@link writeQueue}. Threaded into
+   * each Collection (via Vault) so `put`/`delete` can `track()` writes.
+   * Not part of the public surface — consumers use `writeQueue`.
+   */
+  get _writeQueueTracker() {
+    return this.writeQueueTracker;
+  }
+  /**
+   * Register a hook that runs before each write (#230). Awaited; a throw
+   * aborts the write. Returns an unsubscribe function.
+   */
+  onBeforeWrite(handler) {
+    return this.writeHooks.onBeforeWrite(handler);
+  }
+  /**
+   * Register a hook that runs after each committed write (#230). Awaited;
+   * a handler error is warned, never rolled back. Returns an unsubscribe fn.
+   */
+  onAfterWrite(handler) {
+    return this.writeHooks.onAfterWrite(handler);
+  }
+  /** Subscribe to cross-tab write conflicts (#228c). Returns an unsubscribe. */
+  onWriteConflict(fn) {
+    this.on("write:conflict", fn);
+    return () => this.off("write:conflict", fn);
+  }
+  /**
+   * Enable same-device multi-tab coordination (#228): primary/secondary
+   * election + presence. Browser-only — a graceful no-op (role 'unknown')
+   * when Web Locks / BroadcastChannel are unavailable and nothing is
+   * injected. Idempotent; returns a disposer.
+   */
+  enableTabCoordination(opts = {}) {
+    if (this.tabCoordinator) return { dispose: () => this.disableTabCoordination() };
+    const lockManager = opts.lockManager ?? defaultLockManager();
+    const channel = opts.channel ?? defaultChannel();
+    const c = new TabCoordinator({
+      ...opts,
+      ...lockManager ? { lockManager } : {},
+      ...channel ? { channel } : {},
+      // We own the channel only when we created the default; never close a caller-injected one.
+      closeChannelOnDispose: opts.channel === void 0 && channel !== void 0
+    });
+    this.tabCoordinator = c;
+    c.start();
+    if (opts.propagateWrites !== false) {
+      const writeChannel = opts.writeChannel ?? defaultChannel("noydb:tab-writes");
+      if (writeChannel) {
+        const relay = new CrossTabWriteRelay({
+          channel: writeChannel,
+          writerId: c.tabId,
+          subscribeAfterWrite: (h) => this.onAfterWrite(h),
+          applyRemoteWrite: (vault, collection, docId, action) => this.#applyRemoteWrite(vault, collection, docId, action),
+          reportConflict: (vault, collection, docId, action, baseV, v, ownV) => this.#reportWriteConflict(vault, collection, docId, action, baseV, v, ownV),
+          // Own the channel only when we created the default (mirrors the presence channel).
+          closeChannelOnDispose: opts.writeChannel === void 0 && writeChannel !== void 0
+        });
+        this.writeRelay = relay;
+        relay.start();
+      }
+    }
+    return { dispose: () => this.disableTabCoordination() };
+  }
+  #applyRemoteWrite(vaultName, collectionName, docId, action) {
+    const v = this.vaultCache.get(vaultName);
+    if (!v) return Promise.resolve();
+    return v._applyRemoteWrite(collectionName, docId, action);
+  }
+  async #reportWriteConflict(vaultName, collectionName, docId, action, baseV, v, ownV) {
+    const vault = this.vaultCache.get(vaultName);
+    if (!vault) return;
+    const cap = await vault._captureAndConverge(collectionName, docId, action, baseV);
+    if (!cap) return;
+    const conflict = {
+      vault: vaultName,
+      collection: collectionName,
+      docId,
+      local: cap.local,
+      remote: cap.remote,
+      base: cap.base,
+      localVersion: ownV,
+      remoteVersion: v,
+      baseVersion: baseV
+    };
+    this.emitter.emit("write:conflict", conflict);
+  }
+  disableTabCoordination() {
+    this.tabCoordinator?.dispose();
+    this.tabCoordinator = void 0;
+    this.writeRelay?.dispose();
+    this.writeRelay = void 0;
+  }
+  get tabRole() {
+    return this.tabCoordinator?.role ?? "unknown";
+  }
+  activeTabs() {
+    return this.tabCoordinator?.activeTabs() ?? [];
+  }
+  onTabRoleChange(fn) {
+    return this.tabCoordinator?.onTabRoleChange(fn) ?? (() => {
+    });
+  }
+  onActiveTabsChange(fn) {
+    return this.tabCoordinator?.onActiveTabsChange(fn) ?? (() => {
+    });
+  }
+  /** @internal The write-hook registry, threaded into each Collection. */
+  get _writeHooks() {
+    return this.writeHooks;
+  }
+  /** @internal Stable per-instance id for schema-cutover coordination (#232). */
+  get _clientId() {
+    return this.clientId;
+  }
   /**
    * Soft-lock a single vault: clear its in-memory keyring, DEKs, vault
    * instance, sync engine, policy enforcer, and active-tier entry —
@@ -7715,6 +8838,7 @@ var Noydb = class {
     this.syncEngines.delete(vault);
     this.policyEnforcers.get(vault)?.destroy();
     this.policyEnforcers.delete(vault);
+    this.vaultCache.get(vault)?._stopFenceCoordination();
     this.keyringCache.delete(vault);
     this.vaultCache.delete(vault);
     this.activeTier.delete(vault);
@@ -7734,6 +8858,8 @@ var Noydb = class {
       engine.stopAutoSync();
     }
     this.syncEngines.clear();
+    for (const v of this.vaultCache.values()) v._stopFenceCoordination();
+    this.disableTabCoordination();
     this.keyringCache.clear();
     this.vaultCache.clear();
     this.activeTier.clear();
@@ -8831,4 +9957,4 @@ export {
   Noydb,
   createNoydb
 };
-//# sourceMappingURL=chunk-E535SAN4.js.map
+//# sourceMappingURL=chunk-T6HQMVML.js.map