fix(convention): 持久性降级记 error 而非 warn —— 把 #4460 定成规则,并给规则装上机械检查 (#4632)

[os-zhuang]

Fixes #4632

把 #4460 的点状修复定成规则,并且给规则装上牙齿。

一、规则落在哪,为什么

锚点选了 AGENTS.md,新增一节「Degradation log levels — warn vs error」,放在 “Route & surface ownership” 之后。理由:

• 这是一条写 catch 时当场适用的判据,不是某个子系统的架构决策。ADR 回答「我们决定采用什么架构」,而这条回答「你现在敲的这一行该用哪个级别」—— 后者属于每个 agent 编辑前必读的 AGENTS.md。
• 它的适用面比任何一个 ADR 都宽:任何包、任何 catch,不限于插件 init 期。挂在 ADR-0116(plugin ordering declared contract)的 addendum 上会把它误缩到「插件排序」这一个语境里 —— 而 [automation/approvals] 进程重启后审批决策静默失效:挂起 flow run 仍只存内存(#1518 标记 COMPLETED 但 17.0.0-rc.1 未生效),approve 落库却永不推进且零报错 #4420 只是碰巧发生在那里。
• 它有现成的近邻:同文件 Prime Directive chore: version packages #10 的推论「never advertise a capability the runtime doesn't actually deliver(declared ≠ enforced)」,以及 “Route & surface ownership” 第 3 条「Absence must be loud … Prefer failing to falling back」。持久性降级记 warn,正是「对外宣称持久化、运行时并不交付」的一个实例。新节显式交叉引用了这两处。

文案是判定问句,不是形容词(按验收要求):

After the degradation, does the system still look "normal" from the outside, while something it claims is persisted has not actually landed?
Yes → error. No → warn/info is right.

并规定提到 error 的每一处必须在第一行同时给出后果与修复动作(照 service-automation/src/plugin.ts start() 的 #4460 范本),且只说一次,不是每次写失败都刷一遍。

同时明确写了反向失败:把功能性降级误提到 error 会训练所有人跳读 error,而那正是当初 #4420 那条 warn 没人读的原因。规则特别点出 if (!service) 的组合分支通常是功能性的、该留在 warn;真正咬人的是包住写入 / DDL / store 初始化的 catch。

二、机械检查:做了

「一条只写在 AGENTS.md 里、没有任何东西检查的约定,就是本仓反复修的那个『声明 ≠ 强制』形状」—— 这个批评是对的,所以做了闸门。

pnpm check:durability-log-level(scripts/check-durability-degradation-log-level.mjs,已接入 lint.yml 的必需 job):AST 遍历所有 catch,若其 try 块调用了词表内的持久化关键操作,则该 catch 必须 error(或 fatal)或重新抛出;记 warn/info/debug 或静默吞掉即失败。

几个刻意的设计:

• 靠显式词表,不靠启发式猜测。「这个 catch 是不是持久化缝隙」是语义问题,用 /save|write|persist/ 之类的正则去猜,误报率会高到让人把闸门关掉 —— 而一个被关掉的闸门比没有闸门更糟,因为它还会报成功。词表(DURABILITY_CRITICAL_CALLEES)很小、每条都写明「为什么它的失败意味着字节没落盘」,加一条是需要评审的动作。
• 走 AST 而不是正则:被守护的调用往往和日志行不在同一个块里(objectql 里 await driver.syncSchema(...) 和它的日志隔着两层嵌套循环;[automation/approvals] 进程重启后审批决策静默失效:挂起 flow run 仍只存内存(#1518 标记 COMPLETED 但 17.0.0-rc.1 未生效),approve 落库却永不推进且零报错 #4420 那次干脆在 init() 调用的私有方法里)。判据是块结构,不是行距离。
• try 块内不下沉进嵌套函数体(ctx.hook('kernel:ready', async () => …) 里的调用晚于这个 catch 执行,不受它守护),这和 check-init-service-contract.mjs 的取舍一致。
• catch 侧反过来会跨同文件 helper 追踪。这一条是实测逼出来的:我先把两处重复的错误文案抽成 reportSyncFailure() helper,闸门立刻把它们报成「静默吞掉」。如果不追踪 helper,「把失败藏到一层间接后面」就成了让闸门闭嘴的最省事做法 —— 那正是 [automation/approvals] 进程重启后审批决策静默失效:挂起 flow run 仍只存内存(#1518 标记 COMPLETED 但 17.0.0-rc.1 未生效),approve 落库却永不推进且零报错 #4420 形状本身。
• console.error 与 logger.error 同等响亮。也是实测发现的:metadata/src/loaders/database-loader.ts 的 history-schema 分支用 console.error 老实上报,把它判成违规会是纯误报。
• 自带 --self-test(10 例,双向都钉:必须抓到 [automation/approvals] 进程重启后审批决策静默失效:挂起 flow run 仍只存内存(#1518 标记 COMPLETED 但 17.0.0-rc.1 未生效),approve 落库却永不推进且零报错 #4420 形状,也必须不抓功能性降级),--list 打印全部缝隙及判定。
• 例外走 scripts/durability-degradation.baseline.json,手写、带理由、shrink-only,且故意不提供 --fix/--update —— 有了那个 flag,新违规就能靠「跑一下更新命令」混进来,闸门也就不再意味着什么。条目修好后不删会报 stale 而变红。

闸门的局限,写在脚本头部而不是等人踩:它发现不了词表之外的新持久化缝隙,只能保证已经付过学费的那些不再退回 warn。这是棘轮,不是证明。发现新缝隙时,请在修它的同一个 PR 里把它加进词表。第二条局限:catch 的响亮判定扫的是整棵子树,所以一个通过嵌套 try 恢复的 catch(batch→sequential 那个)会因恢复路径的 error 而通过 —— 对那个形状这是正确判决,但确实意味着一个无关的嵌套 logger.error 也能满足闸门。收紧它会误伤合法的恢复型 catch,那是更糟的交易。

当前实测结果:8 处持久化关键缝隙,7 处已响亮,1 处 baseline(冻结包,见下)。

三、盘点结果(逐条,含判为第一类的)

判定问句 = 「降级后系统对外表现是否仍然『正常』,而声称已持久化的东西实际没有落盘?」

改为 error(第二类)

文件 / 行	后果
objectql/src/plugin.ts ~405 reload-time schema sync	Studio 加一个字段 → 元数据落库、UI 显示、API 接受,而列从未创建。作者被告知「已保存」,实际没有
objectql/src/plugin.ts ~1002 / ~1018 per-object sync	DDL 没跑;对象仍在 registry、仍有 REST 路由、仍然渲染,表/列不存在
objectql/src/plugin.ts 汇总行	原来失败任意多个仍打 info: Schema sync complete —— 这就是「看起来正常」的那一半。现在 failed > 0 时是 error 并报出计数
objectql/src/engine.ts ~5340 syncSchemas()	原本是空 catch {},注释写「log suppressed to avoid noise on already-synced tables」。但 syncSchema 契约要求幂等,能走到这个 catch 的驱动就是没同步成功;唯二调用方是 marketplace 插件安装与模板 seeding,它们随后就往这个失败意味着不存在的表里 INSERT,然后报告安装成功。这一处是闸门发现的,不在 PM 名单里
service-automation/src/plugin.ts ~882 wait-timer 外层	落盘成功,但没有任何 timer 被重新武装:重启前挂起的每个审批永久悬停
service-automation/src/builtin/wait-node.ts ~160 list 失败	直接 return 0,一个 timer 都没武装,整个子系统级别的失效
service-automation/src/builtin/wait-node.ts ~176 overdue resume 失败	该 run 的截止时间已过,不会再有任何东西唤醒它
service-automation/src/builtin/wait-node.ts ~205 re-schedule 失败	run 带着截止时间留在盘上,却没有 job 会唤醒它

关于 wait-node 这三处:数据确实落盘了,坏掉的是恢复。之所以仍判第二类 —— 持久化状态与运行时状态互相矛盾,而看起来没事的是运行时;对那个等审批的人来说,结果与 #4420 的丢失不可区分。这也是为了和同一子系统的外层 catch 保持一致:在一个文件里对同一后果给出两种级别,比任何一种选择都糟。

判为第一类,不改(逐条给理由)

文件 / 行	为什么留在 warn/info
mcp/src/plugin.ts 164	环境变量弃用提示,根本不是降级
objectql/src/plugin.ts 215 / 224 authored hook/action rebind	失败后旧绑定仍在,行为陈旧而非丢失
objectql/src/plugin.ts 431	legacy app.* 弃用提示
objectql/src/plugin.ts 611 / 682 registry ingest / event handler	registry 未刷新,后续查询直接报错,失败是响亮的
objectql/src/plugin.ts 938 external object 注册	联邦对象未映射到远端表,使用时响亮失败;其 schema 本就归远端所有,无 DDL 可丢
objectql/src/plugin.ts 992 batch→sequential	会恢复。真正丢 DDL 的是随后的顺序路径,那一处已提到 error
objectql/src/plugin.ts 1279	存量形状转换成功的提示
objectql/src/plugin.ts 1692 / 1706 authored action runner	action body 不执行 = 功能缺一块
service-analytics/src/plugin.ts 213	init 时没有 data 服务,每次查询重试;真的一直缺就在调用点 throw,响亮
service-analytics/src/plugin.ts 585 getReadScope 缺失	最接近边界的一条。后果是安全/机密性(analytics 查询不做租户隔离),不是持久性;而且单租户 host 没有 security 服务是合法组合,提到 error 会在每个单租户 host 每次启动制造噪音 —— 正是规则的反面失败。规则按维护者原文保持在「持久性 / 数据一致性」,我没有擅自扩到安全域
service-automation/src/plugin.ts 452	init 期 manifest 缺失是「还没到」,start() 会重试;真缺失时由 #4460 那条 error 兜底
service-automation/src/plugin.ts 491 / 758 / 766 / 1355 / 1412 / 1456	引擎缺失、flow 注册/拉取失败 = 某条 flow 不跑,功能性
service-automation/src/plugin.ts 847 / 910	已是写得很好的功能性 warn(触发器未绑定 / 声明式 connector 未注册),都已带修复动作
service-automation/src/plugin.ts 1180	降级 husk 注册失败,紧接着下一行就是 error
service-automation/src/builtin/wait-node.ts 184 !job	声明式缺席:从未组合 job 服务的 host 本就没有自动恢复能力,不存在「先承诺再打破」。提到 error 会在每个无 job host 的每次启动、每个挂起 run 各刷一次
trigger-api 64 / 68 / 80	触发器未安装 / 入站 503 / 端点未挂载 —— 都是功能缺一块,且 503 在请求时响亮
trigger-record-change 49 / 57	同上
trigger-schedule 53 / 62	同上

四、排除的两个包:有发现,已单开 issue

按本轮硬约束,packages/metadata/** 与 packages/metadata-protocol/** 零改动,发现只记录:

• [metadata] database-loader 吞掉 sys_metadata 的 DDL 失败后仍置 schemaReady=true —— 第二类降级(#4632 规则),本轮因包冻结未修 #4728 — packages/metadata/src/loaders/database-loader.ts ensureSchema():catch 完全静默且把 schemaReady 置为 true,与成功路径不可区分。注释的免责理由("e.g. table already exists")只覆盖最良性的一种失败原因,却为全部失败原因开脱。闸门能自动发现这一处,已挂在 baseline 并指向 [metadata] database-loader 吞掉 sys_metadata 的 DDL 失败后仍置 schemaReady=true —— 第二类降级(#4632 规则),本轮因包冻结未修 #4728;修复时请一并删掉 baseline 条目(shrink-only,残留会变红)。
• [metadata-protocol] seed-loader 的「LOUD FAILURE」注释要求 error,代码却记 warn —— 第二类降级(#4632 规则),本轮因包冻结未修 #4729 — packages/metadata-protocol/src/seed-loader.ts ~961:注释与代码直接矛盾 —— 注释明写 "this must be a reported, counted error, never a silent warning",紧跟着的调用是 logger.warn。后果按注释自己的说法:引用停在 NULL,循环关系半写入。(公允地说,它确实通过 recordDeferredError 计入了 allErrors,不是完全静默;但日志行本身是这次 seed 唯一可见的痕迹。)闸门发现不了这一处 —— 写路径没有可识别的调用名,这是上面那条局限的真实例子,issue 里也写明了。

另有 packages/metadata/src/plugin.ts 388(Failed to attach FileSystemRepository)存疑:后果取决于 manager 无 repository 时的行为,冻结包内未深挖,未作断言。若确证属第二类,建议并入 #4728。

packages/spec/** 零改动;content/docs/releases/ 未触碰。

五、验证

• pnpm check:durability-log-level —— self-test 10 例通过;实测 8 缝隙全部响亮或重抛(1 条 baseline)
• pnpm --filter @objectstack/objectql test / pnpm --filter @objectstack/service-automation test
• pnpm --filter @objectstack/objectql typecheck / pnpm --filter @objectstack/service-automation typecheck
• 新增测试双向都钉:持久性降级必须 error 且文案含后果与修复动作;功能性降级(batch 回退、无 job 服务)必须留在 warn;全部成功时一句不吭

已加 changeset(.changeset/durability-degradation-log-level.md)。无 API / schema / 行为变更 —— 只改了已经在失败的路径报告的级别和文案。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 3, 2026 1:02am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/service-automation.

15 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via @objectstack/service-automation)
• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx (via @objectstack/objectql)
• content/docs/deployment/vercel.mdx (via @objectstack/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql, @objectstack/service-automation)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql, @objectstack/service-automation)
• content/docs/protocol/kernel/index.mdx (via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx (via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
• content/docs/releases/implementation-status.mdx (via @objectstack/objectql, @objectstack/service-automation)
• content/docs/releases/v9.mdx (via @objectstack/service-automation)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

CI 红的根因已修(e4fa4af)—— 顺带记一条本地绿 / CI 红的教训

根因:Logger 的 warn 与 error 签名不对称

packages/spec/src/contracts/logger.ts:

warn (message: string,                meta?: Record< string, any >): void
error(message: string, error?: Error, meta?: Record< string, any >): void

上一个 commit 里每一处提级都是机械的 warn → error 替换,而这个替换会把上下文对象从 meta 槽悄悄挪进 Error 槽。超额属性检查让它成为硬错误 —— 但只在会产出声明的地方,所以它炸在 tsup 的 DTS 构建和仓库级 TypeScript Type Check 上,而所有运行时测试照样全绿(往 Error 槽塞个普通对象,日志打得好好的)。

CI 报的那一条(engine.ts(5356,15))只是这批里第一个被编译到的;plugin.ts 里还有三处同样的错,DTS 在第一个错误处就停了,所以没报出来。四处一并按 (message, Error, meta) 修正:

位置	第二槽
engine.ts syncSchemas()	e as Error + { object, tableName, driver }
plugin.ts reload-time schema sync	捕获到的 error
plugin.ts reportSyncFailure()	捕获到的 error + { object, tableName, driver }
plugin.ts 汇总行	undefined —— 整趟 pass 没有哪一个 error 能代表它

教训:--filter … typecheck 覆盖不到 DTS 编译路径

我本地跑的是 pnpm --filter @objectstack/objectql typecheck,它是绿的;红的是 build 里的 DTS 步骤。两者读同一份类型却在不同时机报错,而这一类「对象字面量塞进了错误的参数槽」只有在产出声明时才会被超额属性检查逮到。

结论:改动涉及公开签名 / 日志调用形状时,推送前必须跑带 DTS 的 build,typecheck 不能替代它。 另外这个 worktree 是全新的,依赖包一个 dist 都没有 —— 第一次 tsc 直接报了一屏 Cannot find module '@objectstack/types',那不是我的改动,是 AGENTS.md §9 说的「新 worktree 先刷构建状态」。正确姿势是 pnpm exec turbo run build --filter=<pkg>,靠 ^build 把整个依赖闭包带起来。

测试也补了这个洞

原来的断言把日志尾参拍平成一个 meta 看,所以参数槽错位它照样通过。现在直接断言参数位置:

expect(args[0]).toBeInstanceOf(Error)
expect(args[1]).toMatchObject({ object: 'invoice' })

同一处滑动现在测试就会红,不必等构建。

顺带修了 overdue-resume 那条用例:AutomationEngine.resume() 对「flow 不存在」这类机器状态问题是在结果里报告而不是抛出的,所以我原来用「没注册 flow 的引擎」根本进不到被测的 catch;改成注入一个会抛的 resume stub —— 那才是那个 catch 真正守护的东西。

复验(全部本地跑过)

closure build (turbo ^build)          exit 0
objectql build WITH DTS               exit 0   ← CI 挂的就是这步
service-automation build WITH DTS     exit 0
objectql typecheck                    exit 0
objectql tests                        7 passed
service-automation tests              25 passed (新增 + wait-node + suspended-run-wiring)
check:durability-log-level            self-test 10/10;8 缝隙全部响亮或重抛

(service-automation 没有 typecheck script —— 它在 ratchet 里带 DEBT 条目,其类型覆盖就是上面那条带 DTS 的 build。)

---

Generated by Claude Code