@remit/mailbox-service 0.0.93 → 0.0.95

package/package.json

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

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

@@ -343,8 +343,9 @@ describe("Address.flags.category overrides classification at sync time (issue #2
 		);
 
 		// The harness's default `retrieve` throws, so a storage read would fail
-		// this outright. Issue #415 is where applying the override to this message
-		// deliberately belongs; a sync pass is not it.
+		// this outright. Reaching back is the back-apply job's work (#415,
+		// `backApplySenderCategory`), fired by the flag PATCH; a sync pass is
+		// still not it.
 		assert.equal(result.skippedCount, 1);
 		assert.deepEqual(result.failedMessageIds, []);
 		assert.deepEqual(harness.messageUpdates, []);

package/src/body-sync.ts

@@ -59,9 +59,10 @@ import {
 	classifyPlacement,
 	type FolderPlacement,
 	type PlacementVerdict,
-	resolveBlockedVsTrust,
+	resolveSenderPlacement,
 } from "./heuristics/classifyPlacement.js";
 import { extractSenderMismatch } from "./heuristics/senderMismatch.js";
+import { denormalizeMessageCategory } from "./message-category.js";
 import type { PlacementMoveService } from "./placement-move.js";
 import { type QuarantineService, shapeFromMessageData } from "./quarantine.js";
 import { extractSnippetFromEmail } from "./snippet.js";
@@ -165,23 +166,6 @@ const extractSnippet = (parsed: ParsedMail): string =>
 		SNIPPET_LENGTH,
 	);
 
