@remit/backend 0.0.25 → 0.0.27

package/package.json

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

package/src/derive/autoMoved.test.ts

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { MessageItem } from "@remit/data-ports";
+import { PlacementAction, PlacementConfidence } from "@remit/domain-enums";
+import { deriveAutoMoved } from "./autoMoved.js";
+
+type AutoMovedInput = Pick<
+	MessageItem,
+	"movedByRemit" | "placementVerdict" | "filterMove"
+>;
+
+const confidentVerdict = {
+	action: PlacementAction.MoveToInbox,
+	confidence: PlacementConfidence.Confident,
+	fromPlacement: "junk",
+	reasons: ["provider=spam", "dmarc=pass"],
+	dryRun: false,
+	decidedAt: 1_700_000_000_000,
+};
+
+const filterMove = {
+	filterId: "flt-1",
+	sourceMailboxId: "mb-inbox",
+	destinationMailboxId: "mb-travel",
+	decidedAt: 1_700_000_000_000,
+};
+
+describe("deriveAutoMoved", () => {
+	it("returns undefined when the message was not moved by Remit", () => {
+		const message: AutoMovedInput = {
+			movedByRemit: false,
+			placementVerdict: confidentVerdict,
+		};
+		assert.equal(deriveAutoMoved(message), undefined);
+	});
+
+	it("projects a standing-filter move to its mailbox ids and filter id", () => {
+		const message: AutoMovedInput = { movedByRemit: true, filterMove };
+		assert.deepEqual(deriveAutoMoved(message), {
+			fromMailboxId: "mb-inbox",
+			destinationMailboxId: "mb-travel",
+			filterId: "flt-1",
+		});
+	});
+
+	it("never leaks the classifier action/fromPlacement for a filter move", () => {
+		const result = deriveAutoMoved({ movedByRemit: true, filterMove });
+		assert.equal(result?.action, undefined);
+		assert.equal(result?.fromPlacement, undefined);
+	});
+
+	it("a filter move outranks a co-present placement verdict", () => {
+		// Both a filter move and a classifier verdict can be recorded; the filter's
+		// exclusive move is what ultimately placed the message (RFC 034 Dec. 3.1).
+		const message: AutoMovedInput = {
+			movedByRemit: true,
+			filterMove,
+			placementVerdict: confidentVerdict,
+		};
+		assert.deepEqual(deriveAutoMoved(message), {
+			fromMailboxId: "mb-inbox",
+			destinationMailboxId: "mb-travel",
+			filterId: "flt-1",
+		});
+	});
+
+	it("projects a confident classifier move to action + fromPlacement", () => {
+		const message: AutoMovedInput = {
+			movedByRemit: true,
+			placementVerdict: confidentVerdict,
+		};
+		assert.deepEqual(deriveAutoMoved(message), {
+			action: PlacementAction.MoveToInbox,
+			fromPlacement: "junk",
+		});
+	});
+
+	it("drops an unsure classifier verdict", () => {
+		const message: AutoMovedInput = {
+			movedByRemit: true,
+			placementVerdict: {
+				...confidentVerdict,
+				confidence: PlacementConfidence.Unsure,
+			},
+		};
+		assert.equal(deriveAutoMoved(message), undefined);
+	});
+
+	it("drops a dry-run classifier verdict", () => {
+		const message: AutoMovedInput = {
+			movedByRemit: true,
+			placementVerdict: { ...confidentVerdict, dryRun: true },
+		};
+		assert.equal(deriveAutoMoved(message), undefined);
+	});
+
+	it("does not crash on legacy verdict-less, filter-less moved data", () => {
+		// A message moved before either the verdict or the filter marker existed:
+		// movedByRemit is set but nothing is derivable. Must return undefined, not
+		// throw (issue #223 back-compat).
+		const message: AutoMovedInput = { movedByRemit: true };
+		assert.equal(deriveAutoMoved(message), undefined);
+	});
+});

package/src/derive/autoMoved.ts

