nodejs-store 2.6.0 → 3.0.0

package/src/ddl.js

@@ -186,4 +186,185 @@ function generate(backend, names) {
   return blocks.join('\n\n');
 }
 
-module.exports = { generate };
+// ══════════════════════════════════════════════════════════════════
+// 声明式 schema 迁移（阶段 4；设计见 common-store/迁移设计文档-阶段4.md）
+// 与 py_store/ddl.py 的 migration 段逐字节对齐（parity 锚：tests/migration.test.js）。
+// ══════════════════════════════════════════════════════════════════
+
+/** 类型放宽映射（首批）：值域安全扩大的单向变更；跨大类不在映射内 → Err */
+const WIDEN = {
+  int: ['long', 'float', 'double'],
+  long: ['float', 'double'],
+  float: ['double'],
+};
+
+/** 字段 def → 列 SQL 类型（与 columns 同源；object/array → JSON 文本列） */
+function fieldSqlType(backend, fdef) {
+  const i = idx(backend);
+  const ftype = declaredType(fdef);
+  if (NON_COLUMN.includes(ftype)) return JSON_TYPE[i];
+  if (!Object.prototype.hasOwnProperty.call(TYPES, ftype)) {
+    throw new Error(
+      `迁移生成：字段类型 ${JSON.stringify(ftype)} 未知（支持 ${Object.keys(TYPES).sort()}）`);
+  }
+  return TYPES[ftype][i];
+}
+
+/** default 字面量 → SQL 文本（仅 JSON 标量；SQLite 禁非常量表达式 DEFAULT） */
+function sqlLiteral(v) {
+  if (typeof v === 'boolean') return v ? 'TRUE' : 'FALSE';
+  if (typeof v === 'number') return String(v);
+  if (typeof v === 'string') return `'${v.replace(/'/g, "''")}'`;
+  throw new Error(`迁移生成：default 仅支持 JSON 标量字面量，收到 ${typeof v}`);
+}
+
+/** 主 def → 归档表 def（列 = 主列 + deletedAt；剔除 _id 自增策略；indexes 继承） */
+function archiveDefnOf(defn) {
+  const fields = { ...(defn.fields || {}) };
+  fields.deletedAt = { type: 'number' };
+  if (fields._id && typeof fields._id === 'object') {
+    const { strategy, ...rest } = fields._id;
+    fields._id = rest;
+  }
+  return {
+    ...defn,
+    name: `${defn.name}Deleted`,
+    collection: `${defn.collection || defn.name}_deleted`,
+    fields,
+    timestamps: false,
+    _isArchive: true,
+  };
+}
+
+/** 新旧 schema def 对比 → { changes, errors }（后端无关，纯函数；白名单外记入 errors） */
+function diffDefs(oldDefn, newDefn) {
+  const changes = [];
+  const errors = [];
+  const oldFields = (oldDefn && oldDefn.fields) || {};
+  const newFields = newDefn.fields || {};
+
+  if (oldDefn === null || oldDefn === undefined) {
+    return { changes: [{ op: 'addTable', defn: newDefn }], errors };
+  }
+
+  for (const [name, nf] of Object.entries(newFields)) {
+    if (name === '_id') {
+      const of = oldFields._id;
+      if (of !== undefined && declaredType(of) !== declaredType(nf)) {
+        errors.push(`_id 主键类型变更不支持（${declaredType(of)} → ${declaredType(nf)}）`);
+      }
+      const oStrat = of && typeof of === 'object' ? of.strategy : undefined;
+      const nStrat = nf && typeof nf === 'object' ? nf.strategy : undefined;
+      if (oStrat !== nStrat) {
+        errors.push(`_id 主键策略变更不支持（${JSON.stringify(oStrat)} → ${JSON.stringify(nStrat)}）`);
+      }
+      continue;
+    }
+    const nfType = declaredType(nf);
+    if (!(name in oldFields)) {
+      if (!Object.prototype.hasOwnProperty.call(TYPES, nfType) && !NON_COLUMN.includes(nfType)) {
+        errors.push(`新列 "${name}" 类型 ${JSON.stringify(nfType)} 未知`);
+        continue;
+      }
+      changes.push({
+        op: 'addColumn', name,
+        field: nf && typeof nf === 'object' ? nf : { type: nf },
+      });
+      continue;
+    }
+    const of = oldFields[name];
+    const ofType = declaredType(of);
+    if (ofType === nfType) continue; // 恒等：不上报
+    if (nfType && (WIDEN[ofType] || []).includes(nfType)) {
+      changes.push({ op: 'widenColumn', name, from: ofType, to: nfType });
+    } else {
+      errors.push(
+        `字段 "${name}" 类型 ${JSON.stringify(ofType)} → ${JSON.stringify(nfType)} 非放宽变更`
+        + '（首批仅支持单向放宽：int→long/float/double、long→float/double、float→double）');
+    }
+  }
+  for (const name of Object.keys(oldFields)) {
+    if (!(name in newFields)) {
+      errors.push(`删除字段 "${name}" 不支持（破坏性变更；请显式走数据迁移脚本）`);
+    }
+  }
+
+  const indexKeys = (defn) => (defn.indexes || [])
+    .filter((ix) => ix && typeof ix === 'object' && ix.keys
+      && typeof ix.keys === 'object' && Object.keys(ix.keys).length);
+  const oldIdx = indexKeys(oldDefn);
+  for (const ix of indexKeys(newDefn)) {
+    if (!oldIdx.some((o) => JSON.stringify(o) === JSON.stringify(ix))) {
+      changes.push({ op: 'addIndex', index: ix });
+    }
+  }
+
+  const oldColl = oldDefn.collection || oldDefn.name;
+  const newColl = newDefn.collection || newDefn.name;
+  if (oldColl !== newColl) {
+    errors.push(`collection 改名不支持（${JSON.stringify(oldColl)} → ${JSON.stringify(newColl)}；破坏性变更）`);
+  }
+  return { changes, errors };
+}
+
+/** 新旧 schema def → 迁移 SQL 文本列表（per-dialect；只产文本、不执行） */
+function generateMigration(backend, oldDefn, newDefn) {
+  if (!BACKENDS.includes(backend)) {
+    throw new Error(`迁移生成：不支持的后端 ${JSON.stringify(backend)}（支持 ${BACKENDS.join('/')}）`);
+  }
+  const plan = diffDefs(oldDefn, newDefn);
+  if (plan.errors.length) {
+    throw new Error(
+      'MIGRATION_UNSUPPORTED: ' + plan.errors.join('；')
+      + '（首批白名单：加表/加列/类型放宽/加索引；破坏性变更请走显式数据迁移脚本）');
+  }
+
+  const table = newDefn.collection || newDefn.name;
+  const stmts = [];
+  const order = { addColumn: 0, widenColumn: 1, addIndex: 2 };
+  for (const ch of [...plan.changes].sort((a, b) => (order[a.op] ?? 9) - (order[b.op] ?? 9))) {
+    if (ch.op === 'addTable') {
+      stmts.push(createTable(newDefn, backend));
+      stmts.push(...indexStmts(newDefn, backend));
+      const arch = archiveDefnOf(newDefn);
+      stmts.push(createTable(arch, backend));
+      stmts.push(...indexStmts(arch, backend));
+    } else if (ch.op === 'addColumn') {
+      const ftype = declaredType(ch.field);
+      const colType = fieldSqlType(backend, ch.field);
+      const deflt = ch.field && typeof ch.field === 'object' ? ch.field.default : undefined;
+      let colSql = `${q(backend, ch.name)} ${colType}`;
+      if (deflt !== undefined && deflt !== null) {
+        if (NON_COLUMN.includes(ftype)) {
+          throw new Error(
+            `MIGRATION_UNSUPPORTED: 新列 "${ch.name}"（object/array JSON 列）不支持 DEFAULT`
+            + '（存量行缺失语义由 __present 哨兵表达；default 仅影响新写入）');
+        }
+        colSql += ` DEFAULT ${sqlLiteral(deflt)}`;
+      }
+      stmts.push(`ALTER TABLE ${q(backend, table)} ADD COLUMN ${colSql}`);
+      stmts.push(`ALTER TABLE ${q(backend, `${table}_deleted`)} ADD COLUMN ${colSql}`);
+    } else if (ch.op === 'widenColumn') {
+      const colType = fieldSqlType(backend, newDefn.fields[ch.name]);
+      if (backend === 'sqlite') {
+        throw new Error(
+          'MIGRATION_UNSUPPORTED: SQLite 不支持类型变更 '
+          + `（${ch.from} → ${ch.to} 需重建表）；加列/加索引/加表已支持`);
+      }
+      if (backend === 'mysql') {
+        stmts.push(`ALTER TABLE ${q(backend, table)} MODIFY COLUMN ${q(backend, ch.name)} ${colType}`);
+      } else {
+        stmts.push(
+          `ALTER TABLE ${q(backend, table)} ALTER COLUMN ${q(backend, ch.name)} `
+          + `TYPE ${colType} USING ${q(backend, ch.name)}::${colType}`);
+      }
+    } else if (ch.op === 'addIndex') {
+      stmts.push(...indexStmts({ collection: table, indexes: [ch.index] }, backend));
+    } else {
+      throw new Error(`MIGRATION_UNSUPPORTED: 未知变更 ${ch.op}`);
+    }
+  }
+  return stmts;
+}
+
+module.exports = { generate, diffDefs, generateMigration };

