@remit/drizzle-service 0.0.1

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

@@ -0,0 +1,79 @@
+import { type SQL, sql } from "drizzle-orm";
+import { isSqlite } from "../dialect.js";
+
+// Accent- and case-insensitive substring match over the whole mailbox, isolated
+// here as the one text-search seam that genuinely differs by dialect (RFC 036
+// D1). The subject and sender predicates match the DynamoDB `contains()`
+// substring contract: LIKE metacharacters (`\`, `%`, `_`) are escaped in JS so
+// the needle arrives as bind-parameter text, and the escaped form is treated
+// literally.
+
+const escapeLike = (term: string): string => term.replace(/[\\%_]/g, "\\$&");
+
+// ─── Postgres ────────────────────────────────────────────────────────────────
+// The folded expressions must reproduce the indexed expressions in
+// npm-scripts/pg-search-index.sql exactly (immutable unaccent + lower over the
+// coalesced text) so the planner uses the trigram GIN indexes. Matching runs
+// over the whole mailbox — Postgres indexes the text, so there is no
+// recent-window read bound.
+const PG_SUBJECT_FOLDED = sql`remit_immutable_unaccent(lower(coalesce(subject, '')))`;
+const PG_FROM_FOLDED = sql`remit_immutable_unaccent(lower(coalesce(from_name, '') || ' ' || coalesce(from_email, '')))`;
+
+const pgLikePattern = (term: string): SQL =>
+	sql`'%' || remit_immutable_unaccent(lower(${escapeLike(term)})) || '%'`;
+
+const pgSubjectMatch = (term: string): SQL =>
+	sql`${PG_SUBJECT_FOLDED} like ${pgLikePattern(term)}`;
+const pgFromMatch = (term: string): SQL =>
+	sql`${PG_FROM_FOLDED} like ${pgLikePattern(term)}`;
+
+// ─── SQLite ──────────────────────────────────────────────────────────────────
+// Text search on SQLite is the external-content FTS5 trigram index that
+// npm-scripts/sqlite-search-index.sql installs (RFC 036 D4): `thread_message_fts`
+// indexes the folded subject and sender, and MATCH is an accent- and
+// case-insensitive substring search (the tokenizer folds both sides, so the
+// needle is passed through untransformed). The predicate is a `rowid IN
+// (subquery)` over that index — the outer WHERE still narrows by mailbox.
+//
+// Trigram indexing needs three characters, so a one- or two-character term
+// falls back to the unindexed folded LIKE scan D4 names — lower() both sides,
+// substring-match, `escape '\'` making the JS-escaped metacharacters literal.
+// It is case-insensitive for ASCII and does not fold diacritics; the accepted
+// per-target difference from Postgres `unaccent`.
+
+// FTS5 treats bare query text as its match grammar (AND/OR/NEAR/`*`/`-`/`:`), so
+// wrap the term as a double-quoted string literal — doubling embedded quotes —
+// to match it verbatim as a trigram substring.
+const ftsPhrase = (term: string): string => `"${term.replace(/"/g, '""')}"`;
+
+// Trigram tokenization is by character, so measure the term in code points, not
+// UTF-16 units — a two-astral-character term is still under the three-char
+// index floor.
+const isTrigramIndexable = (term: string): boolean => [...term].length >= 3;
+
+const ftsRowidMatch = (matchExpr: string): SQL =>
+	sql`"thread_message"."rowid" in (select "rowid" from "thread_message_fts" where "thread_message_fts" match ${matchExpr})`;
+
+const SQLITE_SUBJECT_FOLDED = sql`lower(coalesce(subject, ''))`;
+const SQLITE_FROM_FOLDED = sql`lower(coalesce(from_name, '') || ' ' || coalesce(from_email, ''))`;
+
+const sqliteLikePattern = (term: string): SQL =>
+	sql`'%' || lower(${escapeLike(term)}) || '%'`;
+
+const sqliteSubjectMatch = (term: string): SQL =>
+	isTrigramIndexable(term)
+		? ftsRowidMatch(`subject : ${ftsPhrase(term)}`)
+		: sql`${SQLITE_SUBJECT_FOLDED} like ${sqliteLikePattern(term)} escape '\\'`;
+
+const sqliteFromMatch = (term: string): SQL =>
+	isTrigramIndexable(term)
+		? ftsRowidMatch(`sender : ${ftsPhrase(term)}`)
+		: sql`${SQLITE_FROM_FOLDED} like ${sqliteLikePattern(term)} escape '\\'`;
+
+// ─── Dialect selection ───────────────────────────────────────────────────────
+
+export const subjectMatch = (term: string): SQL =>
+	isSqlite() ? sqliteSubjectMatch(term) : pgSubjectMatch(term);
+
+export const fromMatch = (term: string): SQL =>
+	isSqlite() ? sqliteFromMatch(term) : pgFromMatch(term);

