@remit/backend 0.0.103 → 0.0.105

package/dev-server/oauth-callback-route.test.ts

@@ -0,0 +1,66 @@
+/**
+ * The OAuth callback through the dev-server's own app — the process a
+ * self-host container runs.
+ *
+ * One hop further than the handler test: the app object imported from
+ * `server.ts`, so what is asserted is the header express actually writes onto
+ * the socket for Microsoft's returning browser. The handler answering 302 is
+ * not the same claim as the browser being sent anywhere, and the difference
+ * between the two was a blank page.
+ *
+ * The identity tier is left unmounted — this app serves the route either way,
+ * and the callback's exemption from the session gate is pinned where that gate
+ * runs, in `src/handlers/account-oauth-callback.test.ts`.
+ */
+
+import assert from "node:assert/strict";
+import type { Server } from "node:http";
+import { after, before, describe, it } from "node:test";
+import {
+	_resetForTest,
+	type RemitClient,
+	setClient,
+} from "../src/service/data-client.js";
+
+const WEB_ORIGIN = "https://mail.example.com";
+
+let server: Server;
+let port: number;
+
+before(async () => {
+	// Microsoft's redirect carries no session, so the callback answers before it
+	// reads anything: no store is touched on this path.
+	setClient({} as unknown as RemitClient);
+
+	process.env.BETTER_AUTH_SECRET = "a-signing-secret-of-at-least-32-characters";
+	process.env.CORS_ALLOWED_ORIGINS = WEB_ORIGIN;
+	process.env.SERVER_PORT = "0";
+
+	const imported = await import("./server.js");
+	server = imported.listener;
+	if (!server.listening) {
+		await new Promise<void>((resolve) => server.once("listening", resolve));
+	}
+	const address = server.address();
+	port = typeof address === "object" && address ? address.port : 0;
+});
+
+after(async () => {
+	await new Promise<void>((resolve) => server.close(() => resolve()));
+	_resetForTest();
+});
+
+describe("GET /accounts/oauth/microsoft/callback through the dev-server's own app", () => {
+	it("answers the browser with somewhere to go", async () => {
+		const response = await fetch(
+			`http://127.0.0.1:${port}/accounts/oauth/microsoft/callback?error=access_denied`,
+			{ redirect: "manual" },
+		);
+
+		assert.equal(response.status, 302);
+		assert.equal(
+			response.headers.get("location"),
+			`${WEB_ORIGIN}/settings/accounts?oauthError=access_denied`,
+		);
+	});
+});

package/package.json

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

package/src/handlers/account-oauth-callback.test.ts

