@openchambery/web 2.0.0-beta.1 → 2.0.0-beta.4

package/server/lib/session-metadata/session-metadata-store.js

@@ -11,12 +11,18 @@
  * a `null` deletes. That is what the old PATCH did, and it is what keeps two
  * features writing into the same `openchamber` namespace from erasing each
  * other — goal mode saving progress must not drop an assist recap.
+ *
+ * Mutations are fully serialized. Committed `entries` update only after a
+ * successful persist so concurrent readers never observe uncommitted drafts.
+ * A failed or corrupt file read is never empty success: the store stays
+ * unwritable and reports the error instead of overwriting unknown disk state.
  */
 
 import fsDefault from 'node:fs';
 import pathDefault from 'node:path';
 
 const METADATA_FILE_NAME = 'sessions-metadata.json';
+const HOST_ARCHIVE_KEY = 'archive';
 
 const asNonEmptyString = (value) => {
   if (typeof value !== 'string') return null;
@@ -43,6 +49,54 @@ export const mergeMetadataPatch = (current, patch) => {
   return base;
 };
 
+const readPriorArchivedAt = (metadata) => {
+  if (!isPlainObject(metadata?.openchamber)) return null;
+  if (!Object.prototype.hasOwnProperty.call(metadata.openchamber, HOST_ARCHIVE_KEY)) return null;
+  const archive = metadata.openchamber[HOST_ARCHIVE_KEY];
+  if (!isPlainObject(archive) || !Object.prototype.hasOwnProperty.call(archive, 'archivedAt')) return null;
+  const value = archive.archivedAt;
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+};
+
+/** Strip Host archive writes from generic metadata patches. */
+const stripArchiveFromMetadataPatch = (patch) => {
+  if (!isPlainObject(patch) || !isPlainObject(patch.openchamber)) return patch;
+  if (!Object.prototype.hasOwnProperty.call(patch.openchamber, HOST_ARCHIVE_KEY)) return patch;
+  const openchamber = { ...patch.openchamber };
+  delete openchamber[HOST_ARCHIVE_KEY];
+  return { ...patch, openchamber };
+};
+
+/**
+ * Restore reserved archive after a generic merge so null ancestor deletes
+ * (`openchamber: null` / `archive: null`) cannot wipe Host archive state.
+ */
+const applyReservedArchiveProtection = (previous, patch, merged, { allowArchive = false } = {}) => {
+  if (allowArchive) return merged;
+  const priorArchive = readPriorArchivedAt(previous);
+  const result = isPlainObject(merged) ? { ...merged } : {};
+  const openchamber = isPlainObject(result.openchamber) ? { ...result.openchamber } : {};
+
+  if (isPlainObject(patch?.openchamber) && Object.prototype.hasOwnProperty.call(patch.openchamber, HOST_ARCHIVE_KEY)) {
+    delete openchamber[HOST_ARCHIVE_KEY];
+  }
+
+  if (priorArchive !== null) {
+    openchamber[HOST_ARCHIVE_KEY] = {
+      ...(isPlainObject(previous?.openchamber?.[HOST_ARCHIVE_KEY])
+        ? previous.openchamber[HOST_ARCHIVE_KEY]
+        : {}),
+      archivedAt: priorArchive,
+    };
+  } else {
+    delete openchamber[HOST_ARCHIVE_KEY];
+  }
+
+  if (Object.keys(openchamber).length > 0) result.openchamber = openchamber;
+  else delete result.openchamber;
+  return result;
+};
+
 /**
  * @param {object} options
  * @param {string} options.dataDir OpenChamber data directory for this instance.
@@ -58,19 +112,26 @@ export const createSessionMetadataStore = ({
 }) => {
   const filePath = path.join(dataDir, METADATA_FILE_NAME);
 
-  /** sessionID → metadata object. Authoritative once `loaded` is true. */
+  /** sessionID → metadata. Committed only — never holds an in-flight draft. */
   const entries = new Map();
   let loaded = false;
   let loadPromise = null;
   /**
    * Writes stay disabled until one load has told us what is already on disk.
-   * A failed read is not evidence that nothing is stored, and writing over a
-   * file we could not read would drop exactly the state we are protecting.
+   * A failed/corrupt read is not evidence that nothing is stored.
    */
   let writable = false;
-  let writeChain = Promise.resolve();
+  let loadFailureReason = null;
+  /** Full RMW + persist chain — concurrent writers cannot interleave merges. */
+  let mutationChain = Promise.resolve();
 
-  const snapshot = () => Object.fromEntries(entries);
+  const snapshotFrom = (map) => Object.fromEntries(map);
+  const snapshot = () => snapshotFrom(entries);
+
+  const unavailableError = (detail = loadFailureReason) => {
+    const suffix = detail ? `: ${detail}` : ': its file could not be read';
+    return new Error(`session metadata is unavailable${suffix.startsWith(':') ? suffix : `: ${suffix}`}`);
+  };
 
   const parseStored = (raw) => {
     const parsed = JSON.parse(raw);
@@ -80,8 +141,6 @@ export const createSessionMetadataStore = ({
     const result = new Map();
     for (const [sessionID, value] of Object.entries(parsed)) {
       const id = asNonEmptyString(sessionID);
-      // A non-object entry is not metadata; dropping it is better than handing
-      // a consumer something it will read fields off.
       if (id && isPlainObject(value)) result.set(id, value);
     }
     return result;
@@ -92,25 +151,20 @@ export const createSessionMetadataStore = ({
     try {
       raw = await fsPromises.readFile(filePath, 'utf8');
     } catch (error) {
-      // No file yet is the normal first run: nothing is stored, and writing is
-      // safe because there is no state to lose.
       if (error?.code === 'ENOENT') return { ok: true, stored: new Map() };
       console.warn('[session-metadata] could not read the session metadata file:', error?.message ?? error);
-      return { ok: false, stored: null };
+      return { ok: false, stored: null, reason: error?.message || 'read failed' };
     }
 
     try {
       return { ok: true, stored: parseStored(raw) };
     } catch (error) {
-      // Malformed bytes are kept for the user instead of being overwritten on
-      // the next write, and whatever this process already knows stays in memory
-      // rather than collapsing to "no metadata".
-      const backup = `${filePath}.corrupt-${now()}`;
-      await fsPromises.rename(filePath, backup).catch(() => undefined);
+      // Corrupt bytes must not become empty success. Keep the file, stay
+      // unwritable, and surface the error so callers can report/retry.
       console.warn(
-        `[session-metadata] session metadata file was unreadable and was moved to ${backup}: ${error?.message ?? error}`,
+        `[session-metadata] session metadata file is corrupt and will not be overwritten: ${error?.message ?? error}`,
       );
-      return { ok: true, stored: new Map() };
+      return { ok: false, stored: null, reason: error?.message || 'corrupt metadata file' };
     }
   };
 
@@ -118,117 +172,203 @@ export const createSessionMetadataStore = ({
     if (!loadPromise) {
       loadPromise = readFile().then((result) => {
         if (result.ok) {
-          // Merge rather than replace: a write that happened while the first
-          // load was still running must survive it.
           for (const [id, metadata] of result.stored) {
             if (!entries.has(id)) entries.set(id, metadata);
           }
           loaded = true;
           writable = true;
+          loadFailureReason = null;
         } else {
-          // Let a later call retry; until one succeeds the store answers reads
-          // from memory and refuses writes.
           loadPromise = null;
+          loaded = false;
+          writable = false;
+          loadFailureReason = result.reason || 'its file could not be read';
         }
-        return { ok: result.ok, entries: snapshot() };
+        return { ok: result.ok, entries: snapshot(), reason: result.reason || null };
       });
     }
     return loadPromise;
   };
 
-  const persist = () => {
-    const payload = JSON.stringify(snapshot());
-    const write = async () => {
-      await fsPromises.mkdir(dataDir, { recursive: true });
-      // Temp file in the same directory so the rename is atomic on one device:
-      // a reader sees either the previous file or the complete new one.
-      const tmpPath = `${filePath}.${process.pid}.tmp`;
-      await fsPromises.writeFile(tmpPath, payload, 'utf8');
-      await fsPromises.rename(tmpPath, filePath);
-    };
-    // Serialized so two overlapping writes cannot interleave their renames.
-    const next = writeChain.then(write, write);
-    writeChain = next.catch(() => undefined);
+  const ensureReadable = async () => {
+    const result = await load();
+    if (!result.ok || !writable) throw unavailableError(result.reason);
+    return result;
+  };
+
+  const persistMap = async (map) => {
+    const payload = JSON.stringify(snapshotFrom(map));
+    await fsPromises.mkdir(dataDir, { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.tmp`;
+    await fsPromises.writeFile(tmpPath, payload, 'utf8');
+    await fsPromises.rename(tmpPath, filePath);
+  };
+
+  /**
+   * @template T
+   * @param {() => Promise<T>} work
+   * @returns {Promise<T>}
+   */
+  const runExclusive = (work) => {
+    const next = mutationChain.then(work, work);
+    mutationChain = next.then(
+      () => undefined,
+      () => undefined,
+    );
     return next;
   };
 
   const get = async (sessionID) => {
     const id = asNonEmptyString(sessionID);
     if (!id) return {};
-    await load();
+    await ensureReadable();
     return entries.get(id) ?? {};
   };
 
-  /** Whether the store holds anything for the session (an empty object counts as nothing). */
   const has = async (sessionID) => {
     const id = asNonEmptyString(sessionID);
     if (!id) return false;
-    await load();
+    await ensureReadable();
     return entries.has(id);
   };
 
+  /**
+   * Shared exclusive commit path: merge → persist draft → publish committed.
+   * Readers never observe the draft; persist failure leaves prior committed state.
+   *
+   * @param {string} id
+   * @param {object | undefined} previous
+   * @param {object} patch
+   * @param {{ allowArchive?: boolean }} options
+   */
+  const commitMergedPatch = async (id, previous, patch, options = {}) => {
+    const allowArchive = options.allowArchive === true;
+    const effectivePatch = allowArchive ? patch : stripArchiveFromMetadataPatch(patch);
+
+    let merged = mergeMetadataPatch(previous, effectivePatch);
+    merged = applyReservedArchiveProtection(previous, patch, merged, { allowArchive });
+
+    const nextMap = new Map(entries);
+    if (Object.keys(merged).length === 0) nextMap.delete(id);
+    else nextMap.set(id, merged);
+
+    // Persist draft snapshot first; publish to committed entries only on success.
+    await persistMap(nextMap);
+
+    if (Object.keys(merged).length === 0) entries.delete(id);
+    else entries.set(id, merged);
+
+    return merged;
+  };
+
   /**
    * Applies a merge patch and returns the session's full metadata afterwards.
-   * A failed write rolls the memory back and throws, so a caller never believes
-   * it saved something it did not.
+   * Committed map updates only after persist succeeds — readers never see drafts.
+   *
+   * @param {string} sessionID
+   * @param {object} patch
+   * @param {{ allowArchive?: boolean }} [options]
    */
-  const setSessionMetadata = async (sessionID, patch) => {
+  const setSessionMetadata = async (sessionID, patch, options = {}) => {
     const id = asNonEmptyString(sessionID);
     if (!id) throw new Error('a session id is required to store session metadata');
     if (!isPlainObject(patch)) throw new Error('a session metadata patch must be an object');
 
-    const loadResult = await load();
-    if (!loadResult.ok || !writable) {
-      throw new Error('session metadata is unavailable: its file could not be read');
-    }
+    return runExclusive(async () => {
+      await ensureReadable();
+      return commitMergedPatch(id, entries.get(id), patch, options);
+    });
+  };
 
-    const had = entries.has(id);
-    const previous = entries.get(id);
-    const merged = mergeMetadataPatch(previous, patch);
-    if (Object.keys(merged).length === 0) entries.delete(id);
-    else entries.set(id, merged);
+  /**
+   * Conditional metadata mutation on the same exclusive serial boundary as
+   * setSessionMetadata. `decide(committedMetadata)` runs while the lock is held
+   * and must return synchronously:
+   *   - `{ ok: false, reason? }` — no persist; readers keep prior committed state
+   *   - `{ ok: true, patch }` — merge-patch, persist, then publish
+   *
+   * Use this for goal generation / status preconditions so a stale auditor
+   * cannot commit after a user pause that already landed.
+   *
+   * @param {string} sessionID
+   * @param {(current: object) => { ok: false, reason?: string } | { ok: true, patch: object }} decide
+   * @param {{ allowArchive?: boolean }} [options]
+   * @returns {Promise<{ committed: boolean, reason?: string, metadata: object }>}
+   */
+  const mutateSessionMetadata = async (sessionID, decide, options = {}) => {
+    const id = asNonEmptyString(sessionID);
+    if (!id) throw new Error('a session id is required to store session metadata');
+    if (typeof decide !== 'function') throw new Error('a decide function is required to mutate session metadata');
 
-    try {
-      await persist();
-    } catch (error) {
-      if (had) entries.set(id, previous);
-      else entries.delete(id);
-      throw error;
-    }
+    return runExclusive(async () => {
+      await ensureReadable();
 
-    return merged;
+      const previous = entries.get(id);
+      const current = previous ?? {};
+      const decision = decide(current);
+      if (!decision || decision.ok !== true) {
+        return {
+          committed: false,
+          reason: typeof decision?.reason === 'string' && decision.reason
+            ? decision.reason
+            : 'rejected',
+          metadata: current,
+        };
+      }
+      if (!isPlainObject(decision.patch)) {
+        throw new Error('a successful mutate decision must include an object patch');
+      }
+
+      const merged = await commitMergedPatch(id, previous, decision.patch, options);
+      return { committed: true, metadata: merged };
+    });
   };
 
+  /**
+   * Drop a session's metadata.
+   * @returns {Promise<boolean>} true if a row was removed; false if already absent
+   *   (idempotent). Disk/write failures **throw** so callers can retry — never
+   *   conflate not-found with write failure.
+   */
   const removeSession = async (sessionID) => {
     const id = asNonEmptyString(sessionID);
     if (!id) return false;
-    await load();
-    if (!writable || !entries.has(id)) return false;
-    const previous = entries.get(id);
-    entries.delete(id);
-    try {
-      await persist();
-    } catch (error) {
-      entries.set(id, previous);
-      console.warn('[session-metadata] failed to drop session metadata:', error?.message ?? error);
-      return false;
-    }
-    return true;
+
+    return runExclusive(async () => {
+      await ensureReadable();
+      if (!entries.has(id)) return false;
+
+      const nextMap = new Map(entries);
+      nextMap.delete(id);
+      // Write failures propagate — do not report as "already gone".
+      await persistMap(nextMap);
+      entries.delete(id);
+      return true;
+    });
   };
 
   const getAll = async () => {
-    await load();
+    await ensureReadable();
     return snapshot();
   };
 
+  /**
+   * Synchronous committed snapshot for event hot paths.
+   * Returns `null` when not successfully loaded (unknown — never empty).
+   */
+  const getSnapshotSync = () => (loaded && writable ? snapshot() : null);
+
   return {
     load,
     get,
     getAll,
     list: getAll,
-    isLoaded: () => loaded,
+    getSnapshotSync,
+    isLoaded: () => loaded && writable,
+    getLoadFailureReason: () => loadFailureReason,
     has,
     setSessionMetadata,
+    mutateSessionMetadata,
     removeSession,
     filePath,
   };

package/server/lib/session-metadata/session-metadata-store.test.js

@@ -124,16 +124,18 @@ describe('createSessionMetadataStore', () => {
     expect(JSON.parse(readFile(dataDir))).toEqual({ ses_1: { a: 1 }, ses_2: { b: 2 } });
   });
 
-  it('treats a malformed file as empty, keeps a backup, and still accepts writes', async () => {
+  it('refuses corrupt JSON as empty success and does not overwrite the file', async () => {
     const dataDir = makeDataDir();
-    fs.writeFileSync(path.join(dataDir, 'sessions-metadata.json'), '{ not json', 'utf8');
+    const corruptPath = path.join(dataDir, 'sessions-metadata.json');
+    fs.writeFileSync(corruptPath, '{ not json', 'utf8');
     vi.spyOn(console, 'warn').mockImplementation(() => {});
 
     const store = createSessionMetadataStore({ dataDir });
-    await expect(store.getAll()).resolves.toEqual({});
-    await expect(store.setSessionMetadata('ses_1', { a: 1 })).resolves.toEqual({ a: 1 });
-    expect(JSON.parse(readFile(dataDir))).toEqual({ ses_1: { a: 1 } });
-    expect(fs.readdirSync(dataDir).some((name) => name.includes('sessions-metadata.json.'))).toBe(true);
+    await expect(store.getAll()).rejects.toThrow(/unavailable|corrupt/i);
+    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow(/unavailable|corrupt/i);
+    expect(fs.readFileSync(corruptPath, 'utf8')).toBe('{ not json');
+    expect(store.isLoaded()).toBe(false);
+    expect(store.getSnapshotSync()).toBeNull();
   });
 
   it('drops entries that are not metadata objects', async () => {
@@ -159,19 +161,72 @@ describe('createSessionMetadataStore', () => {
     vi.spyOn(console, 'warn').mockImplementation(() => {});
 
     const store = createSessionMetadataStore({ dataDir, fsPromises });
-    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow(/could not be read/);
+    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow(/unavailable/);
     expect(readFile(dataDir)).toBe('{}');
   });
 
-  it('rolls memory back and reports failure when persisting fails', async () => {
+  it('does not publish uncommitted drafts while persist is blocked (set)', async () => {
     const dataDir = makeDataDir();
-    const fsPromises = { ...fs.promises, writeFile: async () => { throw new Error('disk full'); } };
+    let releaseWrite;
+    const writeGate = new Promise((resolve) => { releaseWrite = resolve; });
+    const fsPromises = {
+      ...fs.promises,
+      writeFile: async (target, payload, encoding) => {
+        await writeGate;
+        return fs.promises.writeFile(target, payload, encoding);
+      },
+    };
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    const pending = store.setSessionMetadata('ses_1', { a: 1 });
+    // Concurrent readers must still see committed empty — not the in-flight draft.
+    await expect(store.get('ses_1')).resolves.toEqual({});
+    expect(store.getSnapshotSync()).toEqual({});
+    releaseWrite();
+    await expect(pending).resolves.toEqual({ a: 1 });
+    await expect(store.get('ses_1')).resolves.toEqual({ a: 1 });
+  });
+
+  it('does not publish uncommitted deletes while persist is blocked (remove)', async () => {
+    const dataDir = makeDataDir();
+    const storeWarm = createSessionMetadataStore({ dataDir });
+    await storeWarm.setSessionMetadata('ses_1', { a: 1 });
 
+    let releaseWrite = null;
+    const fsPromises = {
+      ...fs.promises,
+      writeFile: async (target, payload, encoding) => {
+        if (releaseWrite) await new Promise((resolve) => { releaseWrite = resolve; });
+        return fs.promises.writeFile(target, payload, encoding);
+      },
+    };
     const store = createSessionMetadataStore({ dataDir, fsPromises });
-    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow('disk full');
+    await store.load();
+    // Arm the gate only for the remove persist.
+    releaseWrite = () => {};
+    let unlock;
+    const gate = new Promise((resolve) => { unlock = resolve; });
+    fsPromises.writeFile = async (target, payload, encoding) => {
+      await gate;
+      return fs.promises.writeFile(target, payload, encoding);
+    };
+    const pending = store.removeSession('ses_1');
+    await expect(store.get('ses_1')).resolves.toEqual({ a: 1 });
+    unlock();
+    await expect(pending).resolves.toBe(true);
     await expect(store.get('ses_1')).resolves.toEqual({});
   });
 
+  it('keeps committed entries when persist fails (set never published)', async () => {
+    const dataDir = makeDataDir();
+    const storeOk = createSessionMetadataStore({ dataDir });
+    await storeOk.setSessionMetadata('ses_1', { a: 1 });
+
+    const fsPromises = { ...fs.promises, writeFile: async () => { throw new Error('disk full'); } };
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    await expect(store.setSessionMetadata('ses_1', { b: 2 })).rejects.toThrow('disk full');
+    await expect(store.get('ses_1')).resolves.toEqual({ a: 1 });
+  });
+
   it('forgets a session on request', async () => {
     const dataDir = makeDataDir();
     const store = createSessionMetadataStore({ dataDir });
@@ -181,4 +236,144 @@ describe('createSessionMetadataStore', () => {
     await expect(store.removeSession('ses_1')).resolves.toBe(false);
     expect(JSON.parse(readFile(dataDir))).toEqual({});
   });
+
+  it('serializes concurrent writes so neighboring keys are not lost', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await Promise.all([
+      store.setSessionMetadata('ses_1', { openchamber: { goal: { id: 'g1' } } }),
+      store.setSessionMetadata('ses_1', { openchamber: { assist: { recap: 'a' } } }),
+    ]);
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { goal: { id: 'g1' }, assist: { recap: 'a' } },
+    });
+  });
+
+  it('protects Host archive from generic metadata null ancestor deletes', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await store.setSessionMetadata('ses_1', { openchamber: { archive: { archivedAt: 9 } } }, { allowArchive: true });
+    await store.setSessionMetadata('ses_1', { openchamber: { goal: { id: 'g1' } } });
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { archive: { archivedAt: 9 }, goal: { id: 'g1' } },
+    });
+    await store.setSessionMetadata('ses_1', { openchamber: null });
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { archive: { archivedAt: 9 } },
+    });
+    await store.setSessionMetadata('ses_1', { openchamber: { archive: { archivedAt: 1 } } });
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { archive: { archivedAt: 9 } },
+    });
+  });
+
+  it('does not treat a failed load as empty success on get/getAll', async () => {
+    const dataDir = makeDataDir();
+    fs.writeFileSync(path.join(dataDir, 'sessions-metadata.json'), '{}', 'utf8');
+    const unreadable = Object.assign(new Error('EACCES'), { code: 'EACCES' });
+    const fsPromises = {
+      ...fs.promises,
+      readFile: async () => { throw unreadable; },
+    };
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    await expect(store.get('ses_1')).rejects.toThrow(/unavailable|could not be read|EACCES/i);
+    await expect(store.getAll()).rejects.toThrow(/unavailable|could not be read|EACCES/i);
+    expect(store.getSnapshotSync()).toBeNull();
+  });
+
+  it('mutateSessionMetadata commits only when decide returns ok with a patch', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await store.setSessionMetadata('ses_1', {
+      openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 2 }, assist: { recap: 'keep' } },
+    });
+
+    const rejected = await store.mutateSessionMetadata('ses_1', (current) => {
+      const gen = current?.openchamber?.goal?.executionGeneration;
+      if (gen !== 2) return { ok: false, reason: 'generation_mismatch' };
+      return {
+        ok: false,
+        reason: 'status_not_active',
+      };
+    });
+    expect(rejected).toEqual({
+      committed: false,
+      reason: 'status_not_active',
+      metadata: {
+        openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 2 }, assist: { recap: 'keep' } },
+      },
+    });
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 2 }, assist: { recap: 'keep' } },
+    });
+
+    const accepted = await store.mutateSessionMetadata('ses_1', (current) => {
+      if (current?.openchamber?.goal?.executionGeneration !== 2) {
+        return { ok: false, reason: 'generation_mismatch' };
+      }
+      return {
+        ok: true,
+        patch: { openchamber: { goal: { status: 'paused', executionGeneration: 3 } } },
+      };
+    });
+    expect(accepted.committed).toBe(true);
+    expect(accepted.metadata.openchamber.goal).toEqual({
+      id: 'g1',
+      status: 'paused',
+      executionGeneration: 3,
+    });
+    expect(accepted.metadata.openchamber.assist).toEqual({ recap: 'keep' });
+  });
+
+  it('mutateSessionMetadata does not publish drafts while persist is blocked', async () => {
+    const dataDir = makeDataDir();
+    await createSessionMetadataStore({ dataDir }).setSessionMetadata('ses_1', {
+      openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 1 } },
+    });
+
+    let unlock;
+    const gate = new Promise((resolve) => { unlock = resolve; });
+    const fsPromises = {
+      ...fs.promises,
+      writeFile: async (target, payload, encoding) => {
+        await gate;
+        return fs.promises.writeFile(target, payload, encoding);
+      },
+    };
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    await store.load();
+
+    const pending = store.mutateSessionMetadata('ses_1', () => ({
+      ok: true,
+      patch: { openchamber: { goal: { status: 'paused', executionGeneration: 2 } } },
+    }));
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 1 } },
+    });
+    expect(store.getSnapshotSync()?.ses_1?.openchamber?.goal?.status).toBe('active');
+    unlock();
+    await expect(pending).resolves.toMatchObject({
+      committed: true,
+      metadata: { openchamber: { goal: { status: 'paused', executionGeneration: 2 } } },
+    });
+  });
+
+  it('mutateSessionMetadata preserves Host archive and serializes with setSessionMetadata', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await store.setSessionMetadata('ses_1', { openchamber: { archive: { archivedAt: 42 } } }, { allowArchive: true });
+
+    const [mutated] = await Promise.all([
+      store.mutateSessionMetadata('ses_1', () => ({
+        ok: true,
+        patch: { openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 0 } } },
+      })),
+      store.setSessionMetadata('ses_1', { openchamber: { assist: { recap: 'a' } } }),
+    ]);
+    expect(mutated.committed).toBe(true);
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: {
+        archive: { archivedAt: 42 },
+        goal: { id: 'g1', status: 'active', executionGeneration: 0 },
+        assist: { recap: 'a' },
+      },
+    });
+  });
 });