storepy 2.6.0__tar.gz → 2.7.0__tar.gz

{storepy-2.6.0 → storepy-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: storepy
-Version: 2.6.0
+Version: 2.7.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
@@ -563,6 +563,72 @@ complex reads). Full details, semantics and the explicit-error list:
 - **`$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.
+- **Declarative migration** — `ddl.diff_defs(old, new)` + `ddl.generate_migration(backend, old, new)`: whitelist-only (add table/column/index, type widening), per-dialect SQL, pure functions; destructive changes fail with `MIGRATION_UNSUPPORTED`.
+
+## Workflow orchestration (first batch)
+
+Express "orchestration of multi-step data operations" as data: a workflow definition (defn) is pure
+JSON isomorphic to a schema defn, and each run is persisted to the built-in schema `__workflowRun`
+(queryable with plain GQL — zero new observability endpoints). Execution generalizes the existing
+mutation step-sequence mechanism: linear steps + per-step `when` guards + fail-fast. The engine
+lives in the host layer (`py_store/workflow.py`), core unchanged; aligned with
+`nodejs-store/src/workflow.js` (byte-identical outputs guarded by parity anchor tests).
+
+```python
+from py_store import workflow
+
+workflow.register({
+    'name': 'placeOrder',
+    'run': ['admin', 'ops'],              # three-tier whitelists read/write/run (run falls back to write)
+    'steps': [
+        {'op': 'query', 'as': 'inv',
+         'gql': 'Inventory($condition:@c0){_id, stock}',
+         'params': {'c0': {'productId': '{{input.productId}}', 'warehouse': '{{input.warehouse}}'}}},
+        {'op': 'fail', 'when': {'exists': '{{inv._id}}', 'is': None}, 'message': '库存记录不存在'},
+        {'op': 'fail', 'when': {'lt': '{{inv.stock}}', 'than': '{{input.qty}}'}, 'message': '库存不足'},
+        {'op': 'mutation', 'model': 'Inventory',
+         'data': {'_id': '{{inv._id}}', 'stock': '{{dec:{{inv.stock}},{{input.qty}}}}'}},
+    ],
+})
+
+run = await workflow.run('placeOrder', {'productId': 'p1', 'warehouse': 'w1', 'qty': 30})
+# run['status'] ∈ succeeded | failed | rejected | drySucceeded | dryFailed
+# Uniform contract: business failures never raise; the error lives in run['error']
+# (set only on failure; always null on success — never `||`-masked downstream)
+```
+
+- **Step whitelist** (three kinds; anything else fails registration with `WORKFLOW_UNSUPPORTED`):
+  `query` (result must be unique — >1 row is an explicit error), `mutation` (store.mutation /
+  upsert), `fail` (explicit business assertion). Optional `when` guards (exists / is / eq / ne /
+  lt / lte / gt / gte) record `skipped` explicitly — never silently skipped.
+- **Placeholders**: `{{input.<path>}}`, `{{<as>.<path>}}` (forward references only),
+  `{{dec:<a>,<b>}}`; full-string replacement keeps the value type. No placeholders inside gql
+  (bind via params — injection safety); no array-index path segments.
+- **Permissions**: three-tier role whitelists embedded in the defn (same RBAC semantics: admin /
+  super_admin bypass, guest denied, internal bypass); runs inherit the caller's Context and every
+  step goes through core permission checks — no superuser. `require_context(true)` rejects
+  context-less runs (fail-secure wins over dry-run); rejected runs are persisted for audit.
+- **Atomicity**: a single-source run is atomic across steps (outer `run_atomic` wraps the whole
+  loop, inner mutations nest into it); multi-source / prescan-failed runs execute sequentially and
+  emit feedback events (`workflow_non_atomic` / `workflow_prescan_failed`) — never silent. The run
+  record (running → terminal) is committed outside the business transaction so failed runs stay
+  queryable after rollback.
+- **dry-run**: `workflow.run(name, input, dry_run=True)` — query steps execute for real (read-only
+  safe); mutation / fail are recorded as `wouldRun` (`drySucceeded | dryFailed`).
+- **Run persistence**: `__workflowRun` is bootstrapped on import (idempotent); SQL backends need a
+  one-time `ddl.generate(backend, ['__workflowRun'])` (Mongo creates the collection on first write).
+  Its `write` whitelist is explicitly empty (GQL tampering with run audit is rejected by R2).
+
+### Explicitly not in the first batch (detected → error; boundaries shipped with the same weight as features)
+
+| Not supported | Why | Escape hatch |
+|---|---|---|
+| Loops / parallel / sub-workflows / human approval | DAG & wait semantics explode; linear + `when` covers the first batch | orchestrate in host code via the store API |
+| Auto compensation (Saga) / auto retry | Inverse-operation burden; steps have no automatic idempotency | inspect run records and handle explicitly |
+| Per-step host callbacks | Arbitrary code breaks whitelist governance | schema computes (read) / host code (write) |
+| Workflow defn persistence / hot reload | Depends on schema versioning (next on the roadmap) | defn stays code-side JSON + register, like schemas today |
+| Timers / event triggers | Scheduling is a resident-IO concern, orthogonal to pure orchestration | call `run` from the application layer |
+| Placeholders inside gql / array-index paths | Injection surface / per-row iteration semantics | params binding / host-code orchestration |
 
 ## FAQ
 

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

@@ -523,6 +523,72 @@ complex reads). Full details, semantics and the explicit-error list:
 - **`$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.
