zeitlich 0.2.45 → 0.2.47

package/src/lib/session/session-edge-cases.integration.test.ts

@@ -129,6 +129,12 @@ function createMockThreadOps() {
       log.push({ op: "saveThreadState", args: [threadId, state] });
       stateStore.set(threadId, state);
     },
+    hydrateThread: async (threadId) => {
+      log.push({ op: "hydrateThread", args: [threadId] });
+    },
+    flushThread: async (threadId) => {
+      log.push({ op: "flushThread", args: [threadId] });
+    },
   });
   return { ops, log, stateStore };
 }
@@ -824,6 +830,12 @@ describe("createSession edge cases", () => {
       saveThreadState: async (threadId, state) => {
         log.push({ op: "saveThreadState", args: [threadId, state] });
       },
+      hydrateThread: async (threadId) => {
+        log.push({ op: "hydrateThread", args: [threadId] });
+      },
+      flushThread: async (threadId) => {
+        log.push({ op: "flushThread", args: [threadId] });
+      },
     });
 
     const session = await createSession<

package/src/lib/session/session.integration.test.ts

@@ -132,6 +132,12 @@ function createMockThreadOps() {
       log.push({ op: "saveThreadState", args: [threadId, state] });
       stateStore.set(threadId, state);
     },
+    hydrateThread: async (threadId) => {
+      log.push({ op: "hydrateThread", args: [threadId] });
+    },
+    flushThread: async (threadId) => {
+      log.push({ op: "flushThread", args: [threadId] });
+    },
   });
 
   return { ops, log, stateStore };
@@ -1336,4 +1342,136 @@ describe("createSession integration", () => {
     const newThreadSlice = stateStore.get(result.threadId);
     expect(newThreadSlice?.tasks).toHaveLength(1);
   });
+
+  // --- Cold-tier lifecycle (hydrateThread + flushThread) ---
+
+  it("skips hydrateThread for mode:'new' threads but still flushes on exit", async () => {
+    const { ops, log } = createMockThreadOps();
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "fresh-thread" },
+      runAgent: createScriptedRunAgent([{ message: "ok", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "hi",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    await session.runSession({ stateManager });
+
+    expect(log.filter((l) => l.op === "hydrateThread")).toHaveLength(0);
+    const flushes = log.filter((l) => l.op === "flushThread");
+    expect(flushes).toHaveLength(1);
+    expect(at(flushes, 0).args[0]).toBe("fresh-thread");
+  });
+
+  it("hydrates the target thread before continuing it", async () => {
+    const { ops, log, stateStore } = createMockThreadOps();
+    stateStore.set("existing-thread", {
+      tasks: [],
+      custom: { previous: true },
+    });
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "continue", threadId: "existing-thread" },
+      runAgent: createScriptedRunAgent([{ message: "ok", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "follow-up",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    await session.runSession({ stateManager });
+
+    const hydrates = log.filter((l) => l.op === "hydrateThread");
+    expect(hydrates).toHaveLength(1);
+    expect(at(hydrates, 0).args[0]).toBe("existing-thread");
+
+    // hydrate runs strictly before loadThreadState so the load sees
+    // fresh data when a cold tier is wired.
+    const hydrateIdx = log.findIndex((l) => l.op === "hydrateThread");
+    const loadIdx = log.findIndex((l) => l.op === "loadThreadState");
+    expect(hydrateIdx).toBeLessThan(loadIdx);
+  });
+
+  it("hydrates the *source* thread (not the new one) on mode:'fork'", async () => {
+    const { ops, log, stateStore } = createMockThreadOps();
+    stateStore.set("src-thread", { tasks: [], custom: {} });
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "fork", threadId: "src-thread" },
+      runAgent: createScriptedRunAgent([{ message: "ok", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "fork me",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    const result = await session.runSession({ stateManager });
+
+    const hydrates = log.filter((l) => l.op === "hydrateThread");
+    expect(hydrates).toHaveLength(1);
+    expect(at(hydrates, 0).args[0]).toBe("src-thread");
+
+    // hydrate runs before forkThread so the source is hot before
+    // the in-Redis fork copy.
+    const hydrateIdx = log.findIndex((l) => l.op === "hydrateThread");
+    const forkIdx = log.findIndex((l) => l.op === "forkThread");
+    expect(hydrateIdx).toBeLessThan(forkIdx);
+
+    // Flush still targets the *new* thread.
+    const flushes = log.filter((l) => l.op === "flushThread");
+    expect(flushes).toHaveLength(1);
+    expect(at(flushes, 0).args[0]).toBe(result.threadId);
+    expect(at(flushes, 0).args[0]).not.toBe("src-thread");
+  });
+
+  it("flushThread runs even when the session fails", async () => {
+    const { ops, log } = createMockThreadOps();
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "fail-thread" },
+      runAgent: async () => {
+        throw new Error("boom");
+      },
+      threadOps: ops,
+      buildContextMessage: () => "hi",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    await expect(session.runSession({ stateManager })).rejects.toThrow(/boom/);
+
+    const flushes = log.filter((l) => l.op === "flushThread");
+    expect(flushes).toHaveLength(1);
+    expect(at(flushes, 0).args[0]).toBe("fail-thread");
+  });
+
+  it("flushThread runs after saveThreadState", async () => {
+    const { ops, log } = createMockThreadOps();
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "ordered-thread" },
+      runAgent: createScriptedRunAgent([{ message: "ok", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "hi",
+    });
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "system" },
+    });
+    await session.runSession({ stateManager });
+
+    const saveIdx = log.findIndex((l) => l.op === "saveThreadState");
+    const flushIdx = log.findIndex((l) => l.op === "flushThread");
+    expect(saveIdx).toBeGreaterThanOrEqual(0);
+    expect(flushIdx).toBeGreaterThan(saveIdx);
+  });
 });

