@panphora/clayjs 1.17.0 → 1.18.0

package/src/route/route.js

@@ -119,7 +119,9 @@ export function set(patch, { replace = false } = {}) {
     history.replaceState(history.state, "", bare + hash);
     apply();
   } else if (hash) {
+    // Applied now, as the other branches are: the hashchange that follows finds nothing new.
     location.hash = hash;
+    apply();
   } else {
     history.pushState(history.state, "", bare);
     apply();
@@ -161,6 +163,7 @@ export function start() {
   mirrorRoot(parseHash(location.hash));
   window.addEventListener("hashchange", apply);
   document.addEventListener("clay:sync-applied", queueApply);
+  document.addEventListener("clay:drafts-restored", queueApply);
   document.addEventListener("clay:ready", queueApply);
   if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", onDomReady, { once: true });
   else onDomReady();
@@ -173,6 +176,7 @@ export function stop() {
   lastUnmatched = "";
   window.removeEventListener("hashchange", apply);
   document.removeEventListener("clay:sync-applied", queueApply);
+  document.removeEventListener("clay:drafts-restored", queueApply);
   document.removeEventListener("clay:ready", queueApply);
   document.removeEventListener("DOMContentLoaded", onDomReady);
   if (observer) observer.disconnect();

package/src/server/rooms/index.js

@@ -57,4 +57,8 @@ export { makePageTransition, pageTransitionState } from './live-page-history.js'
 
 export { documentEtag, ifMatchSatisfied } from './spec-wire.js';
 
-export { LIVE_LIMITS, REFUSED_MS, createRooms, roomIsDirty, PersistentReservationError } from './live-data-rooms.js';
+export { LIVE_LIMITS, REFUSED_MS, COMPACTOR, createRooms, roomIsDirty, PersistentReservationError } from './live-data-rooms.js';
+
+export { COMPACTION, ROOM_ERROR_STATUS } from '../../live/page-compaction.js';
+
+export { createPageCompactor, pageCompactionWorkerUrl } from './page-compactor.js';

package/src/server/rooms/live-data-rooms.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import { parseJsonRelaxed } from 'hyper-morph/json-parse';
-import { validateOp, checkOp, applyOp, applyTracked, undoTracked, sizeChange, cloneJson, serializeLive, textHash, diffOps } from './live-data-ops.js';
+import { validateOp, checkOp, applyOp, applyOps, applyTracked, undoTracked, sizeChange, cloneJson, serializeLive, textHash, diffOps } from './live-data-ops.js';
 import { liveTags } from './live-data-tags.js';
 import { checkPageConversion, PageConversionError } from './page-conversion.js';
 import { checkPageInitial } from './page-write-admission.js';
@@ -10,6 +10,8 @@ import { makePageTransition, pageTransitionState } from './live-page-history.js'
 export { liveTags } from './live-data-tags.js';
 
 import { frameSet, contains, descendants, receiptHas, receiptBytes, saveReceipt, postReceipt, replaceReceipt, retireReceipt, RECEIPT_LIMIT } from './live-provenance.js';
+import { COMPACTION, pageShape, planCompaction, checkUpdate, admitPageOps, createRangeCache, unionFileEntries, buildCandidate } from '../../live/page-compaction.js';
+import { PART_KEY, entriesOf } from '../../page/ybind/parts.js';
 
 const byteLength = (text) => Buffer.byteLength(text, 'utf8');
 const sizeOf = (value) => byteLength(serializeLive(value));
@@ -54,6 +56,7 @@ export const LIVE_LIMITS = Object.freeze({
 });
 
 const PAGE = /^page(\.[0-9]+)?$/;
+export const COMPACTOR = 'compactor';
 const isContainer = (v) => v !== null && typeof v === 'object';
 
 // The stores a room starts with. A store over the store cap is left out, and so
@@ -193,7 +196,26 @@ export class PersistentReservationError extends Error {
   }
 }
 
-export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes = LIVE_LIMITS.liveBytes } = {}) {
+export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes = LIVE_LIMITS.liveBytes, compaction = null } = {}) {
+  const hostLimits = compaction ? Object.freeze({ ...COMPACTION, ...(typeof compaction === 'object' ? compaction : {}) }) : null;
+  const jobs = new WeakMap();
+  let onDue = () => {};
+  const hostMode = (yjs) => (hostLimits && yjs ? { fence: 0, job: null, lastFull: null, deletesSince: 0, contentSeq: 0, failed: null, retired: new Set(), legacy: new Set(), ranges: createRangeCache() } : null);
+  // A copy of a room to try a file against. Its compaction state is room data plus a
+  // running job and a range cache, which hold functions: the copy starts with neither.
+  const projectRoom = (room) => {
+    const compaction = room.compaction;
+    if (!compaction) return structuredClone(room);
+    room.compaction = null;
+    let projected;
+    try { projected = structuredClone(room); } finally { room.compaction = compaction; }
+    projected.compaction = { ...structuredClone({ ...compaction, job: null, ranges: null }), ranges: createRangeCache() };
+    return projected;
+  };
+  const due = (room, overflow = false) => {
+    if (!room.compaction || room.compaction.job || room.compaction.failed) return;
+    try { onDue(room, { overflow }); } catch {}
+  };
   const rooms = new Map();
   const pageReservations = new Map();
   const reservedNodes = new Map();
@@ -218,6 +240,7 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
     seen: new Map(),
     emptySince: null,
     ...(inspectPage(html).kind === 'yjs' && { pageTransition: makePageTransition() }),
+    compaction: hostMode(inspectPage(html).kind === 'yjs'),
   });
 
   const roomBytes = (room) => {
@@ -226,11 +249,97 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
     return total;
   };
   const heldBy = (room) => {
-    let total = (room.receiptBytes ?? 0) + (room.pageTransition?.bytes ?? 0);
+    let total = (room.receiptBytes ?? 0) + (room.pageTransition?.bytes ?? 0) + (room.compaction?.job?.reserved ?? 0);
     for (const s of room.stores.values()) total += s.bytes + s.logBytes;
     return total;
   };
 
