@sixb/core 0.1.1 → 0.1.3

package/src/testing/agent-storage-contract.ts

@@ -1,18 +1,33 @@
 import { describe, expect, test } from "bun:test"
 import { AGENT_MESSAGE_CONTENT_VERSION } from "../agents/message"
 import type { Principal } from "../auth"
+import type { SixbFailure } from "../errors/types"
 import {
   type AgentRunExecution,
+  type AgentRunFailureCode,
   type AgentStorage,
   AgentStorageError,
   type AgentStorageErrorCode,
+  type CreateAgentContextCheckpointInput,
   type CreateAgentRunInput,
   type CreateAgentThreadInput,
   type StartAgentRunInput,
 } from "../storage/agents"
+import type { AuthStorage } from "../storage/auth"
+import type { ExecutionStorage } from "../storage/executions"
+import type { Storage } from "../storage/types"
+import { createTestAgentExecution } from "./agent-execution"
+
+export interface AgentStorageContractStorage extends Pick<Storage, "transaction"> {
+  readonly agents: AgentStorage
+  readonly auth: AuthStorage
+  readonly executions: ExecutionStorage
+}
 
-export interface AgentStorageContractSuiteOptions<TStorage extends AgentStorage = AgentStorage> {
-  /** Factory that produces a fresh `AgentStorage` instance for each test case. */
+export interface AgentStorageContractSuiteOptions<
+  TStorage extends AgentStorageContractStorage = AgentStorageContractStorage,
+> {
+  /** Factory that produces a fresh storage bundle for each test case. */
   readonly createStorage: () => TStorage | Promise<TStorage>
   /** Optional cleanup invoked after every test case. */
   readonly teardown?: (storage: TStorage) => void | Promise<void>
@@ -26,6 +41,14 @@ const serviceAccount: Extract<Principal, { readonly type: "serviceAccount" }> =
   id: "svc_agent_sales",
 }
 
+function failure(
+  message: string,
+  at: string,
+  code: AgentRunFailureCode = "internal.unexpected"
+): SixbFailure<AgentRunFailureCode> {
+  return { code, message, retryable: false, at }
+}
+
 function at(value: string): Date {
   return new Date(value)
 }
@@ -63,51 +86,139 @@ type TestRunInput = CreateAgentRunInput &
   }
 
 function runInput(overrides: Partial<TestRunInput> = {}): TestRunInput {
-  return {
+  const input = {
     id: "run_1",
     projectId,
     threadId: "thr_1",
     agentId: "sales",
     triggerMessageId: "msg_user_1",
-    requestedByPrincipal: owner,
+    executionId: "test_agent_execution:run_1",
+    requesterGroupIds: ["support", "engineering", "support"],
     execution: execution("exec_1"),
     createdAt: at("2026-06-23T10:00:10.000Z"),
     ...overrides,
   }
+  return {
+    ...input,
+    executionId: overrides.executionId ?? `test_agent_execution:${input.id}`,
+  }
+}
+
+function checkpointInput(
+  overrides: Partial<CreateAgentContextCheckpointInput> = {}
+): CreateAgentContextCheckpointInput {
+  return {
+    id: "checkpoint_1",
+    projectId,
+    threadId: "thr_1",
+    createdByRunId: "run_2",
+    expectedPreviousCheckpointId: null,
+    expectedHeadSeq: 3,
+    executionToken: "exec_2",
+    reason: "threshold",
+    summary: "The user asked for one and the agent answered two.",
+    summaryFormatVersion: 1,
+    summarizedThroughSeq: 2,
+    observedHeadSeq: 3,
+    estimatedInputTokensBefore: 1_000,
+    estimatedInputTokensAfter: 300,
+    summaryModelId: "test-model",
+    createdAt: at("2026-06-23T10:03:00.000Z"),
+    ...overrides,
+  }
 }
 
 async function createAndStartRun(
   storage: AgentStorage,
+  fixture: AgentStorageContractStorage,
   input: TestRunInput
 ): Promise<Awaited<ReturnType<AgentStorage["runs"]["start"]>>> {
-  await storage.runs.create(input)
+  await createRun(storage, fixture, input)
   return storage.runs.start({
     id: input.id,
     projectId: input.projectId,
-    executionPrincipal: input.executionPrincipal,
     modelId: input.modelId,
     execution: input.execution,
     startedAt: input.startedAt,
   })
 }
 
+async function createRun(
+  storage: AgentStorage,
+  fixture: AgentStorageContractStorage,
+  input: CreateAgentRunInput
+) {
+  await createTestAgentExecution(fixture, {
+    projectId: input.projectId,
+    agentId: input.agentId,
+    runId: input.id,
+    executionId: input.executionId,
+  })
+  return storage.runs.create(input)
+}
+
+async function prepareCheckpointCandidate(
+  storage: AgentStorage,
+  fixture: AgentStorageContractStorage
+): Promise<void> {
+  await storage.threads.create(threadInput())
+  await storage.messages.append({
+    id: "m1",
+    projectId,
+    threadId: "thr_1",
+    runId: null,
+    role: "user",
+    parts: [{ type: "text", text: "one" }],
+  })
+  await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
+  await storage.messages.append({
+    id: "m2",
+    projectId,
+    threadId: "thr_1",
+    runId: "run_1",
+    role: "assistant",
+    parts: [{ type: "text", text: "two" }],
+  })
+  await storage.runs.finish({
+    id: "run_1",
+    projectId,
+    executionToken: "exec_1",
+    status: "succeeded",
+  })
+  await storage.messages.append({
+    id: "m3",
+    projectId,
+    threadId: "thr_1",
+    runId: null,
+    role: "user",
+    parts: [{ type: "text", text: "three" }],
+  })
+  await createAndStartRun(
+    storage,
+    fixture,
+    runInput({ id: "run_2", triggerMessageId: "m3", execution: execution("exec_2") })
+  )
+}
+
 /**
  * Runs the shared `AgentStorage` contract against any storage implementation.
  *
  * This is the storage-independent specification for Sixb agent persistence: thread lifecycle and
  * project isolation, single-flight run reservation, execution reclaim, run finalization with
- * execution metadata, and message append with thread-stats bookkeeping.
+ * execution metadata, message append with thread-stats bookkeeping, and fenced context checkpoints.
  */
-export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
+export function runAgentStorageContractSuite<TStorage extends AgentStorageContractStorage>(
   label: string,
   options: AgentStorageContractSuiteOptions<TStorage>
 ): void {
-  const withStorage = async (body: (storage: TStorage) => Promise<void>): Promise<void> => {
-    const storage = await options.createStorage()
+  const withStorage = async (
+    body: (storage: AgentStorage, fixture: TStorage) => Promise<void>
+  ): Promise<void> => {
+    const fixture = await options.createStorage()
     try {
-      await body(storage)
+      await body(fixture.agents, fixture)
     } finally {
-      await options.teardown?.(storage)
+      await options.teardown?.(fixture)
     }
   }
 
@@ -210,10 +321,10 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
     // ── durable queued runs ────────────────────────────────────────────────────────────────────
 
     test("creates a queued run before execution and claims the thread", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
 
-        const queued = await storage.runs.create(runInput({ id: "run_1" }))
+        const queued = await createRun(storage, fixture, runInput({ id: "run_1" }))
         expect(queued).toMatchObject({ status: "queued", attempt: 0, threadId: "thr_1" })
         expect(queued.execution).toBeUndefined()
         expect(queued.startedAt).toBeUndefined()
@@ -230,34 +341,60 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
         const started = await storage.runs.start({
           projectId,
           id: "run_1",
-          executionPrincipal: serviceAccount,
           modelId: "test-model",
           execution: execution("exec_1"),
           startedAt: at("2026-06-23T10:01:00.000Z"),
         })
         expect(started).toMatchObject({ status: "running", attempt: 1, modelId: "test-model" })
         expect(started.execution).toEqual(execution("exec_1"))
-        expect(started.executionPrincipal).toEqual(serviceAccount)
+        expect(started.executionId).toBe("test_agent_execution:run_1")
         expect(started.startedAt?.toISOString()).toBe("2026-06-23T10:01:00.000Z")
       })
     })
 
