@pithy-sh/support 0.5.1 → 0.6.1

package/dist/purge/contribution.js

@@ -0,0 +1,164 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportAssignment } from "../data/assignment.js";
+import { SupportAttachment } from "../data/attachment.js";
+import { SupportMessage } from "../data/message.js";
+import { SupportThread } from "../data/thread.js";
+import { SUPPORT_ASSIGNMENTS_TABLE, SUPPORT_ATTACHMENTS_TABLE, SUPPORT_CLASSIFICATIONS_TABLE, SUPPORT_EMBEDDINGS_TABLE, SUPPORT_FLAGS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE, supportDatabase } from "../data/tables.js";
+import { SUPPORT_BUCKET_BINDING } from "../secret/registry.js";
+import { SUPPORT_VECTORIZE_BINDING } from "../semantic/messageIndex.js";
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { sql } from "kysely";
+import { deleteVectors } from "@pithy-sh/vector/src/index/index";
+import { exportRows, purgeBinding } from "@pithy-sh/core/src/capability/purge";
+//#region src/purge/contribution.ts
+/**
+* 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). */
+const ERASED_ASSIGNER = "erased-user";
+/** The one sentence the purge records with this step. */
+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 = 1e3;
+/** Vector ids one `deleteByIds` call takes — Vectorize's own write batch, the same ceiling an upsert has. */
+const VECTOR_DELETE_IDS = 1e3;
+/**
+* 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) {
+	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(row) {
+	const { assignedBy: _assigner, ...rest } = row;
+	return rest;
+}
+/** The person's thread ids, oldest first, at most `limit`. */
+async function threadIds(db, predicate, limit) {
+	return (await db.selectFrom(SUPPORT_THREADS_TABLE).select("id").where(predicate).orderBy("createdAt").orderBy("id").limit(limit).execute()).map((row) => row.id);
+}
+/** The user contribution `support()` declares. */
+function supportUserPurge(database = "DB", options = {}) {
+	const open = (env) => {
+		const d1 = purgeBinding(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);
+			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)));
+			let bucket;
+			let vectors;
+			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) => typeof key === "string" && key !== "")];
+				if (keys.length > 0) {
+					bucket ??= purgeBinding(context.env, SUPPORT_BUCKET_BINDING, "support", "R2 bucket");
+					for (let start = 0; start < keys.length; start += R2_DELETE_KEYS) await bucket.delete(keys.slice(start, start + R2_DELETE_KEYS));
+				}
+				if (vectors === void 0 && context.env["SUPPORT_VECTORIZE"] === void 0) {
+					if (options.semantic === true || await db.selectFrom("pithySupportEmbeddings").select("messageId").where("messageId", "in", (eb) => eb.selectFrom("pithySupportMessages").select("id").where("threadId", "in", ids)).executeTakeFirst() !== void 0) vectors = purgeBinding(context.env, SUPPORT_VECTORIZE_BINDING, "support", "Vectorize index");
+				} else vectors ??= purgeBinding(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));
+				}
+				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)));
+			}
+		},
+		export: async (context) => {
+			const { db } = open(context.env);
+			const predicate = await theirs(context);
+			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(),
+				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)))
+			};
+		}
+	};
+}
+//#endregion
+export { ERASED_ASSIGNER, SUPPORT_PURGE_SUMMARY, supportUserPurge };

package/dist/secret/registry.d.ts

@@ -2,7 +2,8 @@
 // SPDX-License-Identifier: MIT
 import { type SupportConfig } 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
@@ -26,8 +27,31 @@ export declare const SUPPORT_R2_SECRET = "support-r2-credentials";
  * reads the decline the bindings side already reports.
  */
 export declare 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 declare const supportPresenceRegistry: {
+    readonly "presence-ticket-key": {
+        readonly backend: "d1";
+        readonly scope: "environment";
+        readonly rotatable: true;
+        readonly valueType: "text";
+        readonly devValue: "random";
+    };
+};
 /** The support capability's secret-registry slice — aggregated into the shared accessor at startup. */