+- **Declarative migration** — `ddl.diff_defs(old, new)` + `ddl.generate_migration(backend, old, new)`: whitelist-only (add table/column/index, type widening), per-dialect SQL, pure functions; destructive changes fail with `MIGRATION_UNSUPPORTED`.
+
+## Workflow orchestration (first batch)
+
+Express "orchestration of multi-step data operations" as data: a workflow definition (defn) is pure
+JSON isomorphic to a schema defn, and each run is persisted to the built-in schema `__workflowRun`
+(queryable with plain GQL — zero new observability endpoints). Execution generalizes the existing
+mutation step-sequence mechanism: linear steps + per-step `when` guards + fail-fast. The engine
+lives in the host layer (`py_store/workflow.py`), core unchanged; aligned with
+`nodejs-store/src/workflow.js` (byte-identical outputs guarded by parity anchor tests).
+
+```python
+from py_store import workflow
+
+workflow.register({
+    'name': 'placeOrder',
+    'run': ['admin', 'ops'],              # three-tier whitelists read/write/run (run falls back to write)
+    'steps': [
+        {'op': 'query', 'as': 'inv',
+         'gql': 'Inventory($condition:@c0){_id, stock}',
+         'params': {'c0': {'productId': '{{input.productId}}', 'warehouse': '{{input.warehouse}}'}}},
+        {'op': 'fail', 'when': {'exists': '{{inv._id}}', 'is': None}, 'message': '库存记录不存在'},
+        {'op': 'fail', 'when': {'lt': '{{inv.stock}}', 'than': '{{input.qty}}'}, 'message': '库存不足'},
+        {'op': 'mutation', 'model': 'Inventory',
+         'data': {'_id': '{{inv._id}}', 'stock': '{{dec:{{inv.stock}},{{input.qty}}}}'}},
+    ],
+})
+
+run = await workflow.run('placeOrder', {'productId': 'p1', 'warehouse': 'w1', 'qty': 30})
+# run['status'] ∈ succeeded | failed | rejected | drySucceeded | dryFailed
+# Uniform contract: business failures never raise; the error lives in run['error']
+# (set only on failure; always null on success — never `||`-masked downstream)
+```
+
+- **Step whitelist** (three kinds; anything else fails registration with `WORKFLOW_UNSUPPORTED`):
+  `query` (result must be unique — >1 row is an explicit error), `mutation` (store.mutation /
+  upsert), `fail` (explicit business assertion). Optional `when` guards (exists / is / eq / ne /
+  lt / lte / gt / gte) record `skipped` explicitly — never silently skipped.
+- **Placeholders**: `{{input.<path>}}`, `{{<as>.<path>}}` (forward references only),
+  `{{dec:<a>,<b>}}`; full-string replacement keeps the value type. No placeholders inside gql
+  (bind via params — injection safety); no array-index path segments.
+- **Permissions**: three-tier role whitelists embedded in the defn (same RBAC semantics: admin /
+  super_admin bypass, guest denied, internal bypass); runs inherit the caller's Context and every
+  step goes through core permission checks — no superuser. `require_context(true)` rejects
+  context-less runs (fail-secure wins over dry-run); rejected runs are persisted for audit.
+- **Atomicity**: a single-source run is atomic across steps (outer `run_atomic` wraps the whole
+  loop, inner mutations nest into it); multi-source / prescan-failed runs execute sequentially and
+  emit feedback events (`workflow_non_atomic` / `workflow_prescan_failed`) — never silent. The run
+  record (running → terminal) is committed outside the business transaction so failed runs stay
+  queryable after rollback.
+- **dry-run**: `workflow.run(name, input, dry_run=True)` — query steps execute for real (read-only
+  safe); mutation / fail are recorded as `wouldRun` (`drySucceeded | dryFailed`).
+- **Run persistence**: `__workflowRun` is bootstrapped on import (idempotent); SQL backends need a
+  one-time `ddl.generate(backend, ['__workflowRun'])` (Mongo creates the collection on first write).
+  Its `write` whitelist is explicitly empty (GQL tampering with run audit is rejected by R2).
+
+### Explicitly not in the first batch (detected → error; boundaries shipped with the same weight as features)
+
+| Not supported | Why | Escape hatch |
+|---|---|---|
+| Loops / parallel / sub-workflows / human approval | DAG & wait semantics explode; linear + `when` covers the first batch | orchestrate in host code via the store API |
+| Auto compensation (Saga) / auto retry | Inverse-operation burden; steps have no automatic idempotency | inspect run records and handle explicitly |
+| Per-step host callbacks | Arbitrary code breaks whitelist governance | schema computes (read) / host code (write) |
+| Workflow defn persistence / hot reload | Depends on schema versioning (next on the roadmap) | defn stays code-side JSON + register, like schemas today |
+| Timers / event triggers | Scheduling is a resident-IO concern, orthogonal to pure orchestration | call `run` from the application layer |
+| Placeholders inside gql / array-index paths | Injection surface / per-row iteration semantics | params binding / host-code orchestration |
 
 ## FAQ
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "storepy"
-version = "2.6.0"
+version = "2.7.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"
@@ -56,6 +56,10 @@ Issues = "https://github.com/coenddt/py-store/issues"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+# ask() 的 system prompt 知识源（text-to-query 通用契约裁剪版）随包分发
+[tool.setuptools.package-data]
+py_store = ["ask_knowledge.md"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]

