@pithy-sh/support 0.1.0

package/src/seeds/example.ts

@@ -0,0 +1,385 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed, type SeedSet } from "@pithy-sh/core/src/seed/seed";
+import { SupportClassification } from "../data/classification";
+import { SupportMessage } from "../data/message";
+import { SUPPORT_CLASSIFICATIONS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE } from "../data/tables";
+import { SupportThread } from "../data/thread";
+
+/**
+ * Four conversations for the canonical example cast, spread across the shapes a dashboard has to
+ * render.
+ *
+ * **Ada** is angry about a double charge — `billing`, `urgent`, and she is the one with a live Apple
+ * subscription in the payments seed, so a thread view opened on her shows the linkage working end to
+ * end rather than an empty panel. **Grace** cannot sign in — `account_access`, `normal`, two
+ * messages, so the thread view has an actual conversation in it and the reply path has something
+ * threaded to attach to. **Alan** sent a feature request that has been dealt with — `feature_request`,
+ * `low`, `positive`, and **archived**, so the done pile is not empty on a fresh backend and the
+ * archived filter is demonstrably doing something.
+ *
+ * **Grace again, from inside the app** — a `bug_report` filed through `POST /support/feedback`, so the
+ * fixture carries both channels and the same person on each. That pairing is the demonstration: her
+ * mail thread is linked to her account by an address in a header nobody proved, and her app thread is
+ * linked by a session, and a console that renders the two identically has a bug this seed will show
+ * you. It is also the only row carrying submission context, which is what a bug report knows and a
+ * piece of mail cannot — and the only row carrying a `declaredCategory`, because it is the only sender
+ * who was offered a chooser.
+ *
+ * **And it deliberately disagrees with itself.** Grace filed it under "something is missing" and the
+ * model read the text and called it a bug, so `declaredCategory` is `feature_request` while `category`
+ * is `bug_report`. That is the ordinary case rather than a contrived one — people file "X does not
+ * work for me" under a missing feature constantly — and it is the row that makes the rendering mistake
+ * visible before it ships: a console that shows one word, or shows the wrong one, has a bug this seed
+ * will hand you. Every mail thread's is null, because nobody asked its sender anything.
+ *
+ * That is one row per priority, all four sentiments, four categories, both channels, both link
+ * provenances, both a stated and an unstated category, and both sides of `archived` — the states
+ * anything reading these tables has to handle, without anybody authoring a fixture first.
+ *
+ * **Everything is fixed — the ids and the clock.** `pithy seed` is `INSERT OR IGNORE`, so a generated
+ * UUID would give Ada a second complaint on every run.
+ *
+ * **No attachments, and no raw messages.** Both would mean seeding R2 objects the D1 rows point at,
+ * and a fixture whose rows name bytes that are not there is worse than one that claims less. The
+ * classifications are seeded because they are the interesting half: a thread carries a model id, so
+ * the seed shows what "which rows came from which model" looks like before anybody has run one.
+ *
+ * Composed in only when the project turns on `seed.includeExamples`, and only for `dev` and
+ * `staging` — an example fixture never targets prod, whatever that setting says.
+ */
+
+/** Where this set sorts. After auth's users (100) and payments' purchases (250), which it links to. */
+const SUPPORT_EXAMPLE_SEED_ORDER = 260;
+
+/** Fixed ids, so the fixture is idempotent and a classification cannot drift off its thread. */
+const BILLING_THREAD_ID = "a1b2c3d4-0001-4a11-9c01-0e1f2a3b4c50";
+const ACCESS_THREAD_ID = "a1b2c3d4-0002-4a11-9c01-0e1f2a3b4c51";
+const FEATURE_THREAD_ID = "a1b2c3d4-0003-4a11-9c01-0e1f2a3b4c52";
+const APP_THREAD_ID = "a1b2c3d4-0004-4a11-9c01-0e1f2a3b4c53";
+
+const BILLING_MESSAGE_ID = "b1b2c3d4-0001-4a11-9c01-0e1f2a3b4c60";
+const ACCESS_MESSAGE_ID = "b1b2c3d4-0002-4a11-9c01-0e1f2a3b4c61";
+const ACCESS_REPLY_ID = "b1b2c3d4-0003-4a11-9c01-0e1f2a3b4c62";
+const FEATURE_MESSAGE_ID = "b1b2c3d4-0004-4a11-9c01-0e1f2a3b4c63";
+const APP_MESSAGE_ID = "b1b2c3d4-0005-4a11-9c01-0e1f2a3b4c64";
+
+const BILLING_CLASSIFICATION_ID = "c1b2c3d4-0001-4a11-9c01-0e1f2a3b4c70";
+const ACCESS_CLASSIFICATION_ID = "c1b2c3d4-0002-4a11-9c01-0e1f2a3b4c71";
+const FEATURE_CLASSIFICATION_ID = "c1b2c3d4-0003-4a11-9c01-0e1f2a3b4c72";
+const APP_CLASSIFICATION_ID = "c1b2c3d4-0004-4a11-9c01-0e1f2a3b4c73";
+
+/** The inbox these threads arrived on — a subdomain, which is the only safe shape for a real one. */
+const INBOX = "support@help.example.com";
+
+/** The model the seeded classifications claim to have come from. */
+const MODEL = "@cf/meta/llama-3.1-8b-instruct";
+
+/** One fixed moment. The demo is about state, not about a calendar. */
+const AT = new Date("2026-01-10T09:00:00.000Z");
+const LATER = new Date("2026-01-10T11:30:00.000Z");
+const ARCHIVED_AT = new Date("2026-01-11T16:00:00.000Z");
+
+export const supportExampleSeed: SeedSet = defineSeed({
+  name: "example",
+  order: SUPPORT_EXAMPLE_SEED_ORDER,
+  environments: ["dev", "staging"],
+  example: true,
+  d1: [
+    d1SeedGroup("app", SUPPORT_THREADS_TABLE, SupportThread, [
+      {
+        id: BILLING_THREAD_ID,
+        channel: "email",
+        inboxAddress: INBOX,
+        subject: "I was charged twice this month",
+        fromAddress: EXAMPLE_ADA.email,
+        fromName: EXAMPLE_ADA.name,
+        // Authenticated, which is what lets the seeded thread show a real customer link.
+        senderAuthenticated: true,
+        userId: EXAMPLE_ADA.id,
+        accountLinkSource: "email_address",
+        category: "billing",
+        priority: "urgent",
+        sentiment: "angry",
+        confidence: 0.94,
+        model: MODEL,
+        classifiedAt: AT,
+        archived: false,
+        archivedAt: null,
+        archivedBy: null,
+        messageCount: 1,
+        firstMessageAt: AT,
+        lastMessageAt: AT,
+        createdAt: AT,
+        updatedAt: AT,
+      },
+      {
+        id: ACCESS_THREAD_ID,
+        channel: "email",
+        inboxAddress: INBOX,
+        subject: "Magic link never arrives",
+        fromAddress: EXAMPLE_GRACE.email,
+        fromName: EXAMPLE_GRACE.name,
+        senderAuthenticated: true,
+        userId: EXAMPLE_GRACE.id,
+        accountLinkSource: "email_address",
+        category: "account_access",
+        priority: "normal",
+        sentiment: "frustrated",
+        confidence: 0.81,
+        model: MODEL,
+        classifiedAt: AT,
+        archived: false,
+        archivedAt: null,
+        archivedBy: null,
+        // Two: her message and the answer, so a thread view has a conversation in it.
+        messageCount: 2,
+        firstMessageAt: AT,
+        lastMessageAt: LATER,
+        createdAt: AT,
+        updatedAt: LATER,
+      },
+      {
+        id: FEATURE_THREAD_ID,
+        channel: "email",
+        inboxAddress: INBOX,
+        subject: "Could you add CSV export?",
+        fromAddress: EXAMPLE_ALAN.email,
+        fromName: EXAMPLE_ALAN.name,
+        senderAuthenticated: true,
+        userId: EXAMPLE_ALAN.id,
+        accountLinkSource: "email_address",
+        category: "feature_request",
+        priority: "low",
+        sentiment: "positive",
+        confidence: 0.88,
+        model: MODEL,
+        classifiedAt: AT,
+        // Done. The archived filter needs something to find, and the done pile needs to not be empty
+        // on a fresh backend.
+        archived: true,
+        archivedAt: ARCHIVED_AT,
+        archivedBy: "example-dashboard",
+        messageCount: 1,
+        firstMessageAt: AT,
+        lastMessageAt: AT,
+        createdAt: AT,
+        updatedAt: ARCHIVED_AT,
+      },
+      {
+        id: APP_THREAD_ID,
+        // The other channel. Grace already has a mail thread above, and having the same person on both
+        // is the point: a console that cannot tell her session-proven link from her header-inferred one
+        // is rendering two very different pieces of evidence as one fact.
+        channel: "app",
+        // Populated even on an app thread: it is the address a reply will come back to, which is the
+        // only meaning `inboxAddress` has here.
+        inboxAddress: INBOX,
+        subject: "Export button does nothing on the reports screen",
+        // Her account's own address, read from the account rather than from anything a client sent.
+        fromAddress: EXAMPLE_GRACE.email,
+        fromName: EXAMPLE_GRACE.name,
+        // True for the strongest reason available: there was no header to prove, because the session
+        // was proved before the request reached a handler.
+        senderAuthenticated: true,
+        userId: EXAMPLE_GRACE.id,
+        accountLinkSource: "session",
+        // What she said, beside what the model made of it. She reached for "something is missing"; the
+        // classifier read the text and called it a bug. Both are true, they disagree, and neither may
+        // overwrite the other — which is the entire reason these are two columns.
+        declaredCategory: "feature_request",
+        category: "bug_report",
+        priority: "normal",
+        sentiment: "neutral",
+        confidence: 0.91,
+        model: MODEL,
+        classifiedAt: AT,
+        archived: false,
+        archivedAt: null,
+        archivedBy: null,
+        messageCount: 1,
+        firstMessageAt: LATER,
+        lastMessageAt: LATER,
+        createdAt: LATER,
+        updatedAt: LATER,
+      },
+    ]),
+    d1SeedGroup("app", SUPPORT_MESSAGES_TABLE, SupportMessage, [
+      {
+        id: BILLING_MESSAGE_ID,
+        threadId: BILLING_THREAD_ID,
+        direction: "inbound",
+        channel: "email",
+        submittedByUserId: null,
+        context: null,
+        mimeMessageId: "seed-billing-1@example.com",
+        mimeInReplyTo: null,
+        mimeReferences: null,
+        fromAddress: EXAMPLE_ADA.email,
+        fromName: EXAMPLE_ADA.name,
+        toAddress: INBOX,
+        subject: "I was charged twice this month",
+        textBody:
+          "My card shows two charges for the same subscription on the 3rd. I have only ever had one account. Please refund the duplicate.",
+        htmlBody: null,
+        emailJobId: null,
+        rawKey: null,
+        rawBytes: null,
+        receivedAt: AT,
+        createdAt: AT,
+      },
+      {
+        id: ACCESS_MESSAGE_ID,
+        threadId: ACCESS_THREAD_ID,
+        direction: "inbound",
+        channel: "email",
+        submittedByUserId: null,
+        context: null,
+        mimeMessageId: "seed-access-1@example.com",
+        mimeInReplyTo: null,
+        mimeReferences: null,
+        fromAddress: EXAMPLE_GRACE.email,
+        fromName: EXAMPLE_GRACE.name,
+        toAddress: INBOX,
+        subject: "Magic link never arrives",
+        textBody:
+          "I have asked for a sign-in link four times today and none of them have arrived. I checked spam. Is something broken?",
+        htmlBody: null,
+        emailJobId: null,
+        rawKey: null,
+        rawBytes: null,
+        receivedAt: AT,
+        createdAt: AT,
+      },
+      {
+        id: ACCESS_REPLY_ID,
+        threadId: ACCESS_THREAD_ID,
+        direction: "outbound",
+        // How this answer was delivered: it went out through the durable send path, so it carries the
+        // job id below. An answer stored for the app instead would be `app` and carry none.
+        channel: "email",
+        submittedByUserId: null,
+        context: null,
+        // Null, exactly as the real reply path leaves it: Cloudflare assigns the sent `Message-ID`
+        // and never tells the enqueuer, so a seeded value here would model something that cannot
+        // happen.
+        mimeMessageId: null,
+        mimeInReplyTo: "seed-access-1@example.com",
+        mimeReferences: ["seed-access-1@example.com"],
+        fromAddress: INBOX,
+        fromName: null,
+        toAddress: EXAMPLE_GRACE.email,
+        subject: "Re: Magic link never arrives",
+        textBody:
+          "Hi Grace,\n\nI found the problem — your address had bounced earlier in the week and was on our suppression list. I have cleared it. Try again and it should arrive within a minute.\n\nSorry for the trouble.\n",
+        htmlBody: null,
+        emailJobId: "seed-email-job-access-1",
+        rawKey: null,
+        rawBytes: null,
+        receivedAt: LATER,
+        createdAt: LATER,
+      },
+      {
+        id: FEATURE_MESSAGE_ID,
+        threadId: FEATURE_THREAD_ID,
+        direction: "inbound",
+        channel: "email",
+        submittedByUserId: null,
+        context: null,
+        mimeMessageId: "seed-feature-1@example.com",
+        mimeInReplyTo: null,
+        mimeReferences: null,
+        fromAddress: EXAMPLE_ALAN.email,
+        fromName: EXAMPLE_ALAN.name,
+        toAddress: INBOX,
+        subject: "Could you add CSV export?",
+        textBody:
+          "Loving the product. The one thing I miss is being able to export my data as CSV for a spreadsheet. No rush.",
+        htmlBody: null,
+        emailJobId: null,
+        rawKey: null,
+        rawBytes: null,
+        receivedAt: AT,
+        createdAt: AT,
+      },
+      {
+        id: APP_MESSAGE_ID,
+        threadId: APP_THREAD_ID,
+        direction: "inbound",
+        channel: "app",
+        // The session's own user id — the identity, not a match on an address.
+        submittedByUserId: EXAMPLE_GRACE.id,
+        // The only row here with context, because it is the only one whose sender had an app to ask.
+        // This is what turns "the button does nothing" into a place to look.
+        context: { screen: "reports", appVersion: "2.4.1", platform: "web", environment: "prod", locale: "en-GB" },
+        // Server-minted, so a reply carries an `In-Reply-To` her mail client will echo back — without
+        // it her answer opens a second thread and the conversation fragments.
+        mimeMessageId: `${APP_MESSAGE_ID}@help.example.com`,
+        mimeInReplyTo: null,
+        mimeReferences: null,
+        fromAddress: EXAMPLE_GRACE.email,
+        fromName: EXAMPLE_GRACE.name,
+        toAddress: INBOX,
+        subject: "Export button does nothing on the reports screen",
+        textBody:
+          "I press Export on the reports screen and nothing happens. No download, no error. It worked last week. Chrome, if that helps.",
+        htmlBody: null,
+        emailJobId: null,
+        rawKey: null,
+        rawBytes: null,
+        receivedAt: LATER,
+        createdAt: LATER,
+      },
+    ]),
+    d1SeedGroup("app", SUPPORT_CLASSIFICATIONS_TABLE, SupportClassification, [
+      {
+        id: BILLING_CLASSIFICATION_ID,
+        threadId: BILLING_THREAD_ID,
+        messageId: BILLING_MESSAGE_ID,
+        category: "billing",
+        priority: "urgent",
+        sentiment: "angry",
+        confidence: 0.94,
+        model: MODEL,
+        createdAt: AT,
+      },
+      {
+        id: ACCESS_CLASSIFICATION_ID,
+        threadId: ACCESS_THREAD_ID,
+        messageId: ACCESS_MESSAGE_ID,
+        category: "account_access",
+        priority: "normal",
+        sentiment: "frustrated",
+        confidence: 0.81,
+        model: MODEL,
+        createdAt: AT,
+      },
+      {
+        id: APP_CLASSIFICATION_ID,
+        threadId: APP_THREAD_ID,
+        messageId: APP_MESSAGE_ID,
+        // The same classifier, over the same federated taxonomy. An app submission introduces no
+        // vocabulary of its own — that is what makes this a channel rather than a second capability.
+        category: "bug_report",
+        priority: "normal",
+        sentiment: "neutral",
+        confidence: 0.91,
+        model: MODEL,
+        createdAt: LATER,
+      },
+      {
+        id: FEATURE_CLASSIFICATION_ID,
+        threadId: FEATURE_THREAD_ID,
+        messageId: FEATURE_MESSAGE_ID,
+        category: "feature_request",
+        priority: "low",
+        sentiment: "positive",
+        confidence: 0.88,
+        model: MODEL,
+        createdAt: AT,
+      },
+    ]),
+  ],
+});

