@falai/agent 3.4.5 → 4.0.0-alpha.10

package/docs/guides/persistence.md

@@ -1,256 +1,232 @@
 ---
 title: "Persistence"
-description: "Swap the in-memory default for a durable adapter so sessions survive restarts and span processes."
+description: "Where sessions live: the two-method Store, the version check that makes concurrent turns safe, the seven stores, and moving a 3.x row."
 type: guide
-order: 5
+order: 8
 ---
 
 # Persistence
 
-By default, `createAgent` runs against an in-process `MemoryAdapter`. That is the right choice while you are building — zero setup, instant resets between tests — but it forgets every conversation the moment the process exits. Production needs storage that outlives a deploy, scales to multiple replicas, and lets a session resume by id from any machine.
+A store has two methods: `load(id)` and `save(session, expectedVersion)`. The framework never calls either. You load before a turn and save after it.
 
-This guide covers the swap. You will pick an adapter, wire it through `persistence`, resume sessions by `sessionId`, handle concurrent writers with optimistic locking, version your session schema, and run the v1 → v2 schema migration if you are upgrading an existing store.
+```ts
+import { MemoryStore } from "@falai/agent";
 
-## The seven adapters
+const store = new MemoryStore();
 
-`@falai/agent` ships seven adapters. Every one implements the same `PersistenceAdapter` interface, so the swap is one field on `createAgent`.
-
-| Adapter | When to reach for it |
-|---------|---------------------|
-| [`MemoryAdapter`](../reference/adapters.md#memoryadapter) | The implicit default. Tests, prototypes, single-process demos. |
-| [`PrismaAdapter`](../reference/adapters.md#prismaadapter) | You already use Prisma; want a typed schema. |
-| [`RedisAdapter`](../reference/adapters.md#redisadapter) | Fast, ephemeral, TTL-driven session storage. |
-| [`MongoAdapter`](../reference/adapters.md#mongoadapter) | Document-shape; flexible session payloads. |
-| [`PostgreSQLAdapter`](../reference/adapters.md#postgresqladapter) | Single SQL backend without an ORM. |
-| [`SQLiteAdapter`](../reference/adapters.md#sqliteadapter) | Local dev, single-node deploys, CLI tools. |
-| [`OpenSearchAdapter`](../reference/adapters.md#opensearchadapter) | Searchable session and message archive. |
-
-The full per-option contract for every adapter lives in [persistence adapters](../reference/adapters.md). This page sticks to the moves you make once.
-
-## Recipe 1: Swap memory for Prisma
-
-The fastest path to a real database. Add Prisma, declare the session model, point the adapter at the generated client.
+console.log(await store.load("demo")); // null: no conversation yet
+```
 
-**1. Install Prisma.**
+`null` means there is no session for that id. You pass nothing to `turn()`, it hands one back in `result.session`, and you save that. `save` returns the session with its new version; the turn never touches the version, so `TurnResult.session.version` is still the version you loaded.
 
-```bash
-bun add @prisma/client
-bun add -d prisma
-bunx prisma init
-```
+## The Store seam
 
-**2. Declare the session model.** Two columns matter most: `pendingDirective` and `signals`. The agent serializes its [`Directive`](../reference/directive.md) and signals state into them at the end of every turn and reads them back at the start of the next. Both are required on every adapter's session schema in v2. The `version` column is optional but recommended — it enables [optimistic locking](#concurrent-writers-optimistic-locking); without it the adapter degrades gracefully and locking stays inactive.
-
-```prisma
-model AgentSession {
-  id                String    @id
-  userId            String?
-  status            String    @default("active")
-  currentFlow       String?
-  currentStep       String?
-  collectedData     Json?
-  pendingDirective  Json?
-  signals           Json?
-  version           Int?
-  messageCount      Int       @default(0)
-  lastMessageAt     DateTime?
-  completedAt       DateTime?
-  createdAt         DateTime  @default(now())
-  updatedAt         DateTime  @updatedAt
+```ts fragment
+interface Store<D> {
+  load(id: string): Promise<Session<D> | null>;
+  save(session: Session<D>, expectedVersion: number): Promise<Session<D>>;
 }
 ```
 
-**3. Push and generate.**
+The version rules, the same in all seven stores:
 
-```bash
-bunx prisma db push
-bunx prisma generate
-```
-
-**4. Wire the adapter.** Only one field changes on `createAgent` — every flow, step, tool, and instruction stays the same.
+| You pass | The store does | Result |
+|---|---|---|
+| `expectedVersion: 0` | inserts, if no row exists | the row is at version 1 |
+| `expectedVersion: n` | updates, if the row is still at `n` | the row is at `n + 1` |
+| a version the row is not at | nothing | throws `SessionConflictError` |
 
-```typescript
-import { PrismaClient } from "@prisma/client";
-import { createAgent, GeminiProvider, PrismaAdapter } from "@falai/agent";
+```ts
+import { MemoryStore, type Session } from "@falai/agent";
 
-const prisma = new PrismaClient();
+const store = new MemoryStore();
 
-export const agent = createAgent({
-  name: "BookingBot",
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema,
-  flows,
-  persistence: {
-    adapter: new PrismaAdapter({ prisma }),
-    userId: "user_123",
-  },
-});
+const fresh: Session = { id: "demo", v: 4, version: 0, data: {}, runs: [], claims: {}, inputs: [], metadata: {} };
+console.log((await store.save(fresh, 0)).version); // 1
+console.log((await store.load("demo"))?.version); // 1
 ```
 
