@remit/drizzle-service 0.0.39 → 0.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/drizzle-service",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Drizzle ORM service over SQLite",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -33,6 +33,7 @@ export {
 export * from "./repos/i4-organize-job-request.js";
 export { OutboxAttachmentRepo } from "./repos/i4-outbox-attachment.js";
 export * from "./repos/i4-outbox-message.js";
+export { SenderSignerStandingRepo } from "./repos/i4-sender-signer-standing.js";
 export { LabelRepo } from "./repos/label.js";
 export {
 	DrizzleMessageRepository,

package/src/repos/address-search-predicates.ts

@@ -0,0 +1,82 @@
+import { or, type SQL, sql } from "drizzle-orm";
+import { addressTable } from "../schema/i4-address.js";
+
+// The address search seam. A term is matched as a substring of the display name,
+// the local part, the domain and the whole address, and the order it comes back
+// in is decided by which of those matched and where (#704).
+
+const escapeLike = (term: string): string => term.replace(/[\\%_]/g, "\\$&");
+
+const SEARCH_COLUMNS = [
+	sql`lower(coalesce(${addressTable.displayName}, ''))`,
+	sql`${addressTable.localPart}`,
+	sql`${addressTable.domain}`,
+	sql`${addressTable.normalizedEmail}`,
+] as const;
+
+/**
+ * SQL `lower()` and `like` both fold ASCII only, so a column read through them
+ * can never meet a term folded by JavaScript: `Öz` would miss `Özcan Bakker`.
+ * `normalizedCompound` is written already folded by JavaScript, on the same
+ * rules as the term, so matching it raw is what keeps a name outside ASCII
+ * findable. It carries no column identity — the name and the address are
+ * concatenated in it — so a row reached only this way scores no rank and sorts
+ * last, which is where a fallback belongs.
+ */
+const FOLDED_FALLBACK = sql`${addressTable.normalizedCompound}`;
+
+const like = (column: SQL, pattern: string): SQL =>
+	sql`${column} like ${pattern} escape '\\'`;
+
+const patterns = (term: string) => {
+	const escaped = escapeLike(term.toLowerCase());
+	return { leading: `${escaped}%`, anywhere: `%${escaped}%` };
+};
+
+export const addressSearchMatch = (term: string): SQL => {
+	const { anywhere } = patterns(term);
+	const matched = or(
+		...[...SEARCH_COLUMNS, FOLDED_FALLBACK].map((column) =>
+			like(column, anywhere),
+		),
+	);
+	if (matched === undefined) throw new Error("no address column to search");
+	return matched;
+};
+
+/**
+ * Where the term hit, as one number: every match at the start of a column
+ * outranks every match in the middle of one, and within each the display name
+ * outranks the local part, the domain and the whole address. A mid-string match
+ * still comes back — this only decides the order.
+ */
+export const addressMatchRank = (term: string | undefined): SQL<number> => {
+	// Not the bare literal `0`: SQLite reads an integer literal in ORDER BY as a
+	// column index and rejects it as out of range.
+	if (!term) return sql<number>`cast(0 as integer)`;
+	const { leading, anywhere } = patterns(term);
+	const arms = [
+		...SEARCH_COLUMNS.map((column) => like(column, leading)),
+		...SEARCH_COLUMNS.map((column) => like(column, anywhere)),
+	].map(
+		(condition, index) =>
+			sql`when ${condition} then ${SEARCH_COLUMNS.length * 2 - index}`,
+	);
+	return sql<number>`case ${sql.join(arms, sql` `)} else 0 end`;
+};
+
+// `json_extract` raises on text that is not JSON, and this runs on every row in
+// the account's scan — one unparseable `flags` value would take the whole
+// account's autocomplete down rather than its own row.
+const flagValue = (name: string): SQL<number> =>
+	sql<number>`coalesce(json_extract(coalesce(nullif(${addressTable.flags}, ''), '{}'), ${`$.${name}.value`}), 0)`;
+
+/** The account's own standing for the sender: a VIP first, then one it trusts. */
+export const addressPreference = (): SQL<number> =>
+	sql<number>`(2 * ${flagValue("vip")} + ${flagValue("trusted")})`;
+
+export const addressCorrespondence = (): SQL<number> =>
+	sql<number>`(${addressTable.replyCount} + ${addressTable.inboundCount} + ${addressTable.outboundCount})`;
+
+export const addressRecency = (): SQL<number> =>
+	sql<number>`max(${addressTable.lastInboundAt}, ${addressTable.lastReplyAt}, coalesce(${addressTable.lastOutboundAt}, 0))`;

package/src/repos/i4-address.test.ts

@@ -98,6 +98,45 @@ describe("AddressRepo", () => {
 		await repo.deleteAddress(addr.accountConfigId, addr.addressId);
 	});
 
+	test("three inbound messages promote a person-shaped sender to wellknown", async () => {
+		const addr = await repo.createAddress(makeAddressInput(randomId()));
+		const now = Date.now();
+
+		for (let i = 0; i < 3; i++) {
+			await repo.incrementInboundCount(
+				addr.accountConfigId,
+				addr.addressId,
+				now,
+				false,
+			);
+		}
+
+		const updated = await repo.getAddress(addr.accountConfigId, addr.addressId);
+		assert.equal(updated.flags?.wellknown?.value, true);
+
+		await repo.deleteAddress(addr.accountConfigId, addr.addressId);
+	});
+
+	test("a bulk sender never reaches wellknown on inbound volume alone", async () => {
+		const addr = await repo.createAddress(makeAddressInput(randomId()));
+		const now = Date.now();
+
+		for (let i = 0; i < 5; i++) {
+			await repo.incrementInboundCount(
+				addr.accountConfigId,
+				addr.addressId,
+				now,
+				true,
+			);
+		}
+
+		const updated = await repo.getAddress(addr.accountConfigId, addr.addressId);
+		assert.equal(updated.inboundCount, 5);
+		assert.equal(updated.flags?.wellknown, undefined);
+
+		await repo.deleteAddress(addr.accountConfigId, addr.addressId);
+	});
+
 	test("createEnvelopeAddress and getEnvelopeAddress", async () => {
 		const messageId = randomUUID();
 		const addressId = randomUUID();
@@ -241,23 +280,417 @@ describe("AddressRepo", () => {
 		await repo.deleteManyAddresses(accountConfigId, [created.addressId]);
 	});
 
-	test("listByAccountConfig treats LIKE metacharacters in a search term literally", async () => {
+	test("listByAccountConfig matches any word of the display name, the local part and the domain (#704)", async () => {
 		const accountConfigId = randomId();
-		const plain = await repo.createAddress(
-			makeAddressInput(accountConfigId, "ab@x.com"),
+		const created = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "amsterdam@pocahondas.nl"),
+			displayName: "Pocahondas locatie amsterdam",
+			normalizedCompound:
+				"pocahondas locatie amsterdam amsterdam@pocahondas.nl",
+		});
+
+		for (const term of [
+			"po",
+			"pocahondas",
+			"locatie",
+			"amsterdam",
+			"pocahondas.nl",
+			"@pocahondas.nl",
+			"amsterdam@pocahondas.nl",
+		]) {
+			const found = await repo.listByAccountConfig({
+				accountConfigId,
+				search: term,
+			});
+			assert.deepEqual(
+				found.items.map((a) => a.addressId),
+				[created.addressId],
+				`"${term}" must resolve the address`,
+			);
+		}
+
+		await repo.deleteManyAddresses(accountConfigId, [created.addressId]);
+	});
+
+	test("listByAccountConfig finds a display name whose first letter is not ASCII", async () => {
+		const accountConfigId = randomId();
+		// Written the way message sync writes it: the compound folded in JavaScript.
+		const names = [
+			["Özcan Bakker", "o.bakker@kliniek.nl", ["Öz", "öz", "özcan", "zcan"]],
+			["Émile Zola", "emile@zola.test", ["Ém", "ém", "émile", "zola"]],
+			["Ángela Ruiz", "angela@ruiz.test", ["Án", "án", "ángela", "ngela"]],
+		] as const;
+
+		for (const [displayName, email, terms] of names) {
+			const created = await repo.createAddress({
+				...makeAddressInput(accountConfigId, email),
+				displayName,
+				normalizedCompound: `${displayName.toLowerCase()} ${email}`,
+			});
+
+			for (const term of terms) {
+				const found = await repo.listByAccountConfig({
+					accountConfigId,
+					search: term,
+				});
+				assert.deepEqual(
+					found.items.map((a) => a.addressId),
+					[created.addressId],
+					`"${term}" must resolve ${displayName}`,
+				);
+			}
+
+			await repo.deleteManyAddresses(accountConfigId, [created.addressId]);
+		}
+	});
+
+	test("updateAddress keeps the compound findable when a name is not ASCII", async () => {
+		const accountConfigId = randomId();
+		const created = await repo.createAddress(
+			makeAddressInput(accountConfigId, "o.bakker@kliniek.nl"),
+		);
+
+		await repo.updateAddress(accountConfigId, created.addressId, {
+			displayName: "Özcan Bakker",
+		});
+
+		const found = await repo.listByAccountConfig({
+			accountConfigId,
+			search: "Öz",
+		});
+		assert.deepEqual(
+			found.items.map((a) => a.addressId),
+			[created.addressId],
+		);
+
+		await repo.deleteManyAddresses(accountConfigId, [created.addressId]);
+	});
+
+	test("listByAccountConfig offers a two-letter name match ahead of a louder domain match (#704)", async () => {
+		const accountConfigId = randomId();
+		const colin = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "colin@personal.com"),
+			displayName: "Colin Baker",
+			inboundCount: 4,
+		});
+		const newsletter = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "info@acme.com"),
+			displayName: "Acme Newsletter",
+			inboundCount: 500,
+		});
+
+		const byInitials = await repo.listByAccountConfig({
+			accountConfigId,
+			search: "co",
+			limit: 1,
+		});
+		assert.deepEqual(
+			byInitials.items.map((a) => a.addressId),
+			[colin.addressId],
+			"volume must not take the only suggestion slot from a name match",
+		);
+
+		const shop = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "hello@corner.test"),
+			displayName: "Corner Shop",
+		});
+		const loud = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "news@corner.test"),
+			displayName: "Loud List",
+			inboundCount: 500,
+		});
+		const byName = await repo.listByAccountConfig({
+			accountConfigId,
+			search: "corner",
+		});
+		assert.deepEqual(
+			byName.items.map((a) => a.addressId),
+			[shop.addressId, loud.addressId],
+			"a name match outranks a shared domain",
 		);
 
