@kronos-ts/postgres 0.1.1 → 0.2.0

package/src/postgres-event-scheduler.ts

@@ -0,0 +1,314 @@
+/**
+ * createPostgresEventScheduler — durable {@link EventScheduler} backed by
+ * the kronos_scheduled_events table, plus a polling worker that fires
+ * due schedules into the event store.
+ *
+ * # Schedule path (caller-driven, inside a UoW)
+ *
+ *   schedule(event, at)
+ *     → requires INVOCATION phase
+ *     → captures tags via the configured TagResolver at schedule-time
+ *     → INSERT row (schedule_id = event.identifier, status='pending')
+ *     → joins the active UoW transaction via getOrBeginActiveTransaction;
+ *       if the UoW rolls back, the schedule is never persisted
+ *     → returns { id: schedule_id } as the cancellation token
+ *
+ * # Cancel path
+ *
+ *   cancel(token)
+ *     → SELECT … FOR UPDATE to lock the row + read prior status
+ *     → branch:
+ *         status='pending'   → UPDATE status='cancelled'  → { kind: 'cancelled' }
+ *         status='appended'  → no UPDATE                  → { kind: 'already-appended' }
+ *         status='cancelled' → no UPDATE                  → { kind: 'not-found' }
+ *         no row             → no UPDATE                  → { kind: 'not-found' }
+ *     → cancel inside a UoW joins the active tx; outside, opens its own
+ *       adapter.transaction so the SELECT-FOR-UPDATE + UPDATE land atomically
+ *
+ * # Worker path (background)
+ *
+ *   start() spins a setInterval that, per tick, runs inside a fresh UoW:
+ *     1. force the lazy pg tx open via getOrBeginActiveTransaction
+ *     2. SELECT … WHERE status='pending' AND fire_at <= now()
+ *        ORDER BY fire_at LIMIT $batchSize FOR UPDATE SKIP LOCKED
+ *        — the SKIP LOCKED keeps multiple worker instances safe
+ *     3. for each row: reconstruct EventMessage, call eventStore.append
+ *        (which joins the same UoW tx), UPDATE status='appended'
+ *     4. UoW COMMIT → all appends + status flips land atomically
+ *
+ *   If the worker process dies mid-tick before COMMIT, the rows stay
+ *   'pending' and get re-picked on the next tick — at-least-once delivery.
+ *   The schedule_id is reused as event.identifier so the events table's
+ *   UNIQUE constraint dedupes any spurious double-append (e.g., on the
+ *   rare race where a previous COMMIT succeeded but the status UPDATE
+ *   failed afterwards — though here they share a tx, so this is mainly
+ *   a defensive note).
+ *
+ * # Multi-node safety
+ *
+ *   FOR UPDATE SKIP LOCKED is the locking primitive. Two worker processes
+ *   polling the same table will hand non-overlapping batches of rows to
+ *   their respective ticks; neither blocks the other. No leader election
+ *   or distributed lock is needed.
+ */
+
+import { qualifiedNameToString, qualifiedNameFromString } from "@kronos-ts/common"
+import type { EventMessage } from "@kronos-ts/messaging"
+import type {
+  EventScheduler,
+  ScheduleToken,
+  CancelResult,
+  UoWRunner,
+} from "@kronos-ts/messaging"
+import { getOrBeginActiveTransaction } from "@kronos-ts/messaging"
+// Deep-path import: requireInvocationPhase is intentionally not in the
+// messaging barrel — it's the framework-internal mutator guard consumed
+// by append/send/emitUpdate, and now schedule(). Same access pattern.
+import { requireInvocationPhase } from "@kronos-ts/messaging/processing-state"
+import type { EventStore } from "@kronos-ts/eventsourcing"
+import { IsolationLevel } from "./adapter.js"
+import type { PostgresAdapter, PostgresAdapterTransaction } from "./adapter.js"
+import { encodeTag } from "./criteria-sql.js"
+import { type TableNames, DEFAULT_TABLE_NAMES } from "./schema.js"
+import type { TagResolver } from "./postgres-event-store.js"
+
+export interface PostgresEventSchedulerConfig {
+  readonly adapter: PostgresAdapter
+  readonly eventStore: EventStore
+  /**
+   * The composed UoW runner the worker uses per tick — must be wrapped
+   * with {@link lazyTransactionalUnitOfWorkFactory} (or equivalent) so
+   * the worker's UoW sees the postgres tx. Typically the resolved
+   * `unitOfWorkFactory` slot.
+   */
+  readonly uowFactory: UoWRunner
+  readonly tagResolver: TagResolver
+  readonly tableNames?: TableNames
+  /**
+   * Worker poll interval. Defaults to 1000ms — a compromise between
+   * fire-latency and DB chatter. Production users wanting tighter
+   * latency should lower this, ideally combined with LISTEN/NOTIFY
+   * wake-up (not yet wired here).
+   */
+  readonly pollIntervalMs?: number
+  /** Max rows the worker processes per tick. Defaults to 50. */
+  readonly batchSize?: number
+}
+
+export interface PostgresEventScheduler extends EventScheduler {
+  /** Begin background polling. Idempotent. */
+  start(): Promise<void>
+  /** Stop polling. Resolves once the in-flight tick (if any) has settled. */
+  stop(): Promise<void>
+}
+
+interface ScheduleRow {
+  schedule_id: string
+  type: string
+  tags: string[]
+  payload: unknown
+  metadata: unknown
+  version: string
+  message_timestamp: string | number
+  [key: string]: unknown
+}
+
+export function createPostgresEventScheduler(
+  config: PostgresEventSchedulerConfig,
+): PostgresEventScheduler {
+  const { adapter, eventStore, uowFactory, tagResolver } = config
+  const tables = config.tableNames ?? DEFAULT_TABLE_NAMES
+  const pollIntervalMs = config.pollIntervalMs ?? 1000
+  const batchSize = config.batchSize ?? 50
+
+  async function insertSchedule(
+    tx: PostgresAdapterTransaction,
+    event: EventMessage,
+    at: Date,
+  ): Promise<string> {
+    const scheduleId = event.identifier
+    const encodedTags = tagResolver
+      .resolve(event)
+      .map((t) => encodeTag(t.key, t.value))
+    await tx.query(
+      `INSERT INTO ${tables.scheduled}
+         (schedule_id, fire_at, status, type, tags, payload, metadata, version, message_timestamp)
+       VALUES ($1, $2, 'pending', $3, $4, $5, $6, $7, $8)`,
+      [
+        scheduleId,
+        at.toISOString(),
+        qualifiedNameToString(event.name),
+        encodedTags,
+        JSON.stringify(event.payload ?? {}),
+        JSON.stringify(event.metadata ?? {}),
+        event.version,
+        event.timestamp,
+      ],
+    )
+    return scheduleId
+  }
+
+  async function cancelOnTx(
+    tx: PostgresAdapterTransaction,
+    scheduleId: string,
+  ): Promise<CancelResult> {
+    const rows = await tx.query<{ status: string }>(
+      `SELECT status FROM ${tables.scheduled} WHERE schedule_id = $1 FOR UPDATE`,
+      [scheduleId],
+    )
+    const row = rows[0]
+    if (!row) return { kind: "not-found" }
+    if (row.status === "appended") return { kind: "already-appended" }
+    if (row.status === "cancelled") return { kind: "not-found" }
+
+    await tx.query(
+      `UPDATE ${tables.scheduled} SET status = 'cancelled' WHERE schedule_id = $1`,
+      [scheduleId],
+    )
+    return { kind: "cancelled" }
+  }
+
+  function decodeJsonbValue(v: unknown): unknown {
+    if (typeof v === "string") {
+      try {
+        return JSON.parse(v)
+      } catch {
+        return v
+      }
+    }
+    return v ?? {}
+  }
+
+  function decodeTags(encoded: string[]): EventMessage["tags"] {
+    return encoded.map((t) => {
+      // U+001F unit separator — matches encodeTag in criteria-sql.ts
+      const sep = t.indexOf("")
+      return sep >= 0
+        ? { key: t.slice(0, sep), value: t.slice(sep + 1) }
+        : { key: t, value: "" }
+    })
+  }
+
+  function reconstructEvent(row: ScheduleRow): EventMessage {
+    return {
+      identifier: row.schedule_id,
+      name: qualifiedNameFromString(row.type),
+      payload: decodeJsonbValue(row.payload),
+      metadata: decodeJsonbValue(row.metadata) as EventMessage["metadata"],
+      timestamp: Number(row.message_timestamp),
+      version: row.version,
+      tags: decodeTags(row.tags),
+    }
+  }
+
+  // Worker state
+  let running = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let activeTick: Promise<void> | undefined
+
+  async function tick(): Promise<void> {
+    try {
+      await uowFactory(undefined, async () => {
+        const tx = await getOrBeginActiveTransaction<PostgresAdapterTransaction>()
+        if (!tx) {
+          // No lazy tx factory installed on the UoW — the scheduler was
+          // configured with a uowFactory that doesn't wrap the postgres tx
+          // manager. Without a shared tx the worker can't atomically
+          // append-and-mark, so refuse to fire rather than risk
+          // partial-state. This is a misconfiguration; surface loudly.
+          throw new Error(
+            "postgresEventScheduler worker requires a uowFactory wrapped with lazyTransactionalUnitOfWorkFactory + postgresTransactionManager",
+          )
+        }
+
+        const rows = await tx.query<ScheduleRow>(
+          `SELECT schedule_id, type, tags, payload, metadata, version, message_timestamp
+           FROM ${tables.scheduled}
+           WHERE status = 'pending' AND fire_at <= now()
+           ORDER BY fire_at
+           LIMIT $1
+           FOR UPDATE SKIP LOCKED`,
+          [batchSize],
+        )
+        if (rows.length === 0) return
+
+        for (const row of rows) {
+          const event = reconstructEvent(row)
+          // eventStore.append joins our shared UoW tx via
+          // getOrBeginActiveTransaction (postgres-event-store refactor).
+          // event_id = schedule_id, so re-fires after a crash dedupe via
+          // the events table's UNIQUE(event_id) constraint.
+          await eventStore.append([event])
+          await tx.query(
+            `UPDATE ${tables.scheduled} SET status = 'appended' WHERE schedule_id = $1`,
+            [row.schedule_id],
+          )
+        }
+      })
+    } catch (err) {
+      // A failed tick leaves rows 'pending' (the UoW rolls back the whole
+      // batch). The next tick re-tries. Log so operators see persistent
+      // failures rather than a silent hang.
+      console.warn("postgresEventScheduler: worker tick failed:", err)
+    }
+  }
+
+  function scheduleNextTick(): void {
+    if (!running) return
+    timer = setTimeout(() => {
+      activeTick = tick().finally(() => {
+        activeTick = undefined
+        scheduleNextTick()
+      })
+    }, pollIntervalMs)
+  }
+
+  return {
+    async schedule(event: EventMessage, at: Date): Promise<ScheduleToken> {
+      requireInvocationPhase()
+      const shared = await getOrBeginActiveTransaction<PostgresAdapterTransaction>()
+      if (shared === undefined) {
+        // schedule() must be transactional with the caller's UoW so a
+        // rolled-back command does not leak schedules. Refuse rather
+        // than open a side-channel tx the caller can't roll back.
+        throw new Error(
+          "postgresEventScheduler.schedule requires a UoW with a postgres transaction (configure lazyTransactionalUnitOfWorkFactory + postgresTransactionManager)",
+        )
+      }
+      const id = await insertSchedule(shared, event, at)
+      return { id }
+    },
+
+    async cancel(token: ScheduleToken): Promise<CancelResult> {
+      const shared = await getOrBeginActiveTransaction<PostgresAdapterTransaction>()
+      if (shared !== undefined) {
+        return cancelOnTx(shared, token.id)
+      }
+      return adapter.transaction(IsolationLevel.READ_COMMITTED, (tx) =>
+        cancelOnTx(tx, token.id),
+      )
+    },
+
+    async start(): Promise<void> {
+      if (running) return
+      running = true
+      scheduleNextTick()
+    },
+
+    async stop(): Promise<void> {
+      running = false
+      if (timer !== undefined) {
+        clearTimeout(timer)
+        timer = undefined
+      }
+      if (activeTick !== undefined) {
+        try {
+          await activeTick
+        } catch {
+          // The tick logs its own failures; stop() returns successfully
+          // either way so callers can shut down deterministically.
+        }
+      }
+    },
+  }
+}

