@remit/backend 0.0.40 → 0.0.42

package/dev-server/server.ts

@@ -1,5 +1,12 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { logger } from "@remit/logger-lambda";
+import {
+	metricsContentType,
+	onScrape,
+	renderMetrics,
+	setAccountSyncAges,
+} from "@remit/logger-lambda/metrics";
 import { isStorageNotFoundError } from "@remit/storage-service";
 import type { APIGatewayProxyResult } from "aws-lambda";
 import { env } from "expect-env";
@@ -17,6 +24,7 @@ import { resolveContentPath } from "./content-path.js";
 import { parseAllowedOrigins, resolveAllowOrigin } from "./cors.js";
 import { createLambdaContext, createLambdaEvent } from "./lambda-helpers.js";
 import { checkRelationalStore } from "./relational-health.js";
+import { collectAccountSyncAges } from "./sync-age.js";
 
 const app = express();
 
@@ -137,6 +145,35 @@ app.get("/health", async (_req: Request, res: Response) => {
 	});
 });
 
+// The scrape endpoint (standalone-observability D2), on the port this server
+// already serves on and never routed through Caddy — deploy/vps/caddy/routes.caddy
+// proxies /api/*, /content/* and /health, and everything else goes to the static
+// web server, so there is no path from the public origin to this route.
+//
+// The per-account sync age is a database read, so it is collected when a scrape
+// arrives rather than tracked as syncs complete. A read that fails fails the
+// scrape: a signal that could not be evaluated must not render as a healthy
+// number. Only the self-host backends have a store to read here — the
+// AWS-local dev path composes its client from outside this module.
+if (isSelfHostBackend) {
+	onScrape(async () => {
+		const client = await getClient();
+		setAccountSyncAges(await collectAccountSyncAges(client, Date.now()));
+	});
+}
+
+app.get("/metrics", async (_req: Request, res: Response) => {
+	const body = await renderMetrics().catch((error: unknown) => {
+		logger.error({ error: String(error) }, "Metrics collection failed");
+		return null;
+	});
+	if (body === null) {
+		res.status(500).type("text/plain").send("metrics collection failed\n");
+		return;
+	}
+	res.setHeader("content-type", metricsContentType).send(body);
+});
+
 // Swagger UI exposes the full API schema, so it must never be on the public
 // surface. On the self-host backends this server is the deployed backend
 // container; gate the docs to the AWS-local dev path only. The generated

package/dev-server/sync-age.test.ts

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { AccountItem, MailboxItem } from "@remit/data-ports";
+import { collectAccountSyncAges, type SyncAgeSource } from "./sync-age.js";
+
+const NOW = 1_700_000_000_000;
+
+const account = (overrides: Partial<AccountItem>): AccountItem =>
+	({
+		accountId: "acct-1",
+		createdAt: NOW - 600_000,
+		lastSyncAt: NOW,
+		...overrides,
+	}) as AccountItem;
+
+const mailbox = (lastMessageSyncAt: number): MailboxItem =>
+	({ mailboxId: `mbx-${lastMessageSyncAt}`, lastMessageSyncAt }) as MailboxItem;
+
+const source = (
+	accounts: AccountItem[],
+	mailboxes: Record<string, MailboxItem[]>,
+): SyncAgeSource => ({
+	account: { listAll: async () => accounts },
+	mailbox: {
+		listAllByAccount: async (accountId: string) => mailboxes[accountId] ?? [],
+	},
+});
+
+describe("collectAccountSyncAges", () => {
+	it("measures from the newest mailbox message-sync stamp", async () => {
+		const ages = await collectAccountSyncAges(
+			source([account({})], {
+				"acct-1": [mailbox(NOW - 300_000), mailbox(NOW - 60_000)],
+			}),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 60 }]);
+	});
+
+	it("ignores account.lastSyncAt, which is stamped before the message fan-out", async () => {
+		// lastSyncAt is fresh and every message handler has been failing for an
+		// hour. The exported age must report the hour.
+		const ages = await collectAccountSyncAges(
+			source([account({ lastSyncAt: NOW })], {
+				"acct-1": [mailbox(NOW - 3_600_000)],
+			}),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 3600 }]);
+	});
+
+	it("treats an unstamped mailbox as never synced", async () => {
+		const ages = await collectAccountSyncAges(
+			source([account({ createdAt: NOW - 900_000 })], {
+				"acct-1": [mailbox(0)],
+			}),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 900 }]);
+	});
+
+	it("reports an account with no mailboxes at all rather than omitting it", async () => {
+		const ages = await collectAccountSyncAges(
+			source([account({ createdAt: NOW - 120_000 })], {}),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 120 }]);
+	});
+
+	it("skips a deleted account", async () => {
+		const ages = await collectAccountSyncAges(
+			source(
+				[
+					account({ accountId: "gone", deletedAt: NOW - 1000 }),
+					account({ accountId: "live" }),
+				],
+				{ live: [mailbox(NOW - 30_000)] },
+			),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "live", ageSeconds: 30 }]);
+	});
+
+	it("never reports a negative age when a stamp is ahead of the clock", async () => {
+		const ages = await collectAccountSyncAges(
+			source([account({})], { "acct-1": [mailbox(NOW + 5_000)] }),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 0 }]);
+	});
+});