@@ -0,0 +1,147 @@
+/**
+ * The browser Microsoft sends back, and where it ends up.
+ *
+ * The callback answers a redirect, so the whole response is its Location
+ * header: an answer that arrives without it is a blank page with the account
+ * either connected or not and no way to tell. Driven through the real OpenAPI
+ * document and the self-host request path, so what is asserted is what a
+ * self-hosted deployment writes onto the wire — the header included, which a
+ * handler returning a bare `{statusCode, headers}` shape lost on the way out.
+ */
+
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { after, before, describe, it } from "node:test";
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import {
+	_resetForTest,
+	type RemitClient,
+	setClient,
+} from "../service/data-client.js";
+import { signState } from "./account-oauth.js";
+import { createCalendarSqliteClient } from "./calendar-sqlite-fixture.js";
+
+const CLIENT_SECRET = "callback-test-client-secret";
+const WEB_ORIGIN = "https://mail.example.com";
+const CALLBACK_PATH = "/accounts/oauth/microsoft/callback";
+
+let handler: (
+	event: APIGatewayProxyEvent,
+	context: unknown,
+) => Promise<APIGatewayProxyResult>;
+let client: RemitClient;
+let cleanup: () => void;
+let tokenEndpoint: Server;
+
+const jwt = (claims: Record<string, unknown>): string =>
+	[
+		Buffer.from(JSON.stringify({ alg: "RS256" })).toString("base64url"),
+		Buffer.from(JSON.stringify(claims), "utf8").toString("base64url"),
+		"signature-not-checked-here",
+	].join(".");
+
+/** Microsoft's token endpoint, close enough for the one call the callback makes. */
+const startTokenEndpoint = async (): Promise<string> => {
+	tokenEndpoint = createServer((_request, response) => {
+		response.writeHead(200, { "Content-Type": "application/json" });
+		response.end(
+			JSON.stringify({
+				access_token: "access-token",
+				refresh_token: "refresh-token",
+				id_token: jwt({ preferred_username: "matthijs@example.com" }),
+				expires_in: 3600,
+			}),
+		);
+	});
+	await new Promise<void>((resolve) => tokenEndpoint.listen(0, resolve));
+	const { port } = tokenEndpoint.address() as AddressInfo;
+	return `http://127.0.0.1:${port}/token`;
+};
+
+const callback = (
+	query: Record<string, string>,
+): Promise<APIGatewayProxyResult> =>
+	handler(
+		{
+			httpMethod: "GET",
+			path: CALLBACK_PATH,
+			headers: {},
+			queryStringParameters: query,
+			body: null,
+			requestContext: {},
+		} as unknown as APIGatewayProxyEvent,
+		{ awsRequestId: `req-${randomUUID()}`, functionName: "test" },
+	);
+
+const headerOf = (
+	response: APIGatewayProxyResult,
+	name: string,
+): string | undefined => {
+	for (const [key, value] of Object.entries(response.headers ?? {})) {
+		if (key.toLowerCase() === name) return String(value);
+	}
+	return undefined;
+};
+
+before(async () => {
+	_resetForTest();
+	process.env.DATA_BACKEND = "sqlite";
+	process.env.CORS_ALLOWED_ORIGINS = WEB_ORIGIN;
+	process.env.MSOAUTH_REDIRECT_URI = `${WEB_ORIGIN}${CALLBACK_PATH}`;
+	process.env.MSOAUTH_CLIENT_ID = "callback-test-client-id";
+	process.env.MSOAUTH_CLIENT_SECRET = CLIENT_SECRET;
+	process.env.MSOAUTH_TOKEN_ENDPOINT = await startTokenEndpoint();
+	// The self-host key that encrypts the stored refresh token.
+	process.env.FAKE_KMS_DATAKEY = "0".repeat(64);
+	// Static credentials so the best-effort sync enqueue fails against the local
+	// queue instead of walking the instance-metadata chain for a minute.
+	process.env.AWS_REGION = "eu-west-1";
+	process.env.AWS_ACCESS_KEY_ID = "test";
+	process.env.AWS_SECRET_ACCESS_KEY = "test";
+	({ client, cleanup } = await createCalendarSqliteClient());
+	setClient(client);
+	({ handler } = (await import("../index.js")) as unknown as {
+		handler: typeof handler;
+	});
+});
+
+after(async () => {
+	_resetForTest();
+	cleanup();
+	await new Promise<void>((resolve) => tokenEndpoint.close(() => resolve()));
+});
+
+describe("the Microsoft OAuth callback", () => {
+	it("sends the consenting browser on to the connected account", async () => {
+		const accountConfigId = randomUUID();
+		const state = await signState(
+			{ accountConfigId, nonce: "nonce", timestamp: Date.now() },
+			CLIENT_SECRET,
+		);
+
+		const response = await callback({ code: "auth-code", state });
+
+		assert.equal(response.statusCode, 302, response.body);
+		const location = headerOf(response, "location");
+		assert.ok(location, "a redirect without a Location header is a blank page");
+		const [connected] =
+			await client.account.listAllByAccountConfig(accountConfigId);
+		assert.ok(connected, "the callback stored the account it redirects to");
+		assert.equal(
+			location,
+			`${WEB_ORIGIN}/settings/accounts?connected=${encodeURIComponent(connected.accountId)}`,
+		);
+	});
+
+	it("sends a refused consent back with the reason Microsoft gave", async () => {
+		const response = await callback({ error: "access_denied" });
+
+		assert.equal(response.statusCode, 302, response.body);
+		assert.equal(
+			headerOf(response, "location"),
+			`${WEB_ORIGIN}/settings/accounts?oauthError=access_denied`,
+		);
+	});
+});

package/src/handlers/account-oauth.ts

@@ -16,6 +16,7 @@ import type { Context } from "openapi-backend";
 import { getAccountConfigIdFromEvent } from "../auth.js";
 import { getMsOAuthConfig } from "../config/msoauth.js";
 import { safeJsonParse } from "../json.js";
