@pithy-sh/support 0.1.0

package/src/data/enums.ts

@@ -0,0 +1,90 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The closed axes of the support model — the ones that are genuinely fixed, as opposed to the
+ * taxonomy in `categories.ts`, which is federated because every app has its own vocabulary.
+ *
+ * Priority and sentiment are not federated on purpose. A category answers *what is this*, and that
+ * question has as many answers as there are products. Priority answers *how fast*, and sentiment
+ * answers *who is about to churn* — both are questions about the sender, not about the product, so a
+ * fourth priority level or a fifth sentiment would describe the same reality with more words.
+ */
+
+/** How fast a thread needs a human. */
+export const SupportPriority = z
+  .enum(["urgent", "normal", "low"])
+  .describe("How fast this thread needs a human: `urgent` today, `normal` this week, `low` when there is time.");
+export type SupportPriority = z.infer<typeof SupportPriority>;
+
+/** How the sender sounds. The churn signal, not a politeness score. */
+export const SupportSentiment = z
+  .enum(["angry", "frustrated", "neutral", "positive"])
+  .describe(
+    "How the sender sounds — the churn signal. `angry` and `frustrated` are the ones worth sorting an inbox by.",
+  );
+export type SupportSentiment = z.infer<typeof SupportSentiment>;
+
+/** Which way a message traveled. */
+export const SupportMessageDirection = z
+  .enum(["inbound", "outbound"])
+  .describe("`inbound` arrived from the customer; `outbound` is a reply this Worker sent on the send path.");
+export type SupportMessageDirection = z.infer<typeof SupportMessageDirection>;
+
+/**
+ * How a message reached this inbox.
+ *
+ * Closed for the same reason priority is: a channel is a *transport this capability implements*, not a
+ * vocabulary an adopter brings — there is no third answer a project could need that the code would not
+ * also have to be taught to speak. It is the axis the two halves of the capability differ on, and the
+ * differences are real rather than cosmetic: `email` arrives at a public address from an unauthenticated
+ * `From:` header, and `app` arrives on a request whose session was already proved.
+ */
+export const SupportChannel = z
+  .enum(["email", "app"])
+  .describe(
+    "How this arrived: `email` at a configured inbound address, or `app` from a signed-in user of the adopter's own app. The axis the console filters on, and the one the account link's provenance follows from.",
+  );
+export type SupportChannel = z.infer<typeof SupportChannel>;
+
+/**
+ * How a thread came to name an account — the provenance of `userId`, and the distinction
+ * `inbound/authenticity.ts` spends two hundred lines earning.
+ *
+ * A `From:` header is an unauthenticated claim, so an email thread's link is a *match on an address
+ * anybody could have written*. An in-app submission has no `From:` to spoof: `requireAuth()` proved
+ * the session before the handler ran, so the link is the identity rather than a guess about it.
+ *
+ * **A console must not render the two the same way.** They differ in exactly the situation that
+ * matters — deciding whether to act on somebody's billing history — and a single boolean cannot say
+ * which one it is looking at. `senderAuthenticated` answers *may we believe this*, and this answers
+ * *how did we come to believe it*; the second is what an operator needs when the first is false and
+ * there is still a name on the thread.
+ */
+export const SupportAccountLinkSource = z
+  .enum(["session", "email_address"])
+  .describe(
+    "How this thread's `userId` was established: `session` means an authenticated request proved it, `email_address` means it was matched from the address in a `From:` header. Never equivalent — one is the identity, the other is a lookup on a claim.",
+  );
+export type SupportAccountLinkSource = z.infer<typeof SupportAccountLinkSource>;
+
+/**
+ * The category every taxonomy carries, whatever else it declares, and the value a classification
+ * falls back to.
+ *
+ * It exists so "the model was unsure" is a first-class answer rather than a guess. A text model will
+ * always produce *a* label, and a plausible-sounding invented one silently poisons every filter
+ * downstream — so an out-of-taxonomy answer lands here instead.
+ */
+export const UNCATEGORIZED = "uncategorized";
+
+/**
+ * The one other category key the code names directly, because a behavior hangs off it: a thread the
+ * classifier calls spam is archived on sight when `guard.archiveSpam` is on.
+ *
+ * Naming it here rather than inline keeps the string in one place — an adopter may reword the
+ * *description* the model reads, but the key is the join between the taxonomy and that behavior.
+ */
+export const SPAM = "spam";