-export declare const supportSecretsRegistry: Record<"support-r2-credentials", import("@pithy-sh/storage/src/secret/registry").R2CredentialsEntry>;
+export declare const supportSecretsRegistry: {
+    readonly "presence-ticket-key": {
+        readonly backend: "d1";
+        readonly scope: "environment";
+        readonly rotatable: true;
+        readonly valueType: "text";
+        readonly devValue: "random";
+    };
+    readonly "support-r2-credentials": import("@pithy-sh/storage/src/secret/registry").R2CredentialsEntry;
+};
 /**
  * **The credential this composition cannot reach**, as the `inapplicableSecrets` contribution (#541).
  *

package/dist/secret/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/secret/registry.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;GAYG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD,uGAAuG;AACvG,eAAO,MAAM,sBAAsB,sGAAmE,CAAC;AAEvG;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3F"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/secret/registry.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;;GAaG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;CAElC,CAAC;AAEH,uGAAuG;AACvG,eAAO,MAAM,sBAAsB;;;;;;;;;CAGjC,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3F"}

package/dist/secret/registry.js

@@ -1,10 +1,13 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { supportNeedsBucket } from "../config/config.js";
+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";
 //#region src/secret/registry.ts
 /**
-* 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
@@ -28,8 +31,17 @@ const SUPPORT_R2_SECRET = "support-r2-credentials";
 * reads the decline the bindings side already reports.
 */
 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.
+*/
+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. */
-const supportSecretsRegistry = r2CredentialsRegistry(SUPPORT_R2_SECRET, SUPPORT_BUCKET_BINDING);
+const supportSecretsRegistry = defineSecretRegistry({
+	...r2CredentialsRegistry(SUPPORT_R2_SECRET, SUPPORT_BUCKET_BINDING),
+	...supportPresenceRegistry
+});
 /**
 * **The credential this composition cannot reach**, as the `inapplicableSecrets` contribution (#541).
 *
@@ -53,4 +65,4 @@ function inapplicableAttachmentSecrets(config) {
 	return { [SUPPORT_R2_SECRET]: "support() stores no attachments — attachments.enabled, attachments.retainRaw and submission.attachments.enabled are all off" };
 }
 //#endregion
-export { SUPPORT_BUCKET_BINDING, SUPPORT_R2_SECRET, inapplicableAttachmentSecrets, supportSecretsRegistry };
+export { SUPPORT_BUCKET_BINDING, SUPPORT_R2_SECRET, inapplicableAttachmentSecrets, supportPresenceRegistry, supportSecretsRegistry };

package/dist/semantic/documents.d.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { DocumentStore } from "@pithy-sh/vector/src/data/documents";
+import { type VectorStore } from "@pithy-sh/vector/src/index/index";
+import { type SupportDatabase } from "../data/tables";
+/**
+ * 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 declare function writeStamps(db: SupportDatabase, store: VectorStore | undefined, ids: readonly string[], model: string, at: Date): Promise<Set<string>>;
+/**
+ * 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 declare function supportMessageDocuments(db: SupportDatabase, options?: {
+    store?: VectorStore;
+}): DocumentStore;
+//# sourceMappingURL=documents.d.ts.map

package/dist/semantic/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/semantic/documents.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEnF,OAAO,EAAoD,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAmCxG;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,eAAe,EACnB,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,IAAI,GACP,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CA4BtB;AAgBD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,WAAW,CAAA;CAAO,GAAG,aAAa,CAwEjH"}

package/dist/semantic/documents.js

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportEmbedding } from "../data/embedding.js";
+import { SUPPORT_EMBEDDINGS_TABLE, SUPPORT_MESSAGES_TABLE } from "../data/tables.js";
+import { SUPPORT_MESSAGES_INDEX, embeddingText } from "./messageIndex.js";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { deleteVectors } from "@pithy-sh/vector/src/index/index";
+//#region src/semantic/documents.ts
+/**
+* `@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;
+/**
+* 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.
+*/
+async function writeStamps(db, store, ids, model, at) {
+	const stamped = /* @__PURE__ */ new Set();
+	if (ids.length === 0) return stamped;
+	const embeddedAt = SupportEmbedding.shape.embeddedAt.encode(at);
+	for (const group of chunkByBoundParameters(ids, STAMP_FIXED_PARAMETERS)) {
+		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) {
+	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.
+*/
+function supportMessageDocuments(db, options = {}) {
+	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) => indexName === SUPPORT_MESSAGES_INDEX;
+	return {
+		async put() {
+			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) : null;
+		},
+		async byIds(indexName, ids) {
+			if (!ours(indexName) || ids.length === 0) return [];
+			const documents = [];
+			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));
+			}
+			return documents;
+		},
+		async remove(indexName, id) {
+			if (!ours(indexName)) return false;
+			return ((await db.deleteFrom("pithySupportEmbeddings").where("messageId", "=", id).executeTakeFirst()).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 !== void 0) query = query.where((eb) => eb.or([eb(`${SUPPORT_EMBEDDINGS_TABLE}.model`, "is", null), eb(`${SUPPORT_EMBEDDINGS_TABLE}.model`, "!=", stale)]));
+			return (await query.execute()).map((row) => documentOf(row));
+		},
+		async markEmbedded(indexName, ids, model, at) {
+			if (!ours(indexName)) return;
+			await writeStamps(db, options.store, ids, model, at);
+		}
+	};
+}
+//#endregion
+export { supportMessageDocuments, writeStamps };