+import { rawApiResponse } from "../response.js";
 import { getClient } from "../service/data-client.js";
 import type { MicrosoftOAuthOperationIds, OperationHandler } from "../types.js";
 import { triggerAccountSyncSafe } from "./account.js";
@@ -228,11 +229,15 @@ export const MicrosoftOAuthOperations: Record<
 		const webOrigin = getWebOrigin();
 		const qs = event.queryStringParameters ?? {};
 
-		const redirect = (url: string): APIGatewayProxyResult => ({
-			statusCode: 302,
-			headers: { Location: url },
-			body: "",
-		});
+		// Marked raw so the response formatter forwards the Location header
+		// instead of serializing this object as a JSON body. Microsoft's browser
+		// redirect lands here, so a dropped Location is a blank page.
+		const redirect = (url: string): APIGatewayProxyResult =>
+			rawApiResponse({
+				statusCode: 302,
+				headers: { Location: url },
+				body: "",
+			});
 
 		// If Microsoft returned an error, pass it through to the frontend
 		if (qs.error) {

package/src/handlers/calendar-sqlite-fixture.ts

@@ -1,50 +1,22 @@
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { applyShippedMigrations } from "@remit/drizzle-service/test-sqlite";
 import Database from "better-sqlite3";
 import { buildSqliteClient } from "../service/compose-sqlite.js";
 import type { RemitClient } from "../service/data-client.js";
 
 /**
- * A calendar handler test's store: the backend's own SQLite composition, over
- * the DDL a self-host deployment actually runs.
+ * A handler test's store: the backend's own SQLite composition, over the DDL a
+ * self-host deployment actually runs.
  *
- * The migrations are read rather than pushed from the drizzle table objects, so
- * a handler test exercises the shipped column shapes — the same reason
- * `test-shipped-sqlite-schema.ts` exists on the repository side. The client is
- * built by `compose-sqlite.ts`, which is the composition root a self-host
- * process boots, so nothing here is a second wiring of the calendar repos that
- * could drift from the one that ships.
- */
-const MIGRATIONS = new URL(
-	"../../../../deploy/vps/migrations-sqlite/entities/",
-	import.meta.url,
-);
-
-interface Journal {
-	entries: Array<{ idx: number; tag: string }>;
-}
-
-const applyEntityMigrations = (sqlite: Database.Database): void => {
-	const journal = JSON.parse(
-		readFileSync(new URL("meta/_journal.json", MIGRATIONS), "utf8"),
-	) as Journal;
-	const ordered = [...journal.entries].sort(
-		(left, right) => left.idx - right.idx,
-	);
-	for (const entry of ordered) {
-		const sql = readFileSync(new URL(`${entry.tag}.sql`, MIGRATIONS), "utf8");
-		for (const statement of sql.split("--> statement-breakpoint")) {
-			if (statement.trim() === "") continue;
-			sqlite.exec(statement);
-		}
-	}
-};
-
-/**
- * A migrated database and the client that reads it. One per test file: every
- * calendar row is scoped by account config, so a test that mints its own
- * account config sees only what it wrote.
+ * The migrations are applied rather than pushed from the drizzle table objects,
+ * so a handler test exercises the shipped column shapes. The client is built by
+ * `compose-sqlite.ts`, the composition root a self-host process boots, so
+ * nothing here is a second wiring that could drift from the one that ships.
+ *
+ * One per test file: every row is scoped by account config, so a test that
+ * mints its own account config sees only what it wrote.
  */
 export const createCalendarSqliteClient = async (): Promise<{
 	client: RemitClient;
@@ -53,7 +25,7 @@ export const createCalendarSqliteClient = async (): Promise<{
 	const directory = mkdtempSync(join(tmpdir(), "remit-calendar-handlers-"));
 	const path = join(directory, "remit.db");
 	const sqlite = new Database(path);
-	applyEntityMigrations(sqlite);
+	applyShippedMigrations(sqlite);
 	sqlite.close();
 
 	process.env.SQLITE_DB_PATH = path;

package/src/response.ts

@@ -10,13 +10,14 @@ import {
 const RAW_API_RESPONSE: unique symbol = Symbol("remit.rawApiResponse");
 
 /**
- * A response whose bytes are not JSON — an iCalendar feed, and whatever later
- * joins it.
+ * A response the caller reads by something other than its JSON body — an
+ * iCalendar feed, an OAuth redirect's Location, and whatever later joins them.
  *
  * Every other handler returns a plain object and lets this module decide the
  * status, the content type and the serialization. That is the right default and
- * stays the default; a handler that has to own its own media type says so with
- * `rawApiResponse` rather than by returning a shape this one has to guess at.
+ * stays the default; a handler that has to own its own media type or headers
+ * says so with `rawApiResponse` rather than by returning a shape this one has
+ * to guess at.
  * The CORS and correlation headers are still added here, so a raw response is
  * not a way around them.
  */

package/src/service/organize.test.ts

@@ -18,6 +18,7 @@ import {
 	applyOrganize,
 	BODY_CONTENT_REJECTION_MESSAGE,
 	matchOrganize,
+	ORGANIZE_MATCH_LIMIT,
 	type OrganizeCandidate,
 	type OrganizeMatchDeps,
 	type OrganizeMatched,
@@ -285,7 +286,7 @@ const matchDeps = (
 				embeddingId: CURRENT_EMBEDDING_ID,
 			};
 		},
-		listAccountFilterMessages: async () => corpus,
+		listAccountFilterMessages: async () => ({ items: corpus }),
 		filterAnchors: {
 			listByAccountConfig: async () => filterAnchorRows,
 			put: async () => {
@@ -326,7 +327,7 @@ const vectorlessDeps = (
 				embeddingId: CURRENT_EMBEDDING_ID,
 			};
 		},
-		listAccountFilterMessages: async () => corpus,
+		listAccountFilterMessages: async () => ({ items: corpus }),
 		filterAnchors: {
 			listByAccountConfig: async () => [],
 			put: async () => {
@@ -467,7 +468,7 @@ describe("matchOrganize honors the persisted FilterAnchor (reader #350)", () =>
 				embed: async () => ANCHOR_VECTOR,
 				embeddingId: CURRENT_EMBEDDING_ID,
 			}),
-			listAccountFilterMessages: async () => [],
+			listAccountFilterMessages: async () => ({ items: [] }),
 			filterAnchors: {
 				listByAccountConfig: async () => [persistedAnchor],
 				put: async () => {
@@ -652,7 +653,7 @@ describe("matchOrganize on a deployment without the vector pipeline", () => {
 				},
 				embeddingId: CURRENT_EMBEDDING_ID,
 			}),
-			listAccountFilterMessages: async () => [],
+			listAccountFilterMessages: async () => ({ items: [] }),
 			filterAnchors: {
 				listByAccountConfig: async () => [drifted],
 				put: async () => {
@@ -693,7 +694,7 @@ describe("matchOrganize on a deployment without the vector pipeline", () => {
 				embed: async () => [],
 				embeddingId: CURRENT_EMBEDDING_ID,
 			}),
-			listAccountFilterMessages: async () => [],
+			listAccountFilterMessages: async () => ({ items: [] }),
 			filterAnchors: {
 				listByAccountConfig: async () => [],
 				put: async () => {
@@ -1015,7 +1016,7 @@ describe("back-apply repairs a drifted anchor the way index-time matching does (
 				embed,
 				embeddingId: CURRENT_EMBEDDING_ID,
 			}),
-			listAccountFilterMessages: async () => [],
+			listAccountFilterMessages: async () => ({ items: [] }),
 			filterAnchors: {
 				listByAccountConfig: async () => anchors,
 				put: async (input: CreateFilterAnchorInput) => {
@@ -1167,3 +1168,175 @@ describe("matchOrganize with ListId and FromDomain clauses", () => {
 		]);
 	});
 });
+
+/**
+ * The corpus read a real deployment gets: the store evaluates the terms and
+ * the caller pages the MATCHES. Modelled here rather than stubbed with a fixed
+ * array so a matcher that reads only the newest page cannot pass.
+ */
+const storeBackedDeps = (
+	rows: readonly OrganizeCandidate[],
+): OrganizeMatchDeps & { pagesRead: () => number } => {
+	let pagesRead = 0;
+	const termMatches = (
+		term: { field: string; contains: string },
+		row: OrganizeCandidate,
+	): boolean => {
+		const needle = term.contains.toLowerCase();
+		if (term.field === "subject") {
+			return row.message.subject.toLowerCase().includes(needle);
+		}
+		if (term.field === "listId") {
+			return row.message.listId.toLowerCase().includes(needle);
+		}
+		return `${row.message.fromName} ${row.message.from}`
+			.toLowerCase()
+			.includes(needle);
+	};
+	return {
+		semantic: () => {
+			throw moduleNotFound();
+		},
+		listAccountFilterMessages: async (_accountConfigId, query) => {
+			pagesRead += 1;
+			const narrowed = rows.filter((row) =>
+				query.terms.length === 0
+					? true
+					: query.operator === "or"
+						? query.terms.some((term) => termMatches(term, row))
+						: query.terms.every((term) => termMatches(term, row)),
+			);
+			const offset = query.continuationToken
+				? Number(query.continuationToken)
+				: 0;
+			const items = narrowed.slice(offset, offset + query.limit);
+			const next = offset + items.length;
+			return {
+				items,
+				continuationToken: next < narrowed.length ? String(next) : undefined,
+			};
+		},
+		filterAnchors: {
+			listByAccountConfig: async () => [],
+			put: async () => {
+				throw new Error("unreachable");
+			},
+		},
+		pagesRead: () => pagesRead,
+	};
+};
+
+describe("literal matching bounds the result, not the corpus (reader #459)", () => {
+	const quietSender = candidate("quiet-sender", {
+		from: "noreply@bank.example",
+		fromName: "Statements",
+		subject: "Your March statement",
+	});
+	const newerNoise = Array.from({ length: ORGANIZE_MATCH_LIMIT + 1 }, (_, i) =>
+		candidate(`noise-${i}`, {
+			from: "digest@other.example",
+			fromName: "Digest",
+			subject: `Daily digest ${i}`,
+		}),
+	);
+
+	it("matches a domain rule against mail older than a whole page of newer misses", async () => {
+		const deps = storeBackedDeps([...newerNoise, quietSender]);
+
+		const { messageIds } = await matchAccepted(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			predicate({
+				anchorMessageId: "None",
+				literalClauses: [{ field: "FromDomain", value: "bank.example" }],
+			}),
+		);
+
+		assert.deepEqual(messageIds, ["quiet-sender"]);
+	});
+
+	it("reads one narrowed page rather than paging the whole mailbox", async () => {
+		const deps = storeBackedDeps([...newerNoise, quietSender]);
+
+		await matchAccepted(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			predicate({
+				anchorMessageId: "None",
+				literalClauses: [{ field: "From", value: "noreply@bank.example" }],
+			}),
+		);
+
+		assert.equal(deps.pagesRead(), 1);
+	});
+
+	it("still refines what the store returned: a term is a narrowing, not the verdict", async () => {
+		const deps = storeBackedDeps([
+			candidate("spoofed", { from: "billing@bank.example.evil.test" }),
+			quietSender,
+		]);
+
+		const { messageIds } = await matchAccepted(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			predicate({
+				anchorMessageId: "None",
+				literalClauses: [{ field: "FromDomain", value: "bank.example" }],
+			}),
+		);
+
+		assert.deepEqual(messageIds, ["quiet-sender"]);
+	});
+
+	it("caps the matches at the limit when more of the corpus matches", async () => {
+		const matching = Array.from({ length: ORGANIZE_MATCH_LIMIT * 2 }, (_, i) =>
+			candidate(`hit-${i}`, { from: "noreply@bank.example" }),
+		);
+		const deps = storeBackedDeps(matching);
+
+		const { messageIds } = await matchAccepted(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			predicate({
+				anchorMessageId: "None",
+				literalClauses: [{ field: "FromDomain", value: "bank.example" }],
+			}),
+		);
+
+		assert.equal(messageIds.length, ORGANIZE_MATCH_LIMIT);
+	});
+
+	it("never queries for clauses nothing can satisfy", async () => {
+		const deps = storeBackedDeps([quietSender]);
+
+		const { messageIds } = await matchAccepted(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			predicate({
+				anchorMessageId: "None",
+				literalClauses: [{ field: "From", value: "   " }],
+			}),
+		);
+
+		assert.deepEqual(messageIds, []);
+		assert.equal(deps.pagesRead(), 0);
+	});
+
+	it("counts one match for mail filed in two folders", async () => {
+		const deps = storeBackedDeps([
+			candidate("filed-twice", { from: "noreply@bank.example" }),
+			candidate("filed-twice", { from: "noreply@bank.example" }),
+		]);
+
+		const { messageIds } = await matchAccepted(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			predicate({
+				anchorMessageId: "None",
+				literalClauses: [{ field: "FromDomain", value: "bank.example" }],
+			}),
+		);
+
+		assert.deepEqual(messageIds, ["filed-twice"]);
+	});
+});

package/src/service/organize.ts

@@ -10,7 +10,9 @@ import { logger } from "@remit/logger-lambda";
 import {
 	DEFAULT_SEMANTIC_MATCH_THRESHOLD,
 	type FilterMessage,
+	type LiteralClauseNarrowing,
 	literalClausesMatch,
+	literalClauseTerms,
 	NO_ACTION,
 	PlacementMoveService,
 	refreshAnchorForEmbedder,
@@ -34,8 +36,10 @@ import {
 /**
  * Hard cap on both the previewed and the applied set. A back-apply is a
  * data-heavy corpus pass (remit-data-heavy: frugal): the semantic side is
- * bounded by the vector query's `topK`, the literal-only side by a paginated
- * message scan, and the final match set never exceeds this.
+ * bounded by the vector query's `topK`, the literal-only side by counting
+ * MATCHES as it pages a store-side narrowed listing, and the final match set
+ * never exceeds this. It bounds the answer, never the corpus the question is
+ * asked of (#459).
  */
 export const ORGANIZE_MATCH_LIMIT = 500;
 
@@ -117,6 +121,22 @@ export interface OrganizeCandidate {
 	message: FilterMessage;
 }
 
+/**
+ * One page of the narrowed corpus, cursored exactly as the underlying listing
+ * is: an absent `continuationToken` means the store has no more rows matching
+ * the terms, never that a read window ran out.
+ */
+export interface OrganizeCandidatePage {
+	items: OrganizeCandidate[];
+	continuationToken?: string;
+}
+
+/** What to ask the store for, and where to resume. */
+export interface OrganizeCandidateQuery extends LiteralClauseNarrowing {
+	limit: number;
+	continuationToken?: string;
+}
+
 export interface OrganizeMatchDeps {
 	/**
 	 * Build the semantic side on demand. Invoked only for an anchored predicate,
@@ -126,13 +146,16 @@ export interface OrganizeMatchDeps {
 	 */
 	semantic: () => OrganizeSemanticDeps;
 	/**
-	 * The account's messages as literal-match candidates, bounded and vector-free
-	 * — the corpus slice a purely-literal (or degraded) pass scans.
+	 * One page of the account's messages as literal-match candidates,
+	 * vector-free, with the clause terms evaluated by the store — the corpus a
+	 * purely-literal (or degraded) pass reads. Paged rather than capped, so the
+	 * caller's bound falls on matches instead of on how far back the read
+	 * reached (#459).
 	 */
 	listAccountFilterMessages: (
 		accountConfigId: string,
-		limit: number,
-	) => Promise<OrganizeCandidate[]>;
+		query: OrganizeCandidateQuery,
+	) => Promise<OrganizeCandidatePage>;
 	/**
 	 * Every persisted FilterAnchor for the account — read-only, always
 	 * available (never gated behind {@link semantic}, since it never touches
@@ -378,12 +401,18 @@ export const organizePredicateRejection = (
 	hasAnchor(predicate) ? null : bodyContentRejection(predicate.literalClauses);
 
 /**
- * The literal-only arm: scan a bounded, vector-free slice of the corpus and keep
- * the messages whose literal clauses match. Used both for a purely-literal
+ * The literal-only arm: the store selects on the clause terms, this refines
+ * what it returned and stops at `limit` MATCHES. Used both for a purely-literal
  * predicate and as the degraded fallback when a widen is requested on a
  * deployment without the vector pipeline. Serves `From`/`Subject` clauses at
  * full fidelity from the core thread rows; body-content (`HasWords`) clauses are
  * refused before this runs (see {@link bodyContentRejection}).
+ *
+ * The terms are a narrowing, not the verdict ({@link literalClauseTerms}), so
+ * every page is still run through {@link literalClausesMatch} — and paging
+ * continues until the cap fills or the store runs out, which is what makes the
+ * bound a bound on results rather than on the newest `limit` rows (#459).
+ * Deduped by message id: the same mail filed in two folders is one match.
  */
 const matchLiteral = async (
 	deps: OrganizeMatchDeps,
@@ -392,20 +421,29 @@ const matchLiteral = async (
 	limit: number,
 ): Promise<string[]> => {
 	const clauses = predicate.literalClauses;
-	const candidates = await deps.listAccountFilterMessages(
-		accountConfigId,
-		limit,
-	);
-	if (clauses.length === 0) {
-		return candidates.slice(0, limit).map((c) => c.messageId);
-	}
+	const narrowing = literalClauseTerms(clauses, predicate.matchOperator);
+	if (!narrowing) return [];
+
 	const matched: string[] = [];
-	for (const { messageId, message } of candidates) {
-		if (matched.length >= limit) break;
-		if (literalClausesMatch(clauses, predicate.matchOperator, message)) {
+	const seen = new Set<string>();
+	let continuationToken: string | undefined;
+	do {
+		const page = await deps.listAccountFilterMessages(accountConfigId, {
+			...narrowing,
+			limit,
+			continuationToken,
+		});
+		for (const { messageId, message } of page.items) {
+			if (seen.has(messageId)) continue;
+			seen.add(messageId);
+			if (!literalClausesMatch(clauses, predicate.matchOperator, message)) {
+				continue;
+			}
 			matched.push(messageId);
+			if (matched.length >= limit) return matched;
 		}
-	}
+		continuationToken = page.continuationToken;
+	} while (continuationToken);
 	return matched;
 };
 
@@ -508,11 +546,10 @@ const buildSemanticFromEnv = (): OrganizeSemanticDeps => {
 };
 
 /**
- * A bounded, vector-free corpus slice for a literal back-apply: the account's
- * messages projected onto the literal-match fields, gathered newest-first across
- * every mailbox and capped. Reads the core thread rows, so it runs on a
- * deployment that ships no vector pipeline. Deduped by message id — the same
- * mail filed in two folders is one candidate.
+ * The vector-free corpus read for a literal back-apply: one page of the
+ * account's messages, newest-first across every mailbox, with the clause terms
+ * evaluated in the query. Reads the core thread rows, so it runs on a
+ * deployment that ships no vector pipeline.
  *
  * `From`/`Subject`/`listId` come from the row verbatim (full fidelity), so a
  * `From`, `Subject`, `FromDomain` or `ListId` clause matches here exactly as it
@@ -525,34 +562,30 @@ const buildSemanticFromEnv = (): OrganizeSemanticDeps => {
  */
 const listAccountFilterMessagesFromClient =
 	(client: RemitClient): OrganizeMatchDeps["listAccountFilterMessages"] =>
-	async (accountConfigId, limit) => {
-		const candidates: OrganizeCandidate[] = [];
-		const seen = new Set<string>();
-		let continuationToken: string | undefined;
-		do {
-			const page = await client.threadMessage.listByDate(accountConfigId, {
-				limit,
-				continuationToken,
+	async (accountConfigId, query) => {
+		const page = await client.threadMessage.listByFieldTerms(
+			accountConfigId,
+			query.terms,
+			{
+				operator: query.operator,
+				limit: query.limit,
+				continuationToken: query.continuationToken,
 				excludeDeleted: true,
-			});
-			for (const row of page.items) {
-				if (seen.has(row.messageId)) continue;
-				seen.add(row.messageId);
-				candidates.push({
-					messageId: row.messageId,
-					message: {
-						from: row.fromEmail ?? "",
-						fromName: row.fromName ?? "",
-						subject: row.subject ?? "",
-						text: "",
-						listId: row.listId ?? "",
-					},
-				});
-				if (candidates.length >= limit) return candidates;
-			}
-			continuationToken = page.continuationToken;
-		} while (continuationToken);
-		return candidates;
+			},
+		);
+		return {
+			items: page.items.map((row) => ({
+				messageId: row.messageId,
+				message: {
+					from: row.fromEmail ?? "",
+					fromName: row.fromName ?? "",
+					subject: row.subject ?? "",
+					text: "",
+					listId: row.listId ?? "",
+				},
+			})),
+			continuationToken: page.continuationToken,
+		};
 	};
 
 /**