@tanstack/ai-persistence 0.0.0

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../src/types.ts"],"sourcesContent":["import type {\n  ModelMessage,\n  PersistedArtifactRef,\n  RunStatus,\n  RunStore,\n  Scope,\n  TokenUsage,\n} from '@tanstack/ai'\n\n// Re-export the shared identity type so app code can import Scope from either\n// `@tanstack/ai` or `@tanstack/ai-persistence`. See {@link Scope} security notes:\n// pair a client-visible `threadId` with a server-trusted `userId`/`tenantId`\n// before authorizing load/save (e.g. via `reconstructChat({ authorize })`).\nexport type { Scope }\n\n// ===========================================================================\n// Store contracts\n// ===========================================================================\n//\n// EVOLUTION POLICY\n// ----------------\n// These store interfaces are the compatibility surface between the core\n// middleware and every backend — the in-memory reference store and every\n// adapter an application writes against its own database.\n//\n//   - Store METHODS are REQUIRED. A new method is a breaking contract change:\n//     every adapter gets a compile error and implements it. Do NOT add methods\n//     as optional-and-feature-detected (`store.method?.(...)`) — an adapter\n//     that has not implemented one is then indistinguishable from one whose\n//     answer is legitimately empty, so the feature silently does nothing in\n//     production instead of failing at build time. `findActiveRun` was optional\n//     for exactly one release cycle and cost us precisely that: reconnect\n//     degraded to \"no active run\" on every backend that had not caught up.\n//   - Capability tiers belong at the STORE level, not the method level. A\n//     backend that only stores a transcript declares `ChatTranscriptStores`\n//     (no `runs`); it does not declare a half-implemented `RunStore`.\n//   - Never tighten an existing method's required arguments or widen its\n//     required return shape in a breaking way.\n//\n// The shared conformance testkit (`./testkit/conformance.ts`) is the\n// authoritative compatibility gate: every invariant documented on the methods\n// below is asserted there, and every backend runs the identical suite. If an\n// invariant is not encoded in the testkit, adapters cannot discover it — so\n// promote new invariants into both the JSDoc here AND the testkit.\n//\n// TIMESTAMP CONVENTION\n// --------------------\n// Store *records* (`RunRecord`, `InterruptRecord`, `ArtifactRecord`,\n// `BlobRecord`) speak **epoch milliseconds** (`number`), the native unit for\n// SQL/`BIGINT` columns and `Date.now()`. Wire/result references that leave the\n// persistence layer (e.g. core's `PersistedArtifactRef.createdAt`) speak\n// **ISO-8601 strings**. The middleware performs the number→ISO conversion at\n// the boundary; do not mix the two on a single field.\n\n/**\n * Durable store for a thread's full message transcript.\n *\n * A \"thread\" is the unit of conversation history. The key is\n * {@link Scope.threadId} (the same conversation id as\n * `ChatMiddlewareContext.threadId`). Store methods take a bare string for\n * adapter simplicity; multi-user isolation is the **host's** job — authorize\n * against `Scope.userId` / `Scope.tenantId` (derived server-side from session)\n * before calling load/save, and never treat a client-supplied thread id alone\n * as an ownership proof (see `Scope` security notes in `@tanstack/ai`).\n *\n * `saveThread` always receives and persists the **complete, authoritative**\n * message list — it is an overwrite, never an append. The middleware snapshots\n * `ctx.messages` (the full running transcript) into it.\n */\nexport interface MessageStore {\n  /**\n   * Return the full stored transcript for `threadId` ({@link Scope.threadId}),\n   * in insertion order.\n   *\n   * INVARIANT: returns an empty array (never `null`/`undefined`) for a thread\n   * that was never saved. Callers treat `[]` as \"no history\".\n   */\n  loadThread: (threadId: string) => Promise<Array<ModelMessage>>\n  /**\n   * Overwrite the stored transcript for `threadId` with `messages`.\n   *\n   * INVARIANT: this is a full replace. `messages` is the complete authoritative\n   * history; the previous contents are discarded (not merged or appended).\n   */\n  saveThread: (threadId: string, messages: Array<ModelMessage>) => Promise<void>\n}\n\n// Run lifecycle types live in `@tanstack/ai` and are re-exported here: one run,\n// one record — shared by this package's `runs` store and `@tanstack/ai-sandbox`'s\n// run driver, instead of each package keeping a rival definition that can drift.\nexport type {\n  RunStatus,\n  TerminalRunStatus,\n  RunRecord,\n  RunStore,\n} from '@tanstack/ai'\nexport { isTerminalRunStatus, defineRunStore } from '@tanstack/ai'\n\n/**\n * Lifecycle status of a generation run. Deliberately the same vocabulary as\n * {@link RunStatus}, so an adapter that stores both kinds of run can share one\n * status column and one set of checks.\n */\nexport type GenerationRunStatus = RunStatus\n\n/**\n * A single generation run (one `generateImage` / `generateVideo` / … call).\n *\n * Its primary identity is `runId`: the run/request id the activity mints, the\n * same AG-UI run id the client sends on the wire. `threadId` is the SLOT the\n * run fills, a stable app-chosen name that groups successive runs of the same\n * thing, and it is what a server-driven client hydrates by. Generation state is\n * kept here, never in the chat {@link RunStore}.\n *\n * `result` holds terminal result METADATA (ids, model, urls, a provider video\n * job id), never the media bytes — those live in a {@link BlobStore}.\n * `artifacts` are the durable {@link PersistedArtifactRef}s, present only when\n * byte storage is on.\n *\n * @property startedAt - Epoch ms when the run was first created.\n * @property finishedAt - Epoch ms when the run reached a terminal status.\n */\nexport interface GenerationRunRecord {\n  runId: string\n  /**\n   * The scope this run belongs to: a stable, app-chosen name for the slot\n   * successive runs fill (`product-123-hero`, `video-9-start-frame`).\n   *\n   * REQUIRED, per the store-contract rule at the top of this file.\n   * {@link GenerationRunStore.findLatestForThread} is the only query that\n   * hydrates a run, and it keys on this — so a record without one can be\n   * written and then never found again. `withGenerationPersistence` already\n   * refuses to start a run without a scope, and a server-driven client\n   * discards a snapshot that arrives without one, so an optional field here\n   * only described a record no path could produce and no client would accept.\n   */\n  threadId: string\n  /** `'image' | 'audio' | 'tts' | 'video' | 'transcription'`. */\n  activity: string\n  provider: string\n  model: string\n  status: GenerationRunStatus\n  startedAt: number\n  finishedAt?: number\n  error?: { message: string; code?: string }\n  /** Terminal result metadata (ids, model, urls). Never the media bytes. */\n  result?: unknown\n  /** Durable artifact references, when an artifacts + blobs backend is used. */\n  artifacts?: Array<PersistedArtifactRef>\n  usage?: TokenUsage\n}\n\n/**\n * Durable store for generation run records, the generation counterpart to\n * {@link RunStore}. Keyed by its own `runId`, with `threadId` the slot\n * {@link GenerationRunStore.findLatestForThread} looks runs up by.\n */\nexport interface GenerationRunStore {\n  /**\n   * Create a run record, or return the existing one if `runId` is already\n   * present (resume).\n   *\n   * INVARIANT (idempotency): a second call for a `runId` returns the existing\n   * record unchanged; `startedAt`/`activity`/`provider`/`model`/`threadId` are\n   * not mutated. `status` defaults to `'running'` on first creation.\n   */\n  createOrResume: (\n    input: Pick<\n      GenerationRunRecord,\n      'runId' | 'threadId' | 'activity' | 'provider' | 'model' | 'startedAt'\n    > & { status?: GenerationRunStatus },\n  ) => Promise<GenerationRunRecord>\n  /**\n   * Patch a run record's mutable fields.\n   *\n   * INVARIANT: patching a `runId` that does not exist is a **no-op** — it must\n   * not throw and must not create a record.\n   */\n  update: (\n    runId: string,\n    patch: Partial<\n      Pick<\n        GenerationRunRecord,\n        'status' | 'finishedAt' | 'error' | 'result' | 'artifacts' | 'usage'\n      >\n    >,\n  ) => Promise<void>\n  /** Return the run record for `runId`, or `null` if none exists. */\n  get: (runId: string) => Promise<GenerationRunRecord | null>\n  /**\n   * The most recent run linked to `threadId`, or `null`.\n   *\n   * REQUIRED, per the store-contract rule at the top of this file: a\n   * server-authoritative client hydrates by the stable thread id on every\n   * mount, so an adapter without this would be indistinguishable from one that\n   * legitimately has no run — `persistence: true` would silently restore\n   * nothing, forever. `null` is the correct answer only when the thread really\n   * has no runs. The chat parallel is {@link RunStore.findActiveRun}.\n   */\n  findLatestForThread: (threadId: string) => Promise<GenerationRunRecord | null>\n}\n\n/** Lifecycle status of a human-in-the-loop interrupt. */\nexport type InterruptStatus = 'pending' | 'resolved' | 'cancelled'\n\n/**\n * A human-in-the-loop interrupt (tool approval, client-tool input request, …).\n *\n * @property requestedAt - Epoch ms when the interrupt was created.\n * @property resolvedAt - Epoch ms when the interrupt was resolved/cancelled;\n *   absent while pending.\n */\nexport interface InterruptRecord {\n  interruptId: string\n  runId: string\n  threadId: string\n  status: InterruptStatus\n  requestedAt: number\n  resolvedAt?: number\n  payload: Record<string, unknown>\n  response?: unknown\n}\n\n/** Durable store for human-in-the-loop interrupts. */\nexport interface InterruptStore {\n  /**\n   * Persist a new interrupt in the `'pending'` state.\n   *\n   * The record is accepted without `status`/`resolvedAt` so a \"born resolved\"\n   * interrupt is unrepresentable — every interrupt begins pending and only\n   * `resolve`/`cancel` may move it to a terminal state.\n   *\n   * INVARIANT (insert-if-absent): if an interrupt with the same `interruptId`\n   * already exists, `create` is a **no-op** — it must NOT overwrite the\n   * existing record. This is the canonical behaviour (SQL backends implement it\n   * via `ON CONFLICT DO NOTHING` / upsert-with-empty-update), so a duplicate\n   * create can never clobber a resolved interrupt back to pending.\n   */\n  create: (\n    record: Omit<InterruptRecord, 'status' | 'resolvedAt'>,\n  ) => Promise<void>\n  /**\n   * Move an interrupt to `'resolved'`, stamping `resolvedAt` and storing\n   * `response`. A no-op if `interruptId` does not exist.\n   */\n  resolve: (interruptId: string, response?: unknown) => Promise<void>\n  /**\n   * Move an interrupt to `'cancelled'`, stamping `resolvedAt`. A no-op if\n   * `interruptId` does not exist.\n   */\n  cancel: (interruptId: string) => Promise<void>\n  /** Return the interrupt for `interruptId`, or `null` if none exists. */\n  get: (interruptId: string) => Promise<InterruptRecord | null>\n  /**\n   * All interrupts for a thread.\n   *\n   * INVARIANT: ordered by insertion (equivalently `requestedAt` ascending). SQL\n   * backends MUST `ORDER BY requested_at` — the middleware and testkit rely on\n   * this stable ordering.\n   */\n  list: (threadId: string) => Promise<Array<InterruptRecord>>\n  /** Pending interrupts for a thread, ordered by `requestedAt` ascending. */\n  listPending: (threadId: string) => Promise<Array<InterruptRecord>>\n  /** All interrupts for a run, ordered by `requestedAt` ascending. */\n  listByRun: (runId: string) => Promise<Array<InterruptRecord>>\n  /** Pending interrupts for a run, ordered by `requestedAt` ascending. */\n  listPendingByRun: (runId: string) => Promise<Array<InterruptRecord>>\n}\n\n/**\n * Namespaced key/value store for arbitrary JSON metadata (app-owned).\n *\n * The first argument is an **app-defined namespace string**, not the shared\n * {@link Scope} identity type from `@tanstack/ai`. Composite identity is\n * `(namespace, key)` as two independent fields (SQL backends use a composite\n * primary key; the in-memory store uses nested maps). Do not encode both into a\n * single delimited string — `${namespace}:${key}` collides when either part\n * contains `:`.\n *\n * The same `key` under different namespaces is independent.\n */\nexport interface MetadataStore {\n  /**\n   * Return the stored value for `(namespace, key)`, or `null` if absent.\n   *\n   * CAVEAT: the return type is `unknown | null`, where `| null` collapses into\n   * `unknown` — a stored value of `null` is therefore **indistinguishable from\n   * absence** at the type level. Callers that must persist a real `null`\n   * distinctly from \"not set\" should wrap it (e.g. store `{ value: null }`).\n   */\n  get: (namespace: string, key: string) => Promise<unknown | null>\n  /** Insert or overwrite the value for `(namespace, key)`. */\n  set: (namespace: string, key: string, value: unknown) => Promise<void>\n  /**\n   * Remove `(namespace, key)`. A no-op if absent. Does not affect other\n   * namespaces.\n   */\n  delete: (namespace: string, key: string) => Promise<void>\n}\n\n// ===========================================================================\n// Store typers\n// ===========================================================================\n//\n// Identity helpers that type a store implementation inline: pass an object\n// literal and get autocomplete + contract checking, with no separate\n// `: MessageStore` return annotation. They compose into `defineAIPersistence`,\n// which infers **exact presence** — a store you define becomes a defined,\n// non-optional, autocompleted key on `persistence.stores`, and accessing a store\n// you did not define is a compile error.\n//\n// ```ts\n// const persistence = defineAIPersistence({\n//   stores: {\n//     messages: defineMessageStore({ loadThread, saveThread }),\n//     runs: defineRunStore({ createOrResume, update, get, findActiveRun }),\n//   },\n// })\n// persistence.stores.runs        // RunStore (defined)\n// persistence.stores.interrupts  // compile error — not provided\n// ```\n//\n// Presence is per STORE, not per method: every method of a store you define is\n// required (see the evolution policy above). Omitting one is a compile error,\n// not a partial store.\n\n/** Type a {@link MessageStore} implementation inline. */\nexport function defineMessageStore(store: MessageStore): MessageStore {\n  return store\n}\n/** Type an {@link InterruptStore} implementation inline. */\nexport function defineInterruptStore(store: InterruptStore): InterruptStore {\n  return store\n}\n/** Type a {@link MetadataStore} implementation inline. */\nexport function defineMetadataStore(store: MetadataStore): MetadataStore {\n  return store\n}\n/** Type a {@link GenerationRunStore} implementation inline. */\nexport function defineGenerationRunStore(\n  store: GenerationRunStore,\n): GenerationRunStore {\n  return store\n}\n/** Type an {@link ArtifactStore} implementation inline. */\nexport function defineArtifactStore(store: ArtifactStore): ArtifactStore {\n  return store\n}\n/** Type a {@link BlobStore} implementation inline. */\nexport function defineBlobStore(store: BlobStore): BlobStore {\n  return store\n}\n\n/**\n * Metadata row describing a persisted artifact (generated media, tool output).\n *\n * The bytes themselves live in a {@link BlobStore}; this record holds the\n * descriptive metadata and an optional `sourceUrl` for reference-only\n * backends.\n *\n * @property createdAt - Epoch ms. (Core's wire-facing `PersistedArtifactRef`\n *   exposes the same instant as an ISO string; see the timestamp convention.)\n */\nexport interface ArtifactRecord {\n  artifactId: string\n  runId: string\n  threadId: string\n  /**\n   * The blob-store key these bytes actually live under.\n   *\n   * Optional for backwards compatibility: records written before this existed\n   * resolve via the default `artifacts/<runId>/<artifactId>` convention. New\n   * records always carry it, which is what lets `storageKey` put bytes anywhere\n   * — a reader can no longer recompute the path, so it has to be remembered.\n   * Use `resolveArtifactBlobKey(record)` rather than reading it directly.\n   */\n  blobKey?: string\n  name: string\n  mimeType: string\n  size: number\n  sourceUrl?: string\n  createdAt: number\n}\n\n/** Durable store for artifact metadata records. */\nexport interface ArtifactStore {\n  /** Insert or overwrite the artifact metadata record. */\n  save: (record: ArtifactRecord) => Promise<void>\n  /** Return the artifact for `artifactId`, or `null` if none exists. */\n  get: (artifactId: string) => Promise<ArtifactRecord | null>\n  /** All artifacts for a run. Returns `[]` when the run has none. */\n  list: (runId: string) => Promise<Array<ArtifactRecord>>\n  /**\n   * Delete a single artifact by id. A no-op if absent, mirroring\n   * {@link BlobStore.delete} — the two are written and deleted as a pair, so\n   * their contracts match.\n   */\n  delete: (artifactId: string) => Promise<void>\n  /**\n   * Delete every artifact belonging to `runId`. A no-op when the run has none.\n   *\n   * Required rather than feature-detected: retention and erasure are the point\n   * of storing media durably, and an adapter silently lacking deletion is\n   * indistinguishable from one where there was nothing to delete.\n   */\n  deleteForRun: (runId: string) => Promise<void>\n}\n\n/**\n * Accepted body shapes for {@link BlobStore.put}. `ArrayBufferView` already\n * covers `Uint8Array` and every other typed-array/`DataView`, so no separate\n * `Uint8Array` member is needed.\n */\nexport type BlobBody =\n  | ReadableStream<Uint8Array>\n  | ArrayBuffer\n  | ArrayBufferView\n  | string\n  | Blob\n\n/**\n * Metadata for a stored blob.\n *\n * @property size - Byte length, when known.\n * @property createdAt - Epoch ms first written.\n * @property updatedAt - Epoch ms last overwritten.\n */\nexport interface BlobRecord {\n  key: string\n  size?: number\n  etag?: string\n  contentType?: string\n  customMetadata?: Record<string, string>\n  createdAt?: number\n  updatedAt?: number\n}\n\n/**\n * A byte range to read, in the shape an HTTP `Range` header resolves to.\n *\n * `offset` is measured from the start of the object and must be inside it;\n * `length` defaults to \"everything from `offset` to the end\" and is clamped to\n * the end when it overshoots. Suffix ranges (`bytes=-500`) are the caller's to\n * resolve against the known size — a serve route has the size on the artifact\n * record, and has to compare against it anyway to answer `416` before reading.\n */\nexport interface BlobRange {\n  offset: number\n  length?: number\n}\n\n/** Options for {@link BlobStore.get}. */\nexport interface BlobGetOptions {\n  /**\n   * Read only this slice of the object. `body`, `arrayBuffer()` and `text()`\n   * then cover the slice, `size` still reports the WHOLE object, and `range`\n   * reports the slice actually served — the three numbers a `206` response\n   * needs (`Content-Range: bytes <offset>-<offset+length-1>/<size>`).\n   */\n  range?: BlobRange\n}\n\n/** A stored blob's metadata plus lazy accessors for its bytes. */\nexport interface BlobObject extends BlobRecord {\n  arrayBuffer: () => Promise<ArrayBuffer>\n  text: () => Promise<string>\n  body?: ReadableStream<Uint8Array>\n  /**\n   * The slice this object exposes, when a {@link BlobGetOptions.range} was\n   * requested and honoured: `offset` as asked, `length` as actually served\n   * (clamped to the end of the object). Absent on a whole-object read.\n   */\n  range?: { offset: number; length: number }\n}\n\n/**\n * One page of a {@link BlobStore.list} scan.\n *\n * @property cursor - Opaque continuation token; present only when `truncated`.\n * @property truncated - `true` when more objects match beyond this page.\n */\nexport interface BlobListPage {\n  objects: Array<BlobRecord>\n  cursor?: string\n  truncated?: boolean\n}\n\nexport interface BlobPutOptions {\n  contentType?: string\n  customMetadata?: Record<string, string>\n  /**\n   * The exact byte length of `body`, when the producer knows it up front.\n   *\n   * Advisory, not a contract the store must honor: it exists so a store can\n   * pick an upload strategy knowingly instead of discovering the length by\n   * buffering. Most useful to an SDK that wants the length as a separate\n   * argument rather than reading it off the stream — S3's `PutObject`\n   * (`ContentLength`) is the archetype — and to a runtime that can re-attach\n   * one (workerd's `FixedLengthStream` ahead of `R2Bucket.put`).\n   *\n   * Only ever set when the length is exact — a wrong value is worse than none,\n   * since runtimes that enforce declared lengths fail the write. Absent means\n   * unknown, and a store must accept a length-less stream regardless:\n   * producers hand one over whenever the origin does not declare a length.\n   */\n  expectedLength?: number\n}\n\nexport interface BlobListOptions {\n  prefix?: string\n  cursor?: string\n  limit?: number\n}\n\n/** Durable object/blob store (byte-storing or reference-only backends). */\nexport interface BlobStore {\n  /** Insert or overwrite the object at `key`, returning its metadata. */\n  put: (\n    key: string,\n    body: BlobBody,\n    options?: BlobPutOptions,\n  ) => Promise<BlobRecord>\n  /**\n   * Return the object at `key` (metadata + byte accessors), or `null`.\n   *\n   * RANGE SEMANTICS: with `options.range`, return only that slice — the bytes\n   * a `206` response carries — and report it back as `range`. `size` still\n   * reports the whole object, so the caller can build `Content-Range` without\n   * a second `head`. The reported `length` is what was actually served: a\n   * requested `length` past the end clamps. An `offset` at or past the end is\n   * a caller error, not a store one — the size is on the artifact record, so a\n   * serve route answers `416` before ever asking the store.\n   *\n   * Range support is part of the contract for any store that holds bytes (the\n   * conformance testkit asserts it): serving a whole file where a slice was\n   * asked for is what makes `<video>` seeking, and Safari playback at all,\n   * fail. A reference-only backend that stores no bytes skips `blobs`\n   * entirely rather than half-implementing it.\n   */\n  get: (key: string, options?: BlobGetOptions) => Promise<BlobObject | null>\n  /** Return only the metadata for `key`, or `null`. */\n  head: (key: string) => Promise<BlobRecord | null>\n  /** Remove the object at `key`. A no-op if absent. */\n  delete: (key: string) => Promise<void>\n  /**\n   * List objects, optionally filtered by `prefix`, in ascending key order.\n   *\n   * CURSOR SEMANTICS: `prefix` matches literally and case-sensitively (SQL\n   * backends must escape LIKE metacharacters, so `run_` matches only the exact\n   * bytes `run_`, not `_` as a wildcard). When `limit` is given and more keys\n   * match, the page is `truncated: true` with a `cursor`; passing that `cursor`\n   * back returns the strictly-following keys (keys `> cursor`). Cursor ordering\n   * is the same byte ordering as the sort, so paging visits every key exactly\n   * once with no gaps or repeats. `limit: 0` yields an empty, untruncated page\n   * with no cursor.\n   */\n  list: (options?: BlobListOptions) => Promise<BlobListPage>\n}\n\n/**\n * Sparse bag of **state** store keys — composition / validation only.\n *\n * **Not a public product shape.** Prefer the named chat shapes below\n * ({@link ChatTranscriptStores}, {@link ChatPersistenceStores},\n * {@link ChatWithInterruptsStores}). Locks are not included — use\n * `withLocks` from `@tanstack/ai`.\n *\n * @internal Exported from this module for generics; the package root does not\n * re-export this type — use a named shape or `AIPersistence<{ … }>` instead.\n */\nexport interface AIPersistenceStores {\n  messages?: MessageStore\n  runs?: RunStore\n  interrupts?: InterruptStore\n  metadata?: MetadataStore\n  generationRuns?: GenerationRunStore\n  artifacts?: ArtifactStore\n  blobs?: BlobStore\n}\n\n/**\n * Chat floor: durable transcript. `messages` is required.\n *\n * `runs` / `interrupts` / `metadata` remain optional. If `interrupts` is set,\n * `runs` is required (enforced by `withPersistence` / validators).\n */\nexport interface ChatTranscriptStores {\n  messages: MessageStore\n  runs?: RunStore\n  interrupts?: InterruptStore\n  metadata?: MetadataStore\n}\n\n/**\n * Full chat durability — all four state stores are present. This is what\n * `memoryPersistence()` returns, and the shape most adapters should declare.\n *\n * Backends that only need a transcript should use\n * {@link ChatTranscriptStores} instead.\n */\nexport interface ChatPersistenceStores {\n  messages: MessageStore\n  runs: RunStore\n  interrupts: InterruptStore\n  metadata: MetadataStore\n}\n\n/**\n * Chat with durable human-in-the-loop interrupts (and optional metadata).\n * Implies `runs` (interrupt records are run-scoped).\n *\n * Prefer {@link ChatPersistenceStores} when you also have metadata (packaged\n * backends). Use this when interrupts are required but metadata is not.\n */\nexport interface ChatWithInterruptsStores {\n  messages: MessageStore\n  runs: RunStore\n  interrupts: InterruptStore\n  metadata?: MetadataStore\n}\n\n/**\n * Persistence aggregate. Parameterize with a named store shape, or a sparse\n * map for composition (`defineAIPersistence` / `composePersistence`).\n *\n * Default is the sparse bag so untyped / dynamic bags still type-check;\n * prefer {@link ChatTranscriptPersistence} or {@link ChatPersistence} at\n * call sites.\n */\nexport interface AIPersistence<\n  TStores extends AIPersistenceStores = AIPersistenceStores,\n> {\n  stores: ExactStoreKeys<TStores>\n}\n\n/** {@link AIPersistence} for {@link ChatTranscriptStores}. */\nexport type ChatTranscriptPersistence = AIPersistence<ChatTranscriptStores>\n\n/** {@link AIPersistence} for {@link ChatPersistenceStores}. */\nexport type ChatPersistence = AIPersistence<ChatPersistenceStores>\n\n/** {@link AIPersistence} for {@link ChatWithInterruptsStores}. */\nexport type ChatWithInterruptsPersistence =\n  AIPersistence<ChatWithInterruptsStores>\n\ntype StoreKey = keyof AIPersistenceStores\ntype ExactStoreKeys<TStores> =\n  Exclude<keyof TStores, StoreKey> extends never\n    ? TStores\n    : TStores & Record<Exclude<keyof TStores, StoreKey>, never>\n\nexport type AIPersistenceOverrides = {\n  [TKey in StoreKey]?: AIPersistenceStores[TKey] | false\n}\n\ntype BaseStoreValue<\n  TBase extends AIPersistenceStores,\n  TKey extends StoreKey,\n> = TKey extends keyof TBase ? TBase[TKey] : never\n\ntype OverrideStoreValue<\n  TOverrides extends AIPersistenceOverrides,\n  TKey extends StoreKey,\n> = TKey extends keyof TOverrides ? TOverrides[TKey] : never\n\ntype ResolvedStoreValue<\n  TBase extends AIPersistenceStores,\n  TOverrides extends AIPersistenceOverrides,\n  TKey extends StoreKey,\n> = TKey extends keyof TOverrides\n  ?\n      | Exclude<OverrideStoreValue<TOverrides, TKey>, false | undefined>\n      | (undefined extends OverrideStoreValue<TOverrides, TKey>\n          ? Exclude<BaseStoreValue<TBase, TKey>, undefined>\n          : never)\n  : Exclude<BaseStoreValue<TBase, TKey>, undefined>\n\ntype BaseStoreIsRequired<\n  TBase extends AIPersistenceStores,\n  TKey extends StoreKey,\n> = TKey extends keyof TBase\n  ? object extends Pick<TBase, TKey>\n    ? false\n    : true\n  : false\n\ntype ResolvedStoreIsRequired<\n  TBase extends AIPersistenceStores,\n  TOverrides extends AIPersistenceOverrides,\n  TKey extends StoreKey,\n> = TKey extends keyof TOverrides\n  ? false extends OverrideStoreValue<TOverrides, TKey>\n    ? false\n    : undefined extends OverrideStoreValue<TOverrides, TKey>\n      ? BaseStoreIsRequired<TBase, TKey>\n      : true\n  : BaseStoreIsRequired<TBase, TKey>\n\ntype ResolvedRequiredKeys<\n  TBase extends AIPersistenceStores,\n  TOverrides extends AIPersistenceOverrides,\n> = {\n  [TKey in StoreKey]-?: [ResolvedStoreValue<TBase, TOverrides, TKey>] extends [\n    never,\n  ]\n    ? never\n    : ResolvedStoreIsRequired<TBase, TOverrides, TKey> extends true\n      ? TKey\n      : never\n}[StoreKey]\n\ntype ResolvedOptionalKeys<\n  TBase extends AIPersistenceStores,\n  TOverrides extends AIPersistenceOverrides,\n> = {\n  [TKey in StoreKey]-?: [ResolvedStoreValue<TBase, TOverrides, TKey>] extends [\n    never,\n  ]\n    ? never\n    : ResolvedStoreIsRequired<TBase, TOverrides, TKey> extends true\n      ? never\n      : TKey\n}[StoreKey]\n\ntype Simplify<T> = { [TKey in keyof T]: T[TKey] }\n\nexport type ComposedAIPersistenceStores<\n  TBase extends AIPersistenceStores,\n  TOverrides extends AIPersistenceOverrides,\n> = Simplify<\n  {\n    [TKey in ResolvedRequiredKeys<TBase, TOverrides>]: ResolvedStoreValue<\n      TBase,\n      TOverrides,\n      TKey\n    >\n  } & {\n    [TKey in ResolvedOptionalKeys<TBase, TOverrides>]?: ResolvedStoreValue<\n      TBase,\n      TOverrides,\n      TKey\n    >\n  }\n>\n\nconst storeKeys = [\n  'messages',\n  'runs',\n  'generationRuns',\n  'interrupts',\n  'metadata',\n  'artifacts',\n  'blobs',\n] satisfies Array<StoreKey>\n\nconst storeKeySet = new Set<string>(storeKeys)\n\nfunction assertKnownStoreKeys(stores: object, location: string): void {\n  for (const key of Object.keys(stores)) {\n    if (!storeKeySet.has(key)) {\n      throw new Error(`Unknown AIPersistence ${location} key: ${key}`)\n    }\n  }\n}\n\nexport function validatePersistenceStoreKeys(persistence: AIPersistence): void {\n  assertKnownStoreKeys(persistence.stores, 'store')\n}\n\n/**\n * Chat middleware entrypoint rules:\n * - `messages` is required (chat persistence means a durable transcript)\n * - `interrupts` requires `runs` (interrupt records are run-scoped)\n */\nexport function validateChatPersistenceStores(\n  persistence: AIPersistence,\n): void {\n  validatePersistenceStoreKeys(persistence)\n  if (!persistence.stores.messages) {\n    throw new Error('Chat persistence requires stores.messages.')\n  }\n  if (persistence.stores.interrupts && !persistence.stores.runs) {\n    throw new Error('Chat persistence stores.interrupts requires stores.runs.')\n  }\n}\n\n/**\n * Generation middleware entrypoint rule: `generationRuns` is required (the\n * generation run lifecycle is keyed on its own `runId`, not a chat conversation\n * `threadId`). When artifact persistence is used, `artifacts` and `blobs` must\n * be provided together.\n */\nexport function validateGenerationPersistenceStores(\n  persistence: AIPersistence,\n): void {\n  validatePersistenceStoreKeys(persistence)\n  const hasArtifacts = persistence.stores.artifacts !== undefined\n  const hasBlobs = persistence.stores.blobs !== undefined\n  if (hasArtifacts !== hasBlobs) {\n    throw new Error(\n      'Generation artifact persistence requires both stores.artifacts and stores.blobs.',\n    )\n  }\n  if (!persistence.stores.generationRuns) {\n    throw new Error('Generation persistence requires stores.generationRuns.')\n  }\n}\n\n/**\n * Server hydrate entrypoint rule: `messages` is required.\n */\nexport function validateReconstructChatStores(\n  persistence: AIPersistence,\n): void {\n  validatePersistenceStoreKeys(persistence)\n  if (!persistence.stores.messages) {\n    throw new Error('reconstructChat requires stores.messages.')\n  }\n}\n\n/**\n * Server hydrate entrypoint rule for generation: `generationRuns` is required.\n * The run store resolves the latest generation for a thread (or a specific run\n * id), so a server-authoritative client can hydrate the last generation's\n * status, result, and artifact refs on load.\n */\nexport function validateReconstructGenerationStores(\n  persistence: AIPersistence,\n): void {\n  validatePersistenceStoreKeys(persistence)\n  if (!persistence.stores.generationRuns) {\n    throw new Error('reconstructGeneration requires stores.generationRuns.')\n  }\n}\n\nexport function defineAIPersistence<TStores extends AIPersistenceStores>(\n  persistence: AIPersistence<ExactStoreKeys<TStores>>,\n): AIPersistence<TStores> {\n  validatePersistenceStoreKeys(persistence)\n  return persistence\n}\n\nexport function composePersistence<\n  TBase extends AIPersistenceStores,\n  TOverrides extends AIPersistenceOverrides,\n>(\n  base: AIPersistence<TBase>,\n  config: {\n    overrides: ExactStoreKeys<TOverrides>\n  },\n): AIPersistence<ComposedAIPersistenceStores<TBase, TOverrides>>\nexport function composePersistence(\n  base: AIPersistence,\n  config: { overrides: AIPersistenceOverrides },\n): AIPersistence {\n  validatePersistenceStoreKeys(base)\n  assertKnownStoreKeys(config.overrides, 'override')\n\n  const stores: AIPersistenceStores = { ...base.stores }\n  for (const key of storeKeys) {\n    if (!Object.prototype.hasOwnProperty.call(config.overrides, key)) continue\n    const override = config.overrides[key]\n    if (override === false) {\n      delete stores[key]\n    } else if (override !== undefined) {\n      setStore(stores, key, override)\n    }\n  }\n  return { stores }\n}\n\nfunction setStore<TKey extends StoreKey>(\n  stores: AIPersistenceStores,\n  key: TKey,\n  value: NonNullable<AIPersistenceStores[TKey]>,\n): void {\n  stores[key] = value\n}\n"],"mappings":";;;AAuUA,SAAgB,mBAAmB,OAAmC;CACpE,OAAO;AACT;;AAEA,SAAgB,qBAAqB,OAAuC;CAC1E,OAAO;AACT;;AAEA,SAAgB,oBAAoB,OAAqC;CACvE,OAAO;AACT;;AAEA,SAAgB,yBACd,OACoB;CACpB,OAAO;AACT;;AAEA,SAAgB,oBAAoB,OAAqC;CACvE,OAAO;AACT;;AAEA,SAAgB,gBAAgB,OAA6B;CAC3D,OAAO;AACT;AA0YA,IAAM,YAAY;CAChB;CACA;CACA;CACA;CACA;CACA;CACA;AACF;AAEA,IAAM,cAAc,IAAI,IAAY,SAAS;AAE7C,SAAS,qBAAqB,QAAgB,UAAwB;CACpE,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAClC,IAAI,CAAC,YAAY,IAAI,GAAG,GACtB,MAAM,IAAI,MAAM,yBAAyB,SAAS,QAAQ,KAAK;AAGrE;AAEA,SAAgB,6BAA6B,aAAkC;CAC7E,qBAAqB,YAAY,QAAQ,OAAO;AAClD;;;;;;AAOA,SAAgB,8BACd,aACM;CACN,6BAA6B,WAAW;CACxC,IAAI,CAAC,YAAY,OAAO,UACtB,MAAM,IAAI,MAAM,4CAA4C;CAE9D,IAAI,YAAY,OAAO,cAAc,CAAC,YAAY,OAAO,MACvD,MAAM,IAAI,MAAM,0DAA0D;AAE9E;;;;;;;AAQA,SAAgB,oCACd,aACM;CACN,6BAA6B,WAAW;CAGxC,IAFqB,YAAY,OAAO,cAAc,KAAA,OACrC,YAAY,OAAO,UAAU,KAAA,IAE5C,MAAM,IAAI,MACR,kFACF;CAEF,IAAI,CAAC,YAAY,OAAO,gBACtB,MAAM,IAAI,MAAM,wDAAwD;AAE5E;;;;AAKA,SAAgB,8BACd,aACM;CACN,6BAA6B,WAAW;CACxC,IAAI,CAAC,YAAY,OAAO,UACtB,MAAM,IAAI,MAAM,2CAA2C;AAE/D;;;;;;;AAQA,SAAgB,oCACd,aACM;CACN,6BAA6B,WAAW;CACxC,IAAI,CAAC,YAAY,OAAO,gBACtB,MAAM,IAAI,MAAM,uDAAuD;AAE3E;AAEA,SAAgB,oBACd,aACwB;CACxB,6BAA6B,WAAW;CACxC,OAAO;AACT;AAWA,SAAgB,mBACd,MACA,QACe;CACf,6BAA6B,IAAI;CACjC,qBAAqB,OAAO,WAAW,UAAU;CAEjD,MAAM,SAA8B,EAAE,GAAG,KAAK,OAAO;CACrD,KAAK,MAAM,OAAO,WAAW;EAC3B,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,WAAW,GAAG,GAAG;EAClE,MAAM,WAAW,OAAO,UAAU;EAClC,IAAI,aAAa,OACf,OAAO,OAAO;OACT,IAAI,aAAa,KAAA,GACtB,SAAS,QAAQ,KAAK,QAAQ;CAElC;CACA,OAAO,EAAE,OAAO;AAClB;AAEA,SAAS,SACP,QACA,KACA,OACM;CACN,OAAO,OAAO;AAChB"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@tanstack/ai-persistence",
+  "version": "0.0.0",
+  "description": "Composable state persistence for TanStack AI messages, runs, interrupts, metadata, and locks.",
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-persistence"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "tanstack-intent",
+    "persistence",
+    "durable",
+    "resume",
+    "chat-history"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./testkit": {
+      "types": "./dist/esm/testkit/conformance.d.ts",
+      "import": "./dist/esm/testkit/conformance.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "skills"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "test:oxlint": "oxlint src --type-aware"
+  },
+  "dependencies": {
+    "@tanstack/ai-utils": "workspace:*"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "vitest": "^4.1.10"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14",
+    "vitest": "^4.1.10"
+  }
+}

