@remit/backend 0.0.1

package/src/service/compose-postgres.ts

@@ -0,0 +1,72 @@
+import {
+	AccountConfigRepo,
+	AccountExportRequestRepo,
+	AccountRepo,
+	AccountSettingRepo,
+	AddressRepo,
+	DrizzleEnvelopeRepository,
+	DrizzleMessageFlagRepository,
+	DrizzleMessageRepository,
+	DrizzleThreadMessageRepository,
+	DrizzleUnitOfWork,
+	FilterAnchorRepo,
+	FilterRepo,
+	LabelRepo,
+	MailboxLockRepo,
+	MailboxRepo,
+	MailboxSpecialUseRepo,
+	MessageFlagPushRepo,
+	MessageLabelRepo,
+	MessagePlacementMoveRepo,
+	messageDataSchema,
+	OrganizeJobRequestRepo,
+	OutboxMessageRepo,
+} from "@remit/drizzle-service";
+import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
+import { env } from "expect-env";
+import {
+	buildSharedDeps,
+	createRemitClient,
+	type RemitClient,
+	type RemitClientRepositories,
+} from "./create-remit-client.js";
+
+export const buildPostgresClient = (): RemitClient => {
+	const pgConnectionUrl = env.PG_CONNECTION_URL;
+
+	// One drizzle db instance shared across repos.
+	// The schema is registered for message-data tables; i4 repos use the same
+	// underlying connection and only need the builder API (no relational queries).
+	const db = drizzle(pgConnectionUrl, { schema: messageDataSchema });
+	const genericDb = db as unknown as NodePgDatabase<Record<string, unknown>>;
+
+	const messageDataDb = db as unknown as NodePgDatabase<
+		typeof messageDataSchema
+	>;
+
+	const repositories: RemitClientRepositories = {
+		accountConfig: new AccountConfigRepo(genericDb),
+		account: new AccountRepo(genericDb),
+		accountSetting: new AccountSettingRepo(genericDb),
+		address: new AddressRepo(genericDb),
+		mailbox: new MailboxRepo(genericDb),
+		mailboxSpecialUse: new MailboxSpecialUseRepo(genericDb),
+		mailboxLock: new MailboxLockRepo(genericDb),
+		message: new DrizzleMessageRepository(messageDataDb),
+		messageFlag: new DrizzleMessageFlagRepository(messageDataDb),
+		outboxMessage: new OutboxMessageRepo(genericDb),
+		threadMessage: new DrizzleThreadMessageRepository(pgConnectionUrl),
+		envelope: new DrizzleEnvelopeRepository(messageDataDb),
+		accountExportRequest: new AccountExportRequestRepo(genericDb),
+		organizeJobRequest: new OrganizeJobRequestRepo(genericDb),
+		placementMove: new MessagePlacementMoveRepo(genericDb),
+		flagPush: new MessageFlagPushRepo(genericDb),
+		filter: new FilterRepo(genericDb),
+		filterAnchor: new FilterAnchorRepo(genericDb),
+		label: new LabelRepo(genericDb),
+		messageLabel: new MessageLabelRepo(genericDb),
+		unitOfWork: new DrizzleUnitOfWork(messageDataDb),
+	};
+
+	return createRemitClient({ repositories, ...buildSharedDeps() });
+};

package/src/service/compose-sqlite.ts

