@remit/mailbox-service 0.0.34 → 0.0.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/body-sync-backfill.test.ts

@@ -20,6 +20,7 @@ import type {
 	UpdateMessageInput,
 	UpdateThreadMessageInput,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import { MessageCategory } from "@remit/domain-enums";
 import type { StorageService } from "@remit/storage-service";
 import { BodySyncService } from "./body-sync.js";
@@ -103,7 +104,11 @@ const buildHarness = (
 		messageService,
 		storageService,
 		threadMessageService,
-		{} as unknown as IAddressRepository,
+		{
+			getAddress: async () => {
+				throw new NotFoundError("Address not found");
+			},
+		} as unknown as IAddressRepository,
 		{} as unknown as IEnvelopeRepository,
 		{
 			info: () => {},

package/src/body-sync-category-denormalize.test.ts

@@ -29,6 +29,7 @@ import type {
 	UpdateMessageInput,
 	UpdateThreadMessageInput,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import { MessageCategory } from "@remit/domain-enums";
 import type { StorageService } from "@remit/storage-service";
 import { BodySyncService } from "./body-sync.js";
@@ -171,7 +172,12 @@ const buildHarness = (
 		messageService,
 		storageService,
 		threadMessageService,
-		{ incrementInboundCount: async () => {} } as unknown as IAddressRepository,
+		{
+			getAddress: async () => {
+				throw new NotFoundError("Address not found");
+			},
+			incrementInboundCount: async () => {},
+		} as unknown as IAddressRepository,
 		{ listBodyParts: async () => [] } as unknown as IEnvelopeRepository,
 		{ info: () => {}, error: () => {} },
 	);

package/src/body-sync-category-override.test.ts

@@ -0,0 +1,460 @@
+/**
+ * `Address.flags.category` overrides classification at sync time (issue #299,
+ * RFC 039 Decision 3, closing item 3 of RFC 039). A user who has told Remit
+ * "this sender is actually Personal, not Marketing" via the Reclassify dialog
+ * (`PATCH /addresses/{id}`) gets that category on the sender's next message,
+ * instead of `classifyByHeaders` re-deriving the same header-driven verdict
+ * every time.
+ *
+ * The override sits behind the same `hasDecidedCategory` write-once gate #378
+ * added for `Message.category` (RFC 034 Decision 3.1, RFC 030's message-list
+ * GSI sort key depends on it never churning): a message already carrying a
+ * real category is never re-touched, override present or not. The two tests
+ * under "survives a re-entrant pass" feed a *differing* override to an
+ * already-classified message through both shipped re-entry paths — the
+ * `NoSuchKey` IMAP re-fetch and `syncBodies(..., force: true)` — so a
+ * regression that let the override bypass the guard shows up here, not just
+ * in an isolated unit check.
+ */
+
+import assert from "node:assert/strict";
+import { Readable } from "node:stream";
+import { describe, it } from "node:test";
+import type {
+	AddressItem,
+	IAddressRepository,
+	IEnvelopeRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+	MessageItem,
+	ThreadMessageItem,
+	UpdateMessageInput,
+	UpdateThreadMessageInput,
+} from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { MessageCategory } from "@remit/domain-enums";
+import type { StorageService } from "@remit/storage-service";
+import { BodySyncService } from "./body-sync.js";
+import type { IImapConnection } from "./types.js";
+
+const LINKEDIN_EML = Buffer.from(
+	[
+		"From: LinkedIn <messages-noreply@linkedin.com>",
+		"To: me@example.com",
+		"Subject: You have a new invitation",
+		"List-Unsubscribe: <https://www.linkedin.com/e/unsub>",
+		"Content-Type: text/plain",
+		"",
+		"invitation",
+	].join("\r\n"),
+);
+
+interface ThreadUpdate {
+	threadMessageId: string;
+	input: UpdateThreadMessageInput;
+}
+
+interface Harness {
+	service: BodySyncService;
+	message: MessageItem;
+	rows: ThreadMessageItem[];
+	messageUpdates: Array<{ messageId: string; input: UpdateMessageInput }>;
+	threadUpdates: ThreadUpdate[];
+	getAddressCalls: number;
+}
+
+const buildHarness = (
+	message: Partial<MessageItem> & Pick<MessageItem, "messageId">,
+	flags: AddressItem["flags"] | undefined,
+	retrieve: () => Promise<Buffer> = async () => {
+		throw new Error("no body configured for retrieve()");
+	},
+): Harness => {
+	const messageUpdates: Array<{
+		messageId: string;
+		input: UpdateMessageInput;
+	}> = [];
+	const threadUpdates: ThreadUpdate[] = [];
+	let getAddressCalls = 0;
+
+	const messageRow = {
+		uid: 1,
+		mailboxId: "mb-1",
+		category: MessageCategory.uncategorized,
+		...message,
+	} as unknown as MessageItem;
+
+	const rows: ThreadMessageItem[] = [
+		{
+			threadMessageId: "tm-1",
+			messageId: message.messageId,
+			mailboxId: "mb-1",
+			sentDate: 1,
+			isRead: false,
+			isDeleted: false,
+			hasStars: false,
+			hasAttachment: false,
+			category: messageRow.category,
+		} as unknown as ThreadMessageItem,
+	];
+
+	const messageService = {
+		get: async () => messageRow,
+		update: async (messageId: string, input: UpdateMessageInput) => {
+			messageUpdates.push({ messageId, input });
+			Object.assign(messageRow, input);
+		},
+	} as unknown as IMessageRepository;
+
+	const threadMessageService = {
+		findAllByMessageId: async () => rows,
+		update: async (
+			_accountConfigId: string,
+			threadMessageId: string,
+			input: UpdateThreadMessageInput,
+		) => {
+			threadUpdates.push({ threadMessageId, input });
+			const row = rows.find((r) => r.threadMessageId === threadMessageId);
+			if (row) Object.assign(row, input);
+		},
+	} as unknown as IThreadMessageRepository;
+
+	const storageService = {
+		retrieve,
+		storeMessageBody: async () => ({ uri: `s3://bodies/${message.messageId}` }),
+		storeMessageBodyStream: async () => ({
+			uri: `s3://bodies/${message.messageId}`,
+		}),
+		storeParsedBody: async () => {},
+		listBodyParts: async () => [],
+	} as unknown as StorageService;
+
+	const addressService = {
+		getAddress: async () => {
+			getAddressCalls++;
+			if (flags === undefined) {
+				throw new NotFoundError("Address not found");
+			}
+			return { flags } as unknown as AddressItem;
+		},
+		incrementInboundCount: async () => {},
+	} as unknown as IAddressRepository;
+
+	const envelopeService = {
+		listBodyParts: async () => [],
+	} as unknown as IEnvelopeRepository;
+
+	const service = new BodySyncService(
+		messageService,
+		storageService,
+		threadMessageService,
+		addressService,
+		envelopeService,
+		{ info: () => {}, error: () => {} },
+	);
+
+	return {
+		service,
+		message: messageRow,
+		rows,
+		messageUpdates,
+		threadUpdates,
+		get getAddressCalls() {
+			return getAddressCalls;
+		},
+	};
+};
+
+const noSuchKeyError = () =>
+	Object.assign(new Error("missing"), { name: "NoSuchKey" });
+
+const overrideFlags = (
+	category: (typeof MessageCategory)[keyof typeof MessageCategory],
+): AddressItem["flags"] =>
+	({
+		category: { value: category, setAt: 1_000 },
+	}) as unknown as AddressItem["flags"];
+
+describe("Address.flags.category overrides classification at sync time (issue #299)", () => {
+	it("classifies a new message by the sender's override, not the header-derived category", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", category: MessageCategory.uncategorized },
+			overrideFlags(MessageCategory.personal),
+		);
+
+		const connection = {
+			openBox: async () => {},
+			fetchMessageBody: async () => LINKEDIN_EML,
+		} as unknown as IImapConnection;
+
+		await harness.service.fetchAndGetBody(
+			"m-1",
+			"acc-1",
+			"cfg-1",
+			"INBOX",
+			async () => connection,
+		);
+
+		assert.equal(harness.messageUpdates.length, 1);
+		assert.equal(
+			harness.messageUpdates[0].input.category,
+			MessageCategory.personal,
+		);
+		assert.equal(harness.message.category, MessageCategory.personal);
+		// No placementConfig is wired in this harness, so the override's own
+		// Address read is the only one classification makes per message.
+		assert.equal(harness.getAddressCalls, 1);
+	});
+
+	it("denormalizes the override onto the ThreadMessage, matching the Message row", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", category: MessageCategory.uncategorized },
+			overrideFlags(MessageCategory.personal),
+		);
+
+		const connection = {
+			openBox: async () => {},
+			fetchMessageBody: async () => LINKEDIN_EML,
+		} as unknown as IImapConnection;
+
+		await harness.service.fetchAndGetBody(
+			"m-1",
+			"acc-1",
+			"cfg-1",
+			"INBOX",
+			async () => connection,
+		);
+
+		assert.equal(harness.rows[0].category, MessageCategory.personal);
+	});
+
+	it("classifies by headers as usual when the sender has no category override", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", category: MessageCategory.uncategorized },
+			undefined,
+		);
+
+		const connection = {
+			openBox: async () => {},
+			fetchMessageBody: async () => LINKEDIN_EML,
+		} as unknown as IImapConnection;
+
+		await harness.service.fetchAndGetBody(
+			"m-1",
+			"acc-1",
+			"cfg-1",
+			"INBOX",
+			async () => connection,
+		);
+
+		assert.equal(
+			harness.messageUpdates[0].input.category,
+			MessageCategory.social,
+		);
+	});
+
+	it("classifies by headers as usual when the sender has flags but no category entry", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", category: MessageCategory.uncategorized },
+			{ vip: { value: true, setAt: 1 } } as unknown as AddressItem["flags"],
+		);
+
+		const connection = {
+			openBox: async () => {},
+			fetchMessageBody: async () => LINKEDIN_EML,
+		} as unknown as IImapConnection;
+
+		await harness.service.fetchAndGetBody(
+			"m-1",
+			"acc-1",
+			"cfg-1",
+			"INBOX",
+			async () => connection,
+		);
+
+		assert.equal(
+			harness.messageUpdates[0].input.category,
+			MessageCategory.social,
+		);
+	});
+
+	it("backfillClassification picks up the same override for a body stored before classification existed", async () => {
+		const harness = buildHarness(
+			{
+				messageId: "m-1",
+				bodyStorageKey: "s3://bodies/m-1",
+				category: MessageCategory.uncategorized,
+			},
+			overrideFlags(MessageCategory.transactional),
+			async () => LINKEDIN_EML,
+		);
+
+		const result = await harness.service.syncBodies(
+			["m-1"],
+			"acc-1",
+			"cfg-1",
+			"INBOX",
+			async () => {
+				throw new Error("backfill must not open IMAP");
+			},
+		);
+
+		assert.equal(result.skippedCount, 1);
+		assert.equal(harness.messageUpdates.length, 1);
+		assert.equal(
+			harness.messageUpdates[0].input.category,
+			MessageCategory.transactional,
+		);
+		assert.equal(harness.rows[0].category, MessageCategory.transactional);
+	});
+
+	describe("survives a re-entrant pass with a differing override already set", () => {
+		it("keeps the already-decided category through the NoSuchKey IMAP re-fetch", async () => {
+			const harness = buildHarness(
+				{
+					messageId: "m-1",
+					bodyStorageKey: "s3://bodies/m-1",
+					category: MessageCategory.marketing,
+				},
+				overrideFlags(MessageCategory.personal),
+				async () => {
+					throw noSuchKeyError();
+				},
+			);
+
+			const connection = {
+				openBox: async () => {},
+				fetchMessageBody: async () => LINKEDIN_EML,
+			} as unknown as IImapConnection;
+
+			await harness.service.fetchAndGetBody(
+				"m-1",
+				"acc-1",
+				"cfg-1",
+				"INBOX",
+				async () => connection,
+			);
+
+			assert.equal(harness.messageUpdates.length, 1);
+			assert.equal(
+				harness.messageUpdates[0].input.category,
+				MessageCategory.marketing,
+			);
+			assert.equal(harness.message.category, MessageCategory.marketing);
+			assert.equal(harness.rows[0].category, MessageCategory.marketing);
+		});
+
+		it("keeps the already-decided category when syncBodies re-fetches with force", async () => {
+			const harness = buildHarness(
+				{
+					messageId: "m-1",
+					bodyStorageKey: "s3://bodies/m-1",
+					category: MessageCategory.marketing,
+				},
+				overrideFlags(MessageCategory.personal),
+				async () => {
+					throw new Error("force path must not retrieve from storage");
+				},
+			);
+
+			const connection = {
+				openBox: async () => {},
+				async *fetchMessageBodies(uids: number[]) {
+					for (const uid of uids) {
+						yield { uid, source: Readable.from([LINKEDIN_EML]) };
+					}
+				},
+			} as unknown as IImapConnection;
+
+			const result = await harness.service.syncBodies(
+				["m-1"],
+				"acc-1",
+				"cfg-1",
+				"INBOX",
+				async () => connection,
+				true,
+			);
+
+			assert.deepEqual(result.syncedMessageIds, ["m-1"]);
+			assert.equal(harness.messageUpdates.length, 1);
+			assert.equal(
+				harness.messageUpdates[0].input.category,
+				MessageCategory.marketing,
+			);
+			assert.equal(harness.message.category, MessageCategory.marketing);
+			assert.equal(harness.rows[0].category, MessageCategory.marketing);
+		});
+	});
+
+	it("propagates a non-NotFound Address lookup failure instead of silently classifying by headers", async () => {
+		const message = {
+			messageId: "m-1",
+			category: MessageCategory.uncategorized,
+		};
+		const messageRow = { uid: 1, mailboxId: "mb-1", ...message } as MessageItem;
+
+		const messageService = {
+			get: async () => messageRow,
+			update: async () => {},
+		} as unknown as IMessageRepository;
+
+		const threadMessageService = {
+			findAllByMessageId: async () => [
+				{
+					threadMessageId: "tm-1",
+					mailboxId: "mb-1",
+					sentDate: 1,
+					isRead: false,
+					isDeleted: false,
+					hasStars: false,
+					hasAttachment: false,
+				},
+			],
+			update: async () => {},
+		} as unknown as IThreadMessageRepository;
+
+		const storageService = {
+			storeMessageBody: async () => ({ uri: "s3://bodies/m-1" }),
+			storeParsedBody: async () => {},
+			listBodyParts: async () => [],
+		} as unknown as StorageService;
+
+		const addressService = {
+			getAddress: async () => {
+				const error = new Error("ProvisionedThroughputExceededException");
+				error.name = "ProvisionedThroughputExceededException";
+				throw error;
+			},
+			incrementInboundCount: async () => {},
+		} as unknown as IAddressRepository;
+
+		const envelopeService = {
+			listBodyParts: async () => [],
+		} as unknown as IEnvelopeRepository;
+
+		const service = new BodySyncService(
+			messageService,
+			storageService,
+			threadMessageService,
+			addressService,
+			envelopeService,
+			{ info: () => {}, error: () => {} },
+		);
+
+		const connection = {
+			openBox: async () => {},
+			fetchMessageBody: async () => LINKEDIN_EML,
+		} as unknown as IImapConnection;
+
+		await assert.rejects(
+			service.fetchAndGetBody(
+				"m-1",
+				"acc-1",
+				"cfg-1",
+				"INBOX",
+				async () => connection,
+			),
+			/ProvisionedThroughputExceededException/,
+		);
+	});
+});

