@sixb/core 0.1.1 → 0.1.3

package/src/storage/agents/in-memory.ts

@@ -1,9 +1,24 @@
 import { AGENT_MESSAGE_CONTENT_VERSION } from "../../agents/message"
 import { principalsEqual } from "../../auth"
+import { normalizeRequesterGroupIds } from "../../auth/attribution"
+import { parseSixbFailure } from "../../errors/internal"
+import type { SixbFailure } from "../../errors/types"
+import type { ExecutionStorage } from "../executions"
 import { AgentStorageError } from "./errors"
+import {
+  agentContextCheckpointMatchesCreateInput,
+  assertAgentContextCheckpointAnchors,
+  assertAgentContextCheckpointAuthority,
+  assertAgentContextCheckpointReplayState,
+  assertAgentRunExecution,
+  assertCreateAgentContextCheckpointInput,
+} from "./provider"
 import type {
+  AgentContextCheckpointRecord,
+  AgentContextCheckpointStore,
   AgentMessageRecord,
   AgentMessageStore,
+  AgentRunFailureCode,
   AgentRunRecord,
   AgentRunStore,
   AgentStorage,
@@ -11,8 +26,10 @@ import type {
   AgentThreadStore,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
+  CreateAgentContextCheckpointInput,
   CreateAgentRunInput,
   CreateAgentThreadInput,
+  DeleteAgentMessagesByRunInput,
   FinishAgentRunInput,
   FinishQueuedAgentRunInput,
   ListAgentMessagesInput,
@@ -24,6 +41,13 @@ import type {
   ReclaimAgentRunInput,
   StartAgentRunInput,
 } from "./types"
+import { AGENT_RUN_FAILURE_CODES } from "./types"
+
+function normalizeFailure(
+  failure: SixbFailure<AgentRunFailureCode> | undefined
+): SixbFailure<AgentRunFailureCode> | undefined {
+  return failure ? parseSixbFailure(failure, AGENT_RUN_FAILURE_CODES) : undefined
+}
 
 function key(projectId: string, id: string): string {
   return `${projectId}:${id}`
@@ -64,21 +88,23 @@ function applyWindow<T>(rows: T[], offset = 0, limit?: number): Window<T> {
 }
 
 /**
- * Shared in-memory state behind the three sub-stores. They are tiered for ergonomics
+ * Shared in-memory state behind the four sub-stores. They are tiered for ergonomics
  * (`storage.runs.create(...)`), but several operations span tables — creating/finishing a run
- * updates the thread anchor, appending a message bumps thread stats — so they all read and write the
- * same maps through this object.
+ * updates the thread anchor, appending a message bumps thread stats, and checkpoint creation reads
+ * run/thread/message anchors — so they all read and write the same maps through this object.
  */
 interface AgentStoreState {
   readonly threads: Map<string, AgentThreadRecord>
   readonly runs: Map<string, AgentRunRecord>
   readonly messages: Map<string, AgentMessageRecord>
+  readonly checkpoints: Map<string, AgentContextCheckpointRecord>
 }
 
 export interface InMemoryAgentStorageSnapshot {
   readonly threads: Map<string, AgentThreadRecord>
   readonly runs: Map<string, AgentRunRecord>
   readonly messages: Map<string, AgentMessageRecord>
+  readonly checkpoints: Map<string, AgentContextCheckpointRecord>
 }
 
 // ── threads ───────────────────────────────────────────────────────────────────────────────────
@@ -149,9 +175,19 @@ class InMemoryAgentThreadStore implements AgentThreadStore {
 // ── runs ──────────────────────────────────────────────────────────────────────────────────────
 
 class InMemoryAgentRunStore implements AgentRunStore {
-  constructor(private readonly state: AgentStoreState) {}
+  constructor(
+    private readonly state: AgentStoreState,
+    private readonly executions: ExecutionStorage
+  ) {}
 
   async create(input: CreateAgentRunInput): Promise<AgentRunRecord> {
+    await assertAgentRunExecution({
+      executions: this.executions,
+      projectId: input.projectId,
+      executionId: input.executionId,
+      runId: input.id,
+      agentId: input.agentId,
+    })
     // No `await` between read and write: the in-memory critical section is atomic, so two concurrent
     // queued runs on the same thread cannot both win — the second observes `activeRunId` set.
     const threadKey = key(input.projectId, input.threadId)
@@ -176,15 +212,26 @@ class InMemoryAgentRunStore implements AgentRunStore {
         `[Sixb] Agent run '${input.id}' already exists for project '${input.projectId}'.`
       )
     }
+    if (
+      [...this.state.runs.values()].some(
+        (run) => run.projectId === input.projectId && run.executionId === input.executionId
+      )
+    ) {
+      throw new AgentStorageError(
+        "duplicate_id",
+        `[Sixb] Execution '${input.executionId}' already belongs to another Agent run.`
+      )
+    }
 
     const createdAt = new Date(input.createdAt ?? new Date())
     const run: AgentRunRecord = {
       id: input.id,
       projectId: input.projectId,
+      executionId: input.executionId,
       threadId: input.threadId,
       agentId: input.agentId,
       triggerMessageId: input.triggerMessageId,
-      requestedByPrincipal: clone(input.requestedByPrincipal),
+      requesterGroupIds: normalizeRequesterGroupIds(input.requesterGroupIds),
       status: "queued",
       attempt: 0,
       createdAt,
@@ -207,9 +254,6 @@ class InMemoryAgentRunStore implements AgentRunStore {
     const next: AgentRunRecord = {
       ...run,
       status: "running",
-      ...(input.executionPrincipal === undefined
-        ? {}
-        : { executionPrincipal: clone(input.executionPrincipal) }),
       ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
       attempt: 1,
       execution: clone(input.execution),
@@ -225,7 +269,7 @@ class InMemoryAgentRunStore implements AgentRunStore {
     const next: AgentRunRecord = {
       ...run,
       status: input.status,
-      ...(input.error === undefined ? {} : { error: input.error }),
+      ...(input.error === undefined ? {} : { error: normalizeFailure(input.error) }),
       completedAt,
     }
     this.state.runs.set(key(input.projectId, input.id), clone(next))
@@ -283,9 +327,10 @@ class InMemoryAgentRunStore implements AgentRunStore {
       status: input.status,
       ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
       ...(input.finishReason === undefined ? {} : { finishReason: input.finishReason }),
-      ...(input.usage === undefined ? {} : { usage: clone(input.usage) }),
       ...(input.diagnostics === undefined ? {} : { diagnostics: clone(input.diagnostics) }),
-      ...(input.status === "succeeded" || input.error === undefined ? {} : { error: input.error }),
+      ...(input.status === "succeeded" || input.error === undefined
+        ? {}
+        : { error: normalizeFailure(input.error) }),
       execution: undefined,
       completedAt,
     }
@@ -434,6 +479,50 @@ class InMemoryAgentMessageStore implements AgentMessageStore {
     return clone(message)
   }
 
+  async deleteByRunId(input: DeleteAgentMessagesByRunInput): Promise<number> {
+    const threadKey = key(input.projectId, input.threadId)
+    const thread = this.state.threads.get(threadKey)
+    if (!thread) {
+      throw new AgentStorageError(
+        "thread_not_found",
+        `[Sixb] Agent thread '${input.threadId}' not found for project '${input.projectId}'.`
+      )
+    }
+
+    const messages = [...this.state.messages.entries()].filter(
+      ([, message]) =>
+        message.projectId === input.projectId &&
+        message.threadId === input.threadId &&
+        message.runId === input.runId
+    )
+    if (messages.length === 0) {
+      return 0
+    }
+
+    for (const [messageKey] of messages) {
+      this.state.messages.delete(messageKey)
+    }
+
+    const remainingMessages = [...this.state.messages.values()]
+      .filter(
+        (message) => message.projectId === input.projectId && message.threadId === input.threadId
+      )
+      .sort((left, right) => right.seq - left.seq)
+    const latestMessage = remainingMessages[0]
+    const updatedAt = new Date()
+    this.state.threads.set(
+      threadKey,
+      clone({
+        ...thread,
+        messageCount: remainingMessages.length,
+        lastMessageAt: latestMessage?.createdAt,
+        updatedAt,
+      })
+    )
+
+    return messages.length
+  }
+
   async getById(params: { projectId: string; id: string }): Promise<AgentMessageRecord | null> {
     const record = this.state.messages.get(key(params.projectId, params.id))
     return record ? clone(record) : null
@@ -446,6 +535,7 @@ class InMemoryAgentMessageStore implements AgentMessageStore {
     const filtered = [...this.state.messages.values()]
       .filter((message) => message.projectId === input.projectId)
       .filter((message) => message.threadId === input.threadId)
+      .filter((message) => (input.afterSeq === undefined ? true : message.seq > input.afterSeq))
       .filter((message) => (roles ? roles.has(message.role) : true))
       .sort((a, b) => (order === "asc" ? a.seq - b.seq : b.seq - a.seq))
 
@@ -464,22 +554,136 @@ class InMemoryAgentMessageStore implements AgentMessageStore {
   }
 }
 
+// ── context checkpoints ──────────────────────────────────────────────────────────────────────
+
+class InMemoryAgentContextCheckpointStore implements AgentContextCheckpointStore {
+  constructor(private readonly state: AgentStoreState) {}
+
+  async create(input: CreateAgentContextCheckpointInput): Promise<AgentContextCheckpointRecord> {
+    assertCreateAgentContextCheckpointInput(input)
+
+    // No `await` between authority checks and append: this is one in-memory critical section.
+    const run = this.state.runs.get(key(input.projectId, input.createdByRunId)) ?? null
+    const thread = this.state.threads.get(key(input.projectId, input.threadId)) ?? null
+    assertAgentContextCheckpointAuthority({ create: input, run, thread })
+
+    const messages = [...this.state.messages.values()].filter(
+      (message) => message.projectId === input.projectId && message.threadId === input.threadId
+    )
+    const headSeq = messages.reduce((head, message) => Math.max(head, message.seq), 0)
+    const latest = this.findLatest(input.projectId, input.threadId)
+
+    const existingForRun = [...this.state.checkpoints.values()].find(
+      (checkpoint) =>
+        checkpoint.projectId === input.projectId &&
+        checkpoint.createdByRunId === input.createdByRunId
+    )
+    if (existingForRun) {
+      if (agentContextCheckpointMatchesCreateInput(existingForRun, input)) {
+        assertAgentContextCheckpointReplayState({
+          create: input,
+          existing: existingForRun,
+          latest,
+          headSeq,
+        })
+        return clone(existingForRun)
+      }
+      throw new AgentStorageError(
+        "invalid_state",
+        `[Sixb] Agent run '${input.createdByRunId}' already created a different context checkpoint.`
+      )
+    }
+
+    if (this.state.checkpoints.has(key(input.projectId, input.id))) {
+      throw new AgentStorageError(
+        "duplicate_id",
+        `[Sixb] Agent context checkpoint '${input.id}' already exists for project '${input.projectId}'.`
+      )
+    }
+
+    const firstRetained =
+      messages
+        .filter((message) => message.seq > input.summarizedThroughSeq)
+        .sort((left, right) => left.seq - right.seq)[0] ?? null
+    assertAgentContextCheckpointAnchors({
+      create: input,
+      latest,
+      headSeq,
+      firstRetained,
+    })
+
+    const record: AgentContextCheckpointRecord = {
+      id: input.id,
+      projectId: input.projectId,
+      threadId: input.threadId,
+      createdByRunId: input.createdByRunId,
+      ...(input.expectedPreviousCheckpointId === null
+        ? {}
+        : { previousCheckpointId: input.expectedPreviousCheckpointId }),
+      reason: input.reason,
+      summary: input.summary,
+      summaryFormatVersion: input.summaryFormatVersion,
+      summarizedThroughSeq: input.summarizedThroughSeq,
+      observedHeadSeq: input.observedHeadSeq,
+      estimatedInputTokensBefore: input.estimatedInputTokensBefore,
+      estimatedInputTokensAfter: input.estimatedInputTokensAfter,
+      summaryModelId: input.summaryModelId,
+      createdAt: new Date(input.createdAt ?? new Date()),
+    }
+    this.state.checkpoints.set(key(input.projectId, input.id), clone(record))
+    return clone(record)
+  }
+
+  async getLatest(input: {
+    readonly projectId: string
+    readonly threadId: string
+  }): Promise<AgentContextCheckpointRecord | null> {
+    const record = this.findLatest(input.projectId, input.threadId)
+    return record ? clone(record) : null
+  }
+
+  private findLatest(projectId: string, threadId: string): AgentContextCheckpointRecord | null {
+    return (
+      [...this.state.checkpoints.values()]
+        .filter(
+          (checkpoint) => checkpoint.projectId === projectId && checkpoint.threadId === threadId
+        )
+        .sort(
+          (left, right) =>
+            right.summarizedThroughSeq - left.summarizedThroughSeq ||
+            right.createdAt.getTime() - left.createdAt.getTime() ||
+            right.id.localeCompare(left.id)
+        )[0] ?? null
+    )
+  }
+}
+
 export class InMemoryAgentStorage implements AgentStorage {
   private readonly state: AgentStoreState = {
     threads: new Map(),
     runs: new Map(),
     messages: new Map(),
+    checkpoints: new Map(),
   }
 
-  readonly threads = new InMemoryAgentThreadStore(this.state)
-  readonly runs = new InMemoryAgentRunStore(this.state)
-  readonly messages = new InMemoryAgentMessageStore(this.state)
+  readonly threads: InMemoryAgentThreadStore
+  readonly runs: InMemoryAgentRunStore
+  readonly messages: InMemoryAgentMessageStore
+  readonly checkpoints: InMemoryAgentContextCheckpointStore
+
+  constructor(executions: ExecutionStorage) {
+    this.threads = new InMemoryAgentThreadStore(this.state)
+    this.runs = new InMemoryAgentRunStore(this.state, executions)
+    this.messages = new InMemoryAgentMessageStore(this.state)
+    this.checkpoints = new InMemoryAgentContextCheckpointStore(this.state)
+  }
 
   snapshot(): InMemoryAgentStorageSnapshot {
     return {
       threads: structuredClone(this.state.threads),
       runs: structuredClone(this.state.runs),
       messages: structuredClone(this.state.messages),
+      checkpoints: structuredClone(this.state.checkpoints),
     }
   }
 
@@ -487,6 +691,7 @@ export class InMemoryAgentStorage implements AgentStorage {
     replace(this.state.threads, snapshot.threads)
     replace(this.state.runs, snapshot.runs)
     replace(this.state.messages, snapshot.messages)
+    replace(this.state.checkpoints, snapshot.checkpoints)
   }
 }
 

package/src/storage/agents/index.ts

@@ -3,6 +3,9 @@ export { AgentStorageError } from "./errors"
 export type { InMemoryAgentStorageSnapshot } from "./in-memory"
 export { InMemoryAgentStorage } from "./in-memory"
 export type {
+  AgentContextCheckpointReason,
+  AgentContextCheckpointRecord,
+  AgentContextCheckpointStore,
   AgentExecutionStatus,
   AgentMessageRecord,
   AgentMessageRole,
@@ -11,19 +14,21 @@ export type {
   AgentRunDiagnosticCode,
   AgentRunDiagnosticSeverity,
   AgentRunExecution,
+  AgentRunFailureCode,
   AgentRunFinishReason,
   AgentRunRecord,
   AgentRunStatus,
   AgentRunStore,
-  AgentRunUsage,
   AgentStorage,
   AgentThreadRecord,
   AgentThreadStatus,
   AgentThreadStore,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
+  CreateAgentContextCheckpointInput,
   CreateAgentRunInput,
   CreateAgentThreadInput,
+  DeleteAgentMessagesByRunInput,
   FinishAgentRunInput,
   FinishQueuedAgentRunInput,
   ListAgentMessagesInput,
@@ -37,6 +42,7 @@ export type {
 } from "./types"
 export {
   AGENT_RUN_DIAGNOSTIC_CODES,
+  AGENT_RUN_FAILURE_CODES,
   AGENT_RUN_FINISH_REASONS,
   coerceAgentRunFinishReason,
 } from "./types"

package/src/storage/agents/provider.ts

@@ -0,0 +1,252 @@
+import { agentServiceAccountId } from "../../agents/authority"
+import type { ExecutionStorage } from "../executions"
+import { findAgentRunExecution } from "../executions/run-link"
+import { AgentStorageError } from "./errors"
+import type {
+  AgentContextCheckpointRecord,
+  AgentMessageRecord,
+  AgentRunRecord,
+  AgentThreadRecord,
+  CreateAgentContextCheckpointInput,
+} from "./types"
+
+/** Validate the semantic link between a conversational Agent run and its immutable execution. */
+export async function assertAgentRunExecution(input: {
+  readonly executions: ExecutionStorage
+  readonly projectId: string
+  readonly executionId: string
+  readonly runId: string
+  readonly agentId: string
+}): Promise<void> {
+  const execution = await findAgentRunExecution({
+    executions: input.executions,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    runId: input.runId,
+    serviceAccountId: agentServiceAccountId(input.agentId),
+  })
+  if (!execution) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[Sixb] Execution '${input.executionId}' does not authorize Agent run '${input.runId}'.`
+    )
+  }
+}
+
+/** Validate provider-independent checkpoint fields before entering a storage critical section. */
+export function assertCreateAgentContextCheckpointInput(
+  input: CreateAgentContextCheckpointInput,
+  prefix = "Sixb"
+): void {
+  for (const [name, value] of [
+    ["id", input.id],
+    ["projectId", input.projectId],
+    ["threadId", input.threadId],
+    ["createdByRunId", input.createdByRunId],
+    ["executionToken", input.executionToken],
+    ["summary", input.summary],
+    ["summaryModelId", input.summaryModelId],
+  ] as const) {
+    if (value.trim().length === 0) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Agent context checkpoint '${name}' must not be empty.`
+      )
+    }
+  }
+
+  if (input.summaryFormatVersion !== 1) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint summary format version must be 1.`
+    )
+  }
+  if (input.reason !== "threshold" && input.reason !== "overflow") {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint reason must be 'threshold' or 'overflow'.`
+    )
+  }
+  if (
+    input.expectedPreviousCheckpointId !== null &&
+    input.expectedPreviousCheckpointId.trim().length === 0
+  ) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint expected previous id must not be empty.`
+    )
+  }
+  if (input.createdAt && !Number.isFinite(input.createdAt.getTime())) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint createdAt must be a valid date.`
+    )
+  }
+
+  for (const [name, value, minimum] of [
+    ["expectedHeadSeq", input.expectedHeadSeq, 1],
+    ["summarizedThroughSeq", input.summarizedThroughSeq, 1],
+    ["observedHeadSeq", input.observedHeadSeq, 1],
+    ["estimatedInputTokensBefore", input.estimatedInputTokensBefore, 0],
+    ["estimatedInputTokensAfter", input.estimatedInputTokensAfter, 0],
+  ] as const) {
+    if (!Number.isSafeInteger(value) || value < minimum) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Agent context checkpoint '${name}' must be a safe integer greater than or equal to ${minimum}.`
+      )
+    }
+  }
+
+  if (input.observedHeadSeq !== input.expectedHeadSeq) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint observed head must equal its expected message head.`
+    )
+  }
+  if (input.summarizedThroughSeq >= input.observedHeadSeq) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint must retain the triggering head message.`
+    )
+  }
+}
+
+/** Assert that the current delivery still owns the active conversational run. */
+export function assertAgentContextCheckpointAuthority(input: {
+  readonly create: CreateAgentContextCheckpointInput
+  readonly run: AgentRunRecord | null
+  readonly thread: AgentThreadRecord | null
+  readonly prefix?: string
+}): asserts input is typeof input & {
+  readonly run: AgentRunRecord
+  readonly thread: AgentThreadRecord
+} {
+  const { create, run, thread } = input
+  const prefix = input.prefix ?? "Sixb"
+  if (!run) {
+    throw new AgentStorageError(
+      "run_not_found",
+      `[${prefix}] Agent run '${create.createdByRunId}' not found for project '${create.projectId}'.`
+    )
+  }
+  if (!thread) {
+    throw new AgentStorageError(
+      "thread_not_found",
+      `[${prefix}] Agent thread '${create.threadId}' not found for project '${create.projectId}'.`
+    )
+  }
+  if (run.threadId !== create.threadId) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent run '${run.id}' does not belong to thread '${create.threadId}'.`
+    )
+  }
+  if (run.status !== "running") {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent run '${run.id}' is not running (status '${run.status}').`
+    )
+  }
+  if (!run.execution || run.execution.token !== create.executionToken) {
+    throw new AgentStorageError(
+      "execution_lost",
+      `[${prefix}] Execution token is no longer current on agent run '${run.id}'.`
+    )
+  }
+  if (thread.activeRunId !== run.id) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent run '${run.id}' no longer owns thread '${thread.id}'.`
+    )
+  }
+}
+
+/** Assert both compare-and-swap anchors and the retained-turn boundary. */
+export function assertAgentContextCheckpointAnchors(input: {
+  readonly create: CreateAgentContextCheckpointInput
+  readonly latest: AgentContextCheckpointRecord | null
+  readonly headSeq: number
+  readonly firstRetained: AgentMessageRecord | null
+  readonly prefix?: string
+}): void {
+  const { create, latest, headSeq, firstRetained } = input
+  const prefix = input.prefix ?? "Sixb"
+  if (headSeq !== create.expectedHeadSeq) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent thread '${create.threadId}' message head changed from ${create.expectedHeadSeq} to ${headSeq}.`
+    )
+  }
+
+  const latestId = latest?.id ?? null
+  if (latestId !== create.expectedPreviousCheckpointId) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent thread '${create.threadId}' checkpoint head changed.`
+    )
+  }
+  if (latest && create.summarizedThroughSeq <= latest.summarizedThroughSeq) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint boundary must advance beyond sequence ${latest.summarizedThroughSeq}.`
+    )
+  }
+  if (!firstRetained || firstRetained.seq !== create.summarizedThroughSeq + 1) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent context checkpoint boundary does not align with stored thread messages.`
+    )
+  }
+  if (firstRetained.role !== "user") {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint must retain a complete turn beginning with a user message.`
+    )
+  }
+}
+
+/** Validate the mutable anchors again before returning an idempotently created checkpoint. */
+export function assertAgentContextCheckpointReplayState(input: {
+  readonly create: CreateAgentContextCheckpointInput
+  readonly existing: AgentContextCheckpointRecord
+  readonly latest: AgentContextCheckpointRecord | null
+  readonly headSeq: number
+  readonly prefix?: string
+}): void {
+  const prefix = input.prefix ?? "Sixb"
+  if (input.headSeq !== input.create.expectedHeadSeq) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent thread '${input.create.threadId}' message head changed from ${input.create.expectedHeadSeq} to ${input.headSeq}.`
+    )
+  }
+  if (input.latest?.id !== input.existing.id) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent thread '${input.create.threadId}' checkpoint head changed after '${input.existing.id}'.`
+    )
+  }
+}
+
+/** Compare the durable semantic payload; delivery token and generated timestamp are not content. */
+export function agentContextCheckpointMatchesCreateInput(
+  record: AgentContextCheckpointRecord,
+  input: CreateAgentContextCheckpointInput
+): boolean {
+  return (
+    record.id === input.id &&
+    record.projectId === input.projectId &&
+    record.threadId === input.threadId &&
+    record.createdByRunId === input.createdByRunId &&
+    (record.previousCheckpointId ?? null) === input.expectedPreviousCheckpointId &&
+    record.reason === input.reason &&
+    record.summary === input.summary &&
+    record.summaryFormatVersion === input.summaryFormatVersion &&
+    record.summarizedThroughSeq === input.summarizedThroughSeq &&
+    record.observedHeadSeq === input.observedHeadSeq &&
+    record.estimatedInputTokensBefore === input.estimatedInputTokensBefore &&
+    record.estimatedInputTokensAfter === input.estimatedInputTokensAfter &&
+    record.summaryModelId === input.summaryModelId
+  )
+}