@cueloop/daemon 0.1.0-alpha.8 → 0.1.0-alpha.80

package/src/server.ts

@@ -1,26 +1,52 @@
 /**
  * The socket server: binds DaemonCore's methods to the unix socket, owns the
- * pidfile, stale-socket cleanup, and the idle-exit timer (#14). File
+ * pidfile, stale-socket cleanup, and the idle-exit timer. File
  * permissions are the local auth: the socket and state dir are 0700/0600.
  */
 
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { DaemonCore, type DaemonEvent } from "./api";
 import { DaemonError } from "./errors";
-import { isKnownMethod, parseParams } from "./validate";
-import { LineBuffer, type Request } from "./protocol";
-import { cueloopHome, lockPath, pidPath, socketPath } from "./paths";
+import { DEFAULT_ROLE, roleAllowsMethod, type DaemonRole } from "./capabilities";
+import { isKnownMethod, parseParams, type MethodName } from "./validate";
+import {
+  BackpressureWriter,
+  LineBuffer,
+  parseRequestFrame,
+  type Request,
+  type Response,
+} from "./protocol";
+import { cueloopHome, lockPath, ownerTokenPath, pidPath, socketPath } from "./paths";
+import { DAEMON_VERSION } from "./version";
+import { randomBytes } from "node:crypto";
 
-interface Conn {
+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. */
+  role: DaemonRole;
 }
 
