@tanstack/ai 0.42.0 → 0.43.0

package/skills/ai-core/chat-experience/SKILL.md

@@ -9,13 +9,15 @@ description: >
   NOT Vercel AI SDK — uses chat() not streamText().
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/getting-started/quick-start.md'
   - 'TanStack/ai:docs/chat/streaming.md'
   - 'TanStack/ai:docs/chat/connection-adapters.md'
   - 'TanStack/ai:docs/chat/thinking-content.md'
   - 'TanStack/ai:docs/advanced/multimodal-content.md'
+  - 'TanStack/ai:docs/resumable-streams/overview.md'
+  - 'TanStack/ai:docs/persistence/client-persistence.md'
 ---
 
 # Chat Experience
@@ -41,7 +43,7 @@ export const Route = createFileRoute('/api/chat')({
         const { messages } = body
 
         const stream = chat({
-          adapter: openaiText('gpt-5.2'),
+          adapter: openaiText('gpt-5.5'),
           messages,
           systemPrompts: ['You are a helpful assistant.'],
           abortController,
@@ -148,6 +150,16 @@ const stream = chat({
 return toServerSentEventsResponse(stream, { abortController })
 ```
 
+To make the SSE response resumable (reconnect after a drop/refresh without
+re-running the provider), pass a delivery-durability adapter:
+`toServerSentEventsResponse(stream, { durability: { adapter: memoryStream(request) } })`
+(`memoryStream` from `@tanstack/ai` is process-local, for dev/tests) or
+`durableStream(request, { server })` from `@tanstack/ai-durable-stream`
+(Durable Streams protocol, production). Each SSE event gets an opaque
+adapter-owned `id:`; `fetchServerSentEvents` auto-reconnects with
+`Last-Event-ID` and exposes `joinRun(runId)` to replay a run from the start.
+See `docs/resumable-streams/overview.md`.
+
 **Client:**
 
 ```typescript
@@ -317,7 +329,7 @@ import { chat, toHttpResponse } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 
 const stream = chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   abortController,
 })
@@ -338,6 +350,13 @@ const { messages, sendMessage } = useChat({
 The only difference is swapping `toServerSentEventsResponse` / `fetchServerSentEvents`
 for `toHttpResponse` / `fetchHttpStream`. Everything else stays identical.
 
+This includes resumability: pass the same `durability` adapter to
+`toHttpResponse(stream, { durability: { adapter: memoryStream(request) } })` and
+each NDJSON line becomes an `{ id, chunk }` envelope. `fetchHttpStream`
+auto-reconnects with `Last-Event-ID`, de-dupes the replayed prefix, and exposes
+`joinRun(runId)` — the same guarantees as resumable SSE. The XHR adapters
+(`xhrServerSentEvents` / `xhrHttpStream`) are resumable too.
+
 ### 6. MCP Tool Discovery via `chat({ mcp })`
 
 Pass `mcp` to let `chat()` own discovery **and** lifecycle for one or more MCP
@@ -467,6 +486,73 @@ to `sendMessage`:
 sendMessage('Never mind, do this instead', { whenBusy: 'interrupt' })
 ```
 
+### 8. Browser-Refresh Durability (client persistence)
+
+By default a `ChatClient` / `useChat` keeps messages in memory only, so a full
+page reload loses the conversation. The optional `persistence` option (a
+`ChatClientPersistence` adapter) fixes this from the client side: it stores one
+combined record — `{ messages, resume? }` (`ChatPersistedState`) — per chat `id`,
+so a reload restores the transcript **and** rehydrates any pending interrupt /
+rejoins a run that was still streaming. No manual `initialMessages` + `onFinish`
+boilerplate.
+
+Three storage adapters ship from `@tanstack/ai-client`:
+`localStoragePersistence` (survives reloads and browser restarts),
+`sessionStoragePersistence` (scoped to the tab), and `indexedDBPersistence`
+(async, structured-clone storage — no codec needed for `Date`/`Map`/etc.).
+Give the chat a stable `threadId` so the reload finds the same record.
+Persistence keys on `threadId`; the storage adapters are re-exported from each
+framework package, so a single import works:
+
+```typescript
+import {
+  useChat,
+  fetchServerSentEvents,
+  localStoragePersistence,
+} from '@tanstack/ai-react'
+
+// Defaults to the ChatPersistedState shape and a JSON codec, so no type
+// argument or serialize/deserialize is needed. indexedDBPersistence stores via
+// structured clone (a Date round-trips exactly).
+const persistence = localStoragePersistence()
+
+function Chat() {
+  const { messages, sendMessage } = useChat({
+    threadId: 'support-chat',
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence,
+  })
+  // ...render messages, call sendMessage(text)
+}
+```
+
+**Keep large transcripts off the client.** `persistence` also accepts `true`
+(server-authoritative): the client caches nothing, and on mount it hydrates the
+thread from the server by `threadId` (transcript plus a cursor to any run still
+generating). An adapter is client-authoritative; `true` leaves history on the
+server and needs a connection with a `hydrate` handler plus a server GET
+endpoint (`reconstructChat`), since the delivery log only holds one run.
+
+**Mid-stream reload rejoin.** If the run was still streaming when the page
+reloaded, the client re-attaches instead of showing a frozen half-reply — but
+only when the connection is **resumable**: a delivery-durability-backed route
+that records the stream and exposes a GET replay handler (see
+`docs/resumable-streams/overview.md` and Pattern 1's `durability` adapter). Given
+that, `useChat` finds the persisted in-flight run on load and auto-rejoins it via
+`joinRun`, replaying from the server's log so the reply finishes where it left
+off. No extra client code beyond the resumable connection.
+
+**Every framework, no extra code.** Durability rides the existing `persistence`
+option, so it works identically in `@tanstack/ai-react`, `-solid`, `-vue`,
+`-svelte`, `-angular`, and `-preact` — pass `persistence` (and a stable
+`threadId`, which is the chat's identity) to the framework's `useChat` /
+`createChat` / `injectChat`; nothing is framework-specific.
+
+> **Client vs. server durability.** This is the client (per-browser) half.
+> The authoritative, multi-user, server-side copy is the `withPersistence`
+> middleware — see ai-core/middleware/SKILL.md. The two are independent; use
+> both for instant reload restore plus a durable record of record.
+
 ## Common Mistakes
 
 ### a. CRITICAL: Using Vercel AI SDK patterns (streamText, generateText)
@@ -475,12 +561,12 @@ sendMessage('Never mind, do this instead', { whenBusy: 'interrupt' })
 // WRONG
 import { streamText } from 'ai'
 import { openai } from '@ai-sdk/openai'
-const result = streamText({ model: openai('gpt-4o'), messages })
+const result = streamText({ model: openai('gpt-5.5'), messages })
 
 // CORRECT
 import { chat } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
-const stream = chat({ adapter: openaiText('gpt-5.2'), messages })
+const stream = chat({ adapter: openaiText('gpt-5.5'), messages })
 ```
 
 ### b. CRITICAL: Using Vercel createOpenAI() provider pattern
@@ -489,12 +575,12 @@ const stream = chat({ adapter: openaiText('gpt-5.2'), messages })
 // WRONG
 import { createOpenAI } from '@ai-sdk/openai'
 const openai = createOpenAI({ apiKey })
-streamText({ model: openai('gpt-4o'), messages })
+streamText({ model: openai('gpt-5.5'), messages })
 
 // CORRECT
 import { openaiText } from '@tanstack/ai-openai'
 import { chat } from '@tanstack/ai'
-chat({ adapter: openaiText('gpt-5.2'), messages })
+chat({ adapter: openaiText('gpt-5.5'), messages })
 ```
 
 ### c. CRITICAL: Using monolithic openai() instead of openaiText()
@@ -502,11 +588,11 @@ chat({ adapter: openaiText('gpt-5.2'), messages })
 ```typescript
 // WRONG
 import { openai } from '@tanstack/ai-openai'
-chat({ adapter: openai(), model: 'gpt-5.2', messages })
+chat({ adapter: openai(), model: 'gpt-5.5', messages })
 
 // CORRECT
 import { openaiText } from '@tanstack/ai-openai'
-chat({ adapter: openaiText('gpt-5.2'), messages })
+chat({ adapter: openaiText('gpt-5.5'), messages })
 ```
 
 The monolithic `openai()` adapter is deprecated. Use tree-shakeable adapters:
@@ -528,10 +614,10 @@ return toServerSentEventsResponse(stream, { abortController })
 
 ```typescript
 // WRONG
-chat({ adapter: openaiText(), model: 'gpt-5.2', messages })
+chat({ adapter: openaiText(), model: 'gpt-5.5', messages })
 
 // CORRECT
-chat({ adapter: openaiText('gpt-5.2'), messages })
+chat({ adapter: openaiText('gpt-5.5'), messages })
 ```
 
 The model is passed to the adapter factory, not to `chat()`.
@@ -678,3 +764,4 @@ If not handled, the UI appears to hang with no feedback.
 - See also: **ai-core/tool-calling/SKILL.md** -- Most chats include tools
 - See also: **ai-core/adapter-configuration/SKILL.md** -- Adapter choice affects available features
 - See also: **ai-core/middleware/SKILL.md** -- Use middleware for analytics and lifecycle events
+- See also: **`@tanstack/ai-persistence` skills** (`skills/ai-persistence/SKILL.md` in that package) -- Server + client state persistence, store contracts, adapter recipes (deeper than Pattern 8)

package/skills/ai-core/client-persistence/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: ai-core/client-persistence
+description: >
+  Browser chat persistence on useChat / ChatClient: localStoragePersistence,
+  sessionStoragePersistence, indexedDBPersistence. Client-authoritative
+  (adapter, full transcript) vs server-authoritative (persistence: true, no
+  client cache).
+  Reload restore, pending interrupts, mid-stream rejoin with delivery
+  durability. Use for SPA reload durability — NOT server history alone.
+  Also covers generation hooks (useGenerateImage etc.), which take only the
+  server-driven mode: persistence: true hydrates the last generation for the
+  (REQUIRED) threadId from the server on mount and repaints status/result/error,
+  nothing is cached in the browser.
+  No extra package: the adapters ship in the framework packages.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.42.0'
+sources:
+  - 'TanStack/ai:docs/persistence/client-persistence.md'
+  - 'TanStack/ai:docs/persistence/overview.md'
+---
+
+# Client Persistence
+
+> Builds on ai-core, and on `ai-core/chat-experience` for `useChat` itself.
+>
+> **No extra package.** The adapters below ship in the **framework** packages
+> (`@tanstack/ai-react` and friends, re-exported from `@tanstack/ai-client`),
+> so browser persistence needs nothing installed beyond what a chat UI already
+> has. The **server** half is a separate package — see
+> `@tanstack/ai-persistence` and its `ai-persistence/server` skill.
+
+A `ChatClient` / `useChat` keeps messages in memory. The `persistence` option
+stores one record per `threadId` so a reload can repaint the transcript,
+restore a pending interrupt, and rejoin an in-flight run.
+
+Import adapters from the **framework package** (not `@tanstack/ai-client`
+unless vanilla JS):
+
+```tsx
+import {
+  useChat,
+  fetchServerSentEvents,
+  localStoragePersistence,
+  sessionStoragePersistence,
+  indexedDBPersistence,
+} from '@tanstack/ai-react'
+```
+
+## Adapters
+
+| Adapter                       | Survives                   | Notes                                                           |
+| ----------------------------- | -------------------------- | --------------------------------------------------------------- |
+| `localStoragePersistence()`   | Reloads + browser restarts | Sync hydrate; quota-bound; JSON codec default                   |
+| `sessionStoragePersistence()` | Reloads in the same tab    | Cleared when tab/session ends                                   |
+| `indexedDBPersistence()`      | Reloads + restarts         | Async open (first paint may be empty briefly); structured clone |
+
+All default to the chat persisted-state shape — no type argument or codec
+required for normal use.
+
+## Mode A — cache everything (client-authoritative)
+
+```tsx
+function Chat() {
+  const { messages, sendMessage } = useChat({
+    threadId: 'support-chat', // stable — required
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: localStoragePersistence(),
+  })
+  // ...
+}
+```
+
+Bare adapter ≡ full transcript + resume pointer. Browser owns history; server
+(if any) mirrors when you post non-empty `messages`.
+
+Best for: SPA, offline-first, single device, moderate conversation size.
+
+## Mode B — server-authoritative (`persistence: true`)
+
+```tsx
+function Chat({ threadId }: { threadId: string }) {
+  const { messages, sendMessage } = useChat({
+    threadId,
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: true,
+  })
+  // ...
+}
+```
+
+Nothing is cached client-side: no transcript, no resume pointer.
+
+On mount, `useChat` hydrates the thread from the **server** by `threadId`
+(paint + tail active run). Same path for another device. Pair with server
+`withPersistence` + a hydrate route (`reconstructChat` or equivalent).
+
+Best for: large transcripts, multi-device, compliance (no message bodies in
+browser storage).
+
+## What a reload restores
+
+1. **Finished run** — transcript from the adapter (mode A) or server (mode B).
+2. **Paused on interrupt** — approval UI restored (from the adapter in mode A,
+   the server hydrate in mode B).
+3. **Still streaming** — needs **delivery durability** on the route
+   (`toServerSentEventsResponse(stream, { durability: … })`) so the client can
+   `joinRun` and finish the reply. Persistence alone is not enough.
+
+## Stable `threadId` is the identity
+
+Persistence keys on `threadId`. The hooks have **no separate `id` option** — a
+chat's identity _is_ its `threadId`. Without a stable one, each load is a new
+chat. Generate it server-side or from a route param the user owns; do not
+randomize per mount.
+
+## Generation hooks: server-driven only
+
+The generation hooks (`useGenerateImage`, `useGenerateVideo`, `useGeneration`,
+`useSummarize`, `useTranscription`, …) take a `persistence` option too, but it is
+**boolean only** — there is no storage-adapter mode, and the browser caches
+nothing. **The hooks are transparent, mirroring `useChat`:** a reload repaints the
+hook's
+**normal** fields — `status` (`'idle'` / `'generating'` / `'success'` /
+`'error'`), `error`, and `result` — as if the run had just finished. There is
+**no** `resumeSnapshot`, `resumeState`, `pendingArtifacts`, or `resultArtifacts`
+field. The one extra field is `runId`: the id of the generation job currently
+running, or `null` when nothing is in flight. The persisted record holds run
+identity, status, error, and result metadata (ids, model, a provider video job
+id), **never the generated media bytes**.
+
+The hook return is exactly `generate` / `result` / `isLoading` / `error` /
+`status` / `stop` / `reset` / `runId`.
+
+### Turning it on (`persistence: true`)
+
+```tsx
+const image = useGenerateImage({
+  threadId, // REQUIRED — the scope the last generation is hydrated under
+  connection: fetchServerSentEvents('/api/generate/image'),
+  persistence: true,
+})
+// After a reload: image.status / image.result / image.error are the last
+// generation for `threadId`, fetched from the server — nothing was cached.
+```
+
+The server half — the same route handles the run and the hydration `GET`:
+
+```ts
+import {
+  generateImage,
+  generationParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+import {
+  memoryPersistence,
+  reconstructGeneration,
+  withGenerationPersistence,
+} from '@tanstack/ai-persistence'
+
+// Needs `stores.generationRuns`; `memoryPersistence()` ships one.
+const persistence = memoryPersistence()
+
+export async function POST(request: Request) {
+  const { input, threadId } = await generationParamsFromRequest(
+    'image',
+    request,
+  )
+  if (typeof input.prompt !== 'string') {
+    throw new Error('This endpoint accepts text image prompts only.')
+  }
+  if (threadId === undefined) {
+    throw new Error('Generation persistence requires a `threadId`.')
+  }
+
+  return toServerSentEventsResponse(
+    generateImage({
+      adapter: openaiImage('gpt-image-2'),
+      prompt: input.prompt,
+      // The stable slot this run fills. Required by persistence: the run record
+      // is filed under it, and the client hydrates by it on mount.
+      threadId,
+      stream: true,
+      middleware: [withGenerationPersistence(persistence)],
+    }),
+  )
+}
+
+// Mount-time hydration: resolves `?runId=` (preferred) or the latest run linked
+// to `?threadId=`, and returns `{ resumeSnapshot, activeRun }`.
+export function GET(request: Request) {
+  return reconstructGeneration(persistence, request, {
+    // Multi-user routes MUST authorize: the ids come from the caller. Derive
+    // identity from server-side session state, then check ownership.
+    authorize: async (id, req) => {
+      // const user = await auth(req)
+      // return user != null && (await db.threadOwnedBy(user.id, id))
+      void id
+      void req
+      return true
+    },
+  })
+}
+```
+
+- Nothing is cached client-side. On mount the client hydrates the **last
+  generation** for its `threadId` from the server via the connection's
+  `hydrateGeneration` handler (the SSE/HTTP adapters issue a `GET` with
+  `?threadId=` to the same endpoint URL) and repaints it into the normal fields.
+- The server `GET` returns `reconstructGeneration(persistence, request)` from
+  `@tanstack/ai-persistence` — it resolves the run by `?runId=` (preferred) or
+  the latest run linked to `?threadId=`, and needs `stores.generationRuns`. Pair it with
+  `withGenerationPersistence` on the generation route. See
+  `ai-core/media-generation` and `ai-persistence`.
+- Best for multi-device / compliance (no generation metadata in browser
+  storage), exactly like chat's server-authoritative mode.
+
+### Restoring media: byte storage + `artifactUrl`
+
+`result` comes back with its media only when the **server** persists the bytes
+(`stores.artifacts` + `stores.blobs`) AND `withGenerationPersistence` is given an
+`artifactUrl` mapper:
+
+```ts
+withGenerationPersistence(persistence, {
+  artifactUrl: (ref) => `/api/generate/image/artifact?id=${ref.artifactId}`,
+})
+```
+
+`artifactUrl` stamps a durable app-origin URL onto each persisted ref and
+rewrites the live result's media to it, so live and restored results match. The
+durable refs travel on `result.artifacts`; on restore the hook rebuilds `result`
+from them, so `result.images[i].url` (or a video's `result.url`) serves from your
+own origin. `result.artifacts` is the whole artifact surface on the hook.
+Without byte storage, a reload restores `status` / `error` and `result` stays
+`null`.
+
+Also worth knowing:
+
+- `stop()` marks the record no longer resumable; `reset()` clears the in-memory
+  snapshot.
+- Nothing auto-runs from a hydrated record — `generate(...)` is always explicit.
+- Use `status` / `result` for a finished run; use `runId` to tell that a run was
+  still generating when the page closed, and to name it to your own server (to
+  cancel or poll the provider job — `stop()` only aborts the local stream).
+
+## Common mistakes
+
+### HIGH: No `threadId`
+
+Record cannot be found after reload.
+
+### HIGH: Passing `id` to `useChat`
+
+Removed — `threadId` is the identity. (`ChatClient` still accepts `id` directly
+as a lower-level escape hatch for keying storage separately from the wire
+thread; the framework hooks do not.)
+
+### HIGH: `persistence: true` without server history
+
+Empty chat after reload unless the server can reconstruct by `threadId`.
+
+### MEDIUM: Huge transcripts in `localStorage`
+
+Quota and main-thread cost. Prefer `persistence: true` + server store, or
+IndexedDB with care.
+
+### MEDIUM: Expecting multi-device sync from client storage alone
+
+`localStorage` is per-browser. Use server persistence for multi-device.
+
+## Cross-references
+
+- **ai-persistence/server** (`@tanstack/ai-persistence`) — authoritative server half
+- **ai-core/chat-experience** — `useChat`, resumable connections
+- Resumable streams docs — mid-stream rejoin

package/skills/ai-core/custom-backend-integration/SKILL.md

@@ -9,7 +9,7 @@ description: >
   not @tanstack/ai-client.
 type: composition
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/chat/connection-adapters.md'
 ---

package/skills/ai-core/debug-logging/SKILL.md

@@ -9,7 +9,7 @@ description: >
   log by default even when `debug` is omitted; silence with `debug: false`.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/advanced/debug-logging.md'
 ---

package/skills/ai-core/locks/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: ai-core/locks
+description: >
+  LockStore, InMemoryLockStore, LocksCapability and withLocks for
+  multi-instance coordination in TanStack AI. Ships in @tanstack/ai — NOT in
+  @tanstack/ai-persistence. Separate from AIPersistence state stores — not a
+  stores key, not composable. InMemoryLockStore vs a distributed (e.g.
+  Cloudflare Durable Object) lock, lease recovery, AbortSignal in critical
+  sections. Use when sandbox or other middleware needs cross-worker mutual
+  exclusion — NOT for storing messages/runs (use withPersistence).
+type: sub-skill
+library: tanstack-ai
+library_version: '0.42.0'
+sources:
+  - 'TanStack/ai:docs/advanced/locks.md'
+  - 'TanStack/ai:packages/ai/src/activities/chat/middleware/locks.ts'
+---
+
+# Locks (coordination — not persistence)
+
+> **Dependency note:** This skill builds on ai-core and ai-core/middleware.
+> `withLocks` is a ChatMiddleware that provides a capability. Locks are **not**
+> part of `AIPersistence.stores` and are **not** composed with
+> `composePersistence` — they ship in `@tanstack/ai`, independent of
+> `@tanstack/ai-persistence`.
+
+## Why separate?
+
+State stores answer "what is durable chat data?"  
+Locks answer "who may run this critical section right now?"
+
+`withPersistence` does **not** automatically lock a whole turn. Take a
+per-thread (or other) lock yourself when multi-writer races matter.
+
+## Wire locks
+
+```ts
+import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
+
+middleware: [
+  withLocks(new InMemoryLockStore()), // single process
+]
+```
+
+Alongside persistence — optional, locks do not require it:
+
+```ts
+import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
+import { withPersistence } from '@tanstack/ai-persistence'
+
+middleware: [withPersistence(persistence), withLocks(new InMemoryLockStore())]
+```
+
+`withLocks` provides `LocksCapability` for downstream middleware (e.g.
+sandbox). Order: usually state first, locks alongside or after depending on
+who consumes the capability.
+
+## The contract
+
+```ts
+interface LockStore {
+  withLock<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T>
+}
+```
+
+`InMemoryLockStore` ships in **`@tanstack/ai/locks`**: a per-key promise chain,
+correct **within a single process only**. Multi-instance deployments need a
+distributed implementation — you write it. The Cloudflare Durable Object recipe
+is in **ai-persistence/build-cloudflare-adapter** (`@tanstack/ai-persistence`).
+
+Type your own store with `defineLock` (autocomplete, no `: LockStore`
+annotation), then hand it to `withLocks`. Acquire the key, run `fn`, release when
+`fn` settles:
+
+```ts
+import { defineLock, withLocks } from '@tanstack/ai/locks'
+import { acquire } from './my-lock-backend'
+
+const locks = defineLock({
+  async withLock(key, fn) {
+    const { release, signal } = await acquire(key)
+    try {
+      return await fn(signal)
+    } finally {
+      release()
+    }
+  },
+})
+
+middleware: [withLocks(locks)]
+```
+
+## Lease semantics
+
+A good `LockStore`:
+
+- Serializes owners per key,
+- Uses **leases** (or equivalent) so a crashed owner cannot block forever,
+- Passes an `AbortSignal` into the critical section via `withLock`; when the
+  lease is lost, abort so work stops starting external mutations.
+
+Callbacks must honor the signal and pass it to cancellable dependencies.
+`InMemoryLockStore` never aborts its signal — within one process, ownership
+cannot be lost.
+
+## Capability identity
+
+The `'locks'` capability token lives in `@tanstack/ai/locks`. Capability identity
+is by **object reference**, so one shared token means a `withLocks` in the chain
+reaches `withSandbox` automatically.
+
+## Common mistakes
+
+### HIGH: Importing locks from `@tanstack/ai-persistence`
+
+They are not exported there. Use `@tanstack/ai`.
+
+### HIGH: Putting `locks` on `AIPersistence.stores`
+
+Not supported. `stores` accepts only `messages`, `runs`, `interrupts`,
+`metadata` — never `locks`. Use `withLocks`.
+
+### HIGH: Passing `locks` to `composePersistence` overrides
+
+Same rejection, at the override layer. Locks are not state.
+
+### HIGH: Passing `'locks'` to the conformance testkit's `skip`
+
+`skip` accepts only chat state store keys. The suite does not cover locks
+at all — test lease expiry and abort separately.
+
+### HIGH: `InMemoryLockStore` across multiple processes
+
+No mutual exclusion between machines — use a distributed lock store.
+
+### MEDIUM: Ignoring lease abort
+
+Continuing work after losing the lease races other owners.
+
+## Cross-references
+
+- See also: **ai-core/middleware/SKILL.md** -- the middleware chain and capability plumbing
+- See also: **`@tanstack/ai-persistence` skills** (`skills/ai-persistence/SKILL.md` in that package) -- `ai-persistence/server` (state middleware) and `ai-persistence/build-cloudflare-adapter` (Durable Object lock recipe)