@@ -0,0 +1,80 @@
+import {
+	AccountConfigRepo,
+	AccountExportRequestRepo,
+	AccountRepo,
+	AccountSettingRepo,
+	AddressRepo,
+	createSqliteDatabase,
+	DrizzleEnvelopeRepository,
+	DrizzleMessageFlagRepository,
+	DrizzleMessageRepository,
+	DrizzleThreadMessageRepository,
+	DrizzleUnitOfWork,
+	FilterAnchorRepo,
+	FilterRepo,
+	LabelRepo,
+	MailboxLockRepo,
+	MailboxRepo,
+	MailboxSpecialUseRepo,
+	MessageFlagPushRepo,
+	MessageLabelRepo,
+	MessagePlacementMoveRepo,
+	messageDataSchema,
+	OrganizeJobRequestRepo,
+	OutboxMessageRepo,
+} from "@remit/drizzle-service";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { env } from "expect-env";
+import {
+	buildSharedDeps,
+	createRemitClient,
+	type RemitClient,
+	type RemitClientRepositories,
+} from "./create-remit-client.js";
+
+// The SQLite backend (RFC 036). Mirrors the Postgres composition — the same
+// dialect-neutral Drizzle repos, wired to one shared SQLite file instead of a
+// Postgres server — with two differences the file topology forces (D3): every
+// repo runs on the single serialized connection `createSqliteDatabase` opens
+// (writes cannot bypass serialization, so a plain repo write never joins an
+// open transaction's savepoint), and `threadMessage` takes that shared handle
+// rather than its own connection string, so its writes enlist in the same
+// unit-of-work transaction and the same write queue as everything else.
+export const buildSqliteClient = async (): Promise<RemitClient> => {
+	const sqliteDbPath = env.SQLITE_DB_PATH;
+
+	const { db } = await createSqliteDatabase(messageDataSchema, {
+		filename: sqliteDbPath,
+	});
+	const genericDb = db as unknown as NodePgDatabase<Record<string, unknown>>;
+
+	const messageDataDb = db as unknown as NodePgDatabase<
+		typeof messageDataSchema
+	>;
+
+	const repositories: RemitClientRepositories = {
+		accountConfig: new AccountConfigRepo(genericDb),
+		account: new AccountRepo(genericDb),
+		accountSetting: new AccountSettingRepo(genericDb),
+		address: new AddressRepo(genericDb),
+		mailbox: new MailboxRepo(genericDb),
+		mailboxSpecialUse: new MailboxSpecialUseRepo(genericDb),
+		mailboxLock: new MailboxLockRepo(genericDb),
+		message: new DrizzleMessageRepository(messageDataDb),
+		messageFlag: new DrizzleMessageFlagRepository(messageDataDb),
+		outboxMessage: new OutboxMessageRepo(genericDb),
+		threadMessage: new DrizzleThreadMessageRepository(genericDb),
+		envelope: new DrizzleEnvelopeRepository(messageDataDb),
+		accountExportRequest: new AccountExportRequestRepo(genericDb),
+		organizeJobRequest: new OrganizeJobRequestRepo(genericDb),
+		placementMove: new MessagePlacementMoveRepo(genericDb),
+		flagPush: new MessageFlagPushRepo(genericDb),
+		filter: new FilterRepo(genericDb),
+		filterAnchor: new FilterAnchorRepo(genericDb),
+		label: new LabelRepo(genericDb),
+		messageLabel: new MessageLabelRepo(genericDb),
+		unitOfWork: new DrizzleUnitOfWork(messageDataDb),
+	};
+
+	return createRemitClient({ repositories, ...buildSharedDeps() });
+};

package/src/service/create-remit-client.ts

