@duraflows/kysely 5.1.0 → 5.2.1

package/README.md

@@ -49,27 +49,42 @@ The primary use case for this package is running Duraflows workflow transitions
 ```ts
 import { KyselyTransactionContext } from "@duraflows/kysely";
 
-// Seed the transaction context so Duraflows participates in your transaction
-await db.transaction().execute(async (trx) => {
-  await KyselyTransactionContext.run(db, trx, async () => {
-    // Your own writes -- uses trx
-    await trx.insertInto("orders").values({ id: "ORD-1", status: "paid" }).execute();
-
-    // Duraflows writes -- also uses trx (same transaction)
-    await runtime.triggerEvent({
-      workflowInstanceUuid: instanceUuid,
-      eventName: "PaymentReceived",
-    });
+await KyselyTransactionContext.transaction(db, async (trx) => {
+  // Your own writes -- uses trx
+  await trx.insertInto("orders").values({ id: "ORD-1", status: "paid" }).execute();
+
+  // Duraflows writes -- also uses trx (same transaction)
+  await runtime.triggerEvent({
+    workflowInstanceUuid: instanceUuid,
+    eventName: "PaymentReceived",
   });
 });
-// Both commit or both rollback -- no split-brain
+// Both commit or both roll back. Observers fire after COMMIT, never after a rollback.
 ```
 
+Each duraflows call inside runs in its own savepoint. If one fails, its writes are rolled back, and your transaction can carry on if you catch the error. Calling `transaction()` inside one that is already active joins it as a savepoint instead of opening a second transaction, so composed service methods stay atomic.
+
+"Never after a rollback" has one caveat: if a statement failed and you swallowed its error, PostgreSQL silently turns kysely's `COMMIT` into a rollback, and kysely can't see that. Observers then fire for writes that were never persisted. Don't swallow SQL errors inside a transaction: let them propagate, or run the statement in a nested `KyselyTransactionContext.transaction()` and catch its rejection, which rolls back only that savepoint.
+
+The runner's `lockTimeoutMs` / `statementTimeoutMs` don't apply inside `transaction()` or a seeded `run()`: you own those transaction settings, and nested duraflows calls run under them.
+
+If you already open the transaction yourself, you can still seed the context:
+
+```ts
+await db.transaction().execute((trx) =>
+  KyselyTransactionContext.run(db, trx, async () => {
+    await runtime.triggerEvent({ workflowInstanceUuid: instanceUuid, eventName: "PaymentReceived" });
+  }),
+);
+```
+
+Observers then fire when the seeded callback resolves, which is **before** kysely commits, and duraflows calls they make join your still-open transaction. Prefer `transaction()` when observers must never see a rolled-back write. Don't run duraflows calls concurrently (`Promise.all`) on one transaction.
+
 ### How It Works
 
 `KyselyTransactionContext` uses Node.js `AsyncLocalStorage` to propagate the active Kysely transaction through the async call chain. When Duraflows' internal `WorkflowTransactionRunner.runInTransaction()` is called, it checks for an existing transaction in the context:
 
-- **Found:** Reuses it (no nested transaction)
+- **Found:** Runs the call in a savepoint on it (`SAVEPOINT` … `RELEASE`, or `ROLLBACK TO` on failure)
 - **Not found:** Starts a new Kysely transaction and seeds the context
 
 This re-entrancy contract means your application code controls the transaction boundary.
@@ -127,7 +142,9 @@ Both are applied transaction-locally via `set_config(name, value, true)` — the
 
 ### `kyselyWorkflowProvidersFromTransaction(trx): WorkflowPersistenceProvider`
 
