@cueloop/daemon 0.1.0-alpha.64 → 0.1.0-alpha.66

package/src/server.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as v from "valibot";
@@ -80,6 +80,80 @@ describe("socket round-trip", () => {
     observer.close();
   });
 
+  test("an event names the history entry its change appended", async () => {
+    // Arrange
+    const observer = await DaemonClient.connect({ home });
+    const frames: Array<{ event: string; entryId?: string }> = [];
+
+    observer.onEvent((event) => frames.push(event));
+    await observer.subscribe();
+    const session = await client.sessionCreate(WS, PLAN);
+
+    // Act
+    const annotated = await client.sessionAnnotate(session.id, {
+      id: "a_evt",
+      kind: "comment",
+      anchor: { quote: "Plan", prefix: "", suffix: "" },
+      body: "hello",
+    });
+
+    await Bun.sleep(50);
+
+    // Assert: the update frame carries the comment entry's id
+    const updated = frames.find((frame) => frame.event === "session.updated");
+
+    expect(updated?.entryId).toBe(annotated.history!.entries.at(-1)!.id);
+    observer.close();
+  });
+
+  test("a non-owner removes only the comments of the author it acts as, and names itself", async () => {
+    // Arrange: the owner's and Ana's comments; an agent connection acting as Ana
+    const session = await client.sessionCreate(WS, PLAN);
+
+    await client.sessionAnnotate(session.id, {
+      id: "own",
+      kind: "comment",
+      anchor: { quote: "Plan", prefix: "", suffix: "" },
+      body: "mine",
+    });
+    await client.sessionAnnotate(session.id, {
+      id: "anas",
+      kind: "comment",
+      anchor: { quote: "Plan", prefix: "", suffix: "" },
+      body: "hers",
+      author: "SHA256:ana",
+    });
+    const anonymous = await DaemonClient.connect({ home, role: "agent" });
+    const agent = await DaemonClient.connect({ home, role: "agent", author: "SHA256:ana" });
+
+    // Act + Assert: an unbound connection removes nothing; a bound one never another author's
+    await expect(anonymous.sessionRemoveAnnotation(session.id, "own")).rejects.toHaveProperty(
+      "code",
+      "forbidden",
+    );
+    await expect(agent.sessionRemoveAnnotation(session.id, "own")).rejects.toHaveProperty(
+      "code",
+      "forbidden",
+    );
+    await expect(
+      agent.sessionSetParticipantName(session.id, "SHA256:bob", "Not Bob"),
+    ).rejects.toHaveProperty("code", "forbidden");
+
+    // Act: her own comment goes, and she names herself
+    const removed = await agent.sessionRemoveAnnotation(session.id, "anas");
+    const named = await agent.sessionSetParticipantName(session.id, "SHA256:ana", "Ana");
+
+    // Assert
+    expect(removed.annotations.map((annotation) => annotation.id)).toEqual(["own"]);
+    expect(removed.history!.entries.at(-1)).toMatchObject({
+      type: "comment-removed",
+      annotationId: "anas",
+    });
+    expect(named.participants).toContainEqual({ id: "SHA256:ana", provider: "ssh", name: "Ana" });
+    anonymous.close();
+    agent.close();
+  });
+
   test("malformed requests get structured errors and never wedge the daemon", async () => {
     // missing required params
     await expect(
@@ -123,7 +197,7 @@ describe("socket round-trip", () => {
     expect(got.artifact.meta.agent).toBe("claude-code");
   });
 
-  test("share-sync verbs round-trip: setShareId persists, mergeShared unions notes and identities by id", async () => {
+  test("share-sync primitives round-trip: setShareId persists, mergeShared unions notes and identities by id", async () => {
     // Given a shared session with one local note
     const session = await client.sessionCreate(WS, PLAN);
     const anchor = { quote: "Body text", prefix: "", suffix: "." };
@@ -200,6 +274,159 @@ describe("socket round-trip", () => {
   });
 });
 
+describe("ownership is proven, never declared", () => {
+  /** A wire frame as the daemon answers it: a result or a coded error. */
+  interface WireReply {
+    result?: unknown;
+    error?: { code: string };
+  }
+
+  /** The request body a bare socket sends: the primitive's params as the wire carries them. */
+  type WireParams = Parameters<typeof JSON.stringify>[0];
+
+  interface RawConnection {
+    call: (method: string, params: WireParams) => Promise<WireReply>;
+    close: () => void;
+  }
+
+  /** A bare socket that speaks the wire protocol without the client's handshake. */
+  async function rawConnection(): Promise<RawConnection> {
+    const pending = new Map<number, (frame: WireReply) => void>();
+    let buffered = "";
+    let nextId = 1;
+    const socket = await Bun.connect({
+      unix: join(home, "cueloop.sock"),
+      socket: {
+        data: (_socket, data) => {
+          buffered += data.toString();
+          const lines = buffered.split("\n");
+
+          buffered = lines.pop() ?? "";
+          for (const line of lines) {
+            const frame = JSON.parse(line);
+
+            if ("id" in frame) pending.get(frame.id)?.(frame);
+          }
+        },
+      },
+    });
+
+    return {
+      call: (method, params) =>
+        new Promise((resolve) => {
+          const id = nextId++;
+
+          pending.set(id, resolve);
+          socket.write(JSON.stringify({ id, method, params }) + "\n");
+        }),
+      close: () => socket.end(),
+    };
+  }
+
+  test("a connection that never proves ownership is a collaborator: it reads and comments, nothing more", async () => {
+    // Arrange
+    const session = await client.sessionCreate(WS, PLAN);
+    const raw = await rawConnection();
+
+    // Act + Assert
+    expect((await raw.call("session.get", { id: session.id })).error).toBeUndefined();
+    expect(
+      (
+        await raw.call("session.annotate", {
+          id: session.id,
+          annotation: {
+            id: "a_raw",
+            kind: "comment",
+            anchor: { quote: "Plan", prefix: "", suffix: "" },
+            body: "from a bare socket",
+          },
+        })
+      ).error,
+    ).toBeUndefined();
+    expect(
+      (await raw.call("session.resolve", { id: session.id, verdictKind: "approve", summary: "" }))
+        .error?.code,
+    ).toBe("forbidden");
+    expect((await raw.call("session.delete", { id: session.id })).error?.code).toBe("forbidden");
+    raw.close();
+  });
+
+  test("claiming ownership without the token is refused; the token grants it", async () => {
+    // Arrange
+    const raw = await rawConnection();
+
+    // Act + Assert: a bare claim, then a wrong token, both refused
+    expect((await raw.call("daemon.hello", { role: "owner" })).error?.code).toBe("forbidden");
+    expect((await raw.call("daemon.hello", { role: "owner", token: "nope" })).error?.code).toBe(
+      "forbidden",
+    );
+    expect((await raw.call("daemon.shutdown", {})).error?.code).toBe("forbidden");
+
+    // Act: the token the daemon wrote into its home
+    const token = readFileSync(join(home, "owner.token"), "utf8").trim();
+
+    expect((await raw.call("daemon.hello", { role: "owner", token })).error).toBeUndefined();
+
+    // Assert: owner primitives open up
+    const created = await raw.call("session.create", { workspace: WS, artifact: PLAN });
+
+    expect(created.error).toBeUndefined();
+    raw.close();
+  });
+
+  test("a refused handshake reaches the caller and leaves the live daemon's socket alone", async () => {
+    // Arrange: a token file that is not what the daemon minted
+    const tokenPath = join(home, "owner.token");
+    const minted = readFileSync(tokenPath, "utf8");
+
+    writeFileSync(tokenPath, "0".repeat(64));
+
+    // Act + Assert: the client hears the refusal; autostart does not replace the daemon
+    await expect(DaemonClient.connect({ home, autostart: true })).rejects.toHaveProperty(
+      "code",
+      "forbidden",
+    );
+    expect(existsSync(join(home, "cueloop.sock"))).toBe(true);
+    expect((await client.sessionList()).length).toBe(0);
+
+    // Arrange: a token file that is not a token at all
+    writeFileSync(tokenPath, "not-a-token");
+
+    // Act + Assert
+    await expect(DaemonClient.connect({ home })).rejects.toHaveProperty(
+      "code",
+      "invalid_owner_token",
+    );
+    writeFileSync(tokenPath, minted);
+  });
+
+  test("the token exists before the socket does", () => {
+    // Arrange: a second daemon in another home
+    const other = mkdtempSync(join(tmpdir(), "cueloop-token-"));
+    const daemon = new DaemonServer({ home: other, idleExitMs: 0 });
+
+    try {
+      // Act
+      daemon.start();
+
+      // Assert: the token is on disk the moment the socket is
+      expect(existsSync(join(other, "owner.token"))).toBe(true);
+      expect(existsSync(join(other, "cueloop.sock"))).toBe(true);
+    } finally {
+      daemon.stop();
+      rmSync(other, { recursive: true, force: true });
+    }
+  });
+
+  test("the daemon client proves ownership on connect and the token is private to the home", async () => {
+    // Assert: the client in beforeEach connected as the owner through the token
+    const session = await client.sessionCreate(WS, PLAN);
+
+    expect((await client.sessionResolve(session.id, "approve", "")).status).toBe("resolved");
+    expect(statSync(join(home, "owner.token")).mode & 0o777).toBe(0o600);
+  });
+});
+
 describe("large payloads survive socket backpressure", () => {
   test("a session bigger than the kernel socket buffer round-trips", async () => {
     // Regression: responses larger than one socket write used to truncate

package/src/server.ts

@@ -16,7 +16,7 @@ import {
 } from "node:fs";
 import { DaemonCore, type DaemonEvent } from "./api";
 import { DaemonError } from "./errors";
-import { roleAllowsMethod, type DaemonRole } from "./capabilities";
+import { DEFAULT_ROLE, roleAllowsMethod, type DaemonRole } from "./capabilities";
 import { isKnownMethod, parseParams, type MethodName } from "./validate";
 import {
   BackpressureWriter,
@@ -25,9 +25,12 @@ import {
   type Request,
   type Response,
 } from "./protocol";
-import { cueloopHome, lockPath, pidPath, socketPath } from "./paths";
+import { cueloopHome, lockPath, ownerTokenPath, pidPath, socketPath } from "./paths";
+import { randomBytes } from "node:crypto";
 
 interface Connection {
+  /** The author a non-owner connection acts as, bound in the handshake. */
+  author?: string;
   write(data: string): void;
   subscribed: boolean;
   /** Capability role for this connection; the owner until a daemon.hello caps it. */
@@ -57,6 +60,8 @@ export class DaemonServer {
   private server: ReturnType<typeof Bun.listen> | null = null;
   private idleTimer: ReturnType<typeof setTimeout> | null = null;
   private lockFd: number | null = null;
+  /** The secret that proves ownership; minted per daemon run, readable by the home's user only. */
+  private ownerToken = "";
   private readonly idleExitMs: number;
   private readonly onIdleExit: () => void;
 
@@ -145,6 +150,11 @@ export class DaemonServer {
     // safe now: holding the lock means no live daemon owns this home, so any
     // socket file left behind is stale
     if (existsSync(path)) rmSync(path, { force: true });
+    // the token exists before the socket does: the first client to connect
+    // must be able to prove ownership
+    this.ownerToken = randomBytes(32).toString("hex");
+    writeFileSync(ownerTokenPath(this.home), this.ownerToken, { mode: 0o600 });
+    chmodSync(ownerTokenPath(this.home), 0o600);
     this.server = Bun.listen<{
       buffer: LineBuffer;
       connection: Connection;
@@ -157,7 +167,7 @@ export class DaemonServer {
           const connection: Connection = {
             write: (data) => writer.write(data),
             subscribed: false,
-            role: "owner",
+            role: DEFAULT_ROLE,
           };
 
           socket.data = { buffer: new LineBuffer(), connection, writer };
@@ -194,6 +204,7 @@ export class DaemonServer {
     this.server = null;
     rmSync(socketPath(this.home), { force: true });
     rmSync(pidPath(this.home), { force: true });
+    rmSync(ownerTokenPath(this.home), { force: true });
     if (this.idleTimer) clearTimeout(this.idleTimer);
     this.releaseLock();
   }
@@ -247,7 +258,16 @@ export class DaemonServer {
   private readonly handlers: Record<MethodName, MethodHandler> = {
     "daemon.ping": () => ({ pid: process.pid }),
     "daemon.hello": (connection, request) => {
-      connection.role = parseParams("daemon.hello", request.params).role;
+      const params = parseParams("daemon.hello", request.params);
+
+      // ownership is proven, never declared: the token lives in the home
+      // directory the daemon serves, readable by its user alone
+      if (params.role === "owner" && params.token !== this.ownerToken) {
+        throw new DaemonError("forbidden", "owner token required");
+      }
+      connection.role = params.role;
+      // identity is bound once, here; a non-owner never names it per call
+      if (params.role !== "owner" && params.author !== undefined) connection.author = params.author;
 
       return {};
     },
@@ -283,16 +303,78 @@ export class DaemonServer {
 
       return this.core.sessionAnnotate(params.id, params.annotation, params.authorName);
     },
-    "session.removeAnnotation": (_connection, request) => {
+    "session.removeAnnotation": (connection, request) => {
       const params = parseParams("session.removeAnnotation", request.params);
 
-      return this.core.sessionRemoveAnnotation(params.id, params.annotationId);
+      // the owner removes any comment; a non-owner only the ones of the author it is bound to
+      if (connection.role !== "owner" && connection.author === undefined) {
+        throw new DaemonError(
+          "forbidden",
+          "a non-owner connection removes comments as its bound author",
+        );
+      }
+
+      return this.core.sessionRemoveAnnotation(
+        params.id,
+        params.annotationId,
+        connection.role === "owner" ? undefined : connection.author,
+      );
+    },
+    "session.setParticipantName": (connection, request) => {
+      const params = parseParams("session.setParticipantName", request.params);
+
+      // the owner names anyone; a non-owner names only the author it is bound to
+      if (connection.role !== "owner" && params.author !== connection.author) {
+        throw new DaemonError("forbidden", "a non-owner connection names only its bound author");
+      }
+
+      return this.core.sessionSetParticipantName(params.id, params.author, params.name);
     },
     "session.setWorkingCopy": (_connection, request) => {
       const params = parseParams("session.setWorkingCopy", request.params);
 
       return this.core.sessionSetWorkingCopy(params.id, params.workingCopy);
     },
+    "session.cutBlock": (_connection, request) => {
+      const params = parseParams("session.cutBlock", request.params);
+
+      return this.core.sessionCutBlock(params.id, params.blockIndex);
+    },
+    "session.navigate": (_connection, request) => {
+      const params = parseParams("session.navigate", request.params);
+
+      return this.core.sessionNavigate(params.id, params.entryId, params.summary, params.branch);
+    },
+    "session.branch": (_connection, request) => {
+      const params = parseParams("session.branch", request.params);
+
+      return this.core.sessionBranch(params.id, params.name);
+    },
+    "session.switch": (_connection, request) => {
+      const params = parseParams("session.switch", request.params);
+
+      return this.core.sessionSwitch(params.id, params.branch);
+    },
+    "session.label": (_connection, request) => {
+      const params = parseParams("session.label", request.params);
+
+      return this.core.sessionLabel(params.id, params.label);
+    },
+    "session.fork": (_connection, request) => {
+      const params = parseParams("session.fork", request.params);
+
+      return this.core.sessionFork(params.id);
+    },
+    "session.restoreBlock": (_connection, request) => {
+      const params = parseParams("session.restoreBlock", request.params);
+
+      return this.core.sessionRestoreBlock(params.id, params.baseBlockIndex, params.line);
+    },
+    "session.curate": (_connection, request) => {
+      const params = parseParams("session.curate", request.params);
+
+      return this.core.sessionCurate(params.id, params.rejections);
+    },
     "session.setViewed": (_connection, request) => {
       const params = parseParams("session.setViewed", request.params);
 
@@ -319,6 +401,7 @@ export class DaemonServer {
       return this.core.sessionMergeShared(params.id, {
         annotations: params.annotations,
         participants: params.participants,
+        removals: params.removals,
       });
     },
     "session.resolve": (_connection, request) => {
@@ -352,7 +435,7 @@ export class DaemonServer {
       throw new DaemonError("unknown_method", `unknown method ${request.method}`);
     }
     // Capability gate: a capped role (a review-side agent) cannot escalate past
-    // read + annotate, whatever verb it sends.
+    // read + annotate, whatever primitive it sends.
     if (!roleAllowsMethod(connection.role, request.method)) {
       throw new DaemonError("forbidden", `role ${connection.role} cannot call ${request.method}`);
     }

package/src/share-blob.test.ts

@@ -3,7 +3,7 @@ import { gzipSync } from "node:zlib";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { Artifact, WorkspaceKey } from "@cueloop/schema";
+import { viewFollowing, type Artifact, type WorkspaceKey } from "@cueloop/schema";
 import { DaemonCore } from "./api";
 import { MAX_BLOB_BYTES, packSessionBlob, unpackSessionBlob } from "./share-blob";
 
@@ -38,6 +38,56 @@ describe("share blob roundtrip", () => {
   });
 });
 
+describe("the payload cap against a long review", () => {
+  test("a plan the size of the examples with a long discussion and its history stays far under the cap", () => {
+    // Arrange: the largest example plan, 200 rounds of comment + reply, 20 reviewer edits, 10 removals
+    const paragraph =
+      "Review sessions currently live only in daemon memory. If the daemon crashes mid-review, every pending annotation is lost. This plan makes sessions durable without changing the daemon's socket protocol.\n\n";
+    const content = `# Implementation Plan: Session Persistence\n\n## Context\n\n${paragraph.repeat(8)}`;
+    const session = core.sessionCreate({
+      workspace: WS,
+      artifact: { type: "plan", content, meta: {} },
+    });
+
+    for (let round = 0; round < 200; round++) {
+      core.sessionAnnotate(session.id, {
+        id: `a_${round}`,
+        kind: "comment",
+        anchor: { quote: "daemon memory", prefix: "live only in ", suffix: ". If the" },
+        body: `Round ${round}: what happens when the store directory is read-only at startup?`,
+        author: "SHA256:collaborator-fingerprint-0123456789abcdef",
+      });
+      core.sessionAnnotate(session.id, {
+        id: `r_${round}`,
+        kind: "comment",
+        anchor: { quote: "daemon memory", prefix: "live only in ", suffix: ". If the" },
+        body: "Fail fast with a readable error; the review never opens on a store that cannot write.",
+        replyTo: `a_${round}`,
+      });
+      if (round % 10 === 0)
+        core.sessionSetWorkingCopy(session.id, `${content}\n\nEdit ${round}.\n`);
+      if (round % 20 === 0) core.sessionRemoveAnnotation(session.id, `r_${round}`);
+    }
+    const shared = viewFollowing(core.sessionGet(session.id));
+
+    // Act
+    const decompressed = Buffer.byteLength(JSON.stringify(shared), "utf8");
+    const packed = packSessionBlob(shared).byteLength;
+
+    // Assert: a quarter of the cap decompressed, and the packed blob a small
+    // fraction of it; the round-trip holds
+    expect(shared.history!.entries.length).toBeGreaterThan(400);
+    expect(decompressed).toBeLessThan(MAX_BLOB_BYTES / 4);
+    expect(packed).toBeLessThan(decompressed);
+    expect(unpackSessionBlob(packSessionBlob(shared)).history!.entries.length).toBe(
+      shared.history!.entries.length,
+    );
+    console.info(
+      `share payload: ${shared.history!.entries.length} entries, ${decompressed} bytes decompressed, ${packed} bytes packed, cap ${MAX_BLOB_BYTES}`,
+    );
+  });
+});
+
 describe("unpack rejects bad input", () => {
   test("caps the decompressed size, so a compression bomb throws", () => {
     // Arrange: tiny gzip, huge inflation - the decompression-bomb shape

package/src/store.conformance.test.ts

@@ -0,0 +1,41 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import * as v from "valibot";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MemorySessionStore, SessionStore, type SessionRepository } from "./store";
+import { sessionsDir } from "./paths";
+import { runSessionStoreConformance } from "./testing/store-conformance";
+
+const homes = new WeakMap<SessionRepository, string>();
+
+runSessionStoreConformance("file store", {
+  open: (records) => {
+    const home = mkdtempSync(join(tmpdir(), "cueloop-store-"));
+    const store = new SessionStore(home);
+
+    // records land on disk the way an earlier daemon would have written them;
+    // the file name comes from the record's id when it has one
+    records.forEach((record, index) => {
+      const named = v.safeParse(v.object({ id: v.string() }), record);
+      const id = named.success ? named.output.id : `bad_${index}`;
+
+      writeFileSync(join(sessionsDir(home), `${id}.json`), JSON.stringify(record));
+    });
+    homes.set(store, home);
+
+    return store;
+  },
+  restart: (store) => {
+    const reopened = new SessionStore(homes.get(store)!);
+
+    homes.set(reopened, homes.get(store)!);
+
+    return reopened;
+  },
+});
+
+runSessionStoreConformance("memory store", {
+  open: (records) => new MemorySessionStore(records),
+  // nothing persists past the instance: a restart recovers what it was seeded with
+  restart: (store) => new MemorySessionStore(store.list()),
+});

package/src/store.ts

@@ -1,22 +1,55 @@
 /**
- * Session persistence: one JSON document per session, every write
- * through a temp file + atomic rename so a crash mid-write can never leave
- * a corrupt record. Recovery is a read-only scan; records that fail to
- * parse are skipped and reported, never deleted.
+ * Session persistence: one JSON record per session, written whole through a
+ * temp file and an atomic rename so a crash never leaves a torn file. Recovery
+ * is a read-only scan of the state directory; records that fail to parse are
+ * skipped and reported, never deleted, and records from before histories
+ * existed are given one on read.
+ *
+ * `SessionRepository` is the contract every adapter satisfies; the conformance
+ * suite in ./testing/store-conformance.ts pins it for the file store and the
+ * in-memory store alike.
  */
 
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import type { ReviewSession } from "@cueloop/schema";
-import { validateSessionRecord } from "./validate";
+import { historyFromLinear, type ReviewSession } from "@cueloop/schema";
 import { sessionsDir } from "./paths";
+import { validateSessionRecord } from "./validate";
 
 export interface RecoveryReport {
   recovered: string[];
   skipped: { file: string; error: string }[];
 }
 
-export class SessionStore {
+/** What the daemon needs from session storage. */
+export interface SessionRepository {
+  /** Load what is stored; called once on boot. */
+  recover(): RecoveryReport;
+  get(id: string): ReviewSession | undefined;
+  /** Every session, oldest first. */
+  list(): ReviewSession[];
+  upsert(session: ReviewSession): void;
+  /** True when a session was removed. */
+  delete(id: string): boolean;
+}
+
+/**
+ * A record as it is read: a history is derived for records written without
+ * one. A record with no revision has no head to derive from and keeps
+ * reading without a history - migration never loses a record.
+ */
+export function withHistory(session: ReviewSession): ReviewSession {
+  if (session.history || session.revisions.length === 0) return session;
+
+  return { ...session, history: historyFromLinear(session) };
+}
+
+/** Records in the order `list()` promises: oldest first. */
+function oldestFirst(sessions: Iterable<ReviewSession>): ReviewSession[] {
+  return [...sessions].sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+
+export class SessionStore implements SessionRepository {
   private sessions = new Map<string, ReviewSession>();
   private readonly dir: string;
 
@@ -25,7 +58,6 @@ export class SessionStore {
     mkdirSync(this.dir, { recursive: true });
   }
 
-  /** Read-only scan of the state directory; called once on boot. */
   recover(): RecoveryReport {
     const report: RecoveryReport = { recovered: [], skipped: [] };
 
@@ -36,7 +68,7 @@ export class SessionStore {
         const parsed = validateSessionRecord(JSON.parse(raw));
 
         if (!parsed.ok) throw new Error(`invalid record - ${parsed.error}`);
-        const session: ReviewSession = parsed.value;
+        const session = withHistory(parsed.value);
 
         this.sessions.set(session.id, session);
         report.recovered.push(session.id);
@@ -53,9 +85,7 @@ export class SessionStore {
   }
 
   list(): ReviewSession[] {
-    return [...this.sessions.values()].sort((left, right) =>
-      left.createdAt.localeCompare(right.createdAt),
-    );
+    return oldestFirst(this.sessions.values());
   }
 
   upsert(session: ReviewSession): void {
@@ -74,3 +104,50 @@ export class SessionStore {
     return true;
   }
 }
+
+/**
+ * The in-memory adapter: the same contract with nothing on disk. `seed` stands
+ * in for what a file store finds on recovery, so validation and migration are
+ * exercised the same way.
+ */
+export class MemorySessionStore implements SessionRepository {
+  private sessions = new Map<string, ReviewSession>();
+
+  constructor(private readonly seed: unknown[] = []) {}
+
+  recover(): RecoveryReport {
+    const report: RecoveryReport = { recovered: [], skipped: [] };
+
+    this.seed.forEach((record, index) => {
+      const parsed = validateSessionRecord(record);
+
+      if (!parsed.ok) {
+        report.skipped.push({ file: `seed[${index}]`, error: `invalid record - ${parsed.error}` });
+
+        return;
+      }
+      const session = withHistory(parsed.value);
+
+      this.sessions.set(session.id, session);
+      report.recovered.push(session.id);
+    });
+
+    return report;
+  }
+
+  get(id: string): ReviewSession | undefined {
+    return this.sessions.get(id);
+  }
+
+  list(): ReviewSession[] {
+    return oldestFirst(this.sessions.values());
+  }
+
+  upsert(session: ReviewSession): void {
+    this.sessions.set(session.id, session);
+  }
+
+  delete(id: string): boolean {
+    return this.sessions.delete(id);
+  }
+}