@remit/account-worker 0.0.24 → 0.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/account-worker",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/events.ts

@@ -1,3 +1,7 @@
+import type { ThreadMessageItem } from "@remit/data-ports";
+
+type MessageCategoryValue = ThreadMessageItem["category"];
+
 export type AccountDeleteEvent = {
 	type: "AccountDelete";
 	accountConfigId: string;
@@ -33,11 +37,38 @@ export type OrganizeJobEvent = {
 	organizeJobId: string;
 };
 
+/**
+ * Retroactive half of a sender-category override (#415, RFC 039 Decision 3).
+ * Rides the same account-fanout queue as the organize back-apply: the API
+ * enqueues one when `Address.flags.category` is SET, and the fanout worker
+ * re-labels a bounded recent batch of that sender's already-classified mail.
+ * A CLEAR never enqueues one: reverting to auto-classification says nothing
+ * about what the classifier would have answered, and re-deriving it would need
+ * every message's body back.
+ *
+ * `category` and `categorySetAt` together name WHICH set this job was fired
+ * for, and the worker refuses a job whose set no longer stands on the Address.
+ * That check is what the standard queue's semantics make necessary rather than
+ * merely tidy: delivery is at-least-once and unordered, so without it a job
+ * that fails and redelivers after the user has corrected the category re-labels
+ * those 500 messages back to the superseded one, leaving the flag and the mail
+ * permanently disagreeing with nothing to reconcile them.
+ */
+export type SenderCategoryBackApplyEvent = {
+	type: "SenderCategoryBackApply";
+	accountConfigId: string;
+	addressId: string;
+	normalizedEmail: string;
+	category: MessageCategoryValue;
+	categorySetAt: number;
+};
+
 export type AccountFanoutEvent =
 	| AccountDeleteEvent
 	| AccountDataPurgeEvent
 	| AccountExportEvent
-	| OrganizeJobEvent;
+	| OrganizeJobEvent
+	| SenderCategoryBackApplyEvent;
 
 export type AccountDeleteFinalizeEvent = {
 	type: "FinalizeAccountDelete";

package/src/handlers/account-fanout.ts

@@ -28,6 +28,7 @@ import type {
 import { processAccountExport } from "./account-export.js";
 import { processAccountDataPurge } from "./account-purge.js";
 import { processOrganizeJob } from "./organize-job.js";
+import { processSenderCategoryBackApply } from "./sender-category-backapply.js";
 
 export interface ProcessAccountFanoutDeps {
 	services?: CascadeServices;
@@ -74,6 +75,11 @@ export const processAccountFanout = async (
 		return;
 	}
 
+	if (event.type === "SenderCategoryBackApply") {
+		await processSenderCategoryBackApply(event, log);
+		return;
+	}
+
 	await processAccountDelete(event, log, services, sqsFor, deps);
 };
 

package/src/handlers/organize-job.test.ts

@@ -1,10 +1,23 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { afterEach, describe, it } from "node:test";
 import type { RemitClient } from "@remit/backend/client";
-import type { OrganizeMatchDeps } from "@remit/backend/organize";
+import {
+	buildOrganizeMatchDeps,
+	type OrganizeMatchDeps,
+	type OrganizeSemanticDeps,
+} from "@remit/backend/organize";
+import type { FilterAnchorItem, FilterItem } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { DrizzleThreadMessageRepository } from "@remit/drizzle-service";
+import { createShippedSqliteDb } from "@remit/drizzle-service/test-sqlite";
 import { noopLogger } from "@remit/logger-lambda/noop-logger";
 import type { OrganizeJobEvent } from "../events.js";
-import { processOrganizeJob } from "./organize-job.js";
+import {
+	type ProcessOrganizeJobDeps,
+	processOrganizeJob,
+} from "./organize-job.js";
 
 interface Update {
 	state: string;
@@ -29,6 +42,7 @@ const jobClient = (
 			get: async () => ({
 				organizeJobId: "job-1",
 				accountConfigId: "cfg-1",
+				filterId: "None",
 				anchorMessageId: "None",
 				matchOperator: "And",
 				literalClauses,
@@ -56,6 +70,7 @@ const explodingMatchDeps = (): OrganizeMatchDeps =>
 			throw new Error("SQLITE_BUSY");
 		},
 		filterAnchors: {
+			get: async () => null,
 			listByAccountConfig: async () => [],
 			put: async () => {
 				throw new Error("unreachable");
@@ -104,3 +119,323 @@ describe("processOrganizeJob (reader #463)", () => {
 		assert.equal(updates[1]?.errorMessage, "SQLITE_BUSY");
 	});
 });
+
+interface Move {
+	messageId: string;
+	destinationMailboxId: string;
+}
+
+const CONFIG = "cfg-1";
+const INBOX = "mbx-inbox";
+const ARCHIVE = "mbx-archive";
+
+const standingFilter = (over: Partial<FilterItem> = {}): FilterItem => ({
+	filterId: "flt-1",
+	accountConfigId: CONFIG,
+	name: "Invoices",
+	scope: "Standing",
+	state: "Active",
+	disabledReason: "None",
+	hasAnchor: false,
+	ruleChangedAt: 1,
+	actionChangedAt: 1,
+	matchOperator: "And",
+	literalClauses: [{ field: "From", value: "billing@example.com" }],
+	actionLabelId: "None",
+	actionMailboxId: "mbx-invoices",
+	createdAt: 0,
+	updatedAt: 0,
+	...over,
+});
+
+/**
+ * The thread rows live in the shipped SQLite schema, read through the real
+ * repository, so the inbox narrowing is the store's own query. One invoice
+ * sits in the inbox and one in the archive, both from the filter's sender
+ * and both saying "overdue" in their preview.
+ */
+const seedThreads = async (
+	threadMessage: DrizzleThreadMessageRepository,
+): Promise<{ inbox: string; archive: string }> => {
+	const seed = async (mailboxId: string, uid: number): Promise<string> => {
+		const messageId = randomUUID();
+		await threadMessage.create({
+			accountConfigId: CONFIG,
+			threadId: randomUUID(),
+			messageId,
+			mailboxId,
+			uid,
+			referenceOrder: 0,
+			internalDate: uid,
+			sentDate: uid,
+			subject: "Your invoice",
+			fromEmail: "billing@example.com",
+			fromName: "Billing",
+			snippet: "This invoice is overdue",
+			isRead: false,
+			isDeleted: false,
+			hasAttachment: false,
+			hasStars: false,
+		});
+		return messageId;
+	};
+	return { inbox: await seed(INBOX, 1), archive: await seed(ARCHIVE, 2) };
+};
+
+interface World {
+	client: RemitClient;
+	inbox: string;
+	archive: string;
+	updates: Update[];
+	moves: Move[];
+	labeled: string[];
+	close: () => void;
+}
+
+const world = async (
+	filters: FilterItem[],
+	anchors: FilterAnchorItem[] = [],
+): Promise<World> => {
+	const store = createShippedSqliteDb();
+	store.sqlite.exec(
+		readFileSync(
+			new URL(
+				"../../../../npm-scripts/sqlite-search-index.sql",
+				import.meta.url,
+			),
+			"utf8",
+		),
+	);
+	const threadMessage = new DrizzleThreadMessageRepository(store.db as never);
+	const { inbox, archive } = await seedThreads(threadMessage);
+	const updates: Update[] = [];
+	const labeled: string[] = [];
+	const mailboxOf: Record<string, string> = {
+		[inbox]: INBOX,
+		[archive]: ARCHIVE,
+	};
+	const client = {
+		threadMessage,
+		organizeJobRequest: {
+			get: async () => ({
+				organizeJobId: "job-1",
+				accountConfigId: CONFIG,
+				filterId: "flt-1",
+				anchorMessageId: "None",
+				matchOperator: "And",
+				literalClauses: [],
+				similarityThreshold: 0.75,
+				actionLabelId: "None",
+				actionMailboxId: "None",
+			}),
+			update: async (_id: string, patch: Update) => {
+				updates.push(patch);
+			},
+		},
+		filter: {
+			get: async (_cfg: string, filterId: string) => {
+				const found = filters.find((f) => f.filterId === filterId);
+				if (!found) throw new NotFoundError(`Filter not found: ${filterId}`);
+				return found;
+			},
+			refreshExpiry: async (filter: FilterItem) => filter,
+			listByAccountAndState: async (_cfg: string, state: string) =>
+				filters.filter((f) => f.state === state),
+		},
+		filterAnchor: {
+			get: async (_cfg: string, filterId: string) =>
+				anchors.find((anchor) => anchor.filterId === filterId) ?? null,
+		},
+		account: {
+			listMailSourcesByAccountConfig: async () => [{ accountId: "acct-1" }],
+		},
+		mailboxSpecialUse: {
+			findInboxMailbox: async () => ({ mailboxId: INBOX, fullPath: "INBOX" }),
+		},
+		message: {
+			get: async (messageId: string) => ({
+				messageId,
+				mailboxId: mailboxOf[messageId],
+			}),
+		},
+		mailbox: { resolveAccountId: async () => "acct-1" },
+		messageLabel: {
+			apply: async (input: { messageId: string }) => {
+				labeled.push(input.messageId);
+				return {};
+			},
+		},
+	} as unknown as RemitClient;
+	return {
+		client,
+		inbox,
+		archive,
+		updates,
+		moves: [],
+		labeled,
+		close: store.close,
+	};
+};
+
+const recordingMoves = (moves: Move[]) =>
+	({
+		moveMessage: async (
+			_cfg: string,
+			messageId: string,
+			destinationMailboxId: string,
+		) => {
+			moves.push({ messageId, destinationMailboxId });
+		},
+	}) as unknown as NonNullable<ProcessOrganizeJobDeps["moveService"]>;
+
+const runFilterJob = (w: World) =>
+	processOrganizeJob(event, noopLogger, {
+		client: w.client,
+		matchDeps: buildOrganizeMatchDeps(w.client),
+		moveService: recordingMoves(w.moves),
+	});
+
+const EMBEDDING_ID = "test-model@4";
+const ANCHOR_VECTOR = [1, 0, 0, 0];
+const ORTHOGONAL_VECTOR = [0, 1, 0, 0];
+
+const persistedAnchor: FilterAnchorItem = {
+	filterId: "flt-1",
+	accountConfigId: CONFIG,
+	anchorMessageId: "msg-anchor",
+	anchorEmbedding: ANCHOR_VECTOR,
+	anchorEmbeddingId: EMBEDDING_ID,
+	anchorSourceText: "Your invoice",
+	createdAt: 0,
+	updatedAt: 0,
+};
+
+/**
+ * The vector index answers the anchor with the inbox invoice, and only when
+ * asked about the inbox: the kNN read is where a similarity filter finds its
+ * candidates.
+ */
+const vectorMatchDeps = (w: World): OrganizeMatchDeps => ({
+	...buildOrganizeMatchDeps(w.client),
+	semantic: () => ({
+		buildAnchor: async () => {
+			throw new Error("a filter widens on its persisted anchor");
+		},
+		vectorStore: {
+			query: async (query: { filter?: { mailboxId?: string } }) =>
+				query.filter?.mailboxId === INBOX
+					? [
+							{
+								chunkId: `${w.inbox}#body`,
+								score: 0.9,
+								metadata: { messageId: w.inbox, mailboxIds: [INBOX] },
+							},
+						]
+					: [],
+			getByMessage: async () => [],
+		} as unknown as OrganizeSemanticDeps["vectorStore"],
+		embed: async () => ANCHOR_VECTOR,
+		embeddingId: EMBEDDING_ID,
+	}),
+});
+
+describe("processOrganizeJob for a filter job (#1354)", () => {
+	let current: World | undefined;
+	afterEach(() => current?.close());
+
+	it("moves the pre-existing matching inbox message and leaves the archive alone", async () => {
+		current = await world([standingFilter()]);
+
+		await runFilterJob(current);
+
+		assert.deepEqual(current.moves, [
+			{ messageId: current.inbox, destinationMailboxId: "mbx-invoices" },
+		]);
+		const done = current.updates.at(-1);
+		assert.equal(done?.state, "Complete");
+		assert.equal(done?.matchedCount, 1);
+		assert.equal(done?.appliedCount, 1);
+	});
+
+	it("matches a free-text rule from search on the stored preview", async () => {
+		current = await world([
+			standingFilter({
+				literalClauses: [{ field: "HasWords", value: "overdue" }],
+			}),
+		]);
+
+		await runFilterJob(current);
+
+		assert.deepEqual(current.moves, [
+			{ messageId: current.inbox, destinationMailboxId: "mbx-invoices" },
+		]);
+		assert.equal(current.updates.at(-1)?.state, "Complete");
+	});
+
+	it("leaves the move to a newer filter that also matches, and still labels", async () => {
+		current = await world([
+			standingFilter({ actionLabelId: "lbl-bills" }),
+			standingFilter({
+				filterId: "flt-2",
+				name: "Receipts",
+				actionChangedAt: 2,
+				actionMailboxId: "mbx-receipts",
+			}),
+		]);
+
+		await runFilterJob(current);
+
+		assert.deepEqual(current.moves, []);
+		assert.deepEqual(current.labeled, [current.inbox]);
+		assert.equal(current.updates.at(-1)?.state, "Complete");
+	});
+
+	it("fails the job without a retry when the filter is turned off", async () => {
+		current = await world([
+			standingFilter({ state: "Disabled", disabledReason: "UserDisabled" }),
+		]);
+
+		await runFilterJob(current);
+
+		assert.deepEqual(current.moves, []);
+		assert.equal(current.updates.at(-1)?.state, "Failed");
+		assert.match(String(current.updates.at(-1)?.errorMessage), /turned off/);
+	});
+
+	it("fails the job without a retry when the filter was deleted", async () => {
+		current = await world([]);
+
+		await runFilterJob(current);
+
+		assert.equal(current.updates.at(-1)?.state, "Failed");
+		assert.match(String(current.updates.at(-1)?.errorMessage), /deleted/);
+	});
+
+	it("moves a message the vector query found, though the preview scores below the threshold", async () => {
+		current = await world(
+			[standingFilter({ hasAnchor: true, literalClauses: [] })],
+			[persistedAnchor],
+		);
+
+		// The index-time evaluator embeds subject and preview; this embedder puts
+		// that text orthogonal to the anchor, so evaluate alone would call the
+		// message a miss. It only orders the move, so the vector match stands.
+		await processOrganizeJob(event, noopLogger, {
+			client: current.client,
+			matchDeps: vectorMatchDeps(current),
+			moveService: recordingMoves(current.moves),
+			embedder: {
+				embed: async () => ORTHOGONAL_VECTOR,
+				embeddingId: EMBEDDING_ID,
+			},
+		});
+
+		assert.deepEqual(current.moves, [
+			{ messageId: current.inbox, destinationMailboxId: "mbx-invoices" },
+		]);
+		const done = current.updates.at(-1);
+		assert.equal(done?.state, "Complete");
+		assert.equal(done?.matchedCount, 1);
+		assert.equal(done?.appliedCount, 1);
+	});
+});

package/src/handlers/organize-job.ts

@@ -1,11 +1,16 @@
 import { getClient, type RemitClient } from "@remit/backend/client";
 import {
+	type ApplyOrganizeDeps,
 	applyOrganize,
+	backApplyFilter,
 	buildOrganizeMatchDeps,
 	buildOrganizeMoveService,
+	type FilterBackApplyDeps,
+	isFilterJob,
 	matchOrganize,
 	ORGANIZE_MATCH_LIMIT,
 	type OrganizeMatchDeps,
+	type OrganizeRejection,
 	predicateFromJob,
 } from "@remit/backend/organize";
 import type { Logger } from "@remit/logger-lambda";
@@ -14,12 +19,64 @@ import type { OrganizeJobEvent } from "../events.js";
 export interface ProcessOrganizeJobDeps {
 	client?: RemitClient;
 	matchDeps?: OrganizeMatchDeps;
+	moveService?: ApplyOrganizeDeps["moveService"];
+	embedder?: FilterBackApplyDeps["embedder"];
 }
 
+interface OrganizeOutcome {
+	rejected: OrganizeRejection | null;
+	matched: number;
+	applied: number;
+	failed: number;
+	semanticUnavailable: boolean;
+}
+
+const rejectedOutcome = (rejected: OrganizeRejection): OrganizeOutcome => ({
+	rejected,
+	matched: 0,
+	applied: 0,
+	failed: 0,
+	semanticUnavailable: false,
+});
+
+/**
+ * The "all like these" pass: the predicate snapshotted on the row, over every
+ * folder, every requested move applied (reader #497).
+ */
+const runSnapshot = async (
+	client: RemitClient,
+	matchDeps: OrganizeMatchDeps,
+	moveService: ApplyOrganizeDeps["moveService"],
+	job: Awaited<ReturnType<RemitClient["organizeJobRequest"]["get"]>>,
+): Promise<OrganizeOutcome> => {
+	const predicate = predicateFromJob(job);
+	const match = await matchOrganize(
+		matchDeps,
+		job.accountConfigId,
+		predicate,
+		ORGANIZE_MATCH_LIMIT,
+	);
+	if (match.rejected) return rejectedOutcome(match.rejected);
+	const { applied, failed } = await applyOrganize(
+		{ client, moveService },
+		job.accountConfigId,
+		match.messageIds,
+		predicate,
+	);
+	return {
+		rejected: null,
+		matched: match.messageIds.length,
+		applied,
+		failed,
+		semanticUnavailable: match.semanticUnavailable,
+	};
+};
+
 /**
- * Run a "all like these" back-apply job (RFC 034, #1278): match the corpus
- * against the job's snapshotted predicate and apply the action to every match,
- * in one pass, then record the counts. Mirrors the export job's lifecycle —
+ * Run a back-apply job (RFC 034, #1278): an "all like these" pass matches the
+ * corpus against the job's snapshotted predicate; a filter job (#1354) runs the
+ * named standing filter over the inbox with index-time move precedence. Either
+ * applies the action to every match in one pass, then records the counts. Mirrors the export job's lifecycle —
  * Running, then Complete/Failed — on the same fanout seam.
  *
  * Reuses the shared matcher (so the applied set equals what preview returned)
@@ -53,41 +110,37 @@ export const processOrganizeJob = async (
 	);
 
 	try {
-		const predicate = predicateFromJob(job);
 		const matchDeps = deps.matchDeps ?? buildOrganizeMatchDeps(client);
-		const match = await matchOrganize(
-			matchDeps,
-			accountConfigId,
-			predicate,
-			ORGANIZE_MATCH_LIMIT,
-		);
+		const moveService = deps.moveService ?? buildOrganizeMoveService(client);
+		const outcome = isFilterJob(job)
+			? await backApplyFilter(
+					{ client, matchDeps, moveService, embedder: deps.embedder },
+					accountConfigId,
+					job.filterId,
+				).then((result) =>
+					result.rejected ? rejectedOutcome(result.rejected) : result,
+				)
+			: await runSnapshot(client, matchDeps, moveService, job);
 
-		if (match.rejected) {
+		if (outcome.rejected) {
 			await client.organizeJobRequest.update(organizeJobId, {
 				state: "Failed",
 				matchedCount: 0,
 				appliedCount: 0,
 				failedCount: 0,
-				errorMessage: match.rejected.message,
+				errorMessage: outcome.rejected.message,
 			});
 			log.warn(
-				{ accountConfigId, organizeJobId, reason: match.rejected.reason },
+				{ accountConfigId, organizeJobId, reason: outcome.rejected.reason },
 				"Organize back-apply refused the job's rule; failing the job without a retry",
 			);
 			return;
 		}
 
-		const { messageIds, semanticUnavailable } = match;
-		const { applied, failed } = await applyOrganize(
-			{ client, moveService: buildOrganizeMoveService(client) },
-			accountConfigId,
-			messageIds,
-			predicate,
-		);
-
+		const { matched, applied, failed, semanticUnavailable } = outcome;
 		await client.organizeJobRequest.update(organizeJobId, {
 			state: "Complete",
-			matchedCount: messageIds.length,
+			matchedCount: matched,
 			appliedCount: applied,
 			failedCount: failed,
 		});
@@ -95,7 +148,8 @@ export const processOrganizeJob = async (
 			{
 				accountConfigId,
 				organizeJobId,
-				matched: messageIds.length,
+				filterId: job.filterId,
+				matched,
 				applied,
 				failed,
 				semanticUnavailable,

package/src/handlers/sender-category-backapply.test.ts

@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { RemitClient } from "@remit/backend/client";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { noopLogger } from "@remit/logger-lambda/noop-logger";
+import type { SenderCategoryBackApplyEvent } from "../events.js";
+import { processSenderCategoryBackApply } from "./sender-category-backapply.js";
+
+const SET_AT = 1_700;
+
+const event: SenderCategoryBackApplyEvent = {
+	type: "SenderCategoryBackApply",
+	accountConfigId: "cfg-1",
+	addressId: "addr-1",
+	normalizedEmail: "post@ns.nl",
+	category: "newsletter",
+	categorySetAt: SET_AT,
+};
+
+const row = {
+	threadMessageId: "tm-1",
+	messageId: "msg-1",
+	mailboxId: "mbx-inbox",
+	fromEmail: "post@ns.nl",
+	category: "personal",
+	sentDate: 1_000,
+	isRead: false,
+	isDeleted: false,
+	hasStars: false,
+	hasAttachment: false,
+};
+
+interface ClientShape {
+	relabelled: Array<{ messageId: string; category: unknown }>;
+	storedFlag?: { value: string; setAt: number } | "cleared" | "address-gone";
+	listByFieldTerms?: () => Promise<unknown>;
+	updateMessage?: (messageId: string) => Promise<void>;
+}
+
+const clientOver = ({
+	relabelled,
+	storedFlag = { value: "newsletter", setAt: SET_AT },
+	listByFieldTerms = async () => ({
+		items: [row],
+		continuationToken: undefined,
+	}),
+	updateMessage,
+}: ClientShape): RemitClient =>
+	({
+		address: {
+			getAddress: async () => {
+				if (storedFlag === "address-gone") {
+					throw new NotFoundError("Address addr-1 not found");
+				}
+				if (storedFlag === "cleared") {
+					return { addressId: "addr-1", flags: {} };
+				}
+				return { addressId: "addr-1", flags: { category: storedFlag } };
+			},
+		},
+		message: {
+			update: async (messageId: string, input: { category: unknown }) => {
+				if (updateMessage) await updateMessage(messageId);
+				relabelled.push({ messageId, category: input.category });
+			},
+		},
+		threadMessage: {
+			listByFieldTerms,
+			findAllByMessageId: async () => [row],
+			update: async () => {},
+		},
+	}) as unknown as RemitClient;
+
+describe("processSenderCategoryBackApply (#415)", () => {
+	it("re-labels the sender's stored mail to the category the event carries", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({ relabelled }),
+		});
+
+		assert.deepEqual(relabelled, [
+			{ messageId: "msg-1", category: "newsletter" },
+		]);
+	});
+
+	it("applies nothing when the user has since corrected the category", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({
+				relabelled,
+				storedFlag: { value: "promotions", setAt: SET_AT + 60 },
+			}),
+		});
+
+		assert.deepEqual(
+			relabelled,
+			[],
+			"a redelivery after a correction must not put the superseded category back",
+		);
+	});
+
+	it("applies nothing when the same category was cleared and set again", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({
+				relabelled,
+				storedFlag: { value: "newsletter", setAt: SET_AT + 60 },
+			}),
+		});
+
+		assert.deepEqual(relabelled, []);
+	});
+
+	it("applies nothing when the override was cleared outright", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({ relabelled, storedFlag: "cleared" }),
+		});
+
+		assert.deepEqual(relabelled, []);
+	});
+
+	it("declines quietly when the address is gone", async () => {
+		const relabelled: Array<{ messageId: string; category: unknown }> = [];
+
+		await processSenderCategoryBackApply(event, noopLogger, {
+			client: clientOver({ relabelled, storedFlag: "address-gone" }),
+		});
+
+		assert.deepEqual(relabelled, []);
+	});
+
+	it("leaves a pass with a failed message unacknowledged so it redelivers", async () => {
+		await assert.rejects(
+			processSenderCategoryBackApply(event, noopLogger, {
+				client: clientOver({
+					relabelled: [],
+					updateMessage: async () => {
+						throw new Error("SQLITE_BUSY");
+					},
+				}),
+			}),
+			/1 of 1/,
+			"acknowledging would strand the thread rows re-labelled and the Message row not",
+		);
+	});
+
+	it("propagates a store failure so partial batch failure redelivers the record", async () => {
+		await assert.rejects(
+			processSenderCategoryBackApply(event, noopLogger, {
+				client: clientOver({
+					relabelled: [],
+					listByFieldTerms: async () => {
+						throw new Error("SQLITE_BUSY");
+					},
+				}),
+			}),
+			/SQLITE_BUSY/,
+			"the pass writes only idempotent local rows, so a retry is safe and must happen",
+		);
+	});
+});

package/src/handlers/sender-category-backapply.ts

@@ -0,0 +1,98 @@
+import { getClient, type RemitClient } from "@remit/backend/client";
+import {
+	backApplySenderCategory,
+	SENDER_CATEGORY_BACKAPPLY_LIMIT,
+} from "@remit/backend/sender-category";
+import { NotFoundError } from "@remit/data-ports/errors";
+import type { Logger } from "@remit/logger-lambda";
+import type { SenderCategoryBackApplyEvent } from "../events.js";
+
+export interface ProcessSenderCategoryBackApplyDeps {
+	client?: RemitClient;
+}
+
+/**
+ * Whether the override this job was fired for is still the one standing on the
+ * Address. Both halves are compared: `value` alone would let a set → clear →
+ * re-set to the same category count as unchanged, and `setAt` alone would
+ * refuse a legitimate redelivery.
+ *
+ * A vanished Address is a stale job, not a fault — the account was purged
+ * between the PATCH and the delivery — so it declines quietly. Every other
+ * read failure propagates, because a job that cannot tell whether it is stale
+ * must not guess.
+ */
+const overrideStillStands = async (
+	client: RemitClient,
+	event: SenderCategoryBackApplyEvent,
+): Promise<boolean> => {
+	const address = await client.address
+		.getAddress(event.accountConfigId, event.addressId)
+		.catch((error: unknown) => {
+			if (error instanceof NotFoundError) return undefined;
+			throw error;
+		});
+	const flag = address?.flags?.category;
+	return flag?.value === event.category && flag?.setAt === event.categorySetAt;
+};
+
+/**
+ * Run the retroactive half of a sender-category override (#415): re-label the
+ * bounded recent batch of that sender's already-classified mail, in one pass.
+ * Rides the organize back-apply's seam without its job row — a flag PATCH
+ * returns the address, not a job to poll, so there is no lifecycle for a client
+ * to read and nothing for a row to carry.
+ *
+ * The delivery is at-least-once and unordered, so the pass starts by
+ * re-reading the flag and declines unless the set it was fired for is still
+ * the standing one ({@link overrideStillStands}). Re-labelling blind would let
+ * a redelivered job undo a correction the user has since made.
+ *
+ * A pass in which any message failed is NOT acknowledged: the writes are
+ * idempotent and the converged rows are skipped on the way through, so
+ * redelivery re-runs only what is still wrong. Acknowledging instead would
+ * leave a message whose thread rows were re-labelled but whose Message row was
+ * not — the badge and the detail view disagreeing, permanently, with nothing
+ * left to repair it.
+ */
+export const processSenderCategoryBackApply = async (
+	event: SenderCategoryBackApplyEvent,
+	log: Logger,
+	deps: ProcessSenderCategoryBackApplyDeps = {},
+): Promise<void> => {
+	const { accountConfigId, addressId, normalizedEmail, category } = event;
+	const client = deps.client ?? (await getClient());
+
+	if (!(await overrideStillStands(client, event))) {
+		log.warn(
+			{ accountConfigId, addressId, category },
+			"Sender category back-apply skipped: the override it was fired for no longer stands",
+		);
+		return;
+	}
+
+	const result = await backApplySenderCategory(
+		{ client },
+		accountConfigId,
+		normalizedEmail,
+		category,
+	);
+
+	// biome-ignore lint/plugin/no-logger-info: a back-apply is an audit-grade signal
+	log.info(
+		{
+			accountConfigId,
+			addressId,
+			category,
+			limit: SENDER_CATEGORY_BACKAPPLY_LIMIT,
+			...result,
+		},
+		"Sender category back-apply pass finished",
+	);
+
+	if (result.failed > 0) {
+		throw new Error(
+			`Sender category back-apply left ${result.failed} of ${result.matched} messages unlabelled for address ${addressId}`,
+		);
+	}
+};