velocity-python 0.1.53__tar.gz → 0.1.55__tar.gz

{velocity_python-0.1.53 → velocity_python-0.1.55}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.53
+Version: 0.1.55
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -46,6 +46,7 @@ Requires-Dist: psycopg[binary]>=3.2.0; extra == "postgres"
 Provides-Extra: payment
 Requires-Dist: stripe>=12.0.0; extra == "payment"
 Requires-Dist: braintree>=4.30.0; extra == "payment"
+Requires-Dist: xmltodict>=0.13.0; extra == "payment"
 Provides-Extra: all
 Requires-Dist: velocity-python[aws,excel,http,payment,pdf,postgres,templates]; extra == "all"
 Provides-Extra: dev
@@ -61,6 +62,14 @@ Requires-Dist: pytest>=8.0.0; extra == "test"
 Requires-Dist: pytest-cov>=6.0.0; extra == "test"
 Requires-Dist: pytest-mock>=3.14.0; extra == "test"
 Requires-Dist: pytest-asyncio>=1.0.0; extra == "test"
+Requires-Dist: psycopg[binary]>=3.2.0; extra == "test"
+Requires-Dist: boto3>=1.35.0; extra == "test"
+Requires-Dist: requests>=2.32.0; extra == "test"
+Requires-Dist: stripe>=12.0.0; extra == "test"
+Requires-Dist: braintree>=4.30.0; extra == "test"
+Requires-Dist: xmltodict>=0.13.0; extra == "test"
+Requires-Dist: authorizenet>=1.1.3; extra == "test"
+Requires-Dist: openpyxl>=3.1.0; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx>=8.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "docs"

{velocity_python-0.1.53 → velocity_python-0.1.55}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.53"
+version = "0.1.55"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -72,6 +72,7 @@ postgres = [
 payment = [
   "stripe>=12.0.0",
   "braintree>=4.30.0",
+  "xmltodict>=0.13.0",
 ]
 all = [
   "velocity-python[postgres,aws,excel,templates,http,payment,pdf]",
@@ -90,6 +91,17 @@ test = [
   "pytest-cov>=6.0.0",
   "pytest-mock>=3.14.0",
   "pytest-asyncio>=1.0.0",
+  # Drivers/SDKs the test suite imports directly. Without these the suite
+  # silently degrades to collection errors (see R29). Keep in sync with the
+  # production layer (psycopg v3 is the sole Postgres driver).
+  "psycopg[binary]>=3.2.0",
+  "boto3>=1.35.0",
+  "requests>=2.32.0",
+  "stripe>=12.0.0",
+  "braintree>=4.30.0",
+  "xmltodict>=0.13.0",
+  "authorizenet>=1.1.3",
+  "openpyxl>=3.1.0",
 ]
 docs = [
   "sphinx>=8.0.0",

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.53"
+__version__ = version = "0.1.55"
 
 import importlib as _importlib
 

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/aws/handlers/context.py

@@ -422,6 +422,12 @@ class Context:
                         "job_id": id,
                         "status": "Initialized",
                         "message": "Job Initialized",
+                        # Carry a caller-supplied human-readable description onto
+                        # the job activity row (None when omitted) so scheduled /
+                        # program-object jobs are identifiable in the activity log.
+                        "description": item.get("description")
+                        if isinstance(item, dict)
+                        else None,
                     }
                 )
                 messages.append({"Id": id, "MessageBody": to_json(message)})

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/aws/handlers/lambda_handler.py

@@ -41,8 +41,11 @@ class LambdaHandler(BaseHandler):
         )
 
     def beforeAction(self, tx, context):
-        # Enhanced activity tracking
-        self._enhanced_before_action(tx, context)
+        # Enhanced activity tracking is supplied by the WebHandler mixin; a bare
+        # LambdaHandler (no WebHandler) simply skips it rather than crashing.
+        enhanced = getattr(self, "_enhanced_before_action", None)
+        if callable(enhanced):
+            enhanced(tx, context)
         logger.debug("starting LamdaHandler.beforeAction")
 
         self.current_user = {}

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/aws/handlers/response.py

@@ -1,3 +1,4 @@
+import os
 import sys
 import time
 import traceback
@@ -5,6 +6,11 @@ from typing import Any, Dict, List, Optional
 from velocity.misc.format import to_json
 
 