package/src/data/flag.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * One viewer's private view of one thread, in `pithy_support_thread_flags`.
+ *
+ * The other deliberate exception to "no coordination state", and the milder of the two. `archived` is
+ * shared because done means done; these are **per viewer** because nobody coordinates around them —
+ * whether Ada has read a thread says nothing about whether Grace has, and two people marking the same
+ * thread read is not a conflict. Keeping them in their own table rather than as columns on the thread
+ * is what makes that structural instead of a convention.
+ *
+ * `viewer` is the control-plane subject — the management client's identity, not a Pithy user. There
+ * is no user table behind it and there does not need to be: the value is opaque, and a connection
+ * that goes away simply leaves rows nothing reads.
+ */
+export const SupportThreadFlag = z
+  .object({
+    id: z.string().describe("UUID primary key."),
+    threadId: z.string().describe("The `pithy_support_threads.id` these flags apply to."),
+    viewer: z
+      .string()
+      .describe(
+        "The control-plane subject whose view this is. Unique together with `threadId`, so a viewer has exactly one row per thread and marking read twice is an upsert rather than a second row.",
+      ),
+    read: SQLiteBoolean.describe("Whether this viewer has read the thread."),
+    snoozedUntil: SQLiteDate.nullish().describe(
+      "Hide the thread from this viewer's inbox until this moment. Null means not snoozed. A time rather than a boolean, so a snooze expires on its own and nothing has to sweep.",
+    ),
+    createdAt: SQLiteDate.describe("When the flag row was created."),
+    updatedAt: SQLiteDate.describe("When the flag row was last written."),
+  })
+  .describe("One viewer's read/snooze state for one thread — private, uncoordinated, and safe to lose.");
+export type SupportThreadFlag = z.output<typeof SupportThreadFlag>;

package/src/data/message.ts

