@yss123/cage-cli 0.2.0 → 0.3.0

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

@@ -0,0 +1,51 @@
+# CAGE-ENV-002：运行配置不满足安全边界
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init / migrate / 启动。
+
+生产启动缺少足够强的 Cookie 密钥，或服务配置中的认证并发、超时等参数无效。
+
+## 修复步骤
+
+1. 按诊断的配置项设置合法值；生产提供独立生成的随机 Cookie 密钥并重启服务。
+2. 只报告配置项名称和错误码，不输出密钥或整个环境文件。
+
+## 正例
+
+```text
+由受控环境变量提供随机 CAGE_COOKIE_SECRET，并设置有界认证并发及队列
+```
+
+## 反例
+
+```text
+生产继续使用固定开发 Cookie 密钥，或给并发上限填入无穷值
+```
+
+## 修复后验证
+
+重跑原先失败的命令，确认使用预期库与账号；输出脱敏信息。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/http/src/auth.ts:69`
+- `packages/http/src/auth.ts:72`
+- `packages/http/src/server.ts:111`
+- `packages/http/src/server.ts:115`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+  /** concurrency 是同时派生个数，queueLimit 是额外等待个数；非法配置在启动期抛 CAGE-ENV-002。 */
+  constructor(private readonly concurrency = 4, private readonly queueLimit = 32) {
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1 || !Number.isSafeInteger(queueLimit) || queueLimit < 0) {
+      throw new Error('[CAGE-ENV-002] passwordConcurrency 必须为正整数，passwordQueueLimit 必须为非负整数');
+```

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

@@ -0,0 +1,48 @@
+# CAGE-ENV-003：服务启动不能隐式初始化组织
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init / migrate / 启动。
+
+createServer 显式传入 bootstrap: true。初始化不能混入日常服务启动并输出密码。
+
+## 修复步骤
+
+1. 移除启动参数中的 bootstrap: true；先审查执行迁移，再显式执行 cage bootstrap。
+2. 使用 --credentials-file 指定新的受限凭据文件；组织已有用户时不重置凭据。
+
+## 正例
+
+```text
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
+```
+
+## 反例
+
+```text
+createServer({ domain, bootstrap: true })
+```
+
+## 修复后验证
+
+重跑原先失败的命令，确认使用预期库与账号；输出脱敏信息。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/http/src/server.ts:113`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  }
+  if (opts.bootstrap) throw new Error('[CAGE-ENV-003] 服务启动不再隐式初始化组织；请在受控初始化入口显式调用 bootstrapOrg 并安全交付初始凭据');
+  const readinessTimeoutMs = opts.readinessTimeoutMs ?? 2000;
+  if (!Number.isSafeInteger(readinessTimeoutMs) || readinessTimeoutMs < 1) throw new Error('[CAGE-ENV-002] readinessTimeoutMs 必须为正整数');
+  // 开发会话密钥也是随机值，重启会使旧 CSRF/OIDC cookie 失效；多实例必须显式共享配置。
+```

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

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

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

@@ -34,17 +34,17 @@ note: text().optional() // 新增字段
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/rules.ts:225`
-- `packages/cli/src/rules.ts:237`
-- `packages/cli/src/rules.ts:244`
-- `packages/cli/src/rules.ts:254`
+- `packages/cli/src/rules.ts:275`
+- `packages/cli/src/rules.ts:293`
+- `packages/cli/src/rules.ts:300`
+- `packages/cli/src/rules.ts:310`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
 
 /** CAGE-EVENT-002：事件载荷只允许向后兼容的变更（只能新增可选字段） */
-export function checkEventCompat(base: Ontology, head: Ontology): Finding[] {
-  const findings: Finding[] = [];
-  const b = new Map(base.nodes.filter((n) => n.kind === 'event').map((n) => [n.id, n]));
+/**
+ * 比较同名事件字段的删除、类型改变及新增必填项。
+ * @param base 旧本体，代表可能仍有在途事件的声明。
 ```

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

@@ -34,7 +34,7 @@ text().sensitive('自定义随意字符串')
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/fields.ts:100`
+- `packages/kernel/src/primitives/fields.ts:197`
 
 实现片段（位置随框架版本更新）：
 
@@ -43,5 +43,5 @@ text().sensitive('自定义随意字符串')
     if (!SENSITIVE_KINDS.includes(kind)) throw declError('CAGE-FIELD-001', `未知的敏感种类 ${kind}`);
     return this.with({ sensitiveKind: kind });
   }
-  /** 唯一约束（租户内） */
+  /** 返回要求租户内唯一的新字段；实际约束由 DDL/迁移落实，不是仅一次应用查询。文件和集合已有专用归属/配对语义，拒绝该修饰。 */
 ```

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

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

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

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

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

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

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

