@pithy-sh/support 0.3.3 → 0.4.1

package/src/http/routes.ts

@@ -1,12 +1,12 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import { zValidator } from "@hono/zod-validator";
 import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
 import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
 import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
 import { requireSameOrigin } from "@pithy-sh/core/src/http/sameOrigin";
-import { validationHook } from "@pithy-sh/core/src/http/validation";
+import { validate } from "@pithy-sh/core/src/http/validation";
 import type { Context, Hono } from "hono";
 import { requireAuth } from "./guards";
 import {
@@ -22,7 +22,18 @@ import {
   submitFeedbackRequest,
   updateFlags,
 } from "./handlers";
-import type { SupportRepliesResponse } from "./responses";
+import {
+  SupportArchiveResponse,
+  SupportFlagsResponse,
+  SupportMyThreadResponse,
+  SupportMyThreadsResponse,
+  SupportReclassifiedResponse,
+  SupportRepliesResponse,
+  SupportReplySentResponse,
+  SupportSubmissionResponse,
+  SupportThreadResponse,
+  SupportThreadsResponse,
+} from "./responses";
 import {
   ArchiveThreadInput,
   FlagsInput,
@@ -114,7 +125,10 @@ import {
  * `createBackend` mounts **every** capability's middleware before **any** capability's routes, and the
  * adopter's `app` capability composes last — so their middleware runs after auth has resolved the
  * session and before this file's `requireAuth()`. `createBackend.workers.test.ts` pins that ordering,
- * because a paragraph asserting it is not the same as a test failing when it changes.
+ * because a paragraph asserting it is not the same as a test failing when it changes. Readiness guards
+ * (`Capability.readiness`) mount between the two, after every middleware and before every route, and
+ * skip the admin surface; `createBackend.readiness.workers.test.ts` pins that. A check like this one
+ * refuses a caller, not a broken Worker, so it stays in `middleware`.
  *
  * Two consequences worth stating rather than discovering. Their middleware sees `c.var.auth` as **null**
  * on an unauthenticated request, since it runs ahead of the route's own gate — so it should pass those
@@ -192,40 +206,70 @@ export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono
   return (app) => {
     app.get(
       `${base}/threads`,
+      describeRoute({
+        summary: "List the support inbox.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_READ_SCOPE],
+        responses: { 200: SupportThreadsResponse },
+      }),
       requireControlPlane(SUPPORT_THREADS_READ_SCOPE),
-      zValidator("query", ListThreadsQuery, validationHook),
+      validate("query", ListThreadsQuery),
       async (c) => c.json(await listInbox(await resolve(c), c.req.valid("query"), viewer(c))),
     );
 
     app.get(
       `${base}/replies`,
+      describeRoute({
+        summary: "List the canned replies.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_READ_SCOPE],
+        responses: { 200: SupportRepliesResponse },
+      }),
       requireControlPlane(SUPPORT_THREADS_READ_SCOPE),
-      zValidator("query", RepliesQuery, validationHook),
+      validate("query", RepliesQuery),
       async (c) =>
         c.json({ replies: listReplies(await resolve(c), c.req.valid("query")) } satisfies SupportRepliesResponse),
     );
 
     app.get(
       `${base}/threads/:id`,
+      describeRoute({
+        summary: "Read one conversation and its messages.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_READ_SCOPE],
+        responses: { 200: SupportThreadResponse },
+      }),
       requireControlPlane(SUPPORT_THREADS_READ_SCOPE),
-      zValidator("param", ThreadIdParam, validationHook),
+      validate("param", ThreadIdParam),
       async (c) => c.json(await readConversation(await resolve(c), c.req.valid("param").id)),
     );
 
     app.post(
       `${base}/threads/:id/archive`,
+      describeRoute({
+        summary: "Mark a conversation done, or reopen it.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_ARCHIVE_SCOPE],
+        responses: { 200: SupportArchiveResponse },
+      }),
       requireControlPlane(SUPPORT_THREADS_ARCHIVE_SCOPE),
-      zValidator("param", ThreadIdParam, validationHook),
-      zValidator("json", ArchiveThreadInput, validationHook),
+      validate("param", ThreadIdParam),
+      validate("json", ArchiveThreadInput),
       async (c) =>
         c.json(await archiveConversation(await resolve(c), c.req.valid("param").id, c.req.valid("json"), viewer(c))),
     );
 
     app.post(
       `${base}/threads/:id/reply`,
+      describeRoute({
+        summary: "Answer the customer.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_REPLY_SCOPE],
+        responses: { 201: SupportReplySentResponse },
+      }),
       requireControlPlane(SUPPORT_THREADS_REPLY_SCOPE),
-      zValidator("param", ThreadIdParam, validationHook),
-      zValidator("json", ReplyInput, validationHook),
+      validate("param", ThreadIdParam),
+      validate("json", ReplyInput),
       async (c) =>
         c.json(
           await replyToConversation(await resolve(c), c.req.valid("param").id, c.req.valid("json"), viewer(c)),
@@ -235,16 +279,28 @@ export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono
 
     app.post(
       `${base}/threads/:id/reclassify`,
+      describeRoute({
+        summary: "Run the classifier again on the latest inbound message.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_RECLASSIFY_SCOPE],
+        responses: { 200: SupportReclassifiedResponse },
+      }),
       requireControlPlane(SUPPORT_THREADS_RECLASSIFY_SCOPE),
-      zValidator("param", ThreadIdParam, validationHook),
+      validate("param", ThreadIdParam),
       async (c) => c.json(await reclassifyConversation(await resolve(c), c.req.valid("param").id, viewer(c))),
     );
 
     app.post(
       `${base}/threads/:id/flags`,
+      describeRoute({
+        summary: "Set the caller's private read and snooze flags.",
+        verification: "control-plane",
+        scopes: [SUPPORT_THREADS_FLAG_SCOPE],
+        responses: { 200: SupportFlagsResponse },
+      }),
       requireControlPlane(SUPPORT_THREADS_FLAG_SCOPE),
-      zValidator("param", ThreadIdParam, validationHook),
-      zValidator("json", FlagsInput, validationHook),
+      validate("param", ThreadIdParam),
+      validate("json", FlagsInput),
       async (c) => c.json(await updateFlags(await resolve(c), c.req.valid("param").id, c.req.valid("json"), viewer(c))),
     );
 
@@ -255,18 +311,39 @@ export function registerSupportRoutes(options: SupportRoutesOptions): (app: Hono
     // unauthenticated caller which submissions were well-formed.
     app.post(
       `${base}/feedback`,
+      describeRoute({
+        summary: "Write in to support from the app.",
+        verification: ["bearer", "session"],
+        responses: { 201: SupportSubmissionResponse },
+      }),
       requireAuth(),
       requireSameOrigin(),
-      zValidator("json", SubmitFeedbackInput, validationHook),
+      validate("json", SubmitFeedbackInput),
       async (c) => c.json(await submitFeedbackRequest(await resolve(c), c.req.valid("json"), submitter(c)), 201),
     );
 
-    app.get(`${base}/feedback`, requireAuth(), zValidator("query", MyThreadsQuery, validationHook), async (c) =>
-      c.json(await listMyThreads(await resolve(c), c.req.valid("query"), submitter(c))),
+    app.get(
+      `${base}/feedback`,
+      describeRoute({
+        summary: "List the caller's own support requests.",
+        verification: ["bearer", "session"],
+        responses: { 200: SupportMyThreadsResponse },
+      }),
+      requireAuth(),
+      validate("query", MyThreadsQuery),
+      async (c) => c.json(await listMyThreads(await resolve(c), c.req.valid("query"), submitter(c))),
     );
 
-    app.get(`${base}/feedback/:id`, requireAuth(), zValidator("param", ThreadIdParam, validationHook), async (c) =>
-      c.json(await readMyThread(await resolve(c), c.req.valid("param").id, submitter(c))),
+    app.get(
+      `${base}/feedback/:id`,
+      describeRoute({
+        summary: "Read one of the caller's own support requests.",
+        verification: ["bearer", "session"],
+        responses: { 200: SupportMyThreadResponse },
+      }),
+      requireAuth(),
+      validate("param", ThreadIdParam),
+      async (c) => c.json(await readMyThread(await resolve(c), c.req.valid("param").id, submitter(c))),
     );
   };
 }

package/src/inbound/handler.ts

@@ -74,7 +74,6 @@ export function createSupportEmailHandler(wiring: SupportWiring): CapabilityEmai
           db: supportDatabase(d1),
           config: wiring.config,
           bucket: bindings.SUPPORT_BUCKET,
-          fts: wiring.config.search.fts,
           dispatchClassify: makeClassifyDispatcher(env, log),
           linkSender: (address) => resolveSenderUserId(d1, address, wiring.peers),
           emit: wiring.emit,

package/src/inbound/ingest.ts

@@ -21,7 +21,6 @@ import { MAX_TEXT_BODY, type ParsedInboundMessage, parseInbound } from "../mime/
 import { htmlToText, sanitizeHtml } from "../mime/sanitize";
 import { parentCandidates } from "../mime/threading";
 import { truncateToBytes } from "../mime/truncate";
-import { indexMessage } from "../store/search";
 import { senderAuthenticity } from "./authenticity";
 import { checkRates, checkSize } from "./guard";
 import { resolveInbox } from "./recipient";
@@ -83,8 +82,6 @@ export interface IngestDeps {
   config: SupportConfig;
   /** The R2 bucket raw messages and attachments are written to. Absent means neither is kept. */
   bucket?: R2Bucket;
-  /** Whether the FTS5 index is composed. False means search runs as a `LIKE` scan and nothing is indexed. */
-  fts: boolean;
   /**
    * Start the classification Workflow for a stored message. Allowed to fail and allowed to decline —
    * an unprovisioned project has no binding, and a thread that stays `uncategorized` is a legitimate
@@ -504,17 +501,6 @@ export async function ingestInbound(deps: IngestDeps, input: IngestInput): Promi
     throw error;
   }
 
-  // The full-text index, when it is composed. Best-effort by contract: a failed index write must
-  // never lose a customer's message, so it is logged and the ingest continues. The row is stored,
-  // readable, and repairable by `reindexThread` — it is only missing from one search box.
-  if (deps.fts) {
-    try {
-      await indexMessage(deps.db, { threadId, messageId, subject, body: text });
-    } catch (error) {
-      deps.log.warn("support message not indexed", { messageId, error });
-    }
-  }
-
   // Guarded for the same reason the index write and the dispatch are, and the consequence here is
   // the worst of the three. This runs *after* the message and thread rows are committed but *before*
   // the classification dispatch — so a transient `bucket.put` failure throws out of ingest, the

package/src/provision/provisionSupport.ts

@@ -5,6 +5,7 @@ import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment
 import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
 import { resourceName } from "@pithy-sh/core/src/naming/resource";
 import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import { hostWorkflowsFor } from "@pithy-sh/core/src/workflow/host";
 import {
   assertSharedLeavesLast,
   type DeprovisionTarget,
@@ -12,7 +13,7 @@ import {
   type ManagedEnvironment,
   managedEnvironments,
 } from "@pithy-sh/secrets/src/scope";
-import { SUPPORT_CAPABILITY } from "../workflows/specs";
+import { SUPPORT_CAPABILITY, supportWorkflowRegistry } from "../workflows/specs";
 
 /**
  * The provisioning orchestration for the support capability — the live counterpart to
@@ -67,6 +68,18 @@ export function supportWorkerName(project: string, env: ManagedEnvironment): str
   return resourceNames(project).env(env).worker(SUPPORT_CAPABILITY);
 }
 
+/**
+ * The Workflows the classification worker is deployed with in one environment —
+ * `<project>-<env>-support-classify`. Derived by the call `resolveSupportConfig` deploys with, so teardown
+ * deletes the names provision created and no others (#789). Deleting a Worker does not delete the
+ * Workflows registered against it.
+ */
+export function supportWorkflowNames(project: string, env: ManagedEnvironment): string[] {
+  return hostWorkflowsFor(supportWorkflowRegistry, { project, capability: SUPPORT_CAPABILITY, env }).workflows.map(
+    (workflow) => workflow.name,
+  );
+}
+
 /** The live Cloudflare/wrangler seam. Each step must be idempotent. */
 export interface SupportProvisioner {
   /**
@@ -84,15 +97,22 @@ export interface SupportProvisioner {
   /** Deploy the prebuilt classification worker for this environment. */
   deployWorker(env: ManagedEnvironment): Promise<void>;
   /**
-   * Create or drop the full-text index in this environment's app database, to match `search.fts`.
+   * Create or drop the full-text index **and its triggers** in this environment's app database, to
+   * match `search.fts`.
    *
    * A provisioning step rather than a migration, because the index is **derived** — every row in it
    * comes from `pithy_support_messages` and `reindexThread` rebuilds it on demand. That is the line a
    * migration is for: schema whose loss loses data. Keeping it here is also what makes the flag safe
    * to toggle at all, since a config-conditional migration removed from the set is corruption to
-   * Kysely and blocks `pithy migrate` for every capability sharing the database.
+   * Kysely and blocks `pithy migrate` for every capability sharing the database. The triggers inherit
+   * that constraint exactly: they exist only where the table does, so they are provisioning too.
+   *
+   * **Three outcomes, not two.** `repaired` is a database whose table was already there and whose
+   * triggers were not — an adopter who took the release that moved the index onto triggers and deployed
+   * without re-provisioning. Nothing in the kit maintains that index, so the run creates the triggers
+   * and backfills the gap, and says which of the three it did.
    */
-  ensureSearchIndex(env: ManagedEnvironment): Promise<{ created: boolean; dropped: boolean }>;
+  ensureSearchIndex(env: ManagedEnvironment): Promise<{ created: boolean; dropped: boolean; repaired: boolean }>;
   /**
    * Ensure the inbound Email Routing rule that delivers the support address to the app worker.
    * Idempotent, keyed on the rule name. Returns `skipped: true` when no routing config was supplied.
@@ -106,8 +126,8 @@ export interface SupportProvisionResult {
   bucket: { bucket: string; created: boolean; skipped: boolean };
   /** The environments a classification worker was deployed for. */
   environments: ManagedEnvironment[];
-  /** What the full-text index did, per environment — created, dropped, or already correct. */
-  search: Array<{ env: ManagedEnvironment; created: boolean; dropped: boolean }>;
+  /** What the full-text index did, per environment — created, dropped, repaired, or already correct. */
+  search: Array<{ env: ManagedEnvironment; created: boolean; dropped: boolean; repaired: boolean }>;
   /** Whether the inbound routing rule was created, already present, or skipped. */
   routing: { created: boolean; skipped: boolean };
 }
@@ -157,6 +177,11 @@ export interface SupportDeprovisioner {
    * environment before it removes the bucket or the rule they share (#591).
    */
   hasWorker(env: ManagedEnvironment): Promise<boolean>;
+  /**
+   * Delete the env's classification Workflows, by {@link supportWorkflowNames}. Idempotent (a Workflow already
+   * gone is a no-op). Deleting the worker leaves them registered, so they go first (#789).
+   */
+  deleteWorkflows(env: ManagedEnvironment): Promise<void>;
   /** Delete the env's classification worker. Idempotent. */
   deleteWorker(env: ManagedEnvironment): Promise<void>;
   /**
@@ -200,7 +225,7 @@ export interface SupportDeprovisionResult {
  *    is every environment's support history — so they go with the last environment, never a staging teardown.
  * 3. Remove the routing rule, when asked, **first**: stop new mail arriving before removing the worker that would
  *    have handled it.
- * 4. Delete the environment's worker, then — only when asked — the bucket and everything in it.
+ * 4. Delete the environment's Workflows, then its worker, then — only when asked — the bucket and everything in it.
  */
 export async function deprovisionSupport(
   deprovisioner: SupportDeprovisioner,
@@ -213,6 +238,7 @@ export async function deprovisionSupport(
     ...(options.removeRouting ? [{ what: "the inbound routing rule", flag: "--routing-zone" }] : []),
   ]);
   const routingRuleRemoved = options.removeRouting ? (await deprovisioner.removeRoutingRule()).removed : false;
+  await deprovisioner.deleteWorkflows(env);
   await deprovisioner.deleteWorker(env);
   if (options.deleteStorage) await deprovisioner.deleteBucket();
   return { env, routingRuleRemoved };

package/src/reply/send.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
+import { commandName } from "@pithy-sh/core/src/cli/command";
 import type { Logger } from "@pithy-sh/core/src/logger/logger";
 import { SupportAuditActions } from "../audit/actions";
 import type { SupportConfig } from "../config/config";
@@ -9,7 +10,6 @@ import { SupportMessage } from "../data/message";
 import { SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE, type SupportDatabase } from "../data/tables";
 import { SupportNotFoundError, SupportReplyFailedError } from "../error/errors";
 import { buildReferencesHeader, replySubject } from "../mime/threading";
-import { indexMessage } from "../store/search";
 
 /**
  * Sending a reply — through `@pithy-sh/email`'s durable send path, never directly.
@@ -84,8 +84,6 @@ export interface ReplyDeps {
     inReplyTo?: string;
     references?: string;
   }) => Promise<{ jobId: string }>;
-  /** Whether the full-text index is in use. */
-  fts: boolean;
   /** The audit seam. */
   emit: AuditEmit;
   /** The request logger. */
@@ -213,7 +211,7 @@ export async function sendReply(deps: ReplyDeps, input: ReplyInput): Promise<Rep
     if (!enqueue) {
       throw new SupportReplyFailedError({
         message: "This deployment cannot send mail.",
-        action: "Add the email capability (`pithy add email`) and provision it, then retry.",
+        action: `Compose the email capability into this Worker with \`${commandName("add")}\` and provision it, then retry.`,
         detail: `thread ${input.threadId} needs a mailed reply and no email capability is composed`,
       });
     }
@@ -276,15 +274,6 @@ export async function sendReply(deps: ReplyDeps, input: ReplyInput): Promise<Rep
   };
   await deps.db.insertInto(SUPPORT_MESSAGES_TABLE).values(SupportMessage.encode(message)).execute();
 
-  if (deps.fts) {
-    try {
-      await indexMessage(deps.db, { threadId: input.threadId, messageId, subject, body: input.body });
-    } catch (error) {
-      // A search miss, never a lost reply. `reindexThread` is the repair.
-      deps.log.warn("support reply not indexed", { messageId, error });
-    }
-  }
-
   await deps.db
     .updateTable(SUPPORT_THREADS_TABLE)
     .set((eb) => ({

package/src/store/search.ts

@@ -87,16 +87,23 @@ export function searchPredicate(term: string, options: { fts: boolean }): Expres
 /**
  * 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.
+ * **No write path calls this any more.** The index is maintained by the triggers `createSearchIndex`
+ * provisions (`store/searchIndex.ts`), so a message is indexed because it was written rather than
+ * because the code that wrote it remembered. This is the **repair** primitive now: {@link reindexThread}
+ * and {@link reindexAll} are its only callers in the kit, and it stays exported because
+ * `package.json` exports `./src/*`, so an adopter may be reaching it.
  *
- * 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.
+ * **Remove-then-insert, not a bare insert** — the same shape the trigger bodies use, and for the
+ * reason an FTS5 table always needs it: it 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.
+ *
+ * **It no longer carries a swallow contract, because it is no longer on a message write.** A failure
+ * here is a failed repair, and the caller is a command or a route that can say so. The durability
+ * question moved with the index itself: a trigger runs inside the message's own statement, so a
+ * failure in its body takes the message write down with it — which is what `searchIndex.ts` documents
+ * and what the triggers' own tests hold.
  */
 export async function indexMessage(
   db: SupportDatabase,

package/src/store/searchIndex.ts

@@ -5,8 +5,8 @@ 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**.
+ * The FTS5 index's lifecycle — the virtual table **and the three triggers that keep it in step**,
+ * created and dropped by `pithy support provision`, **not by a migration**.
  *
  * ## Why this is not a migration
  *
@@ -28,7 +28,39 @@ import type { SupportDatabase } from "../data/tables";
  * 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
+ * **The triggers inherit that constraint exactly.** They exist only where the table exists, so they
+ * are provisioning and not schema — a `CREATE TRIGGER` composed conditionally on `search.fts` would
+ * corrupt the ledger for exactly the same reason the table's own statement did. `migrations.workers.test.ts`
+ * keeps proving the migration set carries none.
+ *
+ * ## Why triggers at all
+ *
+ * The index used to be written by hand at every message write — three call sites, each best-effort —
+ * and correctness depended on every future author remembering. There is no shared message-write
+ * helper, so a fourth path that forgot produced a thread nobody could search, with nothing failing,
+ * nothing logging and no test catching it.
+ *
+ * `CREATE TRIGGER` was in an undocumented middle on D1 when that was decided: D1 runs an authorizer
+ * that rejects SQLite constructs workerd permits (`fts5vocab` is refused where plain FTS5 succeeds),
+ * so a trigger passing under Miniflare proved nothing about the deployment that matters. That is
+ * settled — the Leed CMS ships a `BEFORE UPDATE … BEGIN SELECT RAISE(ABORT, …); END` trigger in a
+ * production migration, so the authorizer permits both the statement and a body that aborts.
+ *
+ * **The durability contract inverts, deliberately.** A trigger runs inside the message's own
+ * statement, so a failure in its body takes the message write down with it — where the old call sites
+ * logged and carried on. That swallow existed because a second round trip to a separate table can
+ * fail on its own; inside one statement it cannot. The body is a `DELETE` plus an `INSERT` of values
+ * already present in `NEW.*`, with no conversion, no constraint and no foreign key, so what remains is
+ * the FTS table being absent — which is what {@link SEARCH_TRIGGERS} cannot outlive, since
+ * {@link dropSearchIndex} drops the pair together — or disk and corruption, which would have failed the
+ * message insert anyway.
+ *
+ * The one gap the kit cannot close from here is an adopter who upgrades and deploys without re-running
+ * `pithy support provision`: the calls are gone, the triggers were never created, and messages
+ * silently stop being indexed. `pithy doctor` reports a provisioned table with no triggers as drift
+ * and names that command, per environment.
+ *
+ * Every statement here is idempotent, so provisioning stays safe to re-run — the property every other
  * step of `pithy support provision` already has.
  */
 
@@ -36,7 +68,128 @@ import type { SupportDatabase } from "../data/tables";
 export const SEARCH_TABLE = "pithy_support_search";
 
 /**
- * Create the full-text index if it is not already there.
+ * The three triggers, in create order — `_ai`, `_au`, `_ad` after SQLite's own FTS5 naming for the
+ * insert, update and delete hooks.
+ *
+ * Exported because two other places need the exact names and may not re-derive them: `pithy doctor`
+ * asks a deployed database whether they are there, and {@link dropSearchIndex} drops them. They carry
+ * the `pithy_support_` prefix every table in this capability does, for the same reason — `sqlite_master`
+ * is one flat namespace per database and the prefix is the only partition.
+ */
+export const SEARCH_TRIGGERS = [
+  "pithy_support_search_ai",
+  "pithy_support_search_au",
+  "pithy_support_search_ad",
+] as const;
+
+/**
+ * Every name a provisioner or `pithy doctor` asks `sqlite_master` about — the table and its triggers.
+ *
+ * One list, read by both, because the two have to agree about what "provisioned" means. A doctor that
+ * looked for two triggers while the provisioner created three would report drift nothing could clear.
+ */
+export const SEARCH_OBJECTS: readonly string[] = [SEARCH_TABLE, ...SEARCH_TRIGGERS];
+
+/** What is actually in a database: the virtual table, and how much of the trigger set. */
+export interface SearchIndexState {
+  /** Whether `pithy_support_search` exists. */
+  table: boolean;
+  /** How many of the three triggers exist — `"some"` is drift, not a pass. */
+  triggers: "all" | "some" | "none";
+}
+
+/**
+ * Read a `sqlite_master` name listing into the two facts anything acts on.
+ *
+ * **The trigger count is three-valued, and `"some"` is why.** A partial set means one `CREATE TRIGGER`
+ * failed or one was dropped by hand, and the consequence is per statement kind — two of three leaves
+ * updates or deletes going unindexed while inserts look fine, which is the worst way round. Folding it
+ * into `"none"` would also hide it from a teardown: `search.fts: false` has to clear a stray trigger,
+ * because a trigger whose table is gone fails every write to `pithy_support_messages`.
+ */
+export function searchIndexState(names: readonly string[]): SearchIndexState {
+  const found = new Set(names);
+  const present = SEARCH_TRIGGERS.filter((name) => found.has(name)).length;
+  return {
+    table: found.has(SEARCH_TABLE),
+    triggers: present === SEARCH_TRIGGERS.length ? "all" : present === 0 ? "none" : "some",
+  };
+}
+
+/** What a provision run has to do to one environment's index. */
+export type SearchIndexAction =
+  /** Already in the state `search.fts` asks for. */
+  | "none"
+  /** The table is not there: create it, its triggers, and backfill. */
+  | "create"
+  /** The table is there and its triggers are not: create them, and backfill the gap they left. */
+  | "repair"
+  /** `search.fts` is off and something is there: drop the triggers and the table. */
+  | "drop";
+
+/**
+ * Decide what `pithy support provision` does to one environment's index.
+ *
+ * **`repair` is the member this release exists for.** A run used to compare one boolean against one
+ * boolean — table present against flag set — and return early when they matched. That is exactly the
+ * state an adopter is in after upgrading and deploying: the table is present, the flag is set, the
+ * `indexMessage` calls are gone from every write path, and the triggers were never created. The old
+ * comparison read that as nothing to do, so the command `pithy doctor` names would not have been the
+ * command that fixes it.
+ *
+ * A repair backfills as a create does, because the gap is real: messages written between the deploy
+ * and the re-provision had no trigger to fire for them and no application call either.
+ *
+ * `drop` fires on triggers alone as well as on the table. A trigger body resolves its table at run
+ * time, so a trigger outlives a hand-dropped table — and while it does, every write to
+ * `pithy_support_messages` fails. Turning the flag off has to clear that rather than read it as a
+ * database with no index.
+ */
+export function searchIndexAction(state: SearchIndexState, wanted: boolean): SearchIndexAction {
+  if (!wanted) return state.table || state.triggers !== "none" ? "drop" : "none";
+  if (!state.table) return "create";
+  return state.triggers === "all" ? "none" : "repair";
+}
+
+/**
+ * The `CREATE TRIGGER` statements, one per {@link SEARCH_TRIGGERS} entry and in that order.
+ *
+ * **`BEGIN` and `END` are uppercase, and that is load-bearing.** Miniflare accepts a lowercase
+ * compound-statement body; remote D1 rejects it as `incomplete input [code: 7500]`, so a lowercased
+ * body passes every local test in this repository and fails on deploy. `searchIndex.test.ts` fails on
+ * the lowercase form, because no Workers test can.
+ *
+ * **Every column is the physical snake_case name.** `CamelCasePlugin` snake-cases the identifiers the
+ * query builder emits and never touches a string inside a `sql` template, so this is the one place in
+ * the package that has to spell them itself: `NEW.id`, `NEW.thread_id`, `NEW.subject`, `NEW.text_body`
+ * — never the camelCase keys `data/tables.ts` declares.
+ *
+ * **Insert and update both delete first.** An FTS5 table has no primary key and no unique constraint
+ * to lean on, so a bare insert on a second write for the same message would add a second copy and the
+ * thread would start appearing twice in its own search results — the same reason `indexMessage` is
+ * remove-then-insert. The update body keys its delete on `OLD.id`, so a row whose id changed takes its
+ * old index entry with it.
+ */
+export function searchTriggerStatements(): string[] {
+  const insert = "INSERT INTO pithy_support_search(thread_id, message_id, subject, body)";
+  const values = "VALUES (NEW.thread_id, NEW.id, NEW.subject, NEW.text_body)";
+  return [
+    `CREATE TRIGGER ${SEARCH_TRIGGERS[0]} AFTER INSERT ON pithy_support_messages BEGIN
+       DELETE FROM pithy_support_search WHERE message_id = NEW.id;
+       ${insert} ${values};
+     END`,
+    `CREATE TRIGGER ${SEARCH_TRIGGERS[1]} AFTER UPDATE ON pithy_support_messages BEGIN
+       DELETE FROM pithy_support_search WHERE message_id = OLD.id;
+       ${insert} ${values};
+     END`,
+    `CREATE TRIGGER ${SEARCH_TRIGGERS[2]} AFTER DELETE ON pithy_support_messages BEGIN
+       DELETE FROM pithy_support_search WHERE message_id = OLD.id;
+     END`,
+  ];
+}
+
+/**
+ * Create the full-text index and its triggers if they are 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
@@ -46,6 +199,13 @@ export const SEARCH_TABLE = "pithy_support_search";
  * `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.
+ *
+ * **The triggers are dropped and recreated rather than guarded with `IF NOT EXISTS`**, which is what
+ * makes re-provisioning after a kit upgrade actually converge. `IF NOT EXISTS` is idempotent in the
+ * weak sense — it leaves a trigger whose body this release has changed exactly as it was, so a fixed
+ * body would reach nobody who already had the old one, and the command `pithy doctor` names would not
+ * be the command that fixes it. The pair is ordered so the table is always there before a body refers
+ * to it.
  */
 export async function createSearchIndex(db: SupportDatabase | Kysely<unknown>): Promise<void> {
   await sql`
@@ -57,15 +217,26 @@ export async function createSearchIndex(db: SupportDatabase | Kysely<unknown>):
       tokenize = 'unicode61 remove_diacritics 2'
     )
   `.execute(db as Kysely<unknown>);
+  for (const [index, statement] of searchTriggerStatements().entries()) {
+    await sql.raw(`drop trigger if exists ${SEARCH_TRIGGERS[index]}`).execute(db as Kysely<unknown>);
+    await sql.raw(statement).execute(db as Kysely<unknown>);
+  }
 }
 
 /**
- * Drop the full-text index if it is there.
+ * Drop the full-text index and its triggers if they are 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.
+ *
+ * **The triggers go first, and the order is the whole point.** A trigger whose body inserts into a
+ * table that is gone fails every write to `pithy_support_messages`, so dropping the table out from
+ * under them would turn a feature flag into an outage on the capability's main write path.
  */
 export async function dropSearchIndex(db: SupportDatabase | Kysely<unknown>): Promise<void> {
+  for (const trigger of SEARCH_TRIGGERS) {
+    await sql.raw(`drop trigger if exists ${trigger}`).execute(db as Kysely<unknown>);
+  }
   await sql`drop table if exists pithy_support_search`.execute(db as Kysely<unknown>);
 }