@pithy-sh/support 0.1.2 → 0.1.4

package/dist/submission/submit.js

@@ -0,0 +1,321 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportInvalidCategoryError, SupportNotFoundError, SupportRejectedError } from "../error/errors.js";
+import { categoryEnum } from "../data/categories.js";
+import { SupportAttachment } from "../data/attachment.js";
+import { SupportMessage } from "../data/message.js";
+import { SupportThread, UNCLASSIFIED } from "../data/thread.js";
+import { SUPPORT_ATTACHMENTS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE } from "../data/tables.js";
+import { attachmentKey, putAttachment, sha256Hex } from "../attachment/store.js";
+import { SupportAuditActions } from "../audit/actions.js";
+import { indexMessage } from "../store/search.js";
+import { safeFilename } from "../mime/parse.js";
+import { checkAccountRate, checkAttachment } from "./guard.js";
+import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { chunkRowsByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+//#region src/submission/submit.ts
+/** Record a refusal. Never throws — a guard decision must not become a 500 on top of a 429. */
+async function auditRejection(deps, reason, detail, userId) {
+	try {
+		await deps.emit({
+			action: SupportAuditActions.submissionRejected,
+			outcome: "denied",
+			severity: "warning",
+			actorType: "user",
+			actorId: userId,
+			resourceType: "support_inbox",
+			metadata: {
+				reason,
+				channel: "app"
+			}
+		});
+		deps.log.warn("support submission refused", {
+			reason,
+			detail,
+			userId
+		});
+	} catch (error) {
+		deps.log.warn("support submission rejection audit dropped", {
+			reason,
+			detail,
+			error
+		});
+	}
+}
+/**
+* Resolve the thread a submission continues.
+*
+* **Both conditions, and a 404 rather than a 403 when either fails.** The thread must be this
+* account's and it must be an app thread: a 403 would confirm that the id names a real conversation,
+* which on an inbox of other people's correspondence is the disclosure the check exists to prevent —
+* so an id belonging to somebody else is indistinguishable from one belonging to nobody.
+*
+* An `email` thread is excluded even when it carries this account's `userId`, and that exclusion is
+* the point rather than an oversight: that link was matched from an address in a header nobody proved,
+* so treating it as ownership would let whoever currently holds an address read a conversation that
+* merely *claims* to be theirs.
+*/
+async function resolveOwnThread(db, threadId, userId) {
+	const thread = await db.selectFrom(SUPPORT_THREADS_TABLE).select(["id"]).where("id", "=", threadId).where("userId", "=", userId).where("channel", "=", "app").executeTakeFirst();
+	if (!thread) throw new SupportNotFoundError({ detail: `no app thread ${threadId} owned by ${userId}` });
+	return thread;
+}
+/**
+* Check a submitter's declared category, before anything else and before any I/O.
+*
+* **An undeclared key is refused, never stored and never downgraded.** Storing it would make
+* `declared_category` a client-writable vocabulary: one client shipping `Billing` or `billng` and the
+* console's filter silently misses those threads forever, while the inbox grows a long tail of one-off
+* keys nobody declared. Downgrading to `uncategorized` is the worse of the two remaining options,
+* because it makes a broken chooser indistinguishable from a submitter who genuinely chose nothing —
+* the exact collapse this column exists to prevent, arrived at from the other side.
+*
+* It is refused rather than tolerated **because the writer can be fixed.** `classifyMessage` falls back
+* to `uncategorized` on a label the model invented, and that is right there: a model cannot be told it
+* was wrong at the call site. A client can, and a 400 is how it gets told — the chooser was built from
+* a taxonomy the adopter declared, so a value outside it is that client's bug and should be loud.
+*
+* **A category may not ride along with a `threadId`.** A thread already carries what it was filed
+* under, and a second, later claim has no honest meaning: ignoring it is a chooser that does nothing —
+* which is the whole defect this seam exists to close — and honoring it would let a follow-up rewrite
+* the premise a conversation was opened on, the way `subject` deliberately cannot. So it is refused,
+* loudly, and a chooser stays what it is: something offered on the form that opens a request.
+*
+* **Nothing the submitter wrote reaches `message`.** The offending value goes in `detail`, which the
+* HTTP codec strips — this capability's whole input is text somebody else chose, and an error that
+* echoed it back would make the error channel a reflection surface.
+*/
+function checkDeclaredCategory(deps, input) {
+	const declared = input.declaredCategory;
+	if (declared === void 0) return;
+	if (input.threadId !== void 0) throw new ValidationError({
+		message: "A category is chosen when a request is opened, not on a later message.",
+		action: "Send the category with the first message, or leave it off to continue the conversation.",
+		detail: `submission declared a category alongside threadId ${input.threadId}`
+	});
+	if (!categoryEnum(deps.categories).safeParse(declared).success) throw new SupportInvalidCategoryError({
+		message: "That is not a category this app offers.",
+		action: "Choose one of the categories the app declares, or send the request without one.",
+		detail: `submitted category ${JSON.stringify(declared)} is not in the effective taxonomy (${Object.keys(deps.categories).join(", ")})`
+	});
+}
+/** How many columns one `pithy_support_attachments` row binds — derived, so a new column re-chunks. */
+const SUPPORT_ATTACHMENT_COLUMNS = Object.keys(SupportAttachment.shape).length;
+/**
+* Check every attachment before one byte is written.
+*
+* All-or-nothing, and refused rather than skipped — the opposite of the mail path, and the difference
+* is who is on the other end. An oversize part of an email is dropped because the sender is gone and
+* the message is still worth keeping; a submitter is right there, holding the screenshot that is the
+* most valuable thing the report carries, and silently storing the report without it means the first
+* reply asks for a file they believed they had already sent.
+*/
+function checkAttachments(deps, attachments) {
+	const bounds = deps.config.submission.attachments;
+	if (attachments.length === 0) return;
+	if (!bounds.enabled) throw new ValidationError({
+		message: "This app does not accept attachments on a support request.",
+		action: "Send the report without a file, and describe what you would have attached.",
+		detail: "submission.attachments.enabled is false"
+	});
+	if (attachments.length > bounds.maxCount) throw new ValidationError({
+		message: `A support request may carry at most ${bounds.maxCount} attachments.`,
+		action: `Send at most ${bounds.maxCount} files.`,
+		detail: `submission declared ${attachments.length} attachments, over the ${bounds.maxCount} bound`
+	});
+	for (const attachment of attachments) {
+		const verdict = checkAttachment(deps.config.submission, {
+			contentType: attachment.contentType,
+			bytes: attachment.bytes.byteLength
+		});
+		if (verdict.accepted) continue;
+		throw new ValidationError({
+			message: verdict.reason === "attachment_too_large" ? `An attachment may be at most ${bounds.maxBytes} bytes.` : "That kind of file cannot be attached to a support request.",
+			action: verdict.reason === "attachment_too_large" ? "Attach a smaller file." : `Attach one of: ${bounds.allowedContentTypes.join(", ")}.`,
+			detail: verdict.detail
+		});
+	}
+}
+/** Store the checked attachments. Returns how many rows were written. */
+async function storeAttachments(deps, attachments, threadId, messageId, now) {
+	const bucket = deps.bucket;
+	if (attachments.length === 0) return 0;
+	if (!bucket) {
+		deps.log.warn("support submission attachments dropped — no bucket bound", {
+			threadId,
+			messageId
+		});
+		return 0;
+	}
+	const rows = [];
+	for (const attachment of attachments) {
+		const id = deps.newId();
+		const key = attachmentKey(threadId, id);
+		await putAttachment(bucket, key, attachment.bytes);
+		rows.push({
+			id,
+			messageId,
+			threadId,
+			filename: safeFilename(attachment.filename),
+			contentType: attachment.contentType,
+			size: attachment.bytes.byteLength,
+			sha256: await sha256Hex(attachment.bytes),
+			storageKey: key,
+			contentId: null,
+			inline: false,
+			createdAt: now
+		});
+	}
+	const encoded = rows.map((row) => SupportAttachment.encode(row));
+	for (const chunk of chunkRowsByBoundParameters(encoded, SUPPORT_ATTACHMENT_COLUMNS)) await deps.db.insertInto(SUPPORT_ATTACHMENTS_TABLE).values(chunk).execute();
+	return rows.length;
+}
+/**
+* Mint an RFC 5322 message id for a submission.
+*
+* **Without this the conversation forks the first time the customer answers.** A reply to an app thread
+* leaves by email carrying `In-Reply-To`, the customer's client puts that id in its `References`, and
+* `parentCandidates` looks it up in `pithy_support_messages` — so a submission stored with no id of its
+* own is a thread whose every answer opens a new one. The whole reason `mime/threading.ts` refuses to
+* match on subject is that fragmented conversations are the failure mode worth engineering against.
+*
+* The domain comes from the inbox address, because that is the domain the reply will actually leave
+* from; with no address configured there is no reply and therefore nothing to thread.
+*/
+function submissionMessageId(messageId, inboxAddress) {
+	const domain = inboxAddress?.split("@")[1];
+	return domain ? `${messageId}@${domain}` : null;
+}
+/** Take one in-app submission. */
+async function submitFeedback(deps, input) {
+	const now = deps.now();
+	checkDeclaredCategory(deps, input);
+	const account = await deps.resolveAccount(input.userId);
+	if (!account) throw new InternalError({
+		message: "Your account could not be read.",
+		action: "Retry, and contact support by email if it keeps happening.",
+		detail: `no pithy_auth_users row for authenticated user ${input.userId} — is @pithy-sh/auth composed on this Worker?`
+	});
+	const rate = await checkAccountRate(deps.db, deps.config.submission, {
+		userId: input.userId,
+		now
+	});
+	if (!rate.accepted) {
+		await auditRejection(deps, rate.reason, rate.detail, input.userId);
+		throw new SupportRejectedError({
+			message: "You have sent too many support requests recently.",
+			action: "Wait an hour and try again, or reply to the email on an existing request.",
+			detail: rate.detail
+		});
+	}
+	checkAttachments(deps, input.attachments);
+	const existing = input.threadId ? await resolveOwnThread(deps.db, input.threadId, input.userId) : void 0;
+	const threadId = existing?.id ?? deps.newId();
+	const newThread = existing === void 0;
+	const messageId = deps.newId();
+	const inbox = deps.config.reply.replyToAddress ?? deps.config.inboundAddresses[0] ?? null;
+	const message = {
+		id: messageId,
+		threadId,
+		direction: "inbound",
+		channel: "app",
+		submittedByUserId: input.userId,
+		context: input.context ?? null,
+		mimeMessageId: submissionMessageId(messageId, inbox),
+		mimeInReplyTo: null,
+		mimeReferences: null,
+		fromAddress: account.email,
+		fromName: account.name ?? null,
+		toAddress: inbox,
+		subject: input.subject,
+		textBody: input.body,
+		htmlBody: null,
+		emailJobId: null,
+		rawKey: null,
+		rawBytes: null,
+		receivedAt: now,
+		createdAt: now
+	};
+	await deps.db.insertInto(SUPPORT_MESSAGES_TABLE).values(SupportMessage.encode(message)).execute();
+	try {
+		if (newThread) {
+			const thread = {
+				id: threadId,
+				channel: "app",
+				inboxAddress: inbox,
+				subject: input.subject,
+				fromAddress: account.email,
+				fromName: account.name ?? null,
+				senderAuthenticated: true,
+				userId: input.userId,
+				accountLinkSource: "session",
+				declaredCategory: input.declaredCategory ?? null,
+				...UNCLASSIFIED,
+				archived: false,
+				archivedAt: null,
+				archivedBy: null,
+				messageCount: 1,
+				firstMessageAt: now,
+				lastMessageAt: now,
+				createdAt: now,
+				updatedAt: now
+			};
+			await deps.db.insertInto(SUPPORT_THREADS_TABLE).values(SupportThread.encode(thread)).execute();
+		} else await deps.db.updateTable(SUPPORT_THREADS_TABLE).set((eb) => ({
+			messageCount: eb("messageCount", "+", 1),
+			lastMessageAt: now.getTime(),
+			updatedAt: now.getTime(),
+			archived: 0,
+			archivedAt: null,
+			archivedBy: null
+		})).where("id", "=", threadId).execute();
+	} catch (error) {
+		await deps.db.deleteFrom(SUPPORT_MESSAGES_TABLE).where("id", "=", messageId).execute().catch(() => {
+			deps.log.error("support submission orphaned — thread write failed and the message could not be removed", {
+				messageId,
+				threadId
+			});
+		});
+		throw error;
+	}
+	if (deps.fts) try {
+		await indexMessage(deps.db, {
+			threadId,
+			messageId,
+			subject: input.subject,
+			body: input.body
+		});
+	} catch (error) {
+		deps.log.warn("support submission not indexed", {
+			messageId,
+			error
+		});
+	}
+	let attachments = 0;
+	try {
+		attachments = await storeAttachments(deps, input.attachments, threadId, messageId, now);
+	} catch (error) {
+		deps.log.warn("support submission attachments not stored", {
+			messageId,
+			error
+		});
+	}
+	const classifying = deps.config.ai.enabled;
+	if (classifying) try {
+		await deps.dispatchClassify(messageId);
+	} catch (error) {
+		deps.log.warn("support submission classification dispatch failed", {
+			messageId,
+			error
+		});
+	}
+	return {
+		threadId,
+		messageId,
+		newThread,
+		attachments,
+		classifying
+	};
+}
+//#endregion
+export { submissionMessageId, submitFeedback };

package/dist/version.generated.d.ts

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/** This package's npm name — the join key against a release feed. */
+export declare const PACKAGE_NAME = "@pithy-sh/support";
+/** This package's version, stamped from its own package.json at generation time. */
+export declare const PACKAGE_VERSION = "0.1.4";
+//# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,sBAAsB,CAAC;AAEhD,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}

package/dist/version.generated.js

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/version.generated.ts
+/** This package's npm name — the join key against a release feed. */
+const PACKAGE_NAME = "@pithy-sh/support";
+/** This package's version, stamped from its own package.json at generation time. */
+const PACKAGE_VERSION = "0.1.4";
+//#endregion
+export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/workflows/classify.d.ts

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { SupportAi } from "../ai/classify";
+import type { SupportAiConfig } from "../config/config";
+import type { SupportCategories } from "../data/categories";
+import { type SupportDatabase } from "../data/tables";
+/**
+ * The classification orchestration — the pure, testable core the Workflow step runs.
+ *
+ * Reads a message, asks the model about it, **appends** a classification row, and denormalizes the
+ * answer onto its thread. The two writes are deliberate and asymmetric: the history is append-only
+ * so a model upgrade is visible in the data rather than a silent rewrite, and the thread carries only
+ * the current answer because that is what the inbox query reads.
+ *
+ * Idempotent by construction. Re-running over the same message appends a second row and overwrites
+ * the same three thread columns with a fresh judgment — which is what makes a Workflow retry, a
+ * manual reclassify, and a post-upgrade backfill the same operation.
+ */
+/** Everything classification needs, all injectable. */
+export interface ClassifyDeps {
+    /** The support tables. */
+    db: SupportDatabase;
+    /** The Workers AI binding. */
+    ai: SupportAi;
+    /** The effective taxonomy — the defaults plus the adopter's. */
+    categories: SupportCategories;
+    /** Model, bounds, and temperature. */
+    ai_config: SupportAiConfig;
+    /**
+     * Archive a thread the classifier calls `spam`, so it never reaches the open inbox.
+     *
+     * **Archived, never deleted.** The classifier is wrong sometimes, and a pass that destroyed mail
+     * would be untrustworthy the first time it was — whereas an archived thread is still readable under
+     * the archived filter and one click from being back. That is what makes `spam` a filter rather than
+     * a bin, and it is why this is safe to have on by default.
+     */
+    archiveSpam: boolean;
+    /** Generate a row id. */
+    newId: () => string;
+    /** Now. */
+    now: () => Date;
+}
+/** What one classification run did. `null` when the message no longer exists. */
+export interface ClassifyOutcome {
+    /** The thread the classification landed on. */
+    threadId: string;
+    /** The category chosen. */
+    category: string;
+    /** The model's confidence. */
+    confidence: number;
+    /** The model that produced it. */
+    model: string;
+    /** Whether this run archived the thread because it classified as spam. */
+    archivedAsSpam: boolean;
+}
+/** Classify one stored message and write the result. Returns null when the message is gone. */
+export declare function runClassification(deps: ClassifyDeps, messageId: string): Promise<ClassifyOutcome | null>;
+/**
+ * The message a manual reclassify runs against: a thread's most recent **inbound** message.
+ *
+ * Inbound, not latest — a thread whose last message is our own reply would otherwise be reclassified
+ * on the text the adopter wrote, which says nothing about what the customer wanted.
+ */
+export declare function latestInboundMessageId(db: SupportDatabase, threadId: string): Promise<string | undefined>;
+//# sourceMappingURL=classify.d.ts.map

package/dist/workflows/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/workflows/classify.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;GAWG;AAEH,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,EAAE,EAAE,eAAe,CAAC;IACpB,8BAA8B;IAC9B,EAAE,EAAE,SAAS,CAAC;IACd,gEAAgE;IAChE,UAAU,EAAE,iBAAiB,CAAC;IAC9B,sCAAsC;IACtC,SAAS,EAAE,eAAe,CAAC;IAC3B;;;;;;;OAOG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,yBAAyB;IACzB,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,WAAW;IACX,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,+FAA+F;AAC/F,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAwE9G;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAc/G"}

package/dist/workflows/classify.js

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import "../data/enums.js";
+import { SupportClassification } from "../data/classification.js";
+import { SUPPORT_CLASSIFICATIONS_TABLE, SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE } from "../data/tables.js";
+import { classifyMessage } from "../ai/classify.js";
+//#region src/workflows/classify.ts
+/** Classify one stored message and write the result. Returns null when the message is gone. */
+async function runClassification(deps, messageId) {
+	const message = await deps.db.selectFrom(SUPPORT_MESSAGES_TABLE).select([
+		"id",
+		"threadId",
+		"subject",
+		"textBody"
+	]).where("id", "=", messageId).executeTakeFirst();
+	if (!message) return null;
+	const result = await classifyMessage(deps.ai, {
+		categories: deps.categories,
+		subject: message.subject,
+		body: message.textBody,
+		model: deps.ai_config.model,
+		maxChars: deps.ai_config.maxChars,
+		temperature: deps.ai_config.temperature
+	});
+	const now = deps.now();
+	await deps.db.insertInto(SUPPORT_CLASSIFICATIONS_TABLE).values(SupportClassification.encode({
+		id: deps.newId(),
+		threadId: message.threadId,
+		messageId: message.id,
+		category: result.category,
+		priority: result.priority,
+		sentiment: result.sentiment,
+		confidence: result.confidence,
+		model: result.model,
+		createdAt: now
+	})).execute();
+	const archivedAsSpam = deps.archiveSpam && result.category === "spam";
+	await deps.db.updateTable(SUPPORT_THREADS_TABLE).set({
+		category: result.category,
+		priority: result.priority,
+		sentiment: result.sentiment,
+		confidence: result.confidence,
+		model: result.model,
+		classifiedAt: now.getTime(),
+		updatedAt: now.getTime(),
+		...archivedAsSpam ? {
+			archived: 1,
+			archivedAt: now.getTime(),
+			archivedBy: result.model
+		} : {}
+	}).where("id", "=", message.threadId).execute();
+	return {
+		threadId: message.threadId,
+		category: result.category,
+		confidence: result.confidence,
+		model: result.model,
+		archivedAsSpam
+	};
+}
+/**
+* The message a manual reclassify runs against: a thread's most recent **inbound** message.
+*
+* Inbound, not latest — a thread whose last message is our own reply would otherwise be reclassified
+* on the text the adopter wrote, which says nothing about what the customer wanted.
+*/
+async function latestInboundMessageId(db, threadId) {
+	return (await db.selectFrom(SUPPORT_MESSAGES_TABLE).select(["id"]).where("threadId", "=", threadId).where("direction", "=", "inbound").orderBy("receivedAt", "desc").orderBy("id", "desc").limit(1).executeTakeFirst())?.id;
+}
+//#endregion
+export { latestInboundMessageId, runClassification };

package/dist/workflows/retryPolicy.d.ts

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
+/**
+ * **What a classification retries, and what it refuses to.**
+ *
+ * `ai/classify.ts` already drew this line and drew it correctly: a model that returns prose, an invented
+ * label, or an envelope nobody documented yields `uncategorized` at zero confidence and never throws,
+ * because throwing would burn a retry budget on a model that is going to say the same thing next time.
+ * The one case it deliberately does not swallow is a binding that is *unavailable*. This is that
+ * sentence in the form the durable step reads (pithy-sh/pithy#348).
+ *
+ * ## Retryable, and why
+ *
+ * - **`core/upstream_failed`** — Workers AI rejected the call. Raised at exactly one place, the wrap
+ *   around `ai.run` in `classifyMessage`, and it means the model did not answer at all. That is the
+ *   whole population of transient faults in a classification, and the code is what lets the step tell
+ *   it from a bad answer — a raw throw would be `unclassified`, and unclassified is terminal.
+ * - **A transient D1 fault** — the message read, the appended history row, the thread denormalization.
+ *   Classified in core by `withD1Retry`, never restated here.
+ *
+ * ## Terminal, and why
+ *
+ * - **`support/not_found`** — a thread or message that is gone. `runClassification` does not even raise
+ *   it for the message it was started for: a missing row returns `null`, because an instance outliving
+ *   the row that started it is the ordinary way a rollback looks.
+ * - **`support/classification_failed`** — the AI binding is absent from the env. A binding does not
+ *   appear on the fourth attempt; this wants `pithy support provision`.
+ * - **`support/invalid_category`** — the adopter's taxonomy will not validate. Config, and identical
+ *   next time.
+ * - **`support/unparseable_message`, `support/rejected`, `support/reply_failed`** — all inbound-path and
+ *   reply-path refusals. None runs inside the classify step.
+ * - **`validation/invalid_input`** — a payload the schema refuses.
+ *
+ * **Re-running is free, which is what makes the retryable entry safe.** Classification is idempotent by
+ * construction: a second pass appends a second history row and overwrites the same three thread columns
+ * with a fresh judgment, which is why a Workflow retry, a manual reclassify, and a post-upgrade
+ * backfill are the same operation.
+ */
+export declare const supportWorkflowRetry: WorkflowRetryPolicy;
+//# sourceMappingURL=retryPolicy.d.ts.map

package/dist/workflows/retryPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryPolicy.d.ts","sourceRoot":"","sources":["../../src/workflows/retryPolicy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,oBAAoB,EAAE,mBAMlC,CAAC"}

package/dist/workflows/retryPolicy.js

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/workflows/retryPolicy.ts
+/**
+* **What a classification retries, and what it refuses to.**
+*
+* `ai/classify.ts` already drew this line and drew it correctly: a model that returns prose, an invented
+* label, or an envelope nobody documented yields `uncategorized` at zero confidence and never throws,
+* because throwing would burn a retry budget on a model that is going to say the same thing next time.
+* The one case it deliberately does not swallow is a binding that is *unavailable*. This is that
+* sentence in the form the durable step reads (pithy-sh/pithy#348).
+*
+* ## Retryable, and why
+*
+* - **`core/upstream_failed`** — Workers AI rejected the call. Raised at exactly one place, the wrap
+*   around `ai.run` in `classifyMessage`, and it means the model did not answer at all. That is the
+*   whole population of transient faults in a classification, and the code is what lets the step tell
+*   it from a bad answer — a raw throw would be `unclassified`, and unclassified is terminal.
+* - **A transient D1 fault** — the message read, the appended history row, the thread denormalization.
+*   Classified in core by `withD1Retry`, never restated here.
+*
+* ## Terminal, and why
+*
+* - **`support/not_found`** — a thread or message that is gone. `runClassification` does not even raise
+*   it for the message it was started for: a missing row returns `null`, because an instance outliving
+*   the row that started it is the ordinary way a rollback looks.
+* - **`support/classification_failed`** — the AI binding is absent from the env. A binding does not
+*   appear on the fourth attempt; this wants `pithy support provision`.
+* - **`support/invalid_category`** — the adopter's taxonomy will not validate. Config, and identical
+*   next time.
+* - **`support/unparseable_message`, `support/rejected`, `support/reply_failed`** — all inbound-path and
+*   reply-path refusals. None runs inside the classify step.
+* - **`validation/invalid_input`** — a payload the schema refuses.
+*
+* **Re-running is free, which is what makes the retryable entry safe.** Classification is idempotent by
+* construction: a second pass appends a second history row and overwrites the same three thread columns
+* with a fresh judgment, which is why a Workflow retry, a manual reclassify, and a post-upgrade
+* backfill are the same operation.
+*/
+const supportWorkflowRetry = {
+	capability: "support",
+	retryable: { "core/upstream_failed": "The model did not answer at all; classification is idempotent, so asking again costs one call." }
+};
+//#endregion
+export { supportWorkflowRetry };

package/dist/workflows/specs.d.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { WorkflowRegistry } from "@pithy-sh/core/src/workflow/spec";
+import { z } from "zod";
+/**
+ * The one durable job support owns, declared once.
+ *
+ * **Classification is a Workflow, not part of the `email()` handler**, and that is a hard constraint
+ * rather than a preference. An inbound handler runs under a tight CPU budget; a model call is
+ * hundreds of milliseconds of wall time it cannot spend, and a model that is slow or briefly
+ * unavailable would take the *persistence* of the message down with it. So the handler does the
+ * cheap, must-not-fail half — parse, bound, store — and hands off. A classification that fails
+ * retries against a message that is already safely in D1.
+ *
+ * `optional: true`: the Workflow lives in the prebuilt support worker that `pithy support provision`
+ * deploys, so a project that has not provisioned must still boot and still receive mail. An absent
+ * binding degrades to a logged skip and a thread that stays `uncategorized` — which is exactly the
+ * state a classification is allowed to be in.
+ */
+/** The capability name — the first segment of the dispatch key and of every deployed workflow name. */
+export declare const SUPPORT_CAPABILITY = "support";
+/** Which message to classify. */
+export declare const SupportClassifyParams: z.ZodObject<{
+    messageId: z.ZodString;
+}, z.core.$strip>;
+export type SupportClassifyParams = z.infer<typeof SupportClassifyParams>;
+/** Support's durable jobs, keyed by job name. The key is the second segment of the `support/<job>` dispatch key. */
+export declare const supportWorkflows: {
+    readonly classify: {
+        readonly binding: "SUPPORT_CLASSIFY";
+        readonly className: "SupportClassifyWorkflow";
+        readonly params: z.ZodObject<{
+            messageId: z.ZodString;
+        }, z.core.$strip>;
+        readonly optional: true;
+    };
+};
+/**
+ * Support's jobs as a dispatch registry, keyed `support/<job>`. Built here rather than through
+ * `composeWorkflows` because the inbound handler dispatches from inside the capability, before any
+ * project-wide registry exists — and the key format comes from core's {@link workflowKey} either
+ * way, so the two cannot drift.
+ */
+export declare const supportWorkflowRegistry: WorkflowRegistry;
+//# sourceMappingURL=specs.d.ts.map

package/dist/workflows/specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../src/workflows/specs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;GAcG;AAEH,uGAAuG;AACvG,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C,iCAAiC;AACjC,eAAO,MAAM,qBAAqB;;iBASsE,CAAC;AACzG,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,oHAAoH;AACpH,eAAO,MAAM,gBAAgB;;iBAEzB,OAAO,EAAE,kBAAkB;iBAC3B,SAAS,EAAE,yBAAyB;iBACpC,MAAM;;;iBACN,QAAQ;;CAEwB,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAKrC,CAAC"}