@pithy-sh/support 0.5.0 → 0.6.0

package/src/purge/contribution.ts

@@ -0,0 +1,294 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import {
+  type ErasingPurgeContribution,
+  exportRows,
+  type PurgeContext,
+  purgeBinding,
+} from "@pithy-sh/core/src/capability/purge";
+import { deleteVectors, type VectorStore } from "@pithy-sh/vector/src/index/index";
+import { type Expression, type ExpressionBuilder, type Kysely, type SqlBool, sql } from "kysely";
+import { SupportAssignment } from "../data/assignment";
+import { SupportAttachment } from "../data/attachment";
+import { SupportMessage } from "../data/message";
+import {
+  SUPPORT_ASSIGNMENTS_TABLE,
+  SUPPORT_ATTACHMENTS_TABLE,
+  SUPPORT_CLASSIFICATIONS_TABLE,
+  SUPPORT_EMBEDDINGS_TABLE,
+  SUPPORT_FLAGS_TABLE,
+  SUPPORT_MESSAGES_TABLE,
+  SUPPORT_THREADS_TABLE,
+  type SupportDatabase,
+  supportDatabase,
+} from "../data/tables";
+import { SupportThread } from "../data/thread";
+import { SUPPORT_BUCKET_BINDING } from "../secret/registry";
+import { SUPPORT_VECTORIZE_BINDING } from "../semantic/messageIndex";
+
+/**
+ * What erasing one person means for `@pithy-sh/support` (#814): every thread they opened — linked to their account,
+ * or sent from their address and linked to no account — with every message in it, its attachments and raw mail in
+ * R2, its classifications, every operator's read and snooze state on it, and the history of who had it (#816). And
+ * what exporting them hands back.
+ *
+ * **A thread is the person's when it is linked to their account or came from their address.** An email thread from
+ * someone who never signed in carries no `userId`, only the address it came from; the address is read from the
+ * account that owns it (`PurgeContext.address`), so a thread sent before the person had an account is theirs too.
+ * The address side takes only a thread linked to no account: an address can move, and a thread linked to whoever
+ * held it before is that account's, never handed to the person who holds it now, nor erased with them.
+ *
+ * **The bytes go first, then the rows.** An attachment's row and a message's `rawKey` are the only things that name
+ * their objects, so a row deleted ahead of its object would leave bytes nothing can find. An R2 delete of a key
+ * already gone succeeds, so a retried step is **idempotent**, and a person with no threads finds nothing. Deleting
+ * a message drops it from the full-text index through the index's own triggers. Its vector in the semantic index
+ * is deleted by the message's id, stamped or not, before the message row that names it.
+ *
+ * **Who had a thread goes with the thread; who handed it over is the operator's.** The assignment history is a
+ * thread's own record — each change names the thread, who had it before and after, and the assigner's note about
+ * the person's request — so it is erased with the thread and exported with it, oldest first. Who made each change,
+ * `assignedBy`, is the operator's subject or a staff member's id, not the person's: the export leaves it out of the
+ * history and of the thread, as leaderboard leaves out a moderator, and the audit trail keeps every handover with its
+ * actor.
+ *
+ * **A staff member's own handovers, on threads that are not theirs, lose their id.** On the staff session door,
+ * `assignedBy` is the signed-in user's id, written onto a customer's thread and its history. Their purge sets it to
+ * `ERASED_ASSIGNER` wherever they acted as a user — every history row with `actorType = 'user'` and their id, and the
+ * thread's own `assignedBy` when that row made its current assignment — so the handover stays in the customer's
+ * record and stops naming them. A control-plane subject that happens to share the id is a client, not the person, and
+ * is left alone. Their export hands those handovers back as which thread, when, and how they were verified, never the
+ * assignee or the note, which are about the customer's request. Who **held** a thread is kept: an assignee is an
+ * opaque reference and a name the assigner chose, support cannot tell which reference is the person, and both go
+ * when the customer's thread does.
+ */
+
+/** What a purged staff member's id becomes on the handovers they made (#816). */
+export const ERASED_ASSIGNER = "erased-user";
+
+/** The one sentence the purge records with this step. */
+export const SUPPORT_PURGE_SUMMARY =
+  "Deletes every support thread the user opened, linked to their account or sent from their address and linked to no other account, with its messages, attachments, raw mail, classifications, read state and assignment history. On other people's threads, the handovers they made as a signed-in user lose their id; an assignee is an opaque reference the assigner named, so who held a thread stays until that thread goes.";
+
+/** How many threads one read takes, so a person with a long history is erased in bounded statements. */
+const PAGE = 50;
+
+/** R2's ceiling on the keys one `delete` takes. */
+const R2_DELETE_KEYS = 1000;
+
+/** Vector ids one `deleteByIds` call takes — Vectorize's own write batch, the same ceiling an upsert has. */
+const VECTOR_DELETE_IDS = 1000;
+
+/** The person's threads, as a predicate: linked to the account, or sent from its address and linked to none. */
+type Theirs = (
+  eb: ExpressionBuilder<SupportDatabase extends Kysely<infer Tables> ? Tables : never, typeof SUPPORT_THREADS_TABLE>,
+) => Expression<SqlBool>;
+
+/**
+ * Which threads are the person's: linked to the account, or sent from its address and linked to no account. Both
+ * sides are `normalizeAddress`'s form — a thread's `fromAddress` is normalized on the way in — so the index answers.
+ * It binds at most two parameters, however many threads it matches, so a statement built on it stays under D1's cap.
+ */
+async function theirs(context: PurgeContext): Promise<Theirs> {
+  const read = (await context.address?.()) ?? null;
+  const address = read === null ? null : normalizeAddress(read);
+  const userId = context.subject.id;
+  return (eb) =>
+    address === null
+      ? eb("userId", "=", userId)
+      : eb.or([eb("userId", "=", userId), eb.and([eb("fromAddress", "=", address), eb("userId", "is", null)])]);
+}
+
+/** One handover a staff member made, as their export carries it: which thread, when, and how they were verified. */
+const SupportHandover = SupportAssignment.pick({
+  id: true,
+  threadId: true,
+  actorType: true,
+  assignedBy: true,
+  createdAt: true,
+});
+
+/** A row without who made its assignment: the operator's, never the person's (#816). */
+function withoutAssigner<T extends { assignedBy?: unknown }>(row: T): Omit<T, "assignedBy"> {
+  const { assignedBy: _assigner, ...rest } = row;
+  return rest;
+}
+
+/** The person's thread ids, oldest first, at most `limit`. */
+async function threadIds(db: SupportDatabase, predicate: Theirs, limit: number): Promise<string[]> {
+  const rows = await db
+    .selectFrom(SUPPORT_THREADS_TABLE)
+    .select("id")
+    .where(predicate)
+    .orderBy("createdAt")
+    .orderBy("id")
+    .limit(limit)
+    .execute();
+  return rows.map((row) => row.id);
+}
+
+/** How the purge is composed. `semantic` is whether `search.semantic` is on, so the index must be reachable. */
+export interface SupportPurgeOptions {
+  semantic?: boolean;
+}
+
+/** The user contribution `support()` declares. */
+export function supportUserPurge(database = "DB", options: SupportPurgeOptions = {}): ErasingPurgeContribution {
+  const open = (env: Record<string, unknown>) => {
+    const d1 = purgeBinding<D1Database>(env, database, "support");
+    return { d1, db: supportDatabase(d1) };
+  };
+  return {
+    subject: "user",
+    summary: SUPPORT_PURGE_SUMMARY,
+    erase: async (context) => {
+      const { d1, db } = open(context.env);
+      const predicate = await theirs(context);
+      // Their own acts as a signed-in user, on anybody's thread: the thread first, while its history still names them.
+      const userId = context.subject.id;
+      const anonymize = [
+        db
+          .updateTable(SUPPORT_THREADS_TABLE)
+          .set({ assignedBy: ERASED_ASSIGNER })
+          .where("assignedBy", "=", userId)
+          .where((eb) =>
+            eb.exists(
+              eb
+                .selectFrom(SUPPORT_ASSIGNMENTS_TABLE)
+                .select(sql.lit(1).as("one"))
+                .whereRef(`${SUPPORT_ASSIGNMENTS_TABLE}.threadId`, "=", `${SUPPORT_THREADS_TABLE}.id`)
+                .whereRef(`${SUPPORT_ASSIGNMENTS_TABLE}.createdAt`, "=", `${SUPPORT_THREADS_TABLE}.assignedAt`)
+                .where(`${SUPPORT_ASSIGNMENTS_TABLE}.actorType`, "=", "user")
+                .where(`${SUPPORT_ASSIGNMENTS_TABLE}.assignedBy`, "=", userId),
+            ),
+          )
+          .compile(),
+        db
+          .updateTable(SUPPORT_ASSIGNMENTS_TABLE)
+          .set({ assignedBy: ERASED_ASSIGNER })
+          .where("actorType", "=", "user")
+          .where("assignedBy", "=", userId)
+          .compile(),
+      ];
+      await d1.batch(anonymize.map((compiled) => d1.prepare(compiled.sql).bind(...(compiled.parameters as unknown[]))));
+      let bucket: R2Bucket | undefined;
+      let vectors: VectorStore | undefined;
+      for (;;) {
+        const ids = await threadIds(db, predicate, PAGE);
+        if (ids.length === 0) return;
+        const [attachments, messages] = await Promise.all([
+          db.selectFrom(SUPPORT_ATTACHMENTS_TABLE).select("storageKey").where("threadId", "in", ids).execute(),
+          db.selectFrom(SUPPORT_MESSAGES_TABLE).select(["id", "rawKey"]).where("threadId", "in", ids).execute(),
+        ]);
+        const keys = [
+          ...attachments.map((row) => row.storageKey),
+          ...messages.map((row) => row.rawKey).filter((key): key is string => typeof key === "string" && key !== ""),
+        ];
+        if (keys.length > 0) {
+          // Bound only once there are bytes to delete, so a person whose threads hold none needs no bucket.
+          bucket ??= purgeBinding<R2Bucket>(context.env, SUPPORT_BUCKET_BINDING, "support", "R2 bucket");
+          // One page's threads can hold any number of messages and attachments; R2 takes a thousand keys a call.
+          for (let start = 0; start < keys.length; start += R2_DELETE_KEYS) {
+            await bucket.delete(keys.slice(start, start + R2_DELETE_KEYS));
+          }
+        }
+        // Their messages' vectors, before the rows that name them: a vector is derived from their words. Deleted by
+        // every message id in the page, not only the stamped ones, because a vector can outlive a failed stamp
+        // write, and deleting an id the index does not hold is harmless. The index is required when semantic
+        // search is on or a stamp says a vector exists; otherwise it is used when bound, so a project with
+        // semantic search off needs none.
+        if (vectors === undefined && context.env[SUPPORT_VECTORIZE_BINDING] === undefined) {
+          const required =
+            options.semantic === true ||
+            (await db
+              .selectFrom(SUPPORT_EMBEDDINGS_TABLE)
+              .select("messageId")
+              .where("messageId", "in", (eb) =>
+                eb.selectFrom(SUPPORT_MESSAGES_TABLE).select("id").where("threadId", "in", ids),
+              )
+              .executeTakeFirst()) !== undefined;
+          if (required) {
+            vectors = purgeBinding<VectorStore>(context.env, SUPPORT_VECTORIZE_BINDING, "support", "Vectorize index");
+          }
+        } else {
+          vectors ??= purgeBinding<VectorStore>(context.env, SUPPORT_VECTORIZE_BINDING, "support", "Vectorize index");
+        }
+        if (vectors) {
+          const vectorIds = messages.map((row) => row.id);
+          for (let start = 0; start < vectorIds.length; start += VECTOR_DELETE_IDS) {
+            await deleteVectors(vectors, vectorIds.slice(start, start + VECTOR_DELETE_IDS));
+          }
+        }
+        // One batch, children first, so a failure leaves the page whole and the retry erases it again.
+        const statements = [
+          db
+            .deleteFrom(SUPPORT_EMBEDDINGS_TABLE)
+            .where("messageId", "in", (eb) =>
+              eb.selectFrom(SUPPORT_MESSAGES_TABLE).select("id").where("threadId", "in", ids),
+            )
+            .compile(),
+          db.deleteFrom(SUPPORT_ATTACHMENTS_TABLE).where("threadId", "in", ids).compile(),
+          db.deleteFrom(SUPPORT_ASSIGNMENTS_TABLE).where("threadId", "in", ids).compile(),
+          db.deleteFrom(SUPPORT_CLASSIFICATIONS_TABLE).where("threadId", "in", ids).compile(),
+          db.deleteFrom(SUPPORT_FLAGS_TABLE).where("threadId", "in", ids).compile(),
+          db.deleteFrom(SUPPORT_MESSAGES_TABLE).where("threadId", "in", ids).compile(),
+          db.deleteFrom(SUPPORT_THREADS_TABLE).where("id", "in", ids).compile(),
+        ];
+        await d1.batch(
+          statements.map((compiled) => d1.prepare(compiled.sql).bind(...(compiled.parameters as unknown[]))),
+        );
+      }
+    },
+    export: async (context) => {
+      const { db } = open(context.env);
+      const predicate = await theirs(context);
+      // The thread set as a subquery, never a bound id list: a person with more threads than D1 binds in one
+      // statement is answered in full.
+      const threadIdsOf = db.selectFrom(SUPPORT_THREADS_TABLE).select("id").where(predicate);
+      const [threads, messages, attachments, assignments, handovers] = await Promise.all([
+        db.selectFrom(SUPPORT_THREADS_TABLE).selectAll().where(predicate).orderBy("createdAt").orderBy("id").execute(),
+        db
+          .selectFrom(SUPPORT_MESSAGES_TABLE)
+          .selectAll()
+          .where("threadId", "in", threadIdsOf)
+          .orderBy("receivedAt")
+          .orderBy("id")
+          .execute(),
+        db
+          .selectFrom(SUPPORT_ATTACHMENTS_TABLE)
+          .selectAll()
+          .where("threadId", "in", threadIdsOf)
+          .orderBy("createdAt")
+          .orderBy("id")
+          .execute(),
+        db
+          .selectFrom(SUPPORT_ASSIGNMENTS_TABLE)
+          .selectAll()
+          .where("threadId", "in", threadIdsOf)
+          .orderBy("createdAt")
+          .orderBy("id")
+          .execute(),
+        // The handovers they made as a signed-in user, on any thread: which, when and how — never the assignee or the
+        // note, which are about somebody else's request.
+        db
+          .selectFrom(SUPPORT_ASSIGNMENTS_TABLE)
+          .select(["id", "threadId", "actorType", "assignedBy", "createdAt"])
+          .where("actorType", "=", "user")
+          .where("assignedBy", "=", context.subject.id)
+          .orderBy("threadId")
+          .orderBy("createdAt")
+          .orderBy("id")
+          .execute(),
+      ]);
+      return {
+        threads: exportRows(threads.map((row) => withoutAssigner(SupportThread.parse(row)))),
+        messages: exportRows(messages.map((row) => SupportMessage.parse(row))),
+        attachments: exportRows(attachments.map((row) => SupportAttachment.parse(row))),
+        assignments: exportRows(assignments.map((row) => withoutAssigner(SupportAssignment.parse(row)))),
+        handovers: exportRows(handovers.map((row) => SupportHandover.parse(row))),
+      };
+    },
+  };
+}

