@yss123/cage-cli 0.2.0 → 0.3.1

package/templates/app/docs/errors/CAGE-REG-001.md

@@ -34,20 +34,21 @@ export * from './inventory.js'; export * from './purchase-order.js';
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/kernel.ts:113`
-- `packages/kernel/src/registry.ts:153`
-- `packages/kernel/src/registry.ts:159`
-- `packages/kernel/src/registry.ts:164`
-- `packages/kernel/src/registry.ts:168`
-- `packages/kernel/src/registry.ts:172`
-- `packages/kernel/src/registry.ts:190`
+- `packages/approval/src/route.ts:231`
+- `packages/kernel/src/kernel.ts:161`
+- `packages/kernel/src/registry.ts:209`
+- `packages/kernel/src/registry.ts:215`
+- `packages/kernel/src/registry.ts:220`
+- `packages/kernel/src/registry.ts:234`
+- `packages/kernel/src/registry.ts:238`
+- `packages/kernel/src/registry.ts:268`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-    if (!rc) {
-      throw new Error(`[CAGE-REG-001] 找不到命令 ${typeof ref === 'string' ? ref : ref.agg.name + '.?'}，它是否从 domain 导出了？`);
-    }
-    return rc;
-  }
+        for (const query of s.context.queries ?? []) if (!registry.queries.some(q => q.name === query))
+          throw declError('CAGE-REG-001', `AI 步骤引用的查询 ${query} 未导出`);
+      }
+    },
+  });
 ```

package/templates/app/docs/errors/CAGE-REG-002.md

@@ -34,8 +34,9 @@ aggregate('PurchaseOrder', ...)、aggregate('Inventory', ...)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/registry.ts:88`
+- `packages/kernel/src/registry.ts:134`
 - `packages/kernel/src/registry.ts:176`
+- `packages/kernel/src/registry.ts:242`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-REG-003.md

@@ -34,7 +34,7 @@ name: 'submit' 与 name: 'cancel'
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/registry.ts:156`
+- `packages/kernel/src/registry.ts:212`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-REL-001.md

@@ -39,26 +39,26 @@ list({ members: manyToMany('User') }); // JSON 明细中不能声明关系
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/aggregate.ts:97`
-- `packages/kernel/src/primitives/event.ts:20`
-- `packages/kernel/src/primitives/fields.ts:94`
-- `packages/kernel/src/primitives/fields.ts:99`
-- `packages/kernel/src/primitives/fields.ts:105`
-- `packages/kernel/src/primitives/fields.ts:110`
-- `packages/kernel/src/primitives/fields.ts:167`
-- `packages/kernel/src/primitives/fields.ts:174`
-- `packages/kernel/src/primitives/fields.ts:193`
-- `packages/kernel/src/registry.ts:137`
-- `packages/kernel/src/registry.ts:141`
-- `packages/kernel/src/registry.ts:147`
-- `packages/kernel/src/registry.ts:155`
+- `packages/kernel/src/primitives/aggregate.ts:188`
+- `packages/kernel/src/primitives/event.ts:50`
+- `packages/kernel/src/primitives/fields.ts:190`
+- `packages/kernel/src/primitives/fields.ts:196`
+- `packages/kernel/src/primitives/fields.ts:203`
+- `packages/kernel/src/primitives/fields.ts:209`
+- `packages/kernel/src/primitives/fields.ts:277`
+- `packages/kernel/src/primitives/fields.ts:284`
+- `packages/kernel/src/primitives/fields.ts:335`
+- `packages/kernel/src/registry.ts:193`
+- `packages/kernel/src/registry.ts:197`
+- `packages/kernel/src/registry.ts:203`
+- `packages/kernel/src/registry.ts:211`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
     if (f && f !== 'id' && !(f in fields)) throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
     if (f && f !== 'id' && isRelation(fields[f])) throw declError('CAGE-REL-001', `${name} 的范围字段必须是主表列，不能使用集合关系 ${f}`);
+    if (f && f !== 'id' && isFile(fields[f])) throw declError('CAGE-FILE-001', `${name} 的范围字段不能使用文件 ${f}`);
   }
   const scope: ScopeSpec = Object.freeze({ ...sc, ownerField });
-
 ```

package/templates/app/docs/errors/CAGE-ROUTE-001.md

@@ -34,14 +34,15 @@ app.post('/api/order/submit', handler)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/lint/src/rules/no-manual-routes.ts:11`
+- `packages/lint/src/rules/no-manual-routes.ts:3`
+- `packages/lint/src/rules/no-manual-routes.ts:23`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-    docs: { description: '禁止在业务项目里手写 HTTP 路由' },
-    messages: { route: '[CAGE-ROUTE-001] 不要手写路由 {{call}}：在 domain 里声明命令或查询，路由由框架生成' },
-    schema: [],
-  },
-  create(context) {
+ * 检查业务代码是否绕过声明直接注册 HTTP 路由。
+ * 通过常见接收器名、HTTP 方法和路径形状识别调用，命中返回 CAGE-ROUTE-001。
+ * 这是有界语法检查，不解析任意变量别名或运行时动态路由；框架自己的 HTTP 实现由其维护边界管理。
+ */
+// 业务项目里禁止手写 HTTP 路由：没有声明就没有路由，所有写入都经过内核
 ```