package/src/lib/session/session.ts

@@ -198,6 +198,8 @@ export async function createSession<
     forkThread,
     loadThreadState,
     saveThreadState,
+    hydrateThread,
+    flushThread,
   } = threadOps;
 
   const plugins: ToolMap[string][] = [];
@@ -391,10 +393,19 @@ export async function createSession<
       };
 
       if (threadMode === "fork" && sourceThreadId) {
+        // Pull the source thread from the cold tier into Redis (if a
+        // cold store is configured for this adapter) before the
+        // in-Redis fork copy runs. Hydrate is a no-op when the source
+        // is already hot or when no cold tier is wired.
+        await hydrateThread(sourceThreadId, threadKey);
         await forkThread(sourceThreadId, threadId, threadKey);
         const forkedSlice = await loadThreadState(threadId, threadKey);
         if (forkedSlice) rehydrateFromSlice(forkedSlice);
       } else if (threadMode === "continue") {
+        // Pull the thread from the cold tier into Redis before any
+        // appends. No-op when the thread is already hot or when no
+        // cold tier is wired.
+        await hydrateThread(threadId, threadKey);
         // "continue" — thread already exists, just append the new message
         const continuedSlice = await loadThreadState(threadId, threadKey);
         if (continuedSlice) rehydrateFromSlice(continuedSlice);
@@ -640,6 +651,24 @@ export async function createSession<
           });
         }
 