package/src/secret/registry.ts

@@ -1,11 +1,14 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { PRESENCE_TICKET_KEY_ENTRY, PRESENCE_TICKET_KEY_SECRET } from "@pithy-sh/core/src/presence/declaration";
+import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
 import { r2CredentialsRegistry } from "@pithy-sh/storage/src/secret/registry";
 import { type SupportConfig, supportNeedsBucket } from "../config/config";
 
 /**
- * The secrets support reads — exactly one, and it is not support's own shape.
+ * The secrets support reads — two, and neither is support's own shape: the R2 credential bundle
+ * attachments are signed with, and the presence ticket key its `support.thread` room is joined with.
  *
  * Attachment bytes are written through the R2 binding and served as short-lived signed URLs, and
  * signing needs an S3 key pair. Rather than declare another credential shape, support declares the
@@ -32,8 +35,20 @@ export const SUPPORT_R2_SECRET = "support-r2-credentials";
  */
 export const SUPPORT_BUCKET_BINDING = "SUPPORT_BUCKET";
 
+/**
+ * The presence ticket key (#816), declared exactly as core states it. The name is the join key, so every
+ * capability in a Worker that declares rooms signs and verifies with the one key, and nobody chooses its
+ * value: `pithy add` mints the local one and `pithy secrets provision` the deployed ones.
+ */
+export const supportPresenceRegistry = defineSecretRegistry({
+  [PRESENCE_TICKET_KEY_SECRET]: PRESENCE_TICKET_KEY_ENTRY,
+});
+
 /** The support capability's secret-registry slice — aggregated into the shared accessor at startup. */
