@remit/mailbox-service 0.0.61 → 0.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.61",
+  "version": "0.0.62",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/filters/anchor-drift.ts

@@ -0,0 +1,55 @@
+import type {
+	FilterAnchorItem,
+	IFilterAnchorRepository,
+} from "@remit/data-ports";
+
+/**
+ * The half of an embedding service an anchor refresh needs: the text-to-vector
+ * call and the `<modelId>@<dimensions>` identifier of the model behind it (the
+ * same scheme `EmbeddingService.embeddingId` derives). Compared against
+ * `FilterAnchor.anchorEmbeddingId` to detect a model drift a same-dimension
+ * swap would otherwise pass through silently (RFC 039 Decision 1a, reader
+ * #295).
+ */
+export interface AnchorEmbedder {
+	embed(text: string): Promise<number[]>;
+	readonly embeddingId: string;
+}
+
+export interface AnchorDriftDeps {
+	anchorRepository: Pick<IFilterAnchorRepository, "put">;
+	/** Absent on a deployment with no embedder wired; then nothing can drift. */
+	embedder: AnchorEmbedder | undefined;
+}
+
+/**
+ * The anchor to score against, re-embedded in place when the embedding model
+ * has drifted since it was written (RFC 039 Decision 1a). No migration job
+ * walks these rows proactively, so the refresh is lazy: the first read that
+ * notices the stamp no longer matches the configured model re-embeds the
+ * already-persisted `anchorSourceText` and writes it back under the current
+ * id. A failure here is never a terminal state — the row is left as it was,
+ * so the next read that reaches this anchor retries.
+ *
+ * The single mechanism behind both index-time matching
+ * ({@link FilterPipeline}) and the back-apply pass's cross-filter precedence
+ * check, which must agree on what a filter currently matches (reader #399).
+ */
+export const refreshAnchorForEmbedder = async (
+	deps: AnchorDriftDeps,
+	anchor: FilterAnchorItem,
+): Promise<FilterAnchorItem> => {
+	const { embedder } = deps;
+	if (!embedder || anchor.anchorEmbeddingId === embedder.embeddingId) {
+		return anchor;
+	}
+	const anchorEmbedding = await embedder.embed(anchor.anchorSourceText);
+	return deps.anchorRepository.put({
+		accountConfigId: anchor.accountConfigId,
+		filterId: anchor.filterId,
+		anchorEmbedding,
+		anchorEmbeddingId: embedder.embeddingId,
+		anchorSourceText: anchor.anchorSourceText,
+		anchorMessageId: anchor.anchorMessageId,
+	});
+};

package/src/filters/pipeline.ts

@@ -7,6 +7,10 @@ import type {
 } from "@remit/data-ports";
 import { FilterState } from "@remit/domain-enums";
 import type { PlacementMoveService } from "../placement-move.js";
+import {
+	type AnchorEmbedder,
+	refreshAnchorForEmbedder,
+} from "./anchor-drift.js";
 import {
 	buildMatchText,
 	cosineSimilarity,
@@ -20,22 +24,12 @@ import {
 /**
  * Turns the candidate message's text into a single message-level vector to
  * compare against a filter's persisted `anchorEmbedding`. The anchor side is
- * never embedded here — it is read from `FilterAnchor` as a fixed fact (RFC 034
- * Decision 2.1/2.3); only the incoming message is embedded, and only once per
- * message, and only when a semantic filter is actually in play.
+ * embedded here only to repair a drifted anchor in place (see
+ * {@link refreshAnchorForEmbedder}); the match itself reads `FilterAnchor` as
+ * a fixed fact (RFC 034 Decision 2.1/2.3), and the incoming message is
+ * embedded once per message, only when a semantic filter is actually in play.
  */
-export interface MessageEmbedder {
-	embed(text: string): Promise<number[]>;
-	/**
-	 * `<modelId>@<dimensions>` identifier of the model currently configured —
-	 * the same scheme `EmbeddingService.embeddingId`
-	 * (`packages/search-service/src/embeddings.ts`) derives. Compared against
-	 * `FilterAnchor.anchorEmbeddingId` to detect a model drift a same-dimension
-	 * swap would otherwise pass through silently (RFC 039 Decision 1a, reader
-	 * #295).
-	 */
-	readonly embeddingId: string;
-}
+export type MessageEmbedder = AnchorEmbedder;
 
 export interface FilterLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
@@ -236,26 +230,16 @@ export class FilterPipeline {
 			return false;
 		}
 
-		const embedder = this.config.embedder;
-		if (embedder && anchor.anchorEmbeddingId !== embedder.embeddingId) {
-			// The embedding model has drifted since this anchor was last written
-			// (RFC 039 Decision 1a) — re-embed the already-persisted
-			// `anchorSourceText` and write it back in place, lazily, on this read.
-			// No migration job walks these rows proactively; a re-embed failure
-			// here propagates to the per-filter catch in `match()`, which logs and
-			// skips this filter for this one evaluation exactly as an unrecoverable
-			// stale anchor does today — never a terminal state, so the next
-			// message that reaches this filter retries.
-			const anchorEmbedding = await embedder.embed(anchor.anchorSourceText);
-			anchor = await this.config.filterAnchorService.put({
-				accountConfigId,
-				filterId: filter.filterId,
-				anchorEmbedding,
-				anchorEmbeddingId: embedder.embeddingId,
-				anchorSourceText: anchor.anchorSourceText,
-				anchorMessageId: anchor.anchorMessageId,
-			});
-		}
+		// A re-embed failure here propagates to the per-filter catch in
+		// `match()`, which logs and skips this filter for this one evaluation
+		// exactly as an unrecoverable stale anchor does today.
+		anchor = await refreshAnchorForEmbedder(
+			{
+				anchorRepository: this.config.filterAnchorService,
+				embedder: this.config.embedder,
+			},
+			anchor,
+		);
 
 		const vector = await embed();
 		if (!vector) {

package/src/index.ts

@@ -59,6 +59,11 @@ export {
 	testImapConnection,
 	testSmtpConnection,
 } from "./connection-test.js";
+export {
+	type AnchorDriftDeps,
+	type AnchorEmbedder,
+	refreshAnchorForEmbedder,
+} from "./filters/anchor-drift.js";
 export { extractListId, normalizeListId } from "./filters/list-id.js";
 export {
 	buildMatchText,