@@ -0,0 +1,358 @@
+import type {
+	IAccountConfigRepository,
+	IAccountExportRequestRepository,
+	IAccountRepository,
+	IAccountSettingRepository,
+	IAddressRepository,
+	IEnvelopeRepository,
+	IFilterAnchorRepository,
+	IFilterRepository,
+	ILabelRepository,
+	IMailboxLockRepository,
+	IMailboxRepository,
+	IMailboxSpecialUseRepository,
+	IMessageFlagPushRepository,
+	IMessageFlagRepository,
+	IMessageLabelRepository,
+	IMessagePlacementMoveRepository,
+	IMessageRepository,
+	IOrganizeJobRequestRepository,
+	IOutboxMessageRepository,
+	IThreadMessageRepository,
+	IUnitOfWork,
+} from "@remit/data-ports";
+import { logger } from "@remit/logger-lambda";
+import {
+	BodySyncQueueService,
+	BodySyncService,
+	createConnection,
+	FlagPushService,
+	FlagQueueService,
+	type IImapConnection,
+	MailboxQueueService,
+	MessageMoveService,
+	OutboxQueueService,
+} from "@remit/mailbox-service";
+import { createSearchService, type SearchService } from "@remit/search-service";
+import {
+	buildEmbeddingServiceFromEnv,
+	buildVectorStoreFromEnv,
+} from "@remit/search-service/from-env";
+import {
+	createCachedDataKeyProvider,
+	createKmsDataKeyProvider,
+	createSecretsService,
+	deserializeEncryptedPayload,
+	FAKE_KMS_KEY_ID,
+	type SecretsService,
+} from "@remit/secrets-service";
+import type { StorageService } from "@remit/storage-service";
+import { createStorageService } from "@remit/storage-service/s3";
+import { env } from "expect-env";
+
+export interface ConnectionScope {
+	getConnection: () => Promise<IImapConnection>;
+	disconnect: () => Promise<void>;
+}
+
+export interface RemitClient {
+	// Data repositories (satisfied by ElectroDB services or Drizzle repos)
+	accountConfig: IAccountConfigRepository;
+	account: IAccountRepository;
+	accountSetting: IAccountSettingRepository;
+	address: IAddressRepository;
+	mailbox: IMailboxRepository;
+	mailboxSpecialUse: IMailboxSpecialUseRepository;
+	mailboxLock: IMailboxLockRepository;
+	message: IMessageRepository;
+	messageFlag: IMessageFlagRepository;
+	outboxMessage: IOutboxMessageRepository;
+	threadMessage: IThreadMessageRepository;
+	envelope: IEnvelopeRepository;
+	accountExportRequest: IAccountExportRequestRepository;
+
+	// Smart Organize back-apply job (RFC 034, #1278). Present on both backends,
+	// modeled on accountExportRequest — a Pending row the account-fanout worker
+	// picks up and drives to Complete/Failed. Never a Filter.
+	organizeJobRequest: IOrganizeJobRequestRepository;
+
+	// Smart Organize (RFC 034, epic #1280). Present on both backends
+	// (`FilterService`/`LabelService`/… on DynamoDB, `FilterRepo`/`LabelRepo`/…
+	// on Postgres) so the matching pipeline and filter CRUD run unchanged on
+	// either. The Postgres side has no TTL reaper for expired Temporary filters;
+	// match-time correctness gates on `expiresAt` (RFC 034 Decision 1.1), never
+	// on the row still existing, so the missing reaper is housekeeping only.
+	filter: IFilterRepository;
+	filterAnchor: IFilterAnchorRepository;
+	label: ILabelRepository;
+	messageLabel: IMessageLabelRepository;
+
+	// Atomic write set for a message save. Present on Postgres (real
+	// transaction); absent on DynamoDB, where callers fall back to per-repo
+	// writes with that backend's own (non-transactional) guarantees.
+	unitOfWork?: IUnitOfWork;
+
+	// Storage service
+	storage: StorageService;
+
+	// Search service (semantic vector search)
+	search: SearchService;
+
+	// Secrets service (KMS encryption)
+	secrets: SecretsService;
+
+	// Body sync service (on-demand IMAP body fetch)
+	bodySync: BodySyncService;
+
+	// Re-arms the SYNC_MESSAGE_BODY cue when a read-path body fetch finds the
+	// storage object missing. Absent when SQS_QUEUE_URL_BODY is not configured
+	// (the deployed API Lambda does not carry the body queue today).
+	bodySyncQueue?: BodySyncQueueService;
+
+	// Pending placement-move markers (issue #1271). Present on both backends
+	// (`MessagePlacementMoveService` on DynamoDB, `MessagePlacementMoveRepo` on
+	// Postgres) so a caller never needs to guess which backend is active. Used
+	// for read-time count prediction (epic #1281 invariant 4) and by the
+	// account-worker cascade delete. Written by the imap-worker's bulk
+	// body-sync path through this `placementMove`, so the placement producer
+	// runs on whatever backend is active — DynamoDB, Postgres, or SQLite.
+	placementMove: IMessagePlacementMoveRepository;
+
+	// Pending flag-push markers (issue #1273). Present on both backends
+	// (`MessageFlagPushService` on DynamoDB, `MessageFlagPushRepo` on
+	// Postgres). Used for read-time unseenCount prediction (epic #1281
+	// invariant 4), by the account-worker cascade delete, and by the periodic
+	// per-mailbox sync tick to re-arm a marker stuck `pending`. Unlike
+	// `placementMove`, this one IS written on both backends — `flagQueue`
+	// below writes through it regardless of `DATA_BACKEND`.
+	flagPush: IMessageFlagPushRepository;
+
+	// Queue services (writes with IMAP sync)
+	flagQueue: FlagQueueService;
+	mailboxQueue: MailboxQueueService;
+	messageMove: MessageMoveService;
+	outboxQueue: OutboxQueueService;
+
+	// Helper to create IMAP connection scope from accountId
+	createConnectionScope: (accountId: string) => Promise<ConnectionScope>;
+}
+
+export interface RemitClientRepositories {
+	accountConfig: IAccountConfigRepository;
+	account: IAccountRepository;
+	accountSetting: IAccountSettingRepository;
+	address: IAddressRepository;
+	mailbox: IMailboxRepository;
+	mailboxSpecialUse: IMailboxSpecialUseRepository;
+	mailboxLock: IMailboxLockRepository;
+	message: IMessageRepository;
+	messageFlag: IMessageFlagRepository;
+	outboxMessage: IOutboxMessageRepository;
+	threadMessage: IThreadMessageRepository;
+	envelope: IEnvelopeRepository;
+	accountExportRequest: IAccountExportRequestRepository;
+	organizeJobRequest: IOrganizeJobRequestRepository;
+	placementMove: IMessagePlacementMoveRepository;
+	flagPush: IMessageFlagPushRepository;
+	filter: IFilterRepository;
+	filterAnchor: IFilterAnchorRepository;
+	label: ILabelRepository;
+	messageLabel: IMessageLabelRepository;
+	unitOfWork?: IUnitOfWork;
+}
+
+export interface RemitClientSharedDeps {
+	storage: StorageService;
+	search: SearchService;
+	secrets: SecretsService;
+	sqsQueueUrl: string;
+	sqsSmtpQueueUrl: string;
+	bodySyncQueue?: BodySyncQueueService;
+}
+
+export interface RemitClientDeps extends RemitClientSharedDeps {
+	repositories: RemitClientRepositories;
+}
+
+const buildConnectionScope =
+	(accountService: IAccountRepository, secretsService: SecretsService) =>
+	async (accountId: string): Promise<ConnectionScope> => {
+		const account = await accountService.get(accountId);
+		if (!account.passwordHash) {
+			throw new Error(
+				`Account ${accountId} has no passwordHash — OAuth accounts cannot use this connection path`,
+			);
+		}
+		const password = await secretsService.decrypt(
+			deserializeEncryptedPayload(JSON.parse(account.passwordHash)),
+		);
+
+		let connection: IImapConnection | null = null;
+		let connectPromise: Promise<IImapConnection> | null = null;
+
+		const getConnection = async (): Promise<IImapConnection> => {
+			if (connectPromise) {
+				return connectPromise;
+			}
+
+			const conn = createConnection({
+				user: account.username,
+				credentials: { kind: "password", password },
+				host: account.imapHost,
+				port: account.imapPort,
+				tls: account.imapTls,
+			});
+			connection = conn;
+			connectPromise = conn.connect().then(() => conn);
+
+			return connectPromise;
+		};
+
+		const disconnect = async (): Promise<void> => {
+			if (connection) {
+				await connection.disconnect();
+				connection = null;
+				connectPromise = null;
+			}
+		};
+
+		return { getConnection, disconnect };
+	};
+
+// The vector store and embedder are selected from the environment by the shared
+// builders: S3 Vectors + Bedrock Titan in production, persistent sqlite-vec +
+// Transformers.js when the LOCAL_* / local flags are set (local dev), and the
+// in-memory store + deterministic embedder otherwise (tests).
+const buildSearchService = (): SearchService => {
+	// Build the embedder first so we can pass its dimension count to the
+	// sqlite-vec store — the vec0 table dimension must match the embedder.
+	const embedder = buildEmbeddingServiceFromEnv();
+	return createSearchService({
+		store: buildVectorStoreFromEnv(embedder.dimensions),
+		embedder,
+	});
+};
+
+// The body queue lives on the worker infra; the API only knows it locally
+// (dev / e2e set SQS_QUEUE_URL_BODY). When unset the read path still returns a
+// retryable 202 — it just cannot re-arm the cue itself.
+const buildBodySyncQueue = (): BodySyncQueueService | undefined => {
+	const bodyQueueUrl = process.env.SQS_QUEUE_URL_BODY;
+	if (!bodyQueueUrl) return undefined;
+	return new BodySyncQueueService({ sqsQueueUrl: bodyQueueUrl, logger });
+};
+
+// Everything a RemitClient needs that is chosen from the environment and does
+// not vary by data backend: storage, search, secrets, the SQS queue URLs, and
+// the optional body-sync queue. Each composition root builds its backend's
+// repositories and merges them with this.
+export const buildSharedDeps = (): RemitClientSharedDeps => {
+	const storage = createStorageService();
+	const search = buildSearchService();
+	const kmsKeyId = process.env.KMS_KEY_ID ?? FAKE_KMS_KEY_ID;
+	const dataKeyProvider = createCachedDataKeyProvider(
+		createKmsDataKeyProvider(kmsKeyId),
+	);
+	const secrets = createSecretsService(dataKeyProvider);
+	const sqsQueueUrl = env.SQS_QUEUE_URL;
+	const sqsSmtpQueueUrl = process.env.SQS_QUEUE_URL_SMTP ?? sqsQueueUrl;
+	return {
+		storage,
+		search,
+		secrets,
+		sqsQueueUrl,
+		sqsSmtpQueueUrl,
+		bodySyncQueue: buildBodySyncQueue(),
+	};
+};
+
+// Backend-neutral composition root: given repositories (from any data-ports
+// implementation) and the shared services, wire the domain and queue services
+// and assemble a RemitClient. Imports neither ElectroDB nor Drizzle — the
+// caller chooses the backend.
+export const createRemitClient = (deps: RemitClientDeps): RemitClient => {
+	const {
+		repositories,
+		storage,
+		search,
+		secrets,
+		sqsQueueUrl,
+		sqsSmtpQueueUrl,
+		bodySyncQueue,
+	} = deps;
+
+	const bodySync = new BodySyncService(
+		repositories.message,
+		storage,
+		repositories.threadMessage,
+		repositories.address,
+		repositories.envelope,
+		logger,
+	);
+
+	const flagPushService = new FlagPushService({
+		markerService: repositories.flagPush,
+		sqsQueueUrl,
+		logger,
+	});
+
+	return {
+		accountConfig: repositories.accountConfig,
+		account: repositories.account,
+		accountSetting: repositories.accountSetting,
+		address: repositories.address,
+		mailbox: repositories.mailbox,
+		mailboxSpecialUse: repositories.mailboxSpecialUse,
+		mailboxLock: repositories.mailboxLock,
+		message: repositories.message,
+		messageFlag: repositories.messageFlag,
+		outboxMessage: repositories.outboxMessage,
+		threadMessage: repositories.threadMessage,
+		envelope: repositories.envelope,
+		accountExportRequest: repositories.accountExportRequest,
+		organizeJobRequest: repositories.organizeJobRequest,
+		filter: repositories.filter,
+		filterAnchor: repositories.filterAnchor,
+		label: repositories.label,
+		messageLabel: repositories.messageLabel,
+		unitOfWork: repositories.unitOfWork,
+
+		storage,
+		search,
+		secrets,
+
+		bodySync,
+		bodySyncQueue,
+		placementMove: repositories.placementMove,
+		flagPush: repositories.flagPush,
+
+		flagQueue: new FlagQueueService({
+			messageFlagService: repositories.messageFlag,
+			messageService: repositories.message,
+			threadMessageService: repositories.threadMessage,
+			flagPushService,
+			logger,
+		}),
+		mailboxQueue: new MailboxQueueService({
+			mailboxService: repositories.mailbox,
+			sqsQueueUrl,
+			logger,
+		}),
+		messageMove: new MessageMoveService({
+			messageService: repositories.message,
+			mailboxService: repositories.mailbox,
+			mailboxSpecialUseService: repositories.mailboxSpecialUse,
+			threadMessageService: repositories.threadMessage,
+			sqsQueueUrl,
+			logger,
+		}),
+		outboxQueue: new OutboxQueueService({
+			outboxMessageService: repositories.outboxMessage,
+			accountService: repositories.account,
+			sqsSmtpQueueUrl,
+			logger,
+		}),
+
+		createConnectionScope: buildConnectionScope(repositories.account, secrets),
+	};
+};

