nodejs-store 2.5.0 → 2.7.0

package/README.md

@@ -35,6 +35,7 @@
 - [Schema reference](#schema-reference)
 - [Advanced API](#advanced-api)
 - [Transactions](#transaction-boundary)
+- [Transactional capabilities](#transactional-capabilities)
 - [FAQ](#faq)
 - [Related projects](#related-projects)
 
@@ -210,6 +211,9 @@ GQL tree queries compile to a single native query per backend — never hand-wri
 - **Permission context** — `AsyncLocalStorage`-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 the `mongodb` Node.js driver 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
 
@@ -519,6 +523,97 @@ store.setFeedbackSink((e) => logger.warn({ code: e.code }, e.hint));
 Non-pushdownable commands also throw `PushdownUnsupportedError` — catch it to re-run that
 segment against a Mongo source.
 
+### `store.ask(question, opts)`
+
+AI ask — natural-language query (L1, read-only). The question plus a permission-filtered
+schema summary (`store.describeForAi`) go to a pluggable LLM, which must answer with a
+single `{"gql","params"}` JSON object; that query is then planned and executed inside the
+hardened `text2query` profile (read-only, row/depth caps, route override disabled).
+Structured failures are fed back to the LLM for retry (up to `maxRetries` rounds); on
+exhaustion `AskExhausted` is thrown — ask never silently degrades and never returns
+empty data for a failed query.
+
+LLM output is treated as untrusted input: the guardrails (profile, context enforcement,
+read-only) are hardcoded server-side and unreachable by the model.
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `llm` | `string \| Function` | required; registry name (see [`llm`](#llm-registry-llm) below) or an `async (messages) => string` client |
+| `ctx` | object | required; server-side user context `{ userId, roles }`; a missing ctx is rejected (fail-secure) and the context never enters any LLM message |
+| `maxRetries` | number (default `3`) | retries after a failed attempt (total attempts ≤ `1 + maxRetries`) |
+| `knowledge` | string | override the system-prompt knowledge text (default: bundled `ask_knowledge.md`) |
+
+Resolves to an `AskResult` `{ data, attempts, events }`. Each attempt is
+`{ llmRaw, gql, params, rows }` — the successful round carries no `error` key; failed
+rounds carry `{ error: { code, message } }` with `code` ∈ `badLlmOutput`,
+`profileBlocked`, `permissionDenied`, `planError`. LLM client faults (`LlmError`:
+network / HTTP status / empty content) propagate untouched — link failures fail
+explicitly and are not retried.
+
+```js
+const { llm } = require('nodejs-store');
+
+llm.registerLlm('deepseek', llm.makeOpenaiCompat({
+  baseUrl: 'https://api.deepseek.com/v1',
+  model: 'deepseek-chat',
+  apiKey: process.env.DEEPSEEK_API_KEY,
+}));
+
+const result = await store.ask('Total amount of my last 10 orders?', {
+  llm: 'deepseek',
+  ctx: { userId: 'u1', roles: ['viewer'] },
+});
+console.log(result.data);                 // query result rows
+console.log(result.attempts.at(-1).gql);  // the GQL the model produced
+```
+
+> The `text2query` profile is a process-wide core singleton: concurrent `ask()` calls in
+> one process interleave. Serialize asks per process, or run each in its own worker.
+
+### `store.describeForAi(ctx?)`
+
+Permission-filtered schema summary for LLM prompts — a compact JSON array with one
+`{ name, fields, relations, computes }` entry per model. Without a context only model
+and field *names* are exposed (no types — probe-resistant). With a context, models,
+fields, relations and computed columns are filtered by the caller's role
+(`canRead` / `readableFields` / `readableRelations` / `readableComputes`), archive
+tables (`*Deleted`) are dropped, and ops details (indexes / datasource / namespace)
+never enter the prompt.
+
+```js
+const summary = store.describeForAi({ userId: 'u1', roles: ['viewer'] });
+// [{ name: 'Order', fields: { _id: 'string', code: 'string', ... }, relations: { ... }, computes: { ... } }]
+```
+
+On native bindings that lack the `readableComputes` verdict, computed columns with a
+`read` whitelist are conservatively excluded from the summary and an
+`askSummaryComputeSkipped` feedback event is emitted — narrow the exposure, never
+over-disclose.
+
+### LLM registry (`llm`)
+
+Pluggable LLM clients with no SDK bundled. A client is a single function
+`async (messages: Array<{ role, content }>) => string`:
+
+```js
+const { llm } = require('nodejs-store');
+
+llm.registerLlm('deepseek', client);  // duplicate name → throws
+llm.getLlm('deepseek');               // unregistered name → throws
+
+llm.makeOpenaiCompat({                // OpenAI-compatible factory (global fetch, zero deps);
+  baseUrl, model, apiKey,             // covers DeepSeek / OpenAI / Moonshot / Ollama / ...
+  jsonMode: true,                     // false → omit response_format (prompt convention + strict parse fallback)
+  effort: 'low',                      // null → omit reasoning_effort
+  maxTokens: 4096,
+  timeoutMs: 90000,
+});
+```
+
+Client faults throw `LlmError` with a structured `.detail` (`code` ∈ `llmNetworkError`,
+`llmHttpError`, `llmEmptyContent`, `llmJsonPromptMissing`); `store.ask` propagates them
+untouched.
+
 ### Low-level modules
 
 The package re-exports its building blocks for advanced hosts:
@@ -562,6 +657,84 @@ await init({ default: db, pg_a: executors.createConnection('postgres', pgPool) }
 - 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** — `updateMany('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 insertId; MongoDB and `insertMany` 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.diffDefs(old, new)` + `ddl.generateMigration(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 (`src/workflow.js`), core unchanged; aligned with
+`nodejs-store/src/workflow.js` (byte-identical outputs guarded by parity anchor tests).
+
+```python
+from py_store import workflow
+
+store.registerWorkflow({
+    '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 store.runWorkflow('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**: `store.runWorkflow(name, input, { dryRun: 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 `runWorkflow` from the application layer |
+| Placeholders inside gql / array-index paths | Injection surface / per-row iteration semantics | params binding / host-code orchestration |
+
 ## FAQ
 
 **How do I use one schema for both MongoDB and PostgreSQL in Node.js?**

package/README.zh-CN.md

@@ -34,6 +34,7 @@
 - [Schema 参考](#schema-参考)
 - [高级 API](#高级-api)
 - [事务边界](#事务边界)
+- [事务型能力](#事务型能力)
 - [常见问题](#常见问题)
 - [相关项目](#相关项目)
 
@@ -209,6 +210,9 @@ GQL 树查询会编译为每个后端一条原生查询 —— 再也不必手
 - **权限上下文** —— 基于 `AsyncLocalStorage` 的角色（`super_admin`/`admin`/`guest`/`creator`...）、schema/字段级读写白名单、自动属主条件注入。
 - **多数据源 & 多租户** —— 通过 `(source, namespace, collection)` 定位 schema；按请求用路由覆盖重新定向。
 - **异步优先，Rust 核心** —— 基于 `mongodb` Node.js 驱动与共享的 Rust 核心（含 SQL 方言）。
+- **mutation 关系谓词** —— `update` / `remove` 按关联表字段过滤，下推到全部四个后端（此前 MongoDB 侧是静默 no-op）。
+- **自增主键** —— `_id` 声明 `{ type: 'int', strategy: 'autoincrement' }` 即用数据库自增整数 ID；做不到自增的场景显式报错。
+- **索引 DDL** —— `schema.indexes` 编译为真实 `CREATE [UNIQUE] INDEX` 语句（按后端、逐字节一致）；生成器仍只产文本。
 
 ## GQL 语法
 
@@ -518,6 +522,91 @@ store.setFeedbackSink((e) => logger.warn({ code: e.code }, e.hint));
 不可下推的命令还会抛出 `PushdownUnsupportedError` —— 捕获它即可把该片段
 改投到某个 Mongo 源重跑。
 
+### `store.ask(question, opts)`
+
+AI 问数——自然语言查询（L1，只读）。问题与一份按权限过滤的 schema 摘要
+（`store.describeForAi`）一起交给可插拔的 LLM，LLM 必须返回唯一的
+`{"gql","params"}` JSON 对象；该查询再经加固的 `text2query` 档位规划并执行
+（只读、行数/深度硬限、路由覆盖禁用）。结构化失败会回喂 LLM 重试（至多
+`maxRetries` 轮）；耗尽抛 `AskExhausted`——问数失败就是失败，不静默降级、
+不返回空结果。
+
+LLM 输出永远当不可信输入：护栏（档位、上下文强制、只读）在服务端硬编码，
+模型不可触达。
+
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| `llm` | `string \| Function` | 必填；注册名（见下方 [`llm` 注册表](#llm-注册表)）或符合 `async (messages) => string` 协议的客户端 |
+| `ctx` | object | 必填；服务端构造的用户上下文 `{ userId, roles }`；缺失直接拒绝（fail-secure），且上下文绝不进入任何 LLM 消息 |
+| `maxRetries` | number（默认 `3`） | 失败后的最大重试次数（总尝试 ≤ `1 + maxRetries`） |
+| `knowledge` | string | 覆盖 system prompt 知识文本（缺省用包内 `ask_knowledge.md`） |
+
+返回 `AskResult` `{ data, attempts, events }`。每次尝试为
+`{ llmRaw, gql, params, rows }`——成功轮不含任何 `error` 键；失败轮携带
+`{ error: { code, message } }`，`code` ∈ `badLlmOutput`、`profileBlocked`、
+`permissionDenied`、`planError`。LLM 客户端自身故障（`LlmError`：网络 /
+HTTP 状态 / 空 content）原样穿透——链路故障显式失败，不重试。
+
+```js
+const { llm } = require('nodejs-store');
+
+llm.registerLlm('deepseek', llm.makeOpenaiCompat({
+  baseUrl: 'https://api.deepseek.com/v1',
+  model: 'deepseek-chat',
+  apiKey: process.env.DEEPSEEK_API_KEY,
+}));
+
+const result = await store.ask('我最近 10 笔订单的金额合计是多少？', {
+  llm: 'deepseek',
+  ctx: { userId: 'u1', roles: ['viewer'] },
+});
+console.log(result.data);                 // 查询结果行
+console.log(result.attempts.at(-1).gql);  // 模型产出的 GQL
+```
+
+> `text2query` 档位是进程级 core 单例：同一进程内并发调用 `ask()` 会互相串扰。
+> 请在进程内串行化问数，或每个任务独享进程/worker。
+
+### `store.describeForAi(ctx?)`
+
+输出给 LLM prompt 用的权限过滤 schema 摘要——紧凑 JSON 数组，每模型一条
+`{ name, fields, relations, computes }`。无上下文时仅暴露模型名与字段名
+（不暴露类型细节，防探针）。有上下文时，模型/字段/关系/计算列按调用者角色过滤
+（`canRead` / `readableFields` / `readableRelations` / `readableComputes`），
+归档表（`*Deleted`）排除，运维细节（indexes / datasource / namespace）不进 prompt。
+
+```js
+const summary = store.describeForAi({ userId: 'u1', roles: ['viewer'] });
+// [{ name: 'Order', fields: { _id: 'string', code: 'string', ... }, relations: { ... }, computes: { ... } }]
+```
+
+原生绑定未导出 `readableComputes` 判决时，配置了 `read` 白名单的计算列会保守
+排除出摘要，并 emit `askSummaryComputeSkipped` 反馈事件——宁缺勿泄。
+
+### `llm` 注册表
+
+可插拔 LLM 客户端，不内置任何 SDK。客户端就是一个函数
+`async (messages: Array<{ role, content }>) => string`：
+
+```js
+const { llm } = require('nodejs-store');
+
+llm.registerLlm('deepseek', client);  // 同名重复注册 → 报错
+llm.getLlm('deepseek');               // 未注册 → 报错
+
+llm.makeOpenaiCompat({                // OpenAI 兼容通用工厂（全局 fetch，零依赖），
+  baseUrl, model, apiKey,             // 覆盖 DeepSeek / OpenAI / Moonshot / Ollama 等
+  jsonMode: true,                     // false → 不传 response_format（prompt 约定 + 严格解析回喂）
+  effort: 'low',                      // null → 不传 reasoning_effort
+  maxTokens: 4096,
+  timeoutMs: 90000,
+});
+```
+
+客户端故障抛 `LlmError`（`.detail` 结构化，`code` ∈ `llmNetworkError`、
+`llmHttpError`、`llmEmptyContent`、`llmJsonPromptMissing`）；`store.ask`
+对其原样穿透。
+
 ### 底层模块
 
 该包会重导出其构建模块，供高级宿主使用：
@@ -553,6 +642,7 @@ await init({ default: db, pg_a: executors.createConnection('postgres', pgPool) }
 | `store.session(...)` | 会话内单 SQL 源**跨多次调用**原子；跨源写被显式拦截（`NonAtomicWriteError`） |
 | 无会话的跨源多写 | 非原子（无 2PC / Saga 支持），按数据源顺序执行，并经反馈通道声明 `nonAtomic`（事件 `non_atomic_write`，含涉及源） |
 | Mongo 多步写 | replica set / sharded：单 Mongo 源原子（session 事务）；standalone：非原子并显式声明 `mongo_transaction_unsupported` |
+| 工作流 run（`runWorkflow`） | 单源 run **跨步骤**整体原子（外层 `runAtomic` 包住步骤循环、内层 mutation 嵌套并入）；多源 / 源预扫失败按顺序执行并经反馈通道声明非原子 |
 
 - **Mongo 源**：会话内按运行时能力探测结果事务化；不可事务（standalone / 探测失败）按原样执行，
   并发出 `mongo_transaction_unsupported` 反馈（`deployment: standalone|unknown`）（允许降级，绝不静默假装已事务化）；
@@ -566,6 +656,78 @@ await init({ default: db, pg_a: executors.createConnection('postgres', pgPool) }
   `non_atomic_write` 反馈（`code: nonAtomic`，含涉及源列表）——允许降级、禁止静默。
   把写收敛到单源，或放入 `store.session()` 内（后者对跨源写直接 fail-closed）。
 
+## 事务型能力
+
+面向事务型业务场景（订单、库存——写竞争 + 复杂读）的能力增补。完整语义、用法与显式报错清单：
+**[doc/transaction-capabilities.zh-CN.md](doc/transaction-capabilities.zh-CN.md)** ·
+[English](doc/transaction-capabilities.md).
+
+- **mutation 关系谓词** —— `updateMany('Inventory', { product: { category: 'meat' } }, { $inc: { stock: 10 } })`：条件键命中已声明关系即 semi/anti-join，归一为 preCommand（aggregate 取 `_id`）+ `_id $in`。
+- **`$group by` one 关系路径** —— `by: ['product.category']` 编译为 `$lookup`+`$unwind`（Mongo）/ `LEFT JOIN`（SQL）；many 路径显式报错（扇出破坏计数语义）。
+- **自增主键** —— `_id: { type: 'int', strategy: 'autoincrement' }`；PG/SQLite 经 `INSERT…RETURNING` 回读、MySQL 经 insertId；MongoDB 与 `insertMany` 显式报 `AUTOINCREMENT_NOT_SUPPORTED`（禁 ObjectId 静默顶替）。
+- **索引 DDL** —— `schema.indexes`（Mongo 形态）→ `ddl.generate` 产出 `CREATE [UNIQUE] INDEX idx_<表>_<字段>`，MySQL/PostgreSQL/SQLite 三方言逐字节一致。
+- **声明式迁移** —— `ddl.diffDefs(old, new)` + `ddl.generateMigration(backend, old, new)`：白名单制（加表/加列/加索引/类型放宽），纯函数按方言产 SQL；白名单外显式报 `MIGRATION_UNSUPPORTED`。
+
+## 工作流编排（首批）
+
+把「多步数据操作的编排」用数据表达：工作流定义（Workflow defn）是与 schema defn 同构的纯 JSON、
+运行记录（run）落库为内建 schema `__workflowRun`（普通 GQL 即查，可观测性零新接口）。执行是既有
+mutation 步骤序列机制的推广——线性步骤 + 步骤级 `when` 守卫 + fail-fast。引擎落在宿主层
+（`src/workflow.js`），core 零改动；对齐 `py-store/src/py_store/workflow.py`（双宿主输出逐字节
+一致由 parity 锚单测守护）。
+
+```js
+store.registerWorkflow({                   // 注册即静态校验；白名单外显式 Err（WORKFLOW_UNSUPPORTED）
+  name: 'placeOrder',
+  run: ['admin', 'ops'],                   // 三级白名单 read/write/run（run 缺省回退 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: null }, 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}}}}' } },
+  ],
+});
+
+const run = await store.runWorkflow('placeOrder', { productId: 'p1', warehouse: 'w1', qty: 30 });
+// run.status ∈ succeeded | failed | rejected | drySucceeded | dryFailed
+// 统一契约：业务失败不抛错，错误在 run.error（失败才有值；succeeded 态恒为 null）
+```
+
+- **步骤白名单**（首批仅三种，白名单外注册即 `WORKFLOW_UNSUPPORTED`）：`query`（store.query；
+  结果单条化，>1 行显式 Err）、`mutation`（store.mutation / upsert，继承其步骤序列与占位符机制）、
+  `fail`（显式业务断言失败：run 记 failed + stepIndex + message）。步骤可选 `when` 守卫
+  （exists / is / eq / ne / lt / lte / gt / gte），不满足记 `skipped`——显式留痕，绝不静默跳过。
+- **占位符**：`{{input.<path>}}`（本次 run 输入）、`{{<as>.<path>}}`（前序步骤结果，必须前向引用）、
+  `{{dec:<a>,<b>}}`（递减）；整值替换保类型、内嵌替换字符串化。gql 内禁占位符（参数走 params
+  绑定，防注入）；数组下标路径不支持（逐行处理请走宿主代码编排）。
+- **权限**：defn 内嵌三级角色白名单（复用四级 RBAC 语义：admin / super_admin 放行、guest 拒绝、
+  internal 放行、creator 按 Missing 通过）；run 继承触发者 Context，每步 query/mutation 都过 core
+  权限判定——工作流是「权限内的一次次普通调用」，不存在超级身份。`requireContext(true)` 开启时
+  无 ctx 拒跑（fail-secure 优先于 dry-run）。rejected 同样落库（拒绝可审计）。
+- **原子性**：单源 run 整体原子（外层 `runAtomic` 包住整个步骤循环，内层 mutation 嵌套并入——
+  任一步失败整体回滚）；多源 / 预扫失败按顺序执行并发反馈事件（`workflow_non_atomic` /
+  `workflow_prescan_failed`，禁静默）。run 记录时序：先落 `running`（进程崩溃可见）→ 步骤事务 →
+  终态在事务外独立提交（业务回滚不影响失败 run 可查）。
+- **dry-run**：`store.runWorkflow(name, input, { dryRun: true })`——query 真实执行（只读安全），
+  mutation / fail 记 `wouldRun`；终态 `drySucceeded | dryFailed`。
+- **run 落库**：`__workflowRun` 由模块加载即自举注册（幂等）；SQL 后端首次启用工作流需执行
+  `ddl.generate(backend, ['__workflowRun'])` 建表（Mongo 无需，首次写入自动建集合）。
+  其 `write` 为显式空名单（普通角色 GQL 篡改 run 审计被 R2 拒绝；模块内部写入走 internal 上下文）。
+
+### 首批明确不做（检出即 Err，边界与能力同权重）
+
+| 不做 | 理由 | 出口 |
+|---|---|---|
+| 循环 / 并行 / 子工作流 / 人工审批 | DAG 与人工等待语义复杂度爆炸；线性 + `when` 覆盖首批场景 | 宿主代码用 store API 编排 |
+| 自动补偿（Saga）/ 自动重试 | 反向操作语义负担大；步骤无自动幂等保证 | 人查 run 记录显式处置 |
+| 步骤级宿主回调 | 任意代码击穿白名单治理 | schema computes（读）/ 宿主代码（写） |
+| 工作流定义存库 / 热更 | 依赖 schema 版本化先行（路线图下一步） | defn 暂与 schema 同模式：代码内 JSON + register |
+| 定时触发 / 事件触发 | 触发器是常驻 IO 职责，属调度层，与「纯编排」正交 | 应用层自行调用 `runWorkflow` |
+| gql 内嵌占位符 / 数组下标路径 | 注入面 / 数组逐行处理语义 | params 绑定 / 宿主代码编排 |
+
 ## 常见问题
 
 **如何在 Node.js 中让一份 schema 同时用于 MongoDB 和 PostgreSQL？**

package/llms-full.txt

@@ -379,6 +379,77 @@ store.setFeedbackSink((e) => logger.warn({ code: e.code }, e.hint));
 
 Non-pushdownable commands also throw `PushdownUnsupportedError`.
 
+### `store.ask(question, opts)`
+
+AI ask — natural-language query (L1, read-only). The question plus a permission-filtered
+schema summary go to a pluggable LLM, which must answer with a single `{"gql","params"}`
+JSON object; the query is planned and executed inside the hardened `text2query` profile
+(read-only, row/depth caps, route override disabled). Structured failures are fed back
+to the LLM for retry (up to `maxRetries`); on exhaustion `AskExhausted` is thrown — no
+silent degradation, no empty results.
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `llm` | `string \| Function` | required; registry name or an `async (messages) => string` client |
+| `ctx` | object | required; server-side `{ userId, roles }`; missing ctx is rejected (fail-secure), never enters LLM messages |
+| `maxRetries` | number (default `3`) | retries after a failed attempt |
+| `knowledge` | string | override the system-prompt knowledge text |
+
+Resolves to `{ data, attempts, events }`; each attempt is `{ llmRaw, gql, params, rows }`
+(the successful round has no `error` key), failures carry
+`{ error: { code, message } }` with `code` ∈ `badLlmOutput`, `profileBlocked`,
+`permissionDenied`, `planError`. LLM client faults (`LlmError`) propagate untouched.
+
+```js
+const { llm } = require('nodejs-store');
+
+llm.registerLlm('deepseek', llm.makeOpenaiCompat({
+  baseUrl: 'https://api.deepseek.com/v1',
+  model: 'deepseek-chat',
+  apiKey: process.env.DEEPSEEK_API_KEY,
+}));
+
+const result = await store.ask('Total amount of my last 10 orders?', {
+  llm: 'deepseek',
+  ctx: { userId: 'u1', roles: ['viewer'] },
+});
+console.log(result.data, result.attempts.at(-1).gql);
+```
+
+> The `text2query` profile is a process-wide core singleton: serialize `ask()` calls
+> per process, or run each in its own worker.
+
+### `store.describeForAi(ctx?)`
+
+Permission-filtered schema summary for LLM prompts — a compact JSON array with one
+`{ name, fields, relations, computes }` entry per model. Without a context only model
+and field names are exposed (no types). With a context everything is filtered by the
+caller's role (`canRead` / `readableFields` / `readableRelations` / `readableComputes`);
+archive tables (`*Deleted`) and ops details (indexes / datasource / namespace) never
+enter the prompt. Bindings lacking the `readableComputes` verdict conservatively exclude
+`read`-whitelisted computed columns and emit `askSummaryComputeSkipped`.
+
+### LLM registry (`llm`)
+
+Pluggable LLM clients, no SDK bundled. A client is one function
+`async (messages: Array<{ role, content }>) => string`.
+
+```js
+llm.registerLlm('deepseek', client);  // duplicate name → throws
+llm.getLlm('deepseek');               // unregistered name → throws
+
+llm.makeOpenaiCompat({                // OpenAI-compatible factory (global fetch, zero deps)
+  baseUrl, model, apiKey,
+  jsonMode: true,                     // false → omit response_format
+  effort: 'low',                      // null → omit reasoning_effort
+  maxTokens: 4096,
+  timeoutMs: 90000,
+});
+```
+
+Client faults throw `LlmError` with a structured `.detail` (`code` ∈ `llmNetworkError`,
+`llmHttpError`, `llmEmptyContent`, `llmJsonPromptMissing`).
+
 ### Low-level modules
 
 ```js

package/llms.txt

@@ -37,6 +37,7 @@
 - [Multi-datasource & multi-tenant](https://github.com/coenddt/nodejs-store#multi-datasource-connections): `(source, namespace, collection)` and route override
 - [Schema reference](https://github.com/coenddt/nodejs-store#schema-reference): fields, relations, computes, indexes, read/write whitelists
 - [Advanced API](https://github.com/coenddt/nodejs-store#advanced-api): `buildPipeline`, `syncSchema`, `setFeedbackSink`, low-level modules
+- [AI ask (natural-language query)](https://github.com/coenddt/nodejs-store#storeaskquestion-opts): `store.ask` + `store.describeForAi` + pluggable LLM registry (`makeOpenaiCompat`), guarded by the read-only `text2query` profile
 - [Transactions](https://github.com/coenddt/nodejs-store#transaction-boundary): per-source atomicity guarantees
 
 ## Optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-store",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Multi-backend data layer for Node.js (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",
   "main": "src/index.js",
   "files": [
@@ -65,7 +65,7 @@
     "mongodb": "^6.21.0",
     "mysql2": "^3.24.4",
     "pg": "^8.23.0",
-    "rust-store-node": "^2.3.0"
+    "rust-store-node": "^2.7.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",