@kronos-ts/postgres 0.1.1 → 0.3.0

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,25 @@
  *     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 { ResilienceConfig } from "@kronos-ts/common"
 import { withRetry } from "@kronos-ts/common"
+import {
+  lazyTransactionalUnitOfWorkFactory,
+  runInNewUoW,
+} 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 +55,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 {
@@ -41,6 +67,8 @@ export function postgres(config: PostgresConfig): (app: App) => void {
   const bootstrap = config.bootstrap ?? true
   const tables = config.tableNames ?? DEFAULT_TABLE_NAMES
 
+  const txManager = postgresTransactionManager(adapter)
+
   return (app: App) => {
     app.set("eventStore", ({ serializer, tagResolver }) =>
       createPostgresEventStore({ adapter, serializer, tagResolver, tableNames: tables }),
@@ -48,6 +76,33 @@ export function postgres(config: PostgresConfig): (app: App) => void {
     app.set("snapshotStore", ({ serializer }) =>
       createPostgresSnapshotStore({ adapter, serializer, tableNames: tables }),
     )
+    app.set("transactionManager", () => txManager)
+    // Lazy: pure-read UoWs never claim a connection; the first writer (an
+    // append flush, or a user's own SQL via getOrBeginActiveTransaction)
+    // begins the tx, and everything in that UoW — events AND co-located
+    // writes — commits or rolls back together. The command bus runs handlers
+    // through this factory (see createSimpleCommandBus), so command handlers
+    // get the transaction without this extension reaching into the command
+    // pipeline.
+    app.set("unitOfWorkFactory", () =>
+      lazyTransactionalUnitOfWorkFactory(runInNewUoW, txManager),
+    )
+
+    // 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 +114,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()
     })
   }

package/src/schema.ts

@@ -17,11 +17,13 @@
 export interface TableNames {
   readonly events: string
   readonly snapshots: string
+  readonly scheduled: string
 }
 
 export const DEFAULT_TABLE_NAMES: TableNames = {
   events: "kronos_events",
   snapshots: "kronos_snapshots",
+  scheduled: "kronos_scheduled_events",
 }
 
 /**
@@ -76,6 +78,72 @@ export function buildSnapshotsTableDDL(tables: TableNames): string {
 );`
 }
 
+/**
+ * Scheduled-events table — holds events parked for future append.
+ *
+ * # Row lifecycle (tombstone model)
+ *
+ *   INSERT (status='pending')   ← schedule() inside a UoW
+ *      ├── UPDATE → 'appended'  ← worker fires the schedule; row stays as tombstone
+ *      └── UPDATE → 'cancelled' ← cancel(token) succeeds; row stays as tombstone
+ *
+ * Tombstones (rather than DELETE-on-fire) give cancel() three distinct
+ * outcomes — `cancelled` / `already-appended` / `not-found` — by inspecting
+ * the row's terminal status. The events table already grows unboundedly,
+ * so a parallel tombstone table is no worse from a retention perspective.
+ *
+ * # Schedule id = event id
+ *
+ * `schedule_id` is the same UUID as the eventual `event_id` written to the
+ * events table at fire-time. One UUID identifies the schedule pre-fire and
+ * the event post-fire, so callers tracking the materialised event can
+ * correlate back to the original schedule without an extra column.
+ *
+ * # Payload columns
+ *
+ * The whole EventMessage shape is captured inline (event_id, type, tags,
+ * payload, metadata, version, message_timestamp) so the fire-time worker
+ * can reconstruct it from a single row read. `message_timestamp` is the
+ * EventMessage's authored timestamp (epoch ms) — distinct from
+ * `created_at` (when the row was inserted) and `fire_at` (when it should
+ * fire). At append-time, the worker MAY overwrite message_timestamp with
+ * `now()` so consumers see the actual append time; that is an
+ * implementation decision left to the scheduler.
+ */
+export function buildScheduledEventsTableDDL(tables: TableNames): string {
+  return `CREATE TABLE IF NOT EXISTS ${tables.scheduled} (
+  schedule_id        UUID PRIMARY KEY,
+  fire_at            TIMESTAMPTZ NOT NULL,
+  status             TEXT NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'appended', 'cancelled')),
+  type               TEXT COLLATE "C" NOT NULL,
+  tags               TEXT[] NOT NULL DEFAULT '{}',
+  payload            JSONB NOT NULL,
+  metadata           JSONB NOT NULL DEFAULT '{}',
+  version            TEXT NOT NULL,
+  message_timestamp  BIGINT NOT NULL,
+  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
+);`
+}
+
+/**
+ * Indexes for the scheduled-events table.
+ *
+ * The single critical index is the partial btree on `fire_at WHERE status =
+ * 'pending'`. The worker's hot query — `SELECT … WHERE status = 'pending'
+ * AND fire_at <= now() ORDER BY fire_at LIMIT n FOR UPDATE SKIP LOCKED` —
+ * scans only pending rows, so a partial index keeps the hot path B-tree
+ * tiny regardless of how many appended/cancelled tombstones accumulate.
+ *
+ * No index on `status` alone — every status query also filters by either
+ * schedule_id (PK lookup) or fire_at (the partial index above).
+ */
+export function buildScheduledEventsIndexesDDL(tables: TableNames): string {
+  return `CREATE INDEX IF NOT EXISTS ${tables.scheduled}_pending_fire_at_idx
+  ON ${tables.scheduled} (fire_at)
+  WHERE status = 'pending';`
+}
+
 /**
  * Minimal adapter contract bootstrapSchema needs. A subset of the full
  * PostgresAdapter interface authored in Plan 12-03 — structurally
@@ -195,6 +263,8 @@ export async function bootstrapSchema(
     await adapter.query(buildEventsTableDDL(tables))
     await adapter.query(buildEventsIndexesDDL(tables))
     await adapter.query(buildSnapshotsTableDDL(tables))
+    await adapter.query(buildScheduledEventsTableDDL(tables))
+    await adapter.query(buildScheduledEventsIndexesDDL(tables))
     await adapter.query(buildAppendStoredProcedureDDL(tables))
   } finally {
     // Release even on partial-DDL failure. The error (if any) propagates