@remit/mailbox-service 0.0.31 → 0.0.32

package/package.json

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

package/src/body-sync-placement-flags.test.ts

@@ -0,0 +1,302 @@
+/**
+ * Issue #300 (RFC 039 Decision 3/3a): `Address.flags.blocked`/`autoArchive`
+ * were written by the UI and promised in product copy ("Blocked senders...
+ * go straight to junk") but `classifyPlacement` never read them. These tests
+ * drive `BodySyncService` end-to-end (read-path body materialization →
+ * `applyPostStoreSteps` → `resolvePlacement` → the placement move) and assert
+ * on the actual move call, so a regression that drops the flag read — not
+ * just the `classifyPlacement` branch — shows up here.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	AddressItem,
+	IAddressRepository,
+	IEnvelopeRepository,
+	IMailboxSpecialUseRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+	UpdateMessageInput,
+} from "@remit/data-ports";
+import { MailboxSpecialUse } from "@remit/domain-enums";
+import type { StorageService } from "@remit/storage-service";
+import type { PlacementConfig } from "./body-sync.js";
+import { BodySyncService } from "./body-sync.js";
+import type { PlacementMoveService } from "./placement-move.js";
+import type { IImapConnection } from "./types.js";
+
+const PLAIN_EML = Buffer.from(
+	[
+		"From: Sender <someone@example.com>",
+		"To: me@example.com",
+		"Subject: Hello",
+		"Content-Type: text/plain",
+		"",
+		"body",
+	].join("\r\n"),
+);
+
+/** Carries the provider-spam + dmarc-pass signals the pre-existing junk→inbox rescue needs (independent of this issue). */
+const SPAM_FLAGGED_DMARC_PASS_EML = Buffer.from(
+	[
+		"From: Sender <someone@example.com>",
+		"To: me@example.com",
+		"Subject: Hello",
+		"Authentication-Results: mx.example.com; dmarc=pass",
+		"X-Spam-Status: Yes, score=6.0",
+		"Content-Type: text/plain",
+		"",
+		"body",
+	].join("\r\n"),
+);
+
+interface MoveCall {
+	messageId: string;
+	destinationMailboxId: string;
+}
+
+interface Harness {
+	service: BodySyncService;
+	moves: MoveCall[];
+	messageUpdates: Array<{ messageId: string; input: UpdateMessageInput }>;
+}
+
+const MAILBOXES = {
+	inbox: { mailboxId: "mb-inbox", fullPath: "INBOX" },
+	junk: { mailboxId: "mb-junk", fullPath: "Junk" },
+	archive: { mailboxId: "mb-archive", fullPath: "Archive" },
+};
+
+const buildHarness = (
+	message: { messageId: string; mailboxId: string },
+	flags: AddressItem["flags"],
+): Harness => {
+	const moves: MoveCall[] = [];
+	const messageUpdates: Array<{
+		messageId: string;
+		input: UpdateMessageInput;
+	}> = [];
+
+	const messageService = {
+		get: async () => ({
+			messageId: message.messageId,
+			mailboxId: message.mailboxId,
+			uid: 1,
+		}),
+		update: async (messageId: string, input: UpdateMessageInput) => {
+			messageUpdates.push({ messageId, input });
+		},
+	} as unknown as IMessageRepository;
+
+	const threadMessageService = {
+		findAllByMessageId: async () => [
+			{
+				threadMessageId: "tm-1",
+				sentDate: 1,
+				mailboxId: message.mailboxId,
+				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 () => ({ flags }) as unknown as AddressItem,
+		incrementInboundCount: async () => {},
+	} as unknown as IAddressRepository;
+
+	const envelopeService = {
+		listBodyParts: async () => [],
+	} as unknown as IEnvelopeRepository;
+
+	const mailboxSpecialUseService = {
+		findBySpecialUse: async (_accountId: string, specialUse: string) => {
+			if (specialUse === MailboxSpecialUse.Junk) return MAILBOXES.junk;
+			if (specialUse === MailboxSpecialUse.Archive) return MAILBOXES.archive;
+			return null;
+		},
+		findInboxMailbox: async () => MAILBOXES.inbox,
+	} as unknown as IMailboxSpecialUseRepository;
+
+	const placementMoveService = {
+		moveMessage: async (
+			_accountConfigId: string,
+			messageId: string,
+			destinationMailboxId: string,
+		) => {
+			moves.push({ messageId, destinationMailboxId });
+		},
+	} as unknown as PlacementMoveService;
+
+	const placementConfig: PlacementConfig = {
+		mailboxSpecialUseService,
+		placementMoveService,
+	};
+
+	const service = new BodySyncService(
+		messageService,
+		storageService,
+		threadMessageService,
+		addressService,
+		envelopeService,
+		{ info: () => {}, error: () => {} },
+		placementConfig,
+	);
+
+	return { service, moves, messageUpdates };
+};
+
+const readBody = async (
+	service: BodySyncService,
+	mailboxPath = "INBOX",
+	body: Buffer = PLAIN_EML,
+) => {
+	const connection = {
+		openBox: async () => {},
+		fetchMessageBody: async () => body,
+	} as unknown as IImapConnection;
+	return service.fetchAndGetBody(
+		"m-1",
+		"acc-1",
+		"cfg-1",
+		mailboxPath,
+		async () => connection,
+	);
+};
+
+const flagsAt = (
+	setAt: number,
+): { blocked: { value: true; setAt: number } } => ({
+	blocked: { value: true, setAt },
+});
+
+describe("Address.flags.blocked drives placement (issue #300)", () => {
+	it("moves an inbox message from a blocked sender to junk, with no DKIM/DMARC signal at all", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", mailboxId: MAILBOXES.inbox.mailboxId },
+			flagsAt(1_000),
+		);
+
+		await readBody(harness.service);
+
+		assert.deepEqual(harness.moves, [
+			{ messageId: "m-1", destinationMailboxId: MAILBOXES.junk.mailboxId },
+		]);
+		assert.equal(harness.messageUpdates[0]?.input.movedByRemit, true);
+	});
+
+	it("does not move a blocked sender's message already sitting in junk", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", mailboxId: MAILBOXES.junk.mailboxId },
+			flagsAt(1_000),
+		);
+
+		await readBody(harness.service, "Junk");
+
+		assert.deepEqual(harness.moves, []);
+	});
+
+	it("leaves an unflagged sender's inbox message alone", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", mailboxId: MAILBOXES.inbox.mailboxId },
+			{},
+		);
+
+		await readBody(harness.service);
+
+		assert.deepEqual(harness.moves, []);
+	});
+
+	describe("Decision 3a: setAt tie-break against vip/wellknown", () => {
+		it("demotes when blocked is set after vip", async () => {
+			const harness = buildHarness(
+				{ messageId: "m-1", mailboxId: MAILBOXES.inbox.mailboxId },
+				{
+					vip: { value: true, setAt: 1_000 },
+					blocked: { value: true, setAt: 5_000 },
+				},
+			);
+
+			await readBody(harness.service);
+
+			assert.deepEqual(harness.moves, [
+				{ messageId: "m-1", destinationMailboxId: MAILBOXES.junk.mailboxId },
+			]);
+		});
+
+		it("rescues (does not demote) when vip is set after blocked, from junk", async () => {
+			const harness = buildHarness(
+				{ messageId: "m-1", mailboxId: MAILBOXES.junk.mailboxId },
+				{
+					blocked: { value: true, setAt: 1_000 },
+					vip: { value: true, setAt: 5_000 },
+				},
+			);
+
+			// Provider-spam + dmarc-pass is the pre-existing rescue's own low bar,
+			// independent of this issue — carried by the fixture so the only thing
+			// under test is whether the newer `vip` correctly suppresses `blocked`'s
+			// demote.
+			await readBody(harness.service, "Junk", SPAM_FLAGGED_DMARC_PASS_EML);
+
+			assert.deepEqual(harness.moves, [
+				{ messageId: "m-1", destinationMailboxId: MAILBOXES.inbox.mailboxId },
+			]);
+		});
+	});
+});
+
+describe("Address.flags.autoArchive drives placement (issue #300)", () => {
+	it("files an inbox message from an autoArchive sender straight to Archive", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", mailboxId: MAILBOXES.inbox.mailboxId },
+			{ autoArchive: { value: true, setAt: 1_000 } },
+		);
+
+		await readBody(harness.service);
+
+		assert.deepEqual(harness.moves, [
+			{
+				messageId: "m-1",
+				destinationMailboxId: MAILBOXES.archive.mailboxId,
+			},
+		]);
+	});
+
+	it("does not move an autoArchive sender's message already sitting in Archive", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", mailboxId: MAILBOXES.archive.mailboxId },
+			{ autoArchive: { value: true, setAt: 1_000 } },
+		);
+
+		await readBody(harness.service, "Archive");
+
+		assert.deepEqual(harness.moves, []);
+	});
+
+	it("a confident blocked-demote takes priority over autoArchive", async () => {
+		const harness = buildHarness(
+			{ messageId: "m-1", mailboxId: MAILBOXES.inbox.mailboxId },
+			{
+				blocked: { value: true, setAt: 1_000 },
+				autoArchive: { value: true, setAt: 1_000 },
+			},
+		);
+
+		await readBody(harness.service);
+
+		assert.deepEqual(harness.moves, [
+			{ messageId: "m-1", destinationMailboxId: MAILBOXES.junk.mailboxId },
+		]);
+	});
+});