package/src/repos/unit-of-work.sqlite.test.ts

@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { eq } from "drizzle-orm";
+import {
+	envelopeId as deriveEnvelopeId,
+	rootBodyPartId as deriveRootBodyPartId,
+} from "../id.js";
+import { addressTable } from "../schema/i4-address.js";
+import {
+	type MessageDataSchema,
+	messageDataSchema,
+	messageTable,
+} from "../schema/message-data.js";
+import { threadMessageTable } from "../schema/thread-message.js";
+import { createSqliteTestDb, type SqliteTestDb } from "../test-db-sqlite.js";
+import { DrizzleUnitOfWork } from "./unit-of-work.js";
+
+// The unit-of-work runs its write set inside one SAVEPOINT on sqlite (RFC 036
+// D1) — and each repo's own `create` opens a nested SAVEPOINT, so this also
+// covers savepoint nesting. Commit persists the whole set; a throw rolls all of
+// it back, message and thread-message together.
+
+const SCHEMA = {
+	...messageDataSchema,
+	threadMessage: threadMessageTable,
+	address: addressTable,
+};
+
+describe("DrizzleUnitOfWork (sqlite)", () => {
+	let db: SqliteTestDb<MessageDataSchema>;
+	let close: () => Promise<void>;
+	let uow: DrizzleUnitOfWork;
+
+	before(async () => {
+		({ db, close } = await createSqliteTestDb<MessageDataSchema>(SCHEMA));
+		uow = new DrizzleUnitOfWork(db);
+	});
+
+	after(async () => {
+		await close();
+	});
+
+	const messageInput = (id: string) => ({
+		messageId: id,
+		mailboxId: "00000000-0000-0000-3333-000000000002",
+		uid: 7,
+		sequenceNumber: 1,
+		rfc822Size: 512,
+		internalDate: 1700000000000,
+		envelopeId: deriveEnvelopeId(id),
+		rootBodyPartId: deriveRootBodyPartId(id),
+		status: "active" as const,
+		syncStatus: "synced" as const,
+	});
+
+	const threadInput = (id: string) => ({
+		accountConfigId: "acct-1",
+		threadId: `thread-${id}`,
+		messageId: id,
+		mailboxId: "mbx-1",
+		uid: 7,
+		referenceOrder: 0,
+		internalDate: 1700000000000,
+		sentDate: 1700000000000,
+		isRead: false,
+		isDeleted: false,
+		hasAttachment: false,
+		hasStars: false,
+	});
+
+	test("commits message + thread-message together", async () => {
+		const id = "00000000-0000-0000-3333-000000000010";
+		await uow.transaction(async (repos) => {
+			await repos.message.create(messageInput(id));
+			await repos.threadMessage.create(threadInput(id));
+		});
+
+		const msg = await db
+			.select()
+			.from(messageTable)
+			.where(eq(messageTable.messageId, id));
+		const thread = await db
+			.select()
+			.from(threadMessageTable)
+			.where(eq(threadMessageTable.messageId, id));
+		assert.equal(msg.length, 1);
+		assert.equal(thread.length, 1);
+	});
+
+	test("a throw rolls the whole set back", async () => {
+		const id = "00000000-0000-0000-3333-000000000011";
+		await assert.rejects(() =>
+			uow.transaction(async (repos) => {
+				await repos.message.create(messageInput(id));
+				await repos.threadMessage.create(threadInput(id));
+				throw new Error("boom");
+			}),
+		);
+
+		const msg = await db
+			.select()
+			.from(messageTable)
+			.where(eq(messageTable.messageId, id));
+		const thread = await db
+			.select()
+			.from(threadMessageTable)
+			.where(eq(threadMessageTable.messageId, id));
+		assert.equal(msg.length, 0, "message insert must roll back");
+		assert.equal(thread.length, 0, "thread-message insert must roll back");
+	});
+
+	test("concurrent transactions serialize without corrupting savepoints", async () => {
+		const ids = Array.from(
+			{ length: 12 },
+			(_, i) =>
+				`00000000-0000-0000-3333-0000000001${i.toString().padStart(2, "0")}`,
+		);
+
+		// The failure this guards: shared-connection savepoint interleaving when
+		// callers run under concurrency (message-sync's pMap). All must commit.
+		await Promise.all(
+			ids.map((id) =>
+				uow.transaction(async (repos) => {
+					await repos.message.create(messageInput(id));
+					await repos.threadMessage.create(threadInput(id));
+				}),
+			),
+		);
+
+		for (const id of ids) {
+			const msg = await db
+				.select()
+				.from(messageTable)
+				.where(eq(messageTable.messageId, id));
+			assert.equal(msg.length, 1, `message ${id} must be committed`);
+		}
+	});
+});

