@remit/backend 0.0.23 → 0.0.25

package/package.json

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

package/src/handlers/organize.ts

@@ -157,14 +157,19 @@ export const OrganizeOperations: Record<
 		const client = await getClient();
 		await assertAccount(client, accountId, accountConfigId, "read");
 
-		const messageIds = await matchOrganize(
+		const { messageIds, semanticUnavailable } = await matchOrganize(
 			buildOrganizeMatchDeps(client),
 			accountConfigId,
 			predicateFromInput(input),
 			ORGANIZE_MATCH_LIMIT,
 		);
 
-		return { matchedCount: messageIds.length, messageIds };
+		const response: OrganizePreviewResponse = {
+			matchedCount: messageIds.length,
+			messageIds,
+		};
+		if (semanticUnavailable) response.semanticUnavailable = true;
+		return response;
 	},
 };
 

package/src/service/organize.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { afterEach, beforeEach, describe, it } from "node:test";
 import { FilterMatchOperator } from "@remit/domain-enums";
 import type {
 	AnchorPayload,
@@ -11,9 +11,17 @@ import type { RemitClient } from "./dynamodb.js";
 import {
 	applyOrganize,
 	matchOrganize,
+	type OrganizeCandidate,
 	type OrganizeMatchDeps,
 	type OrganizePredicate,
 } from "./organize.js";
+import { _resetSemanticCapabilityForTest } from "./semantic-capability.js";
+
+const moduleNotFound = (): Error => {
+	const error = new Error("Cannot find package 'sqlite-vec' imported from …");
+	(error as Error & { code: string }).code = "ERR_MODULE_NOT_FOUND";
+	return error;
+};
 
 const ACCOUNT_CONFIG_ID = "cfg-1";
 const ANCHOR_VECTOR = [1, 0, 0, 0];
@@ -148,12 +156,64 @@ 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.
+ */
 const matchDeps = (
 	store: ReturnType<typeof createMemoryVectorStore>,
-): OrganizeMatchDeps => ({
-	buildAnchor: async () => anchorPayload,
-	vectorStore: store,
-	listAccountMessageIds: async () => [],
+	corpus: OrganizeCandidate[] = [],
+): OrganizeMatchDeps & { semanticBuilds: () => number } => {
+	let semanticBuilds = 0;
+	return {
+		semantic: () => {
+			semanticBuilds += 1;
+			return { buildAnchor: async () => anchorPayload, vectorStore: store };
+		},
+		listAccountFilterMessages: async () => corpus,
+		semanticBuilds: () => semanticBuilds,
+	};
+};
+
+/**
+ * Deps modelling a deployment that ships no vector pipeline: any attempt to
+ * build or use the semantic side raises the missing-module shape, and the
+ * literal corpus is served from plain rows.
+ */
+const vectorlessDeps = (
+	corpus: OrganizeCandidate[],
+): OrganizeMatchDeps & { semanticUsed: () => boolean } => {
+	let semanticUsed = false;
+	return {
+		semantic: () => {
+			semanticUsed = true;
+			return {
+				buildAnchor: async () => {
+					throw moduleNotFound();
+				},
+				vectorStore: {
+					query: async () => {
+						throw moduleNotFound();
+					},
+					getByMessage: async () => {
+						throw moduleNotFound();
+					},
+				},
+			};
+		},
+		listAccountFilterMessages: async () => corpus,
+		semanticUsed: () => semanticUsed,
+	};
+};
+
+const candidate = (
+	messageId: string,
+	over: Partial<OrganizeCandidate["message"]> = {},
+): OrganizeCandidate => ({
+	messageId,
+	message: { from: "", fromName: "", subject: "", text: "", ...over },
 });
 
 describe("matchOrganize", () => {
@@ -165,25 +225,30 @@ describe("matchOrganize", () => {
 			bodyChunk("msg-miss", ORTHOGONAL_VECTOR),
 		]);
 
-		const matched = await matchOrganize(
+		const { messageIds, semanticUnavailable } = await matchOrganize(
 			matchDeps(store),
 			ACCOUNT_CONFIG_ID,
 			predicate({ actionLabelId: "lbl-1" }),
 		);
 
-		assert.deepEqual([...matched].sort(), matching);
+		assert.deepEqual([...messageIds].sort(), matching);
+		assert.equal(semanticUnavailable, false);
 	});
 
 	it("matches nothing when the predicate has neither an anchor nor a clause", async () => {
 		const store = createMemoryVectorStore();
 		await store.upsert([bodyChunk("msg-1", ANCHOR_VECTOR)]);
 
-		const matched = await matchOrganize(matchDeps(store), ACCOUNT_CONFIG_ID, {
-			...predicate(),
-			anchorMessageId: "None",
-		});
+		const { messageIds } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			{
+				...predicate(),
+				anchorMessageId: "None",
+			},
+		);
 
-		assert.deepEqual(matched, []);
+		assert.deepEqual(messageIds, []);
 	});
 
 	it("refines the semantic set by literal clauses", async () => {
@@ -199,12 +264,146 @@ describe("matchOrganize", () => {
 			}),
 		]);
 
-		const matched = await matchOrganize(matchDeps(store), ACCOUNT_CONFIG_ID, {
+		const { messageIds } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			{
+				...predicate(),
+				literalClauses: [{ field: "Subject", value: "reservation" }],
+			},
+		);
+
+		assert.deepEqual(messageIds, ["msg-1"]);
+	});
+
+	it("never builds the semantic side for a purely-literal predicate", async () => {
+		const store = createMemoryVectorStore();
+		const deps = matchDeps(store, [
+			candidate("msg-1", { subject: "Dinner reservation" }),
+			candidate("msg-2", { subject: "Newsletter" }),
+		]);
+
+		const { messageIds } = await matchOrganize(deps, ACCOUNT_CONFIG_ID, {
 			...predicate(),
+			anchorMessageId: "None",
 			literalClauses: [{ field: "Subject", value: "reservation" }],
 		});
 
-		assert.deepEqual(matched, ["msg-1"]);
+		assert.deepEqual(messageIds, ["msg-1"]);
+		assert.equal(
+			deps.semanticBuilds(),
+			0,
+			"a literal-only predicate must not construct the vector-backed side",
+		);
+	});
+});
+
+describe("matchOrganize on a deployment without the vector pipeline", () => {
+	const ORIGINAL = process.env.DATA_BACKEND;
+	beforeEach(() => {
+		process.env.DATA_BACKEND = "sqlite";
+		_resetSemanticCapabilityForTest();
+	});
+	afterEach(() => {
+		if (ORIGINAL === undefined) delete process.env.DATA_BACKEND;
+		else process.env.DATA_BACKEND = ORIGINAL;
+		_resetSemanticCapabilityForTest();
+	});
+
+	it("matches a literal predicate from the corpus without touching the vector store", async () => {
+		const deps = vectorlessDeps([
+			candidate("msg-1", { subject: "Dinner reservation" }),
+			candidate("msg-2", { subject: "Weekly newsletter" }),
+			candidate("msg-3", { subject: "Table reservation confirmed" }),
+		]);
+
+		const { messageIds, semanticUnavailable } = await matchOrganize(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			{
+				...predicate(),
+				anchorMessageId: "None",
+				literalClauses: [{ field: "Subject", value: "reservation" }],
+			},
+		);
+
+		assert.deepEqual(messageIds, ["msg-1", "msg-3"]);
+		assert.equal(semanticUnavailable, false);
+		assert.equal(
+			deps.semanticUsed(),
+			false,
+			"a literal-only predicate must never reach the vector store",
+		);
+	});
+
+	it("fails loud on a body-content (HasWords) clause rather than matching it against a preview", async () => {
+		const deps = vectorlessDeps([
+			candidate("msg-1", { subject: "Dinner reservation" }),
+		]);
+
+		await assert.rejects(
+			() =>
+				matchOrganize(deps, ACCOUNT_CONFIG_ID, {
+					...predicate(),
+					anchorMessageId: "None",
+					literalClauses: [{ field: "HasWords", value: "invoice" }],
+				}),
+			/HasWords/,
+			"the vector-free literal path must not silently narrow a body match to a preview",
+		);
+		assert.equal(deps.semanticUsed(), false);
+	});
+
+	it("degrades an anchor+clauses widen to the literal matches, flagged, instead of crashing", async () => {
+		const deps = vectorlessDeps([
+			candidate("msg-1", { subject: "Dinner reservation" }),
+			candidate("msg-2", { subject: "Weekly newsletter" }),
+		]);
+
+		const { messageIds, semanticUnavailable } = await matchOrganize(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			{
+				...predicate(),
+				literalClauses: [{ field: "Subject", value: "reservation" }],
+			},
+		);
+
+		assert.deepEqual(messageIds, ["msg-1"]);
+		assert.equal(semanticUnavailable, true);
+	});
+
+	it("degrades an anchor-only widen to an empty flagged result instead of crashing", async () => {
+		const deps = vectorlessDeps([candidate("msg-1"), candidate("msg-2")]);
+
+		const { messageIds, semanticUnavailable } = await matchOrganize(
+			deps,
+			ACCOUNT_CONFIG_ID,
+			predicate(),
+		);
+
+		assert.deepEqual(messageIds, []);
+		assert.equal(semanticUnavailable, true);
+	});
+
+	it("propagates a genuine (non-capability) semantic failure loudly", async () => {
+		const deps: OrganizeMatchDeps = {
+			semantic: () => ({
+				buildAnchor: async () => {
+					throw new Error("SQLITE_BUSY");
+				},
+				vectorStore: {
+					query: async () => [],
+					getByMessage: async () => [],
+				},
+			}),
+			listAccountFilterMessages: async () => [],
+		};
+
+		await assert.rejects(
+			() => matchOrganize(deps, ACCOUNT_CONFIG_ID, predicate()),
+			/SQLITE_BUSY/,
+		);
 	});
 });
 