+  const admit = (room, store, frame, ops) => {
+    const state = room.compaction;
+    const answer = admitPageOps({ y: store.value.y, ops, state: { ...room.compaction, compaction: frame.compaction }, limits: hostLimits });
+    if (answer.error) {
+      if (answer.error === 'checkpoint-required') due(room);
+      return answer;
+    }
+    const { added, deleted, limit, shape } = answer;
+    return {
+      limit,
+      over() {
+        if (answer.failed || (state.lastFull && state.deletesSince === 0)) return { error: 'page-full' };
+        due(room, true);
+        return { error: 'checkpoint-required', retryAfter: 0 };
+      },
+      admitted(bytes) {
+        state.deletesSince += deleted;
+        state.contentSeq = room.seq;
+        if (answer.failed) return;
+        if (bytes > hostLimits.activeBytes) due(room, true);
+        else if (shape.loose + added >= hostLimits.soft) due(room);
+      },
+    };
+  };
+
+  const mergePageFile = (room, store, value) => {
+    const state = room.compaction;
+    if (value.g !== store.value.g) return null;
+    const adds = unionFileEntries({
+      y: store.value.y,
+      fileY: value.y,
+      retired: state.retired,
+      rangesFor: state.ranges,
+      keyFor: (i) => `f${textHash(room.epoch).slice(0, 8)}-${(room.seq + 1).toString(36)}-${i.toString(36)}`,
+    });
+    const seq = room.seq + 1;
+    const taken = new Set();
+    const ops = [];
+    for (const [key, v] of adds) {
+      if (Object.hasOwn(store.value.y, key) || taken.has(key)) continue;
+      taken.add(key);
+      ops.push(validateOp({ op: 'set', path: ['y', key], value: v }));
+    }
+    if (!ops.length) return null;
+    const fits = (n) => n <= LIVE_LIMITS.storeBytes && roomBytes(room) - store.bytes + n <= LIVE_LIMITS.roomBytes;
+    let next = applyOps(cloneJson(store.value), ops);
+    let bytes = sizeOf(next);
+    if (!fits(bytes)) {
+      // A file from an older tab repeats most of the page, so the plain union can be twice
+      // its real size: fold the room and the file into one checkpoint before giving up.
+      const built = buildCandidate({ kind: 'full', sources: [...entriesOf(store.value.y), ...adds] });
+      if (!built.update || built.pending) return 'dropped';
+      const retire = Object.keys(store.value.y);
+      ops.length = 0;
+      for (const key of retire) ops.push(validateOp({ op: 'del', path: ['y', key] }));
+      ops.push(validateOp({ op: 'set', path: ['y', `c${textHash(room.epoch).slice(0, 8)}-${seq.toString(36)}`], value: built.update }));
+      next = applyOps(cloneJson(store.value), ops);
+      bytes = sizeOf(next);
+      if (!fits(bytes)) return 'dropped';
+      for (const [key] of entriesOf(store.value.y)) {
+        state.retired.add(key);
+        if (state.retired.size > hostLimits.retired) state.retired.delete(state.retired.values().next().value);
+      }
+    }
+    const logged = byteLength(JSON.stringify(ops));
+    store.value = next;
+    store.bytes = bytes;
+    room.seq = seq;
+    store.last = seq;
+    store.log.push({ seq, ops, bytes: logged, merge: true });
+    store.inFile.add(seq);
+    store.logBytes += logged;
+    evict(store);
+    state.contentSeq = seq;
+    state.lastFull = null;
+    due(room);
+    return true;
+  };
+
+  const endJob = (job) => {
+    if (job.room.compaction?.job !== job) return false;
+    job.room.compaction.job = null;
+    if (rooms.get(job.room.key) === job.room) used -= job.reserved;
+    return true;
+  };
+
   const pageSource = (key, nodeId) => {
     if (nodeId == null) throw new PageConversionError('invalid-document');
     if (pageReservations.has(key) || persistentReservations.has(key) || reservedNodes.has(String(nodeId))) throw new PageConversionError('page-converting');
@@ -308,13 +417,14 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
           if (tag.name !== 'page' || !isYPageValue(value)) continue;
         } else if (isYPageValue(value, { complete: false })) continue;
       }