+# When DEBUG is off, exception responses omit the traceback so server-side
+# stack traces are not leaked to API clients. Enable with VELOCITY_DEBUG=true.
+DEBUG = os.environ.get("VELOCITY_DEBUG", "").lower() in ("true", "1", "yes")
+
+
 class Response:
     """Class to manage and structure HTTP responses with various actions and custom headers."""
 
@@ -207,8 +213,10 @@ class Response:
                 "python_exception": {
                     "type": str(exc_type),
                     "value": str(exc_value),
-                    "traceback": traceback.format_exc(),
-                    "tb": traceback.format_tb(tb) if tb else [],
+                    # Only expose the traceback when DEBUG is enabled; otherwise
+                    # we would leak server internals to the API client.
+                    "traceback": traceback.format_exc() if DEBUG else None,
+                    "tb": traceback.format_tb(tb) if (DEBUG and tb) else [],
                 }
             }
         )

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/aws/ssm_config.py

@@ -80,12 +80,17 @@ def _is_lambda_runtime() -> bool:
     return _lambda_function_name() is not None or os.environ.get('AWS_EXECUTION_ENV', '').startswith('AWS_Lambda_')
 
 
+# Stage identity: AppStage is canonical; ENV / USER_BRANCH / AWS_BRANCH are
+# retired compatibility aliases (AppStage wins when more than one is set).
+_STAGE_ENV_KEYS = ('AppStage', 'AWS_BRANCH', 'ENV', 'USER_BRANCH')
+
+
 def _infer_project_name_from_lambda_name() -> str | None:
     function_name = _lambda_function_name()
     if function_name is None:
         return None
 
-    stage = _first_nonempty_env('AppStage', 'AWS_BRANCH')
+    stage = _first_nonempty_env(*_STAGE_ENV_KEYS)
     base_name = function_name
     if stage:
         suffix = f'-{stage}'
@@ -106,7 +111,7 @@ def get_project_name(default: Optional[str] = None) -> Optional[str]:
 
 
 def get_stage(default: Optional[str] = None) -> Optional[str]:
-    return _first_nonempty_env('AppStage', 'AWS_BRANCH') or default
+    return _first_nonempty_env(*_STAGE_ENV_KEYS) or default
 
 
 def get_region(default: Optional[str] = 'us-east-1') -> Optional[str]:

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/aws/tests/test_lambda_handler_json_serialization.py

@@ -46,37 +46,26 @@ class TestLambdaHandlerJSONSerialization(unittest.TestCase):
         # Create handler
         handler = LambdaHandler(self.test_event, self.test_context)
 
-        # Mock the transaction decorator to pass through tx
-        with patch("velocity.aws.handlers.lambda_handler.engine") as mock_engine:
+        # serve() receives the transaction directly (the @engine.transaction
+        # decorator supplies it in production); a mock stands in here.
+        result = handler.serve(MagicMock())
 
-            def mock_transaction(func):
-                def wrapper(*args, **kwargs):
-                    mock_tx = MagicMock()
-                    return func(mock_tx, *args, **kwargs)
+        # Verify result is a dictionary (JSON-serializable)
+        self.assertIsInstance(result, dict)
 
-                return wrapper
+        # Verify it has the expected Lambda response structure
+        self.assertIn("statusCode", result)
+        self.assertIn("headers", result)
+        self.assertIn("body", result)
 
-            mock_engine.transaction = mock_transaction
+        # Verify the body is a JSON string
+        self.assertIsInstance(result["body"], str)
 
-            # Call serve method
-            result = handler.serve(MagicMock())
-
-            # Verify result is a dictionary (JSON-serializable)
-            self.assertIsInstance(result, dict)
-
-            # Verify it has the expected Lambda response structure
-            self.assertIn("statusCode", result)
-            self.assertIn("headers", result)
-            self.assertIn("body", result)
-
-            # Verify the body is a JSON string
-            self.assertIsInstance(result["body"], str)
-
-            # Verify the entire result can be JSON serialized
-            try:
-                json.dumps(result)
-            except (TypeError, ValueError) as e:
-                self.fail(f"Result is not JSON serializable: {e}")
+        # Verify the entire result can be JSON serialized
+        try:
+            json.dumps(result)
+        except (TypeError, ValueError) as e:
+            self.fail(f"Result is not JSON serializable: {e}")
 
     def test_response_object_has_render_method(self):
         """Test that Response object has a proper render method."""

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/aws/tests/test_response.py

@@ -105,7 +105,7 @@ class TestResponse(unittest.TestCase):
         self.assertEqual(self.response.actions[0]["payload"], payload)
 
     def test_exception_handling_debug_on(self):
