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

package/dist/bundle/index.cjs

@@ -4353,9 +4353,252 @@ 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_types3 = __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_COLLECTION2, FENCE_RECORD_ID);
+  if (!envelope) return DEFAULT_FENCE;
+  try {
+    const parsed = JSON.parse(envelope._data);
+    if (!isFenceDoc(parsed)) return DEFAULT_FENCE;
+    return parsed;
+  } catch {
+    return DEFAULT_FENCE;
+  }
+}
+async function saveFence(store, vault, fence) {
+  const envelope = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify(fence)
+  };
+  await store.put(vault, META_COLLECTION2, FENCE_RECORD_ID, envelope);
+}
+function isFenceDoc(x) {
+  if (x === null || typeof x !== "object") return false;
+  const o = x;
+  return typeof o["currentSchemaVersion"] === "number" && (o["fenceState"] === "normal" || o["fenceState"] === "draining" || o["fenceState"] === "migrating" || o["fenceState"] === "complete");
+}
+var FENCE_RECORD_ID, META_COLLECTION2, DEFAULT_FENCE;
+var init_fence = __esm({
+  "src/schema-update/fence.ts"() {
+    "use strict";
+    init_types();
+    FENCE_RECORD_ID = "schema-fence";
+    META_COLLECTION2 = "_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_COLLECTION3, `${CLIENT_PREFIX}${clientId}`, envelope);
+}
+async function listClientDocs(store, vault) {
+  const ids = await store.list(vault, META_COLLECTION3);
+  const out = [];
+  for (const id of ids) {
+    if (!id.startsWith(CLIENT_PREFIX)) continue;
+    const env = await store.get(vault, META_COLLECTION3, id);
+    if (!env) continue;
+    try {
+      const parsed = JSON.parse(env._data);
+      if (isClientDoc(parsed)) out.push(parsed);
+    } catch {
+    }
+  }
+  return out;
+}
+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_COLLECTION3, CLIENT_PREFIX;
+var init_client_registry = __esm({
+  "src/schema-update/client-registry.ts"() {
+    "use strict";
+    init_types();
+    META_COLLECTION3 = "_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_types3();
+    init_store_provider();
+  }
+});
+
 // src/policy/storage.ts
 async function loadVaultPolicy(store, vault) {
-  const envelope = await store.get(vault, META_COLLECTION2, POLICY_RECORD_ID);
+  const envelope = await store.get(vault, META_COLLECTION4, POLICY_RECORD_ID);
   if (!envelope) return void 0;
   try {
     const parsed = JSON.parse(envelope._data);
@@ -4373,7 +4616,7 @@ async function saveVaultPolicy(store, vault, policy) {
     _iv: "",
     _data: JSON.stringify(policy)
   };
-  await store.put(vault, META_COLLECTION2, POLICY_RECORD_ID, envelope);
+  await store.put(vault, META_COLLECTION4, POLICY_RECORD_ID, envelope);
 }
 function isVaultPolicy(x) {
   if (x === null || typeof x !== "object") return false;
@@ -4381,12 +4624,12 @@ function isVaultPolicy(x) {
   const gates = x.gates;
   return gates !== null && typeof gates === "object";
 }
-var META_COLLECTION2, POLICY_RECORD_ID;
+var META_COLLECTION4, POLICY_RECORD_ID;
 var init_storage5 = __esm({
   "src/policy/storage.ts"() {
     "use strict";
     init_types();
-    META_COLLECTION2 = "_meta";
+    META_COLLECTION4 = "_meta";
     POLICY_RECORD_ID = "policy";
   }
 });
@@ -4541,7 +4784,7 @@ function resolveSchema(schema) {
   };
 }
 var PUBLIC_ENVELOPE_FIELDS, DEFAULT_PUBLIC_ENVELOPE_SCHEMA;
-var init_types3 = __esm({
+var init_types4 = __esm({
   "src/meta/public-envelope/types.ts"() {
     "use strict";
     PUBLIC_ENVELOPE_FIELDS = [
@@ -4579,7 +4822,7 @@ __export(public_envelope_exports, {
 var init_public_envelope = __esm({
   "src/meta/public-envelope/index.ts"() {
     "use strict";
-    init_types3();
+    init_types4();
     init_schema();
     init_storage();
   }
@@ -4845,8 +5088,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";
@@ -5410,6 +5660,11 @@ var init_strategy2 = __esm({
       enforceScript(value) {
         return { value, warnings: [] };
       },
+      computeExemptFills() {
+        return /* @__PURE__ */ new Map();
+      },
+      densify() {
+      },
       buildDictionaryHandle() {
         throw notEnabled("vault.dictionary()");
       }
@@ -9584,6 +9839,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
@@ -9770,6 +10031,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;
@@ -10089,6 +10354,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
@@ -10203,6 +10494,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)) {
@@ -10210,18 +10511,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);
         }
@@ -11075,7 +11396,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 ─────────────────────────────────────
@@ -11989,7 +12310,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);
@@ -12056,7 +12377,7 @@ var init_collection = __esm({
           }
           result = withLabels;
         }
-        return result;
+        return stripI18nFilled(result);
       }
       /**
        * Low-level: encrypt a pre-serialised JSON string into an EncryptedEnvelope.
@@ -15134,108 +15455,18 @@ var init_gate = __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;
@@ -15243,10 +15474,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;
@@ -15255,7 +15486,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) {
@@ -15263,7 +15494,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.`
@@ -15282,49 +15513,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 });
       }
     };
@@ -15336,12 +15567,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;
@@ -15349,9 +15579,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 ?? (() => {
@@ -15359,14 +15590,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 });
@@ -16678,10 +16911,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;
@@ -17077,9 +17311,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 })
         });
@@ -21043,6 +21278,7 @@ var init_noydb = __esm({
     init_recovery();
     init_managed_passphrase();
     init_ulid();
+    init_coordination();
     init_errors2();
     init_auth_introspection();
     init_public_envelope();
@@ -21086,6 +21322,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();
@@ -21160,6 +21400,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;
@@ -22213,6 +22455,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 —