package/src/feedback.js

@@ -23,6 +23,11 @@ function setSink(fn) {
   _sink = typeof fn === 'function' ? fn : null;
 }
 
+/** 当前 sink（无则 null）——供接管方（如 ask 编排器）保存/恢复现场 */
+function getSink() {
+  return _sink;
+}
+
 /** 产出一条反馈事件：有 sink 回调之；否则打印 stderr（允许拦截，禁止静默） */
 function emit(event) {
   const e = event || {};
@@ -36,4 +41,4 @@ function emit(event) {
   );
 }
 
-module.exports = { setSink, emit };
+module.exports = { setSink, getSink, emit };

package/src/index.js

@@ -21,8 +21,7 @@
  *   const items = await store.query('Model($condition:@c0) { field1, field2 }', { c0: {} });
  */
 
-const { AsyncLocalStorage } = require('node:async_hooks');
-
+const ask = require('./ask');
 const crud = require('./crud');
 const datasource = require('./datasource');
 const { Session, NonAtomicWriteError } = require('./datasource');
@@ -30,32 +29,12 @@ const ddl = require('./ddl');
 const executors = require('./executors');
 const feedback = require('./feedback');
 const introspect = require('./introspect');
+const llm = require('./llm');
 const permission = require('./permission');
+const { text2query } = require('./profile');
 const schema = require('./schema');
 const { syncSchema } = require('./sync');