package/src/repos/unit-of-work.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { eq } from "drizzle-orm";
+import {
+	envelopeId as deriveEnvelopeId,
+	rootBodyPartId as deriveRootBodyPartId,
+} from "../id.js";
+import {
+	envelopeTable,
+	messageTable,
+	outboxTable,
+} from "../schema/message-data.js";
+import { createTestDb, type TestDb } from "./test-helpers.js";
+import { DrizzleUnitOfWork } from "./unit-of-work.js";
+
+describe("DrizzleUnitOfWork", () => {
+	let db: TestDb;
+	let stop: () => Promise<void>;
+	let unitOfWork: DrizzleUnitOfWork;
+
+	const MESSAGE_ID = "00000000-0000-0000-2222-000000000001";
+	const MAILBOX_ID = "00000000-0000-0000-2222-000000000002";
+	const NOW = 1700000000000;
+
+	const writeEnvelopeAndMessage = async (
+		repos: Parameters<Parameters<DrizzleUnitOfWork["transaction"]>[0]>[0],
+	) => {
+		await repos.envelope.upsertEnvelope({
+			envelopeId: deriveEnvelopeId(MESSAGE_ID),
+			messageId: MESSAGE_ID,
+			dateValue: NOW,
+			dateRaw: "Tue, 14 Nov 2023 22:13:20 +0000",
+			subject: "hello",
+			messageIdValue: "<hello@example.com>",
+		});
+		await repos.message.upsertWithStatus({
+			messageId: MESSAGE_ID,
+			mailboxId: MAILBOX_ID,
+			uid: 7,
+			sequenceNumber: 1,
+			rfc822Size: 1024,
+			internalDate: NOW,
+			envelopeId: deriveEnvelopeId(MESSAGE_ID),
+			rootBodyPartId: deriveRootBodyPartId(MESSAGE_ID),
+		});
+	};
+
+	const rows = async () => {
+		const envelopes = await db
+			.select()
+			.from(envelopeTable)
+			.where(eq(envelopeTable.messageId, MESSAGE_ID));
+		const messages = await db
+			.select()
+			.from(messageTable)
+			.where(eq(messageTable.messageId, MESSAGE_ID));
+		const outbox = await db
+			.select()
+			.from(outboxTable)
+			.where(eq(outboxTable.messageId, MESSAGE_ID));
+		return { envelopes, messages, outbox };
+	};
+
+	before(async () => {
+		({ db, stop } = await createTestDb());
+		unitOfWork = new DrizzleUnitOfWork(db);
+	});
+
+	after(async () => {
+		await stop();
+	});
+
+	test("a mid-save throw rolls back the whole write set, outbox included", async () => {
+		await assert.rejects(
+			() =>
+				unitOfWork.transaction(async (repos) => {
+					await writeEnvelopeAndMessage(repos);
+					// A later write in the set fails after the envelope, message and its
+					// transactional-outbox row have already been written.
+					throw new Error("thread write failed");
+				}),
+			/thread write failed/,
+		);
+
+		const { envelopes, messages, outbox } = await rows();
+		assert.equal(envelopes.length, 0, "envelope must be rolled back");
+		assert.equal(messages.length, 0, "message must be rolled back");
+		assert.equal(
+			outbox.length,
+			0,
+			"outbox row must be rolled back with the message",
+		);
+	});
+
+	test("a successful transaction commits the data rows and the outbox row", async () => {
+		await unitOfWork.transaction(writeEnvelopeAndMessage);
+
+		const { envelopes, messages, outbox } = await rows();
+		assert.equal(envelopes.length, 1);
+		assert.equal(messages.length, 1);
+		assert.equal(outbox.length, 1);
+		assert.equal(outbox[0].event, "message.created");
+		assert.deepStrictEqual(outbox[0].payload, { messageId: MESSAGE_ID });
+	});
+});