package/src/body-sync.ts

@@ -47,6 +47,7 @@ import {
 import {
 	classifyPlacement,
 	type FolderPlacement,
+	resolveBlockedVsTrust,
 } from "./heuristics/classifyPlacement.js";
 import type { PlacementMoveService } from "./placement-move.js";
 import { type QuarantineService, shapeFromMessageData } from "./quarantine.js";
@@ -1071,26 +1072,68 @@ export class BodySyncService {
 		);
 	}
 
-	private async deriveSenderTrust(
+	/**
+	 * The per-sender signals {@link computePlacement} needs, from ONE `Address`
+	 * fetch (RFC 039 Decision 3/3a, issue #300): the trust reads exactly as
+	 * `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
+	 * never reaches `deriveSenderTrust`'s own contract (the trust badge).
+	 */
+	private async deriveSenderPlacementSignals(
 		accountConfigId: string,
 		fromEmail: string,
-	): Promise<(typeof SenderTrust)[keyof typeof SenderTrust]> {
+	): Promise<{
+		trust: (typeof SenderTrust)[keyof typeof SenderTrust];
+		trustSetAt?: number;
+		blocked: boolean;
+		blockedSetAt?: number;
+		autoArchive: boolean;
+	}> {
+		const unknown = {
+			trust: SenderTrust.Unknown,
+			blocked: false,
+			autoArchive: false,
+		} as const;
 		try {
 			const addressId = deriveAddressId(accountConfigId, fromEmail);
 			const address = await this.addressService.getAddress(
 				accountConfigId,
 				addressId,
 			);
-			if (address.flags?.vip?.value === true) return SenderTrust.Vip;
-			if (address.flags?.wellknown?.value === true)
-				return SenderTrust.Wellknown;
+			const flags = address.flags;
+			if (flags?.vip?.value === true) {
+				return {
+					trust: SenderTrust.Vip,
+					trustSetAt: flags.vip.setAt,
+					blocked: flags.blocked?.value === true,
+					blockedSetAt: flags.blocked?.setAt,
+					autoArchive: flags.autoArchive?.value === true,
+				};
+			}
+			if (flags?.wellknown?.value === true) {
+				return {
+					trust: SenderTrust.Wellknown,
+					trustSetAt: flags.wellknown.setAt,
+					blocked: flags.blocked?.value === true,
+					blockedSetAt: flags.blocked?.setAt,
+					autoArchive: flags.autoArchive?.value === true,
+				};
+			}
+			return {
+				...unknown,
+				blocked: flags?.blocked?.value === true,
+				blockedSetAt: flags?.blocked?.setAt,
+				autoArchive: flags?.autoArchive?.value === true,
+			};
 		} catch (err) {
-			// A genuinely-absent address means "unknown trust". Any other failure
-			// (AccessDenied, throttle, infra) must NOT be silently downgraded to
-			// Unknown — let it crash so the rescue decision isn't made on bad data.
+			// A genuinely-absent address means "no signals". Any other failure
+			// (AccessDenied, throttle, infra) must NOT be silently downgraded — let
+			// it crash so the placement decision isn't made on bad data.
 			if (!(err instanceof NotFoundError)) throw err;
 		}
-		return SenderTrust.Unknown;
+		return unknown;
 	}
 
 	/**
@@ -1199,19 +1242,42 @@ export class BodySyncService {
 					: "other";
 
 		const fromEmail = extractPrimaryFromEmail(parsed);
-		const senderTrust = fromEmail
-			? await this.deriveSenderTrust(accountConfigId, fromEmail)
-			: SenderTrust.Unknown;
+		const signals = fromEmail
+			? await this.deriveSenderPlacementSignals(accountConfigId, fromEmail)
+			: {
+					trust: SenderTrust.Unknown,
+					blocked: false,
+					autoArchive: false,
+				};
+
+		const { senderTrust, senderBlocked } = resolveBlockedVsTrust(
+			{ trust: signals.trust, setAt: signals.trustSetAt },
+			{ blocked: signals.blocked, setAt: signals.blockedSetAt },
+		);
 
 		// The verdict needs the classification signals (providerSpam,
 		// authResult, authenticity) that this body-sync pass just derived; the
 		// stored row does not carry them yet, so overlay them onto the message.
 		const candidate = { ...message, ...classification };
-		const verdict = classifyPlacement(candidate, placement, senderTrust);
+		const verdict = classifyPlacement(
+			candidate,
+			placement,
+			senderTrust,
+			senderBlocked,
+		);
 
-		// A `leave` verdict carries no audit record and no move.
+		// A `leave` verdict — including "nothing confident to say" — carries no
+		// audit record of its own. `flags.autoArchive` (issue #300) is a distinct,
+		// lower-priority filing preference: it only files a message away when
+		// `blocked`/DKIM/DMARC had nothing to say, never overriding a confident
+		// junk/inbox verdict computed above.
 		if (verdict.action === "leave") {
-			return {};
+			return this.resolveAutoArchive(
+				mailboxSpecialUseService,
+				message,
+				accountId,
+				signals.autoArchive,
+			);
 		}
 
 		// Audit verdict — recorded for every actionable verdict (both
@@ -1266,6 +1332,55 @@ export class BodySyncService {
 		};
 	}
 
+	/**
+	 * `flags.autoArchive` (issue #300, RFC 039 Decision 3): file a message
+	 * straight to Archive, skipping Inbox. Only reached from
+	 * {@link computePlacement} when {@link classifyPlacement} had no confident
+	 * junk/inbox verdict of its own — `blocked`/DKIM/DMARC always take priority
+	 * over this filing preference.
+	 *
+	 * No {@link MessagePlacementVerdict} is recorded: `PlacementAction` (the
+	 * audit enum) has only `MoveToInbox`/`MoveToJunk` — issue #300 is scoped to
+	 * no TypeSpec change, so an archive move carries no audit verdict, same as
+	 * a matched filter's move. The move itself reuses the same
+	 * `placementMoveService.moveMessage` path as every other confident move.
+	 *
+	 * Idempotent the same way {@link classifyPlacement}'s own branches are: a
+	 * message already sitting in Archive is left alone, not moved again.
+	 */
+	private async resolveAutoArchive(
+		mailboxSpecialUseService: IMailboxSpecialUseRepository,
+		message: MessageItem,
+		accountId: string,
+		autoArchive: boolean,
+	): Promise<PlacementOutcome> {
+		if (!autoArchive) return {};
+
+		const archiveMailbox = await mailboxSpecialUseService.findBySpecialUse(
+			accountId,
+			MailboxSpecialUse.Archive,
+		);
+		if (!archiveMailbox || message.mailboxId === archiveMailbox.mailboxId) {
+			return {};
+		}
+
+		this.log.info(
+			{
+				messageId: message.messageId,
+				accountId,
+				destinationMailboxId: archiveMailbox.mailboxId,
+			},
+			"Auto-archive verdict",
+		);
+
+		return {
+			move: {
+				destinationMailboxId: archiveMailbox.mailboxId,
+				destinationPath: archiveMailbox.fullPath,
+			},
+		};
+	}
+
 	// The old `enqueuePlacementMove` (best-effort, catch-and-log) lived here.
 	// Issue #1271: it ran AFTER `bodyStorageKey` was already durable, so a
 	// failure was swallowed to avoid stranding the message behind the

package/src/heuristics/classifyPlacement.test.ts

@@ -0,0 +1,214 @@
+/**
+ * `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.
+ */
+
+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 {
+	classifyPlacement,
+	resolveBlockedVsTrust,
+} from "./classifyPlacement.js";
+
+const baseMessage = (overrides: Partial<MessageItem> = {}): MessageItem =>
+	({
+		messageId: "m-1",
+		mailboxId: "mb-1",
+		uid: 1,
+		providerSpam: { classified: false },
+		authResult: { dmarc: "Pass" },
+		...overrides,
+	}) as unknown as MessageItem;
+
+describe("classifyPlacement", () => {
+	describe("senderBlocked (RFC 039 Decision 3)", () => {
+		it("demotes an inbox message from a blocked sender, independent of DKIM/DMARC", () => {
+			const message = baseMessage({
+				providerSpam: undefined,
+				authResult: undefined,
+			});
+			const verdict = classifyPlacement(
+				message,
+				"inbox",
+				SenderTrust.Unknown,
+				true,
+			);
+			assert.deepEqual(verdict, {
+				action: "move-to-junk",
+				confidence: "confident",
+				reasons: ["sender=blocked"],
+			});
+		});
+
+		it("demotes a message sitting outside junk/inbox (e.g. a custom folder) from a blocked sender", () => {
+			const verdict = classifyPlacement(
+				baseMessage(),
+				"other",
+				SenderTrust.Unknown,
+				true,
+			);
+			assert.equal(verdict.action, "move-to-junk");
+			assert.equal(verdict.confidence, "confident");
+		});
+
+		it("does not re-move a blocked sender's message already in junk", () => {
+			const verdict = classifyPlacement(
+				baseMessage(),
+				"junk",
+				SenderTrust.Unknown,
+				true,
+			);
+			assert.notEqual(verdict.action, "move-to-junk");
+		});
+
+		it("does not demote when the sender is not blocked, all else equal", () => {
+			const verdict = classifyPlacement(
+				baseMessage({ providerSpam: undefined, authResult: undefined }),
+				"inbox",
+				SenderTrust.Unknown,
+				false,
+			);
+			assert.deepEqual(verdict, {
+				action: "leave",
+				confidence: "unsure",
+				reasons: ["missing-signals"],
+			});
+		});
+
+		it("still leaves an already-Remit-moved message alone even when blocked", () => {
+			const verdict = classifyPlacement(
+				baseMessage({ movedByRemit: true }),
+				"inbox",
+				SenderTrust.Unknown,
+				true,
+			);
+			assert.deepEqual(verdict, {
+				action: "leave",
+				confidence: "confident",
+				reasons: ["already-moved-by-remit"],
+			});
+		});
+	});
+
+	describe("resolveBlockedVsTrust (Decision 3a tie-break)", () => {
+		it("blocked wins when set after vip", () => {
+			const result = resolveBlockedVsTrust(
+				{ trust: SenderTrust.Vip, setAt: 1_000 },
+				{ blocked: true, setAt: 5_000 },
+			);
+			assert.deepEqual(result, {
+				senderTrust: SenderTrust.Unknown,
+				senderBlocked: true,
+			});
+		});
+
+		it("vip wins when set after blocked", () => {
+			const result = resolveBlockedVsTrust(
+				{ trust: SenderTrust.Vip, setAt: 5_000 },
+				{ blocked: true, setAt: 1_000 },
+			);
+			assert.deepEqual(result, {
+				senderTrust: SenderTrust.Vip,
+				senderBlocked: false,
+			});
+		});
+
+		it("breaks a same-second tie in favor of blocked", () => {
+			const result = resolveBlockedVsTrust(
+				{ trust: SenderTrust.Wellknown, setAt: 1_000 },
+				{ blocked: true, setAt: 1_400 },
+			);
+			assert.deepEqual(result, {
+				senderTrust: SenderTrust.Unknown,
+				senderBlocked: true,
+			});
+		});
+
+		it("blocked applies outright when there is no competing trust flag", () => {
+			const result = resolveBlockedVsTrust(
+				{ trust: SenderTrust.Unknown },
+				{ blocked: true, setAt: 1_000 },
+			);
+			assert.deepEqual(result, {
+				senderTrust: SenderTrust.Unknown,
+				senderBlocked: true,
+			});
+		});
+
+		it("passes trust through unchanged when the sender isn't blocked", () => {
+			const result = resolveBlockedVsTrust(
+				{ trust: SenderTrust.Wellknown, setAt: 1_000 },
+				{ blocked: false },
+			);
+			assert.deepEqual(result, {
+				senderTrust: SenderTrust.Wellknown,
+				senderBlocked: false,
+			});
+		});
+	});
+
+	describe("existing DKIM/DMARC paths (unaffected by senderBlocked=false)", () => {
+		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,
+			);
+			assert.equal(verdict.action, "move-to-inbox");
+			assert.equal(verdict.confidence, "confident");
+		});
+
+		it("does not rescue an untrusted sender's mail from junk", () => {
+			const verdict = classifyPlacement(
+				baseMessage({ providerSpam: { classified: true } }),
+				"junk",
+				SenderTrust.Unknown,
+				false,
+			);
+			assert.equal(verdict.action, "leave");
+			assert.equal(verdict.confidence, "unsure");
+		});
+
+		it("demotes an untrusted 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,
+				false,
+			);
+			assert.deepEqual(verdict, {
+				action: "move-to-junk",
+				confidence: "confident",
+				reasons: ["dkim-mismatch", "dmarc=fail", "sender=untrusted"],
+			});
+		});
+
+		it("defers a dkim-mismatch + dmarc-pass message to a later LLM tier", () => {
+			const verdict = classifyPlacement(
+				baseMessage({
+					authResult: { dmarc: "Pass" },
+					authenticity: { fromDomain: "example.com", dkimMismatch: true },
+				}),
+				"inbox",
+				SenderTrust.Unknown,
+				false,
+			);
+			assert.deepEqual(verdict, {
+				action: "leave",
+				confidence: "unsure",
+				reasons: ["dkim-mismatch", "dmarc=pass", "deferred-to-llm"],
+			});
+		});
+	});
+});

