@remit/mailbox-service 0.0.86 → 0.0.88

package/package.json

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

package/src/filters/match.test.ts

@@ -8,6 +8,7 @@ import {
 	cosineSimilarity,
 	type FilterMessage,
 	literalClausesMatch,
+	literalClauseTerms,
 	selectMoveWinner,
 } from "./match.js";
 
@@ -287,3 +288,106 @@ describe("buildMatchText", () => {
 		assert.equal(text.length, 512);
 	});
 });
+
+describe("literalClauseTerms (reader #459)", () => {
+	it("narrows From and Subject onto the columns that carry them", () => {
+		assert.deepEqual(
+			literalClauseTerms(
+				[
+					clause(FilterClauseField.From, " alice@acme.example "),
+					clause(FilterClauseField.Subject, "invoice"),
+				],
+				FilterMatchOperator.And,
+			),
+			{
+				terms: [
+					{ field: "sender", contains: "alice@acme.example" },
+					{ field: "subject", contains: "invoice" },
+				],
+				operator: "and",
+			},
+		);
+	});
+
+	it("narrows FromDomain to the registrable domain, which the sender always contains", () => {
+		const narrowing = literalClauseTerms(
+			[clause(FilterClauseField.FromDomain, "billing@mail.acme.example")],
+			FilterMatchOperator.And,
+		);
+
+		assert.deepEqual(narrowing?.terms, [
+			{ field: "sender", contains: "acme.example" },
+		]);
+		assert.equal(
+			clauseMatches(
+				clause(FilterClauseField.FromDomain, "billing@mail.acme.example"),
+				message(),
+			),
+			true,
+		);
+	});
+
+	it("narrows ListId to its canonical form", () => {
+		assert.deepEqual(
+			literalClauseTerms(
+				[clause(FilterClauseField.ListId, "News <Weekly.News.Example.com>")],
+				FilterMatchOperator.And,
+			)?.terms,
+			[{ field: "listId", contains: "weekly.news.example.com" }],
+		);
+	});
+
+	it("returns null for clauses nothing can satisfy, so no query is worth running", () => {
+		assert.equal(
+			literalClauseTerms(
+				[clause(FilterClauseField.From, "   ")],
+				FilterMatchOperator.And,
+			),
+			null,
+		);
+		assert.equal(
+			literalClauseTerms(
+				[clause(FilterClauseField.FromDomain, "not a domain")],
+				FilterMatchOperator.Or,
+			),
+			null,
+		);
+	});
+
+	it("drops an unsatisfiable clause from an Or instead of losing the rest", () => {
+		assert.deepEqual(
+			literalClauseTerms(
+				[
+					clause(FilterClauseField.From, ""),
+					clause(FilterClauseField.Subject, "invoice"),
+				],
+				FilterMatchOperator.Or,
+			),
+			{ terms: [{ field: "subject", contains: "invoice" }], operator: "or" },
+		);
+	});
+
+	it("narrows nothing when an Or reaches a clause no column carries", () => {
+		assert.deepEqual(
+			literalClauseTerms(
+				[
+					clause(FilterClauseField.HasWords, "quarter"),
+					clause(FilterClauseField.Subject, "invoice"),
+				],
+				FilterMatchOperator.Or,
+			),
+			{ terms: [], operator: "or" },
+		);
+	});
+
+	it("narrows nothing for no clauses, matching the vacuous pass of literalClausesMatch", () => {
+		assert.deepEqual(literalClauseTerms([], FilterMatchOperator.And), {
+			terms: [],
+			operator: "and",
+		});
+		assert.equal(
+			literalClausesMatch([], FilterMatchOperator.And, message()),
+			true,
+		);
+	});
+});

package/src/filters/match.ts

@@ -1,4 +1,8 @@
-import { FILTER_NO_ACTION, type FilterItem } from "@remit/data-ports";
+import {
+	FILTER_NO_ACTION,
+	type FilterItem,
+	type ThreadMessageFieldTerm,
+} from "@remit/data-ports";
 import { FilterClauseField, FilterMatchOperator } from "@remit/domain-enums";
 import { getDomain } from "tldts";
 import { normalizeListId } from "./list-id.js";
@@ -108,6 +112,87 @@ export const literalClausesMatch = (
 		: clauses.every((clause) => clauseMatches(clause, msg));
 };
 
