feat(database): add closure transaction helper

Add ConnectionInterface::transaction() and implement it on
BaseConnection as a small wrapper around the existing transaction API.

- commit successful callback results and return callback values
- roll back and rethrow callback exceptions
- preserve existing false-return behavior for begin/status failures
- support nested transaction state and transaction callbacks
- document callback exception precedence and interface BC impact
- add focused live and base connection coverage

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

system/Database/BaseConnection.php

@@ -1066,6 +1066,44 @@ public function afterRollback(callable $callback): static
         return $this;
     }
 
+    /**
+     * Run the callback inside a transaction.
+     *
+     * @param callable(self): mixed $callback
+     */
+    public function transaction(callable $callback): mixed
+    {
+        if (! $this->transEnabled) {
+            return $callback($this);
+        }
+
+        if (! $this->transBegin()) {
+            return false;
+        }
+
+        try {
+            $result = $callback($this);
+        } catch (Throwable $e) {
+            try {
+                $this->transRollback();
+            } finally {
+                if ($this->transDepth > 0) {
+                    $this->transStatus = false;
+                } elseif ($this->transStrict === false) {
+                    $this->transStatus = true;
+                }
+            }
+
+            throw $e;
+        }
+
+        if (! $this->transComplete()) {
+            return false;
+        }
+
+        return $result;
+    }
+
     /**
      * Begin Transaction
      */

system/Database/ConnectionInterface.php

@@ -133,6 +133,13 @@ public function afterCommit(callable $callback): static;
      */
     public function afterRollback(callable $callback): static;
 
+    /**
+     * Run the callback inside a transaction.
+     *
+     * @param callable(self): mixed $callback
+     */
+    public function transaction(callable $callback): mixed;
+
     /**
      * Returns an instance of the query builder for this connection.
      *

tests/system/Database/BaseConnectionTest.php

@@ -624,6 +624,40 @@ protected function _transRollback(): bool
         $this->assertSame(['rolled back'], $callbacks);
     }
 
+    public function testTransactionReturnsFalseWhenTransactionCannotBegin(): void
+    {
+        $callbackRan = false;
+
+        $db = new class ($this->options) extends MockConnection {
+            protected function _transBegin(): bool
+            {
+                return false;
+            }
+        };
+
+        $result = $db->transaction(static function () use (&$callbackRan): void {
+            $callbackRan = true;
+        });
+
+        $this->assertFalse($result);
+        $this->assertFalse($callbackRan);
+    }
+
+    public function testTransactionRunsCallbackWhenTransactionsAreDisabled(): void
+    {
+        $db = new MockConnection($this->options);
+        $db->transOff();
+
+        $result = $db->transaction(static function (BaseConnection $connection): string {
+            $connection->afterCommit(static function (): void {});
+
+            return 'not wrapped';
+        });
+
+        $this->assertSame('not wrapped', $result);
+        $this->assertSame(0, $db->transDepth);
+    }
+
     public function testCallFunctionDoesNotDoublePrefixAlreadyPrefixedName(): void
     {
         $db = new class ($this->options) extends MockConnection {