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

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

@@ -1,22 +1,30 @@
 /**
- * OpenChamber-owned session metadata.
+ * OpenChamber session metadata cache and migration source.
  *
- * OpenCode 2.x accepts `metadata` only when a session is created; the v1
- * `PATCH /session/{id}` route is gone and nothing replaces it. Session goal
- * progress (and later assist / pinned notes) live here: one JSON file per data
- * dir, `{ [sessionID]: metadata }`, folded back onto the sessions the proxy
- * serves so clients keep reading `session.metadata` where they always did.
+ * The OpenCode session record is the durable authority for title, archive, and
+ * other OpenChamber metadata (`opencode-session-record.js`). This JSON file
+ * remains the cache and the pre-migration source. A failed or corrupt read is
+ * never empty success: the store stays unwritable and does not overwrite
+ * unknown disk state or the OpenCode record.
  *
  * Writes are a JSON Merge Patch (RFC 7386): nested objects merge key by key and
- * 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.
+ * a `null` deletes. That keeps two features writing into the same `openchamber`
+ * namespace from erasing each other — goal mode saving progress must not drop
+ * an assist recap. When a record reader and writer are wired, the merged object
+ * is written onto the OpenCode session before the local cache commits. A failed
+ * record read is not treated as empty metadata.
+ *
+ * Mutations are fully serialized. Committed `entries` update only after a
+ * successful persist so concurrent readers never observe uncommitted drafts.
  */
 
 import fsDefault from 'node:fs';
 import pathDefault from 'node:path';
 
+import { mergeOwnedMetadata } from './opencode-session-record.js';
+
 const METADATA_FILE_NAME = 'sessions-metadata.json';
+const HOST_ARCHIVE_KEY = 'archive';
 
 const asNonEmptyString = (value) => {
   if (typeof value !== 'string') return null;
@@ -43,34 +51,98 @@ 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.
  * @param {typeof fsDefault.promises} [options.fsPromises]
  * @param {typeof pathDefault} [options.path]
  * @param {() => number} [options.now]
+ * @param {(sessionID: string, directory?: string | null) => Promise<object | null>} [options.recordReader]
+ *   OpenCode session read. Null means the session is gone. Any other failure throws.
+ * @param {(sessionID: string, metadata: object, directory?: string | null) => Promise<void>} [options.recordWriter]
+ *   Writes the full merged metadata onto the OpenCode session record. Must not send title.
  */
 export const createSessionMetadataStore = ({
   dataDir,
   fsPromises = fsDefault.promises,
   path = pathDefault,
   now = Date.now,
+  recordReader = null,
+  recordWriter = null,
 }) => {
+  if (typeof recordWriter === 'function' && typeof recordReader !== 'function') {
+    throw new Error('session record writer requires a record reader');
+  }
   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 snapshotFrom = (map) => Object.fromEntries(map);
+  const snapshot = () => snapshotFrom(entries);
 
-  const snapshot = () => Object.fromEntries(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 +152,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 +162,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 +183,239 @@ 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 readRecordMetadata = async (id, directory) => {
+    if (typeof recordReader !== 'function') return undefined;
+    try {
+      const record = await recordReader(id, directory);
+      if (record == null) return null;
+      return isPlainObject(record.metadata) ? record.metadata : {};
+    } catch (error) {
+      if (entries.has(id)) return undefined;
+      throw error;
+    }
+  };
+
+  const get = async (sessionID, options = {}) => {
     const id = asNonEmptyString(sessionID);
     if (!id) return {};
-    await load();
-    return entries.get(id) ?? {};
+    await ensureReadable();
+    const side = entries.get(id);
+    const fromRecord = await readRecordMetadata(id, options.directory);
+    if (fromRecord === undefined) return side ?? {};
+    if (fromRecord === null) return side ?? {};
+    return mergeOwnedMetadata(fromRecord, side);
   };
 
-  /** 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;
+    let base = previous;
+    if (typeof recordReader === 'function') {
+      let record;
+      try {
+        record = await recordReader(id, options.directory);
+      } catch (error) {
+        // A failed read is not an empty record. Do not replace metadata we could not see.
+        throw error;
+      }
+      if (record == null) {
+        const error = new Error(`session ${id} was not found`);
+        error.status = 404;
+        throw error;
+      }
+      base = mergeOwnedMetadata(record.metadata, previous);
+    }
+    const effectivePatch = allowArchive ? patch : stripArchiveFromMetadataPatch(patch);
+
+    let merged = mergeMetadataPatch(base, effectivePatch);
+    merged = applyReservedArchiveProtection(base, patch, merged, { allowArchive });
+
+    if (typeof recordWriter === 'function') {
+      await recordWriter(id, merged, options.directory);
+    }
+
+    const nextMap = new Map(entries);
+    if (Object.keys(merged).length === 0) nextMap.delete(id);
+    else nextMap.set(id, merged);
+
+    // OpenCode write already landed. Publish the local cache only after its persist succeeds.
+    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,
   };