@kronos-ts/postgres 0.1.1 → 0.2.0

package/dist/postgres-transaction-manager.js

@@ -0,0 +1,92 @@
+/**
+ * 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 } from "@kronos-ts/messaging";
+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");
+/** Marker error: signals an intentional rollback so the .catch can suppress it. */
+const ROLLBACK_MARKER = "__kronos_postgres_tx_rollback__";
+export function postgresTransactionManager(adapter, isolationLevel = IsolationLevel.READ_COMMITTED) {
+    return {
+        async begin() {
+            let captureTx;
+            const txReady = new Promise((res) => {
+                captureTx = res;
+            });
+            let resolveCommit;
+            let rejectRollback;
+            const completion = new Promise((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);
+            tx[TX_CONTROL] = { resolveCommit, rejectRollback, txPromise };
+            return tx;
+        },
+        async commit(tx) {
+            const ctrl = tx[TX_CONTROL];
+            ctrl.resolveCommit();
+            await ctrl.txPromise;
+        },
+        async rollback(tx) {
+            const ctrl = tx[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(adapter, fn, isolationLevel = IsolationLevel.READ_COMMITTED) {
+    const shared = await getOrBeginActiveTransaction();
+    if (shared !== undefined)
+        return fn(shared);
+    return adapter.transaction(isolationLevel, fn);
+}
+//# sourceMappingURL=postgres-transaction-manager.js.map

package/dist/postgres-transaction-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-transaction-manager.js","sourceRoot":"","sources":["../src/postgres-transaction-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,2BAA2B,EAA2B,MAAM,sBAAsB,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAE7C;;;;GAIG;AACH,MAAM,UAAU,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAA;AAYrD,mFAAmF;AACnF,MAAM,eAAe,GAAG,iCAAiC,CAAA;AAEzD,MAAM,UAAU,0BAA0B,CACxC,OAAwB,EACxB,iBAAiC,cAAc,CAAC,cAAc;IAE9D,OAAO;QACL,KAAK,CAAC,KAAK;YACT,IAAI,SAAoD,CAAA;YACxD,MAAM,OAAO,GAAG,IAAI,OAAO,CAA6B,CAAC,GAAG,EAAE,EAAE;gBAC9D,SAAS,GAAG,GAAG,CAAA;YACjB,CAAC,CAAC,CAAA;YAEF,IAAI,aAA0B,CAAA;YAC9B,IAAI,cAAuC,CAAA;YAC3C,MAAM,UAAU,GAAG,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;gBAChD,aAAa,GAAG,GAAG,CAAA;gBACnB,cAAc,GAAG,GAAG,CAAA;YACtB,CAAC,CAAC,CAAA;YAEF,MAAM,SAAS,GAAG,OAAO;iBACtB,WAAW,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;gBACxC,SAAS,CAAC,EAAE,CAAC,CAAA;gBACb,MAAM,UAAU,CAAA;YAClB,CAAC,CAAC;iBACD,IAAI,CACH,GAAG,EAAE,CAAC,SAAS,EACf,CAAC,GAAG,EAAE,EAAE;gBACN,yDAAyD;gBACzD,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,KAAK,eAAe;oBAAE,OAAM;gBACnE,MAAM,GAAG,CAAA;YACX,CAAC,CACF,CAAA;YAEH,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAA+B,CAAA;YACxD,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,CAAA;YAC7D,OAAO,EAAE,CAAA;QACX,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAA8B;YACzC,MAAM,IAAI,GAAI,EAAiC,CAAC,UAAU,CAAC,CAAA;YAC3D,IAAI,CAAC,aAAa,EAAE,CAAA;YACpB,MAAM,IAAI,CAAC,SAAS,CAAA;QACtB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,EAA8B;YAC3C,MAAM,IAAI,GAAI,EAAiC,CAAC,UAAU,CAAC,CAAA;YAC3D,IAAI,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC,CAAA;YAC/C,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,SAAS,CAAA;YACtB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,gEAAgE;gBAChE,8DAA8D;gBAC9D,8CAA8C;gBAC9C,OAAO,CAAC,IAAI,CAAC,kDAAkD,EAAE,GAAG,CAAC,CAAA;YACvE,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAwB,EACxB,EAAkD,EAClD,iBAAiC,cAAc,CAAC,cAAc;IAE9D,MAAM,MAAM,GAAG,MAAM,2BAA2B,EAA8B,CAAA;IAC9E,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC,MAAM,CAAC,CAAA;IAC3C,OAAO,OAAO,CAAC,WAAW,CAAC,cAAc,EAAE,EAAE,CAAC,CAAA;AAChD,CAAC"}

package/dist/postgres.d.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,8 +23,8 @@
  *     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";
@@ -29,6 +41,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 declare function postgres(config: PostgresConfig): (app: App) => void;
 //# sourceMappingURL=postgres.d.ts.map

package/dist/postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAGnD,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAEnF,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC;uCACmC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC;4CACwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAChD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CA2BnE"}
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAoB,MAAM,gBAAgB,CAAA;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAOzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAQnD,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAEnF,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC;uCACmC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC;4CACwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC/C,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;QAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAC5B,CAAA;CACF;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CA0DnE"}

package/dist/postgres.js

@@ -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,12 +23,15 @@
  *     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 { withRetry } from "@kronos-ts/common";
+import { lazyTransactionalUnitOfWorkFactory, runInNewUoW, } from "@kronos-ts/messaging";
 import { createPostgresEventStore } from "./postgres-event-store.js";
 import { createPostgresSnapshotStore } from "./postgres-snapshot-store.js";
+import { postgresTransactionManager } from "./postgres-transaction-manager.js";
+import { createPostgresEventScheduler, } from "./postgres-event-scheduler.js";
 import { bootstrapSchema, DEFAULT_TABLE_NAMES } from "./schema.js";
 export function postgres(config) {
     const { adapter, resilience } = config;
@@ -25,6 +40,23 @@ export function postgres(config) {
     return (app) => {
         app.set("eventStore", ({ serializer, tagResolver }) => createPostgresEventStore({ adapter, serializer, tagResolver, tableNames: tables }));
         app.set("snapshotStore", ({ serializer }) => createPostgresSnapshotStore({ adapter, serializer, tableNames: tables }));
+        app.set("transactionManager", () => postgresTransactionManager(adapter));
+        app.set("unitOfWorkFactory", (resolved) => lazyTransactionalUnitOfWorkFactory(runInNewUoW, resolved.transactionManager));
+        // 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;
+        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 });
             if (bootstrap) {
@@ -34,7 +66,16 @@ export function postgres(config) {
                 });
             }
         });
+        // 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/dist/postgres.js.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAE7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAA;AAC1E,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAmB,MAAM,aAAa,CAAA;AAenF,MAAM,UAAU,QAAQ,CAAC,MAAsB;IAC7C,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAAA;IACtC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAA;IAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,IAAI,mBAAmB,CAAA;IAEvD,OAAO,CAAC,GAAQ,EAAE,EAAE;QAClB,GAAG,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,CACpD,wBAAwB,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CACnF,CAAA;QACD,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAC1C,2BAA2B,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CACzE,CAAA;QAED,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAChC,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,UAAU,EAAE,CAAC,CAAA;YACrF,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE;oBACtE,KAAK,EAAE,iBAAiB;oBACxB,GAAG,UAAU;iBACd,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAC/B,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;QAC5B,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -16,6 +16,7 @@
 export interface TableNames {
     readonly events: string;
     readonly snapshots: string;
+    readonly scheduled: string;
 }
 export declare const DEFAULT_TABLE_NAMES: TableNames;
 /**
@@ -32,6 +33,52 @@ export declare const KRONOS_SCHEMA_LOCK_KEY: bigint;
 export declare function buildEventsTableDDL(tables: TableNames): string;
 export declare function buildEventsIndexesDDL(tables: TableNames): string;
 export declare 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 declare function buildScheduledEventsTableDDL(tables: TableNames): string;
+/**
+ * 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 declare function buildScheduledEventsIndexesDDL(tables: TableNames): string;
 /**
  * Minimal adapter contract bootstrapSchema needs. A subset of the full
  * PostgresAdapter interface authored in Plan 12-03 — structurally

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,eAAO,MAAM,mBAAmB,EAAE,UAGjC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAgB,CAAA;AAErD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAkB9D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAMhE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAUjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAED,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAyCxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkBf"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,eAAO,MAAM,mBAAmB,EAAE,UAIjC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAgB,CAAA;AAErD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAkB9D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAMhE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAUjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAcvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAIzE;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAED,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAyCxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAoBf"}

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.2.0",
   "description": "PostgreSQL extension for Kronos — event store and snapshot store adapters.",
   "license": "Apache-2.0",
   "type": "module",

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"