@@ -233,7 +432,7 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 		const result = await applyOrganize(
 			{ client: tracked.client },
 			ACCOUNT_CONFIG_ID,
-			applied,
+			applied.messageIds,
 			p,
 		);
 
@@ -260,7 +459,11 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 		await store.upsert([bodyChunk("msg-1", ANCHOR_VECTOR)]);
 		const p = predicate({ actionMailboxId: "mbox-target" });
 
-		const matched = await matchOrganize(matchDeps(store), ACCOUNT_CONFIG_ID, p);
+		const { messageIds: matched } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			p,
+		);
 		const tracked = trackingClient();
 		const result = await applyOrganize(
 			{ client: tracked.client },
@@ -282,7 +485,11 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 		]);
 		const p = predicate({ actionMailboxId: "mbox-target" });
 
-		const matched = await matchOrganize(matchDeps(store), ACCOUNT_CONFIG_ID, p);
+		const { messageIds: matched } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			p,
+		);
 		const tracked = trackingClient();
 		const mover = trackingMoveService();
 		const result = await applyOrganize(
@@ -324,7 +531,11 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 			actionMailboxId: "mbox-target",
 		});
 
-		const matched = await matchOrganize(matchDeps(store), ACCOUNT_CONFIG_ID, p);
+		const { messageIds: matched } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			p,
+		);
 		const tracked = trackingClient();
 		const mover = trackingMoveService();
 		const result = await applyOrganize(
@@ -351,7 +562,11 @@ describe("back-apply pipeline (matchOrganize -> applyOrganize)", () => {
 		await store.upsert(matching.map((id) => bodyChunk(id, ANCHOR_VECTOR)));
 		const p = predicate({ actionMailboxId: "mbox-target" });
 
-		const matched = await matchOrganize(matchDeps(store), ACCOUNT_CONFIG_ID, p);
+		const { messageIds: matched } = await matchOrganize(
+			matchDeps(store),
+			ACCOUNT_CONFIG_ID,
+			p,
+		);
 		const tracked = trackingClient();
 		const mover = trackingMoveService();
 

package/src/service/organize.ts

@@ -1,4 +1,5 @@
 import type { FilterItem, OrganizeJobRequestItem } from "@remit/data-ports";
+import { FilterClauseField } from "@remit/domain-enums";
 import {
 	DEFAULT_SEMANTIC_MATCH_THRESHOLD,
 	type FilterMessage,
@@ -17,6 +18,7 @@ import {
 	buildVectorStoreFromEnv,
 } from "@remit/search-service/from-env";
 import type { RemitClient } from "./dynamodb.js";
+import { noteSemanticCapabilityAbsence } from "./semantic-capability.js";
 
 /**
  * Hard cap on both the previewed and the applied set. A back-apply is a
@@ -63,16 +65,54 @@ export const predicateFromJob = (
 	actionMailboxId: job.actionMailboxId,
 });
 
-export interface OrganizeMatchDeps {
+/**
+ * The vector-backed semantic side of the matcher — the only part that reaches
+ * `sqlite-vec`/`@huggingface/transformers`. Constructed lazily (see
+ * {@link OrganizeMatchDeps.semantic}) so a literal-only predicate never touches
+ * the vector extension, and so a deployment that ships no vector pipeline only
+ * fails on the import when a predicate actually asks to widen — where the
+ * failure is caught and degraded rather than surfaced as a 500 (#226/#201).
+ */
+export interface OrganizeSemanticDeps {
 	buildAnchor: (
 		accountConfigId: string,
 		anchorMessageId: string,
 	) => Promise<AnchorPayload | null>;
 	vectorStore: Pick<VectorStoreService, "query" | "getByMessage">;
-	listAccountMessageIds: (
+}
+
+/**
+ * One corpus message projected onto the fields a literal clause matches
+ * against, paired with its id. Sourced from the core message rows, never the
+ * vector store, so literal matching runs on any deployment.
+ */
+export interface OrganizeCandidate {
+	messageId: string;
+	message: FilterMessage;
+}
+
+export interface OrganizeMatchDeps {
+	/**
+	 * Build the semantic side on demand. Invoked only for an anchored predicate,
+	 * so constructing the embedder and vector store — and, on first use, the
+	 * lazy import of the vector extension — is deferred until a widen is actually
+	 * requested.
+	 */
+	semantic: () => OrganizeSemanticDeps;
+	/**
+	 * The account's messages as literal-match candidates, bounded and vector-free
+	 * — the corpus slice a purely-literal (or degraded) pass scans.
+	 */
+	listAccountFilterMessages: (
 		accountConfigId: string,
 		limit: number,
-	) => Promise<string[]>;
+	) => Promise<OrganizeCandidate[]>;
+}
+
+/** The matched ids plus whether the semantic widen was skipped as unavailable. */
+export interface OrganizeMatchResult {
+	messageIds: string[];
+	semanticUnavailable: boolean;
 }
 
 const hasAnchor = (predicate: OrganizePredicate): boolean =>
@@ -110,62 +150,50 @@ const filterMessageFromChunks = (
 };
 
 /**
- * The matcher shared by preview and apply — the previewed set equals the applied
- * set for the same input. Read-only. Returns the matching message ids, bounded.
- *
- * - Semantic anchor: the anchor vector is pooled transiently from the anchor
- *   message's existing chunk vectors (never a FilterAnchor row), then a k-NN
- *   query fans out to candidate messages gated on the cosine threshold.
- * - Literal clauses (RFC 031) refine the candidate set; a purely-literal
- *   back-apply scans a bounded slice of the corpus instead.
- * - A predicate with neither an anchor nor a clause matches nothing, mirroring
- *   the index-time filter matcher.
+ * 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.
  */
-export const matchOrganize = async (
-	deps: OrganizeMatchDeps,
+const matchSemantic = async (
+	semantic: OrganizeSemanticDeps,
 	accountConfigId: string,
 	predicate: OrganizePredicate,
-	limit: number = ORGANIZE_MATCH_LIMIT,
-): Promise<string[]> => {
-	const anchored = hasAnchor(predicate);
-	const clauses = predicate.literalClauses;
-	if (!anchored && clauses.length === 0) return [];
-
-	let base: string[];
-	if (anchored) {
-		const anchor = await deps.buildAnchor(
-			accountConfigId,
-			predicate.anchorMessageId,
-		);
-		if (!anchor) return [];
-		const threshold =
-			predicate.similarityThreshold ?? DEFAULT_SEMANTIC_MATCH_THRESHOLD;
-		const matches = await deps.vectorStore.query({
-			vector: anchor.anchorEmbedding,
-			topK: limit * VECTOR_CHUNK_FACTOR,
-			filter: { accountConfigId },
-		});
-		const bestScore = new Map<string, number>();
-		for (const match of matches) {
-			const messageId = match.metadata.messageId;
-			const prev = bestScore.get(messageId);
-			if (prev === undefined || match.score > prev) {
-				bestScore.set(messageId, match.score);
-			}
+	limit: number,
+): Promise<string[] | null> => {
+	const anchor = await semantic.buildAnchor(
+		accountConfigId,
+		predicate.anchorMessageId,
+	);
+	if (!anchor) return null;
+	const threshold =
+		predicate.similarityThreshold ?? DEFAULT_SEMANTIC_MATCH_THRESHOLD;
+	const matches = await semantic.vectorStore.query({
+		vector: anchor.anchorEmbedding,
+		topK: limit * VECTOR_CHUNK_FACTOR,
+		filter: { accountConfigId },
+	});
+	const bestScore = new Map<string, number>();
+	for (const match of matches) {
+		const messageId = match.metadata.messageId;
+		const prev = bestScore.get(messageId);
+		if (prev === undefined || match.score > prev) {
+			bestScore.set(messageId, match.score);
 		}
-		base = [...bestScore.entries()]
-			.filter(([, score]) => score >= threshold)
-			.map(([messageId]) => messageId);
-	} else {
-		base = await deps.listAccountMessageIds(accountConfigId, limit);
 	}
+	const base = [...bestScore.entries()]
+		.filter(([, score]) => score >= threshold)
+		.map(([messageId]) => messageId);
 
+	const clauses = predicate.literalClauses;
 	if (clauses.length === 0) return base.slice(0, limit);
 
 	const matched: string[] = [];
 	for (const messageId of base) {
 		if (matched.length >= limit) break;
-		const records = await deps.vectorStore.getByMessage(messageId);
+		const records = await semantic.vectorStore.getByMessage(messageId);
 		const message = filterMessageFromChunks(records);
 		if (!message) continue;
 		if (literalClausesMatch(clauses, predicate.matchOperator, message)) {
@@ -175,75 +203,205 @@ export const matchOrganize = async (
 	return matched;
 };
 
-let cachedVectorStore: Pick<
-	VectorStoreService,
-	"query" | "getByMessage"
-> | null = null;
+/**
+ * A `HasWords` clause matches the message body (RFC 031, `clauseMatches`). The
+ * live index-time filter evaluates it against the full parsed body
+ * (`body-sync.ts` `toFilterMessage`); the vector-free corpus slice carries only
+ * `From`/`Subject` at full fidelity and no faithful body, so it cannot serve a
+ * body-content clause without silently narrowing the match to whatever preview
+ * happened to be indexed. Body-content matching therefore requires the widen
+ * (vector) path — {@link matchSemantic} reconstructs body text from chunk
+ * previews there. This guard keeps the two matchers from diverging silently: a
+ * body-content clause reaching the vector-free path fails loud instead of
+ * returning a wrong set. It is unreachable today — no product surface emits a
+ * `HasWords` clause (the organize UI sends empty `literalClauses`, the filter
+ * builder emits none) — and stays a fail-fast for any future surface that does.
+ */
+const assertNoBodyContentClause = (
+	clauses: OrganizePredicate["literalClauses"],
+): void => {
+	if (clauses.some((clause) => clause.field === FilterClauseField.HasWords)) {
+		throw new Error(
+			"Organize literal matching cannot evaluate a body-content (HasWords) clause without the vector pipeline — it requires the semantic widen path",
+		);
+	}
+};
 
-const getVectorStore = (): Pick<
-	VectorStoreService,
-	"query" | "getByMessage"
-> => {
-	if (!cachedVectorStore) {
-		const embedder = buildEmbeddingServiceFromEnv();
-		cachedVectorStore = buildVectorStoreFromEnv(embedder.dimensions);
+/**
+ * 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
+ * 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
+ * rejected up front (see {@link assertNoBodyContentClause}).
+ */
+const matchLiteral = async (
+	deps: OrganizeMatchDeps,
+	accountConfigId: string,
+	predicate: OrganizePredicate,
+	limit: number,
+): Promise<string[]> => {
+	const clauses = predicate.literalClauses;
+	assertNoBodyContentClause(clauses);
+	const candidates = await deps.listAccountFilterMessages(
+		accountConfigId,
+		limit,
+	);
+	if (clauses.length === 0) {
+		return candidates.slice(0, limit).map((c) => c.messageId);
+	}
+	const matched: string[] = [];
+	for (const { messageId, message } of candidates) {
+		if (matched.length >= limit) break;
+		if (literalClausesMatch(clauses, predicate.matchOperator, message)) {
+			matched.push(messageId);
+		}
+	}
+	return matched;
+};
+
+/**
+ * The matcher shared by preview and apply — the previewed set equals the applied
+ * set for the same input. Read-only. Returns the matching message ids, bounded,
+ * and whether the semantic widen was skipped as unavailable.
+ *
+ * - Semantic anchor: {@link matchSemantic}, built lazily so a literal-only
+ *   predicate never touches the vector extension.
+ * - Literal clauses (RFC 031) refine the candidate set; a purely-literal
+ *   back-apply scans a bounded vector-free slice of the corpus instead.
+ * - A predicate with neither an anchor nor a clause matches nothing, mirroring
+ *   the index-time filter matcher.
+ * - When a widen is requested but this deployment ships no vector pipeline, the
+ *   capability-absence is absorbed exactly as `/search/semantic` absorbs it:
+ *   the literal matches are returned (empty for an anchor-only predicate) with
+ *   `semanticUnavailable` set, never a 500. Any other failure propagates.
+ */
+export const matchOrganize = async (
+	deps: OrganizeMatchDeps,
+	accountConfigId: string,
+	predicate: OrganizePredicate,
+	limit: number = ORGANIZE_MATCH_LIMIT,
+): Promise<OrganizeMatchResult> => {
+	const anchored = hasAnchor(predicate);
+	const clauses = predicate.literalClauses;
+	if (!anchored && clauses.length === 0) {
+		return { messageIds: [], semanticUnavailable: false };
+	}
+
+	if (!anchored) {
+		const messageIds = await matchLiteral(
+			deps,
+			accountConfigId,
+			predicate,
+			limit,
+		);
+		return { messageIds, semanticUnavailable: false };
+	}
+
+	try {
+		const semanticIds = await matchSemantic(
+			deps.semantic(),
+			accountConfigId,
+			predicate,
+			limit,
+		);
+		return { messageIds: semanticIds ?? [], semanticUnavailable: false };
+	} catch (error) {
+		if (!noteSemanticCapabilityAbsence(error)) throw error;
+		// The widen cannot run on this deployment. Fall back to the literal
+		// clauses over the corpus — nothing when the predicate is anchor-only —
+		// and flag the absence so the client can say so.
+		if (clauses.length === 0) {
+			return { messageIds: [], semanticUnavailable: true };
+		}
+		const messageIds = await matchLiteral(
+			deps,
+			accountConfigId,
+			predicate,
+			limit,
+		);
+		return { messageIds, semanticUnavailable: true };
 	}
-	return cachedVectorStore;
 };
 
-const buildAnchorFromEnv = (): OrganizeMatchDeps["buildAnchor"] => {
+let cachedSemantic: OrganizeSemanticDeps | null = null;
+
+/**
+ * Construct the semantic side from env on first use and memoize it. The embedder
+ * and vector store are selected by env, independent of `DATA_BACKEND`; building
+ * them is cheap (the vector extension imports lazily on the first store call),
+ * but deferring construction keeps a literal-only preview clear of the whole
+ * semantic graph.
+ */
+const buildSemanticFromEnv = (): OrganizeSemanticDeps => {
+	if (cachedSemantic) return cachedSemantic;
 	const embedder = buildEmbeddingServiceFromEnv();
 	const store = buildVectorStoreFromEnv(embedder.dimensions);
-	return (accountConfigId, anchorMessageId) =>
-		buildMessageAnchor(
-			{ store, embedder },
-			{ accountConfigId, anchorMessageId },
-		);
+	cachedSemantic = {
+		buildAnchor: (accountConfigId, anchorMessageId) =>
+			buildMessageAnchor(
+				{ store, embedder },
+				{ accountConfigId, anchorMessageId },
+			),
+		vectorStore: store,
+	};
+	return cachedSemantic;
 };
 
 /**
- * A bounded corpus slice for a purely-literal back-apply: the account's message
- * ids, gathered mailbox by mailbox and capped. Paginated per mailbox so a large
- * corpus never loads at once.
+ * 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.
+ *
+ * `From`/`Subject` come from the row verbatim (full fidelity). `text` (the body)
+ * is left empty: the thread row carries only a truncated `snippet`, and matching
+ * a body-content clause against a preview would silently diverge from the live
+ * index-time filter's full-body match. Body-content (`HasWords`) clauses are
+ * rejected before this is read (see {@link assertNoBodyContentClause}), so the
+ * empty `text` is never matched against.
  */
-const listAccountMessageIdsFromClient =
-	(client: RemitClient): OrganizeMatchDeps["listAccountMessageIds"] =>
+const listAccountFilterMessagesFromClient =
+	(client: RemitClient): OrganizeMatchDeps["listAccountFilterMessages"] =>
 	async (accountConfigId, limit) => {
-		const accounts =
-			await client.account.listAllByAccountConfig(accountConfigId);
-		const ids: string[] = [];
-		for (const account of accounts) {
-			const mailboxes = await client.mailbox.listAllByAccount(
-				account.accountId,
-			);
-			for (const mailbox of mailboxes) {
-				let continuationToken: string | undefined;
-				do {
-					const page = await client.message.listByMailbox(mailbox.mailboxId, {
-						limit,
-						continuationToken,
-					});
-					for (const message of page.items) {
-						ids.push(message.messageId);
-						if (ids.length >= limit) return ids;
-					}
-					continuationToken = page.continuationToken;
-				} while (continuationToken);
+		const candidates: OrganizeCandidate[] = [];
+		const seen = new Set<string>();
+		let continuationToken: string | undefined;
+		do {
+			const page = await client.threadMessage.listByDate(accountConfigId, {
+				limit,
+				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: "",
+					},
+				});
+				if (candidates.length >= limit) return candidates;
 			}
-		}
-		return ids;
+			continuationToken = page.continuationToken;
+		} while (continuationToken);
+		return candidates;
 	};
 
 /**
- * The env-wired matcher deps for the running backend/worker. The vector store
- * and embedder are selected by env, independent of `DATA_BACKEND`.
+ * The env-wired matcher deps for the running backend/worker. The semantic side
+ * is built lazily so a literal-only preview never constructs it.
  */
 export const buildOrganizeMatchDeps = (
 	client: RemitClient,
 ): OrganizeMatchDeps => ({
-	buildAnchor: buildAnchorFromEnv(),
-	vectorStore: getVectorStore(),
-	listAccountMessageIds: listAccountMessageIdsFromClient(client),
+	semantic: buildSemanticFromEnv,
+	listAccountFilterMessages: listAccountFilterMessagesFromClient(client),
 });
 
 /**

package/src/service/semantic-capability.test.ts

@@ -14,6 +14,14 @@ const moduleNotFound = (): Error => {
 	return error;
 };
 
+const modelUnavailable = (): Error => {
+	const error = new Error(
+		'Embedding model "Xenova/paraphrase-multilingual-MiniLM-L12-v2" could not be loaded',
+	);
+	(error as Error & { code: string }).code = "ERR_EMBEDDING_MODEL_UNAVAILABLE";
+	return error;
+};
+
 describe("noteSemanticCapabilityAbsence", () => {
 	const ORIGINAL = process.env.DATA_BACKEND;
 	beforeEach(() => {
@@ -44,6 +52,16 @@ describe("noteSemanticCapabilityAbsence", () => {
 		assert.equal(noteSemanticCapabilityAbsence(error), true);
 	});
 
+	it("absorbs an embedding-model load failure (e2e-dev from source, HuggingFace fetch failed) and remembers it", () => {
+		for (const backend of ["sqlite", "postgres"]) {
+			_resetSemanticCapabilityForTest();
+			process.env.DATA_BACKEND = backend;
+			assert.equal(isSemanticSearchUnavailable(), false);
+			assert.equal(noteSemanticCapabilityAbsence(modelUnavailable()), true);
+			assert.equal(isSemanticSearchUnavailable(), true);
+		}
+	});
+
 	it("rethrows genuine query errors on the self-host SQL backends", () => {
 		process.env.DATA_BACKEND = "sqlite";
 		assert.equal(
@@ -57,8 +75,10 @@ describe("noteSemanticCapabilityAbsence", () => {
 	it("never engages on the AWS DynamoDB path — a missing module there is a broken deploy", () => {
 		delete process.env.DATA_BACKEND;
 		assert.equal(noteSemanticCapabilityAbsence(moduleNotFound()), false);
+		assert.equal(noteSemanticCapabilityAbsence(modelUnavailable()), false);
 		process.env.DATA_BACKEND = "dynamodb";
 		assert.equal(noteSemanticCapabilityAbsence(moduleNotFound()), false);
+		assert.equal(noteSemanticCapabilityAbsence(modelUnavailable()), false);
 		assert.equal(isSemanticSearchUnavailable(), false);
 	});
 });

package/src/service/semantic-capability.ts

@@ -13,6 +13,15 @@ import { isSelfHostSqlBackend } from "../data-backend.js";
  * fetches semantic hits alongside every literal search), retried by the client
  * on top.
  *
+ * The e2e-dev lane runs this backend from source rather than the container, so
+ * `@huggingface/transformers` IS present and the local embedder instead tries to
+ * lazily download the model from HuggingFace; a transient `fetch failed` there
+ * surfaces the same way. The search-service raises it as a typed
+ * `EmbeddingModelUnavailableError` (code ERR_EMBEDDING_MODEL_UNAVAILABLE), which
+ * this gate treats as the same capability absence — the model is not available,
+ * empty semantic results are the truthful answer, and the lane never depends on
+ * a live external download.
+ *
  * When the pipeline is genuinely absent, empty hits are the truthful answer:
  * the FTS/literal engine is the primary search surface on these profiles and is
  * unaffected. The absence is remembered so subsequent requests short-circuit.
@@ -29,6 +38,7 @@ const CAPABILITY_ABSENCE_CODES = new Set([
 	"ERR_MODULE_NOT_FOUND",
 	"MODULE_NOT_FOUND",
 	"ERR_DLOPEN_FAILED",
+	"ERR_EMBEDDING_MODEL_UNAVAILABLE",
 ]);
 
 let semanticUnavailable = false;