package/src/repos/unit-of-work.ts

@@ -0,0 +1,31 @@
+import type { IUnitOfWork, UnitOfWorkRepositories } from "@remit/data-ports";
+import type { Db } from "../db.js";
+import type { MessageDataSchema } from "../schema/message-data.js";
+import { runInTransaction } from "../tx.js";
+import { DrizzleEnvelopeRepository } from "./envelope.js";
+import { AddressRepo } from "./i4-address.js";
+import { DrizzleMessageRepository } from "./message.js";
+import { DrizzleThreadMessageRepository } from "./thread-message.js";
+
+/**
+ * Runs a write set inside a single Postgres transaction. The repositories handed
+ * to the callback are bound to that transaction, so the data rows and the
+ * transactional-outbox rows the message write appends commit atomically — a
+ * throw anywhere rolls the whole set back, outbox included.
+ */
+export class DrizzleUnitOfWork implements IUnitOfWork {
+	constructor(private db: Db<MessageDataSchema>) {}
+
+	transaction<T>(
+		fn: (repos: UnitOfWorkRepositories) => Promise<T>,
+	): Promise<T> {
+		return runInTransaction(this.db, (tx) =>
+			fn({
+				message: new DrizzleMessageRepository(tx),
+				envelope: new DrizzleEnvelopeRepository(tx),
+				address: new AddressRepo(tx),
+				threadMessage: new DrizzleThreadMessageRepository(tx),
+			}),
+		);
+	}
+}

package/src/schema/active-entities.ts

@@ -0,0 +1,19 @@
+// The dialect-selected entity table set (RFC 036 D1). Both generated packages
+// export the same table symbols under the same names — they differ only in the
+// column builders (`pgTable`/`jsonb`/`timestamp` vs `sqliteTable`/`text(json)`/
+// `integer`). A process runs one dialect (see ../dialect.ts), so the active set
+// is chosen once here and re-exported through the schema facades the repos
+// import from.
+//
+// The cast to the Postgres module type is the single "typing loosens at the
+// injection boundary" point RFC 036 D1 names: the repos are written once
+// against the Postgres-typed shape, and at runtime the SQLite tables carry
+// their own dialect so the queries generate the correct SQL. The backend
+// already crosses this boundary with a cast on the db handle.
+import * as pgEntities from "@remit/drizzle-pg-schema";
+import * as sqliteEntities from "@remit/drizzle-sqlite-schema";
+import { isSqlite } from "../dialect.js";
+
+export const entities: typeof pgEntities = isSqlite()
+	? (sqliteEntities as unknown as typeof pgEntities)
+	: pgEntities;

package/src/schema/i4-account-config.ts

@@ -0,0 +1,4 @@
+import { entities } from "./active-entities.js";
+
+export const accountConfigTable = entities.accountConfigs;
+export const accountTable = entities.accounts;

package/src/schema/i4-account-export-request.ts