+    test("rejects a run whose durable execution does not match its Agent authority", async () => {
+      await withStorage(async (storage, fixture) => {
+        await storage.threads.create(threadInput())
+        const executionId = await createTestAgentExecution(fixture, {
+          projectId,
+          agentId: "support",
+          runId: "run_1",
+        })
+
+        await expectAgentError(
+          storage.runs.create(runInput({ id: "run_1", executionId })),
+          "invalid_input"
+        )
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          activeRunId: null,
+        })
+      })
+    })
+
     test("finishes a queued run and releases the thread", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
-        await storage.runs.create(runInput({ id: "run_1" }))
+        await createRun(storage, fixture, runInput({ id: "run_1" }))
 
         const cancelled = await storage.runs.finishQueued({
           projectId,
           id: "run_1",
           status: "cancelled",
-          error: "Cancelled before execution",
+          error: failure(
+            "Cancelled before execution",
+            "2026-06-23T10:01:00.000Z",
+            "runtime.cancelled"
+          ),
           completedAt: at("2026-06-23T10:01:00.000Z"),
         })
         expect(cancelled).toMatchObject({
           status: "cancelled",
           attempt: 0,
-          error: "Cancelled before execution",
+          error: failure(
+            "Cancelled before execution",
+            "2026-06-23T10:01:00.000Z",
+            "runtime.cancelled"
+          ),
         })
         await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
           activeRunId: null,
@@ -271,52 +408,70 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
           "invalid_state"
         )
 
