storepy 2.4.0__tar.gz → 2.5.0__tar.gz

{storepy-2.4.0/src/storepy.egg-info → storepy-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: storepy
-Version: 2.4.0
+Version: 2.5.0
 Summary: Multi-backend data layer for Python asyncio (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control
 Author-email: leo <coen_ddt@qq.com>
 License-Expression: MIT
@@ -370,11 +370,27 @@ async def transfer():
 await store.transaction("default", transfer)
 ```
 
-- `store.transaction(source, fn)` opens a transaction scope on one SQL source: every `execute_raw` / CRUD call inside `fn` lands on that source's transaction connection, with `commit` / `rollback` as one unit (reuses the internal `run_in_transaction`). Mongo sources or executors without transactions run `fn` as-is — it never pretends to be atomic.
-- `store.execute_raw(source, sql, params=None, is_write=False)` runs raw SQL, bypassing GQL parsing and dialect translation. Placeholders follow each backend's native style: `?` for MySQL / SQLite, `$1..$n` for PostgreSQL. SQL sources only — a Mongo source raises `RawSqlError` (`py_store.RawSqlError` / `store.RawSqlError`).
-- `is_write=False` (default) returns `{"rows", "affectedRows"}` with the result-set rows; `is_write=True` returns the affected-row count.
+- `store.transaction(source, fn)` opens a transaction scope on one source: every `execute_raw` / CRUD call inside `fn` lands on that source's transaction connection, with `commit` / `rollback` as one unit (reuses the internal `run_in_transaction`). Mongo sources are probed at runtime (replica set / sharded) and wrapped in a session transaction; on standalone or probe failure `fn` runs as-is and emits `mongo_transaction_unsupported` (`deployment: standalone|unknown`) — it never pretends to be atomic. Executors without `with_transaction` also run `fn` as-is and emit a `transaction_not_atomic` feedback event (degradation is allowed, silent pretence is not). A nested same-source transaction opens a savepoint (an inner failure rolls back only that scope); without savepoint primitives it degrades by joining the outer transaction and emits `nested_savepoint_unsupported`.
+- `store.execute_raw(source, sql, params=None, is_write=None)` runs raw SQL, compiled by the core `raw_stmt_compile`. Two styles selected by the `params` type: **positional** (list/tuple/None) passes the SQL through as-is with native placeholders (`?` for MySQL / SQLite, `$1..$n` for PostgreSQL); **named** (dict) compiles `:name` tokens in the SQL into dialect placeholders (same-name reuse, `::` casts / quotes / comments kept intact; missing or unused names raise `RawSqlError`). SQL sources only — a Mongo source raises `RawSqlError` (`py_store.RawSqlError` / `store.RawSqlError`).
+- When `is_write` is omitted it is inferred from the SQL's first word (SELECT / WITH / EXPLAIN / SHOW / PRAGMA / TABLE count as reads, everything else as a write — defaulting to write is the safe direction); passing it explicitly overrides the inference. Returns `{"rows", "affectedRows"}`: rows for reads, the affected-row count for writes.
+- `store.execute_native(source, collection, pipeline=None, options=None)` runs a native aggregation pipeline on a Mongo source (the Mongo counterpart of the SQL-side `execute_raw` escape hatch): `pipeline` is a native aggregation pipeline, `options` uses driver-native keys (`allowDiskUse` / `batchSize` / `hint` / `maxTimeMS`..., no host-side whitelist). Inside a transaction / session the session is injected automatically (owned by the transaction; `options.session` cannot override it); resolution always follows the read path, so `$merge` / `$out` write stages require you to open a transaction yourself. Mongo sources only — a SQL source raises `NativeCommandError` pointing to `execute_raw`; the MongoClient form requires a schema-declared namespace. Returns `{"rows"}`.
 - **The non-transactional path commits explicitly**: on SQL sources, a write plan that runs outside `store.transaction` is committed by the executor (`commit` on success; `rollback` then re-raise on failure). `aiosqlite` is not autocommit by default, so without that commit the write would be visible only on the current connection while `execute_raw` still reported success — a silent data-loss hazard. Multi-statement writes that must be atomic as a group belong inside `store.transaction`.
 
+### Session (Unit of Work)
+
+```python
+async with store.session() as s:
+    await s.insert("Order", {...})
+    await s.update("Account", cond, {...})
+    await s.execute_raw("pg_main", "SELECT ... FOR UPDATE", [1])
+```
+
+- Inside a session, **every command on the same SQL source lands on one transaction connection**: the session commits once on exit, and rolls back as one unit on any exception.
+- **Lazy transaction start**: a session with no commands never checks out a connection.
+- **Cross-source writes fail closed**: if a session writes to ≥2 datasources, it rolls everything back and raises `NonAtomicWriteError` on exit (no distributed transaction — it never commits a half-done unit of work).
+- Mongo sources are probed at runtime (replica set / sharded) and made transactional; on standalone or probe failure they run as-is (non-atomic) and emit one `mongo_transaction_unsupported` (`deployment: standalone|unknown`) feedback event.
+- Sessions nest: an inner scope opens a savepoint (`SAVEPOINT sp_<n>`) on the outer transaction and, on exit, `RELEASE`s it (success) or `ROLLBACK TO`s and releases it (failure) — **an inner failure rolls back only the inner scope while the outer one continues**. When the transaction handle has no savepoint primitives, the nested scope degrades by joining the outer one and emits one `nested_savepoint_unsupported` feedback event.
+
 ### DDL generation
 
 ```python
@@ -517,11 +533,20 @@ Boundary rules worth knowing up front (all **fail explicitly**, never silently d
 
 ## Transaction boundary
 
-- **Single SQL source**: `mutation` parent-child step sequences and `remove` (archive + delete) run inside one driver transaction on one checked-out connection — any step failure rolls back the whole sequence.
-- **Each SQL write command** is itself atomic: multi-statement plans (e.g. MySQL write + readback) are transaction-wrapped in the executor.
-- **Mongo sources**: single-document writes are atomic; multi-step `mutation` and `remove` execute sequentially and are **not** atomic across steps (Mongo transactions require a replica set). If your consistency requirement spans steps on Mongo, either use an SQL source for those models or add application-level compensation.
+| Scenario | Atomicity |
+|---|---|
+| Single-command API (`insert` / `insert_many` / `update_many` / `upsert` / `remove` / `count` / `exists`) | Naturally atomic within one SQL source (a single statement); single documents are atomic on Mongo |
+| `store.transaction(source, fn)` | Atomic within one SQL source: every command in the scope shares one connection and one transaction; nested same-source scopes use a savepoint (an inner failure rolls back only that scope) |
+| `store.session(...)` | Atomic **across multiple calls** on one SQL source inside the session; cross-source writes are rejected explicitly (`NonAtomicWriteError`) |
+| Cross-source multi-write without a session | Not atomic (no 2PC / Saga), executed datasource by datasource, and declares `nonAtomic` via the feedback channel (event `non_atomic_write`, with the sources) |
+| Multi-step writes on Mongo | replica set / sharded: atomic on a single Mongo source (session transaction); standalone: non-atomic and explicitly declares `mongo_transaction_unsupported` |
+
+- **Mongo sources**: made transactional inside a session according to the runtime probe; non-transactable ones (standalone / probe failure) run as-is and emit a `mongo_transaction_unsupported` feedback event (`deployment: standalone|unknown`) (degradation is allowed, silent pretence is not).
+- **SQL executors without `open_transaction`**: commands run as-is inside a session and emit a `session_not_atomic` feedback event (degradation is allowed, silent pretence is not).
+- **SQL executors without `with_transaction`**: commands run as-is inside a transaction scope (or the top-level atomic envelope) and emit a `transaction_not_atomic` feedback event (symmetric with `session_not_atomic`; degradation is allowed, silent pretence is not).
 - **Archive idempotency**: `remove` archives with upsert-by-`_id` semantics, so a retry after partial failure no longer fails on duplicate `_id`.
-- **Cross-source steps** (parent and child bound to different datasources) cannot be atomic — they run sequentially by design.
+- Read consistency: only multiple reads inside an explicit session share one transaction connection; reads outside a session do not open an extra transaction.
+- **Cross-source writes (no session)**: a single write call touching ≥2 datasources **cannot be atomic**; it runs sequentially and emits one `non_atomic_write` feedback event (`code: nonAtomic`, with the source list) — degradation is allowed, silence is not. Converge writes onto a single source, or wrap them in `store.session()` (which fails closed on cross-source writes).
 
 ## FAQ
 

{storepy-2.4.0 → storepy-2.5.0}/README.md

@@ -330,11 +330,27 @@ async def transfer():
 await store.transaction("default", transfer)
 ```
 
-- `store.transaction(source, fn)` opens a transaction scope on one SQL source: every `execute_raw` / CRUD call inside `fn` lands on that source's transaction connection, with `commit` / `rollback` as one unit (reuses the internal `run_in_transaction`). Mongo sources or executors without transactions run `fn` as-is — it never pretends to be atomic.
-- `store.execute_raw(source, sql, params=None, is_write=False)` runs raw SQL, bypassing GQL parsing and dialect translation. Placeholders follow each backend's native style: `?` for MySQL / SQLite, `$1..$n` for PostgreSQL. SQL sources only — a Mongo source raises `RawSqlError` (`py_store.RawSqlError` / `store.RawSqlError`).
-- `is_write=False` (default) returns `{"rows", "affectedRows"}` with the result-set rows; `is_write=True` returns the affected-row count.
+- `store.transaction(source, fn)` opens a transaction scope on one source: every `execute_raw` / CRUD call inside `fn` lands on that source's transaction connection, with `commit` / `rollback` as one unit (reuses the internal `run_in_transaction`). Mongo sources are probed at runtime (replica set / sharded) and wrapped in a session transaction; on standalone or probe failure `fn` runs as-is and emits `mongo_transaction_unsupported` (`deployment: standalone|unknown`) — it never pretends to be atomic. Executors without `with_transaction` also run `fn` as-is and emit a `transaction_not_atomic` feedback event (degradation is allowed, silent pretence is not). A nested same-source transaction opens a savepoint (an inner failure rolls back only that scope); without savepoint primitives it degrades by joining the outer transaction and emits `nested_savepoint_unsupported`.
+- `store.execute_raw(source, sql, params=None, is_write=None)` runs raw SQL, compiled by the core `raw_stmt_compile`. Two styles selected by the `params` type: **positional** (list/tuple/None) passes the SQL through as-is with native placeholders (`?` for MySQL / SQLite, `$1..$n` for PostgreSQL); **named** (dict) compiles `:name` tokens in the SQL into dialect placeholders (same-name reuse, `::` casts / quotes / comments kept intact; missing or unused names raise `RawSqlError`). SQL sources only — a Mongo source raises `RawSqlError` (`py_store.RawSqlError` / `store.RawSqlError`).
+- When `is_write` is omitted it is inferred from the SQL's first word (SELECT / WITH / EXPLAIN / SHOW / PRAGMA / TABLE count as reads, everything else as a write — defaulting to write is the safe direction); passing it explicitly overrides the inference. Returns `{"rows", "affectedRows"}`: rows for reads, the affected-row count for writes.
+- `store.execute_native(source, collection, pipeline=None, options=None)` runs a native aggregation pipeline on a Mongo source (the Mongo counterpart of the SQL-side `execute_raw` escape hatch): `pipeline` is a native aggregation pipeline, `options` uses driver-native keys (`allowDiskUse` / `batchSize` / `hint` / `maxTimeMS`..., no host-side whitelist). Inside a transaction / session the session is injected automatically (owned by the transaction; `options.session` cannot override it); resolution always follows the read path, so `$merge` / `$out` write stages require you to open a transaction yourself. Mongo sources only — a SQL source raises `NativeCommandError` pointing to `execute_raw`; the MongoClient form requires a schema-declared namespace. Returns `{"rows"}`.
 - **The non-transactional path commits explicitly**: on SQL sources, a write plan that runs outside `store.transaction` is committed by the executor (`commit` on success; `rollback` then re-raise on failure). `aiosqlite` is not autocommit by default, so without that commit the write would be visible only on the current connection while `execute_raw` still reported success — a silent data-loss hazard. Multi-statement writes that must be atomic as a group belong inside `store.transaction`.
 
+### Session (Unit of Work)
+
+```python
+async with store.session() as s:
+    await s.insert("Order", {...})
+    await s.update("Account", cond, {...})
+    await s.execute_raw("pg_main", "SELECT ... FOR UPDATE", [1])
+```
+
+- Inside a session, **every command on the same SQL source lands on one transaction connection**: the session commits once on exit, and rolls back as one unit on any exception.
+- **Lazy transaction start**: a session with no commands never checks out a connection.
+- **Cross-source writes fail closed**: if a session writes to ≥2 datasources, it rolls everything back and raises `NonAtomicWriteError` on exit (no distributed transaction — it never commits a half-done unit of work).
+- Mongo sources are probed at runtime (replica set / sharded) and made transactional; on standalone or probe failure they run as-is (non-atomic) and emit one `mongo_transaction_unsupported` (`deployment: standalone|unknown`) feedback event.
+- Sessions nest: an inner scope opens a savepoint (`SAVEPOINT sp_<n>`) on the outer transaction and, on exit, `RELEASE`s it (success) or `ROLLBACK TO`s and releases it (failure) — **an inner failure rolls back only the inner scope while the outer one continues**. When the transaction handle has no savepoint primitives, the nested scope degrades by joining the outer one and emits one `nested_savepoint_unsupported` feedback event.
+
 ### DDL generation
 
 ```python
@@ -477,11 +493,20 @@ Boundary rules worth knowing up front (all **fail explicitly**, never silently d
 
 ## Transaction boundary
 
-- **Single SQL source**: `mutation` parent-child step sequences and `remove` (archive + delete) run inside one driver transaction on one checked-out connection — any step failure rolls back the whole sequence.
-- **Each SQL write command** is itself atomic: multi-statement plans (e.g. MySQL write + readback) are transaction-wrapped in the executor.
-- **Mongo sources**: single-document writes are atomic; multi-step `mutation` and `remove` execute sequentially and are **not** atomic across steps (Mongo transactions require a replica set). If your consistency requirement spans steps on Mongo, either use an SQL source for those models or add application-level compensation.
+| Scenario | Atomicity |
+|---|---|
+| Single-command API (`insert` / `insert_many` / `update_many` / `upsert` / `remove` / `count` / `exists`) | Naturally atomic within one SQL source (a single statement); single documents are atomic on Mongo |
+| `store.transaction(source, fn)` | Atomic within one SQL source: every command in the scope shares one connection and one transaction; nested same-source scopes use a savepoint (an inner failure rolls back only that scope) |
+| `store.session(...)` | Atomic **across multiple calls** on one SQL source inside the session; cross-source writes are rejected explicitly (`NonAtomicWriteError`) |
+| Cross-source multi-write without a session | Not atomic (no 2PC / Saga), executed datasource by datasource, and declares `nonAtomic` via the feedback channel (event `non_atomic_write`, with the sources) |
+| Multi-step writes on Mongo | replica set / sharded: atomic on a single Mongo source (session transaction); standalone: non-atomic and explicitly declares `mongo_transaction_unsupported` |
+
+- **Mongo sources**: made transactional inside a session according to the runtime probe; non-transactable ones (standalone / probe failure) run as-is and emit a `mongo_transaction_unsupported` feedback event (`deployment: standalone|unknown`) (degradation is allowed, silent pretence is not).
+- **SQL executors without `open_transaction`**: commands run as-is inside a session and emit a `session_not_atomic` feedback event (degradation is allowed, silent pretence is not).
+- **SQL executors without `with_transaction`**: commands run as-is inside a transaction scope (or the top-level atomic envelope) and emit a `transaction_not_atomic` feedback event (symmetric with `session_not_atomic`; degradation is allowed, silent pretence is not).
 - **Archive idempotency**: `remove` archives with upsert-by-`_id` semantics, so a retry after partial failure no longer fails on duplicate `_id`.
-- **Cross-source steps** (parent and child bound to different datasources) cannot be atomic — they run sequentially by design.
+- Read consistency: only multiple reads inside an explicit session share one transaction connection; reads outside a session do not open an extra transaction.
+- **Cross-source writes (no session)**: a single write call touching ≥2 datasources **cannot be atomic**; it runs sequentially and emits one `non_atomic_write` feedback event (`code: nonAtomic`, with the source list) — degradation is allowed, silence is not. Converge writes onto a single source, or wrap them in `store.session()` (which fails closed on cross-source writes).
 
 ## FAQ
 

{storepy-2.4.0 → storepy-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "storepy"
-version = "2.4.0"
+version = "2.5.0"
 description = "Multi-backend data layer for Python asyncio (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control"
 readme = "README.md"
 requires-python = ">=3.10"

{storepy-2.4.0 → storepy-2.5.0}/src/py_store/__init__.py

@@ -39,7 +39,10 @@ from . import (
 from . import (
     introspect as introspect,
 )
+from .datasource import NativeCommandError as NativeCommandError
+from .datasource import NonAtomicWriteError as NonAtomicWriteError
 from .datasource import RawSqlError as RawSqlError
+from .datasource import Session as Session
 from .sync import sync_schema
 
 
@@ -145,18 +148,57 @@ class Store:
         fn 内 execute_raw / CRUD 均落到该源的事务连接（commit/rollback 一体）；
         Mongo 源或执行器未实现事务时按原样执行（跨源无法原子），绝不静默假装已事务化。
         单源场景 source 传 ``'default'``。
+
+        同源嵌套 transaction 会开保存点（内层失败只回滚本层）；句柄无保存点原语时
+        降级并入外层并发 ``nested_savepoint_unsupported``。
         """
         return await datasource.run_in_transaction(source, fn)
 
-    async def execute_raw(self, source: str, sql: str, params: list | None = None,
-                          is_write: bool = False) -> dict[str, Any]:
-        """在指定 SQL 源执行原生 SQL（事务内可用；占位符按各后端原生风格）
+    def session(self):
+        """会话（工作单元）：``async with`` 语法，退出统一提交 / 异常统一回滚
+
+        用法::
+
+            async with store.session() as s:
+                await s.insert('Order', {...})
+                await s.update('Account', cond, {...})
+                await s.execute_raw('pg_main', 'SELECT ... FOR UPDATE', [1])
+
+        约束：同一会话内写命令只允许落在**单一数据源**；跨源写退出时抛
+        ``NonAtomicWriteError``（先全部回滚，绝不提交半截）。
 
-        mysql/sqlite 用 ``?``，postgres 用 ``$1..$n``；仅支持 SQL 源（Mongo 源抛
-        RawSqlError）。``is_write=False`` 取行（rows），``True`` 取影响行数（affectedRows）。
+        嵌套：内层会话作为嵌套作用域在已有事务上开保存点，内层失败只回滚本层
+        （生命周期仍交外层）。
+        """
+        return Session()
+
+    async def execute_raw(self, source: str, sql: str, params: list | tuple | dict | None = None,
+                          is_write: bool | None = None) -> dict[str, Any]:
+        """在指定 SQL 源执行原生 SQL（事务内可用；编译由 core raw_stmt_compile 完成）
+
+        两档参数风格：位置档（params 为 list/tuple/None）→ 占位符为各后端原生风格
+        （mysql/sqlite 用 ``?``，postgres 用 ``$1..$n``），SQL 原样透传；命名档
+        （params 为 dict）→ SQL 文本中的 ``:name`` 编译为方言占位符（同名复用、
+        跳过 ``::`` cast / 引号 / 注释边界；缺名 / 多余名显式报错）。
+        ``is_write`` 缺省时按 SQL 首词推断（读白名单外一律按写——安全方向）。
+        仅支持 SQL 源（Mongo 源抛 RawSqlError）。返回 rows / affectedRows。
         """
         return await datasource.execute_raw(source, sql, params, is_write)
 
+    async def execute_native(self, source: str, collection: str,
+                             pipeline: list | None = None,
+                             options: dict | None = None) -> dict[str, Any]:
+        """在指定 Mongo 源执行原生聚合管道（事务内可用；对标 SQL 侧 execute_raw）
+
+        ``pipeline`` 为原生聚合管道（list[dict]），``options`` 为驱动原生透传项
+        （allowDiskUse/batchSize/hint/maxTimeMS…，宿主不做白名单）。事务 / 会话
+        作用域内自动透传 session（由事务强制接管，``options.session`` 不可覆盖）；
+        统一按读路径解析，``$merge``/``$out`` 写管道请自行开事务。
+        仅支持 Mongo 源（SQL 源抛 NativeCommandError 并指引 execute_raw）。
+        返回 ``{'rows': list}``。
+        """
+        return await datasource.execute_native(source, collection, pipeline, options)
+
     def generate_ddl(self, backend: str, names: list | None = None) -> str:
         """从已注册 schema def 生成指定后端 DDL 文本（纯函数，不连库、不回写；铁律 6）"""
         return ddl.generate(backend, names)
@@ -170,6 +212,7 @@ class Store:
     syncSchema = sync_schema
     buildPipeline = build_pipeline
     executeRaw = execute_raw
+    executeNative = execute_native
     generateDdl = generate_ddl
 
     # ── 其余 API 显式绑定（staticmethod：避免实例化后 self 注入）──
@@ -193,6 +236,8 @@ class Store:
     PermissionError = permission.PermissionError
     # 原生 SQL 入口错误（实例可被 store.RawSqlError 捕获）
     RawSqlError = datasource.RawSqlError
+    # 原生 Mongo 命令入口错误（实例可被 store.NativeCommandError 捕获）
+    NativeCommandError = datasource.NativeCommandError
     # 上下文强制开关（fail-secure：开启后 ctx 缺失报 ERR_NO_CONTEXT，内部调用走 run_as_internal）
     setRequireContext = staticmethod(schema.set_require_context)
     set_require_context = staticmethod(schema.set_require_context)

{storepy-2.4.0 → storepy-2.5.0}/src/py_store/crud/exec.py

@@ -12,6 +12,7 @@ Mongo 走原生驱动，SQL 走 ``translate → exec``。对齐 ``nodejs-store/s
 
 import re
 import time
+from collections.abc import Mapping
 
 from .. import datasource as _datasource
 from ..executors.mongo import exec_mongo as _exec_mongo
@@ -113,8 +114,12 @@ def _call(fn):
 
 async def _exec_on(source, cmd):
     """在指定数据源上执行命令（Mongo 走原生驱动，SQL 走 translate → exec；
-    事务作用域内经 datasource.connection_for 落到事务专用连接）"""
-    connection = _datasource.connection_for(source)
+    事务 / 会话作用域内经 datasource.resolve_connection 落到事务专用连接）"""
+    connection = await _datasource.resolve_connection(source, _datasource.is_write_cmd(cmd))
+    if isinstance(connection, Mapping) and connection.get('kind') == 'mongo':
+        # Mongo 事务视图：db 按命令 namespace 解析，session 透传给驱动
+        db = _datasource.mongo_db(connection['conn'], source, cmd.get('namespace'))
+        return await _exec_mongo(db, cmd, session=connection.get('session'))
     db = _datasource.mongo_db(connection, source, cmd.get('namespace'))
     if db is not None:
         return await _exec_mongo(db, cmd)
@@ -126,6 +131,61 @@ async def _exec(cmd):
     return await _exec_on(cmd.get('source') or _datasource.DEFAULT_SOURCE, cmd)
 
 
+def _sources_of(plan):
+    """从规划结果中提取数据源集合（探针 / 写 / 查 / 删 / mutation 步骤命令）
+
+    ``sources`` 必须由规划结果提取，不得写死 ``default``（多租户路由场景下的
+    源由 core 规划决定）。
+    """
+    out = set()
+    for key in ('needsProbe', 'command', 'findCommand', 'deleteCommand'):
+        cmd = (plan or {}).get(key) or {}
+        if cmd:
+            out.add(cmd.get('source') or _datasource.DEFAULT_SOURCE)
+    for step in (plan or {}).get('steps') or []:
+        cmd = (step or {}).get('command') or {}
+        if cmd:
+            out.add(cmd.get('source') or _datasource.DEFAULT_SOURCE)
+    return out or {_datasource.DEFAULT_SOURCE}
+
+
+def _warn_multi_source(sources):
+    """多源写：无法原子 → 程序化声明 nonAtomic（允许顺序执行，禁止静默）"""
+    listed = sorted(sources)
+    _emit_feedback({
+        'type': 'non_atomic_write',
+        'code': 'nonAtomic',
+        'layer': 'crud',
+        'message': ('本次写调用跨 %d 个数据源（%s）：无法原子，按顺序执行（非原子）'
+                    % (len(listed), ', '.join(listed))),
+        'hint': '把写操作收敛到单源；或在 store.session() 内执行以便跨源写被拒（fail-closed）',
+        'sources': listed,
+    })
+
+
+async def run_atomic(sources, fn):
+    """顶层 API 调用的原子包络：无会话 + 单一源（SQL 或 Mongo）→ 包事务；否则原样执行
+
+    - 会话内：事务边界由会话统一管理，直接执行（不嵌套）；
+    - 单一 SQL 源：包事务（原子）；
+    - 多源：无法原子 → 程序化声明 ``nonAtomic``（反馈通道），再按顺序原样执行；
+    - 单一 Mongo 源：按探测结果包 session 事务或降级声明（见 ``run_in_transaction``）；
+    - 未配置源：按原样执行；
+    - sources 由调用方从「规划结果」中提取（``_sources_of``），命令源与事务源一致。
+    """
+    if _datasource.current_session() is not None:
+        return await fn()
+    uniq = {s or _datasource.DEFAULT_SOURCE for s in sources}
+    if len(uniq) == 1:
+        source = next(iter(uniq))
+        if _datasource.has_connection(source) and (
+                _datasource.is_sql_source(source) or _datasource.is_mongo_source(source)):
+            return await _datasource.run_in_transaction(source, fn)
+    elif len(uniq) > 1:
+        _warn_multi_source(uniq)
+    return await fn()
+
+
 def _substitute(value, resolver):
     """深度替换命令中的占位符（命中 resolver 返回非字符串时替换）"""
     if isinstance(value, str):

{storepy-2.4.0 → storepy-2.5.0}/src/py_store/crud/mutation.py

@@ -1,10 +1,17 @@
 """Mutation / Upsert / 原生聚合 —— 规划步骤序列 → 依序执行 + 父子 _id 占位符回填"""
 
-from .. import datasource as _datasource
 from ..feedback import emit as _emit_feedback
 from ..schema import core as _core
 from ..schema import get as _get_schema
-from .exec import _call, _ctx, _exec, _now_for, resolve_placeholders
+from .exec import (
+    _call,
+    _ctx,
+    _exec,
+    _now_for,
+    _sources_of,
+    resolve_placeholders,
+    run_atomic,
+)
 from .id import _generate_id, _new_id_pool
 
 
@@ -33,12 +40,8 @@ async def _mutation_one(schema_name, data, now, route_override=None):
 
     # 单一 SQL 源 → 步骤序列整体事务化（同连接同事务，任一步失败整体回滚）；
     # Mongo 源 / 跨源步骤按原样顺序执行（非原子边界见 README「事务边界」）
-    sources = {(s['command'].get('source') or _datasource.DEFAULT_SOURCE) for s in plan['steps']}
-    if len(sources) == 1:
-        source = next(iter(sources))
-        if _datasource.is_sql_source(source):
-            return await _datasource.run_in_transaction(source, _run_steps)
-    return await _run_steps()
+    sources = _sources_of(plan)
+    return await run_atomic(sources, _run_steps)
 
 
 async def mutation(schema_name, data, route_override=None):

{storepy-2.4.0 → storepy-2.5.0}/src/py_store/crud/write.py

@@ -1,9 +1,8 @@
 """写路径 —— 单条/批量插入、更新、删除归档、存在性与计数"""
 
-from .. import datasource as _datasource
 from ..schema import core as _core
 from ..schema import get as _get_schema
-from .exec import _call, _ctx, _exec, _now_for
+from .exec import _call, _ctx, _exec, _now_for, _sources_of, run_atomic
 from .id import _generate_id
 
 
@@ -52,12 +51,27 @@ async def update(schema_name, condition, data, options=None, route_override=None
 
     data 的 key 以 '$' 开头 → 原生 MongoDB 操作符（$set/$inc/$unset 等）直接透传。
     否则自动包装为 $set 模式。``route_override`` 可选（多租户路由）。
+
+    「权限探针 + 写」整体纳入同一原子作用域（``run_atomic``）：单一 SQL 源时探针与写
+    同连接同事务，消除二者之间的并发窗口；``now`` 只取一次，两次规划共用（调用级确定性）。
     """
-    out = await _plan_with_probe(lambda found, doc: _call(lambda: _core.plan_update(
-        schema_name, condition, data, options, _now_for(schema_name), _ctx(), found, doc,
-        route_override)))
-    result = await _exec(out['command'])
-    return _call(lambda: _core.apply_write_defaults(schema_name, result)) if result else None
+    now = _now_for(schema_name)
+    ctx = _ctx()
+    first = _call(lambda: _core.plan_update(
+        schema_name, condition, data, options, now, ctx, None, None, route_override))
+    sources = _sources_of(first)
+
+    async def _do():
+        out = first
+        if out.get('needsProbe'):
+            probe_doc = await _exec(out['needsProbe'])
+            out = _call(lambda: _core.plan_update(
+                schema_name, condition, data, options, now, ctx,
+                probe_doc is not None, probe_doc, route_override))
+        result = await _exec(out['command'])
+        return _call(lambda: _core.apply_write_defaults(schema_name, result)) if result else None
+
+    return await run_atomic(sources, _do)
 
 
 async def update_many(schema_name, condition, data, route_override=None):
@@ -88,14 +102,8 @@ async def remove(schema_name, condition, route_override=None):
         result = await _exec(out['deleteCommand'])
         return {'deletedCount': result.deleted_count, 'archivedCount': archived_count}
 
-    sources = {out['deleteCommand'].get('source') or _datasource.DEFAULT_SOURCE}
-    if out.get('findCommand'):
-        sources.add(out['findCommand'].get('source') or _datasource.DEFAULT_SOURCE)
-    if len(sources) == 1:
-        source = next(iter(sources))
-        if _datasource.is_sql_source(source):
-            return await _datasource.run_in_transaction(source, _do_remove)
-    return await _do_remove()
+    sources = _sources_of(out)
+    return await run_atomic(sources, _do_remove)
 
 
 async def exists(schema_name, condition, route_override=None):