@tanstack/ai-persistence 0.0.0

package/skills/ai-persistence/build-cloudflare-adapter/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: ai-persistence/build-cloudflare-adapter
+description: Use when a Cloudflare Worker needs TanStack AI chat persistence — writes a chat-persistence.ts into the app against its D1 binding (raw or via Drizzle), plus a Durable Object LockStore. Covers per-request bindings, wrangler config, D1 migrations, and lease-based locks.
+---
+
+# Cloudflare Chat Persistence
+
+The deliverable is **one file in the Worker** — `src/lib/chat-persistence.ts` —
+exporting a factory that builds a `ChatPersistence` from the request's D1
+binding, plus (when the app needs coordination) a Durable Object lock store.
+Tables go into the app's existing `migrations/` directory and are applied with
+`wrangler d1 migrations apply`.
+
+Do not create a package or a migration runner. Wrangler already tracks applied
+migrations; a second bookkeeping table only creates drift.
+
+Read the **Store Reference**
+(`docs/persistence/store-reference.md`) for the store contracts, and
+**ai-persistence/stores** for the shape rules. This skill covers only
+the Cloudflare-specific parts.
+
+## 1. Read the app before writing anything
+
+| Find                   | Where to look                                                                                    | What it decides                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
+| D1 binding name        | `wrangler.jsonc` `d1_databases[].binding`                                                        | `env.DB` vs `env.AI_STATE` in the factory         |
+| How `env` reaches code | the Worker `fetch(request, env)`, or an async-local helper (`getDb()`, `getCloudflareContext()`) | Whether the factory takes `env` or reads a helper |
+| Drizzle or raw D1      | `drizzle-orm` in `package.json`, a `src/db/schema.ts`                                            | Which recipe below to follow                      |
+| Migrations dir         | `wrangler.jsonc` `migrations_dir`, default `migrations/`                                         | Where the new `.sql` file goes                    |
+| Existing table names   | the current migrations / schema                                                                  | Prefix (`chat_*`) so nothing collides             |
+
+## 2. Two independent pieces
+
+```
+D1 database      -> messages, runs, interrupts, metadata   (AIPersistence.stores)
+Durable Object   -> LockStore                              (withLocks — NOT a store)
+```
+
+These do not compose into one object. `AIPersistence.stores` accepts exactly
+four keys. Putting `locks` in the map throws
+`Unknown AIPersistence store key: locks`; putting it in a `composePersistence`
+override throws `Unknown AIPersistence override key: locks`. Both also fail to
+type-check. Return
+the state persistence from one factory and the lock store from another, then
+wire them as two middlewares.
+
+Most apps need only the first piece. Add the Durable Object when other
+middleware genuinely needs mutual exclusion across isolates —
+`InMemoryLockStore` gives none, because a Worker runs on many isolates at once.
+
+## 3. Bindings are per-request
+
+This is the one rule that separates Cloudflare from every other backend. A D1
+binding does not exist at module scope, so `chat-persistence.ts` **must export a
+factory**, not a const:
+
+```ts ignore
+import { defineAIPersistence } from '@tanstack/ai-persistence'
+import type { ChatPersistence } from '@tanstack/ai-persistence'
+
+/** Call inside a request handler — `env` is not available at module scope. */
+export function chatPersistence(d1: D1Database): ChatPersistence {
+  return defineAIPersistence({
+    stores: {
+      messages: createMessageStore(d1),
+      runs: createRunStore(d1),
+      interrupts: createInterruptStore(d1),
+      metadata: createMetadataStore(d1),
+    },
+  })
+}
+```
+
+Annotate `ChatPersistence` — bare `AIPersistence` is the all-optional bag and
+`withPersistence` rejects it. Building it per request is cheap: the stores hold
+no state beyond the binding.
+
+## 4. The stores
+
+Two routes, same invariants:
+
+- **Drizzle over D1** — if the app already runs Drizzle, wrap the binding with
+  `drizzle(env.DB, { schema })` and follow
+  **ai-persistence/build-drizzle-adapter** verbatim (its "if `db` is
+  per-request" section is exactly this case). Stop reading here.
+- **Raw D1** — implement the four stores against `d1.prepare(sql).bind(...)`:
+  `.first()` for `get`, `.all()` for `list*`, `.run()` for writes. D1 speaks
+  SQLite, so this mirrors the `node:sqlite` walkthrough in the guide one-for-one;
+  everything is already async, so no `Promise.resolve` wrapping.
+
+The invariants are the whole game, whichever route you take:
+
+| Store        | Rule                                                                                                                                                                                               |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `messages`   | `saveThread` is a full replace (`INSERT … ON CONFLICT(thread_id) DO UPDATE`)                                                                                                                       |
+| `runs`       | `createOrResume` reads first, else `INSERT … ON CONFLICT DO NOTHING`, then re-reads                                                                                                                |
+| `runs`       | `update` on an unknown id is a silent no-op — never throws, never inserts                                                                                                                          |
+| `runs`       | `findActiveRun` (required) returns the latest `'running'` run for the thread, else null                                                                                                            |
+| `runs`       | `listByThread` (optional) returns every run for the thread `ORDER BY started_at ASC`                                                                                                               |
+| `runs`       | `listReclaimable` (optional) returns runs where `status = 'running' AND detached_since IS NOT NULL AND detached_since <= now - ttlMs` (inclusive cutoff); it is a query, not automatic reclamation |
+| `interrupts` | `create` is insert-if-absent; never clobber a resolved interrupt back to pending                                                                                                                   |
+| `interrupts` | every `list*` ends `ORDER BY requested_at ASC`                                                                                                                                                     |
+| `metadata`   | reject nullish `set` with a clear `TypeError`; tell callers to use `delete`                                                                                                                        |
+
+On `runs`, `findActiveRun` is required; `listByThread` and `listReclaimable` are
+optional, so implement those two only if the app needs them. `withPersistence`
+calls **none** of the three — the consumers are `reconstruct.ts`
+(`findActiveRun`, for rejoin-by-thread) and `@tanstack/ai-sandbox`'s `reapDetachedRuns`
+(`listReclaimable`, without which the store cannot be reaped); nothing in the
+framework calls `listByThread`. Consumers of the two OPTIONAL methods
+feature-detect with `store.method?.(...)` and degrade to "not supported" when one
+is absent. The conformance testkit does not: either of those you leave out must
+be listed in `skipMethods` or the suite fails, so declare them and it reports the
+omission as a skip.
+
+`RunRecord.error` is a structured `RunError` (`{ message: string, code?: string }`),
+so the table gets two columns rather than one JSON blob: `error` for the
+provider's prose and `error_code` for the stable classification an operator
+filters and groups by. Write both together in `update`, so a later code-less
+failure can never leave a stale `error_code` from an earlier one behind, and
+omit `code` from the mapped record when the column is `null`:
+`...(row.error != null ? { error: { message: row.error, ...(row.error_code != null ? { code: row.error_code } : {}) } } : {})`.
+Other row mappers omit absent optionals the same way
+(`...(row.sandbox_key != null ? { sandboxKey: row.sandbox_key } : {})`) so
+records compare cleanly against the reference in-memory backend. JSON columns
+are `text`: `JSON.parse` on read, `JSON.stringify` on write. Timestamps are
+`integer` epoch ms.
+
+`sandbox_key`, `detached_since`, `cancel_requested`, and `driver_epoch` are the
+durable-agent-runs columns. In `update`, check `'field' in patch` for all
+four — never `patch.field !== undefined` — because a reattach clears
+`detachedSince` by passing it explicitly as `undefined`, which must bind
+`NULL` into the `SET` clause rather than being filtered out of it (a filtered
+clear leaves the stale value and the run looks permanently detached to the
+reaper). The same applies to `cancelRequested`: `false` written explicitly is
+a real, meaningful value distinct from "never set", not something to coerce
+away. See `examples/ts-react-chat/src/lib/sqlite-persistence.ts` (D1 speaks
+the same SQLite dialect) for the worked `update` body.
+
+## 5. The migration
+
+Write the tables into the app's `migrations/` directory as a new numbered file:
+
+```sql
+CREATE TABLE IF NOT EXISTS chat_threads (
+  thread_id text PRIMARY KEY NOT NULL,
+  messages_json text NOT NULL,
+  updated_at integer NOT NULL
+);
+CREATE TABLE IF NOT EXISTS chat_runs (
+  run_id text PRIMARY KEY NOT NULL,
+  thread_id text NOT NULL,
+  status text NOT NULL,
+  started_at integer NOT NULL,
+  finished_at integer,
+  error text,
+  error_code text,
+  usage_json text,
+  sandbox_key text,
+  detached_since integer,
+  cancel_requested integer,
+  driver_epoch integer
+);
+CREATE INDEX IF NOT EXISTS chat_runs_thread_status ON chat_runs (thread_id, status);
+CREATE INDEX IF NOT EXISTS chat_runs_thread_started ON chat_runs (thread_id, started_at);
+-- Powers listReclaimable: status = 'running' AND detached_since <= cutoff.
+CREATE INDEX IF NOT EXISTS chat_runs_status_detached ON chat_runs (status, detached_since);
+CREATE TABLE IF NOT EXISTS chat_interrupts (
+  interrupt_id text PRIMARY KEY NOT NULL,
+  run_id text NOT NULL,
+  thread_id text NOT NULL,
+  status text NOT NULL,
+  requested_at integer NOT NULL,
+  resolved_at integer,
+  payload_json text NOT NULL,
+  response_json text
+);
+CREATE INDEX IF NOT EXISTS chat_interrupts_thread ON chat_interrupts (thread_id, requested_at);
+CREATE TABLE IF NOT EXISTS chat_metadata (
+  namespace text NOT NULL,
+  key text NOT NULL,
+  value_json text NOT NULL,
+  PRIMARY KEY (namespace, key)
+);
+```
+
+Apply with `wrangler d1 migrations apply <database-name>` (`--local` first, then
+`--remote`). If the app also uses Drizzle, generate this file with
+`drizzle-kit generate` instead of hand-writing it — the SQL and the Drizzle
+table definitions must agree, so let one of them own the other.
+
+## 6. Wire it into the chat route
+
+```ts ignore
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withPersistence } from '@tanstack/ai-persistence'
+import { chatPersistence } from './lib/chat-persistence'
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const params = await chatParamsFromRequest(request)
+    const stream = chat({
+      adapter: openaiText('gpt-5.5'),
+      messages: params.messages,
+      threadId: params.threadId,
+      runId: params.runId,
+      ...(params.resume ? { resume: params.resume } : {}),
+      middleware: [withPersistence(chatPersistence(env.DB))],
+    })
+    return toServerSentEventsResponse(stream)
+  },
+}
+```
+
+`threadId` is a bare string to the stores. **Authorize thread access at the
+route** — derive the user from the session, never trust a client-supplied id.
+
+## 7. Durable Object lock store (only if needed)
+
+Implement `LockStore` from `@tanstack/ai/locks`. `withLock(key, fn)`
+routes each key to a Durable Object instance (`idFromName(key)`) that serializes
+owners. Use **leases** so a crashed owner cannot block forever: the DO grants a
+lease with an expiry, an alarm reclaims it, and the lock passes the callback an
+`AbortSignal` that fires when ownership can no longer be guaranteed. Callbacks
+must stop starting external mutations once the signal aborts.
+
+Export the DO class from the Worker entry so wrangler can bind it:
+
+```ts ignore
+export { ChatLockDurableObject } from './locks'
+```
+
+Then wire both middlewares:
+
+```ts ignore
+import { withLocks } from '@tanstack/ai/locks'
+import { withPersistence } from '@tanstack/ai-persistence'
+
+const middleware = [
+  withPersistence(chatPersistence(env.AI_STATE)),
+  withLocks(createDurableObjectLockStore(env.AI_LOCKS)),
+]
+```
+
+## wrangler bindings
+
+```jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "AI_STATE",
+      "database_name": "tanstack-ai-state",
+      "database_id": "<id>",
+      "migrations_dir": "migrations",
+    },
+  ],
+  "durable_objects": {
+    "bindings": [{ "name": "AI_LOCKS", "class_name": "ChatLockDurableObject" }],
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["ChatLockDurableObject"] },
+  ],
+}
+```
+
+Durable Object locks do not use the D1 table migration set; their state is
+configured through the migration tags above.
+
+## Verify
+
+```ts ignore
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { env } from 'cloudflare:test'
+import { chatPersistence } from '../src/lib/chat-persistence'
+
+runPersistenceConformance('app-d1', () => chatPersistence(env.AI_STATE), {
+  skip: ['generationRuns', 'artifacts', 'blobs'],
+})
+```
+
+Run it against a Miniflare D1 binding with the migration applied, reset between
+runs. All four state stores are provided; the suite also covers the three
+generation stores, so a chat-only adapter declares them skipped (drop the `skip`
+once you add the R2-backed set from
+**ai-persistence/build-cloudflare-artifact-store**). `skip` never accepts
+`'locks'`, which is not a store.
+
+If your recipe leaves an optional `runs` method
+(`listByThread`/`listReclaimable`) unimplemented, declare it
+with `skipMethods`, e.g. `{ skipMethods: ['runs.listByThread'] }`. An
+omitted method that is not declared fails the suite instead of silently
+passing.
+
+The lock store needs its **own** tests, because nothing in the conformance suite
+touches it. Cover at minimum: two concurrent `withLock` calls on the same key
+serialize; different keys do not block each other; a lease that expires aborts
+the signal handed to the critical section; and a callback that throws still
+releases the lock.
+
+## Only if you are publishing this as a package
+
+For a reusable npm adapter rather than a file in the app: peer-dep
+`@cloudflare/workers-types >=4.x`, and prepend
+`/// <reference types="@cloudflare/workers-types" />` to the generated
+`index.d.ts` so consumers get the D1/DurableObject types. Emit the table SQL
+into the consumer's `migrations/` directory rather than shipping a runner, and
+if you offer both raw-D1 and Drizzle paths, guard with a test that the emitted
+SQL and the Drizzle tables describe the same schema.