Stores

---
name: ai-persistence/stores
description: >
  Implement the MessageStore, RunStore, InterruptStore, MetadataStore contracts
  for @tanstack/ai-persistence against any database. defineAIPersistence,
  composePersistence overrides, critical invariants (full-replace saveThread,
  insert-if-absent createOrResume and interrupt create), authorize thread
  access, runPersistenceConformance testkit. Use whenever you need server
  persistence — the package ships contracts, not a backend for your database.
type: sub-skill
library: tanstack-ai
library_version: '0.0.0'
sources:
  - 'TanStack/ai:docs/persistence/store-reference.md'
  - 'TanStack/ai:docs/persistence/controls.md'
  - 'TanStack/ai:packages/ai-persistence/src/types.ts'
---

# Persistence Stores

> Builds on **ai-persistence** and **ai-persistence/server**.

`@tanstack/ai-persistence` ships **contracts**, not a backend for your
database. An adapter is an object with a `stores` map; implement the stores you
need against whatever you already run and hand the result to
`withPersistence`. The core never inspects your tables, so the schema is yours.

Use `memoryPersistence()` for dev and tests. Everything durable is an adapter
you write. This skill is the contract reference; the per-stack recipes that
write a `chat-persistence.ts` into an app are
`ai-persistence/build-{drizzle,prisma,cloudflare,custom}-adapter`, and
a complete `node:sqlite` implementation lives in
`examples/ts-react-chat/src/lib/sqlite-persistence.ts`.

## Choose a shape

```ts
import { defineAIPersistence } from '@tanstack/ai-persistence'
import type { ChatWithInterruptsPersistence } from '@tanstack/ai-persistence'

// Sparse is fine — only implement what you need.
export const persistence: ChatWithInterruptsPersistence = defineAIPersistence({
  stores: {
    messages, // required for withPersistence / reconstructChat
    runs, // required if you have interrupts
    interrupts,
    // metadata optional
  },
})
```

| Shape                           | Contents                                         |
| ------------------------------- | ------------------------------------------------ |
| `ChatTranscriptPersistence`     | `messages` (+ optional runs/interrupts/metadata) |
| `ChatWithInterruptsPersistence` | `messages` + `runs` + `interrupts`               |
| `ChatPersistence`               | all four chat stores                             |

`defineAIPersistence` preserves exact keys and rejects unknown keys at runtime.

**Annotate your factory with a named shape.** Bare `AIPersistence` is the
all-optional sparse bag, so `withPersistence` and `reconstructChat` reject it
(`stores.messages` is possibly `undefined`). This is the single most common
mistake when writing an adapter.

**`stores` accepts exactly four keys** — `messages`, `runs`, `interrupts`,
`metadata`. Anything else (notably `locks` or sandbox instance maps) throws
`Unknown AIPersistence store key` at runtime and fails to type-check. Locks:
**ai-core/locks** / `@tanstack/ai/locks`. Sandbox instance resume:
`@tanstack/ai-sandbox`.

## Contracts and invariants

### `MessageStore`

```ts
interface MessageStore {
  loadThread(threadId: string): Promise<Array<ModelMessage>>
  saveThread(threadId: string, messages: Array<ModelMessage>): Promise<void>
}
```

- `loadThread` → `[]` for unknown threads (never `null`).
- `saveThread` is a **full overwrite**, not append. A one-message payload wipes history.

### `RunStore`

`RunStatus`, `TerminalRunStatus`, `RunRecord`, `RunStore`, `defineRunStore`, and
`isTerminalRunStatus` are defined in `@tanstack/ai` and re-exported from
`@tanstack/ai-persistence`. Import those from either; the recipes in this skill
import from `@tanstack/ai-persistence` so an adapter author needs only one
package name.

**`RunError` is the exception — it is NOT re-exported.** Import it from
`@tanstack/ai` directly (`import type { RunError } from '@tanstack/ai'`); the
`@tanstack/ai-persistence` barrel has no such export and the import fails to
resolve.

Four methods are required (`createOrResume` / `update` / `get` /
`findActiveRun`). Two are optional: implement only the ones your backend needs,
and leave the rest off the object entirely (not `undefined`, just absent). A
four-method `RunStore` is a fully valid backend.

