@remit/data-ports 0.0.52 → 0.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/conformance/calendar-collection.ts

@@ -59,6 +59,29 @@ export function calendarCollectionRepositoryConformance(
 			assert.equal(all.length, 1);
 		});
 
+		test("createExclusive refuses a segment the account already uses", async () => {
+			const accountConfigId = harness.makeId();
+
+			const first = await repo.createExclusive({
+				accountConfigId,
+				urlSegment: "work",
+				displayName: "Work",
+			});
+			const second = await repo.createExclusive({
+				accountConfigId,
+				urlSegment: "work",
+				displayName: "Work again",
+			});
+
+			assert.ok(first);
+			assert.equal(second, null);
+			assert.equal(
+				(await repo.get(accountConfigId, first.calendarId)).displayName,
+				"Work",
+				"the loser never overwrote the calendar the winner made",
+			);
+		});
+
 		test("get throws a not-found error for a missing collection", async () => {
 			await assert.rejects(
 				repo.get(harness.makeId(), harness.makeId()),

package/src/conformance/calendar-event-index.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { after, before, describe, test } from "node:test";
+import { CalendarEventStatus, CalendarTransparency } from "@remit/domain-enums";
 import type { ICalendarEventIndexRepository } from "../interfaces/calendar-event-index.js";
 import type { CalendarOccurrenceInput } from "../types.js";
 import type { RepositoryConformanceHarness } from "./harness.js";
@@ -8,11 +9,16 @@ const occurrence = (
 	recurrenceId: string,
 	startAt: string,
 	endAt: string,
+	overrides: Partial<CalendarOccurrenceInput> = {},
 ): CalendarOccurrenceInput => ({
 	recurrenceId,
 	startAt,
 	endAt,
 	allDay: false,
+	summary: "Stand-up",
+	status: CalendarEventStatus.Confirmed,
+	transparency: CalendarTransparency.Opaque,
+	...overrides,
 });
 
 export function calendarEventIndexRepositoryConformance(
@@ -139,6 +145,46 @@ export function calendarEventIndexRepositoryConformance(
 			assert.equal(rows.length, 1);
 		});
 
+		test("an occurrence keeps its own summary, status and transparency", async () => {
+			const calendarId = harness.makeId();
+			const calendarObjectId = harness.makeId();
+
+			await repo.replaceForObject(calendarId, calendarObjectId, [
+				occurrence(
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T07:00:00Z",
+					"2026-08-26T08:00:00Z",
+				),
+				occurrence(
+					"2026-09-02T07:00:00Z",
+					"2026-09-02T07:00:00Z",
+					"2026-09-02T08:00:00Z",
+					{
+						summary: "Stand-up (moved)",
+						status: CalendarEventStatus.Cancelled,
+						transparency: CalendarTransparency.Transparent,
+					},
+				),
+			]);
+
+			const rows = await repo.listForObject(calendarId, calendarObjectId);
+			assert.deepEqual(
+				rows.map((row) => [row.summary, row.status, row.transparency]),
+				[
+					[
+						"Stand-up",
+						CalendarEventStatus.Confirmed,
+						CalendarTransparency.Opaque,
+					],
+					[
+						"Stand-up (moved)",
+						CalendarEventStatus.Cancelled,
+						CalendarTransparency.Transparent,
+					],
+				],
+			);
+		});
+
 		test("deleteForObject removes every occurrence of one resource", async () => {
 			const calendarId = harness.makeId();
 			const calendarObjectId = harness.makeId();

package/src/conformance/calendar-object.ts

@@ -107,6 +107,49 @@ export function calendarObjectRepositoryConformance(
 			);
 		});
 
+		test("find answers with null where get throws", async () => {
+			const calendarId = harness.makeId();
+			const object = await repo.put(objectInput(calendarId));
+
+			assert.equal(
+				(await repo.find(calendarId, object.calendarObjectId))?.icalData,
+				ICAL_DATA,
+			);
+			assert.equal(await repo.find(calendarId, harness.makeId()), null);
+			assert.equal(
+				await repo.find(harness.makeId(), object.calendarObjectId),
+				null,
+				"a resource is only found through the collection that holds it",
+			);
+		});
+
+		test("listIncompleteExpansions returns only the series whose index stops short", async () => {
+			const calendarId = harness.makeId();
+			await repo.put(objectInput(calendarId, { resourceName: "complete.ics" }));
+			const incomplete = await repo.put(
+				objectInput(calendarId, {
+					resourceName: "incomplete.ics",
+					expandedThrough: "2026-01-01T00:00:00Z",
+				}),
+			);
+
+			assert.deepEqual(
+				(
+					await repo.listIncompleteExpansions(
+						calendarId,
+						"2026-06-01T00:00:00Z",
+					)
+				).map((object) => object.calendarObjectId),
+				[incomplete.calendarObjectId],
+				"a resource with no expandedThrough is complete and never appears",
+			);
+			assert.deepEqual(
+				await repo.listIncompleteExpansions(calendarId, "2025-06-01T00:00:00Z"),
+				[],
+				"and one whose index already reaches the window does not either",
+			);
+		});
+
 		test("findByResourceName returns null for a name the collection does not hold", async () => {
 			assert.equal(
 				await repo.findByResourceName(harness.makeId(), "absent.ics"),

package/src/conformance/calendar-suggestion.ts

@@ -0,0 +1,293 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import {
+	CalendarInviteMethod,
+	CalendarSuggestionSource,
+	CalendarSuggestionState,
+	ZoneCertainty,
+} from "@remit/domain-enums";
+import { deriveCalendarSuggestionId } from "../id.js";
+import type { ICalendarSuggestionRepository } from "../interfaces/calendar-suggestion.js";
+import type { PutCalendarSuggestionInput } from "../types.js";
+import type { RepositoryConformanceHarness } from "./harness.js";
+
+const suggestion = (
+	accountConfigId: string,
+	messageId: string,
+	bodyPartId: string,
+	icalUid: string,
+	overrides: Partial<PutCalendarSuggestionInput> = {},
+): PutCalendarSuggestionInput => ({
+	accountConfigId,
+	messageId,
+	bodyPartId,
+	icalUid,
+	sequence: 0,
+	method: CalendarInviteMethod.Request,
+	source: CalendarSuggestionSource.IcalendarPart,
+	summary: "Design review",
+	dtStart: "2026-09-01T10:00:00+02:00",
+	dtEnd: "2026-09-01T11:00:00+02:00",
+	allDay: false,
+	location: "",
+	organizer: "organizer@example.test",
+	zoneCertainty: ZoneCertainty.Explicit,
+	icalData: "BEGIN:VCALENDAR\r\nEND:VCALENDAR\r\n",
+	...overrides,
+});
+
+export function calendarSuggestionRepositoryConformance(
+	harness: RepositoryConformanceHarness<ICalendarSuggestionRepository>,
+): void {
+	describe("ICalendarSuggestionRepository conformance", () => {
+		let repo: ICalendarSuggestionRepository;
+
+		before(async () => {
+			repo = await harness.createRepository();
+		});
+
+		after(() => harness.teardown());
+
+		test("put writes a Pending suggestion under its derived id", async () => {
+			const accountConfigId = harness.makeId();
+			const messageId = harness.makeId();
+			const bodyPartId = harness.makeId();
+
+			const written = await repo.put(
+				suggestion(accountConfigId, messageId, bodyPartId, "uid-1"),
+			);
+
+			assert.equal(
+				written.suggestionId,
+				deriveCalendarSuggestionId(messageId, bodyPartId, "uid-1"),
+			);
+			assert.equal(written.state, CalendarSuggestionState.Pending);
+			assert.equal(written.acceptedCalendarObjectId, "");
+		});
+
+		test("put re-reading the same message converges on one row", async () => {
+			const accountConfigId = harness.makeId();
+			const messageId = harness.makeId();
+			const bodyPartId = harness.makeId();
+
+			await repo.put(
+				suggestion(accountConfigId, messageId, bodyPartId, "uid-1"),
+			);
+			await repo.put(
+				suggestion(accountConfigId, messageId, bodyPartId, "uid-1", {
+					summary: "Design review, moved",
+				}),
+			);
+
+			const rows = await repo.listByMessage(accountConfigId, messageId);
+			assert.equal(rows.length, 1);
+			assert.equal(rows[0]?.summary, "Design review, moved");
+		});
+
+		test("put leaves an answered suggestion answered", async () => {
+			// A re-sync must never walk a decision back to Pending: the user
+			// already added this event to a calendar, and a producer write is not
+			// allowed to un-decide that.
+			const accountConfigId = harness.makeId();
+			const messageId = harness.makeId();
+			const bodyPartId = harness.makeId();
+
+			const written = await repo.put(
+				suggestion(accountConfigId, messageId, bodyPartId, "uid-1"),
+			);
+			await repo.settle(accountConfigId, written.suggestionId, {
+				state: CalendarSuggestionState.Accepted,
+				acceptedCalendarObjectId: "cal-object-1",
+			});
+			await repo.put(
+				suggestion(accountConfigId, messageId, bodyPartId, "uid-1"),
+			);
+
+			const reread = await repo.get(accountConfigId, written.suggestionId);
+			assert.equal(reread.state, CalendarSuggestionState.Accepted);
+			assert.equal(reread.acceptedCalendarObjectId, "cal-object-1");
+		});
+
+		test("get rejects a suggestion that is not there", async () => {
+			const accountConfigId = harness.makeId();
+			await assert.rejects(
+				() => repo.get(accountConfigId, harness.makeId()),
+				(error: unknown) => harness.isNotFoundError(error),
+			);
+		});
+
+		test("get scopes to the account config", async () => {
+			const accountConfigId = harness.makeId();
+			const written = await repo.put(
+				suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"),
+			);
+
+			await assert.rejects(
+				() => repo.get(harness.makeId(), written.suggestionId),
+				(error: unknown) => harness.isNotFoundError(error),
+			);
+		});
+
+		test("listByMessage returns every suggestion one message produced", async () => {
+			const accountConfigId = harness.makeId();
+			const messageId = harness.makeId();
+			const other = harness.makeId();
+
+			await repo.put(
+				suggestion(accountConfigId, messageId, harness.makeId(), "uid-a"),
+			);
+			await repo.put(
+				suggestion(accountConfigId, messageId, harness.makeId(), "uid-b"),
+			);
+			await repo.put(
+				suggestion(accountConfigId, other, harness.makeId(), "uid-c"),
+			);
+
+			const rows = await repo.listByMessage(accountConfigId, messageId);
+			assert.deepEqual(rows.map((row) => row.icalUid).sort(), [
+				"uid-a",
+				"uid-b",
+			]);
+		});
+
+		test("listByState returns only the state asked for", async () => {
+			const accountConfigId = harness.makeId();
+			const pending = await repo.put(
+				suggestion(accountConfigId, harness.makeId(), harness.makeId(), "p"),
+			);
+			const declined = await repo.put(
+				suggestion(accountConfigId, harness.makeId(), harness.makeId(), "d"),
+			);
+			await repo.settle(accountConfigId, declined.suggestionId, {
+				state: CalendarSuggestionState.Declined,
+				acceptedCalendarObjectId: "",
+			});
+
+			const page = await repo.listByState(
+				accountConfigId,
+				CalendarSuggestionState.Pending,
+			);
+			assert.deepEqual(
+				page.items.map((row) => row.suggestionId),
+				[pending.suggestionId],
+			);
+		});
+
+		test("listByState scopes to the account config", async () => {
+			const accountConfigId = harness.makeId();
+			await repo.put(
+				suggestion(harness.makeId(), harness.makeId(), harness.makeId(), "x"),
+			);
+
+			const page = await repo.listByState(
+				accountConfigId,
+				CalendarSuggestionState.Pending,
+			);
+			assert.equal(page.items.length, 0);
+		});
+
+		test("listByState pages, and the token resumes where the page stopped", async () => {
+			const accountConfigId = harness.makeId();
+			for (const uid of ["a", "b", "c"]) {
+				await repo.put(
+					suggestion(accountConfigId, harness.makeId(), harness.makeId(), uid),
+				);
+			}
+
+			const first = await repo.listByState(
+				accountConfigId,
+				CalendarSuggestionState.Pending,
+				{ limit: 2 },
+			);
+			assert.equal(first.items.length, 2);
+			assert.ok(first.continuationToken);
+
+			const second = await repo.listByState(
+				accountConfigId,
+				CalendarSuggestionState.Pending,
+				{ limit: 2, continuationToken: first.continuationToken },
+			);
+			const seen = [...first.items, ...second.items].map(
+				(row) => row.suggestionId,
+			);
+			assert.equal(new Set(seen).size, 3);
+		});
+
+		test("settle records the accepted resource", async () => {
+			const accountConfigId = harness.makeId();
+			const written = await repo.put(
+				suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"),
+			);
+
+			const settled = await repo.settle(accountConfigId, written.suggestionId, {
+				state: CalendarSuggestionState.Accepted,
+				acceptedCalendarObjectId: "cal-object-9",
+			});
+
+			assert.equal(settled.state, CalendarSuggestionState.Accepted);
+			assert.equal(settled.acceptedCalendarObjectId, "cal-object-9");
+		});
+
+		test("supersedeIfPending retires a card still waiting on the user", async () => {
+			const accountConfigId = harness.makeId();
+			const written = await repo.put(
+				suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"),
+			);
+
+			const retired = await repo.supersedeIfPending(
+				accountConfigId,
+				written.suggestionId,
+			);
+
+			assert.equal(retired?.state, CalendarSuggestionState.Superseded);
+		});
+
+		test("supersedeIfPending leaves an answered card alone and says so", async () => {
+			// The producer reads the pending set and writes to it in two steps. A
+			// person accepting in between must keep their acceptance — and the
+			// link to the event it put in their calendar.
+			const accountConfigId = harness.makeId();
+			const written = await repo.put(
+				suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"),
+			);
+			await repo.settle(accountConfigId, written.suggestionId, {
+				state: CalendarSuggestionState.Accepted,
+				acceptedCalendarObjectId: "cal-object-7",
+			});
+
+			const retired = await repo.supersedeIfPending(
+				accountConfigId,
+				written.suggestionId,
+			);
+
+			assert.equal(retired, null);
+			const reread = await repo.get(accountConfigId, written.suggestionId);
+			assert.equal(reread.state, CalendarSuggestionState.Accepted);
+			assert.equal(reread.acceptedCalendarObjectId, "cal-object-7");
+		});
+
+		test("supersedeIfPending scopes to the account config", async () => {
+			const accountConfigId = harness.makeId();
+			const written = await repo.put(
+				suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"),
+			);
+
+			assert.equal(
+				await repo.supersedeIfPending(harness.makeId(), written.suggestionId),
+				null,
+			);
+		});
+
+		test("settle rejects a suggestion that is not there", async () => {
+			const accountConfigId = harness.makeId();
+			await assert.rejects(
+				() =>
+					repo.settle(accountConfigId, harness.makeId(), {
+						state: CalendarSuggestionState.Declined,
+						acceptedCalendarObjectId: "",
+					}),
+				(error: unknown) => harness.isNotFoundError(error),
+			);
+		});
+	});
+}

package/src/conformance/index.ts

@@ -1,6 +1,7 @@
 export { calendarCollectionRepositoryConformance } from "./calendar-collection.js";
 export { calendarEventIndexRepositoryConformance } from "./calendar-event-index.js";
 export { calendarObjectRepositoryConformance } from "./calendar-object.js";
+export { calendarSuggestionRepositoryConformance } from "./calendar-suggestion.js";
 export type { RepositoryConformanceHarness } from "./harness.js";
 export { labelRepositoryConformance } from "./label.js";
 export { senderSignerStandingRepositoryConformance } from "./sender-signer-standing.js";

package/src/id.test.ts

@@ -6,6 +6,7 @@ import {
 	deriveBodyPartId,
 	deriveCalendarId,
 	deriveCalendarObjectId,
+	deriveCalendarSuggestionId,
 	deriveCopyMessageId,
 	deriveEnvelopeId,
 	deriveMessageId,
@@ -161,6 +162,43 @@ describe("deriveCalendarObjectId", () => {
 	});
 });
 
+describe("deriveCalendarSuggestionId", () => {
+	const MESSAGE = "msg-1";
+	const PART = "part-1";
+	const UID = "invite@example.com";
+
+	it("converges a re-read of the same message on one row", () => {
+		assert.equal(
+			deriveCalendarSuggestionId(MESSAGE, PART, UID),
+			deriveCalendarSuggestionId(MESSAGE, PART, UID),
+		);
+	});
+
+	it("keeps two invitations in one message apart", () => {
+		assert.notEqual(
+			deriveCalendarSuggestionId(MESSAGE, PART, UID),
+			deriveCalendarSuggestionId(MESSAGE, "part-2", UID),
+		);
+	});
+
+	it("gives a revision its own row, so the superseded card survives", () => {
+		// A later message carrying the same UID is a second suggestion, never an
+		// overwrite of the first: the older message keeps its card and the user
+		// can see which revision replaced which.
+		assert.notEqual(
+			deriveCalendarSuggestionId(MESSAGE, PART, UID),
+			deriveCalendarSuggestionId("msg-2", PART, UID),
+		);
+	});
+
+	it("separates two events sent as one part", () => {
+		assert.notEqual(
+			deriveCalendarSuggestionId(MESSAGE, PART, UID),
+			deriveCalendarSuggestionId(MESSAGE, PART, "other@example.com"),
+		);
+	});
+});
+
 describe("derived ids are stored primary keys: a changed value orphans every row already written and needs a migration, never a new expectation here", () => {
 	const ACCOUNT = "account-golden";
 	const MESSAGE = "message-golden";
@@ -268,6 +306,17 @@ describe("derived ids are stored primary keys: a changed value orphans every row
 		);
 	});
 
+	it("deriveCalendarSuggestionId pins the calendar_suggestion primary key", () => {
+		assert.equal(
+			deriveCalendarSuggestionId(
+				MESSAGE,
+				"bodypart-golden",
+				"golden-invite@example.com",
+			),
+			"1pesdr3fl02uyoz5k1qrfik3e",
+		);
+	});
+
 	it("quarantineMessageIdHash pins the stored Message-ID hash that correlates reports", () => {
 		assert.equal(
 			quarantineMessageIdHash("<golden@example.com>"),

package/src/id.ts

@@ -64,6 +64,34 @@ export const deriveCalendarObjectId = (
 ): string =>
 	base36uuidv5(`calendarobject:${calendarId}:${resourceName}`, REMIT_NAMESPACE);
 
+/**
+ * Identity of a suggestion read out of a message (issue #1033). Derived from
+ * the message, the MIME part the bytes came from and the event's iCalendar
+ * UID, so re-reading the same message converges on the row it already wrote
+ * instead of stacking a second card on the message every pass.
+ *
+ * All three parts are needed. The message alone would merge two invitations
+ * sent in one mail; the part alone is not stable enough to key on across a
+ * re-parse; and the UID keeps two events sent as one part apart.
+ *
+ * The message is in the seed, so identity is per message, not per event: a
+ * later message carrying the same UID derives its own id, and the earlier
+ * suggestion survives beside it as `Superseded`. The user can see which
+ * revision they are being asked about, and the older message still has a card.
+ * The same holds for a plain resend — a redelivered copy is a new message and
+ * so a new card, which the SEQUENCE comparison then declines to supersede
+ * anything for.
+ */
+export const deriveCalendarSuggestionId = (
+	messageId: string,
+	bodyPartId: string,
+	icalUid: string,
+): string =>
+	base36uuidv5(
+		`calendarsuggestion:${messageId}:${bodyPartId}:${icalUid}`,
+		REMIT_NAMESPACE,
+	);
+
 export const isValidMessageId = (messageId: string | undefined): boolean => {
 	if (!messageId) return false;
 	const trimmed = messageId.trim();

package/src/index.ts

@@ -7,6 +7,10 @@ export type { IAddressRepository } from "./interfaces/address.js";
 export type { ICalendarCollectionRepository } from "./interfaces/calendar-collection.js";
 export type { ICalendarEventIndexRepository } from "./interfaces/calendar-event-index.js";
 export type { ICalendarObjectRepository } from "./interfaces/calendar-object.js";
+export type {
+	ICalendarSuggestionRepository,
+	SettleCalendarSuggestionInput,
+} from "./interfaces/calendar-suggestion.js";
 export type {
 	CalendarUnitOfWorkRepositories,
 	ICalendarUnitOfWork,
@@ -46,6 +50,11 @@ export type {
 	IUnitOfWork,
 	UnitOfWorkRepositories,
 } from "./interfaces/unit-of-work.js";
+export {
+	FILTER_NO_ACTION,
+	isSenderMuted,
+	isSenderMuteFilter,
+} from "./sender-mute.js";
 export type {
 	AccountConfigDescription,
 	AccountConfigItem,
@@ -68,6 +77,7 @@ export type {
 	CalendarEventIndexItem,
 	CalendarObjectItem,
 	CalendarOccurrenceInput,
+	CalendarSuggestionItem,
 	ConfigImportItem,
 	ConfigImportUnresolvedRefItem,
 	CreateAccountConfigInput,
@@ -113,6 +123,7 @@ export type {
 	OutboxAttachmentItem,
 	OutboxMessageItem,
 	PutCalendarObjectInput,
+	PutCalendarSuggestionInput,
 	PutMessageFlagPushInput,
 	PutMessagePlacementMoveInput,
 	QuarantineItem,

package/src/interfaces/calendar-collection.ts

@@ -12,6 +12,18 @@ export interface ICalendarCollectionRepository {
 	 * request without a prior read.
 	 */
 	create(input: CreateCalendarCollectionInput): Promise<CalendarCollectionItem>;
+	/**
+	 * Writes the collection, or answers `null` when its `urlSegment` is already
+	 * taken in this account config.
+	 *
+	 * The distinction from `create` is who asked. Provisioning wants the row
+	 * whoever got there first wrote; a person naming a calendar wants to be told
+	 * the name is taken, and handing them somebody else's calendar instead is a
+	 * silent merge of two things they meant to keep apart.
+	 */
+	createExclusive(
+		input: CreateCalendarCollectionInput,
+	): Promise<CalendarCollectionItem | null>;
 	get(
 		accountConfigId: string,
 		calendarId: string,

package/src/interfaces/calendar-object.ts

@@ -6,6 +6,16 @@ export interface ICalendarObjectRepository {
 		calendarId: string,
 		calendarObjectId: string,
 	): Promise<CalendarObjectItem>;
+	/**
+	 * The resource under an id, or `null` when the collection does not hold it.
+	 * `get` throws instead, which is right for a caller that already knows the
+	 * resource exists; a request naming one is asking whether it does, and that
+	 * is an answer rather than a fault.
+	 */
+	find(
+		calendarId: string,
+		calendarObjectId: string,
+	): Promise<CalendarObjectItem | null>;
 	delete(calendarId: string, calendarObjectId: string): Promise<void>;
 	findByResourceName(
 		calendarId: string,
@@ -21,6 +31,17 @@ export interface ICalendarObjectRepository {
 		icalUid: string,
 	): Promise<CalendarObjectItem | null>;
 	listByCalendar(calendarId: string): Promise<CalendarObjectItem[]>;
+	/**
+	 * The resources whose occurrence rows stop before `instant` — the series a
+	 * range read has to expand for itself because the index does not reach that
+	 * far. Narrow by construction: a resource that fits inside the expansion
+	 * horizon carries no `expandedThrough` and never appears here, so a view of
+	 * an ordinary calendar reads no iCalendar text at all.
+	 */
+	listIncompleteExpansions(
+		calendarId: string,
+		instant: string,
+	): Promise<CalendarObjectItem[]>;
 	/**
 	 * Everything written to the collection after `syncSequence`, in change
 	 * order — the read behind a WebDAV-Sync report. Exclusive of the token

package/src/interfaces/calendar-suggestion.ts

@@ -0,0 +1,73 @@
+import type {
+	CalendarSuggestionItem,
+	PutCalendarSuggestionInput,
+	ResultList,
+} from "../types.js";
+
+/**
+ * The two fields that record what a person decided about a suggestion. They
+ * move together and only through {@link ICalendarSuggestionRepository.settle},
+ * so no producer write can walk an answered card back to `Pending`, and no
+ * state can name a calendar object that was never written.
+ *
+ * `acceptedCalendarObjectId` is `""` for every outcome but `Accepted` — the
+ * named absent state, never a missing attribute.
+ */
+export interface SettleCalendarSuggestionInput {
+	state: CalendarSuggestionItem["state"];
+	acceptedCalendarObjectId: string;
+}
+
+export interface ICalendarSuggestionRepository {
+	/**
+	 * Writes the suggestion under its derived `suggestionId`. An upsert: the
+	 * producer re-reading the same message rewrites the row it already wrote.
+	 *
+	 * Never touches `state` or `acceptedCalendarObjectId` on a row that already
+	 * exists, so a re-sync of a message whose invitation the user accepted
+	 * leaves the acceptance intact. A row it creates starts `Pending`.
+	 */
+	put(input: PutCalendarSuggestionInput): Promise<CalendarSuggestionItem>;
+	get(
+		accountConfigId: string,
+		suggestionId: string,
+	): Promise<CalendarSuggestionItem>;
+	/** Every suggestion one message produced, superseded revisions included. */
+	listByMessage(
+		accountConfigId: string,
+		messageId: string,
+	): Promise<CalendarSuggestionItem[]>;
+	/**
+	 * The account's suggestions in one state, newest first. Also how the
+	 * producer finds the revision a new message supersedes: only a `Pending`
+	 * suggestion can be superseded, so the candidate set is this one.
+	 */
+	listByState(
+		accountConfigId: string,
+		state: CalendarSuggestionItem["state"],
+		options?: { limit?: number; continuationToken?: string },
+	): Promise<ResultList<CalendarSuggestionItem>>;
+	/**
+	 * Records the outcome of a person's decision. Returns the settled row.
+	 */
+	settle(
+		accountConfigId: string,
+		suggestionId: string,
+		input: SettleCalendarSuggestionInput,
+	): Promise<CalendarSuggestionItem>;
+	/**
+	 * Retires a card as `Superseded`, but only while it is still `Pending`.
+	 * Returns the retired row, or `null` when the card had already been
+	 * answered and nothing was written.
+	 *
+	 * A compare-and-set rather than a plain `settle` because the producer reads
+	 * the pending set and writes to it in two steps, and a person can accept a
+	 * card in between. An unconditional write there would overwrite their
+	 * acceptance with `Superseded` and blank `acceptedCalendarObjectId`,
+	 * severing the card from the event it put in their calendar.
+	 */
+	supersedeIfPending(
+		accountConfigId: string,
+		suggestionId: string,
+	): Promise<CalendarSuggestionItem | null>;
+}

package/src/interfaces/calendar-unit-of-work.ts

@@ -1,6 +1,7 @@
 import type { ICalendarCollectionRepository } from "./calendar-collection.js";
 import type { ICalendarEventIndexRepository } from "./calendar-event-index.js";
 import type { ICalendarObjectRepository } from "./calendar-object.js";
+import type { ICalendarSuggestionRepository } from "./calendar-suggestion.js";
 
 /**
  * The repositories one calendar write set touches, bound to a single unit of
@@ -10,6 +11,13 @@ export interface CalendarUnitOfWorkRepositories {
 	calendarCollection: ICalendarCollectionRepository;
 	calendarObject: ICalendarObjectRepository;
 	calendarEventIndex: ICalendarEventIndexRepository;
+	/**
+	 * Present so accepting a suggestion settles the card in the same unit that
+	 * writes the resource (issue #1033). The two are one fact: a card still
+	 * asking with the event already in the calendar, or a card marked accepted
+	 * with no event behind it, is a state nothing later can repair.
+	 */
+	calendarSuggestion: ICalendarSuggestionRepository;
 }
 
 /**

package/src/sender-mute.test.ts

@@ -0,0 +1,76 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isSenderMuted, isSenderMuteFilter } from "./sender-mute.js";
+import type { FilterItem } from "./types.js";
+
+const rule = (overrides: Partial<FilterItem> = {}): FilterItem =>
+	({
+		scope: "Standing",
+		literalClauses: [{ field: "From", value: "ada@example.test" }],
+		actionLabelId: "None",
+		actionMailboxId: "None",
+		...overrides,
+	}) as unknown as FilterItem;
+
+describe("isSenderMuteFilter", () => {
+	it("recognises a standing rule that names a sender and does nothing", () => {
+		assert.equal(isSenderMuteFilter(rule()), true);
+	});
+
+	it("declines a rule that applies a label", () => {
+		assert.equal(isSenderMuteFilter(rule({ actionLabelId: "label-1" })), false);
+	});
+
+	it("declines a rule that moves the message", () => {
+		assert.equal(
+			isSenderMuteFilter(rule({ actionMailboxId: "mailbox-1" })),
+			false,
+		);
+	});
+
+	it("declines a rule that matches on something other than the sender", () => {
+		assert.equal(
+			isSenderMuteFilter(
+				rule({
+					literalClauses: [{ field: "Subject", value: "invitation" }],
+				} as Partial<FilterItem>),
+			),
+			false,
+		);
+	});
+
+	it("declines a rule with no clauses, which would mute everybody", () => {
+		assert.equal(isSenderMuteFilter(rule({ literalClauses: [] })), false);
+	});
+
+	it("declines a temporary rule", () => {
+		assert.equal(isSenderMuteFilter(rule({ scope: "Temporary" })), false);
+	});
+});
+
+describe("isSenderMuted", () => {
+	it("matches an address whatever case either side was written in", () => {
+		assert.equal(isSenderMuted([rule()], "Ada@Example.TEST"), true);
+	});
+
+	it("matches the whole address, never a substring of one", () => {
+		// A rule about ada@example.test must not silence an address that merely
+		// contains it — the lookalike is exactly what a spoofer would send from.
+		assert.equal(
+			isSenderMuted([rule()], "not-ada@example.test.evil.test"),
+			false,
+		);
+	});
+
+	it("says no when nothing names the sender", () => {
+		assert.equal(isSenderMuted([rule()], "someone@example.test"), false);
+	});
+
+	it("says no for an empty sender rather than matching an empty clause", () => {
+		assert.equal(isSenderMuted([rule()], ""), false);
+	});
+
+	it("says no with no rules at all", () => {
+		assert.equal(isSenderMuted([], "ada@example.test"), false);
+	});
+});

package/src/sender-mute.ts

@@ -0,0 +1,59 @@
+import { FilterClauseField, FilterScope } from "@remit/domain-enums";
+import type { FilterItem } from "./types.js";
+
+/**
+ * The `Filter` model's sentinel for "this rule takes no such action" — the
+ * value `actionLabelId` and `actionMailboxId` hold when a filter applies no
+ * label and moves nothing (RFC 034 Decision 3.1).
+ */
+export const FILTER_NO_ACTION = "None";
+
+/**
+ * A standing rule that names senders and does nothing else.
+ *
+ * That combination has exactly one meaning. The index-time filter pipeline
+ * skips a filter with no label and no move, so such a rule changes nothing
+ * about where mail lands or how it is tagged; the only thing it can express is
+ * the user saying "not from this sender". `dismiss{muteSender:true}` writes
+ * one, and the calendar-suggestion producer reads it.
+ *
+ * Structural, never name-matching: the rule is recognised by its shape, so a
+ * rename in the settings UI cannot quietly un-mute a sender.
+ */
+export const isSenderMuteFilter = (
+	filter: Pick<
+		FilterItem,
+		"scope" | "literalClauses" | "actionLabelId" | "actionMailboxId"
+	>,
+): boolean =>
+	filter.scope === FilterScope.Standing &&
+	filter.actionLabelId === FILTER_NO_ACTION &&
+	filter.actionMailboxId === FILTER_NO_ACTION &&
+	filter.literalClauses.length > 0 &&
+	filter.literalClauses.every(
+		(clause) =>
+			clause.field === FilterClauseField.From && clause.value.trim() !== "",
+	);
+
+const fold = (value: string): string => value.trim().toLowerCase();
+
+/**
+ * Whether one of these rules mutes an address. Compared case-insensitively and
+ * whole: a mail address is one value, and a substring match would let a rule
+ * about `ada@example.com` silence `not-ada@example.com.evil.test`.
+ */
+export const isSenderMuted = (
+	filters: readonly Pick<
+		FilterItem,
+		"scope" | "literalClauses" | "actionLabelId" | "actionMailboxId"
+	>[],
+	sender: string,
+): boolean => {
+	const wanted = fold(sender);
+	if (wanted === "") return false;
+	return filters.some(
+		(filter) =>
+			isSenderMuteFilter(filter) &&
+			filter.literalClauses.some((clause) => fold(clause.value) === wanted),
+	);
+};

package/src/types.ts

@@ -9,6 +9,7 @@ import type {
 	CalendarCollectionSchema,
 	CalendarEventIndexSchema,
 	CalendarObjectSchema,
+	CalendarSuggestionSchema,
 	ConfigImportSchema,
 	ConfigImportUnresolvedRefSchema,
 	EnvelopeAddressSchema,
@@ -607,6 +608,29 @@ export type CalendarOccurrenceInput = Omit<
 	"calendarId" | "calendarObjectId" | "createdAt" | "updatedAt"
 >;
 
+export type CalendarSuggestionItem = z.infer<typeof CalendarSuggestionSchema>;
+
+/**
+ * A whole suggestion, as the producer read it out of a message. Every field is
+ * derived from the message — nothing here is client-supplied — and
+ * `suggestionId` is derived from messageId + bodyPartId + icalUid, so this is
+ * an upsert: re-reading the same message rewrites its own row rather than
+ * stacking a second card on the message.
+ *
+ * `state` and `acceptedCalendarObjectId` are excluded: a producer only ever
+ * writes a `Pending` suggestion, and the two fields that record what a person
+ * decided move exclusively through `settle`, so a re-sync can never walk an
+ * answered card back to Pending.
+ */
+export type PutCalendarSuggestionInput = Omit<
+	CalendarSuggestionItem,
+	| "suggestionId"
+	| "state"
+	| "acceptedCalendarObjectId"
+	| "createdAt"
+	| "updatedAt"
+>;
+
 export type SenderSignerStandingItem = z.infer<
 	typeof SenderSignerStandingSchema
 >;