You want server-side chat persistence, but your data lives in your own database: Postgres behind Prisma, a SQLite file, Cloudflare D1, Mongo, whatever you already run. TanStack AI does not ship a backend for your exact stack, and you would rather not add one more service just for chat history.
You do not need a packaged backend. Server persistence is a small set of plain store interfaces from @tanstack/ai-persistence. Implement the ones you want against your database, hand the result to withPersistence, and you are done. The core never inspects your tables, so the schema is yours to shape.
This guide builds a complete SQLite adapter on Node's built-in node:sqlite, end to end, then shows how to map the same contracts onto a database schema you already have. The runnable version of everything here lives in the examples/ts-react-chat app (src/lib/sqlite-persistence.ts).
There are seven stores and you almost certainly do not want all of them. Each one switches on a single capability. Find the column for what you are building and implement the rows marked ✅:
| Store | Save the transcript | Rejoin a run after reload | Durable approvals | App key/value | Persist generation runs | Keep generated files |
|---|---|---|---|---|---|---|
| messages | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| runs | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
| interrupts | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
| metadata | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| generationRuns | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| artifacts | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| blobs | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
How to read it:
Two pairs cannot be split:
So the smallest adapter worth shipping is a single messages store, and the common production shape is messages + runs + interrupts. The guide below builds them in that order.
An adapter is an object with a stores map:
import type { ChatTranscriptPersistence } from '@tanstack/ai-persistence'
// `messages` and `runs` are your store implementations (built below); import
// them from your own modules.
import { messages } from './message-store'
import { runs } from './run-store'
const persistence: ChatTranscriptPersistence = {
stores: { messages, runs },
}import type { ChatTranscriptPersistence } from '@tanstack/ai-persistence'
// `messages` and `runs` are your store implementations (built below); import
// them from your own modules.
import { messages } from './message-store'
import { runs } from './run-store'
const persistence: ChatTranscriptPersistence = {
stores: { messages, runs },
}Each store is independent, so provide only the ones you need.
For chat:
For generation:
The middleware turns on behavior for whatever stores it finds, so a messages-only adapter is a valid adapter.
Those seven — messages, runs, interrupts, metadata, generationRuns, artifacts, blobs — are the only keys stores accepts; anything else throws Unknown AIPersistence store key at construction. Need a mutex across instances? That is withLocks; see Locks.
Type each store with its define*Store helper, as the sections below do. There is one per store:
Each checks the object against the contract inline (autocomplete, no : MessageStore annotation) and composes into defineAIPersistence, which tracks exact presence:
Annotate the value with a named shape:
Every method signature and invariant is in the store interface reference at the end of this page. The invariants (idempotent creates, insert-if-absent, ordered listings) are what the shared conformance suite checks, and getting one wrong is the usual source of subtle bugs.
The records the stores hold form a small schema. The thread is not a table of its own — it exists as the thread_id key the other records hang off — and metadata is independent of all of it (its identity is (namespace, key)). Note the asymmetry on the generation side. A chat run belongs to a thread, and its own run_id is secondary. A generation run is keyed by its own run_id first, and its thread_id names the slot the run fills, which is what findLatestForThread hydrates by:
erDiagram
MESSAGES ||--o{ RUN : "thread_id — a thread has many runs"
RUN ||--o{ INTERRUPT : "run_id — a run may pause on interrupts"
MESSAGES ||..o{ GENERATION_RUN : "thread_id, the slot a run fills"
GENERATION_RUN ||--o{ ARTIFACT : "run_id — a run produces artifacts"
ARTIFACT ||--|| BLOB : "blob_key — the bytes"
MESSAGES {
string thread_id PK
json messages_json "full transcript, overwritten on save"
}
RUN {
string run_id PK
string thread_id
string status "running | completed | failed | interrupted"
int started_at
int finished_at
}
INTERRUPT {
string interrupt_id PK
string run_id
string thread_id
string status "pending | resolved | cancelled"
int requested_at
}
GENERATION_RUN {
string run_id PK
string thread_id "the slot this run fills"
string activity "image | audio | tts | video | transcription"
string status "running | completed | failed | interrupted"
}
ARTIFACT {
string artifact_id PK
string run_id
string blob_key "where the bytes live"
string mime_type
int size
}
BLOB {
string key PK
blob bytes
}
Four tables. JSON payloads are stored as text (SQLite has no JSON column type), timestamps as integers (epoch milliseconds), everything keyed the way the store methods look records up.
CREATE TABLE IF NOT EXISTS messages (
thread_id text PRIMARY KEY NOT NULL,
messages_json text NOT NULL
);
CREATE TABLE IF NOT EXISTS 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,
usage_json text
);
CREATE TABLE IF NOT EXISTS 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 TABLE IF NOT EXISTS metadata (
scope text NOT NULL,
key text NOT NULL,
value_json text NOT NULL,
PRIMARY KEY (scope, key)
);CREATE TABLE IF NOT EXISTS messages (
thread_id text PRIMARY KEY NOT NULL,
messages_json text NOT NULL
);
CREATE TABLE IF NOT EXISTS 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,
usage_json text
);
CREATE TABLE IF NOT EXISTS 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 TABLE IF NOT EXISTS metadata (
scope text NOT NULL,
key text NOT NULL,
value_json text NOT NULL,
PRIMARY KEY (scope, key)
);Two contracts to hold:
import { DatabaseSync } from 'node:sqlite'
import { defineMessageStore } from '@tanstack/ai-persistence'
import type { ModelMessage } from '@tanstack/ai'
// `defineMessageStore` types the object inline against the contract — you get
// autocomplete and checking with no separate `: MessageStore` annotation.
function createMessageStore(db: DatabaseSync) {
const select = db.prepare(
'SELECT messages_json FROM messages WHERE thread_id = ?',
)
const upsert = db.prepare(
`INSERT INTO messages (thread_id, messages_json) VALUES (?, ?)
ON CONFLICT(thread_id) DO UPDATE SET messages_json = excluded.messages_json`,
)
return defineMessageStore({
async loadThread(threadId) {
const json = select.get(threadId)?.messages_json
// Unknown thread → [] (never null). `node:sqlite` types columns as a
// SQL-value union, so narrow to string before parsing (no cast).
if (typeof json !== 'string') return []
const parsed: Array<ModelMessage> = JSON.parse(json)
return parsed
},
async saveThread(threadId, messages) {
upsert.run(threadId, JSON.stringify(messages))
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineMessageStore } from '@tanstack/ai-persistence'
import type { ModelMessage } from '@tanstack/ai'
// `defineMessageStore` types the object inline against the contract — you get
// autocomplete and checking with no separate `: MessageStore` annotation.
function createMessageStore(db: DatabaseSync) {
const select = db.prepare(
'SELECT messages_json FROM messages WHERE thread_id = ?',
)
const upsert = db.prepare(
`INSERT INTO messages (thread_id, messages_json) VALUES (?, ?)
ON CONFLICT(thread_id) DO UPDATE SET messages_json = excluded.messages_json`,
)
return defineMessageStore({
async loadThread(threadId) {
const json = select.get(threadId)?.messages_json
// Unknown thread → [] (never null). `node:sqlite` types columns as a
// SQL-value union, so narrow to string before parsing (no cast).
if (typeof json !== 'string') return []
const parsed: Array<ModelMessage> = JSON.parse(json)
return parsed
},
async saveThread(threadId, messages) {
upsert.run(threadId, JSON.stringify(messages))
},
})
}The methods are async, so node:sqlite (a synchronous driver) needs no Promise.resolve wrapper: async promotes the returned value to a promise, and a method that returns nothing resolves to void. On an async driver, await the query instead.
Two contracts to hold:
import { DatabaseSync } from 'node:sqlite'
import { defineRunStore } from '@tanstack/ai-persistence'
import type { RunRecord, RunStatus } from '@tanstack/ai-persistence'
// The `status` column is text; validate it back into the union (no cast).
function toRunStatus(value: unknown): RunStatus {
switch (value) {
case 'running':
case 'completed':
case 'failed':
case 'interrupted':
return value
default:
throw new TypeError(`Unexpected run status: ${String(value)}`)
}
}
// `node:sqlite` types columns as a SQL-value union, so coerce/narrow each field
// (String / Number / typeof) rather than casting the whole row.
function mapRun(row: Record<string, unknown>): RunRecord {
return {
runId: String(row.run_id),
threadId: String(row.thread_id),
status: toRunStatus(row.status),
startedAt: Number(row.started_at),
...(row.finished_at != null ? { finishedAt: Number(row.finished_at) } : {}),
...(typeof row.error === 'string' ? { error: row.error } : {}),
...(typeof row.usage_json === 'string'
? { usage: JSON.parse(row.usage_json) }
: {}),
}
}
function createRunStore(db: DatabaseSync) {
const select = db.prepare('SELECT * FROM runs WHERE run_id = ?')
const insert = db.prepare(
`INSERT INTO runs (run_id, thread_id, status, started_at) VALUES (?, ?, ?, ?)
ON CONFLICT(run_id) DO NOTHING`,
)
const active = db.prepare(
`SELECT * FROM runs WHERE thread_id = ? AND status = 'running'
ORDER BY started_at DESC LIMIT 1`,
)
return defineRunStore({
async createOrResume(input) {
const existing = select.get(input.runId)
if (existing) return mapRun(existing)
const status: RunStatus = input.status ?? 'running'
insert.run(input.runId, input.threadId, status, input.startedAt)
return {
runId: input.runId,
threadId: input.threadId,
status,
startedAt: input.startedAt,
}
},
async update(runId, patch) {
const sets: Array<string> = []
const params: Array<string | number> = []
if (patch.status !== undefined) {
sets.push('status = ?')
params.push(patch.status)
}
if (patch.finishedAt !== undefined) {
sets.push('finished_at = ?')
params.push(patch.finishedAt)
}
if (patch.error !== undefined) {
sets.push('error = ?')
params.push(patch.error)
}
if (patch.usage !== undefined) {
sets.push('usage_json = ?')
params.push(JSON.stringify(patch.usage))
}
if (sets.length === 0) return
params.push(runId)
db.prepare(`UPDATE runs SET ${sets.join(', ')} WHERE run_id = ?`).run(
...params,
)
},
async get(runId) {
const row = select.get(runId)
return row ? mapRun(row) : null
},
// The most recent still-running run for a thread. `reconstructChat` calls
// this so a hydrating client (a reload, another device, or switching back to
// a generating thread) learns there is a live run and tails it. Stub it to
// null and the thread always looks idle on hydrate: the transcript restores,
// but a reply that was mid-stream never resumes.
async findActiveRun(threadId) {
const row = active.get(threadId)
return row ? mapRun(row) : null
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineRunStore } from '@tanstack/ai-persistence'
import type { RunRecord, RunStatus } from '@tanstack/ai-persistence'
// The `status` column is text; validate it back into the union (no cast).
function toRunStatus(value: unknown): RunStatus {
switch (value) {
case 'running':
case 'completed':
case 'failed':
case 'interrupted':
return value
default:
throw new TypeError(`Unexpected run status: ${String(value)}`)
}
}
// `node:sqlite` types columns as a SQL-value union, so coerce/narrow each field
// (String / Number / typeof) rather than casting the whole row.
function mapRun(row: Record<string, unknown>): RunRecord {
return {
runId: String(row.run_id),
threadId: String(row.thread_id),
status: toRunStatus(row.status),
startedAt: Number(row.started_at),
...(row.finished_at != null ? { finishedAt: Number(row.finished_at) } : {}),
...(typeof row.error === 'string' ? { error: row.error } : {}),
...(typeof row.usage_json === 'string'
? { usage: JSON.parse(row.usage_json) }
: {}),
}
}
function createRunStore(db: DatabaseSync) {
const select = db.prepare('SELECT * FROM runs WHERE run_id = ?')
const insert = db.prepare(
`INSERT INTO runs (run_id, thread_id, status, started_at) VALUES (?, ?, ?, ?)
ON CONFLICT(run_id) DO NOTHING`,
)
const active = db.prepare(
`SELECT * FROM runs WHERE thread_id = ? AND status = 'running'
ORDER BY started_at DESC LIMIT 1`,
)
return defineRunStore({
async createOrResume(input) {
const existing = select.get(input.runId)
if (existing) return mapRun(existing)
const status: RunStatus = input.status ?? 'running'
insert.run(input.runId, input.threadId, status, input.startedAt)
return {
runId: input.runId,
threadId: input.threadId,
status,
startedAt: input.startedAt,
}
},
async update(runId, patch) {
const sets: Array<string> = []
const params: Array<string | number> = []
if (patch.status !== undefined) {
sets.push('status = ?')
params.push(patch.status)
}
if (patch.finishedAt !== undefined) {
sets.push('finished_at = ?')
params.push(patch.finishedAt)
}
if (patch.error !== undefined) {
sets.push('error = ?')
params.push(patch.error)
}
if (patch.usage !== undefined) {
sets.push('usage_json = ?')
params.push(JSON.stringify(patch.usage))
}
if (sets.length === 0) return
params.push(runId)
db.prepare(`UPDATE runs SET ${sets.join(', ')} WHERE run_id = ?`).run(
...params,
)
},
async get(runId) {
const row = select.get(runId)
return row ? mapRun(row) : null
},
// The most recent still-running run for a thread. `reconstructChat` calls
// this so a hydrating client (a reload, another device, or switching back to
// a generating thread) learns there is a live run and tails it. Stub it to
// null and the thread always looks idle on hydrate: the transcript restores,
// but a reply that was mid-stream never resumes.
async findActiveRun(threadId) {
const row = active.get(threadId)
return row ? mapRun(row) : null
},
})
}update builds its SET list from only the fields present in the patch, so an empty patch touches nothing and a partial patch leaves other columns alone. Map each row back with a small helper that omits absent optional fields and parses the JSON columns.
create is insert-if-absent: a duplicate interrupt id must never overwrite an interrupt that was already resolved. Every list* method returns records ordered by requested_at ascending, which the middleware relies on.
import { DatabaseSync } from 'node:sqlite'
import { defineInterruptStore } from '@tanstack/ai-persistence'
import type {
InterruptRecord,
InterruptStatus,
} from '@tanstack/ai-persistence'
function toInterruptStatus(value: unknown): InterruptStatus {
switch (value) {
case 'pending':
case 'resolved':
case 'cancelled':
return value
default:
throw new TypeError(`Unexpected interrupt status: ${String(value)}`)
}
}
function mapInterrupt(row: Record<string, unknown>): InterruptRecord {
return {
interruptId: String(row.interrupt_id),
runId: String(row.run_id),
threadId: String(row.thread_id),
status: toInterruptStatus(row.status),
requestedAt: Number(row.requested_at),
...(row.resolved_at != null ? { resolvedAt: Number(row.resolved_at) } : {}),
payload:
typeof row.payload_json === 'string' ? JSON.parse(row.payload_json) : {},
...(typeof row.response_json === 'string'
? { response: JSON.parse(row.response_json) }
: {}),
}
}
function createInterruptStore(db: DatabaseSync) {
const insert = db.prepare(
`INSERT INTO interrupts
(interrupt_id, run_id, thread_id, status, requested_at, payload_json, response_json)
VALUES (?, ?, ?, 'pending', ?, ?, ?)
ON CONFLICT(interrupt_id) DO NOTHING`,
)
const resolveRow = db.prepare(
`UPDATE interrupts SET status = 'resolved', resolved_at = ?, response_json = ?
WHERE interrupt_id = ?`,
)
const cancelRow = db.prepare(
`UPDATE interrupts SET status = 'cancelled', resolved_at = ? WHERE interrupt_id = ?`,
)
const selectOne = db.prepare('SELECT * FROM interrupts WHERE interrupt_id = ?')
// Every listing is ORDER BY requested_at ASC — the middleware relies on it.
const byThread = db.prepare(
'SELECT * FROM interrupts WHERE thread_id = ? ORDER BY requested_at ASC',
)
const pendingByThread = db.prepare(
`SELECT * FROM interrupts WHERE thread_id = ? AND status = 'pending'
ORDER BY requested_at ASC`,
)
const byRun = db.prepare(
'SELECT * FROM interrupts WHERE run_id = ? ORDER BY requested_at ASC',
)
const pendingByRun = db.prepare(
`SELECT * FROM interrupts WHERE run_id = ? AND status = 'pending'
ORDER BY requested_at ASC`,
)
return defineInterruptStore({
async create(record) {
// Insert-if-absent: a duplicate id must never clobber an already-resolved
// interrupt back to pending.
insert.run(
record.interruptId,
record.runId,
record.threadId,
record.requestedAt,
JSON.stringify(record.payload),
record.response === undefined ? null : JSON.stringify(record.response),
)
},
async resolve(interruptId, response) {
resolveRow.run(
Date.now(),
response === undefined ? null : JSON.stringify(response),
interruptId,
)
},
async cancel(interruptId) {
cancelRow.run(Date.now(), interruptId)
},
async get(interruptId) {
const row = selectOne.get(interruptId)
return row ? mapInterrupt(row) : null
},
async list(threadId) {
return byThread.all(threadId).map(mapInterrupt)
},
async listPending(threadId) {
return pendingByThread.all(threadId).map(mapInterrupt)
},
async listByRun(runId) {
return byRun.all(runId).map(mapInterrupt)
},
async listPendingByRun(runId) {
return pendingByRun.all(runId).map(mapInterrupt)
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineInterruptStore } from '@tanstack/ai-persistence'
import type {
InterruptRecord,
InterruptStatus,
} from '@tanstack/ai-persistence'
function toInterruptStatus(value: unknown): InterruptStatus {
switch (value) {
case 'pending':
case 'resolved':
case 'cancelled':
return value
default:
throw new TypeError(`Unexpected interrupt status: ${String(value)}`)
}
}
function mapInterrupt(row: Record<string, unknown>): InterruptRecord {
return {
interruptId: String(row.interrupt_id),
runId: String(row.run_id),
threadId: String(row.thread_id),
status: toInterruptStatus(row.status),
requestedAt: Number(row.requested_at),
...(row.resolved_at != null ? { resolvedAt: Number(row.resolved_at) } : {}),
payload:
typeof row.payload_json === 'string' ? JSON.parse(row.payload_json) : {},
...(typeof row.response_json === 'string'
? { response: JSON.parse(row.response_json) }
: {}),
}
}
function createInterruptStore(db: DatabaseSync) {
const insert = db.prepare(
`INSERT INTO interrupts
(interrupt_id, run_id, thread_id, status, requested_at, payload_json, response_json)
VALUES (?, ?, ?, 'pending', ?, ?, ?)
ON CONFLICT(interrupt_id) DO NOTHING`,
)
const resolveRow = db.prepare(
`UPDATE interrupts SET status = 'resolved', resolved_at = ?, response_json = ?
WHERE interrupt_id = ?`,
)
const cancelRow = db.prepare(
`UPDATE interrupts SET status = 'cancelled', resolved_at = ? WHERE interrupt_id = ?`,
)
const selectOne = db.prepare('SELECT * FROM interrupts WHERE interrupt_id = ?')
// Every listing is ORDER BY requested_at ASC — the middleware relies on it.
const byThread = db.prepare(
'SELECT * FROM interrupts WHERE thread_id = ? ORDER BY requested_at ASC',
)
const pendingByThread = db.prepare(
`SELECT * FROM interrupts WHERE thread_id = ? AND status = 'pending'
ORDER BY requested_at ASC`,
)
const byRun = db.prepare(
'SELECT * FROM interrupts WHERE run_id = ? ORDER BY requested_at ASC',
)
const pendingByRun = db.prepare(
`SELECT * FROM interrupts WHERE run_id = ? AND status = 'pending'
ORDER BY requested_at ASC`,
)
return defineInterruptStore({
async create(record) {
// Insert-if-absent: a duplicate id must never clobber an already-resolved
// interrupt back to pending.
insert.run(
record.interruptId,
record.runId,
record.threadId,
record.requestedAt,
JSON.stringify(record.payload),
record.response === undefined ? null : JSON.stringify(record.response),
)
},
async resolve(interruptId, response) {
resolveRow.run(
Date.now(),
response === undefined ? null : JSON.stringify(response),
interruptId,
)
},
async cancel(interruptId) {
cancelRow.run(Date.now(), interruptId)
},
async get(interruptId) {
const row = selectOne.get(interruptId)
return row ? mapInterrupt(row) : null
},
async list(threadId) {
return byThread.all(threadId).map(mapInterrupt)
},
async listPending(threadId) {
return pendingByThread.all(threadId).map(mapInterrupt)
},
async listByRun(runId) {
return byRun.all(runId).map(mapInterrupt)
},
async listPendingByRun(runId) {
return pendingByRun.all(runId).map(mapInterrupt)
},
})
}(scope, key) is the composite identity. A SQL backend cannot store a nullish value in a NOT NULL text column, so reject null and undefined with a clear error instead of a cryptic driver failure. Callers clear a value with delete.
import { DatabaseSync } from 'node:sqlite'
import { defineMetadataStore } from '@tanstack/ai-persistence'
function createMetadataStore(db: DatabaseSync) {
const select = db.prepare(
'SELECT value_json FROM metadata WHERE scope = ? AND key = ?',
)
const upsert = db.prepare(
`INSERT INTO metadata (scope, key, value_json) VALUES (?, ?, ?)
ON CONFLICT(scope, key) DO UPDATE SET value_json = excluded.value_json`,
)
return defineMetadataStore({
async get(scope, key) {
const json = select.get(scope, key)?.value_json
return typeof json === 'string' ? JSON.parse(json) : null
},
async set(scope, key, value) {
if (value == null) {
throw new TypeError(
'Metadata values must be defined, non-null JSON. Use delete() to clear.',
)
}
upsert.run(scope, key, JSON.stringify(value))
},
async delete(scope, key) {
db.prepare('DELETE FROM metadata WHERE scope = ? AND key = ?').run(
scope,
key,
)
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineMetadataStore } from '@tanstack/ai-persistence'
function createMetadataStore(db: DatabaseSync) {
const select = db.prepare(
'SELECT value_json FROM metadata WHERE scope = ? AND key = ?',
)
const upsert = db.prepare(
`INSERT INTO metadata (scope, key, value_json) VALUES (?, ?, ?)
ON CONFLICT(scope, key) DO UPDATE SET value_json = excluded.value_json`,
)
return defineMetadataStore({
async get(scope, key) {
const json = select.get(scope, key)?.value_json
return typeof json === 'string' ? JSON.parse(json) : null
},
async set(scope, key, value) {
if (value == null) {
throw new TypeError(
'Metadata values must be defined, non-null JSON. Use delete() to clear.',
)
}
upsert.run(scope, key, JSON.stringify(value))
},
async delete(scope, key) {
db.prepare('DELETE FROM metadata WHERE scope = ? AND key = ?').run(
scope,
key,
)
},
})
}Open the database, create the tables, and return the stores as an AIPersistence. defineAIPersistence keeps the exact store keys in the type and rejects unknown keys at runtime.
import { DatabaseSync } from 'node:sqlite'
import { defineAIPersistence } from '@tanstack/ai-persistence'
import type { ChatPersistence } from '@tanstack/ai-persistence'
// The four store factories and the schema string, each from your own module.
import { createInterruptStore } from './interrupt-store'
import { createMessageStore } from './message-store'
import { createMetadataStore } from './metadata-store'
import { createRunStore } from './run-store'
import { SCHEMA_SQL } from './schema'
export function sqlitePersistence(options: {
url: string
migrate?: boolean
}): ChatPersistence {
const db = new DatabaseSync(options.url)
if (options.migrate) db.exec(SCHEMA_SQL)
return defineAIPersistence({
stores: {
messages: createMessageStore(db),
runs: createRunStore(db),
interrupts: createInterruptStore(db),
metadata: createMetadataStore(db),
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineAIPersistence } from '@tanstack/ai-persistence'
import type { ChatPersistence } from '@tanstack/ai-persistence'
// The four store factories and the schema string, each from your own module.
import { createInterruptStore } from './interrupt-store'
import { createMessageStore } from './message-store'
import { createMetadataStore } from './metadata-store'
import { createRunStore } from './run-store'
import { SCHEMA_SQL } from './schema'
export function sqlitePersistence(options: {
url: string
migrate?: boolean
}): ChatPersistence {
const db = new DatabaseSync(options.url)
if (options.migrate) db.exec(SCHEMA_SQL)
return defineAIPersistence({
stores: {
messages: createMessageStore(db),
runs: createRunStore(db),
interrupts: createInterruptStore(db),
metadata: createMetadataStore(db),
},
})
}That is a complete backend. If you also need a mutex across workers, add withLocks alongside it; see Locks.
Wire it into chat() exactly like any other persistence:
import {
chat,
chatParamsFromRequest,
toServerSentEventsResponse,
} from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { withPersistence } from '@tanstack/ai-persistence'
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)
}import {
chat,
chatParamsFromRequest,
toServerSentEventsResponse,
} from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { withPersistence } from '@tanstack/ai-persistence'
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)
}Everything above builds a chat adapter. Media generation persists differently: it does not use the chat runs store at all.
threadId is the slot the run belongs to, recorded on each run record.
These are three more tables alongside the four from the schema in step 1:
CREATE TABLE IF NOT EXISTS generation_runs (
run_id text PRIMARY KEY NOT NULL,
thread_id text NOT NULL,
activity text NOT NULL,
provider text NOT NULL,
model text NOT NULL,
status text NOT NULL,
started_at integer NOT NULL,
finished_at integer,
error_json text,
result_json text,
artifacts_json text,
usage_json text
);
CREATE TABLE IF NOT EXISTS artifacts (
artifact_id text PRIMARY KEY NOT NULL,
run_id text NOT NULL,
thread_id text NOT NULL,
blob_key text,
name text NOT NULL,
mime_type text NOT NULL,
size integer NOT NULL,
source_url text,
created_at integer NOT NULL
);
CREATE TABLE IF NOT EXISTS blobs (
key text PRIMARY KEY NOT NULL,
bytes blob NOT NULL,
size integer NOT NULL,
etag text NOT NULL,
content_type text,
custom_metadata_json text,
created_at integer NOT NULL,
updated_at integer NOT NULL
);CREATE TABLE IF NOT EXISTS generation_runs (
run_id text PRIMARY KEY NOT NULL,
thread_id text NOT NULL,
activity text NOT NULL,
provider text NOT NULL,
model text NOT NULL,
status text NOT NULL,
started_at integer NOT NULL,
finished_at integer,
error_json text,
result_json text,
artifacts_json text,
usage_json text
);
CREATE TABLE IF NOT EXISTS artifacts (
artifact_id text PRIMARY KEY NOT NULL,
run_id text NOT NULL,
thread_id text NOT NULL,
blob_key text,
name text NOT NULL,
mime_type text NOT NULL,
size integer NOT NULL,
source_url text,
created_at integer NOT NULL
);
CREATE TABLE IF NOT EXISTS blobs (
key text PRIMARY KEY NOT NULL,
bytes blob NOT NULL,
size integer NOT NULL,
etag text NOT NULL,
content_type text,
custom_metadata_json text,
created_at integer NOT NULL,
updated_at integer NOT NULL
);GenerationRunStore is the generation analogue of RunStore. Three contracts to hold:
import { DatabaseSync } from 'node:sqlite'
import { defineGenerationRunStore } from '@tanstack/ai-persistence'
import type {
GenerationRunRecord,
GenerationRunStatus,
} from '@tanstack/ai-persistence'
function toGenerationRunStatus(value: unknown): GenerationRunStatus {
switch (value) {
case 'running':
case 'completed':
case 'failed':
case 'interrupted':
return value
default:
throw new TypeError(`Unexpected generation run status: ${String(value)}`)
}
}
// `node:sqlite` types columns as a SQL-value union, so coerce/narrow each field
// (String / Number / typeof) and JSON-parse the text columns — no cast.
function mapGenerationRun(row: Record<string, unknown>): GenerationRunRecord {
return {
runId: String(row.run_id),
threadId: String(row.thread_id),
activity: String(row.activity),
provider: String(row.provider),
model: String(row.model),
status: toGenerationRunStatus(row.status),
startedAt: Number(row.started_at),
...(row.finished_at != null ? { finishedAt: Number(row.finished_at) } : {}),
...(typeof row.error_json === 'string'
? { error: JSON.parse(row.error_json) }
: {}),
...(typeof row.result_json === 'string'
? { result: JSON.parse(row.result_json) }
: {}),
...(typeof row.artifacts_json === 'string'
? { artifacts: JSON.parse(row.artifacts_json) }
: {}),
...(typeof row.usage_json === 'string'
? { usage: JSON.parse(row.usage_json) }
: {}),
}
}
function createGenerationRunStore(db: DatabaseSync) {
const select = db.prepare('SELECT * FROM generation_runs WHERE run_id = ?')
const insert = db.prepare(
`INSERT INTO generation_runs
(run_id, thread_id, activity, provider, model, status, started_at)
VALUES (?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(run_id) DO NOTHING`,
)
const latest = db.prepare(
`SELECT * FROM generation_runs WHERE thread_id = ?
ORDER BY started_at DESC LIMIT 1`,
)
return defineGenerationRunStore({
async createOrResume(input) {
const existing = select.get(input.runId)
if (existing) return mapGenerationRun(existing)
const status: GenerationRunStatus = input.status ?? 'running'
insert.run(
input.runId,
input.threadId,
input.activity,
input.provider,
input.model,
status,
input.startedAt,
)
return {
runId: input.runId,
threadId: input.threadId,
activity: input.activity,
provider: input.provider,
model: input.model,
status,
startedAt: input.startedAt,
}
},
async update(runId, patch) {
const sets: Array<string> = []
const params: Array<string | number> = []
if (patch.status !== undefined) {
sets.push('status = ?')
params.push(patch.status)
}
if (patch.finishedAt !== undefined) {
sets.push('finished_at = ?')
params.push(patch.finishedAt)
}
if (patch.error !== undefined) {
sets.push('error_json = ?')
params.push(JSON.stringify(patch.error))
}
if (patch.result !== undefined) {
sets.push('result_json = ?')
params.push(JSON.stringify(patch.result))
}
if (patch.artifacts !== undefined) {
sets.push('artifacts_json = ?')
params.push(JSON.stringify(patch.artifacts))
}
if (patch.usage !== undefined) {
sets.push('usage_json = ?')
params.push(JSON.stringify(patch.usage))
}
// Empty patch, or an unknown run id, touches nothing (UPDATE no-ops).
if (sets.length === 0) return
params.push(runId)
db.prepare(
`UPDATE generation_runs SET ${sets.join(', ')} WHERE run_id = ?`,
).run(...params)
},
async get(runId) {
const row = select.get(runId)
return row ? mapGenerationRun(row) : null
},
// The most recent run linked to a thread. `reconstructGeneration` calls this
// so a server-driven client (`persistence: true`) hydrates the last
// generation for its thread by the stable thread id, without a run id.
async findLatestForThread(threadId) {
const row = latest.get(threadId)
return row ? mapGenerationRun(row) : null
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineGenerationRunStore } from '@tanstack/ai-persistence'
import type {
GenerationRunRecord,
GenerationRunStatus,
} from '@tanstack/ai-persistence'
function toGenerationRunStatus(value: unknown): GenerationRunStatus {
switch (value) {
case 'running':
case 'completed':
case 'failed':
case 'interrupted':
return value
default:
throw new TypeError(`Unexpected generation run status: ${String(value)}`)
}
}
// `node:sqlite` types columns as a SQL-value union, so coerce/narrow each field
// (String / Number / typeof) and JSON-parse the text columns — no cast.
function mapGenerationRun(row: Record<string, unknown>): GenerationRunRecord {
return {
runId: String(row.run_id),
threadId: String(row.thread_id),
activity: String(row.activity),
provider: String(row.provider),
model: String(row.model),
status: toGenerationRunStatus(row.status),
startedAt: Number(row.started_at),
...(row.finished_at != null ? { finishedAt: Number(row.finished_at) } : {}),
...(typeof row.error_json === 'string'
? { error: JSON.parse(row.error_json) }
: {}),
...(typeof row.result_json === 'string'
? { result: JSON.parse(row.result_json) }
: {}),
...(typeof row.artifacts_json === 'string'
? { artifacts: JSON.parse(row.artifacts_json) }
: {}),
...(typeof row.usage_json === 'string'
? { usage: JSON.parse(row.usage_json) }
: {}),
}
}
function createGenerationRunStore(db: DatabaseSync) {
const select = db.prepare('SELECT * FROM generation_runs WHERE run_id = ?')
const insert = db.prepare(
`INSERT INTO generation_runs
(run_id, thread_id, activity, provider, model, status, started_at)
VALUES (?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(run_id) DO NOTHING`,
)
const latest = db.prepare(
`SELECT * FROM generation_runs WHERE thread_id = ?
ORDER BY started_at DESC LIMIT 1`,
)
return defineGenerationRunStore({
async createOrResume(input) {
const existing = select.get(input.runId)
if (existing) return mapGenerationRun(existing)
const status: GenerationRunStatus = input.status ?? 'running'
insert.run(
input.runId,
input.threadId,
input.activity,
input.provider,
input.model,
status,
input.startedAt,
)
return {
runId: input.runId,
threadId: input.threadId,
activity: input.activity,
provider: input.provider,
model: input.model,
status,
startedAt: input.startedAt,
}
},
async update(runId, patch) {
const sets: Array<string> = []
const params: Array<string | number> = []
if (patch.status !== undefined) {
sets.push('status = ?')
params.push(patch.status)
}
if (patch.finishedAt !== undefined) {
sets.push('finished_at = ?')
params.push(patch.finishedAt)
}
if (patch.error !== undefined) {
sets.push('error_json = ?')
params.push(JSON.stringify(patch.error))
}
if (patch.result !== undefined) {
sets.push('result_json = ?')
params.push(JSON.stringify(patch.result))
}
if (patch.artifacts !== undefined) {
sets.push('artifacts_json = ?')
params.push(JSON.stringify(patch.artifacts))
}
if (patch.usage !== undefined) {
sets.push('usage_json = ?')
params.push(JSON.stringify(patch.usage))
}
// Empty patch, or an unknown run id, touches nothing (UPDATE no-ops).
if (sets.length === 0) return
params.push(runId)
db.prepare(
`UPDATE generation_runs SET ${sets.join(', ')} WHERE run_id = ?`,
).run(...params)
},
async get(runId) {
const row = select.get(runId)
return row ? mapGenerationRun(row) : null
},
// The most recent run linked to a thread. `reconstructGeneration` calls this
// so a server-driven client (`persistence: true`) hydrates the last
// generation for its thread by the stable thread id, without a run id.
async findLatestForThread(threadId) {
const row = latest.get(threadId)
return row ? mapGenerationRun(row) : null
},
})
}ArtifactStore holds one metadata row per generated file: its runId, mimeType, size, and a createdAt. The bytes live in the blob store below.
Persist blobKey verbatim. It records where these bytes actually went, and a storageKey mapper can put them anywhere, so a reader cannot recompute the path — resolveArtifactBlobKey(record) falls back to the default convention only for rows written before the column existed. Drop it and every artifact stored under a custom key becomes unreadable.
import { DatabaseSync } from 'node:sqlite'
import { defineArtifactStore } from '@tanstack/ai-persistence'
import type { ArtifactRecord } from '@tanstack/ai-persistence'
function mapArtifact(row: Record<string, unknown>): ArtifactRecord {
return {
artifactId: String(row.artifact_id),
runId: String(row.run_id),
threadId: String(row.thread_id),
...(typeof row.blob_key === 'string' ? { blobKey: row.blob_key } : {}),
name: String(row.name),
mimeType: String(row.mime_type),
size: Number(row.size),
...(typeof row.source_url === 'string'
? { sourceUrl: row.source_url }
: {}),
createdAt: Number(row.created_at),
}
}
function createArtifactStore(db: DatabaseSync) {
const upsert = db.prepare(
`INSERT INTO artifacts
(artifact_id, run_id, thread_id, blob_key, name, mime_type, size, source_url, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(artifact_id) DO UPDATE SET
run_id = excluded.run_id, thread_id = excluded.thread_id,
blob_key = excluded.blob_key, name = excluded.name,
mime_type = excluded.mime_type, size = excluded.size,
source_url = excluded.source_url, created_at = excluded.created_at`,
)
const selectOne = db.prepare('SELECT * FROM artifacts WHERE artifact_id = ?')
const byRun = db.prepare(
'SELECT * FROM artifacts WHERE run_id = ? ORDER BY created_at ASC',
)
return defineArtifactStore({
async save(record) {
upsert.run(
record.artifactId,
record.runId,
record.threadId,
record.blobKey ?? null,
record.name,
record.mimeType,
record.size,
record.sourceUrl ?? null,
record.createdAt,
)
},
async get(artifactId) {
const row = selectOne.get(artifactId)
return row ? mapArtifact(row) : null
},
async list(runId) {
return byRun.all(runId).map(mapArtifact)
},
async delete(artifactId) {
db.prepare('DELETE FROM artifacts WHERE artifact_id = ?').run(artifactId)
},
async deleteForRun(runId) {
db.prepare('DELETE FROM artifacts WHERE run_id = ?').run(runId)
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineArtifactStore } from '@tanstack/ai-persistence'
import type { ArtifactRecord } from '@tanstack/ai-persistence'
function mapArtifact(row: Record<string, unknown>): ArtifactRecord {
return {
artifactId: String(row.artifact_id),
runId: String(row.run_id),
threadId: String(row.thread_id),
...(typeof row.blob_key === 'string' ? { blobKey: row.blob_key } : {}),
name: String(row.name),
mimeType: String(row.mime_type),
size: Number(row.size),
...(typeof row.source_url === 'string'
? { sourceUrl: row.source_url }
: {}),
createdAt: Number(row.created_at),
}
}
function createArtifactStore(db: DatabaseSync) {
const upsert = db.prepare(
`INSERT INTO artifacts
(artifact_id, run_id, thread_id, blob_key, name, mime_type, size, source_url, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(artifact_id) DO UPDATE SET
run_id = excluded.run_id, thread_id = excluded.thread_id,
blob_key = excluded.blob_key, name = excluded.name,
mime_type = excluded.mime_type, size = excluded.size,
source_url = excluded.source_url, created_at = excluded.created_at`,
)
const selectOne = db.prepare('SELECT * FROM artifacts WHERE artifact_id = ?')
const byRun = db.prepare(
'SELECT * FROM artifacts WHERE run_id = ? ORDER BY created_at ASC',
)
return defineArtifactStore({
async save(record) {
upsert.run(
record.artifactId,
record.runId,
record.threadId,
record.blobKey ?? null,
record.name,
record.mimeType,
record.size,
record.sourceUrl ?? null,
record.createdAt,
)
},
async get(artifactId) {
const row = selectOne.get(artifactId)
return row ? mapArtifact(row) : null
},
async list(runId) {
return byRun.all(runId).map(mapArtifact)
},
async delete(artifactId) {
db.prepare('DELETE FROM artifacts WHERE artifact_id = ?').run(artifactId)
},
async deleteForRun(runId) {
db.prepare('DELETE FROM artifacts WHERE run_id = ?').run(runId)
},
})
}BlobStore is a small object store. withGenerationPersistence writes each generated file under the key artifacts/<runId>/<artifactId>, so a prefix-filtered list({ prefix: 'artifacts/<runId>/' }) enumerates a run's media.
import { DatabaseSync } from 'node:sqlite'
import { defineBlobStore, resolveBlobRange } from '@tanstack/ai-persistence'
import type {
BlobBody,
BlobObject,
BlobRecord,
} from '@tanstack/ai-persistence'
async function toBytes(body: BlobBody): Promise<Uint8Array> {
if (typeof body === 'string') return new TextEncoder().encode(body)
if (body instanceof ArrayBuffer) return new Uint8Array(body.slice(0))
if (ArrayBuffer.isView(body)) {
return new Uint8Array(body.buffer, body.byteOffset, body.byteLength).slice()
}
if (body instanceof Blob) {
return new Uint8Array(await body.arrayBuffer())
}
// ReadableStream<Uint8Array>: drain it into one buffer.
const reader = body.getReader()
const chunks: Array<Uint8Array> = []
let total = 0
for (;;) {
const { done, value } = await reader.read()
if (done) break
chunks.push(value)
total += value.byteLength
}
const bytes = new Uint8Array(total)
let offset = 0
for (const chunk of chunks) {
bytes.set(chunk, offset)
offset += chunk.byteLength
}
return bytes
}
function mapBlobRecord(row: Record<string, unknown>): BlobRecord {
return {
key: String(row.key),
...(row.size != null ? { size: Number(row.size) } : {}),
...(typeof row.etag === 'string' ? { etag: row.etag } : {}),
...(typeof row.content_type === 'string'
? { contentType: row.content_type }
: {}),
...(typeof row.custom_metadata_json === 'string'
? { customMetadata: JSON.parse(row.custom_metadata_json) }
: {}),
...(row.created_at != null ? { createdAt: Number(row.created_at) } : {}),
...(row.updated_at != null ? { updatedAt: Number(row.updated_at) } : {}),
}
}
function blobObject(
record: BlobRecord,
bytes: Uint8Array,
range?: { offset: number; length: number },
): BlobObject {
return {
...record,
// `size` keeps describing the whole object; `range` describes these bytes.
...(range ? { range } : {}),
body: new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(bytes.slice())
controller.close()
},
}),
arrayBuffer() {
const copy = new ArrayBuffer(bytes.byteLength)
new Uint8Array(copy).set(bytes)
return Promise.resolve(copy)
},
text: () => Promise.resolve(new TextDecoder().decode(bytes)),
}
}
function createBlobStore(db: DatabaseSync) {
const upsert = db.prepare(
`INSERT INTO blobs
(key, bytes, size, etag, content_type, custom_metadata_json, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(key) DO UPDATE SET
bytes = excluded.bytes, size = excluded.size, etag = excluded.etag,
content_type = excluded.content_type,
custom_metadata_json = excluded.custom_metadata_json,
updated_at = excluded.updated_at`,
)
const selectCreated = db.prepare('SELECT created_at FROM blobs WHERE key = ?')
const selectOne = db.prepare('SELECT * FROM blobs WHERE key = ?')
// Metadata without the bytes, and the bounded slice: a ranged read must not
// load the whole object to hand back a piece of it.
const selectMeta = db.prepare(
`SELECT key, size, etag, content_type, custom_metadata_json,
created_at, updated_at
FROM blobs WHERE key = ?`,
)
const selectSlice = db.prepare(
'SELECT substr(bytes, ?, ?) AS bytes FROM blobs WHERE key = ?',
)
return defineBlobStore({
async put(key, body, options) {
const bytes = await toBytes(body)
const now = Date.now()
const prior = selectCreated.get(key)
const createdAt =
prior && prior.created_at != null ? Number(prior.created_at) : now
const etag = String(now)
upsert.run(
key,
bytes,
bytes.byteLength,
etag,
options?.contentType ?? null,
options?.customMetadata ? JSON.stringify(options.customMetadata) : null,
createdAt,
now,
)
return {
key,
size: bytes.byteLength,
etag,
createdAt,
updatedAt: now,
...(options?.contentType !== undefined
? { contentType: options.contentType }
: {}),
...(options?.customMetadata !== undefined
? { customMetadata: options.customMetadata }
: {}),
}
},
async get(key, options) {
if (!options?.range) {
const row = selectOne.get(key)
if (!row) return null
const bytes =
row.bytes instanceof Uint8Array ? row.bytes : new Uint8Array()
return blobObject(mapBlobRecord(row), bytes)
}
// Metadata first, WITHOUT the bytes, so the clamp costs no I/O...
const meta = selectMeta.get(key)
if (!meta) return null
const served = resolveBlobRange(Number(meta.size), options.range)
// ...then let SQLite cut the slice (`substr` is 1-based and byte-wise
// over a BLOB). Reading the row whole and slicing in JS would load the
// entire object on every video seek — the cost ranges exist to avoid.
const slice = selectSlice.get(served.offset + 1, served.length, key)
if (!slice) return null
const bytes =
slice.bytes instanceof Uint8Array ? slice.bytes : new Uint8Array()
return blobObject(mapBlobRecord(meta), bytes, served)
},
async head(key) {
// Metadata only: never pull the bytes to answer a question about them.
const row = selectMeta.get(key)
return row ? mapBlobRecord(row) : null
},
async delete(key) {
db.prepare('DELETE FROM blobs WHERE key = ?').run(key)
},
async list(options) {
if (options?.limit === 0) return { objects: [], truncated: false }
// Match the prefix with `substr(...) = ?` rather than LIKE: SQLite's LIKE
// is case-INsensitive for ASCII and treats `%`/`_` as wildcards, while the
// contract says a prefix matches literally and case-sensitively. Then page
// with a keyset cursor (keys strictly greater than the last one returned).
const prefix = options?.prefix ?? ''
const params: Array<string | number> = [prefix, prefix]
let where = 'substr(key, 1, length(?)) = ?'
if (options?.cursor !== undefined) {
where += ' AND key > ?'
params.push(options.cursor)
}
let sql = `SELECT * FROM blobs WHERE ${where} ORDER BY key ASC`
const limit = options?.limit
if (limit !== undefined) {
sql += ' LIMIT ?' // fetch one extra row to detect truncation
params.push(limit + 1)
}
const rows = db
.prepare(sql)
.all(...params)
.map(mapBlobRecord)
if (limit !== undefined && rows.length > limit) {
const page = rows.slice(0, limit)
const cursor = page.at(-1)?.key
return {
objects: page,
truncated: true,
...(cursor !== undefined ? { cursor } : {}),
}
}
return { objects: rows, truncated: false }
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineBlobStore, resolveBlobRange } from '@tanstack/ai-persistence'
import type {
BlobBody,
BlobObject,
BlobRecord,
} from '@tanstack/ai-persistence'
async function toBytes(body: BlobBody): Promise<Uint8Array> {
if (typeof body === 'string') return new TextEncoder().encode(body)
if (body instanceof ArrayBuffer) return new Uint8Array(body.slice(0))
if (ArrayBuffer.isView(body)) {
return new Uint8Array(body.buffer, body.byteOffset, body.byteLength).slice()
}
if (body instanceof Blob) {
return new Uint8Array(await body.arrayBuffer())
}
// ReadableStream<Uint8Array>: drain it into one buffer.
const reader = body.getReader()
const chunks: Array<Uint8Array> = []
let total = 0
for (;;) {
const { done, value } = await reader.read()
if (done) break
chunks.push(value)
total += value.byteLength
}
const bytes = new Uint8Array(total)
let offset = 0
for (const chunk of chunks) {
bytes.set(chunk, offset)
offset += chunk.byteLength
}
return bytes
}
function mapBlobRecord(row: Record<string, unknown>): BlobRecord {
return {
key: String(row.key),
...(row.size != null ? { size: Number(row.size) } : {}),
...(typeof row.etag === 'string' ? { etag: row.etag } : {}),
...(typeof row.content_type === 'string'
? { contentType: row.content_type }
: {}),
...(typeof row.custom_metadata_json === 'string'
? { customMetadata: JSON.parse(row.custom_metadata_json) }
: {}),
...(row.created_at != null ? { createdAt: Number(row.created_at) } : {}),
...(row.updated_at != null ? { updatedAt: Number(row.updated_at) } : {}),
}
}
function blobObject(
record: BlobRecord,
bytes: Uint8Array,
range?: { offset: number; length: number },
): BlobObject {
return {
...record,
// `size` keeps describing the whole object; `range` describes these bytes.
...(range ? { range } : {}),
body: new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(bytes.slice())
controller.close()
},
}),
arrayBuffer() {
const copy = new ArrayBuffer(bytes.byteLength)
new Uint8Array(copy).set(bytes)
return Promise.resolve(copy)
},
text: () => Promise.resolve(new TextDecoder().decode(bytes)),
}
}
function createBlobStore(db: DatabaseSync) {
const upsert = db.prepare(
`INSERT INTO blobs
(key, bytes, size, etag, content_type, custom_metadata_json, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(key) DO UPDATE SET
bytes = excluded.bytes, size = excluded.size, etag = excluded.etag,
content_type = excluded.content_type,
custom_metadata_json = excluded.custom_metadata_json,
updated_at = excluded.updated_at`,
)
const selectCreated = db.prepare('SELECT created_at FROM blobs WHERE key = ?')
const selectOne = db.prepare('SELECT * FROM blobs WHERE key = ?')
// Metadata without the bytes, and the bounded slice: a ranged read must not
// load the whole object to hand back a piece of it.
const selectMeta = db.prepare(
`SELECT key, size, etag, content_type, custom_metadata_json,
created_at, updated_at
FROM blobs WHERE key = ?`,
)
const selectSlice = db.prepare(
'SELECT substr(bytes, ?, ?) AS bytes FROM blobs WHERE key = ?',
)
return defineBlobStore({
async put(key, body, options) {
const bytes = await toBytes(body)
const now = Date.now()
const prior = selectCreated.get(key)
const createdAt =
prior && prior.created_at != null ? Number(prior.created_at) : now
const etag = String(now)
upsert.run(
key,
bytes,
bytes.byteLength,
etag,
options?.contentType ?? null,
options?.customMetadata ? JSON.stringify(options.customMetadata) : null,
createdAt,
now,
)
return {
key,
size: bytes.byteLength,
etag,
createdAt,
updatedAt: now,
...(options?.contentType !== undefined
? { contentType: options.contentType }
: {}),
...(options?.customMetadata !== undefined
? { customMetadata: options.customMetadata }
: {}),
}
},
async get(key, options) {
if (!options?.range) {
const row = selectOne.get(key)
if (!row) return null
const bytes =
row.bytes instanceof Uint8Array ? row.bytes : new Uint8Array()
return blobObject(mapBlobRecord(row), bytes)
}
// Metadata first, WITHOUT the bytes, so the clamp costs no I/O...
const meta = selectMeta.get(key)
if (!meta) return null
const served = resolveBlobRange(Number(meta.size), options.range)
// ...then let SQLite cut the slice (`substr` is 1-based and byte-wise
// over a BLOB). Reading the row whole and slicing in JS would load the
// entire object on every video seek — the cost ranges exist to avoid.
const slice = selectSlice.get(served.offset + 1, served.length, key)
if (!slice) return null
const bytes =
slice.bytes instanceof Uint8Array ? slice.bytes : new Uint8Array()
return blobObject(mapBlobRecord(meta), bytes, served)
},
async head(key) {
// Metadata only: never pull the bytes to answer a question about them.
const row = selectMeta.get(key)
return row ? mapBlobRecord(row) : null
},
async delete(key) {
db.prepare('DELETE FROM blobs WHERE key = ?').run(key)
},
async list(options) {
if (options?.limit === 0) return { objects: [], truncated: false }
// Match the prefix with `substr(...) = ?` rather than LIKE: SQLite's LIKE
// is case-INsensitive for ASCII and treats `%`/`_` as wildcards, while the
// contract says a prefix matches literally and case-sensitively. Then page
// with a keyset cursor (keys strictly greater than the last one returned).
const prefix = options?.prefix ?? ''
const params: Array<string | number> = [prefix, prefix]
let where = 'substr(key, 1, length(?)) = ?'
if (options?.cursor !== undefined) {
where += ' AND key > ?'
params.push(options.cursor)
}
let sql = `SELECT * FROM blobs WHERE ${where} ORDER BY key ASC`
const limit = options?.limit
if (limit !== undefined) {
sql += ' LIMIT ?' // fetch one extra row to detect truncation
params.push(limit + 1)
}
const rows = db
.prepare(sql)
.all(...params)
.map(mapBlobRecord)
if (limit !== undefined && rows.length > limit) {
const page = rows.slice(0, limit)
const cursor = page.at(-1)?.key
return {
objects: page,
truncated: true,
...(cursor !== undefined ? { cursor } : {}),
}
}
return { objects: rows, truncated: false }
},
})
}Hand the three stores to defineAIPersistence the same way. generationRuns alone is a valid generation adapter (run records, no byte storage); add artifacts + blobs — together — to keep the media:
import { DatabaseSync } from 'node:sqlite'
import { defineAIPersistence } from '@tanstack/ai-persistence'
// The three generation store factories and the schema string, from your modules.
import { createArtifactStore } from './artifact-store'
import { createBlobStore } from './blob-store'
import { createGenerationRunStore } from './generation-run-store'
import { GENERATION_SCHEMA_SQL } from './generation-schema'
export function generationPersistence(options: {
url: string
migrate?: boolean
}) {
const db = new DatabaseSync(options.url)
if (options.migrate) db.exec(GENERATION_SCHEMA_SQL)
return defineAIPersistence({
stores: {
generationRuns: createGenerationRunStore(db),
artifacts: createArtifactStore(db),
blobs: createBlobStore(db),
},
})
}import { DatabaseSync } from 'node:sqlite'
import { defineAIPersistence } from '@tanstack/ai-persistence'
// The three generation store factories and the schema string, from your modules.
import { createArtifactStore } from './artifact-store'
import { createBlobStore } from './blob-store'
import { createGenerationRunStore } from './generation-run-store'
import { GENERATION_SCHEMA_SQL } from './generation-schema'
export function generationPersistence(options: {
url: string
migrate?: boolean
}) {
const db = new DatabaseSync(options.url)
if (options.migrate) db.exec(GENERATION_SCHEMA_SQL)
return defineAIPersistence({
stores: {
generationRuns: createGenerationRunStore(db),
artifacts: createArtifactStore(db),
blobs: createBlobStore(db),
},
})
}Pass the result to withGenerationPersistence on a generateImage / generateVideo / … call; see Generation persistence. You can also fold these stores into an existing chat adapter with composePersistence, so one backend serves both withPersistence and withGenerationPersistence.
You do not have to create the four tables above. If you already have a database, map each store method onto the tables and columns you already run. Three things change from the from-scratch version.
Your column names, your types. The core reads and writes only through your store methods, so name columns whatever you like and use your database's native types. Store messages_json as a real jsonb column on Postgres, use a timestamptz for started_at and convert to epoch milliseconds in your row mapper, split usage into real columns if you want to query it. The record shape the methods return is fixed; how you store it is not.
Extra columns are fine. Add a user_id to the messages table to scope threads per user, add created_at/updated_at audit columns, add a tenant id. Keep added columns nullable or defaulted so the store's inserts still succeed. The TanStack AI stores never read or write columns they do not know about.
Adopt part of it. You rarely need all four stores in the same database. Put messages and runs in your primary database and nothing else, then fill the rest from another source with composePersistence:
import { composePersistence, memoryPersistence } from '@tanstack/ai-persistence'
import { messages, runs } from './my-postgres-stores'
// Start from any base and replace the stores you own.
export const persistence = composePersistence(memoryPersistence(), {
overrides: { messages, runs },
})import { composePersistence, memoryPersistence } from '@tanstack/ai-persistence'
import { messages, runs } from './my-postgres-stores'
// Start from any base and replace the stores you own.
export const persistence = composePersistence(memoryPersistence(), {
overrides: { messages, runs },
})One caveat: composePersistence does not add a transaction across different systems. If messages lives in Postgres and interrupts in Redis, a write that must touch both is two writes; design retries and idempotency for that yourself. The store invariants (idempotent createOrResume, insert-if-absent create) are what make those retries safe, which is exactly why they are invariants.
Do not eyeball it. @tanstack/ai-persistence ships the same conformance test suite every packaged backend runs. Point it at your factory and it exercises every method of every store you provide, including the ordering and idempotency rules that are easy to get subtly wrong.
import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
import { sqlitePersistence } from './sqlite-persistence'
runPersistenceConformance('my sqlite adapter', () =>
sqlitePersistence({ url: ':memory:', migrate: true }),
)import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
import { sqlitePersistence } from './sqlite-persistence'
runPersistenceConformance('my sqlite adapter', () =>
sqlitePersistence({ url: ':memory:', migrate: true }),
)The suite covers all seven stores — the four chat state stores and the three generation stores from the section above — so an adapter lists whatever it deliberately omits. A chat-only adapter skips the generation half:
import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
import { chatOnlyPersistence } from './chat-only'
runPersistenceConformance('chat-only adapter', () => chatOnlyPersistence(), {
skip: ['generationRuns', 'artifacts', 'blobs'],
})import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
import { chatOnlyPersistence } from './chat-only'
runPersistenceConformance('chat-only adapter', () => chatOnlyPersistence(), {
skip: ['generationRuns', 'artifacts', 'blobs'],
})and a transcript-only one skips more:
import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
import { transcriptOnlyPersistence } from './transcript-only'
runPersistenceConformance(
'transcript-only adapter',
() => transcriptOnlyPersistence(),
{
skip: [
'runs',
'interrupts',
'metadata',
'generationRuns',
'artifacts',
'blobs',
],
},
)import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
import { transcriptOnlyPersistence } from './transcript-only'
runPersistenceConformance(
'transcript-only adapter',
() => transcriptOnlyPersistence(),
{
skip: [
'runs',
'interrupts',
'metadata',
'generationRuns',
'artifacts',
'blobs',
],
},
)skip accepts only store keys. A store that is absent and not listed fails the suite loudly, so you cannot ship a half-wired adapter by accident. When this is green, your adapter is a drop-in for withPersistence (and, with the generation stores, withGenerationPersistence). The examples/ts-react-chat app runs exactly this test against its SQLite backend, which provides all seven.
You do not have to type this page out. @tanstack/ai-persistence ships Agent Skills that turn it into a recipe your assistant follows against your stack: it reads your existing ORM config, schema file, and database handle, appends the four tables to the schema you already have, and writes a single src/lib/chat-persistence.ts exporting the ChatPersistence — no new package, no second database client, and no migration mechanism competing with the one you run.
Install the skills with TanStack Intent, which scans node_modules for packages that ship skills and writes the mappings into your agent's config (AGENTS.md, CLAUDE.md, .cursorrules, …):
pnpm add @tanstack/ai-persistence
npx @tanstack/intent@latest installpnpm add @tanstack/ai-persistence
npx @tanstack/intent@latest installThen ask for what you want — "add chat persistence to this app" — and the matching skill loads itself into context:
| Skill | Covers |
|---|---|
| ai-persistence | Entry point — routes to everything below |
| ai-persistence/server | withPersistence, run lifecycle, interrupts, reconstructChat |
| ai-persistence/stores | The store contracts and their invariants |
| ai-core/locks | LockStore / withLocks coordination (ships in @tanstack/ai/locks) |
| ai-persistence/build-drizzle-adapter | chat-persistence.ts for a Drizzle app (SQLite / Postgres / MySQL) |
| ai-persistence/build-prisma-adapter | chat-persistence.ts for a Prisma app |
| ai-persistence/build-cloudflare-adapter | chat-persistence.ts for a Worker on D1, plus Durable Object locks |
| ai-persistence/build-custom-adapter | chat-persistence.ts for anything else — raw pg, Kysely, SQLite, Mongo, Supabase |
Browser-side persistence is not in this package — its skill ships with @tanstack/ai as ai-core/client-persistence, alongside the framework code it teaches.
They are plain Markdown at node_modules/@tanstack/ai-persistence/skills/<skill-name>/SKILL.md if you prefer to read or follow them yourself.
These are the public contracts from @tanstack/ai-persistence. Implement only the stores you need.
import type { ModelMessage } from '@tanstack/ai'
interface MessageStore {
loadThread(threadId: string): Promise<Array<ModelMessage>>
saveThread(threadId: string, messages: Array<ModelMessage>): Promise<void>
}import type { ModelMessage } from '@tanstack/ai'
interface MessageStore {
loadThread(threadId: string): Promise<Array<ModelMessage>>
saveThread(threadId: string, messages: Array<ModelMessage>): Promise<void>
}saveThread receives the full authoritative model-message history, not a delta. loadThread returns [] (never null) for a thread that was never saved.
import type { TokenUsage } from '@tanstack/ai'
interface RunRecord {
runId: string
threadId: string
status: 'running' | 'completed' | 'failed' | 'interrupted'
startedAt: number // epoch ms
finishedAt?: number // epoch ms, set once the run reaches a terminal status
error?: string
usage?: TokenUsage // token counts, from @tanstack/ai
}
interface RunStore {
createOrResume(input: {
runId: string
threadId: string
status?: RunRecord['status']
startedAt: number
}): Promise<RunRecord>
update(
runId: string,
patch: Partial<
Pick<RunRecord, 'status' | 'finishedAt' | 'error' | 'usage'>
>,
): Promise<void>
get(runId: string): Promise<RunRecord | null>
// The most recent 'running' run for a thread (greatest `startedAt` wins), or
// null when the thread is idle. `reconstructChat` calls it to report
// `activeRun`, which is how a hydrating client tails a run that is still
// generating.
findActiveRun(threadId: string): Promise<RunRecord | null>
}import type { TokenUsage } from '@tanstack/ai'
interface RunRecord {
runId: string
threadId: string
status: 'running' | 'completed' | 'failed' | 'interrupted'
startedAt: number // epoch ms
finishedAt?: number // epoch ms, set once the run reaches a terminal status
error?: string
usage?: TokenUsage // token counts, from @tanstack/ai
}
interface RunStore {
createOrResume(input: {
runId: string
threadId: string
status?: RunRecord['status']
startedAt: number
}): Promise<RunRecord>
update(
runId: string,
patch: Partial<
Pick<RunRecord, 'status' | 'finishedAt' | 'error' | 'usage'>
>,
): Promise<void>
get(runId: string): Promise<RunRecord | null>
// The most recent 'running' run for a thread (greatest `startedAt` wins), or
// null when the thread is idle. `reconstructChat` calls it to report
// `activeRun`, which is how a hydrating client tails a run that is still
// generating.
findActiveRun(threadId: string): Promise<RunRecord | null>
}Three contracts to hold:
Every method on a store you provide is required. A backend that genuinely has no run lifecycle should declare ChatTranscriptStores and omit runs entirely rather than supply a RunStore with a stubbed method: an absent store is caught by the type system, an incomplete one fails silently at runtime.
interface InterruptRecord {
interruptId: string
runId: string
threadId: string
status: 'pending' | 'resolved' | 'cancelled'
requestedAt: number // epoch ms
resolvedAt?: number // epoch ms, set once resolved or cancelled
payload: Record<string, unknown>
response?: unknown
}
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>>
}interface InterruptRecord {
interruptId: string
runId: string
threadId: string
status: 'pending' | 'resolved' | 'cancelled'
requestedAt: number // epoch ms
resolvedAt?: number // epoch ms, set once resolved or cancelled
payload: Record<string, unknown>
response?: unknown
}
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 accepts a record without status/resolvedAt so every interrupt is born 'pending'; it is insert-if-absent, so a duplicate create never clobbers an already-resolved interrupt. The list* methods return records ordered by requestedAt ascending. An interrupts store requires a runs store when used with chat persistence.
interface MetadataStore {
get(scope: string, key: string): Promise<unknown | null>
set(scope: string, key: string, value: unknown): Promise<void>
delete(scope: string, key: string): Promise<void>
}interface MetadataStore {
get(scope: string, key: string): Promise<unknown | null>
set(scope: string, key: string, value: unknown): Promise<void>
delete(scope: string, key: string): Promise<void>
}Namespaces and value schemas are application-owned, and (scope, key) is the composite identity. A stored null is indistinguishable from absence at the type level, so wrap a value you must persist as null (e.g. { value: null }), or reject nullish values outright the way the SQLite store above does.
The generation counterpart to RunStore. Keyed by its own runId, with threadId the slot findLatestForThread looks runs up by. withGenerationPersistence requires this store, not runs.
Its status uses the same vocabulary as a chat run's RunStatus, so one status column and one set of checks cover both tables.
import type { PersistedArtifactRef, TokenUsage } from '@tanstack/ai'
// The same vocabulary as a chat run's `RunStatus`.
type GenerationRunStatus = 'running' | 'completed' | 'failed' | 'interrupted'
interface GenerationRunRecord {
runId: string
threadId: string // the slot this run fills, hydrated by findLatestForThread
activity: string // 'image' | 'audio' | 'tts' | 'video' | 'transcription'
provider: string
model: string
status: GenerationRunStatus
startedAt: number // epoch ms
finishedAt?: number // epoch ms, set once the run reaches a terminal status
error?: { message: string; code?: string }
result?: unknown // terminal result metadata (ids, urls) — never media bytes
artifacts?: Array<PersistedArtifactRef> // present with an artifacts + blobs backend
usage?: TokenUsage
}
interface GenerationRunStore {
createOrResume(input: {
runId: string
activity: string
provider: string
model: string
startedAt: number
threadId: string
status?: GenerationRunStatus
}): Promise<GenerationRunRecord>
update(
runId: string,
patch: Partial<
Pick<
GenerationRunRecord,
'status' | 'finishedAt' | 'error' | 'result' | 'artifacts' | 'usage'
>
>,
): Promise<void>
get(runId: string): Promise<GenerationRunRecord | null>
// The most recent run filed under a thread (greatest `startedAt`), or null.
// Required: it is the only query that hydrates a generation, so an adapter
// without it would be indistinguishable from one whose thread has no runs —
// `persistence: true` would silently restore nothing, forever.
findLatestForThread(threadId: string): Promise<GenerationRunRecord | null>
}import type { PersistedArtifactRef, TokenUsage } from '@tanstack/ai'
// The same vocabulary as a chat run's `RunStatus`.
type GenerationRunStatus = 'running' | 'completed' | 'failed' | 'interrupted'
interface GenerationRunRecord {
runId: string
threadId: string // the slot this run fills, hydrated by findLatestForThread
activity: string // 'image' | 'audio' | 'tts' | 'video' | 'transcription'
provider: string
model: string
status: GenerationRunStatus
startedAt: number // epoch ms
finishedAt?: number // epoch ms, set once the run reaches a terminal status
error?: { message: string; code?: string }
result?: unknown // terminal result metadata (ids, urls) — never media bytes
artifacts?: Array<PersistedArtifactRef> // present with an artifacts + blobs backend
usage?: TokenUsage
}
interface GenerationRunStore {
createOrResume(input: {
runId: string
activity: string
provider: string
model: string
startedAt: number
threadId: string
status?: GenerationRunStatus
}): Promise<GenerationRunRecord>
update(
runId: string,
patch: Partial<
Pick<
GenerationRunRecord,
'status' | 'finishedAt' | 'error' | 'result' | 'artifacts' | 'usage'
>
>,
): Promise<void>
get(runId: string): Promise<GenerationRunRecord | null>
// The most recent run filed under a thread (greatest `startedAt`), or null.
// Required: it is the only query that hydrates a generation, so an adapter
// without it would be indistinguishable from one whose thread has no runs —
// `persistence: true` would silently restore nothing, forever.
findLatestForThread(threadId: string): Promise<GenerationRunRecord | null>
}Implement createOrResume idempotently: a second call for an existing runId returns the stored record unchanged (startedAt / activity / provider / model / threadId are not mutated), which is what makes resuming a run safe. update against an unknown runId is a no-op.
Metadata rows for persisted media. The bytes live in a BlobStore; this record holds the descriptive metadata and an optional sourceUrl for reference-only backends. Provide it together with a BlobStore to keep generated bytes.
interface ArtifactRecord {
artifactId: string
runId: string
threadId: string
blobKey?: string // where the bytes live; absent on pre-blobKey records
name: string
mimeType: string
size: number
sourceUrl?: string // where the bytes were fetched FROM (provenance)
createdAt: number // epoch ms
}
interface ArtifactStore {
save(record: ArtifactRecord): Promise<void>
get(artifactId: string): Promise<ArtifactRecord | null>
list(runId: string): Promise<Array<ArtifactRecord>> // [] when the run has none
delete(artifactId: string): Promise<void>
deleteForRun(runId: string): Promise<void>
}interface ArtifactRecord {
artifactId: string
runId: string
threadId: string
blobKey?: string // where the bytes live; absent on pre-blobKey records
name: string
mimeType: string
size: number
sourceUrl?: string // where the bytes were fetched FROM (provenance)
createdAt: number // epoch ms
}
interface ArtifactStore {
save(record: ArtifactRecord): Promise<void>
get(artifactId: string): Promise<ArtifactRecord | null>
list(runId: string): Promise<Array<ArtifactRecord>> // [] when the run has none
delete(artifactId: string): Promise<void>
deleteForRun(runId: string): Promise<void>
}A durable object/blob store for the bytes. withGenerationPersistence writes each generated file under the key artifacts/<runId>/<artifactId>.
type BlobBody =
| ReadableStream<Uint8Array>
| ArrayBuffer
| ArrayBufferView
| string
| Blob
interface BlobRecord {
key: string
size?: number
etag?: string
contentType?: string
customMetadata?: Record<string, string>
createdAt?: number // epoch ms first written
updatedAt?: number // epoch ms last overwritten
}
interface BlobObject extends BlobRecord {
arrayBuffer(): Promise<ArrayBuffer>
text(): Promise<string>
body?: ReadableStream<Uint8Array>
// The slice served, when a range was requested. Absent on a whole read.
range?: { offset: number; length: number }
}
interface BlobListPage {
objects: Array<BlobRecord>
cursor?: string // present only when `truncated`
truncated?: boolean
}
interface BlobPutOptions {
contentType?: string
customMetadata?: Record<string, string>
// Exact byte length of `body`, when the producer knows it. Advisory: use it
// to pick an upload strategy (single-shot vs multipart), never as a
// substitute for counting the bytes you actually store.
expectedLength?: number
}
interface BlobRange {
offset: number // from the start of the object; must be inside it
length?: number // defaults to "to the end"; clamped when it overshoots
}
interface BlobGetOptions {
range?: BlobRange
}
interface BlobListOptions {
prefix?: string
cursor?: string
limit?: number
}
interface BlobStore {
put(key: string, body: BlobBody, options?: BlobPutOptions): Promise<BlobRecord>
get(key: string, options?: BlobGetOptions): Promise<BlobObject | null>
head(key: string): Promise<BlobRecord | null>
delete(key: string): Promise<void>
list(options?: BlobListOptions): Promise<BlobListPage>
}type BlobBody =
| ReadableStream<Uint8Array>
| ArrayBuffer
| ArrayBufferView
| string
| Blob
interface BlobRecord {
key: string
size?: number
etag?: string
contentType?: string
customMetadata?: Record<string, string>
createdAt?: number // epoch ms first written
updatedAt?: number // epoch ms last overwritten
}
interface BlobObject extends BlobRecord {
arrayBuffer(): Promise<ArrayBuffer>
text(): Promise<string>
body?: ReadableStream<Uint8Array>
// The slice served, when a range was requested. Absent on a whole read.
range?: { offset: number; length: number }
}
interface BlobListPage {
objects: Array<BlobRecord>
cursor?: string // present only when `truncated`
truncated?: boolean
}
interface BlobPutOptions {
contentType?: string
customMetadata?: Record<string, string>
// Exact byte length of `body`, when the producer knows it. Advisory: use it
// to pick an upload strategy (single-shot vs multipart), never as a
// substitute for counting the bytes you actually store.
expectedLength?: number
}
interface BlobRange {
offset: number // from the start of the object; must be inside it
length?: number // defaults to "to the end"; clamped when it overshoots
}
interface BlobGetOptions {
range?: BlobRange
}
interface BlobListOptions {
prefix?: string
cursor?: string
limit?: number
}
interface BlobStore {
put(key: string, body: BlobBody, options?: BlobPutOptions): Promise<BlobRecord>
get(key: string, options?: BlobGetOptions): Promise<BlobObject | null>
head(key: string): Promise<BlobRecord | null>
delete(key: string): Promise<void>
list(options?: BlobListOptions): Promise<BlobListPage>
}Three contracts to hold for list:
And one for put: the body can be a ReadableStream with no declared length. That is how a URL-fetched artifact arrives whenever the origin does not declare one it can be held to — a chunked reply, or a compressed one whose content-length describes the compressed bytes. (When the origin does declare a usable length, the body reaches you exactly as fetch produced it, length intact, and expectedLength carries the same number.) Your store must drain a length-less stream, not require a length up front. Backends that need a declared length for a single-shot upload (Cloudflare R2 on workerd is one) can re-attach expectedLength when it is present and stream through a multipart upload when it is not — the ai-persistence/build-cloudflare-artifact-store skill ships that recipe. The conformance testkit exercises the length-less case, so a store that only handles byte bodies fails the suite.
And one for get: honour options.range by returning only that slice. size keeps reporting the whole object, and the returned range reports what you actually served — together they are the 206 response a media player's seeking depends on. resolveBlobRange(size, range) does the clamping (a length past the end is legal and clamps; an offset past the end throws, because a serve route should have answered 416 from record.size first):
import { resolveBlobRange } from '@tanstack/ai-persistence'
async get(key: string, options?: BlobGetOptions) {
const row = await selectBlob(key)
if (!row) return null
if (!options?.range) return blobObject(row, row.body)
const served = resolveBlobRange(row.size, options.range)
// Slice at the storage layer, not after loading the whole object.
const bytes = await selectBlobSlice(key, served.offset, served.length)
return blobObject(row, bytes, served)
}import { resolveBlobRange } from '@tanstack/ai-persistence'
async get(key: string, options?: BlobGetOptions) {
const row = await selectBlob(key)
if (!row) return null
if (!options?.range) return blobObject(row, row.body)
const served = resolveBlobRange(row.size, options.range)
// Slice at the storage layer, not after loading the whole object.
const bytes = await selectBlobSlice(key, served.offset, served.length)
return blobObject(row, bytes, served)
}This is not optional for a store that holds bytes — the conformance testkit asserts it. Ignoring range and returning the whole file is what makes <video> seeking (and Safari playback at all) fail, and it silently sends the entire artifact for every seek. A reference-only backend that stores no bytes skips blobs altogether instead.
'%3e%3cpath%20d='M117.436%20207.036V154.604L118.529%20153.51H129.452L130.545%20154.604V207.036L129.452%20208.13H118.529L117.436%20207.036Z'%20fill='%2305BDBA'/%3e%3cpath%20d='M117.436%2053.5225V1.09339L118.529%200H129.452L130.545%201.09339V53.5225L129.452%2054.6159H118.529L117.436%2053.5225Z'%20fill='%2305BDBA'/%3e%3cpath%20d='M69.9539%20169.238H68.4094L60.6869%20161.512V159.967L78.7201%20141.938L86.8976%20141.942L87.9948%20143.031V151.209L69.9539%20169.238Z'%20fill='%2305BDBA'/%3e%3cpath%20d='M69.9462%2038.8917H68.4017L60.6792%2046.6181V48.1626L78.7124%2066.192L86.8899%2066.1882L87.9871%2065.0986V56.9212L69.9462%2038.8917Z'%20fill='%2305BDBA'/%3e%3cpath%20d='M1.09339%2097.5104H75.3711L76.4645%2098.6038V109.526L75.3711%20110.62H1.09339L0%20109.526V98.6038L1.09339%2097.5104Z'%20fill='%2305BDBA'/%3e%3cpath%20d='M440.999%2097.5104H510.91L512.004%2098.6038V109.526L510.91%20110.62H436.633L435.539%20109.526L439.905%2098.6038L440.999%2097.5104Z'%20fill='%2305BDBA'/%3e%3cpath%20d='M212.056%20108.727L210.963%20109.821H177.079L175.986%20110.914C175.986%20113.101%20178.173%20119.657%20186.916%20119.657C190.196%20119.657%20193.472%20118.564%20194.566%20116.377L195.659%20115.284H208.776L209.869%20116.377C208.776%20122.934%20203.313%20132.774%20186.916%20132.774C168.336%20132.774%20159.589%20119.657%20159.589%20104.357C159.589%2089.0576%20168.332%2075.9408%20185.822%2075.9408C203.313%2075.9408%20212.056%2089.0576%20212.056%20104.357V108.731V108.727ZM195.659%2097.7971C195.659%2096.7037%20194.566%2089.0538%20185.822%2089.0538C177.079%2089.0538%20175.986%2096.7037%20175.986%2097.7971L177.079%2098.8905H194.566L195.659%2097.7971Z'%20fill='%23014847'/%3e%3cpath%20d='M242.66%20115.284C242.66%20117.47%20243.753%20118.564%20245.94%20118.564H255.776L256.87%20119.657V130.587L255.776%20131.681H245.94C236.103%20131.681%20227.36%20127.307%20227.36%20115.284V91.2368L226.266%2090.1434H218.617L217.523%2089.05V78.1199L218.617%2077.0265H226.266L227.36%2075.9332V66.0965L228.453%2065.0031H241.57L242.663%2066.0965V75.9332L243.757%2077.0265H255.78L256.874%2078.1199V89.05L255.78%2090.1434H243.757L242.663%2091.2368V115.284H242.66Z'%20fill='%23014847'/%3e%3cpath%20d='M283.1%20131.681H269.983L268.889%20130.587V56.2636L269.983%2055.1702H283.1L284.193%2056.2636V130.587L283.1%20131.681Z'%20fill='%23014847'/%3e%3cpath%20d='M312.61%2068.2871H299.493L298.399%2067.1937V56.2636L299.493%2055.1702H312.61L313.703%2056.2636V67.1937L312.61%2068.2871ZM312.61%20131.681H299.493L298.399%20130.587V78.1237L299.493%2077.0304H312.61L313.703%2078.1237V130.587L312.61%20131.681Z'%20fill='%23014847'/%3e%3cpath%20d='M363.98%2056.2636V67.1937L362.886%2068.2871H353.05C350.863%2068.2871%20349.769%2069.3805%20349.769%2071.5672V75.9408L350.863%2077.0342H361.793L362.886%2078.1276V89.0576L361.793%2090.151H350.863L349.769%2091.2444V130.591L348.676%20131.684H335.559L334.466%20130.591V91.2444L333.372%2090.151H325.723L324.629%2089.0576V78.1276L325.723%2077.0342H333.372L334.466%2075.9408V71.5672C334.466%2059.5438%20343.209%2055.1702%20353.046%2055.1702H362.882L363.976%2056.2636H363.98Z'%20fill='%23014847'/%3e%3cpath%20d='M404.42%20132.774C400.046%20143.704%20395.677%20150.261%20380.373%20150.261H374.906L373.813%20149.167V138.237L374.906%20137.144H380.373C385.836%20137.144%20386.929%20136.05%20388.023%20132.77V131.677L370.536%2089.05V78.1199L371.63%2077.0265H381.466L382.56%2078.1199L395.677%20115.284H396.77L409.887%2078.1199L410.98%2077.0265H420.817L421.91%2078.1199V89.05L404.424%20132.77L404.42%20132.774Z'%20fill='%23014847'/%3e%3cpath%20d='M135.454%20131.681L134.361%20130.587L134.368%2098.9172C134.368%2093.4541%20132.22%2089.2182%20125.625%2089.0806C122.234%2088.9926%20118.354%2089.0729%20114.209%2089.2488L113.59%2089.8834L113.598%20130.587L112.504%20131.681H99.3913L98.2979%20130.587V77.5388L99.3913%2076.4454L128.901%2076.1778C143.685%2076.1778%20149.668%2086.3356%20149.668%2097.8009V130.587L148.575%20131.681H135.454Z'%20fill='%23014847'/%3e%3c/g%3e%3cdefs%3e%3cclipPath%20id='clip0_235_8'%3e%3crect%20width='512'%20height='208.126'%20fill='white'/%3e%3c/clipPath%3e%3c/defs%3e%3c/svg%3e)
'%3e%3cpath%20d='M117.436%20207.036V154.604L118.529%20153.51H129.452L130.545%20154.604V207.036L129.452%20208.13H118.529L117.436%20207.036Z'%20fill='%2332E6E2'/%3e%3cpath%20d='M117.436%2053.5225V1.09339L118.529%200H129.452L130.545%201.09339V53.5225L129.452%2054.6159H118.529L117.436%2053.5225Z'%20fill='%2332E6E2'/%3e%3cpath%20d='M69.9539%20169.238H68.4094L60.6869%20161.512V159.967L78.7201%20141.938L86.8976%20141.942L87.9948%20143.031V151.209L69.9539%20169.238Z'%20fill='%2332E6E2'/%3e%3cpath%20d='M69.9462%2038.8917H68.4017L60.6792%2046.6181V48.1626L78.7124%2066.192L86.8899%2066.1882L87.9871%2065.0986V56.9212L69.9462%2038.8917Z'%20fill='%2332E6E2'/%3e%3cpath%20d='M1.09339%2097.5104H75.3711L76.4645%2098.6038V109.526L75.3711%20110.62H1.09339L0%20109.526V98.6038L1.09339%2097.5104Z'%20fill='%2332E6E2'/%3e%3cpath%20d='M440.999%2097.5104H510.91L512.004%2098.6038V109.526L510.91%20110.62H436.633L435.539%20109.526L439.905%2098.6038L440.999%2097.5104Z'%20fill='%2332E6E2'/%3e%3cpath%20d='M212.056%20108.727L210.963%20109.821H177.079L175.986%20110.914C175.986%20113.101%20178.173%20119.657%20186.916%20119.657C190.196%20119.657%20193.472%20118.564%20194.566%20116.377L195.659%20115.284H208.776L209.869%20116.377C208.776%20122.934%20203.313%20132.774%20186.916%20132.774C168.336%20132.774%20159.589%20119.657%20159.589%20104.357C159.589%2089.0576%20168.332%2075.9408%20185.822%2075.9408C203.313%2075.9408%20212.056%2089.0576%20212.056%20104.357V108.731V108.727ZM195.659%2097.7971C195.659%2096.7037%20194.566%2089.0538%20185.822%2089.0538C177.079%2089.0538%20175.986%2096.7037%20175.986%2097.7971L177.079%2098.8905H194.566L195.659%2097.7971Z'%20fill='white'/%3e%3cpath%20d='M242.66%20115.284C242.66%20117.47%20243.753%20118.564%20245.94%20118.564H255.776L256.87%20119.657V130.587L255.776%20131.681H245.94C236.103%20131.681%20227.36%20127.307%20227.36%20115.284V91.2368L226.266%2090.1434H218.617L217.523%2089.05V78.1199L218.617%2077.0265H226.266L227.36%2075.9332V66.0965L228.453%2065.0031H241.57L242.663%2066.0965V75.9332L243.757%2077.0265H255.78L256.874%2078.1199V89.05L255.78%2090.1434H243.757L242.663%2091.2368V115.284H242.66Z'%20fill='white'/%3e%3cpath%20d='M283.1%20131.681H269.983L268.889%20130.587V56.2636L269.983%2055.1702H283.1L284.193%2056.2636V130.587L283.1%20131.681Z'%20fill='white'/%3e%3cpath%20d='M312.61%2068.2871H299.493L298.399%2067.1937V56.2636L299.493%2055.1702H312.61L313.703%2056.2636V67.1937L312.61%2068.2871ZM312.61%20131.681H299.493L298.399%20130.587V78.1237L299.493%2077.0304H312.61L313.703%2078.1237V130.587L312.61%20131.681Z'%20fill='white'/%3e%3cpath%20d='M363.98%2056.2636V67.1937L362.886%2068.2871H353.05C350.863%2068.2871%20349.769%2069.3805%20349.769%2071.5672V75.9408L350.863%2077.0342H361.793L362.886%2078.1276V89.0576L361.793%2090.151H350.863L349.769%2091.2444V130.591L348.676%20131.684H335.559L334.466%20130.591V91.2444L333.372%2090.151H325.723L324.629%2089.0576V78.1276L325.723%2077.0342H333.372L334.466%2075.9408V71.5672C334.466%2059.5438%20343.209%2055.1702%20353.046%2055.1702H362.882L363.976%2056.2636H363.98Z'%20fill='white'/%3e%3cpath%20d='M404.42%20132.774C400.046%20143.704%20395.677%20150.261%20380.373%20150.261H374.906L373.813%20149.167V138.237L374.906%20137.144H380.373C385.836%20137.144%20386.929%20136.05%20388.023%20132.77V131.677L370.536%2089.05V78.1199L371.63%2077.0265H381.466L382.56%2078.1199L395.677%20115.284H396.77L409.887%2078.1199L410.98%2077.0265H420.817L421.91%2078.1199V89.05L404.424%20132.77L404.42%20132.774Z'%20fill='white'/%3e%3cpath%20d='M135.454%20131.681L134.361%20130.587L134.368%2098.9172C134.368%2093.4541%20132.22%2089.2182%20125.625%2089.0806C122.234%2088.9926%20118.354%2089.0729%20114.209%2089.2488L113.59%2089.8834L113.598%20130.587L112.504%20131.681H99.3913L98.2979%20130.587V77.5388L99.3913%2076.4454L128.901%2076.1778C143.685%2076.1778%20149.668%2086.3356%20149.668%2097.8009V130.587L148.575%20131.681H135.454Z'%20fill='white'/%3e%3c/g%3e%3cdefs%3e%3cclipPath%20id='clip0_235_26'%3e%3crect%20width='512'%20height='208.126'%20fill='white'/%3e%3c/clipPath%3e%3c/defs%3e%3c/svg%3e)
'%3e%3cg%20fill-rule='nonzero'%3e%3cpath%20d='m1099.4%20549.4v-12.5h-21.3l-12.5%2012.5z'%20fill='%23ff8b00'/%3e%3cpath%20d='m1123.4%20518.4h-26.7l-12.6%2012.5h39.3z'%20fill='%2355b2c6'/%3e%3cpath%20d='m1053.2%20561.9%206.4-6.4h21.6v12.5h-28z'%20fill='%23f00'/%3e%3cpath%20d='m1057.9%20543.3h13.8l12.6-12.5h-26.4z'%20fill='%23b4bbbf'/%3e%3cpath%20d='m1042.8%20561.9h10.4l12.4-12.5h-22.8z'%20fill='%23b4bbbf'/%3e%3cpath%20d='m1096.7%20518.4-6.4%206.4h-40.8v-12.5h47.2z'%20fill='%23b4bbbf'/%3e%3cpath%20d='m828.6%20559.7h-19.6l-3.4%208.4h-8.6l18.1-42.4h7.5l18.1%2042.4h-8.7zm-2.7-6.7-7.1-17.3-7.1%2017.3z'%20fill='%23031c4c'/%3e%3cpath%20d='m960.1%20541.3c2.5-3.7%208.8-4.1%2011.4-4.1v7.2c-3.2%200-6.4.1-8.3%201.5s-2.9%203.3-2.9%205.6v16.6h-7.8v-30.9h7.5z'%20fill='%23031c4c'/%3e%3c/g%3e%3cpath%20d='m975.8%20537.2h7.8v30.9h-7.8z'%20fill='%23031c4c'/%3e%3cpath%20d='m975.8%20523.4h7.8v9.2h-7.8z'%20fill='%23031c4c'/%3e%3cpath%20d='m1022.3%20523.4v44.7h-7.5l-.2-4.7c-1.1%201.6-2.5%202.9-4.2%203.9-1.7.9-3.8%201.4-6.2%201.4-2.1%200-4.1-.4-5.8-1.1-1.8-.8-3.4-1.8-4.7-3.2s-2.4-3.1-3.1-5c-.8-1.9-1.1-4.1-1.1-6.5s.4-4.6%201.1-6.6c.8-2%201.8-3.7%203.1-5.1s2.9-2.5%204.7-3.3%203.7-1.2%205.8-1.2c2.4%200%204.4.4%206.1%201.3s3.1%202.1%204.2%203.8v-18.3h7.8zm-16.4%2038.6c2.6%200%204.6-.9%206.2-2.6s2.4-4%202.4-6.8-.8-5-2.4-6.8c-1.6-1.7-3.6-2.6-6.2-2.6-2.5%200-4.6.9-6.1%202.6-1.6%201.7-2.4%204-2.4%206.8s.8%205%202.4%206.7c1.6%201.8%203.6%202.7%206.1%202.7'%20fill='%23031c4c'%20fill-rule='nonzero'/%3e%3cpath%20d='m885.8%20544.2h-19.3v6.7h11c-.3%203.4-1.6%206-3.8%208.1-2.2%202-5%203-8.6%203-2%200-3.9-.4-5.5-1.1-1.7-.7-3.1-1.7-4.3-3.1-1.2-1.3-2.1-2.9-2.8-4.8s-1-3.9-1-6.2.3-4.3%201-6.2c.6-1.9%201.6-3.4%202.8-4.8%201.2-1.3%202.6-2.3%204.3-3.1%201.7-.7%203.5-1.1%205.6-1.1%204.2%200%207.4%201%209.6%203l5.2-5.2c-3.9-3-8.9-4.6-14.8-4.6-3.3%200-6.3.5-9%201.6s-5%202.5-6.9%204.4-3.4%204.2-4.4%206.9-1.5%205.7-1.5%208.9.5%206.2%201.6%208.9%202.5%205%204.4%206.9%204.2%203.4%206.9%204.4c2.7%201.1%205.7%201.6%208.9%201.6s6.1-.5%208.7-1.6%204.8-2.5%206.6-4.4%203.2-4.2%204.2-6.9%201.5-5.7%201.5-8.9v-1.3c-.3-.2-.4-.7-.4-1.1'%20fill='%23031c4c'%20fill-rule='nonzero'/%3e%3cpath%20d='m946.8%20544.2h-19.3v6.7h11c-.3%203.4-1.6%206-3.8%208.1-2.2%202-5%203-8.6%203-2%200-3.9-.4-5.5-1.1-1.7-.7-3.1-1.7-4.3-3.1-1.2-1.3-2.1-2.9-2.8-4.8s-1-3.9-1-6.2.3-4.3%201-6.2c.6-1.9%201.6-3.4%202.8-4.8%201.2-1.3%202.6-2.3%204.3-3.1%201.7-.7%203.5-1.1%205.6-1.1%204.2%200%207.4%201%209.6%203l5.2-5.2c-3.9-3-8.9-4.6-14.8-4.6-3.3%200-6.3.5-9%201.6s-5%202.5-6.9%204.4-3.4%204.2-4.4%206.9-1.5%205.7-1.5%208.9.5%206.2%201.6%208.9%202.5%205%204.4%206.9%204.2%203.4%206.9%204.4c2.7%201.1%205.7%201.6%208.9%201.6s6.1-.5%208.7-1.6%204.8-2.5%206.6-4.4%203.2-4.2%204.2-6.9%201.5-5.7%201.5-8.9v-1.3c-.3-.2-.4-.7-.4-1.1'%20fill='%23031c4c'%20fill-rule='nonzero'/%3e%3c/g%3e%3c/svg%3e)
'%3e%3cg%20fill-rule='nonzero'%3e%3cpath%20d='m1099.4%20549.4v-12.5h-21.3l-12.5%2012.5z'%20fill='%23ff8b00'/%3e%3cpath%20d='m1123.4%20518.4h-26.7l-12.6%2012.5h39.3z'%20fill='%2355b2c6'/%3e%3cpath%20d='m1053.2%20561.9%206.4-6.4h21.6v12.5h-28z'%20fill='%23f00'/%3e%3cpath%20d='m1057.9%20543.3h13.8l12.6-12.5h-26.4z'%20fill='%23b4bbbf'/%3e%3cpath%20d='m1042.8%20561.9h10.4l12.4-12.5h-22.8z'%20fill='%23b4bbbf'/%3e%3cpath%20d='m1096.7%20518.4-6.4%206.4h-40.8v-12.5h47.2z'%20fill='%23b4bbbf'/%3e%3cpath%20d='m828.6%20559.7h-19.6l-3.4%208.4h-8.6l18.1-42.4h7.5l18.1%2042.4h-8.7zm-2.7-6.7-7.1-17.3-7.1%2017.3z'%20fill='%23fff'/%3e%3cpath%20d='m960.1%20541.3c2.5-3.7%208.8-4.1%2011.4-4.1v7.2c-3.2%200-6.4.1-8.3%201.5s-2.9%203.3-2.9%205.6v16.6h-7.8v-30.9h7.5z'%20fill='%23fff'/%3e%3c/g%3e%3cpath%20d='m975.8%20537.2h7.8v30.9h-7.8z'%20fill='%23fff'/%3e%3cpath%20d='m975.8%20523.4h7.8v9.2h-7.8z'%20fill='%23fff'/%3e%3cpath%20d='m1022.3%20523.4v44.7h-7.5l-.2-4.7c-1.1%201.6-2.5%202.9-4.2%203.9-1.7.9-3.8%201.4-6.2%201.4-2.1%200-4.1-.4-5.8-1.1-1.8-.8-3.4-1.8-4.7-3.2s-2.4-3.1-3.1-5c-.8-1.9-1.1-4.1-1.1-6.5s.4-4.6%201.1-6.6c.8-2%201.8-3.7%203.1-5.1s2.9-2.5%204.7-3.3%203.7-1.2%205.8-1.2c2.4%200%204.4.4%206.1%201.3s3.1%202.1%204.2%203.8v-18.3h7.8zm-16.4%2038.6c2.6%200%204.6-.9%206.2-2.6s2.4-4%202.4-6.8-.8-5-2.4-6.8c-1.6-1.7-3.6-2.6-6.2-2.6-2.5%200-4.6.9-6.1%202.6-1.6%201.7-2.4%204-2.4%206.8s.8%205%202.4%206.7c1.6%201.8%203.6%202.7%206.1%202.7'%20fill='%23fff'%20fill-rule='nonzero'/%3e%3cpath%20d='m885.8%20544.2h-19.3v6.7h11c-.3%203.4-1.6%206-3.8%208.1-2.2%202-5%203-8.6%203-2%200-3.9-.4-5.5-1.1-1.7-.7-3.1-1.7-4.3-3.1-1.2-1.3-2.1-2.9-2.8-4.8s-1-3.9-1-6.2.3-4.3%201-6.2c.6-1.9%201.6-3.4%202.8-4.8%201.2-1.3%202.6-2.3%204.3-3.1%201.7-.7%203.5-1.1%205.6-1.1%204.2%200%207.4%201%209.6%203l5.2-5.2c-3.9-3-8.9-4.6-14.8-4.6-3.3%200-6.3.5-9%201.6s-5%202.5-6.9%204.4-3.4%204.2-4.4%206.9-1.5%205.7-1.5%208.9.5%206.2%201.6%208.9%202.5%205%204.4%206.9%204.2%203.4%206.9%204.4c2.7%201.1%205.7%201.6%208.9%201.6s6.1-.5%208.7-1.6%204.8-2.5%206.6-4.4%203.2-4.2%204.2-6.9%201.5-5.7%201.5-8.9v-1.3c-.3-.2-.4-.7-.4-1.1'%20fill='%23fff'%20fill-rule='nonzero'/%3e%3cpath%20d='m946.8%20544.2h-19.3v6.7h11c-.3%203.4-1.6%206-3.8%208.1-2.2%202-5%203-8.6%203-2%200-3.9-.4-5.5-1.1-1.7-.7-3.1-1.7-4.3-3.1-1.2-1.3-2.1-2.9-2.8-4.8s-1-3.9-1-6.2.3-4.3%201-6.2c.6-1.9%201.6-3.4%202.8-4.8%201.2-1.3%202.6-2.3%204.3-3.1%201.7-.7%203.5-1.1%205.6-1.1%204.2%200%207.4%201%209.6%203l5.2-5.2c-3.9-3-8.9-4.6-14.8-4.6-3.3%200-6.3.5-9%201.6s-5%202.5-6.9%204.4-3.4%204.2-4.4%206.9-1.5%205.7-1.5%208.9.5%206.2%201.6%208.9%202.5%205%204.4%206.9%204.2%203.4%206.9%204.4c2.7%201.1%205.7%201.6%208.9%201.6s6.1-.5%208.7-1.6%204.8-2.5%206.6-4.4%203.2-4.2%204.2-6.9%201.5-5.7%201.5-8.9v-1.3c-.3-.2-.4-.7-.4-1.1'%20fill='%23fff'%20fill-rule='nonzero'/%3e%3c/g%3e%3c/svg%3e)
'%3e%3cpath%20d='M255.264%2025.3765H279.579L297.086%2097.519C300.332%20111.135%20300.976%20119.244%20300.976%20119.244H301.304C301.304%20119.244%20302.435%20111.306%20305.681%2097.519L322.373%2025.3765H349.934L367.599%2097.519C371.003%20111.622%20371.818%20119.244%20371.818%20119.244H372.304C372.304%20119.244%20372.632%20111.622%20375.866%2097.519L392.729%2025.3765H417.043L386.249%20143.717H359.174L340.536%2072.0612C336.646%2056.4997%20336.318%2049.5334%20336.318%2049.5334H335.99C335.99%2049.5334%20335.661%2056.4997%20332.099%2072.0612L314.592%20143.717H286.715L255.264%2025.3765Z'%20fill='white'/%3e%3cpath%20d='M412.984%20100.726C412.984%2073.6509%20430.491%2056.1442%20456.921%2056.1442C483.181%2056.1442%20500.688%2073.6509%20500.688%20100.726C500.688%20127.958%20483.181%20145.635%20456.921%20145.635C430.503%20145.623%20412.984%20127.958%20412.984%20100.726ZM477.99%20100.726C477.99%2083.2189%20469.565%2073.3227%20456.921%2073.3227C443.305%2073.3227%20435.682%2084.3495%20435.682%20100.726C435.682%20118.561%20444.107%20128.445%20456.921%20128.445C470.537%20128.445%20477.99%20117.418%20477.99%20100.726Z'%20fill='white'/%3e%3cpath%20d='M511.545%2057.4711H533.101V73.3609H533.587C537.319%2065.0938%20546.231%2056.8267%20561.464%2056.8267C564.054%2056.8267%20565.683%2057.155%20566.813%2057.4711V79.0263H566.169C566.169%2079.0263%20564.224%2078.3819%20558.875%2078.3819C542.182%2078.3819%20533.101%2088.266%20533.101%20106.745V143.704H511.545V57.4711Z'%20fill='white'/%3e%3cpath%20d='M576.868%2025.3765H598.423V63.3079C598.423%2085.6776%20598.095%2089.7261%20598.095%2089.7261H598.423L630.519%2057.4723H657.424L619.833%2094.7592L663.442%20143.717H637.984L606.532%20108.047L598.423%20115.986V143.705H576.868V25.3765Z'%20fill='white'/%3e%3cpath%20d='M663.757%2084.9796C663.757%2048.5072%20686.455%2024.1923%20720.496%2024.1923C754.537%2024.1923%20777.235%2048.5072%20777.235%2084.9796C777.235%20121.452%20754.537%20145.767%20720.496%20145.767C686.455%20145.767%20663.757%20121.452%20663.757%2084.9796ZM753.722%2084.9796C753.722%2060.1784%20740.434%2043.474%20720.483%2043.474C700.533%2043.474%20687.257%2060.1784%20687.257%2084.9796C687.257%20109.781%20700.545%20126.485%20720.483%20126.485C740.422%20126.485%20753.722%20109.781%20753.722%2084.9796Z'%20fill='white'/%3e%3cpath%20d='M785.488%20104.326H810.131C810.131%20118.271%20819.699%20126.052%20834.288%20126.052C846.603%20126.052%20855.041%20119.888%20855.041%20111.135C855.041%20101.25%20848.561%2098.6488%20827.966%2094.6003C809.158%2090.868%20789.22%2084.5461%20789.22%2059.9029C789.22%2039.3203%20806.727%2023.7587%20833.473%2023.7587C861.35%2023.7587%20878.541%2038.3477%20878.541%2060.3892H853.898C853.898%2049.6906%20845.631%2043.0405%20833.473%2043.0405C821.158%2043.0405%20813.535%2049.0341%20813.535%2057.7875C813.535%2067.0272%20818.884%2070.5893%20835.419%2073.9934C859.892%2079.1847%20880%2081.9323%20880%20109.165C880%20130.745%20861.192%20145.333%20833.473%20145.333C805.268%20145.333%20785.488%20128.957%20785.488%20104.326Z'%20fill='white'/%3e%3cpath%20d='M0%2084.0003C0%2087.6782%200.967855%2091.356%202.83904%2094.5177L36.7785%20153.299C40.2628%20159.299%2045.5537%20164.203%2052.1351%20166.397C65.1044%20170.72%2078.5253%20165.171%2084.9131%20154.073L93.1076%20139.878L60.7813%2084.0003L94.9143%2024.8321L103.109%2010.6369C105.561%206.37836%20108.851%202.89408%20112.723%200.119568H109.174H60.0715C50.8446%200.119568%2042.3275%205.02337%2037.7463%2013.0243L2.83904%2073.483C0.967855%2076.6446%200%2080.3225%200%2084.0003Z'%20fill='white'/%3e%3cpath%20d='M193.571%2083.9997C193.571%2080.3219%20192.603%2076.644%20190.732%2073.4824L156.341%2013.9271C149.953%202.89352%20136.532%20-2.65551%20123.563%201.60305C116.982%203.79685%20111.691%208.70065%20108.206%2014.7013L100.464%2028.0577L132.79%2083.9997L98.6569%20143.168L90.4624%20157.363C88.0105%20161.557%2084.7198%20165.106%2080.8484%20167.88H84.3972H133.5C142.727%20167.88%20151.244%20162.977%20155.825%20154.976L190.732%2094.5171C192.603%2091.3554%20193.571%2087.6776%20193.571%2083.9997Z'%20fill='white'/%3e%3c/g%3e%3cdefs%3e%3cclipPath%20id='clip0_1647_45'%3e%3crect%20width='880'%20height='168'%20fill='white'/%3e%3c/clipPath%3e%3c/defs%3e%3c/svg%3e)
'/%3e%3c/svg%3e)
'/%3e%3c/svg%3e)
