@remit/account-worker 0.0.32 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/account-worker",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/cascade.ts

@@ -1,3 +1,4 @@
+import type { RemitClient } from "@remit/backend/client";
 import type {
 	IAccountConfigRepository,
 	IAccountExportRequestRepository,
@@ -45,6 +46,26 @@ export interface CascadeServices {
 	messageLabelService: IMessageLabelRepository;
 }
 
+export const cascadeServicesOf = (client: RemitClient): CascadeServices => ({
+	accountConfigService: client.accountConfig,
+	accountService: client.account,
+	addressService: client.address,
+	mailboxService: client.mailbox,
+	messageService: client.message,
+	messageFlagService: client.messageFlag,
+	envelopeService: client.envelope,
+	outboxMessageService: client.outboxMessage,
+	threadMessageService: client.threadMessage,
+	mailboxLockService: client.mailboxLock,
+	messagePlacementMoveService: client.placementMove,
+	messageFlagPushService: client.flagPush,
+	accountExportRequestService: client.accountExportRequest,
+	accountSettingService: client.accountSetting,
+	filterService: client.filter,
+	labelService: client.label,
+	messageLabelService: client.messageLabel,
+});
+
 export interface CascadeResult {
 	entities: CascadeEntity[];
 	messageIds: string[];

package/src/config.ts

@@ -7,7 +7,7 @@ import {
 import type { StorageService } from "@remit/storage-service";
 import { createStorageService } from "@remit/storage-service/s3";
 import { env } from "expect-env";
-import type { CascadeServices } from "./cascade.js";
+import { type CascadeServices, cascadeServicesOf } from "./cascade.js";
 import type {
 	AccountDataPurgeFinalizeEvent,
 	AccountFinalizeEvent,
@@ -49,25 +49,7 @@ let cascadeServicesPromise: Promise<CascadeServices> | null = null;
 // backend-specific wiring here.
 export const getCascadeServices = (): Promise<CascadeServices> => {
 	if (!cascadeServicesPromise) {
-		cascadeServicesPromise = getClient().then((remitClient) => ({
-			accountConfigService: remitClient.accountConfig,
-			accountService: remitClient.account,
-			addressService: remitClient.address,
-			mailboxService: remitClient.mailbox,
-			messageService: remitClient.message,
-			messageFlagService: remitClient.messageFlag,
-			envelopeService: remitClient.envelope,
-			outboxMessageService: remitClient.outboxMessage,
-			threadMessageService: remitClient.threadMessage,
-			mailboxLockService: remitClient.mailboxLock,
-			messagePlacementMoveService: remitClient.placementMove,
-			messageFlagPushService: remitClient.flagPush,
-			accountExportRequestService: remitClient.accountExportRequest,
-			accountSettingService: remitClient.accountSetting,
-			filterService: remitClient.filter,
-			labelService: remitClient.label,
-			messageLabelService: remitClient.messageLabel,
-		}));
+		cascadeServicesPromise = getClient().then(cascadeServicesOf);
 	}
 	return cascadeServicesPromise;
 };

package/src/deletion-capabilities.ts

@@ -1,58 +1,6 @@
-import type { Logger } from "@remit/logger";
-import type { CascadeEntity } from "./cascade.js";
+import type { DeletionCapabilities } from "./deletion-port.js";
 
-/**
- * The four steps of the deletion cascade that vary by deployment. Everything
- * else — enumerating the AccountConfig's rows, the FIFO purge orchestration, the
- * queue sends — is backend-neutral and lives in the handlers unchanged.
- *
- * Two composition roots build this:
- *
- * - The DynamoDB composition (AWS custody stack): Cognito global sign-out,
- *   CloudFront invalidation, raw-S3 prefix delete, DynamoDB `BatchWriteItem`
- *   cascade. Byte-for-byte the pre-split behavior. It imports the AWS SDK /
- *   ElectroDB graph and lives outside this shared, open-core module; it is
- *   injected here through `setDeletionCapabilities` so that graph never reaches
- *   the relational tree.
- * - `compose-relational.ts` (self-host stack, RFC 035/036): no-op sign-out
- *   (deleting the AccountConfig severs the session's data resolution; there is
- *   no CDN to sign out of), no-op invalidation (Caddy proxies `/content/*`
- *   straight to the backend with no cache), filesystem prefix delete, and the
- *   Drizzle cascade over SQLite.
- */
-export interface DeletionCapabilities {
-	/**
-	 * Validate every precondition the destructive steps depend on, BEFORE any row
-	 * or object is deleted. AWS checks both `CONTENT_DISTRIBUTION_ID` and
-	 * `S3_STORAGE_BUCKET_NAME` up front so a missing var fails loud instead of
-	 * destroying rows in the cascade and only then erroring at the storage step.
-	 * Relational is a no-op — its steps carry no such deploy-time configuration.
-	 */
-	assertReady(log: Logger): Promise<void>;
-	/**
-	 * Invalidate the deleted user's active auth sessions. AWS: Cognito
-	 * `AdminUserGlobalSignOut`. Relational: no-op.
-	 */
-	signOut(userId: string, log: Logger): Promise<void>;
-	/**
-	 * Purge any CDN/edge cache under a tenant/account content prefix
-	 * (`accountConfigId` or `accountConfigId/accountId`). AWS: CloudFront
-	 * invalidation of `/content/accounts/{prefix}/*`. Relational: no-op.
-	 */
-	invalidateContent(contentPrefix: string, log: Logger): Promise<void>;
-	/**
-	 * Delete every stored object under a storage key prefix
-	 * (`accounts/{accountConfigId}/…`). AWS: raw-S3 list+delete. Relational:
-	 * recursive filesystem removal under the local storage root.
-	 */
-	deleteStoragePrefix(keyPrefix: string, log: Logger): Promise<void>;
-	/**
-	 * Remove the enumerated rows in dependency order (children → parents). AWS:
-	 * DynamoDB `BatchWriteItem`. Relational: a Drizzle transaction. Excludes the AccountConfig row, which the caller deletes last
-	 * through its repository as the cascade-in-progress marker.
-	 */
-	cascadeDelete(entities: CascadeEntity[], log: Logger): Promise<void>;
-}
+export type { DeletionCapabilities };
 
 let injectedCapabilities: DeletionCapabilities | null = null;
 

package/src/deletion-port.ts

@@ -0,0 +1,55 @@
+import type { Logger } from "@remit/logger";
+import type { CascadeEntity } from "./cascade.js";
+
+/**
+ * The four steps of the deletion cascade that vary by deployment. Everything
+ * else — enumerating the AccountConfig's rows, the FIFO purge orchestration, the
+ * queue sends — is backend-neutral and lives in the handlers unchanged.
+ *
+ * Two composition roots build this:
+ *
+ * - The DynamoDB composition (AWS custody stack): Cognito global sign-out,
+ *   CloudFront invalidation, raw-S3 prefix delete, DynamoDB `BatchWriteItem`
+ *   cascade. Byte-for-byte the pre-split behavior. It imports the AWS SDK /
+ *   ElectroDB graph and lives outside this shared, open-core module; it is
+ *   injected here through `setDeletionCapabilities` so that graph never reaches
+ *   the relational tree.
+ * - `compose-relational.ts` (self-host stack, RFC 035/036): no-op sign-out
+ *   (deleting the AccountConfig severs the session's data resolution; there is
+ *   no CDN to sign out of), no-op invalidation (Caddy proxies `/content/*`
+ *   straight to the backend with no cache), filesystem prefix delete, and the
+ *   Drizzle cascade over SQLite.
+ */
+export interface DeletionCapabilities {
+	/**
+	 * Validate every precondition the destructive steps depend on, BEFORE any row
+	 * or object is deleted. AWS checks both `CONTENT_DISTRIBUTION_ID` and
+	 * `S3_STORAGE_BUCKET_NAME` up front so a missing var fails loud instead of
+	 * destroying rows in the cascade and only then erroring at the storage step.
+	 * Relational is a no-op — its steps carry no such deploy-time configuration.
+	 */
+	assertReady(log: Logger): Promise<void>;
+	/**
+	 * Invalidate the deleted user's active auth sessions. AWS: Cognito
+	 * `AdminUserGlobalSignOut`. Relational: no-op.
+	 */
+	signOut(userId: string, log: Logger): Promise<void>;
+	/**
+	 * Purge any CDN/edge cache under a tenant/account content prefix
+	 * (`accountConfigId` or `accountConfigId/accountId`). AWS: CloudFront
+	 * invalidation of `/content/accounts/{prefix}/*`. Relational: no-op.
+	 */
+	invalidateContent(contentPrefix: string, log: Logger): Promise<void>;
+	/**
+	 * Delete every stored object under a storage key prefix
+	 * (`accounts/{accountConfigId}/…`). AWS: raw-S3 list+delete. Relational:
+	 * recursive filesystem removal under the local storage root.
+	 */
+	deleteStoragePrefix(keyPrefix: string, log: Logger): Promise<void>;
+	/**
+	 * Remove the enumerated rows in dependency order (children → parents). AWS:
+	 * DynamoDB `BatchWriteItem`. Relational: a Drizzle transaction. Excludes the AccountConfig row, which the caller deletes last
+	 * through its repository as the cascade-in-progress marker.
+	 */
+	cascadeDelete(entities: CascadeEntity[], log: Logger): Promise<void>;
+}

package/src/handlers/account-finalize.ts

@@ -9,7 +9,6 @@ import type { SQSEvent, SQSHandler } from "aws-lambda";
 import {
 	type CascadeEntity,
 	type CascadeServices,
-	collectMessageChildEntities,
 	enumerateCascadeEntities,
 } from "../cascade.js";
 import { getCascadeServices } from "../config.js";
@@ -18,10 +17,10 @@ import {
 	getDeletionCapabilities,
 } from "../deletion-capabilities.js";
 import type {
-	AccountDataPurgeFinalizeEvent,
 	AccountDeleteFinalizeEvent,
 	AccountFinalizeEvent,
 } from "../events.js";
+import { processAccountDataPurgeFinalize } from "./account-purge-finalize.js";
 
 installNodeLogger();
 
@@ -124,154 +123,6 @@ export const processAccountFinalize = async (
 	log.info({ accountConfigId }, "AccountConfig deleted; cascade complete");
 };
 
-/**
- * Destructive phase of the per-account purge. Consumes the FIFO stream the
- * fanout producer emits (#1069), one message group per account so the messages
- * arrive strictly in order: every `subtrees` batch, then exactly one
- * `container` leftover. There is NO self-re-enqueue — the producer enqueues all
- * the work; this worker only ever consumes.
- *
- * Idempotency: the cascade on a missing key is a no-op, so a redelivered batch
- * (or container) no-ops on already-gone rows.
- */
-export const processAccountDataPurgeFinalize = async (
-	event: AccountDataPurgeFinalizeEvent,
-	log: Logger,
-	deps: ProcessFinalizeDeps = {},
-): Promise<void> => {
-	if (event.kind === "subtrees") {
-		await processPurgeSubtrees(event, log, deps);
-		return;
-	}
-	await processPurgeContainer(event, log, deps);
-};
-
-/**
- * Delete a batch of message subtrees. For each `{ threadMessageId, messageId }`
- * the manifest row is deleted UNCONDITIONALLY — there are ghost ThreadMessages
- * whose Message is already gone — and the Message + its 9 child entities are
- * deleted only when `describe()` resolves. A `describe()` 404 means the subtree
- * is already gone: skip the children, still drop the manifest row.
- */
-const processPurgeSubtrees = async (
-	event: Extract<AccountDataPurgeFinalizeEvent, { kind: "subtrees" }>,
-	log: Logger,
-	deps: ProcessFinalizeDeps,
-): Promise<void> => {
-	const { accountId, accountConfigId, items } = event;
-	const { capabilities, services } = await resolveDeps(deps);
-
-	const entities: CascadeEntity[] = [];
-	for (const { threadMessageId, messageId } of items) {
-		entities.push({
-			entityType: "ThreadMessage",
-			key: { accountConfigId, threadMessageId },
-		});
-		try {
-			const messageData = await services.messageService.describe(messageId);
-			entities.push({ entityType: "Message", key: { messageId } });
-			collectMessageChildEntities(entities, messageData);
-		} catch (error) {
-			if ((error as { name?: string })?.name === "NotFoundError") {
-				log.info(
-					{ accountConfigId, accountId, messageId },
-					"Message subtree already gone — deleting manifest row only",
-				);
-				continue;
-			}
-			throw error;
-		}
-	}
-
-	await capabilities.cascadeDelete(entities, log);
-	log.info(
-		{ accountConfigId, accountId, count: items.length },
-		"Per-account purge subtree batch deleted",
-	);
-};
-
-/**
- * The container leftover — processed last in the FIFO group, after every subtree
- * delete. Deletes the account-keyed container rows (mailboxes, outbox, locks),
- * the storage prefix `accounts/{cfg}/{acct}/`, and invalidates the account's
- * cached content. Ordering is invalidate-before-storage, storage-after-cascade.
- * The tenant-shared Address rows, the AccountConfig, sibling accounts, and the
- * soft-deleted account row (the purge-in-progress marker) are all kept.
- */
-const processPurgeContainer = async (
-	event: Extract<AccountDataPurgeFinalizeEvent, { kind: "container" }>,
-	log: Logger,
-	deps: ProcessFinalizeDeps,
-): Promise<void> => {
-	const { accountId, accountConfigId } = event;
-	const { capabilities, services } = await resolveDeps(deps);
-
-	// The account row is kept as the purge-in-progress marker. Its absence means
-	// the container leftover already ran — no-op on redelivery.
-	let accountDescription: Awaited<
-		ReturnType<CascadeServices["accountService"]["describe"]>
-	>;
-	try {
-		accountDescription = await services.accountService.describe(accountId);
-	} catch (error) {
-		if ((error as { name?: string })?.name === "NotFoundError") {
-			log.info(
-				{ accountConfigId, accountId },
-				"Per-account purge already complete (account row gone) — no-op",
-			);
-			return;
-		}
-		throw error;
-	}
-
-	// Validate every deploy-time precondition BEFORE the first destructive step.
-	// Runs after the account-existence guard so a redelivery whose account row is
-	// already gone still returns cleanly without needing the config present.
-	await capabilities.assertReady(log);
-
-	// Step 1: content invalidation — first, so cached body parts cannot leak
-	// after the underlying objects are gone.
-	log.info(
-		{ accountConfigId, accountId },
-		"Invalidating cached content for purged account",
-	);
-	await capabilities.invalidateContent(`${accountConfigId}/${accountId}`, log);
-
-	// Step 2: container rows — mailboxes, outbox, locks. Address is
-	// tenant-shared and never deleted on a per-account purge.
-	const entities: CascadeEntity[] = [];
-	for (const mailbox of accountDescription.mailbox) {
-		entities.push({
-			entityType: "Mailbox",
-			key: { mailboxId: mailbox.mailboxId },
-		});
-	}
-	const outboxMessages =
-		await services.outboxMessageService.listByAccount(accountId);
-	for (const outbox of outboxMessages.items) {
-		entities.push({
-			entityType: "OutboxMessage",
-			key: { outboxMessageId: outbox.outboxMessageId },
-		});
-	}
-	const locks = await services.mailboxLockService.listByAccount(accountId);
-	for (const lock of locks) {
-		entities.push({
-			entityType: "MailboxLock",
-			key: { mailboxId: lock.mailboxId, eventName: lock.eventName },
-		});
-	}
-	await capabilities.cascadeDelete(entities, log);
-
-	// Step 3: storage prefix cleanup scoped to this account only.
-	await capabilities.deleteStoragePrefix(
-		`accounts/${accountConfigId}/${accountId}/`,
-		log,
-	);
-
-	log.info({ accountConfigId, accountId }, "Per-account data purge complete");
-};
-
 // ---------- SQS handler ----------
 
 const log = createLogger();
@@ -292,7 +143,9 @@ export const handler: SQSHandler = withTelemetry(async (event: SQSEvent) => {
 		const start = Date.now();
 		const work =
 			finalizeEvent.type === "FinalizeAccountDataPurge"
-				? processAccountDataPurgeFinalize(finalizeEvent, log)
+				? resolveDeps({}).then((deps) =>
+						processAccountDataPurgeFinalize(finalizeEvent, log, deps),
+					)
 				: processAccountFinalize(finalizeEvent, log);
 
 		const failed = await work

package/src/handlers/account-purge-finalize.test.ts

@@ -0,0 +1,155 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { RemitClient } from "@remit/backend/client";
+import { recordingQueue } from "@remit/data-ports/recording-queue";
+import type { CascadeEntity } from "../cascade.js";
+import type { DeletionCapabilities } from "../deletion-port.js";
+import { processAccountPurgeEvent } from "../process.js";
+
+const notFound = (): Error =>
+	Object.assign(new Error("gone"), { name: "NotFoundError" });
+
+const messageDescription = {
+	messageFlag: [{ messageFlagId: "flag-1" }],
+	envelope: [{ envelopeId: "env-1" }],
+	messageReference: [],
+	envelopeAddress: [],
+	bodyPart: [],
+	bodyPartParameter: [],
+	rawMessageStorage: [],
+	bodyPartStorage: [],
+};
+
+const fakeClient = (accountGone = false): RemitClient =>
+	({
+		account: {
+			describe: async () => {
+				if (accountGone) throw notFound();
+				return { mailbox: [{ mailboxId: "mbx-1" }] };
+			},
+		},
+		message: {
+			describe: async (messageId: string) => {
+				if (messageId === "msg-gone") throw notFound();
+				return messageDescription;
+			},
+		},
+		outboxMessage: {
+			listByAccount: async () => ({ items: [{ outboxMessageId: "out-1" }] }),
+		},
+		mailboxLock: {
+			listByAccount: async () => [
+				{ mailboxId: "mbx-1", eventName: "SYNC_MESSAGES" },
+			],
+		},
+	}) as unknown as RemitClient;
+
+interface Recorded {
+	readonly capabilities: DeletionCapabilities;
+	readonly deleted: CascadeEntity[];
+	readonly prefixes: string[];
+	readonly invalidated: string[];
+}
+
+const recordingCapabilities = (): Recorded => {
+	const deleted: CascadeEntity[] = [];
+	const prefixes: string[] = [];
+	const invalidated: string[] = [];
+	return {
+		deleted,
+		prefixes,
+		invalidated,
+		capabilities: {
+			assertReady: async () => {},
+			signOut: async () => {},
+			invalidateContent: async (prefix) => {
+				invalidated.push(prefix);
+			},
+			deleteStoragePrefix: async (prefix) => {
+				prefixes.push(prefix);
+			},
+			cascadeDelete: async (entities) => {
+				deleted.push(...entities);
+			},
+		},
+	};
+};
+
+const typesOf = (entities: CascadeEntity[]): string[] =>
+	entities.map((entity) => entity.entityType);
+
+describe("processAccountPurgeEvent", () => {
+	it("deletes each message subtree and the manifest row of a message already gone", async () => {
+		const recorded = recordingCapabilities();
+		await processAccountPurgeEvent(
+			{
+				type: "FinalizeAccountDataPurge",
+				kind: "subtrees",
+				accountId: "acc-1",
+				accountConfigId: "cfg-1",
+				items: [
+					{ threadMessageId: "tm-1", messageId: "msg-1" },
+					{ threadMessageId: "tm-2", messageId: "msg-gone" },
+				],
+			},
+			{
+				client: fakeClient(),
+				purgeQueue: recordingQueue().grouped,
+				capabilities: recorded.capabilities,
+			},
+		);
+
+		assert.deepEqual(typesOf(recorded.deleted), [
+			"ThreadMessage",
+			"Message",
+			"MessageFlag",
+			"Envelope",
+			"ThreadMessage",
+		]);
+	});
+
+	it("deletes the account's mailboxes, outbox and locks, then its stored objects", async () => {
+		const recorded = recordingCapabilities();
+		await processAccountPurgeEvent(
+			{
+				type: "FinalizeAccountDataPurge",
+				kind: "container",
+				accountId: "acc-1",
+				accountConfigId: "cfg-1",
+			},
+			{
+				client: fakeClient(),
+				purgeQueue: recordingQueue().grouped,
+				capabilities: recorded.capabilities,
+			},
+		);
+
+		assert.deepEqual(typesOf(recorded.deleted), [
+			"Mailbox",
+			"OutboxMessage",
+			"MailboxLock",
+		]);
+		assert.deepEqual(recorded.invalidated, ["cfg-1/acc-1"]);
+		assert.deepEqual(recorded.prefixes, ["accounts/cfg-1/acc-1/"]);
+	});
+
+	it("does nothing for a container whose account row is gone", async () => {
+		const recorded = recordingCapabilities();
+		await processAccountPurgeEvent(
+			{
+				type: "FinalizeAccountDataPurge",
+				kind: "container",
+				accountId: "acc-1",
+				accountConfigId: "cfg-1",
+			},
+			{
+				client: fakeClient(true),
+				purgeQueue: recordingQueue().grouped,
+				capabilities: recorded.capabilities,
+			},
+		);
+
+		assert.deepEqual(recorded.deleted, []);
+		assert.deepEqual(recorded.prefixes, []);
+	});
+});

package/src/handlers/account-purge-finalize.ts

@@ -0,0 +1,161 @@
+import type { Logger } from "@remit/logger";
+import {
+	type CascadeEntity,
+	type CascadeServices,
+	collectMessageChildEntities,
+} from "../cascade.js";
+import type { DeletionCapabilities } from "../deletion-port.js";
+import type { AccountDataPurgeFinalizeEvent } from "../events.js";
+
+export interface PurgeFinalizeDeps {
+	capabilities: DeletionCapabilities;
+	services: CascadeServices;
+}
+
+/**
+ * Destructive phase of the per-account purge. Consumes the FIFO stream the
+ * fanout producer emits (#1069), one message group per account so the messages
+ * arrive strictly in order: every `subtrees` batch, then exactly one
+ * `container` leftover. There is NO self-re-enqueue — the producer enqueues all
+ * the work; this worker only ever consumes.
+ *
+ * Idempotency: the cascade on a missing key is a no-op, so a redelivered batch
+ * (or container) no-ops on already-gone rows.
+ */
+export const processAccountDataPurgeFinalize = async (
+	event: AccountDataPurgeFinalizeEvent,
+	log: Logger,
+	deps: PurgeFinalizeDeps,
+): Promise<void> => {
+	if (event.kind === "subtrees") {
+		await processPurgeSubtrees(event, log, deps);
+		return;
+	}
+	await processPurgeContainer(event, log, deps);
+};
+
+/**
+ * Delete a batch of message subtrees. For each `{ threadMessageId, messageId }`
+ * the manifest row is deleted UNCONDITIONALLY — there are ghost ThreadMessages
+ * whose Message is already gone — and the Message + its 9 child entities are
+ * deleted only when `describe()` resolves. A `describe()` 404 means the subtree
+ * is already gone: skip the children, still drop the manifest row.
+ */
+const processPurgeSubtrees = async (
+	event: Extract<AccountDataPurgeFinalizeEvent, { kind: "subtrees" }>,
+	log: Logger,
+	deps: PurgeFinalizeDeps,
+): Promise<void> => {
+	const { accountId, accountConfigId, items } = event;
+	const { capabilities, services } = deps;
+
+	const entities: CascadeEntity[] = [];
+	for (const { threadMessageId, messageId } of items) {
+		entities.push({
+			entityType: "ThreadMessage",
+			key: { accountConfigId, threadMessageId },
+		});
+		try {
+			const messageData = await services.messageService.describe(messageId);
+			entities.push({ entityType: "Message", key: { messageId } });
+			collectMessageChildEntities(entities, messageData);
+		} catch (error) {
+			if ((error as { name?: string })?.name === "NotFoundError") {
+				log.info(
+					{ accountConfigId, accountId, messageId },
+					"Message subtree already gone — deleting manifest row only",
+				);
+				continue;
+			}
+			throw error;
+		}
+	}
+
+	await capabilities.cascadeDelete(entities, log);
+	log.info(
+		{ accountConfigId, accountId, count: items.length },
+		"Per-account purge subtree batch deleted",
+	);
+};
+
+/**
+ * The container leftover — processed last in the FIFO group, after every subtree
+ * delete. Deletes the account-keyed container rows (mailboxes, outbox, locks),
+ * the storage prefix `accounts/{cfg}/{acct}/`, and invalidates the account's
+ * cached content. Ordering is invalidate-before-storage, storage-after-cascade.
+ * The tenant-shared Address rows, the AccountConfig, sibling accounts, and the
+ * soft-deleted account row (the purge-in-progress marker) are all kept.
+ */
+const processPurgeContainer = async (
+	event: Extract<AccountDataPurgeFinalizeEvent, { kind: "container" }>,
+	log: Logger,
+	deps: PurgeFinalizeDeps,
+): Promise<void> => {
+	const { accountId, accountConfigId } = event;
+	const { capabilities, services } = deps;
+
+	// The account row is kept as the purge-in-progress marker. Its absence means
+	// the container leftover already ran — no-op on redelivery.
+	let accountDescription: Awaited<
+		ReturnType<CascadeServices["accountService"]["describe"]>
+	>;
+	try {
+		accountDescription = await services.accountService.describe(accountId);
+	} catch (error) {
+		if ((error as { name?: string })?.name === "NotFoundError") {
+			log.info(
+				{ accountConfigId, accountId },
+				"Per-account purge already complete (account row gone) — no-op",
+			);
+			return;
+		}
+		throw error;
+	}
+
+	// Validate every deploy-time precondition BEFORE the first destructive step.
+	// Runs after the account-existence guard so a redelivery whose account row is
+	// already gone still returns cleanly without needing the config present.
+	await capabilities.assertReady(log);
+
+	// Step 1: content invalidation — first, so cached body parts cannot leak
+	// after the underlying objects are gone.
+	log.info(
+		{ accountConfigId, accountId },
+		"Invalidating cached content for purged account",
+	);
+	await capabilities.invalidateContent(`${accountConfigId}/${accountId}`, log);
+
+	// Step 2: container rows — mailboxes, outbox, locks. Address is
+	// tenant-shared and never deleted on a per-account purge.
+	const entities: CascadeEntity[] = [];
+	for (const mailbox of accountDescription.mailbox) {
+		entities.push({
+			entityType: "Mailbox",
+			key: { mailboxId: mailbox.mailboxId },
+		});
+	}
+	const outboxMessages =
+		await services.outboxMessageService.listByAccount(accountId);
+	for (const outbox of outboxMessages.items) {
+		entities.push({
+			entityType: "OutboxMessage",
+			key: { outboxMessageId: outbox.outboxMessageId },
+		});
+	}
+	const locks = await services.mailboxLockService.listByAccount(accountId);
+	for (const lock of locks) {
+		entities.push({
+			entityType: "MailboxLock",
+			key: { mailboxId: lock.mailboxId, eventName: lock.eventName },
+		});
+	}
+	await capabilities.cascadeDelete(entities, log);
+
+	// Step 3: storage prefix cleanup scoped to this account only.
+	await capabilities.deleteStoragePrefix(
+		`accounts/${accountConfigId}/${accountId}/`,
+		log,
+	);
+
+	log.info({ accountConfigId, accountId }, "Per-account data purge complete");
+};

package/src/handlers/account-purge.ts

@@ -1,7 +1,6 @@
 import type { GroupedQueueProducer } from "@remit/data-ports";
 import type { Logger } from "@remit/logger";
 import type { CascadeServices } from "../cascade.js";
-import { getCascadeServices } from "../config.js";
 import type {
 	AccountDataPurgeEvent,
 	AccountDataPurgeFinalizeEvent,
@@ -10,7 +9,7 @@ import type {
 
 export interface ProcessPurgeFanoutDeps {
 	queue: GroupedQueueProducer<AccountDataPurgeFinalizeEvent>;
-	services?: CascadeServices;
+	services: CascadeServices;
 }
 
 /**
@@ -81,7 +80,7 @@ export const processAccountDataPurge = async (
 	deps: ProcessPurgeFanoutDeps,
 ): Promise<void> => {
 	const { accountId, accountConfigId } = event;
-	const services = deps.services ?? (await getCascadeServices());
+	const { services } = deps;
 
 	let mailboxIds: Set<string>;
 	try {

package/src/process.ts

@@ -1,18 +1,39 @@
 import type { RemitClient } from "@remit/backend/client";
+import type { GroupedQueueProducer } from "@remit/data-ports";
 import { createLogger } from "@remit/logger";
+import { cascadeServicesOf } from "./cascade.js";
+import type { DeletionCapabilities } from "./deletion-port.js";
 import type {
+	AccountDataPurgeEvent,
+	AccountDataPurgeFinalizeEvent,
 	OrganizeJobEvent,
 	SenderCategoryBackApplyEvent,
 } from "./events.js";
+import { processAccountDataPurge } from "./handlers/account-purge.js";
+import { processAccountDataPurgeFinalize } from "./handlers/account-purge-finalize.js";
 import { processOrganizeJob } from "./handlers/organize-job.js";
 import { processSenderCategoryBackApply } from "./handlers/sender-category-backapply.js";
 
+export type { CascadeEntity } from "./cascade.js";
+export type { DeletionCapabilities } from "./deletion-port.js";
+export type { AccountDataPurgeEvent, AccountDataPurgeFinalizeEvent };
+
 export type ClientFanoutEvent = OrganizeJobEvent | SenderCategoryBackApplyEvent;
 
 export interface AccountFanoutContext {
 	client: RemitClient<"messageManagement">;
 }
 
+export type AccountPurgeEvent =
+	| AccountDataPurgeEvent
+	| AccountDataPurgeFinalizeEvent;
+
+export interface AccountPurgeContext {
+	client: RemitClient;
+	purgeQueue: GroupedQueueProducer<AccountDataPurgeFinalizeEvent>;
+	capabilities: DeletionCapabilities;
+}
+
 const log = createLogger();
 
 export const processAccountFanoutEvent = (
@@ -26,3 +47,22 @@ export const processAccountFanoutEvent = (
 			return processSenderCategoryBackApply(event, log, { client: ctx.client });
 	}
 };
+
+export const processAccountPurgeEvent = (
+	event: AccountPurgeEvent,
+	ctx: AccountPurgeContext,
+): Promise<void> => {
+	const services = cascadeServicesOf(ctx.client);
+	switch (event.type) {
+		case "AccountDataPurge":
+			return processAccountDataPurge(event, log, {
+				services,
+				queue: ctx.purgeQueue,
+			});
+		case "FinalizeAccountDataPurge":
+			return processAccountDataPurgeFinalize(event, log, {
+				services,
+				capabilities: ctx.capabilities,
+			});
+	}
+};