@kronos-ts/postgres 0.5.0 → 0.7.0

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;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,CA+B9D;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;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAmBf"}
+{"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,CA+B9D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAMhE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAUjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/dist/schema.js

@@ -34,11 +34,12 @@ export function buildEventsTableDDL(tables) {
     // UNIQUE auto-creates a btree; v7's time-ordered prefix keeps it compact under
     // append load (a v4 random UUID would fragment the leaf pages over time).
     //
-    // version + message_timestamp persist the EventMessage's own `version` and authored
-    // `timestamp` (epoch ms) so source()/open() reconstruct the full EventMessage contract,
-    // matching the in-memory, axon-server, and kronosdb engines. message_timestamp is the
-    // authored time — distinct from recorded_at (DB insert time). This mirrors the
-    // scheduled-events table, which already carries both columns.
+    // version + timestamp persist the EventMessage's own `version` and authored `timestamp`
+    // (epoch ms) so source()/open() reconstruct the full EventMessage contract, matching the
+    // in-memory, axon-server, and kronosdb engines. `timestamp` is a BIGINT (epoch ms), fully
+    // btree/BRIN-indexable; `timestamp` is a non-reserved keyword in Postgres and works
+    // unquoted in every position we use (the only conflict is the `TIMESTAMP 'literal'` cast,
+    // which we never write).
     //
     // MIGRATION: this is CREATE-only. `CREATE TABLE IF NOT EXISTS` does NOT add columns to a
     // pre-existing table, and the columns are NOT NULL, so an events table created before
@@ -53,8 +54,7 @@ export function buildEventsTableDDL(tables) {
   payload            JSONB NOT NULL,
   metadata           JSONB NOT NULL DEFAULT '{}',
   version            TEXT NOT NULL,
-  message_timestamp  BIGINT NOT NULL,
-  recorded_at        TIMESTAMPTZ NOT NULL DEFAULT now()
+  timestamp          BIGINT NOT NULL
 ) WITH (
   autovacuum_freeze_min_age   = 10000000,
   autovacuum_freeze_table_age = 100000000,
@@ -103,13 +103,15 @@ export function buildSnapshotsTableDDL(tables) {
  * # 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.
+ * payload, metadata, version, timestamp) so the fire-time worker can
+ * reconstruct it from a single row read. `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 `timestamp` with `now()` so consumers see the actual
+ * append time; that is an implementation decision left to the scheduler.
+ *
+ * Column names mirror the events table (`version`, `timestamp`) so a schedule
+ * row and the event it materialises into share the same vocabulary.
  */
 export function buildScheduledEventsTableDDL(tables) {
     return `CREATE TABLE IF NOT EXISTS ${tables.scheduled} (
@@ -122,7 +124,7 @@ export function buildScheduledEventsTableDDL(tables) {
   payload            JSONB NOT NULL,
   metadata           JSONB NOT NULL DEFAULT '{}',
   version            TEXT NOT NULL,
-  message_timestamp  BIGINT NOT NULL,
+  timestamp          BIGINT NOT NULL,
   created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
 );`;
 }

package/dist/schema.js.map

@@ -1 +1 @@
-{"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,EAAE;IACF,oFAAoF;IACpF,wFAAwF;IACxF,sFAAsF;IACtF,+EAA+E;IAC/E,8DAA8D;IAC9D,EAAE;IACF,yFAAyF;IACzF,sFAAsF;IACtF,oFAAoF;IACpF,+DAA+D;IAC/D,OAAO,8BAA8B,MAAM,CAAC,MAAM;;;;;;;;;;;;;;;GAejD,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;;;;;;;;;;GAUG;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;IAC7D,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,EAAE;IACF,wFAAwF;IACxF,yFAAyF;IACzF,0FAA0F;IAC1F,oFAAoF;IACpF,0FAA0F;IAC1F,yBAAyB;IACzB,EAAE;IACF,yFAAyF;IACzF,sFAAsF;IACtF,oFAAoF;IACpF,+DAA+D;IAC/D,OAAO,8BAA8B,MAAM,CAAC,MAAM;;;;;;;;;;;;;;GAcjD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;;;;;;;;;;GAUG;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;IAC7D,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/dist/session-timeouts.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-transaction safety timeouts, armed via `SET LOCAL` by each adapter's
+ * `transaction()` at BEGIN. Living on the adapter (not the transaction
+ * manager) means EVERY postgres transaction is bounded — UoW-scoped commits,
+ * the event store's own-tx append/publish, and the scheduler worker tick alike
+ * — and each adapter instance carries its own settings, so two adapters
+ * pointed at two different databases stay fully decoupled.
+ *
+ * A non-postgres adapter (e.g. a future sqlite one) arms its own
+ * dialect-appropriate settings, or none.
+ */
+import type { PostgresAdapterTransaction } from "./adapter.js";
+export interface SessionTimeoutOptions {
+    /**
+     * `idle_in_transaction_session_timeout` (ms) applied via `SET LOCAL` on every
+     * transaction. A transaction that begins but stalls before commit/rollback
+     * would otherwise hold its connection — and pin `pg_snapshot_xmin`, which
+     * gates the gap-free tailing query in the event store — open indefinitely,
+     * stalling all streaming processors until the process restarts. This bounds
+     * that window: postgres aborts the idle transaction and the connection (and
+     * xmin) is freed. Default 30000 (30s). Set 0 to disable (postgres default).
+     */
+    readonly idleInTransactionTimeoutMs?: number;
+    /**
+     * `statement_timeout` (ms) applied via `SET LOCAL` on every transaction.
+     * Bounds a single hung statement inside the tx. Default 0 (disabled) — large
+     * appends / replays can legitimately run long, so opt in per deployment.
+     */
+    readonly statementTimeoutMs?: number;
+}
+export interface ResolvedSessionTimeouts {
+    readonly idleInTransactionTimeoutMs: number;
+    readonly statementTimeoutMs: number;
+}
+/** Resolve config to concrete, normalized timeouts (applying defaults). */
+export declare function resolveSessionTimeouts(opts?: SessionTimeoutOptions): ResolvedSessionTimeouts;
+/**
+ * Arm the resolved timeouts on a freshly-opened transaction. No-op for any
+ * timeout resolved to 0.
+ *
+ * GUCs cannot be parameterized ($1) — the value is a config-supplied integer,
+ * normalized to a non-negative whole number, so inlining is injection-safe.
+ * `SET LOCAL` auto-resets at COMMIT/ROLLBACK, so it never leaks onto pooled
+ * connections.
+ */
+export declare function applySessionTimeouts(tx: PostgresAdapterTransaction, timeouts: ResolvedSessionTimeouts): Promise<void>;
+//# sourceMappingURL=session-timeouts.d.ts.map

package/dist/session-timeouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-timeouts.d.ts","sourceRoot":"","sources":["../src/session-timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAE9D,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAA;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CACrC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAA;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CACpC;AAID,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,IAAI,CAAC,EAAE,qBAAqB,GAAG,uBAAuB,CAO5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,0BAA0B,EAC9B,QAAQ,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/session-timeouts.js

@@ -0,0 +1,44 @@
+/**
+ * Per-transaction safety timeouts, armed via `SET LOCAL` by each adapter's
+ * `transaction()` at BEGIN. Living on the adapter (not the transaction
+ * manager) means EVERY postgres transaction is bounded — UoW-scoped commits,
+ * the event store's own-tx append/publish, and the scheduler worker tick alike
+ * — and each adapter instance carries its own settings, so two adapters
+ * pointed at two different databases stay fully decoupled.
+ *
+ * A non-postgres adapter (e.g. a future sqlite one) arms its own
+ * dialect-appropriate settings, or none.
+ */
+const DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS = 30_000;
+/** Resolve config to concrete, normalized timeouts (applying defaults). */
+export function resolveSessionTimeouts(opts) {
+    return {
+        idleInTransactionTimeoutMs: normalizeTimeoutMs(opts?.idleInTransactionTimeoutMs ?? DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS),
+        statementTimeoutMs: normalizeTimeoutMs(opts?.statementTimeoutMs ?? 0),
+    };
+}
+/**
+ * Arm the resolved timeouts on a freshly-opened transaction. No-op for any
+ * timeout resolved to 0.
+ *
+ * GUCs cannot be parameterized ($1) — the value is a config-supplied integer,
+ * normalized to a non-negative whole number, so inlining is injection-safe.
+ * `SET LOCAL` auto-resets at COMMIT/ROLLBACK, so it never leaks onto pooled
+ * connections.
+ */
+export async function applySessionTimeouts(tx, timeouts) {
+    if (timeouts.idleInTransactionTimeoutMs > 0) {
+        await tx.query(`SET LOCAL idle_in_transaction_session_timeout = ${timeouts.idleInTransactionTimeoutMs}`);
+    }
+    if (timeouts.statementTimeoutMs > 0) {
+        await tx.query(`SET LOCAL statement_timeout = ${timeouts.statementTimeoutMs}`);
+    }
+}
+/** Coerce a config timeout to a non-negative whole number of milliseconds.
+ *  Non-finite or negative values disable the timeout (treated as 0). */
+function normalizeTimeoutMs(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return 0;
+    return Math.floor(value);
+}
+//# sourceMappingURL=session-timeouts.js.map

package/dist/session-timeouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-timeouts.js","sourceRoot":"","sources":["../src/session-timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA4BH,MAAM,sCAAsC,GAAG,MAAM,CAAA;AAErD,2EAA2E;AAC3E,MAAM,UAAU,sBAAsB,CAAC,IAA4B;IACjE,OAAO;QACL,0BAA0B,EAAE,kBAAkB,CAC5C,IAAI,EAAE,0BAA0B,IAAI,sCAAsC,CAC3E;QACD,kBAAkB,EAAE,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,IAAI,CAAC,CAAC;KACtE,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAA8B,EAC9B,QAAiC;IAEjC,IAAI,QAAQ,CAAC,0BAA0B,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,EAAE,CAAC,KAAK,CAAC,mDAAmD,QAAQ,CAAC,0BAA0B,EAAE,CAAC,CAAA;IAC1G,CAAC;IACD,IAAI,QAAQ,CAAC,kBAAkB,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,EAAE,CAAC,KAAK,CAAC,iCAAiC,QAAQ,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAChF,CAAC;AACH,CAAC;AAED;wEACwE;AACxE,SAAS,kBAAkB,CAAC,KAAa;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,CAAA;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/postgres",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "PostgreSQL extension for Kronos — event store and snapshot store adapters.",
   "license": "Apache-2.0",
   "type": "module",
@@ -68,9 +68,9 @@
   },
   "dependencies": {
     "@kronos-ts/common": "0.1.1",
-    "@kronos-ts/app": "0.4.0",
-    "@kronos-ts/eventsourcing": "0.2.2",
-    "@kronos-ts/messaging": "0.6.0"
+    "@kronos-ts/app": "0.5.0",
+    "@kronos-ts/eventsourcing": "0.3.0",
+    "@kronos-ts/messaging": "0.8.0"
   },
   "peerDependencies": {
     "pg": ">=8.0.0",

package/src/adapters/bun-sql.ts

@@ -23,8 +23,13 @@ import type {
   QueryRow,
 } from "../adapter.js"
 import { IsolationLevel } from "../adapter.js"
+import {
+  type SessionTimeoutOptions,
+  applySessionTimeouts,
+  resolveSessionTimeouts,
+} from "../session-timeouts.js"
 
-export interface BunSqlAdapterConfig {
+export interface BunSqlAdapterConfig extends SessionTimeoutOptions {
   readonly connectionString: string
 }
 
@@ -106,6 +111,7 @@ function getBunSql(): BunSqlConstructor {
 export function bunSqlAdapter(config: BunSqlAdapterConfig): PostgresAdapter {
   let sql: BunSqlInstance | undefined
   let disconnected = false
+  const timeouts = resolveSessionTimeouts(config)
 
   function getInstance(): BunSqlInstance {
     if (!sql) {
@@ -183,6 +189,9 @@ export function bunSqlAdapter(config: BunSqlAdapterConfig): PostgresAdapter {
             return txSql.unsafe(text, normalizeParams(params)).catch(normalizeBunSqlError) as Promise<R[]>
           },
         }
+        // Arm the per-transaction safety timeouts before handing the tx to the
+        // caller, so even the very first awaited statement is bounded.
+        await applySessionTimeouts(tx, timeouts)
         return fn(tx)
       }).catch(normalizeBunSqlError)
     },

package/src/adapters/pg.ts

@@ -21,8 +21,13 @@ import type {
   QueryRow,
 } from "../adapter.js"
 import { IsolationLevel } from "../adapter.js"
+import {
+  type SessionTimeoutOptions,
+  applySessionTimeouts,
+  resolveSessionTimeouts,
+} from "../session-timeouts.js"
 
-export interface PgAdapterConfig {
+export interface PgAdapterConfig extends SessionTimeoutOptions {
   /** Standard libpq URI: postgresql://user:pass@host:port/db */
   readonly connectionString: string
   /** Optional pg.Pool config overrides (max connections, idleTimeoutMillis, etc.). */
@@ -39,6 +44,7 @@ export function pgAdapter(config: PgAdapterConfig): PostgresAdapter {
   let listenClient: PoolClient | undefined
   const listenSlots = new Map<string, Set<ListenerSlot>>()
   let disconnected = false
+  const timeouts = resolveSessionTimeouts(config)
 
   function getPool(): Pool {
     if (!pool) {
@@ -132,6 +138,9 @@ export function pgAdapter(config: PgAdapterConfig): PostgresAdapter {
         }
         let result: T
         try {
+          // Arm the per-transaction safety timeouts before handing the tx to
+          // the caller, so even the very first awaited statement is bounded.
+          await applySessionTimeouts(tx, timeouts)
           result = await fn(tx)
         } catch (err) {
           // ROLLBACK best-effort; preserve the ORIGINAL error.

package/src/adapters/postgres.ts

@@ -26,8 +26,13 @@ import type {
   QueryRow,
 } from "../adapter.js"
 import { IsolationLevel } from "../adapter.js"
+import {
+  type SessionTimeoutOptions,
+  applySessionTimeouts,
+  resolveSessionTimeouts,
+} from "../session-timeouts.js"
 
-export interface PostgresAdapterConfig {
+export interface PostgresAdapterConfig extends SessionTimeoutOptions {
   readonly connectionString: string
   /** Additional postgres.js options. `transform.column.from` is forced off regardless. */
   readonly clientOptions?: Parameters<typeof postgresClient>[1]
@@ -36,6 +41,7 @@ export interface PostgresAdapterConfig {
 export function postgresAdapter(config: PostgresAdapterConfig): PostgresAdapter {
   let sql: Sql | undefined
   let disconnected = false
+  const timeouts = resolveSessionTimeouts(config)
 
   function getSql(): Sql {
     if (!sql) {
@@ -112,6 +118,9 @@ export function postgresAdapter(config: PostgresAdapterConfig): PostgresAdapter
             return rows
           },
         }
+        // Arm the per-transaction safety timeouts before handing the tx to the
+        // caller, so even the very first awaited statement is bounded.
+        await applySessionTimeouts(tx, timeouts)
         return fn(tx)
       })) as T
     },

package/src/index.ts

@@ -49,6 +49,16 @@ export { postgres, type PostgresConfig } from "./postgres.js"
 // hand.
 export { postgresTransactionManager } from "./postgres-transaction-manager.js"
 
+// Per-transaction safety timeouts (idle-in-transaction / statement), armed by
+// each adapter's transaction() at BEGIN. The options are spread onto every
+// adapter config; the helpers are exported for authors of custom adapters.
+export {
+  type SessionTimeoutOptions,
+  type ResolvedSessionTimeouts,
+  resolveSessionTimeouts,
+  applySessionTimeouts,
+} from "./session-timeouts.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;

package/src/postgres-event-scheduler.ts

@@ -109,7 +109,7 @@ interface ScheduleRow {
   payload: unknown
   metadata: unknown
   version: string
-  message_timestamp: string | number
+  timestamp: string | number
   [key: string]: unknown
 }
 
@@ -132,7 +132,7 @@ export function createPostgresEventScheduler(
       .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)
+         (schedule_id, fire_at, status, type, tags, payload, metadata, version, timestamp)
        VALUES ($1, $2, 'pending', $3, $4, $5, $6, $7, $8)`,
       [
         scheduleId,
@@ -196,7 +196,7 @@ export function createPostgresEventScheduler(
       name: qualifiedNameFromString(row.type),
       payload: decodeJsonbValue(row.payload),
       metadata: decodeJsonbValue(row.metadata) as EventMessage["metadata"],
-      timestamp: Number(row.message_timestamp),
+      timestamp: Number(row.timestamp),
       version: row.version,
       tags: decodeTags(row.tags),
     }
@@ -223,7 +223,7 @@ export function createPostgresEventScheduler(
         }
 
         const rows = await tx.query<ScheduleRow>(
-          `SELECT schedule_id, type, tags, payload, metadata, version, message_timestamp
+          `SELECT schedule_id, type, tags, payload, metadata, version, timestamp
            FROM ${tables.scheduled}
            WHERE status = 'pending' AND fire_at <= now()
            ORDER BY fire_at

package/src/postgres-event-store.ts

@@ -163,7 +163,7 @@ export function createPostgresEventStore(
       const metadata = e.metadata ?? {}
 
       const rows = await tx.query<{ sequence_position: string; transaction_id: string }>(
-        `INSERT INTO ${tables.events} (event_id, type, tags, payload, metadata, version, message_timestamp)
+        `INSERT INTO ${tables.events} (event_id, type, tags, payload, metadata, version, timestamp)
          VALUES ($1, $2, $3, $4, $5, $6, $7)
          RETURNING sequence_position, transaction_id`,
         [
@@ -193,7 +193,7 @@ export function createPostgresEventStore(
       const start = condition.start ?? 0n
       const built = buildCriteriaWhere(condition.criteria, 2) // $1 = start
       const sql = `
-        SELECT sequence_position, event_id, type, tags, payload, metadata, version, message_timestamp
+        SELECT sequence_position, event_id, type, tags, payload, metadata, version, timestamp
         FROM ${tables.events}
         WHERE sequence_position >= $1 AND (${built.where})
         ORDER BY sequence_position ASC
@@ -206,7 +206,7 @@ export function createPostgresEventStore(
         payload: unknown
         metadata: unknown
         version: string
-        message_timestamp: string | number
+        timestamp: string | number
       }>(sql, [start, ...built.params])
 
       const events: EventMessage[] = rows.map((r) => decodeEvent(r))
@@ -482,7 +482,7 @@ export function createPostgresEventStore(
           sql = `
             SELECT sequence_position::text AS sequence_position,
                    transaction_id::text AS transaction_id,
-                   event_id, type, tags, payload, metadata, version, message_timestamp
+                   event_id, type, tags, payload, metadata, version, timestamp
             FROM ${tables.events}
             WHERE sequence_position > $1::bigint
               AND transaction_id < pg_snapshot_xmin(pg_current_snapshot())
@@ -501,7 +501,7 @@ export function createPostgresEventStore(
           sql = `
             SELECT sequence_position::text AS sequence_position,
                    transaction_id::text AS transaction_id,
-                   event_id, type, tags, payload, metadata, version, message_timestamp
+                   event_id, type, tags, payload, metadata, version, timestamp
             FROM ${tables.events}
             WHERE (transaction_id, sequence_position) > ($1::xid8, $2::bigint)
               AND transaction_id < pg_snapshot_xmin(pg_current_snapshot())
@@ -521,7 +521,7 @@ export function createPostgresEventStore(
           payload: unknown
           metadata: unknown
           version: string
-          message_timestamp: string | number
+          timestamp: string | number
         }>(sql, queryParams)
 
         for (const r of rows) {
@@ -614,7 +614,7 @@ function decodeEvent(row: {
   sequence_position: string
   event_id: string
   version: string
-  message_timestamp: string | number
+  timestamp: string | number
 }): EventMessage {
   const qn = qualifiedNameFromString(row.type)
   const tags = row.tags.map((t) => {
@@ -631,7 +631,7 @@ function decodeEvent(row: {
     tags,
     payload: decodeJsonb(row.payload),
     metadata: decodeJsonb(row.metadata) as EventMessage["metadata"],
-    timestamp: Number(row.message_timestamp),
+    timestamp: Number(row.timestamp),
   }
 }
 

package/src/postgres-transaction-manager.ts

@@ -36,51 +36,10 @@ interface ManagedPostgresTransaction extends PostgresAdapterTransaction {
 /** Marker error: signals an intentional rollback so the .catch can suppress it. */
 const ROLLBACK_MARKER = "__kronos_postgres_tx_rollback__"
 
-/** Tuning for the safety timeouts applied to every UoW-scoped transaction. */
-export interface PostgresTransactionManagerOptions {
-  /**
-   * `idle_in_transaction_session_timeout` (ms) applied via `SET LOCAL` on every
-   * transaction. A UoW that begins a tx but stalls before commit/rollback would
-   * otherwise hold its connection — and pin `pg_snapshot_xmin`, which gates the
-   * gap-free tailing query in the event store — open indefinitely, stalling all
-   * streaming processors until the process restarts. This bounds that window:
-   * postgres aborts the idle transaction and the connection (and xmin) is freed.
-   * Default 30000 (30s). Set 0 to disable (postgres default — no timeout).
-   */
-  readonly idleInTransactionTimeoutMs?: number
-  /**
-   * `statement_timeout` (ms) applied via `SET LOCAL` on every transaction.
-   * Bounds a single hung statement inside the tx. Default 0 (disabled) — large
-   * appends / replays can legitimately run long, so opt in per deployment.
-   */
-  readonly statementTimeoutMs?: number
-}
-
-const DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS = 30_000
-
 export function postgresTransactionManager(
   adapter: PostgresAdapter,
   isolationLevel: IsolationLevel = IsolationLevel.READ_COMMITTED,
-  options: PostgresTransactionManagerOptions = {},
 ): TransactionManager<PostgresAdapterTransaction> {
-  const idleTimeoutMs = normalizeTimeoutMs(
-    options.idleInTransactionTimeoutMs ?? DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS,
-  )
-  const statementTimeoutMs = normalizeTimeoutMs(options.statementTimeoutMs ?? 0)
-
-  // GUCs cannot be parameterized ($1) — the value is a config-supplied integer,
-  // normalized to a non-negative whole number, so inlining is injection-safe.
-  // SET LOCAL auto-resets at COMMIT/ROLLBACK, so it never leaks onto pooled
-  // connections.
-  async function applyTimeouts(tx: PostgresAdapterTransaction): Promise<void> {
-    if (idleTimeoutMs > 0) {
-      await tx.query(`SET LOCAL idle_in_transaction_session_timeout = ${idleTimeoutMs}`)
-    }
-    if (statementTimeoutMs > 0) {
-      await tx.query(`SET LOCAL statement_timeout = ${statementTimeoutMs}`)
-    }
-  }
-
   return {
     async begin(): Promise<PostgresAdapterTransaction> {
       let captureTx!: (tx: PostgresAdapterTransaction) => void
@@ -97,9 +56,9 @@ export function postgresTransactionManager(
 
       const txPromise = adapter
         .transaction(isolationLevel, async (tx) => {
-          // Arm the per-transaction safety timeouts before handing the tx to
-          // the UoW, so even the very first awaited statement is bounded.
-          await applyTimeouts(tx)
+          // Per-transaction safety timeouts are armed by the adapter's
+          // transaction() at BEGIN (see session-timeouts.ts), so they cover
+          // this UoW-scoped tx and every ad-hoc adapter.transaction() alike.
           captureTx(tx)
           await completion
         })
@@ -153,13 +112,6 @@ export function postgresTransactionManager(
   }
 }
 
-/** Coerce a config timeout to a non-negative whole number of milliseconds.
- *  Non-finite or negative values disable the timeout (treated as 0). */
-function normalizeTimeoutMs(value: number): number {
-  if (!Number.isFinite(value) || value <= 0) return 0
-  return Math.floor(value)
-}
-
 /**
  * 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`.

package/src/postgres.ts

@@ -60,14 +60,6 @@ export interface PostgresConfig {
     readonly pollIntervalMs?: number
     readonly batchSize?: number
   }
-  /** Safety timeouts applied via `SET LOCAL` to every UoW-scoped transaction.
-   *  Guards against a stalled UoW holding a connection — and pinning
-   *  `pg_snapshot_xmin`, which would stall all streaming tailing — open until
-   *  restart. Defaults: 30s idle-in-transaction, statement timeout disabled. */
-  readonly transaction?: {
-    readonly idleInTransactionTimeoutMs?: number
-    readonly statementTimeoutMs?: number
-  }
 }
 
 export function postgres(config: PostgresConfig): (app: App) => void {
@@ -75,7 +67,11 @@ export function postgres(config: PostgresConfig): (app: App) => void {
   const bootstrap = config.bootstrap ?? true
   const tables = config.tableNames ?? DEFAULT_TABLE_NAMES
 
-  const txManager = postgresTransactionManager(adapter, undefined, config.transaction)
+  // Safety timeouts (idle-in-transaction / statement) are armed by the adapter
+  // itself — configure them on the adapter (e.g. `pgAdapter({ connectionString,
+  // idleInTransactionTimeoutMs })`), so every transaction through it is bounded
+  // and two adapters on two databases stay independently configured.
+  const txManager = postgresTransactionManager(adapter)
 
   return (app: App) => {
     app.set("eventStore", ({ serializer, tagResolver }) =>

package/src/schema.ts

@@ -43,11 +43,12 @@ export function buildEventsTableDDL(tables: TableNames): string {
   // UNIQUE auto-creates a btree; v7's time-ordered prefix keeps it compact under
   // append load (a v4 random UUID would fragment the leaf pages over time).
   //
-  // version + message_timestamp persist the EventMessage's own `version` and authored
-  // `timestamp` (epoch ms) so source()/open() reconstruct the full EventMessage contract,
-  // matching the in-memory, axon-server, and kronosdb engines. message_timestamp is the
-  // authored time — distinct from recorded_at (DB insert time). This mirrors the
-  // scheduled-events table, which already carries both columns.
+  // version + timestamp persist the EventMessage's own `version` and authored `timestamp`
+  // (epoch ms) so source()/open() reconstruct the full EventMessage contract, matching the
+  // in-memory, axon-server, and kronosdb engines. `timestamp` is a BIGINT (epoch ms), fully
+  // btree/BRIN-indexable; `timestamp` is a non-reserved keyword in Postgres and works
+  // unquoted in every position we use (the only conflict is the `TIMESTAMP 'literal'` cast,
+  // which we never write).
   //
   // MIGRATION: this is CREATE-only. `CREATE TABLE IF NOT EXISTS` does NOT add columns to a
   // pre-existing table, and the columns are NOT NULL, so an events table created before
@@ -62,8 +63,7 @@ export function buildEventsTableDDL(tables: TableNames): string {
   payload            JSONB NOT NULL,
   metadata           JSONB NOT NULL DEFAULT '{}',
   version            TEXT NOT NULL,
-  message_timestamp  BIGINT NOT NULL,
-  recorded_at        TIMESTAMPTZ NOT NULL DEFAULT now()
+  timestamp          BIGINT NOT NULL
 ) WITH (
   autovacuum_freeze_min_age   = 10000000,
   autovacuum_freeze_table_age = 100000000,
@@ -115,13 +115,15 @@ export function buildSnapshotsTableDDL(tables: TableNames): string {
  * # 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.
+ * payload, metadata, version, timestamp) so the fire-time worker can
+ * reconstruct it from a single row read. `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 `timestamp` with `now()` so consumers see the actual
+ * append time; that is an implementation decision left to the scheduler.
+ *
+ * Column names mirror the events table (`version`, `timestamp`) so a schedule
+ * row and the event it materialises into share the same vocabulary.
  */
 export function buildScheduledEventsTableDDL(tables: TableNames): string {
   return `CREATE TABLE IF NOT EXISTS ${tables.scheduled} (
@@ -134,7 +136,7 @@ export function buildScheduledEventsTableDDL(tables: TableNames): string {
   payload            JSONB NOT NULL,
   metadata           JSONB NOT NULL DEFAULT '{}',
   version            TEXT NOT NULL,
-  message_timestamp  BIGINT NOT NULL,
+  timestamp          BIGINT NOT NULL,
   created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
 );`
 }