-Convenience factory for short-lived runtimes pre-bound to an existing transaction. The returned transaction runner seeds the context with the bound `trx` if no context already exists.
+Convenience factory for short-lived runtimes pre-bound to an existing transaction. Each workflow call runs in a savepoint on `trx`, so a failed call leaves no partial writes behind even if you catch its error. Observers fire when the call resolves, before your transaction commits, and duraflows calls they make join `trx`. For strictly post-commit observers, use `KyselyTransactionContext.transaction(db, …)` with the long-lived providers instead.
+
+Don't mix these providers with the long-lived `kyselyWorkflowProviders(db)` (or `KyselyTransactionContext.transaction(db, …)`) inside one transaction. The two track their active transaction separately, one per `trx` and the other per `db`, so a call through one doesn't see a transaction opened through the other. It starts a second transaction on another connection instead, which can wait on row locks the first one holds. Use one style per transaction.
 
 ### `KyselyTransactionContext`
 
@@ -135,6 +152,7 @@ The context is scoped per Kysely instance:
 
 - `getTransaction(db)` -- Returns the active `Transaction<WorkflowDatabase>` for the given `db` instance, or `undefined`
 - `run(db, trx, callback)` -- Executes `callback` with `trx` as the active transaction context for the given `db` instance
+- `transaction(db, callback)` -- Runs `callback(trx)` in a new transaction on `db` with `trx` active for workflow calls; observers fire after it commits. Inside an already-active transaction for `db`, it joins that transaction as a savepoint instead
 
 ## Documentation
 

package/dist/cjs/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KyselyWorkflowDefinitionStore = exports.KyselyWorkflowHistoryStore = exports.KyselyWorkflowInstanceStore = exports.KyselyTransactionRunner = exports.KyselyTransactionContext = void 0;
 exports.kyselyWorkflowProviders = kyselyWorkflowProviders;
 exports.kyselyWorkflowProvidersFromTransaction = kyselyWorkflowProvidersFromTransaction;
+const core_1 = require("@duraflows/core");
 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");