package/src/service/dynamodb.test.ts

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { afterEach, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { _resetForTest, getClient, type RemitClient } from "./dynamodb.js";
+
+// The DynamoDB composition module is stripped from the open-core tree; its
+// no-regression guard runs where the module ships and skips where it does not.
+const hasDynamoComposition = existsSync(
+	fileURLToPath(new URL("./compose-dynamodb.ts", import.meta.url)),
+);
+
+const REQUIRED_KEYS: ReadonlyArray<keyof RemitClient> = [
+	"accountConfig",
+	"account",
+	"accountSetting",
+	"address",
+	"mailbox",
+	"mailboxSpecialUse",
+	"message",
+	"messageFlag",
+	"outboxMessage",
+	"threadMessage",
+	"envelope",
+	"accountExportRequest",
+	"storage",
+	"search",
+	"secrets",
+	"bodySync",
+	"flagQueue",
+	"mailboxQueue",
+	"messageMove",
+	"outboxQueue",
+	"createConnectionScope",
+] as const;
+
+afterEach(() => {
+	_resetForTest();
+});
+
+test("getClient() with DATA_BACKEND=postgres constructs all services without throwing", async () => {
+	const savedBackend = process.env.DATA_BACKEND;
+	const savedPgUrl = process.env.PG_CONNECTION_URL;
+
+	process.env.DATA_BACKEND = "postgres";
+	process.env.PG_CONNECTION_URL =
+		"postgresql://remit:remit@localhost:5432/remit_test";
+
+	try {
+		const client = await getClient();
+
+		for (const key of REQUIRED_KEYS) {
+			assert.ok(
+				client[key] !== undefined && client[key] !== null,
+				`RemitClient.${key} must be defined on the postgres path`,
+			);
+		}
+
+		assert.equal(typeof client.createConnectionScope, "function");
+	} finally {
+		_resetForTest();
+		if (savedBackend === undefined) {
+			delete process.env.DATA_BACKEND;
+		} else {
+			process.env.DATA_BACKEND = savedBackend;
+		}
+		if (savedPgUrl === undefined) {
+			delete process.env.PG_CONNECTION_URL;
+		} else {
+			process.env.PG_CONNECTION_URL = savedPgUrl;
+		}
+	}
+});
+
+test(
+	"getClient() without DATA_BACKEND constructs all services without throwing (DynamoDB path, no regression)",
+	{ skip: !hasDynamoComposition },
+	async () => {
+		const savedBackend = process.env.DATA_BACKEND;
+		delete process.env.DATA_BACKEND;
+
+		try {
+			const client = await getClient();
+
+			for (const key of REQUIRED_KEYS) {
+				assert.ok(
+					client[key] !== undefined && client[key] !== null,
+					`RemitClient.${key} must be defined on the DynamoDB path`,
+				);
+			}
+
+			assert.equal(typeof client.createConnectionScope, "function");
+		} finally {
+			_resetForTest();
+			if (savedBackend !== undefined) {
+				process.env.DATA_BACKEND = savedBackend;
+			}
+		}
+	},
+);

package/src/service/dynamodb.ts

@@ -0,0 +1,58 @@
+import type { RemitClient } from "./create-remit-client.js";
+
+export type {
+	ConnectionScope,
+	RemitClient,
+} from "./create-remit-client.js";
+
+// The DynamoDB composition module is stripped from the open-core export (it
+// imports the closed electrodb-service). The `as string` specifier keeps
+// tsgo from resolving it there — where the file is absent — while this named
+// contract keeps the call site typed rather than `any`. The relational tree
+// never takes this branch; the DynamoDB deploy, where the module is present,
+// resolves it at runtime.
+type ComposeDynamoDBModule = { buildDynamoDBClient: () => RemitClient };
+
+let clientPromise: Promise<RemitClient> | null = null;
+
+// The API process and the imap-worker share this composition root. Each backend
+// is loaded through a dynamic import of its own composition module, so the
+// module that a given deploy never runs never enters its graph: `@remit/remit-
+// drizzle-service`/`drizzle-orm` stay out of a Lambda bundle (both `external`
+// for the Lambda esbuild build; `remit-lambda-bundles.test.ts` enforces this),
+// and the DynamoDB composition — which imports the closed `@remit/remit-
+// electrodb-service` — stays out of the relational (open-core) tree, where its
+// module is not shipped at all. esbuild still bundles the DynamoDB path into
+// the Lambda because `./compose-dynamodb.js` is a relative import, not an
+// `external`.
+export const getClient = (): Promise<RemitClient> => {
+	if (!clientPromise) {
+		if (process.env.DATA_BACKEND === "postgres") {
+			clientPromise = import("./compose-postgres.js").then((m) =>
+				m.buildPostgresClient(),
+			);
+		} else if (process.env.DATA_BACKEND === "sqlite") {
+			clientPromise = import("./compose-sqlite.js").then((m) =>
+				m.buildSqliteClient(),
+			);
+		} else {
+			clientPromise = (
+				import(
+					"./compose-dynamodb.js" as string
+				) as Promise<ComposeDynamoDBModule>
+			).then((m) => m.buildDynamoDBClient());
+		}
+	}
+
+	return clientPromise;
+};
+
+/** Reset the singleton — test use only. */
+export const _resetForTest = (): void => {
+	clientPromise = null;
+};
+
+/** Inject a (usually partial) client — test use only. */
+export const _setClientForTest = (override: RemitClient): void => {
+	clientPromise = Promise.resolve(override);
+};