package/src/store/paging.ts

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The inbox page bounds, in the one module that has no reason to import anything (#430).
+ *
+ * `http/schemas.ts` bounds a caller's `limit` with the same number the reader clamps to, and it used to
+ * read it out of `store/threads.ts` — the Kysely reader, which brings `kysely`, `kysely-d1` and
+ * `@cloudflare/workers-types` with it. A request schema is a client's business: a management client
+ * building a call must be able to compile the shape it may send, in a browser, with no Worker types in
+ * reach. So the two numbers moved and the reader kept the query.
+ *
+ * **Both moved, not only the one the schema needs.** They are read together — a default clamped into a
+ * maximum, on one line, in two queries — and a pair split across two modules is how the next person
+ * picks the wrong one.
+ */
+
+/** How many threads a page holds by default. */
+export const DEFAULT_PAGE_SIZE = 25;
+
+/** The most a caller may ask for in one page. */
+export const MAX_PAGE_SIZE = 100;

package/src/store/search.ts

@@ -0,0 +1,197 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type Expression, type SqlBool, sql } from "kysely";
+import { SUPPORT_MESSAGES_TABLE, type SupportDatabase } from "../data/tables";
+
+/**
+ * Text search over the inbox — two backends behind one predicate.
+ *
+ * **`LIKE` is the default and FTS5 is the opt-in**, which is the opposite of what it looks like it
+ * should be. The reason is in `store/searchIndex.ts`: an FTS5 virtual table anywhere in a D1
+ * database makes `wrangler d1 export` refuse to dump *the whole database*, so turning it on by
+ * default would quietly cost every adopter their backup story for tables that have nothing to do
+ * with support. `LIKE` is an unindexed scan and is completely adequate for an inbox measured in
+ * thousands of messages, which is what this capability is for.
+ *
+ * Both paths return a **predicate over `pithy_support_threads`**, not a list of ids, so search
+ * composes with the category/archived filters and — crucially — with cursor pagination. Returning
+ * ids would mean either capping the match set (silent truncation, which reads as "that is all there
+ * is") or paginating twice over.
+ *
+ * Either way this is keyword search, deliberately. People search a support inbox for a word they
+ * remember — an order number, an error string, a surname — not for a concept. `@pithy-sh/vector` is
+ * there for anyone who wants meaning-matching, and it is the nicer demo and the wrong default: it
+ * cannot find `ORD-40912`.
+ */
+
+/** The longest search term accepted. Bounded because it becomes a scan predicate. */
+const MAX_TERM = 200;
+
+/** Escape the `LIKE` wildcards so a term containing `%` matches a literal `%`. */
+function escapeLike(term: string): string {
+  return term.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+
+/**
+ * Turn a user's words into an FTS5 MATCH expression.
+ *
+ * Every token is quoted and the whole thing is ANDed. Quoting is what stops FTS5's own query syntax
+ * from leaking through: a bare `NOT`, `OR`, `*` or `(` is an operator to FTS5, so a customer whose
+ * surname is a keyword — or anyone deliberately probing — would otherwise change the shape of the
+ * query rather than search for a word. This is the same "input is data, never syntax" rule the rest
+ * of the package applies to model output and to HTML.
+ */
+export function ftsQuery(term: string): string {
+  const tokens = term
+    .slice(0, MAX_TERM)
+    // FTS5 tokenizes on non-alphanumerics anyway, so anything else is punctuation we would only be
+    // handing to its parser.
+    .split(/[^\p{L}\p{N}_-]+/u)
+    .filter((token) => token.length > 0)
+    .slice(0, 16);
+  return tokens.map((token) => `"${token.replace(/"/g, '""')}"`).join(" AND ");
+}
+
+/** Whether a term has anything searchable left after tokenizing. */
+export function isSearchable(term: string, fts: boolean): boolean {
+  return fts ? ftsQuery(term).length > 0 : term.trim().length > 0;
+}
+
+/**
+ * A predicate matching threads whose messages contain `term`.
+ *
+ * Correlated on the thread id so it drops into a `where` beside every other filter. The subquery is
+ * `exists`, so it stops at the first matching message rather than counting them.
+ */
+export function searchPredicate(term: string, options: { fts: boolean }): Expression<SqlBool> {
+  if (options.fts) {
+    // `<table> MATCH ?` naming the table in full is the documented FTS5 form, and the only one that
+    // works: the hidden match column keeps the table's own name, so aliasing the table to `s` and
+    // writing `s match ?` is `no such column: s`. `thread_id` is UNINDEXED, so the correlation is a
+    // filter over the match set rather than part of the match.
+    return sql<SqlBool>`exists (
+      select 1 from pithy_support_search
+      where pithy_support_search.thread_id = pithy_support_threads.id
+        and pithy_support_search match ${ftsQuery(term)}
+    )`;
+  }
+  const pattern = `%${escapeLike(term.slice(0, MAX_TERM))}%`;
+  return sql<SqlBool>`exists (
+    select 1 from pithy_support_messages m
+    where m.thread_id = pithy_support_threads.id
+      and (m.subject like ${pattern} escape '\\' or m.text_body like ${pattern} escape '\\')
+  )`;
+}
+
+/**
+ * Add a message to the full-text index, replacing any row already there for it.
+ *
+ * **Remove-then-insert, not a bare insert** — the same shape the CMS `syncFts` uses, and for the
+ * reason application-managed indexes always need it: an FTS5 table has no primary key and no unique
+ * constraint to lean on, so a second call for the same message would silently add a second copy and
+ * the thread would start appearing twice in its own search results. Making the write idempotent means
+ * a retry, a reindex, and a first index are all the same operation, which is the property every other
+ * write path in this repo is built on.
+ *
+ * Best-effort by contract: a failed index write must never lose a customer's message, so the caller
+ * logs and carries on — the row is still there, still readable, still repairable by
+ * {@link reindexThread}, and only missing from one search box.
+ */
+export async function indexMessage(
+  db: SupportDatabase,
+  entry: { threadId: string; messageId: string; subject: string; body: string },
+): Promise<void> {
+  await sql`delete from pithy_support_search where message_id = ${entry.messageId}`.execute(db);
+  await sql`
+    insert into pithy_support_search(thread_id, message_id, subject, body)
+    values (${entry.threadId}, ${entry.messageId}, ${entry.subject}, ${entry.body})
+  `.execute(db);
+}
+
+/**
+ * Rebuild the index for one thread — delete its rows, then re-add every message.
+ *
+ * The repair path for the failure mode application-side indexing has and triggers would not: a
+ * message stored while the index write failed. Also what a reindex after a tokenizer change runs.
+ */
+export async function reindexThread(db: SupportDatabase, threadId: string): Promise<number> {
+  // Clears by thread rather than relying on `indexMessage`'s per-message delete, so a row whose
+  // message has since been removed goes too — that one is unreachable by any per-message call.
+  await sql`delete from pithy_support_search where thread_id = ${threadId}`.execute(db);
+  const messages = await db
+    .selectFrom(SUPPORT_MESSAGES_TABLE)
+    .select(["id", "threadId", "subject", "textBody"])
+    .where("threadId", "=", threadId)
+    .execute();
+  for (const message of messages) {
+    await indexMessage(db, {
+      threadId: message.threadId,
+      messageId: message.id,
+      subject: message.subject,
+      body: message.textBody,
+    });
+  }
+  return messages.length;
+}
+
+/**
+ * Rebuild the whole index from the messages table, in pages.
+ *
+ * **Creating the index is not the same as populating it**, and that gap is the one failure a search
+ * box must not have: an adopter who turns `search.fts` on after mail already exists gets an empty
+ * virtual table, and because the table now *exists* the `LIKE` fallback never fires — so the inbox
+ * answers "no matches" for a term that is demonstrably in the body. Silently returning nothing is
+ * worse than returning slowly, so provisioning backfills immediately after it creates.
+ *
+ * Paged on `(receivedAt, id)` rather than an offset, for the same reason the inbox is: rows arriving
+ * during a long backfill would shift an offset underneath it and skip messages.
+ */
+export async function reindexAll(
+  db: SupportDatabase,
+  options: { pageSize?: number; onProgress?: (indexed: number) => void } = {},
+): Promise<number> {
+  const pageSize = options.pageSize ?? 200;
+  // Cheaper and more obviously correct than deleting per message as we go: the index is derived, so
+  // emptying it costs nothing that is not about to be rewritten.
+  await sql`delete from pithy_support_search`.execute(db);
+
+  let cursor: { receivedAt: number; id: string } | undefined;
+  let indexed = 0;
+
+  for (;;) {
+    let page = db
+      .selectFrom(SUPPORT_MESSAGES_TABLE)
+      .select(["id", "threadId", "subject", "textBody", "receivedAt"])
+      .orderBy("receivedAt", "asc")
+      .orderBy("id", "asc")
+      .limit(pageSize);
+    if (cursor) {
+      const at = cursor.receivedAt;
+      const id = cursor.id;
+      page = page.where((eb) =>
+        eb.or([eb("receivedAt", ">", at), eb.and([eb("receivedAt", "=", at), eb("id", ">", id)])]),
+      );
+    }
+
+    const rows = await page.execute();
+    if (rows.length === 0) break;
+
+    for (const row of rows) {
+      await indexMessage(db, {
+        threadId: row.threadId,
+        messageId: row.id,
+        subject: row.subject,
+        body: row.textBody,
+      });
+      indexed += 1;
+    }
+    options.onProgress?.(indexed);
+
+    const last = rows[rows.length - 1];
+    if (!last || rows.length < pageSize) break;
+    cursor = { receivedAt: Number(last.receivedAt), id: last.id };
+  }
+
+  return indexed;
+}

package/src/store/searchIndex.ts

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type Kysely, sql } from "kysely";
+import type { SupportDatabase } from "../data/tables";
+
+/**
+ * The FTS5 index's lifecycle — created and dropped by `pithy support provision`, **not by a
+ * migration**.
+ *
+ * ## Why this is not a migration
+ *
+ * Because it holds no data. Every row in it is derived from `pithy_support_messages`, and
+ * `reindexThread` rebuilds it from there at any time — so dropping it loses a search box for as long
+ * as it takes to rebuild, and nothing else. That is the line: a migration is for schema whose loss
+ * loses data, and this is a provisioned resource like the R2 bucket and the routing rule, which
+ * support already creates the same way.
+ *
+ * Making it a migration was the mistake, and the failure was specific rather than theoretical.
+ * Composing it conditionally on `search.fts` meant turning the flag **off** removed an
+ * already-applied migration from the set, and Kysely reads a previously-executed migration that has
+ * vanished as corruption:
+ *
+ *     corrupted migrations: previously executed migration 1200_support_0002_search is missing
+ *
+ * Every capability's migrations for a database compose into one provider, so that throw blocked
+ * `pithy migrate` for auth, payments, and email too — a whole-database outage from one capability's
+ * config flag, fixable only by knowing to roll back first. Out of the ledger, there is nothing to
+ * corrupt and toggling either way is just a re-provision.
+ *
+ * Both statements are idempotent, so provisioning stays safe to re-run — the property every other
+ * step of `pithy support provision` already has.
+ */
+
+/** The virtual table's name. Snake_case because nothing translates it — every statement here is hand-written. */
+export const SEARCH_TABLE = "pithy_support_search";
+
+/**
+ * Create the full-text index if it is not already there.
+ *
+ * A standalone (not external-content) FTS5 table. External content would store the text once rather
+ * than twice, but it requires the indexed column names to exist verbatim on the content table, and
+ * ours is `text_body` rather than `body`. Duplicating is the honest trade for an index that cannot
+ * desynchronize on a column rename.
+ *
+ * `thread_id` and `message_id` are UNINDEXED: they are carried so a match resolves straight to a
+ * conversation and so one message's rows can be replaced, and tokenizing a UUID would only add noise
+ * to every query.
+ */
+export async function createSearchIndex(db: SupportDatabase | Kysely<unknown>): Promise<void> {
+  await sql`
+    create virtual table if not exists pithy_support_search using fts5(
+      thread_id unindexed,
+      message_id unindexed,
+      subject,
+      body,
+      tokenize = 'unicode61 remove_diacritics 2'
+    )
+  `.execute(db as Kysely<unknown>);
+}
+
+/**
+ * Drop the full-text index if it is there.
+ *
+ * Safe by construction: the index is derived, so this costs a rebuild rather than a restore. It is
+ * what `pithy support provision` runs when `search.fts` goes back to false — and the reason turning
+ * the feature off is now a one-command operation instead of a migration rollback.
+ */
+export async function dropSearchIndex(db: SupportDatabase | Kysely<unknown>): Promise<void> {
+  await sql`drop table if exists pithy_support_search`.execute(db as Kysely<unknown>);
+}