storepy 2.0.4__tar.gz → 2.3.1__tar.gz

{storepy-2.0.4/src/storepy.egg-info → storepy-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: storepy
-Version: 2.0.4
+Version: 2.3.1
 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
@@ -33,6 +33,7 @@ Provides-Extra: sqlite
 Requires-Dist: aiosqlite>=0.19; extra == "sqlite"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
 Requires-Dist: ruff>=0.16; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Dynamic: license-file
@@ -147,7 +148,7 @@ Typical concrete scenarios (see [`doc/use-cases/`](doc/use-cases/) for full walk
 
 Being explicit about the boundary saves you time:
 
-- **You want a full ORM with a migration engine (Alembic, Django migrations).** `py-store` is a *data layer*, not a migration tool. It can **read** a SQL backend's physical structure (`sync_schema` → introspection) but it never writes DDL back.
+- **You want a full ORM with a migration engine (Alembic, Django migrations).** `py-store` is a *data layer*, not a migration tool. It can **read** a SQL backend's physical structure (`sync_schema` → introspection) but it never writes DDL back. There is an optional `generate_ddl()` that renders `CREATE TABLE` text from your registered schemas — pure text, it never connects to or writes to the database.
 - **You want a Pydantic-model-centric ORM.** Schemas here are runtime JSON dicts, giving you cross-language parity (the same schema runs in Python and Node.js) rather than Pydantic type validation.
 - **You only ever use one database and rarely join.** A plain driver (or a single-database ODM/ORM) will be simpler.
 - **You need raw aggregation escape hatches.** `$pipeline` passthrough and `store.aggregate()` were deliberately removed. Use `$condition` / `$group` / `$having` / relations; anything that cannot be safely translated fails **explicitly** rather than silently.
@@ -165,7 +166,7 @@ General positioning, not a benchmark — always verify against each tool's curre
 | Built-in role / field-level RBAC + owner injection | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ (permissions are app-level) |
 | Read-time computed columns (sync / async / relation-agg) | ✅ | ➖ (hybrid properties) | ➖ | ➖ | ➖ | ➖ |
 | Soft-delete archive table auto-provisioned | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ |
-| Migration / DDL engine | ➖ (introspection read-only) | ✅ (Alembic) | ➖ | ✅ (Aerich) | ✅ (Alembic) | ✅ |
+| Migration / DDL engine | ➖ (introspection read-only; optional `generate_ddl` text) | ✅ (Alembic) | ➖ | ✅ (Aerich) | ✅ (Alembic) | ✅ |
 | Framework coupling | none (asyncio) | none | none | none | none | Django |
 | Shared native core across Python & Node | ✅ (Rust `rust-store`) | ➖ | ➖ | ➖ | ➖ | ➖ |
 
@@ -175,7 +176,7 @@ Positioning only, based on those projects' public documentation at the time of w
 
 - **vs SQLAlchemy / SQLModel / Django ORM** — all SQL-only and model-class-centric: they do not target MongoDB, and none of them ships schema-declared role/field access control or read-time computed columns. `py-store` compiles one GQL to native MongoDB aggregation or to parameterized SQL.
 - **vs Beanie / Motor** — MongoDB-only. `py-store` uses the same MongoDB-flavoured query style but the identical query also runs on MySQL, SQLite and PostgreSQL.
-- **vs Tortoise ORM / pyloquent** — async Python ORMs over SQL backends, with model classes and (in Tortoise's case) a migration tool. `py-store` has no migration engine — introspection reads physical structure only — and describes models as plain dicts, which is exactly what makes a schema portable to the Node.js host.
+- **vs Tortoise ORM / pyloquent** — async Python ORMs over SQL backends, with model classes and (in Tortoise's case) a migration tool. `py-store` has no migration engine — introspection only reads physical structure, and `generate_ddl()` only *renders* `CREATE TABLE` text without touching the database — and describes models as plain dicts, which is exactly what makes a schema portable to the Node.js host.
 - **vs `nodejs-store`** — the same engine and the same GQL, in JavaScript. Use whichever host matches your service; schemas and query semantics are interchangeable.
 
 Short version: use an ORM when you want **model classes, Pydantic validation and migrations**; use `py-store` when you want **one runtime schema + one query dialect spanning MongoDB and SQL**, with RBAC and computed columns built in.
@@ -356,6 +357,39 @@ Notes:
 - `update_many` / `remove` with an **empty condition** (`{}`, `None`, `{"$and": []}`) is rejected outright — it never falls through to a full-table write.
 - Snake-case aliases available: `query_one`, `insert_many`, `update_many`, `build_pipeline`, ...
 
+### Transactions and raw SQL
+
+```python
+async def transfer():
+    rows = await store.execute_raw(
+        "default", "SELECT * FROM accounts WHERE _id = ? FOR UPDATE", [acc_id])
+    await store.execute_raw(
+        "default", "UPDATE accounts SET balance = ? WHERE _id = ?", [new_balance, acc_id],
+        is_write=True)
+
+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.
+- **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`.
+
+### DDL generation
+
+```python
+sql = store.generate_ddl("mysql")                       # every registered model
+sql = store.generate_ddl("postgres", ["Course", "CourseDeleted"])
+```
+
+`store.generate_ddl(backend, names=None)` maps one registered schema def to one `CREATE TABLE` — the inverse of `sync_schema()`, which only *reads*. The generator is **pure text**: it never connects to, or writes to, the database (iron rule 6 still holds).
+
+- Only scalar fields become columns; `object` / `array` fields do not.
+- Every table gets the `__present` sentinel column; `timestamps` models also get `createdAt` / `updatedAt`; the `<collection>_deleted` archive table is generated like any other registered def.
+- The `<Name>Deleted` archive def is **derived by the Rust core when the model is registered**; the Python host only mirrors it (`collection` `<c>_deleted`, the `deletedAt` field, empty `idPrefix`) and never re-registers it into the core. So `schema.list()` and `generate_ddl()` contain each archive table exactly once; if a duplicate ever appears (upstream regression), they deduplicate and emit a `schemaDuplicateName` / `ddlDuplicateTable` feedback event instead of silently emitting duplicate `CREATE TABLE`s.
+- No `CREATE INDEX` is emitted — SQL backends keep indexes as metadata only.
+- MySQL `__present` is `VARCHAR(255)`; a schema whose present-token string would overflow emits a `ddlPresentOverflow` feedback event rather than failing silently.
+
 ## Multi-datasource connections
 
 Every schema is located by the triple `(source, namespace, collection)` — the triple must be
@@ -513,7 +547,7 @@ Every registered model automatically gets a `<Model>Deleted` archive collection/
 Yes. Bind a schema to `(source, namespace, collection)` and pass a `{"source", "namespace"}` route override per request. Treat `route_override` as trusted server-side input only.
 
 **Does it run migrations?**
-No. `sync_schema()` only *reads* physical structure via introspection (introspect → merge overlay → register). Schema changes / DDL are your migration tool's job (Alembic, etc.).
+No. `sync_schema()` only *reads* physical structure via introspection (introspect → merge overlay → register). Schema changes / DDL are your migration tool's job (Alembic, etc.). If you want a starting point, `store.generate_ddl(backend)` renders `CREATE TABLE` text from the registered schemas — but it is pure text generation: it never runs or writes DDL.
 
 **Can I see the generated query without running it?**
 Yes — `store.build_pipeline(gql, params)` returns the compiled plan with no execution and no permission/compute application.

{storepy-2.0.4 → storepy-2.3.1}/README.md

@@ -108,7 +108,7 @@ Typical concrete scenarios (see [`doc/use-cases/`](doc/use-cases/) for full walk
 
 Being explicit about the boundary saves you time:
 
-- **You want a full ORM with a migration engine (Alembic, Django migrations).** `py-store` is a *data layer*, not a migration tool. It can **read** a SQL backend's physical structure (`sync_schema` → introspection) but it never writes DDL back.
+- **You want a full ORM with a migration engine (Alembic, Django migrations).** `py-store` is a *data layer*, not a migration tool. It can **read** a SQL backend's physical structure (`sync_schema` → introspection) but it never writes DDL back. There is an optional `generate_ddl()` that renders `CREATE TABLE` text from your registered schemas — pure text, it never connects to or writes to the database.
 - **You want a Pydantic-model-centric ORM.** Schemas here are runtime JSON dicts, giving you cross-language parity (the same schema runs in Python and Node.js) rather than Pydantic type validation.
 - **You only ever use one database and rarely join.** A plain driver (or a single-database ODM/ORM) will be simpler.
 - **You need raw aggregation escape hatches.** `$pipeline` passthrough and `store.aggregate()` were deliberately removed. Use `$condition` / `$group` / `$having` / relations; anything that cannot be safely translated fails **explicitly** rather than silently.
@@ -126,7 +126,7 @@ General positioning, not a benchmark — always verify against each tool's curre
 | Built-in role / field-level RBAC + owner injection | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ (permissions are app-level) |
 | Read-time computed columns (sync / async / relation-agg) | ✅ | ➖ (hybrid properties) | ➖ | ➖ | ➖ | ➖ |
 | Soft-delete archive table auto-provisioned | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ |
-| Migration / DDL engine | ➖ (introspection read-only) | ✅ (Alembic) | ➖ | ✅ (Aerich) | ✅ (Alembic) | ✅ |
+| Migration / DDL engine | ➖ (introspection read-only; optional `generate_ddl` text) | ✅ (Alembic) | ➖ | ✅ (Aerich) | ✅ (Alembic) | ✅ |
 | Framework coupling | none (asyncio) | none | none | none | none | Django |
 | Shared native core across Python & Node | ✅ (Rust `rust-store`) | ➖ | ➖ | ➖ | ➖ | ➖ |
 
@@ -136,7 +136,7 @@ Positioning only, based on those projects' public documentation at the time of w
 
 - **vs SQLAlchemy / SQLModel / Django ORM** — all SQL-only and model-class-centric: they do not target MongoDB, and none of them ships schema-declared role/field access control or read-time computed columns. `py-store` compiles one GQL to native MongoDB aggregation or to parameterized SQL.
 - **vs Beanie / Motor** — MongoDB-only. `py-store` uses the same MongoDB-flavoured query style but the identical query also runs on MySQL, SQLite and PostgreSQL.
-- **vs Tortoise ORM / pyloquent** — async Python ORMs over SQL backends, with model classes and (in Tortoise's case) a migration tool. `py-store` has no migration engine — introspection reads physical structure only — and describes models as plain dicts, which is exactly what makes a schema portable to the Node.js host.
+- **vs Tortoise ORM / pyloquent** — async Python ORMs over SQL backends, with model classes and (in Tortoise's case) a migration tool. `py-store` has no migration engine — introspection only reads physical structure, and `generate_ddl()` only *renders* `CREATE TABLE` text without touching the database — and describes models as plain dicts, which is exactly what makes a schema portable to the Node.js host.
 - **vs `nodejs-store`** — the same engine and the same GQL, in JavaScript. Use whichever host matches your service; schemas and query semantics are interchangeable.
 
 Short version: use an ORM when you want **model classes, Pydantic validation and migrations**; use `py-store` when you want **one runtime schema + one query dialect spanning MongoDB and SQL**, with RBAC and computed columns built in.
@@ -317,6 +317,39 @@ Notes:
 - `update_many` / `remove` with an **empty condition** (`{}`, `None`, `{"$and": []}`) is rejected outright — it never falls through to a full-table write.
 - Snake-case aliases available: `query_one`, `insert_many`, `update_many`, `build_pipeline`, ...
 
+### Transactions and raw SQL
+
+```python
+async def transfer():
+    rows = await store.execute_raw(
+        "default", "SELECT * FROM accounts WHERE _id = ? FOR UPDATE", [acc_id])
+    await store.execute_raw(
+        "default", "UPDATE accounts SET balance = ? WHERE _id = ?", [new_balance, acc_id],
+        is_write=True)
+
+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.
+- **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`.
+
+### DDL generation
+
+```python
+sql = store.generate_ddl("mysql")                       # every registered model
+sql = store.generate_ddl("postgres", ["Course", "CourseDeleted"])
+```
+
+`store.generate_ddl(backend, names=None)` maps one registered schema def to one `CREATE TABLE` — the inverse of `sync_schema()`, which only *reads*. The generator is **pure text**: it never connects to, or writes to, the database (iron rule 6 still holds).
+
+- Only scalar fields become columns; `object` / `array` fields do not.
+- Every table gets the `__present` sentinel column; `timestamps` models also get `createdAt` / `updatedAt`; the `<collection>_deleted` archive table is generated like any other registered def.
+- The `<Name>Deleted` archive def is **derived by the Rust core when the model is registered**; the Python host only mirrors it (`collection` `<c>_deleted`, the `deletedAt` field, empty `idPrefix`) and never re-registers it into the core. So `schema.list()` and `generate_ddl()` contain each archive table exactly once; if a duplicate ever appears (upstream regression), they deduplicate and emit a `schemaDuplicateName` / `ddlDuplicateTable` feedback event instead of silently emitting duplicate `CREATE TABLE`s.
+- No `CREATE INDEX` is emitted — SQL backends keep indexes as metadata only.
+- MySQL `__present` is `VARCHAR(255)`; a schema whose present-token string would overflow emits a `ddlPresentOverflow` feedback event rather than failing silently.
+
 ## Multi-datasource connections
 
 Every schema is located by the triple `(source, namespace, collection)` — the triple must be
@@ -474,7 +507,7 @@ Every registered model automatically gets a `<Model>Deleted` archive collection/
 Yes. Bind a schema to `(source, namespace, collection)` and pass a `{"source", "namespace"}` route override per request. Treat `route_override` as trusted server-side input only.
 
 **Does it run migrations?**
-No. `sync_schema()` only *reads* physical structure via introspection (introspect → merge overlay → register). Schema changes / DDL are your migration tool's job (Alembic, etc.).
+No. `sync_schema()` only *reads* physical structure via introspection (introspect → merge overlay → register). Schema changes / DDL are your migration tool's job (Alembic, etc.). If you want a starting point, `store.generate_ddl(backend)` renders `CREATE TABLE` text from the registered schemas — but it is pure text generation: it never runs or writes DDL.
 
 **Can I see the generated query without running it?**
 Yes — `store.build_pipeline(gql, params)` returns the compiled plan with no execution and no permission/compute application.

{storepy-2.0.4 → storepy-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "storepy"
-version = "2.0.4"
+version = "2.3.1"
 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"
@@ -45,7 +45,7 @@ classifiers = [
 mysql = ["asyncmy>=0.2.9"]
 postgres = ["asyncpg>=0.29"]
 sqlite = ["aiosqlite>=0.19"]
-dev = ["pytest>=8", "ruff>=0.16", "mypy>=1.0"]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.16", "mypy>=1.0"]
 
 [project.urls]
 Homepage = "https://github.com/coenddt/py-store"
@@ -83,3 +83,15 @@ python_version = "3.10"
 # 宽松起步：py_store 为动态薄适配层，注解覆盖不足，先只挡「导入失败/明显类型矛盾」
 ignore_missing_imports = true
 check_untyped_defs = true
+
+# ── 覆盖率（门禁口径：语句 ≥90%，见 .github/workflows/ci.yml；分支单独出具） ──
+[tool.coverage.run]
+source = ["py_store"]
+relative_files = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+]

{storepy-2.0.4 → storepy-2.3.1}/src/py_store/__init__.py

@@ -20,6 +20,7 @@ py-store — 轻量多后端数据层（Python 版，Rust 单核心架构；支
 """
 
 from collections.abc import Mapping
+from contextlib import contextmanager
 from typing import Any
 
 from pymongo.errors import PyMongoError
@@ -27,6 +28,7 @@ from pymongo.errors import PyMongoError
 from . import (
     crud,
     datasource,
+    ddl,
     feedback,
     permission,
     schema,
@@ -37,6 +39,7 @@ from . import (
 from . import (
     introspect as introspect,
 )
+from .datasource import RawSqlError as RawSqlError
 from .sync import sync_schema
 
 
@@ -46,6 +49,21 @@ def _build_pipeline(gql, params=None):
         gql, params if params is not None else {}, permission.get_context())
 
 
+@contextmanager
+def text2query():
+    """以 text2query 档执行（功能收缩 + 硬限制），退出恢复原档位。
+
+    AI 问数链路入口；与 ``permission.scoped_roles`` 同构（token-set/reset，嵌套安全）。
+    进入档位即等效强制携带用户上下文（core `ensure_profile_ctx`，见执行文档 §4.2）。
+    """
+    prev = schema.get_profile()
+    schema.set_profile('text2query')
+    try:
+        yield
+    finally:
+        schema.set_profile(prev)
+
+
 class Store:
     """以属性方式访问各 API（**全显式类方法，无动态查找**）
 
@@ -120,6 +138,29 @@ class Store:
     def build_pipeline(self, gql: str, params: dict | None = None) -> dict[str, Any]:
         return _build_pipeline(gql, params)
 
+    # ── 事务 + 原生 SQL（复用 datasource.run_in_transaction；见 README「事务边界」）──
+    async def transaction(self, source: str, fn) -> Any:
+        """事务作用域：单 SQL 源「同连接 + 同事务」执行 fn（复用 run_in_transaction）
+
+        fn 内 execute_raw / CRUD 均落到该源的事务连接（commit/rollback 一体）；
+        Mongo 源或执行器未实现事务时按原样执行（跨源无法原子），绝不静默假装已事务化。
+        单源场景 source 传 ``'default'``。
+        """
+        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（事务内可用；占位符按各后端原生风格）
+
+        mysql/sqlite 用 ``?``，postgres 用 ``$1..$n``；仅支持 SQL 源（Mongo 源抛
+        RawSqlError）。``is_write=False`` 取行（rows），``True`` 取影响行数（affectedRows）。
+        """
+        return await datasource.execute_raw(source, sql, params, is_write)
+
+    def generate_ddl(self, backend: str, names: list | None = None) -> str:
+        """从已注册 schema def 生成指定后端 DDL 文本（纯函数，不连库、不回写；铁律 6）"""
+        return ddl.generate(backend, names)
+
     # ── 驼峰别名（与上方同名蛇形方法为**同一实现**，仅命名差异）──
     queryOne = query_one
     queryWithCount = query_with_count
@@ -128,6 +169,8 @@ class Store:
     updateMany = update_many
     syncSchema = sync_schema
     buildPipeline = build_pipeline
+    executeRaw = execute_raw
+    generateDdl = generate_ddl
 
     # ── 其余 API 显式绑定（staticmethod：避免实例化后 self 注入）──
     # Schema 管理
@@ -148,11 +191,23 @@ class Store:
     run_as_internal = staticmethod(permission.run_as_internal)
     # 自定义权限错误（实例可被 store.PermissionError 捕获）
     PermissionError = permission.PermissionError
+    # 原生 SQL 入口错误（实例可被 store.RawSqlError 捕获）
+    RawSqlError = datasource.RawSqlError
     # 上下文强制开关（fail-secure：开启后 ctx 缺失报 ERR_NO_CONTEXT，内部调用走 run_as_internal）
     setRequireContext = staticmethod(schema.set_require_context)
     set_require_context = staticmethod(schema.set_require_context)
     requireContext = staticmethod(schema.require_context)
     require_context = staticmethod(schema.require_context)
+    # 查询档位（判决唯一在 core）：standard 默认放开 / text2query 功能收缩
+    # 进入档即等效强制 ctx；未知档由 core 抛 ValueError 上抛（禁静默回落默认档）
+    setProfile = staticmethod(schema.set_profile)
+    set_profile = staticmethod(schema.set_profile)
+    getProfile = staticmethod(schema.get_profile)
+    get_profile = staticmethod(schema.get_profile)
+    # 档位拒绝错误（实例可被 store.ProfileViolation 捕获；权限错误另见 PermissionError）
+    ProfileViolation = crud.ProfileViolation
+    # text2query 便捷上下文（进入设档、退出恢复；同 scoped_roles 的 token-set/reset）
+    text2query = staticmethod(text2query)
     # 反馈事件通道（兜底/降级/拦截的统一出口，接入自动反馈闭环）
     setFeedbackSink = staticmethod(feedback.set_sink)
     set_feedback_sink = staticmethod(feedback.set_sink)
@@ -200,8 +255,17 @@ async def _create_indexes_if_needed():
 
                 await coll.create_index(list(keys.items()), **final_options)
             except PyMongoError as e:
-                import sys
-                print(f'[py-store] 创建索引失败 {s["collection"]}: {e}', file=sys.stderr)
+                # 索引创建失败不阻塞 init（辅助动作），但必须走统一反馈通道：
+                # 无 sink 时由 feedback 默认落 stderr（不双份打印），宿主可 set_sink 接管。
+                # 对齐 nodejs-store/src/index.js（评审项 R7-m1）。
+                feedback.emit({
+                    'type': 'index_create_failed',
+                    'code': 'indexCreateFailed',
+                    'layer': 'host',
+                    'message': f'创建索引失败 {s["collection"]}: {e}',
+                    'hint': ('检查该集合的索引定义与连接权限；'
+                             '索引缺失不影响读写，相关查询将退化为全表扫描'),
+                })
 
 
 async def init(connections):

{storepy-2.0.4 → storepy-2.3.1}/src/py_store/crud/__init__.py

@@ -7,12 +7,13 @@ CRUD 包 —— 薄 Host 适配层（对齐 nodejs-store/src/crud.js 的分工
   - 写入时不补默认值（DB 存最少数据）；读取时由 core 补默认值 + 计算列
 """
 
-from .exec import _get_db, set_connections, set_db
+from .exec import ProfileViolation, _get_db, set_connections, set_db
 from .mutation import mutation, upsert
 from .query import query, query_federated, query_one, query_with_count
 from .write import count, exists, insert, insert_many, remove, update, update_many
 
 __all__ = [
+    'ProfileViolation',
     '_get_db',
     'count',
     'exists',

{storepy-2.0.4 → storepy-2.3.1}/src/py_store/crud/exec.py

@@ -15,6 +15,7 @@ import time
 
 from .. import datasource as _datasource
 from ..executors.mongo import exec_mongo as _exec_mongo
+from ..feedback import emit as _emit_feedback
 from ..permission import PermissionError, get_context
 from ..schema import get as _schema_get
 
@@ -26,6 +27,31 @@ _STEP_PH = re.compile(r'^\{\{step\.(\d+)\._id\}\}$')
 # 可自由调整，映射不随文案漂移而静默失效。构造 PermissionError 时剥离前缀。
 _PERM_PREFIX = 'ERR_PERMISSION:'
 
+# 档位类错误识别：core text2query 档门禁统一携带 `ERR_TEXT2QUERY:` 稳定前缀
+# （见 core `command/mod.rs::ERR_TEXT2QUERY`），同上按前缀映射。命中即 emit
+# 反馈事件 `profile_blocked`（自动反馈原则：允许拦截，禁止静默）。
+_PROFILE_PREFIX = 'ERR_TEXT2QUERY:'
+
+# 从 core 文案 `... [$feature]（功能收缩）` 中提取门禁项名；无 `[..]` 时留白（None），
+# 不伪造 feature —— 缺值必须显式暴露（禁静默兜底）。
+_FEATURE_RE = re.compile(r'\[(.+?)\]')
+
+# 档位拦截反馈的统一提示（反馈事件契约 §4.6 的一部分；单点定义防文案漂移）
+_PROFILE_HINT = ('上游（LLM 产出的 GQL / 调用方入参）越界；'
+                 'text2query 档白名单见 SKILL.md §后端无关性与边界')
+
+
+class ProfileViolation(Exception):
+    """档位（profile）拒绝：text2query 档违反功能收缩 / 硬限制
+
+    与权限错误（``PermissionError``，403）区分：档位拒绝是**调用方合约违反**（400），
+    非授权问题（见执行文档 §4.4）。实参 ``status`` 供上层（HTTP 网关等）映射响应码。
+    """
+
+    def __init__(self, message, status=400):
+        super().__init__(message)
+        self.status = status
+
 
 def set_db(db):
     """单库简写：等价于 ``set_connections({'default': db})``"""
@@ -53,13 +79,33 @@ def _ctx():
 
 
 def _call(fn):
-    """绑定层调用包装：权限类错误（``ERR_PERMISSION:`` 前缀）映射为 PermissionError"""
+    """绑定层调用包装：
+
+      - 权限类错误（``ERR_PERMISSION:`` 前缀）→ ``PermissionError``
+      - 档位类错误（``ERR_TEXT2QUERY:`` 前缀）→ emit ``profile_blocked`` 反馈 + ``ProfileViolation``
+
+    按前缀映射而非具体文案（core 文案可自由调整，映射不随文案漂移而静默失效）。
+    其余异常原样上抛（不吞错）。
+    """
     try:
         return fn()
     except Exception as e:
         msg = str(e)
         if msg.startswith(_PERM_PREFIX):
             raise PermissionError(msg[len(_PERM_PREFIX):]) from e
+        if msg.startswith(_PROFILE_PREFIX):
+            detail = msg[len(_PROFILE_PREFIX):]
+            m = _FEATURE_RE.search(detail)
+            _emit_feedback({
+                'type': 'profile_blocked',
+                'code': 'profileBlocked',
+                'layer': 'core',
+                'profile': 'text2query',
+                'feature': m.group(1) if m else None,
+                'message': detail,
+                'hint': _PROFILE_HINT,
+            })
+            raise ProfileViolation(detail) from e
         raise
 
 

{storepy-2.0.4 → storepy-2.3.1}/src/py_store/crud/query.py

@@ -6,8 +6,39 @@ import inspect
 
 from ..feedback import emit as _emit_feedback
 from ..schema import core as _core
-from ..schema import get_async_fn
-from .exec import _call, _ctx, _exec, _exec_on, resolve_placeholders
+from ..schema import get_async_fn, get_profile
+from .exec import (
+    _PROFILE_HINT,
+    ProfileViolation,
+    _call,
+    _ctx,
+    _exec,
+    _exec_on,
+    resolve_placeholders,
+)
+
+
+def _guard_route_override(route_override):
+    """Host 兜底：text2query 档禁用 ``route_override``（受信参数，禁 AI 侧指定）
+
+    判决唯一在 core（执行文档 §4.2 ⑤：各 ``plan_query*`` 入口已判并 Err）；此为
+    第二层防护——即使 core 判决被绕过，Host 也不放行受信参数（CWE-639）。命中即
+    emit ``profile_blocked``，``layer='host'`` 本身即反馈：core 层未拦住，须回溯加固
+    （自动反馈原则：允许拦截，禁止静默）。
+    """
+    if route_override is None or get_profile() != 'text2query':
+        return
+    detail = 'text2query 档禁用 route_override（受信参数，禁 AI 侧指定）'
+    _emit_feedback({
+        'type': 'profile_blocked',
+        'code': 'profileBlocked',
+        'layer': 'host',
+        'profile': 'text2query',
+        'feature': 'route_override',
+        'message': detail,
+        'hint': _PROFILE_HINT,
+    })
+    raise ProfileViolation(detail)
 
 
 async def _run_query_plan(plan):
@@ -50,6 +81,7 @@ async def query(gql, params=None, route_override=None):
     权限/计算列仍按结构 schema 判定（见 multi-datasource-routing-plan.md §6）。
     注意：``route_override`` 为**受信服务端参数**，禁止透传用户输入（否则可被用于跨源路由，CWE-639）。
     """
+    _guard_route_override(route_override)
     plan = _call(lambda: _core.plan_query(
         gql, params if params is not None else {}, _ctx(), route_override))
     return await _finalize(plan, await _run_query_plan(plan))
@@ -61,6 +93,7 @@ async def query_one(gql, params=None, route_override=None):
     走 core ``plan_query_one``：用户未显式 ``$limit`` 时强制下推 ``$limit(1)``，
     大集合不再全量取回后取首条（对齐 PyMongo ``find_one`` 的 limit-1 语义）。
     """
+    _guard_route_override(route_override)
     plan = _call(lambda: _core.plan_query_one(
         gql, params if params is not None else {}, _ctx(), route_override))
     items = await _finalize(plan, await _run_query_plan(plan))
@@ -118,6 +151,7 @@ async def query_with_count(gql, params=None, route_override=None):
       2. 传统 $skip/$limit — 从 GQL 参数推导 page/pageSize
     pageSize 上限 5000，防止拖库。
     """
+    _guard_route_override(route_override)
     plan = _call(lambda: _core.plan_query_with_count(
         gql, params if params is not None else {}, _ctx(), None, route_override))
     items = await _finalize(plan, await _run_query_plan(plan))

{storepy-2.0.4 → storepy-2.3.1}/src/py_store/datasource.py

@@ -239,3 +239,30 @@ async def exec_sql(source, connection, cmd):
             f'SQL 数据源 {source}({_kind_of(connection)}) 的执行器未接入（见执行文档 Phase 4）')
     out = await exec_fn(plan)
     return executors.shape_result(cmd, out)
+
+
+class RawSqlError(RuntimeError):
+    """原生 SQL 入口的显式错误（非 SQL 源 / 执行器未接入）"""
+
+
+async def execute_raw(source, sql, params=None, is_write=False):
+    """
+    在指定 SQL 源上执行原生 SQL（Host 层逃生口，绕开 core 的 dialect_translate）
+
+      - 事务作用域内经 ``connection_for`` 落到事务专用连接 → 支持 SELECT ... FOR UPDATE；
+      - 占位符沿用各后端原生风格（mysql/sqlite 用 ``?``，postgres 用 ``$1..$n``）；
+      - 仅支持 SQL 源；Mongo 源显式报错（绝不静默）；
+      - ``is_write=False`` 视为读（取行）；``True`` 视为写（取影响行数）；
+      - 返回 ``{'rows': list|None, 'affectedRows': int}``。
+    """
+    conn = connection_for(source)
+    if not is_sql(conn):
+        raise RawSqlError(
+            f'数据源 {source} 不是 SQL 源（原生 SQL 入口仅支持 mysql/postgres/sqlite）')
+    exec_fn = _exec_of(conn)
+    if not callable(exec_fn):
+        raise RawSqlError(
+            f'SQL 数据源 {source}({_kind_of(conn)}) 的执行器未接入')
+    stmt = {'text': sql, 'params': list(params or []), 'isWrite': bool(is_write)}
+    out = await exec_fn({'stmts': [stmt]})
+    return {'rows': out.get('rows'), 'affectedRows': int(out.get('affectedRows') or 0)}