@remit/backend 0.0.42 → 0.0.44

package/package.json

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

package/src/derive/enrichThreadRows.ts

@@ -7,7 +7,7 @@ import type {
 	ThreadMessageItem,
 } from "@remit/data-ports";
 import { deriveAddressId } from "@remit/data-ports/id";
-import { MessageCategory, SenderTrust, StarColor } from "@remit/domain-enums";
+import { SenderTrust, StarColor } from "@remit/domain-enums";
 import { deriveAutoMoved } from "./autoMoved.js";
 import { deriveSenderTrust } from "./senderTrust.js";
 
@@ -50,6 +50,7 @@ const toResponse = (item: ThreadMessageItem): ThreadMessageResponse => ({
 	hasStars: item.hasStars,
 	isDeleted: item.isDeleted,
 	snippet: item.snippet,
+	category: item.category,
 	createdAt: item.createdAt,
 	updatedAt: item.updatedAt,
 	senderTrust: SenderTrust.Unknown,
@@ -97,19 +98,20 @@ export const planBatchFetch = (rows: ThreadMessageItem[]): BatchPlan => {
 };
 
 /**
- * Enrich a page of ThreadMessage rows with `category` (from the underlying
- * Message), `senderTrust` (derived from the From Address's flags map) and
- * `autoMoved` (projected from the Message's internal placement verdict, see
- * `deriveAutoMoved`).
+ * Enrich a page of ThreadMessage rows with `senderTrust` (derived from the From
+ * Address's flags map), `authenticity` and `autoMoved` (both projected from the
+ * Message row, see `deriveAutoMoved`).
+ *
+ * `category` is not enriched: it is denormalized onto the ThreadMessage row and
+ * carried straight through by `toResponse`, so the value a client renders is the
+ * value the category filter matched.
  *
  * Two BatchGetItem calls per page, regardless of page size — see
  * `planBatchFetch` for the dedup contract.
  *
- * Missing rows fall back gracefully: `category` is omitted only when the
- * underlying Message row is absent (clients treat as `personal`); a present
- * Message with no stored category coalesces to `uncategorized` (RFC 032 Tier 2).
- * `senderTrust` defaults to `"unknown"`. `autoMoved` is omitted whenever the
- * move isn't a real, in-effect auto-move (or the Message row is absent).
+ * Missing rows fall back gracefully: `senderTrust` defaults to `"unknown"`, and
+ * `authenticity` / `autoMoved` are omitted whenever the Message row is absent or
+ * the move isn't a real, in-effect auto-move.
  *
  * Not annotated `Promise<ThreadMessageResponse[]>`: `labels` is a new field on
  * it in this same PR, and that package publishes separately from this repo —
@@ -158,12 +160,6 @@ export const enrichThreadRows = async (
 		}
 	}
 
-	const categoryByMessageId = new Map(
-		messages.map((m) => [
-			m.messageId,
-			m.category ?? MessageCategory.uncategorized,
-		]),
-	);
 	const authenticityByMessageId = new Map(
 		messages.map((m) => [m.messageId, m.authenticity]),
 	);
@@ -176,7 +172,6 @@ export const enrichThreadRows = async (
 
 	return rows.map((row) => {
 		const base = toResponse(row);
-		const category = categoryByMessageId.get(row.messageId);
 		const authenticity = authenticityByMessageId.get(row.messageId);
 		const autoMoved = autoMovedByMessageId.get(row.messageId);
 		const addressId = plan.addressIdByRow.get(row.threadMessageId);
@@ -186,7 +181,6 @@ export const enrichThreadRows = async (
 		const labels = labelsByMessageId.get(row.messageId);
 		return {
 			...base,
-			...(category !== undefined ? { category } : {}),
 			...(authenticity !== undefined ? { authenticity } : {}),
 			...(autoMoved !== undefined ? { autoMoved } : {}),
 			...(labels !== undefined ? { labels } : {}),

package/src/derive/filterThreadCriteria.test.ts

@@ -25,6 +25,7 @@ const row = (
 	star: StarColor.None,
 	isDeleted: false,
 	snippet: "",
+	category: MessageCategory.uncategorized,
 	createdAt: 0,
 	updatedAt: 0,
 	senderTrust: SenderTrust.Unknown,
@@ -37,7 +38,7 @@ describe("hasOffRowCriteria", () => {
 	});
 
 	it("is false for empty arrays", () => {
-		assert.equal(hasOffRowCriteria({ senderTrust: [], category: [] }), false);
+		assert.equal(hasOffRowCriteria({ senderTrust: [] }), false);
 	});
 
 	it("is true when any criterion is set", () => {
@@ -65,17 +66,12 @@ describe("filterByOffRowCriteria", () => {
 		assert.ok(result.every((r) => r.senderTrust !== SenderTrust.Unknown));
 	});
 
-	it("filters by category any-of and excludes rows with no category", () => {
+	it("leaves category alone — it is a SQL predicate, not an off-row criterion", () => {
 		const rows = [
 			row({ category: MessageCategory.newsletter }),
 			row({ category: MessageCategory.personal }),
-			row({ category: undefined }),
 		];
-		const result = filterByOffRowCriteria(rows, {
-			category: [MessageCategory.newsletter],
-		});
-		assert.equal(result.length, 1);
-		assert.equal(result[0].category, MessageCategory.newsletter);
+		assert.equal(filterByOffRowCriteria(rows, {}).length, 2);
 	});
 
 	it("filters by dkimMismatch and never matches rows lacking an authenticity signal", () => {

package/src/derive/filterThreadCriteria.ts

@@ -1,31 +1,31 @@
 import type {
-	MessageCategory,
 	SenderTrust,
 	ThreadMessageResponse,
 } from "@remit/api-openapi-types";
 
 /**
  * Off-row search criteria — fields that live on the underlying Message/Address,
- * not on the ThreadMessage DynamoDB item. They are resolved by enriching the
- * windowed rows (see enrichThreadRows) and filtering in app code, because no
- * index or FilterExpression can serve them.
+ * not on the ThreadMessage row. They are resolved by enriching the windowed
+ * rows (see enrichThreadRows) and filtering in app code, because no index or
+ * FilterExpression can serve them.
+ *
+ * `senderTrust` derives from AddressItem.flags and `dkimMismatch` from
+ * MessageItem.authenticity. `category` is not one of these: it is denormalized
+ * onto the ThreadMessage row and filtered in SQL, inside the window.
  */
 export interface OffRowCriteria {
 	senderTrust?: SenderTrust[];
-	category?: MessageCategory[];
 	dkimMismatch?: boolean;
 }
 
 export const hasOffRowCriteria = (criteria: OffRowCriteria): boolean =>
-	Boolean(criteria.senderTrust?.length) ||
-	Boolean(criteria.category?.length) ||
-	criteria.dkimMismatch !== undefined;
+	Boolean(criteria.senderTrust?.length) || criteria.dkimMismatch !== undefined;
 
 /**
  * Filter enriched rows by the off-row criteria. Each active criterion is an
- * any-of set (AND across criteria, OR within a set). A row with no `category`
- * never matches a category filter; a row with no `authenticity` signal never
- * matches a `dkimMismatch` filter (absence means no signal, not a verdict).
+ * any-of set (AND across criteria, OR within a set). A row with no
+ * `authenticity` signal never matches a `dkimMismatch` filter (absence means no
+ * signal, not a verdict).
  */
 export const filterByOffRowCriteria = (
 	rows: ThreadMessageResponse[],
@@ -36,19 +36,10 @@ export const filterByOffRowCriteria = (
 	const trustSet = criteria.senderTrust?.length
 		? new Set(criteria.senderTrust)
 		: undefined;
-	const categorySet = criteria.category?.length
-		? new Set(criteria.category)
-		: undefined;
 	const { dkimMismatch } = criteria;
 
 	return rows.filter((row) => {
 		if (trustSet && !trustSet.has(row.senderTrust)) return false;
-		if (
-			categorySet &&
-			(row.category === undefined || !categorySet.has(row.category))
-		) {
-			return false;
-		}
 		if (
 			dkimMismatch !== undefined &&
 			row.authenticity?.dkimMismatch !== dkimMismatch

package/src/handlers/filter.test.ts

@@ -1,8 +1,23 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import type { UpdateFilterInput as UpdateFilterRequestBody } from "@remit/api-openapi-types";
-import { FilterScope, FilterState } from "@remit/domain-enums";
+import { describe, it, mock } from "node:test";
+import type {
+	CreateFilterInput,
+	UpdateFilterInput as UpdateFilterRequestBody,
+} from "@remit/api-openapi-types";
+import type {
+	CreateFilterAnchorInput,
+	CreateFilterInput as FilterAnchorTxCreateInput,
+	FilterItem,
+} from "@remit/data-ports";
 import {
+	FilterMatchOperator,
+	FilterScope,
+	FilterState,
+} from "@remit/domain-enums";
+import type { AnchorPayload } from "@remit/search-service";
+import {
+	createFilterWithAnchor,
+	type FilterCrudDeps,
 	pickFilterUpdate,
 	rejectAnchorMutation,
 	resolveFilterScopeExpiry,
@@ -163,3 +178,139 @@ describe("resolveFilterScopeExpiry (reader #266)", () => {
 		);
 	});
 });
+
+describe("createFilterWithAnchor (#351)", () => {
+	const ACCOUNT_CONFIG_ID = "acct-1";
+
+	const baseInput: CreateFilterInput = {
+		name: "Booking confirmations",
+		scope: FilterScope.Standing,
+		matchOperator: FilterMatchOperator.And,
+		literalClauses: [],
+		actionLabelId: "None",
+		actionMailboxId: "None",
+	};
+
+	const baseFilter: FilterItem = {
+		filterId: "filter-1",
+		accountConfigId: ACCOUNT_CONFIG_ID,
+		name: baseInput.name,
+		scope: FilterScope.Standing,
+		state: FilterState.Active,
+		hasAnchor: false,
+		ruleChangedAt: 1_700_000_000,
+		matchOperator: FilterMatchOperator.And,
+		literalClauses: [],
+		actionLabelId: "None",
+		actionMailboxId: "None",
+		createdAt: 1_700_000_000_000,
+		updatedAt: 1_700_000_000_000,
+	};
+
+	const anchorPayload: AnchorPayload = {
+		anchorEmbedding: [0.1, 0.2, 0.3],
+		anchorEmbeddingId: "amazon.titan-embed-text-v2:0@1024",
+		anchorSourceText: "Your booking is confirmed",
+	};
+
+	type AnchorArg = Omit<CreateFilterAnchorInput, "filterId"> | null;
+	const createWithAnchorMock = (
+		impl: (
+			filter: FilterAnchorTxCreateInput,
+			anchor: AnchorArg,
+		) => Promise<FilterItem>,
+	) => mock.fn(impl);
+
+	it("creates a purely-literal filter through one atomic call when there is no anchor message", async () => {
+		const createWithAnchor = createWithAnchorMock(async () => baseFilter);
+		const deps: FilterCrudDeps = {
+			filterAnchorTransaction: { createWithAnchor },
+			buildAnchor: mock.fn(async () => null),
+		};
+
+		const filter = await createFilterWithAnchor(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			baseInput,
+		);
+
+		assert.equal(filter, baseFilter);
+		assert.equal(createWithAnchor.mock.calls.length, 1);
+		const [filterArg, anchorArg] = createWithAnchor.mock.calls[0].arguments;
+		assert.equal(filterArg.hasAnchor, false);
+		assert.equal(anchorArg, null);
+	});
+
+	it("passes the built anchor and the new hasAnchor flag to the same atomic call", async () => {
+		const createWithAnchor = createWithAnchorMock(async () => ({
+			...baseFilter,
+			hasAnchor: true,
+		}));
+		const buildAnchor = mock.fn(async () => anchorPayload);
+		const deps: FilterCrudDeps = {
+			filterAnchorTransaction: { createWithAnchor },
+			buildAnchor,
+		};
+		const input: CreateFilterInput = {
+			...baseInput,
+			anchorMessageId: "msg-1",
+		};
+
+		const filter = await createFilterWithAnchor(deps, ACCOUNT_CONFIG_ID, input);
+
+		assert.equal(filter.hasAnchor, true);
+		assert.equal(buildAnchor.mock.calls.length, 1);
+		assert.deepEqual(buildAnchor.mock.calls[0].arguments, [
+			ACCOUNT_CONFIG_ID,
+			"msg-1",
+		]);
+
+		assert.equal(createWithAnchor.mock.calls.length, 1);
+		const [filterArg, anchorArg] = createWithAnchor.mock.calls[0].arguments;
+		assert.equal(filterArg.hasAnchor, true);
+		assert.deepEqual(anchorArg, {
+			accountConfigId: ACCOUNT_CONFIG_ID,
+			anchorMessageId: "msg-1",
+			anchorEmbedding: anchorPayload.anchorEmbedding,
+			anchorEmbeddingId: anchorPayload.anchorEmbeddingId,
+			anchorSourceText: anchorPayload.anchorSourceText,
+		});
+	});
+
+	it("creates a purely-literal filter when the anchor message has no indexed chunks", async () => {
+		const createWithAnchor = createWithAnchorMock(async () => baseFilter);
+		const deps: FilterCrudDeps = {
+			filterAnchorTransaction: { createWithAnchor },
+			buildAnchor: mock.fn(async () => null),
+		};
+		const input: CreateFilterInput = {
+			...baseInput,
+			anchorMessageId: "msg-with-no-chunks",
+		};
+
+		await createFilterWithAnchor(deps, ACCOUNT_CONFIG_ID, input);
+
+		const [filterArg, anchorArg] = createWithAnchor.mock.calls[0].arguments;
+		assert.equal(filterArg.hasAnchor, false);
+		assert.equal(anchorArg, null);
+	});
+
+	it("propagates a failed atomic write as a failed create request, not a silent partial success", async () => {
+		const createWithAnchor = createWithAnchorMock(async () => {
+			throw new Error("anchor write failed");
+		});
+		const deps: FilterCrudDeps = {
+			filterAnchorTransaction: { createWithAnchor },
+			buildAnchor: mock.fn(async () => anchorPayload),
+		};
+		const input: CreateFilterInput = {
+			...baseInput,
+			anchorMessageId: "msg-1",
+		};
+
+		await assert.rejects(
+			createFilterWithAnchor(deps, ACCOUNT_CONFIG_ID, input),
+			/anchor write failed/,
+		);
+	});
+});

package/src/handlers/filter.ts

@@ -3,7 +3,11 @@ import type {
 	FilterResponse,
 	UpdateFilterInput as UpdateFilterRequestBody,
 } from "@remit/api-openapi-types";
-import type { FilterItem, UpdateFilterInput } from "@remit/data-ports";
+import type {
+	FilterItem,
+	IFilterAnchorTransaction,
+	UpdateFilterInput,
+} from "@remit/data-ports";
 import { BadRequestError } from "@remit/data-ports/errors";
 import { FilterScope, FilterState } from "@remit/domain-enums";
 import type { AnchorPayload } from "@remit/search-service";
@@ -19,46 +23,18 @@ import type {
 import { assertAccountOwnership } from "./account-ownership.js";
 
 /**
- * Minimal filter-service surface the CRUD handlers need — declared as a `Pick`
- * so tests can stub it without a live table.
+ * Minimal filter-service surface the create handler needs — declared as a
+ * `Pick` so tests can stub it without a live table.
  */
 export interface FilterCrudDeps {
-	filter: {
-		create(input: {
-			accountConfigId: string;
-			name: string;
-			scope: FilterItem["scope"];
-			expiresAt?: string;
-			ttl?: number;
-			matchOperator: FilterItem["matchOperator"];
-			literalClauses: FilterItem["literalClauses"];
-			actionLabelId: string;
-			actionMailboxId: string;
-			hasAnchor: boolean;
-		}): Promise<FilterItem>;
-		get(accountConfigId: string, filterId: string): Promise<FilterItem>;
-		update(
-			accountConfigId: string,
-			filterId: string,
-			input: UpdateFilterInput,
-		): Promise<FilterItem>;
-		delete(accountConfigId: string, filterId: string): Promise<void>;
-		refreshExpiry(item: FilterItem): Promise<FilterItem>;
-		listPageByAccountConfig(
-			accountConfigId: string,
-			options?: { limit?: number; continuationToken?: string },
-		): Promise<{ items: FilterItem[]; continuationToken: string | undefined }>;
-	};
-	filterAnchor: {
-		put(input: {
-			accountConfigId: string;
-			filterId: string;
-			anchorMessageId: string;
-			anchorEmbedding: number[];
-			anchorEmbeddingId: string;
-			anchorSourceText: string;
-		}): Promise<unknown>;
-	};
+	/**
+	 * Creates the `Filter` row and its optional sibling `FilterAnchor` row in
+	 * one transaction (#351) — a failure on the anchor write can never leave a
+	 * `Filter` durably marked `hasAnchor: true` with no matching anchor row,
+	 * and it surfaces as a failed create request rather than a silently
+	 * broken filter.
+	 */
+	filterAnchorTransaction: IFilterAnchorTransaction;
 	buildAnchor(
 		accountConfigId: string,
 		anchorMessageId: string,
@@ -221,12 +197,11 @@ const toFilterResponse = (item: FilterItem): FilterResponse => ({
 
 /**
  * Create a filter, wiring the semantic anchor when `anchorMessageId` is set
- * (RFC 034 Decision 2). The anchor is built first, before the row is written,
- * so `hasAnchor` is set correctly at creation and the sibling `FilterAnchor`
- * row is written against the new `filterId` — never a second round-trip that
- * would bump `ruleChangedAt`. A message with no indexed chunks yields no anchor:
- * the filter is created as purely literal (`hasAnchor: false`) rather than with
- * an empty anchor.
+ * (RFC 034 Decision 2). The anchor is built first, then the `Filter` row and
+ * its sibling `FilterAnchor` row are written together in one transaction
+ * (#351) — never as two independent writes a partial failure could split. A
+ * message with no indexed chunks yields no anchor: the filter is created as
+ * purely literal (`hasAnchor: false`) rather than with an empty anchor.
  */
 export const createFilterWithAnchor = async (
 	deps: FilterCrudDeps,
@@ -238,31 +213,29 @@ export const createFilterWithAnchor = async (
 		? await deps.buildAnchor(accountConfigId, anchorMessageId)
 		: null;
 
-	const filter = await deps.filter.create({
-		accountConfigId,
-		name: input.name,
-		scope: input.scope,
-		expiresAt: input.expiresAt,
-		ttl: deriveFilterTtl(input.scope, input.expiresAt),
-		matchOperator: input.matchOperator,
-		literalClauses: input.literalClauses,
-		actionLabelId: input.actionLabelId,
-		actionMailboxId: input.actionMailboxId,
-		hasAnchor: anchor !== null,
-	});
-
-	if (anchor && anchorMessageId) {
-		await deps.filterAnchor.put({
+	return deps.filterAnchorTransaction.createWithAnchor(
+		{
 			accountConfigId,
-			filterId: filter.filterId,
-			anchorMessageId,
-			anchorEmbedding: anchor.anchorEmbedding,
-			anchorEmbeddingId: anchor.anchorEmbeddingId,
-			anchorSourceText: anchor.anchorSourceText,
-		});
-	}
-
-	return filter;
+			name: input.name,
+			scope: input.scope,
+			expiresAt: input.expiresAt,
+			ttl: deriveFilterTtl(input.scope, input.expiresAt),
+			matchOperator: input.matchOperator,
+			literalClauses: input.literalClauses,
+			actionLabelId: input.actionLabelId,
+			actionMailboxId: input.actionMailboxId,
+			hasAnchor: anchor !== null,
+		},
+		anchor && anchorMessageId
+			? {
+					accountConfigId,
+					anchorMessageId,
+					anchorEmbedding: anchor.anchorEmbedding,
+					anchorEmbeddingId: anchor.anchorEmbeddingId,
+					anchorSourceText: anchor.anchorSourceText,
+				}
+			: null,
+	);
 };
 
 export const FilterOperations: Record<
@@ -311,8 +284,7 @@ export const FilterOperations: Record<
 
 		const filter = await createFilterWithAnchor(
 			{
-				filter: client.filter,
-				filterAnchor: client.filterAnchor,
+				filterAnchorTransaction: client.filterAnchorTransaction,
 				buildAnchor: buildFilterAnchor,
 			},
 			accountConfigId,

package/src/handlers/thread.test.ts

@@ -1,10 +1,19 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
+import type { ThreadMessageItem } from "@remit/data-ports";
+import { MessageCategory, SenderTrust, StarColor } from "@remit/domain-enums";
 import {
 	buildListThreadMessagesOptions,
+	buildListThreadsOptions,
+	buildSearchThreadsOptions,
 	dedupeThreadMessages,
+	executeThreadSearch,
+	type ThreadSearchClient,
 } from "./thread.js";
 
+const ACCOUNT = "cfg-1";
+const MAILBOX = "mbx-inbox";
+
 type Row = {
 	threadMessageId: string;
 	messageIdHeader?: string;
@@ -84,3 +93,156 @@ describe("dedupeThreadMessages", () => {
 		assert.deepEqual(dedupeThreadMessages([]), []);
 	});
 });
+
+// #304: `category` is a column on the thread_message row, so it is a SQL
+// predicate the port applies inside its window — not a criterion resolved by
+// enriching whatever the window happened to return. These assertions are on the
+// routing, because that is what a later refactor can silently undo: the SQL
+// clause goes dead and the filter falls back to a window-sized filter with no
+// test failing.
+describe("executeThreadSearch", () => {
+	type Category = ThreadMessageItem["category"];
+
+	const threadRow = (
+		threadMessageId: string,
+		category: Category,
+	): ThreadMessageItem => ({
+		threadMessageId,
+		threadId: `t-${threadMessageId}`,
+		messageId: `m-${threadMessageId}`,
+		accountConfigId: ACCOUNT,
+		mailboxId: MAILBOX,
+		uid: 1,
+		referenceOrder: 0,
+		internalDate: 0,
+		sentDate: 0,
+		isRead: false,
+		hasAttachment: false,
+		star: StarColor.None,
+		hasStars: false,
+		isDeleted: false,
+		category,
+		createdAt: 0,
+		updatedAt: 0,
+	});
+
+	type RecordedCall = { search: { category?: Category[] } };
+
+	const fakeClient = (rows: ThreadMessageItem[]) => {
+		const windowCalls: RecordedCall[] = [];
+		const countCalls: RecordedCall[] = [];
+
+		// The fake applies the category predicate itself, the way a port does, so
+		// a request that never reaches `search` cannot answer correctly by
+		// accident.
+		const matching = (categories?: Category[]) =>
+			categories?.length
+				? rows.filter((row) => categories.includes(row.category))
+				: rows;
+
+		const client: ThreadSearchClient = {
+			threadMessage: {
+				async searchByMailboxWindow(_account, _mailbox, search) {
+					windowCalls.push({ search });
+					return {
+						items: matching(search.category),
+						continuationToken: undefined,
+					};
+				},
+				async countByMailbox(_account, _mailbox, search) {
+					countCalls.push({ search });
+					return matching(search.category).length;
+				},
+			},
+			message: { get: async () => [] },
+			address: { getAddress: async () => [] },
+			messageLabel: { listByMessageIds: async () => [] },
+			label: { listByAccountConfig: async () => [] },
+		};
+
+		return { client, windowCalls, countCalls };
+	};
+
+	const ACCOUNT_ROWS = [
+		threadRow("tm-1", MessageCategory.personal),
+		threadRow("tm-2", MessageCategory.marketing),
+		threadRow("tm-3", MessageCategory.uncategorized),
+	];
+
+	it("passes category to the port's search, not to the off-row filter", async () => {
+		const { client, windowCalls } = fakeClient(ACCOUNT_ROWS);
+
+		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
+			category: [MessageCategory.personal],
+		});
+
+		assert.deepEqual(windowCalls.length, 1);
+		assert.deepEqual(windowCalls[0].search.category, [
+			MessageCategory.personal,
+		]);
+		assert.deepEqual(
+			response.items?.map((item) => item.threadMessageId),
+			["tm-1"],
+		);
+	});
+
+	it("takes the count-only path for a category-only query", async () => {
+		const { client, windowCalls, countCalls } = fakeClient(ACCOUNT_ROWS);
+
+		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
+			category: [MessageCategory.personal, MessageCategory.marketing],
+			count: true,
+			results: false,
+		});
+
+		assert.equal(windowCalls.length, 0, "no window read in count-only mode");
+		assert.equal(countCalls.length, 1);
+		assert.deepEqual(countCalls[0].search.category, [
+			MessageCategory.personal,
+			MessageCategory.marketing,
+		]);
+		assert.equal(response.count, 2);
+		assert.equal(response.items, undefined);
+	});
+
+	// The one request shape that still takes the off-row branch. `category` must
+	// reach `search` anyway, so the window is category-filtered before the
+	// enrichment the off-row criterion needs.
+	it("keeps category in search when an off-row criterion is also set", async () => {
+		const { client, windowCalls } = fakeClient(ACCOUNT_ROWS);
+
+		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
+			category: [MessageCategory.personal],
+			senderTrust: [SenderTrust.Unknown],
+		});
+
+		assert.equal(windowCalls.length, 1);
+		assert.deepEqual(windowCalls[0].search.category, [
+			MessageCategory.personal,
+		]);
+		assert.deepEqual(
+			response.items?.map((item) => item.threadMessageId),
+			["tm-1"],
+		);
+	});
+
+	it("serves category from the row, so it survives an absent message row", async () => {
+		const { client } = fakeClient(ACCOUNT_ROWS);
+
+		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {});
+
+		assert.deepEqual(
+			response.items?.map((item) => item.category),
+			[
+				MessageCategory.personal,
+				MessageCategory.marketing,
+				MessageCategory.uncategorized,
+			],
+		);
+	});
+
+	it("projects category, so the DynamoDB port reads it with the row", () => {
+		assert.ok(buildSearchThreadsOptions({}).attributes.includes("category"));
+		assert.ok(buildListThreadsOptions({}).attributes.includes("category"));
+	});
+});

package/src/handlers/thread.ts

@@ -48,6 +48,7 @@ const THREAD_LIST_ATTRIBUTES: ReadonlyArray<keyof ThreadMessageItem> = [
 	"hasStars",
 	"isDeleted",
 	"snippet",
+	"category",
 	"createdAt",
 	"updatedAt",
 ];
@@ -109,6 +110,7 @@ type ThreadSearch = {
 	unread?: boolean;
 	starred?: boolean;
 	attachments?: boolean;
+	category?: MessageCategory[];
 };
 
 /**
@@ -174,10 +176,10 @@ export const executeThreadSearch = async (
 		unread: params.unread,
 		starred: params.starred,
 		attachments: params.attachments,
+		category: params.category,
 	};
 	const offRow = {
 		senderTrust: params.senderTrust,
-		category: params.category,
 		dkimMismatch: params.dkimMismatch,
 	};
 	const wantCount = params.count === true;

package/src/handlers/unified-threads.ts

@@ -325,7 +325,7 @@ export const dedupeByMessageId = <T extends { messageId: string }>(
 /**
  * Attach accountId to each enriched ThreadMessageResponse row using the
  * mailboxId→accountId map built from inbox discovery. Same read-time-attach
- * pattern as senderTrust/category in enrichThreadRows.
+ * pattern as senderTrust in enrichThreadRows.
  */
 export const attachAccountIds = (
 	rows: Awaited<ReturnType<typeof enrichThreadRows>>,

package/src/service/compose-postgres.ts

@@ -5,6 +5,7 @@ import {
 	AccountSettingRepo,
 	AddressRepo,
 	DrizzleEnvelopeRepository,
+	DrizzleFilterAnchorTransaction,
 	DrizzleMessageFlagRepository,
 	DrizzleMessageRepository,
 	DrizzleThreadMessageRepository,
@@ -65,6 +66,7 @@ export const buildPostgresClient = (): RemitClient => {
 		flagPush: new MessageFlagPushRepo(genericDb),
 		filter: new FilterRepo(genericDb),
 		filterAnchor: new FilterAnchorRepo(genericDb),
+		filterAnchorTransaction: new DrizzleFilterAnchorTransaction(genericDb),
 		label: new LabelRepo(genericDb),
 		messageLabel: new MessageLabelRepo(genericDb),
 		unitOfWork: new DrizzleUnitOfWork(messageDataDb),

package/src/service/compose-sqlite.ts

@@ -6,6 +6,7 @@ import {
 	AddressRepo,
 	createSqliteDatabase,
 	DrizzleEnvelopeRepository,
+	DrizzleFilterAnchorTransaction,
 	DrizzleMessageFlagRepository,
 	DrizzleMessageRepository,
 	DrizzleThreadMessageRepository,
@@ -73,6 +74,7 @@ export const buildSqliteClient = async (): Promise<RemitClient> => {
 		flagPush: new MessageFlagPushRepo(genericDb),
 		filter: new FilterRepo(genericDb),
 		filterAnchor: new FilterAnchorRepo(genericDb),
+		filterAnchorTransaction: new DrizzleFilterAnchorTransaction(genericDb),
 		label: new LabelRepo(genericDb),
 		messageLabel: new MessageLabelRepo(genericDb),
 		unitOfWork: new DrizzleUnitOfWork(messageDataDb),

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

@@ -6,6 +6,7 @@ import type {
 	IAddressRepository,
 	IEnvelopeRepository,
 	IFilterAnchorRepository,
+	IFilterAnchorTransaction,
 	IFilterRepository,
 	ILabelRepository,
 	IMailboxLockRepository,
@@ -90,6 +91,11 @@ export interface RemitClient {
 	// on the row still existing, so the missing reaper is housekeeping only.
 	filter: IFilterRepository;
 	filterAnchor: IFilterAnchorRepository;
+
+	// Atomically creates a Filter and its optional sibling FilterAnchor row in
+	// one transaction (#351) — a failed anchor write can never leave a Filter
+	// durably marked hasAnchor: true with no matching FilterAnchor row.
+	filterAnchorTransaction: IFilterAnchorTransaction;
 	label: ILabelRepository;
 	messageLabel: IMessageLabelRepository;
 
@@ -163,6 +169,7 @@ export interface RemitClientRepositories {
 	flagPush: IMessageFlagPushRepository;
 	filter: IFilterRepository;
 	filterAnchor: IFilterAnchorRepository;
+	filterAnchorTransaction: IFilterAnchorTransaction;
 	label: ILabelRepository;
 	messageLabel: IMessageLabelRepository;
 	unitOfWork?: IUnitOfWork;
@@ -365,6 +372,7 @@ export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
 		organizeJobRequest: repositories.organizeJobRequest,
 		filter: repositories.filter,
 		filterAnchor: repositories.filterAnchor,
+		filterAnchorTransaction: repositories.filterAnchorTransaction,
 		label: repositories.label,
 		messageLabel: repositories.messageLabel,
 		unitOfWork: repositories.unitOfWork,