@duraflows/kysely 4.0.1 → 5.0.0

package/README.md

@@ -103,13 +103,27 @@ See the [`@duraflows/pg` README](https://github.com/camcima/duraflows/tree/main/
 
 ## API
 
-### `kyselyWorkflowProviders(db): WorkflowPersistenceProvider`
+### `kyselyWorkflowProviders(db, options?): WorkflowPersistenceProvider`
 
 Factory function that creates all required persistence providers from a `Kysely<WorkflowDatabase>` instance. Returns:
 
 - `instanceStore` -- `KyselyWorkflowInstanceStore`
 - `historyStore` -- `KyselyWorkflowHistoryStore`
 - `transactionRunner` -- `KyselyTransactionRunner`
+- `definitionStore` -- `KyselyWorkflowDefinitionStore`
+
+Options (all optional; omitting them keeps the previous behaviour):
+
+- `lockTimeoutMs` -- sets `lock_timeout` for the duration of each transaction. Bounds how long a statement **waits for a row lock**, so a stuck lock holder cannot hang `triggerEvent()` while it keeps a pooled connection checked out. **This is the recommended setting.**
+- `statementTimeoutMs` -- sets `statement_timeout` for the duration of each transaction. Bounds how long **any single statement** may run — including SQL your own commands issue inside the transaction, which is why it is left unset by default: a legitimately slow command statement would be aborted and take the whole transition with it.
+
+```ts
+const persistence = kyselyWorkflowProviders(db, { lockTimeoutMs: 3000 });
+```
+
+Both are applied transaction-locally via `set_config(name, value, true)` — the function form of `SET LOCAL` — so they are reverted on `COMMIT`/`ROLLBACK` and never leak to other users of the shared pool. Values must be non-negative integers in milliseconds (`0` means "no timeout"); anything else throws a `WorkflowError` at construction time.
+
+`kyselyWorkflowProvidersFromTransaction()` takes no timeout options: the transaction is owned by the caller, so its settings are the caller's to configure.
 
 ### `kyselyWorkflowProvidersFromTransaction(trx): WorkflowPersistenceProvider`
 

package/dist/cjs/index.d.ts

@@ -1,11 +1,19 @@
 import type { Kysely, Transaction } from "kysely";
 import type { WorkflowPersistenceProvider } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+import { type KyselyTransactionRunnerOptions } from "./kysely-transaction-runner.js";
 export { KyselyTransactionContext } from "./kysely-transaction-context.js";
 export { KyselyTransactionRunner } from "./kysely-transaction-runner.js";
+export type { KyselyTransactionRunnerOptions } from "./kysely-transaction-runner.js";
 export { KyselyWorkflowInstanceStore } from "./kysely-instance-store.js";
 export { KyselyWorkflowHistoryStore } from "./kysely-history-store.js";
-export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable } from "./kysely-database.js";
+export { KyselyWorkflowDefinitionStore } from "./kysely-definition-store.js";
+export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable, WorkflowDefinitionsTable, } from "./kysely-database.js";
+/**
+ * Options accepted by {@link kyselyWorkflowProviders}. Every field is optional
+ * and omitting the argument entirely reproduces the pre-existing behaviour.
+ */
+export type KyselyWorkflowProvidersOptions = KyselyTransactionRunnerOptions;
 /**
  * Creates long-lived persistence providers from a Kysely instance.
  *
@@ -14,7 +22,7 @@ export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable } f
  * only access workflow tables; the `unknown` cast is needed because
  * Kysely is invariant in its DB type parameter).
  */