package/skills/ai-persistence/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: ai-persistence
+description: >
+  Durability and state persistence for TanStack AI chats with
+  @tanstack/ai-persistence. Routes to server chat persistence (withPersistence),
+  client persistence (localStorage/IndexedDB), the store contracts, and adapter
+  recipes. Distinguishes delivery durability (resumable streams) from
+  conversation state. Use when conversations must survive reloads, multi-device,
+  approvals, or server restarts — NOT for stream reconnect alone.
+type: core
+library: tanstack-ai
+library_version: '0.0.0'
+sources:
+  - 'TanStack/ai:docs/persistence/overview.md'
+  - 'TanStack/ai:docs/persistence/chat-persistence.md'
+  - 'TanStack/ai:docs/persistence/client-persistence.md'
+  - 'TanStack/ai:docs/persistence/controls.md'
+  - 'TanStack/ai:docs/persistence/build-your-own-adapter.md'
+---
+
+# TanStack AI Persistence
+
+> Builds on the `ai-core` skill in `@tanstack/ai`, and usually
+> `ai-core/chat-experience`.
+
+TanStack AI splits **delivery durability** from **state persistence**. They
+share no code and solve different problems.
+
+| Layer                   | Answers                             | Package / API                                                                                |
+| ----------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- |
+| **Delivery durability** | Reconnect to a stream still running | `memoryStream` / `@tanstack/ai-durable-stream` on the response; see resumable streams docs   |
+| **State persistence**   | What is the conversation, later?    | Client `persistence` on `useChat` + server `withPersistence` from `@tanstack/ai-persistence` |
+
+A replayable stream is **not** a saved conversation. A saved conversation is
+**not** a live stream. Production apps often use both.
+
+## Persistence is a contract, not a database
+
+`@tanstack/ai-persistence` ships the **store interfaces**, the middleware that
+drives them, an in-memory reference backend, and a conformance testkit. It does
+**not** ship a backend for your database, and you do not need one: implement the
+stores against whatever you already run — Postgres, SQLite, D1, Mongo — and hand
+the result to `withPersistence`. The core never inspects your tables.
+
+| Ships in the package                                                        | What it is                                                  |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `MessageStore` / `RunStore` / `InterruptStore` / `MetadataStore`            | The four **chat** state contracts                           |
+| `GenerationRunStore` / `ArtifactStore` / `BlobStore`                        | The **generation** contracts (job lifecycle + bytes)        |
+| `withPersistence` / `withGenerationPersistence`                             | Chat + generation middleware                                |
+| `memoryPersistence()`                                                       | In-process reference backend, all seven stores (dev, tests) |
+| `reconstructChat` / `reconstructGeneration`                                 | Server hydrate route helpers (chat / generation)            |
+| `retrieveArtifact` / `retrieveBlob` / `resolveArtifactBlobKey`              | Serve persisted generation-media bytes back                 |
+| `LockStore` / `withLocks` / `InMemoryLockStore` (from `@tanstack/ai/locks`) | Coordination, **not** this package — see ai-core/locks      |
+| `@tanstack/ai-persistence/testkit`                                          | `runPersistenceConformance` gate (chat state stores)        |
+
+**Chat vs generation stores.** Chat persistence keys on `threadId` and uses
+`messages` + optional `runs` / `interrupts` / `metadata`. Generation persistence
+keys on its own `runId` and uses `generationRuns` (required by `withGenerationPersistence`) plus an
+optional `artifacts` + `blobs` **pair** — provide both or neither — to store the
+generated media bytes at blob key `artifacts/<runId>/<artifactId>`. A generation
+run's identity is its own `runId`, but `threadId` is **required** on the record:
+it is the stable slot successive runs fill, and `findLatestForThread` — the only
+query that hydrates a run — keys on it. To
+build the R2/D1-backed byte stores for a Worker, see
+**ai-persistence/build-cloudflare-artifact-store**.
+
+**Where bytes land.** Default blob key is `artifacts/<runId>/<artifactId>`. Pass
+`storageKey` to `withGenerationPersistence` for your own folder structure — it
+receives `{ artifactId, runId, threadId, role, activity, path, mimeType, name }`
+and returns the key. Server-side only (a browser-supplied key is path traversal +
+cross-tenant writes). The resolved key is recorded on `ArtifactRecord.blobKey`
+because it is no longer derivable; read through `resolveArtifactBlobKey(record)`,
+never by recomputing. Records predating `blobKey` fall back to the default
+convention — which is why that convention can never be changed retroactively. A
+non-unique key overwrites, so include `artifactId` unless that is intended.
+
+**Byte storage stores generated output, not prompt URLs.** Provider result URLs
+expire, so they are downloaded and kept. Prompt media sent as base64
+(`source: { type: 'data' }`) is stored too. Prompt media sent as a **URL** is
+NOT fetched — that URL is caller-supplied, so downloading it server-side is an
+SSRF vector, and the bytes are redundant. Apps that genuinely need a durable
+copy opt in with `allowInputUrl`, a predicate so the check can't be skipped:
+`allowInputUrl: ({ url }) => url.hostname.endsWith('.cdn.example.com')`. Never
+suggest `() => true`. All artifact fetches are http/https-only, timed out
+(`artifactFetchTimeoutMs`) and size-capped (`maxArtifactBytes`); input fetches
+also block loopback/private/link-local hosts and refuse redirects. `artifactFetch`
+injects the `fetch`, for routing through an egress-restricted proxy.
+
+Two related route-level rules: a `GET` that serves artifact bytes by id MUST
+authorize the caller against `ArtifactRecord.threadId` before serving (404, not
+403, so valid ids aren't confirmed), and `reconstructGeneration` MUST be given
+`authorize` on any multi-user route. Both take ids straight from the caller.
+
+## Sub-skills
+
+| Need to...                                      | Read                                                  |
+| ----------------------------------------------- | ----------------------------------------------------- |
+| Wire server-side chat history, runs, interrupts | ai-persistence/server/SKILL.md                        |
+| Survive reloads in the browser                  | ai-core/client-persistence/SKILL.md in `@tanstack/ai` |
+| Implement the store interfaces for your DB      | ai-persistence/stores/SKILL.md                        |
+| Multi-instance locks (separate from state)      | ai-core/locks/SKILL.md in `@tanstack/ai`              |
+
+Adding persistence to an app? Pick the recipe that matches what it already
+runs — each one writes a single `chat-persistence.ts` against the app's
+existing database client and schema:
+
+| The app runs...                                      | Read                                                    |
+| ---------------------------------------------------- | ------------------------------------------------------- |
+| Drizzle ORM (SQLite / Postgres / MySQL)              | ai-persistence/build-drizzle-adapter/SKILL.md           |
+| Prisma                                               | ai-persistence/build-prisma-adapter/SKILL.md            |
+| Cloudflare Workers + D1 (± Durable Object locks)     | ai-persistence/build-cloudflare-adapter/SKILL.md        |
+| Cloudflare Workers + R2/D1 for generated media bytes | ai-persistence/build-cloudflare-artifact-store/SKILL.md |
+| Anything else — raw `pg`, Kysely, SQLite, Mongo      | ai-persistence/build-custom-adapter/SKILL.md            |
+
+## State persistence has two halves
+
+| Half       | Stores                                          | Survives                         | Typical use                              |
+| ---------- | ----------------------------------------------- | -------------------------------- | ---------------------------------------- |
+| **Client** | transcript ± resume pointer in browser storage  | reload / tab close (per browser) | SPA restore, offline-first               |
+| **Server** | messages, runs, interrupts, metadata in your DB | restart + multi-device           | authoritative history, durable approvals |
+
+They are independent. Use either alone or both.
+
+## Identity: `threadId` and `Scope`
+
+Server stores key on **`threadId`** (same as `chat({ threadId })` /
+`ChatMiddlewareContext.threadId` / `Scope.threadId` from `@tanstack/ai`).
+
+- Store methods take bare `threadId` strings for adapter simplicity.
+- Multi-user isolation is **your** job: derive `userId` / `tenantId` from
+  session server-side; authorize before load/save / `reconstructChat`.
+- Never treat a client-supplied thread id alone as ownership — ids are guessable.
+
+## Authoritative-history contract
+
+When both halves run, ownership per turn is decided by request `messages`:
+
+| Client sends             | Meaning                           | On finish                           |
+| ------------------------ | --------------------------------- | ----------------------------------- |
+| **Non-empty** `messages` | Full transcript (source of truth) | Server **overwrites** stored thread |
+| **Empty** `messages`     | Continue from server copy         | Server **loads** stored thread      |
+
+Never post a delta as `messages` — that wipes history down to the delta.
+
+**Client-authoritative:** always send full transcript; browser is truth, server mirrors.  
+**Server-authoritative:** send empty `messages` (or hydrate via server load); server is truth, multi-device works.
+
+## Recommended production stack
+
+1. **Client:** `persistence: true` — server-authoritative, no client cache.
+2. **Server:** `withPersistence(backend)` — messages + runs + interrupts.
+3. **Route:** delivery durability if mid-stream reconnect matters.
+4. **Optional:** `withLocks(distributedLockStore)` from `@tanstack/ai/locks` when other middleware needs multi-instance coordination (not part of the state bag).
+
+## Minimal end-to-end sketch
+
+**Server**
+
+```ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withPersistence } from '@tanstack/ai-persistence'
+// Your adapter — see ai-persistence/stores.
+import { persistence } from './persistence'
+
+export async function POST(request: Request) {
+  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(persistence)],
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+**Client (server-authoritative)**
+
+```tsx
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+
+function Chat({ threadId }: { threadId: string }) {
+  const { messages, sendMessage } = useChat({
+    threadId,
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: true,
+  })
+  // ...
+}
+```
+
+With `persistence: true`, the client caches nothing and hydrates the transcript
+from the server on mount (thread id is the key). Pair with a server load path
+such as `reconstructChat` for the GET.
+
+## Critical rules
+
+1. **Not Vercel AI SDK.** Persistence is `@tanstack/ai-persistence` + middleware, not Vercel `useChat` storage hacks.
+2. **`saveThread` is full overwrite**, never append.
+3. **`createOrResume` is insert-if-absent** for the same `runId`.
+4. **Interrupt `create` is insert-if-absent** — never clobber resolved → pending.
+5. **Locks ≠ state.** Import `withLocks` from `@tanstack/ai/locks`. Sandbox resume is a sandbox-package concern — not a `stores` key. `stores` accepts only `messages`, `runs`, `interrupts`, `metadata`.
+6. **You own the schema.** No package invents migrations for you.
+7. **Run the conformance testkit** against any adapter you write.
+8. **Authorize thread access** at the route boundary.
+
+## Cross-references
+
+- **ai-core/chat-experience** (`@tanstack/ai`) — `useChat`, SSE, client `persistence` option overview
+- **ai-core/middleware** (`@tanstack/ai`) — middleware hooks; `withPersistence` is a ChatMiddleware
+- **Resumable streams docs** — delivery durability only