@checkstack/ai-backend 0.1.0

package/src/chat/classifier-service.ts

@@ -0,0 +1,64 @@
+import { generateText, type LanguageModel, type LanguageModelUsage } from "ai";
+import {
+  buildClassifierPrompt,
+  parseClassifierVerdict,
+  type ClassifierVerdict,
+} from "./classifier.logic";
+
+/**
+ * Result of a single classifier call: the verdict plus the (small) token usage
+ * so the caller can record it against the spend ledger like any other model
+ * call. Usage is best-effort - a provider that omits counts yields zeros.
+ */
+export interface ClassifierResult {
+  verdict: ClassifierVerdict;
+  usage: LanguageModelUsage;
+}
+
+/**
+ * The model call used by the classifier. Defaults to the AI SDK's
+ * `generateText` against the turn's resolved model; INJECTABLE (like the title
+ * generator) so the chat-service short-circuit logic is unit-testable WITHOUT a
+ * live provider mock.
+ */
+export type ClassifierTextGenerator = (args: {
+  model: LanguageModel;
+  system: string;
+  prompt: string;
+}) => Promise<{ text: string; usage: LanguageModelUsage }>;
+
+/** Default generator: a cheap `generateText` reusing the turn's model. */
+const defaultGenerateClassifierText: ClassifierTextGenerator = async ({
+  model,
+  system,
+  prompt,
+}) => {
+  const { text, usage } = await generateText({ model, system, prompt });
+  return { text, usage };
+};
+
+/**
+ * Classify whether the user's message is on-topic for operating Checkstack.
+ *
+ * Runs the cheap classifier model call and parses its reply. The call is NOT
+ * fail-open here: it propagates a thrown error so the caller can decide to
+ * fail-open (proceed with the normal turn) AND distinguish a classifier outage
+ * from a real OFF_TOPIC verdict. A non-throwing reply is parsed leniently
+ * (ambiguous -> ON_TOPIC) by `parseClassifierVerdict`.
+ */
+export async function classifyTopic({
+  model,
+  userText,
+  generate = defaultGenerateClassifierText,
+}: {
+  /** The already-built language model used for the turn (provider-agnostic). */
+  model: LanguageModel;
+  /** The user's new message text. */
+  userText: string;
+  /** Override the model call (tests inject a fake; defaults to generateText). */
+  generate?: ClassifierTextGenerator;
+}): Promise<ClassifierResult> {
+  const { system, prompt } = buildClassifierPrompt({ userText });
+  const { text, usage } = await generate({ model, system, prompt });
+  return { verdict: parseClassifierVerdict(text), usage };
+}