@@ -0,0 +1,224 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { SupportChannel, SupportMessageDirection } from "./enums";
+
+/**
+ * What the app knows about the moment a report was written, and the user did not have to type.
+ *
+ * A bug report without the screen, the build, and the environment is a round trip — the first reply is
+ * always "which version, and where were you?". The app already holds all three, so asking a human to
+ * retype them is the kind of friction this channel exists to remove.
+ *
+ * **It is a closed object, and unknown keys are refused rather than stripped.** This is a capability,
+ * not a telemetry pipe: the risk of an open bag is that an adopter passes their whole client state
+ * through it and quietly lands a customer's data in a support inbox that a console renders and an
+ * operator reads. A closed set means a field that is not here cannot be posted by accident, and a
+ * refusal says so at the boundary rather than silently dropping what somebody believed they sent.
+ * Every field is bounded, because every one of them is a string a client chose.
+ */
+export const SupportSubmissionContext = z
+  .object({
+    screen: z
+      .string()
+      .min(1)
+      .max(120)
+      .optional()
+      .describe(
+        "Where in the app they were — a route, a screen name, whatever the app calls it. The single most useful field, because it turns 'the button does nothing' into a place to look.",
+      ),
+    appVersion: z
+      .string()
+      .min(1)
+      .max(64)
+      .optional()
+      .describe(
+        "The build the report came from. Answers 'is this already fixed' without a round trip, which is the whole reason a bug report asks for it.",
+      ),
+    platform: z
+      .string()
+      .min(1)
+      .max(64)
+      .optional()
+      .describe(
+        "The client the app is running as — `ios`, `android`, `web`, or whatever the adopter's own build calls itself. Free text rather than an enum: the set of clients is the adopter's, not this capability's.",
+      ),
+    environment: z
+      .string()
+      .min(1)
+      .max(32)
+      .optional()
+      .describe(
+        "Which environment the client was pointed at. A report from staging read as production is a bug hunted in the wrong database, and the client is the only thing that knows.",
+      ),
+    // **A bounded string, and the tag is validated where it is used rather than here.**
+    //
+    // This is the *public submission body*. A `Locale` on it rejects the whole bug report with
+    // `validation/invalid_input` when the tag is not well-formed — and `en_US` is exactly what Android,
+    // iOS and Java `Locale.toString()` produce, which is to say the likeliest thing a mobile client
+    // sends. Losing a report because its diagnostic metadata had an underscore in it is a far worse
+    // trade than losing the metadata, and a report is the one thing this route exists to not lose.
+    //
+    // The boundary that matters is the one into `pithy_email_jobs.locale`, whose column really is
+    // `Locale`-constrained: `enqueueEmail` normalizes an unusable tag to `null` there, so a malformed
+    // value stored here degrades the language of one reply and breaks nothing. `.catch(undefined)`
+    // would express that here, but `asRead` cannot derive a reader's contract from a `ZodCatch`, and
+    // the admin view is projected from this schema.
+    locale: z
+      .string()
+      .min(1)
+      .max(32)
+      .optional()
+      .describe(
+        "The locale the app was rendering in. Carried because a whole class of reports — a date a day out, a currency in the wrong place, text that overflows — is only reproducible in the reporter's locale. Not validated as a tag here: see `enqueueEmail`, which normalizes it before it reaches a column that is.",
+      ),
+  })
+  .strict()
+  .describe(
+    "The bounded context an app supplies with a submission, so a bug report arrives with the facts its first reply would otherwise have to ask for.",
+  );
+export type SupportSubmissionContext = z.output<typeof SupportSubmissionContext>;
+
+/** The `References` header, split into ids. A JSON column so the chain stays a list rather than a string to re-split. */
+export const SupportReferenceIds = z
+  .array(z.string().describe("One RFC 5322 message id from the `References` chain, without its angle brackets."))
+  .describe("The `References` chain, oldest first — the thread's ancestry as the sender's mail client recorded it.");
+export type SupportReferenceIds = z.output<typeof SupportReferenceIds>;
+
+/**
+ * One message in `pithy_support_messages` — inbound mail as it arrived, or a reply as it went out.
+ *
+ * **The raw MIME is kept immutable in R2 and never rewritten.** `textBody`/`htmlBody` are a derived,
+ * sanitized rendering of it, so a parser bug, a sanitizer change, or a reclassification pass can all
+ * be re-run from the bytes that actually arrived. Storing only the parsed form would make the parse a
+ * one-way decision taken at the worst possible moment — inside an `email()` handler with a CPU budget.
+ *
+ * `mimeMessageId` carries a **unique index**, and that is the idempotency anchor: Email Routing can
+ * deliver the same message twice, and the second delivery must be a no-op rather than a duplicate.
+ * SQLite permits repeated `NULL`s in a unique index, so a message that arrived without a `Message-ID`
+ * (rare, and always a sign of something hand-rolled) still stores instead of colliding.
+ */
+export const SupportMessage = z
+  .object({
+    id: z.string().describe("UUID primary key for this message row — Pithy's id, not the sender's."),
+    threadId: z.string().describe("The `pithy_support_threads.id` this message belongs to."),
+    direction: SupportMessageDirection.describe("Which way this message traveled."),
+    channel: SupportChannel.describe(
+      "How this message traveled, which on an outbound row is **how the answer was delivered**: `email` means it was handed to `@pithy-sh/email`'s durable send path, `app` means it was stored for the submitter to read in the app and no mail was sent. Per message rather than only per thread, because the two genuinely differ — one `app` thread can hold an answer that was mailed and an answer that was not, and those are different promises about when somebody will read them.",
+    ),
+    submittedByUserId: z
+      .string()
+      .nullish()
+      .describe(
+        "The authenticated `pithy_auth_users.id` that posted this message from inside the app. Null on every mail-path message and on every outbound reply. Taken from the request's session and **never** from anything the client sent — it is the identity, so it is also what the per-account submission bound counts.",
+      ),
+    context: sqliteJson(SupportSubmissionContext)
+      .nullish()
+      .describe(
+        "The bounded context the app supplied — screen, build, platform, environment, locale. Null on every mail-path message, and on an app submission that declared none.",
+      ),
+    mimeMessageId: z
+      .string()
+      .nullish()
+      .describe(
+        "The RFC 5322 `Message-ID`, without angle brackets. Uniquely indexed, so a redelivered message is dropped rather than duplicated. Null when the sender omitted one.",
+      ),
+    mimeInReplyTo: z
+      .string()
+      .nullish()
+      .describe(
+        "The `In-Reply-To` id, without angle brackets — the direct parent. The first key threading tries, because it names exactly one message.",
+      ),
+    mimeReferences: sqliteJson(SupportReferenceIds)
+      .nullish()
+      .describe(
+        "The `References` chain as a JSON column. Threading falls back to it when `In-Reply-To` names nothing we hold, which is what keeps a conversation together across a client that rewrites the subject.",
+      ),
+    fromAddress: z
+      .string()
+      .nullish()
+      .describe(
+        "The address this message was sent from, lowercased. **Null exactly on an answer delivered in the app**, which left no envelope — there is no address a reply that was never mailed came from, and putting the deployment's own address there would claim a send that did not happen. Never null on anything that traveled by mail, and never present on anything that did not. Checked on the object, both ways, so it is a rule rather than a note.",
+      ),
+    fromName: z.string().nullish().describe("The sender's display name. Untrusted text; render it escaped."),
+    toAddress: z
+      .string()
+      .nullish()
+      .describe(
+        "The address this message was addressed to, lowercased. **Null on an app submission to a project with no inbound address configured** — there was no envelope, and inventing one would put a string nothing can deliver to into the column the idempotency index keys on. Never null on a mail-path message.",
+      ),
+    subject: z.string().describe("This message's own subject line, which may differ from the thread's."),
+    textBody: z
+      .string()
+      .describe(
+        "The plain-text body, or a text rendering of an HTML-only message. Always present, because the classifier reads this and a model should never be handed markup.",
+      ),
+    htmlBody: z
+      .string()
+      .nullish()
+      .describe(
+        "The HTML body **after sanitization** — scripts, event handlers, styles, frames, and remote-loading attributes removed. Null when the message carried no HTML. The raw original is still in R2 if the sanitizer ever needs re-running.",
+      ),
+    emailJobId: z
+      .string()
+      .nullish()
+      .describe(
+        "The `pithy_email_jobs.id` this message was enqueued as. **Present exactly when `direction` is `outbound` and `channel` is `email`**, and null everywhere else — it is the join to the job, never the way to ask whether an answer went out. That question is `channel`'s, because a null here would otherwise mean both 'this arrived' and 'this was delivered in the app', and a client would have to consult `direction` to tell them apart. It is the *job* id rather than the sent `Message-ID` deliberately: Cloudflare assigns the real id at send time and never tells the enqueuer, so a column claiming to hold it would be null exactly when somebody needed it.",
+      ),
+    rawKey: z
+      .string()
+      .nullish()
+      .describe(
+        "The R2 object key holding the immutable raw MIME. Null only when the bucket binding was absent at ingest, which is a degraded mode rather than a normal one.",
+      ),
+    rawBytes: z.number().int().nullish().describe("The raw message's size in bytes, as received."),
+    receivedAt: SQLiteDate.describe(
+      "When this Worker received the message — our clock, never the sender's `Date` header, which is attacker-controlled and would let anyone place themselves at the top of an inbox.",
+    ),
+    createdAt: SQLiteDate.describe("When the message row was written."),
+  })
+  .describe("One message in `pithy_support_messages` — the derived rendering of mail whose raw form lives in R2.")
+  // **The invariant, stated once, where every producer already passes.** `emailJobId` is the join to
+  // `pithy_email_jobs` and nothing else: it is present exactly when this message traveled by mail on
+  // the way out. Written at a call site instead, this rule would hold until the second writer — and
+  // there are already five (ingest, submission, the reply path, the seeds, the tests). Enforced here
+  // it also runs on the way *back* out of D1, so a row that reached the table by any other route
+  // cannot be handed to a projection that would render it as sent.
+  .check((ctx) => {
+    const row = ctx.value;
+    const mailed = row.direction === "outbound" && row.channel === "email";
+    const hasJob = row.emailJobId !== null && row.emailJobId !== undefined;
+    if (hasJob === mailed) return;
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      path: ["emailJobId"],
+      message: mailed
+        ? "An outbound `email` message must carry the `emailJobId` it was enqueued as. The row is written after the enqueue is accepted, so one without a job id is a reply nothing was ever asked to send."
+        : "Only an outbound `email` message carries an `emailJobId`. An answer delivered in the app was never enqueued, and an inbound message was never sent — a job id on either makes the column mean something other than the job it names.",
+    });
+  })
+  // **The second invariant, enforced the way the first one is.** `fromAddress` was loosened to nullable
+  // for one row — the answer `sendReply` stores in the app, which has no envelope — and the rule that
+  // bounds that was written as prose on the field. Prose holds until the second writer, which is the
+  // argument the check above is made of; there is no reason it carries less weight here. A null on a
+  // message that traveled by mail is a thread nobody can answer, because `sendReply` addresses the
+  // reply to it. An address on one that did not travel claims a send that never happened, to every
+  // projection that renders the column.
+  .check((ctx) => {
+    const row = ctx.value;
+    const inApp = row.direction === "outbound" && row.channel === "app";
+    const hasAddress = row.fromAddress !== null && row.fromAddress !== undefined;
+    if (hasAddress === !inApp) return;
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      path: ["fromAddress"],
+      message: inApp
+        ? "An answer delivered in the app has no `fromAddress`. It left no envelope, so an address there names a send that did not happen."
+        : "Everything but an answer delivered in the app carries the `fromAddress` it came from or went out as. Without one there is no address to reply to.",
+    });
+  });
+export type SupportMessage = z.output<typeof SupportMessage>;