-        with patch("your_module.DEBUG", True), patch(
+        with patch("velocity.aws.handlers.response.DEBUG", True), patch(
             "traceback.format_exc", return_value="formatted traceback"
         ):
             try:
@@ -119,7 +119,7 @@ class TestResponse(unittest.TestCase):
         self.assertEqual(exception_info["traceback"], "formatted traceback")
 
     def test_exception_handling_debug_off(self):
-        with patch("your_module.DEBUG", False), patch(
+        with patch("velocity.aws.handlers.response.DEBUG", False), patch(
             "traceback.format_exc", return_value="formatted traceback"
         ):
             try:

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/db/core/decorators.py

@@ -1,4 +1,5 @@
 import logging
+import os
 import time
 import random
 from collections.abc import Mapping, Sequence
@@ -8,6 +9,19 @@ from velocity.db import exceptions
 logger = logging.getLogger("velocity.db")
 
 
+def _raise_on_db_error():
+    """R22 — opt-in strict mode.
+
+    When ``VELOCITY_RAISE_ON_DB_ERROR`` is truthy, ``@return_default`` re-raises
+    the underlying DB exception instead of silently swallowing it and returning a
+    default. Off by default to preserve historical behaviour; turn it on in an
+    environment that would rather see DB errors than empty/zero results.
+    """
+    return os.environ.get("VELOCITY_RAISE_ON_DB_ERROR", "").lower() in (
+        "true", "1", "yes",
+    )
+
+
 _PRIMARY_KEY_PATTERNS = (
     "primary key",
     "key 'primary'",
@@ -76,7 +90,15 @@ def reset_id_on_dup_key(func):
             if retries < max_retries:
                 backoff_time = (2**retries) * 0.01 + random.uniform(0, 0.02)
                 time.sleep(backoff_time)
-                self.set_sequence(self.max("sys_id") + 1)
+                # R23 — Resolve the true MAX(sys_id) WITHOUT going through the
+                # @return_default(0) wrapper on Table.max(). If max() silently
+                # swallowed an error and returned 0, set_sequence(1) would reset
+                # a populated table's sequence and guarantee future PK
+                # collisions. Run the aggregate directly so any error surfaces
+                # instead of corrupting the sequence.
+                sql, vals = self.max("sys_id", sql_only=True)
+                current_max = self.tx.execute(sql, vals, cursor=self.cursor()).scalar()
+                self.set_sequence((current_max or 0) + 1)
                 return reset_decorator(self, *args, retries=retries + 1, **kwds)
         raise exceptions.DbDuplicateKeyError("Max retries reached.")
 
@@ -93,15 +115,29 @@ def return_default(
         exceptions.DbTruncationError,
         exceptions.DbObjectExistsError,
     ),
+    default_factory=None,
 ):
     """
     If the wrapped function raises one of the specified exceptions, or returns None,
     this decorator returns the `default` value instead.
+
+    Use ``default_factory`` (a zero-arg callable) instead of ``default`` whenever
+    the default is **mutable** (e.g. ``Result()``). A bare ``default=Result()``
+    evaluates once at import and would be aliased across every swallowed call,
+    so one caller mutating/iterating it would corrupt the next caller's result
+    (R22). ``default_factory`` produces a fresh value per call.
+
+    When ``VELOCITY_RAISE_ON_DB_ERROR`` is set, the swallow is bypassed and the
+    underlying exception propagates (see :func:`_raise_on_db_error`).
     """
 
+    def _make_default():
+        return default_factory() if default_factory is not None else default
+
     def decorator(func):
         func.default = default
         func.exceptions = exceptions
+        func.default_factory = default_factory
 
         @wraps(func)
         def wrapper(self, *args, **kwds):
@@ -109,10 +145,15 @@ def return_default(
             try:
                 result = func(self, *args, **kwds)
                 if result is None:
-                    result = default
+                    result = _make_default()
             except func.exceptions as e:
                 self.tx.rollback_savepoint(sp, cursor=self.cursor())
 
+                # R22 — opt-in strict mode: surface the DB error instead of
+                # silently degrading to a default value.
+                if _raise_on_db_error():
+                    raise
+
                 # Log the swallowed exception so silent failures are visible.
                 logger.warning(
                     "@return_default swallowed %s in %s.%s: %s",
@@ -140,7 +181,7 @@ def return_default(
                     }
                 except Exception:
                     pass
-                return default
+                return _make_default()
             self.tx.release_savepoint(sp, cursor=self.cursor())
             return result
 

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/db/core/engine.py

@@ -61,6 +61,20 @@ def _build_error_code_map(sql_dialect) -> dict:
 _ENGINE_FILE = os.path.normpath(__file__)
 
 
+def _retry_blocked_by_side_effect(tx):
+    """R21 — return True (and log) when *tx* has performed an irreversible
+    external side effect, so the auto-retry envelope must re-raise instead of
+    re-running the function (which would repeat the side effect)."""
+    if getattr(tx, "_external_side_effect", False):
+        logger.error(
+            "Refusing to auto-retry a transaction that already performed an "
+            "external side effect (e.g. a payment charge); re-raising to avoid "
+            "a duplicate side effect (R21)."
+        )
+        return True
+    return False
+
+
 class ConnectionPool:
     """
     A simple thread-safe connection pool for database connections.
@@ -75,7 +89,8 @@ class ConnectionPool:
     transparently.
     """
 
-    def __init__(self, connect_fn, minconn=1, maxconn=5, *, validate=True):
+    def __init__(self, connect_fn, minconn=1, maxconn=5, *, validate=True,
+                 acquire_timeout=None):
         """
         Args:
             connect_fn: Zero-argument callable that returns a new DB-API connection.
@@ -84,6 +99,11 @@ class ConnectionPool:
             validate:   When True, run a lightweight check before handing out a
                         connection.  Disable when behind pgbouncer in transaction
                         mode to avoid an extra round-trip.
+            acquire_timeout: Max seconds to wait for a free slot when the pool is
+                        exhausted before raising ``DbConnectionError``.  ``None``
+                        or <= 0 blocks indefinitely (legacy behaviour).  A bounded
+                        default lets callers fail fast instead of hanging until the
+                        surrounding Lambda/request times out (R24).
         """
         if maxconn < 1:
             raise ValueError("maxconn must be >= 1")
@@ -96,6 +116,7 @@ class ConnectionPool:
         self._minconn = minconn
         self._maxconn = maxconn
         self._validate = validate
+        self._acquire_timeout = acquire_timeout if (acquire_timeout and acquire_timeout > 0) else None
 
         self._lock = threading.Lock()
         self._available = threading.Semaphore(maxconn)
@@ -124,7 +145,16 @@ class ConnectionPool:
             raise exceptions.DbConnectionError("Connection pool is closed")
 
         t0 = time.perf_counter()
-        self._available.acquire()  # blocks when maxconn reached
+        # R24 — bounded wait for a free slot. Without a timeout an exhausted
+        # pool blocks until the surrounding Lambda/request itself times out,
+        # which masks the real problem and wastes the whole invocation window.
+        acquired = self._available.acquire(timeout=self._acquire_timeout)
+        if not acquired:
+            raise exceptions.DbConnectionError(
+                f"Connection pool exhausted: no connection available within "
+                f"{self._acquire_timeout}s (maxconn={self._maxconn}). "
+                f"A connection is likely held open across a slow external call."
+            )
 
         with self._lock:
             # Try to reuse an idle connection.
@@ -239,7 +269,7 @@ class Engine:
 
     def __init__(self, driver, config, sql, connect_timeout=None, schema_locked=False,
                  pool_min=None, pool_max=None, pool_enabled=None, pool_validate=True,
-                 prepare_enabled=None):
+                 prepare_enabled=None, pool_acquire_timeout=None):
         self.__config = config
         self.__sql = sql
         self.__driver = driver
@@ -270,6 +300,12 @@ class Engine:
             pool_min = int(os.environ.get("VELOCITY_POOL_MIN", "1"))
         if pool_max is None:
             pool_max = int(os.environ.get("VELOCITY_POOL_MAX", "5"))
+        # R24 — bounded wait for a pooled connection. Default 30s; set to 0 to
+        # restore the legacy block-forever behaviour.
+        if pool_acquire_timeout is None:
+            pool_acquire_timeout = float(
+                os.environ.get("VELOCITY_POOL_ACQUIRE_TIMEOUT", "30")
+            )
 
         self.__pool_enabled = pool_enabled
         self.__pool: ConnectionPool | None = None
@@ -281,6 +317,7 @@ class Engine:
                     minconn=pool_min,
                     maxconn=pool_max,
                     validate=pool_validate,
+                    acquire_timeout=pool_acquire_timeout,
                 )
                 logger.info("Connection pool created (min=%d, max=%d)", pool_min, pool_max)
             except Exception as exc:
@@ -506,6 +543,8 @@ class Engine:
                     try:
                         return function(*args, **kwds)
                     except exceptions.DbRetryTransaction:
+                        if _retry_blocked_by_side_effect(_tx):
+                            raise
                         retry_count += 1
                         if retry_count > self.MAX_RETRIES:
                             raise
@@ -513,6 +552,8 @@ class Engine:
                         time.sleep(min(2.0, 0.05 * (2**min(retry_count, 6))))
                         _tx.rollback()
                     except exceptions.DbLockTimeoutError:
+                        if _retry_blocked_by_side_effect(_tx):
+                            raise
                         lock_timeout_count += 1
                         if lock_timeout_count > self.MAX_RETRIES:
                             raise
@@ -521,7 +562,12 @@ class Engine:
                         continue
                     except exceptions.DbConnectionError as e:
                         # Transient disconnects can happen during maintenance / restarts.
-                        # Retrying the entire top-level function is the safest option.
+                        # Retrying the entire top-level function is the safest option —
+                        # UNLESS the function already performed an irreversible external
+                        # side effect (R21), in which case re-running it could e.g.
+                        # double-charge a customer.
+                        if _retry_blocked_by_side_effect(_tx):
+                            raise
                         msg = str(e).strip().lower()
                         if not getattr(
                             self.sql, "is_transient_connection_error_message", lambda _m: False

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/db/core/table.py

@@ -2262,7 +2262,7 @@ class Table:
         sql, vals = self.sql.select(self.tx, columns="count(*)", table=self.name)
         return self.tx.execute(sql, vals, cursor=self.cursor()).scalar()
 
-    @return_default(Result())
+    @return_default(default_factory=Result)
     def select(
         self,
         columns=None,
@@ -2400,7 +2400,7 @@ class Table:
             raise Exception("A query generator does not support dictionary-type WHERE.")
         return Query(sql)
 
-    @return_default(Result())
+    @return_default(default_factory=Result)
     def server_select(
         self,
         columns=None,
@@ -2434,7 +2434,7 @@ class Table:
             return sql, vals
         return self.tx.server_execute(sql, vals)
 
-    @return_default(Result())
+    @return_default(default_factory=Result)
     def batch(self, size=100, *args, **kwds):
         """
         Generator that yields batches of rows (lists) of size `size`.

{velocity_python-0.1.53 → velocity_python-0.1.55}/src/velocity/db/core/transaction.py

@@ -176,6 +176,11 @@ class Transaction:
         # R14 — N+1 detection: per-table SELECT counts.
         self._table_select_counts: dict[str, int] = {}
         self._n1_warned: set[str] = set()
+        # R21 — set once an irreversible external side effect (e.g. a payment
+        # charge/capture) has happened in this transaction. The engine's
+        # auto-retry envelope must NOT re-run a function after this, or a
+        # transient DB error post-charge would charge the customer again.
+        self._external_side_effect = False
 
     def __str__(self):
         config = mask_config_for_display(self.engine.config)
@@ -265,64 +270,73 @@ class Transaction:
 
         t0 = _time.perf_counter()
         try:
-            if parms:
-                cursor.execute(sql, parms, prepare=prepare)
-            else:
-                cursor.execute(sql, prepare=prepare)
-        except TypeError:
-            # Driver doesn't support 'prepare' keyword (non-psycopg3).
             try:
                 if parms:
-                    cursor.execute(sql, parms)
+                    cursor.execute(sql, parms, prepare=prepare)
                 else:
-                    cursor.execute(sql)
+                    cursor.execute(sql, prepare=prepare)
+            except TypeError:
+                # Driver doesn't support 'prepare' keyword (non-psycopg3).
+                try:
+                    if parms:
+                        cursor.execute(sql, parms)
+                    else:
+                        cursor.execute(sql)
+                except Exception as e:
+                    raise self.engine.process_error(e, sql, parms)
             except Exception as e:
                 raise self.engine.process_error(e, sql, parms)
-        except Exception as e:
-            raise self.engine.process_error(e, sql, parms)
-
-        elapsed_ms = (_time.perf_counter() - t0) * 1000
-        self._query_count += 1
-        self._query_time_ms += elapsed_ms
-
-        # R12 — Slow query logging.
-        if _SLOW_QUERY_MS and elapsed_ms > _SLOW_QUERY_MS:
-            op = _classify_sql(sql)
-            tbl = _extract_table_name(sql)
-            sql_preview = _summarize_sql(sql)
-            _logger.warning(
-                "Slow query (%s): %.1f ms table=%s sql=%s",
-                op, elapsed_ms, tbl, sql_preview,
-                extra={
-                    "query_duration_ms": round(elapsed_ms, 1),
-                    "table_name": tbl,
-                    "operation": op,
-                    "sql_preview": sql_preview,
-                },
-                stack_info=True,
-            )
-
-        # R14 — N+1 detection (only when debug=True).
-        if debug and _N_PLUS_1_THRESHOLD:
-            op = _classify_sql(sql)
-            if op == "SELECT":
-                tbl = _extract_table_name(sql)
-                if tbl:
-                    self._table_select_counts[tbl] = self._table_select_counts.get(tbl, 0) + 1
-                    count = self._table_select_counts[tbl]
-                    if count > _N_PLUS_1_THRESHOLD and tbl not in self._n1_warned:
-                        self._n1_warned.add(tbl)
-                        _logger.warning(
-                            "Possible N+1: table %s queried %d times in this transaction "
-                            "(threshold=%d). Consider using prefetch=True or select_rows().",
-                            tbl, count, _N_PLUS_1_THRESHOLD,
-                            extra={"table_name": tbl, "select_count": count},
-                        )
 
-        if single:
-            self.connection.autocommit = False
+            elapsed_ms = (_time.perf_counter() - t0) * 1000
+            self._query_count += 1
+            self._query_time_ms += elapsed_ms
 
-        return Result(cursor, self, sql, parms)
+            # R12 — Slow query logging.
+            if _SLOW_QUERY_MS and elapsed_ms > _SLOW_QUERY_MS:
+                op = _classify_sql(sql)
+                tbl = _extract_table_name(sql)
+                sql_preview = _summarize_sql(sql)
+                _logger.warning(
+                    "Slow query (%s): %.1f ms table=%s sql=%s",
+                    op, elapsed_ms, tbl, sql_preview,
+                    extra={
+                        "query_duration_ms": round(elapsed_ms, 1),
+                        "table_name": tbl,
+                        "operation": op,
+                        "sql_preview": sql_preview,
+                    },
+                    stack_info=True,
+                )
+
+            # R14 — N+1 detection (only when debug=True).
+            if debug and _N_PLUS_1_THRESHOLD:
+                op = _classify_sql(sql)
+                if op == "SELECT":
+                    tbl = _extract_table_name(sql)
+                    if tbl:
+                        self._table_select_counts[tbl] = self._table_select_counts.get(tbl, 0) + 1
+                        count = self._table_select_counts[tbl]
+                        if count > _N_PLUS_1_THRESHOLD and tbl not in self._n1_warned:
+                            self._n1_warned.add(tbl)
+                            _logger.warning(
+                                "Possible N+1: table %s queried %d times in this transaction "
+                                "(threshold=%d). Consider using prefetch=True or select_rows().",
+                                tbl, count, _N_PLUS_1_THRESHOLD,
+                                extra={"table_name": tbl, "select_count": count},
+                            )
+
+            return Result(cursor, self, sql, parms)
+        finally:
+            # R20 — Always restore transactional mode for single-statement
+            # (autocommit) execution, even when execute() raised. Otherwise a
+            # connection can be returned to the pool stuck in autocommit mode,
+            # silently turning the next borrower's commit/rollback/savepoints
+            # into no-ops.
+            if single and self.connection is not None:
+                try:
+                    self.connection.autocommit = False
+                except Exception:
+                    pass
 
     def _execute_values(self, sql, args_list, template=None, page_size=1000):
         """
@@ -443,6 +457,23 @@ class Transaction:
         if sql:
             self._execute(sql, vals, cursor=cursor)
 
+    def mark_external_side_effect(self):
+        """Record that this transaction performed an irreversible external side
+        effect (a payment charge/capture, an email send, an external API write).
+
+        Once set, :meth:`Engine.exec_function` will refuse to auto-retry the
+        decorated function on transient DB errors and will re-raise instead — a
+        retry would re-run the side effect (e.g. double-charge a customer). Call
+        this immediately after the external call succeeds (R21).
+        """
+        self._external_side_effect = True
+        return self
+
+    @property
+    def has_external_side_effect(self):
+        """True if :meth:`mark_external_side_effect` was called on this txn."""
+        return self._external_side_effect
+
     def advisory_lock(self, key):
         """Acquire a transaction-scoped PostgreSQL advisory lock.