package/src/chat/classifier.logic.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildClassifierPrompt,
+  parseClassifierVerdict,
+  OFF_TOPIC_REFUSAL,
+} from "./classifier.logic";
+
+describe("buildClassifierPrompt", () => {
+  test("carries the user text verbatim as the prompt and a non-empty system prompt", () => {
+    const { system, prompt } = buildClassifierPrompt({
+      userText: "Summarize the open incidents",
+    });
+    expect(prompt).toBe("Summarize the open incidents");
+    expect(system.length).toBeGreaterThan(0);
+    // The system prompt names the platform domains so the model knows what is
+    // on-topic.
+    expect(system).toContain("Checkstack");
+    expect(system).toContain("ON_TOPIC");
+    expect(system).toContain("OFF_TOPIC");
+  });
+
+  test("system prompt explicitly lists meta/capability questions as ON_TOPIC", () => {
+    const { system } = buildClassifierPrompt({ userText: "what can you do?" });
+    // Must contain language that classifies assistant capability/meta questions
+    // as ON_TOPIC. If this regresses (e.g. someone tightens the prompt and
+    // removes the meta allowance), this assertion catches it.
+    expect(system).toMatch(/what can you do|meta.*capability|capability.*question/i);
+  });
+
+  test("system prompt explicitly lists greetings as ON_TOPIC", () => {
+    const { system } = buildClassifierPrompt({ userText: "hi" });
+    // Greetings / conversational openers must be named in the ON_TOPIC section.
+    expect(system).toMatch(/greeting|conversational opener|\"hi\"/i);
+  });
+
+  test("system prompt explicitly lists how-to/conceptual questions as ON_TOPIC", () => {
+    const { system } = buildClassifierPrompt({
+      userText: "how do health checks work?",
+    });
+    // How-to and conceptual questions about using Checkstack must be on-topic.
+    expect(system).toMatch(/how.to|conceptual/i);
+  });
+
+  test("system prompt restricts OFF_TOPIC to CLEARLY unrelated requests only", () => {
+    const { system } = buildClassifierPrompt({ userText: "write me a poem" });
+    // The word "clearly" (or equivalent) must gate the OFF_TOPIC definition so
+    // borderline messages default to ON_TOPIC.
+    expect(system).toMatch(/clearly unrelated|CLEARLY unrelated/i);
+  });
+
+  test("system prompt retains the 'when in doubt' ON_TOPIC default", () => {
+    const { system } = buildClassifierPrompt({ userText: "???" });
+    expect(system).toMatch(/when in doubt.*on_topic/i);
+  });
+});
+
+describe("parseClassifierVerdict", () => {
+  test("recognizes a bare ON_TOPIC reply", () => {
+    expect(parseClassifierVerdict("ON_TOPIC")).toBe("ON_TOPIC");
+  });
+
+  test("recognizes a bare OFF_TOPIC reply", () => {
+    expect(parseClassifierVerdict("OFF_TOPIC")).toBe("OFF_TOPIC");
+  });
+
+  test("tolerates surrounding whitespace/punctuation/casing on OFF_TOPIC", () => {
+    expect(parseClassifierVerdict("  off_topic.\n")).toBe("OFF_TOPIC");
+    expect(parseClassifierVerdict("Verdict: OFF-TOPIC")).toBe("OFF_TOPIC");
+  });
+
+  test("defaults ambiguous replies to ON_TOPIC (false refusal is worse)", () => {
+    expect(parseClassifierVerdict("maybe?")).toBe("ON_TOPIC");
+    expect(parseClassifierVerdict("")).toBe("ON_TOPIC");
+    expect(parseClassifierVerdict("I think this is fine")).toBe("ON_TOPIC");
+  });
+
+  test("a reply mentioning BOTH tokens defaults to ON_TOPIC (does not refuse)", () => {
+    expect(parseClassifierVerdict("not OFF_TOPIC, it is ON_TOPIC")).toBe(
+      "ON_TOPIC",
+    );
+  });
+
+  test("the canned refusal is concise, uses no em-dashes, and nudges toward supported topics", () => {
+    expect(OFF_TOPIC_REFUSAL).toContain("Checkstack");
+    expect(OFF_TOPIC_REFUSAL).not.toContain("—");
+    // The refusal should redirect the user rather than just saying "I can't".
+    // It must mention at least one supported domain so the user knows what to ask.
+    expect(OFF_TOPIC_REFUSAL).toMatch(
+      /incident|health check|anomal|automation/i,
+    );
+  });
+});

package/src/chat/classifier.logic.ts

@@ -0,0 +1,71 @@
+/**
+ * Pure, DOM-free helpers for the cheap topical PRE-CLASSIFIER that runs before
+ * the expensive agent/tool loop. The classifier asks a small model whether the
+ * user's message is about operating Checkstack; an OFF_TOPIC verdict lets the
+ * chat service short-circuit with a canned refusal INSTEAD of running the full
+ * tool loop, saving generation + tool tokens.
+ *
+ * Both functions are total (never throw). The parser leans toward ON_TOPIC on
+ * anything it does not clearly recognize as OFF_TOPIC: a false refusal of a real
+ * ops question is worse than letting one off-topic request slide.
+ */
+
+/** The classifier's verdict. ON_TOPIC proceeds; OFF_TOPIC short-circuits. */
+export type ClassifierVerdict = "ON_TOPIC" | "OFF_TOPIC";
+
+/**
+ * System prompt for the classifier. Kept tiny + deterministic: the model must
+ * reply with a bare token so the (cheap) call stays short. The parser defends
+ * against any decoration regardless.
+ */
+const CLASSIFIER_SYSTEM_PROMPT =
+  "You are a topical classifier for Checkstack, an incident, health-check, " +
+  "anomaly, automation, and monitoring/operations platform. Decide whether the " +
+  "user's message is ON_TOPIC or OFF_TOPIC. " +
+  "ON_TOPIC includes: operating or reasoning about Checkstack (incidents, " +
+  "health checks, anomalies, automations, monitoring, on-call, the platform's " +
+  "data and configuration); meta/capability questions about the assistant itself " +
+  "(\"what can you do\", \"who are you\", \"help\", \"what features do you have\"); " +
+  "greetings and conversational openers (\"hi\", \"hello\", \"hey\"); " +
+  "how-to or conceptual questions about using Checkstack features or workflows " +
+  "(\"how do health checks work\", \"how do I create an automation\"). " +
+  "OFF_TOPIC means CLEARLY unrelated requests: general coding help unrelated to " +
+  "Checkstack, creative writing, and general trivia or knowledge questions. " +
+  "When in doubt, reply ON_TOPIC. Reply with the token only.";
+
+/**
+ * The canned refusal returned (over the normal SSE stream) when the classifier
+ * says OFF_TOPIC. Concise, with a one-line redirect. No em-dashes (user-facing).
+ */
+export const OFF_TOPIC_REFUSAL =
+  "That looks outside my scope - I focus on Checkstack monitoring and " +
+  "operations (incidents, health checks, anomalies, automations). " +
+  "Try asking me about those, or ask \"what can you do?\" to see what I support.";
+
+/**
+ * Build the classifier prompt pair (system + user) for a given message. Pure so
+ * the prompt shape is unit-testable without a model. The user message is passed
+ * through verbatim as the prompt (the system prompt carries all instruction).
+ */
+export function buildClassifierPrompt({
+  userText,
+}: {
+  userText: string;
+}): { system: string; prompt: string } {
+  return { system: CLASSIFIER_SYSTEM_PROMPT, prompt: userText };
+}
+
+/**
+ * Parse the classifier's raw reply into a verdict. Returns OFF_TOPIC only when
+ * the reply clearly says so (contains the OFF_TOPIC token and NOT the ON_TOPIC
+ * token); everything else - ON_TOPIC, ambiguous, empty, or unrecognized -
+ * defaults to ON_TOPIC (fail toward letting a real ops question through).
+ */
+export function parseClassifierVerdict(raw: string): ClassifierVerdict {
+  const upper = raw.toUpperCase();
+  const saysOff = upper.includes("OFF_TOPIC") || upper.includes("OFF-TOPIC");
+  const saysOn = upper.includes("ON_TOPIC") || upper.includes("ON-TOPIC");
+  // Only treat as OFF_TOPIC when the reply unambiguously says off and not on.
+  if (saysOff && !saysOn) return "OFF_TOPIC";
+  return "ON_TOPIC";
+}

package/src/chat/conversation-store.it.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Cross-pod conversation readback (real Postgres) — matrix #15, plan §16,
+ * state-and-scale §9.
+ *
+ * The DETERMINISTIC backstop the single-process unit suite cannot provide: "does
+ * a read return the same answer on every pod?". A conversation created against
+ * one connection pool MUST be readable, owner-scoped, via a SECOND pool over the
+ * SAME Postgres — because the chat agent loop is resumable on whichever pod
+ * handles the next turn, and nothing about a conversation is pod-local.
+ *
+ * Two-pod model (faithful proxy, mirrors `automation-backend`'s
+ * `cross-pod-read-consistency.it.test.ts`): two independent `AiConversationStore`
+ * instances, each over its OWN `pg.Pool`, BOTH pointed at the SAME schema.
+ * Separate pools = no shared JS heap; one DB = the shared durable substrate N
+ * pods share in production.
+ *
+ * NEGATIVE: a conversation owned by user A is NOT readable by user B from pod B
+ * (the store is always owner-scoped, so it can never leak another user's chat).
+ *
+ * Gated behind `CHECKSTACK_IT=1`; connection from `CHECKSTACK_IT_PG_URL`. Runs in
+ * a freshly created, self-cleaning schema.
+ */
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import * as schema from "../schema";
+import {
+  createAiConversationStore,
+  type AiConversationStore,
+} from "./conversation-store";
+
+const PG_URL =
+  process.env.CHECKSTACK_IT_PG_URL ??
+  "postgres://postgres:postgres@localhost:5432/postgres";
+
+const SCHEMA = `it_ai_conv_${crypto.randomUUID().replace(/-/g, "")}`;
+
+interface Pod {
+  pool: Pool;
+  store: AiConversationStore;
+  end(): Promise<void>;
+}
+
+function makePod(): Pod {
+  const pool = new Pool({
+    connectionString: PG_URL,
+    options: `-c search_path=${SCHEMA}`,
+  });
+  const db = drizzle(pool, { schema }) as unknown as SafeDatabase<typeof schema>;
+  return { pool, store: createAiConversationStore({ db }), end: () => pool.end() };
+}
+
+describe.skipIf(!process.env.CHECKSTACK_IT)(
+  "cross-pod conversation readback (shared Postgres)",
+  () => {
+    let admin: Pool;
+    let podA: Pod;
+    let podB: Pod;
+
+    beforeAll(async () => {
+      admin = new Pool({ connectionString: PG_URL });
+      await admin.query(`CREATE SCHEMA "${SCHEMA}"`);
+      await admin.query(`
+        CREATE TABLE "${SCHEMA}".ai_conversations (
+          id text PRIMARY KEY,
+          user_id text NOT NULL,
+          title text,
+          integration_id text,
+          model text,
+          permission_mode text NOT NULL DEFAULT 'approve',
+          created_at timestamp NOT NULL DEFAULT now(),
+          updated_at timestamp NOT NULL DEFAULT now(),
+          archived_at timestamp
+        )
+      `);
+      await admin.query(`
+        CREATE TABLE "${SCHEMA}".ai_messages (
+          id text PRIMARY KEY,
+          conversation_id text NOT NULL
+            REFERENCES "${SCHEMA}".ai_conversations(id) ON DELETE CASCADE,
+          role text NOT NULL,
+          content jsonb NOT NULL,
+          tool_calls jsonb,
+          model_messages jsonb,
+          created_at timestamp NOT NULL DEFAULT now()
+        )
+      `);
+      podA = makePod();
+      podB = makePod();
+    });
+
+    afterAll(async () => {
+      await podA?.end();
+      await podB?.end();
+      await admin.query(`DROP SCHEMA IF EXISTS "${SCHEMA}" CASCADE`);
+      await admin.end();
+    });
+
+    it("a conversation created on pod A is fully readable on pod B (same owner)", async () => {
+      const created = await podA.store.createConversation({
+        userId: "user-A",
+        title: "Investigate prod outage",
+        integrationId: "ai.openai-compatible.c1",
+        model: "gpt-4o-mini",
+      });
+      await podA.store.appendMessage({
+        conversationId: created.id,
+        role: "user",
+        content: { text: "what changed in the last hour?" },
+      });
+
+      // Pod B — a DIFFERENT pool, no shared heap — reads the SAME conversation.
+      const fetched = await podB.store.getConversation({
+        id: created.id,
+        userId: "user-A",
+      });
+      expect(fetched?.id).toBe(created.id);
+      expect(fetched?.title).toBe("Investigate prod outage");
+      expect(fetched?.model).toBe("gpt-4o-mini");
+
+      // And the transcript continues correctly from pod B.
+      const messages = await podB.store.listMessages({
+        conversationId: created.id,
+      });
+      expect(messages).toHaveLength(1);
+      expect(messages[0]?.content).toEqual({
+        text: "what changed in the last hour?",
+      });
+
+      // A follow-up appended on pod B is visible back on pod A (resumable). The
+      // assistant turn carries the canonical AI-SDK ResponseMessage[] for
+      // tool-call REPLAY — it must round-trip cross-pod so the next turn on any
+      // pod replays the prior tool interaction (state-and-scale §9).
+      await podB.store.appendMessage({
+        conversationId: created.id,
+        role: "assistant",
+        content: { text: "a deploy at 14:02" },
+        modelMessages: [
+          {
+            role: "assistant",
+            content: [
+              {
+                type: "tool-call",
+                toolCallId: "tc1",
+                toolName: "incident.list",
+                input: { status: "open" },
+              },
+            ],
+          },
+          {
+            role: "tool",
+            content: [
+              {
+                type: "tool-result",
+                toolCallId: "tc1",
+                toolName: "incident.list",
+                output: { type: "json", value: { rows: [] } },
+              },
+            ],
+          },
+        ],
+      });
+      const fromA = await podA.store.listMessages({ conversationId: created.id });
+      expect(fromA.map((m) => m.role)).toEqual(["user", "assistant"]);
+      // The replay history written on pod B is fully readable on pod A.
+      const assistant = fromA[1];
+      expect(assistant?.modelMessages).toHaveLength(2);
+      expect(assistant?.modelMessages?.[0]?.role).toBe("assistant");
+      expect(assistant?.modelMessages?.[1]?.role).toBe("tool");
+    });
+
+    it("NEGATIVE: pod B cannot read user A's conversation as a DIFFERENT user", async () => {
+      const created = await podA.store.createConversation({
+        userId: "user-A",
+        title: "private",
+      });
+
+      // User B asks pod B for the row by id — owner-scoped read returns nothing.
+      const leaked = await podB.store.getConversation({
+        id: created.id,
+        userId: "user-B",
+      });
+      expect(leaked).toBeUndefined();
+
+      // User B's list never includes it either.
+      const listB = await podB.store.listConversations({ userId: "user-B" });
+      expect(listB.find((c) => c.id === created.id)).toBeUndefined();
+
+      // And user B cannot delete it (owner-scoped) — the row survives.
+      const deleted = await podB.store.deleteConversation({
+        id: created.id,
+        userId: "user-B",
+      });
+      expect(deleted).toBe(false);
+      const stillThere = await podA.store.getConversation({
+        id: created.id,
+        userId: "user-A",
+      });
+      expect(stillThere?.id).toBe(created.id);
+    });
+  },
+);

package/src/chat/conversation-store.test.ts

@@ -0,0 +1,248 @@
+import { describe, expect, test, mock } from "bun:test";
+import { createAiConversationStore } from "./conversation-store";
+import type { AiConversationRow, AiMessageRow } from "../schema";
+
+/**
+ * State-and-scale (#15): the conversation store is pure shared-Postgres CRUD —
+ * it holds NO pod-local state, so a conversation written by one pod is readable
+ * by any other simply because both read/write the same database. These unit
+ * tests assert that property structurally:
+ *
+ *  - every read/write goes through the injected `db` (no in-memory cache that
+ *    would diverge between pods), and
+ *  - reads are always owner-scoped (a `userId` filter), so the store can never
+ *    leak another user's chat.
+ *
+ * True cross-pod readback against a live Postgres is exercised in
+ * `conversation-store.it.test.ts` (env-gated). Here we use a spy db.
+ */
+
+function convRow(over: Partial<AiConversationRow> = {}): AiConversationRow {
+  return {
+    id: "c1",
+    userId: "u1",
+    title: "t",
+    integrationId: null,
+    model: null,
+    permissionMode: "approve",
+    createdAt: new Date("2026-06-01T00:00:00Z"),
+    updatedAt: new Date("2026-06-01T00:00:00Z"),
+    archivedAt: null,
+    ...over,
+  };
+}
+
+function msgRow(over: Partial<AiMessageRow> = {}): AiMessageRow {
+  return {
+    id: "m1",
+    conversationId: "c1",
+    role: "user",
+    content: { text: "hi" },
+    toolCalls: null,
+    modelMessages: null,
+    createdAt: new Date("2026-06-01T00:00:00Z"),
+    ...over,
+  };
+}
+
+describe("AiConversationStore", () => {
+  test("createConversation inserts and returns the row", async () => {
+    const returning = mock(() => Promise.resolve([convRow()]));
+    const values = mock((_v: Record<string, unknown>) => ({ returning }));
+    const db = { insert: mock(() => ({ values })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    const created = await store.createConversation({
+      userId: "u1",
+      title: "t",
+      integrationId: "ai.openai-compatible.c1",
+      model: "gpt-4o-mini",
+    });
+    expect(created.id).toBe("c1");
+    const inserted = values.mock.calls[0]?.[0] as {
+      userId: string;
+      model: string;
+    };
+    expect(inserted.userId).toBe("u1");
+    expect(inserted.model).toBe("gpt-4o-mini");
+  });
+
+  test("createConversation passes permissionMode through to the insert", async () => {
+    const returning = mock(() =>
+      Promise.resolve([convRow({ permissionMode: "auto" })]),
+    );
+    const values = mock((_v: Record<string, unknown>) => ({ returning }));
+    const db = { insert: mock(() => ({ values })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    const created = await store.createConversation({
+      userId: "u1",
+      permissionMode: "auto",
+    });
+    expect(created.permissionMode).toBe("auto");
+    const inserted = values.mock.calls[0]?.[0] as { permissionMode?: string };
+    expect(inserted.permissionMode).toBe("auto");
+  });
+
+  test("createConversation omits permissionMode when not given (column default applies)", async () => {
+    const returning = mock(() => Promise.resolve([convRow()]));
+    const values = mock((_v: Record<string, unknown>) => ({ returning }));
+    const db = { insert: mock(() => ({ values })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    await store.createConversation({ userId: "u1" });
+    const inserted = values.mock.calls[0]?.[0] as { permissionMode?: string };
+    // Omitted -> undefined, so the NOT NULL DEFAULT 'approve' column applies.
+    expect(inserted.permissionMode).toBeUndefined();
+  });
+
+  test("updateConversation writes permissionMode (owner-scoped) and bumps updatedAt", async () => {
+    const returning = mock(() =>
+      Promise.resolve([convRow({ permissionMode: "auto" })]),
+    );
+    const where = mock(() => ({ returning }));
+    const set = mock(
+      (_patch: { permissionMode?: string; updatedAt: Date }) => ({ where }),
+    );
+    const db = { update: mock(() => ({ set })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    const updated = await store.updateConversation({
+      id: "c1",
+      userId: "u1",
+      permissionMode: "auto",
+    });
+    expect(updated?.permissionMode).toBe("auto");
+    const patch = set.mock.calls[0]?.[0] as {
+      permissionMode?: string;
+      updatedAt: Date;
+    };
+    expect(patch.permissionMode).toBe("auto");
+    expect(patch.updatedAt).toBeInstanceOf(Date);
+    // Owner-scoped: a WHERE clause filtering id + userId is always present.
+    expect(where).toHaveBeenCalledTimes(1);
+  });
+
+  test("updateConversation leaves permissionMode untouched when not provided", async () => {
+    const returning = mock(() => Promise.resolve([convRow()]));
+    const where = mock(() => ({ returning }));
+    const set = mock((_patch: Record<string, unknown>) => ({ where }));
+    const db = { update: mock(() => ({ set })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    await store.updateConversation({ id: "c1", userId: "u1", title: "new" });
+    const patch = set.mock.calls[0]?.[0] as { permissionMode?: string };
+    expect(patch.permissionMode).toBeUndefined();
+  });
+
+  test("getConversation reads through the db (no pod-local cache) and is owner-scoped", async () => {
+    const where = mock(() => ({ limit: () => Promise.resolve([convRow()]) }));
+    const from = mock(() => ({ where }));
+    const db = { select: mock(() => ({ from })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    const fetched = await store.getConversation({ id: "c1", userId: "u1" });
+    expect(fetched?.id).toBe("c1");
+    // Every read hits the shared db — there is no in-memory shortcut that would
+    // return different answers on different pods.
+    expect(db.select).toHaveBeenCalledTimes(1);
+    // The query is filtered (id + userId): the WHERE clause is always present so
+    // a caller can never read another user's conversation.
+    expect(where).toHaveBeenCalledTimes(1);
+  });
+
+  test("appendMessage inserts the message and bumps the conversation updatedAt", async () => {
+    const returning = mock(() => Promise.resolve([msgRow()]));
+    const values = mock(() => ({ returning }));
+    const updateWhere = mock(() => Promise.resolve([]));
+    const set = mock((_patch: { updatedAt: Date }) => ({ where: updateWhere }));
+    const db = {
+      insert: mock(() => ({ values })),
+      update: mock(() => ({ set })),
+    };
+    const store = createAiConversationStore({ db: db as never });
+
+    const m = await store.appendMessage({
+      conversationId: "c1",
+      role: "assistant",
+      content: { text: "hello" },
+    });
+    expect(m.id).toBe("m1");
+    // updatedAt bump = an UPDATE on the conversation row.
+    expect(db.update).toHaveBeenCalledTimes(1);
+    const patch = set.mock.calls[0]?.[0] as { updatedAt: Date };
+    expect(patch.updatedAt).toBeInstanceOf(Date);
+  });
+
+  test("listMessages reads ordered by createdAt for the conversation", async () => {
+    const orderBy = mock(() =>
+      Promise.resolve([msgRow({ id: "m1" }), msgRow({ id: "m2" })]),
+    );
+    const where = mock(() => ({ orderBy }));
+    const from = mock(() => ({ where }));
+    const db = { select: mock(() => ({ from })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    const msgs = await store.listMessages({ conversationId: "c1" });
+    expect(msgs.map((m) => m.id)).toEqual(["m1", "m2"]);
+    expect(orderBy).toHaveBeenCalledTimes(1);
+  });
+
+  test("listConversations is owner-scoped and ordered newest-first", async () => {
+    const orderBy = mock(() => Promise.resolve([convRow()]));
+    const where = mock(() => ({ orderBy }));
+    const from = mock(() => ({ where }));
+    const db = { select: mock(() => ({ from })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    await store.listConversations({ userId: "u1" });
+    expect(where).toHaveBeenCalledTimes(1);
+    expect(orderBy).toHaveBeenCalledTimes(1);
+  });
+
+  test("archiveConversation soft-deletes via UPDATE (never DELETE), owner-scoped", async () => {
+    const returning = mock(() => Promise.resolve([{ id: "c1" }]));
+    const where = mock(() => ({ returning }));
+    const set = mock((_patch: { archivedAt: Date }) => ({ where }));
+    const db = {
+      update: mock(() => ({ set })),
+      // A DELETE on the store during archive would be a bug — assert it never runs.
+      delete: mock(() => {
+        throw new Error("archive must not hard-delete");
+      }),
+    };
+    const store = createAiConversationStore({ db: db as never });
+
+    expect(await store.archiveConversation({ id: "c1", userId: "u1" })).toBe(
+      true,
+    );
+    // Soft delete = UPDATE stamping archivedAt, never a row removal.
+    expect(db.update).toHaveBeenCalledTimes(1);
+    expect(db.delete).not.toHaveBeenCalled();
+    const patch = set.mock.calls[0]?.[0] as { archivedAt: Date };
+    expect(patch.archivedAt).toBeInstanceOf(Date);
+    expect(where).toHaveBeenCalledTimes(1);
+  });
+
+  test("archiveConversation returns false when no owned active row matched", async () => {
+    const returning = mock(() => Promise.resolve([]));
+    const where = mock(() => ({ returning }));
+    const set = mock(() => ({ where }));
+    const db = { update: mock(() => ({ set })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    expect(await store.archiveConversation({ id: "c1", userId: "u1" })).toBe(
+      false,
+    );
+  });
+
+  test("deleteConversation is owner-scoped and reports whether a row was removed", async () => {
+    const returning = mock(() => Promise.resolve([{ id: "c1" }]));
+    const where = mock(() => ({ returning }));
+    const db = { delete: mock(() => ({ where })) };
+    const store = createAiConversationStore({ db: db as never });
+
+    expect(await store.deleteConversation({ id: "c1", userId: "u1" })).toBe(true);
+    expect(where).toHaveBeenCalledTimes(1);
+  });
+});