package/src/body-sync-category-writeonce.test.ts

@@ -24,6 +24,7 @@ import type {
 	MessageItem,
 	UpdateMessageInput,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import { MessageCategory } from "@remit/domain-enums";
 import type { StorageService } from "@remit/storage-service";
 import { BodySyncService } from "./body-sync.js";
@@ -111,7 +112,12 @@ const buildHarness = (
 		messageService,
 		storageService,
 		threadMessageService,
-		{ incrementInboundCount: async () => {} } as unknown as IAddressRepository,
+		{
+			getAddress: async () => {
+				throw new NotFoundError("Address not found");
+			},
+			incrementInboundCount: async () => {},
+		} as unknown as IAddressRepository,
 		{ listBodyParts: async () => [] } as unknown as IEnvelopeRepository,
 		{ info: () => {}, error: () => {} },
 	);

package/src/body-sync-filter.test.ts

@@ -28,6 +28,7 @@ import type {
 	MessageItem,
 	UpdateMessageInput,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import {
 	FilterClauseField,
 	FilterMatchOperator,
@@ -123,6 +124,9 @@ const buildHarness = (
 	} as unknown as StorageService;
 
 	const addressService = {
+		getAddress: async () => {
+			throw new NotFoundError("Address not found");
+		},
 		incrementInboundCount: async () => {},
 	} as unknown as IAddressRepository;
 

package/src/body-sync.ts

@@ -705,14 +705,22 @@ export class BodySyncService {
 		body: Buffer,
 		bodyRef: { uri: string },
 	): Promise<ParsedMail> {
-		// Snippet + thread update; reuses the parsed mail for the steps below.
-		// This is a ThreadMessage write — a different entity — so it does NOT
-		// trigger the Message-filtered stream bridge and stays separate.
-		const parsed = await this.updateSnippets(messageId, accountConfigId, body);
+		// The one operation on this path that can fail because of how the message
+		// is built. Its own try block lives in `parseMessageBody`, so this frame —
+		// which also wraps the S3 body write, the parsed-body cache, the placement
+		// move, the label writes and the counter update — can tell the two apart
+		// and quarantine only this one (issue #72). The ThreadMessage write these
+		// feed happens later, alongside the Message write (see below), once the
+		// write-once category is decided.
+		const parsed = await parseMessageBody(body);
+		const snippet = extractSnippet(parsed);
+		const listId = extractListId(parsed);
 
-		// Compute the header classification once. The derived fields are folded
-		// into the single Message update below — they are NOT written here.
-		const classification = this.classifyMessage(parsed);
+		// Compute the header classification once, folding in the sender's
+		// `flags.category` override when one applies (issue #299). The derived
+		// fields are folded into the single Message update below — they are NOT
+		// written here.
+		const classification = await this.classifyMessage(accountConfigId, parsed);
 
 		// Decide the placement move from the in-memory classification before the
 		// write, so its `movedByRemit` flag and audit verdict join the same
@@ -855,13 +863,29 @@ export class BodySyncService {
 		// fallback in `fetchAndGetBody` and `syncBodies(..., force: true)` — so a
 		// real, previously-decided category is carried forward unchanged instead
 		// of the just-recomputed one, the same rule `backfillClassification` uses.
+		// This also protects a `flags.category` override (issue #299): without
+		// this guard a re-entrant pass would let a *later* override silently
+		// rewrite a category already decided on an earlier message, which is
+		// exactly the churn RFC 030's GSI-safety argument forbids.
 		const existingMessage = await this.messageService.get(messageId);
+		const finalCategory = hasDecidedCategory(existingMessage.category)
+			? existingMessage.category
+			: classification.category;
+
+		// Thread-list denormalization, using the same write-once category as the
+		// Message update below — the two rows must never disagree on category.
+		await this.denormalizeCategory(
+			accountConfigId,
+			messageId,
+			finalCategory,
+			snippet,
+			listId,
+		);
+
 		const update: UpdateMessageInput = {
 			bodyStorageKey: bodyRef.uri,
 			...classification,
-			category: hasDecidedCategory(existingMessage.category)
-				? existingMessage.category
-				: classification.category,
+			category: finalCategory,
 			...(moved ? { movedByRemit: true } : {}),
 			...(resolved.verdict ? { placementVerdict: resolved.verdict } : {}),
 			...(filterMove ? { filterMove } : {}),
@@ -1017,7 +1041,7 @@ export class BodySyncService {
 
 		const body = await this.storageService.retrieve(message.bodyStorageKey);
 		const parsed = await parseMessageBody(body);
-		const classification = this.classifyMessage(parsed);
+		const classification = await this.classifyMessage(accountConfigId, parsed);
 
 		// Same order as {@link applyPostStoreSteps}, for the same reason: the
 		// signal the skip guard reads is written last. `message.category` is that
@@ -1025,12 +1049,13 @@ export class BodySyncService {
 		// the requeued retry redoes both. Writing the Message first strands the
 		// denormalized row at `uncategorized` forever — the guard is satisfied and
 		// the retry returns early (issue #320).
-		// The same three denormalized fields `updateSnippets` writes on the
-		// full body-store path, not just the category. A copied message inherits
-		// `bodyStorageKey` and a decided category from its source, so it reaches
-		// neither that path nor this one's classification — but nothing else ever
-		// writes `listId`, so leaving it out here made a copy's `list_id`
-		// permanently NULL. Both are derived from the same bytes already in hand.
+		// The same three denormalized fields the full body-store path writes (see
+		// `applyPostStoreSteps`), not just the category. A copied message
+		// inherits `bodyStorageKey` and a decided category from its source, so it
+		// reaches neither that path nor this one's classification — but nothing
+		// else ever writes `listId`, so leaving it out here made a copy's
+		// `list_id` permanently NULL. Both are derived from the same bytes
+		// already in hand.
 		await this.denormalizeCategory(
 			accountConfigId,
 			message.messageId,
@@ -1047,21 +1072,39 @@ export class BodySyncService {
 	}
 
 	/**
-	 * Pure header classification. Returns the subset of the Message update that
-	 * carries the derived fields; the caller folds it into a single UpdateItem
-	 * alongside `bodyStorageKey`. Optional signals are omitted when absent so we
-	 * never overwrite an existing value with `undefined`.
+	 * Header classification, with the sender's `Address.flags.category`
+	 * override (issue #299, RFC 039 Decision 3) substituted for the
+	 * header-derived category when one is set. Returns the subset of the
+	 * Message update that carries the derived fields; the caller folds it into
+	 * a single UpdateItem alongside `bodyStorageKey`. Optional signals are
+	 * omitted when absent so we never overwrite an existing value with
+	 * `undefined`.
+	 *
+	 * The override wins outright rather than blending with the heuristic — RFC
+	 * 039 Decision 3 treats a direct reclassification as final, the same as
+	 * `flags.blocked`/`vip` already override placement. Both callers
+	 * (`applyPostStoreSteps`, `backfillClassification`) already gate on
+	 * `hasDecidedCategory` before this result reaches a write, so a message
+	 * that already carries a real category is never re-touched regardless of
+	 * what this returns.
 	 */
-	private classifyMessage(
+	private async classifyMessage(
+		accountConfigId: string,
 		parsed: ParsedMail,
-	): UpdateMessageInput & { category: ThreadMessageCategory } {
-		const category = classifyByHeaders(parsed);
+	): Promise<UpdateMessageInput & { category: ThreadMessageCategory }> {
+		const headerCategory = classifyByHeaders(parsed);
 		const authenticity = extractAuthenticity(parsed);
 		const authResult = extractAuthResult(parsed);
 		const providerSpam = extractProviderSpam(parsed);
 		const hasListUnsubscribe = extractHasListUnsubscribe(parsed);
+
+		const fromEmail = extractPrimaryFromEmail(parsed);
+		const categoryOverride = fromEmail
+			? await this.resolveCategoryOverride(accountConfigId, fromEmail)
+			: undefined;
+
 		return {
-			category,
+			category: categoryOverride ?? headerCategory,
 			hasListUnsubscribe,
 			...(authenticity !== null ? { authenticity } : {}),
 			...(authResult !== null ? { authResult } : {}),
@@ -1069,6 +1112,36 @@ export class BodySyncService {
 		};
 	}
 
+	/**
+	 * The one-sided half of `Address.flags.category` (issue #299, RFC 039
+	 * Decision 3): a real value here overrides `classifyByHeaders` outright.
+	 * A second, separate `Address` read from `deriveSenderPlacementSignals`'s
+	 * (issue #300) — sharing one fetch was not practical, because the two have
+	 * different failure contracts: placement's read is best-effort (a failure
+	 * is caught and logged, never failing the sync), while this one feeds the
+	 * write-once `Message.category` at the moment it is decided, where a
+	 * masked infra failure would silently classify by headers when the user
+	 * asked for something else. Only a genuinely-absent Address is "no
+	 * override" — any other failure (throttle, infra) propagates, matching the
+	 * existing `deriveSenderPlacementSignals` convention.
+	 */
+	private async resolveCategoryOverride(
+		accountConfigId: string,
+		fromEmail: string,
+	): Promise<ThreadMessageCategory | undefined> {
+		try {
+			const addressId = deriveAddressId(accountConfigId, fromEmail);
+			const address = await this.addressService.getAddress(
+				accountConfigId,
+				addressId,
+			);
+			return address.flags?.category?.value;
+		} catch (err) {
+			if (!(err instanceof NotFoundError)) throw err;
+			return undefined;
+		}
+	}
+
 	private async incrementInboundCount(
 		messageId: string,
 		accountConfigId: string,
@@ -1682,47 +1755,6 @@ export class BodySyncService {
 		}
 	}
 
-	/**
-	 * Extract snippet, header category and the normalized `List-Id` from the body
-	 * and denormalize them onto the ThreadMessage. `category` mirrors the Message:
-	 * created as `uncategorized` at metadata-sync and set to the classified value
-	 * here; `listId` is written so the back-apply corpus projection can match a
-	 * `ListId` clause vector-free, off the same row the list/search path reads.
-	 * Returns the parsed mail so callers can reuse it (e.g., to write the
-	 * parsed-body cache) without paying for mailparser twice.
-	 */
-	private async updateSnippets(
-		messageId: string,
-		accountConfigId: string,
-		body: Buffer,
-	): Promise<ParsedMail> {
-		// The one operation on this path that can fail because of how the message
-		// is built. Its own try block lives in `parseMessageBody`, so the caller's
-		// frame — which also wraps the S3 body write, the parsed-body cache, the
-		// placement move, the label writes and the counter update — can tell the
-		// two apart and quarantine only this one (issue #72).
-		const parsed = await parseMessageBody(body);
-
-		const snippet = extractSnippet(parsed);
-		const category = classifyByHeaders(parsed);
-		const listId = extractListId(parsed);
-
-		await this.denormalizeCategory(
-			accountConfigId,
-			messageId,
-			category,
-			snippet,
-			listId,
-		);
-
-		this.log.debug?.(
-			{ messageId, category, snippetLength: snippet?.length ?? 0 },
-			"ThreadMessage snippet + category updated",
-		);
-
-		return parsed;
-	}
-
 	/**
 	 * Write the denormalized `category` (and optionally the snippet and the
 	 * normalized `List-Id`) onto EVERY ThreadMessage row the message has — the