+      const host = Boolean(room.compaction && tag.name === 'page' && room.pageTransition?.format === 'yjs');
       const before = store.landed;
       const base = baseOf(room, store, tag.at);
       // A capture (stamped, and still the value its stamp names) holds no merge
       // past its stamp. Anything else descends from the file on disk, which
       // holds the merges in inFile: they are not replayed over it.
       const stamped = placed(room, store, tag.at) && tag.at.hash === textHash(serializeLive(value));
-      if (base < store.floor) {
+      if (!host && base < store.floor) {
         store.landed = -1;
         if (before !== -1) landed.push(tag.name);
         continue;
@@ -322,53 +432,69 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
       // A restore proves neither frame inclusion nor descent from a capture.
       const by = restored ? null : provenBy(room, tag.name, tag, stamped);
       const frames = tag.at?.epoch === room.epoch ? frameSet(by) : [];
-      const ancestry = descendants(by);
-      const own = (entry) => {
-        if (!by) return false;
-        if (!entry.merge) return contains(frames, entry.from, entry.n);
-        const p = entry.provenance;
-        return by.v === 2 && p && p.at.epoch === tag.at.epoch && p.at.seq === tag.at.seq && contains(ancestry, ...p.capture);
-      };
-      if (stamped) store.inFile.clear();
-      const entries = [];
-      for (const entry of store.log) {
-        if (entry.seq <= base) continue;
-        if (own(entry)) store.inFile.add(entry.seq);
-        else if (stamped || !store.inFile.has(entry.seq)) entries.push(entry);
-      }
-      for (const entry of entries) {
-        for (const op of entry.ops) {
-          try {
-            checkOp(value, op);
-            value = applyOp(value, op);
-          } catch {}
-        }
-      }
-      const text = serializeLive(value);
-      if (text !== serializeLive(store.value)) {
-        const bytes = byteLength(text);
-        if (bytes > LIVE_LIMITS.storeBytes || roomBytes(room) - store.bytes + bytes > LIVE_LIMITS.roomBytes) {
+      if (host) {
+        // No log replay: the room takes in every edit the file holds and that it
+        // lacks, each under a fresh key, and never deletes or overwrites its own.
+        const merged = mergePageFile(room, store, value);
+        if (merged === 'dropped') {
           room.stores.delete(tag.name);
           valueChanged = true;
           continue;
         }
-        // Logged like a frame, so a capture stamped before this merge gets it
-        // replayed on top (leaf ops: a capture that holds it already is unchanged).
-        const ops = diffOps(store.value, value);
-        store.value = value;
-        store.bytes = bytes;
-        room.seq += 1;
-        store.last = room.seq;
-        const provenance = by?.v === 2 ? { at: { epoch: tag.at.epoch, seq: tag.at.seq }, by: by.frames, capture: by.capture } : null;
-        const logged = byteLength(JSON.stringify(provenance ? { ops, provenance } : ops));
-        store.log.push({ seq: room.seq, ops, bytes: logged, merge: true, ...(provenance && { provenance }) });
-        store.inFile.add(room.seq);
-        store.logBytes += logged;
-        evict(store);
-        valueChanged = true;
+        if (merged) valueChanged = true;
+        if (stamped && tag.at.epoch === room.epoch) {
+          store.landed = tag.at.seq >= room.compaction.contentSeq ? store.last : tag.at.seq;
+          if (store.landed !== before) landed.push(tag.name);
+        }
+      } else {
+        const ancestry = descendants(by);
+        const own = (entry) => {
+          if (!by) return false;
+          if (!entry.merge) return contains(frames, entry.from, entry.n);
+          const p = entry.provenance;
+          return by.v === 2 && p && p.at.epoch === tag.at.epoch && p.at.seq === tag.at.seq && contains(ancestry, ...p.capture);
+        };
+        if (stamped) store.inFile.clear();
+        const entries = [];
+        for (const entry of store.log) {
+          if (entry.seq <= base) continue;
+          if (own(entry)) store.inFile.add(entry.seq);
+          else if (stamped || !store.inFile.has(entry.seq)) entries.push(entry);
+        }
+        for (const entry of entries) {
+          for (const op of entry.ops) {
+            try {
+              checkOp(value, op);
+              value = applyOp(value, op);
+            } catch {}
+          }
+        }
+        const text = serializeLive(value);
+        if (text !== serializeLive(store.value)) {
+          const bytes = byteLength(text);
+          if (bytes > LIVE_LIMITS.storeBytes || roomBytes(room) - store.bytes + bytes > LIVE_LIMITS.roomBytes) {
+            room.stores.delete(tag.name);
+            valueChanged = true;
+            continue;
+          }
+          // Logged like a frame, so a capture stamped before this merge gets it
+          // replayed on top (leaf ops: a capture that holds it already is unchanged).
+          const ops = diffOps(store.value, value);
+          store.value = value;
+          store.bytes = bytes;
+          room.seq += 1;
+          store.last = room.seq;
+          const provenance = by?.v === 2 ? { at: { epoch: tag.at.epoch, seq: tag.at.seq }, by: by.frames, capture: by.capture } : null;
+          const logged = byteLength(JSON.stringify(provenance ? { ops, provenance } : ops));
+          store.log.push({ seq: room.seq, ops, bytes: logged, merge: true, ...(provenance && { provenance }) });
+          store.inFile.add(room.seq);
+          store.logBytes += logged;
+          evict(store);
+          valueChanged = true;
+        }
+        store.landed = entries.length ? base : store.last;
+        if (store.landed !== before) landed.push(tag.name);
       }
-      store.landed = entries.length ? base : store.last;
-      if (store.landed !== before) landed.push(tag.name);
       // Saves record exact inclusion; only legacy captures advance a watermark.
       if (by?.v === 2) {
         for (const [client, ranges] of frames) {
@@ -449,6 +575,7 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
         reservation.result = null;
         return null;
       }
+      if (room.compaction?.job) endJob(room.compaction.job);
       const before = heldBy(room);
       const { stores, transition } = reservation.target;
       for (const name of room.stores.keys()) if (PAGE.test(name)) room.stores.delete(name);
@@ -465,6 +592,7 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
         bytes += store.bytes;
       }
       room.pageTransition = transition;
+      if (hostLimits) room.compaction = hostMode(transition.format === 'yjs');
       reservation.target = null;
       used += heldBy(room) - before - reservation.budget;
       reservation.budget = 0;
@@ -547,7 +675,7 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
         if (!store || store.ephemeral) throw new PersistentReservationError('invalid-target');
       }
       const currentHeld = heldBy(record.room);
-      const projected = structuredClone(record.room);
+      const projected = projectRoom(record.room);
       reconcileFile(projected, record.key, html, {});
       for (const [name, store] of record.room.stores) {
         if (!store.ephemeral && !projected.stores.has(name)) throw new PersistentReservationError('budget');
@@ -738,6 +866,8 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
       }
       const nKey = frame.name + '\n' + clientId;
       const last = room.lastN.get(nKey);
+      const admission = room.compaction && frame.name === 'page' && !receiptHas(last, frame.n) ? admit(room, store, frame, ops) : null;
+      if (admission?.error) return admission;
       // Answered with the seq the sender's last frame landed at, so the tab knows
       // which applied state holds it.
       if (receiptHas(last, frame.n)) return { duplicate: true, seq: frame.n <= last.n ? last.seq : last.savedSeq, epoch: room.epoch };
@@ -793,8 +923,13 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
       }
       if (bytes > LIVE_LIMITS.storeBytes || roomBytes(room) - store.bytes + bytes > LIVE_LIMITS.roomBytes) {
         undo();
+        if (admission) return admission.over(bytes);
         return { error: 'too-large' };
       }
+      if (admission && bytes > admission.limit) {
+        undo();
+        return admission.over(bytes);
+      }
       const logged = done.length ? byteLength(JSON.stringify(ops)) : 0;
       const grows = done.length ? bytes - store.bytes + logAfter(store, logged) - store.logBytes : 0;
       const retiredBytes = victim === null ? 0 : receiptBytes(room.lastN.get(victim));
@@ -819,19 +954,28 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
       room.lastSentAt.set(clientId, now());
       room.seen.set(clientId, now());
       if (PAGE.test(frame.name) && typeof frame.adopted === 'string' && frame.adopted.length <= 64) room.adopted = frame.adopted;
+      if (admission && done.length) admission.admitted(bytes);
       const writerGone = room.writer && connected && !connected.includes(room.writer);
       if ((!room.writer || writerGone) && (!connected || connected.includes(clientId))) room.writer = clientId;
       return { seq: room.seq, epoch: room.epoch, name: frame.name, ops, writer: room.writer, checkpoint: pressed(store), receiptGeneration: room.receiptGeneration ?? 0, ...(transition && { pageGeneration: transition.id }) };
     },
 
     /** Everything a joining tab needs, with clientId's own receipt per store. Values are the room's own objects: serialize, never mutate. With since in this room's epoch, moves carries each store's log entries after since.seq (null where the log no longer reaches back that far). */
-    state(room, clientId = null, since = undefined) {
+    state(room, clientId = null, since = undefined, { compaction: capable } = {}) {
       const stores = {};
+      const legacy = room.compaction?.legacy;
+      if (legacy && clientId && capable !== undefined) {
+        if (capable === hostLimits.version) legacy.delete(clientId);
+        else legacy.add(clientId);
+      }
+      const hidden = Boolean(legacy && (capable !== undefined ? capable !== hostLimits.version : clientId && legacy.has(clientId)));
       for (const [name, s] of room.stores) {
+        if (hidden && name === 'page') continue;
         const seen = {};
         const mine = clientId ? room.lastN.get(name + '\n' + clientId) : null;
         if (mine) seen[clientId] = mine.n;
-        stores[name] = { value: s.value, ephemeral: s.ephemeral, from: s.from, landed: s.landed, floor: s.floor, last: s.last, seen, ...(mine?.saved?.length && { saved: mine.saved }) };
+        stores[name] = { value: s.value, ephemeral: s.ephemeral, from: s.from, landed: s.landed, floor: s.floor, last: s.last, seen, ...(mine?.saved?.length && { saved: mine.saved }),
+          ...(name === 'page' && room.compaction && { compaction: { v: hostLimits.version, loose: hostLimits.loose, activeBytes: hostLimits.activeBytes } }) };
       }
       // A client's own read (since is its { epoch, seq }, or null for a first
       // read) carries moves: those after its seq in its own epoch, else this
@@ -876,7 +1020,11 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
       if (room.writer !== clientId) return { writerChanged: false, writer: room.writer };
       let best = null;
       let bestAt = -1;
-      for (const id of remaining.filter((candidate) => room.seen.has(candidate))) {
+      // A tab too old to see the page store cannot checkpoint it: a capable tab goes first.
+      const seen = remaining.filter((candidate) => room.seen.has(candidate));
+      const legacy = room.compaction?.legacy;
+      const capable = legacy ? seen.filter((candidate) => !legacy.has(candidate)) : seen;
+      for (const id of capable.length ? capable : seen) {
         const at = room.lastSentAt.get(id) ?? 0;
         if (at > bestAt) {
           best = id;
@@ -898,6 +1046,9 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
      */
     sweep(connectedOf = () => [], { mayExpire = () => true } = {}) {
       const t = now();
+      for (const room of rooms.values()) {
+        if (room.compaction?.job && t >= room.compaction.job.deadline) endJob(room.compaction.job);
+      }
       for (const [key, room] of rooms) {
         if (!roomIsDirty(room) && mayExpire(room) && !pageReservations.has(key) && !persistentReservations.has(key) && room.emptySince !== null && t - room.emptySince >= LIVE_LIMITS.retainMs) {
           used -= heldBy(room);
@@ -948,6 +1099,107 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
       return changed;
     },
 
+    onCompactionDue(listener) {
+      onDue = typeof listener === 'function' ? listener : () => {};
+    },
+
+    beginCompaction(room, { overflow = false } = {}) {
+      const state = room?.compaction;
+      if (!state || rooms.get(room.key) !== room || state.failed) return null;
+      if (state.job) {
+        if (now() < state.job.deadline) return null;
+        endJob(state.job);
+      }
+      const store = room.stores.get('page');
+      if (!store || pageReservations.has(room.key) || persistentReservations.has(room.key)) return null;
+      const plan = planCompaction(store.value.y, { overflow }, hostLimits);
+      if (!plan) return null;
+      const reserved = plan.sources.reduce((sum, [k, v]) => sum + k.length + v.length, 0);
+      if (used + reserved > liveBytes) return null;
+      state.fence += 1;
+      const token = Object.freeze({ key: room.key, epoch: room.epoch, fence: state.fence });
+      const job = { token, room, store, epoch: room.epoch, generation: room.pageTransition?.id ?? null, kind: plan.kind,
+        sources: new Map(plan.sources), physical: Object.keys(store.value.y), reserved, deadline: now() + hostLimits.leaseMs, deletesAtBegin: state.deletesSince };
+      state.job = job;
+      used += reserved;
+      jobs.set(token, job);
+      return { token, kind: plan.kind, sources: plan.sources };
+    },
+
+    abandonCompaction(token, { failed = null } = {}) {
+      const job = jobs.get(token);
+      if (!job) return false;
+      jobs.delete(token);
+      const ended = endJob(job);
+      if (ended && failed) job.room.compaction.failed = { reason: failed, at: now() };
+      return ended;
+    },
+
+    commitCompaction(token, result) {
+      const job = jobs.get(token);
+      if (!job) return { refused: 'stale-token' };
+      jobs.delete(token);
+      const { room, store } = job;
+      if (!endJob(job)) return { refused: 'stale-token' };
+      if (rooms.get(room.key) !== room || room.epoch !== job.epoch || room.stores.get('page') !== store ||
+        (room.pageTransition?.id ?? null) !== job.generation) return { refused: 'stale-token' };
+      const y = store.value.y;
+      const retire = job.physical.filter((k) => {
+        const part = PART_KEY.exec(k);
+        return job.sources.has(part ? part[1] : k) || (part && job.kind === 'full');
+      });
+      if (retire.some((k) => !Object.hasOwn(y, k))) return { refused: 'sources-changed' };
+      const held = new Map(entriesOf(Object.fromEntries(retire.map((k) => [k, y[k]]))));
+      for (const [k, v] of job.sources) if (held.get(k) !== v) return { refused: 'sources-changed' };
+      if (typeof result?.update !== 'string' || !checkUpdate(result.update)) return { refused: 'bad-candidate' };
+      const key = `${job.kind === 'full' ? 'c' : 't'}${textHash(room.epoch).slice(0, 8)}-${(room.seq + 1).toString(36)}`;
+      if (Object.hasOwn(y, key)) return { refused: 'bad-candidate' };
+      const ops = [...retire.map((k) => ({ op: 'del', path: ['y', k] })), { op: 'set', path: ['y', key], value: result.update }].map(validateOp);
+      let value = store.value;
+      let bytes = store.bytes;
+      const done = [];
+      for (const op of ops) {
+        const rec = applyTracked(value, op);
+        if (!rec) continue;
+        done.push(rec);
+        bytes += sizeChange(rec, sizeOf, bytes);
+        value = rec.root;
+      }
+      if (bytes > hostLimits.activeBytes && bytes > store.bytes) {
+        for (let i = done.length - 1; i >= 0; i--) undoTracked(done[i]);
+        // A full fold of the whole page that still does not fit: the page is as small as it
+        // gets, so the next write is refused as full instead of waiting for another fold.
+        if (job.kind === 'full' && retire.length === Object.keys(y).length) {
+          room.compaction.lastFull = { bytes: store.bytes, seq: room.seq, deletesAtBegin: job.deletesAtBegin };
+          room.compaction.deletesSince -= job.deletesAtBegin;
+        }
+        return { refused: 'too-large' };
+      }
+      const clean = store.landed === store.last;
+      const logged = byteLength(JSON.stringify(ops));
+      used += bytes - store.bytes + logAfter(store, logged) - store.logBytes;
+      store.value = value;
+      store.bytes = bytes;
+      room.seq += 1;
+      store.last = room.seq;
+      if (clean) store.landed = store.last;
+      store.log.push({ seq: room.seq, ops, bytes: logged, from: COMPACTOR, n: 0 });
+      store.logBytes += logged;
+      evict(store);
+      const state = room.compaction;
+      for (const k of job.sources.keys()) {
+        state.retired.add(k);
+        if (state.retired.size > hostLimits.retired) state.retired.delete(state.retired.values().next().value);
+      }
+      if (job.kind === 'full') {
+        state.lastFull = { bytes, seq: room.seq, deletesAtBegin: job.deletesAtBegin };
+        state.deletesSince -= job.deletesAtBegin;
+      }
+      if (pageShape(store.value.y, hostLimits).loose >= hostLimits.soft || !pageShape(store.value.y, hostLimits).normal) due(room);
+      return { seq: room.seq, epoch: room.epoch, name: 'page', ops, from: COMPACTOR, kind: job.kind, landed: store.landed,
+        ...(room.pageTransition && { pageGeneration: room.pageTransition.id }) };
+    },
+
     /** Every room's key. */
     keys() {
       return [...rooms.keys()];

package/src/server/rooms/page-compaction-worker.js

@@ -0,0 +1,12 @@
+import { parentPort } from 'node:worker_threads';
+import { buildCandidate } from '../../live/page-compaction.js';
+
+parentPort.on('message', ({ id, kind, sources }) => {
+  let result;
+  try {
+    result = buildCandidate({ kind, sources });
+  } catch (error) {
+    result = { failure: 'crashed', message: error?.message || String(error) };
+  }
+  parentPort.postMessage({ id, ...result });
+});

package/src/server/rooms/page-compactor.js

@@ -0,0 +1,92 @@
+import { Worker } from 'node:worker_threads';
+import { pathToFileURL } from 'node:url';
+
+const RETRY_MS = [1000, 5000, 30000];
+
+const MODULE_URL = typeof __dirname === 'string' ? pathToFileURL(`${__dirname}/`).href : import.meta.url;
+const WORKER_FILE = typeof __PAGE_COMPACTION_WORKER__ === 'string' ? __PAGE_COMPACTION_WORKER__ : './page-compaction-worker.js';
+
+export const pageCompactionWorkerUrl = () => new URL(WORKER_FILE, MODULE_URL);
+
+export function createPageCompactor({ rooms, onCommit = () => {}, workerUrl = pageCompactionWorkerUrl(),
+  timeoutMs = 30000, WorkerClass = Worker, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+  const queue = new Map();
+  const retries = new Map();
+  let worker = null;
+  let running = null;
+  let ids = 0;
+  let closed = false;
+
+  // A worker's events count only while it is still the current one: a terminated worker
+  // exits on a later tick, after its replacement may already be running the next job.
+  const spawn = () => {
+    const instance = new WorkerClass(workerUrl);
+    worker = instance;
+    instance.unref?.();
+    instance.on('message', (message) => { if (worker === instance) finish(message); });
+    instance.on('error', () => { if (worker === instance) crashed(); });
+    instance.on('exit', () => { if (worker !== instance) return; worker = null; if (running) crashed(); });
+  };
+
+  function crashed() {
+    const job = running;
+    if (!job) return;
+    running = null;
+    clearTimer(job.timer);
+    worker?.terminate?.();
+    worker = null;
+    const tries = (retries.get(job.room) ?? 0) + 1;
+    retries.set(job.room, tries);
+    rooms.abandonCompaction(job.token, tries > RETRY_MS.length ? { failed: 'crashed' } : {});
+    if (tries <= RETRY_MS.length) setTimer(() => due(job.room, { overflow: job.overflow }), RETRY_MS[tries - 1]);
+    pump();
+  }
+
+  function finish({ id, ...result }) {
+    const job = running;
+    if (!job || job.id !== id) return;
+    running = null;
+    clearTimer(job.timer);
+    if (result.failure) {
+      rooms.abandonCompaction(job.token, { failed: result.failure });
+    } else {
+      const answer = rooms.commitCompaction(job.token, result);
+      if (answer.seq !== undefined) {
+        retries.delete(job.room);
+        try { onCommit(job.room, answer); } catch {}
+      }
+    }
+    pump();
+  }
+
+  function pump() {
+    if (closed || running || !queue.size) return;
+    const [room, { overflow }] = queue.entries().next().value;
+    queue.delete(room);
+    const begun = rooms.beginCompaction(room, { overflow });
+    if (!begun) { pump(); return; }
+    if (!worker) spawn();
+    const id = ++ids;
+    running = { id, room, overflow, token: begun.token, timer: setTimer(crashed, timeoutMs) };
+    worker.postMessage({ id, kind: begun.kind, sources: begun.sources });
+  }
+
+  function due(room, { overflow = false } = {}) {
+    const queued = queue.get(room);
+    queue.set(room, { overflow: overflow || Boolean(queued?.overflow) });
+    queueMicrotask(pump);
+  }
+
+  rooms.onCompactionDue(due);
+  return {
+    get running() { return running !== null; },
+    close() {
+      closed = true;
+      rooms.onCompactionDue(null);
+      if (running) { clearTimer(running.timer); rooms.abandonCompaction(running.token); running = null; }
+      const current = worker;
+      worker = null;
+      return current?.terminate?.();
+    },
+  };
+}