+/**
+ * What a store can be asked for on behalf of one clause: a column term, or the
+ * two answers a term cannot express — a clause nothing can satisfy, and a
+ * clause selecting on something no ThreadMessage column carries.
+ */
+type ClauseNarrowing =
+	| { kind: "Term"; term: ThreadMessageFieldTerm }
+	| { kind: "NeverMatches" }
+	| { kind: "Unnarrowable" };
+
+const clauseNarrowing = (clause: FilterClause): ClauseNarrowing => {
+	const value = clause.value.trim();
+	if (value === "") return { kind: "NeverMatches" };
+	switch (clause.field) {
+		case FilterClauseField.From:
+			return { kind: "Term", term: { field: "sender", contains: value } };
+		case FilterClauseField.Subject:
+			return { kind: "Term", term: { field: "subject", contains: value } };
+		case FilterClauseField.ListId: {
+			const target = normalizeListId(value);
+			if (target === "") return { kind: "NeverMatches" };
+			return { kind: "Term", term: { field: "listId", contains: target } };
+		}
+		case FilterClauseField.FromDomain: {
+			const target = registrableDomain(value);
+			if (target === null) return { kind: "NeverMatches" };
+			return { kind: "Term", term: { field: "sender", contains: target } };
+		}
+		default:
+			return { kind: "Unnarrowable" };
+	}
+};
+
+/**
+ * The terms to query with, and how to combine them. Empty terms narrow nothing
+ * — the caller reads the whole corpus and refines it.
+ */
+export interface LiteralClauseNarrowing {
+	terms: ThreadMessageFieldTerm[];
+	operator: "and" | "or";
+}
+
+/**
+ * The store-side half of {@link literalClausesMatch}: the column terms a query
+ * can evaluate on behalf of these clauses, or `null` when they can match
+ * nothing at all and there is no query worth running.
+ *
+ * A term is deliberately WIDER than the clause it stands for — a `FromDomain`
+ * clause narrows to the registrable domain appearing anywhere in the sender,
+ * so `github.com.evil.example` still comes back — and a `HasWords` clause
+ * cannot be narrowed at all, since no row column carries the body. The rows a
+ * term selects are candidates; `literalClausesMatch` still decides. Pushing the
+ * terms down is what makes the caller's bound a bound on RESULTS: filtering a
+ * date-ordered page instead answers "matches among the newest N messages"
+ * (#459).
+ */
+export const literalClauseTerms = (
+	clauses: readonly FilterClause[],
+	operator: FilterItem["matchOperator"],
+): LiteralClauseNarrowing | null => {
+	const combine = operator === FilterMatchOperator.Or ? "or" : "and";
+	if (clauses.length === 0) return { terms: [], operator: combine };
+	const narrowings = clauses.map(clauseNarrowing);
+	const terms = narrowings.flatMap((narrowing) =>
+		narrowing.kind === "Term" ? [narrowing.term] : [],
+	);
+	if (combine === "and") {
+		if (narrowings.some((narrowing) => narrowing.kind === "NeverMatches")) {
+			return null;
+		}
+		return { terms, operator: "and" };
+	}
+	if (narrowings.every((narrowing) => narrowing.kind === "NeverMatches")) {
+		return null;
+	}
+	if (narrowings.some((narrowing) => narrowing.kind === "Unnarrowable")) {
+		return { terms: [], operator: "or" };
+	}
+	return { terms, operator: "or" };
+};
+
 /**
  * Cosine similarity of two equal-length vectors. Throws on a dimension mismatch
  * rather than silently scoring incomparable vectors — a mismatch means a stale

package/src/index.ts

@@ -76,7 +76,9 @@ export {
 	cosineSimilarity,
 	DEFAULT_SEMANTIC_MATCH_THRESHOLD,
 	type FilterMessage,
+	type LiteralClauseNarrowing,
 	literalClausesMatch,
+	literalClauseTerms,
 	NO_ACTION,
 	selectMoveWinner,
 } from "./filters/match.js";
@@ -249,7 +251,11 @@ export {
 	type ResolveExhaustedPlacementMoveResult,
 	resolveExhaustedPlacementMoveFailure,
 } from "./placement-move-terminal.js";
-export { isPlacementUnsettled } from "./placement-settled.js";
+export {
+	isPlacementUnsettled,
+	type PlacementBinding,
+	placementBindingOf,
+} from "./placement-settled.js";
 export {
 	type QuarantineContext,
 	QuarantinedUids,

package/src/placement-settled.ts

@@ -44,10 +44,12 @@ export const bindsForeignUid = (
 
 /**
  * `in_flight` — a mover is still working on the row, so waiting resolves it.
- * `abandoned` — the mover gave up without confirming (`syncStatus: failed`,
- * written by every handler's give-up path while `status` stays `moving`, since
- * only `updateUid` clears it). Nothing routine settles such a row, so waiting
- * on one is a wait that never ends, and the pair stays a lie either way.
+ * `abandoned` — the last attempt failed (`syncStatus: failed`) and the row is
+ * still `moving`: either a redelivery is pending, or the record dead-lettered
+ * and nothing is coming for it. The two are indistinguishable from the row
+ * (`message-settlement.ts`), and the pair is a lie either way, so neither is
+ * worth spending the settle ceiling on. A mover that exhausts its budget
+ * settles the row against IMAP instead of leaving this state behind (#1005).
  */
 export type PlacementBinding = "consistent" | "in_flight" | "abandoned";