package/templates/app/docs/errors/CAGE-SCOPE-001.md

@@ -34,7 +34,7 @@ combinator: '部门及下级'
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/scope/index.ts:66`
+- `packages/kernel/src/scope/index.ts:67`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-SCOPE-002.md

@@ -34,7 +34,7 @@ scope.deptSubtree('departmentId')，fields 只有 deptId
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/aggregate.ts:96`
+- `packages/kernel/src/primitives/aggregate.ts:187`
 
 实现片段（位置随框架版本更新）：
 
@@ -42,6 +42,6 @@ scope.deptSubtree('departmentId')，fields 只有 deptId
   for (const f of [sc.deptField, ownerField]) {
     if (f && f !== 'id' && !(f in fields)) throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
     if (f && f !== 'id' && isRelation(fields[f])) throw declError('CAGE-REL-001', `${name} 的范围字段必须是主表列，不能使用集合关系 ${f}`);
+    if (f && f !== 'id' && isFile(fields[f])) throw declError('CAGE-FILE-001', `${name} 的范围字段不能使用文件 ${f}`);
   }
-  const scope: ScopeSpec = Object.freeze({ ...sc, ownerField });
 ```

package/templates/app/docs/errors/CAGE-SECRET-001.md

@@ -34,8 +34,8 @@ secret: 'ERP_API_TOKEN'，运行环境提供该变量
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/runtime.ts:22`
-- `packages/http/src/routes.ts:74`
+- `packages/connectors/src/runtime.ts:25`
+- `packages/http/src/routes.ts:88`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-SECRET-002.md

@@ -34,7 +34,7 @@ verify: hmacSha256('ERP_WEBHOOK_SECRET')
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/lint/src/rules/no-secret-literal.ts:19`
+- `packages/lint/src/rules/no-secret-literal.ts:34`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-SENS-001.md

@@ -34,15 +34,15 @@ event('OrderChanged', { phone: text().sensitive('phone') })
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/rules.ts:114`
-- `packages/cli/src/rules.ts:128`
+- `packages/cli/src/rules.ts:144`
+- `packages/cli/src/rules.ts:163`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
 
 /** CAGE-SENS-001：敏感字段不得原样进入事件载荷 */