@@ -41,14 +42,28 @@ function kyselyWorkflowProviders(db, options = {}) {
  */
 function kyselyWorkflowProvidersFromTransaction(trx) {
     const narrowed = trx;
+    const boundTrx = trx;
     const transactionRunner = {
         async runInTransaction(callback) {
-            // Nested calls reuse the bound transaction; an unrelated ambient
-            // transaction from another provider must never supersede it.
-            if (kysely_transaction_context_js_1.KyselyTransactionContext.getTransaction(narrowed)) {
-                return callback();
+            // Scoped to the bound trx; an unrelated ambient transaction from another
+            // provider must never supersede it.
+            const scope = kysely_transaction_context_js_1.kyselyTransactionScopes.current(narrowed);
+            if (scope) {
+                return (0, kysely_transaction_context_js_1.runInKyselySavepoint)(narrowed, scope, callback);
             }
-            return kysely_transaction_context_js_1.KyselyTransactionContext.run(narrowed, trx, callback);
+            // The caller owns `trx`, so even this outermost call is nested in their
+            // transaction: run it in a savepoint so a failure leaves no partial
+            // writes behind, and deliver its observers once it resolves. `trx` is
+            // still open then, so the observers run inside the root scope: a
+            // duraflows call they make joins `trx` as a savepoint, and the
+            // callbacks it queues drain in the same pass.
+            const root = kysely_transaction_context_js_1.kyselyTransactionScopes.createRoot(boundTrx);
+            const result = await kysely_transaction_context_js_1.kyselyTransactionScopes.run(narrowed, root, () => (0, kysely_transaction_context_js_1.runInKyselySavepoint)(narrowed, root, callback));
+            await kysely_transaction_context_js_1.kyselyTransactionScopes.run(narrowed, root, () => (0, core_1.runAfterCommitCallbacks)(root.callbacks));
+            return result;
+        },
+        afterCommit(callback) {
+            kysely_transaction_context_js_1.kyselyTransactionScopes.afterCommit(narrowed, callback);
         },
     };
     const instanceStore = new kysely_instance_store_js_1.KyselyWorkflowInstanceStore(narrowed);

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

@@ -1,9 +1,30 @@
 import type { Kysely, Transaction } from "kysely";
+import { ScopedTransactionContext, type TransactionScope } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+type WorkflowTransaction = Transaction<WorkflowDatabase>;
+/** @internal Shared with the runners; not part of the public API. */
+export declare const kyselyTransactionScopes: ScopedTransactionContext<Kysely<WorkflowDatabase>, WorkflowTransaction>;
+/**
+ * @internal Runs `callback` in a savepoint nested in `scope`, issuing the
+ * savepoint statements on that scope's own transaction. Every kysely entry
+ * point that nests (the runners and `transaction()`) goes through here.
+ */
+export declare function runInKyselySavepoint<T>(owner: Kysely<WorkflowDatabase>, scope: TransactionScope<WorkflowTransaction>, callback: () => Promise<T>): Promise<T>;
+/**
+ * @internal Runs `callback` as the root of a new kysely transaction on `db`
+ * (after `setup`, e.g. transaction-local timeouts), and only once kysely has
+ * committed runs the after-commit callbacks queued inside. On error kysely
+ * rolls back and the callbacks are dropped.
+ */
+export declare function runOwnedKyselyTransaction<T>(db: Kysely<WorkflowDatabase>, setup: (trx: WorkflowTransaction) => Promise<void>, callback: (trx: WorkflowTransaction) => Promise<T>): Promise<T>;
 export declare const KyselyTransactionContext: {
-    getTransaction(owner: Kysely<WorkflowDatabase>): Transaction<WorkflowDatabase> | undefined;
+    getTransaction(owner: Kysely<WorkflowDatabase>): WorkflowTransaction | undefined;
     /**
-     * Executes callback with `trx` as the active transaction for `owner`.
+     * Executes callback with `trx` as the active transaction for `owner`. You
+     * own the transaction. Workflow calls inside run in savepoints, and their
+     * observers fire when `callback`'s promise resolves (before your COMMIT);
+     * nothing fires if it rejects. Use {@link KyselyTransactionContext.transaction}
+     * for delivery strictly after COMMIT.
      *
      * Generic so callers can pass `Transaction<MyDb & WorkflowDatabase>`
      * (Kysely is invariant in DB, so a non-generic signature would reject
@@ -12,5 +33,20 @@ export declare const KyselyTransactionContext: {
      * workflow tables.
      */
     run<T, DB extends WorkflowDatabase = WorkflowDatabase>(owner: Kysely<WorkflowDatabase>, trx: Transaction<DB>, callback: () => T): T;
+    /**
+     * Runs `callback` in a new transaction on `db` (`db.transaction().execute`),
+     * with that transaction active for workflow calls. Observers of workflow
+     * calls made inside fire after the transaction commits, and never if it
+     * rolls back.
+     *
+     * Called while a transaction for `db` is already active (an outer
+     * `transaction()`, a workflow call, or a seeded `run()`), it joins that
+     * transaction instead: `callback` receives the existing transaction and runs
+     * in a savepoint, which is released on success (its observers then wait for
+     * the enclosing transaction) and rolled back on failure (its observers are
+     * dropped).
+     */
+    transaction<T, DB extends WorkflowDatabase = WorkflowDatabase>(db: Kysely<DB>, callback: (trx: Transaction<DB>) => Promise<T>): Promise<T>;
 };
+export {};
 //# sourceMappingURL=kysely-transaction-context.d.ts.map

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

@@ -1,24 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KyselyTransactionContext = void 0;
-const node_async_hooks_1 = require("node:async_hooks");
-// One context per Kysely instance (or per pre-bound Transaction): a
-// transaction on db A is invisible to stores and runners bound to db B.
-const storages = new WeakMap();
-function storageFor(owner) {
-    let storage = storages.get(owner);
-    if (!storage) {
-        storage = new node_async_hooks_1.AsyncLocalStorage();
-        storages.set(owner, storage);
+exports.KyselyTransactionContext = exports.kyselyTransactionScopes = void 0;
+exports.runInKyselySavepoint = runInKyselySavepoint;
+exports.runOwnedKyselyTransaction = runOwnedKyselyTransaction;
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@duraflows/core");
+// One context per Kysely instance, so a transaction on db A is invisible to
+// stores and runners bound to db B.
+/** @internal Shared with the runners; not part of the public API. */
+exports.kyselyTransactionScopes = new core_1.ScopedTransactionContext();
+/**
+ * Runs one fixed SQL statement (a savepoint command) on `trx`.
+ *
+ * `Transaction` has no savepoint API in kysely 0.29 (only `ControlledTransaction`
+ * does), and this package imports kysely for types only, since kysely is
+ * ESM-only and a runtime import would break the CommonJS build. So the
+ * statement is handed to `executeQuery` as a compiled query built by hand,
+ * shaped exactly like `CompiledQuery.raw(sql)`. `sql` is always an internally
+ * generated `SAVEPOINT` / `RELEASE` / `ROLLBACK TO` statement, never user input.
+ */
+function executeRawStatement(trx, sql) {
+    const query = {
+        sql,
+        parameters: [],
+        query: { kind: "RawNode", sqlFragments: [sql], parameters: [] },
+        queryId: { queryId: `duraflows_${(0, node_crypto_1.randomUUID)()}` },
+    };
+    return trx.executeQuery(query);
+}
+/**
+ * @internal Runs `callback` in a savepoint nested in `scope`, issuing the
+ * savepoint statements on that scope's own transaction. Every kysely entry
+ * point that nests (the runners and `transaction()`) goes through here.
+ */
+function runInKyselySavepoint(owner, scope, callback) {
+    return exports.kyselyTransactionScopes.runInSavepoint(owner, scope, callback, (sql) => executeRawStatement(scope.connection, sql));
+}
+/**
+ * @internal Runs `callback` as the root of a new kysely transaction on `db`
+ * (after `setup`, e.g. transaction-local timeouts), and only once kysely has
+ * committed runs the after-commit callbacks queued inside. On error kysely
+ * rolls back and the callbacks are dropped.
+ */
+async function runOwnedKyselyTransaction(db, setup, callback) {
+    let root;
+    const result = await db.transaction().execute(async (trx) => {
+        await setup(trx);
+        const scope = exports.kyselyTransactionScopes.createRoot(trx);
+        root = scope;
+        return exports.kyselyTransactionScopes.run(db, scope, () => callback(trx));
+    });
+    if (root) {
+        await (0, core_1.runAfterCommitCallbacks)(root.callbacks);
     }
-    return storage;
+    return result;
 }
 exports.KyselyTransactionContext = {
     getTransaction(owner) {
-        return storages.get(owner)?.getStore();
+        return exports.kyselyTransactionScopes.current(owner)?.connection;
     },
     /**
-     * Executes callback with `trx` as the active transaction for `owner`.
+     * Executes callback with `trx` as the active transaction for `owner`. You
+     * own the transaction. Workflow calls inside run in savepoints, and their
+     * observers fire when `callback`'s promise resolves (before your COMMIT);
+     * nothing fires if it rejects. Use {@link KyselyTransactionContext.transaction}
+     * for delivery strictly after COMMIT.
      *
      * Generic so callers can pass `Transaction<MyDb & WorkflowDatabase>`
      * (Kysely is invariant in DB, so a non-generic signature would reject
@@ -27,7 +73,28 @@ exports.KyselyTransactionContext = {
      * workflow tables.
      */
     run(owner, trx, callback) {
-        return storageFor(owner).run(trx, callback);
+        return exports.kyselyTransactionScopes.runSeeded(owner, trx, callback);
+    },
+    /**
+     * Runs `callback` in a new transaction on `db` (`db.transaction().execute`),
+     * with that transaction active for workflow calls. Observers of workflow
+     * calls made inside fire after the transaction commits, and never if it
+     * rolls back.
+     *
+     * Called while a transaction for `db` is already active (an outer
+     * `transaction()`, a workflow call, or a seeded `run()`), it joins that
+     * transaction instead: `callback` receives the existing transaction and runs
+     * in a savepoint, which is released on success (its observers then wait for
+     * the enclosing transaction) and rolled back on failure (its observers are
+     * dropped).
+     */
+    transaction(db, callback) {
+        const owner = db;
+        const scope = exports.kyselyTransactionScopes.current(owner);
+        if (scope) {
+            return runInKyselySavepoint(owner, scope, () => callback(scope.connection));
+        }
+        return runOwnedKyselyTransaction(owner, async () => { }, (trx) => callback(trx));
     },
 };
 //# sourceMappingURL=kysely-transaction-context.js.map

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

@@ -1,5 +1,5 @@
 import type { Kysely } from "kysely";
-import type { WorkflowTransactionRunner } from "@duraflows/core";
+import type { AfterCommitCallback, WorkflowTransactionRunner } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
 /**
  * Transaction-scoped PostgreSQL timeouts.
@@ -31,6 +31,7 @@ export declare class KyselyTransactionRunner implements WorkflowTransactionRunne
     private readonly timeoutSettings;
     constructor(db: Kysely<WorkflowDatabase>, options?: KyselyTransactionRunnerOptions);
     runInTransaction<T>(callback: () => Promise<T>): Promise<T>;
+    afterCommit(callback: AfterCommitCallback): void;
     /**
      * 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

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

@@ -36,14 +36,16 @@ class KyselyTransactionRunner {
         this.timeoutSettings = buildTimeoutSettings(options);
     }
     async runInTransaction(callback) {
-        const existing = kysely_transaction_context_js_1.KyselyTransactionContext.getTransaction(this.db);
-        if (existing) {
-            return callback();
+        const scope = kysely_transaction_context_js_1.kyselyTransactionScopes.current(this.db);
+        if (scope) {
+            // Nested: a savepoint on the outer transaction, so a failure rolls back
+            // only this call. The outer transaction's timeouts stay in force.
+            return (0, kysely_transaction_context_js_1.runInKyselySavepoint)(this.db, scope, callback);
         }
-        return this.db.transaction().execute(async (trx) => {
-            await this.applyTimeouts(trx);
-            return kysely_transaction_context_js_1.KyselyTransactionContext.run(this.db, trx, callback);
-        });
+        return (0, kysely_transaction_context_js_1.runOwnedKyselyTransaction)(this.db, (trx) => this.applyTimeouts(trx), () => callback());
+    }
+    afterCommit(callback) {
+        kysely_transaction_context_js_1.kyselyTransactionScopes.afterCommit(this.db, callback);
     }
     /**
      * Applies the configured timeouts to `trx` as transaction-local settings, so

package/dist/index.js

@@ -1,8 +1,9 @@
+import { runAfterCommitCallbacks } from "@duraflows/core";
 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";
+import { kyselyTransactionScopes, runInKyselySavepoint } 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";
@@ -31,14 +32,28 @@ export function kyselyWorkflowProviders(db, options = {}) {
  */
 export function kyselyWorkflowProvidersFromTransaction(trx) {
     const narrowed = trx;
+    const boundTrx = trx;
     const transactionRunner = {
         async runInTransaction(callback) {
-            // Nested calls reuse the bound transaction; an unrelated ambient
-            // transaction from another provider must never supersede it.
-            if (KyselyTransactionContext.getTransaction(narrowed)) {
-                return callback();
+            // Scoped to the bound trx; an unrelated ambient transaction from another
+            // provider must never supersede it.
+            const scope = kyselyTransactionScopes.current(narrowed);
+            if (scope) {
+                return runInKyselySavepoint(narrowed, scope, callback);
             }
-            return KyselyTransactionContext.run(narrowed, trx, callback);
+            // The caller owns `trx`, so even this outermost call is nested in their
+            // transaction: run it in a savepoint so a failure leaves no partial
+            // writes behind, and deliver its observers once it resolves. `trx` is
+            // still open then, so the observers run inside the root scope: a
+            // duraflows call they make joins `trx` as a savepoint, and the
+            // callbacks it queues drain in the same pass.
+            const root = kyselyTransactionScopes.createRoot(boundTrx);
+            const result = await kyselyTransactionScopes.run(narrowed, root, () => runInKyselySavepoint(narrowed, root, callback));
+            await kyselyTransactionScopes.run(narrowed, root, () => runAfterCommitCallbacks(root.callbacks));
+            return result;
+        },
+        afterCommit(callback) {
+            kyselyTransactionScopes.afterCommit(narrowed, callback);
         },
     };
     const instanceStore = new KyselyWorkflowInstanceStore(narrowed);

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

@@ -1,9 +1,30 @@
 import type { Kysely, Transaction } from "kysely";
+import { ScopedTransactionContext, type TransactionScope } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
+type WorkflowTransaction = Transaction<WorkflowDatabase>;
+/** @internal Shared with the runners; not part of the public API. */
+export declare const kyselyTransactionScopes: ScopedTransactionContext<Kysely<WorkflowDatabase>, WorkflowTransaction>;
+/**
+ * @internal Runs `callback` in a savepoint nested in `scope`, issuing the
+ * savepoint statements on that scope's own transaction. Every kysely entry
+ * point that nests (the runners and `transaction()`) goes through here.
+ */
+export declare function runInKyselySavepoint<T>(owner: Kysely<WorkflowDatabase>, scope: TransactionScope<WorkflowTransaction>, callback: () => Promise<T>): Promise<T>;
+/**
+ * @internal Runs `callback` as the root of a new kysely transaction on `db`
+ * (after `setup`, e.g. transaction-local timeouts), and only once kysely has
+ * committed runs the after-commit callbacks queued inside. On error kysely
+ * rolls back and the callbacks are dropped.
+ */
+export declare function runOwnedKyselyTransaction<T>(db: Kysely<WorkflowDatabase>, setup: (trx: WorkflowTransaction) => Promise<void>, callback: (trx: WorkflowTransaction) => Promise<T>): Promise<T>;
 export declare const KyselyTransactionContext: {
-    getTransaction(owner: Kysely<WorkflowDatabase>): Transaction<WorkflowDatabase> | undefined;
+    getTransaction(owner: Kysely<WorkflowDatabase>): WorkflowTransaction | undefined;
     /**
-     * Executes callback with `trx` as the active transaction for `owner`.
+     * Executes callback with `trx` as the active transaction for `owner`. You
+     * own the transaction. Workflow calls inside run in savepoints, and their
+     * observers fire when `callback`'s promise resolves (before your COMMIT);
+     * nothing fires if it rejects. Use {@link KyselyTransactionContext.transaction}
+     * for delivery strictly after COMMIT.
      *
      * Generic so callers can pass `Transaction<MyDb & WorkflowDatabase>`
      * (Kysely is invariant in DB, so a non-generic signature would reject
@@ -12,5 +33,20 @@ export declare const KyselyTransactionContext: {
      * workflow tables.
      */
     run<T, DB extends WorkflowDatabase = WorkflowDatabase>(owner: Kysely<WorkflowDatabase>, trx: Transaction<DB>, callback: () => T): T;
+    /**
+     * Runs `callback` in a new transaction on `db` (`db.transaction().execute`),
+     * with that transaction active for workflow calls. Observers of workflow
+     * calls made inside fire after the transaction commits, and never if it
+     * rolls back.
+     *
+     * Called while a transaction for `db` is already active (an outer
+     * `transaction()`, a workflow call, or a seeded `run()`), it joins that
+     * transaction instead: `callback` receives the existing transaction and runs
+     * in a savepoint, which is released on success (its observers then wait for
+     * the enclosing transaction) and rolled back on failure (its observers are
+     * dropped).
+     */
+    transaction<T, DB extends WorkflowDatabase = WorkflowDatabase>(db: Kysely<DB>, callback: (trx: Transaction<DB>) => Promise<T>): Promise<T>;
 };
+export {};
 //# sourceMappingURL=kysely-transaction-context.d.ts.map

package/dist/kysely-transaction-context.js

@@ -1,21 +1,65 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-// One context per Kysely instance (or per pre-bound Transaction): a
-// transaction on db A is invisible to stores and runners bound to db B.
-const storages = new WeakMap();
-function storageFor(owner) {
-    let storage = storages.get(owner);
-    if (!storage) {
-        storage = new AsyncLocalStorage();
-        storages.set(owner, storage);
+import { randomUUID } from "node:crypto";
+import { ScopedTransactionContext, runAfterCommitCallbacks } from "@duraflows/core";
+// One context per Kysely instance, so a transaction on db A is invisible to
+// stores and runners bound to db B.
+/** @internal Shared with the runners; not part of the public API. */
+export const kyselyTransactionScopes = new ScopedTransactionContext();
+/**
+ * Runs one fixed SQL statement (a savepoint command) on `trx`.
+ *
+ * `Transaction` has no savepoint API in kysely 0.29 (only `ControlledTransaction`
+ * does), and this package imports kysely for types only, since kysely is
+ * ESM-only and a runtime import would break the CommonJS build. So the
+ * statement is handed to `executeQuery` as a compiled query built by hand,
+ * shaped exactly like `CompiledQuery.raw(sql)`. `sql` is always an internally
+ * generated `SAVEPOINT` / `RELEASE` / `ROLLBACK TO` statement, never user input.
+ */
+function executeRawStatement(trx, sql) {
+    const query = {
+        sql,
+        parameters: [],
+        query: { kind: "RawNode", sqlFragments: [sql], parameters: [] },
+        queryId: { queryId: `duraflows_${randomUUID()}` },
+    };
+    return trx.executeQuery(query);
+}
+/**
+ * @internal Runs `callback` in a savepoint nested in `scope`, issuing the
+ * savepoint statements on that scope's own transaction. Every kysely entry
+ * point that nests (the runners and `transaction()`) goes through here.
+ */
+export function runInKyselySavepoint(owner, scope, callback) {
+    return kyselyTransactionScopes.runInSavepoint(owner, scope, callback, (sql) => executeRawStatement(scope.connection, sql));
+}
+/**
+ * @internal Runs `callback` as the root of a new kysely transaction on `db`
+ * (after `setup`, e.g. transaction-local timeouts), and only once kysely has
+ * committed runs the after-commit callbacks queued inside. On error kysely
+ * rolls back and the callbacks are dropped.
+ */
+export async function runOwnedKyselyTransaction(db, setup, callback) {
+    let root;
+    const result = await db.transaction().execute(async (trx) => {
+        await setup(trx);
+        const scope = kyselyTransactionScopes.createRoot(trx);
+        root = scope;
+        return kyselyTransactionScopes.run(db, scope, () => callback(trx));
+    });
+    if (root) {
+        await runAfterCommitCallbacks(root.callbacks);
     }
-    return storage;
+    return result;
 }
 export const KyselyTransactionContext = {
     getTransaction(owner) {
-        return storages.get(owner)?.getStore();
+        return kyselyTransactionScopes.current(owner)?.connection;
     },
     /**
-     * Executes callback with `trx` as the active transaction for `owner`.
+     * Executes callback with `trx` as the active transaction for `owner`. You
+     * own the transaction. Workflow calls inside run in savepoints, and their
+     * observers fire when `callback`'s promise resolves (before your COMMIT);
+     * nothing fires if it rejects. Use {@link KyselyTransactionContext.transaction}
+     * for delivery strictly after COMMIT.
      *
      * Generic so callers can pass `Transaction<MyDb & WorkflowDatabase>`
      * (Kysely is invariant in DB, so a non-generic signature would reject
@@ -24,7 +68,28 @@ export const KyselyTransactionContext = {
      * workflow tables.
      */
     run(owner, trx, callback) {
-        return storageFor(owner).run(trx, callback);
+        return kyselyTransactionScopes.runSeeded(owner, trx, callback);
+    },
+    /**
+     * Runs `callback` in a new transaction on `db` (`db.transaction().execute`),
+     * with that transaction active for workflow calls. Observers of workflow
+     * calls made inside fire after the transaction commits, and never if it
+     * rolls back.
+     *
+     * Called while a transaction for `db` is already active (an outer
+     * `transaction()`, a workflow call, or a seeded `run()`), it joins that
+     * transaction instead: `callback` receives the existing transaction and runs
+     * in a savepoint, which is released on success (its observers then wait for
+     * the enclosing transaction) and rolled back on failure (its observers are
+     * dropped).
+     */
+    transaction(db, callback) {
+        const owner = db;
+        const scope = kyselyTransactionScopes.current(owner);
+        if (scope) {
+            return runInKyselySavepoint(owner, scope, () => callback(scope.connection));
+        }
+        return runOwnedKyselyTransaction(owner, async () => { }, (trx) => callback(trx));
     },
 };
 //# sourceMappingURL=kysely-transaction-context.js.map

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

@@ -1,5 +1,5 @@
 import type { Kysely } from "kysely";
-import type { WorkflowTransactionRunner } from "@duraflows/core";
+import type { AfterCommitCallback, WorkflowTransactionRunner } from "@duraflows/core";
 import type { WorkflowDatabase } from "./kysely-database.js";
 /**
  * Transaction-scoped PostgreSQL timeouts.
@@ -31,6 +31,7 @@ export declare class KyselyTransactionRunner implements WorkflowTransactionRunne
     private readonly timeoutSettings;
     constructor(db: Kysely<WorkflowDatabase>, options?: KyselyTransactionRunnerOptions);
     runInTransaction<T>(callback: () => Promise<T>): Promise<T>;
+    afterCommit(callback: AfterCommitCallback): void;
     /**
      * 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

package/dist/kysely-transaction-runner.js

@@ -1,5 +1,5 @@
 import { WorkflowError } from "@duraflows/core";
-import { KyselyTransactionContext } from "./kysely-transaction-context.js";
+import { kyselyTransactionScopes, runInKyselySavepoint, runOwnedKyselyTransaction, } 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.
@@ -33,14 +33,16 @@ export class KyselyTransactionRunner {
         this.timeoutSettings = buildTimeoutSettings(options);
     }
     async runInTransaction(callback) {
-        const existing = KyselyTransactionContext.getTransaction(this.db);
-        if (existing) {
-            return callback();
+        const scope = kyselyTransactionScopes.current(this.db);
+        if (scope) {
+            // Nested: a savepoint on the outer transaction, so a failure rolls back
+            // only this call. The outer transaction's timeouts stay in force.
+            return runInKyselySavepoint(this.db, scope, callback);
         }
-        return this.db.transaction().execute(async (trx) => {
-            await this.applyTimeouts(trx);
-            return KyselyTransactionContext.run(this.db, trx, callback);
-        });
+        return runOwnedKyselyTransaction(this.db, (trx) => this.applyTimeouts(trx), () => callback());
+    }
+    afterCommit(callback) {
+        kyselyTransactionScopes.afterCommit(this.db, callback);
     }
     /**
      * Applies the configured timeouts to `trx` as transaction-local settings, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duraflows/kysely",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "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": "^5.1.0",
-    "kysely": "^0.29.5"
+    "@duraflows/core": "^5.2.1",
+    "kysely": "^0.29.6"
   },
   "devDependencies": {
-    "@types/pg": "^8.21.0",
-    "kysely": "^0.29.5",
+    "@types/pg": "^8.23.1",
+    "kysely": "^0.29.6",
     "pg": "^8.23.0",
-    "@duraflows/core": "5.1.0",
-    "@duraflows/pg": "5.1.0"
+    "@duraflows/core": "5.2.1",
+    "@duraflows/pg": "5.2.1"
   },
   "scripts": {
     "build": "tsc --build"