{storepy-2.6.0 → storepy-2.7.0}/src/py_store/__init__.py

@@ -20,18 +20,19 @@ py-store — 轻量多后端数据层（Python 版，Rust 单核心架构；支
 """
 
 from collections.abc import Mapping
-from contextlib import contextmanager
 from typing import Any
 
 from pymongo.errors import PyMongoError
 
 from . import (
+    ask,
     crud,
     datasource,
     ddl,
     feedback,
     permission,
     schema,
+    workflow,
 )
 from . import (
     executors as executors,
@@ -39,10 +40,16 @@ from . import (
 from . import (
     introspect as introspect,
 )
+from .ask import AskExhausted as AskExhausted
+from .ask import AskResult as AskResult
 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 .llm import get_llm as get_llm
+from .llm import make_openai_compat as make_openai_compat
+from .llm import register_llm as register_llm
+from .schema import text2query
 from .sync import sync_schema
 
 
@@ -52,21 +59,6 @@ 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（**全显式类方法，无动态查找**）
 
@@ -203,6 +195,35 @@ class Store:
         """从已注册 schema def 生成指定后端 DDL 文本（纯函数，不连库、不回写；铁律 6）"""
         return ddl.generate(backend, names)
 
+    # ── 工作流编排（首批：线性 + when 守卫 + fail-fast；见 workflow.py 与设计文档）──
+    def registerWorkflow(self, defn: dict) -> dict:
+        """注册工作流定义（注册即静态校验，白名单外显式 Err 含 WORKFLOW_UNSUPPORTED）"""
+        return workflow.register(defn)
+
+    def workflows(self, ctx: dict | None = None) -> list[str]:
+        """全部可见工作流名（read 白名单过滤）"""
+        return workflow.list(ctx)
+
+    def getWorkflow(self, name: str, ctx: dict | None = None) -> dict:
+        """按名取工作流定义（read 白名单过滤；不可见与不存在同形——防枚举）"""
+        return workflow.get(name, ctx)
+
+    async def runWorkflow(self, name: str, input: dict | None = None, *,
+                          dry_run: bool = False,
+                          route_override: dict | None = None) -> dict[str, Any]:
+        """触发工作流 → 完整 run 文档（终态 failed/rejected 不抛错，以 run.status + error 表达）"""
+        return await workflow.run(name, input, dry_run=dry_run, route_override=route_override)
+
+    # ── AI 问数（L1，只读）：自然语言 → LLM 翻译 → text2query 沙箱执行 → 结构化回喂 ──
+    # 护栏（档位/ctx/route_override）全部服务端硬编码于 ask.py，零暴露进 LLM 消息面（D5）
+    # （先于 ask 赋值取 describe_for_ai：赋值后类体命名空间的 ask 不再是模块）
+    describeForAi = staticmethod(ask.describe_for_ai)
+    describe_for_ai = describeForAi
+    ask = staticmethod(ask.ask)
+    # 问数结果/耗尽错误（实例可被 store.AskExhausted 捕获；对齐 PermissionError 先例）
+    AskResult = AskResult
+    AskExhausted = AskExhausted
+
     # ── 驼峰别名（与上方同名蛇形方法为**同一实现**，仅命名差异）──
     queryOne = query_one
     queryWithCount = query_with_count
@@ -214,6 +235,10 @@ class Store:
     executeRaw = execute_raw
     executeNative = execute_native
     generateDdl = generate_ddl
+    # 工作流编排（蛇形别名与上方驼峰同实现）
+    register_workflow = registerWorkflow
+    run_workflow = runWorkflow
+    get_workflow = getWorkflow
 
     # ── 其余 API 显式绑定（staticmethod：避免实例化后 self 注入）──
     # Schema 管理
@@ -243,6 +268,19 @@ class Store:
     set_require_context = staticmethod(schema.set_require_context)
     requireContext = staticmethod(schema.require_context)
     require_context = staticmethod(schema.require_context)
+    # RBAC 动态策略（判决唯一在 core；本层仅透传配置与查询面）
+    setRbac = staticmethod(permission.set_rbac)
+    set_rbac = staticmethod(permission.set_rbac)
+    rbacEnabled = staticmethod(permission.rbac_enabled)
+    rbac_enabled = staticmethod(permission.rbac_enabled)
+    rbacCan = staticmethod(permission.rbac_can)
+    rbac_can = staticmethod(permission.rbac_can)
+    rbacReadableFields = staticmethod(permission.rbac_readable_fields)
+    rbac_readable_fields = staticmethod(permission.rbac_readable_fields)
+    rbacWritableFields = staticmethod(permission.rbac_writable_fields)
+    rbac_writable_fields = staticmethod(permission.rbac_writable_fields)
+    rbacRowCondition = staticmethod(permission.rbac_row_condition)
+    rbac_row_condition = staticmethod(permission.rbac_row_condition)
     # 查询档位（判决唯一在 core）：standard 默认放开 / text2query 功能收缩
     # 进入档即等效强制 ctx；未知档由 core 抛 ValueError 上抛（禁静默回落默认档）
     setProfile = staticmethod(schema.set_profile)

storepy-2.7.0/src/py_store/ask.py

@@ -0,0 +1,322 @@
+"""AI 问数（L1）—— ``ask()`` 唯一入口 + ``describe_for_ai`` schema 摘要生成器
+
+《AI能力接入设计-L1问数档.md》§4 的宿主侧两个新组件，把既有能力接线：
+
+    用户问题 → ① describe_for_ai(ctx) 权限过滤摘要
+             → ② LLM（注入式客户端）翻译为 {"gql","params"}
+             → ③ with text2query(): 规划期校验（core 判决：语法/档位/权限/硬限）
+             → ④ crud.query 执行（只读）
+             → ⑤ 失败结构化回喂 LLM 重试（≤ max_retries 次），耗尽抛 AskExhausted
+
+护栏面（D5，服务端硬编码，LLM 零可触）：
+  - 档位 = text2query：本模块硬编码 ``with text2query():`` 包裹全部执行；
+  - 用户上下文 = ctx：服务端注入参数，经 ``permission.scoped_context`` 进执行面，
+    绝不进入任何 LLM 消息；core 档位门禁强制无 ctx 即拒（fail-secure，A4）；
+  - route_override = None：硬编码（CWE-639；Host 兜底 ``_guard_route_override`` 双保险）；
+  - 行数/深度/联邦硬限：core 常量（T2Q_MAX_ROWS=1000 / T2Q_MAX_DEPTH=3 / ...，A5）；
+  - 只读：编排面仅 ``crud.query``（mutation/remove 属 L2，禁入）。
+
+LLM 输出永远当不可信输入：唯一产出形状 ``{"gql","params"}`` 单 JSON 对象（D3），
+严格 JSON 解析、禁正则容错提取；幻觉最坏后果是「规划失败 + 结构化错误回喂」，
+不可能变成不受控命令。一切失败结构化显式暴露（no-error-masking：是错就是错，
+禁降级、禁返回空结果——「问数失败」就是失败，交上层裁决，D4）。
+
+并发限制（如实声明）：``text2query`` 档位（core 单例）与反馈 sink 为进程级全局，
+同一进程内并发调用 ``ask()`` 会互相串扰，宿主需串行化（或每任务独享进程/事件循环）。
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+from dataclasses import dataclass, field
+
+from . import crud, feedback, permission, schema
+from .core import core
+from .llm import get_llm as _get_llm
+from .schema import text2query
+
+__all__ = ['AskExhausted', 'AskResult', 'ask', 'describe_for_ai']
+
+
+# ─── 轨迹载体 ──────────────────────────────────────────────────
+
+
+@dataclass
+class AskResult:
+    """问数成功结果：查询数据 + 全部尝试轨迹 + 反馈事件
+
+    - ``data``：查询结果数组（crud.query 原样返回）；
+    - ``attempts``：每次尝试一条（``llm_raw`` / ``gql`` / ``params`` / ``rows``），
+      最后一轮为成功轮——**不含任何 error 键**（成功态无错误字段，no-error-masking 正向断言）；
+    - ``events``：执行期接管到的反馈事件（拦截/降级告警；无拦截时为空列表）。
+    """
+
+    data: list
+    attempts: list = field(default_factory=list)
+    events: list = field(default_factory=list)
+
+
+class AskExhausted(Exception):
+    """重试耗尽：max_retries 次回喂重试后仍失败（D4：显式失败，不降级、不返回空结果）
+
+    ``attempts`` / ``events`` 携带全部尝试轨迹；消息内嵌最后一轮结构化错误，
+    上游不读属性也能看到失败原因。
+    """
+
+    def __init__(self, attempts, events):
+        last_error = (attempts[-1].get('error') if attempts else None) or {'code': 'unknown'}
+        super().__init__(
+            f'ask() 重试耗尽（共 {len(attempts)} 次尝试全部失败），不降级、不返回空结果；'
+            f'最后一轮错误: {json.dumps(last_error, ensure_ascii=False)}；'
+            '完整轨迹见 .attempts / .events'
+        )
+        self.attempts = attempts
+        self.events = events
+
+
+# ─── 组件 A：schema 摘要生成器 ─────────────────────────────────
+
+# 计算列收窄告警去重（同 (model, compute) 只告警一次，对齐 schema.list 的 _dup_signatures 先例）
+_COMPUTE_SKIP_SIGS: set = set()
+
+
+def _field_type(fdef):
+    """字段类型字符串（str 形态原样；dict 形态取 type；其余显式 None，不伪造）"""
+    if isinstance(fdef, str):
+        return fdef
+    if isinstance(fdef, dict):
+        return fdef.get('type')
+    return None
+
+
+def _emit_compute_skipped(model, compute):
+    sig = (model, compute)
+    if sig in _COMPUTE_SKIP_SIGS:
+        return
+    _COMPUTE_SKIP_SIGS.add(sig)
+    feedback.emit({
+        'type': 'ask_summary_compute_skipped',
+        'code': 'askSummaryComputeSkipped',
+        'layer': 'host',
+        'message': (f'AI 摘要收窄：模型 {model} 的计算列 {compute} 配置了 read 白名单，'
+                    'core-py 绑定未导出 readable_computes 判决，为不越权暴露已从摘要排除'),
+        'hint': ('去掉该计算列的 read 配置可进摘要；或在 core-py 导出 readable_computes '
+                 '后接入 describe_for_ai（执行面权限判决始终在 core，此处仅摘要暴露面收窄）'),
+        'model': model,
+        'compute': compute,
+    })
+
+
+def describe_for_ai(ctx=None) -> list[dict]:
+    """输出 LLM 可读的 schema 摘要（紧凑 JSON 数组，每模型一条）。
+
+    过滤规则（顺序固定，设计文档 §4.1）：
+      1. 排除归档表（名称以 ``Deleted`` 结尾，对齐 store-api 派生路由先例）；
+      2. 模型级按 core ``can_read``；字段/关系按 core 角色可读集（``readable_fields`` /
+         ``readable_relations``，列级白名单）；计算列按声明 read 白名单**保守收窄**——
+         core-py 未导出 ``readable_computes`` 判决，配了 read 的计算列不进摘要并 emit
+         告警（宁缺勿泄；执行面判决始终在 core，收窄只影响摘要暴露面）；
+         无 ctx → 仅暴露模型名与字段名，不暴露类型细节（防探针）；
+      3. 不输出 indexes / datasource / namespace（运维细节不进 prompt）。
+    """
+    summaries = []
+    for name in schema.list():
+        if name.endswith('Deleted'):
+            continue
+        mirror = schema.get(name)
+        if ctx is None:
+            summaries.append({'name': name, 'fields': sorted(mirror['fields'])})
+            continue
+        if not core.can_read(name, ctx):
+            continue
+        readable = set(core.readable_fields(name, ctx))
+        fields = {fname: _field_type(fdef)
+                  for fname, fdef in mirror['fields'].items() if fname in readable}
+        for fname in sorted(readable - set(mirror['fields'])):
+            # core 自动补的时间戳字段（createdAt/updatedAt）不在 Host 镜像——类型显式留白
+            fields[fname] = None
+        relations = {}
+        readable_rels = set(core.readable_relations(name, ctx))
+        for rname, rdef in mirror['relations'].items():
+            if rname in readable_rels:
+                relations[rname] = {'model': rdef.get('model'), 'type': rdef.get('type')}
+        computes = {}
+        for cname, cdef in mirror['computes'].items():
+            if cdef.get('read') is not None:
+                _emit_compute_skipped(name, cname)
+                continue
+            entry = {}
+            if cdef.get('agg') is not None:
+                entry['agg'] = cdef['agg']
+            if cdef.get('type') is not None:
+                entry['type'] = cdef['type']
+            computes[cname] = entry
+        summaries.append({
+            'name': name, 'fields': fields,
+            'relations': relations, 'computes': computes,
+        })
+    return summaries
+
+
+# ─── 组件 B：ask() 编排器 ──────────────────────────────────────
+
+_KNOWLEDGE_CACHE: str | None = None
+
+
+class _BadLlmOutput(Exception):
+    """LLM 输出未通过严格解析（携带结构化 detail 供回喂）——内部控制流，不外穿"""
+
+    def __init__(self, detail):
+        super().__init__(detail.get('detail', 'badLlmOutput'))
+        self.detail = detail
+
+
+def _load_knowledge(knowledge):
+    """知识文本：传参优先（测试/自定义）；缺省读包内 ask_knowledge.md（text-to-query 裁剪版）"""
+    global _KNOWLEDGE_CACHE
+    if knowledge is not None:
+        return knowledge
+    if _KNOWLEDGE_CACHE is None:
+        _KNOWLEDGE_CACHE = (
+            importlib.resources.files(__package__) / 'ask_knowledge.md'
+        ).read_text(encoding='utf-8')
+    return _KNOWLEDGE_CACHE
+
+
+def _build_system_prompt(summary, knowledge):
+    """system prompt = 翻译知识 + 摘要 + 输出契约（D3；含 "json" 字样满足 json_mode 预检）"""
+    return (
+        f'{knowledge}\n\n'
+        '## 可用模型摘要（当前用户可见；字段/关系/计算列已按权限过滤）\n'
+        f'{json.dumps(summary, ensure_ascii=False)}\n\n'
+        '## 输出契约（唯一产出形状）\n'
+        '只输出一个 json 对象：{"gql": "<GQL 查询串>", "params": {<参数对象>}}。\n'
+        '- 条件值一律参数化：GQL 内用 @key 引用，真实值放 params（键 = 去掉 @ 的引用名）；\n'
+        '  禁止内联值进 GQL 串。\n'
+        '- 禁止输出解释文字、markdown 代码围栏、或除 gql/params 外的任何键。\n'
+    )
+
+
+def _parse_llm_output(raw):
+    """严格 JSON 解析 + 形状校验（D3）；失败抛 ``_BadLlmOutput``（禁正则容错提取）"""
+    def fail(detail):
+        return _BadLlmOutput({
+            'code': 'badLlmOutput',
+            'message': 'LLM 输出不是合法的 {"gql","params"} 单 JSON 对象',
+            'detail': detail,
+            'raw': (raw or '')[:500],
+        })
+
+    if not isinstance(raw, str):
+        raise fail(f'输出不是字符串: {type(raw).__name__}')
+    try:
+        parsed = json.loads(raw)
+    except ValueError as e:
+        raise fail(f'JSON 解析失败: {e}') from e
+    if not isinstance(parsed, dict):
+        raise fail(f'顶层不是 JSON 对象: {type(parsed).__name__}')
+    if set(parsed) != {'gql', 'params'}:
+        raise fail(f'键集合必须恰为 gql/params，实际: {sorted(parsed)}')
+    gql, params = parsed['gql'], parsed['params']
+    if not isinstance(gql, str) or not gql.strip():
+        raise fail('gql 必须为非空字符串')
+    if not isinstance(params, dict):
+        raise fail('params 必须为 JSON 对象')
+    return gql, params
+
+
+def _error_from_exception(e, round_events):
+    """执行失败 → 回喂错误对象：core/Host 拦截事件**原样透传**（禁改写禁摘要）；
+    无事件兜底构造时只给确证字段（feature/layer 留白不伪造）"""
+    for ev in round_events:
+        if ev.get('type') == 'profile_blocked':
+            return dict(ev)
+    if isinstance(e, permission.PermissionError):
+        return {'code': 'permissionDenied', 'message': str(e)}
+    if isinstance(e, crud.ProfileViolation):
+        return {'code': 'profileBlocked', 'message': str(e)}
+    return {'code': 'planError', 'message': str(e)}
+
+
+async def ask(question: str, *, llm, ctx: dict, max_retries: int = 3,
+              knowledge: str | None = None) -> AskResult:
+    """AI 问数唯一入口（L1 只读）：自然语言 → LLM 翻译 → 受控沙箱执行 → 结构化回喂。
+
+    参数：
+      question    : 自然语言问题（非空字符串）。
+      llm         : 注册名（str，经 ``llm.get_llm``）或现成客户端
+                    （协议 ``async def(messages) -> str``，D2/D6 注入式，py-store 零 SDK）。
+      ctx         : 服务端构造的用户上下文（``{'userId': ..., 'roles': [...]}``）；
+                    None 直接拒绝（fail-secure）；LLM 永远碰不到本参数（D5）。
+      max_retries : 失败后的最大**重试**次数（总尝试 ≤ 1 + max_retries）；耗尽抛 ``AskExhausted``。
+      knowledge   : 覆盖 system prompt 知识文本（缺省用包内 ask_knowledge.md）。
+
+    返回 ``AskResult(data, attempts, events)``；LLM 客户端自身的异常（网络/HTTP/空 content，
+    ``RuntimeError(dict)`` 结构化）**原样穿透**——回喂循环只裁决「翻译质量/查询合法性」，
+    链路故障显式失败不重试。
+
+    轨迹契约：成功轮 attempt 不含 error 键；每次失败以 user 消息追加
+    ``{"error": {...}}``（core/Host 结构化错误原样透传，§4.3）。
+    """
+    if not isinstance(question, str) or not question.strip():
+        raise ValueError('ask(question) 需要非空自然语言问题字符串')
+    if ctx is None:
+        # fail-secure：core text2query 档强制 ctx（ensure_profile_ctx）——入口先拒，
+        # 免一次注定失败的 LLM 调用；空 dict 等其余边界交 core/权限层如实判决
+        raise ValueError(
+            'ask() 需要服务端构造的用户上下文 ctx（如 {"userId": ..., "roles": [...]}）；'
+            'ctx 属受信参数，LLM 永远碰不到（D5）')
+    if not isinstance(max_retries, int) or max_retries < 0:
+        raise ValueError(f'max_retries 必须为非负整数，实际: {max_retries!r}')
+    client = llm if callable(llm) else _get_llm(llm)
+    system = _build_system_prompt(describe_for_ai(ctx), _load_knowledge(knowledge))
+
+    messages = [
+        {'role': 'system', 'content': system},
+        {'role': 'user', 'content': question},
+    ]
+    attempts: list[dict] = []
+    events: list[dict] = []
+    round_events: list[dict] = []
+
+    def _collect(event):
+        events.append(event)
+        round_events.append(event)
+
+    prev_sink = feedback.get_sink()
+    feedback.set_sink(_collect)
+    try:
+        with text2query(), permission.scoped_context(ctx):
+            for _ in range(1 + max_retries):
+                round_events.clear()
+                # LLM 客户端异常（llmNetworkError/llmHttpError/llmEmptyContent）原样穿透
+                raw = await client(messages)
+                attempt = {'llm_raw': raw}
+                try:
+                    gql, params = _parse_llm_output(raw)
+                except _BadLlmOutput as e:
+                    attempt['error'] = e.detail
+                    attempts.append(attempt)
+                    messages.append({'role': 'assistant', 'content': raw})
+                    messages.append({'role': 'user', 'content': json.dumps(
+                        {'error': e.detail}, ensure_ascii=False)})
+                    continue
+                attempt['gql'] = gql
+                attempt['params'] = params
+                try:
+                    # route_override 硬编码 None（受信参数，禁 AI 侧指定，D5/CWE-639）
+                    data = await crud.query(gql, params, None)
+                except Exception as e:
+                    attempt['error'] = _error_from_exception(e, round_events)
+                    attempts.append(attempt)
+                    messages.append({'role': 'assistant', 'content': raw})
+                    messages.append({'role': 'user', 'content': json.dumps(
+                        {'error': attempt['error']}, ensure_ascii=False)})
+                    continue
+                attempt['rows'] = len(data)
+                attempts.append(attempt)
+                return AskResult(data=data, attempts=attempts, events=events)
+    finally:
+        feedback.set_sink(prev_sink)
+    raise AskExhausted(attempts, events)