@@ -0,0 +1,56 @@
+# CAGE-FILE-001：文件字段或上传配置无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：字段声明 / 私有文件服务配置。
+
+文件缺少明确的大小/MIME 限制，多文件数量无效，文件嵌入 JSON/事件/范围字段，或存储分片配置超出适配器限制。
+
+## 修复步骤
+
+1. 文件直接声明在聚合 fields 中，设置正整数 maxBytes、明确 MIME accept；files 还需 1–100 的 maxCount。
+2. 不使用 sensitive/hidden/unique 修饰文件；事件只传 id/list(id())。上传 partBytes/maxFileBytes 必须符合存储适配器分片限制。
+
+## 正例
+
+```text
+attachments: files({ maxBytes: 20971520, maxCount: 10, accept: ['application/pdf'] })
+```
+
+## 反例
+
+```text
+list({ contract: file({ maxBytes: 0, accept: ['*/*'] }) })
+```
+
+## 修复后验证
+
+重跑 cage check、gen 和文件回归；实际验证暂停、续传、命令绑定及当前权限下载，云存储联调单独报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/files/src/service.ts:95`
+- `packages/files/src/service.ts:98`
+- `packages/kernel/src/primitives/aggregate.ts:189`
+- `packages/kernel/src/primitives/event.ts:51`
+- `packages/kernel/src/primitives/fields.ts:195`
+- `packages/kernel/src/primitives/fields.ts:202`
+- `packages/kernel/src/primitives/fields.ts:208`
+- `packages/kernel/src/primitives/fields.ts:305`
+- `packages/kernel/src/primitives/fields.ts:336`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    };
+    for (const [name, value] of Object.entries(this.options)) if (!Number.isSafeInteger(value) || value < 1) throw new Error(`[CAGE-FILE-001] ${name} 必须为正安全整数`);
+    const limits = this.storage.limits;
+    if (this.options.partBytes < limits.minPartBytes || this.options.partBytes > limits.maxPartBytes || Math.ceil(this.options.maxFileBytes / this.options.partBytes) > limits.maxParts)
+      throw new Error('[CAGE-FILE-001] 分片配置超出存储适配器限制');
+```

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