-export const supportSecretsRegistry = r2CredentialsRegistry(SUPPORT_R2_SECRET, SUPPORT_BUCKET_BINDING);
+export const supportSecretsRegistry = defineSecretRegistry({
+  ...r2CredentialsRegistry(SUPPORT_R2_SECRET, SUPPORT_BUCKET_BINDING),
+  ...supportPresenceRegistry,
+});
 
 /**
  * **The credential this composition cannot reach**, as the `inapplicableSecrets` contribution (#541).

package/src/semantic/documents.ts

@@ -0,0 +1,178 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { VectorDocument } from "@pithy-sh/vector/src/data/document";
+import type { DocumentStore } from "@pithy-sh/vector/src/data/documents";
+import { deleteVectors, type VectorStore } from "@pithy-sh/vector/src/index/index";
+import { SupportEmbedding } from "../data/embedding";
+import { SUPPORT_EMBEDDINGS_TABLE, SUPPORT_MESSAGES_TABLE, type SupportDatabase } from "../data/tables";
+import { embeddingText, SUPPORT_MESSAGES_INDEX } from "./messageIndex";
+
+/**
+ * `@pithy-sh/vector`'s `DocumentStore` seam over `pithy_support_messages` — so the semantic index is
+ * re-embedded by `vector`'s own reprocess orchestration rather than a second one.
+ *
+ * **The text stays in support's table.** A document is a message read through the join: its content is the text
+ * {@link embeddingText} embeds, and its `model` is the stamp in `pithy_support_embeddings`, null for a message
+ * never embedded. `markEmbedded` writes stamps. Nothing here copies a message into `pithy_vector_documents`.
+ *
+ * **Inbound messages only**, because only they are embedded on arrival: an operator's own reply says nothing
+ * about what the customer asked, and embedding it would put the adopter's words beside the customer's.
+ *
+ * **Metadata is empty, always.** Reprocess upserts a document's metadata onto its vector, so `{}` here is what
+ * keeps a re-embed to ids only, the same as the write in `embed.ts`.
+ *
+ * One index: every call names `support-messages` or reads nothing.
+ */
+
+/** A stamp insert binds the model and the time before the id list. */
+const STAMP_FIXED_PARAMETERS = 2;
+
+/** Message reads bind `direction` before the id list. */
+const READ_FIXED_PARAMETERS = 1;
+
+interface MessageRow {
+  id: string;
+  subject: string;
+  textBody: string;
+  receivedAt: number;
+  model: string | null;
+  embeddedAt: number | null;
+}
+
+/**
+ * Stamp `ids` with `model`, for the messages that still exist, and delete the vector of every one that does not.
+ *
+ * The stamp is an `INSERT … SELECT` from `pithy_support_messages`, so a message deleted after its vector was read
+ * gets no stamp. Its vector was upserted after the purge deleted it, so it is deleted here, by id: nothing else
+ * names it once the message row is gone. Returns the ids that were stamped.
+ */
+export async function writeStamps(
+  db: SupportDatabase,
+  store: VectorStore | undefined,
+  ids: readonly string[],
+  model: string,
+  at: Date,
+): Promise<Set<string>> {
+  const stamped = new Set<string>();
+  if (ids.length === 0) return stamped;
+  const embeddedAt = SupportEmbedding.shape.embeddedAt.encode(at);
+  for (const group of chunkByBoundParameters(ids, STAMP_FIXED_PARAMETERS)) {
+    // One statement per chunk, upserting: a re-embed replaces the stamp a model change left behind.
+    await db
+      .insertInto(SUPPORT_EMBEDDINGS_TABLE)
+      .columns(["messageId", "model", "embeddedAt"])
+      .expression((eb) =>
+        eb
+          .selectFrom(SUPPORT_MESSAGES_TABLE)
+          .select((inner) => ["id", inner.val(model).as("model"), inner.val(embeddedAt).as("embeddedAt")])
+          .where("id", "in", group),
+      )
+      .onConflict((conflict) =>
+        conflict.column("messageId").doUpdateSet((eb) => ({
+          model: eb.ref("excluded.model"),
+          embeddedAt: eb.ref("excluded.embeddedAt"),
+        })),
+      )
+      .execute();
+    const present = await db.selectFrom(SUPPORT_MESSAGES_TABLE).select("id").where("id", "in", group).execute();
+    for (const row of present) stamped.add(row.id);
+  }
+  const gone = ids.filter((id) => !stamped.has(id));
+  if (gone.length > 0 && store) await deleteVectors(store, gone);
+  return stamped;
+}
+
+function documentOf(row: MessageRow): VectorDocument {
+  const receivedAt = new Date(Number(row.receivedAt));
+  return {
+    id: row.id,
+    indexName: SUPPORT_MESSAGES_INDEX,
+    namespace: null,
+    content: embeddingText(row.subject, row.textBody),
+    metadata: {},
+    model: row.model,
+    createdAt: receivedAt,
+    updatedAt: row.embeddedAt === null ? receivedAt : new Date(Number(row.embeddedAt)),
+  };
+}
+
+/**
+ * The message corpus as a `DocumentStore`. `store` is the index a re-embed writes to, so a stamp that finds its
+ * message gone deletes the vector the re-embed just wrote for it.
+ */
+export function supportMessageDocuments(db: SupportDatabase, options: { store?: VectorStore } = {}): DocumentStore {
+  const base = () =>
+    db
+      .selectFrom(SUPPORT_MESSAGES_TABLE)
+      .leftJoin(SUPPORT_EMBEDDINGS_TABLE, `${SUPPORT_EMBEDDINGS_TABLE}.messageId`, `${SUPPORT_MESSAGES_TABLE}.id`)
+      .select([
+        `${SUPPORT_MESSAGES_TABLE}.id as id`,
+        `${SUPPORT_MESSAGES_TABLE}.subject as subject`,
+        `${SUPPORT_MESSAGES_TABLE}.textBody as textBody`,
+        `${SUPPORT_MESSAGES_TABLE}.receivedAt as receivedAt`,
+        `${SUPPORT_EMBEDDINGS_TABLE}.model as model`,
+        `${SUPPORT_EMBEDDINGS_TABLE}.embeddedAt as embeddedAt`,
+      ])
+      .where(`${SUPPORT_MESSAGES_TABLE}.direction`, "=", "inbound");
+
+  const ours = (indexName: string) => indexName === SUPPORT_MESSAGES_INDEX;
+
+  return {
+    async put() {
+      // Messages are written by the mail path and the submission route, never by a re-embed.
+      throw new InternalError({
+        message: "Support messages cannot be written through the vector document store.",
+        detail: "supportMessageDocuments.put: the corpus is pithy_support_messages, written by support alone",
+      });
+    },
+
+    async get(indexName, id) {
+      if (!ours(indexName)) return null;
+      const row = await base().where(`${SUPPORT_MESSAGES_TABLE}.id`, "=", id).executeTakeFirst();
+      return row ? documentOf(row as MessageRow) : null;
+    },
+
+    async byIds(indexName, ids) {
+      if (!ours(indexName) || ids.length === 0) return [];
+      const documents: VectorDocument[] = [];
+      for (const group of chunkByBoundParameters(ids, READ_FIXED_PARAMETERS)) {
+        const rows = await base().where(`${SUPPORT_MESSAGES_TABLE}.id`, "in", group).execute();
+        for (const row of rows) documents.push(documentOf(row as MessageRow));
+      }
+      return documents;
+    },
+
+    async remove(indexName, id) {
+      // The message is support's to delete. What a re-embed may forget is its stamp.
+      if (!ours(indexName)) return false;
+      const result = await db.deleteFrom(SUPPORT_EMBEDDINGS_TABLE).where("messageId", "=", id).executeTakeFirst();
+      return (result.numDeletedRows ?? 0n) > 0n;
+    },
+
+    async page(request) {
+      if (!ours(request.indexName)) return [];
+      let query = base().orderBy(`${SUPPORT_MESSAGES_TABLE}.id`, "asc").limit(request.limit);
+      if (request.after !== null) query = query.where(`${SUPPORT_MESSAGES_TABLE}.id`, ">", request.after);
+      const stale = request.staleModel;
+      if (stale !== undefined) {
+        // Never stamped counts as stale: a message that missed its embedding is exactly what a pass is for.
+        query = query.where((eb) =>
+          eb.or([
+            eb(`${SUPPORT_EMBEDDINGS_TABLE}.model`, "is", null),
+            eb(`${SUPPORT_EMBEDDINGS_TABLE}.model`, "!=", stale),
+          ]),
+        );
+      }
+      const rows = await query.execute();
+      return rows.map((row) => documentOf(row as MessageRow));
+    },
+
+    async markEmbedded(indexName, ids, model, at) {
+      if (!ours(indexName)) return;
+      await writeStamps(db, options.store, ids, model, at);
+    },
+  };
+}