package/dist/semantic/embed.d.ts

@@ -0,0 +1,59 @@
+// 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 { type VectorAi } from "@pithy-sh/vector/src/embed/embed";
+import { type VectorStore } from "@pithy-sh/vector/src/index/index";
+import { type SupportDatabase } from "../data/tables";
+/**
+ * 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 declare function embedMessage(deps: EmbedMessageDeps, messageId: string): Promise<boolean>;
+/** 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 declare function runEmbedding(deps: Omit<EmbedMessageDeps, "store"> & {
+    store: VectorStore | undefined;
+    log?: Logger;
+}, messageId: string): Promise<EmbedOutcome>;
+//# sourceMappingURL=embed.d.ts.map

package/dist/semantic/embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../../src/semantic/embed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI9E;;;;;;;;;;;;;GAaG;AAEH,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,0BAA0B;IAC1B,EAAE,EAAE,eAAe,CAAC;IACpB,8BAA8B;IAC9B,EAAE,EAAE,QAAQ,CAAC;IACb,0DAA0D;IAC1D,KAAK,EAAE,WAAW,CAAC;IACnB,6EAA6E;IAC7E,KAAK,EAAE,iBAAiB,CAAC;IACzB,WAAW;IACX,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,sGAAsG;AACtG,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAe9F;AAED,uFAAuF;AACvF,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClB;IACE,QAAQ,EAAE,KAAK,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;CACvC,CAAC;AAEN;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GAAG;IAAE,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACxF,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC,CAkBvB"}

package/dist/semantic/embed.js

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SUPPORT_MESSAGES_TABLE } from "../data/tables.js";
+import { embeddingText } from "./messageIndex.js";
+import { writeStamps } from "./documents.js";
+import { embedForIndex } from "@pithy-sh/vector/src/embed/embed";
+import { upsertVectors } from "@pithy-sh/vector/src/index/index";
+//#region src/semantic/embed.ts
+/** Embed one message and stamp it. Returns false when the message no longer exists, read or stamp. */
+async function embedMessage(deps, messageId) {
+	const message = await deps.db.selectFrom(SUPPORT_MESSAGES_TABLE).select([
+		"id",
+		"subject",
+		"textBody"
+	]).where("id", "=", messageId).executeTakeFirst();
+	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
+	}]);
+	return (await writeStamps(deps.db, deps.store, [message.id], deps.index.model, deps.now())).has(message.id);
+}
+/**
+* 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.
+*/
+async function runEmbedding(deps, messageId) {
+	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"
+		};
+	}
+}
+//#endregion
+export { embedMessage, runEmbedding };