-That is the whole swap. Every `agent.respond` call now reads and writes through Prisma instead of an in-process map.
+Nobody writes that literal in real code — it is here to show the insert. In an app the session comes from `turn()`.
 
-## Recipe 2: Resume a conversation with `sessionId`
+The session blob is the unit of consistency. Two turns on the same session both load version 3; both run; the first save moves the row to 4 and the second throws. Nothing the loser computed reaches the customer, because you send messages only after a save succeeds. You load again and replay the same input on version 4.
 
-`sessionId` is the contract between client and server. The same id on every request keeps the user pinned to the same conversation; the adapter loads the right `pendingDirective` and `signals`, the agent picks up exactly where the last turn ended.
+## The host loop
 
-There are two equivalent patterns — pick whichever fits your call site.
+```ts
+import { falai, GeminiProvider, MemoryScheduler, MemoryStore, SessionConflictError, type DataOf, type OutboundMessage, type TurnKind } from "@falai/agent";
 
-**Construct-time.** Pass `sessionId` to `createAgent` and the engine auto-loads it at the start of the first turn:
-
-```typescript
-const agent = createAgent({
-  /* ...same as above... */
-  persistence: { adapter: new PrismaAdapter({ prisma }) },
-  sessionId: "user_123:thread_abc",
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
 });
+type Data = DataOf<typeof f>;
 
-await agent.respond({ history: [{ role: "user", content: "Hi again" }] });
-```
-
-**Per-request.** Hydrate explicitly when the session id is only known at request time (typical HTTP server shape):
-
-```typescript
-const session = await agent.session.getOrCreate("user_123:thread_abc");
-
-const response = await agent.respond({
-  history: [{ role: "user", content: "Hi again" }],
-  session,
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [f.flow({ id: "boas-vindas", name: "Boas-vindas", on: [{ message: [] }], steps: [{ id: "nome", collect: ["nome"] }] })],
 });
-```
-
-`getOrCreate` returns the stored `SessionState` (collected data, flow position, `pendingDirective`, signals state) — or creates a fresh session with that id if nothing exists yet. Unknown ids are not an error path; they are the start of a new conversation pinned to that id.
-
-If you load a persisted session blob yourself — a custom cache, a queue payload, a row fetched outside the adapter's normal path — pass it through [`restoreSession`](../reference/adapters.md) instead of hand-shaping a `SessionState`. It is the named inverse of `createPersistedState`: it takes the persisted slice and returns a fully-shaped `SessionState`, including a completed-flow blob whose collected state must survive the round trip.
-
-```typescript
-import { restoreSession } from "@falai/agent";
-
-const session = restoreSession(await myCache.get(sessionId));
-```
-
-A practical id shape: `<userId>:<threadId>`. Keep it stable across restarts and replicas. The adapter does the rest.
 
-## Recipe 3: Redis for fast, ephemeral sessions
-
-Redis is the right pick when you want fast reads, automatic expiry, and do not need long-term archives — chat widgets, ephemeral copilots, anything where a session can reasonably TTL out after a day. The adapter writes JSON-serialized strings under prefixed keys; `pendingDirective` and `signals` ride along inside the session value transparently, so there is no schema to migrate.
-
-```typescript
-import Redis from "ioredis";
-import { createAgent, GeminiProvider, RedisAdapter } from "@falai/agent";
-
-const redis = new Redis(process.env.REDIS_URL!);
+const store = new MemoryStore<Data>();
+const scheduler = new MemoryScheduler(); // your queue in production
+const outbox: OutboundMessage[] = []; // your channel in production
+
+async function runTurn(input: TurnKind & { sessionId: string }): Promise<void> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const session = await store.load(input.sessionId);
+    const r = await agent.turn({ ...input, session: session ?? undefined });
+    if (!r.changed) return; // an ignored input: save nothing, send nothing
+    try {
+      await store.save(r.session, session?.version ?? 0);
+    } catch (error) {
+      if (error instanceof SessionConflictError) continue; // someone saved first: replay on the new version
+      throw error;
+    }
+    outbox.push(...r.messages);
+    for (const entry of r.schedule) scheduler.add(entry);
+    return;
+  }
+  throw new Error(`three conflicts in a row on session "${input.sessionId}": check for a stuck queue worker`);
+}
 