package/src/semantic/embed.ts

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import type { VectorIndexConfig } from "@pithy-sh/vector/src/config/config";
+import { embedForIndex, type VectorAi } from "@pithy-sh/vector/src/embed/embed";
+import { upsertVectors, type VectorStore } from "@pithy-sh/vector/src/index/index";
+import { SUPPORT_MESSAGES_TABLE, type SupportDatabase } from "../data/tables";
+import { writeStamps } from "./documents";
+import { embeddingText } from "./messageIndex";
+
+/**
+ * Embed one stored message into the semantic index — the step the classification Workflow runs after it
+ * classifies.
+ *
+ * **The vector is written, then the stamp.** A step that dies between the two leaves a message with no stamp,
+ * which is exactly the set `pithy vector reprocess --index support-messages` picks up, so a half-done write heals
+ * rather than hides.
+ *
+ * **A message gone by the stamp keeps no vector.** The stamp is written only while the message exists, and a
+ * message deleted between the read and the upsert has its vector deleted again, so a purge that lands mid-step
+ * leaves nothing derived from the person's words.
+ *
+ * **Ids only.** The upsert carries the message id and the components, and no metadata at all.
+ */
+
+/** What embedding a message needs. Every one is a seam, so a test hands in fakes. */
+export interface EmbedMessageDeps {
+  /** The support tables. */
+  db: SupportDatabase;
+  /** The Workers AI binding. */
+  ai: VectorAi;
+  /** The Vectorize binding the message index arrives on. */
+  store: VectorStore;
+  /** The index's config — the model it is pinned to and the width it holds. */
+  index: VectorIndexConfig;
+  /** Now. */
+  now: () => Date;
+}
+
+/** Embed one message and stamp it. Returns false when the message no longer exists, read or stamp. */
+export async function embedMessage(deps: EmbedMessageDeps, messageId: string): Promise<boolean> {
+  const message = await deps.db
+    .selectFrom(SUPPORT_MESSAGES_TABLE)
+    .select(["id", "subject", "textBody"])
+    .where("id", "=", messageId)
+    .executeTakeFirst();
+  // A Workflow instance can outlive the row that started it; a purge is the ordinary way.
+  if (!message) return false;
+
+  const [values] = await embedForIndex(deps.ai, deps.index, [embeddingText(message.subject, message.textBody)]);
+  await upsertVectors(deps.store, deps.index, [{ id: message.id, values: values as number[] }]);
+
+  // A message deleted since the read gets no stamp, and its vector is deleted again.
+  const stamped = await writeStamps(deps.db, deps.store, [message.id], deps.index.model, deps.now());
+  return stamped.has(message.id);
+}
+
+/** What one embedding step did. Returned through the step, so a replay restores it. */
+export type EmbedOutcome =
+  | { embedded: true }
+  | {
+      embedded: false;
+      /**
+       * `gone` — the message no longer exists. `unbound` — the index's binding is not on this worker yet, until
+       * `pithy support provision` deploys it. `failed` — the model or the index did not answer.
+       */
+      reason: "gone" | "unbound" | "failed";
+    };
+
+/**
+ * The embedding step, as the classification Workflow runs it: **never fatal**.
+ *
+ * A message that could not be embedded is stored, classified, and missing from semantic results only — and,
+ * having no stamp, it is exactly what the next `pithy vector reprocess --index support-messages` picks up. So a
+ * failure is reported in the outcome and the log, and never thrown into the Workflow that also classifies.
+ */
+export async function runEmbedding(
+  deps: Omit<EmbedMessageDeps, "store"> & { store: VectorStore | undefined; log?: Logger },
+  messageId: string,
+): Promise<EmbedOutcome> {
+  if (!deps.store) {
+    deps.log?.warn("support semantic search is on but the index is not bound to this worker — not embedding", {
+      messageId,
+    });
+    return { embedded: false, reason: "unbound" };
+  }
+  try {
+    return (await embedMessage({ ...deps, store: deps.store }, messageId))
+      ? { embedded: true }
+      : { embedded: false, reason: "gone" };
+  } catch (error) {
+    deps.log?.warn("support message not embedded — it stays out of semantic results until a reprocess", {
+      messageId,
+      error,
+    });
+    return { embedded: false, reason: "failed" };
+  }
+}