package/dist/semantic/messageIndex.d.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type FeatureIdentity } from "@pithy-sh/core/src/naming/feature";
+import type { VectorIndexConfig } from "@pithy-sh/vector/src/config/config";
+import type { VectorIndexShape } from "@pithy-sh/vector/src/provision/provisionVector";
+import { type SupportSearchConfig } from "../config/config";
+/**
+ * The semantic message index — what it is called, what shape it has, and what text goes into it.
+ *
+ * **Support owns it, through `@pithy-sh/vector`'s public modules, and the adopter composes no `vector()`.** The
+ * index is declared here as a {@link VectorIndexConfig}, the same value `vector()` builds from an adopter's
+ * `indexes` block, so `embedForIndex`, `queryVectors` and the reprocess orchestration take it unchanged and pin
+ * the model on writes and queries alike.
+ *
+ * **Vectors carry ids and nothing else.** A vector's id is the message's id, and no subject, body or address
+ * reaches Vectorize metadata: the text stays in D1 under the privacy markers its schema carries. A match is
+ * resolved back to its thread in D1, which is also where every filter applies.
+ */
+/** The index's name in `pithy vector reprocess --index`, and the `<thing>` its Cloudflare name ends with. */
+export declare const SUPPORT_MESSAGES_INDEX = "support-messages";
+/** The Vectorize binding the index arrives on, in the app Worker and the classification worker alike. */
+export declare const SUPPORT_VECTORIZE_BINDING = "SUPPORT_VECTORIZE";
+/** The Workers AI binding a query and an inbound message are embedded on. */
+export declare const SUPPORT_AI_BINDING = "AI";
+/**
+ * How much of a message is embedded. A support message states its point early, and the rest is usually a
+ * quoted thread and a signature — text that would pull every vector toward the same neighborhood.
+ */
+export declare const MAX_EMBED_CHARS = 4000;
+/** The index this search config asks for, or `undefined` when `search.semantic` is off. */
+export declare function supportMessageIndex(search: SupportSearchConfig): VectorIndexConfig | undefined;
+/**
+ * The shape `pithy support provision` creates the index with — `vector`'s own provisioning shape, so a support
+ * index and a `vector()` index are created, and refused on a mismatch, by the same rule. `undefined` when off.
+ */
+export declare function supportMessageIndexShape(search: SupportSearchConfig): VectorIndexShape | undefined;
+/**
+ * The index's Cloudflare name — `<project>-<env>-support-messages`, or a feature's own.
+ *
+ * Through the naming facade, which refuses a Vectorize name over 64 bytes rather than truncating it: a shortened
+ * name is a different, empty index.
+ */
+export declare function supportMessageIndexName(project: string, env: string, feature?: FeatureIdentity): string;
+/** The text one message is embedded as: its subject, then its body, bounded. */
+export declare function embeddingText(subject: string, body: string): string;
+//# sourceMappingURL=messageIndex.d.ts.map

package/dist/semantic/messageIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageIndex.d.ts","sourceRoot":"","sources":["../../src/semantic/messageIndex.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAA6B,MAAM,mCAAmC,CAAC;AAEpG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAAE,KAAK,mBAAmB,EAAmB,MAAM,kBAAkB,CAAC;AAE7E;;;;;;;;;;;GAWG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,yGAAyG;AACzG,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAE7D,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,SAAS,CAU9F;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,SAAS,CAGlG;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAGvG;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE"}