package/src/heuristics/classifyPlacement.ts

@@ -16,6 +16,50 @@ export interface PlacementVerdict {
 const isTrusted = (senderTrust: SenderTrustValue): boolean =>
 	senderTrust === SenderTrust.Vip || senderTrust === SenderTrust.Wellknown;
 
+/** The trust signal plus the `setAt` of whichever flag (`vip`/`wellknown`) produced it, `undefined` when the sender is `Unknown`. */
+export interface SenderTrustSignal {
+	trust: SenderTrustValue;
+	setAt?: number;
+}
+
+/** The sender's `blocked` flag value plus its `setAt`. */
+export interface SenderBlockedSignal {
+	blocked: boolean;
+	setAt?: number;
+}
+
+/**
+ * RFC 039 Decision 3a: when a sender's `blocked` flag and their `vip`/
+ * `wellknown` flag disagree on placement, the one set most recently wins.
+ * Scoped to {@link classifyPlacement}'s own verdict only — it never touches
+ * `deriveSenderTrust` or the trust badge, which stay a plain `vip → wellknown
+ * → unknown` read with no `blocked` case.
+ *
+ * A same-second tie (both `setAt` floor to the same second) breaks in a
+ * fixed, arbitrary order: `blocked` before `vip` before `wellknown` — a
+ * determinism backstop, not a meaningful signal.
+ */
+export const resolveBlockedVsTrust = (
+	trust: SenderTrustSignal,
+	blocked: SenderBlockedSignal,
+): { senderTrust: SenderTrustValue; senderBlocked: boolean } => {
+	if (!blocked.blocked) {
+		return { senderTrust: trust.trust, senderBlocked: false };
+	}
+	if (trust.trust === SenderTrust.Unknown || trust.setAt === undefined) {
+		return { senderTrust: SenderTrust.Unknown, senderBlocked: true };
+	}
+
+	const blockedSecond = Math.floor((blocked.setAt ?? 0) / 1000);
+	const trustSecond = Math.floor(trust.setAt / 1000);
+
+	// Newer (or a same-second tie, which `blocked` wins) — blocked wins.
+	if (blockedSecond >= trustSecond) {
+		return { senderTrust: SenderTrust.Unknown, senderBlocked: true };
+	}
+	return { senderTrust: trust.trust, senderBlocked: false };
+};
+
 /**
  * Tier 0 deterministic placement verdict (RFC 031, "Confident moves").
  *
@@ -24,11 +68,18 @@ const isTrusted = (senderTrust: SenderTrustValue): boolean =>
  * It generalizes `shouldRescueFromJunk` into a two-directional verdict and is
  * 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
+ * compare `setAt`.
  */
 export const classifyPlacement = (
 	message: MessageItem,
 	placement: FolderPlacement,
 	senderTrust: SenderTrustValue,
+	senderBlocked: boolean,
 ): PlacementVerdict => {
 	if (message.movedByRemit === true) {
 		return {
@@ -38,6 +89,14 @@ export const classifyPlacement = (
 		};
 	}
 
+	if (senderBlocked && placement !== "junk") {
+		return {
+			action: "move-to-junk",
+			confidence: "confident",
+			reasons: ["sender=blocked"],
+		};
+	}
+
 	if (!message.providerSpam || !message.authResult) {
 		return {
 			action: "leave",