+        // Archive the thread to the durable cold tier (S3 / R2 / etc.)
+        // after the state slice has been written. No-op when no cold
+        // store is wired into the adapter. Best-effort — failures
+        // must not mask the original exit reason and the thread is
+        // still readable from Redis via its TTL window.
+        try {
+          await flushThread(threadId, threadKey);
+        } catch (flushError) {
+          log.warn("failed to flush thread to cold tier", {
+            agentName,
+            threadId,
+            error:
+              flushError instanceof Error
+                ? flushError.message
+                : String(flushError),
+          });
+        }
+
         await callSessionEnd(exitReason, stateManager.getTurns());
 
         if (sandboxOwned && sandboxId && sandboxOps) {

package/src/lib/session/types.ts

@@ -109,6 +109,28 @@ export interface ThreadOps<TContent = string> {
     state: PersistedThreadState,
     threadKey?: string
   ): Promise<void>;
+  /**
+   * Restore the thread's contents from the durable cold tier (if any)
+   * into Redis. Called once on session entry for `mode: "continue"`
+   * and `mode: "fork"` so the rest of the loop reads the freshest data.
+   *
+   * Adapters configured without a cold-store implementation treat this
+   * as a no-op. Implementations must be **idempotent** — Temporal
+   * retries the activity on transient failures, and a thread that is
+   * already hot must not be wiped.
+   */
+  hydrateThread(threadId: string, threadKey?: string): Promise<void>;
+  /**
+   * Archive the thread's contents to the durable cold tier and
+   * (optionally) drop the hot-tier Redis keys. Called once in the
+   * session's `finally` block on every exit path, after
+   * `saveThreadState`.
+   *
+   * Adapters configured without a cold-store implementation treat this
+   * as a no-op. Implementations must be **idempotent** — the cold
+   * tier is last-writer-wins and a retried flush must converge.
+   */
+  flushThread(threadId: string, threadKey?: string): Promise<void>;
 }
 
 /**

package/src/lib/subagent/define.ts

@@ -44,6 +44,7 @@ export function defineSubagent<
     enabled?: boolean | (() => boolean);
     taskQueue?: string;
     thread?: "new" | "fork" | "continue";
+    newThreadSource?: "new" | "from-parent";
     sandbox?: SubagentSandboxConfig;
   }
 ): SubagentConfig<TResult> {

package/src/lib/subagent/handler.ts

@@ -237,8 +237,17 @@ export function createSubagentHandler<
 
     const threadMode = config.thread ?? "new";
     const allowsContinuation = threadMode !== "new";
-    const continuationThreadId =
-      args.threadId && allowsContinuation ? args.threadId : undefined;
+    // The parent agent's tool call wins. When `threadId` is omitted,
+    // `newThreadSource` decides what to fall back to: `"new"` (default)
+    // starts fresh, `"from-parent"` continues/forks the parent's own
+    // thread via `context.threadId`. Both paths still require
+    // `thread: "fork" | "continue"` — `thread: "new"` always starts
+    // fresh regardless of the source.
+    const newThreadSource = config.newThreadSource ?? "new";
+    const continuationThreadId = !allowsContinuation
+      ? undefined
+      : (args.threadId ??
+        (newThreadSource === "from-parent" ? context.threadId : undefined));
 
     // --- Build thread init ---
     let thread: ThreadInit | undefined;

package/src/lib/subagent/subagent.integration.test.ts

@@ -635,6 +635,145 @@ describe("createSubagentHandler", () => {
     expect(workflowInput.thread).toBeUndefined();
   });
 
+  // --- newThreadSource: "from-parent" ---
+
+  it("uses the parent's threadId when fork + newThreadSource 'from-parent' and args.threadId is absent", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const subagent: SubagentConfig = {
+      agentName: "parent-fork",
+      description: "Forks parent thread by default",
+      workflow: mockWorkflow(),
+      thread: "fork",
+      newThreadSource: "from-parent",
+    };
+
+    const { handler } = createSubagentHandler([subagent]);
+
+    await handler(
+      { subagent: "parent-fork", description: "test", prompt: "test" },
+      { threadId: "parent-t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
+    expect(workflowInput.thread).toEqual({
+      mode: "fork",
+      threadId: "parent-t",
+    });
+  });
+
+  it("uses the parent's threadId when continue + newThreadSource 'from-parent' and args.threadId is absent", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const subagent: SubagentConfig = {
+      agentName: "parent-continue",
+      description: "Continues parent thread by default",
+      workflow: mockWorkflow(),
+      thread: "continue",
+      newThreadSource: "from-parent",
+    };
+
+    const { handler } = createSubagentHandler([subagent]);
+
+    await handler(
+      { subagent: "parent-continue", description: "test", prompt: "test" },
+      { threadId: "parent-t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
+    expect(workflowInput.thread).toEqual({
+      mode: "continue",
+      threadId: "parent-t",
+    });
+  });
+
+  it("prefers args.threadId over the parent source when both are available", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const subagent: SubagentConfig = {
+      agentName: "parent-fork-explicit",
+      description: "Forks parent thread by default",
+      workflow: mockWorkflow(),
+      thread: "fork",
+      newThreadSource: "from-parent",
+    };
+
+    const { handler } = createSubagentHandler([subagent]);
+
+    await handler(
+      {
+        subagent: "parent-fork-explicit",
+        description: "test",
+        prompt: "test",
+        threadId: "explicit-prev",
+      },
+      { threadId: "parent-t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
+    expect(workflowInput.thread).toEqual({
+      mode: "fork",
+      threadId: "explicit-prev",
+    });
+  });
+
+  it("ignores newThreadSource 'from-parent' when thread is new", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const subagent: SubagentConfig = {
+      agentName: "new-with-source",
+      description: "Should still start fresh",
+      workflow: mockWorkflow(),
+      newThreadSource: "from-parent",
+    };
+
+    const { handler } = createSubagentHandler([subagent]);
+
+    await handler(
+      { subagent: "new-with-source", description: "test", prompt: "test" },
+      { threadId: "parent-t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
+    expect(workflowInput.thread).toBeUndefined();
+  });
+
+  it("preserves prior behavior when fork is set with default newThreadSource and args.threadId is absent", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const subagent: SubagentConfig = {
+      agentName: "fork-default-source",
+      description: "Fork with default new-thread source",
+      workflow: mockWorkflow(),
+      thread: "fork",
+    };
+
+    const { handler } = createSubagentHandler([subagent]);
+
+    await handler(
+      { subagent: "fork-default-source", description: "test", prompt: "test" },
+      { threadId: "parent-t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
+    expect(workflowInput.thread).toBeUndefined();
+  });
+
   // --- Sandbox continuation ---
 
   it("does not pass sandbox when thread is fork (own sandbox)", async () => {

package/src/lib/subagent/types.ts

@@ -632,6 +632,22 @@ export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
    *   directly to the existing thread in-place.
    */
   thread?: "new" | "fork" | "continue";