-		const result = await repo.listByAccountConfig({
+		await repo.deleteManyAddresses(accountConfigId, [
+			colin.addressId,
+			newsletter.addressId,
+			shop.addressId,
+			loud.addressId,
+		]);
+	});
+
+	test("cross-tenant: a search never reaches another account's addresses", async () => {
+		const mine = randomId();
+		const theirs = randomId();
+		const ours = await repo.createAddress({
+			...makeAddressInput(mine, "amsterdam@pocahondas.nl"),
+			displayName: "Pocahondas locatie amsterdam",
+		});
+		const foreign = await repo.createAddress({
+			...makeAddressInput(theirs, "amsterdam@pocahondas.nl"),
+			displayName: "Pocahondas locatie amsterdam",
+		});
+
+		for (const term of ["po", "amsterdam", "pocahondas.nl"]) {
+			const found = await repo.listByAccountConfig({
+				accountConfigId: mine,
+				search: term,
+			});
+			assert.deepEqual(
+				found.items.map((a) => a.addressId),
+				[ours.addressId],
+				`"${term}" must stay inside the caller's account`,
+			);
+		}
+
+		await repo.deleteManyAddresses(mine, [ours.addressId]);
+		await repo.deleteManyAddresses(theirs, [foreign.addressId]);
+	});
+
+	test("listByAccountConfig puts a match at the start of a name above one in the middle", async () => {
+		const accountConfigId = randomId();
+		const leading = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "amsterdam@pocahondas.nl"),
+			displayName: "Pocahondas locatie amsterdam",
+		});
+		const middle = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "hello@example.test"),
+			displayName: "Studio Pocahondas",
+			inboundCount: 500,
+		});
+
+		const found = await repo.listByAccountConfig({
 			accountConfigId,
-			search: "a_@x.com",
+			search: "po",
+		});
+		assert.deepEqual(
+			found.items.map((a) => a.addressId),
+			[leading.addressId, middle.addressId],
+			"a mid-name match is returned, but below the one the term starts",
+		);
+
+		await repo.deleteManyAddresses(accountConfigId, [
+			leading.addressId,
+			middle.addressId,
+		]);
+	});
+
+	test("listByAccountConfig leads a tier with the account's own VIP", async () => {
+		const accountConfigId = randomId();
+		const vip = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "one@vips.test"),
+			displayName: "Sales Alice",
+			flags: { vip: { value: true, setAt: 1 } },
 		});
