fix: reject sync inside transactions

Author: cardmagic

CHANGELOG.md

@@ -54,6 +54,8 @@
   PostgreSQL, and MySQL; distinguish an uncommitted enqueue timeout from a
   recoverable durable wait timeout; and report structured database, activation,
   and mailbox blockers.
+- Reject committed calls and message waits inside an ambient Solid Objects
+  database transaction before they can self-deadlock.
 
 ## 0.1.0 - 2026-08-13
 

README.md

@@ -252,6 +252,13 @@ await counter
 Invocation options stay separate from actor arguments, so an actor may safely
 use argument names such as `timeoutMilliseconds` or `authorizationContext`.
 
+Do not make a committed actor call or wait on a message from inside
+`database.transaction(...)` on the Solid Objects database. The runtime raises
+`SyncInsideTransaction` before enqueue or waiting, avoiding a self-deadlock on
+the transaction's checked-out connection. Send background work outside the
+transaction, or let the actor coordinate same-database changes through a commit
+action.
+
 ## Send background work without a queue service
 
 Use the typed `send` dispatcher when the caller should not wait for execution:

docs/architecture.md

@@ -47,6 +47,11 @@ Already-running JavaScript actor code is cooperative rather than forcefully
 preempted; leases and fenced commits remain authoritative if it outlives the
 caller's wait.
 
+Each database adapter also tracks its active transaction through Node's async
+context. A committed call or message wait fails before enqueue or polling when
+the same logical call stack already owns a Solid Objects transaction, rather
+than waiting for a connection or serialized SQLite slot it cannot release.
+
 PostgreSQL notifications are an opt-in latency layer. One event-driven client
 per runtime listens on role-specific channels before the worker checks durable
 state, which closes the listener-startup race without Ruby's connection per

docs/operations.md

@@ -61,6 +61,12 @@ forcefully terminated. An actor operation that has started may therefore
 finish after the caller's timeout; durable leases and fenced commits remain the
 correctness boundary.
 
+Committed calls and `message.wait()` fail with `SyncInsideTransaction` when
+invoked inside `database.transaction(...)` on the configured Solid Objects
+adapter. The check happens before enqueue for direct calls. This prevents the
+caller from waiting on a pool connection or SQLite access slot that its own
+ambient transaction still holds.
+
 Authorized operators can inspect terminal actor failures with
 `runtime.deadLetters.all()` and retry one with `runtime.deadLetters.retry()`.
 Retry is idempotent per dead letter: the record retains the replacement message

docs/parity.md

@@ -31,6 +31,7 @@ Reference: Ruby `solid_objects` 0.12.0 at commit `a01b6f5`.
 | Actor-to-actor delivery                                                                                       | Native  | `sendTo(reference).operation()` stages delivery in the source actor commit.                                                                                                                                  |
 | One-shot and recurring reminders                                                                              | Native  | Scheduling, replacement events, catch-up policy, stale-claim recovery, pausing, authorized inspection, and idempotent resume are implemented.                                                                |
 | Same-database commit actions                                                                                  | Native  | Registered actions receive the fenced transaction connection.                                                                                                                                                |
+| Ambient transaction rejection                                                                                 | Native  | Committed calls and message waits fail before blocking when the current async context already owns a transaction on the Solid Objects adapter.                                                               |
 | Direct application-write isolation during actor code                                                          | Partial | `guardApplicationDatabase()` fails closed for operations, projections, and migrations, while registered commit actions remain writable. Unwrapped ORM pools and third-party clients cannot be intercepted.   |
 | Committed snapshots                                                                                           | Native  | `snapshot()` returns authorized committed state; realtime replay reads the explicit observable projection with instance ID and revision without creating mailbox history.                                    |
 | Actor destruction and incarnation fencing                                                                     | Native  | Authorized cascading deletion creates a fresh instance ID on recreation.                                                                                                                                     |

src/application-database.ts

@@ -15,6 +15,10 @@ class GuardedApplicationDatabase implements Database {
     this.schemaIdentity = database.schemaIdentity
   }
 