-
-/** 档位 AsyncLocalStorage：记录「进入 text2query 前的原档」，供退出恢复（嵌套安全） */
-const _profileAls = new AsyncLocalStorage();
-
-/**
- * 以 text2query 档执行（功能收缩 + 硬限制），退出恢复原档位。
- *
- * AI 问数链路入口；与 permission.scopedRoles 同构（token-set/reset，嵌套安全）。
- * 档位是 core 进程级状态（非本 ALS 隔离），ALS 仅记录「进入时的原档」以便正确恢复，
- * 使异步 / 嵌套调用各自回到自己进入前的档位。进入档位即等效强制携带用户上下文
- * （core `ensureProfileCtx`，见执行文档 §4.2）。
- */
-async function text2query(fn) {
-  const prev = schema.getProfile();
-  schema.setProfile('text2query');
-  return _profileAls.run(prev, async () => {
-    try {
-      return await fn();
-    } finally {
-      schema.setProfile(prev);
-    }
-  });
-}
+const workflow = require('./workflow');
 
 class Store {
   // ── Schema 管理 ──
@@ -233,6 +212,30 @@ class Store {
     return ddl.generate(backend, names);
   }
 
+  // ── 工作流编排（首批：线性 + when 守卫 + fail-fast；见 workflow.js 与设计文档）──
+  /** 注册工作流定义（注册即静态校验，白名单外显式 Err 含 WORKFLOW_UNSUPPORTED） */
+  registerWorkflow(defn) {
+    return workflow.register(defn);
+  }
+
+  /** 全部可见工作流名（read 白名单过滤） */
+  workflows(ctx) {
+    return workflow.list(ctx);
+  }
+
+  /** 按名取工作流定义（read 白名单过滤；不可见与不存在同形——防枚举） */
+  getWorkflow(name, ctx) {
+    return workflow.get(name, ctx);
+  }
+
+  /**
+   * 触发工作流 → 完整 run 文档
+   * （终态 failed/rejected 不抛错，以 run.status + error 表达；dryRun 下 mutation/fail 记 wouldRun）
+   */
+  async runWorkflow(name, input, opts) {
+    return workflow.run(name, input ?? null, opts);
+  }
+
   // ── 底层工具（调试/高级用法） ──
   /** 解析 GQL 并构建 pipeline，返回 `{tokens, ast, pipeline, projection}` */
   buildPipeline(gql, params) {
@@ -273,6 +276,23 @@ class Store {
     return text2query(fn);
   }
 
+  // ── AI 问数（L1，对齐 py-store store.ask / store.describe_for_ai）──
+  /**
+   * AI 问数唯一入口（LLM 输出永远当不可信输入；护栏面服务端硬编码，详见 ask.js）
+   *
+   * @param {string} question 自然语言问题
+   * @param {{llm: (string|Function), ctx: object, maxRetries?: number, knowledge?: string}} opts
+   * @returns {Promise<ask.AskResult>}
+   */
+  ask(question, opts) {
+    return ask.ask(question, opts);
+  }
+
+  /** 输出 LLM 可读的 schema 摘要（权限过滤后的紧凑 JSON 数组；详见 ask.js） */
+  describeForAi(ctx = null) {
+    return ask.describeForAi(ctx);
+  }
+
   /** 设置数据源连接映射（多后端路由；对齐 py-store store.set_connections） */
   setConnections(connections) {
     return datasource.setConnections(connections);
@@ -299,6 +319,44 @@ class Store {
   async runAsInternal(fn) {
     return permission.runAsInternal(fn);
   }
+
+  // ── RBAC 动态策略（判决唯一在 core；本层仅透传配置与查询面） ──
+  setRbac(policy) {
+    return permission.setRbac(policy);
+  }
+
+  rbacEnabled() {
+    return permission.rbacEnabled();
+  }
+
+  rbacCan(model, action, ctx) {
+    return permission.rbacCan(model, action, ctx);
+  }
+
+  rbacReadableFields(model, ctx) {
+    return permission.rbacReadableFields(model, ctx);
+  }
+
+  rbacWritableFields(model, ctx) {
+    return permission.rbacWritableFields(model, ctx);
+  }
+
+  rbacRowCondition(model, action, ctx) {
+    return permission.rbacRowCondition(model, action, ctx);
+  }
+
+  // ── 角色清单与未配置姿态（清单化语义，判决唯一在 core；本层仅透传配置） ──
+  setExemptRoles(roles) {
+    return permission.setExemptRoles(roles);
+  }
+
+  setDenyWriteRoles(roles) {
+    return permission.setDenyWriteRoles(roles);
+  }
+
+  setUnconfiguredPolicy(policy) {
+    return permission.setUnconfiguredPolicy(policy);
+  }
 }
 
 /** 自定义权限错误（实例可被 store.PermissionError 捕获） */
@@ -309,6 +367,10 @@ Store.prototype.ProfileViolation = crud.ProfileViolation;
 Store.prototype.RawSqlError = datasource.RawSqlError;
 /** 原生 Mongo 命令入口错误（实例可被 store.NativeCommandError 捕获） */
 Store.prototype.NativeCommandError = datasource.NativeCommandError;
+/** AI 问数重试耗尽（实例可被 store.AskExhausted 捕获，携带 .attempts / .events 全轨迹） */
+Store.prototype.AskExhausted = ask.AskExhausted;
+/** AI 问数成功结果（store.ask 的返回类型） */
+Store.prototype.AskResult = ask.AskResult;
 
 const store = new Store();
 
@@ -416,4 +478,12 @@ module.exports = {
   feedback,
   introspect,
   syncSchema,
+  workflow,
+  WorkflowError: workflow.WorkflowError,
+  // ── AI 问数（L1）：编排器 + schema 摘要 + LLM 插拔注册表（对齐 py-store ask/llm）──
+  ask: ask.ask,
+  describeForAi: ask.describeForAi,
+  AskResult: ask.AskResult,
+  AskExhausted: ask.AskExhausted,
+  llm,
 };

package/src/llm.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * 插拔式 LLM 注册表 —— 《AI能力接入设计-L1问数档.md》§4.2 决策 D6（M2 nodejs-store parity）
+ *
+ * 协议（唯一）：`async function llm(messages: Array<{role, content}>) => string`
+ * nodejs-store 不引入任何 LLM SDK（依赖由宿主应用决定）；护栏在 core/Host 不在 LLM，
+ * 能力开关只影响首次命中率，不影响正确性。
+ *
+ * 插拔三件套（对齐 py_store.llm 同名件）：
+ *   - registerLlm()       注册；client 为符合协议的函数（测试注入假 LLM 同走此口）；
+ *                         同名重复注册显式报错（禁静默覆盖）
+ *   - getLlm()            按名取用；未注册显式报错（禁静默回落默认厂商）
+ *   - makeOpenaiCompat()  OpenAI 兼容通用工厂（Node 18+ 全局 fetch，零依赖）：
+ *                         一个实现覆盖 DeepSeek/OpenAI/Moonshot/SiliconFlow/Ollama 等
+ *                         兼容端点；Anthropic 原生等特殊协议由应用侧自行 make 后注册，
+ *                         数据层不内置 SDK。
+ *
+ * 能力差异收敛为工厂开关（同 py）：
+ *   - jsonMode=false：不传 response_format，退化路径 = prompt 约定 + ask() 严格
+ *     JSON 解析失败回喂（D3）；
+ *   - effort=null：不传 reasoning_effort（非推理模型或不支持该参数的端点）。
+ *
+ * 实测接入事实（py 侧原型实证，直接继承；见设计文档 §4.2「三个接入事实」）：
+ *   1. DeepSeek 网关对默认 UA 断连（curl 同参 200 实证）→ 显式覆盖 User-Agent
+ *      （fetch 默认 UA 为 `node`，同理覆盖）；
+ *   2. json_object 模式要求 prompt 含 "json" 字样，缺失时网关 400 → 工厂契约预检，
+ *      缺失即抛 llmJsonPromptMissing（禁静默替调用方改写消息面，no-error-masking）；
+ *   3. 网络层断连/超时 → llmNetworkError；HTTP 4xx/5xx → llmHttpError（携状态码
+ *      与响应体片段）；空 content（多为推理 token 耗尽 max_tokens）→ llmEmptyContent
+ *      （携 finish_reason 与推理 token 数，禁静默返回空串）。
+ *      三者均以 LlmError（Error 子类，.detail 携结构化对象）抛出，ask() 原样穿透
+ *      （不回喂、不降级）——对齐 py 侧 RuntimeError(dict) 的「异常本体携带结构化详情」。
+ */
+
+const _REGISTRY = new Map();
+
+/**
+ * LLM 客户端自身的结构化失败（网络 / HTTP / 契约预检 / 空 content）
+ *
+ * .detail 为结构化对象（code 稳定、其余字段如实），message 内嵌序列化详情——
+ * 上游不读属性也能看到失败原因（对齐 AskExhausted 的消息形态）。
+ */
+class LlmError extends Error {
+  constructor(detail) {
+    super(`${(detail && detail.code) || 'llmError'}: ${JSON.stringify(detail)}`);
+    this.name = 'LlmError';
+    this.detail = detail;
+  }
+}
+
+/** 注册一个 LLM 客户端；同名重复注册显式报错（禁静默覆盖） */
+function registerLlm(name, client) {
+  if (typeof name !== 'string' || !name) {
+    throw new TypeError('registerLlm(name, client) 需要非空字符串注册名');
+  }
+  if (typeof client !== 'function') {
+    throw new TypeError('LLM 客户端必须是符合协议的函数：async (messages) => string');
+  }
+  if (_REGISTRY.has(name)) {
+    throw new Error(`LLM 客户端重复注册: ${name}`);
+  }
+  _REGISTRY.set(name, client);
+}
+
+/** 按注册名取客户端；未注册显式报错（禁静默回落默认厂商） */
+function getLlm(name) {
+  if (!_REGISTRY.has(name)) {
+    throw new Error(`LLM 客户端未注册: ${String(name)}（已注册: ${[..._REGISTRY.keys()].sort().join(', ') || '（无）'}）`);
+  }
+  return _REGISTRY.get(name);
+}
+
+/**
+ * OpenAI 兼容端点通用工厂（返回符合协议的 async llm；Node 18+ 全局 fetch，零依赖）。
+ *
+ * 失败全部显式抛 LlmError（.detail 结构化），禁静默返回空串——
+ * 空 content 的实证成因与防御见模块 docstring 与设计文档 W3。
+ */
+function makeOpenaiCompat({
+  baseUrl,
+  model,
+  apiKey,
+  jsonMode = true,
+  effort = 'low',
+  maxTokens = 4096,
+  timeoutMs = 90000,
+} = {}) {
+  if (typeof baseUrl !== 'string' || !baseUrl.trim()) {
+    throw new TypeError('makeOpenaiCompat 需要非空 baseUrl');
+  }
+  if (typeof model !== 'string' || !model) {
+    throw new TypeError('makeOpenaiCompat 需要非空 model');
+  }
+
+  async function llm(messages) {
+    const body = { model, messages, max_tokens: maxTokens };
+    if (jsonMode) {
+      // 契约预检：json_object 要求 prompt 含 "json" 字样（DeepSeek 实测 400 实证）。
+      // 缺失显式报错交上游装配修复，禁静默改写调用方消息面（no-error-masking）
+      const joined = messages.map((m) => String((m && m.content) ?? '')).join(' ').toLowerCase();
+      if (!joined.includes('json')) {
+        throw new LlmError({
+          code: 'llmJsonPromptMissing',
+          model,
+          message: "json_mode=true 要求 messages（system/user）中包含 'json' 字样",
+          hint: "ask() 的 system 输出契约模板已固定含 'JSON' 措辞；自定义 knowledge 时须保留",
+        });
+      }
+      body.response_format = { type: 'json_object' };
+    }
+    if (effort !== null && effort !== undefined) {
+      body.reasoning_effort = effort;
+    }
+
+    let resp;
+    try {
+      resp = await fetch(`${baseUrl.replace(/\/+$/, '')}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+          // 默认 UA「node」被 DeepSeek 网关断连（py 侧 urllib 同因实证），显式覆盖
+          'User-Agent': 'nodejs-store-ask/0.1',
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (e) {
+      // 网络层断连 / 超时 / 重置，结构化暴露（不吞错、不重试）
+      throw new LlmError({ code: 'llmNetworkError', model, detail: String((e && e.message) || e) });
+    }
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => '');
+      throw new LlmError({ code: 'llmHttpError', status: resp.status, model, body: String(text).slice(0, 500) });
+    }
+    const data = await resp.json();
+    const choice = (Array.isArray(data.choices) && data.choices[0]) || {};
+    const content = choice.message ? choice.message.content : undefined;
+    if (!content) {
+      throw new LlmError({
+        code: 'llmEmptyContent',
+        model,
+        finish_reason: choice.finish_reason ?? null,
+        reasoning_tokens: (data.usage && data.usage.completion_tokens_details)
+          ? (data.usage.completion_tokens_details.reasoning_tokens ?? null)
+          : null,
+        message: 'LLM 返回空 content（多为 max_tokens 被推理耗尽，调大 max_tokens 或降 effort）',
+      });
+    }
+    return content;
+  }
+
+  return llm;
+}
+
+module.exports = { LlmError, registerLlm, getLlm, makeOpenaiCompat, _registry: _REGISTRY };

package/src/permission.js

@@ -36,6 +36,18 @@ function scopedRoles(roles, fn) {
   return _als.run(next, () => fn());
 }
 
+/**
+ * 以完整上下文 ctx 进入临时权限上下文（嵌套安全），执行 fn 后自动恢复原上下文。
+ *
+ * 对齐 py_store.permission.scoped_context；与 scopedRoles 同构，区别在于整体替换
+ * ctx（保留调用方原上下文于外层），供 AI 问数（ask）等把服务端构造的用户上下文
+ * 显式注入执行面的场景——不用「setContext + finally 清空」写法（嵌套时误清外层，
+ * 静默失守方向）。
+ */
+function scopedContext(ctx, fn) {
+  return _als.run(ctx ?? null, () => fn());
+}
+
 /** 在内部上下文中执行操作（绕过权限检查），结束后自动恢复上下文 */
 async function runAsInternal(fn) {
   const prev = getContext();
@@ -76,6 +88,11 @@ function getReadableRelations(schema, ctx) {
   return core.readableRelations(_model(schema), ctx ?? null);
 }
 
+/** 角色可读计算列集（列级白名单；core 未导出该判决的旧绑定上为 undefined） */
+function getReadableComputes(schema, ctx) {
+  return core.readableComputes(_model(schema), ctx ?? null);
+}
+
 function getWritableFields(schema, ctx) {
   return core.writableFields(_model(schema), ctx ?? null);
 }
@@ -84,6 +101,52 @@ function filterWritableData(schema, ctx, data) {
   return core.filterWritableData(_model(schema), ctx ?? null, data);
 }
 
+// ─── RBAC 动态策略（core 判决；本模块零判决，仅透传，对齐 py_store.permission） ──
+
+/** 注入/清除 RBAC 策略。object = 注入（解析失败 core 抛错）；null = 清除关闭 */
+function setRbac(policy) {
+  return core.setRbac(policy ?? null);
+}
+
+/** RBAC 策略是否已注入 */
+function rbacEnabled() {
+  return core.rbacEnabled();
+}
+
+/** RBAC 动作判决：action ∈ {read, insert, update, remove}；RBAC 不介入 → true */
+function rbacCan(model, action, ctx) {
+  return core.rbacCan(_model(model), action, ctx ?? null);
+}
+
+/** RBAC 叠加后的可读字段集（静态 ∩ readFields）；无 ctx → null 不裁剪 */
+function rbacReadableFields(model, ctx) {
+  return core.rbacReadableFields(_model(model), ctx ?? null);
+}
+
+/** RBAC 叠加后的可写字段集（静态 ∩ writeFields）；无 ctx → null 不裁剪 */
+function rbacWritableFields(model, ctx) {
+  return core.rbacWritableFields(_model(model), ctx ?? null);
+}
+
+/** RBAC 行级条件（ownerOnly/condition 的 OR 合并体）；action ∈ {read, update, remove} */
+function rbacRowCondition(model, action, ctx) {
+  return core.rbacRowCondition(_model(model), action, ctx ?? null);
+}
+
+// ── 角色清单与未配置姿态（清单化语义，判决唯一在 core；本层仅透传） ──
+
+function setExemptRoles(roles) {
+  return core.setExemptRoles(roles);
+}
+
+function setDenyWriteRoles(roles) {
+  return core.setDenyWriteRoles(roles);
+}
+
+function setUnconfiguredPolicy(policy) {
+  return core.setUnconfiguredPolicy(policy);
+}
+
 // ─── 自定义错误 ──────────────────────────────────────────────
 
 class PermissionError extends Error {
@@ -96,8 +159,10 @@ class PermissionError extends Error {
 
 module.exports = {
   setContext,
+  _als,
   getContext,
   scopedRoles,
+  scopedContext,
   runAsInternal,
   canReadSchema,
   canWriteSchema,
@@ -105,7 +170,17 @@ module.exports = {
   mergeOwnerCondition,
   getReadableFields,
   getReadableRelations,
+  getReadableComputes,
   getWritableFields,
   filterWritableData,
+  setRbac,
+  rbacEnabled,
+  rbacCan,
+  rbacReadableFields,
+  rbacWritableFields,
+  rbacRowCondition,
+  setExemptRoles,
+  setDenyWriteRoles,
+  setUnconfiguredPolicy,
   PermissionError,
 };

package/src/profile.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * 查询档位上下文 —— text2query 便捷上下文
+ *
+ * 自 index.js 提取为独立模块（ask.js 需硬编码进入 text2query 档，直接依赖本模块
+ * 而非包入口，避免循环 require）；对 index.js 的导出面零变化（index.js re-export）。
+ *
+ * 档位 AsyncLocalStorage：记录「进入 text2query 前的原档」，供退出恢复（嵌套安全）。
+ * 与 permission.scopedRoles 同构（token-set/reset，嵌套安全）。
+ * 档位是 core 进程级状态（非本 ALS 隔离），ALS 仅记录「进入时的原档」以便正确恢复，
+ * 使异步 / 嵌套调用各自回到自己进入前的档位。进入档位即等效强制携带用户上下文
+ * （core `ensureProfileCtx`，见执行文档 §4.2）。
+ */
+
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+const { getProfile, setProfile } = require('./schema');
+
+const _profileAls = new AsyncLocalStorage();
+
+/** 以 text2query 档执行 fn，退出恢复原档位（AI 问数链路入口） */
+async function text2query(fn) {
+  const prev = getProfile();
+  setProfile('text2query');
+  return _profileAls.run(prev, async () => {
+    try {
+      return await fn();
+    } finally {
+      setProfile(prev);
+    }
+  });
+}
+
+module.exports = { text2query, _profileAls };