package/dev-server/sync-age.ts

@@ -0,0 +1,55 @@
+import type { IAccountRepository, IMailboxRepository } from "@remit/data-ports";
+
+export interface SyncAgeSource {
+	readonly account: Pick<IAccountRepository, "listAll">;
+	readonly mailbox: Pick<IMailboxRepository, "listAllByAccount">;
+}
+
+export interface AccountSyncAge {
+	readonly accountId: string;
+	readonly ageSeconds: number;
+}
+
+/**
+ * Seconds since each account last completed a message-sync round
+ * (standalone-observability D3).
+ *
+ * Measured from `mailbox.lastMessageSyncAt`, not `account.lastSyncAt`.
+ * `account.lastSyncAt` is stamped after the mailbox *list* sync and before the
+ * per-mailbox fan-out that fetches messages, so a deployment whose message
+ * handlers all throw keeps it fresh forever while no mail arrives.
+ * `lastMessageSyncAt` is stamped at the end of a message-sync round, after the
+ * fetch and the writes.
+ *
+ * The value is the age of the newest such stamp across the account's mailboxes:
+ * seconds since this account last completed a round trip that would have found
+ * new mail if there were any. An account with no stamped mailbox has never
+ * completed one, and reports the age of the account row instead of being
+ * omitted — "never synced" is the condition most worth seeing, not a gap in the
+ * series.
+ *
+ * Labelled by account id, never by address: a scraped label travels wherever
+ * the scrape goes.
+ */
+export const collectAccountSyncAges = async (
+	source: SyncAgeSource,
+	now: number,
+): Promise<AccountSyncAge[]> => {
+	const accounts = await source.account.listAll();
+	const ages: AccountSyncAge[] = [];
+	for (const account of accounts) {
+		if (account.deletedAt) continue;
+		const mailboxes = await source.mailbox.listAllByAccount(account.accountId);
+		const stamps = mailboxes
+			.map((mailbox) => mailbox.lastMessageSyncAt)
+			.filter(
+				(stamp): stamp is number => typeof stamp === "number" && stamp > 0,
+			);
+		const newest = stamps.length > 0 ? Math.max(...stamps) : account.createdAt;
+		ages.push({
+			accountId: account.accountId,
+			ageSeconds: Math.max(0, Math.round((now - newest) / 1000)),
+		});
+	}
+	return ages;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",

package/src/service/organize.test.ts

@@ -1,6 +1,8 @@
 import assert from "node:assert/strict";
 import { afterEach, beforeEach, describe, it } from "node:test";
-import { FilterMatchOperator } from "@remit/domain-enums";
+import type { FilterAnchorItem, FilterItem } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { FilterMatchOperator, FilterState } from "@remit/domain-enums";
 import type {
 	AnchorPayload,
 	ChunkMetadata,
@@ -68,15 +70,51 @@ const predicate = (
 	...over,
 });
 
+/** A standing filter fixture — the "other" filters the precedence check reads. */
+const filterItem = (over: Partial<FilterItem> = {}): FilterItem => ({
+	filterId: "filter-other",
+	accountConfigId: ACCOUNT_CONFIG_ID,
+	name: "other filter",
+	scope: "Standing",
+	state: FilterState.Active,
+	hasAnchor: false,
+	ruleChangedAt: 0,
+	matchOperator: FilterMatchOperator.And,
+	literalClauses: [],
+	actionLabelId: "None",
+	actionMailboxId: "None",
+	createdAt: 0,
+	updatedAt: 0,
+	...over,
+});
+
 /**
  * A client that records MessageLabel writes and blows up if the back-apply path
  * ever touches Filter/FilterAnchor — the RFC 034 guardrail: this scope never
  * persists a standing rule.
+ *
+ * `activeFilters`/`filterAnchorRows`/`threadMessages` model the account's
+ * *other*, already-existing standing filters and message rows the exclusive-
+ * move precedence check (reader #350) reads — empty by default, so every
+ * existing test (which never seeded a competing filter) is unaffected and the
+ * precedence check is a same-length no-op.
  */
-const trackingClient = () => {
+const trackingClient = (
+	seed: {
+		activeFilters?: FilterItem[];
+		filterAnchorRows?: FilterAnchorItem[];
+		threadMessages?: Record<
+			string,
+			{ fromEmail?: string; fromName?: string; subject?: string }
+		>;
+	} = {},
+) => {
 	const labeled: Array<{ messageId: string; labelId: string }> = [];
 	let filterWrites = 0;
 	let filterAnchorWrites = 0;
+	const activeFilters = seed.activeFilters ?? [];
+	const filterAnchorRows = seed.filterAnchorRows ?? [];
+	const threadMessages = seed.threadMessages ?? {};
 	const client = {
 		messageLabel: {
 			apply: async (input: {
@@ -100,17 +138,36 @@ const trackingClient = () => {
 		mailbox: {
 			resolveAccountId: async () => "acct-1",
 		},
+		threadMessage: {
+			get: async (_accountConfigId: string, messageId: string) => {
+				const row = threadMessages[messageId];
+				if (!row) {
+					throw new NotFoundError("ThreadMessage not found");
+				}
+				return {
+					threadMessageId: messageId,
+					fromEmail: row.fromEmail,
+					fromName: row.fromName,
+					subject: row.subject,
+				} as never;
+			},
+		},
 		filter: {
 			create: async () => {
 				filterWrites += 1;
 				return {} as never;
 			},
+			listByAccountAndState: async () => activeFilters,
+			refreshExpiry: async (filter: FilterItem) => filter,
 		},
 		filterAnchor: {
 			put: async () => {
 				filterAnchorWrites += 1;
 				return {} as never;
 			},
+			get: async (_accountConfigId: string, filterId: string) =>
+				filterAnchorRows.find((row) => row.filterId === filterId) ?? null,
+			listByAccountConfig: async () => filterAnchorRows,
 		},
 	} as unknown as RemitClient;
 	return {
@@ -160,19 +217,30 @@ const trackingMoveService = () => {
  * Deps whose semantic side is the in-memory vector store — the vector-backed
  * deployment. `listAccountFilterMessages` returns the given corpus (empty by
  * default), and constructing the semantic side is tracked so a literal-only
- * predicate can be shown never to build it.
+ * predicate can be shown never to build it. `filterAnchorRows` seeds the
+ * account's *persisted* FilterAnchor rows (empty by default) — the reverse
+ * lookup back-apply's anchor consultation reads (reader #350) — and `embed`
+ * is a deterministic stand-in for the configured embedding model, used only
+ * by the exclusive-move precedence check.
  */
 const matchDeps = (
 	store: ReturnType<typeof createMemoryVectorStore>,
 	corpus: OrganizeCandidate[] = [],
+	filterAnchorRows: FilterAnchorItem[] = [],
 ): OrganizeMatchDeps & { semanticBuilds: () => number } => {
 	let semanticBuilds = 0;
 	return {
 		semantic: () => {
 			semanticBuilds += 1;
-			return { buildAnchor: async () => anchorPayload, vectorStore: store };
+			return {
+				buildAnchor: async () => anchorPayload,
+				vectorStore: store,
+				embed: async (text: string) =>
+					text.includes("reservation") ? ANCHOR_VECTOR : ORTHOGONAL_VECTOR,
+			};
 		},
 		listAccountFilterMessages: async () => corpus,
+		filterAnchors: { listByAccountConfig: async () => filterAnchorRows },
 		semanticBuilds: () => semanticBuilds,
 	};
 };
@@ -201,9 +269,13 @@ const vectorlessDeps = (
 						throw moduleNotFound();
 					},
 				},
+				embed: async () => {
+					throw moduleNotFound();
+				},
 			};
 		},
 		listAccountFilterMessages: async () => corpus,
+		filterAnchors: { listByAccountConfig: async () => [] },
 		semanticUsed: () => semanticUsed,
 	};
 };
@@ -305,6 +377,77 @@ describe("matchOrganize", () => {
 	});
 });
 
+describe("matchOrganize honors the persisted FilterAnchor (reader #350)", () => {
+	it("still matches by reading the persisted anchor after the anchor message is purged", async () => {
+		const store = createMemoryVectorStore();
+		const matching = ["msg-1", "msg-2"];
+		await store.upsert([
+			...matching.map((id) => bodyChunk(id, ANCHOR_VECTOR)),
+			bodyChunk("msg-miss", ORTHOGONAL_VECTOR),
+		]);
+
+		const persistedAnchor: FilterAnchorItem = {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			filterId: "filter-a",
+			anchorEmbedding: ANCHOR_VECTOR,
+			anchorEmbeddingId: "test-model@4",
+			anchorSourceText: "book me a table",
+			anchorMessageId: "msg-anchor",
+			createdAt: 0,
+			updatedAt: 0,
+		};
+
+		let buildAnchorCalls = 0;
+		const deps: OrganizeMatchDeps = {
+			semantic: () => ({
+				buildAnchor: async () => {
+					// The live path: the anchor message's chunks are gone (purged),
+					// exactly what buildMessageAnchor returns in that case today.
+					buildAnchorCalls += 1;
+					return null;
+				},
+				vectorStore: store,
+				embed: async () => ANCHOR_VECTOR,
+			}),
+			listAccountFilterMessages: async () => [],
+			filterAnchors: { listByAccountConfig: async () => [persistedAnchor] },
+		};
+
+		const { messageIds } = await matchOrganize(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			predicate(),
+		);
+
+		assert.deepEqual(
+			[...messageIds].sort(),
+			matching,
+			"the persisted anchor vector still finds the same matches the live message would have",
+		);
+		assert.equal(
+			buildAnchorCalls,
+			0,
+			"a persisted anchor must be read instead of re-deriving one from the (now-gone) live message",
+		);
+	});
+
+	it("falls back to deriving the anchor from the live message when no filter was ever anchored on it", async () => {
+		const store = createMemoryVectorStore();
+		await store.upsert([bodyChunk("msg-1", ANCHOR_VECTOR)]);
+
+		// No persisted FilterAnchor names this anchorMessageId — an ad hoc "all
+		// like these" widen over a bare message selection, never tied to a
+		// standing filter.
+		const { messageIds } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			predicate(),
+		);
+
+		assert.deepEqual(messageIds, ["msg-1"]);
+	});
+});
+
 describe("matchOrganize on a deployment without the vector pipeline", () => {
 	const ORIGINAL = process.env.DATA_BACKEND;
 	beforeEach(() => {
@@ -403,8 +546,10 @@ describe("matchOrganize on a deployment without the vector pipeline", () => {
 					query: async () => [],
 					getByMessage: async () => [],
 				},
+				embed: async () => [],
 			}),
 			listAccountFilterMessages: async () => [],
+			filterAnchors: { listByAccountConfig: async () => [] },
 		};
 
 		await assert.rejects(
@@ -437,7 +582,7 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 
 		const tracked = trackingClient();
 		const result = await applyOrganize(
-			{ client: tracked.client },
+			{ client: tracked.client, match: matchDeps(store) },
 			ACCOUNT_CONFIG_ID,
 			applied.messageIds,
 			p,
@@ -473,7 +618,7 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 		);
 		const tracked = trackingClient();
 		const result = await applyOrganize(
-			{ client: tracked.client },
+			{ client: tracked.client, match: matchDeps(store) },
 			ACCOUNT_CONFIG_ID,
 			matched,
 			p,
@@ -500,7 +645,11 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 		const tracked = trackingClient();
 		const mover = trackingMoveService();
 		const result = await applyOrganize(
-			{ client: tracked.client, moveService: mover.moveService },
+			{
+				client: tracked.client,
+				moveService: mover.moveService,
+				match: matchDeps(store),
+			},
 			ACCOUNT_CONFIG_ID,
 			matched,
 			p,
@@ -546,7 +695,11 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 		const tracked = trackingClient();
 		const mover = trackingMoveService();
 		const result = await applyOrganize(
-			{ client: tracked.client, moveService: mover.moveService },
+			{
+				client: tracked.client,
+				moveService: mover.moveService,
+				match: matchDeps(store),
+			},
 			ACCOUNT_CONFIG_ID,
 			matched,
 			p,
@@ -578,13 +731,21 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 		const mover = trackingMoveService();
 
 		const first = await applyOrganize(
-			{ client: tracked.client, moveService: mover.moveService },
+			{
+				client: tracked.client,
+				moveService: mover.moveService,
+				match: matchDeps(store),
+			},
 			ACCOUNT_CONFIG_ID,
 			matched,
 			p,
 		);
 		const second = await applyOrganize(
-			{ client: tracked.client, moveService: mover.moveService },
+			{
+				client: tracked.client,
+				moveService: mover.moveService,
+				match: matchDeps(store),
+			},
 			ACCOUNT_CONFIG_ID,
 			matched,
 			p,
@@ -605,6 +766,154 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 	});
 });
 
+describe("applyOrganize resolves move precedence against current Active filters (reader #350)", () => {
+	it("suppresses an out-ranked move but still applies the label", async () => {
+		const store = createMemoryVectorStore();
+		await store.upsert([bodyChunk("msg-1", ANCHOR_VECTOR)]);
+		// The back-applied filter — "move to mbox-old" — is out-ranked by a
+		// more-recently-changed standing filter that currently claims msg-1 for a
+		// different destination.
+		const p = predicate({
+			actionLabelId: "lbl-1",
+			actionMailboxId: "mbox-old",
+		});
+		const newerFilter = filterItem({
+			filterId: "filter-newer",
+			ruleChangedAt: 1_000,
+			actionMailboxId: "mbox-new",
+			literalClauses: [{ field: "Subject", value: "reservation" }],
+		});
+
+		const { messageIds: matched } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			p,
+		);
+		const tracked = trackingClient({
+			activeFilters: [newerFilter],
+			threadMessages: { "msg-1": { subject: "Dinner reservation" } },
+		});
+		const mover = trackingMoveService();
+		const result = await applyOrganize(
+			{
+				client: tracked.client,
+				moveService: mover.moveService,
+				match: matchDeps(store),
+			},
+			ACCOUNT_CONFIG_ID,
+			matched,
+			p,
+		);
+
+		assert.equal(result.applied, 1, "a suppressed move is not a failure");
+		assert.equal(result.failed, 0);
+		assert.deepEqual(
+			tracked.labeled,
+			[{ messageId: "msg-1", labelId: "lbl-1" }],
+			"the additive label still applies even though the move is suppressed",
+		);
+		assert.deepEqual(
+			mover.moves,
+			[],
+			"the exclusive move is skipped in favor of the newer filter's own move",
+		);
+	});
+
+	it("moves the message when no other Active filter currently outranks it", async () => {
+		const store = createMemoryVectorStore();
+		await store.upsert([bodyChunk("msg-1", ANCHOR_VECTOR)]);
+		const p = predicate({ actionMailboxId: "mbox-target" });
+		// A different standing filter matches this message too, but agrees on the
+		// same destination — nothing to defer to.
+		const agreeingFilter = filterItem({
+			filterId: "filter-agrees",
+			ruleChangedAt: 1_000,
+			actionMailboxId: "mbox-target",
+			literalClauses: [{ field: "Subject", value: "reservation" }],
+		});
+
+		const { messageIds: matched } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			p,
+		);
+		const tracked = trackingClient({
+			activeFilters: [agreeingFilter],
+			threadMessages: { "msg-1": { subject: "Dinner reservation" } },
+		});
+		const mover = trackingMoveService();
+		const result = await applyOrganize(
+			{
+				client: tracked.client,
+				moveService: mover.moveService,
+				match: matchDeps(store),
+			},
+			ACCOUNT_CONFIG_ID,
+			matched,
+			p,
+		);
+
+		assert.equal(result.applied, 1);
+		assert.equal(result.failed, 0);
+		assert.deepEqual(
+			mover.moves.map((m) => m.messageId),
+			["msg-1"],
+			"the move proceeds exactly as it would have before this check existed",
+		);
+	});
+
+	it("suppresses an out-ranked move by a newer *semantic* filter's persisted anchor", async () => {
+		const store = createMemoryVectorStore();
+		await store.upsert([bodyChunk("msg-1", ANCHOR_VECTOR)]);
+		const p = predicate({ actionMailboxId: "mbox-old" });
+		const newerSemanticFilter = filterItem({
+			filterId: "filter-newer-semantic",
+			ruleChangedAt: 1_000,
+			actionMailboxId: "mbox-new",
+			hasAnchor: true,
+		});
+		const persistedAnchor: FilterAnchorItem = {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			filterId: "filter-newer-semantic",
+			anchorEmbedding: ANCHOR_VECTOR,
+			anchorEmbeddingId: "test-model@4",
+			anchorSourceText: "book me a table",
+			anchorMessageId: "msg-anchor-2",
+			createdAt: 0,
+			updatedAt: 0,
+		};
+
+		const { messageIds: matched } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			p,
+		);
+		const tracked = trackingClient({
+			activeFilters: [newerSemanticFilter],
+			filterAnchorRows: [persistedAnchor],
+			threadMessages: { "msg-1": { subject: "Dinner reservation" } },
+		});
+		const mover = trackingMoveService();
+		const result = await applyOrganize(
+			{
+				client: tracked.client,
+				moveService: mover.moveService,
+				match: matchDeps(store, [], [persistedAnchor]),
+			},
+			ACCOUNT_CONFIG_ID,
+			matched,
+			p,
+		);
+
+		assert.equal(result.applied, 1);
+		assert.deepEqual(
+			mover.moves,
+			[],
+			"a newer semantic filter's own persisted anchor outranks the move",
+		);
+	});
+});
+
 describe("matchOrganize with ListId and FromDomain clauses", () => {
 	const senderChunk = (
 		messageId: string,
@@ -702,7 +1011,7 @@ describe("matchOrganize with ListId and FromDomain clauses", () => {
 
 		const tracked = trackingClient();
 		const result = await applyOrganize(
-			{ client: tracked.client },
+			{ client: tracked.client, match: deps },
 			ACCOUNT_CONFIG_ID,
 			applied.messageIds,
 			p,

package/src/service/organize.ts

@@ -1,11 +1,19 @@
-import type { FilterItem, OrganizeJobRequestItem } from "@remit/data-ports";
-import { FilterClauseField } from "@remit/domain-enums";
+import type {
+	FilterItem,
+	IFilterAnchorRepository,
+	OrganizeJobRequestItem,
+} from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
+import { FilterClauseField, FilterState } from "@remit/domain-enums";
 import {
+	buildMatchText,
+	cosineSimilarity,
 	DEFAULT_SEMANTIC_MATCH_THRESHOLD,
 	type FilterMessage,
 	literalClausesMatch,
 	NO_ACTION,
 	PlacementMoveService,
+	selectMoveWinner,
 } from "@remit/mailbox-service";
 import {
 	type AnchorPayload,
@@ -79,6 +87,15 @@ export interface OrganizeSemanticDeps {
 		anchorMessageId: string,
 	) => Promise<AnchorPayload | null>;
 	vectorStore: Pick<VectorStoreService, "query" | "getByMessage">;
+	/**
+	 * Embed one candidate message's text — used only by the cross-filter
+	 * precedence check ({@link findCurrentMoveWinner}) to compare a message
+	 * against a *different* Active filter's persisted anchor, the same
+	 * comparison `FilterPipeline.filterMatches` runs at index time. Never
+	 * called by the anchor widen itself, which only ever runs a vector-store
+	 * kNN read (see `semantic-capability.ts`).
+	 */
+	embed: (text: string) => Promise<number[]>;
 }
 
 /**
@@ -107,6 +124,17 @@ export interface OrganizeMatchDeps {
 		accountConfigId: string,
 		limit: number,
 	) => Promise<OrganizeCandidate[]>;
+	/**
+	 * Every persisted FilterAnchor for the account — read-only, always
+	 * available (never gated behind {@link semantic}, since it never touches
+	 * the vector store). A back-apply predicate carries only a bare
+	 * `anchorMessageId`, never a `filterId` (RFC 034 recap: this job is
+	 * deliberately not a Filter), so this is how {@link matchSemantic} finds
+	 * "the standing filter this anchor came from," if one still exists, to
+	 * read its fixed-at-save-time vector instead of re-deriving one from the
+	 * anchor message's current chunks (reader #350 / RFC 039 Decision 1).
+	 */
+	filterAnchors: Pick<IFilterAnchorRepository, "listByAccountConfig">;
 }
 
 /** The matched ids plus whether the semantic widen was skipped as unavailable. */
@@ -152,23 +180,61 @@ const filterMessageFromChunks = (
 };
 
 /**
- * The semantic (anchor) arm: pool the anchor vector from the anchor message's
- * existing chunk vectors, fan out with a k-NN query gated on the cosine
- * threshold, then refine by literal clauses reconstructed from the same chunk
- * vectors. Every read here goes through the vector store; a deployment without
- * the vector pipeline fails on the first call, which {@link matchOrganize}
- * catches. Returns null when the anchor message has no vectors to pool.
+ * The persisted FilterAnchor whose `anchorMessageId` matches this predicate's
+ * anchor, if the account has a standing filter built from that message (RFC
+ * 034 Decision 2 / RFC 039 Decision 1, reader #350). A back-apply predicate
+ * never carries a `filterId` — this job structurally is not a Filter — so the
+ * only way to recover "the filter this anchor came from" is by the value it
+ * was anchored on. The scan is over one account's (small, bounded) anchor
+ * rows, read-only, and never touches the vector store. Returns `undefined`
+ * when no standing filter was ever anchored on this message (or it has since
+ * been deleted), in which case the caller falls back to deriving the anchor
+ * live from the message's current chunk vectors, exactly as before.
+ */
+const findPersistedAnchor = async (
+	filterAnchors: Pick<IFilterAnchorRepository, "listByAccountConfig">,
+	accountConfigId: string,
+	anchorMessageId: string,
+): Promise<AnchorPayload | undefined> => {
+	const anchors = await filterAnchors.listByAccountConfig(accountConfigId);
+	const persisted = anchors.find(
+		(anchor) => anchor.anchorMessageId === anchorMessageId,
+	);
+	if (!persisted) return undefined;
+	return {
+		anchorEmbedding: persisted.anchorEmbedding,
+		anchorEmbeddingId: persisted.anchorEmbeddingId,
+		anchorSourceText: persisted.anchorSourceText,
+	};
+};
+
+/**
+ * The semantic (anchor) arm: read the anchor vector — the persisted
+ * `FilterAnchor` for a message a standing filter was built from (fixed at
+ * save time, unaffected by the anchor message's later deletion or
+ * re-chunking), or else pool it fresh from the anchor message's existing
+ * chunk vectors, the same as before this filter existed or ever had one.
+ * Fan out with a k-NN query gated on the cosine threshold, then refine by
+ * literal clauses reconstructed from the same chunk vectors. Every read here
+ * goes through the vector store; a deployment without the vector pipeline
+ * fails on the first call, which {@link matchOrganize} catches. Returns null
+ * when neither a persisted anchor nor the message's own chunk vectors exist
+ * to pool.
  */
 const matchSemantic = async (
-	semantic: OrganizeSemanticDeps,
+	deps: OrganizeMatchDeps,
 	accountConfigId: string,
 	predicate: OrganizePredicate,
 	limit: number,
 ): Promise<string[] | null> => {
-	const anchor = await semantic.buildAnchor(
-		accountConfigId,
-		predicate.anchorMessageId,
-	);
+	const semantic = deps.semantic();
+	const anchor =
+		(await findPersistedAnchor(
+			deps.filterAnchors,
+			accountConfigId,
+			predicate.anchorMessageId,
+		)) ??
+		(await semantic.buildAnchor(accountConfigId, predicate.anchorMessageId));
 	if (!anchor) return null;
 	const threshold =
 		predicate.similarityThreshold ?? DEFAULT_SEMANTIC_MATCH_THRESHOLD;
@@ -302,7 +368,7 @@ export const matchOrganize = async (
 
 	try {
 		const semanticIds = await matchSemantic(
-			deps.semantic(),
+			deps,
 			accountConfigId,
 			predicate,
 			limit,
@@ -343,6 +409,7 @@ const buildSemanticFromEnv = (): OrganizeSemanticDeps => {
 		buildAnchor: (accountConfigId, anchorMessageId) =>
 			buildMessageAnchor({ store }, { accountConfigId, anchorMessageId }),
 		vectorStore: store,
+		embed: async (text) => (await embedder.embed([text]))[0],
 	};
 	return cachedSemantic;
 };
@@ -404,6 +471,7 @@ export const buildOrganizeMatchDeps = (
 ): OrganizeMatchDeps => ({
 	semantic: buildSemanticFromEnv,
 	listAccountFilterMessages: listAccountFilterMessagesFromClient(client),
+	filterAnchors: client.filterAnchor,
 });
 
 /**
@@ -433,6 +501,13 @@ export const buildOrganizeMoveService = (
 export interface ApplyOrganizeDeps {
 	client: RemitClient;
 	moveService?: PlacementMoveService;
+	/**
+	 * The same matcher deps {@link matchOrganize} uses — reused here only for
+	 * their vector-store/embedder access, to compare a candidate message
+	 * against a *different* filter's persisted anchor when checking exclusive-
+	 * move precedence (RFC 039 Decision 2, reader #350).
+	 */
+	match: OrganizeMatchDeps;
 }
 
 export interface ApplyOrganizeResult {
@@ -440,6 +515,160 @@ export interface ApplyOrganizeResult {
 	failed: number;
 }
 
+/**
+ * The vector-free literal-match projection of one already-stored message,
+ * read from its ThreadMessage row — the same fields and the same fidelity
+ * tradeoff {@link listAccountFilterMessagesFromClient} accepts for the
+ * back-apply predicate's own literal clauses (full-fidelity From/Subject/
+ * ListId, empty body text, so a `HasWords` clause on a *different* filter
+ * cannot be proven to currently match here). `undefined` when the message no
+ * longer exists.
+ */
+const findFilterMessageForPrecedence = async (
+	client: Pick<RemitClient, "threadMessage">,
+	accountConfigId: string,
+	messageId: string,
+): Promise<FilterMessage | undefined> => {
+	const row = await client.threadMessage
+		.get(accountConfigId, messageId)
+		.catch((error: unknown) => {
+			if (error instanceof NotFoundError) return undefined;
+			throw error;
+		});
+	if (!row) return undefined;
+	return {
+		from: row.fromEmail ?? "",
+		fromName: row.fromName ?? "",
+		subject: row.subject ?? "",
+		text: "",
+		listId: row.listId ?? "",
+	};
+};
+
+/**
+ * Whether one *other* Active filter with a move action currently matches this
+ * message — mirrors `FilterPipeline.filterMatches` (mailbox-service
+ * filters/pipeline.ts) exactly: literal clauses first, then, for a filter
+ * with a semantic anchor, its own persisted `FilterAnchor` compared against
+ * the candidate's embedding. A stale/incompatible anchor on the *other*
+ * filter is isolated to that filter (skipped, not thrown) — the same
+ * resilience `filterMatches` gives index-time matching, so one bad anchor
+ * elsewhere never breaks this back-apply's move.
+ */
+const filterCurrentlyMatches = async (
+	filterAnchorService: Pick<IFilterAnchorRepository, "get">,
+	accountConfigId: string,
+	filter: FilterItem,
+	msg: FilterMessage,
+	embed: () => Promise<number[] | null>,
+): Promise<boolean> => {
+	if (!literalClausesMatch(filter.literalClauses, filter.matchOperator, msg)) {
+		return false;
+	}
+	if (!filter.hasAnchor) {
+		return filter.literalClauses.length > 0;
+	}
+	const anchor = await filterAnchorService.get(
+		accountConfigId,
+		filter.filterId,
+	);
+	if (!anchor) return false;
+	const vector = await embed();
+	if (!vector) return false;
+	try {
+		return (
+			cosineSimilarity(vector, anchor.anchorEmbedding) >=
+			DEFAULT_SEMANTIC_MATCH_THRESHOLD
+		);
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * The filter that currently wins this message's exclusive move, evaluated
+ * fresh against every Active filter with a move action — the same
+ * cross-filter arbitration index-time matching runs
+ * (`FilterPipeline`/`selectMoveWinner`), never the back-apply job's own
+ * snapshotted predicate (RFC 039 Decision 2, reader #350). This is what lets
+ * back-apply defer to a filter created or edited *after* the job was
+ * requested. `movers` is fetched once per {@link applyOrganize} call, not
+ * once per message — a back-apply pass runs in one short burst, so the
+ * account's Active filter set does not need re-reading per message.
+ *
+ * Returns `undefined` — meaning "nothing else contests this move" — whenever
+ * there are no other Active mover filters, or the message's own projection
+ * cannot be built (deleted between match and apply). Both are the common
+ * case and the safe default: proceed with the requested move exactly as
+ * before this check existed.
+ */
+const findCurrentMoveWinner = async (
+	deps: {
+		client: Pick<RemitClient, "threadMessage" | "filterAnchor">;
+		match: OrganizeMatchDeps;
+	},
+	movers: readonly FilterItem[],
+	accountConfigId: string,
+	messageId: string,
+): Promise<FilterItem | undefined> => {
+	if (movers.length === 0) return undefined;
+	const msg = await findFilterMessageForPrecedence(
+		deps.client,
+		accountConfigId,
+		messageId,
+	);
+	if (!msg) return undefined;
+
+	let messageEmbedding: number[] | null | undefined;
+	const embed = async (): Promise<number[] | null> => {
+		if (messageEmbedding !== undefined) return messageEmbedding;
+		try {
+			messageEmbedding = await deps.match.semantic().embed(buildMatchText(msg));
+		} catch (error) {
+			if (!noteSemanticCapabilityAbsence(error)) throw error;
+			messageEmbedding = null;
+		}
+		return messageEmbedding;
+	};
+
+	const matched: FilterItem[] = [];
+	for (const filter of movers) {
+		const isMatch = await filterCurrentlyMatches(
+			deps.client.filterAnchor,
+			accountConfigId,
+			filter,
+			msg,
+			embed,
+		);
+		if (isMatch) matched.push(filter);
+	}
+	return selectMoveWinner(matched);
+};
+
+/**
+ * Every currently-Active filter with a move action, its lazy Temporary-expiry
+ * check already applied — the fixed candidate set {@link findCurrentMoveWinner}
+ * arbitrates against for every message in this pass. Empty (and read exactly
+ * once) when no move action was requested, so a label-only back-apply never
+ * pays for this at all.
+ */
+const listCurrentMovers = async (
+	client: Pick<RemitClient, "filter">,
+	accountConfigId: string,
+): Promise<FilterItem[]> => {
+	const active = await client.filter.listByAccountAndState(
+		accountConfigId,
+		FilterState.Active,
+	);
+	const movers: FilterItem[] = [];
+	for (const filter of active) {
+		if (filter.actionMailboxId === NO_ACTION) continue;
+		const usable = await client.filter.refreshExpiry(filter);
+		if (usable.state === FilterState.Active) movers.push(usable);
+	}
+	return movers;
+};
+
 /**
  * Apply the back-apply action to every matched message, reusing the index-time
  * apply plumbing: an idempotent MessageLabel upsert (additive) with
@@ -447,6 +676,13 @@ export interface ApplyOrganizeResult {
  * exactly like a hand-applied label (RFC 034 Decision 3.3) — and an idempotent
  * folder move (exclusive). One poisoned message never fails the batch; it is
  * counted as failed and the pass continues.
+ *
+ * Before an exclusive move, resolves whether a *different* Active filter
+ * currently wins that message (RFC 039 Decision 2, reader #350): if so, the
+ * move is skipped for that message — the label action above, if requested,
+ * still applies, since labels are additive and always safe. A message with no
+ * contesting filter, or whose own back-applied filter is still the current
+ * winner, moves exactly as before this check existed.
  */
 export const applyOrganize = async (
 	deps: ApplyOrganizeDeps,
@@ -454,12 +690,16 @@ export const applyOrganize = async (
 	messageIds: readonly string[],
 	predicate: OrganizePredicate,
 ): Promise<ApplyOrganizeResult> => {
-	const { client, moveService } = deps;
+	const { client, moveService, match } = deps;
 	const applyLabel =
 		predicate.actionLabelId !== NO_ACTION && predicate.actionLabelId !== "";
 	const applyMove =
 		predicate.actionMailboxId !== NO_ACTION && predicate.actionMailboxId !== "";
 
+	const movers = applyMove
+		? await listCurrentMovers(client, accountConfigId)
+		: [];
+
 	const applyToMessage = async (messageId: string): Promise<void> => {
 		if (applyLabel) {
 			await client.messageLabel.apply({
@@ -469,6 +709,18 @@ export const applyOrganize = async (
 			});
 		}
 		if (applyMove) {
+			const winner = await findCurrentMoveWinner(
+				{ client, match },
+				movers,
+				accountConfigId,
+				messageId,
+			);
+			if (winner && winner.actionMailboxId !== predicate.actionMailboxId) {
+				// A more-recently-changed filter currently claims this message's
+				// move (RFC 034 Decision 3.2) — defer to it. The label above, if
+				// requested, has already applied; only the move is suppressed.
+				return;
+			}
 			if (!moveService) {
 				// An exclusive move was requested but this caller wired no move
 				// service. Never silently pretend it applied — surface it as a