+  transactionActive(): boolean {
+    return this.database.transactionActive?.() ?? false
+  }
+
   connection<Result>(
     callback: (connection: DatabaseConnection) => Promise<Result>,
   ): Promise<Result> {

src/database/mysql.ts

@@ -13,6 +13,7 @@ import {
   requireDatabaseDeadlineRemaining,
 } from "./deadline.js"
 import { DatabaseDeadlineExceeded } from "../errors.js"
+import { databaseTransactionActive, withDatabaseTransaction } from "./transaction-context.js"
 
 export interface MySQLDatabaseOptions {
   connectionString: string
@@ -151,42 +152,48 @@ export class MySQLDatabase implements Database {
   async transaction<Result>(
     callback: (connection: DatabaseConnection) => Promise<Result>,
   ): Promise<Result> {
-    const deadlineActive = databaseDeadlineRemainingMilliseconds() !== undefined
-    const connection = await acquireBeforeDatabaseDeadline(
-      this.pool.getConnection(),
-      (lateConnection) => lateConnection.release(),
-    )
-    try {
-      await connection.beginTransaction()
-      const remaining = requireDatabaseDeadlineRemaining()
-      if (remaining !== undefined) {
-        await connection.query("SET SESSION innodb_lock_wait_timeout = ?", [
-          Math.max(Math.ceil(remaining / 1_000), 1),
-        ])
-        await connection.query("SET SESSION max_execution_time = ?", [Math.max(remaining, 1)])
+    return withDatabaseTransaction(this, async () => {
+      const deadlineActive = databaseDeadlineRemainingMilliseconds() !== undefined
+      const connection = await acquireBeforeDatabaseDeadline(
+        this.pool.getConnection(),
+        (lateConnection) => lateConnection.release(),
+      )
+      try {
+        await connection.beginTransaction()
+        const remaining = requireDatabaseDeadlineRemaining()
+        if (remaining !== undefined) {
+          await connection.query("SET SESSION innodb_lock_wait_timeout = ?", [
+            Math.max(Math.ceil(remaining / 1_000), 1),
+          ])
+          await connection.query("SET SESSION max_execution_time = ?", [Math.max(remaining, 1)])
+        }
+        const result = await callback(new MySQLConnection(connection))
+        requireDatabaseDeadlineRemaining()
+        await connection.commit()
+        return result
+      } catch (error) {
+        await connection.rollback().catch(() => undefined)
+        if (
+          error instanceof DatabaseDeadlineExceeded ||
+          (deadlineActive && mysqlDeadlineError(error))
+        ) {
+          throw databaseDeadlineError(error)
+        }
+        throw error
+      } finally {
+        if (deadlineActive) {
+          await connection
+            .query("SET SESSION innodb_lock_wait_timeout = DEFAULT")
+            .catch(() => undefined)
+          await connection.query("SET SESSION max_execution_time = DEFAULT").catch(() => undefined)
+        }
+        connection.release()
       }
-      const result = await callback(new MySQLConnection(connection))
-      requireDatabaseDeadlineRemaining()
-      await connection.commit()
-      return result
-    } catch (error) {
-      await connection.rollback().catch(() => undefined)
-      if (
-        error instanceof DatabaseDeadlineExceeded ||
-        (deadlineActive && mysqlDeadlineError(error))
-      ) {
-        throw databaseDeadlineError(error)
-      }
-      throw error
-    } finally {
-      if (deadlineActive) {
-        await connection
-          .query("SET SESSION innodb_lock_wait_timeout = DEFAULT")
-          .catch(() => undefined)
-        await connection.query("SET SESSION max_execution_time = DEFAULT").catch(() => undefined)
-      }
-      connection.release()
-    }
+    })
+  }
+
+  transactionActive(): boolean {
+    return databaseTransactionActive(this)
   }
 
   async close(): Promise<void> {

src/database/postgresql.ts

@@ -9,6 +9,7 @@ import {
   requireDatabaseDeadlineRemaining,
 } from "./deadline.js"
 import { DatabaseDeadlineExceeded } from "../errors.js"
+import { databaseTransactionActive, withDatabaseTransaction } from "./transaction-context.js"
 
 export {
   PostgreSQLWakeUpAdapter,
@@ -152,32 +153,38 @@ export class PostgreSQLDatabase implements Database {
   async transaction<Result>(
     callback: (connection: DatabaseConnection) => Promise<Result>,
   ): Promise<Result> {
-    const deadlineActive = databaseDeadlineRemainingMilliseconds() !== undefined
-    const client = await acquireBeforeDatabaseDeadline(this.pool.connect(), (lateClient) =>
-      lateClient.release(),
-    )
-    try {
-      await client.query("BEGIN")
-      const remaining = requireDatabaseDeadlineRemaining()
-      if (remaining !== undefined) {
-        await applyPostgreSQLDeadline({ client, milliseconds: remaining, scope: "transaction" })
+    return withDatabaseTransaction(this, async () => {
+      const deadlineActive = databaseDeadlineRemainingMilliseconds() !== undefined
+      const client = await acquireBeforeDatabaseDeadline(this.pool.connect(), (lateClient) =>
+        lateClient.release(),
+      )
+      try {
+        await client.query("BEGIN")
+        const remaining = requireDatabaseDeadlineRemaining()
+        if (remaining !== undefined) {
+          await applyPostgreSQLDeadline({ client, milliseconds: remaining, scope: "transaction" })
+        }
+        const result = await callback(new PostgreSQLConnection(client))
+        requireDatabaseDeadlineRemaining()
+        await client.query("COMMIT")
+        return result
+      } catch (error) {
+        await client.query("ROLLBACK").catch(() => undefined)
+        if (
+          error instanceof DatabaseDeadlineExceeded ||
+          (deadlineActive && postgresqlDeadlineError(error))
+        ) {
+          throw databaseDeadlineError(error)
+        }
+        throw error
+      } finally {
+        client.release()
       }
-      const result = await callback(new PostgreSQLConnection(client))
-      requireDatabaseDeadlineRemaining()
-      await client.query("COMMIT")
-      return result
-    } catch (error) {
-      await client.query("ROLLBACK").catch(() => undefined)
-      if (
-        error instanceof DatabaseDeadlineExceeded ||
-        (deadlineActive && postgresqlDeadlineError(error))
-      ) {
-        throw databaseDeadlineError(error)
-      }
-      throw error
-    } finally {
-      client.release()
-    }
+    })
+  }
+
+  transactionActive(): boolean {
+    return databaseTransactionActive(this)
   }
 
   async close(): Promise<void> {

src/database/sqlite.ts

@@ -2,6 +2,7 @@ import { DatabaseSync } from "node:sqlite"
 import type { Database, DatabaseConnection, RunResult } from "./types.js"
 import { databaseDeadlineError, requireDatabaseDeadlineRemaining } from "./deadline.js"
 import { DatabaseDeadlineExceeded } from "../errors.js"
+import { databaseTransactionActive, withDatabaseTransaction } from "./transaction-context.js"
 
 export interface SQLiteDatabaseOptions {
   path: string
@@ -69,17 +70,23 @@ export class SQLiteDatabase implements Database {
   async transaction<Result>(
     callback: (connection: DatabaseConnection) => Promise<Result>,
   ): Promise<Result> {
-    return this.withAccess(async () => {
-      this.database.exec("BEGIN IMMEDIATE")
-      try {
-        const result = await callback(this.databaseConnection)
-        this.database.exec("COMMIT")
-        return result
-      } catch (error) {
-        this.database.exec("ROLLBACK")
-        throw error
-      }
-    })
+    return withDatabaseTransaction(this, () =>
+      this.withAccess(async () => {
+        this.database.exec("BEGIN IMMEDIATE")
+        try {
+          const result = await callback(this.databaseConnection)
+          this.database.exec("COMMIT")
+          return result
+        } catch (error) {
+          this.database.exec("ROLLBACK")
+          throw error
+        }
+      }),
+    )
+  }
+
+  transactionActive(): boolean {
+    return databaseTransactionActive(this)
   }
 
   async close(): Promise<void> {

src/database/transaction-context.ts

@@ -0,0 +1,30 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+
+interface TransactionScope {
+  database: object
+  active: boolean
+}
+
+const transactionScopes = new AsyncLocalStorage<readonly TransactionScope[]>()
+
+export function withDatabaseTransaction<Result>(
+  database: object,
+  operation: () => Promise<Result>,
+): Promise<Result> {
+  const scope: TransactionScope = { database, active: true }
+  const scopes = [...(transactionScopes.getStore() ?? []), scope]
+  return transactionScopes.run(scopes, async () => {
+    try {
+      return await operation()
+    } finally {
+      scope.active = false
+    }
+  })
+}
+
+export function databaseTransactionActive(database: object): boolean {
+  return (
+    transactionScopes.getStore()?.some((scope) => scope.database === database && scope.active) ??
+    false
+  )
+}