package/src/data/tables.ts

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { SupportAttachment } from "./attachment";
+import { SupportClassification } from "./classification";
+import { SupportThreadFlag } from "./flag";
+import { SupportMessage } from "./message";
+import { SupportThread } from "./thread";
+
+/**
+ * The support tables. Keys are camelCase; `CamelCasePlugin` snake-cases them to the `pithy_support_*`
+ * SQL, so query code in this package never types the prefix and never types an underscore.
+ */
+
+/** Conversations. `pithy_support_threads`. */
+export const SUPPORT_THREADS_TABLE = "pithySupportThreads";
+/** Messages, inbound and outbound. `pithy_support_messages`. */
+export const SUPPORT_MESSAGES_TABLE = "pithySupportMessages";
+/** Attachment metadata. `pithy_support_attachments`. */
+export const SUPPORT_ATTACHMENTS_TABLE = "pithySupportAttachments";
+/** Append-only classification history. `pithy_support_classifications`. */
+export const SUPPORT_CLASSIFICATIONS_TABLE = "pithySupportClassifications";
+/** Per-viewer read/snooze state. `pithy_support_thread_flags`. */
+export const SUPPORT_FLAGS_TABLE = "pithySupportThreadFlags";
+
+/**
+ * The FTS5 full-text index. Not a Kysely table and deliberately not in {@link supportTables}: it is a
+ * virtual table with no Zod schema and no rows of its own worth typing, reached through raw `sql`
+ * from `store/search.ts` alone.
+ *
+ * Named in snake_case because nothing translates it — `CamelCasePlugin` rewrites identifiers Kysely
+ * builds, and every statement touching this one is written by hand.
+ */
+export const SUPPORT_SEARCH_TABLE = "pithy_support_search";
+
+/** The table map the capability contributes to the app database. */
+export const supportTables = {
+  [SUPPORT_THREADS_TABLE]: SupportThread,
+  [SUPPORT_MESSAGES_TABLE]: SupportMessage,
+  [SUPPORT_ATTACHMENTS_TABLE]: SupportAttachment,
+  [SUPPORT_CLASSIFICATIONS_TABLE]: SupportClassification,
+  [SUPPORT_FLAGS_TABLE]: SupportThreadFlag,
+} satisfies Record<string, z.ZodObject>;
+
+/** The support tables, as a type. */
+export type SupportTables = typeof supportTables;
+
+/** The typed Kysely view over the support tables. Carries `CamelCasePlugin`. */
+export type SupportDatabase = Kysely<DatabaseSchema<SupportTables>>;
+
+/** Build the support database from a `DB` binding. */
+export function supportDatabase(d1: D1Database): SupportDatabase {
+  return createDatabase(d1, supportTables) as unknown as SupportDatabase;
+}