@@ -0,0 +1,3 @@
+import { entities } from "./active-entities.js";
+
+export const accountExportRequestTable = entities.accountExportRequests;

package/src/schema/i4-account-setting.ts

@@ -0,0 +1,3 @@
+import { entities } from "./active-entities.js";
+
+export const accountSettingTable = entities.accountSettings;

package/src/schema/i4-address.ts

@@ -0,0 +1,3 @@
+import { entities } from "./active-entities.js";
+
+export const addressTable = entities.addresses;

package/src/schema/i4-mailbox-lock.ts

@@ -0,0 +1,3 @@
+import { entities } from "./active-entities.js";
+
+export const mailboxLockTable = entities.mailboxLocks;

package/src/schema/i4-mailbox.ts

@@ -0,0 +1,4 @@
+import { entities } from "./active-entities.js";
+
+export const mailboxTable = entities.mailboxes;
+export const mailboxSpecialUseTable = entities.mailboxSpecialUseEntries;

package/src/schema/i4-message-flag-push.ts

@@ -0,0 +1,3 @@
+import { entities } from "./active-entities.js";
+
+export const messageFlagPushTable = entities.messageFlagPushes;

package/src/schema/i4-message-placement-move.ts

@@ -0,0 +1,3 @@
+import { entities } from "./active-entities.js";
+
+export const messagePlacementMoveTable = entities.messagePlacementMoves;

package/src/schema/i4-organize-job-request.ts

@@ -0,0 +1 @@
+export { organizeJobRequests as organizeJobRequestTable } from "@remit/drizzle-pg-schema";

package/src/schema/i4-outbox-message.ts

@@ -0,0 +1,3 @@
+import { entities } from "./active-entities.js";
+
+export const outboxMessageTable = entities.outboxMessages;

package/src/schema/message-data.ts

@@ -0,0 +1,44 @@
+import { entities } from "./active-entities.js";
+import { outboxTable } from "./outbox.js";
+
+export { outboxTable };
+
+const bodyPartContentTable = entities.bodyPartContents;
+const bodyPartParameterTable = entities.bodyPartParameters;
+const bodyPartStorageTable = entities.bodyPartStorages;
+const bodyPartTable = entities.bodyParts;
+const envelopeAddressTable = entities.envelopeAddresses;
+const envelopeTable = entities.envelopes;
+const messageFlagTable = entities.messageFlags;
+const messageReferenceTable = entities.messageReferences;
+const messageTable = entities.messages;
+const rawMessageStorageTable = entities.rawMessageStorages;
+
+export {
+	bodyPartContentTable,
+	bodyPartParameterTable,
+	bodyPartStorageTable,
+	bodyPartTable,
+	envelopeAddressTable,
+	envelopeTable,
+	messageFlagTable,
+	messageReferenceTable,
+	messageTable,
+	rawMessageStorageTable,
+};
+
+export const messageDataSchema = {
+	envelope: envelopeTable,
+	messageReference: messageReferenceTable,
+	envelopeAddress: envelopeAddressTable,
+	bodyPart: bodyPartTable,
+	bodyPartParameter: bodyPartParameterTable,
+	rawMessageStorage: rawMessageStorageTable,
+	bodyPartStorage: bodyPartStorageTable,
+	bodyPartContent: bodyPartContentTable,
+	message: messageTable,
+	messageFlag: messageFlagTable,
+	outbox: outboxTable,
+};
+
+export type MessageDataSchema = typeof messageDataSchema;

package/src/schema/outbox.ts