-/**
- * A row is skipped only when every field the denormalization would write
- * already matches. `snippet` and `listId` are absent from the update when the
- * message has neither, and an absent field is not a mismatch.
- */
-const alreadyDenormalized = (
-	row: ThreadMessageItem,
-	update: {
-		category: ThreadMessageCategory;
-		snippet?: string;
-		listId?: string;
-	},
-): boolean =>
-	row.category === update.category &&
-	(update.snippet === undefined || row.snippet === update.snippet) &&
-	(update.listId === undefined || row.listId === update.listId);
-
 /**
  * RFC 034 Decision 3.1: `Message.category` is written once and never mutated
  * after — RFC 030's message-list GSI sort key depends on it never churning.
@@ -928,12 +912,11 @@ export class BodySyncService {
 
 		// 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(
+		await denormalizeMessageCategory(
+			{ threadMessageService: this.threadMessageService },
 			accountConfigId,
 			messageId,
-			finalCategory,
-			snippet,
-			listId,
+			{ category: finalCategory, snippet, listId },
 		);
 
 		// `classificationState` records that the classifier ran, in the same
@@ -1193,7 +1176,7 @@ export class BodySyncService {
 	 * `deriveSenderTrust` always did — `vip → wellknown → unknown`, untouched by
 	 * `blocked` — plus `blocked`/`autoArchive` off the same row. `trustSetAt` is
 	 * the `setAt` of whichever flag produced the trust value, needed by
-	 * {@link resolveBlockedVsTrust}'s tie-break; it stays local to placement and
+	 * {@link resolveSenderPlacement}'s tie-break; it stays local to placement and
 	 * never reaches `deriveSenderTrust`'s own contract (the trust badge).
 	 */
 	private async deriveSenderPlacementSignals(
@@ -1204,11 +1187,13 @@ export class BodySyncService {
 		trustSetAt?: number;
 		blocked: boolean;
 		blockedSetAt?: number;
+		neverSpam: boolean;
 		autoArchive: boolean;
 	}> {
 		const unknown = {
 			trust: SenderTrust.Unknown,
 			blocked: false,
+			neverSpam: false,
 			autoArchive: false,
 		} as const;
 		try {
@@ -1224,6 +1209,7 @@ export class BodySyncService {
 					trustSetAt: flags.vip.setAt,
 					blocked: flags.blocked?.value === true,
 					blockedSetAt: flags.blocked?.setAt,
+					neverSpam: flags.neverSpam?.value === true,
 					autoArchive: flags.autoArchive?.value === true,
 				};
 			}
@@ -1233,6 +1219,7 @@ export class BodySyncService {
 					trustSetAt: flags.wellknown.setAt,
 					blocked: flags.blocked?.value === true,
 					blockedSetAt: flags.blocked?.setAt,
+					neverSpam: flags.neverSpam?.value === true,
 					autoArchive: flags.autoArchive?.value === true,
 				};
 			}
@@ -1240,6 +1227,7 @@ export class BodySyncService {
 				...unknown,
 				blocked: flags?.blocked?.value === true,
 				blockedSetAt: flags?.blocked?.setAt,
+				neverSpam: flags?.neverSpam?.value === true,
 				autoArchive: flags?.autoArchive?.value === true,
 			};
 		} catch (err) {
@@ -1531,12 +1519,14 @@ export class BodySyncService {
 			: {
 					trust: SenderTrust.Unknown,
 					blocked: false,
+					neverSpam: false,
 					autoArchive: false,
 				};
 
-		const { senderTrust, senderBlocked } = resolveBlockedVsTrust(
+		const { senderTrust, senderOverride } = resolveSenderPlacement(
 			{ trust: signals.trust, setAt: signals.trustSetAt },
 			{ blocked: signals.blocked, setAt: signals.blockedSetAt },
+			signals.neverSpam,
 		);
 
 		// The verdict needs the classification signals (providerSpam,
@@ -1547,7 +1537,7 @@ export class BodySyncService {
 			candidate,
 			placement,
 			senderTrust,
-			senderBlocked,
+			senderOverride,
 		);
 
 		// A `leave` verdict — including "nothing confident to say" — carries no
@@ -1891,73 +1881,4 @@ export class BodySyncService {
 			throw err;
 		}
 	}
-
-	/**
-	 * Write the denormalized `category` (and optionally the snippet and the
-	 * normalized `List-Id`) onto EVERY ThreadMessage row the message has — the
-	 * copy the list/search read path serves without a per-row Message fetch.
-	 *
-	 * More than one row per messageId is schema-legal but not normally produced,
-	 * and this iterates for the same reason `message-move.ts` does (see the model
-	 * stated at its `deleteThreadMessagesForMessage`): the key permits it and
-	 * nothing enforces otherwise. It is NOT the second mailbox a message appears
-	 * in — `deriveMessageId` and `deriveThreadMessageId` are both
-	 * mailbox-independent, so INBOX and Archive resolve to one row, and a copy
-	 * gets its own messageId. The reachable case is thread-root drift: the same
-	 * message re-saved under different `References`, which mints a second
-	 * threadId and so a second row. Iterating is therefore hardening against a
-	 * legal state, not a repair for one the sync path manufactures, which is why
-	 * the tree's other single-row `messageId` lookups are correct as they stand.
-	 * `flag-queue.ts` iterates the same list.
-	 *
-	 * Rows are looked up by messageId, so this does not depend on the RFC822
-	 * Message-ID header — a headerless message still gets denormalized, matching
-	 * the unconditional Message.category write. The composite set is built per
-	 * row, never reused: `mailboxId` and `isRead` can differ between two rows for
-	 * one message, and it is passed at all so that a future key-attribute
-	 * addition touching the lsi3/lsi4/lsi5/gsi2 sort keys keeps the index rows
-	 * consistent.
-	 */
-	private async denormalizeCategory(
-		accountConfigId: string,
-		messageId: string,
-		category: ThreadMessageCategory,
-		snippet?: string,
-		listId?: string,
-	): Promise<void> {
-		const rows = await this.threadMessageService.findAllByMessageId(
-			accountConfigId,
-			messageId,
-		);
-		if (rows.length === 0) {
-			throw new NotFoundError(
-				`ThreadMessage not found for message ${messageId}`,
-			);
-		}
-
-		const update = {
-			category,
-			...(snippet ? { snippet } : {}),
-			...(listId ? { listId } : {}),
-		};
-
-		for (const row of rows) {
-			if (alreadyDenormalized(row, update)) continue;
-			await this.threadMessageService.update(
-				accountConfigId,
-				row.threadMessageId,
-				update,
-				{
-					composites: {
-						sentDate: row.sentDate,
-						mailboxId: row.mailboxId,
-						isRead: row.isRead,
-						isDeleted: row.isDeleted,
-						hasStars: row.hasStars,
-						hasAttachment: row.hasAttachment,
-					},
-				},
-			);
-		}
-	}
 }

package/src/heuristics/classifyPlacement.test.ts

@@ -1,20 +1,21 @@
 /**
  * `classifyPlacement` had no dedicated unit test — only the DKIM/DMARC paths
  * were exercised indirectly through realistic-mail fixtures elsewhere. Issue
- * #300 (RFC 039 Decision 3/3a) adds `senderBlocked` as a confident demote
- * independent of every DKIM/DMARC/provider signal, plus a `setAt` tie-break
- * against `vip`/`wellknown` (Decision 3a, `resolveBlockedVsTrust`). These tests
- * cover both the new branch and the pre-existing DKIM/DMARC branches, so a
- * regression in either shows up here.
+ * #300 (RFC 039 Decision 3/3a) added the user's placement instruction as a
+ * confident move independent of every DKIM/DMARC/provider signal, plus a
+ * `setAt` tie-break against `vip`/`wellknown` (Decision 3a). Issue #605 adds
+ * the other direction, `neverSpam`. These tests cover both instruction
+ * branches and the pre-existing DKIM/DMARC branches, so a regression in any of
+ * them shows up here.
  */
 
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import type { MessageItem } from "@remit/data-ports";
-import { SenderTrust } from "@remit/domain-enums";
+import { SenderOverride, SenderTrust } from "@remit/domain-enums";
 import {
 	classifyPlacement,
-	resolveBlockedVsTrust,
+	resolveSenderPlacement,
 } from "./classifyPlacement.js";
 
 const baseMessage = (overrides: Partial<MessageItem> = {}): MessageItem =>
@@ -28,7 +29,7 @@ const baseMessage = (overrides: Partial<MessageItem> = {}): MessageItem =>
 	}) as unknown as MessageItem;
 
 describe("classifyPlacement", () => {
-	describe("senderBlocked (RFC 039 Decision 3)", () => {
+	describe("SenderOverride.Blocked (RFC 039 Decision 3)", () => {
 		it("demotes an inbox message from a blocked sender, independent of DKIM/DMARC", () => {
 			const message = baseMessage({
 				providerSpam: undefined,
@@ -38,7 +39,7 @@ describe("classifyPlacement", () => {
 				message,
 				"inbox",
 				SenderTrust.Unknown,
-				true,
+				SenderOverride.Blocked,
 			);
 			assert.deepEqual(verdict, {
 				action: "move-to-junk",
@@ -52,7 +53,7 @@ describe("classifyPlacement", () => {
 				baseMessage(),
 				"other",
 				SenderTrust.Unknown,
-				true,
+				SenderOverride.Blocked,
 			);
 			assert.equal(verdict.action, "move-to-junk");
 			assert.equal(verdict.confidence, "confident");
@@ -63,17 +64,17 @@ describe("classifyPlacement", () => {
 				baseMessage(),
 				"junk",
 				SenderTrust.Unknown,
-				true,
+				SenderOverride.Blocked,
 			);
 			assert.notEqual(verdict.action, "move-to-junk");
 		});
 
-		it("does not demote when the sender is not blocked, all else equal", () => {
+		it("does not demote when the sender carries no instruction, all else equal", () => {
 			const verdict = classifyPlacement(
 				baseMessage({ providerSpam: undefined, authResult: undefined }),
 				"inbox",
 				SenderTrust.Unknown,
-				false,
+				SenderOverride.None,
 			);
 			assert.deepEqual(verdict, {
 				action: "leave",
@@ -87,7 +88,7 @@ describe("classifyPlacement", () => {
 				baseMessage({ movedByRemit: true }),
 				"inbox",
 				SenderTrust.Unknown,
-				true,
+				SenderOverride.Blocked,
 			);
 			assert.deepEqual(verdict, {
 				action: "leave",
@@ -97,70 +98,221 @@ describe("classifyPlacement", () => {
 		});
 	});
 
-	describe("resolveBlockedVsTrust (Decision 3a tie-break)", () => {
+	describe("SenderOverride.NeverSpam (issue #605)", () => {
+		it("rescues mail the provider rated clean from a domain that publishes no DMARC", () => {
+			const verdict = classifyPlacement(
+				baseMessage({
+					providerSpam: { classified: false },
+					authResult: { dmarc: "None" },
+				}),
+				"junk",
+				SenderTrust.Unknown,
+				SenderOverride.NeverSpam,
+			);
+			assert.deepEqual(verdict, {
+				action: "move-to-inbox",
+				confidence: "confident",
+				reasons: ["sender=never-spam"],
+			});
+		});
+
+		it("rescues before the missing-signals return, so a message with no parsed signals still comes out of junk", () => {
+			const verdict = classifyPlacement(
+				baseMessage({ providerSpam: undefined, authResult: undefined }),
+				"junk",
+				SenderTrust.Unknown,
+				SenderOverride.NeverSpam,
+			);
+			assert.equal(verdict.action, "move-to-inbox");
+			assert.equal(verdict.confidence, "confident");
+		});
+
+		it("leaves a never-spam sender's mail filed in a user folder where it is", () => {
+			const verdict = classifyPlacement(
+				baseMessage(),
+				"other",
+				SenderTrust.Unknown,
+				SenderOverride.NeverSpam,
+			);
+			assert.equal(verdict.action, "leave");
+		});
+
+		// The demote branch is reached only from `inbox`, so a spoof already in
+		// Junk never meets it. Without the guard on the rescue, the grant would
+		// carry mail impersonating the granted address out of Junk.
+		it("refuses to rescue a dkim-mismatch + dmarc-fail spoof sitting in junk", () => {
+			const verdict = classifyPlacement(
+				baseMessage({
+					providerSpam: { classified: true },
+					authResult: { dmarc: "Fail" },
+					authenticity: { fromDomain: "example.com", dkimMismatch: true },
+				}),
+				"junk",
+				SenderTrust.Unknown,
+				SenderOverride.NeverSpam,
+			);
+			assert.notEqual(verdict.action, "move-to-inbox");
+		});
+
+		it("refuses to rescue on a hard DMARC failure even with DKIM aligned", () => {
+			const verdict = classifyPlacement(
+				baseMessage({
+					providerSpam: { classified: true },
+					authResult: { dmarc: "Fail" },
+				}),
+				"junk",
+				SenderTrust.Unknown,
+				SenderOverride.NeverSpam,
+			);
+			assert.notEqual(verdict.action, "move-to-inbox");
+		});
+
+		it("refuses to rescue on a DKIM mismatch even where DMARC did not fail", () => {
+			const verdict = classifyPlacement(
+				baseMessage({
+					providerSpam: { classified: true },
+					authResult: { dmarc: "None" },
+					authenticity: { fromDomain: "example.com", dkimMismatch: true },
+				}),
+				"junk",
+				SenderTrust.Unknown,
+				SenderOverride.NeverSpam,
+			);
+			assert.notEqual(verdict.action, "move-to-inbox");
+		});
+
+		it("still demotes a never-spam sender's inbox mail on dkim-mismatch + dmarc-fail", () => {
+			const verdict = classifyPlacement(
+				baseMessage({
+					authResult: { dmarc: "Fail" },
+					authenticity: { fromDomain: "example.com", dkimMismatch: true },
+				}),
+				"inbox",
+				SenderTrust.Unknown,
+				SenderOverride.NeverSpam,
+			);
+			assert.deepEqual(verdict, {
+				action: "move-to-junk",
+				confidence: "confident",
+				reasons: ["dkim-mismatch", "dmarc=fail", "sender=untrusted"],
+			});
+		});
+
+		it("still leaves an already-Remit-moved message alone", () => {
+			const verdict = classifyPlacement(
+				baseMessage({ movedByRemit: true }),
+				"junk",
+				SenderTrust.Unknown,
+				SenderOverride.NeverSpam,
+			);
+			assert.deepEqual(verdict, {
+				action: "leave",
+				confidence: "confident",
+				reasons: ["already-moved-by-remit"],
+			});
+		});
+	});
+
+	describe("resolveSenderPlacement (Decision 3a tie-break)", () => {
 		it("blocked wins when set after vip", () => {
-			const result = resolveBlockedVsTrust(
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Vip, setAt: 1_000 },
 				{ blocked: true, setAt: 5_000 },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Unknown,
-				senderBlocked: true,
+				senderOverride: SenderOverride.Blocked,
 			});
 		});
 
 		it("vip wins when set after blocked", () => {
-			const result = resolveBlockedVsTrust(
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Vip, setAt: 5_000 },
 				{ blocked: true, setAt: 1_000 },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Vip,
-				senderBlocked: false,
+				senderOverride: SenderOverride.None,
 			});
 		});
 
 		it("breaks a same-second tie in favor of blocked", () => {
-			const result = resolveBlockedVsTrust(
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Wellknown, setAt: 1_000 },
 				{ blocked: true, setAt: 1_400 },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Unknown,
-				senderBlocked: true,
+				senderOverride: SenderOverride.Blocked,
 			});
 		});
 
 		it("blocked applies outright when there is no competing trust flag", () => {
-			const result = resolveBlockedVsTrust(
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Unknown },
 				{ blocked: true, setAt: 1_000 },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Unknown,
-				senderBlocked: true,
+				senderOverride: SenderOverride.Blocked,
 			});
 		});
 
-		it("passes trust through unchanged when the sender isn't blocked", () => {
-			const result = resolveBlockedVsTrust(
+		it("passes trust through unchanged when the sender carries no instruction", () => {
+			const result = resolveSenderPlacement(
 				{ trust: SenderTrust.Wellknown, setAt: 1_000 },
 				{ blocked: false },
+				false,
 			);
 			assert.deepEqual(result, {
 				senderTrust: SenderTrust.Wellknown,
-				senderBlocked: false,
+				senderOverride: SenderOverride.None,
 			});
 		});
+
+		it("reads never-spam as the instruction, leaving trust untouched", () => {
+			const result = resolveSenderPlacement(
+				{ trust: SenderTrust.Unknown },
+				{ blocked: false },
+				true,
+			);
+			assert.deepEqual(result, {
+				senderTrust: SenderTrust.Unknown,
+				senderOverride: SenderOverride.NeverSpam,
+			});
+		});
+
+		it("does not promote a never-spam sender's trust to vip or wellknown", () => {
+			const result = resolveSenderPlacement(
+				{ trust: SenderTrust.Vip, setAt: 1_000 },
+				{ blocked: false },
+				true,
+			);
+			assert.equal(result.senderTrust, SenderTrust.Vip);
+			assert.equal(result.senderOverride, SenderOverride.NeverSpam);
+		});
+
+		it("resolves a row that somehow carries both instructions to blocked", () => {
+			const result = resolveSenderPlacement(
+				{ trust: SenderTrust.Unknown },
+				{ blocked: true, setAt: 1_000 },
+				true,
+			);
+			assert.equal(result.senderOverride, SenderOverride.Blocked);
+		});
 	});
 
-	describe("existing DKIM/DMARC paths (unaffected by senderBlocked=false)", () => {
+	describe("existing DKIM/DMARC paths (unaffected by SenderOverride.None)", () => {
 		it("rescues a trusted sender's mail from junk on provider-spam + dmarc-pass", () => {
 			const verdict = classifyPlacement(
 				baseMessage({ providerSpam: { classified: true } }),
 				"junk",
 				SenderTrust.Vip,
-				false,
+				SenderOverride.None,
 			);
 			assert.equal(verdict.action, "move-to-inbox");
 			assert.equal(verdict.confidence, "confident");
@@ -171,7 +323,7 @@ describe("classifyPlacement", () => {
 				baseMessage({ providerSpam: { classified: true } }),
 				"junk",
 				SenderTrust.Unknown,
-				false,
+				SenderOverride.None,
 			);
 			assert.equal(verdict.action, "leave");
 			assert.equal(verdict.confidence, "unsure");
@@ -185,7 +337,7 @@ describe("classifyPlacement", () => {
 				}),
 				"inbox",
 				SenderTrust.Unknown,
-				false,
+				SenderOverride.None,
 			);
 			assert.deepEqual(verdict, {
 				action: "move-to-junk",
@@ -202,7 +354,7 @@ describe("classifyPlacement", () => {
 				}),
 				"inbox",
 				SenderTrust.Unknown,
-				false,
+				SenderOverride.None,
 			);
 			assert.deepEqual(verdict, {
 				action: "leave",

package/src/heuristics/classifyPlacement.ts

@@ -1,8 +1,10 @@
 import type { MessageItem } from "@remit/data-ports";
-import { SenderTrust } from "@remit/domain-enums";
+import { SenderOverride, SenderTrust } from "@remit/domain-enums";
 
 type SenderTrustValue = (typeof SenderTrust)[keyof typeof SenderTrust];
 
+type SenderOverrideValue = (typeof SenderOverride)[keyof typeof SenderOverride];
+
 export type FolderPlacement = "inbox" | "junk" | "other";
 
 export type PlacementAction = "move-to-inbox" | "move-to-junk" | "leave";
@@ -39,7 +41,7 @@ export interface SenderBlockedSignal {
  * fixed, arbitrary order: `blocked` before `vip` before `wellknown` — a
  * determinism backstop, not a meaningful signal.
  */
-export const resolveBlockedVsTrust = (
+const resolveBlockedVsTrust = (
 	trust: SenderTrustSignal,
 	blocked: SenderBlockedSignal,
 ): { senderTrust: SenderTrustValue; senderBlocked: boolean } => {
@@ -60,6 +62,32 @@ export const resolveBlockedVsTrust = (
 	return { senderTrust: trust.trust, senderBlocked: false };
 };
 
+/**
+ * Resolve the two axes {@link classifyPlacement} takes: the trust signal, and
+ * the user's standing instruction about placement.
+ *
+ * `blocked` and `neverSpam` are two directly contradictory instructions and
+ * cannot both stand — `AddressRepository.mergeFlags` drops the loser at write
+ * time. Reading a row that carries both anyway (written before that invariant)
+ * resolves to `Blocked`, the same direction the `blocked`/`vip` same-second tie
+ * already breaks in: the demote is the recoverable mistake.
+ */
+export const resolveSenderPlacement = (
+	trust: SenderTrustSignal,
+	blocked: SenderBlockedSignal,
+	neverSpam: boolean,
+): {
+	senderTrust: SenderTrustValue;
+	senderOverride: SenderOverrideValue;
+} => {
+	const { senderTrust, senderBlocked } = resolveBlockedVsTrust(trust, blocked);
+	if (senderBlocked)
+		return { senderTrust, senderOverride: SenderOverride.Blocked };
+	if (neverSpam)
+		return { senderTrust, senderOverride: SenderOverride.NeverSpam };
+	return { senderTrust, senderOverride: SenderOverride.None };
+};
+
 /**
  * Tier 0 deterministic placement verdict (RFC 031, "Confident moves").
  *
@@ -69,17 +97,32 @@ export const resolveBlockedVsTrust = (
  * recall-biased — a confident move only fires when cheap, deterministic signals
  * agree; everything else is left in place for a later LLM tier.
  *
- * `senderBlocked` (RFC 039 Decision 3) is a confident demote independent of
- * every DKIM/DMARC/provider signal below — a user's explicit block is not a
- * heuristic. Already-tie-broken against `vip`/`wellknown` by
- * {@link resolveBlockedVsTrust} in the caller; this function itself does not
+ * `senderOverride` (RFC 039 Decision 3, issue #605) is the user's standing
+ * instruction about this sender's placement, and it outranks every
+ * DKIM/DMARC/provider signal below — an explicit block or never-spam grant is
+ * not a heuristic. Already-tie-broken against `vip`/`wellknown` by
+ * {@link resolveSenderPlacement} in the caller; this function itself does not
  * compare `setAt`.
+ *
+ * `NeverSpam` is checked above the `missing-signals` return and above the
+ * `providerSpam.classified` gate on purpose: the senders who need the grant are
+ * the ones the provider rated clean and whose domain publishes no DMARC record,
+ * so a check inside the rescue branch below would never fire for them. It
+ * rescues only from `junk` — a message a standing filter put in a user folder
+ * is not a spam question.
+ *
+ * It refuses outright on a `dmarc === "Fail"` or a DKIM mismatch. The demote
+ * branch below is reached only from `inbox`, so a spoof already sitting in Junk
+ * would never meet it: without this guard the grant would launder mail out of
+ * Junk on exactly the two signals that identify someone impersonating the
+ * address the user granted. A domain that publishes no DMARC record never
+ * scores `Fail`, so the case the grant exists for is untouched.
  */
 export const classifyPlacement = (
 	message: MessageItem,
 	placement: FolderPlacement,
 	senderTrust: SenderTrustValue,
-	senderBlocked: boolean,
+	senderOverride: SenderOverrideValue,
 ): PlacementVerdict => {
 	if (message.movedByRemit === true) {
 		return {
@@ -89,7 +132,7 @@ export const classifyPlacement = (
 		};
 	}
 
-	if (senderBlocked && placement !== "junk") {
+	if (senderOverride === SenderOverride.Blocked && placement !== "junk") {
 		return {
 			action: "move-to-junk",
 			confidence: "confident",
@@ -97,6 +140,19 @@ export const classifyPlacement = (
 		};
 	}
 
+	if (
+		senderOverride === SenderOverride.NeverSpam &&
+		placement === "junk" &&
+		message.authResult?.dmarc !== "Fail" &&
+		message.authenticity?.dkimMismatch !== true
+	) {
+		return {
+			action: "move-to-inbox",
+			confidence: "confident",
+			reasons: ["sender=never-spam"],
+		};
+	}
+
 	if (!message.providerSpam || !message.authResult) {
 		return {
 			action: "leave",

package/src/index.ts

@@ -193,6 +193,12 @@ export {
 	MailboxSyncService,
 	type SyncAccountInfo,
 } from "./mailbox-sync.js";
+export {
+	denormalizeMessageCategory,
+	type MessageCategoryDenormalizeDeps,
+	type MessageCategoryDenormalizeInput,
+	type MessageCategoryValue,
+} from "./message-category.js";
 export {
 	type DeleteMessagesOutcome,
 	type DeleteOptions,

package/src/message-category.ts

@@ -0,0 +1,100 @@
+import type {
+	IThreadMessageRepository,
+	ThreadMessageItem,
+} from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+
+export type MessageCategoryValue = ThreadMessageItem["category"];
+
+export interface MessageCategoryDenormalizeDeps {
+	threadMessageService: Pick<
+		IThreadMessageRepository,
+		"findAllByMessageId" | "update"
+	>;
+}
+
+export interface MessageCategoryDenormalizeInput {
+	category: MessageCategoryValue;
+	snippet?: string;
+	listId?: string;
+}
+
+/**
+ * A row is skipped only when every field the denormalization would write
+ * already matches. `snippet` and `listId` are absent from the update when the
+ * message has neither, and an absent field is not a mismatch.
+ */
+const alreadyDenormalized = (
+	row: ThreadMessageItem,
+	update: MessageCategoryDenormalizeInput,
+): boolean =>
+	row.category === update.category &&
+	(update.snippet === undefined || row.snippet === update.snippet) &&
+	(update.listId === undefined || row.listId === update.listId);
+
+/**
+ * Write a message's category (and, when the caller has them, its snippet and
+ * `List-Id`) onto every ThreadMessage row that indexes it. The thread row is
+ * what the message list renders and what the category filter matches, so it
+ * must never disagree with the Message row it mirrors.
+ *
+ * More than one row per messageId is schema-legal but not normally produced,
+ * and this iterates for the same reason `message-move.ts` does (see the model
+ * stated at its `deleteThreadMessagesForMessage`): the key permits it and
+ * nothing enforces otherwise. It is NOT the second mailbox a message appears
+ * in — `deriveMessageId` and `deriveThreadMessageId` are both
+ * mailbox-independent, so INBOX and Archive resolve to one row, and a copy
+ * gets its own messageId. The reachable case is thread-root drift: the same
+ * message re-saved under different `References`, which mints a second
+ * threadId and so a second row. Iterating is therefore hardening against a
+ * legal state, not a repair for one the sync path manufactures, which is why
+ * the tree's other single-row `messageId` lookups are correct as they stand.
+ * `flag-queue.ts` iterates the same list.
+ *
+ * Rows are looked up by messageId, so this does not depend on the RFC822
+ * Message-ID header — a headerless message still gets denormalized, matching
+ * the unconditional Message.category write. The composite set is built per
+ * row, never reused: `mailboxId` and `isRead` can differ between two rows for
+ * one message, and it is passed at all so that a future key-attribute
+ * addition touching the lsi3/lsi4/lsi5/gsi2 sort keys keeps the index rows
+ * consistent.
+ */
+export const denormalizeMessageCategory = async (
+	deps: MessageCategoryDenormalizeDeps,
+	accountConfigId: string,
+	messageId: string,
+	update: MessageCategoryDenormalizeInput,
+): Promise<void> => {
+	const rows = await deps.threadMessageService.findAllByMessageId(
+		accountConfigId,
+		messageId,
+	);
+	if (rows.length === 0) {
+		throw new NotFoundError(`ThreadMessage not found for message ${messageId}`);
+	}
+
+	const written = {
+		category: update.category,
+		...(update.snippet ? { snippet: update.snippet } : {}),
+		...(update.listId ? { listId: update.listId } : {}),
+	};
+
+	for (const row of rows) {
+		if (alreadyDenormalized(row, written)) continue;
+		await deps.threadMessageService.update(
+			accountConfigId,
+			row.threadMessageId,
+			written,
+			{
+				composites: {
+					sentDate: row.sentDate,
+					mailboxId: row.mailboxId,
+					isRead: row.isRead,
+					isDeleted: row.isDeleted,
+					hasStars: row.hasStars,
+					hasAttachment: row.hasAttachment,
+				},
+			},
+		);
+	}
+};