-export function checkSensitiveEvents(g: Ontology): Finding[] {
-  const { get, out } = index(g);
-  const findings: Finding[] = [];
+/**
+ * 检查事件同名载荷字段是否保留聚合敏感标记。
+ * @param g 当前图。
 ```

package/templates/app/docs/errors/CAGE-SQL-001.md

@@ -34,7 +34,7 @@ sql: 'select id from safe.purchase_order where status = :status'
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/lint/src/rules/no-sql-concat.ts:19`
+- `packages/lint/src/rules/no-sql-concat.ts:32`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-SQL-002.md

@@ -34,7 +34,7 @@ sql.raw(input.orderBy)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/lint/src/rules/no-sql-concat.ts:20`
+- `packages/lint/src/rules/no-sql-concat.ts:33`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-STATE-001.md

@@ -34,9 +34,9 @@ to: 'finished'，状态集中只有 done
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/command.ts:130`
-- `packages/kernel/src/primitives/command.ts:138`
-- `packages/kernel/src/primitives/states.ts:29`
+- `packages/kernel/src/primitives/command.ts:228`
+- `packages/kernel/src/primitives/command.ts:236`
+- `packages/kernel/src/primitives/states.ts:59`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-STATE-002.md

@@ -34,7 +34,7 @@ states()
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/states.ts:22`
+- `packages/kernel/src/primitives/states.ts:52`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-STATE-003.md

@@ -34,7 +34,7 @@ states('PendingApproval', '已完成')
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/states.ts:24`
+- `packages/kernel/src/primitives/states.ts:54`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-STATE-004.md

@@ -34,7 +34,7 @@ states('draft', 'draft')
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/states.ts:26`
+- `packages/kernel/src/primitives/states.ts:56`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-STATE-005.md

@@ -34,8 +34,9 @@ fields: { stage: POStatus }，或 states 与 fields.status 同时提供
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/aggregate.ts:78`
-- `packages/kernel/src/primitives/aggregate.ts:79`
+- `packages/kernel/src/primitives/aggregate.ts:169`
+- `packages/kernel/src/primitives/aggregate.ts:170`
+- `packages/kernel/src/primitives/states.ts:62`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-STATE-010.md

@@ -34,15 +34,15 @@ states 包含 received，却没有任何命令迁移到它
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/rules.ts:67`
-- `packages/cli/src/rules.ts:93`
+- `packages/cli/src/rules.ts:92`
+- `packages/cli/src/rules.ts:123`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
 
 /** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
-export function checkStates(g: Ontology): Finding[] {
-  const { get } = index(g);
-  const findings: Finding[] = [];
+/**
+ * 从新建或初始状态计算可达性，并检查非终态出边。
+ * @param g 当前图。
 ```

package/templates/app/docs/errors/CAGE-STATE-011.md

@@ -34,15 +34,15 @@ states('draft', 'done', { terminal: ['done'] })，draft 有提交路径
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/rules.ts:67`
-- `packages/cli/src/rules.ts:102`
+- `packages/cli/src/rules.ts:92`
+- `packages/cli/src/rules.ts:132`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
 
 /** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
-export function checkStates(g: Ontology): Finding[] {
-  const { get } = index(g);
-  const findings: Finding[] = [];
+/**
+ * 从新建或初始状态计算可达性，并检查非终态出边。
+ * @param g 当前图。
 ```

package/templates/app/docs/errors/CAGE-STRUCT-001.md

@@ -38,7 +38,7 @@ packages/domain/src/expense.ts
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/project-structure.ts:58`
+- `packages/cli/src/project-structure.ts:74`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-STRUCT-002.md

@@ -38,7 +38,7 @@ import { ExpensePage } from '../../modules/expense/pages/expense-page';
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/project-structure.ts:108`
+- `packages/cli/src/project-structure.ts:124`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-SYNC-001.md

@@ -34,8 +34,9 @@ sync --check 发现框架规则需更新，或 begin/end 标记缺失一边、
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/sync.ts:97`
-- `packages/cli/src/sync.ts:110`
+- `packages/cli/src/sync.ts:149`
+- `packages/cli/src/sync.ts:156`
+- `packages/cli/src/sync.ts:167`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-TEST-001.md

@@ -34,7 +34,7 @@
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/verify.ts:36`
+- `packages/cli/src/verify.ts:48`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-TEST-002.md

@@ -0,0 +1,50 @@
+# CAGE-TEST-002：派生测试准备或初始夹具失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：test / verify。
+
+派生测试在业务命令执行前无法构造合法夹具，或初始记录已经违反不变量。
+
+## 修复步骤
+
+1. 按 trace 的阶段、种子、fixture 和前置不变量修复准备数据；必要时提供业务 fixture。
+2. 使用相同随机种子重放；区分准备失败与合法初始状态下的真实业务反例，不放宽不变量。
+
+## 正例
+
+```text
+derived(domain, { seed: 20261103, /* 按公开类型提供合法 fixture */ })
+```
+
+## 反例
+
+```text
+初始预算已经不守恒，却报告命令破坏预算守恒
+```
+
+## 修复后验证
+
+确认当前运行退出码与 JSON 报告，分别报告通过、失败和跳过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/testkit/src/derived-diagnostics.ts:73`
+- `packages/testkit/src/derived-diagnostics.ts:77`
+- `packages/testkit/src/derived-diagnostics.ts:82`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+/**
+ * 携带结构化失败轨迹的测试异常，统一标识为 CAGE-TEST-002。
+ * 构造前由调用方脱敏 detail，消息序列化同一轨迹，phase/aggregate/seed 提供快速定位字段。
+ */
+export class DerivedTestError extends Error {
+```

package/templates/app/docs/errors/CAGE-TEST-003.md

@@ -0,0 +1,52 @@
+# CAGE-TEST-003：测试数据库目录归属不匹配
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：test / verify。
+
+临时 PostgreSQL 的目录、归属标记、实际 data_directory 或端口与本次启动实例不符。
+
+## 修复步骤
+
+1. 保留诊断并核对本次测试自己的实例；修复路径或生命周期后重新运行。
+2. 已有目录明确使用 persistent: true；不删除未知目录、不按进程名批量终止 PostgreSQL。
+
+## 正例
+
+```text
+测试工具停止自己创建且验证归属的临时实例
+```
+
+## 反例
+
+```text
+将已有业务目录作为自动清理目录，或为了退出测试结束所有 postgres 进程
+```
+
+## 修复后验证
+
+确认当前运行退出码与 JSON 报告，分别报告通过、失败和跳过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/testkit/src/pg.ts:63`
+- `packages/testkit/src/pg.ts:65`
+- `packages/testkit/src/pg.ts:90`
+- `packages/testkit/src/pg.ts:96`
+- `packages/testkit/src/pg.ts:107`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const dir = resolve(opts.dir ?? mkdtempSync(join(tmpdir(), 'cage-pg-')));
+  if (dir === parse(dir).root) throw new Error('[CAGE-TEST-003] 内嵌 PostgreSQL 目录不能是文件系统根目录');
+  const fresh = !existsSync(join(dir, 'PG_VERSION'));
+  if (!persistent && !fresh) throw new Error('[CAGE-TEST-003] 不允许将已有 PostgreSQL 目录作为自动删除的临时实例；使用 persistent: true');
+  if (persistent) mkdirSync(dir, { recursive: true });
+```

package/templates/app/docs/errors/CAGE-UNSAFE-001.md

@@ -34,8 +34,9 @@ unsafe({ reason: '', owner: '' }, action)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/flow.ts:219`
-- `packages/lint/src/rules/unsafe-needs-reason.ts:8`
+- `packages/kernel/src/primitives/flow.ts:383`
+- `packages/lint/src/rules/unsafe-needs-reason.ts:10`
+- `packages/lint/src/rules/unsafe-needs-reason.ts:17`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-UPGRADE-001.md

@@ -34,8 +34,8 @@ command(A, { caller: 'user', invokedBy: 'process', ... })
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/upgrade.ts:45`
-- `packages/cli/src/upgrade.ts:58`
+- `packages/cli/src/upgrade.ts:60`
+- `packages/cli/src/upgrade.ts:79`
 
 实现片段（位置随框架版本更新）：
 

package/templates/app/docs/errors/CAGE-WORKER-001.md

@@ -0,0 +1,48 @@
+# CAGE-WORKER-001：缺少必要后台引擎
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+声明存在审批等必要消费者，但启动 worker 时没有提供相应引擎。
+
+## 修复步骤
+
+1. 按 domain 声明装配真实审批引擎和连接器运行环境，检查 worker manifest。
+2. 不要删除审批声明或把必需引擎缺失降级为警告。
+
+## 正例
+
+```text
+使用标准 createWorker 入口装配声明要求的审批引擎
+```
+
+## 反例
+
+```text
+带审批绑定的注册表启动时跳过审批引擎
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/consumers.ts:66`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (!engine) {
+      throw new Error(`[CAGE-WORKER-001] 审批绑定 ${name} 缺少流程 ${a.process} 的审批引擎；补齐路由或装配引擎后再启动 worker`);
+    }
+    out.push({
+      name: `approval:${name}:start`,
+```

package/templates/app/docs/errors/CAGE-WORKER-002.md

@@ -0,0 +1,50 @@
+# CAGE-WORKER-002：事件与消费者清单不匹配
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+worker 收到未知事件或缺少声明要求的消费者，消息不能静默完成。
+
+## 修复步骤
+
+1. 通过 doctor/timeline 核对 API 与 worker 的版本、注册指纹、消费者清单和心跳。
+2. 首阶段停止旧进程后同版本升级 API 与 worker，再检查死信并按允许方式恢复；不要直接修改 done 状态。
+
+## 正例
+
+```text
+更新匹配版本后重放死信，确认消费者处理证据
+```
+
+## 反例
+
+```text
+旧 worker 对新关键事件找不到消费者仍标记 done
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:289`
+- `packages/kernel/src/worker/outbox.ts:40`
+- `packages/kernel/src/worker/outbox.ts:106`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    async handle(row, tx, _kernel, prepared) {
+      if (!prepared) throw new Error('[CAGE-WORKER-002] 出站消费者必须经 worker prepare 阶段执行');
+      const result = prepared as OutboundPrepared;
+      if (result.skipped) return;
+      if (ob.onSuccess) {
+```

package/templates/app/docs/errors/CAGE-WORKER-003.md

@@ -0,0 +1,48 @@
+# CAGE-WORKER-003：后台任务未在停机时限内结束
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：worker 启动 / 投递 / 停机。
+
+停止接收新任务并取消外部 IO 后，在途任务仍超过退出时限。
+
+## 修复步骤
+
+1. 检查任务、网络超时和阻塞阶段；等待在途任务结束后再释放锁与连接。
+2. 核对恢复记录和远端幂等结果；不要在任务还执行时强行释放互斥锁。
+
+## 正例
+
+```text
+先停止领取，再等待并核对运行任务的退出结果
+```
+
+## 反例
+
+```text
+停机时直接关锁连接，允许第二个实例和旧任务同时执行
+```
+
+## 修复后验证
+
+核对同版本注册指纹、消费者清单、心跳和时间线，再验证投递及停机恢复。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/index.ts:269`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+        const timeout = setTimeout(() => {
+          state.lastError = `[CAGE-WORKER-003] 停机等待超时，在途任务：${snapshot().inFlight.join(', ')}`;
+          log.error({ err: state.lastError }, 'worker 停机超时；任务结束前保留锁和连接');
+          reject(new Error(state.lastError));
+        }, opts.shutdownTimeoutMs ?? 30_000);
+```