+  /**
+   * Where the subagent's thread comes from when the parent's tool call
+   * omits `threadId`. Only meaningful in combination with
+   * `thread: "fork"` or `"continue"`.
+   *
+   * - `"new"` (default) — start a fresh thread (the prior behavior).
+   * - `"from-parent"` — use the parent's own `threadId` (from
+   *   `RouterContext`). With `thread: "fork"` the parent's conversation
+   *   is copied into a new thread; with `thread: "continue"` the
+   *   subagent appends to the parent's thread in-place.
+   *
+   * Has no effect when `thread` is `"new"` (or omitted). A `threadId`
+   * supplied by the parent agent always wins — `newThreadSource` only
+   * applies when none is provided.
+   */
+  newThreadSource?: "new" | "from-parent";
   /**
    * Sandbox strategy for this subagent.
    *

package/src/lib/thread/cold-store.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { createS3ColdStore, type S3LikeClient } from "./cold-store";
+import type { ThreadSnapshot } from "./cold-store";
+
+interface StoredObject {
+  body: Buffer;
+  contentType?: string;
+}
+
+interface CommandInput {
+  Bucket: string;
+  Key: string;
+  Body?: Buffer | string;
+  ContentType?: string;
+}
+
+/**
+ * Minimal S3-shaped fake. `send()` dispatches by command constructor
+ * name; `config` provides the fields `@aws-sdk/lib-storage`'s
+ * single-part upload path inspects.
+ */
+function createFakeS3(): {
+  s3: S3LikeClient;
+  store: Map<string, StoredObject>;
+  calls: { get: number; put: number; delete: number };
+} {
+  const store = new Map<string, StoredObject>();
+  const calls = { get: 0, put: 0, delete: 0 };
+
+  const compositeKey = (bucket: string, key: string): string =>
+    `${bucket}/${key}`;
+
+  const s3 = {
+    config: {
+      requestHandler: undefined,
+      forcePathStyle: false,
+      endpoint: async (): Promise<URL> => new URL("https://fake.s3.local"),
+    },
+    async send<TInput, TOutput>(
+      command: { input: TInput } & object
+    ): Promise<TOutput> {
+      const name = (command as { constructor: { name: string } }).constructor
+        .name;
+      const input = command.input as unknown as CommandInput;
+      const fullKey = compositeKey(input.Bucket, input.Key);
+      if (name === "GetObjectCommand") {
+        calls.get++;
+        const obj = store.get(fullKey);
+        if (!obj) {
+          const err = new Error("NoSuchKey") as Error & { name: string };
+          err.name = "NoSuchKey";
+          throw err;
+        }
+        return { Body: obj.body } as unknown as TOutput;
+      }
+      if (name === "PutObjectCommand") {
+        calls.put++;
+        const body =
+          typeof input.Body === "string"
+            ? Buffer.from(input.Body, "utf8")
+            : (input.Body as Buffer);
+        store.set(fullKey, {
+          body,
+          ...(input.ContentType && { contentType: input.ContentType }),
+        });
+        return {} as TOutput;
+      }
+      if (name === "DeleteObjectCommand") {
+        calls.delete++;
+        store.delete(fullKey);
+        return {} as TOutput;
+      }
+      throw new Error(`unknown command: ${name}`);
+    },
+  } as unknown as S3LikeClient;
+
+  return { s3, store, calls };
+}
+
+const sampleSnapshot: ThreadSnapshot = {
+  v: 1,
+  messages: [JSON.stringify({ id: "m1", text: "hi" })],
+  state: null,
+  dedupIds: ["m1"],
+};
+
+describe("createS3ColdStore", () => {
+  let fake: ReturnType<typeof createFakeS3>;
+
+  beforeEach(() => {
+    fake = createFakeS3();
+  });
+
+  it("read returns null when no object exists for the thread", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    expect(await cold.read("messages", "t-1")).toBeNull();
+  });
+
+  it("write then read round-trips a snapshot (gzip default)", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+      prefix: "prod/threads",
+    });
+    await cold.write("messages", "t-1", sampleSnapshot);
+    expect(await cold.read("messages", "t-1")).toEqual(sampleSnapshot);
+
+    // Verify the on-disk format is gzip + JSON.
+    const stored = fake.store.get("test-bucket/prod/threads/messages/t-1.json.gz");
+    expect(stored).toBeDefined();
+    if (!stored) throw new Error("expected stored object");
+    expect(stored.contentType).toBe("application/gzip");
+    const decoded = JSON.parse(gunzipSync(stored.body).toString("utf8"));
+    expect(decoded).toEqual(sampleSnapshot);
+  });
+
+  it("supports plain JSON when gzip is disabled", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+      gzip: false,
+    });
+    await cold.write("messages", "t-1", sampleSnapshot);
+
+    const stored = fake.store.get("test-bucket/threads/messages/t-1.json");
+    expect(stored).toBeDefined();
+    if (!stored) throw new Error("expected stored object");
+    expect(stored.contentType).toBe("application/json");
+    expect(JSON.parse(stored.body.toString("utf8"))).toEqual(sampleSnapshot);
+
+    expect(await cold.read("messages", "t-1")).toEqual(sampleSnapshot);
+  });
+
+  it("uses 'threads' as the default prefix", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    await cold.write("messages", "abc", sampleSnapshot);
+    expect(fake.store.has("test-bucket/threads/messages/abc.json.gz")).toBe(true);
+  });
+
+  it("delete removes the underlying object", async () => {
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    await cold.write("messages", "t-1", sampleSnapshot);
+    await cold.delete("messages", "t-1");
+    expect(await cold.read("messages", "t-1")).toBeNull();
+    expect(fake.store.size).toBe(0);
+  });
+
+  it("read treats 404 errors as null (not throw)", async () => {
+    const cold = createS3ColdStore({
+      s3: {
+        async send() {
+          const err = {
+            name: "NotFound",
+            $metadata: { httpStatusCode: 404 },
+          };
+          throw err;
+        },
+      } as unknown as S3LikeClient,
+      bucket: "test-bucket",
+    });
+    expect(await cold.read("messages", "t-1")).toBeNull();
+  });
+
+  it("read rethrows non-404 errors", async () => {
+    const cold = createS3ColdStore({
+      s3: {
+        async send() {
+          throw new Error("AccessDenied");
+        },
+      } as unknown as S3LikeClient,
+      bucket: "test-bucket",
+    });
+    await expect(cold.read("messages", "t-1")).rejects.toThrow("AccessDenied");
+  });
+
+  it("falls back to gunzip when the cold object is gzip-encoded but read with gzip:true", async () => {
+    // Pre-seed the fake S3 with a gzip-encoded payload, then read.
+    const compressed = gzipSync(Buffer.from(JSON.stringify(sampleSnapshot)));
+    fake.store.set("test-bucket/threads/messages/t-1.json.gz", {
+      body: compressed,
+    });
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    expect(await cold.read("messages", "t-1")).toEqual(sampleSnapshot);
+  });
+
+  it("round-trips a large payload through the async gzip path", async () => {
+    // ~1 MB payload — regression guard that large payloads still
+    // encode/decode correctly through the promisified gzip path.
+    const big: ThreadSnapshot = {
+      v: 1,
+      messages: Array.from({ length: 500 }, (_, i) =>
+        JSON.stringify({
+          id: `m${i}`,
+          text: "x".repeat(2048),
+        })
+      ),
+      state: null,
+      dedupIds: Array.from({ length: 500 }, (_, i) => `m${i}`),
+    };
+
+    const cold = createS3ColdStore({
+      s3: fake.s3,
+      bucket: "test-bucket",
+    });
+    await cold.write("messages", "big", big);
+    expect(await cold.read("messages", "big")).toEqual(big);
+  });
+});