storepy 2.4.0__tar.gz → 2.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: storepy
-Version: 2.4.0
+Version: 2.6.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
@@ -85,6 +85,7 @@ from py_store import init, store
 - [Feedback events](#feedback-events)
 - [Schema reference](#schema-reference)
 - [Transactions](#transaction-boundary)
+- [Transactional capabilities](#transactional-capabilities)
 - [FAQ](#faq)
 - [Related projects](#related-projects)
 
@@ -265,6 +266,9 @@ GQL tree queries compile to a single native query per backend — never hand-wri
 - **Permission context** — `ContextVar`-based roles (`super_admin`/`admin`/`guest`/`creator`...), schema/field-level read/write whitelists, automatic owner-condition injection.
 - **Multi-datasource & multi-tenant** — locate a schema by `(source, namespace, collection)`; re-target per request with a route override.
 - **Async-first, Rust core** — built on PyMongo's `AsyncMongoClient` and a shared Rust core with SQL dialects.
+- **Relation predicates in mutations** — filter `update` / `remove` by related-table fields, pushed down to all four backends (previously a silent no-op on MongoDB).
+- **Autoincrement primary keys** — declare `_id` as `{"type": "int", "strategy": "autoincrement"}` for database-assigned integer IDs, with explicit errors where autoincrement is impossible.
+- **Index DDL** — `schema.indexes` compiles to real `CREATE [UNIQUE] INDEX` statements (per backend, byte-identical); the generator still only emits text.
 
 ## GQL syntax
 
@@ -370,11 +374,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 +537,32 @@ 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).
+
+## Transactional capabilities
+
+Capabilities aimed at transactional workloads (orders, inventory — write contention plus
+complex reads). Full details, semantics and the explicit-error list:
+**[doc/transaction-capabilities.md](doc/transaction-capabilities.md)** ·
+[中文](doc/transaction-capabilities.zh-CN.md).
+
+- **Relation predicates in mutations** — `update_many('Inventory', {'product': {'category': 'meat'}}, {'$inc': {'stock': 10}})`: condition keys matching a declared relation become a semi/anti-join, normalized into a preCommand (aggregate fetching `_id`s) plus `_id $in`.
+- **`$group by` one-relation paths** — `by: ['product.category']` compiles to `$lookup`+`$unwind` (Mongo) / `LEFT JOIN` (SQL); `many` paths fail explicitly (fan-out breaks count semantics).
+- **Autoincrement PKs** — `_id: {'type': 'int', 'strategy': 'autoincrement'}`; PG/SQLite read back via `INSERT…RETURNING`, MySQL via last-insert-id; MongoDB and `insert_many` fail explicitly with `AUTOINCREMENT_NOT_SUPPORTED` (no silent ObjectId substitution).
+- **Index DDL** — `schema.indexes` (MongoDB shape) → `CREATE [UNIQUE] INDEX idx_<table>_<cols>` in `ddl.generate`, byte-identical across MySQL/PostgreSQL/SQLite.
 
 ## FAQ
 

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

@@ -45,6 +45,7 @@ from py_store import init, store
 - [Feedback events](#feedback-events)
 - [Schema reference](#schema-reference)
 - [Transactions](#transaction-boundary)
+- [Transactional capabilities](#transactional-capabilities)
 - [FAQ](#faq)
 - [Related projects](#related-projects)
 
@@ -225,6 +226,9 @@ GQL tree queries compile to a single native query per backend — never hand-wri
 - **Permission context** — `ContextVar`-based roles (`super_admin`/`admin`/`guest`/`creator`...), schema/field-level read/write whitelists, automatic owner-condition injection.
 - **Multi-datasource & multi-tenant** — locate a schema by `(source, namespace, collection)`; re-target per request with a route override.
 - **Async-first, Rust core** — built on PyMongo's `AsyncMongoClient` and a shared Rust core with SQL dialects.
+- **Relation predicates in mutations** — filter `update` / `remove` by related-table fields, pushed down to all four backends (previously a silent no-op on MongoDB).
+- **Autoincrement primary keys** — declare `_id` as `{"type": "int", "strategy": "autoincrement"}` for database-assigned integer IDs, with explicit errors where autoincrement is impossible.
+- **Index DDL** — `schema.indexes` compiles to real `CREATE [UNIQUE] INDEX` statements (per backend, byte-identical); the generator still only emits text.
 
 ## GQL syntax
 
@@ -330,11 +334,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 +497,32 @@ 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).
+
+## Transactional capabilities
+
+Capabilities aimed at transactional workloads (orders, inventory — write contention plus
+complex reads). Full details, semantics and the explicit-error list:
+**[doc/transaction-capabilities.md](doc/transaction-capabilities.md)** ·
+[中文](doc/transaction-capabilities.zh-CN.md).
+
+- **Relation predicates in mutations** — `update_many('Inventory', {'product': {'category': 'meat'}}, {'$inc': {'stock': 10}})`: condition keys matching a declared relation become a semi/anti-join, normalized into a preCommand (aggregate fetching `_id`s) plus `_id $in`.
+- **`$group by` one-relation paths** — `by: ['product.category']` compiles to `$lookup`+`$unwind` (Mongo) / `LEFT JOIN` (SQL); `many` paths fail explicitly (fan-out breaks count semantics).
+- **Autoincrement PKs** — `_id: {'type': 'int', 'strategy': 'autoincrement'}`; PG/SQLite read back via `INSERT…RETURNING`, MySQL via last-insert-id; MongoDB and `insert_many` fail explicitly with `AUTOINCREMENT_NOT_SUPPORTED` (no silent ObjectId substitution).
+- **Index DDL** — `schema.indexes` (MongoDB shape) → `CREATE [UNIQUE] INDEX idx_<table>_<cols>` in `ddl.generate`, byte-identical across MySQL/PostgreSQL/SQLite.
 
 ## FAQ
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "storepy"
-version = "2.4.0"
+version = "2.6.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.6.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.6.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.6.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.6.0/src/py_store/crud/write.py

@@ -0,0 +1,176 @@
+"""写路径 —— 单条/批量插入、更新、删除归档、存在性与计数"""
+
+from ..schema import core as _core
+from ..schema import get as _get_schema
+from .exec import _call, _ctx, _exec, _now_for, _sources_of, run_atomic
+from .id import _generate_id
+
+
+async def _plan_with_probe(plan_fn):
+    """creator 写权限探针：先规划，若 needsProbe 则执行探针命令后重入"""
+    out = plan_fn(None, None)
+    if out.get('needsProbe'):
+        probe_doc = await _exec(out['needsProbe'])
+        out = plan_fn(probe_doc is not None, probe_doc)
+    return out
+
+
+async def insert(schema_name, data, route_override=None):
+    """插入一条（``route_override`` 可选：多租户路由 ``{'source', 'namespace'}``）"""
+    s = _get_schema(schema_name)
+    plan = _call(lambda: _core.plan_insert(
+        schema_name, data, _now_for(schema_name), _generate_id(s) if s['idPrefix'] else '', _ctx(),
+        route_override))
+    result = await _exec(plan['command'])
+    returns = plan['returns']
+    # 阶段2：autoincrement 主键 —— 执行器已回读自增值，returns 补 `_id`
+    if isinstance(returns, dict) and not returns.get('_id')             and isinstance(result, dict) and result.get('_id') is not None:
+        returns = {**returns, '_id': result['_id']}
+    return returns
+
+
+async def insert_many(schema_name, docs, route_override=None):
+    """批量插入（带权限检查，自动生成 _id 和时间戳；空数组直接返回空）"""
+    if not isinstance(docs, list) or not docs:
+        return []
+
+    s = _get_schema(schema_name)
+    # 阶段2（no-error-masking）：autoincrement 的批量自增值回读不可靠（MySQL 批量
+    # lastrowid 仅首行、且并发插入会留间隙）→ 显式报错，不静默产出错误 _id
+    id_fdef = (s.get('fields') or {}).get('_id') or {}
+    if id_fdef.get('strategy') == 'autoincrement' and any(not (d or {}).get('_id') for d in docs):
+        raise ValueError(
+            'AUTOINCREMENT_NOT_SUPPORTED: insert_many 不支持 autoincrement schema'
+            '（批量自增值回读不可靠）；请逐条 insert 或显式提供 _id')
+    plan = _call(lambda: _core.plan_insert_many(
+        schema_name,
+        docs,
+        _now_for(schema_name),
+        # core 按需消费（仅无 _id 的文档取用），多备无害
+        [_generate_id(s) if s['idPrefix'] else '' for _ in docs],
+        _ctx(),
+        route_override,
+    ))
+    if plan.get('command'):
+        await _exec(plan['command'])
+    return plan['returns']
+
+
+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`` 只取一次，两次规划共用（调用级确定性）。
+    """
+    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 _exec_with_pre(command):
+    """执行带 ``preCommand`` 的命令（阶段1：mutation 关系谓词归一）。
+
+    preCommand（aggregate 取命中 `_id`）先行执行，把结果 `_id` 列表回填进主命令
+    filter 的 `_id.$in` 占位（core 规划注入 ``"__REL_PRED_IDS__"``）。空集 → `$in: []`，
+    各后端语义一致 = 不命中任何行。同批可传 ``extra_targets``：其他携带同一占位的
+    命令（如 remove 的归档 findCommand）一并回填，避免二次执行 preCommand。"""
+    pre = command.get('preCommand')
+    if not pre:
+        return await _exec(command)
+    ids = []
+    for doc in await _exec(pre):
+        if isinstance(doc, dict) and '_id' in doc:
+            ids.append(doc['_id'])
+    return await _fill_pre_ids(command, ids)
+
+
+def _fill_pre_ids(command, ids):
+    """把 preCommand 取得的 `_id` 列表回填进命令 filter 的 `$in` 占位（递归查找后执行）。
+
+    core 注入的占位可能位于 `$and` 数组内（改写条件已有其他键时），故递归遍历。"""
+    main = {k: v for k, v in command.items() if k != 'preCommand'}
+
+    def _walk(node):
+        if isinstance(node, dict):
+            for k, v in list(node.items()):
+                if isinstance(v, dict) and v.get('$in') == '__REL_PRED_IDS__':
+                    node[k] = {'$in': list(ids)}
+                else:
+                    _walk(v)
+        elif isinstance(node, list):
+            for it in node:
+                _walk(it)
+
+    if 'filter' in main:
+        _walk(main['filter'])
+    return _exec(main)
+
+
+async def update_many(schema_name, condition, data, route_override=None):
+    """批量更新（支持原生操作符）"""
+    out = _call(lambda: _core.plan_update_many(
+        schema_name, condition, data, _now_for(schema_name), _ctx(), route_override))
+    result = await _exec_with_pre(out['command'])
+    return {'modifiedCount': result.modified_count}
+
+
+async def remove(schema_name, condition, route_override=None):
+    """删除 —— 原表数据先归档到对应 `_deleted` 附表（附 deletedAt），再物理删除原表数据。
+    归档命令带 ``upsertById``（幂等），重试不再因 _id 冲突整批失败；单一 SQL 源时
+    归档+删除整体事务化（Mongo / 跨源按顺序执行，非原子边界见 README「事务边界」）"""
+    out = await _plan_with_probe(lambda found, doc: _call(lambda: _core.plan_remove(
+        schema_name, condition, _ctx(), found, doc, route_override)))
+
+    async def _do_remove():
+        archived_count = 0
+        # 关系谓词：先执行 deleteCommand.preCommand 取命中 _id（归档 find 与删除共用同一列表）
+        pre = (out.get('deleteCommand') or {}).get('preCommand')
+        ids = None
+        if pre:
+            ids = [d['_id'] for d in await _exec(pre) if isinstance(d, dict) and '_id' in d]
+        if out.get('findCommand'):
+            find_cmd = out['findCommand']
+            docs = await (_fill_pre_ids(find_cmd, ids) if ids is not None else _exec(find_cmd))
+            if docs:
+                arch = _call(lambda: _core.plan_archive_docs(
+                    schema_name, docs, _now_for(schema_name), route_override))
+                await _exec(arch['command'])
+                archived_count = len(docs)
+
+        result = await (_fill_pre_ids(out['deleteCommand'], ids)
+                        if ids is not None else _exec(out['deleteCommand']))
+        return {'deletedCount': result.deleted_count, 'archivedCount': archived_count}
+
+    sources = _sources_of(out)
+    return await run_atomic(sources, _do_remove)
+
+
+async def exists(schema_name, condition, route_override=None):
+    """判断是否存在"""
+    cmd = _call(lambda: _core.plan_exists(schema_name, condition, route_override))
+    doc = await _exec(cmd)
+    return doc is not None
+
+
+async def count(schema_name, filter=None, route_override=None):
+    """统计符合条件的文档数量"""
+    cmd = _call(lambda: _core.plan_count(schema_name, filter, _ctx(), route_override))
+    return await _exec(cmd)