@@ -3,19 +3,47 @@ import type { MessageItem } from "@remit/data-ports";
 import { PlacementConfidence } from "@remit/domain-enums";
 
 /**
- * Project a Message's internal placement verdict to the public `AutoMovedInfo`
- * shape. Present only for a real, in-effect auto-move — `movedByRemit` is
- * true, the verdict is `Confident`, and it was not a dry run. Confidence,
- * dryRun, decidedAt and reasons are internal diagnostics and never cross to
- * the wire; the client derives everything else (whether the move is still in
- * effect, the undo target) from `action`/`fromPlacement` plus current
- * placement.
+ * Project a Message's internal auto-move state to the public `AutoMovedInfo`
+ * shape. Present only for a real, in-effect auto-move; absent otherwise, so a
+ * message synced before either mechanism existed (no `filterMove`, no
+ * `placementVerdict`) projects nothing and renders no badge.
+ *
+ * Two mechanisms move mail and both raise `movedByRemit`:
+ *
+ * 1. A standing filter (RFC 034) records a `filterMove` marker naming the
+ *    source folder, the destination folder, and the filter. It has no
+ *    classifier direction/role, so the projection carries mailbox ids
+ *    (`fromMailboxId`/`destinationMailboxId`) and the `filterId` for the
+ *    Settings link — an arbitrary destination the Inbox/Junk-shaped `action`
+ *    cannot name.
+ * 2. The Tier 0 classifier records a `placementVerdict`. Its `action`
+ *    (MoveToInbox/MoveToJunk) and `fromPlacement` (inbox/junk/other) are the
+ *    only fields that cross to the wire; confidence, dryRun, decidedAt and
+ *    reasons stay internal.
+ *
+ * The filter marker outranks the verdict check: a matched filter's move is
+ * exclusive and outranks the classifier's placement move at index time (RFC 034
+ * Decision 3.1), so a message carrying both was ultimately moved by the filter.
+ * The client derives everything else (whether the move is still in effect, the
+ * undo target) from these fields plus current placement.
  */
 export const deriveAutoMoved = (
-	message: Pick<MessageItem, "movedByRemit" | "placementVerdict">,
+	message: Pick<
+		MessageItem,
+		"movedByRemit" | "placementVerdict" | "filterMove"
+	>,
 ): AutoMovedInfo | undefined => {
 	if (message.movedByRemit !== true) return undefined;
 
+	const filterMove = message.filterMove;
+	if (filterMove) {
+		return {
+			fromMailboxId: filterMove.sourceMailboxId,
+			destinationMailboxId: filterMove.destinationMailboxId,
+			filterId: filterMove.filterId,
+		};
+	}
+
 	const verdict = message.placementVerdict;
 	if (!verdict) return undefined;
 	if (verdict.confidence !== PlacementConfidence.Confident) return undefined;

package/src/handlers/index.ts

@@ -16,6 +16,7 @@ import { OrganizeJobDetailOperations, OrganizeOperations } from "./organize.js";
 import { OutboxDetailOperations, OutboxOperations } from "./outbox.js";
 import { SemanticSearchOperations } from "./search.js";
 import { SyncOperations } from "./sync.js";
+import { SystemOperations } from "./system-update.js";
 import { ThreadDetailOperations, ThreadOperations } from "./thread.js";
 import { UnifiedThreadOperations } from "./unified-threads.js";
 
@@ -23,6 +24,7 @@ import { UnifiedThreadOperations } from "./unified-threads.js";
 export const handlers: Record<OperationIds, OperationHandler<any>> = {
 	...MeOperations,
 	...ConfigOperations,
+	...SystemOperations,
 	...AccountOperations,
 	...AccountDetailOperations,
 	...MicrosoftOAuthOperations,

package/src/handlers/system-update.test.ts

@@ -0,0 +1,286 @@
+import assert from "node:assert/strict";
+import {
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { createInstanceOwnerStore } from "@remit/auth-service";
+import type { APIGatewayProxyEvent } from "aws-lambda";
+import Database from "better-sqlite3";
+import type { Context } from "openapi-backend";
+import { SystemOperations } from "./system-update.js";
+
+const tmpRoot = join(
+	fileURLToPath(new URL(".", import.meta.url)),
+	"..",
+	"..",
+	".tmp",
+	"system-update",
+);
+
+const readMigrationSql = (relativePath: string): string =>
+	readFileSync(fileURLToPath(new URL(relativePath, import.meta.url)), "utf8");
+
+const authMigrationSql = readMigrationSql(
+	"../../../../deploy/vps/migrations-sqlite/auth/0000_rainy_iron_monger.sql",
+);
+const metaMigrationSql = readMigrationSql(
+	"../../../../deploy/vps/migrations-sqlite/meta/0000_demonic_lilith.sql",
+);
+
+const OWNER = "the-owner";
+const MANIFEST_URL = "https://updates.example.com/stable.json";
+
+let dbPath: string;
+let controlDir: string;
+
+const okState = {
+	currentVersion: "v1.4.1",
+	check: {
+		status: "ok",
+		lastCheckedAt: "2026-07-20T08:00:00Z",
+		latestVersion: "v1.5.0",
+		publishedAt: "2026-07-18T09:00:00Z",
+		summary: "Faster search.",
+		releaseNotesUrl: "https://example.com/notes",
+		updateAvailable: true,
+	},
+	run: null,
+};
+
+const writeState = (state: unknown): void => {
+	writeFileSync(join(controlDir, "state.json"), JSON.stringify(state));
+};
+
+before(async () => {
+	mkdirSync(tmpRoot, { recursive: true });
+	dbPath = join(mkdtempSync(join(tmpRoot, "db-")), "app.db");
+	const sqlite = new Database(dbPath);
+	for (const sql of [authMigrationSql, metaMigrationSql]) {
+		for (const statement of sql.split("--> statement-breakpoint")) {
+			sqlite.exec(statement);
+		}
+	}
+	sqlite
+		.prepare(
+			"INSERT INTO auth_user (id, name, email, email_verified, created_at, updated_at) VALUES (?, ?, ?, 0, ?, ?)",
+		)
+		.run(OWNER, OWNER, "owner@example.com", 1000, 1000);
+	sqlite.close();
+	process.env.DATA_BACKEND = "sqlite";
+	process.env.SQLITE_DB_PATH = dbPath;
+	const store = await createInstanceOwnerStore({
+		provider: "sqlite",
+		connectionString: dbPath,
+	});
+	await store.claimIfUnclaimed(OWNER);
+	await store.close();
+});
+
+after(() => {
+	rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+	controlDir = mkdtempSync(join(tmpRoot, "control-"));
+	process.env.REMIT_UPDATE_CONTROL_DIR = controlDir;
+	process.env.REMIT_UPDATE_MANIFEST_URL = MANIFEST_URL;
+	process.env.REMIT_TAG = "v1.4.1";
+});
+
+afterEach(() => {
+	delete process.env.REMIT_UPDATE_MANIFEST_URL;
+	delete process.env.REMIT_UPDATE_CONTROL_DIR;
+	delete process.env.REMIT_TAG;
+});
+
+const buildEvent = (sub?: string): APIGatewayProxyEvent =>
+	({
+		headers: {},
+		requestContext: sub ? { authorizer: { claims: { sub } } } : {},
+	}) as unknown as APIGatewayProxyEvent;
+
+const postContext = (targetVersion: string): Context =>
+	({ request: { requestBody: { targetVersion } } }) as unknown as Context;
+
+const getSystemUpdate =
+	SystemOperations.SystemOperations_getSystemUpdate as unknown as (
+		context: Context,
+		event: APIGatewayProxyEvent,
+	) => Promise<unknown>;
+
+const applySystemUpdate =
+	SystemOperations.SystemOperations_applySystemUpdate as unknown as (
+		context: Context,
+		event: APIGatewayProxyEvent,
+	) => Promise<unknown>;
+
+const getUpdate = (event: APIGatewayProxyEvent) =>
+	getSystemUpdate({} as unknown as Context, event);
+
+const applyUpdate = (targetVersion: string, event: APIGatewayProxyEvent) =>
+	applySystemUpdate(postContext(targetVersion), event);
+
+const hasStatus = (value: unknown, code: number): boolean =>
+	typeof value === "object" &&
+	value !== null &&
+	(value as { statusCode?: number }).statusCode === code;
+
+describe("GET /system/update", () => {
+	it("returns 404 when no manifest URL is configured", async () => {
+		delete process.env.REMIT_UPDATE_MANIFEST_URL;
+
+		const result = await getUpdate(buildEvent(OWNER));
+
+		assert.ok(hasStatus(result, 404));
+	});
+
+	it("returns 403 for a non-owner", async () => {
+		const result = await getUpdate(buildEvent("someone-else"));
+
+		assert.ok(hasStatus(result, 403));
+	});
+
+	it("returns 200 with the state file verbatim", async () => {
+		writeState(okState);
+
+		const result = await getUpdate(buildEvent(OWNER));
+
+		assert.deepEqual(result, okState);
+	});
+
+	it("returns a disabled, empty resource when no state file exists", async () => {
+		const result = await getUpdate(buildEvent(OWNER));
+
+		assert.deepEqual(result, {
+			currentVersion: "v1.4.1",
+			check: { status: "disabled" },
+			run: null,
+		});
+	});
+
+	it("returns 200 with the run block untouched when the check has failed", async () => {
+		const run = {
+			runId: "run-1",
+			fromVersion: "v1.3.0",
+			targetVersion: "v1.4.1",
+			phase: "committing",
+			outcome: "succeeded",
+			startedAt: "2026-07-19T08:00:00Z",
+			updatedAt: "2026-07-19T08:05:00Z",
+			message: "Update installed.",
+			logCommand: "remit logs backend",
+		};
+		writeState({
+			currentVersion: "v1.4.1",
+			check: {
+				status: "failed",
+				lastCheckedAt: "2026-07-20T08:00:00Z",
+				error: "The update manifest could not be fetched.",
+			},
+			run,
+		});
+
+		const result = (await getUpdate(buildEvent(OWNER))) as {
+			check: { status: string };
+			run: unknown;
+		};
+
+		assert.equal(result.check.status, "failed");
+		assert.deepEqual(result.run, run);
+	});
+});
+
+describe("POST /system/update", () => {
+	it("returns 404 when no manifest URL is configured", async () => {
+		delete process.env.REMIT_UPDATE_MANIFEST_URL;
+
+		const result = await applyUpdate("v1.5.0", buildEvent(OWNER));
+
+		assert.ok(hasStatus(result, 404));
+	});
+
+	it("returns 403 for a non-owner", async () => {
+		writeState(okState);
+
+		const result = await applyUpdate("v1.5.0", buildEvent("someone-else"));
+
+		assert.ok(hasStatus(result, 403));
+	});
+
+	it("returns 409 when a run is already in flight", async () => {
+		writeState({
+			...okState,
+			run: {
+				runId: "run-9",
+				fromVersion: "v1.4.1",
+				targetVersion: "v1.5.0",
+				phase: "verifying",
+				outcome: null,
+				startedAt: "2026-07-20T08:01:00Z",
+				updatedAt: "2026-07-20T08:04:00Z",
+				message: "Waiting for the new version to answer.",
+				logCommand: "remit logs backend",
+			},
+		});
+
+		await assert.rejects(applyUpdate("v1.5.0", buildEvent(OWNER)), {
+			statusCode: 409,
+		});
+	});
+
+	it("returns 422 when the target is not the checked version", async () => {
+		writeState(okState);
+
+		await assert.rejects(applyUpdate("v9.9.9", buildEvent(OWNER)), {
+			statusCode: 422,
+		});
+	});
+
+	it("returns 422 when no check has ever succeeded", async () => {
+		await assert.rejects(applyUpdate("v1.5.0", buildEvent(OWNER)), {
+			statusCode: 422,
+		});
+	});
+
+	it("returns 202 with a run block carrying a fresh runId", async () => {
+		writeState(okState);
+
+		const result = (await applyUpdate("v1.5.0", buildEvent(OWNER))) as {
+			statusCode: number;
+			body: { run: { runId: string; targetVersion: string; outcome: null } };
+		};
+
+		assert.equal(result.statusCode, 202);
+		assert.equal(result.body.run.targetVersion, "v1.5.0");
+		assert.equal(result.body.run.outcome, null);
+		assert.ok(result.body.run.runId.length > 0);
+	});
+
+	it("writes request.json with exactly the four seam fields and nothing else", async () => {
+		writeState(okState);
+
+		await applyUpdate("v1.5.0", buildEvent(OWNER));
+
+		const request = JSON.parse(
+			readFileSync(join(controlDir, "request.json"), "utf8"),
+		);
+
+		assert.deepEqual(Object.keys(request).sort(), [
+			"requestedAt",
+			"requestedBy",
+			"runId",
+			"targetVersion",
+		]);
+		assert.equal(request.targetVersion, "v1.5.0");
+		assert.equal(request.requestedBy, OWNER);
+		for (const forbidden of ["registry", "image", "digest"]) {
+			assert.ok(!(forbidden in request));
+		}
+	});
+});

package/src/handlers/system-update.ts

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type {
+	SystemUpdateResponse,
+	SystemUpdateRun,
+} from "@remit/api-openapi-types";
+import { ConflictError, HTTPError } from "@remit/data-ports/errors";
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import type { Context } from "openapi-backend";
+import { getSubFromEvent } from "../auth.js";
+import type { OperationHandler, SystemOperationIds } from "../types.js";
+import { requireInstanceOwner } from "./owner-guard.js";
+
+class TargetVersionMismatchError extends HTTPError {
+	name = "TargetVersionMismatchError";
+	statusCode = 422;
+}
+
+const DEFAULT_CONTROL_DIR = "/data/control";
+
+const controlDir = (): string =>
+	process.env.REMIT_UPDATE_CONTROL_DIR ?? DEFAULT_CONTROL_DIR;
+
+const manifestUrl = (): string | undefined =>
+	process.env.REMIT_UPDATE_MANIFEST_URL;
+
+const currentVersion = (): string => process.env.REMIT_TAG ?? "unknown";
+
+const notFound = (): APIGatewayProxyResult => ({
+	statusCode: 404,
+	headers: { "Content-Type": "application/json" },
+	body: JSON.stringify({ message: "Not found" }),
+});
+
+/**
+ * The self-update seam is off unless a manifest URL is configured (RFC 037 D8),
+ * which the hosted deployment leaves unset. Both endpoints answer 404 in that
+ * case — before the owner guard, so a probe cannot tell an off surface from a
+ * forbidden one.
+ */
+const guardManifestConfigured = (): APIGatewayProxyResult | null =>
+	manifestUrl() ? null : notFound();
+
+/**
+ * Read `state.json` off the control volume. A missing file is an instance that
+ * has never checked or updated (RFC 037 D8), not an error, so it reads as
+ * `null`; the caller renders the disabled/empty resource. Any other read or
+ * parse failure propagates.
+ */
+const readState = (): SystemUpdateResponse | null => {
+	let raw: string;
+	try {
+		raw = readFileSync(join(controlDir(), "state.json"), "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+	return JSON.parse(raw) as SystemUpdateResponse;
+};
+
+const emptyResource = (): SystemUpdateResponse => ({
+	currentVersion: currentVersion(),
+	check: { status: "disabled" },
+	run: null,
+});
+
+const isRunInFlight = (run: SystemUpdateRun | null | undefined): boolean =>
+	run != null && run.outcome === null;
+
+/**
+ * The version the caller may install is the one the last check reported. It
+ * exists only on a successful check; a disabled or failed check offers nothing
+ * to match, so any target is a mismatch.
+ */
+const checkedVersion = (
+	state: SystemUpdateResponse | null,
+): string | undefined =>
+	state?.check.status === "ok" ? state.check.latestVersion : undefined;
+
+/**
+ * Write `request.json` atomically with exactly the four fields the seam accepts
+ * (#133). The updater resolves the registry and every image reference from the
+ * manifest it fetches itself; a request naming any of those is rejected whole,
+ * so the backend never writes one. The temp file sits in the same directory as
+ * the target for the rename to be atomic on one filesystem.
+ */
+const writeRequest = (request: {
+	runId: string;
+	targetVersion: string;
+	requestedAt: string;
+	requestedBy: string;
+}): void => {
+	const dir = controlDir();
+	const tmp = join(dir, `.request.json.${request.runId}.tmp`);
+	writeFileSync(tmp, JSON.stringify(request), { mode: 0o644 });
+	renameSync(tmp, join(dir, "request.json"));
+};
+
+/**
+ * The resource returned by the POST. The updater has not yet written the
+ * authoritative run — it polls the seam — so this bootstraps the run block with
+ * the id just requested and the first phase, giving the client a `runId` to
+ * persist and poll (RFC 037 D9). The updater's own `state.json` supersedes it on
+ * the next read.
+ */
+const requestedResource = (
+	state: SystemUpdateResponse | null,
+	runId: string,
+	targetVersion: string,
+	requestedAt: string,
+): SystemUpdateResponse => {
+	const from = state?.currentVersion ?? currentVersion();
+	return {
+		currentVersion: from,
+		check: state?.check ?? { status: "disabled" },
+		run: {
+			runId,
+			fromVersion: from,
+			targetVersion,
+			phase: "checking",
+			outcome: null,
+			startedAt: requestedAt,
+			updatedAt: requestedAt,
+			message: "The update has been requested.",
+			logCommand: "remit logs updater",
+		},
+	};
+};
+
+export const SystemOperations: Record<
+	SystemOperationIds,
+	OperationHandler<SystemOperationIds>
+> = {
+	SystemOperations_getSystemUpdate: async (
+		_context: Context,
+		...args: unknown[]
+	): Promise<SystemUpdateResponse | APIGatewayProxyResult> => {
+		const offSurface = guardManifestConfigured();
+		if (offSurface) return offSurface;
+
+		const event = args[0] as APIGatewayProxyEvent;
+		const forbidden = await requireInstanceOwner(event);
+		if (forbidden) return forbidden;
+
+		return readState() ?? emptyResource();
+	},
+
+	SystemOperations_applySystemUpdate: async (
+		context: Context,
+		...args: unknown[]
+	): Promise<SystemUpdateResponse | APIGatewayProxyResult> => {
+		const offSurface = guardManifestConfigured();
+		if (offSurface) return offSurface;
+
+		const event = args[0] as APIGatewayProxyEvent;
+		const forbidden = await requireInstanceOwner(event);
+		if (forbidden) return forbidden;
+
+		const { targetVersion } = context.request.requestBody as {
+			targetVersion: string;
+		};
+		const state = readState();
+
+		if (isRunInFlight(state?.run)) {
+			throw new ConflictError("An update is already in progress.");
+		}
+
+		if (targetVersion !== checkedVersion(state)) {
+			throw new TargetVersionMismatchError(
+				"targetVersion does not match the latest checked release.",
+			);
+		}
+
+		const runId = randomUUID();
+		const requestedAt = new Date().toISOString();
+		writeRequest({
+			runId,
+			targetVersion,
+			requestedAt,
+			requestedBy: getSubFromEvent(event) ?? "",
+		});
+
+		return {
+			statusCode: 202,
+			body: requestedResource(state, runId, targetVersion, requestedAt),
+		} as unknown as APIGatewayProxyResult;
+	},
+};

package/src/service/create-remit-client.ts

@@ -33,6 +33,7 @@ import {
 	MailboxQueueService,
 	MessageMoveService,
 	OutboxQueueService,
+	PlacementMoveService,
 } from "@remit/mailbox-service";
 import { createSearchService, type SearchService } from "@remit/search-service";
 import {
@@ -287,6 +288,34 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 		bodySyncQueue,
 	} = deps;
 
+	// The read-path body backfill (describeMessage / getRawMessage →
+	// fetchAndGetBody) materializes a body that was never sync-synced, and must
+	// run the account's standing filters the same way the imap-worker's sync path
+	// does. Without this, a message a user opens before background body-sync is
+	// classified but never filter-evaluated — and once its body is stored the
+	// filter-capable sync path skips it, so an explicit standing filter silently
+	// never fires (issue #223). Only the explicit user-rule half is wired here;
+	// heuristic classifier placement stays on the sync path. Wired like
+	// `sync-message-body.ts`, over the message-management queue's local-first
+	// PlacementMoveService; filters stay off when that queue is unset.
+	const placementMoveQueueUrl = process.env.SQS_QUEUE_URL_MESSAGE_MGMT;
+	const placementMoveService = placementMoveQueueUrl
+		? new PlacementMoveService({
+				messageService: repositories.message,
+				threadMessageService: repositories.threadMessage,
+				markerService: repositories.placementMove,
+				sqsQueueUrl: placementMoveQueueUrl,
+			})
+		: undefined;
+	const filterConfig = placementMoveService
+		? {
+				filterService: repositories.filter,
+				filterAnchorService: repositories.filterAnchor,
+				messageLabelService: repositories.messageLabel,
+				placementMoveService,
+			}
+		: undefined;
+
 	const bodySync = new BodySyncService(
 		repositories.message,
 		storage,
@@ -294,6 +323,8 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 		repositories.address,
 		repositories.envelope,
 		logger,
+		undefined,
+		filterConfig,
 	);
 
 	const flagPushService = new FlagPushService({

package/src/types.ts

@@ -12,6 +12,8 @@ export type OperationIds =
 	| "MeOperations_getExport"
 	| "MeOperations_listQuarantine"
 	| "ConfigOperations_getConfig"
+	| "SystemOperations_getSystemUpdate"
+	| "SystemOperations_applySystemUpdate"
 	| "AccountOperations_createAccount"
 	| "AccountOperations_testConnection"
 	| "AccountDetailOperations_updateAccount"
@@ -60,6 +62,8 @@ export type MeOperationIds = MatchPrefix<"MeOperations_", OperationIds>;
 
 export type ConfigOperationIds = MatchPrefix<"ConfigOperations_", OperationIds>;
 
+export type SystemOperationIds = MatchPrefix<"SystemOperations_", OperationIds>;
+
 export type AccountOperationIds = MatchPrefix<
 	"AccountOperations_",
 	OperationIds