-export declare function kyselyWorkflowProviders<DB extends WorkflowDatabase>(db: Kysely<DB>): WorkflowPersistenceProvider;
+export declare function kyselyWorkflowProviders<DB extends WorkflowDatabase>(db: Kysely<DB>, options?: KyselyWorkflowProvidersOptions): WorkflowPersistenceProvider;
 /**
  * Creates providers pre-bound to an existing Kysely transaction.
  *

package/dist/cjs/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KyselyWorkflowHistoryStore = exports.KyselyWorkflowInstanceStore = exports.KyselyTransactionRunner = exports.KyselyTransactionContext = void 0;
+exports.KyselyWorkflowDefinitionStore = exports.KyselyWorkflowHistoryStore = exports.KyselyWorkflowInstanceStore = exports.KyselyTransactionRunner = exports.KyselyTransactionContext = void 0;
 exports.kyselyWorkflowProviders = kyselyWorkflowProviders;
 exports.kyselyWorkflowProvidersFromTransaction = kyselyWorkflowProvidersFromTransaction;
 const kysely_instance_store_js_1 = require("./kysely-instance-store.js");
 const kysely_history_store_js_1 = require("./kysely-history-store.js");
+const kysely_definition_store_js_1 = require("./kysely-definition-store.js");
 const kysely_transaction_runner_js_1 = require("./kysely-transaction-runner.js");
 const kysely_transaction_context_js_1 = require("./kysely-transaction-context.js");
 var kysely_transaction_context_js_2 = require("./kysely-transaction-context.js");
@@ -15,6 +16,8 @@ var kysely_instance_store_js_2 = require("./kysely-instance-store.js");
 Object.defineProperty(exports, "KyselyWorkflowInstanceStore", { enumerable: true, get: function () { return kysely_instance_store_js_2.KyselyWorkflowInstanceStore; } });
 var kysely_history_store_js_2 = require("./kysely-history-store.js");
 Object.defineProperty(exports, "KyselyWorkflowHistoryStore", { enumerable: true, get: function () { return kysely_history_store_js_2.KyselyWorkflowHistoryStore; } });
+var kysely_definition_store_js_2 = require("./kysely-definition-store.js");
+Object.defineProperty(exports, "KyselyWorkflowDefinitionStore", { enumerable: true, get: function () { return kysely_definition_store_js_2.KyselyWorkflowDefinitionStore; } });
 /**
  * Creates long-lived persistence providers from a Kysely instance.
  *
@@ -23,12 +26,13 @@ Object.defineProperty(exports, "KyselyWorkflowHistoryStore", { enumerable: true,
  * only access workflow tables; the `unknown` cast is needed because
  * Kysely is invariant in its DB type parameter).
  */