package/src/data/thread.ts

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { SupportAccountLinkSource, SupportChannel, SupportPriority, SupportSentiment, UNCATEGORIZED } from "./enums";
+
+/**
+ * One conversation in `pithy_support_threads` — the row the inbox is a list of.
+ *
+ * **Everything on it is derived from immutable inbound mail.** The classification is recomputed, never
+ * repaired; the user link is a lookup, not a decision; the counters are facts about the messages
+ * below. There is no assignee and no status, because a status field is a state machine and a state
+ * machine attracts SLAs, escalation, and reporting — which is a ticketing product and explicitly not
+ * this. The two exceptions are deliberate and named: `archived` (one shared boolean meaning done) and
+ * the per-viewer flags, which live in their own table because nobody coordinates around them.
+ *
+ * The classification axes are **denormalized onto the thread** rather than joined from
+ * `pithy_support_classifications`. The whole dashboard interaction is "newest first, filtered by
+ * category and priority and archived", and that is a composite-index workload — a join to find the
+ * latest classification per thread would make the one query this table exists to serve the expensive
+ * one. The classification table keeps the history; this keeps the answer.
+ */
+export const SupportThread = z
+  .object({
+    id: z
+      .string()
+      .describe(
+        "UUID primary key. Text, not autoincrement, because a thread id reaches a dashboard and an enumerable inbox is an enumerable customer list.",
+      ),
+    channel: SupportChannel.describe(
+      "How this conversation started — `email` at an inbound address, or `app` from a signed-in user. Never rewritten by a later message: the channel a thread opened on is what its account link's provenance follows from, and a thread that changed channel would change what its link means.",
+    ),
+    inboxAddress: z
+      .string()
+      .nullish()
+      .describe(
+        "The support address this thread arrived on, lowercased. Stored per thread so one Worker can serve several inboxes (support@, security@) and the dashboard can filter by which — and it is the address a reply comes back to. **Null on an `app` thread with no inbound address configured**, which is a supported deployment: a project can collect in-app feedback with no mail set up at all. Never null on an `email` thread, which by definition arrived at one.",
+      ),
+    subject: z
+      .string()
+      .describe(
+        "The subject of the message that opened the thread. Later replies never rewrite it — the thread keeps its name.",
+      ),
+    fromAddress: z
+      .string()
+      .describe(
+        "The sender's address, lowercased. The join key for the user link, the sender history, and the volume guard — so it is normalized on the way in, once. On an `app` thread it is the authenticated account's own email, read from the account rather than from anything the client sent, which is what lets a reply leave on the existing mail path with nothing new to configure.",
+      ),
+    fromName: z
+      .string()
+      .nullish()
+      .describe(
+        "The sender's display name from the `From` header, when they had one. Untrusted text; render it escaped.",
+      ),
+    senderAuthenticated: SQLiteBoolean.describe(
+      "Whether the sender was proved to be who they claim. On an `email` thread that means the `From:` header was proved — DMARC passed, or SPF passed on an aligned domain — and **false does not mean forged**, it means unproven, which is the common case for a domain publishing no DMARC policy. On an `app` thread it is always true, and it is true for a stronger reason: there was no header to prove, because `requireAuth()` proved the session before the request reached a handler. It gates the customer link: an unproven sender is never decorated with somebody's real purchase history, because that is what turns a spoofed message into support-driven account takeover.",
+    ),
+    userId: z
+      .string()
+      .nullish()
+      .describe(
+        "The `pithy_auth_users.id` this sender resolves to, or null when the address belongs to nobody with an account — or when the sender was not authenticated, because an unproven `From:` must not resolve to a real customer. Derived on the mail path, so a customer who signs up later is linked by the next message rather than by a repair; on the app path it is the session's own user id and there is nothing to derive.",
+      ),
+    accountLinkSource: SupportAccountLinkSource.nullish().describe(
+      "How `userId` was established, or null when there is no link. **The column that keeps a session-proven link from reading like a header-inferred one** — `senderAuthenticated` says whether to believe it, this says what was believed. A console rendering the two identically is the failure this exists to prevent, because the same operator action follows from very different evidence.",
+    ),
+    declaredCategory: z
+      .string()
+      .nullish()
+      .describe(
+        "**What the submitter said this is about** — a claim, made once, by the person writing. Null when nobody said: every `email` thread, and every `app` thread whose client offered no chooser. Written when the thread opens and **never afterwards**: not by a later message, and not by the classifier, which owns `category` and does not know this column exists. That separation is the whole point. A classification is recomputed on every retry, every manual reclassify, and every post-upgrade backfill — so a single column holding both facts loses whichever was written first, and the one an operator most needs is the *disagreement* between them: `declaredCategory: billing` beside `category: bug_report` says the customer thinks they were overcharged and the model thinks the app is broken, and no one column can say that. Validated against the effective taxonomy before it is stored, so this is never a client-writable vocabulary.",
+      ),
+    category: z
+      .string()
+      .describe(
+        "**What the classifier made of it** — the current answer, from this project's effective taxonomy, recomputed and never repaired. A plain string rather than an enum because the taxonomy is federated — the valid set is not known until an adopter composes the capability, so it is validated at the classification boundary instead of by the column. Distinct from `declaredCategory` above, which nothing here ever reads or writes.",
+      ),
+    priority: SupportPriority.describe("The current priority — how fast this thread needs a human."),
+    sentiment: SupportSentiment.describe("The current sentiment — the churn signal."),
+    confidence: z
+      .number()
+      .min(0)
+      .max(1)
+      .nullish()
+      .describe(
+        "The model's self-reported confidence in the current classification, 0..1. Null until a classification lands. Kept so a low-confidence inbox can be reviewed separately from a confident one.",
+      ),
+    model: z
+      .string()
+      .nullish()
+      .describe(
+        "The Workers AI model id that produced the current classification. Recorded so a reclassification pass after a model upgrade can tell which rows came from which model — the whole reason reclassification is possible at all.",
+      ),
+    classifiedAt: SQLiteDate.nullish().describe(
+      "When the current classification was written; null until the Workflow has run.",
+    ),
+    archived: SQLiteBoolean.describe(
+      "Done. One shared boolean, not per viewer, because if one person resolves a thread another should not still see it open. The mildest possible coordination state: no transitions to get wrong, nothing can be stuck, and unarchiving undoes a mistake instantly.",
+    ),
+    archivedAt: SQLiteDate.nullish().describe("When the thread was last archived; null while it is open."),
+    archivedBy: z
+      .string()
+      .nullish()
+      .describe(
+        "The control-plane subject that archived it. Recorded for the dashboard's convenience only — the answer to 'who marked this done' comes from the audit trail, which is why this is not an ownership column.",
+      ),
+    messageCount: z.number().int().describe("How many messages the thread holds, inbound and outbound together."),
+    firstMessageAt: SQLiteDate.describe("When the thread opened — the receive time of its first message."),
+    lastMessageAt: SQLiteDate.describe(
+      "When the thread last moved. The inbox sorts on this, and it is the `receivedAt` half of every composite index and of the pagination cursor.",
+    ),
+    createdAt: SQLiteDate.describe("When the thread row was created."),
+    updatedAt: SQLiteDate.describe("When the thread row was last written."),
+  })
+  .describe("One support conversation in `pithy_support_threads` — derived entirely from the mail below it.");
+export type SupportThread = z.output<typeof SupportThread>;
+
+/**
+ * What a brand-new thread's classification columns hold before the Workflow has run.
+ *
+ * **`declaredCategory` is deliberately not in here**, and the omission is load-bearing rather than an
+ * oversight. This object is the set of columns the classifier owns — `runClassification` overwrites
+ * every one of them on each run — so a submitter's claim listed among them would be erased by the
+ * first classification and by every retry after it. It is set beside this spread, from the submission,
+ * and nothing on the classification path names it.
+ */
+export const UNCLASSIFIED = {
+  category: UNCATEGORIZED,
+  priority: "normal",
+  sentiment: "neutral",
+  confidence: null,
+  model: null,
+  classifiedAt: null,
+} as const satisfies Pick<
+  SupportThread,
+  "category" | "priority" | "sentiment" | "confidence" | "model" | "classifiedAt"
+>;