package/src/postgres-event-store.ts

@@ -49,7 +49,13 @@ import type {
   StreamingCondition,
   TrackingToken,
 } from "@kronos-ts/messaging"
-import { createMessageStream, globalSequenceToken, FIRST_TOKEN } from "@kronos-ts/messaging"
+import {
+  createMessageStream,
+  globalSequenceToken,
+  FIRST_TOKEN,
+  getOrBeginActiveTransaction,
+  onAfterCommit,
+} from "@kronos-ts/messaging"
 import { qualifiedNameToString, qualifiedNameFromString } from "@kronos-ts/common"
 import type { Serializer } from "@kronos-ts/common"
 export type { Serializer } from "@kronos-ts/common"
@@ -325,31 +331,54 @@ export function createPostgresEventStore(
       events: ReadonlyArray<EventMessage>,
       condition?: AppendCondition,
     ): Promise<ConsistencyMarker> {
-      // Convenience: appendEvents + commit + afterCommit in one shot.
+      // Two paths: join an active UoW tx (writes commit atomically with
+      // everything else in the UoW — scheduler inserts, future outbox, etc.),
+      // or open our own short-lived tx when no UoW is active. The shared
+      // path defers NOTIFY + subscriber dispatch to AFTER_COMMIT because the
+      // tx hasn't actually committed yet when checkAndInsert returns.
       const targets = lockTargetsForCondition(condition)
-      let marker: ConsistencyMarker
-      try {
-        marker = await adapter.transaction(IsolationLevel.READ_COMMITTED, async (tx) => {
-          await acquireWriteLocks(tx, targets)
-          const captured = await checkAndInsert(tx, events, condition)
-          return markerAt(captured.position)
-        })
-      } catch (err) {
-        if (isDcbViolation(err)) {
-          // Re-throw AppendConditionError directly (already has correct type)
-          throw err
+      const shared = await getOrBeginActiveTransaction<PostgresAdapterTransaction>()
+
+      const notifyAndFanout = async () => {
+        await adapter.query(`NOTIFY ${notifyChannel}`)
+        for (const sub of eventSubscribers) {
+          try { await sub(events) } catch { /* ignore subscriber errors */ }
         }
+      }
+
+      const runAppend = async (tx: PostgresAdapterTransaction): Promise<ConsistencyMarker> => {
+        await acquireWriteLocks(tx, targets)
+        const captured = await checkAndInsert(tx, events, condition)
+        return markerAt(captured.position)
+      }
+
+      const translateError = (err: unknown): never => {
+        if (isDcbViolation(err)) throw err
         if ((err as { code?: string }).code === "23505") {
           throw AppendConditionError.fromConflictCount(0, condition?.marker.position ?? -1n)
         }
         throw err
       }
-      // Wake up tailing streams + notify push-based subscribers
-      await adapter.query(`NOTIFY ${notifyChannel}`)
-      for (const sub of eventSubscribers) {
-        try { await sub(events) } catch { /* ignore subscriber errors */ }
+
+      if (shared !== undefined) {
+        let marker: ConsistencyMarker
+        try {
+          marker = await runAppend(shared)
+        } catch (err) {
+          translateError(err)
+        }
+        onAfterCommit(notifyAndFanout)
+        return marker!
+      }
+
+      let marker: ConsistencyMarker
+      try {
+        marker = await adapter.transaction(IsolationLevel.READ_COMMITTED, runAppend)
+      } catch (err) {
+        translateError(err)
       }
-      return marker
+      await notifyAndFanout()
+      return marker!
     },
 
     async getHeadPosition(): Promise<bigint> {
@@ -372,26 +401,44 @@ export function createPostgresEventStore(
     },
 
     async publish(events: ReadonlyArray<EventMessage>): Promise<void> {
-      // publish = append without condition; also notifies subscribers + streams
+      // publish = append without condition; same shared/own tx split as append().
       const targets: LockTarget[] = []
-      let marker: ConsistencyMarker
+      const shared = await getOrBeginActiveTransaction<PostgresAdapterTransaction>()
+
+      const notifyAndFanout = async () => {
+        await adapter.query(`NOTIFY ${notifyChannel}`)
+        for (const sub of eventSubscribers) {
+          try { await sub(events) } catch { /* ignore subscriber errors */ }
+        }
+      }
+
+      const runPublish = async (tx: PostgresAdapterTransaction): Promise<void> => {
+        await acquireWriteLocks(tx, targets)
+        await checkAndInsert(tx, events, undefined)
+      }
+
+      if (shared !== undefined) {
+        try {
+          await runPublish(shared)
+        } catch (err) {
+          if ((err as { code?: string }).code === "23505") {
+            throw AppendConditionError.fromConflictCount(0, -1n)
+          }
+          throw err
+        }
+        onAfterCommit(notifyAndFanout)
+        return
+      }
+
       try {
-        marker = await adapter.transaction(IsolationLevel.READ_COMMITTED, async (tx) => {
-          await acquireWriteLocks(tx, targets)
-          const captured = await checkAndInsert(tx, events, undefined)
-          return markerAt(captured.position)
-        })
+        await adapter.transaction(IsolationLevel.READ_COMMITTED, runPublish)
       } catch (err) {
         if ((err as { code?: string }).code === "23505") {
           throw AppendConditionError.fromConflictCount(0, -1n)
         }
         throw err
       }
-      void marker
-      await adapter.query(`NOTIFY ${notifyChannel}`)
-      for (const sub of eventSubscribers) {
-        try { await sub(events) } catch { /* ignore subscriber errors */ }
-      }
+      await notifyAndFanout()
     },
 
     subscribe(

package/src/postgres-transaction-manager.ts

@@ -0,0 +1,120 @@
+/**
+ * postgresTransactionManager — bridges the framework's TransactionManager
+ * lifecycle to the postgres adapter's callback-shaped `adapter.transaction`.
+ *
+ * adapter.transaction(IL, fn) opens a pg tx, runs `fn(tx)`, and COMMITs on
+ * fn-resolve / ROLLBACKs on fn-reject. The framework needs a tx whose
+ * commit/rollback is callable LATER (at the UoW's COMMIT or onError phase),
+ * not when fn returns. We bridge by parking `fn` on a deferred completion
+ * promise — `commit()` resolves it (→ adapter commits), `rollback()`
+ * rejects it (→ adapter rolls back).
+ *
+ * Same shape as kysely/prisma transaction managers in this repo.
+ */
+
+import { getOrBeginActiveTransaction, type TransactionManager } from "@kronos-ts/messaging"
+import type { PostgresAdapter, PostgresAdapterTransaction } from "./adapter.js"
+import { IsolationLevel } from "./adapter.js"
+
+/**
+ * Module-private symbol attaching commit/rollback control to a tx handle.
+ * Consumers via `getActiveTransaction<PostgresAdapterTransaction>()` see
+ * only `{ query }` — they cannot read this without importing the symbol.
+ */
+const TX_CONTROL = Symbol("kronos.postgresTxControl")
+
+interface TxControl {
+  readonly resolveCommit: () => void
+  readonly rejectRollback: (err: unknown) => void
+  readonly txPromise: Promise<void>
+}
+
+interface ManagedPostgresTransaction extends PostgresAdapterTransaction {
+  [TX_CONTROL]: TxControl
+}
+
+/** Marker error: signals an intentional rollback so the .catch can suppress it. */
+const ROLLBACK_MARKER = "__kronos_postgres_tx_rollback__"
+
+export function postgresTransactionManager(
+  adapter: PostgresAdapter,
+  isolationLevel: IsolationLevel = IsolationLevel.READ_COMMITTED,
+): TransactionManager<PostgresAdapterTransaction> {
+  return {
+    async begin(): Promise<PostgresAdapterTransaction> {
+      let captureTx!: (tx: PostgresAdapterTransaction) => void
+      const txReady = new Promise<PostgresAdapterTransaction>((res) => {
+        captureTx = res
+      })
+
+      let resolveCommit!: () => void
+      let rejectRollback!: (err: unknown) => void
+      const completion = new Promise<void>((res, rej) => {
+        resolveCommit = res
+        rejectRollback = rej
+      })
+
+      const txPromise = adapter
+        .transaction(isolationLevel, async (tx) => {
+          captureTx(tx)
+          await completion
+        })
+        .then(
+          () => undefined,
+          (err) => {
+            // Suppress the marker — rollback is an expected outcome.
+            if (err instanceof Error && err.message === ROLLBACK_MARKER) return
+            throw err
+          },
+        )
+
+      const tx = (await txReady) as ManagedPostgresTransaction
+      tx[TX_CONTROL] = { resolveCommit, rejectRollback, txPromise }
+      return tx
+    },
+
+    async commit(tx: PostgresAdapterTransaction): Promise<void> {
+      const ctrl = (tx as ManagedPostgresTransaction)[TX_CONTROL]
+      ctrl.resolveCommit()
+      await ctrl.txPromise
+    },
+
+    async rollback(tx: PostgresAdapterTransaction): Promise<void> {
+      const ctrl = (tx as ManagedPostgresTransaction)[TX_CONTROL]
+      ctrl.rejectRollback(new Error(ROLLBACK_MARKER))
+      try {
+        await ctrl.txPromise
+      } catch (err) {
+        // A real follow-up error during ROLLBACK execution. Don't throw
+        // from rollback() — the UoW is already in an error path and a
+        // cascading throw masks the original failure.
+        console.warn("postgresTransactionManager: rollback path threw:", err)
+      }
+    },
+  }
+}
+
+/**
+ * Run `fn` inside a postgres tx, joining a UoW-scoped tx if one is active
+ * (or installed lazily), otherwise opening an ad-hoc tx via `adapter.transaction`.
+ *
+ * This is what every postgres-extension write path should funnel through —
+ * event store appends, snapshot writes, scheduler inserts — so that all
+ * writes inside a single UoW land in one pg tx and commit/roll back atomically.
+ * Calls from outside any UoW (e.g., the scheduler worker loop, projection
+ * queries, lifecycle bootstraps) get their own short-lived tx.
+ *
+ * Returns whatever `fn` returns. Tx commit/rollback happens when the
+ * surrounding UoW's COMMIT/onError fires (joined path) or when `fn` resolves/
+ * rejects (ad-hoc path).
+ */
+export async function withSharedOrOwnTx<R>(
+  adapter: PostgresAdapter,
+  fn: (tx: PostgresAdapterTransaction) => Promise<R>,
+  isolationLevel: IsolationLevel = IsolationLevel.READ_COMMITTED,
+): Promise<R> {
+  const shared = await getOrBeginActiveTransaction<PostgresAdapterTransaction>()
+  if (shared !== undefined) return fn(shared)
+  return adapter.transaction(isolationLevel, fn)
+}
+

package/src/postgres.ts

@@ -1,9 +1,21 @@
 /**
  * postgres(config) — Extension factory for @kronos-ts/postgres.
  *
- * Populates two slots (D-12.01):
- *   - eventStore     : EventStorageEngine via createPostgresEventStore
- *   - snapshotStore  : SnapshotStore via createPostgresSnapshotStore
+ * Populates five slots:
+ *   - eventStore           : EventStorageEngine via createPostgresEventStore
+ *   - snapshotStore        : SnapshotStore via createPostgresSnapshotStore
+ *   - transactionManager   : postgresTransactionManager(adapter)
+ *   - unitOfWorkFactory    : lazyTransactionalUnitOfWorkFactory(runInNewUoW, tm)
+ *   - eventScheduler       : createPostgresEventScheduler(...) (durable,
+ *                            background worker started in "processors" stage)
+ *
+ * Setting the last two together is what gives `append() + schedule()` (and
+ * any future postgres-extension writer) a SHARED UoW transaction —
+ * everything that writes inside one UoW commits or rolls back atomically.
+ * Lazy variant chosen so pure-read UoWs (queries, projections that don't
+ * write) never claim a pool connection. Users who need different
+ * composition (e.g., eager for benchmarking, custom UoW wrapping) can
+ * override with `app.forceSet(...)`.
  *
  * Lifecycle (mirrors @kronos-ts/kronosdb extension shape):
  *   - app.onStart("connect", ...) — adapter.connect() with withRetry; then
@@ -11,16 +23,26 @@
  *     their own migration tooling are not surprised)
  *   - app.onStop("connect", ...)  — adapter.disconnect()
  *
- * Does NOT populate eventBus, commandBus, queryBus, tokenStore, or
- * transactionManager (D-12.01 — out of scope for this extension).
+ * Does NOT populate eventBus, commandBus, queryBus, or tokenStore (out of
+ * scope for this extension — postgres token store is a separate package).
  */
 
-import type { App } from "@kronos-ts/app"
+import type { App, KronosComponents } from "@kronos-ts/app"
 import type { ResilienceConfig } from "@kronos-ts/common"
 import { withRetry } from "@kronos-ts/common"
+import {
+  lazyTransactionalUnitOfWorkFactory,
+  runInNewUoW,
+  type TransactionManager,
+} from "@kronos-ts/messaging"
 import type { PostgresAdapter } from "./adapter.js"
 import { createPostgresEventStore } from "./postgres-event-store.js"
 import { createPostgresSnapshotStore } from "./postgres-snapshot-store.js"
+import { postgresTransactionManager } from "./postgres-transaction-manager.js"
+import {
+  createPostgresEventScheduler,
+  type PostgresEventScheduler,
+} from "./postgres-event-scheduler.js"
 import { bootstrapSchema, DEFAULT_TABLE_NAMES, type TableNames } from "./schema.js"
 
 export interface PostgresConfig {
@@ -34,6 +56,11 @@ export interface PostgresConfig {
   /** Retry policy for the initial connect + bootstrap. Defaults to
    *  framework defaults via withRetry. */
   readonly resilience?: Partial<ResilienceConfig>
+  /** Tuning for the durable scheduler's polling worker. */
+  readonly scheduler?: {
+    readonly pollIntervalMs?: number
+    readonly batchSize?: number
+  }
 }
 
 export function postgres(config: PostgresConfig): (app: App) => void {
@@ -48,6 +75,29 @@ export function postgres(config: PostgresConfig): (app: App) => void {
     app.set("snapshotStore", ({ serializer }) =>
       createPostgresSnapshotStore({ adapter, serializer, tableNames: tables }),
     )
+    app.set("transactionManager", () => postgresTransactionManager(adapter))
+    app.set("unitOfWorkFactory", (resolved: KronosComponents) =>
+      lazyTransactionalUnitOfWorkFactory(
+        runInNewUoW,
+        resolved.transactionManager as TransactionManager<unknown>,
+      ),
+    )
+
+    // Durable scheduler — closure captures the instance so the worker can be
+    // start()'d in "processors" and stop()'d in "connect" symmetric to other
+    // background workers.
+    let scheduler: PostgresEventScheduler | undefined
+    app.set("eventScheduler", ({ eventStore, unitOfWorkFactory, tagResolver }) => {
+      scheduler = createPostgresEventScheduler({
+        adapter,
+        eventStore,
+        uowFactory: unitOfWorkFactory,
+        tagResolver,
+        tableNames: tables,
+        ...config.scheduler,
+      })
+      return scheduler
+    })
 
     app.onStart("connect", async () => {
       await withRetry(() => adapter.connect(), { event: "initial-connect", ...resilience })
@@ -59,7 +109,15 @@ export function postgres(config: PostgresConfig): (app: App) => void {
       }
     })
 
+    // Worker spins up after registration/warmup so all slots are resolved and
+    // any user-supplied processors are in place before due schedules start
+    // firing into the event store.
+    app.onStart("processors", async () => {
+      if (scheduler) await scheduler.start()
+    })
+
     app.onStop("connect", async () => {
+      if (scheduler) await scheduler.stop()
       await adapter.disconnect()
     })
   }