+		const trusted = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "two@vips.test"),
+			displayName: "Sales Bob",
+			flags: { trusted: { value: true, setAt: 1 } },
+			inboundCount: 40,
+		});
+		const stranger = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "three@vips.test"),
+			displayName: "Sales Carol",
+			inboundCount: 900,
+		});
+
+		const found = await repo.listByAccountConfig({
+			accountConfigId,
+			search: "sales",
+		});
+		assert.deepEqual(
+			found.items.map((a) => a.addressId),
+			[vip.addressId, trusted.addressId, stranger.addressId],
+			"standing decides ahead of volume",
+		);
+
+		await repo.deleteManyAddresses(accountConfigId, [
+			vip.addressId,
+			trusted.addressId,
+			stranger.addressId,
+		]);
+	});
+
+	test("listByAccountConfig finds an address whose display name arrived after the first sighting", async () => {
+		const accountConfigId = randomId();
+		// How message-sync writes a first sighting with no display name, then a
+		// later one that carries it.
+		const nameless = {
+			...makeAddressInput(accountConfigId, "amsterdam@pocahondas.nl"),
+			displayName: "",
+			normalizedCompound: "amsterdam@pocahondas.nl",
+		};
+		await repo.upsertAddress(nameless);
+		const created = await repo.upsertAddress({
+			...nameless,
+			displayName: "Pocahondas locatie amsterdam",
+			normalizedCompound:
+				"pocahondas locatie amsterdam amsterdam@pocahondas.nl",
+		});
+		assert.equal(created.displayName, "Pocahondas locatie amsterdam");
+
+		for (const term of ["po", "locatie", "pocahondas"]) {
+			const found = await repo.listByAccountConfig({
+				accountConfigId,
+				search: term,
+			});
+			assert.deepEqual(
+				found.items.map((a) => a.addressId),
+				[created.addressId],
+				`"${term}" must resolve the address`,
+			);
+		}
+
+		await repo.deleteManyAddresses(accountConfigId, [created.addressId]);
+	});
+
+	test("upsertAddress keeps a known display name when a later sighting carries none", async () => {
+		const accountConfigId = randomId();
+		const named = {
+			...makeAddressInput(accountConfigId, "amsterdam@pocahondas.nl"),
+			displayName: "Pocahondas locatie amsterdam",
+			normalizedCompound:
+				"pocahondas locatie amsterdam amsterdam@pocahondas.nl",
+		};
+		await repo.upsertAddress(named);
+		const after = await repo.upsertAddress({
+			...named,
+			displayName: "",
+			normalizedCompound: "amsterdam@pocahondas.nl",
+		});
+
+		assert.equal(after.displayName, "Pocahondas locatie amsterdam");
 		assert.equal(
-			result.items.length,
-			0,
-			"`_` must not act as a single-character wildcard",
+			after.normalizedCompound,
+			"pocahondas locatie amsterdam amsterdam@pocahondas.nl",
+		);
+		const found = await repo.listByAccountConfig({
+			accountConfigId,
+			search: "locatie",
+		});
+		assert.deepEqual(
+			found.items.map((a) => a.addressId),
+			[named.addressId],
+		);
+
+		await repo.deleteManyAddresses(accountConfigId, [named.addressId]);
+	});
+
+	test("listByAccountConfig ranks an address the account writes to above an alphabetically earlier stranger (#704)", async () => {
+		const accountConfigId = randomId();
+		const stranger = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "aaron@example.com"),
+			displayName: "Aaron Stranger",
+			normalizedCompound: "aaron stranger aaron@example.com",
+		});
+		const frequent = await repo.createAddress({
+			...makeAddressInput(accountConfigId, "zoe@example.com"),
+			displayName: "Zoe Frequent",
+			normalizedCompound: "zoe frequent zoe@example.com",
+		});
+		// Written to, never heard back from — the compose field's most useful
+		// suggestion and the one a received-mail-only score would bury.
+		const now = Date.now();
+		await repo.incrementOutboundCount(accountConfigId, frequent.addressId, now);
+		await repo.incrementOutboundCount(accountConfigId, frequent.addressId, now);
+
+		const ranked = await repo.listByAccountConfig({
+			accountConfigId,
+			search: "example.com",
+		});
+		assert.deepEqual(
+			ranked.items.map((a) => a.normalizedEmail),
+			["zoe@example.com", "aaron@example.com"],
+			"correspondence outranks the alphabet",
+		);
+
+		const cut = await repo.listByAccountConfig({
+			accountConfigId,
+			search: "example.com",
+			limit: 1,
+		});
+		assert.deepEqual(
+			cut.items.map((a) => a.normalizedEmail),
+			["zoe@example.com"],
+			"a short suggestion list keeps the address worth suggesting",
 		);
 
