@remit/drizzle-service 0.0.39 → 0.0.40

package/package.json

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

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

@@ -241,23 +241,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"),
 		);
 
-		const result = await repo.listByAccountConfig({
+		await repo.updateAddress(accountConfigId, created.addressId, {
+			displayName: "Özcan Bakker",
+		});
+
+		const found = await repo.listByAccountConfig({
 			accountConfigId,
-			search: "a_@x.com",
+			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",
+		);
+
+		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: "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, [
+			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"),
 		);
 
-		await repo.deleteManyAddresses(accountConfigId, [plain.addressId]);
+		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 +806,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;
@@ -484,48 +556,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,
 		);