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

package/dist/bundle/index.cjs

@@ -31,7 +31,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/errors.ts
-var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, BundleVersionConflictError, ValidationError, SchemaValidationError, GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -291,6 +291,30 @@ var init_errors = __esm({
         this.direction = direction;
       }
     };
+    SchemaUpdateError = class extends NoydbError {
+      constructor(code, message) {
+        super(code, message);
+        this.name = "SchemaUpdateError";
+      }
+    };
+    SchemaFenceError = class extends SchemaUpdateError {
+      constructor(message) {
+        super("SCHEMA_FENCE", message);
+        this.name = "SchemaFenceError";
+      }
+    };
+    MigrationRequiredError = class extends SchemaUpdateError {
+      constructor(message) {
+        super("MIGRATION_REQUIRED", message);
+        this.name = "MigrationRequiredError";
+      }
+    };
+    QuiesceTimeoutError = class extends SchemaUpdateError {
+      constructor(message) {
+        super("QUIESCE_TIMEOUT", message);
+        this.name = "QuiesceTimeoutError";
+      }
+    };
     GroupCardinalityError = class extends NoydbError {
       /** The field being grouped on. */
       field;
@@ -5578,7 +5602,10 @@ var init_transaction = __esm({
   "src/tx/transaction.ts"() {
     "use strict";
     init_errors();
+    init_ulid();
     TxContext = class {
+      /** Stable id for this transaction; shared by all writes it performs (#230). */
+      txId = generateULID();
       /** @internal */
       _ops = [];
       /**
@@ -6617,6 +6644,11 @@ var init_collection = __esm({
       keyring;
       encrypted;
       emitter;
+      writeQueue;
+      schemaUpdateGate;
+      schemaFence;
+      writeHooks;
+      activeTxId;
       getDEK;
       onDirty;
       historyConfig;
@@ -6891,6 +6923,11 @@ var init_collection = __esm({
         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;
@@ -7116,7 +7153,8 @@ var init_collection = __esm({
         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
@@ -7127,6 +7165,59 @@ var init_collection = __esm({
        *                `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();
         }
@@ -7503,8 +7594,71 @@ var init_collection = __esm({
           }
         }
       }
-      /** 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);
       }
       /**
@@ -8327,6 +8481,21 @@ var init_collection = __esm({
         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);
@@ -10202,15 +10371,79 @@ var init_derive = __esm({
   }
 });
 
+// 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 };
+}
+var init_delta = __esm({
+  "src/schema-update/delta.ts"() {
+    "use strict";
+    init_canonicalize();
+  }
+});
+
+// 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" };
+}
+var init_dispatch = __esm({
+  "src/schema-update/dispatch.ts"() {
+    "use strict";
+  }
+});
+
 // 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;
@@ -10223,6 +10456,293 @@ var init_register = __esm({
     "use strict";
     init_derive();
     init_storage2();
+    init_delta();
+    init_dispatch();
+  }
+});
+
+// src/schema-update/gate.ts
+var SchemaUpdateGate;
+var init_gate = __esm({
+  "src/schema-update/gate.ts"() {
+    "use strict";
+    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
+async function loadFence(store, vault) {
+  const envelope = await store.get(vault, META_COLLECTION3, 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_COLLECTION3, 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");
+}
+var FENCE_RECORD_ID, META_COLLECTION3, DEFAULT_FENCE;
+var init_fence = __esm({
+  "src/schema-update/fence.ts"() {
+    "use strict";
+    init_types();
+    FENCE_RECORD_ID = "schema-fence";
+    META_COLLECTION3 = "_meta";
+    DEFAULT_FENCE = { currentSchemaVersion: 0, fenceState: "normal" };
+  }
+});
+
+// src/schema-update/client-registry.ts
+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_COLLECTION4, `${CLIENT_PREFIX}${clientId}`, envelope);
+}
+async function listClientDocs(store, vault) {
+  const ids = await store.list(vault, META_COLLECTION4);
+  const out = [];
+  for (const id of ids) {
+    if (!id.startsWith(CLIENT_PREFIX)) continue;
+    const env = await store.get(vault, META_COLLECTION4, 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");
+}
+var META_COLLECTION4, CLIENT_PREFIX;
+var init_client_registry = __esm({
+  "src/schema-update/client-registry.ts"() {
+    "use strict";
+    init_types();
+    META_COLLECTION4 = "_meta";
+    CLIENT_PREFIX = "schema-fence:client:";
+  }
+});
+
+// src/schema-update/fence-controller.ts
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var SchemaFenceController;
+var init_fence_controller = __esm({
+  "src/schema-update/fence-controller.ts"() {
+    "use strict";
+    init_fence();
+    init_errors();
+    init_client_registry();
+    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 });
+      }
+    };
+  }
+});
+
+// src/schema-update/fence-watcher.ts
+var FenceWatcher;
+var init_fence_watcher = __esm({
+  "src/schema-update/fence-watcher.ts"() {
+    "use strict";
+    init_fence();
+    init_client_registry();
+    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;
+        }
+      }
+    };
   }
 });
 
@@ -10684,6 +11204,13 @@ var init_registry2 = __esm({
       guardsFor(collection) {
         return this._byCollection.get(collection) ?? [];
       }
+      /** Per-collection guard counts, for introspection (#229). */
+      summary() {
+        return [...this._byCollection.entries()].map(([collection, guards]) => ({
+          collection,
+          count: guards.length
+        }));
+      }
       /**
        * Run every guard's `check` for this collection. First throw wins —
        * remaining guards are not invoked. Guards without a `check` skip.
@@ -11082,6 +11609,10 @@ var init_vault = __esm({
     init_magic_link_grant();
     init_api();
     init_register();
+    init_gate();
+    init_fence_controller();
+    init_fence_watcher();
+    init_fence();
     init_storage2();
     init_walk();
     init_types2();
@@ -11188,6 +11719,13 @@ var init_vault = __esm({
        */
       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
@@ -11303,6 +11841,13 @@ var init_vault = __esm({
         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;
@@ -11411,6 +11956,35 @@ var init_vault = __esm({
             }
             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,
@@ -11418,6 +11992,11 @@ var init_vault = __esm({
             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,
@@ -11504,7 +12083,7 @@ var init_vault = __esm({
           }
           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 {
@@ -11537,6 +12116,87 @@ var init_vault = __esm({
         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
@@ -12965,6 +13625,27 @@ var init_vault = __esm({
       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,
@@ -13612,6 +14293,411 @@ var init_events = __esm({
   }
 });
 
+// src/write-queue.ts
+var WriteQueueTracker;
+var init_write_queue = __esm({
+  "src/write-queue.ts"() {
+    "use strict";
+    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;
+var init_write_hooks = __esm({
+  "src/write-hooks.ts"() {
+    "use strict";
+    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
+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();
+    }
+  };
+}
+var TabCoordinator;
+var init_tab_coordination = __esm({
+  "src/tab-coordination.ts"() {
+    "use strict";
+    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);
+      }
+    };
+  }
+});
+
+// src/tab-write-relay.ts
+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";
+}
+var CrossTabWriteRelay;
+var init_tab_write_relay = __esm({
+  "src/tab-write-relay.ts"() {
+    "use strict";
+    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)));
+        });
+      }
+    };
+  }
+});
+
 // src/team/authenticators.ts
 async function enrollAuthenticator(store, vault, keyring, options) {
   const existing = keyring.authenticators.find((a) => a.id === options.id);
@@ -13759,6 +14845,9 @@ var init_strategy10 = __esm({
     NO_TX = {
       async runTransaction() {
         throw NOT_ENABLED5;
+      },
+      async runDryRun() {
+        throw NOT_ENABLED5;
       }
     };
   }
@@ -14135,6 +15224,10 @@ var init_noydb = __esm({
     init_public_envelope();
     init_vault();
     init_events();
+    init_write_queue();
+    init_write_hooks();
+    init_tab_coordination();
+    init_tab_write_relay();
     init_keyring();
     init_authenticators();
     init_unlock_state();
@@ -14154,6 +15247,9 @@ var init_noydb = __esm({
     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();
@@ -14186,6 +15282,10 @@ var init_noydb = __esm({
       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;
@@ -14378,6 +15478,7 @@ var init_noydb = __esm({
         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;
       }
@@ -14805,6 +15906,14 @@ var init_noydb = __esm({
         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(
@@ -14917,6 +16026,133 @@ var init_noydb = __esm({
       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 —
@@ -14943,6 +16179,7 @@ var init_noydb = __esm({
         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);
@@ -14962,6 +16199,8 @@ var init_noydb = __esm({
           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();