better-ship 0.3.2 → 0.4.0

package/src/application/message-already-processed.error.ts

@@ -0,0 +1,33 @@
+import { AppError, DatabaseError } from '@/core'
+
+import type { MessageId } from './messages.ts'
+
+/** The message's effects already committed. A caller can skip duplicate delivery without repeating those effects. */
+export class MessageAlreadyProcessedError extends AppError {
+  readonly _tag = 'MessageAlreadyProcessedError'
+  readonly classification = 'terminal'
+
+  constructor(
+    readonly messageId: MessageId,
+    options?: { readonly cause: unknown },
+  ) {
+    super(`message ${messageId} already processed`, options)
+  }
+
+  /** Recognize only the processed-message primary key; preserve other failures unchanged at the call site. */
+  static from(cause: unknown, messageId: MessageId): MessageAlreadyProcessedError | undefined {
+    if (cause instanceof MessageAlreadyProcessedError) return cause
+    if (!(cause instanceof DatabaseError)) return undefined
+    const details = cause.details
+    const duplicate =
+      details.database === 'd1'
+        ? details.kind === 'unique' &&
+          details.table === 'processed_messages' &&
+          details.column === 'message_id'
+        : details.code === '23505' &&
+          details.table_name === 'processed_messages' &&
+          details.constraint_name === 'processed_messages_pkey'
+    if (!duplicate) return undefined
+    return new MessageAlreadyProcessedError(messageId, { cause })
+  }
+}

package/src/application/message-bus.ts

@@ -2,7 +2,7 @@ import { panic } from 'better-result'
 
 import { createLogger, unreachable } from '@/core'
 
-import { DuplicateMessageError } from './message-bus.errors.ts'
+import { MessageAlreadyProcessedError } from './message-already-processed.error.ts'
 import type { Command, Event, Message, Query } from './messages.ts'
 import type { Handlers, MessageResult, RegistryMessage } from './registry.ts'
 