`withPersistence` itself calls **none** of the three non-`createOrResume`/`update`
query methods, so leaving both optional ones off costs nothing in the middleware.
Their consumers are elsewhere, and each absence disables exactly one feature:

| method            | consumer                                                  | absent ⇒                                                                 |
| ----------------- | --------------------------------------------------------- | ------------------------------------------------------------------------ |
| `findActiveRun`   | `reconstruct.ts` (`stores.runs?.findActiveRun(threadId)`) | required — cannot be absent; stubbing it to `null` silently kills rejoin |
| `listReclaimable` | `reapDetachedRuns` in `@tanstack/ai-sandbox`              | the store cannot be reaped at all                                        |
| `listByThread`    | application code — nothing in the framework calls it      | nothing framework-side breaks                                            |

Consumers of the two OPTIONAL methods feature-detect with `store.method?.(...)`
and degrade rather than throwing. `findActiveRun` is required, so nothing
feature-detects it.

The conformance testkit does not feature-detect. An optional method that is
missing and not declared in `skipMethods` fails the suite, so an omission is
always a choice you made on purpose rather than a check that quietly did not
run. Declare yours and the suite reports them as skipped with a reason:

```ts
// The shipped sqlite example implements findActiveRun and listReclaimable and
// declares only the one it omits.
runPersistenceConformance('sqlite', () => persistence, {
  skipMethods: ['runs.listByThread'],
})
```

```ts
interface RunStore {
  // Required
  createOrResume(
    input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {
      status?: RunStatus
    },
  ): Promise<RunRecord>
  update(
    runId: string,
    patch: Partial<
      Pick<
        RunRecord,
        | 'status'
        | 'finishedAt'
        | 'error'
        | 'usage'
        | 'sandboxKey'
        | 'detachedSince'
        | 'cancelRequested'
        | 'driverEpoch'
      >
    >,
  ): Promise<void>
  get(runId: string): Promise<RunRecord | null>
  findActiveRun(threadId: string): Promise<RunRecord | null>

  // Optional
  listByThread?(threadId: string): Promise<Array<RunRecord>>
  listReclaimable?(opts: {
    now: number
    ttlMs: number
  }): Promise<Array<RunRecord>>
}
```

`RunStatus` is `'running' | 'interrupted' | 'completed' | 'failed' | 'aborted'`.
`'interrupted'` is a human-in-the-loop pause, not terminal: it is what
interrupt-resume continues from, and must never be conflated with `'aborted'`
(an explicit cancellation). `TerminalRunStatus` narrows to
`'completed' | 'failed' | 'aborted'`. `isTerminalRunStatus(status)` is a type
predicate: `(status: RunStatus) => status is TerminalRunStatus`, so calling it
inside a guard narrows `status` to `TerminalRunStatus` for the rest of that
branch, with no cast needed.

`RunRecord.usage` is optional. `withPersistence` sums reported numeric fields
across provider calls for that `runId`, while opaque `providerUsageDetails`
retains the latest reported bag. Known usage is persisted on interruption and
every terminal status.

`RunRecord.error` is a structured `RunError`, not a bare string:

```ts
interface RunError {
  message: string
  code?: string
}
```

`message` is the provider's prose (it changes between model versions and
cannot be branched on); `code` is the stable, machine-branchable
classification a consumer switches over to retry, escalate, or show specific
UI. Store both, and omit `code` from a mapped record when its column is
`null` rather than writing `code: undefined` (`...(row.errorCode != null ? { code: row.errorCode } : {})`).

`defineRunStore<const T extends RunStore>(store: T): T` returns the passed
object's own type, so an optional method your store implements (say,
`listByThread`) stays known-present on the returned value instead of widening
back to `RunStore`'s `| undefined`. You get autocomplete and contract checking
without a separate `: RunStore` annotation, and without a feature-detection
guard on your own return value.

#### The durable-agent-runs fields: `sandboxKey`, `detachedSince`, `cancelRequested`, `driverEpoch`