-function kyselyWorkflowProviders(db) {
+function kyselyWorkflowProviders(db, options = {}) {
     const narrowed = db;
-    const transactionRunner = new kysely_transaction_runner_js_1.KyselyTransactionRunner(narrowed);
+    const transactionRunner = new kysely_transaction_runner_js_1.KyselyTransactionRunner(narrowed, options);
     const instanceStore = new kysely_instance_store_js_1.KyselyWorkflowInstanceStore(narrowed);
     const historyStore = new kysely_history_store_js_1.KyselyWorkflowHistoryStore(narrowed);
-    return { instanceStore, historyStore, transactionRunner };
+    const definitionStore = new kysely_definition_store_js_1.KyselyWorkflowDefinitionStore(narrowed);
+    return { instanceStore, historyStore, transactionRunner, definitionStore };
 }
 /**
  * Creates providers pre-bound to an existing Kysely transaction.
@@ -49,6 +53,7 @@ function kyselyWorkflowProvidersFromTransaction(trx) {
     };
     const instanceStore = new kysely_instance_store_js_1.KyselyWorkflowInstanceStore(narrowed);
     const historyStore = new kysely_history_store_js_1.KyselyWorkflowHistoryStore(narrowed);
-    return { instanceStore, historyStore, transactionRunner };
+    const definitionStore = new kysely_definition_store_js_1.KyselyWorkflowDefinitionStore(narrowed);
+    return { instanceStore, historyStore, transactionRunner, definitionStore };
 }
 //# sourceMappingURL=index.js.map

package/dist/cjs/kysely-database.d.ts

@@ -17,6 +17,7 @@ export interface WorkflowInstancesTable {
     workflow_name: string;
     current_state: string;
     version: number;
+    definition_version: number | null;
     expires_at: Date | null;
     last_transition_at: Date;
     context_json: JsonObjectColumn;
@@ -35,11 +36,20 @@ export interface WorkflowHistoryTable {
     rejected_by: string | null;
     command_results_json: JsonArrayColumn;
     trigger_metadata_json: JsonObjectColumn;
+    definition_version: number | null;
     created_at: Generated<Date>;
 }
+export interface WorkflowDefinitionsTable {
+    workflow_name: string;
+    version: number;
+    content_hash: string;
+    definition_json: JsonObjectColumn;
+    registered_at: Generated<Date>;
+}
 export interface WorkflowDatabase {
     workflow_instances: WorkflowInstancesTable;
     workflow_history: WorkflowHistoryTable;
+    workflow_definitions: WorkflowDefinitionsTable;
 }
 export {};
 //# sourceMappingURL=kysely-database.d.ts.map

package/dist/cjs/kysely-definition-store.d.ts

@@ -0,0 +1,17 @@
+import type { Kysely } from "kysely";
+import type { WorkflowDefinitionStore, StoredWorkflowDefinition, WorkflowDefinition } from "@duraflows/core";
+import type { WorkflowDatabase } from "./kysely-database.js";
+export declare class KyselyWorkflowDefinitionStore implements WorkflowDefinitionStore {
+    private readonly db;
+    constructor(db: Kysely<WorkflowDatabase>);
+    private getExecutor;
+    ensure(record: {
+        workflowName: string;
+        version: number;
+        contentHash: string;
+        definitionJson: WorkflowDefinition;
+    }): Promise<StoredWorkflowDefinition>;
+    findByNameAndVersion(workflowName: string, version: number): Promise<StoredWorkflowDefinition | null>;
+    private mapRow;
+}
+//# sourceMappingURL=kysely-definition-store.d.ts.map

package/dist/cjs/kysely-definition-store.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KyselyWorkflowDefinitionStore = void 0;
+const core_1 = require("@duraflows/core");
+const kysely_transaction_context_js_1 = require("./kysely-transaction-context.js");
+class KyselyWorkflowDefinitionStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    getExecutor() {
+        return kysely_transaction_context_js_1.KyselyTransactionContext.getTransaction(this.db) ?? this.db;
+    }
+    async ensure(record) {
+        const executor = this.getExecutor();
+        await executor
+            .insertInto("workflow_definitions")
+            .values({
+            workflow_name: record.workflowName,
+            version: record.version,
+            content_hash: record.contentHash,
+            definition_json: JSON.stringify(record.definitionJson),
+        })
+            .onConflict((oc) => oc.columns(["workflow_name", "version"]).doNothing())
+            .execute();
+        const stored = await this.findByNameAndVersion(record.workflowName, record.version);
+        if (!stored) {
+            // The row we just ensured must exist; its absence means the statement
+            // did not do what the adapter assumes. Fail loudly.
+            throw new core_1.WorkflowError(`Failed to ensure workflow definition "${record.workflowName}" version ${record.version}`);
+        }
+        return stored;
+    }
+    async findByNameAndVersion(workflowName, version) {
+        const executor = this.getExecutor();
+        const row = await executor
+            .selectFrom("workflow_definitions")
+            .selectAll()
+            .where("workflow_name", "=", workflowName)
+            .where("version", "=", version)
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        return this.mapRow(row);
+    }
+    mapRow(row) {
+        return {
+            workflowName: row.workflow_name,
+            version: row.version,
+            contentHash: row.content_hash,
+            definitionJson: row.definition_json,
+            registeredAt: row.registered_at,
+        };
+    }
+}
+exports.KyselyWorkflowDefinitionStore = KyselyWorkflowDefinitionStore;
+//# sourceMappingURL=kysely-definition-store.js.map

package/dist/cjs/kysely-history-store.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KyselyWorkflowHistoryStore = void 0;
+const core_1 = require("@duraflows/core");
 const kysely_transaction_context_js_1 = require("./kysely-transaction-context.js");
 class KyselyWorkflowHistoryStore {
     db;
@@ -24,9 +25,13 @@ class KyselyWorkflowHistoryStore {
             rejected_by: entry.rejectedBy ?? null,
             command_results_json: JSON.stringify(entry.commandResultsJson),
             trigger_metadata_json: JSON.stringify(entry.triggerMetadata ?? {}),
+            definition_version: entry.definitionVersion ?? null,
         })
             .returning("uuid")
-            .executeTakeFirstOrThrow();
+            // `INSERT ... RETURNING` always yields a row, so an empty result means the
+            // statement did not do what the adapter assumes. Surface that as the
+            // library's own error type rather than kysely's `NoResultError`.
+            .executeTakeFirstOrThrow(() => new core_1.WorkflowError("Failed to append workflow history: INSERT ... RETURNING uuid returned no row"));
         return row.uuid;
     }
     async findByInstanceUuid(workflowInstanceUuid, options) {
@@ -52,6 +57,8 @@ class KyselyWorkflowHistoryStore {
             rejectedBy: row.rejected_by ?? undefined,
             commandResultsJson: row.command_results_json,
             triggerMetadata: row.trigger_metadata_json,
+            definitionVersion: row.definition_version ?? undefined,
+            createdAt: row.created_at,
         }));
     }
 }

package/dist/cjs/kysely-instance-store.js

@@ -20,6 +20,7 @@ class KyselyWorkflowInstanceStore {
             workflow_name: instance.workflowName,
             current_state: instance.currentState,
             version: instance.version,
+            definition_version: instance.definitionVersion,
             expires_at: instance.expiresAt,
             last_transition_at: instance.lastTransitionAt,
             context_json: JSON.stringify(instance.context),
@@ -59,6 +60,7 @@ class KyselyWorkflowInstanceStore {
             .set({
             current_state: instance.currentState,
             version: instance.version,
+            definition_version: instance.definitionVersion,
             expires_at: instance.expiresAt,
             last_transition_at: instance.lastTransitionAt,
             context_json: JSON.stringify(instance.context),
@@ -95,6 +97,7 @@ class KyselyWorkflowInstanceStore {
             workflowName: row.workflow_name,
             currentState: row.current_state,
             version: row.version,
+            definitionVersion: row.definition_version ?? null,
             expiresAt: row.expires_at,
             lastTransitionAt: row.last_transition_at,
             context: row.context_json,

package/dist/cjs/kysely-transaction-runner.d.ts

@@ -1,9 +1,47 @@
 import type { Kysely } from "kysely";
 import type { WorkflowTransactionRunner } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+/**
+ * Transaction-scoped PostgreSQL timeouts.
+ *
+ * Both settings are optional and both default to unset: when neither is
+ * supplied the runner issues no extra statement at all, leaving the session and
+ * server defaults exactly as they were before this option existed.
+ */
+export interface KyselyTransactionRunnerOptions {
+    /**
+     * `lock_timeout` in milliseconds -- how long a statement waits for a row lock
+     * before it aborts. This is the recommended setting: it bounds the blocking
+     * `SELECT ... FOR UPDATE` behind `lockByUuid()`, so a stuck lock holder cannot
+     * hang a `triggerEvent()` call indefinitely while it keeps a pooled connection
+     * checked out. `0` disables the timeout (PostgreSQL's own default).
+     */
+    lockTimeoutMs?: number;
+    /**
+     * `statement_timeout` in milliseconds -- how long any single statement may run
+     * before it aborts. Deliberately unset by default: commands run inside the
+     * same transaction and may legitimately issue slow statements on the shared
+     * connection, and aborting one of those rolls the whole transition back.
+     * `0` disables the timeout (PostgreSQL's own default).
+     */
+    statementTimeoutMs?: number;
+}
 export declare class KyselyTransactionRunner implements WorkflowTransactionRunner {
     private readonly db;
-    constructor(db: Kysely<WorkflowDatabase>);
+    private readonly timeoutSettings;
+    constructor(db: Kysely<WorkflowDatabase>, options?: KyselyTransactionRunnerOptions);
     runInTransaction<T>(callback: () => Promise<T>): Promise<T>;
+    /**
+     * Applies the configured timeouts to `trx` as transaction-local settings, so
+     * they are reverted on COMMIT/ROLLBACK and never leak to other users of the
+     * shared pool.
+     *
+     * `set_config(name, value, is_local = true)` is the function form of
+     * `SET LOCAL`, reached through the query builder rather than kysely's `sql`
+     * template on purpose: this package imports kysely for types only, which is
+     * what keeps its CommonJS build loadable (kysely itself is ESM-only). Both
+     * arguments are bound parameters, so no value is ever interpolated into SQL.
+     */
+    private applyTimeouts;
 }
 //# sourceMappingURL=kysely-transaction-runner.d.ts.map

package/dist/cjs/kysely-transaction-runner.js

@@ -1,11 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KyselyTransactionRunner = void 0;
+const core_1 = require("@duraflows/core");
 const kysely_transaction_context_js_1 = require("./kysely-transaction-context.js");
+/**
+ * Rejects anything that is not a finite, non-negative integer. Called at
+ * construction time so an invalid value can never reach the database.
+ */
+function assertTimeoutMs(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new core_1.WorkflowError(`${name} must be a non-negative integer number of milliseconds, got ${value}`);
+    }
+}
+/**
+ * Resolves the configured timeouts into `(setting, value)` pairs, or an empty
+ * list when neither is configured.
+ */
+function buildTimeoutSettings(options) {
+    const settings = [];
+    if (options.lockTimeoutMs !== undefined) {
+        assertTimeoutMs(options.lockTimeoutMs, "lockTimeoutMs");
+        settings.push(["lock_timeout", String(options.lockTimeoutMs)]);
+    }
+    if (options.statementTimeoutMs !== undefined) {
+        assertTimeoutMs(options.statementTimeoutMs, "statementTimeoutMs");
+        settings.push(["statement_timeout", String(options.statementTimeoutMs)]);
+    }
+    return settings;
+}
 class KyselyTransactionRunner {
     db;
-    constructor(db) {
+    timeoutSettings;
+    constructor(db, options = {}) {
         this.db = db;
+        this.timeoutSettings = buildTimeoutSettings(options);
     }
     async runInTransaction(callback) {
         const existing = kysely_transaction_context_js_1.KyselyTransactionContext.getTransaction(this.db);
@@ -13,9 +41,28 @@ class KyselyTransactionRunner {
             return callback();
         }
         return this.db.transaction().execute(async (trx) => {
+            await this.applyTimeouts(trx);
             return kysely_transaction_context_js_1.KyselyTransactionContext.run(this.db, trx, callback);
         });
     }
+    /**
+     * Applies the configured timeouts to `trx` as transaction-local settings, so
+     * they are reverted on COMMIT/ROLLBACK and never leak to other users of the
+     * shared pool.
+     *
+     * `set_config(name, value, is_local = true)` is the function form of
+     * `SET LOCAL`, reached through the query builder rather than kysely's `sql`
+     * template on purpose: this package imports kysely for types only, which is
+     * what keeps its CommonJS build loadable (kysely itself is ESM-only). Both
+     * arguments are bound parameters, so no value is ever interpolated into SQL.
+     */
+    async applyTimeouts(trx) {
+        for (const [setting, value] of this.timeoutSettings) {
+            await trx
+                .selectNoFrom((eb) => eb.fn("set_config", [eb.val(setting), eb.val(value), eb.val(true)]).as("set_config"))
+                .executeTakeFirst();
+        }
+    }
 }
 exports.KyselyTransactionRunner = KyselyTransactionRunner;
 //# sourceMappingURL=kysely-transaction-runner.js.map

package/dist/index.d.ts

@@ -1,11 +1,19 @@
 import type { Kysely, Transaction } from "kysely";
 import type { WorkflowPersistenceProvider } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+import { type KyselyTransactionRunnerOptions } from "./kysely-transaction-runner.js";
 export { KyselyTransactionContext } from "./kysely-transaction-context.js";
 export { KyselyTransactionRunner } from "./kysely-transaction-runner.js";
+export type { KyselyTransactionRunnerOptions } from "./kysely-transaction-runner.js";
 export { KyselyWorkflowInstanceStore } from "./kysely-instance-store.js";
 export { KyselyWorkflowHistoryStore } from "./kysely-history-store.js";
-export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable } from "./kysely-database.js";
+export { KyselyWorkflowDefinitionStore } from "./kysely-definition-store.js";
+export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable, WorkflowDefinitionsTable, } from "./kysely-database.js";
+/**
+ * Options accepted by {@link kyselyWorkflowProviders}. Every field is optional
+ * and omitting the argument entirely reproduces the pre-existing behaviour.
+ */
+export type KyselyWorkflowProvidersOptions = KyselyTransactionRunnerOptions;
 /**
  * Creates long-lived persistence providers from a Kysely instance.
  *
@@ -14,7 +22,7 @@ export type { WorkflowDatabase, WorkflowInstancesTable, WorkflowHistoryTable } f
  * only access workflow tables; the `unknown` cast is needed because
  * Kysely is invariant in its DB type parameter).
  */