+type MethodHandler = (connection: Connection, request: Request) => Response["result"];
+
 export interface DaemonOptions {
   home?: string;
   /** Idle-exit delay; 0 disables (tests, foreground runs). */
   idleExitMs?: number;
   onIdleExit?: () => void;
+  /** The version the ping handshake reports; defaults to this build. Tests override it to pose as a stale daemon. */
+  version?: string;
 }
 
 /**
@@ -33,20 +59,24 @@ const HELD_HOMES = new Set<string>();
 export class DaemonServer {
   readonly core: DaemonCore;
   readonly home: string;
-  private conns = new Set<Conn>();
+  private connections = new Set<Connection>();
   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;
+  private readonly version: string;
 
-  constructor(opts: DaemonOptions = {}) {
-    this.home = opts.home ?? cueloopHome();
-    this.idleExitMs = opts.idleExitMs ?? 15 * 60 * 1000;
-    this.onIdleExit = opts.onIdleExit ?? (() => process.exit(0));
+  constructor(options: DaemonOptions = {}) {
+    this.home = options.home ?? cueloopHome();
+    this.idleExitMs = options.idleExitMs ?? 15 * 60 * 1000;
+    this.onIdleExit = options.onIdleExit ?? (() => process.exit(0));
+    this.version = options.version ?? DAEMON_VERSION;
     mkdirSync(this.home, { recursive: true, mode: 0o700 });
     this.core = new DaemonCore(this.home);
-    this.core.onEvent((e) => this.broadcast(e));
+    this.core.onEvent((event) => this.broadcast(event));
   }
 
   /**
@@ -59,16 +89,20 @@ export class DaemonServer {
   private acquireLock(): boolean {
     if (HELD_HOMES.has(this.home)) return false; // another instance here owns it
     const path = lockPath(this.home);
+
     for (let attempt = 0; attempt < 3; attempt++) {
       try {
         // "wx" fails when the file exists - the atomic part of the handshake
         const fd = openSync(path, "wx");
+
         writeFileSync(fd, String(process.pid));
         this.lockFd = fd;
         HELD_HOMES.add(this.home);
+
         return true;
       } catch {
         let ownerPid = 0;
+
         try {
           ownerPid = Number(readFileSync(path, "utf8").trim());
         } catch {
@@ -78,6 +112,7 @@ export class DaemonServer {
         if (ownerPid && ownerPid !== process.pid) {
           try {
             process.kill(ownerPid, 0); // throws when the pid is gone
+
             return false; // a live daemon owns this home
           } catch {
             // stale lock from a crashed daemon
@@ -92,6 +127,7 @@ export class DaemonServer {
         }
       }
     }
+
     return false;
   }
 
@@ -115,27 +151,47 @@ export class DaemonServer {
   start(): string | null {
     if (!this.acquireLock()) return null;
     const path = socketPath(this.home);
+
     // 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 });
-    const self = this;
-    this.server = Bun.listen<{ buffer: LineBuffer; conn: Conn }>({
+    // 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;
+      writer: BackpressureWriter;
+    }>({
       unix: path,
       socket: {
-        open(socket) {
-          const conn: Conn = { write: (d) => socket.write(d), subscribed: false };
-          socket.data = { buffer: new LineBuffer(), conn };
-          self.conns.add(conn);
-          self.scheduleIdleCheck();
+        open: (socket) => {
+          const writer = new BackpressureWriter(socket);
+          const connection: Connection = {
+            write: (data) => writer.write(data),
+            subscribed: false,
+            role: DEFAULT_ROLE,
+          };
+
+          socket.data = { buffer: new LineBuffer(), connection, writer };
+          this.connections.add(connection);
+          this.scheduleIdleCheck();
         },
-        data(socket, data) {
+        data: (socket, data) => {
           socket.data.buffer.push(data.toString(), (line) => {
-            void self.handleLine(socket.data.conn, line);
+            void this.respondToRequestLine(socket.data.connection, line);
           });
         },
-        close(socket) {
-          self.conns.delete(socket.data.conn);
-          self.scheduleIdleCheck();
+        drain(socket) {
+          // drain can fire before open has attached data on some platforms;
+          // a throw here would take the whole daemon down with the socket
+          socket.data?.writer.drain();
+        },
+        close: (socket) => {
+          this.connections.delete(socket.data.connection);
+          this.scheduleIdleCheck();
         },
         error() {},
       },
@@ -143,21 +199,25 @@ export class DaemonServer {
     chmodSync(path, 0o600);
     writeFileSync(pidPath(this.home), String(process.pid));
     this.scheduleIdleCheck();
+
     return path;
   }
 
   stop(): void {
+    this.core.dispose();
     this.server?.stop(true);
     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();
   }
 
-  private broadcast(e: DaemonEvent): void {
-    const frame = JSON.stringify(e) + "\n";
-    for (const c of this.conns) if (c.subscribed) c.write(frame);
+  private broadcast(event: DaemonEvent): void {
+    const frame = JSON.stringify(event) + "\n";
+
+    for (const connection of this.connections) if (connection.subscribed) connection.write(frame);
     this.scheduleIdleCheck();
   }
 
@@ -166,7 +226,7 @@ export class DaemonServer {
     if (this.idleExitMs <= 0) return;
     if (this.idleTimer) clearTimeout(this.idleTimer);
     this.idleTimer = setTimeout(() => {
-      if (this.conns.size === 0 && !this.core.hasPendingSessions()) {
+      if (this.connections.size === 0 && !this.core.hasPendingSessions()) {
         this.stop();
         this.onIdleExit();
       } else {
@@ -175,76 +235,294 @@ export class DaemonServer {
     }, this.idleExitMs);
   }
 
-  private async handleLine(conn: Conn, line: string): Promise<void> {
-    let req: Request;
+  private async respondToRequestLine(connection: Connection, line: string): Promise<void> {
+    let request: Request;
+
     try {
-      req = JSON.parse(line) as Request;
+      request = parseRequestFrame(line);
     } catch {
-      conn.write(JSON.stringify({ id: -1, error: { code: "bad_json", message: "unparseable request" } }) + "\n");
+      connection.write(
+        JSON.stringify({ id: -1, error: { code: "bad_json", message: "unparseable request" } }) +
+          "\n",
+      );
+
       return;
     }
     try {
-      const result = await this.dispatch(conn, req);
-      conn.write(JSON.stringify({ id: req.id, result }) + "\n");
+      const result = await this.dispatch(connection, request);
+
+      connection.write(JSON.stringify({ id: request.id, result }) + "\n");
     } catch (err) {
       const code = err instanceof DaemonError ? err.code : "internal";
       const message = err instanceof Error ? err.message : String(err);
-      conn.write(JSON.stringify({ id: req.id, error: { code, message } }) + "\n");
+
+      connection.write(JSON.stringify({ id: request.id, error: { code, message } }) + "\n");
     }
   }
 
-  private async dispatch(conn: Conn, req: Request): Promise<unknown> {
-    // The wire is untrusted JSON: validate before DaemonCore sees anything.
-    if (typeof req.method !== "string" || !isKnownMethod(req.method)) {
-      throw new DaemonError("unknown_method", `unknown method ${String(req.method)}`);
-    }
-    const core = this.core;
-    switch (req.method) {
-      case "daemon.ping":
-        return { pid: process.pid };
-      case "daemon.shutdown":
-        setTimeout(() => {
-          this.stop();
-          this.onIdleExit();
-        }, 10);
-        return {};
-      case "events.subscribe":
-        conn.subscribed = true;
-        return {};
-      case "session.create": {
-        const p = parseParams("session.create", req.params);
-        return core.sessionCreate({ workspace: p.workspace, artifact: p.artifact });
-      }
-      case "session.get":
-        return core.sessionGet(parseParams("session.get", req.params).id);
-      case "session.list":
-        return core.sessionList(parseParams("session.list", req.params).filter);
-      case "session.wait": {
-        const p = parseParams("session.wait", req.params);
-        return core.sessionWait(p.id, p.timeoutMs);
-      }
-      case "session.annotate": {
-        const p = parseParams("session.annotate", req.params);
-        return core.sessionAnnotate(p.id, p.annotation);
-      }
-      case "session.removeAnnotation": {
-        const p = parseParams("session.removeAnnotation", req.params);
-        return core.sessionRemoveAnnotation(p.id, p.annotationId);
-      }
-      case "session.setWorkingCopy": {
-        const p = parseParams("session.setWorkingCopy", req.params);
-        return core.sessionSetWorkingCopy(p.id, p.workingCopy);
+  private readonly handlers: Record<MethodName, MethodHandler> = {
+    "daemon.ping": () => ({ pid: process.pid, version: this.version }),
+    "daemon.hello": (connection, request) => {
+      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");
       }
-      case "session.resolve": {
-        const p = parseParams("session.resolve", req.params);
-        return core.sessionResolve(p.id, p.verdictKind, p.summary);
+      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 {};
+    },
+    "daemon.shutdown": () => {
+      setTimeout(() => {
+        this.stop();
+        this.onIdleExit();
+      }, 10);
+
+      return {};
+    },
+    "events.subscribe": (connection) => {
+      connection.subscribed = true;
+
+      return {};
+    },
+    "session.create": (_connection, request) => {
+      const params = parseParams("session.create", request.params);
+
+      return this.core.sessionCreate({ workspace: params.workspace, artifact: params.artifact });
+    },
+    "session.get": (_connection, request) =>
+      this.core.sessionGet(parseParams("session.get", request.params).id),
+    "session.list": (_connection, request) =>
+      this.core.sessionList(parseParams("session.list", request.params).filter),
+    "session.wait": (_connection, request) => {
+      const params = parseParams("session.wait", request.params);
+
+      return this.core.sessionWait(params.id, params.timeoutMs);
+    },
+    "session.annotate": (_connection, request) => {
+      const params = parseParams("session.annotate", request.params);
+
+      return this.core.sessionAnnotate(params.id, params.annotation, params.authorName);
+    },
+    "session.comment": (_connection, request) => {
+      const params = parseParams("session.comment", request.params);
+
+      return this.core.sessionAnnotate(params.id, params.annotation, params.authorName);
+    },
+    "session.removeAnnotation": (connection, request) => {
+      const params = parseParams("session.removeAnnotation", request.params);
+
+      // 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",
+        );
       }
-      case "session.submitRevision": {
-        const p = parseParams("session.submitRevision", req.params);
-        return core.sessionSubmitRevision(p.id, p.content);
+
+      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");
       }
-      default:
-        throw new DaemonError("unknown_method", `unknown method ${req.method}`);
+
+      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.setAccess": (_connection, request) => {
+      const params = parseParams("session.setAccess", request.params);
+
+      return this.core.sessionSetAccess(params.id, params.githubLogins);
+    },
+    "session.setViewed": (_connection, request) => {
+      const params = parseParams("session.setViewed", request.params);
+
+      return this.core.sessionSetViewed(params.id, params.viewedPaths);
+    },
+    "session.setTitle": (_connection, request) => {
+      const params = parseParams("session.setTitle", request.params);
+
+      return this.core.sessionSetTitle(params.id, params.title);
+    },
+    "session.projectFiles": (_connection, request) =>
+      this.core.projectFiles(parseParams("session.projectFiles", request.params).id),
+    "session.fileContents": (_connection, request) => {
+      const params = parseParams("session.fileContents", request.params);
+
+      return this.core.fileContents(params.id, params.path);
+    },
+    "repo.files": (_connection, request) =>
+      this.core.repoFiles(parseParams("repo.files", request.params).cwd),
+    "repo.fileContents": (_connection, request) => {
+      const params = parseParams("repo.fileContents", request.params);
+
+      return this.core.repoFileContents(params.cwd, params.path);
+    },
+    "repo.changes": (_connection, request) =>
+      this.core.repoChanges(parseParams("repo.changes", request.params).cwd),
+    "repo.diff": (_connection, request) =>
+      this.core.repoDiff(parseParams("repo.diff", request.params).cwd),
+    "session.workbench": (_connection, request) =>
+      this.core.workbenchSession(parseParams("session.workbench", request.params).cwd),
+    "session.refreshDiff": (_connection, request) => {
+      const params = parseParams("session.refreshDiff", request.params);
+
+      return this.core.sessionRefreshDiff(params.id);
+    },
+    "session.setShareId": (_connection, request) => {
+      const params = parseParams("session.setShareId", request.params);
+
+      return this.core.sessionSetShareId(params.id, params.shareId);
+    },
+    "session.setShares": (_connection, request) => {
+      const params = parseParams("session.setShares", request.params);
+
+      return this.core.sessionSetShares(params.id, params.shares);
+    },
+    "session.delete": (_connection, request) => {
+      this.core.sessionDelete(parseParams("session.delete", request.params).id);
+
+      return {};
+    },
+    "session.mergeShared": (_connection, request) => {
+      const params = parseParams("session.mergeShared", request.params);
+
+      return this.core.sessionMergeShared(params.id, {
+        annotations: params.annotations,
+        participants: params.participants,
+        removals: params.removals,
+      });
+    },
+    "session.sendMessage": (_connection, request) => {
+      const params = parseParams("session.sendMessage", request.params);
+
+      return this.core.sessionSendMessage(
+        params.id,
+        params.outcome,
+        params.summary,
+        params.actionBodies,
+      );
+    },
+    "harness.bind": (_connection, request) => {
+      const params = parseParams("harness.bind", request.params);
+
+      return this.core.harnessBind(params);
+    },
+    "harness.getBinding": (_connection, request) => {
+      const params = parseParams("harness.getBinding", request.params);
+
+      return this.core.harnessGetBinding(params.bindingId);
+    },
+    "harness.consumeApprovedRetry": (_connection, request) => {
+      const params = parseParams("harness.consumeApprovedRetry", request.params);
+
+      return this.core.harnessConsumeApprovedRetry(
+        params.bindingId,
+        params.messageId,
+        params.content,
+      );
+    },
+    "delivery.pending": (_connection, request) => {
+      const params = parseParams("delivery.pending", request.params);
+
+      return this.core.deliveryPending(params.bindingId);
+    },
+    "delivery.acknowledge": (_connection, request) => {
+      const params = parseParams("delivery.acknowledge", request.params);
+
+      return this.core.deliveryAcknowledge(params.deliveryId);
+    },
+    "session.submitRevision": (_connection, request) => {
+      const params = parseParams("session.submitRevision", request.params);
+
+      return this.core.sessionSubmitRevision(
+        params.id,
+        params.content,
+        params.addressedAnnotationIds,
+        params.files,
+      );
+    },
+    "herdr.getTab": (_connection, request) =>
+      this.core.herdrGetTab(parseParams("herdr.getTab", request.params).id),
+    "herdr.setTab": (_connection, request) => {
+      const params = parseParams("herdr.setTab", request.params);
+
+      this.core.herdrSetTab(params.id, { tabId: params.tabId, paneId: params.paneId });
+
+      return {};
+    },
+  };
+
+  private async dispatch(connection: Connection, request: Request): Promise<Response["result"]> {
+    // The wire is untrusted JSON: validate before DaemonCore sees anything.
+    if (!isKnownMethod(request.method)) {
+      throw new DaemonError("unknown_method", `unknown method ${request.method}`);
+    }
+    // Capability gate: a capped role (a review-side agent) cannot escalate past
+    // read + annotate, whatever primitive it sends.
+    if (!roleAllowsMethod(connection.role, request.method)) {
+      throw new DaemonError("forbidden", `role ${connection.role} cannot call ${request.method}`);
     }
+    if (!Object.hasOwn(this.handlers, request.method)) {
+      throw new DaemonError("unknown_method", `unknown method ${request.method}`);
+    }
+
+    return this.handlers[request.method](connection, request);
   }
 }

package/src/share-blob.test.ts

@@ -0,0 +1,112 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { gzipSync } from "node:zlib";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { viewFollowing, type Artifact, type WorkspaceKey } from "@cueloop/schema";
+import { DaemonCore } from "./api";
+import { MAX_BLOB_BYTES, packSessionBlob, unpackSessionBlob } from "./share-blob";
+
+const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
+const PLAN: Artifact = { type: "plan", content: "# Plan\n\nDo the thing.\n", meta: {} };
+
+let home: string;
+let core: DaemonCore;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-blob-"));
+  core = new DaemonCore(home);
+});
+afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+describe("share blob roundtrip", () => {
+  test("pack then unpack restores the session with its annotations", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const annotated = core.sessionAnnotate(session.id, {
+      id: "a_1",
+      kind: "comment",
+      anchor: { quote: "the thing", prefix: "", suffix: "" },
+      body: "why this?",
+    });
+
+    // Act
+    const restored = unpackSessionBlob(packSessionBlob(annotated));
+
+    // Assert
+    expect(restored).toEqual(annotated);
+  });
+});
+
+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
+    const bomb = gzipSync(Buffer.alloc(MAX_BLOB_BYTES + 1, 0x61));
+
+    // Act / Assert
+    expect(() => unpackSessionBlob(bomb)).toThrow(/exceeds|maxOutputLength/i);
+  });
+
+  test("throws on bytes that are not gzip", () => {
+    // Act / Assert
+    expect(() => unpackSessionBlob(Buffer.from("not gzip at all"))).toThrow(/gzip/i);
+  });
+
+  test("throws on a shape that is not a session", () => {
+    // Arrange
+    const notASession = gzipSync(Buffer.from(JSON.stringify({ hello: "world" })));
+
+    // Act / Assert
+    expect(() => unpackSessionBlob(notASession)).toThrow(/not a valid session/i);
+  });
+});