These four `RunRecord` fields exist for the sandbox/durable-run layer to
reattach a run a client disconnected from, and for out-of-band cancellation.
A `RunStore` you write must round-trip all four through `update` → `get`, even
if your app does not use sandboxes yet — the conformance testkit checks this
unconditionally (it is not behind `skipMethods`, because `update`/`get` are
REQUIRED methods).

- **`sandboxKey`** — compound key identifying the sandbox this run is bound
  to, so a reclaimer can find it to tear down.
- **`detachedSince`** — epoch ms when the last viewer detached; absent while
  someone is attached. Read by `listReclaimable`.
- **`cancelRequested`** — set by an explicit out-of-band cancel (see below),
  distinct from a mere disconnect.
- **`driverEpoch`** — monotonic fencing token, bumped by each host that
  claims the run, so a superseded host can discover it lost by comparing the
  stored value against the one it holds.

**Fresh-run reads must be `undefined`, not a coerced falsy default.** A
backend that reads a `NULL`/absent column back as `cancelRequested: false` or
`driverEpoch: 0` is claiming knowledge it does not have ("explicitly not
cancelled") — that is a different fact from "never set". Omit the field from
the mapped record instead
(`...(row.cancel_requested != null ? { cancelRequested: row.cancel_requested !== 0 } : {})`).

**`update` must use `'field' in patch`, not `patch.field !== undefined`, for
these four.** A caller clears `detachedSince` on reattach by passing it
explicitly as `undefined` — `store.update(runId, { detachedSince: undefined })`
— and that must write `NULL`, not be filtered out of the write. Checking
`!== undefined` cannot tell "clear this field" apart from "I didn't mention
this field", so it silently drops the clear and the run looks permanently
detached to the reaper forever after. `'detachedSince' in patch` is `true` for
an explicit `undefined` and `false` when the caller omitted the key entirely —
that is the distinction you need. The same applies to `cancelRequested`
(`false` is a real, meaningful value, not "unset") and to `sandboxKey` /
`driverEpoch`. See `examples/ts-react-chat/src/lib/sqlite-persistence.ts` for
a worked implementation of exactly this pattern.

#### Out-of-band cancellation

Cancel intent is **never inferred from a disconnect** — a user pressing Stop
and a user closing the tab produce an identical connection close, so the two
are indistinguishable from the abort alone. `@tanstack/ai` exports the actual
primitives:

- **`requestRunCancel`** — records durable cancel intent (writes
  `cancelRequested: true` through a `RunStore`), for a run being driven on a
  host other than the one handling the cancel request.
- **`wasCancelRequested`** — reads that intent back.
- **`RUN_CANCEL_REASON`** — the well-known abort reason string used for the
  in-process case (the same host aborting its own signal), paired with
  `isCancelRequestedReason` to check for it.

A `RunStore` you write does not call these directly — they operate on your
store through `update`/`get` — but `cancelRequested` must round-trip
faithfully (previous section) for the durable path to work at all.

- **`createOrResume`** (required): if `runId` exists, return it **unchanged**,
  including its stored `usage`, and ignore the passed `threadId` / `startedAt` /
  `status`. Resuming a run does not reset `startedAt` or overwrite its current
  status. Idempotent retries and double-submit depend on this. `status` defaults
  to `'running'` on first creation.
- **`update`** (required): missing `runId` is a **no-op** (do not throw, do not
  insert).
- **`get`** (required): current record, or `null` when unknown.
- **`listByThread`** (optional): every run for `threadId`, ascending by
  `startedAt`. Only needed to render a thread's past agent activity.
- **`listReclaimable`** (optional): runs where `status === 'running'` AND
  `detachedSince` is set AND `detachedSince <= now - ttlMs`. The cutoff is
  inclusive: a run detached exactly at the cutoff qualifies. This is a query, not
  automatic behavior — the consumer is `reapDetachedRuns` from
  `@tanstack/ai-sandbox`, which the application schedules itself (cron, queue,
  `alarm()`, `waitUntil`), so returning this list has no side effect until that
  sweep runs. `detachedSince` is written for you by `withSandbox`'s detach path
  (alongside `sandboxKey`) and cleared by the takeover path; drop either field and
  nothing can reclaim the sandbox. `cancelRequested` is written by
  `requestRunCancel` and read by `wasCancelRequested`, and the reaper's expiry
  path goes through `requestRunCancel` to stop a run past its TTL.
- **`findActiveRun`** (**required**): the most recent `'running'` run for
  `threadId` (max `startedAt`), or `null` if none is active. Enables reconnect
  from a stable thread id without a client-held run id. Stub it out and
  reconnect silently stops working — `null` is also the correct answer for an
  idle thread, so nothing can detect the difference. It was optional for exactly
  one release cycle and cost precisely that, which is why it is required now.

Capability tiers belong at the STORE level (omit `runs` entirely and declare
`ChatTranscriptStores`), not the method level — never ship a `RunStore` with a
stubbed method. The two list queries above are the only method-level options,
and each must be declared via `skipMethods` when absent.

### `InterruptStore`

```ts
interface InterruptStore {
  create(record: Omit<InterruptRecord, 'status' | 'resolvedAt'>): Promise<void>
  resolve(interruptId: string, response?: unknown): Promise<void>
  cancel(interruptId: string): Promise<void>
  get(interruptId: string): Promise<InterruptRecord | null>
  list(threadId: string): Promise<Array<InterruptRecord>>
  listPending(threadId: string): Promise<Array<InterruptRecord>>
  listByRun(runId: string): Promise<Array<InterruptRecord>>
  listPendingByRun(runId: string): Promise<Array<InterruptRecord>>
}
```

- `create` always births `'pending'`; **insert-if-absent** on `interruptId`
  (never clobber resolved back to pending).
- All `list*` ordered by `requestedAt` ascending.
- Requires a `runs` store when used with chat persistence.

### `MetadataStore`

```ts
interface MetadataStore {
  get(namespace: string, key: string): Promise<unknown | null>
  set(namespace: string, key: string, value: unknown): Promise<void>
  delete(namespace: string, key: string): Promise<void>
}
```

- The first argument is an **app-defined namespace string**, not the `Scope`
  identity type — despite SQL backends conventionally naming the column
  `scope`.
- Identity is **two fields** `(namespace, key)` — do not join with `:`
  (`('a:b','c')` and `('a','b:c')` must stay distinct).
- Stored `null` is type-indistinguishable from absence; wrap if you must
  persist real null (`{ value: null }`).
- SQL backends usually reject nullish `set` (NOT NULL JSON columns) with a
  clear `TypeError` — match that or document your semantics.

## Timestamp convention

Store _records_ (`RunRecord`, `InterruptRecord`) speak **epoch milliseconds**
(`number`). Wire/result references that leave the persistence layer speak
**ISO-8601 strings**; the middleware converts at the boundary. Do not mix the
two on one field.

## Minimal message store example

Type each store with its `define*Store` helper (`defineMessageStore`,
`defineRunStore`, `defineInterruptStore`, `defineMetadataStore`): pass the object
literal and get autocomplete + contract checking inline, with no `: MessageStore`
annotation. The result composes into `defineAIPersistence` with exact presence.

```ts
import { defineMessageStore } from '@tanstack/ai-persistence'
import type { ModelMessage } from '@tanstack/ai'

const threads = new Map<string, Array<ModelMessage>>()

export const messages = defineMessageStore({
  async loadThread(threadId) {
    return [...(threads.get(threadId) ?? [])]
  },
  async saveThread(threadId, next) {
    threads.set(threadId, [...next])
  },
})
```

For durable DBs, preserve the same semantics with upserts / full-row replace.

## Adopt part of it

You rarely need all four stores in the same system. Implement the ones you own
and fill the rest from another base with `composePersistence`:

```ts
import { composePersistence, memoryPersistence } from '@tanstack/ai-persistence'
import { messages, runs } from './my-postgres-stores'

export const persistence = composePersistence(memoryPersistence(), {
  overrides: { messages, runs },
})
```

Only listed keys move; others stay on the base. Pass `false` to drop a store.
There is **no cross-store transaction** — if `messages` lives in Postgres and
`interrupts` in Redis, a write touching both is two writes. The store
invariants (idempotent `createOrResume`, insert-if-absent `create`) are exactly
what make those retries safe.

`composePersistence` accepts the four state keys. Locks and sandbox instance
maps are not composable here.

## Map onto an existing schema

- **Your column names, your types.** Name columns anything; use `jsonb`,
  `timestamptz`, whatever — convert in the row mapper. The record shape the
  methods return is fixed; how you store it is not.
- **Extra columns are fine.** Add `user_id`, audit columns, a tenant id. Keep
  them nullable or defaulted so the store's inserts still succeed. The stores
  never read or write columns they do not know about.
- **Omit absent optionals** in row mappers (`...(row.error != null ? { error: row.error } : {})`)
  so records compare cleanly.

## Authorization

Store methods take bare `threadId`s. **Authorize at the route** before
`loadThread` / `saveThread` / `reconstructChat({ authorize })`. Derive user
identity from session, not the client body alone.

## Conformance tests (required)

```ts
import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
import { myPersistence } from '../src/persistence'

runPersistenceConformance('my-backend', () => myPersistence())

// Declare intentional omissions. The suite covers all seven stores, so a
// chat-only backend skips the generation half:
// runPersistenceConformance('chat-only', () => p, {
//   skip: ['generationRuns', 'artifacts', 'blobs'],
// })
// `skip` never accepts 'locks' — locks are not a store.

// Declare an intentionally-unimplemented OPTIONAL RunStore method with
// skipMethods, so vitest reports it as a real SKIPPED case:
// runPersistenceConformance('my-backend', () => myPersistence(), {
//   skipMethods: ['runs.listByThread', 'runs.listReclaimable'],
// })
```

The testkit is the compatibility gate: round-trips, rich message shapes,
empty-thread `[]`, `createOrResume` idempotency, interrupt insert-if-absent,
list ordering, composite-key non-aliasing. A missing store that is not listed
in `skip` fails loudly.

`skip` accepts only `'messages' | 'runs' | 'interrupts' | 'metadata'`. **Do not
pass `'locks'`** — it is not a state store and the suite does not cover it.

**`skipMethods` (declare-or-fail for optional `RunStore` methods).** A backend
that omits an OPTIONAL `RunStore` method (`listByThread`, `listReclaimable` —
`findActiveRun` is required and cannot be declared away) must declare it in
`skipMethods` as `'runs.<method>'`, e.g.
`skipMethods: ['runs.listByThread', 'runs.listReclaimable']`. An omitted
method that is NOT declared throws with an actionable message instead of
silently reporting a pass; a declared one is reported as a SKIPPED vitest
case, never as a pass. A case that did not run must never be
indistinguishable from one that did. See
`examples/ts-react-chat/src/lib/sqlite-persistence.test.ts` for a worked
example: it declares `skipMethods: ['runs.listByThread']` only, keeping both
`findActiveRun` and `listReclaimable` under test.

Reference implementation: `memoryPersistence()` in `@tanstack/ai-persistence`.

## Common mistakes

### CRITICAL: Append-only `saveThread`

Breaks the authoritative-history contract.

### CRITICAL: `createOrResume` overwriting existing runs

Breaks safe resume / double-submit.

### CRITICAL: Interrupt `create` upserting to pending

Can resurrect a resolved approval.

### HIGH: Returning bare `AIPersistence` from the factory

`withPersistence` rejects it. Annotate a named shape.

### HIGH: `list*` without stable `requestedAt` order

Middleware and tests assume ascending order.

### HIGH: Skipping the testkit

Silent semantic drift shows up as stuck approvals or wiped history in prod.

### HIGH: `listReclaimable` cutoff off by one

The cutoff is inclusive (`detachedSince <= now - ttlMs`). Using a strict `<`
drops runs detached exactly at the boundary.

### HIGH: Treating `listReclaimable` as automatic reclamation

It is a query a caller runs, not something the package acts on by itself.
Nothing reaps a returned run for you.

## Cross-references

- **ai-persistence/server** — when middleware calls each store
- **ai-persistence/build-drizzle-adapter** / **-prisma-** / **-cloudflare-** / **-custom-** — per-stack recipes
- **ai-core/locks** — not a state store