-export const agent = createAgent({
-  name: "BookingBot",
-  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
-  schema,
-  flows,
-  persistence: {
-    adapter: new RedisAdapter({
-      redis,
-      keyPrefix: "myapp:agent:",
-      sessionTTL: 60 * 60 * 24, // 1 day
-      messageTTL: 60 * 60 * 24 * 7, // 1 week
-    }),
-    userId: "user_123",
-  },
-});
+await runTurn({ sessionId: "s1", message: "oi, sou a Ana", id: "m1" });
+console.log(outbox[0]?.text, (await store.load("s1"))?.version); // "…", 1
 ```
 
-A few things worth noting:
-
-- `keyPrefix` namespaces every key the adapter writes — pick something app-specific so it coexists cleanly with other Redis tenants.
-- `sessionTTL` and `messageTTL` are seconds. Pass a large number to effectively disable expiry; default is 7 days for sessions, 30 days for messages.
-- Connection pooling and reconnect strategy come from your Redis client (`ioredis` or `node-redis`) — the adapter does not own them.
-
-If you need an archive of every session and message (audit logs, search, analytics), pair Redis with a second adapter on a slower path, or pick a durable adapter from the table above directly.
+Three attempts is enough: a fourth conflict means two workers are firing on the same session, which is a queue problem, not a race.
 
-## Concurrent writers: optimistic locking
+Three things happen after the save and never before it: messages go out (honouring `afterMs`, keyed by `key`), `schedule[]` entries go into your queue with the key in the payload and `encodeURIComponent(key)` as the job id (BullMQ refuses a `:` in a custom id, and every key has one), and at fire time you call `turn({ wake: key })` through this same loop. `changed: false` means the input changed nothing (a stale wake, a repeated message id): skip the save and the send.
 
-Once sessions span processes, two writers can race on one id — parallel webhooks, a double-send from a chat widget, two browser tabs. Every save is a compare-and-swap on the session's `version` (incremented on each save): the loser's save throws `SessionConflictError` instead of silently overwriting the winner's state. The error carries `sessionId`, `expectedVersion`, and `actualVersion`; the recovery is mechanical — reload, retry.
+## What a row holds
 
-```typescript
-import { ResponseGenerationError, SessionConflictError } from "@falai/agent";
-
-function isSessionConflict(err: unknown): boolean {
-  if (err instanceof SessionConflictError) return true; // bare from respond()
-  if (err instanceof ResponseGenerationError) {
-    return err.cause instanceof SessionConflictError; // wrapped on the stream path
-  }
-  return false;
-}
+Every store writes the same blob and nothing else:
 
