litedbmodel-runtime 2.2.2__tar.gz → 2.2.4__tar.gz

{litedbmodel_runtime-2.2.2 → litedbmodel_runtime-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: litedbmodel-runtime
-Version: 2.2.2
+Version: 2.2.4
 Summary: Thin multi-language runtime for litedbmodel v2 SCP makeSQL bundles (Python port). Executes the published static-makeSQL artifacts (a read ReadGraph = a bc surrogate ComponentGraphIR + per-node static statement templates, or a gate-first TransactionPlan) against a SQL driver — semantics-identical to the TS reference. Delegates the Expression-IR evaluation + map/Φ/wiring orchestration to behavior-contracts.
 Author: foo-ogawa
 License: MIT

{litedbmodel_runtime-2.2.2 → litedbmodel_runtime-2.2.4}/litedbmodel_runtime/__init__.py

@@ -102,29 +102,9 @@ from .connection_routing import (
     single_pool_pair,
     with_writer,
 )
-from .static_bundle import (
-    assemble_make_sql,
-    compose_make_sql,
-    execute_read_graph,
-    render_placeholders,
-    render_read_primary,
-    render_statements,
-)
-from .runtime import (
-    ENTITY_ROOT,
-    execute_bundle,
-    execute_transaction_bundle,
-    order_by_nulls,
-)
-from .relation import (
-    dedupe_keys,
-    distribute_to_parent,
-    read_bundle,
-    run_relation_op,
-)
-from .leaves import make_handlers
+from .leaves import make_handlers, render_placeholders
 
-__version__ = "2.2.2"
+__version__ = "2.2.4"
 
 __all__ = [
     "__version__",
@@ -231,23 +211,8 @@ __all__ = [
     "session_statements",
     "single_pool_pair",
     "with_writer",
-    # static makeSQL bundle runtime (the sole read/render path)
-    "assemble_make_sql",
-    "compose_make_sql",
-    "execute_read_graph",
-    "render_placeholders",
-    "render_read_primary",
-    "render_statements",
-    # runtime
-    "ENTITY_ROOT",
-    "execute_bundle",
-    "execute_transaction_bundle",
-    "order_by_nulls",
-    # read-relation batch execution + hydration (#43)
-    "dedupe_keys",
-    "distribute_to_parent",
-    "read_bundle",
-    "run_relation_op",
     # op-agnostic leaf transport for the bc-generated native (ir-exec) modules (#141 / epic #123)
+    # + the render-layer placeholder resolution (`?`→`$N`) the leaf transport applies
     "make_handlers",
+    "render_placeholders",
 ]

{litedbmodel_runtime-2.2.2 → litedbmodel_runtime-2.2.4}/litedbmodel_runtime/connection_routing.py

@@ -11,7 +11,8 @@ resolution (steps 2-4).
 
 A statement's connection is resolved in THIS priority (first match wins):
 
-  1. **active tx connection** — inside a transaction, always the tx-owned connection (Phase A;
+  1. **active tx connection** — inside a transaction, the tx-owned connection — a statement naming a
+     DIFFERENT database than the tx opened on is REJECTED there rather than routed (Phase A;
      resolved by :class:`ExecutionContext` BEFORE the routing steps, since only it holds the pin).
   2. **writer scope / writer-sticky** — inside :func:`with_writer`, or within ``writer_sticky_duration``
      after a transaction (read-your-writes), a READ goes to the WRITER pool (Phase C — here).
@@ -418,6 +419,57 @@ def reader_writer_pair(reader: ConnectionPool, writer: ConnectionPool) -> Reader
 DEFAULT_CONNECTION = "default"
 
 
+def assert_routable_named_db(db: Optional[str], context_description: str) -> None:
+    """Reject a statement that NAMES a database on a context that holds NO connection registry (the
+    single-driver :class:`~litedbmodel_runtime.exec_context.ExecutionContext`). The companion of
+    :meth:`ConnectionRegistry.pair_for`'s unknown-name failure, and for the same reason: an unresolvable
+    name must be LOUD, because the alternative is running the statement against whatever single driver
+    the context happens to hold — a DIFFERENT database than the statement's model declares (#217).
+    ``None`` (the default connection) is the single-driver case itself and passes. Mirrors the TS
+    ``assertRoutableNamedDb`` / go ``namedDBUnroutable`` / rust ``assert_routable_named_db``."""
+    if _effective_connection(db) == DEFAULT_CONNECTION:
+        return
+    raise ValueError(
+        "scp connection routing: a statement names connection '%s', but it is executing on %s — there "
+        "is no connection registry to resolve the name against. Build the context from a RoutingConfig "
+        "(set_config/ConnectionRegistry), or drop the connection tag on the model."
+        % (db, context_description)
+    )
+
+
+def _effective_connection(db: Optional[str]) -> str:
+    """A connection name reduced to its effective identity: unnamed ⇒ :data:`DEFAULT_CONNECTION`."""
+    return DEFAULT_CONNECTION if db is None else db
+
+
+def assert_tx_db_agrees(db: Optional[str], tx_db: Optional[str]) -> None:
+    """Reject a statement whose named database is NOT the one the active transaction opened on.
+
+    A transaction is ONE connection on ONE database: a statement that names a DIFFERENT database cannot be
+    executed atomically with it, by any amount of routing. So there are exactly two possible behaviors and
+    no third — run it on the transaction's database (silently the WRONG one) or refuse — and the first is
+    the silent default the tx pin used to produce: the pin is resolved BEFORE routing (it must be —
+    per-execution ownership depends on it), so ``intent.db`` was dropped unread and even an UNREGISTERED
+    name never surfaced (#217).
+
+    ``tx_db`` is the transaction's own connection name
+    (:meth:`~litedbmodel_runtime.exec_context.ExecutionContext.with_connection_name`, the same attribute
+    ``begin_tx`` reads). An UNNAMED statement agrees with any transaction — the ordinary in-body statement,
+    which every named-DB tx gate pins — and one naming the SAME database agrees too. Mirrors the TS
+    ``assertTxDbAgrees``."""
+    if db is None:
+        return
+    want, open_ = _effective_connection(db), _effective_connection(tx_db)
+    if want == open_:
+        return
+    raise ValueError(
+        "scp connection routing: a statement names connection '%s', but it is executing inside a "
+        "transaction opened on '%s' — a transaction is ONE connection on ONE database, so the two cannot "
+        "both be honored. Open the transaction on '%s', or issue the statement outside it."
+        % (want, open_, want)
+    )
+
+
 class ConnectionRegistry:
     """The multi-DB connection registry (C2): a map from a connection NAME → its
     :class:`ReaderWriterPools`. :func:`resolve_pool` selects the pair by ``intent.db`` (the connection
@@ -449,7 +501,7 @@ class ConnectionRegistry:
     def pair_for(self, name: Optional[str]) -> ReaderWriterPools:
         """The reader/writer pair for ``name`` (or :data:`DEFAULT_CONNECTION` when ``None``). LOUD on a
         missing name."""
-        key = name if name is not None else DEFAULT_CONNECTION
+        key = _effective_connection(name)
         pair = self._connections.get(key)
         if pair is None:
             known = ", ".join("'%s'" % k for k in self._connections.keys())
@@ -578,7 +630,11 @@ class WriterStickyClock:
         writer_sticky_duration: int = 5000,
         now: Optional[Callable[[], int]] = None,
     ) -> None:
-        self._last_write_at = 0
+        # ``None`` until the first ``mark()`` — absence, NOT a value sentinel. The injectable clock
+        # legitimately returns 0 (rust's SystemClock does right after process start), so encoding
+        # "never marked" as the value 0 would mis-classify a ``mark()`` at clock t=0 as unmarked and
+        # leak the read-your-writes read to the reader replica. Absence must be distinct from value 0.
+        self._last_write_at: Optional[int] = None
         self._enabled = use_writer_after_transaction
         self._sticky_duration_ms = writer_sticky_duration
         # Default clock: monotonic ms (Date.now analogue). An injectable clock makes expiry deterministic.
@@ -591,13 +647,13 @@ class WriterStickyClock:
 
     def is_sticky(self) -> bool:
         """Is a read currently sticky-to-writer (within ``writer_sticky_duration`` of the last write)?"""
-        if not self._enabled or self._last_write_at == 0:
+        if not self._enabled or self._last_write_at is None:
             return False
         return (self._now() - self._last_write_at) < self._sticky_duration_ms
 
     def reset(self) -> None:
         """Reset the clock (e.g. between tests / on :func:`close_all_pools`)."""
-        self._last_write_at = 0
+        self._last_write_at = None
 
 
 # ── The routing config a ctx carries (C1+C2+C3) ────────────────────────────────
@@ -961,8 +1017,9 @@ def routed_begin_tx(
 ) -> TxConnection:
     """Acquire + OWN one :class:`litedbmodel_runtime.driver._PooledTxConnection` for a transaction on the
     NAMED connection ``connection``'s WRITER pool (Phase C-2; ``None`` ⇒ the default connection). The
-    tx runs entirely on this ONE connection — the active-tx pin then wins over routing for every
-    statement in the body (Phase B unbroken). tx-control (the isolation SET / BEGIN / COMMIT / ROLLBACK)
+    tx runs entirely on this ONE connection: every UNNAMED in-body statement resolves the pin, one that
+    names THIS connection does too, and one naming a DIFFERENT database is rejected
+    (:func:`assert_tx_db_agrees`) — a transaction cannot span two databases. tx-control (the isolation SET / BEGIN / COMMIT / ROLLBACK)
     is issued THROUGH the seam on this pinned connection by the combinator (Phase D / #95,
     middleware-visible), NOT here. The writer pool's ``xform`` (``$N``/``?`` → ``%s``) +
     ``emulate_returning`` flag drive the tx statements byte-identically to the Phase A

{litedbmodel_runtime-2.2.2 → litedbmodel_runtime-2.2.4}/litedbmodel_runtime/driver.py

@@ -112,7 +112,7 @@ class Driver(Protocol):
 
     def begin_tx(self) -> TxConnection:
         """Acquire + OWN a :class:`TxConnection` for a transaction (per-execution connection ownership,
-        §3). The central seam's ``with_transaction`` pins the returned handle so every statement in the
+        §3). The central seam's ``with_transaction`` pins the returned handle so every statement of the tx's own database in the
         tx body runs on it, and issues the isolation SET + BEGIN/COMMIT/ROLLBACK THROUGH the seam on this
         connection (Phase D / #95, middleware-visible) — this method only acquires the owned connection.
         Empty prelude ⇒ a bare ``BEGIN`` (the Phase A behavior, byte-identical statements + connection)."""
@@ -248,6 +248,16 @@ class _SqliteTxConnection:
 # relations can each hold a live connection without starving.
 DEFAULT_POOL_SIZE = 16
 
+# Bound EVERY acquire so an UNREACHABLE / non-responding DB fails in FINITE time instead of hanging
+# (#225). `acquire` has two sub-waits, both bounded to this budget: the factory's TCP connect
+# (`connect_timeout`, set in the pg/mysql factories) and the wait for a released connection when the
+# pool is at capacity (`_free.get(timeout=…)`). 30s matches the established codebase default — the v1
+# pg/mysql drivers' `config.timeout || 30` (src/drivers/postgres.ts, src/drivers/mysql.ts) — and the
+# other runtimes' pool-library connect/acquire timeouts (rust sqlx ~30s / deadpool wait, go database/sql
+# Ping, TS pg `connectionTimeoutMillis`). Only Python hand-rolls its pool, so it must supply the bound
+# those libraries give the other four legs for free.
+DEFAULT_ACQUIRE_TIMEOUT_SECONDS = 30.0
+
 
 class _ConnectionPool:
     """A minimal thread-safe, bounded pool of DB-API connections (dependency-free).
@@ -258,9 +268,9 @@ class _ConnectionPool:
     concurrent sibling its own connection.
     """
 
-    __slots__ = ("_factory", "_max", "_free", "_opened", "_lock", "_closed")
+    __slots__ = ("_factory", "_max", "_free", "_opened", "_lock", "_closed", "_acquire_timeout")
 
-    def __init__(self, factory, max_size: int) -> None:
+    def __init__(self, factory, max_size: int, acquire_timeout: float = DEFAULT_ACQUIRE_TIMEOUT_SECONDS) -> None:
         import queue as _queue
         import threading as _threading
 
@@ -269,6 +279,10 @@ class _ConnectionPool:
         self._free: "Any" = _queue.LifoQueue()
         self._opened = 0
         self._lock = _threading.Lock()
+        # The bound on the at-capacity wait for a released connection (see acquire). Finite so an
+        # exhausted pool that will never be replenished (e.g. every open failed) raises instead of
+        # blocking forever (#225).
+        self._acquire_timeout = acquire_timeout
         # Fail-fast after close(): a post-close acquire must RAISE, not block forever on `_free.get()`
         # (the pool is drained and nothing will be released). Additive — the Phase A/B paths never
         # acquire after close, so behavior there is unchanged; Phase C's close_all_pools relies on it so
@@ -285,14 +299,36 @@ class _ConnectionPool:
             return self._free.get_nowait()
         except _queue.Empty:
             pass
-        # Open a new one if below the ceiling; else wait for a release.
+        # Reserve a slot if below the ceiling, then open OUTSIDE the lock (a slow/blocked connect must
+        # not serialize every other acquire/release on this pool).
+        reserved = False
         with self._lock:
             if self._closed:
                 raise RuntimeError("scp connection pool: acquire after close (the pool has been closed)")
             if self._opened < self._max:
                 self._opened += 1
+                reserved = True
+        if reserved:
+            try:
                 return self._factory()
-        return self._free.get()  # block until a connection is released
+            except BaseException:
+                # The open FAILED — RELEASE the reserved slot (mirror `discard`'s decrement). Without
+                # this a failed connect permanently consumes capacity; once `_opened` hits the ceiling
+                # every later acquire falls through to the wait below with no connection ever coming, so
+                # an unreachable DB turns each fast connect-refused into an unbounded hang (#225).
+                with self._lock:
+                    self._opened -= 1
+                raise
+        # Pool at capacity: wait for a released connection, but BOUND the wait. An unbounded get() hangs
+        # forever when nothing will ever be released; on timeout raise a clear error instead (#225 — the
+        # parity target: the other runtimes' pool libraries bound this acquire wait).
+        try:
+            return self._free.get(timeout=self._acquire_timeout)
+        except _queue.Empty:
+            raise TimeoutError(
+                f"scp connection pool: acquire timed out after {self._acquire_timeout}s "
+                f"(pool at capacity {self._max}, no connection released)"
+            ) from None
 
     def release(self, conn: Any) -> None:
         self._free.put(conn)
@@ -352,9 +388,42 @@ def _dollar_to_pyformat(sql: str) -> str:
     return _DOLLAR_RE.sub("%s", sql.replace("%", "%%"))
 
 
+def rewrite_unquoted_placeholders(sql: str, render: Callable[[int], str]) -> str:
+    """Rewrite every ``?`` that is NOT inside a single-quoted SQL string literal, in order, to
+    ``render(n)`` (``n`` = 1-based placeholder ordinal). A ``?`` inside a literal is TEXT, not a
+    placeholder, and is left exactly as it is.
+
+    The ONE quote-aware ``?`` walk on this plane: both the dialect placeholder render
+    (:func:`litedbmodel_runtime.leaves.render_placeholders` — PG ``$N``) and the DB-API
+    paramstyle conversion (:func:`_qmark_to_pyformat` — PyMySQL ``%s``) go through it, so the two
+    cannot disagree about which ``?`` is a placeholder. They did: a naive ``str.replace`` rewrote a
+    quoted ``?`` as a placeholder and bound a value into a string literal, while the render skipped
+    it (the same class of split #202 names).
+    """
+    out: List[str] = []
+    index = 0
+    in_string = False
+    for ch in sql:
+        if in_string:
+            out.append(ch)
+            if ch == "'":
+                in_string = False
+        elif ch == "'":
+            out.append(ch)
+            in_string = True
+        elif ch == "?":
+            index += 1
+            out.append(render(index))
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
 def _qmark_to_pyformat(sql: str) -> str:
-    """MySQL render keeps `?`; PyMySQL binds `%s`. Replace each `?` with `%s` (literal `%` doubled)."""
-    return sql.replace("%", "%%").replace("?", "%s")
+    """MySQL render keeps `?`; PyMySQL binds `%s`. Rewrite each PLACEHOLDER `?` to `%s` (literal `%`
+    doubled). A `?` inside a string literal is TEXT — PyMySQL substitutes positionally over the whole
+    text, so rewriting one would bind a value INSIDE the literal and shift every later value."""
+    return rewrite_unquoted_placeholders(sql.replace("%", "%%"), lambda _n: "%s")
 
 
 def _parse_pk_hint(hint_region: str):
@@ -730,8 +799,12 @@ class PostgresDriver(_PooledDriver):
         import psycopg  # imported lazily so the SQLite conformance never needs the driver installed
 
         def factory():
+            # connect_timeout bounds the TCP connect so an unreachable/non-responding host fails in
+            # finite time (psycopg has NO default connect timeout — a blackhole host would block the
+            # acquire forever, #225). Matches the v1 driver's 30s default and the other runtimes.
             return psycopg.connect(
-                host=host, port=port, user=user, password=password, dbname=dbname, autocommit=True
+                host=host, port=port, user=user, password=password, dbname=dbname, autocommit=True,
+                connect_timeout=int(DEFAULT_ACQUIRE_TIMEOUT_SECONDS),
             )
 
         pool = _ConnectionPool(factory, pool_size)
@@ -761,8 +834,11 @@ class MysqlDriver(_PooledDriver):
         import pymysql  # lazy import (conformance bar never needs it)
 
         def factory():
+            # connect_timeout bounds the TCP connect so an unreachable host fails in finite time (#225).
+            # PyMySQL defaults this to 10s; pin it to the shared budget so both live drivers agree.
             return pymysql.connect(
-                host=host, port=port, user=user, password=password, database=dbname, autocommit=True
+                host=host, port=port, user=user, password=password, database=dbname, autocommit=True,
+                connect_timeout=int(DEFAULT_ACQUIRE_TIMEOUT_SECONDS),
             )
 
         pool = _ConnectionPool(factory, pool_size)

{litedbmodel_runtime-2.2.2 → litedbmodel_runtime-2.2.4}/litedbmodel_runtime/errors.py

@@ -67,12 +67,12 @@ class LimitExceededError(Exception):
     """The SHARED cross-language runaway-prevention error (Phase E-2, epic #74; Python port of the TS
     ``LimitExceededError`` reference in ``src/scp/errors.ts``, #99).
 
-    Raised by the native read / relation post-fetch guard when a read (``context='find'``) or a
-    ``hasMany`` relation batch (``context='relation'``) returns MORE rows than the cap BAKED onto the
-    portable artifact (``ReadGraph.findGuard.hardLimit`` / ``RelationOp.hardLimit``), so an accidental
-    missing-WHERE / N+1 pattern fails LOUD instead of loading an unbounded result. NOT a
+    Raised by the leaf transport's post-fetch guard (:func:`check_find_hard_limit`) when a read
+    (``context='find'``) or a ``hasMany`` relation batch (``context='relation'``) returns MORE rows than
+    the cap BAKED onto the portable artifact and carried in the leaf payload's guard record, so an
+    accidental missing-WHERE / N+1 pattern fails LOUD instead of loading an unbounded result. NOT a
     :class:`SqlFailure` (a runaway guard is a litedbmodel-level policy error, carrying no ``SQLITE_*``
-    code — so :func:`litedbmodel_runtime.static_bundle._re_error_to_sql_failure` propagates it
+    code — so the ``SQLITE_*``-keyed driver-error mapping (:func:`map_sqlite_error`) propagates it
     unchanged). Byte-for-byte with the TS reference:
 
       - fields: ``limit`` (the cap), ``count`` (rows fetched), ``context`` (``'find'`` | ``'relation'``),
@@ -124,7 +124,7 @@ class LimitExceededError(Exception):
     ) -> None:
         """The SHARED post-fetch runaway check (SSoT) — the ONE ``count > limit ⇒ raise`` primitive
         both the FIND-context guard (:func:`check_find_hard_limit`) and the RELATION-context guard
-        (:func:`litedbmodel_runtime.relation.run_relation_op`) call, so no path re-implements the
+        (the ``guard`` control field the emitter bakes) call, so no path re-implements the
         comparison or the error assembly (Python port of the rust ``LimitExceededError::check`` /
         go ``CheckLimit`` SSoT). ``None`` (returns) when within the cap; raises otherwise."""
         if count > limit:

{litedbmodel_runtime-2.2.2 → litedbmodel_runtime-2.2.4}/litedbmodel_runtime/exec_context.py

@@ -3,7 +3,7 @@
 The Python port of the TS contract-defining artifact ``src/scp/exec-context.ts`` (#75), mirroring the
 rust port ``rust/litedbmodel_runtime/src/exec_context.rs`` (#76) and the go port
 ``go/litedbmodel_runtime/exec_context.go`` (#77). It replaces the raw ``driver: Driver`` threaded
-through ``execute_bundle`` / ``execute_read_graph`` / the relation walker / ``execute_transaction_bundle``
+through the leaf transport (:func:`execute` / :func:`run` / :func:`run_guarded`)
 with an :class:`ExecutionContext` that carries:
 
   1. a **connection provider** — :meth:`ExecutionContext.connection_for` ``(intent)`` resolves WHICH
@@ -11,8 +11,9 @@ with an :class:`ExecutionContext` that carries:
      only the tx-owned + single-DB cases, reader/writer/named-DB are B/C/D on this seam);
   2. a **middleware chain** — :attr:`ExecutionContext.middleware`, wrapping every SQL (empty in
      Phase A = passthrough; the registration API is Phase D — this is only the hook point);
-  3. a **pinned tx connection** — a tx-scoped ctx pins ONE owned connection so every statement in a
-     transaction body runs on it (per-execution connection ownership, §3).
+  3. a **pinned tx connection** — a tx-scoped ctx pins ONE owned connection so every statement of the tx's own database
+     in a transaction body runs on it — a statement naming a DIFFERENT database is rejected
+     (per-execution connection ownership, §3).
 
 ## The central seam (§2) — ALL SQL funnels through here
 
@@ -150,8 +151,9 @@ class DriverConnection(Connection):
 
 class _TxConnectionAdapter(Connection):
     """A :class:`Connection` view over a tx's OWNED :class:`TxConnection` handle. The seam resolves
-    this (via ``connection_for``) for every statement inside a tx, so all of them run on the SAME
-    owned connection. Concurrent transactions each hold a DISTINCT handle over a DISTINCT pooled
+    this (via ``connection_for``) for every statement inside a tx of the tx's own database — an unnamed one, or one naming
+    that database — so all of THOSE run on the SAME owned connection (a statement naming a DIFFERENT database is rejected
+    instead). Concurrent transactions each hold a DISTINCT handle over a DISTINCT pooled
     connection, so their writes never cross-talk — the isolation the removed driver-global ``_writer``
     slot violated.
     """
@@ -240,8 +242,8 @@ _EMPTY_CHAIN = MiddlewareChain()
 
 
 class ExecutionContext:
-    """The execution context threaded through ``execute_bundle`` / ``execute_read_graph`` / the
-    relation walker / ``execute_transaction_bundle`` in place of a raw :class:`Driver`. It carries the
+    """The execution context threaded through the leaf transport and the central execute/run/run_guarded
+    seam in place of a raw :class:`Driver`. It carries the
     connection provider (the primary driver + an optional pinned tx connection), the middleware chain,
     and derives a tx-scoped ctx via :meth:`with_connection`.
 
@@ -255,9 +257,10 @@ class ExecutionContext:
     An OPTIONAL ``routing`` (a ``litedbmodel_runtime.connection_routing.RoutingConfig``) completes
     ``connection_for``'s resolution steps 2-4 (reader/writer split, named-DB, writer-sticky). Absent ⇒
     the byte-identical Phase A/B single-``driver`` path (``context_for_driver`` builds NO routing). The
-    active-tx pin STILL wins over routing (step 1) — a named-DB transaction runs entirely on ONE pinned
-    writer connection (Phase B unbroken). Only when routing IS present does ``connection_for`` consult
-    the registry; the driver-only ctors keep working unchanged.
+    active-tx pin STILL comes first (step 1) — a transaction runs entirely on ONE pinned writer
+    connection, so a statement naming a DIFFERENT database is rejected there rather than routed. Only when
+    routing IS present does ``connection_for`` consult the registry; the driver-only ctors keep working
+    unchanged.
     """
 
     __slots__ = ("_driver", "middleware", "_pinned", "_read_only", "_routing", "_connection")
@@ -273,7 +276,8 @@ class ExecutionContext:
     ) -> None:
         self._driver = driver
         self.middleware = middleware
-        # The pinned tx connection (present ⇒ this is a tx-scoped ctx; every statement resolves it).
+        # The pinned tx connection (present ⇒ a tx-scoped ctx; every statement
+        # of the tx's own database (an unnamed one, or one naming that database) resolves it).
         self._pinned = pinned
         # The READ-ONLY marker (Phase B / #84 write=tx guard — mirror v1 `withWriter` / the TS
         # `withReadOnly` ALS marker / rust/go `read_only`): a write in a read-only-scoped ctx is
@@ -315,7 +319,7 @@ class ExecutionContext:
     def with_read_only(self) -> "ExecutionContext":
         """Derive a READ-ONLY-scoped ctx (mirror v1 ``withWriter`` / the TS ``withReadOnly`` / rust/go
         ``with_read_only``): reads are allowed, but ANY write funneled through the GUARDED write seam
-        (:func:`run_guarded` / a guarded ``execute_transaction_bundle``) is rejected with
+        (:func:`run_guarded`) is rejected with
         :class:`WriteInReadOnlyContextError`. A tx-scoped ctx INHERITS its pinned connection + driver +
         middleware; a Transaction() opened inside a read-only scope stays read-only (v1 parity)."""
         return ExecutionContext(
@@ -325,14 +329,24 @@ class ExecutionContext:
     def connection_for(self, intent: StatementIntent = READ_INTENT) -> Connection:
         """Resolve WHICH connection a statement runs on (§3). Resolution order (first match wins):
 
-          1. the tx-owned (pinned) connection — inside a tx it ALWAYS wins (Phase A / B). A named-DB
-             transaction runs entirely on this ONE pinned writer connection (Phase B unbroken).
+          1. the tx-owned (pinned) connection — inside a tx it serves every statement of the tx's own database,
+             because a transaction is ONE
+             connection. A statement naming a DIFFERENT database than the transaction opened on therefore
+             cannot be honored and is LOUD (:func:`~litedbmodel_runtime.connection_routing.assert_tx_db_agrees`);
+             an unnamed one, and one naming the SAME database, run on the pin.
           2-4. when Phase C routing is present: named-DB → reader/writer split → writer-sticky/withWriter
              (:func:`litedbmodel_runtime.connection_routing.resolve_pool`), running the statement on ONE
              pooled connection per statement (the read fan-out).
           otherwise (no routing): the primary driver — the byte-identical Phase A/B single-DB path.
         """
         if self._pinned is not None:
+            # A statement that names a DIFFERENT database than the transaction opened on cannot be honored
+            # on the pinned connection — a transaction is ONE connection on ONE database — so it is LOUD
+            # rather than silently executed against the transaction's database (#217). The name the tx
+            # opened on is this ctx's own (``with_connection_name``, the same attribute ``begin_tx`` reads).
+            from .connection_routing import assert_tx_db_agrees
+
+            assert_tx_db_agrees(intent.db, self._connection)
             return self._pinned
         if self._routing is not None:
             # Phase C (#90): named-DB → reader/writer → writer-sticky. Lazy import avoids the circular
@@ -340,10 +354,17 @@ class ExecutionContext:
             from .connection_routing import PoolConnection, resolve_pool
 
             return PoolConnection(resolve_pool(intent, self._routing))
+        # No pin: a statement that NAMES a database has nowhere to go on a single-driver ctx either
+        # (there is no registry to resolve the name against), so it is LOUD — exactly as an unregistered name is on a
+        # routed ctx (``ConnectionRegistry.pair_for``). Running it on the primary driver instead would
+        # execute it against a DIFFERENT database than its model declares, silently (#217).
+        from .connection_routing import assert_routable_named_db
+
+        assert_routable_named_db(intent.db, "a single-driver (non-routed) execution context")
         return DriverConnection(self._driver)
 
     def with_connection(self, conn: Connection, tx: bool) -> "ExecutionContext":
-        """Derive a tx-scoped ctx pinning ``conn`` (every statement resolves it while ``tx`` is True).
+        """Derive a tx-scoped ctx pinning ``conn`` (every statement of the tx's own database (an unnamed one, or one naming that database) resolves it while ``tx`` is True).
         The derived ctx shares the primary driver + middleware chain + routing, and INHERITS the
         read-only marker (a tx opened inside a read-only scope stays read-only — v1 parity). This is the
         Python analogue of the TS ``withConnection(conn, tx)`` / go ``WithTxConnection`` / rust
@@ -375,8 +396,9 @@ class ExecutionContext:
         """Acquire + OWN the tx connection for THIS ctx (§3). On the single-driver Phase A/B path this
         delegates to ``driver.begin_tx``. When Phase C routing is present the tx acquires ONE connection
         from the target NAMED connection's WRITER pool (:attr:`_connection` → the writer pool of that
-        registry pair), so a named-DB transaction runs entirely on ONE pinned writer connection — the
-        active-tx pin then wins over routing for every statement in the body (Phase B unbroken).
+        registry pair), so a named-DB transaction runs entirely on ONE pinned writer connection: every
+        UNNAMED in-body statement resolves the pin, one that names THIS connection does too, and one naming
+        a DIFFERENT database is rejected (a transaction cannot span two databases).
 
         tx-control (the isolation SET / BEGIN / COMMIT / ROLLBACK) is issued THROUGH the seam on the
         pinned connection by :func:`with_transaction_decided` (Phase D / #95, middleware-visible), NOT
@@ -473,9 +495,8 @@ def context_for_driver(driver: Driver) -> ExecutionContext:
 
 def as_context(driver_or_ctx: Union[Driver, ExecutionContext]) -> ExecutionContext:
     """Accept EITHER a raw :class:`Driver` (wrap it via :func:`context_for_driver` — the byte-identical
-    backward-compat path) OR an already-built :class:`ExecutionContext` (pass through). The public
-    runtime entry points (``execute_bundle`` / ``execute_transaction_bundle`` / ``run_relation_op`` /
-    ``read_bundle``) take this union so every existing caller that threads a raw driver keeps working
+    backward-compat path) OR an already-built :class:`ExecutionContext` (pass through). The leaf
+    transport (:func:`make_handlers`) takes this union so a caller that threads a raw driver keeps working
     while the ctx-threaded internals funnel every SQL through the seam.
     """
     if isinstance(driver_or_ctx, ExecutionContext):
@@ -525,7 +546,8 @@ def with_transaction_decided(
          exclusive connection), the Python analogue of v1 ``PoolTransaction``. **No tx-control is issued
          at acquire** (Phase D / #95): the connection is only owned here.
       2. pin it into a tx-scoped :class:`ExecutionContext` (and the ambient contextvar) so EVERY
-         statement resolves THAT connection via the seam — never a fresh pooled one;
+         statement of the tx's own database resolves THAT connection via the seam — never a fresh
+         pooled one, and a statement naming a DIFFERENT database is rejected instead;
       3. issue the isolation SET + ``BEGIN`` (``before`` → BEGIN → ``after``) THROUGH the seam
          (:func:`run` on the PINNED ctx) — so a registered middleware OBSERVES the runtime BEGIN (full TS
          parity, Phase D / #95). tx-control goes through the UNGUARDED :func:`run` seam (never
@@ -702,8 +724,8 @@ def transaction(
     ## The ambient-tx JOIN — how operations participate (the core #86 fix; python = contextvars)
 
     ``fn`` takes NO connection argument. Instead the pinned tx ctx lives in the ambient contextvar
-    (:func:`current_context`). Every operation ``fn`` issues — a live-DB write via
-    ``execute_transaction_bundle``, a read via ``execute_bundle`` — detects that ambient pinned ctx and
+    (:func:`current_context`). Every operation ``fn`` issues — a write via the guarded write seam
+    (:func:`run_guarded`), a read via the read seam — resolves that ambient pinned ctx and
     runs its statements on THAT connection **without opening its own BEGIN/COMMIT** (the nested-join,
     below). So N operations inside one ``transaction(fn)`` produce exactly ONE BEGIN + ONE COMMIT on
     ONE connection. Outside a ``transaction(fn)`` the ambient pin is absent, so a bare guarded write's
@@ -759,7 +781,7 @@ def transaction(
             # A live PG 40001 / MySQL 1213 (raised at COMMIT as a raw psycopg/PyMySQL error) thus flows
             # through `map_sqlite_error` here, making the `.wrapped` chain genuinely load-bearing on the
             # live retry path (neuter `.wrapped` → this classification goes RED). An already-mapped
-            # `SqlFailure` (e.g. from a nested `execute_transaction_bundle`) is left as-is (no re-map).
+            # `SqlFailure` (e.g. surfaced by the guarded write seam) is left as-is (no re-map).
             failure = error if isinstance(error, SqlFailure) else map_sqlite_error(error)
             if attempt < retry_limit and opts.retry_on_error and is_retryable_tx_error(failure):
                 # Exponential backoff before RETRYing the whole transaction on a fresh connection.

{litedbmodel_runtime-2.2.2 → litedbmodel_runtime-2.2.4}/litedbmodel_runtime/grouping.py

@@ -7,7 +7,7 @@ a single source of truth (no duplicated grouping logic):
 
   - the op-INDEPENDENT ``pluck`` / ``group`` leaves (``./leaves``) — the eager N+1-free graph
     (``parents → pluck → executeSQL(WHERE fk = ANY(?)) → group``);
-  - the RUNTIME batch relation path (``./relation`` ``run_relation_op`` / ``distribute_to_parent``),
+  - already-fetched rows, grouped over the SAME algorithm,
     which groups already-fetched rows over the SAME core.
 
 Nothing here touches SQL or a driver: it is pure in-memory grouping over already-fetched rows