-export declare function kyselyWorkflowProviders<DB extends WorkflowDatabase>(db: Kysely<DB>): WorkflowPersistenceProvider;
+export declare function kyselyWorkflowProviders<DB extends WorkflowDatabase>(db: Kysely<DB>, options?: KyselyWorkflowProvidersOptions): WorkflowPersistenceProvider;
 /**
  * Creates providers pre-bound to an existing Kysely transaction.
  *

package/dist/index.js

@@ -1,11 +1,13 @@
 import { KyselyWorkflowInstanceStore } from "./kysely-instance-store.js";
 import { KyselyWorkflowHistoryStore } from "./kysely-history-store.js";
+import { KyselyWorkflowDefinitionStore } from "./kysely-definition-store.js";
 import { KyselyTransactionRunner } from "./kysely-transaction-runner.js";
 import { KyselyTransactionContext } from "./kysely-transaction-context.js";
 export { KyselyTransactionContext } from "./kysely-transaction-context.js";
 export { KyselyTransactionRunner } from "./kysely-transaction-runner.js";
 export { KyselyWorkflowInstanceStore } from "./kysely-instance-store.js";
 export { KyselyWorkflowHistoryStore } from "./kysely-history-store.js";
+export { KyselyWorkflowDefinitionStore } from "./kysely-definition-store.js";
 /**
  * Creates long-lived persistence providers from a Kysely instance.
  *
@@ -14,12 +16,13 @@ export { KyselyWorkflowHistoryStore } from "./kysely-history-store.js";
  * only access workflow tables; the `unknown` cast is needed because
  * Kysely is invariant in its DB type parameter).
  */
