@pithy-sh/support 0.5.1 → 0.6.0

package/src/http/scopes.ts

@@ -1,13 +1,13 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
+import type { AdminRouteDeclaration } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
 import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
 
 /**
  * Support's control-plane scopes, and the admin surface a manifest advertises.
  *
- * **Separate from `guards.ts` because a scope name is a client's business** (#315). A management
+ * **Separate from `guards.ts` because a scope name is a client's business**. A management
  * client reads these to render what a connection may do, and `pithy-sh/dashboard`'s scope builder
  * writes the `pithy dashboard connect --scope …` command from exactly these constants — in a browser
  * program, with the DOM lib and no Workers types. While they sat beside the Hono middleware, naming
@@ -15,7 +15,7 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
  * program has none of. **This module imports types and nothing else, and a gate holds it there**:
  * `tooling/browser-scopes` compiles a DOM-only program against every scope the kit declares.
  *
- * ## Five scopes, because these are five different blast radii
+ * ## Six scopes, because these are six different blast radii
  *
  * The temptation is one `support:admin` flag. It is wrong on the merits, the same way payments'
  * single flag was: **reading** an inbox exposes every customer's private correspondence, while
@@ -35,7 +35,7 @@ export const SUPPORT_THREADS_READ_SCOPE: ControlPlaneScope = "support:threads:re
 export const SUPPORT_THREADS_ARCHIVE_SCOPE: ControlPlaneScope = "support:threads:archive";
 
 /**
- * Send mail to a customer under the adopter's domain. The most dangerous of the five and the reason
+ * Send mail to a customer under the adopter's domain. The most dangerous of the six and the reason
  * a single admin flag was never an option.
  */
 export const SUPPORT_THREADS_REPLY_SCOPE: ControlPlaneScope = "support:threads:reply";
@@ -46,6 +46,12 @@ export const SUPPORT_THREADS_RECLASSIFY_SCOPE: ControlPlaneScope = "support:thre
 /** Set a viewer's own read/snooze flags. Private, uncoordinated, and the least dangerous thing here. */
 export const SUPPORT_THREADS_FLAG_SCOPE: ControlPlaneScope = "support:threads:flag";
 
+/**
+ * Say who has a thread, or that nobody does. Shared state like archive, and its own scope like
+ * archive, because deciding who answers a customer is not the same permission as marking them done.
+ */
+export const SUPPORT_THREADS_ASSIGN_SCOPE: ControlPlaneScope = "support:threads:assign";
+
 /**
  * Every control-plane scope support defines — what `pithy dashboard connect` offers for this
  * capability, and the list a manifest or a doc quotes rather than re-typing.
@@ -56,6 +62,7 @@ export const SUPPORT_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
   SUPPORT_THREADS_REPLY_SCOPE,
   SUPPORT_THREADS_RECLASSIFY_SCOPE,
   SUPPORT_THREADS_FLAG_SCOPE,
+  SUPPORT_THREADS_ASSIGN_SCOPE,
 ];
 
 /**
@@ -69,48 +76,78 @@ export const SUPPORT_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
  * The summaries say what the operation is *for*. A client renders these next to a button somebody is
  * about to press on a real customer's conversation.
  */
