@noy-db/hub 0.2.0-pre.26 → 0.2.0-pre.28

package/dist/index.cjs

@@ -7255,6 +7255,249 @@ var init_peer_recover = __esm({
   }
 });
 
+// src/coordination/types.ts
+function isQuorum(writers, generation, excludeWriterId) {
+  return writers.filter((w) => w.writerId !== excludeWriterId).every((w) => w.quiescedAtVersion === generation);
+}
+async function runDrainBarrier(provider, o, run) {
+  await provider.setFence(o.vault, { currentSchemaVersion: o.generation, fenceState: "draining" });
+  await o.onFlush();
+  const deadline = o.now() + o.quiesceTimeoutMs;
+  const seeded = await provider.reachableWriters(o.vault, { staleMs: o.staleMs, now: o.now() });
+  if (!isQuorum(seeded, o.generation, o.writerId)) {
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (fn) => {
+        if (!settled) {
+          settled = true;
+          unsub();
+          fn();
+        }
+      };
+      const unsub = provider.observePresence(o.vault, (writers) => {
+        if (isQuorum(writers, o.generation, o.writerId)) finish(resolve);
+      });
+      const tick = async () => {
+        if (settled) return;
+        if (o.now() >= deadline) {
+          finish(
+            () => reject(
+              new QuiesceTimeoutError(
+                `Cutover of vault "${o.vault}" to generation ${o.generation} timed out after ${o.quiesceTimeoutMs}ms waiting for active writers to quiesce.`
+              )
+            )
+          );
+          return;
+        }
+        if (o.onPoll) await o.onPoll();
+        const w = await provider.reachableWriters(o.vault, { staleMs: o.staleMs, now: o.now() });
+        if (isQuorum(w, o.generation, o.writerId)) finish(resolve);
+        else setTimeout(() => void tick(), 25);
+      };
+      void tick();
+    });
+  }
+  await run();
+}
+var init_types4 = __esm({
+  "src/coordination/types.ts"() {
+    "use strict";
+    init_errors();
+  }
+});
+
+// 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;
+}
+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") && (o["sessionId"] === void 0 || typeof o["sessionId"] === "string");
+}
+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/coordination/store-provider.ts
+function toPresence(doc) {
+  return {
+    writerId: doc.clientId,
+    // Pre-#469 docs (and explicit empty) have no session — fall back to the
+    // writerId so every presence is session-addressable.
+    sessionId: doc.sessionId && doc.sessionId.length > 0 ? doc.sessionId : doc.clientId,
+    lastSeen: doc.lastSeen,
+    quiescedAtVersion: doc.quiescedAtVersion
+  };
+}
+function fenceEqual(a, b) {
+  return a.currentSchemaVersion === b.currentSchemaVersion && a.fenceState === b.fenceState;
+}
+function presenceListEqual(a, b) {
+  if (a.length !== b.length) return false;
+  const key = (w) => `${w.writerId}\0${w.sessionId}\0${w.lastSeen}\0${String(w.quiescedAtVersion)}`;
+  const bk = new Set(b.map(key));
+  return a.every((w) => bk.has(key(w)));
+}
+function unref(timer) {
+  const t = timer;
+  if (typeof t.unref === "function") t.unref();
+}
+var DEFAULT_POLL_INTERVAL_MS, StoreCoordinationProvider;
+var init_store_provider = __esm({
+  "src/coordination/store-provider.ts"() {
+    "use strict";
+    init_fence();
+    init_client_registry();
+    DEFAULT_POLL_INTERVAL_MS = 50;
+    StoreCoordinationProvider = class {
+      #store;
+      #pollIntervalMs;
+      constructor(store, opts) {
+        this.#store = store;
+        this.#pollIntervalMs = opts?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+      }
+      async setFence(vault, fence) {
+        await saveFence(this.#store, vault, fence);
+      }
+      async readFence(vault) {
+        return loadFence(this.#store, vault);
+      }
+      observeFence(vault, onChange) {
+        let last = null;
+        let busy = false;
+        const poll = async () => {
+          if (busy) return;
+          busy = true;
+          try {
+            const fence = await loadFence(this.#store, vault);
+            if (last === null || !fenceEqual(last, fence)) {
+              last = fence;
+              onChange(fence);
+            }
+          } catch {
+          } finally {
+            busy = false;
+          }
+        };
+        void poll();
+        const timer = setInterval(() => void poll(), this.#pollIntervalMs);
+        unref(timer);
+        return () => clearInterval(timer);
+      }
+      async reportPresence(vault, p) {
+        await writeClientDoc(this.#store, vault, p.writerId, {
+          lastSeen: p.lastSeen,
+          quiescedAtVersion: p.quiescedAtVersion,
+          sessionId: p.sessionId
+        });
+      }
+      observePresence(vault, onChange) {
+        let last = null;
+        let busy = false;
+        const poll = async () => {
+          if (busy) return;
+          busy = true;
+          try {
+            const docs = await listClientDocs(this.#store, vault);
+            const writers = docs.map(toPresence);
+            if (last === null || !presenceListEqual(last, writers)) {
+              last = writers;
+              onChange(writers);
+            }
+          } catch {
+          } finally {
+            busy = false;
+          }
+        };
+        void poll();
+        const timer = setInterval(() => void poll(), this.#pollIntervalMs);
+        unref(timer);
+        return () => clearInterval(timer);
+      }
+      async reachableWriters(vault, o) {
+        const docs = await listClientDocs(this.#store, vault);
+        return docs.map(toPresence).filter((w) => o.now - w.lastSeen <= o.staleMs);
+      }
+    };
+  }
+});
+
+// src/coordination/index.ts
+var init_coordination = __esm({
+  "src/coordination/index.ts"() {
+    "use strict";
+    init_types4();
+    init_store_provider();
+  }
+});
+
 // src/crdt/strategy.ts
 var NOT_ENABLED, NO_CRDT;
 var init_strategy = __esm({
@@ -7335,13 +7578,14 @@ function stripDisallowed(str, scripts) {
   for (const ch of str) if (ok.test(ch)) out += ch;
   return out;
 }
-function enforceScript(value, field, descriptor) {
+function enforceScript(value, field, descriptor, exempt) {
   const opt = descriptor.options;
   if (!opt.script) return { value, warnings: [] };
   const mode = opt.onScriptViolation ?? "reject";
   const warnings = [];
   let out = value;
   for (const [locale, raw] of Object.entries(value)) {
+    if (exempt?.has(locale)) continue;
     if (typeof raw !== "string") continue;
     const allowed = allowedFor(descriptor, locale);
     if (fullMatcher(allowed).test(raw)) continue;
@@ -7432,8 +7676,18 @@ var init_script = __esm({
 
 // src/i18n/core.ts
 function i18nText(options) {
+  if (options.densifyOnWrite === true && hasThrowPolicy(options.onMissing)) {
+    throw new Error(
+      `i18nText: densifyOnWrite cannot be combined with an explicit onMissing 'throw' policy \u2014 densify fills every empty slot, so a 'throw' would be unreachable. Remove the 'throw' policy or disable densifyOnWrite.`
+    );
+  }
   return { _noydbI18nText: true, options };
 }
+function hasThrowPolicy(onMissing) {
+  if (onMissing === void 0) return false;
+  if (typeof onMissing === "string") return onMissing === "throw";
+  return Object.values(onMissing).includes("throw");
+}
 function isI18nTextDescriptor(x) {
   return typeof x === "object" && x !== null && x._noydbI18nText === true;
 }
@@ -7631,8 +7885,15 @@ function applyI18nLocale(record, i18nFields, locale, fallback, layer = "read") {
     };
     result = applyAtPath(result, field, locale, fallback, opts);
   }
+  result = stripI18nFilled(result);
   return result;
 }
+function stripI18nFilled(record) {
+  if (!Object.prototype.hasOwnProperty.call(record, "_i18nFilled")) return record;
+  const rest = { ...record };
+  delete rest._i18nFilled;
+  return rest;
+}
 var init_core = __esm({
   "src/i18n/core.ts"() {
     "use strict";
@@ -8662,6 +8923,11 @@ var init_strategy2 = __esm({
       enforceScript(value) {
         return { value, warnings: [] };
       },
+      computeExemptFills() {
+        return /* @__PURE__ */ new Map();
+      },
+      densify() {
+      },
       buildDictionaryHandle() {
         throw notEnabled("vault.dictionary()");
       }
@@ -13625,6 +13891,12 @@ var init_collection = __esm({
        * Declared via the `i18nFields` collection option.
        */
       i18nFields;
+      /**
+       * #435 — the densify-enabled subset of {@link i18nFields} (fields whose
+       * descriptor opts in via `densifyOnWrite: true`). `undefined` when none opt
+       * in, so the write path skips all densify work for ordinary collections.
+       */
+      i18nDensifyFields;
       /**
        * Map of field name → `DictKeyDescriptor` for fields declared with
        * `dictKey()`. Used by `get()`/`list()` to add `<field>Label` virtual
@@ -13811,6 +14083,10 @@ var init_collection = __esm({
         this.refEnforcer = opts.refEnforcer;
         this.joinResolver = opts.joinResolver;
         this.i18nFields = opts.i18nFields;
+        const densifyFields = opts.i18nFields ? Object.fromEntries(
+          Object.entries(opts.i18nFields).filter(([, d]) => d.options.densifyOnWrite === true)
+        ) : {};
+        this.i18nDensifyFields = Object.keys(densifyFields).length > 0 ? densifyFields : void 0;
         this.dictKeyFields = opts.dictKeyFields;
         if (opts.moneyFields) validateMoneyFieldPaths(opts.moneyFields);
         this.moneyFields = opts.moneyFields;
@@ -14130,6 +14406,32 @@ var init_collection = __esm({
           if (busAfterPut) await this.subsystemBus.dispatch("afterPut", event);
         }
       }
+      /**
+       * #435 — resolve the prior stored record (with its `_i18nFilled` marker) for
+       * densify. Eager: in-memory cache; lazy: LRU then adapter. undefined if absent.
+       */
+      async resolveDensifyPrior(id) {
+        if (this.lazy && this.lru) {
+          const cached = this.lru.get(id);
+          if (cached) return cached.record;
+          const env = await this.adapter.get(this.vault, this.name, id);
+          if (!env) return void 0;
+          const rec = await this.decryptRecord(env);
+          return rec === null ? void 0 : rec;
+        }
+        await this.ensureHydrated();
+        return this.cache.get(id)?.record;
+      }
+      /**
+       * #435 — densify provenance for a record: which i18n slots were auto-filled,
+       * e.g. `{ name: ['en'] }`. undefined when nothing was filled. The marker is
+       * stripped from ordinary reads; this is the sanctioned audit accessor.
+       */
+      async i18nProvenance(id) {
+        const prior = await this.resolveDensifyPrior(id);
+        const marker = prior?.["_i18nFilled"];
+        return marker && Object.keys(marker).length > 0 ? marker : void 0;
+      }
       /**
        * Validate a record against this collection's schema WITHOUT writing it.
        * Returns the (possibly coerced) record on success; throws
@@ -14244,6 +14546,16 @@ var init_collection = __esm({
             setAtPathInPlace(obj, field, translated);
           }
         }
+        let densifyPrior;
+        let exemptFills;
+        if (this.i18nDensifyFields) {
+          densifyPrior = await this.resolveDensifyPrior(id);
+          exemptFills = this.i18nStrategy.computeExemptFills(
+            densifyPrior,
+            record,
+            this.i18nDensifyFields
+          );
+        }
         if (this.i18nFields) {
           const obj = record;
           for (const [field, descriptor] of Object.entries(this.i18nFields)) {
@@ -14251,18 +14563,38 @@ var init_collection = __esm({
             for (const leaf of getAtPath(obj, field)) {
               if (!leaf || typeof leaf !== "object" || Array.isArray(leaf)) continue;
               const leafMap = leaf;
-              const { value: cleaned } = this.i18nStrategy.enforceScript(
+              const { value: cleaned, warnings } = this.i18nStrategy.enforceScript(
                 leafMap,
                 field,
-                descriptor
+                descriptor,
+                exemptFills?.get(field)
               );
               if (cleaned !== leafMap) Object.assign(leafMap, cleaned);
+              const mode = descriptor.options.onScriptViolation;
+              if (mode === "warn" || mode === "filter") {
+                for (const w of warnings) {
+                  this.emitter.emit("i18n:script-violation", {
+                    vault: this.vault,
+                    collection: this.name,
+                    id,
+                    mode,
+                    warning: w
+                  });
+                }
+              }
             }
           }
         }
         if (this.i18nPutValidator !== void 0) {
           this.i18nPutValidator(record);
         }
+        if (this.i18nDensifyFields) {
+          this.i18nStrategy.densify(
+            record,
+            densifyPrior,
+            this.i18nDensifyFields
+          );
+        }
         if (this.refEnforcer !== void 0) {
           await this.refEnforcer.enforceRefsOnPut(this.name, record);
         }
@@ -15116,7 +15448,7 @@ var init_collection = __esm({
         }
         await this.ensureHydrated();
         const entries = [];
-        for (const [id, e] of this.cache) entries.push({ id, record: e.record });
+        for (const [id, e] of this.cache) entries.push({ id, record: stripI18nFilled(e.record) });
         return searchScan(entries, field, query, opts);
       }
       // ─── Bulk operations ─────────────────────────────────────
@@ -16030,7 +16362,7 @@ var init_collection = __esm({
         const hasStaticDisplay = hasDict && this.dictKeyFields !== void 0 && Object.values(this.dictKeyFields).some(
           (d) => isStaticDictDescriptor(d) && d.displayLocale !== void 0
         );
-        if (!locale && !hasStaticDisplay) return result;
+        if (!locale && !hasStaticDisplay) return stripI18nFilled(result);
         const layer = localeOpts?._layer ?? "read";
         if (locale && hasI18n && this.i18nFields) {
           result = this.i18nStrategy.applyI18nLocale(result, this.i18nFields, locale, localeOpts?.fallback, layer);
@@ -16097,7 +16429,7 @@ var init_collection = __esm({
           }
           result = withLabels;
         }
-        return result;
+        return stripI18nFilled(result);
       }
       /**
        * Low-level: encrypt a pre-serialised JSON string into an EncryptedEnvelope.
@@ -17764,108 +18096,18 @@ var init_magic_link_grant = __esm({
   }
 });
 
-// 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();
+    init_coordination();
     SchemaFenceController = class {
-      #store;
+      #coordination;
       #vault;
       #onFlush;
-      #clientId;
+      #writerId;
       #now;
       #staleMs;
       #quiesceTimeoutMs;
@@ -17873,10 +18115,10 @@ var init_fence_controller = __esm({
       #snapshot = 0;
       #pending = /* @__PURE__ */ new Map();
       constructor(opts) {
-        this.#store = opts.store;
+        this.#coordination = opts.coordination;
         this.#vault = opts.vault;
         this.#onFlush = opts.onFlush;
-        this.#clientId = opts.clientId ?? "migrator";
+        this.#writerId = opts.clientId ?? "migrator";
         this.#now = opts.now ?? (() => Date.now());
         this.#staleMs = opts.staleMs ?? 3e4;
         this.#quiesceTimeoutMs = opts.quiesceTimeoutMs ?? 6e4;
@@ -17885,7 +18127,7 @@ var init_fence_controller = __esm({
       }
       /** Capture the generation snapshot at vault-open. */
       async init() {
-        this.#snapshot = (await loadFence(this.#store, this.#vault)).currentSchemaVersion;
+        this.#snapshot = (await this.#coordination.readFence(this.#vault)).currentSchemaVersion;
       }
       /** Record a per-collection pending cutover (from a registration `cutover` decision). */
       registerPendingCutover(collection, transform) {
@@ -17893,7 +18135,7 @@ var init_fence_controller = __esm({
       }
       /** Write-path gate. Throws when behind, fenced, or this collection is cutover-pending. */
       async assertWritable(collection) {
-        const fence = await loadFence(this.#store, this.#vault);
+        const fence = await this.#coordination.readFence(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.`
@@ -17912,49 +18154,49 @@ var init_fence_controller = __esm({
        * 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.
+       * inside {@link runDrainBarrier}). `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 base = await this.#coordination.readFence(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");
+        this.#emit({ currentSchemaVersion: generation, fenceState: "draining" });
         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;
+        await runDrainBarrier(
+          this.#coordination,
+          {
+            vault: this.#vault,
+            generation,
+            writerId: this.#writerId,
+            onFlush: this.#onFlush,
+            staleMs: this.#staleMs,
+            quiesceTimeoutMs: this.#quiesceTimeoutMs,
+            now: this.#now,
+            ...opts?.onPoll ? { onPoll: opts.onPoll } : {}
+          },
+          async () => {
+            await this.#setState(generation, "migrating");
+            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);
+        const fence = await this.#coordination.readFence(this.#vault);
         await this.#setState(fence.currentSchemaVersion, "normal");
       }
       async #setState(currentSchemaVersion, fenceState) {
-        await saveFence(this.#store, this.#vault, { currentSchemaVersion, fenceState });
+        await this.#coordination.setFence(this.#vault, { currentSchemaVersion, fenceState });
         this.#emit({ currentSchemaVersion, fenceState });
       }
     };
@@ -17966,12 +18208,11 @@ var FenceWatcher;
 var init_fence_watcher = __esm({
   "src/schema-update/fence-watcher.ts"() {
     "use strict";
-    init_fence();
-    init_client_registry();
     FenceWatcher = class {
-      #store;
+      #coordination;
       #vault;
-      #clientId;
+      #writerId;
+      #sessionId;
       #onFlush;
       #now;
       #emit;
@@ -17979,9 +18220,10 @@ var init_fence_watcher = __esm({
       #quiescedAtVersion = null;
       #timer;
       constructor(opts) {
-        this.#store = opts.store;
+        this.#coordination = opts.coordination;
         this.#vault = opts.vault;
-        this.#clientId = opts.clientId;
+        this.#writerId = opts.clientId;
+        this.#sessionId = opts.sessionId ?? opts.clientId;
         this.#onFlush = opts.onFlush;
         this.#now = opts.now ?? (() => Date.now());
         this.#emit = opts.emit ?? (() => {
@@ -17989,14 +18231,16 @@ var init_fence_watcher = __esm({
       }
       /** Publish liveness (and the current ack) without changing quiesce state. */
       async beat() {
-        await writeClientDoc(this.#store, this.#vault, this.#clientId, {
+        await this.#coordination.reportPresence(this.#vault, {
+          writerId: this.#writerId,
+          sessionId: this.#sessionId,
           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);
+        const fence = await this.#coordination.readFence(this.#vault);
         if (fence.fenceState !== this.#lastState) {
           this.#lastState = fence.fenceState;
           this.#emit({ currentSchemaVersion: fence.currentSchemaVersion, fenceState: fence.fenceState });
@@ -19308,10 +19552,11 @@ var init_vault = __esm({
         this.keyring = opts.keyring;
         this.encrypted = opts.encrypted;
         this.schemaFence = new SchemaFenceController({
-          store: this.adapter,
+          coordination: this.noydb.coordination,
           vault: this.name,
           onFlush: () => this.noydb._writeQueueTracker.onFlush(),
           clientId: this.noydb._clientId,
+          sessionId: this.noydb._sessionId,
           emit: (e) => this.emitter.emit("schema:fence-changed", { vault: this.name, ...e })
         });
         this.emitter = opts.emitter;
@@ -19707,9 +19952,10 @@ var init_vault = __esm({
         if (this.#fenceCoordinationStarted) return;
         this.#fenceCoordinationStarted = true;
         this.#fenceWatcher = new FenceWatcher({
-          store: this.adapter,
+          coordination: this.noydb.coordination,
           vault: this.name,
           clientId: this.noydb._clientId,
+          sessionId: this.noydb._sessionId,
           onFlush: () => this.noydb._writeQueueTracker.onFlush(),
           emit: (e) => this.emitter.emit("schema:fence-changed", { vault: this.name, ...e })
         });
@@ -23450,6 +23696,7 @@ var init_noydb = __esm({
     init_recovery();
     init_managed_passphrase();
     init_ulid();
+    init_coordination();
     init_errors2();
     init_auth_introspection();
     init_public_envelope();
@@ -23493,6 +23740,10 @@ var init_noydb = __esm({
       writeHooks = new WriteHookRegistry();
       subsystemBus = new SubsystemBus();
       clientId = generateULID();
+      /** Session that owns this instance's writers (one user's writers across vaults). */
+      sessionId;
+      /** Drain-barrier coordination transport for the schema fence (#469). */
+      coordinationProvider;
       vaultCache = /* @__PURE__ */ new Map();
       keyringCache = /* @__PURE__ */ new Map();
       syncEngines = /* @__PURE__ */ new Map();
@@ -23567,6 +23818,8 @@ var init_noydb = __esm({
             "[noydb] debugPlaintext is ON \u2014 records are stored UNENCRYPTED and laid out for native store inspection. NEVER use this for production or client data."
           );
         }
+        this.sessionId = options.sessionId ?? generateULID();
+        this.coordinationProvider = options.coordinationStrategy ?? new StoreCoordinationProvider(options.store);
         this.txStrategy = options.txStrategy ?? NO_TX;
         this.forgetStrategy = options.forgetStrategy ?? NO_FORGET;
         this.sessionStrategy = options.sessionStrategy ?? NO_SESSION;
@@ -24620,6 +24873,18 @@ var init_noydb = __esm({
       get _clientId() {
         return this.clientId;
       }
+      /** @internal Session that owns this instance's writers (#469). */
+      get _sessionId() {
+        return this.sessionId;
+      }
+      /**
+       * @internal Drain-barrier coordination transport for the schema fence (#469).
+       * The default store-backed provider reproduces today's fence behavior; a
+       * `by-*` real-time transport is injected via `coordinationStrategy`.
+       */
+      get coordination() {
+        return this.coordinationProvider;
+      }
       /**
        * Soft-lock a single vault: clear its in-memory keyring, DEKs, vault
        * instance, sync engine, policy enforcer, and active-tier entry —
@@ -28036,8 +28301,8 @@ function withRetry(opts = {}) {
       } catch (err) {
         lastError = err;
         if (attempt >= maxRetries || !shouldRetry(err)) throw err;
-        const delay2 = backoffMs * Math.pow(2, attempt) * (1 + Math.random() * jitter);
-        await new Promise((r) => setTimeout(r, delay2));
+        const delay = backoffMs * Math.pow(2, attempt) * (1 + Math.random() * jitter);
+        await new Promise((r) => setTimeout(r, delay));
       }
     }
     throw lastError;