-export function kyselyWorkflowProviders(db) {
+export function kyselyWorkflowProviders(db, options = {}) {
     const narrowed = db;
-    const transactionRunner = new KyselyTransactionRunner(narrowed);
+    const transactionRunner = new KyselyTransactionRunner(narrowed, options);
     const instanceStore = new KyselyWorkflowInstanceStore(narrowed);
     const historyStore = new KyselyWorkflowHistoryStore(narrowed);
-    return { instanceStore, historyStore, transactionRunner };
+    const definitionStore = new KyselyWorkflowDefinitionStore(narrowed);
+    return { instanceStore, historyStore, transactionRunner, definitionStore };
 }
 /**
  * Creates providers pre-bound to an existing Kysely transaction.
@@ -40,6 +43,7 @@ export function kyselyWorkflowProvidersFromTransaction(trx) {
     };
     const instanceStore = new KyselyWorkflowInstanceStore(narrowed);
     const historyStore = new KyselyWorkflowHistoryStore(narrowed);
-    return { instanceStore, historyStore, transactionRunner };
+    const definitionStore = new KyselyWorkflowDefinitionStore(narrowed);
+    return { instanceStore, historyStore, transactionRunner, definitionStore };
 }
 //# sourceMappingURL=index.js.map

package/dist/kysely-database.d.ts

@@ -17,6 +17,7 @@ export interface WorkflowInstancesTable {
     workflow_name: string;
     current_state: string;
     version: number;
+    definition_version: number | null;
     expires_at: Date | null;
     last_transition_at: Date;
     context_json: JsonObjectColumn;
@@ -35,11 +36,20 @@ export interface WorkflowHistoryTable {
     rejected_by: string | null;
     command_results_json: JsonArrayColumn;
     trigger_metadata_json: JsonObjectColumn;
+    definition_version: number | null;
     created_at: Generated<Date>;
 }
+export interface WorkflowDefinitionsTable {
+    workflow_name: string;
+    version: number;
+    content_hash: string;
+    definition_json: JsonObjectColumn;
+    registered_at: Generated<Date>;
+}
 export interface WorkflowDatabase {
     workflow_instances: WorkflowInstancesTable;
     workflow_history: WorkflowHistoryTable;
+    workflow_definitions: WorkflowDefinitionsTable;
 }
 export {};
 //# sourceMappingURL=kysely-database.d.ts.map

package/dist/kysely-definition-store.d.ts

@@ -0,0 +1,17 @@
+import type { Kysely } from "kysely";
+import type { WorkflowDefinitionStore, StoredWorkflowDefinition, WorkflowDefinition } from "@duraflows/core";
+import type { WorkflowDatabase } from "./kysely-database.js";
+export declare class KyselyWorkflowDefinitionStore implements WorkflowDefinitionStore {
+    private readonly db;
+    constructor(db: Kysely<WorkflowDatabase>);
+    private getExecutor;
+    ensure(record: {
+        workflowName: string;
+        version: number;
+        contentHash: string;
+        definitionJson: WorkflowDefinition;
+    }): Promise<StoredWorkflowDefinition>;
+    findByNameAndVersion(workflowName: string, version: number): Promise<StoredWorkflowDefinition | null>;
+    private mapRow;
+}
+//# sourceMappingURL=kysely-definition-store.d.ts.map

package/dist/kysely-definition-store.js

@@ -0,0 +1,53 @@
+import { WorkflowError } from "@duraflows/core";
+import { KyselyTransactionContext } from "./kysely-transaction-context.js";
+export class KyselyWorkflowDefinitionStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    getExecutor() {
+        return KyselyTransactionContext.getTransaction(this.db) ?? this.db;
+    }
+    async ensure(record) {
+        const executor = this.getExecutor();
+        await executor
+            .insertInto("workflow_definitions")
+            .values({
+            workflow_name: record.workflowName,
+            version: record.version,
+            content_hash: record.contentHash,
+            definition_json: JSON.stringify(record.definitionJson),
+        })
+            .onConflict((oc) => oc.columns(["workflow_name", "version"]).doNothing())
+            .execute();
+        const stored = await this.findByNameAndVersion(record.workflowName, record.version);
+        if (!stored) {
+            // The row we just ensured must exist; its absence means the statement
+            // did not do what the adapter assumes. Fail loudly.
+            throw new WorkflowError(`Failed to ensure workflow definition "${record.workflowName}" version ${record.version}`);
+        }
+        return stored;
+    }
+    async findByNameAndVersion(workflowName, version) {
+        const executor = this.getExecutor();
+        const row = await executor
+            .selectFrom("workflow_definitions")
+            .selectAll()
+            .where("workflow_name", "=", workflowName)
+            .where("version", "=", version)
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        return this.mapRow(row);
+    }
+    mapRow(row) {
+        return {
+            workflowName: row.workflow_name,
+            version: row.version,
+            contentHash: row.content_hash,
+            definitionJson: row.definition_json,
+            registeredAt: row.registered_at,
+        };
+    }
+}
+//# sourceMappingURL=kysely-definition-store.js.map

package/dist/kysely-history-store.js

@@ -1,3 +1,4 @@
+import { WorkflowError } from "@duraflows/core";
 import { KyselyTransactionContext } from "./kysely-transaction-context.js";
 export class KyselyWorkflowHistoryStore {
     db;
@@ -21,9 +22,13 @@ export class KyselyWorkflowHistoryStore {
             rejected_by: entry.rejectedBy ?? null,
             command_results_json: JSON.stringify(entry.commandResultsJson),
             trigger_metadata_json: JSON.stringify(entry.triggerMetadata ?? {}),
+            definition_version: entry.definitionVersion ?? null,
         })
             .returning("uuid")
-            .executeTakeFirstOrThrow();
+            // `INSERT ... RETURNING` always yields a row, so an empty result means the
+            // statement did not do what the adapter assumes. Surface that as the
+            // library's own error type rather than kysely's `NoResultError`.
+            .executeTakeFirstOrThrow(() => new WorkflowError("Failed to append workflow history: INSERT ... RETURNING uuid returned no row"));
         return row.uuid;
     }
     async findByInstanceUuid(workflowInstanceUuid, options) {
@@ -49,6 +54,8 @@ export class KyselyWorkflowHistoryStore {
             rejectedBy: row.rejected_by ?? undefined,
             commandResultsJson: row.command_results_json,
             triggerMetadata: row.trigger_metadata_json,
+            definitionVersion: row.definition_version ?? undefined,
+            createdAt: row.created_at,
         }));
     }
 }

package/dist/kysely-instance-store.js

@@ -17,6 +17,7 @@ export class KyselyWorkflowInstanceStore {
             workflow_name: instance.workflowName,
             current_state: instance.currentState,
             version: instance.version,
+            definition_version: instance.definitionVersion,
             expires_at: instance.expiresAt,
             last_transition_at: instance.lastTransitionAt,
             context_json: JSON.stringify(instance.context),
@@ -56,6 +57,7 @@ export class KyselyWorkflowInstanceStore {
             .set({
             current_state: instance.currentState,
             version: instance.version,
+            definition_version: instance.definitionVersion,
             expires_at: instance.expiresAt,
             last_transition_at: instance.lastTransitionAt,
             context_json: JSON.stringify(instance.context),
@@ -92,6 +94,7 @@ export class KyselyWorkflowInstanceStore {
             workflowName: row.workflow_name,
             currentState: row.current_state,
             version: row.version,
+            definitionVersion: row.definition_version ?? null,
             expiresAt: row.expires_at,
             lastTransitionAt: row.last_transition_at,
             context: row.context_json,

package/dist/kysely-transaction-runner.d.ts

@@ -1,9 +1,47 @@
 import type { Kysely } from "kysely";
 import type { WorkflowTransactionRunner } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+/**
+ * Transaction-scoped PostgreSQL timeouts.
+ *
+ * Both settings are optional and both default to unset: when neither is
+ * supplied the runner issues no extra statement at all, leaving the session and
+ * server defaults exactly as they were before this option existed.
+ */
+export interface KyselyTransactionRunnerOptions {
+    /**
+     * `lock_timeout` in milliseconds -- how long a statement waits for a row lock
+     * before it aborts. This is the recommended setting: it bounds the blocking
+     * `SELECT ... FOR UPDATE` behind `lockByUuid()`, so a stuck lock holder cannot
+     * hang a `triggerEvent()` call indefinitely while it keeps a pooled connection
+     * checked out. `0` disables the timeout (PostgreSQL's own default).
+     */
+    lockTimeoutMs?: number;
+    /**
+     * `statement_timeout` in milliseconds -- how long any single statement may run
+     * before it aborts. Deliberately unset by default: commands run inside the
+     * same transaction and may legitimately issue slow statements on the shared
+     * connection, and aborting one of those rolls the whole transition back.
+     * `0` disables the timeout (PostgreSQL's own default).
+     */
+    statementTimeoutMs?: number;
+}
 export declare class KyselyTransactionRunner implements WorkflowTransactionRunner {
     private readonly db;
-    constructor(db: Kysely<WorkflowDatabase>);
+    private readonly timeoutSettings;
+    constructor(db: Kysely<WorkflowDatabase>, options?: KyselyTransactionRunnerOptions);
     runInTransaction<T>(callback: () => Promise<T>): Promise<T>;
+    /**
+     * Applies the configured timeouts to `trx` as transaction-local settings, so
+     * they are reverted on COMMIT/ROLLBACK and never leak to other users of the
+     * shared pool.
+     *
+     * `set_config(name, value, is_local = true)` is the function form of
+     * `SET LOCAL`, reached through the query builder rather than kysely's `sql`
+     * template on purpose: this package imports kysely for types only, which is
+     * what keeps its CommonJS build loadable (kysely itself is ESM-only). Both
+     * arguments are bound parameters, so no value is ever interpolated into SQL.
+     */
+    private applyTimeouts;
 }
 //# sourceMappingURL=kysely-transaction-runner.d.ts.map

package/dist/kysely-transaction-runner.js

@@ -1,8 +1,36 @@
+import { WorkflowError } from "@duraflows/core";
 import { KyselyTransactionContext } from "./kysely-transaction-context.js";
+/**
+ * Rejects anything that is not a finite, non-negative integer. Called at
+ * construction time so an invalid value can never reach the database.
+ */
+function assertTimeoutMs(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new WorkflowError(`${name} must be a non-negative integer number of milliseconds, got ${value}`);
+    }
+}
+/**
+ * Resolves the configured timeouts into `(setting, value)` pairs, or an empty
+ * list when neither is configured.
+ */
+function buildTimeoutSettings(options) {
+    const settings = [];
+    if (options.lockTimeoutMs !== undefined) {
+        assertTimeoutMs(options.lockTimeoutMs, "lockTimeoutMs");
+        settings.push(["lock_timeout", String(options.lockTimeoutMs)]);
+    }
+    if (options.statementTimeoutMs !== undefined) {
+        assertTimeoutMs(options.statementTimeoutMs, "statementTimeoutMs");
+        settings.push(["statement_timeout", String(options.statementTimeoutMs)]);
+    }
+    return settings;
+}
 export class KyselyTransactionRunner {
     db;
-    constructor(db) {
+    timeoutSettings;
+    constructor(db, options = {}) {
         this.db = db;
+        this.timeoutSettings = buildTimeoutSettings(options);
     }
     async runInTransaction(callback) {
         const existing = KyselyTransactionContext.getTransaction(this.db);
@@ -10,8 +38,27 @@ export class KyselyTransactionRunner {
             return callback();
         }
         return this.db.transaction().execute(async (trx) => {
+            await this.applyTimeouts(trx);
             return KyselyTransactionContext.run(this.db, trx, callback);
         });
     }
+    /**
+     * Applies the configured timeouts to `trx` as transaction-local settings, so
+     * they are reverted on COMMIT/ROLLBACK and never leak to other users of the
+     * shared pool.
+     *
+     * `set_config(name, value, is_local = true)` is the function form of
+     * `SET LOCAL`, reached through the query builder rather than kysely's `sql`
+     * template on purpose: this package imports kysely for types only, which is
+     * what keeps its CommonJS build loadable (kysely itself is ESM-only). Both
+     * arguments are bound parameters, so no value is ever interpolated into SQL.
+     */
+    async applyTimeouts(trx) {
+        for (const [setting, value] of this.timeoutSettings) {
+            await trx
+                .selectNoFrom((eb) => eb.fn("set_config", [eb.val(setting), eb.val(value), eb.val(true)]).as("set_config"))
+                .executeTakeFirst();
+        }
+    }
 }
 //# sourceMappingURL=kysely-transaction-runner.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duraflows/kysely",
-  "version": "4.0.1",
+  "version": "5.0.0",
   "description": "PostgreSQL persistence adapter for duraflows using `kysely`. Integrates with kysely's type-safe query builder and AsyncLocalStorage-based transaction context.",
   "keywords": [
     "duraflows",
@@ -51,15 +51,15 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@duraflows/core": "^4.0.1",
-    "kysely": "^0.29.4"
+    "@duraflows/core": "^5.0.0",
+    "kysely": "^0.29.5"
   },
   "devDependencies": {
-    "@types/pg": "^8.20.4",
-    "kysely": "^0.29.4",
-    "pg": "^8.22.0",
-    "@duraflows/core": "4.0.1",
-    "@duraflows/pg": "4.0.1"
+    "@types/pg": "^8.21.0",
+    "kysely": "^0.29.5",
+    "pg": "^8.23.0",
+    "@duraflows/core": "5.0.0",
+    "@duraflows/pg": "5.0.0"
   },
   "scripts": {
     "build": "tsc --build"