@kronos-ts/postgres 0.1.1 → 0.3.0

package/dist/schema.js

@@ -16,6 +16,7 @@
 export const DEFAULT_TABLE_NAMES = {
     events: "kronos_events",
     snapshots: "kronos_snapshots",
+    scheduled: "kronos_scheduled_events",
 };
 /**
  * Session-scoped advisory lock key for the schema bootstrap.
@@ -65,6 +66,70 @@ export function buildSnapshotsTableDDL(tables) {
   PRIMARY KEY (state_name, state_id)
 );`;
 }
+/**
+ * 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) {
+    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) {
+    return `CREATE INDEX IF NOT EXISTS ${tables.scheduled}_pending_fire_at_idx
+  ON ${tables.scheduled} (fire_at)
+  WHERE status = 'pending';`;
+}
 /**
  * Append-with-DCB-check stored procedure.
  *
@@ -163,6 +228,8 @@ export async function bootstrapSchema(adapter, options = {}) {
         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 {

package/dist/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,MAAM,EAAE,eAAe;IACvB,SAAS,EAAE,kBAAkB;CAC9B,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAW,CAAC,MAAM,CAAA;AAErD,MAAM,UAAU,mBAAmB,CAAC,MAAkB;IACpD,mFAAmF;IACnF,+EAA+E;IAC/E,0EAA0E;IAC1E,OAAO,8BAA8B,MAAM,CAAC,MAAM;;;;;;;;;;;;;GAajD,CAAA;AACH,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAkB;IACtD,OAAO,qCAAqC,MAAM,CAAC,MAAM;OACpD,MAAM,CAAC,MAAM;;6BAES,MAAM,CAAC,MAAM;OACnC,MAAM,CAAC,MAAM,2CAA2C,CAAA;AAC/D,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAkB;IACvD,OAAO,8BAA8B,MAAM,CAAC,SAAS;;;;;;;;GAQpD,CAAA;AACH,CAAC;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,6BAA6B,CAAC,MAAkB;IAC9D,OAAO;;;;;;;;;;;;;;;;;8BAiBqB,MAAM,CAAC,MAAM;;;;;;;;;;;;;;;;kBAgBzB,MAAM,CAAC,MAAM;;;;;;qBAMV,CAAA;AACrB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA+B,EAC/B,UAAkC,EAAE;IAEpC,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAA;IAExD,uEAAuE;IACvE,qEAAqE;IACrE,sBAAsB;IACtB,MAAM,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAA;IAE5E,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAA;QAChD,MAAM,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAA;QAClD,MAAM,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAA;QACnD,MAAM,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAA;IAC5D,CAAC;YAAS,CAAC;QACT,qEAAqE;QACrE,+CAA+C;QAC/C,MAAM,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAA;IAChF,CAAC;AACH,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,MAAM,EAAE,eAAe;IACvB,SAAS,EAAE,kBAAkB;IAC7B,SAAS,EAAE,yBAAyB;CACrC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAW,CAAC,MAAM,CAAA;AAErD,MAAM,UAAU,mBAAmB,CAAC,MAAkB;IACpD,mFAAmF;IACnF,+EAA+E;IAC/E,0EAA0E;IAC1E,OAAO,8BAA8B,MAAM,CAAC,MAAM;;;;;;;;;;;;;GAajD,CAAA;AACH,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAkB;IACtD,OAAO,qCAAqC,MAAM,CAAC,MAAM;OACpD,MAAM,CAAC,MAAM;;6BAES,MAAM,CAAC,MAAM;OACnC,MAAM,CAAC,MAAM,2CAA2C,CAAA;AAC/D,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAkB;IACvD,OAAO,8BAA8B,MAAM,CAAC,SAAS;;;;;;;;GAQpD,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAkB;IAC7D,OAAO,8BAA8B,MAAM,CAAC,SAAS;;;;;;;;;;;;GAYpD,CAAA;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,8BAA8B,CAAC,MAAkB;IAC/D,OAAO,8BAA8B,MAAM,CAAC,SAAS;OAChD,MAAM,CAAC,SAAS;4BACK,CAAA;AAC5B,CAAC;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,6BAA6B,CAAC,MAAkB;IAC9D,OAAO;;;;;;;;;;;;;;;;;8BAiBqB,MAAM,CAAC,MAAM;;;;;;;;;;;;;;;;kBAgBzB,MAAM,CAAC,MAAM;;;;;;qBAMV,CAAA;AACrB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA+B,EAC/B,UAAkC,EAAE;IAEpC,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAA;IAExD,uEAAuE;IACvE,qEAAqE;IACrE,sBAAsB;IACtB,MAAM,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAA;IAE5E,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAA;QAChD,MAAM,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAA;QAClD,MAAM,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAA;QACnD,MAAM,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,MAAM,CAAC,CAAC,CAAA;QACzD,MAAM,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,MAAM,CAAC,CAAC,CAAA;QAC3D,MAAM,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAA;IAC5D,CAAC;YAAS,CAAC;QACT,qEAAqE;QACrE,+CAA+C;QAC/C,MAAM,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAA;IAChF,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/postgres",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "PostgreSQL extension for Kronos — event store and snapshot store adapters.",
   "license": "Apache-2.0",
   "type": "module",

package/src/adapter.ts

@@ -41,6 +41,19 @@ export type QueryRow = Record<string, unknown>
  */
 export interface PostgresAdapterTransaction {
   query<R extends QueryRow = QueryRow>(sql: string, params?: unknown[]): Promise<R[]>
+  /**
+   * Escape hatch returning the live driver-specific handle backing this
+   * transaction — the pg `PoolClient`, or the scoped `sql` for postgres.js /
+   * Bun.sql. Lets an external query builder (e.g. Drizzle) issue statements on
+   * the SAME connection, and therefore the SAME transaction, as the engine's
+   * appends — so an application's CRUD writes commit or roll back atomically
+   * with its events.
+   *
+   * The caller owns the cast (the handle type is driver-specific) and the
+   * handle is valid ONLY for the lifetime of this transaction — never retain
+   * it past the UoW that opened it.
+   */
+  unwrap<T = unknown>(): T
 }
 
 /** Handle to a live LISTEN subscription. unlisten() unregisters + releases

package/src/adapters/bun-sql.ts

@@ -173,6 +173,9 @@ export function bunSqlAdapter(config: BunSqlAdapterConfig): PostgresAdapter {
       // normalized (errno -> code) via normalizeBunSqlError before propagating.
       return inst.begin(`ISOLATION LEVEL ${isolationLevel}`, async (txSql) => {
         const tx: PostgresAdapterTransaction = {
+          unwrap<T = unknown>(): T {
+            return txSql as unknown as T
+          },
           async query<R extends QueryRow = QueryRow>(
             text: string,
             params?: unknown[],

package/src/adapters/pg.ts

@@ -119,6 +119,9 @@ export function pgAdapter(config: PgAdapterConfig): PostgresAdapter {
       try {
         await client.query(`BEGIN ISOLATION LEVEL ${isolationLevel}`)
         const tx: PostgresAdapterTransaction = {
+          unwrap<T = unknown>(): T {
+            return client as unknown as T
+          },
           async query<R extends QueryRow = QueryRow>(
             sql: string,
             params?: unknown[],

package/src/adapters/postgres.ts

@@ -101,6 +101,9 @@ export function postgresAdapter(config: PostgresAdapterConfig): PostgresAdapter
       // pins to the underlying connection for the duration.
       return (await c.begin(`ISOLATION LEVEL ${isolationLevel}`, async (txSql) => {
         const tx: PostgresAdapterTransaction = {
+          unwrap<T = unknown>(): T {
+            return txSql as unknown as T
+          },
           async query<R extends QueryRow = QueryRow>(
             text: string,
             params?: unknown[],

package/src/index.ts

@@ -43,6 +43,22 @@ export {
 // Extension factory (Plan 05)
 export { postgres, type PostgresConfig } from "./postgres.js"
 
+// Transaction manager — bridges the framework's TransactionManager lifecycle
+// to adapter.transaction(). Users typically get this wired automatically via
+// `postgres(config)`; exported for direct use when composing UoW runners by
+// hand.
+export { postgresTransactionManager } from "./postgres-transaction-manager.js"
+
+// Postgres event scheduler — durable schedule() + cancel() + polling worker
+// that fires due schedules into the event store. Wired into postgres()
+// automatically when a uowFactory with the lazy postgres tx is in place;
+// exported here so users who compose their own wiring can construct one.
+export {
+  createPostgresEventScheduler,
+  type PostgresEventScheduler,
+  type PostgresEventSchedulerConfig,
+} from "./postgres-event-scheduler.js"
+
 // Schema bootstrap + DDL builders — exposed for users who want to run their
 // own migrations (set `postgres({ bootstrap: false })`) or drive the store
 // directly without going through the extension factory.
@@ -51,6 +67,8 @@ export {
   buildEventsTableDDL,
   buildEventsIndexesDDL,
   buildSnapshotsTableDDL,
+  buildScheduledEventsTableDDL,
+  buildScheduledEventsIndexesDDL,
   DEFAULT_TABLE_NAMES,
   type TableNames,
 } from "./schema.js"

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(