@pithy-sh/support 0.1.0

package/src/link/sender.ts

@@ -0,0 +1,334 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { parseAddress } from "@pithy-sh/core/src/address/address";
+import type { Entitlement } from "@pithy-sh/core/src/entitlement/entitlement";
+import { SUPPORT_BILLING_SCOPE } from "../data/billingScope";
+
+/**
+ * The link from an address in a `From` header to the customer the app already knows about.
+ *
+ * This is the feature the whole capability exists for. A support thread that arrives already knowing
+ * who the sender is, what they bought, on which rail, and whether their last renewal failed is a
+ * different object from a message in a mailbox — and every one of those facts is already in the
+ * adopter's own D1, one table over, unused.
+ *
+ * ## Guarded dynamic imports, not dependencies
+ *
+ * `@pithy-sh/auth` and `@pithy-sh/payments` are **optional** here (principle 4: depend on core seams,
+ * never on a sibling's internals), so both are reached the way `@pithy-sh/matchmaking` already
+ * reaches auth — a dynamic import inside a `try`, degrading to "no link" when the package is not
+ * installed. A support inbox in a project with no accounts and no payments is a perfectly reasonable
+ * thing to run, and it must not fail to start, or to store mail, because of what it cannot see.
+ *
+ * Every function here is **best-effort by contract**: it returns nothing rather than throwing, and
+ * the caller stores the message either way. Linkage is context, and context is never worth losing a
+ * customer's support request over.
+ *
+ * ## The billing half links people, and only people
+ *
+ * `@pithy-sh/payments` keys a purchase on a **subject pair** — a user or an organization, plus an id —
+ * and which of the two a project uses is its `billingSubject` config. Support cannot honor that choice.
+ * It starts from a `From:` header, resolves it to a *person*, and does its billing lookup at thread-read
+ * time, where there is no Hono `Context` to hand the adopter's subject resolver: the seam's whole job is
+ * to answer "which organization is *this caller* acting for", and a support thread has no caller.
+ *
+ * So this file reads `user`-subject rows, and {@link SUPPORT_BILLING_SCOPE} says so on every response.
+ * Under organization billing the panel is empty, and it must not be *silently* empty — the lookups below
+ * are guarded dynamic imports whose `catch` already returns `[]`, so an empty panel is indistinguishable
+ * between "bought nothing", "`@pithy-sh/payments` is not installed" and "billed to an organization".
+ * An operator reads the first of those and decides a refund on it. A declared scope is what turns the
+ * third case from a silence into a limitation somebody can see.
+ *
+ * **The scope constant used to be declared here, and is now `data/billingScope.ts` (Jim, 2026-08-21).**
+ * The old argument was that the query and the wire must read one value, which is right and unchanged —
+ * but `http/responses.ts` honoring it by importing from *this* file pulled the whole server data layer
+ * into a browser program, because that is what this file's imports are (#419). One value, in a module
+ * neither half owns.
+ */
+
+/** The account a sender resolves to, and what the app knows about them. */
+export interface SenderContext {
+  /**
+   * Whether the `From:` header was proved to belong to the sender. **Everything below is empty when
+   * this is false**, and a dashboard must render the sender as an unverified claim rather than as a
+   * customer — the whole value of this panel is that an operator trusts it, so it must not be
+   * populated from an address anybody could have written.
+   */
+  authenticated: boolean;
+  /** The linked `pithy_auth_users.id`, or null when this address belongs to nobody with an account. */
+  userId: string | null;
+  /** The account's display name, when auth is composed and the sender is known. */
+  name?: string;
+  /** Whether the account has verified this address. A useful signal beside an unverified claim in a header. */
+  emailVerified?: boolean;
+  /**
+   * Their purchase history, newest first — **individually billed purchases only**. Empty when payments
+   * is absent, when they have bought nothing, and when their billing is held by an organization this
+   * seam cannot resolve. `SenderContextView.billingScope` is what tells a console those apart.
+   */
+  purchases: readonly SenderPurchase[];
+  /**
+   * Their entitlements, lapsed ones included and marked inactive — a paywall wants to say when Pro
+   * ended. Same scope as {@link SenderContext.purchases}: `user` subjects, nothing organization-held.
+   */
+  entitlements: readonly Entitlement[];
+}
+
+/** One purchase, flattened to what a support console renders. */
+export interface SenderPurchase {
+  /** The purchase row id. */
+  id: string;
+  /** Which rail it went through — `apple`, `google`, or `stripe`. */
+  rail: string;
+  /** The Pithy product key. */
+  productId: string;
+  /** Its lifecycle state — `active`, `refunded`, `expired`, and so on. */
+  status: string;
+  /** Whether the purchase happened in the store's sandbox rather than production. */
+  environment: string;
+  /** When it was bought. */
+  purchasedAt: Date;
+  /** When it runs out; null for something owned forever. */
+  expiresAt: Date | null;
+  /** When it was refunded or revoked; null while it stands. */
+  revokedAt: Date | null;
+}
+
+/** How many purchases a thread view carries. Enough to see the pattern, bounded so a whale is not a slow page. */
+export const MAX_LINKED_PURCHASES = 25;
+
+/**
+ * Resolve a sender address to a user id.
+ *
+ * **Exact match on the normalized address, and deliberately no case-insensitive fallback.** The
+ * `email` column is indexed and unique, so this is one index seek; a `lower(email) = ?` fallback
+ * would be a full table scan, and it would run for *every unknown sender* — which on a public
+ * address means every piece of spam scanning the entire user table. Better Auth normalizes on its
+ * own signup path, so the exact match is the case that actually occurs; an address stored with
+ * capitals by some other route simply does not link, which costs a line of context rather than a
+ * customer's request.
+ */
+export async function resolveSenderUserId(d1: D1Database, address: string): Promise<string | null> {
+  const normalized = parseAddress(address);
+  if (!normalized) return null;
+
+  try {
+    const { authDatabase } = await import("@pithy-sh/auth/src/data/tables");
+    const row = await authDatabase(d1)
+      .selectFrom("pithyAuthUsers")
+      .select(["id"])
+      .where("email", "=", normalized)
+      .executeTakeFirst();
+    return row?.id ?? null;
+  } catch {
+    // `@pithy-sh/auth` is not installed, or the table does not exist yet. Both mean the same thing
+    // here: nobody to link to.
+    return null;
+  }
+}
+
+/**
+ * The address an operator's reply to an app thread will be sent to, or null when the account carries
+ * nothing deliverable.
+ *
+ * Extracted rather than inlined because it is the one decision in {@link resolveSubmitterAccount} with
+ * a wrong answer available, and inlining it puts that decision behind a guarded dynamic import where
+ * no test can reach it.
+ *
+ * **`parseAddress` only, with no `normalizeAddress` fallback.** The fallback merely trims and
+ * lowercases, so it would hand back an address this capability's own parser had just refused — and
+ * this value becomes the thread's `fromAddress`, which `sendReply` enqueues an answer to. Returning
+ * null makes an unparseable account the same hard fault as a missing one, which is what the caller
+ * already does with it: refusing the submission beats accepting a report whose only reply address
+ * cannot be delivered to.
+ */
+export function submitterAddress(email: string | null | undefined): string | null {
+  return (email && parseAddress(email)) || null;
+}
+
+/**
+ * The account behind an authenticated submitter — resolved by id, never by an address.
+ *
+ * The inverse of {@link resolveSenderUserId}, and it exists because the in-app channel starts from the
+ * opposite end: a session names a user id, and what the thread needs is the address a reply will go
+ * back to. Deriving that from anything the client sent would hand a signed-in caller the ability to
+ * point a support conversation — and every operator reply on it — at somebody else's mailbox.
+ *
+ * Returns null when `@pithy-sh/auth` is absent or the account is gone. A submission whose account
+ * cannot be read is refused by the caller rather than stored with a guessed address: an app thread with
+ * no working reply address is a report nobody can answer.
+ */
+export async function resolveSubmitterAccount(
+  d1: D1Database,
+  userId: string,
+): Promise<{ email: string; name?: string; emailVerified?: boolean } | null> {
+  try {
+    const { authDatabase } = await import("@pithy-sh/auth/src/data/tables");
+    const { User } = await import("@pithy-sh/auth/src/data/betterAuth");
+    const row = await authDatabase(d1)
+      .selectFrom("pithyAuthUsers")
+      .selectAll()
+      .where("id", "=", userId)
+      .executeTakeFirst();
+    if (!row) return null;
+    const user = User.parse(row);
+    const email = submitterAddress(user.email);
+    if (!email) return null;
+    return { email, name: user.name, emailVerified: user.emailVerified };
+  } catch {
+    return null;
+  }
+}
+
+/** Read the account's own fields, when auth is composed. */
+async function resolveAccount(
+  d1: D1Database,
+  address: string,
+): Promise<{ userId: string; name?: string; emailVerified?: boolean } | null> {
+  try {
+    const { authDatabase } = await import("@pithy-sh/auth/src/data/tables");
+    const { User } = await import("@pithy-sh/auth/src/data/betterAuth");
+    const row = await authDatabase(d1)
+      .selectFrom("pithyAuthUsers")
+      .selectAll()
+      .where("email", "=", address)
+      .executeTakeFirst();
+    if (!row) return null;
+    const user = User.parse(row);
+    return { userId: user.id, name: user.name, emailVerified: user.emailVerified };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read what the account bought, when payments is composed — **`user`-subject rows only**.
+ *
+ * Both halves of the pair, deliberately. Nothing in the kit keeps an organization id from equalling some
+ * user's, so a filter on the id alone would eventually hand one holder's purchases to the other — which
+ * is the whole reason payments made the holder a pair. See {@link SUPPORT_BILLING_SCOPE} for why the
+ * type half is pinned to `user` rather than resolved.
+ */
+async function resolvePurchases(d1: D1Database, userId: string): Promise<readonly SenderPurchase[]> {
+  try {
+    const { PAYMENTS_PURCHASES_TABLE, paymentsDatabase } = await import("@pithy-sh/payments/src/data/tables");
+    const { PaymentsPurchase } = await import("@pithy-sh/payments/src/data/purchase");
+    const rows = await paymentsDatabase(d1)
+      .selectFrom(PAYMENTS_PURCHASES_TABLE)
+      .selectAll()
+      .where("subjectType", "=", SUPPORT_BILLING_SCOPE)
+      .where("subjectId", "=", userId)
+      .orderBy("purchasedAt", "desc")
+      .limit(MAX_LINKED_PURCHASES)
+      .execute();
+    return rows.map((row) => {
+      const purchase = PaymentsPurchase.parse(row);
+      return {
+        id: purchase.id,
+        rail: purchase.rail,
+        productId: purchase.productId,
+        status: purchase.status,
+        environment: purchase.environment,
+        purchasedAt: purchase.purchasedAt,
+        expiresAt: purchase.expiresAt ?? null,
+        revokedAt: purchase.revokedAt ?? null,
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/** Read what the account is entitled to, when payments is composed — **`user`-subject rows only**. */
+async function resolveLinkedEntitlements(d1: D1Database, userId: string, now: Date): Promise<readonly Entitlement[]> {
+  try {
+    const { paymentsDatabase } = await import("@pithy-sh/payments/src/data/tables");
+    const { resolveEntitlements } = await import("@pithy-sh/payments/src/projection/resolve");
+    return await resolveEntitlements(
+      paymentsDatabase(d1),
+      { subjectType: SUPPORT_BILLING_SCOPE, subjectId: userId },
+      now,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Everything the app already knows about a sender — read at thread-read time rather than stored.
+ *
+ * Derived, so it is always current: a customer who buys Pro an hour after writing in shows as
+ * entitled the next time the thread is opened, with nothing to backfill and nothing to invalidate.
+ * That is the same rule the classification follows, applied to the half of the model that lives in
+ * somebody else's tables.
+ */
+export async function resolveSenderContext(
+  d1: D1Database,
+  address: string,
+  now: Date,
+  options: { authenticated: boolean },
+): Promise<SenderContext> {
+  const empty: SenderContext = { authenticated: options.authenticated, userId: null, purchases: [], entitlements: [] };
+
+  const normalized = parseAddress(address);
+  if (!normalized) return empty;
+
+  const account = await resolveAccount(d1, normalized);
+  if (!account) return empty;
+
+  // **An unverified match is reported; its billing history is not.**
+  //
+  // The two halves carry very different risk. A name beside an address is a labeled guess an
+  // operator can sanity-check, and withholding it would make the panel useless for the majority of
+  // real senders, since most domains publish no verdict this Worker can trust. An itemized purchase
+  // history is what somebody decides to issue a refund or reset an account on — presenting a real
+  // customer's on a thread that merely *claims* to be them is the whole account-takeover path.
+  //
+  // `emailVerified` is withheld too: it describes the *account*, but next to an unverified sender it
+  // reads as "this sender is verified", which is exactly the confusion this seam exists to remove.
+  if (!options.authenticated) {
+    return { authenticated: false, userId: account.userId, name: account.name, purchases: [], entitlements: [] };
+  }
+
+  return provenContext(d1, account, now);
+}
+
+/**
+ * The customer context behind a **session-proven** link, resolved from the user id itself.
+ *
+ * An app thread already holds the id its session proved, so re-deriving it from the thread's address
+ * would be both a step backwards and a correctness bug: `resolveSenderUserId` matches the `email`
+ * column exactly, and an account stored with capitals by some other route would silently resolve to
+ * nobody — turning the one link that *is* certain into the one the console shows as unknown.
+ *
+ * Everything below the link degrades exactly as it does on the mail path: purchases and entitlements
+ * are guarded dynamic imports and come back empty when `@pithy-sh/payments` is absent.
+ */
+export async function resolveSubmitterContext(d1: D1Database, userId: string, now: Date): Promise<SenderContext> {
+  const account = await resolveSubmitterAccount(d1, userId);
+  if (!account) return { authenticated: true, userId, purchases: [], entitlements: [] };
+  return provenContext(d1, { userId, name: account.name, emailVerified: account.emailVerified }, now);
+}
+
+/** The proven half, shared by both entry points: the account, plus what it bought and what it holds. */
+async function provenContext(
+  d1: D1Database,
+  account: { userId: string; name?: string; emailVerified?: boolean },
+  now: Date,
+): Promise<SenderContext> {
+  const [purchases, entitlements] = await Promise.all([
+    resolvePurchases(d1, account.userId),
+    resolveLinkedEntitlements(d1, account.userId, now),
+  ]);
+
+  return {
+    authenticated: true,
+    userId: account.userId,
+    name: account.name,
+    emailVerified: account.emailVerified,
+    purchases,
+    entitlements,
+  };
+}

package/src/migrations/0001_threads.ts

@@ -0,0 +1,296 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * The support inbox: threads, their messages, attachment metadata, the append-only classification
+ * history, and per-viewer flags.
+ *
+ * **The indexes are the point of this migration, not an afterthought.** The dashboard's entire
+ * interaction is "inbox, newest first, filtered by category and priority and archived" — a query
+ * workload, and one that is miserable to retrofit once a table has rows in production. So the two
+ * composite indexes the issue names are created here, in the first migration, alongside the tables.
+ *
+ * camelCase identifiers throughout; `CamelCasePlugin` snake-cases them in the DDL. `down` is the
+ * tested inverse — indexes first, then tables, children before parents.
+ *
+ * **No CHECK constraints, deliberately.** CLAUDE.md's rule is that one Zod schema per table is the
+ * entire table definition, and a CHECK mirroring a `z.enum` or a `SQLiteBoolean` is a second, partial
+ * copy of that definition — one that can drift from the schema and that SQLite cannot alter, so
+ * adding a priority level or a sentiment would mean a table rebuild rather than a one-line edit to
+ * the enum. Every value here reaches SQLite through `Schema.encode`, so the schema already refuses
+ * what a CHECK would have. The three bounds that were doing real work — both `confidence` ranges and
+ * the attachment `size` floor — moved into the schemas, which is where they belonged.
+ *
+ * A CHECK still earns its place for an invariant Zod genuinely cannot express: `@pithy-sh/ledger`
+ * constrains `held <= balance` across columns, which no per-field schema can state.
+ */
+export const support_0001_threads: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithySupportThreads")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("channel", "text", (c) => c.notNull().defaultTo("email"))
+      // Nullable, unlike every other address on this table: an `app` thread in a project with no
+      // inbound address configured never arrived anywhere, and collecting in-app feedback with no mail
+      // set up at all is a deployment this capability supports.
+      .addColumn("inboxAddress", "text")
+      .addColumn("subject", "text", (c) => c.notNull())
+      .addColumn("fromAddress", "text", (c) => c.notNull())
+      .addColumn("fromName", "text")
+      .addColumn("senderAuthenticated", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("userId", "text")
+      .addColumn("accountLinkSource", "text")
+      // Nullable and with no default, unlike `category` beside it, because "nobody said" is a real and
+      // common state — every mail thread, and every app thread whose client offered no chooser — and
+      // `uncategorized` here would be indistinguishable from a submitter who chose it deliberately.
+      .addColumn("declaredCategory", "text")
+      .addColumn("category", "text", (c) => c.notNull().defaultTo("uncategorized"))
+      .addColumn("priority", "text", (c) => c.notNull().defaultTo("normal"))
+      .addColumn("sentiment", "text", (c) => c.notNull().defaultTo("neutral"))
+      .addColumn("confidence", "real")
+      .addColumn("model", "text")
+      .addColumn("classifiedAt", "integer")
+      .addColumn("archived", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("archivedAt", "integer")
+      .addColumn("archivedBy", "text")
+      .addColumn("messageCount", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("firstMessageAt", "integer", (c) => c.notNull())
+      .addColumn("lastMessageAt", "integer", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .execute();
+
+    // The inbox itself: open threads, newest first. `id` rides along as the pagination tiebreak, so
+    // the cursor read is covered by the index rather than sorting rows it had to fetch first.
+    await db.schema
+      .createIndex("pithySupportThreadsArchivedIdx")
+      .on("pithySupportThreads")
+      .columns(["archived", "lastMessageAt", "id"])
+      .execute();
+    // The filtered inbox. Category is the filter people actually use, and it is the one the issue
+    // names, so it gets its own composite rather than relying on the archived index plus a scan.
+    await db.schema
+      .createIndex("pithySupportThreadsCategoryIdx")
+      .on("pithySupportThreads")
+      .columns(["category", "lastMessageAt", "id"])
+      .execute();
+    // The other filtered inbox: threads by what the *submitter* said they were about. It carries the
+    // same `(lastMessageAt, id)` tail as the category composite because it serves the same query in
+    // the same order, and it is a second index rather than a second use of the first — an operator
+    // triaging a project with `ai.enabled: false` filters on this one exclusively, since nothing ever
+    // writes `category` there.
+    await db.schema
+      .createIndex("pithySupportThreadsDeclaredCategoryIdx")
+      .on("pithySupportThreads")
+      .columns(["declaredCategory", "lastMessageAt", "id"])
+      .execute();
+    // The sender's history — what the volume guard counts and what a thread view shows beside the
+    // current conversation.
+    await db.schema
+      .createIndex("pithySupportThreadsFromIdx")
+      .on("pithySupportThreads")
+      .columns(["fromAddress", "lastMessageAt"])
+      .execute();
+    // "Everything from this customer", once the sender has been linked to an account.
+    await db.schema.createIndex("pithySupportThreadsUserIdx").on("pithySupportThreads").column("userId").execute();
+    // The console's channel filter, and the submitter's own list. Both read one channel newest-first,
+    // so this carries the same `(lastMessageAt, id)` tail as the archived and category composites —
+    // an index on `channel` alone would filter and then sort rows it had to fetch first.
+    await db.schema
+      .createIndex("pithySupportThreadsChannelIdx")
+      .on("pithySupportThreads")
+      .columns(["channel", "lastMessageAt", "id"])
+      .execute();
+    // The read-back: this account's own app threads, newest first. Keyed on the pair rather than on
+    // `userId` alone because the read-back is scoped to both — an email thread linked to an account by
+    // an unproven header must never be readable by whoever currently holds that address.
+    await db.schema
+      .createIndex("pithySupportThreadsUserChannelIdx")
+      .on("pithySupportThreads")
+      .columns(["userId", "channel", "lastMessageAt", "id"])
+      .execute();
+
+    await db.schema
+      .createTable("pithySupportMessages")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("threadId", "text", (c) => c.notNull())
+      .addColumn("direction", "text", (c) => c.notNull())
+      .addColumn("channel", "text", (c) => c.notNull().defaultTo("email"))
+      .addColumn("submittedByUserId", "text")
+      .addColumn("context", "text")
+      .addColumn("mimeMessageId", "text")
+      .addColumn("mimeInReplyTo", "text")
+      .addColumn("mimeReferences", "text")
+      // Nullable, unlike the thread's: an answer delivered in the app left no envelope, so there is
+      // no address it came from. It stays in the volume-guard index below, which counts inbound mail
+      // and so never meets a null.
+      .addColumn("fromAddress", "text")
+      .addColumn("fromName", "text")
+      // Nullable for the same reason `pithy_support_threads.inbox_address` is: an app submission has
+      // no envelope recipient. It stays in the unique index below — SQLite treats two NULLs as
+      // distinct, so app rows never collide there.
+      .addColumn("toAddress", "text")
+      .addColumn("subject", "text", (c) => c.notNull())
+      .addColumn("textBody", "text", (c) => c.notNull())
+      .addColumn("htmlBody", "text")
+      .addColumn("emailJobId", "text")
+      .addColumn("rawKey", "text")
+      .addColumn("rawBytes", "integer")
+      .addColumn("receivedAt", "integer", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .execute();
+
+    // The idempotency anchor. Email Routing can deliver the same message twice, and the second
+    // delivery has to be a no-op rather than a duplicate in somebody's inbox. SQLite permits repeated
+    // NULLs in a unique index, so a message with no `Message-ID` still stores.
+    //
+    // Keyed on `(mimeMessageId, toAddress)` rather than the id alone, matching the ingest lookup. A
+    // Worker may serve several inboxes, and a customer who addresses one message to both `support@`
+    // and `security@` causes two legitimate deliveries of the same `Message-ID` — a global key would
+    // reject the second, so the message would land in one inbox and silently never reach the other.
+    await db.schema
+      .createIndex("pithySupportMessagesMimeIdIdx")
+      .on("pithySupportMessages")
+      .columns(["mimeMessageId", "toAddress"])
+      .unique()
+      .execute();
+    // The thread view, in order.
+    await db.schema
+      .createIndex("pithySupportMessagesThreadIdx")
+      .on("pithySupportMessages")
+      .columns(["threadId", "receivedAt"])
+      .execute();
+    // Threading's fallback lookup: find the message an `In-Reply-To` or a `References` entry names.
+    await db.schema
+      .createIndex("pithySupportMessagesInReplyToIdx")
+      .on("pithySupportMessages")
+      .column("mimeInReplyTo")
+      .execute();
+    // What the volume guard counts: messages from one address inside a window.
+    await db.schema
+      .createIndex("pithySupportMessagesFromIdx")
+      .on("pithySupportMessages")
+      .columns(["fromAddress", "receivedAt"])
+      .execute();
+    // What the *submission* guard counts: one account's app submissions inside a window. The app
+    // channel's bound is per account rather than per address, because the account is what a session
+    // proves and what an adopter can revoke — so it needs its own index rather than the address one.
+    await db.schema
+      .createIndex("pithySupportMessagesSubmitterIdx")
+      .on("pithySupportMessages")
+      .columns(["submittedByUserId", "receivedAt"])
+      .execute();
+    // The mail guard counts only mail. Both rate bounds filter on `channel` so that neither surface
+    // can starve the other — heavy in-app feedback must never lock a real customer out of the inbox,
+    // and a mail flood must never stop the app's own users reporting the outage.
+    await db.schema
+      .createIndex("pithySupportMessagesChannelIdx")
+      .on("pithySupportMessages")
+      .columns(["channel", "direction", "receivedAt"])
+      .execute();
+
+    await db.schema
+      .createTable("pithySupportAttachments")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("messageId", "text", (c) => c.notNull())
+      .addColumn("threadId", "text", (c) => c.notNull())
+      .addColumn("filename", "text", (c) => c.notNull())
+      .addColumn("contentType", "text", (c) => c.notNull())
+      .addColumn("size", "integer", (c) => c.notNull())
+      .addColumn("sha256", "text", (c) => c.notNull())
+      .addColumn("storageKey", "text", (c) => c.notNull())
+      .addColumn("contentId", "text")
+      .addColumn("inline", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .execute();
+
+    await db.schema
+      .createIndex("pithySupportAttachmentsMessageIdx")
+      .on("pithySupportAttachments")
+      .column("messageId")
+      .execute();
+    await db.schema
+      .createIndex("pithySupportAttachmentsThreadIdx")
+      .on("pithySupportAttachments")
+      .column("threadId")
+      .execute();
+
+    await db.schema
+      .createTable("pithySupportClassifications")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("threadId", "text", (c) => c.notNull())
+      .addColumn("messageId", "text", (c) => c.notNull())
+      .addColumn("category", "text", (c) => c.notNull())
+      .addColumn("priority", "text", (c) => c.notNull())
+      .addColumn("sentiment", "text", (c) => c.notNull())
+      .addColumn("confidence", "real", (c) => c.notNull())
+      .addColumn("model", "text", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .execute();
+
+    await db.schema
+      .createIndex("pithySupportClassificationsThreadIdx")
+      .on("pithySupportClassifications")
+      .columns(["threadId", "createdAt"])
+      .execute();
+    // "Which rows came from which model" — the query a reclassification pass after a model upgrade
+    // is planned from, and the reason the column exists at all.
+    await db.schema
+      .createIndex("pithySupportClassificationsModelIdx")
+      .on("pithySupportClassifications")
+      .columns(["model", "createdAt"])
+      .execute();
+
+    await db.schema
+      .createTable("pithySupportThreadFlags")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("threadId", "text", (c) => c.notNull())
+      .addColumn("viewer", "text", (c) => c.notNull())
+      .addColumn("read", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("snoozedUntil", "integer")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .execute();
+
+    // One row per viewer per thread, so marking read twice is an upsert rather than a second row.
+    await db.schema
+      .createIndex("pithySupportThreadFlagsViewerIdx")
+      .on("pithySupportThreadFlags")
+      .columns(["threadId", "viewer"])
+      .unique()
+      .execute();
+  },
+
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropIndex("pithySupportThreadFlagsViewerIdx").execute();
+    await db.schema.dropTable("pithySupportThreadFlags").execute();
+
+    await db.schema.dropIndex("pithySupportClassificationsModelIdx").execute();
+    await db.schema.dropIndex("pithySupportClassificationsThreadIdx").execute();
+    await db.schema.dropTable("pithySupportClassifications").execute();
+
+    await db.schema.dropIndex("pithySupportAttachmentsThreadIdx").execute();
+    await db.schema.dropIndex("pithySupportAttachmentsMessageIdx").execute();
+    await db.schema.dropTable("pithySupportAttachments").execute();
+
+    await db.schema.dropIndex("pithySupportMessagesChannelIdx").execute();
+    await db.schema.dropIndex("pithySupportMessagesSubmitterIdx").execute();
+    await db.schema.dropIndex("pithySupportMessagesFromIdx").execute();
+    await db.schema.dropIndex("pithySupportMessagesInReplyToIdx").execute();
+    await db.schema.dropIndex("pithySupportMessagesThreadIdx").execute();
+    await db.schema.dropIndex("pithySupportMessagesMimeIdIdx").execute();
+    await db.schema.dropTable("pithySupportMessages").execute();
+
+    await db.schema.dropIndex("pithySupportThreadsUserChannelIdx").execute();
+    await db.schema.dropIndex("pithySupportThreadsChannelIdx").execute();
+    await db.schema.dropIndex("pithySupportThreadsUserIdx").execute();
+    await db.schema.dropIndex("pithySupportThreadsFromIdx").execute();
+    await db.schema.dropIndex("pithySupportThreadsDeclaredCategoryIdx").execute();
+    await db.schema.dropIndex("pithySupportThreadsCategoryIdx").execute();
+    await db.schema.dropIndex("pithySupportThreadsArchivedIdx").execute();
+    await db.schema.dropTable("pithySupportThreads").execute();
+  },
+};

package/src/mime/address.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * What a MIME header contributes that an address rule does not.
+ *
+ * Addresses themselves are `@pithy-sh/core/src/address/address` — `parseAddress` reads one out of a
+ * header and `normalizeAddress` puts it in the form every comparison in the kit is against. This
+ * capability used to own that rule; it does not any more, because `auth`, `email` and `testers`
+ * compare addresses too, and four rules is four chances to disagree about whether two strings are the
+ * same person. That disagreement presents as one customer with two threads, not as anything about
+ * addresses.
+ *
+ * What is left here is the display name, which is this capability alone: nobody else stores one, and it
+ * is the half of a `From` header that is free text an attacker wrote.
+ */
+
+/**
+ * A display name, made safe to store.
+ *
+ * Trimmed, bounded, and stripped of control characters — including the bidirectional overrides that
+ * let `moc.elpmaxe@ada` render as something else entirely. The result is still untrusted text that a
+ * renderer must escape; this only guarantees it is text.
+ */
+export function normalizeDisplayName(value: string | null | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const cleaned = value
+    // C0/C1 controls, plus the LTR/RTL overrides and embeddings (U+202A–U+202E, U+2066–U+2069).
+    // biome-ignore-start lint/suspicious/noControlCharactersInRegex: stripping control
+    // characters is the entire purpose — a bidi override renders a filename or a display name as
+    // something other than what it is, which is the oldest trick in inbound mail.
+    .replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, "")
+    // biome-ignore-end lint/suspicious/noControlCharactersInRegex: see above
+    .trim()
+    .slice(0, 200);
+  return cleaned.length > 0 ? cleaned : undefined;
+}