-        await storage.runs.create(runInput({ id: "run_2" }))
+        await createRun(storage, fixture, runInput({ id: "run_2" }))
         await expect(
           storage.runs.finishQueued({
             projectId,
             id: "run_2",
             status: "failed",
-            error: "Agent is unavailable",
+            error: failure("Agent is unavailable", "2026-06-23T10:02:00.000Z"),
+            completedAt: at("2026-06-23T10:02:00.000Z"),
           })
-        ).resolves.toMatchObject({ status: "failed", attempt: 0, error: "Agent is unavailable" })
+        ).resolves.toMatchObject({
+          status: "failed",
+          attempt: 0,
+          error: failure("Agent is unavailable", "2026-06-23T10:02:00.000Z"),
+        })
       })
     })
 
     // ── single-flight execution ─────────────────────────────────────────────────────────────────
 
     test("allows a single active run per thread", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
 
-        const run = await createAndStartRun(storage, runInput({ id: "run_1" }))
+        const run = await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
         expect(run).toMatchObject({ status: "running", attempt: 1, threadId: "thr_1" })
-        expect(run.requestedByPrincipal).toEqual(owner)
+        expect(run.executionId).toBe("test_agent_execution:run_1")
+        expect(run.requesterGroupIds).toEqual(["engineering", "support"])
         expect(run.execution?.token).toBe("exec_1")
         await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
           activeRunId: "run_1",
         })
 
         await expectAgentError(
-          createAndStartRun(storage, runInput({ id: "run_2", execution: execution("exec_2") })),
+          createAndStartRun(
+            storage,
+            fixture,
+            runInput({ id: "run_2", execution: execution("exec_2") })
+          ),
           "active_run_exists"
         )
 
         // Reservation against an unknown thread / duplicate run id.
         await expectAgentError(
-          createAndStartRun(storage, runInput({ id: "run_x", threadId: "ghost" })),
+          createAndStartRun(storage, fixture, runInput({ id: "run_x", threadId: "ghost" })),
           "thread_not_found"
         )
       })
     })
 
     test("never lets two concurrent queued runs both claim one thread", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
 
         const results = await Promise.allSettled([
-          createAndStartRun(storage, runInput({ id: "run_a", execution: execution("exec_a") })),
-          createAndStartRun(storage, runInput({ id: "run_b", execution: execution("exec_b") })),
+          createAndStartRun(
+            storage,
+            fixture,
+            runInput({ id: "run_a", execution: execution("exec_a") })
+          ),
+          createAndStartRun(
+            storage,
+            fixture,
+            runInput({ id: "run_b", execution: execution("exec_b") })
+          ),
         ])
         const fulfilled = results.filter((result) => result.status === "fulfilled")
         const rejected = results.filter(
@@ -332,9 +487,9 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
     // ── execution reclaim ───────────────────────────────────────────────────────────────────────
 
     test("reclaim rotates the execution token and bumps the attempt", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
-        await createAndStartRun(storage, runInput({ id: "run_1" }))
+        await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
 
         const reclaimed = await storage.runs.reclaim({
           projectId,
@@ -357,10 +512,11 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
     })
 
     test("projects confirmed queue ownership monotonically and fences stale executions", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
         await createAndStartRun(
           storage,
+          fixture,
           runInput({
             id: "run_1",
             execution: execution("exec_1", at("2026-06-23T10:02:00.000Z")),
@@ -403,9 +559,9 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
     })
 
     test("does not alias stored run records to callers", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
-        const run = await createAndStartRun(storage, runInput({ id: "run_1" }))
+        const run = await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
 
         const mutableExecution = run.execution as
           | { token: string; queueLeaseExpiresAt: Date }
@@ -414,20 +570,23 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
           mutableExecution.token = "mutated"
           mutableExecution.queueLeaseExpiresAt.setTime(0)
         }
+        ;(run.requesterGroupIds as string[]).push("mutated")
         const reread = await storage.runs.getById({ projectId, id: "run_1" })
         expect(reread?.execution?.token).toBe("exec_1")
+        expect(reread?.requesterGroupIds).toEqual(["engineering", "support"])
       })
     })
 
     // ── finalization ────────────────────────────────────────────────────────────────────────────
 
     test("releasing a run only clears its own thread's active pointer", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput({ id: "thr_1" }))
         await storage.threads.create(threadInput({ id: "thr_2" }))
-        await createAndStartRun(storage, runInput({ id: "run_1", threadId: "thr_1" }))
+        await createAndStartRun(storage, fixture, runInput({ id: "run_1", threadId: "thr_1" }))
         await createAndStartRun(
           storage,
+          fixture,
           runInput({
             id: "run_2",
             threadId: "thr_2",
@@ -453,9 +612,9 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
     })
 
     test("finishes a run, records execution metadata, and releases the thread", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
-        await createAndStartRun(storage, runInput({ id: "run_1" }))
+        await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
 
         const finished = await storage.runs.finish({
           projectId,
@@ -464,7 +623,6 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
           status: "succeeded",
           modelId: "claude-haiku-4-5",
           finishReason: "stop",
-          usage: { inputTokens: 120, outputTokens: 80, totalTokens: 200 },
           diagnostics: [
             {
               code: "output_file_too_large",
@@ -481,7 +639,6 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
           modelId: "claude-haiku-4-5",
           finishReason: "stop",
         })
-        expect(finished.usage).toEqual({ inputTokens: 120, outputTokens: 80, totalTokens: 200 })
         expect(finished.diagnostics).toEqual([
           {
             code: "output_file_too_large",
@@ -502,15 +659,19 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
           activeRunId: null,
         })
         await expect(
-          createAndStartRun(storage, runInput({ id: "run_2", execution: execution("exec_2") }))
+          createAndStartRun(
+            storage,
+            fixture,
+            runInput({ id: "run_2", execution: execution("exec_2") })
+          )
         ).resolves.toMatchObject({ status: "running" })
       })
     })
 
     test("records failure detail and rejects a non-running run or stale execution", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
-        await createAndStartRun(storage, runInput({ id: "run_1" }))
+        await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
 
         await expectAgentError(
           storage.runs.finish({
@@ -518,7 +679,7 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
             id: "run_1",
             executionToken: "wrong",
             status: "failed",
-            error: "boom",
+            error: failure("boom", "2026-06-23T10:08:00.000Z"),
           }),
           "execution_lost"
         )
@@ -528,11 +689,11 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
           id: "run_1",
           executionToken: "exec_1",
           status: "failed",
-          error: "ProviderError: boom",
+          error: failure("ProviderError: boom", "2026-06-23T10:08:00.000Z"),
           completedAt: at("2026-06-23T10:08:00.000Z"),
         })
         expect(failed.status).toBe("failed")
-        expect(failed.error).toBe("ProviderError: boom")
+        expect(failed.error).toEqual(failure("ProviderError: boom", "2026-06-23T10:08:00.000Z"))
 
         // Already terminal → cannot finish again.
         await expectAgentError(
@@ -548,12 +709,13 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
     })
 
     test("lists runs with thread, status, and ordering filters", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput({ id: "thr_1" }))
         await storage.threads.create(threadInput({ id: "thr_2" }))
 
         await createAndStartRun(
           storage,
+          fixture,
           runInput({
             id: "run_1",
             threadId: "thr_1",
@@ -568,6 +730,7 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
         })
         await createAndStartRun(
           storage,
+          fixture,
           runInput({
             id: "run_2",
             threadId: "thr_1",
@@ -577,6 +740,7 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
         )
         await createAndStartRun(
           storage,
+          fixture,
           runInput({
             id: "run_3",
             threadId: "thr_2",
@@ -597,26 +761,32 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
     })
 
     test("filters queued runs by their effective created timestamp", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput({ id: "thr_before" }))
         await storage.threads.create(threadInput({ id: "thr_inside" }))
         await storage.threads.create(threadInput({ id: "thr_after" }))
 
-        await storage.runs.create(
+        await createRun(
+          storage,
+          fixture,
           runInput({
             id: "run_before",
             threadId: "thr_before",
             createdAt: at("2026-06-23T10:00:00.000Z"),
           })
         )
-        await storage.runs.create(
+        await createRun(
+          storage,
+          fixture,
           runInput({
             id: "run_inside",
             threadId: "thr_inside",
             createdAt: at("2026-06-23T11:00:00.000Z"),
           })
         )
-        await storage.runs.create(
+        await createRun(
+          storage,
+          fixture,
           runInput({
             id: "run_after",
             threadId: "thr_after",
@@ -640,7 +810,7 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
     // ── messages ──────────────────────────────────────────────────────────────────────────────
 
     test("appends messages, assigns seq, and bumps thread stats", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
 
         const userMessage = await storage.messages.append({
@@ -661,14 +831,8 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
         })
         expect(userMessage.authorPrincipal).toEqual(owner)
 
-        const run = await createAndStartRun(
-          storage,
-          runInput({
-            id: "run_1",
-            executionPrincipal: serviceAccount,
-          })
-        )
-        expect(run.executionPrincipal).toEqual(serviceAccount)
+        const run = await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
+        expect(run.executionId).toBe("test_agent_execution:run_1")
         const assistantMessage = await storage.messages.append({
           id: "msg_asst_1",
           projectId,
@@ -715,8 +879,64 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
       })
     })
 
+    test("deletes messages produced by a run and repairs thread stats", async () => {
+      await withStorage(async (storage, fixture) => {
+        await storage.threads.create(threadInput())
+        await storage.messages.append({
+          id: "msg_user_1",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text: "Try this" }],
+          createdAt: at("2026-06-23T10:00:30.000Z"),
+        })
+        await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
+        await storage.messages.append({
+          id: "msg_asst_1",
+          projectId,
+          threadId: "thr_1",
+          runId: "run_1",
+          role: "assistant",
+          parts: [
+            { type: "text", text: "Partial answer" },
+            {
+              type: "tool-call",
+              toolCallId: "call_1",
+              toolName: "search",
+              input: { query: "sixb" },
+              state: "output-available",
+              output: { matches: 1 },
+            },
+          ],
+          createdAt: at("2026-06-23T10:01:00.000Z"),
+        })
+
+        await expect(
+          storage.messages.deleteByRunId({ projectId, threadId: "thr_1", runId: "run_1" })
+        ).resolves.toBe(1)
+        await expect(storage.messages.getById({ projectId, id: "msg_asst_1" })).resolves.toBeNull()
+
+        const messages = await storage.messages.list({ projectId, threadId: "thr_1" })
+        expect(messages.messages.map((message) => message.id)).toEqual(["msg_user_1"])
+        expect(messages.total).toBe(1)
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          messageCount: 1,
+          lastMessageAt: at("2026-06-23T10:00:30.000Z"),
+        })
+
+        await expect(
+          storage.messages.deleteByRunId({ projectId, threadId: "thr_1", runId: "run_1" })
+        ).resolves.toBe(0)
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          messageCount: 1,
+          lastMessageAt: at("2026-06-23T10:00:30.000Z"),
+        })
+      })
+    })
+
     test("lists messages with role filter, ordering, and pagination", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (storage, fixture) => {
         await storage.threads.create(threadInput())
         await storage.messages.append({
           id: "m1",
@@ -727,7 +947,7 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
           parts: [{ type: "text", text: "one" }],
           createdAt: at("2026-06-23T10:00:00.000Z"),
         })
-        await createAndStartRun(storage, runInput({ id: "run_1" }))
+        await createAndStartRun(storage, fixture, runInput({ id: "run_1" }))
         await storage.messages.append({
           id: "m2",
           projectId,
@@ -762,6 +982,15 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
         })
         expect(users.messages.map((message) => message.id)).toEqual(["m1", "m3"])
 
+        const retainedTail = await storage.messages.list({
+          projectId,
+          threadId: "thr_1",
+          afterSeq: 1,
+          order: "asc",
+        })
+        expect(retainedTail.messages.map((message) => message.id)).toEqual(["m2", "m3"])
+        expect(retainedTail.total).toBe(2)
+
         const firstPage = await storage.messages.list({
           projectId,
           threadId: "thr_1",
@@ -820,5 +1049,210 @@ export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
         )
       })
     })
+
+    // ── context checkpoints ─────────────────────────────────────────────────────────────────
+
+    test("creates an idempotent checkpoint without mutating the transcript", async () => {
+      await withStorage(async (storage, fixture) => {
+        await prepareCheckpointCandidate(storage, fixture)
+        await storage.threads.create(threadInput({ id: "thr_2" }))
+
+        const threadBefore = await storage.threads.getById({ projectId, id: "thr_1" })
+        const [created, replayed] = await Promise.all([
+          storage.checkpoints.create(checkpointInput()),
+          storage.checkpoints.create(checkpointInput()),
+        ])
+
+        expect(replayed).toEqual(created)
+        expect(created).toMatchObject({
+          id: "checkpoint_1",
+          createdByRunId: "run_2",
+          summarizedThroughSeq: 2,
+          observedHeadSeq: 3,
+        })
+        expect(await storage.checkpoints.getLatest({ projectId, threadId: "thr_1" })).toEqual(
+          created
+        )
+        expect(
+          await storage.checkpoints.getLatest({ projectId: otherProjectId, threadId: "thr_1" })
+        ).toBeNull()
+        expect(await storage.checkpoints.getLatest({ projectId, threadId: "thr_2" })).toBeNull()
+
+        const retained = await storage.messages.list({
+          projectId,
+          threadId: "thr_1",
+          afterSeq: created.summarizedThroughSeq,
+          order: "asc",
+        })
+        expect(retained.messages.map((message) => message.id)).toEqual(["m3"])
+
+        const complete = await storage.messages.list({
+          projectId,
+          threadId: "thr_1",
+          order: "asc",
+        })
+        expect(complete.messages.map((message) => message.id)).toEqual(["m1", "m2", "m3"])
+        expect(await storage.threads.getById({ projectId, id: "thr_1" })).toEqual(threadBefore)
+      })
+    })
+
+    test("rejects checkpoints from an inactive run or a different thread", async () => {
+      await withStorage(async (storage, fixture) => {
+        await prepareCheckpointCandidate(storage, fixture)
+        await storage.threads.create(threadInput({ id: "thr_2" }))
+
+        await expectAgentError(
+          storage.checkpoints.create(checkpointInput({ threadId: "thr_2" })),
+          "invalid_input"
+        )
+
+        await storage.runs.finish({
+          id: "run_2",
+          projectId,
+          executionToken: "exec_2",
+          status: "failed",
+        })
+        await expectAgentError(storage.checkpoints.create(checkpointInput()), "invalid_state")
+        expect(await storage.checkpoints.getLatest({ projectId, threadId: "thr_1" })).toBeNull()
+      })
+    })
+
+    test("rolls back a checkpoint with its containing storage transaction", async () => {
+      await withStorage(async (storage, fixture) => {
+        await prepareCheckpointCandidate(storage, fixture)
+        const rollback = new Error("rollback checkpoint")
+
+        await expect(
+          fixture.transaction(async (tx) => {
+            if (!tx.agents) throw new Error("Expected agent storage in transaction.")
+            const created = await tx.agents.checkpoints.create(checkpointInput())
+            expect(await tx.agents.checkpoints.getLatest({ projectId, threadId: "thr_1" })).toEqual(
+              created
+            )
+            throw rollback
+          })
+        ).rejects.toBe(rollback)
+
+        expect(await storage.checkpoints.getLatest({ projectId, threadId: "thr_1" })).toBeNull()
+      })
+    })
+
+    test("fences checkpoint creation by execution, message head, and prior checkpoint", async () => {
+      await withStorage(async (storage, fixture) => {
+        await prepareCheckpointCandidate(storage, fixture)
+
+        await expectAgentError(
+          storage.checkpoints.create(checkpointInput({ executionToken: "stale" })),
+          "execution_lost"
+        )
+        await expectAgentError(
+          storage.checkpoints.create(
+            checkpointInput({ expectedHeadSeq: 2, observedHeadSeq: 2, summarizedThroughSeq: 1 })
+          ),
+          "invalid_state"
+        )
+        await expectAgentError(
+          storage.checkpoints.create(
+            checkpointInput({ expectedPreviousCheckpointId: "checkpoint_missing" })
+          ),
+          "invalid_state"
+        )
+        await expectAgentError(
+          storage.checkpoints.create(checkpointInput({ summarizedThroughSeq: 1 })),
+          "invalid_input"
+        )
+
+        await storage.runs.reclaim({
+          id: "run_2",
+          projectId,
+          execution: execution("exec_2_reclaimed"),
+        })
+        await expectAgentError(storage.checkpoints.create(checkpointInput()), "execution_lost")
+
+        const reclaimedInput = checkpointInput({ executionToken: "exec_2_reclaimed" })
+        await storage.checkpoints.create(reclaimedInput)
+        await expectAgentError(
+          storage.checkpoints.create({ ...reclaimedInput, summary: "different" }),
+          "invalid_state"
+        )
+        await expectAgentError(storage.checkpoints.create(checkpointInput()), "execution_lost")
+        await storage.messages.append({
+          id: "m4",
+          projectId,
+          threadId: "thr_1",
+          runId: "run_2",
+          role: "assistant",
+          parts: [{ type: "text", text: "four" }],
+        })
+        await expectAgentError(storage.checkpoints.create(reclaimedInput), "invalid_state")
+      })
+    })
+
+    test("chains checkpoints only when the retained boundary advances", async () => {
+      await withStorage(async (storage, fixture) => {
+        await prepareCheckpointCandidate(storage, fixture)
+        await storage.checkpoints.create(checkpointInput())
+        await storage.messages.append({
+          id: "m4",
+          projectId,
+          threadId: "thr_1",
+          runId: "run_2",
+          role: "assistant",
+          parts: [{ type: "text", text: "four" }],
+        })
+        await storage.runs.finish({
+          id: "run_2",
+          projectId,
+          executionToken: "exec_2",
+          status: "succeeded",
+        })
+        await storage.messages.append({
+          id: "m5",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text: "five" }],
+        })
+        await createAndStartRun(
+          storage,
+          fixture,
+          runInput({ id: "run_3", triggerMessageId: "m5", execution: execution("exec_3") })
+        )
+
+        await expectAgentError(
+          storage.checkpoints.create(
+            checkpointInput({
+              id: "checkpoint_2",
+              createdByRunId: "run_3",
+              expectedPreviousCheckpointId: "checkpoint_1",
+              expectedHeadSeq: 5,
+              executionToken: "exec_3",
+              summarizedThroughSeq: 2,
+              observedHeadSeq: 5,
+            })
+          ),
+          "invalid_input"
+        )
+
+        const second = await storage.checkpoints.create(
+          checkpointInput({
+            id: "checkpoint_2",
+            createdByRunId: "run_3",
+            expectedPreviousCheckpointId: "checkpoint_1",
+            expectedHeadSeq: 5,
+            executionToken: "exec_3",
+            summary: "The prior summary was extended through the fourth message.",
+            summarizedThroughSeq: 4,
+            observedHeadSeq: 5,
+            createdAt: at("2026-06-23T10:05:00.000Z"),
+          })
+        )
+        expect(second.previousCheckpointId).toBe("checkpoint_1")
+        expect(await storage.checkpoints.getLatest({ projectId, threadId: "thr_1" })).toEqual(
+          second
+        )
+      })
+    })
   })
 }