-try {
-  return await agent.respond({ history, session });
-} catch (err) {
-  if (isSessionConflict(err)) {
-    const fresh = await agent.session.getOrCreate(sessionId); // reload the winning state
-    return agent.respond({ history, session: fresh });
-  }
-  throw err;
+```ts fragment
+{
+  id, v: 4, version,
+  data,              // the collected fields
+  runs,              // live runs only
+  claims,            // once/cooldown claims, and the last 50 always-claims per flow
+  inputs,            // the last 50 message ids, for replay detection
+  metadata,          // yours
+  lastUserAt?, lastAssistantAt?,
+  history?,          // only when the host does not manage history itself
 }
 ```
 
-Three things you do **not** have to worry about:
-
-- **Same-process concurrency.** Concurrent saves of one session from a single process are serialized through a per-session queue — they never conflict with each other. Conflicts only fire between genuinely independent copies (two processes, or two separately loaded sessions).
-- **Existing rows.** Sessions written by pre-2.4 versions have no stored `version` and are accepted without conflict; the first save stamps them. Memory, Mongo, Redis, and OpenSearch need no schema change at all, and the SQLite/PostgreSQL adapters auto-add the `version` column in `initialize()`.
-- **Opting out.** Prisma users who skip the `version Int?` column simply run without locking — the adapter detects the missing column and degrades gracefully.
-
-The per-adapter storage details live in [persistence adapters](../reference/adapters.md#optimistic-locking); the retry pattern is also covered in [Errors](./error-handling.md).
-
-## Schema versioning: migrate old sessions on load
-
-The locking `version` guards *who* writes; `schemaVersion` guards *what shape* they write. When you rename a schema field or restructure collected data, sessions persisted by the previous deploy still carry the old shape. Declare a `schemaVersion` and a `migrateSession` function, and the agent upgrades stale state at load time:
-
-```typescript
-const agent = createAgent({
-  schema, provider, flows,
-  persistence: {
-    adapter,
-    schemaVersion: 2,
-    migrateSession: (collected, fromVersion) => {
-      // v1 stored `destination`; v2 renamed it to `city`
-      if ((fromVersion ?? 1) < 2) {
-        const { destination, ...rest } = collected.data as { destination?: string };
-        return { ...collected, data: { ...rest, city: destination } };
-      }
-      return collected;
-    },
-  },
-});
+`undefined` values drop and `Date`s become text on the way in, in every store, including `MemoryStore`, which keeps rows as JSON text for exactly this reason. On the way out every store runs `assertSession`, so a row that is not a v4 session for that id throws `InvalidSessionError` instead of coming back as an empty conversation. A store's own `created_at` / `updated_at` columns are never part of the session.
+
+Pass `history` on every `turn()` yourself when you already keep the conversation somewhere. `session.history` is for the playground case where you do not.
+
+## MemoryStore
+
+Nothing survives the process. It is for tests, prototypes and the playground, and it runs the same version check and the same shape check as the durable stores, so a test against it proves the same loop. `clear()` drops every session.
+
+## The six durable stores
+
+All six are optional peer dependencies: you install the driver, open the client, and hand it over. The store never opens a connection of its own. Five of them close the client you gave it with `disconnect()`; `OpenSearchStore` has none, so close that client yourself.
+
+```ts
+import {
+  MongoStore,
+  OpenSearchStore,
+  PostgresStore,
+  PrismaStore,
+  RedisStore,
+  SQLiteStore,
+  type MongoClient,
+  type OpenSearchClient,
+  type PgClient,
+  type PrismaClient,
+  type RedisClient,
+  type SqliteDatabase,
+} from "@falai/agent";
+
+declare const pg: PgClient; // a `pg` Pool or Client
+declare const prisma: PrismaClient; // your generated client
+declare const redis: RedisClient; // an ioredis client
+declare const mongo: MongoClient; // the mongodb driver's MongoClient
+declare const db: SqliteDatabase; // better-sqlite3 or bun:sqlite
+declare const opensearch: OpenSearchClient; // @opensearch-project/opensearch
+
+const postgres = new PostgresStore({ client: pg });
+await postgres.initialize(); // CREATE TABLE IF NOT EXISTS agent_sessions
+
+const viaPrisma = new PrismaStore({ prisma, tables: { sessions: "agentSession" } });
+const viaRedis = new RedisStore({ redis, keyPrefix: "agent:", sessionTTL: 7 * 24 * 60 * 60 });
+const viaMongo = new MongoStore({ client: mongo, databaseName: "app" });
+const sqlite = new SQLiteStore({ db });
+await sqlite.initialize();
+const search = new OpenSearchStore(opensearch, { refresh: "wait_for" });
+await search.initialize();
+
+console.log([postgres, viaPrisma, viaRedis, viaMongo, sqlite, search].length); // 6
 ```
 
-How it behaves:
-
-- Every save stamps the configured `schemaVersion` onto the persisted state.
-- On load, when the stored version differs from the configured one (or is missing — pre-versioning rows pass `fromVersion: undefined`), `migrateSession` runs and its return value is used for the turn. The new stamp persists on the next save.
-- The migrator may be async, and must return state valid for the current `schemaVersion`.
-- With a version mismatch but **no** `migrateSession`, the agent logs a warning and loads the state as-is.
-
-Bump `schemaVersion` with every breaking change to your collected-data shape and keep the migrator's old-version branches around — a long-idle session might skip several versions and arrive with any historical `fromVersion`.
-
-## Schema migration: v1 → v2
-
-If you are upgrading an existing v1 store, the session schema needs two new columns before v2 runs against it:
-
-- **`pendingDirective`** — the persisted [`Directive`](../reference/directive.md) consumed at the start of the next turn. Replaces the v1 column for the same slot.
-- **`signals`** (new in v2) — the [signals](../reference/signals.md) runtime state. Required even if you do not use signals; v2 reads and writes it.
+| Store | Client it takes | Where a session lives | How a conflict is detected |
+|---|---|---|---|
+| `PostgresStore` | `PgClient`: a `pg` `Pool` or `Client` | table `agent_sessions`: `id`, `version`, `blob` JSONB, `created_at`, `updated_at` | `INSERT … ON CONFLICT DO NOTHING` first, `UPDATE … WHERE version = $n` after; no row back is the conflict |
+| `SQLiteStore` | `SqliteDatabase`: better-sqlite3 or `bun:sqlite` | table `agent_sessions`: `id`, `version`, `blob` TEXT, `created_at`, `updated_at` | `INSERT OR IGNORE` first, `UPDATE … WHERE version = ?` after; `changes === 0` is the conflict |
+| `PrismaStore` | `PrismaClient`: your generated client | model `agentSession` with `id`, `version`, `blob Json`, `createdAt`, `updatedAt`; rename with `fieldMappings.sessions` | `create` first, and Prisma's `P2002` is the conflict; `updateMany` on `{ id, version }` after, `count === 0` is the conflict |
+| `RedisStore` | `RedisClient`: ioredis, or node-redis with `eval` wrapped to the positional form | one hash at `${keyPrefix}session:${id}` with `version`, `blob`, `createdAt`, `updatedAt` | one Lua script checks and writes in one step, so two writers on a shared client cannot interleave |
+| `MongoStore` | `MongoClient`: the official driver | collection `agent_sessions`: `_id`, `version`, `blob` as JSON text, `createdAt`, `updatedAt` | `insertOne` first, and the duplicate-key error `11000` is the conflict; `updateOne` on `{ _id, version }` after, `matchedCount === 0` is the conflict |
+| `OpenSearchStore` | `OpenSearchClient`: `@opensearch-project/opensearch` (Elasticsearch 7.x fits) | index `agent_sessions`: `id`, `version`, `blob` stored but not indexed, `createdAt`, `updatedAt` | `index` with `op_type: 'create'` first, and the 409 is the conflict; a painless script after, which becomes a `noop` when the version differs |
+
+Options and defaults:
+
+- `PostgresStore`, `SQLiteStore`: `tables.sessions`, default `"agent_sessions"`. `initialize()` creates the table when it is missing.
+- `PrismaStore`: `tables.sessions` is the model name on the client, default `"agentSession"`; `fieldMappings.sessions` renames any of `id`, `version`, `blob`, `createdAt`, `updatedAt`. The constructor throws a `TypeError` when the client has no such model.
+- `RedisStore`: `keyPrefix`, default `"agent:"`; `sessionTTL` in seconds since the last save, default 7 days; `0` keeps the hash forever.
+- `MongoStore`: `databaseName` is required; `collections.sessions`, default `"agent_sessions"`. The blob is JSON text because claim keys carry channel message ids, which may contain dots that older servers reject in field names.
+- `OpenSearchStore`: the client is the first argument; `indices.sessions`, default `"agent_sessions"`; `autoCreateIndices`, default `true`, for `initialize()`; `refresh`, default `false` (`true` refreshes at once, `"wait_for"` blocks until visible).
+
+Use a fresh table. The default names are the 3.x names, but the columns are new, and a v4 store pointed at a live 3.x table throws `InvalidSessionError` on every load. Create the new table, then move rows with `migrateSession` as they are first needed.
+
+## Moving a 3.x row
+
+A 3.x row holds four keys v4 does not have: `currentFlow`, `currentStep`, `flowHistory` and `signals`. `migrateSession` turns it into one v4 session, once, where you deserialize. The migrated session is at version 0, so your usual save is the insert.
+
+```ts
+import { migrateSession, type Session } from "@falai/agent";
+
+// A 3.x row, as it sits in the old table (shape from tests/fixtures/blobs/prospectar-midflow.json).
+const legacyRow: unknown = {
+  id: "session_1756731890123_k3j9x2",
+  currentFlow: { id: "qualificacao", title: "Qualificação", enteredAt: "2026-09-01T13:05:12.000Z" },
+  currentStep: { id: "ask_budget", enteredAt: "2026-09-01T13:07:40.000Z" },
+  data: { nome: "Mariana", empresa: "Padaria Estrela", tamanho: "1-10" },
+  flowHistory: [
+    { flowId: "boas_vindas", enteredAt: "2026-09-01T13:04:50.000Z", exitedAt: "2026-09-01T13:05:12.000Z", completed: true },
+    { flowId: "qualificacao", enteredAt: "2026-09-01T13:05:12.000Z", completed: false },
+  ],
+  metadata: { workspaceId: "ws_demo", channel: "whatsapp" },
+  version: 12,
+};
+
+const session: Session = migrateSession(legacyRow, {
+  sessionId: "session_1756731890123_k3j9x2",
+  flowIdOf: (key) => key, // an old flow id, or a key under `signals.triggers` → v4 flow id; identity when you kept the ids
+});
 
-Without these columns, v2 throws a driver-specific column-not-found error on the first write, and any v1 value in the old slot is silently dropped on read.
+console.log(session.version); // 0
+console.log(session.runs[0]?.flowId, session.runs[0]?.stepId, session.runs[0]?.status); // qualificacao ask_budget asking
+console.log(Object.keys(session.claims)); // [ 'boas_vindas:session_…:', 'qualificacao:session_…:' ]
+```
 
-The full migration steps per adapter — SQL `ALTER TABLE` for Postgres and SQLite, Prisma model diff, MongoDB `updateMany`, Redis Lua transform, OpenSearch `_reindex` script — live in the [v1 → v2 migration guide](../migration/v1-to-v2.md). Run those once against your store before deploying v2.
+What the migration keeps and drops:
 
-For brand-new v2 deploys there is nothing to migrate. The `PostgreSQLAdapter`, `SQLiteAdapter`, and `OpenSearchAdapter` create v2-shaped tables and indices when you call `await adapter.initialize()` once on boot. The `PrismaAdapter` and `MongoAdapter` follow your declared schema. The `MemoryAdapter` and `RedisAdapter` need no DDL at all.
+- `data` is kept as it is, the same object.
+- `currentFlow` plus `currentStep` become one run at that step with `status: "asking"`, so the conversation keeps its place. Keep your talk-step ids when you convert flows. A flow entered before its first step becomes a `running` run with no step.
+- Every completed `flowHistory` entry and every `signals.triggers[key]` becomes a claim, `${flowIdOf(key)}:${sessionId}:`, so a `once` flow does not fire again. The mid-flow run gets its own claim too.
+- `metadata` is kept, with any `Date` turned into ISO text.
+- `history` is kept only when the row had one.
+- Every other 3.x key is dropped, the old `version` included: the new table has no row yet.
 
-## Verification
+A blob that already carries `v: 4` passes straight through `assertSession`. Anything that is neither throws `InvalidSessionError`.
 
-A quick checklist after the swap:
+`assertSession(blob, sessionId)` is the shape check on its own, for a blob you read from somewhere other than a store. It returns a `Session` holding only the session keys, or throws.
 
-1. **Restart the process between turns** and confirm the session resumes — same flow, same step, same collected data.
-2. **Inspect the row.** `pendingDirective` and `signals` should be present (possibly `null`); `collectedData` should hold whatever fields the user has supplied so far.
-3. **Run two requests with the same `sessionId` from different processes** (e.g., two `curl` calls against your endpoint). The second turn should land at the right step without re-asking for collected fields.
+## Checking a store of your own
 
-If any of these fails, the issue is almost always the schema — re-check the column names against [persistence adapters](../reference/adapters.md) for your adapter and run the [v1 → v2 migration](../migration/v1-to-v2.md) if applicable.
+If you write a `Store` for another database, it needs the same three behaviours: `0` inserts and refuses to overwrite an existing row, a matching version updates and bumps by one, and a stale version throws `SessionConflictError` with the stored version in `actualVersion`. Read the blob back through `assertSession`. `tests/store-contract.test.ts` in the repo runs one contract against all seven stores; copy it.
 
-**Next:** [Streaming](./streaming.md)
+See [the stores reference](../reference/stores.md) for every option type, and [the session reference](../reference/session.md) for the blob's fields.