@@ -34,8 +34,8 @@ gen --check/verify 比较发现需提交的生成文件缺失或与声明不一
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/gen/index.ts:48`
-- `packages/cli/src/gen/index.ts:90`
+- `packages/cli/src/gen/index.ts:76`
+- `packages/cli/src/gen/index.ts:122`
 
 实现片段（位置随框架版本更新）：
 

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

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

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

@@ -0,0 +1,53 @@
+# CAGE-GEN-003：输入校验需要服务端执行
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：gen --check / verify。
+
+refine/superRefine、transform 等可执行校验无法无损转换到生成的客户端 schema，报告包含字段路径。
+
+## 修复步骤
+
+1. 阅读诊断定位的命令和字段；把可表达规则声明成标准 schema，保留服务端作为最终校验。
+2. 确需自定义逻辑时，在页面解释业务拒绝并处理领域错误；不要认为契约生成成功代表执行函数已被复制。
+
+## 正例
+
+```text
+strict、multipleOf、default 使用标准 Zod 声明；自定义规则按字段报告降级
+```
+
+## 反例
+
+```text
+把服务端 refine 丢失当作客户端校验完全等价
+```
+
+## 修复后验证
+
+重新生成并审查后执行 cage gen --check；结构变化还需审查并执行 migrate。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/gen/index.ts:159`
+- `packages/cli/src/gen/zod-code.ts:64`
+- `packages/cli/src/gen/zod-code.ts:84`
+- `packages/cli/src/gen/zod-code.ts:120`
+- `packages/cli/src/gen/zod-code.ts:140`
+- `packages/cli/src/gen/zod-code.ts:217`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    for (const diagnostic of schemaDiagnostics(entry.input)) findings.push({
+      code: 'CAGE-GEN-003', severity: 'warning', at: `${entry.name}:${diagnostic.path}`,
+      reason: diagnostic.reason, fix: '前端校验只提供即时提示，以服务端命令校验为准；不要复制可执行函数到契约。',
+    });
+
+```

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

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

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

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

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

@@ -34,14 +34,15 @@ PurchaseOrder.anything // 没有对应声明
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/admin/src/domain/constraints.ts:13`
+- `packages/admin/src/domain/constraints.ts:21`
+- `packages/admin/src/domain/constraints.ts:26`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-  check: (_role, _ctx, input, meta) =>
-    meta.catalog().includes(input.capability) ? ok() : violation(`[CAGE-GRANT-003] 能力点 ${input.capability} 不在能力目录里`),
-});
-
-/** 防提权：不能授出自己没有的能力点；数值参数（额度）不能超过自己的 */
+ * 构造目录存在性约束。check 使用内核提供的实时目录核对 input.capability，
+ * 未知能力返回 CAGE-GRANT-003；该检查不负责判断操作者是否拥有这个能力。
+ */
+export const knownCapability = (): Constraint => ({
+  name: 'knownCapability',
 ```

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

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

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

@@ -0,0 +1,52 @@
+# CAGE-IMPACT-002：命名本体快照无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：impact / 基线加载。
+
+快照名非法、同名已存在、指定快照不存在，或快照格式损坏。
+
+## 修复步骤
+
+1. 先 cage snapshot list 核对已有名称，再用新的稳定名称保存。
+2. 保存后通过 impact --snapshot 比较；不要覆盖旧基线或把修改后的图当成修改前状态。
+
+## 正例
+
+```text
+cage snapshot save before-rental-change；cage impact --snapshot before-rental-change
+```
+
+## 反例
+
+```text
+多次使用同名快照覆盖唯一旧图
+```
+
+## 修复后验证
+
+使用可靠基线重新 impact，确认报告中的变化与本次需求相符。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/impact.ts:95`
+- `packages/cli/src/snapshots.ts:24`
+- `packages/cli/src/snapshots.ts:27`
+- `packages/cli/src/snapshots.ts:56`
+- `packages/cli/src/snapshots.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const graph = value.graph ?? value;
+  if (graph.version !== 1 || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) throw new Error('[CAGE-IMPACT-002] 基线文件不是有效本体图或命名快照');
+  return graph as Ontology;
+}
+
+```

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

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

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

@@ -36,7 +36,7 @@ ALTER ROLE 重置共享账号密码，导致已有应用断连
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/init.ts:94`
+- `packages/cli/src/init.ts:114`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,8 +34,8 @@ app 连接 business_db，而 read/migrate 指向另一个库
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/init.ts:22`
-- `packages/cli/src/init.ts:97`
+- `packages/cli/src/init.ts:30`
+- `packages/cli/src/init.ts:117`
 
 实现片段（位置随框架版本更新）：
 

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

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

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

@@ -0,0 +1,52 @@
+# CAGE-INIT-005：显式组织初始化或凭据交付失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init。
+
+bootstrap 配置不完整，凭据文件已存在、权限无法限制，或组织初始化事务失败。
+
+## 修复步骤
+
+1. 审查执行迁移后，提供新的凭据文件路径和实际可用连接；父目录需存在。
+2. 先修复文件权限或数据库错误，再重新执行；不能把密码转而打印到服务日志。
+
+## 正例
+
+```text
+cage bootstrap --credentials-file .cage/admin-credentials.json // 新受限文件
+```
+
+## 反例
+
+```text
+覆盖已有凭据文件，或初始化失败后继续输出“成功”
+```
+
+## 修复后验证
+
+恢复/核对配置后运行 cage init 验证，随后按流程 gen、审查迁移并 migrate；不输出凭证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/bootstrap.ts:19`
+- `packages/cli/src/bootstrap.ts:23`
+- `packages/cli/src/bootstrap.ts:32`
+- `packages/cli/src/bootstrap.ts:45`
+- `packages/cli/src/bootstrap.ts:61`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+ * @param file 已解析的目标路径，父目录必须存在，目标不得已存在。
+ * @throws 创建或 ACL 限制失败时抛出 CAGE-INIT-005；已创建空文件可能保留，不能视为交付成功。
+ */
+export function protectCredentialFile(file: string): void {
+  try { closeSync(openSync(file, 'wx', 0o600)); }
+```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -34,14 +34,14 @@ event('order-submitted', fields)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/event.ts:19`
+- `packages/kernel/src/primitives/event.ts:49`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-export function event<const N extends string, F extends Fields>(name: N, fields: F, opts?: { description?: string }): Event<N, F> {
+export function event<const N extends string, F extends Fields>(name: N, fields: F, opts?: { /** 可选事件事实说明，供本体与文档使用；不改变事件名、字段或投递语义。 */ description?: string }): Event<N, F> {
   if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-003', `事件名 ${name} 必须是大驼峰`);
   if (Object.values(fields).some(isRelation)) throw declError('CAGE-REL-001', '事件载荷不声明持久化关系；传递 ID 数组请使用 list(id())');
+  if (Object.values(fields).some(isFile)) throw declError('CAGE-FILE-001', '事件传递文件 ID 请使用 id/list(id())，不声明文件生命周期');
   return Object.freeze({
-    [EVENT]: true as const,
 ```

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

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