@@ -60,7 +60,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
 
   /**
    * Every subscriber runs to completion. One failure is rethrown as is. Several are thrown as
-   * one `AggregateError`. A `DuplicateMessageError` means that subscriber already committed on
+   * one `AggregateError`. A `MessageAlreadyProcessedError` means that subscriber already committed on
    * an earlier delivery, so it counts as delivered.
    */
   private async handleEvent(event: Event): Promise<void> {
@@ -71,7 +71,7 @@ export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMess
     const failures: unknown[] = []
     for (const [subscriber, outcome] of outcomes.entries()) {
       if (outcome.status === 'fulfilled') continue
-      if (outcome.reason instanceof DuplicateMessageError) {
+      if (outcome.reason instanceof MessageAlreadyProcessedError) {
         // The bus swallows this error, so this line is the only record that the skip happened.
         logger.info('duplicate_subscriber_ignored', { event: event.name, id: event.id, subscriber })
         continue

package/src/application/message-store.ts

@@ -0,0 +1,12 @@
+import type { Event, MessageId } from './messages.ts'
+
+/**
+ * Stores processed messages and outgoing events in the same transaction as application writes.
+ * One adapter per database, built on the boundary like every other repository.
+ */
+export interface IMessageStore {
+  /** Record this message in the transaction; reject an existing record with `MessageAlreadyProcessedError`. */
+  claim(messageId: MessageId): Promise<void>
+  /** Write the events to the outbox, inside the same boundary as the state change. */
+  persistEvents(events: ReadonlyArray<Event>): Promise<void>
+}

package/src/application/outbox-relay.ts

@@ -0,0 +1,8 @@
+/**
+ * Delivers committed outbox rows. The unit of work only wakes it after a commit that wrote
+ * events; the app decides what a wake is: `waitUntil`, a Durable Object alarm, nothing.
+ * The sweep is the source of truth, so a lost wake loses no events.
+ */
+export interface IOutboxRelay {
+  wake(): void
+}

package/src/application/transaction.ts

@@ -0,0 +1,8 @@
+/**
+ * Supplies `Tx` to participating repositories and resolves after their writes commit. Failure rolls back or discards writes.
+ * Nested calls reject with `UnitOfWorkAlreadyActiveError` before opening another boundary.
+ * Independent concurrent calls are allowed.
+ */
+export interface ITransaction<Tx> {
+  transaction<T>(work: (tx: Tx) => Promise<T>): Promise<T>
+}

package/src/application/unit-of-work.errors.ts

@@ -0,0 +1,11 @@
+import { AppError } from '@/core'
+
+/** A boundary was opened inside another. One message, one atomic scope. */
+export class UnitOfWorkAlreadyActiveError extends AppError {
+  readonly _tag = 'UnitOfWorkAlreadyActiveError'
+  readonly classification = 'terminal'
+
+  constructor() {
+    super('a unit of work is already active')
+  }
+}

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

@@ -0,0 +1,54 @@
+import type { IEventCollector } from './event-collector.ts'
+import { MessageAlreadyProcessedError } from './message-already-processed.error.ts'
+import type { IMessageStore } from './message-store.ts'
+import type { MessageId } from './messages.ts'
+import type { IOutboxRelay } from './outbox-relay.ts'
+import type { ITransaction } from './transaction.ts'
+
+/**
+ * Commits the processed-message record, repository writes, and emitted events together before resolving.
+ * An existing record rejects with `MessageAlreadyProcessedError`; external effects must run through the outbox after commit.
+ * Nested calls reject with `UnitOfWorkAlreadyActiveError`; independent concurrent calls are allowed.
+ */
+export interface IUnitOfWork<Repos> {
+  run<T>(messageId: MessageId, work: (repos: Repos) => Promise<T>): Promise<T>
+}
+
+export type UnitOfWorkDeps<Tx, Repos> = {
+  readonly transaction: ITransaction<Tx>
+  /** The processed-messages and outbox repository for this transaction. */
+  readonly messageStore: (tx: Tx) => IMessageStore
+  /** Repositories participate in the current transaction. */
+  readonly createRepositories: (tx: Tx) => Repos
+  readonly eventCollector: IEventCollector
+  readonly relay: IOutboxRelay
+}
+
+/** The unit of work: the boundary, the repositories, the events. Every database call is a port. */
+export class UnitOfWork<Tx, Repos> implements IUnitOfWork<Repos> {
+  constructor(private readonly deps: UnitOfWorkDeps<Tx, Repos>) {}
+
+  async run<T>(messageId: MessageId, work: (repos: Repos) => Promise<T>): Promise<T> {
+    const { transaction, messageStore, createRepositories, eventCollector, relay } = this.deps
+    let written = 0
+
+    let value: T
+    try {
+      value = await transaction.transaction(async (tx) => {
+        const store = messageStore(tx)
+        await store.claim(messageId)
+        const repos = createRepositories(tx)
+        const result = await work(repos)
+        const pending = eventCollector.collect()
+        await store.persistEvents(pending)
+        written = pending.length
+        return result
+      })
+    } catch (error) {
+      throw MessageAlreadyProcessedError.from(error, messageId) ?? error
+    }
+
+    if (written > 0) relay.wake()
+    return value
+  }
+}

package/src/core/database.error.ts

@@ -0,0 +1,37 @@
+import { AppError } from './app-error.ts'
+import type { FailureClassification } from './failure-classification.ts'
+
+/** SQLite reports these constraint categories through D1. */
+export type D1ConstraintKind = 'unique' | 'not_null' | 'foreign_key' | 'check'
+
+/** Database evidence for callers that interpret a specific code or constraint. */
+export type DatabaseFailure =
+  | {
+      readonly database: 'd1'
+      readonly code: string | undefined
+      readonly kind: D1ConstraintKind | undefined
+      readonly table: string | undefined
+      readonly column: string | undefined
+      readonly constraintName: string | undefined
+    }
+  | {
+      readonly database: 'postgres'
+      readonly code: string | undefined
+      readonly table_name: string | undefined
+      readonly column_name: string | undefined
+      readonly constraint_name: string | undefined
+    }
+
+/** Classification describes the failure; callers must separately establish whether repetition is safe. */
+export class DatabaseError extends AppError {
+  readonly _tag = 'DatabaseError'
+
+  constructor(
+    readonly operation: string,
+    readonly classification: FailureClassification,
+    readonly details: DatabaseFailure,
+    options: { readonly cause: unknown },
+  ) {
+    super(`Database operation failed: ${operation}`, options)
+  }
+}

package/src/core/index.ts

@@ -1,4 +1,5 @@
 export { AppError } from './app-error.ts'
+export { DatabaseError, type DatabaseFailure, type D1ConstraintKind } from './database.error.ts'
 export { notImplemented, unreachable } from './defects.ts'
 export {
   shouldRetryFailure,

package/src/infrastructure/cloudflare/base-d1-repository.ts

@@ -0,0 +1,40 @@
+import type { BatchItem } from 'drizzle-orm/batch'
+
+import type { Event } from '@/application'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+import { eventCollector, stageD1Statement } from '../unit-of-work-context.ts'
+import { executeDatabase } from './d1-database-execution.ts'
+import type { D1Db } from './d1-database-types.ts'
+
+/** A domain aggregate that accumulates events for the unit of work to drain. */
+export interface AggregateEvents {
+  collectEvents(): ReadonlyArray<Event>
+  clearEvents(): void
+}
+
+/**
+ * Shared plumbing for a repository that writes inside a D1 unit of work.
+ * Writes are staged, never run; the boundary commits them as one batch. Reads run on `db` now.
+ */
+export abstract class BaseD1Repository<Schema extends DrizzleSchema> {
+  constructor(protected readonly db: D1Db<Schema>) {}
+
+  /** Add a statement to the current D1 batch without executing it. */
+  protected stage(statement: BatchItem<'sqlite'>): void {
+    stageD1Statement(statement)
+  }
+
+  /** Execute one read with database error conversion and no automatic retries. */
+  protected read<T>(operation: string, query: () => PromiseLike<T>): Promise<T> {
+    return executeDatabase(operation, query)
+  }
+
+  /** Drain an aggregate's pending events into the active boundary. */
+  protected dispatchEvents(aggregate: AggregateEvents): void {
+    const events = aggregate.collectEvents()
+    if (events.length === 0) return
+    for (const event of events) eventCollector.emit(event)
+    aggregate.clearEvents()
+  }
+}

package/src/infrastructure/cloudflare/classify-d1-error.ts

@@ -0,0 +1,82 @@
+import { DrizzleQueryError } from 'drizzle-orm/errors'
+
+import { AppError, DatabaseError, type D1ConstraintKind, type FailureClassification } from '@/core'
+
+const KIND_BY_CODE: ReadonlyMap<string, D1ConstraintKind> = new Map([
+  ['SQLITE_CONSTRAINT_PRIMARYKEY', 'unique'],
+  ['SQLITE_CONSTRAINT_UNIQUE', 'unique'],
+  ['SQLITE_CONSTRAINT_NOTNULL', 'not_null'],
+  ['SQLITE_CONSTRAINT_FOREIGNKEY', 'foreign_key'],
+  ['SQLITE_CONSTRAINT_CHECK', 'check'],
+])
+
+const KIND_BY_PROSE: ReadonlyArray<readonly [string, D1ConstraintKind]> = [
+  ['UNIQUE constraint failed', 'unique'],
+  ['NOT NULL constraint failed', 'not_null'],
+  ['FOREIGN KEY constraint failed', 'foreign_key'],
+  ['CHECK constraint failed', 'check'],
+]
+
+/**
+ * Recognize D1 failures and preserve the original cause. Unrecognized callback exceptions remain unchanged.
+ * D1 exposes error codes and constraint locations in text, so parsing stays at this boundary.
+ */
+export function classifyD1Error(cause: unknown, operation = 'D1 query'): DatabaseError | undefined {
+  if (cause instanceof AppError || (cause instanceof Error && cause.name === 'AbortError'))
+    return undefined
+  const message = messagesOf(cause)
+  const kind = kindOf(message)
+  const classification = kind === undefined ? classificationOf(message) : 'terminal'
+  const code = message.match(/\b(?:SQLITE_[A-Z_]+|D1_[A-Z_]+)\b/)?.[0]
+  if (code === undefined && classification === 'unknown' && !(cause instanceof DrizzleQueryError))
+    return undefined
+  // A composite unique constraint must not be mistaken for the processed-message primary key.
+  const location = message.match(/constraint failed: (\w+)\.(\w+)(?=\s*(?::\s*SQLITE_|$|\n))/)
+  const check = kind === 'check' ? message.match(/CHECK constraint failed: ([A-Za-z_]\w*)/) : null
+  return new DatabaseError(
+    operation,
+    classification,
+    {
+      database: 'd1',
+      code,
+      kind,
+      table: location?.[1],
+      column: location?.[2],
+      constraintName: check?.[1],
+    },
+    { cause },
+  )
+}
+
+function kindOf(message: string): D1ConstraintKind | undefined {
+  const code = message.match(/SQLITE_CONSTRAINT_\w+/)?.[0]
+  if (code !== undefined) return KIND_BY_CODE.get(code)
+  return KIND_BY_PROSE.find(([prose]) => message.includes(prose))?.[1]
+}
+
+// Drizzle query messages contain SQL and values, which are not evidence about the database failure.
+function messagesOf(cause: unknown): string {
+  const messages: string[] = []
+  const seen = new Set<unknown>()
+  let current = cause
+  while (current instanceof Error && !seen.has(current)) {
+    seen.add(current)
+    if (!(current instanceof DrizzleQueryError)) messages.push(current.message)
+    current = current.cause
+  }
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- D1 can expose a raw string cause; this boundary accepts only that representation.
+  if (typeof current === 'string') messages.push(current)
+  return messages.join('\n')
+}
+
+// Cloudflare documents these conditions separately from transient storage resets.
+const TERMINAL_FAILURE =
+  /\bSQLITE_(?:ERROR|MISMATCH|TOOBIG|FULL|AUTH|PERM|READONLY)\b|\bD1_(?:TYPE_ERROR|COLUMN_NOTFOUND)\b|no such (?:table|column|function)|syntax error|datatype mismatch|exceeded (?:timeout|its memory limit|its CPU time limit|maximum DB size)|maximum account storage limit|free tier daily row (?:read|write) limit/i
+const TRANSIENT_FAILURE =
+  /Network connection lost\.|Replica disconnected from primary\.|D1 DB reset because its code was updated\.|Internal error (?:while starting up|in) D1 DB storage caused object to be reset\.|Cannot resolve D1 DB due to transient issue on remote node\.|Can't read from request stream because client disconnected\./i
+
+function classificationOf(message: string): FailureClassification {
+  if (TERMINAL_FAILURE.test(message)) return 'terminal'
+  if (TRANSIENT_FAILURE.test(message)) return 'transient'
+  return 'unknown'
+}

package/src/infrastructure/cloudflare/d1-batch-transaction.ts

@@ -0,0 +1,27 @@
+import type { ITransaction } from '@/application'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+import { collectD1Statements, runWithUnitOfWorkContext } from '../unit-of-work-context.ts'
+import { executeDatabase } from './d1-database-execution.ts'
+import type { D1Db, D1Tx } from './d1-database-types.ts'
+
+/**
+ * The D1 transaction boundary: every write is staged during `work` and committed as one
+ * `db.batch()`. A throw inside `work` means the batch never runs.
+ */
+export class D1BatchTransaction<Schema extends DrizzleSchema> implements ITransaction<
+  D1Tx<Schema>
+> {
+  constructor(private readonly db: D1Db<Schema>) {}
+
+  async transaction<T>(work: (tx: D1Tx<Schema>) => Promise<T>): Promise<T> {
+    return runWithUnitOfWorkContext('d1', async () => {
+      const value = await work({ db: this.db })
+      const [first, ...rest] = collectD1Statements()
+      if (first !== undefined) {
+        await executeDatabase('commit unit of work', () => this.db.batch([first, ...rest]))
+      }
+      return value
+    })
+  }
+}

package/src/infrastructure/cloudflare/d1-database-execution.ts

@@ -0,0 +1,13 @@
+import { classifyD1Error } from './classify-d1-error.ts'
+
+/** Execute once without retries; convert recognized D1 failures and preserve other exceptions unchanged. */
+export async function executeDatabase<T>(
+  operation: string,
+  work: () => PromiseLike<T>,
+): Promise<T> {
+  try {
+    return await work()
+  } catch (cause) {
+    throw classifyD1Error(cause, operation) ?? cause
+  }
+}

package/src/infrastructure/cloudflare/d1-database-types.ts

@@ -0,0 +1,20 @@
+import type { AnyD1Database, DrizzleD1Database } from 'drizzle-orm/d1'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+
+/** A D1 binding or local D1 client accepted by Drizzle. */
+export type D1Connection = AnyD1Database
+
+/** The application's Drizzle D1 database, preserving its schema and relational query types. */
+export type D1Db<Schema extends DrizzleSchema> = DrizzleD1Database<Schema>
+
+/** Exposes Drizzle query methods without insert, update, delete, batch, or raw execution methods. */
+export type D1ReadDb<Schema extends DrizzleSchema> = Pick<
+  D1Db<Schema>,
+  'select' | 'selectDistinct' | 'query'
+>
+
+/** D1 reads use this database; repository writes join the active batch through the unit-of-work context. */
+export type D1Tx<Schema extends DrizzleSchema> = {
+  readonly db: D1Db<Schema>
+}

package/src/infrastructure/cloudflare/d1-message-store.ts

@@ -0,0 +1,41 @@
+import { eq } from 'drizzle-orm'
+
+import {
+  MessageAlreadyProcessedError,
+  type Event,
+  type IMessageStore,
+  type MessageId,
+} from '@/application'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+import { BaseD1Repository } from './base-d1-repository.ts'
+import { messageOutbox, processedMessages } from './d1-schema.ts'
+
+/** Processed messages and outbox events share one D1 batch; the primary key prevents concurrent duplicate commits. */
+export class D1MessageStore<Schema extends DrizzleSchema>
+  extends BaseD1Repository<Schema>
+  implements IMessageStore
+{
+  async claim(messageId: MessageId): Promise<void> {
+    const processed = await this.read('claim message', () =>
+      this.db
+        .select({ messageId: processedMessages.messageId })
+        .from(processedMessages)
+        .where(eq(processedMessages.messageId, messageId))
+        .get(),
+    )
+    if (processed !== undefined) throw new MessageAlreadyProcessedError(messageId)
+
+    // Concurrent deliveries can pass the read; the primary key enforces the claim at commit.
+    this.stage(this.db.insert(processedMessages).values({ messageId }))
+  }
+
+  async persistEvents(events: ReadonlyArray<Event>): Promise<void> {
+    if (events.length === 0) return
+    this.stage(
+      this.db
+        .insert(messageOutbox)
+        .values(events.map((event) => ({ id: event.id, payload: event }))),
+    )
+  }
+}

package/src/infrastructure/cloudflare/d1-schema.ts

@@ -0,0 +1,43 @@
+import { sql } from 'drizzle-orm'
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+import type { Event } from '@/application'
+
+/** One row per committed message. The primary key is the idempotency claim. */
+export const processedMessages = sqliteTable(
+  'processed_messages',
+  {
+    messageId: text('message_id').primaryKey(),
+    processedAt: integer('processed_at', { mode: 'timestamp' })
+      .notNull()
+      .$defaultFn(() => new Date()),
+  },
+  (table) => [index('idx_processed_messages_processed_at').on(table.processedAt)],
+)
+
+/** Events committed with their state change, waiting for the relay to deliver them. */
+export const messageOutbox = sqliteTable(
+  'message_outbox',
+  {
+    id: text('id').primaryKey(),
+    payload: text('payload', { mode: 'json' }).$type<Event>().notNull(),
+    createdAt: integer('created_at', { mode: 'timestamp' })
+      .notNull()
+      .$defaultFn(() => new Date()),
+    availableAt: integer('available_at', { mode: 'timestamp' })
+      .notNull()
+      .$defaultFn(() => new Date()),
+    attempts: integer('attempts').notNull().default(0),
+    claimToken: text('claim_token'),
+    claimExpiresAt: integer('claim_expires_at', { mode: 'timestamp' }),
+    publishedAt: integer('published_at', { mode: 'timestamp' }),
+    failedAt: integer('failed_at', { mode: 'timestamp' }),
+    lastError: text('last_error'),
+  },
+  (table) => [
+    index('idx_message_outbox_due')
+      .on(table.availableAt, table.createdAt)
+      .where(sql`${table.publishedAt} IS NULL`),
+    index('idx_message_outbox_claim_token').on(table.claimToken),
+  ],
+)

package/src/infrastructure/cloudflare/index.ts

@@ -0,0 +1,9 @@
+export { BaseD1Repository, type AggregateEvents } from './base-d1-repository.ts'
+export { classifyD1Error } from './classify-d1-error.ts'
+export { D1MessageStore } from './d1-message-store.ts'
+export { messageOutbox, processedMessages } from './d1-schema.ts'
+export { D1BatchTransaction } from './d1-batch-transaction.ts'
+export type { D1Connection, D1Db, D1ReadDb, D1Tx } from './d1-database-types.ts'
+export { DatabaseError, type DatabaseFailure, type D1ConstraintKind } from '@/core'
+export { executeDatabase } from './d1-database-execution.ts'
+export { eventCollector } from '../unit-of-work-context.ts'

package/src/infrastructure/drizzle-schema.ts

@@ -0,0 +1,6 @@
+/**
+ * The app's drizzle schema: the tables it declared, keyed by name. This is drizzle's own
+ * constraint on every database and transaction type, restated once so the adapters name it.
+ */
+// oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- drizzle's constraint; the tables are the contract.
+export type DrizzleSchema = Record<string, unknown>

package/src/infrastructure/postgres/base-postgres-repository.ts

@@ -0,0 +1,30 @@
+import type { Event } from '@/application'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+import { eventCollector } from '../unit-of-work-context.ts'
+import { executeDatabase } from './postgres-database-execution.ts'
+import type { PostgresDbTransaction } from './postgres-database-types.ts'
+
+/** A domain aggregate that accumulates events for the unit of work to drain. */
+export interface AggregateEvents {
+  collectEvents(): ReadonlyArray<Event>
+  clearEvents(): void
+}
+
+/** Shared plumbing for a repository that writes inside a Postgres unit of work. */
+export abstract class BasePostgresRepository<Schema extends DrizzleSchema> {
+  constructor(protected readonly db: PostgresDbTransaction<Schema>) {}
+
+  /** Execute one read with database error conversion and no automatic retries. */
+  protected read<T>(operation: string, query: () => PromiseLike<T>): Promise<T> {
+    return executeDatabase(operation, query)
+  }
+
+  /** Drain an aggregate's pending events into the active boundary. */
+  protected dispatchEvents(aggregate: AggregateEvents): void {
+    const events = aggregate.collectEvents()
+    if (events.length === 0) return
+    for (const event of events) eventCollector.emit(event)
+    aggregate.clearEvents()
+  }
+}

package/src/infrastructure/postgres/classify-postgres-error.ts

@@ -0,0 +1,90 @@
+import { DrizzleQueryError } from 'drizzle-orm/errors'
+
+import { AppError, DatabaseError, type FailureClassification } from '@/core'
+
+const TRANSIENT_CODES = new Set([
+  '40001',
+  '40P01',
+  '08000',
+  '08001',
+  '08003',
+  '08006',
+  '57P01',
+  '57P02',
+  '57P03',
+  'CONNECT_TIMEOUT',
+  'CONNECTION_CLOSED',
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'EPIPE',
+  'ETIMEDOUT',
+  'EAI_AGAIN',
+])
+const TERMINAL_CODES = new Set(['57014', 'CONNECTION_ENDED', 'CONNECTION_DESTROYED', 'ECANCELED'])
+const DRIVER_CODES = new Set([
+  'CONNECT_TIMEOUT',
+  'CONNECTION_CLOSED',
+  'CONNECTION_ENDED',
+  'CONNECTION_DESTROYED',
+])
+const TERMINAL_CLASSES = new Set(['0A', '22', '23', '25', '28', '3D', '3F', '42', '54'])
+
+/* oxlint-disable anti-slop/no-runtime-typeof -- Raw driver exceptions have no shared schema; this boundary validates the fields it exposes. */
+/** Read SQLSTATE or driver codes; unknown callback exceptions remain unchanged. */
+export function classifyPostgresError(
+  cause: unknown,
+  operation: string,
+): DatabaseError | undefined {
+  let error = cause
+  const seen = new Set<unknown>()
+  while (error instanceof DrizzleQueryError && !seen.has(error)) {
+    seen.add(error)
+    error = error.cause
+  }
+  if (error instanceof AppError || (error instanceof Error && error.name === 'AbortError'))
+    return undefined
+  const code =
+    error instanceof Error && 'code' in error && typeof error.code === 'string'
+      ? error.code
+      : undefined
+  const serverError =
+    error instanceof Error &&
+    error.name === 'PostgresError' &&
+    code !== undefined &&
+    /^[0-9A-Z]{5}$/.test(code)
+  const driverError = code !== undefined && DRIVER_CODES.has(code)
+  if (!(cause instanceof DrizzleQueryError) && !serverError && !driverError) return undefined
+
+  return new DatabaseError(
+    operation,
+    classificationOf(code),
+    {
+      database: 'postgres',
+      code,
+      table_name:
+        error instanceof Error && 'table_name' in error && typeof error.table_name === 'string'
+          ? error.table_name
+          : undefined,
+      column_name:
+        error instanceof Error && 'column_name' in error && typeof error.column_name === 'string'
+          ? error.column_name
+          : undefined,
+      constraint_name:
+        error instanceof Error &&
+        'constraint_name' in error &&
+        typeof error.constraint_name === 'string'
+          ? error.constraint_name
+          : undefined,
+    },
+    { cause },
+  )
+}
+
+/* oxlint-enable anti-slop/no-runtime-typeof */
+
+function classificationOf(code: string | undefined): FailureClassification {
+  if (code === undefined) return 'unknown'
+  if (TRANSIENT_CODES.has(code)) return 'transient'
+  if (TERMINAL_CODES.has(code) || TERMINAL_CLASSES.has(code.slice(0, 2))) return 'terminal'
+  return 'unknown'
+}

package/src/infrastructure/postgres/index.ts

@@ -0,0 +1,15 @@
+export { BasePostgresRepository, type AggregateEvents } from './base-postgres-repository.ts'
+export { PostgresMessageStore } from './postgres-message-store.ts'
+export { messageOutbox, processedMessages } from './postgres-schema.ts'
+export { PostgresTransaction } from './postgres-transaction.ts'
+export type {
+  PostgresConnection,
+  PostgresDb,
+  PostgresReadDb,
+  PostgresDbTransaction,
+  PostgresTx,
+} from './postgres-database-types.ts'
+export { DatabaseError, type DatabaseFailure } from '@/core'
+export { executeDatabase } from './postgres-database-execution.ts'
+export { classifyPostgresError } from './classify-postgres-error.ts'
+export { eventCollector } from '../unit-of-work-context.ts'

package/src/infrastructure/postgres/postgres-database-execution.ts

@@ -0,0 +1,13 @@
+import { classifyPostgresError } from './classify-postgres-error.ts'
+
+/** Execute once without retries; convert recognized Postgres failures and preserve other exceptions unchanged. */
+export async function executeDatabase<T>(
+  operation: string,
+  work: () => PromiseLike<T>,
+): Promise<T> {
+  try {
+    return await work()
+  } catch (cause) {
+    throw classifyPostgresError(cause, operation) ?? cause
+  }
+}