@@ -0,0 +1,74 @@
+import { sql } from "drizzle-orm";
+import {
+	bigint,
+	jsonb,
+	index as pgIndex,
+	pgTable,
+	text as pgText,
+	timestamp,
+	uuid,
+} from "drizzle-orm/pg-core";
+import {
+	index as sqliteIndex,
+	integer as sqliteInteger,
+	sqliteTable,
+	text as sqliteText,
+} from "drizzle-orm/sqlite-core";
+import { isSqlite } from "../dialect.js";
+
+/**
+ * Transactional outbox. It has no TypeSpec entity — it is infrastructure for
+ * the search-index worker (append a row per body change / move, drain by id,
+ * mark `processed_at`). The partial index selects unprocessed rows for the
+ * boot-time backstop scan (Postgres) and the short-cadence poll (SQLite,
+ * RFC 036 D2). It is hand-written per dialect because the two column-builder
+ * sets share no surface; both keep identical column names so the repos and the
+ * drain logic read the same rows on either backend.
+ *
+ * Both raw tables are exported for committed-migration generation (schema-full
+ * per dialect). The runtime `outboxTable` is the dialect-selected one, cast to
+ * the Postgres type so the repos keep one static shape (RFC 036 D1).
+ */
+export const pgOutboxTable = pgTable(
+	"outbox",
+	{
+		id: uuid("id").primaryKey(),
+		messageId: pgText("message_id").notNull(),
+		event: pgText("event").notNull(),
+		payload: jsonb("payload").notNull(),
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		processedAt: bigint("processed_at", { mode: "number" }),
+	},
+	(t) => [
+		pgIndex("outbox_message_id_idx").on(t.messageId),
+		pgIndex("outbox_unprocessed_idx")
+			.on(t.createdAt)
+			.where(sql`${t.processedAt} IS NULL`),
+	],
+);
+
+export const sqliteOutboxTable = sqliteTable(
+	"outbox",
+	{
+		id: sqliteText("id").primaryKey(),
+		messageId: sqliteText("message_id").notNull(),
+		event: sqliteText("event").notNull(),
+		payload: sqliteText("payload", { mode: "json" }).notNull(),
+		createdAt: sqliteInteger("created_at", { mode: "timestamp_ms" })
+			.$defaultFn(() => new Date())
+			.notNull(),
+		processedAt: sqliteInteger("processed_at", { mode: "number" }),
+	},
+	(t) => [
+		sqliteIndex("outbox_message_id_idx").on(t.messageId),
+		sqliteIndex("outbox_unprocessed_idx")
+			.on(t.createdAt)
+			.where(sql`${t.processedAt} IS NULL`),
+	],
+);
+
+export const outboxTable: typeof pgOutboxTable = isSqlite()
+	? (sqliteOutboxTable as unknown as typeof pgOutboxTable)
+	: pgOutboxTable;

package/src/schema/thread-message.ts

@@ -0,0 +1,3 @@
+import { entities } from "./active-entities.js";
+
+export const threadMessageTable = entities.threadMessages;

package/src/schema-full-sqlite.ts

@@ -0,0 +1,11 @@
+// Complete SQLite drizzle schema for committed-migration GENERATION only
+// (RFC 036 D5) — consumed by deploy/vps/migrate/drizzle.entities.sqlite.config.ts
+// and the drift guard (npm-scripts/check-vps-migrations.mjs), never at runtime.
+//
+// The SQLite twin of schema-full.ts: the sqlite-dialect entity package
+// wholesale (`sqliteTable`/`text(json)`/`integer`) plus the raw sqlite outbox
+// infra table. Kept separate from the runtime facade (../schema/active-entities)
+// because drizzle-kit's `generate --dialect sqlite` needs the real sqlite table
+// objects, not the pg-cast the repos consume.
+export * from "@remit/drizzle-sqlite-schema";
+export { sqliteOutboxTable as outboxTable } from "./schema/outbox.js";

package/src/schema-full.ts

@@ -0,0 +1,16 @@
+// Complete Postgres drizzle schema for committed-migration GENERATION only —
+// consumed by deploy/vps/migrate/drizzle.entities.config.ts and the drift guard
+// (npm-scripts/check-vps-migrations.mjs), never by `pushSchema`.
+//
+// It pulls the generated entity package in wholesale, so a new TypeSpec entity
+// flows into the committed migration with nothing to hand-maintain — the
+// omission that let eight tables drift out of the deployed schema. The only
+// addition is the `outbox` infra table, which has no entity. This file imports
+// the raw pg outbox directly (not the dialect-selected `outboxTable`), so
+// migration generation never depends on the runtime `DATA_BACKEND`.
+//
+// schema.ts stays the app/dev surface (single `*Table` alias per table, what
+// the repos and `pushSchema` need); this file exposes canonical names, so it
+// must not be fed to `pushSchema` alongside schema.ts (duplicate index names).
+export * from "@remit/drizzle-pg-schema";
+export { pgOutboxTable as outboxTable } from "./schema/outbox.js";