-		await repo.deleteManyAddresses(accountConfigId, [plain.addressId]);
+		await repo.deleteManyAddresses(accountConfigId, [
+			stranger.addressId,
+			frequent.addressId,
+		]);
+	});
+
+	test("listByAccountConfig pages a ranked search without dupes or gaps", async () => {
+		const accountConfigId = randomId();
+		const created: string[] = [];
+		for (const [index, name] of ["a", "b", "c", "d", "e"].entries()) {
+			const addr = await repo.createAddress({
+				...makeAddressInput(accountConfigId, `${name}@ranked.test`),
+				displayName: name,
+				normalizedCompound: `${name} ${name}@ranked.test`,
+				inboundCount: index % 2,
+			});
+			created.push(addr.addressId);
+		}
+
+		const seen: string[] = [];
+		let cursor: string | undefined;
+		let pages = 0;
+		do {
+			const page = await repo.listByAccountConfig({
+				accountConfigId,
+				search: "ranked.test",
+				limit: 2,
+				cursor,
+			});
+			seen.push(...page.items.map((a) => a.addressId));
+			cursor = page.continuationToken;
+			pages++;
+			assert.ok(pages < 10, "pagination must terminate");
+		} while (cursor);
+
+		assert.equal(new Set(seen).size, 5, "every row returned exactly once");
+		assert.deepEqual([...seen].sort(), [...created].sort(), "no gaps");
+
+		await repo.deleteManyAddresses(accountConfigId, created);
+	});
+
+	test("listByAccountConfig treats LIKE metacharacters in a search term literally", async () => {
+		const accountConfigId = randomId();
+		const plain = await repo.createAddress(
+			makeAddressInput(accountConfigId, "ab@x.com"),
+		);
+		const literal = await repo.createAddress(
+			makeAddressInput(accountConfigId, "a%b_c@x.com"),
+		);
+
+		for (const term of ["a_@x.com", "a%x", "a%b_c@y"]) {
+			const found = await repo.listByAccountConfig({
+				accountConfigId,
+				search: term,
+			});
+			assert.deepEqual(
+				found.items.map((a) => a.addressId),
+				[],
+				`"${term}" must match no wildcard`,
+			);
+		}
+
+		for (const term of ["a%b", "b_c", "a%b_c@x.com"]) {
+			const found = await repo.listByAccountConfig({
+				accountConfigId,
+				search: term,
+			});
+			assert.deepEqual(
+				found.items.map((a) => a.addressId),
+				[literal.addressId],
+				`"${term}" must match the metacharacter literally`,
+			);
+		}
+
+		await repo.deleteManyAddresses(accountConfigId, [
+			plain.addressId,
+			literal.addressId,
+		]);
 	});
 
 	test("cross-tenant: getAddress refuses a foreign accountConfig", async () => {
@@ -412,6 +845,12 @@ describe("AddressRepo", () => {
 			["an unparseable", "not-a-cursor"],
 			["a bare number", Buffer.from("123").toString("base64url")],
 			["a JSON array", Buffer.from("[1,2]").toString("base64url")],
+			[
+				"a token without a ranking key",
+				Buffer.from(
+					JSON.stringify({ normalizedCompound: "a", addressId: "b" }),
+				).toString("base64url"),
+			],
 		] as const) {
 			test(`${label} cursor is rejected as a 400`, async () => {
 				await assert.rejects(

package/src/repos/i4-address.ts

@@ -9,40 +9,105 @@ import type {
 	ResultList,
 	UpdateAddressInput,
 } from "@remit/data-ports";
-import { and, asc, eq, gt, inArray, or, sql } from "drizzle-orm";
+import { BadRequestError } from "@remit/data-ports/errors";
+import {
+	and,
+	asc,
+	desc,
+	eq,
+	getTableColumns,
+	inArray,
+	type SQL,
+	sql,
+} from "drizzle-orm";
 import type { Db } from "../db.js";
 import { NotFoundError } from "../error.js";
 import { envelopeAddressId as deriveEnvelopeAddressId } from "../id.js";
 import { decodeToken, resultList } from "../pagination.js";
 import { addressTable } from "../schema/i4-address.js";
 import { envelopeAddressTable } from "../schema/message-data.js";
+import {
+	addressCorrespondence,
+	addressMatchRank,
+	addressPreference,
+	addressRecency,
+	addressSearchMatch,
+} from "./address-search-predicates.js";
 import { shouldPromoteWellknown } from "./i4-address-wellknown.js";
 
 type DB = Db<Record<string, unknown>>;
 
+type AddressUpdate = Partial<{
+	[K in keyof typeof addressTable.$inferInsert]:
+		| (typeof addressTable.$inferInsert)[K]
+		| SQL;
+}>;
+
 /**
- * Escape the LIKE metacharacters so a term containing `%` or `_` (both legal in
- * an email local part) matches literally instead of as a wildcard.
+ * The stored `"<display name> <email>"` compound, folded in JavaScript exactly
+ * as message sync folds it — SQL `lower()` stops at ASCII, and the search reads
+ * this column expecting a full fold.
  */
-const escapeLikeTerm = (term: string): string =>
-	term.replace(/[\\%_]/g, (char) => `\\${char}`);
+const compoundOfSql = (displayName: string): SQL<string> =>
+	sql<string>`trim(${displayName.toLowerCase()} || ' ' || ${addressTable.normalizedEmail})`;
 
 /**
- * Match an address search term as a prefix of either the display-name compound
- * or the normalized email.
- *
- * `normalizedCompound` is stored as `"<display name> <email>"`, so a prefix
- * match on it only ever answers display-name queries — an exact-address lookup
- * such as `support@npmjs.com` can never match a row whose sender has a display
- * name. Matching `normalizedEmail` in the same predicate is what makes address
- * resolution by email work at all (issue #51).
+ * The order a suggestion list comes back in: where the term hit, then the
+ * account's own standing for the sender, then how much it corresponds with it,
+ * then how recently — and the stored compound and the id last, so the order is
+ * total and a page boundary is a position rather than a guess.
  */
-const addressSearchPredicate = (term: string) => {
-	const pattern = `${escapeLikeTerm(term)}%`;
-	return or(
-		sql`${addressTable.normalizedCompound} LIKE ${pattern} ESCAPE '\\'`,
-		sql`${addressTable.normalizedEmail} LIKE ${pattern} ESCAPE '\\'`,
-	);
+const searchOrder = (search: string | undefined) =>
+	[
+		{ key: "rank", expr: addressMatchRank(search), direction: "desc" },
+		{ key: "preference", expr: addressPreference(), direction: "desc" },
+		{ key: "correspondence", expr: addressCorrespondence(), direction: "desc" },
+		{ key: "recency", expr: addressRecency(), direction: "desc" },
+		{
+			key: "normalizedCompound",
+			expr: sql`${addressTable.normalizedCompound}`,
+			direction: "asc",
+		},
+		{
+			key: "addressId",
+			expr: sql`${addressTable.addressId}`,
+			direction: "asc",
+		},
+	] as const;
+
+type SearchOrder = ReturnType<typeof searchOrder>;
+type CursorPosition = Record<SearchOrder[number]["key"], number | string>;
+
+const decodeAddressCursor = (
+	cursor: string,
+	order: SearchOrder,
+): CursorPosition => {
+	const decoded = decodeToken(cursor);
+	const position = {} as Record<string, number | string>;
+	for (const { key } of order) {
+		const value = decoded[key];
+		if (typeof value !== "number" && typeof value !== "string") {
+			throw new BadRequestError("Invalid continuationToken");
+		}
+		position[key] = value;
+	}
+	return position as CursorPosition;
+};
+
+/**
+ * Resume after a position in that order: strictly past the first key, or equal
+ * on it and strictly past the rest.
+ */
+const after = (order: SearchOrder, position: CursorPosition): SQL => {
+	const step = (index: number): SQL => {
+		const { key, expr, direction } = order[index];
+		const value = position[key];
+		const past =
+			direction === "desc" ? sql`${expr} < ${value}` : sql`${expr} > ${value}`;
+		if (index === order.length - 1) return past;
+		return sql`(${past} or (${expr} = ${value} and ${step(index + 1)}))`;
+	};
+	return step(0);
 };
 
 export function rowToAddress(
@@ -115,6 +180,10 @@ export class AddressRepo implements IAddressRepository {
 		return rowToAddress(row);
 	}
 
+	/**
+	 * Message sync sends `""` for a bare address, so a sighting carrying no
+	 * display name must leave the stored one alone rather than erase it.
+	 */
 	async upsertAddress(input: CreateAddressInput): Promise<AddressItem> {
 		const now = Date.now();
 		const [row] = await this.db
@@ -139,10 +208,13 @@ export class AddressRepo implements IAddressRepository {
 			})
 			.onConflictDoUpdate({
 				target: addressTable.addressId,
-				set: {
-					displayName: input.displayName ?? sql`${addressTable.displayName}`,
-					updatedAt: now,
-				},
+				set: input.displayName
+					? {
+							displayName: input.displayName,
+							normalizedCompound: input.normalizedCompound,
+							updatedAt: now,
+						}
+					: { updatedAt: now },
 			})
 			.returning();
 		return rowToAddress(row);
@@ -192,11 +264,11 @@ export class AddressRepo implements IAddressRepository {
 		input: UpdateAddressInput,
 	): Promise<AddressItem> {
 		const now = Date.now();
-		const updates: Partial<typeof addressTable.$inferInsert> = {
-			updatedAt: now,
-		};
-		if (input.displayName !== undefined)
+		const updates: AddressUpdate = { updatedAt: now };
+		if (input.displayName !== undefined) {
 			updates.displayName = input.displayName;
+			updates.normalizedCompound = compoundOfSql(input.displayName);
+		}
 		if (input.flags !== undefined) updates.flags = input.flags as never;
 		if (input.inboundCount !== undefined)
 			updates.inboundCount = input.inboundCount;
@@ -324,13 +396,14 @@ export class AddressRepo implements IAddressRepository {
 		accountConfigId: string,
 		addressId: string,
 		now: number,
-		_isBulk?: boolean,
+		isBulk?: boolean,
 	): Promise<void> {
 		const current = await this.getAddress(accountConfigId, addressId);
 		const post = {
 			...current,
 			inboundCount: (current.inboundCount ?? 0) + 1,
 			lastInboundAt: now,
+			isBulk: isBulk ?? false,
 		};
 		if (shouldPromoteWellknown(post, now)) {
 			const nextFlags: AddressFlags = {
@@ -484,48 +557,46 @@ export class AddressRepo implements IAddressRepository {
 		limit?: number;
 	}): Promise<ResultList<AddressItem>> {
 		const { accountConfigId, search, cursor, limit = 100 } = input;
-		const decoded = cursor ? decodeToken(cursor) : undefined;
-		const after = decoded
-			? {
-					normalizedCompound: decoded.normalizedCompound as string,
-					addressId: decoded.addressId as string,
-				}
-			: undefined;
+		const order = searchOrder(search);
+		const position = cursor ? decodeAddressCursor(cursor, order) : undefined;
 
 		const rows = await this.db
-			.select()
+			.select({
+				...getTableColumns(addressTable),
+				rank: order[0].expr,
+				preference: order[1].expr,
+				correspondence: order[2].expr,
+				recency: order[3].expr,
+			})
 			.from(addressTable)
 			.where(
 				and(
 					eq(addressTable.accountConfigId, accountConfigId),
-					search ? addressSearchPredicate(search) : undefined,
-					after
-						? or(
-								gt(addressTable.normalizedCompound, after.normalizedCompound),
-								and(
-									eq(addressTable.normalizedCompound, after.normalizedCompound),
-									gt(addressTable.addressId, after.addressId),
-								),
-							)
-						: undefined,
+					search ? addressSearchMatch(search) : undefined,
+					position ? after(order, position) : undefined,
 				),
 			)
 			.orderBy(
-				asc(addressTable.normalizedCompound),
-				asc(addressTable.addressId),
+				...order.map(({ expr, direction }) =>
+					direction === "desc" ? desc(expr) : asc(expr),
+				),
 			)
 			.limit(limit + 1);
 
 		const hasMore = rows.length > limit;
-		const items = rows.slice(0, limit).map(rowToAddress);
-		const lastItem = items[items.length - 1];
+		const page = rows.slice(0, limit);
+		const lastRow = page[page.length - 1];
 		return resultList(
-			items,
+			page.map(rowToAddress),
 			limit,
-			hasMore && lastItem
+			hasMore && lastRow
 				? {
-						normalizedCompound: lastItem.normalizedCompound,
-						addressId: lastItem.addressId,
+						rank: lastRow.rank,
+						preference: lastRow.preference,
+						correspondence: lastRow.correspondence,
+						recency: lastRow.recency,
+						normalizedCompound: lastRow.normalizedCompound,
+						addressId: lastRow.addressId,
 					}
 				: undefined,
 		);

package/src/repos/i4-sender-signer-standing.test.ts

@@ -0,0 +1,188 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { eq } from "drizzle-orm";
+import { NotFoundError } from "../error.js";
+import { senderSignerStandingTable } from "../schema.js";
+import { createTestDb, randomId, type TestDb } from "../test-db.js";
+import { SenderSignerStandingRepo } from "./i4-sender-signer-standing.js";
+
+describe("SenderSignerStandingRepo", () => {
+	let db: TestDb;
+	let close: () => Promise<void>;
+	let repo: SenderSignerStandingRepo;
+
+	const rowsFor = async (accountConfigId: string) =>
+		db
+			.select()
+			.from(senderSignerStandingTable)
+			.where(eq(senderSignerStandingTable.accountConfigId, accountConfigId));
+
+	before(async () => {
+		({ db, close } = await createTestDb());
+		repo = new SenderSignerStandingRepo(db as never);
+	});
+
+	after(async () => {
+		await close();
+	});
+
+	test("observing a new key inserts one row at a count of one", async () => {
+		const accountConfigId = randomId();
+		const observedAt = 1_700_000_000_000;
+
+		const standing = await repo.observe({
+			accountConfigId,
+			senderKey: "vip.example",
+			signerDomain: "esp.example",
+			observedAt,
+		});
+
+		assert.equal(standing.messageCount, 1);
+		assert.equal(standing.firstSeenAt, observedAt);
+		assert.equal(standing.lastSeenAt, observedAt);
+		assert.equal(standing.userAffirmedAt, 0);
+		assert.equal((await rowsFor(accountConfigId)).length, 1);
+	});
+
+	test("observing the same key again increments the count in place rather than inserting a second row", async () => {
+		const accountConfigId = randomId();
+		const key = {
+			accountConfigId,
+			senderKey: "vip.example",
+			signerDomain: "esp.example",
+		};
+
+		await repo.observe({ ...key, observedAt: 1_700_000_000_000 });
+		await repo.observe({ ...key, observedAt: 1_700_000_060_000 });
+		const third = await repo.observe({
+			...key,
+			observedAt: 1_700_000_120_000,
+		});
+
+		assert.equal(third.messageCount, 3);
+		const rows = await rowsFor(accountConfigId);
+		assert.equal(rows.length, 1);
+		assert.equal(rows[0]?.messageCount, 3);
+	});
+
+	// The failure this guards is silent: naming first_seen_at in the conflict
+	// `set` makes every message reset the key's age, so standing reads as
+	// brand-new forever and nothing downstream can tell.
+	test("a repeat leaves firstSeenAt at the first observation while lastSeenAt follows the latest", async () => {
+		const accountConfigId = randomId();
+		const key = {
+			accountConfigId,
+			senderKey: "list.example",
+			signerDomain: "unverified",
+		};
+		const first = 1_600_000_000_000;
+
+		await repo.observe({ ...key, observedAt: first });
+		await repo.observe({ ...key, observedAt: first + 3_600_000 });
+		const latest = await repo.observe({
+			...key,
+			observedAt: first + 7_200_000,
+		});
+
+		assert.equal(latest.firstSeenAt, first);
+		assert.equal(latest.lastSeenAt, first + 7_200_000);
+
+		const [row] = await rowsFor(accountConfigId);
+		assert.equal(row?.firstSeenAt, first);
+		assert.equal(row?.lastSeenAt, first + 7_200_000);
+	});
+
+	test("an out-of-order observation still counts, and never rewrites firstSeenAt", async () => {
+		const accountConfigId = randomId();
+		const key = {
+			accountConfigId,
+			senderKey: "delayed.example",
+			signerDomain: "esp.example",
+		};
+		const first = 1_650_000_000_000;
+
+		await repo.observe({ ...key, observedAt: first });
+		const older = await repo.observe({
+			...key,
+			observedAt: first - 86_400_000,
+		});
+
+		assert.equal(older.messageCount, 2);
+		assert.equal(older.firstSeenAt, first);
+	});
+
+	test("the same sender under two signer domains keeps two independent rows", async () => {
+		const accountConfigId = randomId();
+		const observedAt = 1_700_000_000_000;
+
+		await repo.observe({
+			accountConfigId,
+			senderKey: "shop.example",
+			signerDomain: "esp-one.example",
+			observedAt,
+		});
+		await repo.observe({
+			accountConfigId,
+			senderKey: "shop.example",
+			signerDomain: "esp-one.example",
+			observedAt,
+		});
+		const other = await repo.observe({
+			accountConfigId,
+			senderKey: "shop.example",
+			signerDomain: "esp-two.example",
+			observedAt,
+		});
+
+		assert.equal(other.messageCount, 1);
+		assert.equal((await rowsFor(accountConfigId)).length, 2);
+	});
+
+	test("standing never crosses accounts", async () => {
+		const mine = randomId();
+		const theirs = randomId();
+		const key = {
+			senderKey: "shared.example",
+			signerDomain: "esp.example",
+			observedAt: 1_700_000_000_000,
+		};
+
+		await repo.observe({ accountConfigId: mine, ...key });
+		await repo.observe({ accountConfigId: mine, ...key });
+		const foreign = await repo.observe({ accountConfigId: theirs, ...key });
+
+		assert.equal(foreign.messageCount, 1);
+		assert.equal(
+			(await repo.get(mine, key.senderKey, key.signerDomain)).messageCount,
+			2,
+		);
+	});
+
+	test("get raises NotFoundError for a key that was never observed", async () => {
+		await assert.rejects(
+			repo.get(randomId(), "stranger.example", "esp.example"),
+			(error) => error instanceof NotFoundError,
+		);
+	});
+
+	test("get reads back the row the last observation returned", async () => {
+		const accountConfigId = randomId();
+		const key = {
+			accountConfigId,
+			senderKey: "readback.example",
+			signerDomain: "esp.example",
+		};
+
+		const written = await repo.observe({
+			...key,
+			observedAt: 1_700_000_000_000,
+		});
+		const read = await repo.get(
+			accountConfigId,
+			key.senderKey,
+			key.signerDomain,
+		);
+
+		assert.deepEqual(read, written);
+	});
+});

package/src/repos/i4-sender-signer-standing.ts

@@ -0,0 +1,101 @@
+import type {
+	ISenderSignerStandingRepository,
+	ObserveSenderSignerStandingInput,
+	SenderSignerStandingItem,
+} from "@remit/data-ports";
+import { and, eq, sql } from "drizzle-orm";
+import type { Db } from "../db.js";
+import { NotFoundError } from "../error.js";
+import { senderSignerStandingTable } from "../schema.js";
+
+type DB = Db<Record<string, unknown>>;
+
+function rowToStanding(
+	row: typeof senderSignerStandingTable.$inferSelect,
+): SenderSignerStandingItem {
+	return {
+		accountConfigId: row.accountConfigId,
+		senderKey: row.senderKey,
+		signerDomain: row.signerDomain,
+		messageCount: row.messageCount,
+		firstSeenAt: row.firstSeenAt,
+		lastSeenAt: row.lastSeenAt,
+		userAffirmedAt: row.userAffirmedAt,
+		createdAt: row.createdAt,
+		updatedAt: row.updatedAt,
+	};
+}
+
+export class SenderSignerStandingRepo
+	implements ISenderSignerStandingRepository
+{
+	constructor(private db: DB) {}
+
+	async observe(
+		input: ObserveSenderSignerStandingInput,
+	): Promise<SenderSignerStandingItem> {
+		const now = Date.now();
+		// `first_seen_at` is deliberately absent from the conflict `set`.
+		// onConflictDoUpdate writes only the columns it names, so naming it here
+		// would let every message reset the key's age to its own arrival and the
+		// standing this row exists to record would never be older than the last
+		// message. The mirror-image mistake — a conflict path that must reset a
+		// timestamp and would silently inherit the old one by omitting it — is at
+		// i4-message-flag-push.ts:70.
+		const [row] = await this.db
+			.insert(senderSignerStandingTable)
+			.values({
+				accountConfigId: input.accountConfigId,
+				senderKey: input.senderKey,
+				signerDomain: input.signerDomain,
+				messageCount: 1,
+				firstSeenAt: input.observedAt,
+				lastSeenAt: input.observedAt,
+				userAffirmedAt: 0,
+				createdAt: now,
+				updatedAt: now,
+			})
+			.onConflictDoUpdate({
+				target: [
+					senderSignerStandingTable.accountConfigId,
+					senderSignerStandingTable.senderKey,
+					senderSignerStandingTable.signerDomain,
+				],
+				set: {
+					messageCount: sql`${senderSignerStandingTable.messageCount} + 1`,
+					lastSeenAt: input.observedAt,
+					updatedAt: now,
+				},
+			})
+			.returning();
+		if (!row) {
+			throw new Error(
+				`Failed to upsert SenderSignerStanding: ${input.accountConfigId}/${input.senderKey}/${input.signerDomain}`,
+			);
+		}
+		return rowToStanding(row);
+	}
+
+	async get(
+		accountConfigId: string,
+		senderKey: string,
+		signerDomain: string,
+	): Promise<SenderSignerStandingItem> {
+		const [row] = await this.db
+			.select()
+			.from(senderSignerStandingTable)
+			.where(
+				and(
+					eq(senderSignerStandingTable.accountConfigId, accountConfigId),
+					eq(senderSignerStandingTable.senderKey, senderKey),
+					eq(senderSignerStandingTable.signerDomain, signerDomain),
+				),
+			);
+		if (!row) {
+			throw new NotFoundError(
+				`SenderSignerStanding not found: ${senderKey}/${signerDomain}`,
+			);
+		}
+		return rowToStanding(row);
+	}
+}

package/src/repos/message.ts

@@ -59,6 +59,7 @@ function toMessageItem(row: typeof messageTable.$inferSelect): MessageItem {
 		status: row.status,
 		syncStatus: row.syncStatus,
 		category: row.category,
+		authenticityVerdict: row.authenticityVerdict,
 		hasListUnsubscribe: row.hasListUnsubscribe,
 		movedByRemit: row.movedByRemit,
 		createdAt: row.createdAt,
@@ -184,6 +185,8 @@ export class DrizzleMessageRepository implements IMessageRepository {
 			status: input.status ?? ("active" as const),
 			syncStatus: input.syncStatus ?? ("pending" as const),
 			category: input.category ?? ("uncategorized" as const),
+			authenticityVerdict:
+				input.authenticityVerdict ?? ("NotEvaluated" as const),
 			hasListUnsubscribe: input.hasListUnsubscribe ?? false,
 			movedByRemit: input.movedByRemit ?? false,
 			messageIdHeader: input.messageIdHeader ?? null,
@@ -365,6 +368,9 @@ export class DrizzleMessageRepository implements IMessageRepository {
 				? { syncStatus: input.syncStatus }
 				: {}),
 			...(input.category !== undefined ? { category: input.category } : {}),
+			...(input.authenticityVerdict !== undefined
+				? { authenticityVerdict: input.authenticityVerdict }
+				: {}),
 			...(input.hasListUnsubscribe !== undefined
 				? { hasListUnsubscribe: input.hasListUnsubscribe }
 				: {}),

package/src/repos/sender-signer-standing.conformance.sqlite.test.ts

@@ -0,0 +1,23 @@
+import { senderSignerStandingRepositoryConformance } from "@remit/data-ports/conformance";
+import { NotFoundError } from "../error.js";
+import { randomId } from "../id.js";
+import { senderSignerStandingTable } from "../schema.js";
+import { createSqliteTestDb } from "../test-db-sqlite.js";
+import { SenderSignerStandingRepo } from "./i4-sender-signer-standing.js";
+
+let close: (() => Promise<void>) | undefined;
+
+senderSignerStandingRepositoryConformance({
+	async createRepository() {
+		const { db, close: closeDb } = await createSqliteTestDb({
+			senderSignerStandings: senderSignerStandingTable,
+		});
+		close = closeDb;
+		return new SenderSignerStandingRepo(db as never);
+	},
+	teardown: async () => {
+		await close?.();
+	},
+	makeId: () => randomId(),
+	isNotFoundError: (error) => error instanceof NotFoundError,
+});

package/src/schema.ts

@@ -14,6 +14,7 @@ export const labelTable = entities.labels;
 export const mailboxAttributeEntryTable = entities.mailboxAttributeEntries;
 export const mailboxFlagTable = entities.mailboxFlags;
 export const messageLabelTable = entities.messageLabels;
+export const senderSignerStandingTable = entities.senderSignerStandings;
 export * from "./schema/i4-account-config.js";
 export * from "./schema/i4-account-export-request.js";
 export * from "./schema/i4-account-setting.js";