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

package/dist/index.cjs

@@ -46,7 +46,7 @@ var init_types = __esm({
 });
 
 // src/errors.ts
-var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, PeriodClosedError, RecordLockedError, FieldFrozenError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, PeriodClosedError, RecordLockedError, FieldFrozenError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -377,6 +377,42 @@ var init_errors = __esm({
         this.direction = direction;
       }
     };
+    SchemaUpdateError = class extends NoydbError {
+      constructor(code, message) {
+        super(code, message);
+        this.name = "SchemaUpdateError";
+      }
+    };
+    NonAdditiveSchemaChangeError = class extends SchemaUpdateError {
+      constructor(message) {
+        super("NON_ADDITIVE_SCHEMA_CHANGE", message);
+        this.name = "NonAdditiveSchemaChangeError";
+      }
+    };
+    SchemaLockedError = class extends SchemaUpdateError {
+      constructor(message) {
+        super("SCHEMA_LOCKED", message);
+        this.name = "SchemaLockedError";
+      }
+    };
+    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;
@@ -3506,6 +3542,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.
@@ -3956,6 +3999,7 @@ __export(src_exports, {
   MaterializedViewTooLargeError: () => MaterializedViewTooLargeError,
   MemoryRecipientSealer: () => MemoryRecipientSealer,
   MemorySealingKeyProvider: () => MemorySealingKeyProvider,
+  MigrationRequiredError: () => MigrationRequiredError,
   MissingTranslationError: () => MissingTranslationError,
   NOYDB_BACKUP_VERSION: () => NOYDB_BACKUP_VERSION,
   NOYDB_BUNDLE_FORMAT_VERSION: () => NOYDB_BUNDLE_FORMAT_VERSION,
@@ -3966,6 +4010,7 @@ __export(src_exports, {
   NOYDB_SYNC_VERSION: () => NOYDB_SYNC_VERSION,
   NetworkError: () => NetworkError,
   NoAccessError: () => NoAccessError,
+  NonAdditiveSchemaChangeError: () => NonAdditiveSchemaChangeError,
   NotFoundError: () => NotFoundError,
   Noydb: () => Noydb,
   NoydbError: () => NoydbError,
@@ -3987,6 +4032,7 @@ __export(src_exports, {
   PrivilegeEscalationError: () => PrivilegeEscalationError,
   Query: () => Query,
   QuickUnlockStore: () => QuickUnlockStore,
+  QuiesceTimeoutError: () => QuiesceTimeoutError,
   ReadOnlyAtInstantError: () => ReadOnlyAtInstantError,
   ReadOnlyError: () => ReadOnlyError,
   ReadOnlyFrameError: () => ReadOnlyFrameError,
@@ -4002,6 +4048,9 @@ __export(src_exports, {
   STRICT_POLICY: () => STRICT_POLICY,
   SYNC_CREDENTIALS_COLLECTION: () => SYNC_CREDENTIALS_COLLECTION,
   ScanBuilder: () => ScanBuilder,
+  SchemaFenceError: () => SchemaFenceError,
+  SchemaLockedError: () => SchemaLockedError,
+  SchemaUpdateError: () => SchemaUpdateError,
   SchemaValidationError: () => SchemaValidationError,
   SessionExpiredError: () => SessionExpiredError,
   SessionNotFoundError: () => SessionNotFoundError,
@@ -4028,6 +4077,7 @@ __export(src_exports, {
   VaultInstant: () => VaultInstant,
   WeakPassphraseError: () => WeakPassphraseError,
   activeSessionCount: () => activeSessionCount,
+  additiveOnly: () => additiveOnly,
   applyI18nLocale: () => applyI18nLocale,
   applyJoins: () => applyJoins,
   applyPatch: () => applyPatch,
@@ -4035,6 +4085,7 @@ __export(src_exports, {
   assertTierAccess: () => assertTierAccess,
   avg: () => avg,
   base64ToBuffer: () => base64ToBuffer,
+  blindUpdate: () => blindUpdate,
   bufferToBase64: () => bufferToBase64,
   buildLiveQuery: () => buildLiveQuery,
   buildRecipientKeyringFile: () => buildRecipientKeyringFile,
@@ -4043,6 +4094,7 @@ __export(src_exports, {
   checkGate: () => checkGate,
   clearDevUnlock: () => clearDevUnlock,
   computePatch: () => computePatch,
+  coordinatedCutover: () => coordinatedCutover,
   count: () => count,
   createBundleStore: () => createBundleStore,
   createEnforcer: () => createEnforcer,
@@ -4121,6 +4173,7 @@ __export(src_exports, {
   loadShamirRecoveryEntries: () => loadShamirRecoveryEntries,
   loadUserEnvelope: () => loadUserEnvelope,
   loadVaultPolicy: () => loadVaultPolicy,
+  lockSchema: () => lockSchema,
   magicLinkGrantRecordId: () => magicLinkGrantRecordId,
   max: () => max,
   mergeCrdtStates: () => mergeCrdtStates,
@@ -5202,6 +5255,127 @@ function createBundleStore(factory) {
   return factory;
 }
 
+// src/persisted-schemas/canonicalize.ts
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalize).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  const parts = keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]));
+  return "{" + parts.join(",") + "}";
+}
+
+// src/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/schema-update/strategies.ts
+init_errors();
+function blindUpdate() {
+  return { name: "blindUpdate", onSchemaDelta: () => ({ action: "allow" }) };
+}
+function additiveOnly() {
+  return {
+    name: "additiveOnly",
+    onSchemaDelta(delta) {
+      if (delta.kind === "non-additive") {
+        return {
+          action: "reject",
+          error: new NonAdditiveSchemaChangeError(
+            `Non-additive schema change to "${delta.collection}" (added: [${delta.added.join(", ")}], removed: [${delta.removed.join(", ")}], changed: [${delta.changed.map((c) => c.field).join(", ")}]). Register a coordinatedCutover() strategy to migrate, or revert the change.`
+          )
+        };
+      }
+      return { action: "allow" };
+    }
+  };
+}
+function lockSchema(opts) {
+  const fields = opts?.fields;
+  return {
+    name: "lockSchema",
+    onSchemaDelta(delta) {
+      if (delta.kind === "none") return { action: "allow" };
+      const touched = fields ? [...delta.added, ...delta.removed, ...delta.changed.map((c) => c.field)].filter((f) => fields.includes(f)) : ["<any>"];
+      if (touched.length === 0) return { action: "allow" };
+      return {
+        action: "reject",
+        error: new SchemaLockedError(
+          `Schema for "${delta.collection}" is locked` + (fields ? ` on fields [${fields.join(", ")}] (touched: [${touched.join(", ")}])` : "") + `; the change was refused.`
+        )
+      };
+    }
+  };
+}
+
+// src/schema-update/cutover.ts
+function coordinatedCutover(opts) {
+  return {
+    name: "coordinatedCutover",
+    onSchemaDelta(delta) {
+      if (delta.kind === "non-additive") {
+        return { action: "cutover", transform: opts.transform };
+      }
+      return { action: "allow" };
+    }
+  };
+}
+
+// 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/store/sync-policy.ts
 var INDEXED_STORE_POLICY = {
   push: { mode: "on-change", minIntervalMs: 0, onUnload: true },
@@ -5776,8 +5950,8 @@ function withRetry(opts = {}) {
       } catch (err) {
         lastError = err;
         if (attempt >= maxRetries || !shouldRetry(err)) throw err;
-        const delay = backoffMs * Math.pow(2, attempt) * (1 + Math.random() * jitter);
-        await new Promise((r) => setTimeout(r, delay));
+        const delay2 = backoffMs * Math.pow(2, attempt) * (1 + Math.random() * jitter);
+        await new Promise((r) => setTimeout(r, delay2));
       }
     }
     throw lastError;
@@ -6824,20 +6998,6 @@ function formatPath(path) {
   ).join(".");
 }
 
-// src/persisted-schemas/canonicalize.ts
-function canonicalize(value) {
-  if (value === null || typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return "[" + value.map(canonicalize).join(",") + "]";
-  }
-  const obj = value;
-  const keys = Object.keys(obj).sort();
-  const parts = keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]));
-  return "{" + parts.join(",") + "}";
-}
-
 // src/persisted-schemas/derive.ts
 init_crypto();
 function isZodSchema(value) {
@@ -6918,10 +7078,22 @@ 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 && isPlainObject(stored.jsonSchema) && isPlainObject(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 isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 function isEquivalent(a, b) {
   if (a.kind !== b.kind) return false;
@@ -7063,7 +7235,7 @@ var CollectionInstant = class {
       if (e.collection !== this.name || e.id !== id) continue;
       if (e.ts > this.targetTs) break;
       if (e.op === "amendment" || e.op === "lifecycle") continue;
-      latest = { op: e.op, version: e.version };
+      latest = { op: e.op === "migration" ? "put" : e.op, version: e.version };
     }
     if (!latest) return null;
     if (latest.op === "delete") return null;
@@ -9016,7 +9188,7 @@ var UserApi = class {
   }
 };
 function deepMerge(source, patch) {
-  if (!isPlainObject(source) || !isPlainObject(patch)) {
+  if (!isPlainObject2(source) || !isPlainObject2(patch)) {
     return patch;
   }
   const out = { ...source };
@@ -9029,8 +9201,8 @@ function deepMerge(source, patch) {
       continue;
     }
     const sourceVal = source[key];
-    if (isPlainObject(patchVal)) {
-      const recurseSource = isPlainObject(sourceVal) ? sourceVal : {};
+    if (isPlainObject2(patchVal)) {
+      const recurseSource = isPlainObject2(sourceVal) ? sourceVal : {};
       out[key] = deepMerge(recurseSource, patchVal);
     } else {
       out[key] = patchVal;
@@ -9038,7 +9210,7 @@ function deepMerge(source, patch) {
   }
   return out;
 }
-function isPlainObject(x) {
+function isPlainObject2(x) {
   if (x === null || typeof x !== "object") return false;
   if (Array.isArray(x)) return false;
   const proto = Object.getPrototypeOf(x);
@@ -11521,7 +11693,10 @@ var NO_BLOBS = {
 
 // src/tx/transaction.ts
 init_errors();
+init_ulid();
 var TxContext = class {
+  /** Stable id for this transaction; shared by all writes it performs (#230). */
+  txId = generateULID();
   /** @internal */
   _ops = [];
   /**
@@ -11886,6 +12061,11 @@ var Collection = class {
   keyring;
   encrypted;
   emitter;
+  writeQueue;
+  schemaUpdateGate;
+  schemaFence;
+  writeHooks;
+  activeTxId;
   getDEK;
   onDirty;
   historyConfig;
@@ -12160,6 +12340,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;
@@ -12385,7 +12570,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
@@ -12396,6 +12582,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();
     }
@@ -12772,8 +13011,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 count2 = 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(() => {
+        });
+      }
+      count2++;
+    }
+    return count2;
+  }
+  /** @internal Untracked delete body — call {@link delete}, not this. */
+  async deleteInternal(id) {
     await this._doDelete(id, false);
   }
   /**
@@ -13596,6 +13898,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);
@@ -15425,6 +15742,245 @@ function isMagicLinkGrantExpired(payload, now = /* @__PURE__ */ new Date()) {
   return payload.until <= now.toISOString();
 }
 
+// src/schema-update/fence.ts
+init_types();
+var FENCE_RECORD_ID = "schema-fence";
+var META_COLLECTION3 = "_meta";
+var DEFAULT_FENCE = { currentSchemaVersion: 0, fenceState: "normal" };
+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");
+}
+
+// src/schema-update/fence-controller.ts
+init_errors();
+
+// src/schema-update/client-registry.ts
+init_types();
+var META_COLLECTION4 = "_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_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");
+}
+
+// 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)) {
@@ -15771,6 +16327,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
@@ -15886,6 +16449,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;
@@ -15994,6 +16564,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,
@@ -16001,6 +16600,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,
@@ -16087,7 +16691,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 {
@@ -16120,6 +16724,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
@@ -17548,6 +18233,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,
@@ -18187,6 +18893,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/tx/strategy.ts
 var NOT_ENABLED5 = new Error(
   'Multi-record transactions require the tx strategy. Import `{ withTransactions }` from "@noy-db/hub/tx" and pass it to `createNoydb({ txStrategy: withTransactions() })`.'
@@ -18194,6 +19281,9 @@ var NOT_ENABLED5 = new Error(
 var NO_TX = {
   async runTransaction() {
     throw NOT_ENABLED5;
+  },
+  async runDryRun() {
+    throw NOT_ENABLED5;
   }
 };
 
@@ -18491,6 +19581,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();
@@ -18523,6 +19616,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;
@@ -18715,6 +19812,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;
   }
@@ -19142,6 +20240,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(
@@ -19254,6 +20360,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 —
@@ -19280,6 +20513,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);
@@ -19299,6 +20533,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();
@@ -22101,6 +23337,7 @@ function shortJSON(value) {
   MaterializedViewTooLargeError,
   MemoryRecipientSealer,
   MemorySealingKeyProvider,
+  MigrationRequiredError,
   MissingTranslationError,
   NOYDB_BACKUP_VERSION,
   NOYDB_BUNDLE_FORMAT_VERSION,
@@ -22111,6 +23348,7 @@ function shortJSON(value) {
   NOYDB_SYNC_VERSION,
   NetworkError,
   NoAccessError,
+  NonAdditiveSchemaChangeError,
   NotFoundError,
   Noydb,
   NoydbError,
@@ -22132,6 +23370,7 @@ function shortJSON(value) {
   PrivilegeEscalationError,
   Query,
   QuickUnlockStore,
+  QuiesceTimeoutError,
   ReadOnlyAtInstantError,
   ReadOnlyError,
   ReadOnlyFrameError,
@@ -22147,6 +23386,9 @@ function shortJSON(value) {
   STRICT_POLICY,
   SYNC_CREDENTIALS_COLLECTION,
   ScanBuilder,
+  SchemaFenceError,
+  SchemaLockedError,
+  SchemaUpdateError,
   SchemaValidationError,
   SessionExpiredError,
   SessionNotFoundError,
@@ -22173,6 +23415,7 @@ function shortJSON(value) {
   VaultInstant,
   WeakPassphraseError,
   activeSessionCount,
+  additiveOnly,
   applyI18nLocale,
   applyJoins,
   applyPatch,
@@ -22180,6 +23423,7 @@ function shortJSON(value) {
   assertTierAccess,
   avg,
   base64ToBuffer,
+  blindUpdate,
   bufferToBase64,
   buildLiveQuery,
   buildRecipientKeyringFile,
@@ -22188,6 +23432,7 @@ function shortJSON(value) {
   checkGate,
   clearDevUnlock,
   computePatch,
+  coordinatedCutover,
   count,
   createBundleStore,
   createEnforcer,
@@ -22266,6 +23511,7 @@ function shortJSON(value) {
   loadShamirRecoveryEntries,
   loadUserEnvelope,
   loadVaultPolicy,
+  lockSchema,
   magicLinkGrantRecordId,
   max,
   mergeCrdtStates,