package/src/schema.ts

@@ -0,0 +1,28 @@
+// App/dev-facing drizzle schema: every table under a single `*Table` alias,
+// the names the repos and `pushSchema` (test-db.ts) consume. Each table appears
+// exactly once here — `pushSchema` registers a table's indexes per exported
+// binding, so exposing one table under two names creates duplicate index names
+// and breaks `apply()`. The committed-migration `generate` reads schema-full.ts
+// instead (the entity package wholesale), so the migration is driven by the
+// entities, not by this hand-maintained alias list.
+
+import { entities } from "./schema/active-entities.js";
+
+export const filterAnchorTable = entities.filterAnchors;
+export const filterTable = entities.filters;
+export const labelTable = entities.labels;
+export const mailboxAttributeEntryTable = entities.mailboxAttributeEntries;
+export const mailboxFlagTable = entities.mailboxFlags;
+export const messageLabelTable = entities.messageLabels;
+export * from "./schema/i4-account-config.js";
+export * from "./schema/i4-account-export-request.js";
+export * from "./schema/i4-account-setting.js";
+export * from "./schema/i4-address.js";
+export * from "./schema/i4-mailbox.js";
+export * from "./schema/i4-mailbox-lock.js";
+export * from "./schema/i4-message-flag-push.js";
+export * from "./schema/i4-message-placement-move.js";
+export * from "./schema/i4-organize-job-request.js";
+export * from "./schema/i4-outbox-message.js";
+export * from "./schema/message-data.js";
+export { threadMessageTable } from "./schema/thread-message.js";

package/src/sqlite-client.ts

@@ -0,0 +1,52 @@
+import type { Db } from "./db.js";
+import { serializeSqliteWrites } from "./tx.js";
+
+// The one place a SQLite connection is opened for the app (RFC 036 D3). Every
+// writer container (backend, imap-worker, smtp-worker, account-worker) opens the
+// same file here with the same cross-process settings — WAL for concurrent
+// readers, a 5 s busy_timeout so a writer waits out another's short transaction
+// instead of failing, synchronous=NORMAL (durable under WAL), foreign keys on.
+//
+// The handle is wrapped by `serializeSqliteWrites` before it leaves this
+// function, so a repo's insert/update/delete cannot bypass the in-process write
+// serialization (RFC 036 D3). `run`/`transaction`/reads pass through by design —
+// see the wrapper's comment.
+//
+// better-sqlite3 and its drizzle driver are imported dynamically so the Postgres
+// path never loads the native binding, and so the whole module stays out of the
+// DynamoDB Lambda bundle (this package is `external` there — see
+// remit-backend/src/service/dynamodb.ts).
+
+export interface SqliteClientOptions {
+	filename: string;
+}
+
+export interface SqliteClient<TSchema extends Record<string, unknown>> {
+	db: Db<TSchema>;
+	close: () => Promise<void>;
+}
+
+export async function createSqliteDatabase<
+	TSchema extends Record<string, unknown>,
+>(
+	schema: TSchema,
+	options: SqliteClientOptions,
+): Promise<SqliteClient<TSchema>> {
+	const { default: Database } = await import("better-sqlite3");
+	const { drizzle } = await import("drizzle-orm/better-sqlite3");
+
+	const sqlite = new Database(options.filename);
+	sqlite.pragma("journal_mode = WAL");
+	sqlite.pragma("busy_timeout = 5000");
+	sqlite.pragma("synchronous = NORMAL");
+	sqlite.pragma("foreign_keys = ON");
+
+	const base = drizzle(sqlite, { schema }) as unknown as Db<TSchema>;
+
+	return {
+		db: serializeSqliteWrites(base),
+		close: async () => {
+			sqlite.close();
+		},
+	};
+}