-export function supportAdminRoutes(basePath: string): AdminRoute[] {
+export function supportAdminRoutes(basePath: string): AdminRouteDeclaration[] {
   return [
     {
       method: "GET",
+      operation: "threads.list",
       path: `${basePath}/threads`,
       scope: SUPPORT_THREADS_READ_SCOPE,
-      summary: "List the inbox, newest first, filtered by category, priority, and archived, searched by text.",
+      kind: "reads",
+      summary: "List the inbox, newest first, filtered by category, priority, assignee, and archived.",
+    },
+    {
+      method: "GET",
+      operation: "threads.search",
+      path: `${basePath}/threads/search`,
+      scope: SUPPORT_THREADS_READ_SCOPE,
+      kind: "reads",
+      summary: "Search the inbox by words and by meaning, ranked as one, with the same filters as the list.",
     },
     {
       method: "GET",
+      operation: "threads.read",
       path: `${basePath}/threads/:id`,
       scope: SUPPORT_THREADS_READ_SCOPE,
+      kind: "reads",
       summary: "Read one conversation, with the sender's linked account and what they bought.",
     },
     {
       method: "POST",
+      operation: "threads.archive",
       path: `${basePath}/threads/:id/archive`,
       scope: SUPPORT_THREADS_ARCHIVE_SCOPE,
+      kind: "writes",
       summary: "Mark a conversation done, or reopen one.",
     },
     {
       method: "POST",
+      operation: "threads.assign",
+      path: `${basePath}/threads/:id/assign`,
+      scope: SUPPORT_THREADS_ASSIGN_SCOPE,
+      kind: "writes",
+      summary: "Give a conversation to somebody, hand it on, or give it up.",
+    },
+    {
+      method: "POST",
+      operation: "threads.reply",
       path: `${basePath}/threads/:id/reply`,
       scope: SUPPORT_THREADS_REPLY_SCOPE,
+      kind: "sends",
       summary: "Answer the customer, threaded so their mail client keeps one conversation.",
     },
     {
       method: "POST",
+      operation: "threads.reclassify",
       path: `${basePath}/threads/:id/reclassify`,
       scope: SUPPORT_THREADS_RECLASSIFY_SCOPE,
+      kind: "writes",
       summary: "Re-run the classifier over this conversation's latest inbound message.",
     },
     {
       method: "POST",
+      operation: "threads.flags",
       path: `${basePath}/threads/:id/flags`,
       scope: SUPPORT_THREADS_FLAG_SCOPE,
+      kind: "writes",
       summary: "Set your own read and snooze state for a conversation. Private to you.",
     },
     {
       method: "GET",
+      operation: "replies.list",
       path: `${basePath}/replies`,
       scope: SUPPORT_THREADS_READ_SCOPE,
+      kind: "reads",
       summary: "The canned reply catalog — starting points to pick from, ordered for a thread's category.",
     },
   ];

package/src/http/views.ts

@@ -1,17 +1,22 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import type { SupportAssignment } from "../data/assignment";
 import type { SupportMessage } from "../data/message";
 import type { SupportThread } from "../data/thread";
 import type { SenderContext } from "../link/sender";
+import type { SearchOutcome, SearchResult } from "../store/hybrid";
 import type { ListedThread } from "../store/threads";
 import type {
   SenderContextView,
+  SupportAssignmentView,
   SupportAttachmentView,
   SupportListedThreadView,
   SupportMessageView,
   SupportMyMessageView,
   SupportMyThreadView,
+  SupportSearchResponse,
+  SupportSearchResultView,
   SupportThreadView,
 } from "./responses";
 
@@ -60,6 +65,10 @@ export function threadView(thread: SupportThread): SupportThreadView {
     archived: thread.archived,
     archivedAt: iso(thread.archivedAt),
     archivedBy: thread.archivedBy ?? null,
+    assigneeRef: thread.assigneeRef ?? null,
+    assigneeName: thread.assigneeName ?? null,
+    assignedAt: iso(thread.assignedAt),
+    assignedBy: thread.assignedBy ?? null,
     messageCount: thread.messageCount,
     firstMessageAt: thread.firstMessageAt.toISOString(),
     lastMessageAt: thread.lastMessageAt.toISOString(),
@@ -68,11 +77,46 @@ export function threadView(thread: SupportThread): SupportThreadView {
   };
 }
 
+/** Project one change of a thread's assignee. The thread id is the route's, so it is not repeated. */
+export function assignmentView(assignment: SupportAssignment): SupportAssignmentView {
+  return {
+    id: assignment.id,
+    assigneeRef: assignment.assigneeRef ?? null,
+    assigneeName: assignment.assigneeName ?? null,
+    previousRef: assignment.previousRef ?? null,
+    previousName: assignment.previousName ?? null,
+    actorType: assignment.actorType,
+    assignedBy: assignment.assignedBy,
+    note: assignment.note ?? null,
+    createdAt: assignment.createdAt.toISOString(),
+  };
+}
+
 /** Project one thread for the inbox, carrying this viewer's own read and snooze state. */
 export function listedThreadView(thread: ListedThread): SupportListedThreadView {
   return { ...threadView(thread), read: thread.read, snoozedUntil: iso(thread.snoozedUntil) };
 }
 
+/** Project one search result: the thread as this viewer sees it, and its best message's raw scores. */
+export function searchResultView(result: SearchResult): SupportSearchResultView {
+  return {
+    thread: listedThreadView(result.thread),
+    messageId: result.messageId,
+    ...(result.bm25 !== undefined ? { bm25: result.bm25 } : {}),
+    ...(result.similarity !== undefined ? { similarity: result.similarity } : {}),
+  };
+}
+
+/** Project a whole search. */
+export function searchView(outcome: SearchOutcome): SupportSearchResponse {
+  return {
+    mode: outcome.mode,
+    backends: { ran: [...outcome.ran], skipped: outcome.skipped.map((skip) => ({ ...skip })) },
+    count: outcome.results.length,
+    results: outcome.results.map(searchResultView),
+  };
+}
+
 /**
  * Project one message.
  *

package/src/inbound/ingest.ts

@@ -7,7 +7,7 @@ import { chunkRowsByBoundParameters } from "@pithy-sh/core/src/data/boundParamet
 import type { Logger } from "@pithy-sh/core/src/logger/logger";
 import { attachmentKey, putAttachment, rawMessageKey, sha256Hex } from "../attachment/store";
 import { SupportAuditActions } from "../audit/actions";
-import type { SupportConfig } from "../config/config";
+import { type SupportConfig, supportSemantic } from "../config/config";
 import { SupportAttachment } from "../data/attachment";
 import { SupportMessage } from "../data/message";
 import {
@@ -520,7 +520,10 @@ export async function ingestInbound(deps: IngestDeps, input: IngestInput): Promi
   // 9. Classification, last and allowed to fail. An out-of-office is not worth an inference, and an
   // adopter who turned classification off should pay nothing for it.
   const classifying = deps.config.ai.enabled && !parsed.autoSubmitted;
-  if (classifying) {
+  // The same Workflow embeds the message when semantic search is on, so it runs for either reason —
+  // an inbox with classification off and semantic search on still wants its mail findable by meaning.
+  const embedding = supportSemantic(deps.config.search) !== undefined && !parsed.autoSubmitted;
+  if (classifying || embedding) {
     try {
       await deps.dispatchClassify(messageId);
     } catch (error) {

package/src/index.ts

@@ -25,7 +25,9 @@ export {
   SupportGuardConfig,
   SupportReplyConfig,
   SupportSearchConfig,
+  SupportStaffConfig,
 } from "./config/config";
+export { SupportAssignment, SupportAssignmentActorType, UNASSIGNED } from "./data/assignment";
 export { SupportAttachment } from "./data/attachment";
 export {
   DEFAULT_SUPPORT_CATEGORIES,
@@ -37,6 +39,7 @@ export { SupportMessageDirection, SupportPriority, SupportSentiment, UNCATEGORIZ
 export { SupportThreadFlag } from "./data/flag";
 export { SupportMessage } from "./data/message";
 export {
+  SUPPORT_ASSIGNMENTS_TABLE,
   SUPPORT_ATTACHMENTS_TABLE,
   SUPPORT_CLASSIFICATIONS_TABLE,
   SUPPORT_FLAGS_TABLE,
@@ -50,11 +53,13 @@ export { SupportThread } from "./data/thread";
 export {
   SUPPORT_CONTROL_PLANE_SCOPES,
   SUPPORT_THREADS_ARCHIVE_SCOPE,
+  SUPPORT_THREADS_ASSIGN_SCOPE,
   SUPPORT_THREADS_FLAG_SCOPE,
   SUPPORT_THREADS_READ_SCOPE,
   SUPPORT_THREADS_RECLASSIFY_SCOPE,
   SUPPORT_THREADS_REPLY_SCOPE,
 } from "./http/scopes";
+export { SUPPORT_THREAD_ACTIVITIES, SUPPORT_THREAD_ROOM } from "./presence/room";
 export {
   DEFAULT_SUPPORT_REPLIES,
   defineSupportReplies,

package/src/migrations/0002_assignment.ts

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Who has a thread (#816): the current assignee on `pithy_support_threads`, and every change of it in a
+ * new append-only `pithy_support_assignments`.
+ *
+ * **A `0002`, appended, never folded into `0001`.** `@pithy-sh/support` has shipped, so its chain is
+ * history.
+ *
+ * **Four nullable columns and no backfill.** Every thread that exists when this runs has no assignee, and
+ * null is exactly that.
+ *
+ * **One index for the filter.** The inbox lists `archived`, newest first, and `assignee=<ref>` narrows it;
+ * `(assigneeRef, archived, lastMessageAt, id)` serves that page and its cursor the way
+ * `pithySupportThreadsArchivedIdx` serves the unfiltered one. `assignee=none` reads the unfiltered index
+ * and is a residual predicate on it.
+ */
+export const support_0002_assignment: Migration = {
+  async up(db: Kysely<unknown>): Promise<void> {
+    await db.schema.alterTable("pithySupportThreads").addColumn("assigneeRef", "text").execute();
+    await db.schema.alterTable("pithySupportThreads").addColumn("assigneeName", "text").execute();
+    await db.schema.alterTable("pithySupportThreads").addColumn("assignedAt", "integer").execute();
+    await db.schema.alterTable("pithySupportThreads").addColumn("assignedBy", "text").execute();
+    await db.schema
+      .createIndex("pithySupportThreadsAssigneeIdx")
+      .on("pithySupportThreads")
+      .columns(["assigneeRef", "archived", "lastMessageAt", "id"])
+      .execute();
+
+    await db.schema
+      .createTable("pithySupportAssignments")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("threadId", "text", (c) => c.notNull())
+      .addColumn("assigneeRef", "text")
+      .addColumn("assigneeName", "text")
+      .addColumn("previousRef", "text")
+      .addColumn("previousName", "text")
+      .addColumn("actorType", "text", (c) => c.notNull())
+      .addColumn("assignedBy", "text", (c) => c.notNull())
+      .addColumn("note", "text")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .execute();
+    // A thread's history, oldest first — the only way this table is read.
+    await db.schema
+      .createIndex("pithySupportAssignmentsThreadIdx")
+      .on("pithySupportAssignments")
+      .columns(["threadId", "createdAt"])
+      .execute();
+  },
+  async down(db: Kysely<unknown>): Promise<void> {
+    // The exact inverse, in reverse. The index goes before its columns, because SQLite refuses to drop a
+    // column an index still names.
+    await db.schema.dropIndex("pithySupportAssignmentsThreadIdx").execute();
+    await db.schema.dropTable("pithySupportAssignments").execute();
+    await db.schema.dropIndex("pithySupportThreadsAssigneeIdx").execute();
+    await db.schema.alterTable("pithySupportThreads").dropColumn("assignedBy").execute();
+    await db.schema.alterTable("pithySupportThreads").dropColumn("assignedAt").execute();
+    await db.schema.alterTable("pithySupportThreads").dropColumn("assigneeName").execute();
+    await db.schema.alterTable("pithySupportThreads").dropColumn("assigneeRef").execute();
+  },
+};

package/src/migrations/0003_embeddings.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * The semantic index's model stamps: one row per embedded message in `pithy_support_embeddings`.
+ *
+ * **Appended, and the messages table is not touched**: a released migration is never edited, and the stamp
+ * describes a derived index, not the mail. The table exists whether or not `search.semantic` is on, because the
+ * migration set must not vary with a config flag (`store/searchIndex.ts` says why); an empty table costs nothing.
+ *
+ * No index beyond the primary key. A reprocess page reads messages in id order and joins this on `messageId`,
+ * which the key serves.
+ */
+export const support_0003_embeddings: Migration = {
+  async up(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+      .createTable("pithySupportEmbeddings")
+      .addColumn("messageId", "text", (c) => c.primaryKey())
+      .addColumn("model", "text", (c) => c.notNull())
+      .addColumn("embeddedAt", "integer", (c) => c.notNull())
+      .execute();
+  },
+  async down(db: Kysely<unknown>): Promise<void> {
+    await db.schema.dropTable("pithySupportEmbeddings").execute();
+  },
+};

package/src/migrations/set.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Migration } from "kysely/migration";
+import { support_0001_threads } from "./0001_threads";
+import { support_0002_assignment } from "./0002_assignment";
+import { support_0003_embeddings } from "./0003_embeddings";
+
+/**
+ * Every support migration, in order — the set the capability contributes and the one every test that
+ * needs today's schema runs. Append-only: a released chain is history.
+ *
+ * The full-text index is **not** here: it is a provisioned resource `pithy support provision` creates and
+ * drops (`store/searchIndex.ts`), so a config flag can never corrupt a migration set shared with every
+ * other capability in the database.
+ */
+export const SUPPORT_MIGRATIONS: Record<string, Migration> = {
+  "0001_threads": support_0001_threads,
+  "0002_assignment": support_0002_assignment,
+  "0003_embeddings": support_0003_embeddings,
+};

package/src/presence/room.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import {
+  PRESENCE_TICKET_KEY_SECRET,
+  type PresenceDeclaration,
+  type PresenceSessionGate,
+} from "@pithy-sh/core/src/presence/declaration";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import type { Context } from "hono";
+import type { SupportWiring } from "../capability";
+import type { SupportStaffConfig } from "../config/config";
+import { SUPPORT_THREADS_READ_SCOPE } from "../http/scopes";
+import { resolveSubmitterAccount } from "../link/sender";
+import { supportPresenceRegistry } from "../secret/registry";
+import { staffMay } from "../staff/staff";
+
+/**
+ * Who else has a support thread open (#816) — support's one room kind on core's presence seam (#815).
+ *
+ * Anyone who may read a thread may see who else has it open, so the room joins with the scope that already
+ * reads it, `support:threads:read`, and adds none of its own. A management client mints its ticket at
+ * `POST /control-plane/presence/tickets`; a signed-in user of the app mints one at
+ * `POST {basePath}/presence/tickets` when `support({ staff })` names a read power their role holds. The room
+ * holds nothing but who is here and writes nothing anywhere.
+ */
+
+/** The room kind: one room per thread, keyed by the thread's id. */
+export const SUPPORT_THREAD_ROOM = "support.thread";
+
+/**
+ * What a participant may announce. `viewing` first, because the first is what a participant joins as;
+ * `replying` is announced by the client when its reply form opens, and cleared when it closes.
+ */
+export const SUPPORT_THREAD_ACTIVITIES = ["viewing", "replying"] as const;
+
+/** The account name a staff participant joins under, or null when it cannot be read. */
+export type StaffName = (c: Context<PithyHonoEnv>, userId: string) => Promise<{ name?: string } | null>;
+
+/**
+ * The session gate: the read power in the organization this request acts for, the same question the staff
+ * routes ask. Admits under the account's own name; with none to read, core falls back to the user id.
+ */
+export function staffPresenceGate(staff: SupportStaffConfig, nameOf: StaffName): PresenceSessionGate {
+  return async (c) => {
+    const userId = c.var.auth?.userId;
+    if (!userId) return null;
+    if (!staffMay(await c.var.actingOrganization(), staff, "readPower")) return null;
+    const account = await nameOf(c, userId);
+    return account?.name ? { name: account.name } : {};
+  };
+}
+
+/**
+ * The ticket signing keys, read through `@pithy-sh/secrets` per request — the current version signs and
+ * every version still honored verifies, so a rotation never strands a socket mid-handshake.
+ */
+async function ticketKeys(env: Record<string, unknown>): Promise<string[]> {
+  const secrets = await sharedSecretsStore(env as unknown as SecretsStoreEnv, supportPresenceRegistry);
+  const { currentVersion, versions } = secrets.getVersions(PRESENCE_TICKET_KEY_SECRET);
+  const current = versions[currentVersion];
+  return [
+    ...(current === undefined ? [] : [current]),
+    ...Object.entries(versions)
+      .filter(([version]) => version !== currentVersion)
+      .map(([, value]) => value),
+  ];
+}
+
+/** Support's presence declaration, built from its resolved mount and staff config. */
+export function supportPresence(basePath: string, wiring: SupportWiring): PresenceDeclaration {
+  const staff = wiring.config.staff;
+  return {
+    basePath,
+    ticketKey: ticketKeys,
+    rooms: [
+      {
+        kind: SUPPORT_THREAD_ROOM,
+        scope: SUPPORT_THREADS_READ_SCOPE,
+        activities: SUPPORT_THREAD_ACTIVITIES,
+        ...(staff
+          ? {
+              session: staffPresenceGate(staff, async (c, userId) => {
+                const d1 = (c.env as unknown as { DB?: Parameters<typeof resolveSubmitterAccount>[0] }).DB;
+                return d1 ? resolveSubmitterAccount(d1, userId, wiring.peers) : null;
+              }),
+            }
+          : {}),
+      },
+    ],
+  };
+}

package/src/provision/provisionSupport.ts

@@ -113,6 +113,24 @@ export interface SupportProvisioner {
    * and backfills the gap, and says which of the three it did.
    */
   ensureSearchIndex(env: ManagedEnvironment): Promise<{ created: boolean; dropped: boolean; repaired: boolean }>;
+  /**
+   * The semantic message index in this environment, **before** the worker that binds it is deployed:
+   * created when `search.semantic` is on and it does not exist yet, untouched otherwise. Before, because a
+   * deploy that binds an index nobody created fails. Idempotent — an index that exists is reused as-is, and
+   * one with a different shape is refused rather than silently queried in the wrong space.
+   */
+  ensureSemanticIndex(env: ManagedEnvironment): Promise<{ indexName: string; created: boolean }>;
+  /**
+   * The semantic message index in this environment, **after** the worker is deployed:
+   *
+   * - On, and holding nothing yet — `created` by this run, or holding no stamp while inbound mail exists, which
+   *   is what a run that failed after creating it leaves: backfill it once, by starting the reprocess Workflow
+   *   over every inbound message. An index holding any stamp is never re-embedded here — that is
+   *   `pithy vector reprocess`.
+   * - Off: drop the index if it exists, and the model stamps with it, since every stamp now names a vector
+   *   that is gone. After the deploy, because the worker that bound it no longer does.
+   */
+  settleSemanticIndex(env: ManagedEnvironment, created: boolean): Promise<{ dropped: boolean; backfilled: 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.
@@ -128,6 +146,14 @@ export interface SupportProvisionResult {
   environments: ManagedEnvironment[];
   /** What the full-text index did, per environment — created, dropped, repaired, or already correct. */
   search: Array<{ env: ManagedEnvironment; created: boolean; dropped: boolean; repaired: boolean }>;
+  /** What the semantic message index did, per environment — created and backfilled, dropped, or unchanged. */
+  semantic: Array<{
+    env: ManagedEnvironment;
+    indexName: string;
+    created: boolean;
+    dropped: boolean;
+    backfilled: boolean;
+  }>;
   /** Whether the inbound routing rule was created, already present, or skipped. */
   routing: { created: boolean; skipped: boolean };
 }
@@ -155,19 +181,25 @@ export async function provisionSupport(
   await provisioner.preflight();
   const bucket = await provisioner.ensureBucket();
   const search: SupportProvisionResult["search"] = [];
+  const semantic: SupportProvisionResult["semantic"] = [];
   const deployed = managedEnvironments(environments);
   for (const env of deployed) {
+    // The message index first: the worker about to be deployed binds it, and a binding to an index nobody
+    // created fails the deploy.
+    const index = await provisioner.ensureSemanticIndex(env);
     await provisioner.deployWorker(env);
     // Per environment, because each has its own app database — and after the worker, so a database
     // that gains the index always has something able to write to it.
     search.push({ env, ...(await provisioner.ensureSearchIndex(env)) });
+    // The backfill runs on the worker just deployed, and a drop waits until no worker binds the index.
+    semantic.push({ env, ...index, ...(await provisioner.settleSemanticIndex(env, index.created)) });
   }
   // Only when at least one classification host is up. The rule is what starts delivering real customer
   // mail, so making it over a run that deployed nothing is the same window the ordering above closes,
   // widened to the whole project.
   const routing =
     deployed.length > 0 ? await provisioner.ensureRoutingRule() : { created: false, skipped: true as const };
-  return { bucket, environments: deployed, routing, search };
+  return { bucket, environments: deployed, routing, search, semantic };
 }
 
 /** The teardown seam — the inverse of {@link SupportProvisioner}. Every step idempotent. */

package/src/provision/resolveSupportConfig.ts

@@ -5,6 +5,7 @@ import type { FeatureIdentity } from "@pithy-sh/core/src/naming/feature";
 import { hostWorkflowsFor, resolveWorkflowHost, type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
 import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
 import type { SupportConfig } from "../config/config";
+import { supportMessageIndex, supportMessageIndexName } from "../semantic/messageIndex";
 import { SUPPORT_CAPABILITY, supportWorkflowRegistry } from "../workflows/specs";
 
 /**
@@ -60,21 +61,31 @@ export function resolveSupportConfig(
 ): WorkflowHostTemplate {
   const feature = params.feature;
   const { project, env } = params;
-  return resolveWorkflowHost(template, {
-    project,
-    capability: SUPPORT_CAPABILITY,
-    env,
-    ...(feature ? { feature } : {}),
-    databaseIds: { DB: params.appDatabaseId },
-    remoteBindings: ["AI"],
-    vars: { SUPPORT_CONFIG: JSON.stringify(params.supportConfig) },
-    // The classification Workflow, derived from support's own specs. A Workflow name is
-    // account-scoped, so it has to carry the project, and only the registry knows the job.
-    workflows: hostWorkflowsFor(supportWorkflowRegistry, {
+  // The semantic message index, only when `search.semantic` is on. The template carries no `vectorize`
+  // entry because most inboxes have none; one is added here, named the way provisioning created it.
+  const index = supportMessageIndex(params.supportConfig.search);
+  const indexName = index ? supportMessageIndexName(project, env, feature) : undefined;
+  return resolveWorkflowHost(
+    index && indexName
+      ? { ...template, vectorize: [{ binding: index.binding, index_name: indexName, remote: true }] }
+      : template,
+    {
       project,
       capability: SUPPORT_CAPABILITY,
       env,
       ...(feature ? { feature } : {}),
-    }).workflows,
-  });
+      databaseIds: { DB: params.appDatabaseId },
+      ...(index && indexName ? { vectorizeIndexNames: { [index.binding]: indexName } } : {}),
+      remoteBindings: index ? ["AI", index.binding] : ["AI"],
+      vars: { SUPPORT_CONFIG: JSON.stringify(params.supportConfig) },
+      // The classification Workflow, derived from support's own specs. A Workflow name is
+      // account-scoped, so it has to carry the project, and only the registry knows the job.
+      workflows: hostWorkflowsFor(supportWorkflowRegistry, {
+        project,
+        capability: SUPPORT_CAPABILITY,
+        env,
+        ...(feature ? { feature } : {}),
+      }).workflows,
+    },
+  );
 }