@remit/drizzle-service 0.0.30 → 0.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/drizzle-service",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "description": "Drizzle ORM service parameterized by dialect (Postgres / SQLite)",
   "type": "module",
   "main": "src/index.ts",

package/src/repair/thread-message-category-contract.ts

@@ -0,0 +1,507 @@
+/**
+ * The behaviour `thread_message.category`'s repair (#321) must have, asserted
+ * against a real engine of each dialect from one place: the statement ships in
+ * two dialects and an assertion that only ran on one of them is how a dialect
+ * quietly stops being repaired.
+ *
+ * Every seed is raw SQL against the real column names, so it exercises the same
+ * statement text the migrator runs rather than a drizzle re-spelling of it.
+ */
+import assert from "node:assert/strict";
+import { after, before, beforeEach, describe, test } from "node:test";
+import {
+	type CategoryDivergenceReport,
+	checkThreadMessageCategory,
+	formatCheckReport,
+	formatRepairResult,
+	formatRepairSkipped,
+	type RepairSqlClient,
+	readResidual,
+	repairThreadMessageCategory,
+} from "./thread-message-category.js";
+
+export type RepairHarness = {
+	readonly client: RepairSqlClient;
+	readonly reset: () => Promise<void>;
+	readonly close: () => Promise<void>;
+};
+
+const literal = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+
+type MessageSeed = {
+	readonly messageId: string;
+	readonly category: string;
+};
+
+type ThreadMessageSeed = {
+	readonly threadMessageId: string;
+	readonly messageId: string;
+	readonly category: string;
+	readonly mailboxId?: string;
+	readonly updatedAt?: number;
+};
+
+const insertMessage = ({ messageId, category }: MessageSeed): string =>
+	`INSERT INTO message (
+		message_id, mailbox_id, uid, sequence_number, rfc822_size, internal_date,
+		envelope_id, root_body_part_id, category, created_at, updated_at
+	) VALUES (
+		${literal(messageId)}, 'mbx-inbox', 1, 1, 100, 0,
+		'env-1', 'part-1', ${literal(category)}, 0, 0
+	)`;
+
+const insertThreadMessage = ({
+	threadMessageId,
+	messageId,
+	category,
+	mailboxId = "mbx-inbox",
+	updatedAt = 1000,
+}: ThreadMessageSeed): string =>
+	`INSERT INTO thread_message (
+		thread_message_id, thread_id, message_id, account_config_id, mailbox_id, uid,
+		reference_order, internal_date, sent_date, is_read, has_attachment, has_stars,
+		is_deleted, category, created_at, updated_at
+	) VALUES (
+		${literal(threadMessageId)}, 'thr-1', ${literal(messageId)}, 'acct-1',
+		${literal(mailboxId)}, 1, 0, 0, 0, false, false, false, false,
+		${literal(category)}, 0, ${updatedAt}
+	)`;
+
+type ThreadMessageRow = {
+	readonly threadMessageId: string;
+	readonly category: string;
+	readonly updatedAt: number;
+};
+
+const readRows = async (
+	client: RepairSqlClient,
+): Promise<ThreadMessageRow[]> => {
+	const rows = await client.all(
+		"SELECT thread_message_id, category, updated_at FROM thread_message ORDER BY thread_message_id",
+	);
+	return rows.map((row) => {
+		if (typeof row !== "object" || row === null) {
+			throw new Error("expected a row object");
+		}
+		const record: Record<string, unknown> = { ...row };
+		return {
+			threadMessageId: String(record.thread_message_id),
+			category: String(record.category),
+			updatedAt: Number(record.updated_at),
+		};
+	});
+};
+
+const categoryOf = (
+	rows: readonly ThreadMessageRow[],
+	threadMessageId: string,
+): string => {
+	const row = rows.find((entry) => entry.threadMessageId === threadMessageId);
+	if (!row) {
+		throw new Error(`no thread_message row ${threadMessageId}`);
+	}
+	return row.category;
+};
+
+export const describeRepairContract = (
+	label: string,
+	open: () => Promise<RepairHarness>,
+): void => {
+	describe(`thread_message.category repair — ${label}`, () => {
+		let harness: RepairHarness;
+
+		before(async () => {
+			harness = await open();
+		});
+
+		after(async () => {
+			await harness.close();
+		});
+
+		beforeEach(async () => {
+			await harness.reset();
+		});
+
+		const seed = async (
+			messages: readonly MessageSeed[],
+			threadMessages: readonly ThreadMessageSeed[],
+		): Promise<void> => {
+			for (const message of messages) {
+				await harness.client.run(insertMessage(message));
+			}
+			for (const threadMessage of threadMessages) {
+				await harness.client.run(insertThreadMessage(threadMessage));
+			}
+		};
+
+		const check = (): Promise<CategoryDivergenceReport> =>
+			checkThreadMessageCategory(harness.client);
+
+		test("repairs a stale row and does not touch a matching one", async () => {
+			await seed(
+				[
+					{ messageId: "msg-stale", category: "newsletter" },
+					{ messageId: "msg-agrees", category: "social" },
+				],
+				[
+					{
+						threadMessageId: "tm-stale",
+						messageId: "msg-stale",
+						category: "uncategorized",
+					},
+					{
+						threadMessageId: "tm-agrees",
+						messageId: "msg-agrees",
+						category: "social",
+						updatedAt: 4242,
+					},
+				],
+			);
+
+			const before = await check();
+			assert.equal(before.rows, 2);
+			assert.equal(before.divergent, 1);
+			assert.equal(before.repairable, 1);
+			assert.equal(before.behind, 1);
+			assert.equal(before.crossed, 0);
+
+			const result = await repairThreadMessageCategory(harness.client);
+			assert.equal(result.rowsWritten, 1);
+
+			const rows = await readRows(harness.client);
+			assert.equal(categoryOf(rows, "tm-stale"), "newsletter");
+			assert.equal(categoryOf(rows, "tm-agrees"), "social");
+
+			const untouched = rows.find(
+				(row) => row.threadMessageId === "tm-agrees",
+			)?.updatedAt;
+			assert.equal(untouched, 4242);
+
+			const after = await check();
+			assert.equal(after.divergent, 0);
+			assert.equal(after.repairable, 0);
+		});
+
+		test("repairs a row classified differently from its message", async () => {
+			await seed(
+				[{ messageId: "msg-crossed", category: "marketing" }],
+				[
+					{
+						threadMessageId: "tm-crossed",
+						messageId: "msg-crossed",
+						category: "personal",
+					},
+				],
+			);
+
+			const before = await check();
+			assert.equal(before.crossed, 1);
+			assert.equal(before.behind, 0);
+			assert.equal(before.repairable, 1);
+
+			await repairThreadMessageCategory(harness.client);
+			const rows = await readRows(harness.client);
+			assert.equal(categoryOf(rows, "tm-crossed"), "marketing");
+		});
+
+		test("leaves a row pending when its message is pending", async () => {
+			await seed(
+				[{ messageId: "msg-pending", category: "uncategorized" }],
+				[
+					{
+						threadMessageId: "tm-pending",
+						messageId: "msg-pending",
+						category: "uncategorized",
+					},
+				],
+			);
+
+			const before = await check();
+			assert.equal(before.notYetClassified, 1);
+			assert.equal(before.divergent, 0);
+
+			const result = await repairThreadMessageCategory(harness.client);
+			assert.equal(result.rowsWritten, 0);
+
+			const rows = await readRows(harness.client);
+			assert.equal(categoryOf(rows, "tm-pending"), "uncategorized");
+			assert.equal((await check()).notYetClassified, 1);
+		});
+
+		// `uncategorized` is a declared pending state, not absence (#45). After #326
+		// body-sync writes the row before the message, so a row classified against a
+		// pending message is a classification in flight — pushing it back would undo
+		// a correct classification and serve Unclassified for classified mail. This
+		// is #326's closing question, answered: the row is left alone, not converged.
+		test("never copies pending over a classified row", async () => {
+			await seed(
+				[{ messageId: "msg-ahead", category: "uncategorized" }],
+				[
+					{
+						threadMessageId: "tm-ahead",
+						messageId: "msg-ahead",
+						category: "personal",
+					},
+				],
+			);
+
+			const before = await check();
+			assert.equal(before.divergent, 1);
+			assert.equal(before.ahead, 1);
+			assert.equal(before.repairable, 0);
+
+			const result = await repairThreadMessageCategory(harness.client);
+			assert.equal(result.rowsWritten, 0);
+
+			const rows = await readRows(harness.client);
+			assert.equal(categoryOf(rows, "tm-ahead"), "personal");
+			assert.match(
+				formatCheckReport(await check()).join("\n"),
+				/ahead: 1 row .*Expected non-zero on a live instance mid-sync/,
+			);
+		});
+
+		test("leaves a row with no message row alone and counts it", async () => {
+			await seed(
+				[],
+				[
+					{
+						threadMessageId: "tm-orphan",
+						messageId: "msg-absent",
+						category: "personal",
+					},
+				],
+			);
+
+			const before = await check();
+			assert.equal(before.rows, 1);
+			assert.equal(before.rowsWithMessage, 0);
+			assert.equal(before.orphanRows, 1);
+
+			const result = await repairThreadMessageCategory(harness.client);
+			assert.equal(result.rowsWritten, 0);
+			assert.equal(
+				categoryOf(await readRows(harness.client), "tm-orphan"),
+				"personal",
+			);
+		});
+
+		test("repairs every row of a message held in two mailboxes", async () => {
+			await seed(
+				[{ messageId: "msg-fanned", category: "transactional" }],
+				[
+					{
+						threadMessageId: "tm-inbox",
+						messageId: "msg-fanned",
+						category: "uncategorized",
+					},
+					{
+						threadMessageId: "tm-archive",
+						messageId: "msg-fanned",
+						mailboxId: "mbx-archive",
+						category: "uncategorized",
+					},
+				],
+			);
+
+			const before = await check();
+			assert.equal(before.fanOutMessages, 1);
+			assert.equal(before.fanOutRows, 2);
+			assert.deepEqual(before.divergentByMailbox, [
+				{ mailboxId: "mbx-archive", rows: 1 },
+				{ mailboxId: "mbx-inbox", rows: 1 },
+			]);
+
+			const result = await repairThreadMessageCategory(harness.client);
+			assert.equal(result.rowsWritten, 2);
+
+			const rows = await readRows(harness.client);
+			assert.equal(categoryOf(rows, "tm-inbox"), "transactional");
+			assert.equal(categoryOf(rows, "tm-archive"), "transactional");
+			assert.equal((await check()).divergent, 0);
+		});
+
+		test("is a no-op on the second run", async () => {
+			await seed(
+				[{ messageId: "msg-twice", category: "automated" }],
+				[
+					{
+						threadMessageId: "tm-twice",
+						messageId: "msg-twice",
+						category: "uncategorized",
+					},
+				],
+			);
+
+			assert.equal(
+				(await repairThreadMessageCategory(harness.client)).rowsWritten,
+				1,
+			);
+			const afterFirst = await readRows(harness.client);
+			assert.equal(
+				(await repairThreadMessageCategory(harness.client)).rowsWritten,
+				0,
+			);
+			assert.deepEqual(await readRows(harness.client), afterFirst);
+		});
+
+		// The guard's mechanics: a row whose stamp is beyond the statement's clock
+		// fails the WHERE clause and is left alone. A row stamped that far ahead is
+		// not a concurrent writer — it is a clock that jumped or a restored backup —
+		// and the residual has to say so, because that row fails the guard on every
+		// run and no later start will fix it.
+		test("skips a row stamped beyond the statement's clock and says why", async () => {
+			await seed(
+				[
+					{ messageId: "msg-ahead-clock", category: "newsletter" },
+					{ messageId: "msg-quiet", category: "newsletter" },
+				],
+				[
+					{
+						threadMessageId: "tm-ahead-clock",
+						messageId: "msg-ahead-clock",
+						category: "uncategorized",
+						updatedAt: Date.now() + 600_000,
+					},
+					{
+						threadMessageId: "tm-quiet",
+						messageId: "msg-quiet",
+						category: "uncategorized",
+					},
+				],
+			);
+
+			const result = await repairThreadMessageCategory(harness.client);
+			assert.equal(result.rowsWritten, 1);
+
+			const rows = await readRows(harness.client);
+			assert.equal(categoryOf(rows, "tm-ahead-clock"), "uncategorized");
+			assert.equal(categoryOf(rows, "tm-quiet"), "newsletter");
+
+			const residual = await readResidual(harness.client);
+			assert.deepEqual(residual, { repairable: 1, aheadOfClock: 1 });
+
+			const reported = formatRepairResult(result, residual).join("\n");
+			assert.match(reported, /ahead of the database clock/);
+			assert.match(reported, /every run, not just this one/);
+			assert.ok(
+				!reported.includes("skipped because a writer touched them"),
+				"a clock-ahead row must not be reported as a concurrent writer",
+			);
+		});
+
+		test("names the concurrent writer and the update cadence when a run leaves a residual", () => {
+			const reported = formatRepairResult(
+				{ rowsWritten: 4, elapsedMs: 7 },
+				{ repairable: 2, aheadOfClock: 0 },
+			).join("\n");
+			assert.match(reported, /2 rows skipped because a writer touched them/);
+			assert.match(reported, /the next 'remit update'/);
+			assert.ok(!reported.includes("ahead of the database clock"));
+		});
+
+		test("a clean run reports no warning at all", () => {
+			assert.deepEqual(
+				formatRepairResult(
+					{ rowsWritten: 3, elapsedMs: 2 },
+					{ repairable: 0, aheadOfClock: 0 },
+				),
+				[
+					"repair wrote 3 rows in 2ms",
+					"residual repairable divergence: 0 (expected zero)",
+				],
+			);
+		});
+
+		test("a skipped repair says no write lock was taken", async () => {
+			await seed(
+				[{ messageId: "msg-clean", category: "personal" }],
+				[
+					{
+						threadMessageId: "tm-clean",
+						messageId: "msg-clean",
+						category: "personal",
+					},
+				],
+			);
+
+			const report = await check();
+			assert.equal(report.repairable, 0);
+			assert.match(
+				formatRepairSkipped(report).join("\n"),
+				/repair skipped: nothing repairable .*No write, so no write lock is taken\./,
+			);
+		});
+
+		test("--check writes nothing", async () => {
+			await seed(
+				[{ messageId: "msg-readonly", category: "personal" }],
+				[
+					{
+						threadMessageId: "tm-readonly",
+						messageId: "msg-readonly",
+						category: "uncategorized",
+						updatedAt: 7777,
+					},
+				],
+			);
+
+			const rowsBefore = await readRows(harness.client);
+			await check();
+			assert.deepEqual(await readRows(harness.client), rowsBefore);
+		});
+
+		test("the report names a cause and its expected result for every figure", async () => {
+			await seed(
+				[{ messageId: "msg-report", category: "social" }],
+				[
+					{
+						threadMessageId: "tm-report",
+						messageId: "msg-report",
+						category: "uncategorized",
+					},
+				],
+			);
+
+			const lines = formatCheckReport(await check());
+			const text = lines.join("\n");
+
+			for (const cause of [
+				"behind:",
+				"crossed:",
+				"ahead:",
+				"fan-out:",
+				"orphans:",
+				"not-yet-classified:",
+				"divergent per mailbox:",
+				"category tally:",
+			]) {
+				assert.ok(text.includes(cause), `missing cause: ${cause}`);
+			}
+			assert.equal(
+				lines.filter((line) => /Expected (zero|non-zero)/.test(line)).length,
+				6,
+			);
+			assert.match(text, /category tally: uncategorized=1/);
+		});
+
+		// The causes are the deliverable, so each one names something that can
+		// actually happen on the deployment this repair ships to. A cause an
+		// operator can rule out by inspection reads as a broken figure.
+		test("no figure cites a cause that cannot occur on this deployment", async () => {
+			const text = formatCheckReport(await check()).join("\n");
+			for (const stale of [
+				"2026-07-08",
+				"drizzle push",
+				"Postgres instance whose column was added",
+			]) {
+				assert.ok(
+					!text.includes(stale),
+					`the report still cites ${stale}, which no SQLite instance can have experienced`,
+				);
+			}
+			assert.match(text, /behind: .*write-path defects #326 fixes end here/);
+			assert.match(text, /crossed: .*no write path leaves a row here/);
+		});
+	});
+};

package/src/repair/thread-message-category.sqlite.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, before, describe, test } from "node:test";
+import Database from "better-sqlite3";
+import { messageTable } from "../schema/message-data.js";
+import { threadMessageTable } from "../schema/thread-message.js";
+import { createSqliteTestDb } from "../test-db-sqlite.js";
+import {
+	checkThreadMessageCategory,
+	type RepairSqlClient,
+	repairStatement,
+} from "./thread-message-category.js";
+import { describeRepairContract } from "./thread-message-category-contract.js";
+
+const sqliteClient = (sqlite: Database.Database): RepairSqlClient => ({
+	dialect: "sqlite",
+	all: async (sql) => sqlite.prepare(sql).all(),
+	run: async (sql) => sqlite.prepare(sql).run().changes,
+});
+
+// The repair against a real better-sqlite3 database — the engine every self-host
+// instance runs, and the one whose `unixepoch()` and single-writer serialization
+// the statement leans on.
+describeRepairContract("sqlite", async () => {
+	const { sqlite, close } = await createSqliteTestDb({
+		message: messageTable,
+		threadMessage: threadMessageTable,
+	});
+
+	return {
+		client: sqliteClient(sqlite),
+		reset: async () => {
+			sqlite.exec("DELETE FROM thread_message");
+			sqlite.exec("DELETE FROM message");
+		},
+		close,
+	};
+});
+
+// Why the repair is skipped when the check found nothing: SQLite takes its
+// exclusive write lock when the UPDATE begins, before it can know the WHERE
+// matches nothing. Without the skip, every boot of a healthy instance would
+// contend for that lock, and a contended boot fails the whole migration — which
+// holds all six gated services down.
+describe("thread_message.category repair — SQLite's write lock", () => {
+	let dir: string;
+	let file: string;
+	let reader: Database.Database;
+	let writer: Database.Database;
+
+	before(async () => {
+		dir = mkdtempSync(join(tmpdir(), "remit-repair-lock-"));
+		file = join(dir, "remit.db");
+		const { sqlite, close } = await createSqliteTestDb(
+			{ message: messageTable, threadMessage: threadMessageTable },
+			{ filename: file },
+		);
+		sqlite.pragma("journal_mode = WAL");
+		await close();
+
+		// 200 ms rather than the migrator's busy_timeout of 5000: the point is that
+		// the lock is wanted at all, and waiting five seconds to prove it is waste.
+		reader = new Database(file, { timeout: 200 });
+		reader.pragma("journal_mode = WAL");
+		writer = new Database(file);
+	});
+
+	after(() => {
+		reader.close();
+		writer.close();
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	test("the check reads while another connection holds the write lock", async () => {
+		writer.exec("BEGIN IMMEDIATE");
+		try {
+			const report = await checkThreadMessageCategory(sqliteClient(reader));
+			assert.equal(report.rows, 0);
+			assert.equal(report.repairable, 0);
+		} finally {
+			writer.exec("ROLLBACK");
+		}
+	});
+
+	test("the statement still wants the lock with nothing to repair", async () => {
+		writer.exec("BEGIN IMMEDIATE");
+		try {
+			assert.throws(
+				() => reader.prepare(repairStatement("sqlite")).run(),
+				(error: unknown) =>
+					error instanceof Error &&
+					"code" in error &&
+					error.code === "SQLITE_BUSY",
+			);
+		} finally {
+			writer.exec("ROLLBACK");
+		}
+	});
+});

package/src/repair/thread-message-category.test.ts

@@ -0,0 +1,229 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { createTestDb } from "../test-db.js";
+import {
+	type RepairSqlClient,
+	repairStatement,
+	repairThreadMessageCategory,
+} from "./thread-message-category.js";
+import { describeRepairContract } from "./thread-message-category-contract.js";
+
+const { pool, close } = await createTestDb();
+
+after(async () => {
+	await close();
+});
+
+const client: RepairSqlClient = {
+	dialect: "postgres",
+	all: async (sql) => (await pool.query(sql)).rows,
+	run: async (sql) => (await pool.query(sql)).rowCount ?? 0,
+};
+
+const truncate = async (): Promise<void> => {
+	await pool.query("DELETE FROM thread_message");
+	await pool.query("DELETE FROM message");
+};
+
+describeRepairContract("postgres", async () => ({
+	client,
+	reset: truncate,
+	close: async () => undefined,
+}));
+
+// Postgres is where a mid-sync run can go wrong, and the two interleavings have
+// opposite outcomes — so each is driven with two real connections rather than
+// argued about. Under READ COMMITTED an UPDATE that meets a row a concurrent
+// transaction just changed re-evaluates its WHERE clause against the new version
+// of that row, but keeps reading other tables at its original snapshot.
+//
+// Both cases need a *re*-classification to be observable at all: `message` moving
+// from one decided category to another. `backfillClassification` cannot do that
+// (it returns early once the category is decided), but the primary path is
+// re-enterable — `if (message.bodyStorageKey && !force)`, where `force` is the
+// read-miss re-arm cue — and a forced re-fetch decides differently across a
+// release that changed the classifier. So the uncovered case below is
+// effectively unreachable rather than impossible. The seeds are synthetic
+// because reproducing it otherwise would mean changing the classifier.
+describe("thread_message.category repair — a writer racing the statement", () => {
+	const insertMessage = async (
+		messageId: string,
+		category: string,
+	): Promise<void> => {
+		await pool.query(
+			`INSERT INTO message (
+				message_id, mailbox_id, uid, sequence_number, rfc822_size, internal_date,
+				envelope_id, root_body_part_id, category, created_at, updated_at
+			) VALUES ($1, 'mbx-inbox', 1, 1, 100, 0, 'env-1', 'part-1', $2, 0, 0)`,
+			[messageId, category],
+		);
+	};
+
+	const insertRow = async (
+		messageId: string,
+		category: string,
+	): Promise<void> => {
+		await pool.query(
+			`INSERT INTO thread_message (
+				thread_message_id, thread_id, message_id, account_config_id, mailbox_id,
+				uid, reference_order, internal_date, sent_date, is_read, has_attachment,
+				has_stars, is_deleted, category, created_at, updated_at
+			) VALUES ($1, 'thr-1', $1, 'acct-1', 'mbx-inbox', 1, 0, 0, 0,
+				false, false, false, false, $2, 0, 1000)`,
+			[messageId, category],
+		);
+	};
+
+	// A body-sync denormalize, faithful to the shipped order (#326): the row
+	// first, the message second, both stamped with the wall clock at write time.
+	const reclassify = async (
+		connection: {
+			query: (sql: string, values?: unknown[]) => Promise<unknown>;
+		},
+		messageId: string,
+		category: string,
+	): Promise<void> => {
+		await connection.query(
+			"UPDATE thread_message SET category = $2, updated_at = $3 WHERE thread_message_id = $1",
+			[messageId, category, Date.now()],
+		);
+		await connection.query(
+			"UPDATE message SET category = $2, updated_at = $3 WHERE message_id = $1",
+			[messageId, category, Date.now()],
+		);
+	};
+
+	const categories = async (): Promise<Record<string, string>> => {
+		const { rows } = await pool.query<{
+			thread_message_id: string;
+			category: string;
+		}>("SELECT thread_message_id, category FROM thread_message");
+		return Object.fromEntries(
+			rows.map((row) => [row.thread_message_id, row.category]),
+		);
+	};
+
+	before(truncate);
+
+	// The case the guard covers: the writer's transaction begins after the
+	// statement, so its stamp is beyond the statement's clock and the re-check
+	// against the committed row excludes it. The repair is held on an unrelated
+	// row lock for the duration, which is what puts the writer inside the
+	// statement's window without touching its stamp.
+	test("a writer that begins after the statement keeps its value", async () => {
+		await truncate();
+		await insertMessage("aaa-blocker", "newsletter");
+		await insertRow("aaa-blocker", "uncategorized");
+		await insertMessage("bbb-raced", "newsletter");
+		await insertRow("bbb-raced", "uncategorized");
+
+		const holder = await pool.connect();
+		const writer = await pool.connect();
+		try {
+			await holder.query("BEGIN");
+			await holder.query(
+				"UPDATE thread_message SET updated_at = 1001 WHERE thread_message_id = 'aaa-blocker'",
+			);
+
+			const repairing = repairThreadMessageCategory(client);
+			// The repair reaches the blocker row — inserted first, so first in the
+			// sequential scan — and waits there. The sleep is on the holder's own
+			// connection, so nothing polls.
+			await holder.query("SELECT pg_sleep(0.5)");
+
+			await writer.query("BEGIN");
+			await reclassify(writer, "bbb-raced", "marketing");
+			await writer.query("COMMIT");
+
+			await holder.query("COMMIT");
+
+			// Only the blocker. A 2 here means the repair finished before the writer
+			// began, so the interleaving this test is named for did not happen.
+			assert.equal((await repairing).rowsWritten, 1);
+		} finally {
+			holder.release();
+			writer.release();
+		}
+
+		assert.deepEqual(await categories(), {
+			"aaa-blocker": "newsletter",
+			"bbb-raced": "marketing",
+		});
+	});
+
+	// The live mid-sync case, and it is safe: a writer whose transaction began
+	// before the statement, doing what body-sync actually does — filling in the
+	// copy of a category the message already holds. The repair blocks on the row,
+	// re-checks against the committed version, finds it now agrees, and writes
+	// nothing. This is the interleaving D16's safety argument rests on.
+	test("a concurrent denormalize of the same row leaves it correct", async () => {
+		await truncate();
+		await insertMessage("ddd-catchup", "newsletter");
+		await insertRow("ddd-catchup", "uncategorized");
+
+		const writer = await pool.connect();
+		try {
+			await writer.query("BEGIN");
+			await writer.query(
+				"UPDATE thread_message SET category = 'newsletter', updated_at = $1 WHERE thread_message_id = 'ddd-catchup'",
+				[Date.now()],
+			);
+
+			const repairing = repairThreadMessageCategory(client);
+			await writer.query("SELECT pg_sleep(0.5)");
+			await writer.query("COMMIT");
+
+			assert.equal((await repairing).rowsWritten, 0);
+		} finally {
+			writer.release();
+		}
+
+		assert.deepEqual(await categories(), { "ddd-catchup": "newsletter" });
+	});
+
+	// The known limit, pinned so it cannot silently widen. Reaching it needs four
+	// things at once: an unrepaired `behind` row, a writer whose transaction began
+	// before the statement, that writer's row write committing before the statement
+	// while its message write commits after, and that writer moving
+	// message.category from one decided value to a different one. Only a forced
+	// re-fetch across a classifier change does the fourth, which makes this
+	// effectively unreachable rather than impossible; the seed is synthetic and the
+	// assertion records the loss rather than endorsing it. If this test ever fails,
+	// the guard got stronger and D16 and the module header should say so.
+	test("a writer that began before the statement is outside the guard", async () => {
+		await truncate();
+		await insertMessage("ccc-reclass", "newsletter");
+		await insertRow("ccc-reclass", "uncategorized");
+
+		const writer = await pool.connect();
+		try {
+			await writer.query("BEGIN");
+			await reclassify(writer, "ccc-reclass", "marketing");
+
+			const repairing = repairThreadMessageCategory(client);
+			await writer.query("SELECT pg_sleep(0.5)");
+			await writer.query("COMMIT");
+
+			assert.equal((await repairing).rowsWritten, 1);
+		} finally {
+			writer.release();
+		}
+
+		assert.deepEqual(await categories(), { "ccc-reclass": "newsletter" });
+		const { rows } = await pool.query<{ category: string }>(
+			"SELECT category FROM message WHERE message_id = 'ccc-reclass'",
+		);
+		assert.deepEqual(rows, [{ category: "marketing" }]);
+	});
+
+	test("only the clock expression differs between the dialects", () => {
+		const postgres = repairStatement("postgres");
+		const sqlite = repairStatement("sqlite");
+		assert.ok(postgres.includes("EXTRACT(EPOCH FROM now())"));
+		assert.ok(sqlite.includes("unixepoch('subsec')"));
+		assert.equal(
+			postgres.replace(/CAST\(EXTRACT.*$/, ""),
+			sqlite.replace(/CAST\(unixepoch.*$/, ""),
+		);
+	});
+});

package/src/repair/thread-message-category.ts

@@ -0,0 +1,426 @@
+/**
+ * The repair for `thread_message.category` (#321, D16 and D17 of
+ * `docs/design/mail-list-server-query.md`).
+ *
+ * `thread_message.category` is a denormalized copy of `message.category`. The
+ * read path never used it, so nothing ever depended on its write path being
+ * complete, and it has drifted. #304 makes it the SQL predicate behind the
+ * inbox category filter, so it has to be correct on every existing instance
+ * before that read path goes live — otherwise the filter under-returns mail
+ * with nothing masking it.
+ *
+ * One set-based statement per dialect. The value it copies is reachable through
+ * `message`'s primary key, so the write is single-valued by construction and
+ * there is no checkpointing, batching or resumability here: an interrupted run
+ * leaves a consistent table and the next start finishes the job.
+ *
+ * The statement runs only when the check found something to repair. SQLite takes
+ * its exclusive write lock when an UPDATE begins, before it can know the WHERE
+ * matches nothing, so an unconditional statement would take that lock on every
+ * boot forever — and a lock it cannot acquire within the migrator's
+ * `busy_timeout` fails the migration and holds every gated service down. The
+ * steady state after the first run is zero, so the skip is the normal path.
+ *
+ * Two things the statement will not do, both because the repair must never
+ * leave a row worse than it found it:
+ *
+ *  - It never copies `uncategorized` over a classified row. `message` is the
+ *    authority, but a pending message holds nothing to copy, and after #326
+ *    body-sync writes the row before the message, so a classification in flight
+ *    is legitimately `ahead` of its message for a moment. Pushing it back would
+ *    undo a correct classification and, on the read path #328 builds, serve
+ *    `Unclassified` for mail that is already classified. Counted as `ahead`.
+ *  - It never overwrites a row that was written after the statement began. The
+ *    migrate one-shot normally runs with every app service stopped, but
+ *    `docker compose up -d` can restart it while workers still run, so the
+ *    quiet window is not assumed. On SQLite writers are serialized, so a
+ *    concurrent body-sync write lands wholly before or wholly after and both
+ *    orders converge on the same value. On Postgres READ COMMITTED an UPDATE
+ *    re-evaluates its WHERE clause against the version a concurrent
+ *    transaction just committed, but still reads other tables at its original
+ *    snapshot — so without the `updated_at` guard it could write a
+ *    pre-classification value over the fresh one. The guard makes that row fail
+ *    the re-check and the writer's value stands.
+ *
+ * The guard covers a writer whose transaction begins after the statement. A
+ * writer that began before it and commits during it carries an older stamp and
+ * passes, which would revert its write. Four things have to hold at once for
+ * that to lose anything:
+ *
+ *  1. a row the statement's WHERE matches, so an unrepaired `behind` row;
+ *  2. a writer overlapping the statement;
+ *  3. that writer's row write committing before the statement began while its
+ *     message write commits after it — the two are separate commits;
+ *  4. the writer moving `message.category` from one decided value to a
+ *     *different* decided value. A first classification cannot lose anything:
+ *     `message.category` is still `uncategorized`, so the pending exclusion
+ *     above refuses the row outright.
+ *
+ * Only the fourth is interesting, and it is not impossible. It is unreachable
+ * through `backfillClassification`, which returns early once the category is
+ * decided. It is reachable through the primary path, which is re-enterable: the
+ * skip guard is `if (message.bodyStorageKey && !force)` (`body-sync.ts`), and
+ * `force` is a live event flag — the read-miss re-arm cue, resolved in the
+ * imap-worker's `sync-message-body.ts`. A forced re-fetch re-runs
+ * `classifyByHeaders` over the same bytes, so it normally rewrites the value it
+ * already held; it decides *differently* only across a release that changed the
+ * classifier, which #62 was.
+ *
+ * So: effectively unreachable, needing a forced re-fetch of a message whose
+ * stored classification predates a classifier change, overlapping this
+ * statement. Not impossible, and the `crossed` figure is what reports it.
+ *
+ * The statement does not touch `updated_at`. That column means "when the app
+ * last wrote this row", which is what the guard above reads, and a repair that
+ * bumped it would both lie about the row and defeat its own guard.
+ */
+
+export type RepairDialect = "sqlite" | "postgres";
+
+/**
+ * The smallest surface the repair needs, so this module imports nothing and can
+ * be driven by the migrator's `better-sqlite3` handle, its `pg.Pool`, or a test
+ * harness of either dialect.
+ */
+export interface RepairSqlClient {
+	readonly dialect: RepairDialect;
+	all(sql: string): Promise<unknown[]>;
+	run(sql: string): Promise<number>;
+}
+
+/**
+ * The declared pending state, not absence (#45). It must never fold into
+ * `personal`, and it is the one value the repair refuses to write over a
+ * classified row.
+ */
+const PENDING = "uncategorized";
+
+const nowMillis = (dialect: RepairDialect): string =>
+	dialect === "sqlite"
+		? "CAST(unixepoch('subsec') * 1000 AS INTEGER)"
+		: "CAST(EXTRACT(EPOCH FROM now()) * 1000 AS bigint)";
+
+export const repairStatement = (dialect: RepairDialect): string =>
+	`UPDATE thread_message
+SET category = (
+	SELECT m.category FROM message m WHERE m.message_id = thread_message.message_id
+)
+WHERE EXISTS (
+	SELECT 1 FROM message m
+	WHERE m.message_id = thread_message.message_id
+	  AND m.category <> thread_message.category
+	  AND m.category <> '${PENDING}'
+)
+  AND thread_message.updated_at <= ${nowMillis(dialect)}`;
+
+const BUCKETS_SQL = `SELECT t.category AS row_category, m.category AS message_category, count(*) AS row_count
+FROM thread_message t
+JOIN message m ON m.message_id = t.message_id
+GROUP BY t.category, m.category`;
+
+const TALLY_SQL = `SELECT category, count(*) AS row_count
+FROM thread_message
+GROUP BY category
+ORDER BY row_count DESC, category ASC`;
+
+const BY_MAILBOX_SQL = `SELECT t.mailbox_id AS mailbox_id, count(*) AS row_count
+FROM thread_message t
+JOIN message m ON m.message_id = t.message_id
+WHERE m.category <> t.category
+GROUP BY t.mailbox_id
+ORDER BY row_count DESC, mailbox_id ASC`;
+
+const FAN_OUT_SQL = `SELECT count(*) AS message_count, coalesce(sum(row_count), 0) AS row_total
+FROM (
+	SELECT message_id, count(*) AS row_count
+	FROM thread_message
+	GROUP BY message_id
+	HAVING count(*) > 1
+) fan_out`;
+
+/**
+ * The residual after a repair, split by why the row was left. A row skipped
+ * because a writer touched it during the statement is repaired on the next run;
+ * a row whose `updated_at` is ahead of the database clock fails the guard on
+ * every run until the stamp is corrected, which is a different thing to tell an
+ * operator and would otherwise be indistinguishable in the output.
+ */
+const residualSql = (dialect: RepairDialect): string =>
+	`SELECT count(*) AS row_count,
+	coalesce(sum(CASE WHEN t.updated_at > ${nowMillis(dialect)} THEN 1 ELSE 0 END), 0) AS ahead_of_clock
+FROM thread_message t
+JOIN message m ON m.message_id = t.message_id
+WHERE m.category <> t.category
+  AND m.category <> '${PENDING}'`;
+
+export type CategoryCount = {
+	readonly category: string;
+	readonly rows: number;
+};
+
+export type MailboxCount = {
+	readonly mailboxId: string;
+	readonly rows: number;
+};
+
+/**
+ * Divergence split by direction, because the direction is the cause. A repair
+ * that never ran and a corpus that was already correct both report
+ * `divergent: 0`; only the per-cause figures tell them apart, and only the
+ * per-cause expectations say which zeros are the healthy answer.
+ *
+ *  - `behind` — the row is pending, its message is classified. Every one of the
+ *    three write-path defects #326 fixes lands here, and this is the cohort the
+ *    repair exists for.
+ *  - `crossed` — both classified, differently. No write path leaves a row here:
+ *    the row and the message take the same `classifyByHeaders` value off the
+ *    same bytes in the same pass, so a re-classification moves both.
+ *  - `ahead` — the row is classified, its message is pending. After #326 that is
+ *    a classification in flight, so on a live instance it is expected and
+ *    transient. Not repaired.
+ */
+export type CategoryDivergence = {
+	readonly rowsWithMessage: number;
+	readonly divergent: number;
+	readonly repairable: number;
+	readonly behind: number;
+	readonly crossed: number;
+	readonly ahead: number;
+	readonly notYetClassified: number;
+};
+
+export type CategoryResidual = {
+	readonly repairable: number;
+	readonly aheadOfClock: number;
+};
+
+export type CategoryDivergenceReport = CategoryDivergence & {
+	readonly rows: number;
+	readonly orphanRows: number;
+	readonly fanOutMessages: number;
+	readonly fanOutRows: number;
+	readonly divergentByMailbox: readonly MailboxCount[];
+	readonly categoryTally: readonly CategoryCount[];
+};
+
+export type RepairResult = {
+	readonly rowsWritten: number;
+	readonly elapsedMs: number;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	typeof value === "object" && value !== null;
+
+const columnOf = (row: unknown, column: string): unknown => {
+	if (!isRecord(row)) {
+		throw new Error(
+			`thread_message.category check: expected a row object, received ${JSON.stringify(row)}`,
+		);
+	}
+	return row[column];
+};
+
+// node-postgres hands back bigint aggregates as strings, so a count is a number
+// or the decimal text of one, and anything else is a query that changed shape.
+const countOf = (row: unknown, column: string): number => {
+	const value = columnOf(row, column);
+	if (typeof value === "number" && Number.isFinite(value)) {
+		return value;
+	}
+	if (typeof value === "string" && /^\d+$/.test(value)) {
+		return Number(value);
+	}
+	throw new Error(
+		`thread_message.category check: expected a count in "${column}", received ${JSON.stringify(value)}`,
+	);
+};
+
+const textOf = (row: unknown, column: string): string => {
+	const value = columnOf(row, column);
+	if (typeof value === "string") {
+		return value;
+	}
+	throw new Error(
+		`thread_message.category check: expected text in "${column}", received ${JSON.stringify(value)}`,
+	);
+};
+
+const sum = (values: readonly number[]): number =>
+	values.reduce((total, value) => total + value, 0);
+
+/**
+ * One grouped scan of the join answers every divergence figure, so the check
+ * costs two aggregate passes over `thread_message` rather than one per number.
+ */
+export const readDivergence = async (
+	client: RepairSqlClient,
+): Promise<CategoryDivergence> => {
+	const buckets = (await client.all(BUCKETS_SQL)).map((row) => ({
+		rowCategory: textOf(row, "row_category"),
+		messageCategory: textOf(row, "message_category"),
+		rows: countOf(row, "row_count"),
+	}));
+
+	const total = (
+		predicate: (bucket: (typeof buckets)[number]) => boolean,
+	): number => sum(buckets.filter(predicate).map((bucket) => bucket.rows));
+
+	const behind = total(
+		(bucket) =>
+			bucket.rowCategory === PENDING && bucket.messageCategory !== PENDING,
+	);
+	const crossed = total(
+		(bucket) =>
+			bucket.rowCategory !== PENDING &&
+			bucket.messageCategory !== PENDING &&
+			bucket.rowCategory !== bucket.messageCategory,
+	);
+	const ahead = total(
+		(bucket) =>
+			bucket.rowCategory !== PENDING && bucket.messageCategory === PENDING,
+	);
+
+	return {
+		rowsWithMessage: total(() => true),
+		divergent: total((bucket) => bucket.rowCategory !== bucket.messageCategory),
+		repairable: behind + crossed,
+		behind,
+		crossed,
+		ahead,
+		notYetClassified: total(
+			(bucket) =>
+				bucket.rowCategory === PENDING && bucket.messageCategory === PENDING,
+		),
+	};
+};
+
+export const checkThreadMessageCategory = async (
+	client: RepairSqlClient,
+): Promise<CategoryDivergenceReport> => {
+	const divergence = await readDivergence(client);
+
+	const categoryTally = (await client.all(TALLY_SQL)).map((row) => ({
+		category: textOf(row, "category"),
+		rows: countOf(row, "row_count"),
+	}));
+
+	const divergentByMailbox = (await client.all(BY_MAILBOX_SQL)).map((row) => ({
+		mailboxId: textOf(row, "mailbox_id"),
+		rows: countOf(row, "row_count"),
+	}));
+
+	const [fanOut] = await client.all(FAN_OUT_SQL);
+
+	const rows = sum(categoryTally.map((entry) => entry.rows));
+
+	return {
+		...divergence,
+		rows,
+		orphanRows: rows - divergence.rowsWithMessage,
+		fanOutMessages: countOf(fanOut, "message_count"),
+		fanOutRows: countOf(fanOut, "row_total"),
+		divergentByMailbox,
+		categoryTally,
+	};
+};
+
+export const repairThreadMessageCategory = async (
+	client: RepairSqlClient,
+): Promise<RepairResult> => {
+	const startedAt = Date.now();
+	const rowsWritten = await client.run(repairStatement(client.dialect));
+	return { rowsWritten, elapsedMs: Date.now() - startedAt };
+};
+
+export const readResidual = async (
+	client: RepairSqlClient,
+): Promise<CategoryResidual> => {
+	const [row] = await client.all(residualSql(client.dialect));
+	return {
+		repairable: countOf(row, "row_count"),
+		aheadOfClock: countOf(row, "ahead_of_clock"),
+	};
+};
+
+const plural = (rows: number): string => (rows === 1 ? "row" : "rows");
+
+/**
+ * Every figure carries the cause it measures and the result a healthy instance
+ * is expected to produce. Most of them are legitimately zero, so a bare `0`
+ * cannot be told apart from a repair that never ran — and a cause an operator
+ * can rule out by inspection is worse than no cause at all, because it reads as
+ * a broken figure.
+ */
+export const formatCheckReport = (
+	report: CategoryDivergenceReport,
+): string[] => [
+	`thread_message rows: ${report.rows} (${report.rowsWithMessage} with a message row)`,
+	`divergent (thread_message.category <> message.category): ${report.divergent}, of which ${report.repairable} repairable`,
+	`  behind: ${report.behind} ${plural(report.behind)} pending against a classified message — the copy of a decided category never landed. All three of the write-path defects #326 fixes end here: a retro classification stranded between its two writes, a denormalize that wrote one of several rows for a message, and a row created for a message that was already classified. Repaired, and this is the cohort the repair exists for. Expected non-zero on an instance where any of those fired, zero otherwise.`,
+	`  crossed: ${report.crossed} ${plural(report.crossed)} classified differently from the message — no write path leaves a row here: both take the same classifyByHeaders value off the same bytes in the same pass, so a re-classification moves the row and the message together. Repaired. Expected zero; a non-zero means the pair was interrupted between its two writes — a forced re-fetch that re-decided the category and died before the message write — or the database was edited outside the app.`,
+	`  ahead: ${report.ahead} ${plural(report.ahead)} classified against a pending message — after #326 body-sync writes the row before the message, so this is a classification in flight. Not repaired: pushing it back to pending would undo a correct classification and serve Unclassified for mail that is already classified. Expected non-zero on a live instance mid-sync, zero on a quiescent one.`,
+	`fan-out: ${report.fanOutMessages} messages holding ${report.fanOutRows} thread_message rows — the multi-row shape #326 hardens against. Expected zero: deriveMessageId and deriveThreadMessageId are both mailbox-independent, so a message in two mailboxes collapses to one row, and the reachable case is thread-root drift.`,
+	`orphans: ${report.orphanRows} ${plural(report.orphanRows)} with no message row — not repaired, nothing to copy. Expected zero.`,
+	`not-yet-classified: ${report.notYetClassified} ${plural(report.notYetClassified)} pending against a pending message — not classified yet. Not a defect, not touched by the repair, and unchanged by it. Expected non-zero on a live instance.`,
+	`divergent per mailbox: ${
+		report.divergentByMailbox.length === 0
+			? "none"
+			: report.divergentByMailbox
+					.map((entry) => `${entry.mailboxId}=${entry.rows}`)
+					.join(" ")
+	}`,
+	`category tally: ${
+		report.categoryTally.length === 0
+			? "none"
+			: report.categoryTally
+					.map((entry) => `${entry.category}=${entry.rows}`)
+					.join(" ")
+	}`,
+];
+
+/**
+ * The next run of the repair is the next start of the migrate one-shot, which on
+ * a self-host instance means the next `remit update` — weeks, not minutes. A
+ * residual is therefore named as something an operator may have to act on, not
+ * as something that clears itself shortly.
+ */
+export const formatRepairResult = (
+	result: RepairResult,
+	residual: CategoryResidual,
+): string[] => {
+	const lines = [
+		`repair wrote ${result.rowsWritten} ${plural(result.rowsWritten)} in ${result.elapsedMs}ms`,
+		`residual repairable divergence: ${residual.repairable} (expected zero)`,
+	];
+	if (residual.repairable === 0) {
+		return lines;
+	}
+
+	const concurrent = residual.repairable - residual.aheadOfClock;
+	if (concurrent > 0) {
+		lines.push(
+			`WARNING: ${concurrent} ${plural(concurrent)} skipped because a writer touched them while the repair ran. The writer's value stands, which is correct, but the copy is only rechecked the next time this one-shot runs — the next 'remit update' — and until then the mail list serves that row's category as it now stands.`,
+		);
+	}
+	if (residual.aheadOfClock > 0) {
+		lines.push(
+			`WARNING: ${residual.aheadOfClock} ${plural(residual.aheadOfClock)} carry an updated_at ahead of the database clock, so they fail the repair's guard on every run, not just this one. That is a clock that jumped, a restored backup, or a host whose time was wrong — not a concurrent writer. They stay divergent until the stamp is corrected.`,
+		);
+	}
+	return lines;
+};
+
+/**
+ * The repair is skipped outright when the check found nothing to write, because
+ * SQLite takes the exclusive write lock when an UPDATE begins — before it can
+ * know the WHERE matches nothing. The steady state is zero, so without this
+ * every boot would take that lock, and a lock it cannot acquire within
+ * busy_timeout fails the migration and holds every gated service down. The
+ * figures the skip is decided on were just read; a row that diverges in the
+ * moment between is skipped by the guard anyway and repaired on the next run.
+ */
+export const formatRepairSkipped = (
+	divergence: CategoryDivergence,
+): string[] => [
+	`repair skipped: nothing repairable (${divergence.divergent} divergent, ${divergence.ahead} of them a classification in flight). No write, so no write lock is taken.`,
+];