fix(objectql): seedAutonumber 把非「表未建」的读故障上抛,不再从 0 重发自增号 (#5979)

[baozhoutao]

Fixes #5979

前提复核

单据是线索不是规格,四条前提逐条在 origin/main(复核时 be59695,推送前已并到 830f3f16f)实读复核 —— 全部成立,行号有位移,实质无变化。

前提	结论	证据
seedAutonumber() 结尾是裸 } catch { return 0; }	✅ 成立	packages/objectql/src/engine.ts:2063 声明,catch 在 :2102-2104(单据写的 ~2046 / ~2085-2087 是更早提交的行号,位移约 17 行)
调用点 if (next == null) next = await this.seedAutonumber(...) 是活路径	✅ 成立	同文件 :2049,在 applyAutonumbers 内,仅当 driver 不声明 supports.autonumber 时进入
同一个 try 上方有 #4371 注释,含 "the catch below would have swallowed the guard's rejection into 'seed from 0', i.e. duplicate autonumbers"	✅ 成立	原文逐字在 :2070-2074 —— 仓内既有的书面预言
baseline 有 packages/objectql/src/engine.ts::seedAutonumber 条目	✅ 成立	scripts/durability-read-invention.baseline.json,verdict: unfixed-degradation,tracked_by: "#5979"

处置

seedAutonumber 的 catch 改为按错误类型判别,其余一律上抛:

} catch (error) {
  if (isMissingTableError(error)) return 0;  // 唯一良性:表尚未 provision,从 0 起号不撞任何东西
  throw error;                               // 其余一律上抛:不得用没读到的数据推算号段
}

只动这一个 catch(加必要 import)。delete() / update() 的前置行门区域、recomputeSummaries 一带,以及 engine.ts 其他任何区域,一行未碰 —— 见下方「必答项」。

isMissingTableError 引入路线:选了「直接依赖 + /errors 子路径」

先实测,再选路。 依赖图用脚本跑了两个方向:

metadata reaches objectql (prod deps)? false
objectql reaches metadata already?    true

即:@objectstack/metadata 的生产依赖闭包不含 objectql(不成环),而 objectql -> metadata-protocol -> metadata 这条路在 main 上早已存在。所以加一条直接边不是新边,是把图里已有的一条路径抄了近道 —— 既没有新的构建序约束,也没有新的安装体积(metadata 及其 chokidar/glob/js-yaml 本来就在 objectql 的安装闭包里)。

于是采用 packages/metadata/src/errors.ts 头注释里的方案三(从现有归属处刻意导出),这也正是该子路径存在的理由 —— 它只 re-export 一个叶子模块,schema-sync-errors.ts 自身零 import,所以跨包边始终是叶子边,拿不到 manager / loaders / YAML 那一堆东西。@objectstack/metadata-protocol 已经这么用了两处(protocol.ts:15、sys-metadata-repository.ts:58),本 PR 是第三个同形消费者。

没有走「沉到公共依赖」(方案二),理由三条,按三轴讲清楚:

• 真实业务需求:需要的是一个 40 行谓词,消费者一共三个,全在 metadata/持久化层内。没有任何新的业务拉力要求换一个家 —— 换家服务的是整洁感,不是场景。按「创业期聚焦、能力扩张默认收紧」,一次纯搬迁在本单里买不到东西。
• 本项目的长期健康:@objectstack/metadata-core 确实是更漂亮的落点(objectql 与 metadata 都已依赖它,它只依赖 spec + zod,且它的 package description 里本来就写着 "errors";[engine-double-contract] 把 assertEngineDeleteDispatch 下沉到 @objectstack/metadata-core —— 七条 metadata-protocol 基线条目唯一存在的关闭路线(#4987 只修了处方文字) #5619 把 engine dispatch 谓词沉进去正是这个先例)。但 [engine-double-contract] 把 assertEngineDeleteDispatch 下沉到 @objectstack/metadata-core —— 七条 metadata-protocol 基线条目唯一存在的关闭路线(#4987 只修了处方文字) #5619 有一个成环的强制因素(反向 import 会闭合 turbo 拒绝的环),这里没有:不成环,搬迁就纯属自选动作。而 metadata/errors.ts 的作者是刻意把方案二挂起的("explicitly not precluded … out of scope on the round that needed it",并留了 "a single, greppable seam to delete if the maintainer later takes option 2")—— 在一个 bug 修复 PR 里替维护者拍掉这个挂起的决定,既越界又会撞上正在处理 MetadataProtocol.listCommits 把 commit store 读不到答成 [] —— ADR-0067 时间线上「无历史」与「读不到」不可分辨(零日志,JSDoc 里写着这是设计) #5980(listCommits,同样 import 这个子路径)的并行开发席。方案二仍然完全开着,本 PR 没有关上它,只是没有顺手拍。
• 让 AI 写的代码难写错:两条路线都是「一个谓词、一份实现」。但方案二在过渡期会同时存在两个 import 路径(metadata-core 正典 + metadata/errors 兼容 re-export),恰好是让 AI 生成的 import 漂移的那种「一件事两种说法」的面;除非同一 PR 立刻退掉 re-export,而那会打断 MetadataProtocol.listCommits 把 commit store 读不到答成 [] —— ADR-0067 时间线上「无历史」与「读不到」不可分辨(零日志,JSDoc 里写着这是设计) #5980 在途的文件。所以这一轴反而反对方案二。

关键的是:闸门按谓词名判别,与 import 路径无关(READ_FAILURE_DISCRIMINATORS 只登记 isMissingTableError 这个名字),所以两条路线在闸门面前等价,选择完全由上面三轴决定。手抄一份 code === '42P01' 是明确被排除的第三种做法 —— 那正是 #5841 修掉的「第二套良性词表」缺陷。

同 PR 摘掉了 baseline 里现已失效的 seedAutonumber 条目(shrink-only:闸门对陈旧条目直接报红,修复必须同 PR 删条目)。

测试与反向验证

新增 packages/objectql/src/engine-autonumber-seed-outage.test.ts,12 例,贴 engine-autonumber-defer.test.ts 的既有 harness(fake driver,不是 fake engine,所以本单不涉及引擎写动词 dispatch 契约,assertEngineDeleteDispatch / assertEngineUpdateDispatch 均无需出场)。

• 表未 provision 的三种 driver 拼写(PG 42P01 / MySQL ER_NO_SUCH_TABLE / SQLite 纯 message)→ 从 0 起号、不抛;
• 四类读故障(连接拒绝 / 语句超时 / 权限拒绝 / 连接中断)→ 上抛,driver.create 一次未被调用;
• 原始 driver 错误原样透出,不被包成泛化错误;
• 撞号场景本身:表里已有 D-0007,故障期间写入失败而非发出 D-0001;恢复后续号为 D-0008(顺带证明失败的播种没有污染内存计数器);
• 正常路径(取 max、真空表)不变。

反向验证:方向先写死,再运行

预测写在 predictions.md 后才执行。方向是普通的红向(不是 #5046 的「诊断变多」,也不是 #5018 的倒挂):被删的肢是错误路径上的一个谓词,不是喂给下游闸门的计数。

肢 1 —— 把 catch 临时改回 } catch { return 0; },跑新用例

	预测	实测	相符
翻红数	6 / 12	6 failed | 6 passed (12)	✅
具体哪 6 条	4 条 outage「rethrows and writes NOTHING」+「propagates the ORIGINAL driver error」+「does NOT restart at 1 against a table that already holds rows」	逐条一致(见下)	✅
保持绿的 6 条	3 条 missing-table + 「keeps counting after a benign seed」+ 2 条正常路径	一致	✅

实测失败断言原文,正是缺陷本身 —— 读故障期间插入成功了:

FAIL … rethrows and writes NOTHING — connection refused
FAIL … rethrows and writes NOTHING — statement timeout
FAIL … rethrows and writes NOTHING — permission denied
FAIL … rethrows and writes NOTHING — connection terminated mid-query
FAIL … propagates the ORIGINAL driver error, not a synthesized one
AssertionError: promise resolved "{ id: 'r1', title: 'First', …(1) }" instead of rejecting
FAIL … does NOT restart at 1 against a table that already holds rows
AssertionError: promise resolved "{ id: 'r1', …(2) }" instead of rejecting

肢 2 —— baseline 条目,两个方向都验

状态	预测	实测	相符
2a. 修复在场 + 条目恢复	红,理由「陈旧条目」	✗ 1 stale entr(ies) … the seam no longer invents an unreported answer, so delete the entry → packages/objectql/src/engine.ts::seedAutonumber	✅
2b. 修复不在场 + 条目已摘	红,理由「未登记的违规」	✗ 1 read seam(s) invent an empty answer for a read that failed, and tell nobody → packages/objectql/src/engine.ts:2111 (in seedAutonumber())	✅
2c. 修复在场 + 条目已摘(本 PR 状态)	绿	✓ read-seam invention … none invents an unreported empty answer	✅

两肢、四个方向,预测与实测全部相符,没有翻不红的肢。

命令与真实输出

以下为合并 origin/main(830f3f1)之后的最终态数字。重活全部经 flock /tmp/os-heavy-verify.lock 串行。

$ pnpm --filter @objectstack/objectql test
 Test Files  132 passed (132)
      Tests  2180 passed (2180)

$ pnpm --filter @objectstack/objectql typecheck
> tsc --noEmit
PIPELINE_EXIT=0                      # 无输出即无错误

$ node scripts/check-durability-degradation-log-level.mjs
✓ durability-degradation log levels: 24 durability-critical catch seam(s), all loud, rethrowing or propagating to the caller (3 propagating, declared).
✓ read-seam invention (#5186, 3 package roots): 64 read seam(s), none invents an unreported empty answer (6 return an empty value on a type-discriminated benign branch) (2 baselined).

$ node scripts/check-engine-double-contract.mjs
check-engine-double-contract: OK — 73 pinned, 133 in the DEBT ledger, 2 exempt.

$ node scripts/check-empty-changeset.mjs     # main 本轮新增的闸门
✓ No empty-frontmatter changeset introduced by this diff (1 declaring changeset(s) added).

$ node scripts/check-nul-bytes.mjs
check-nul-bytes: OK (scanned 5859 tracked text file(s); skipped 5 binary, 1 non-regular; no raw ASCII control bytes).

补充说明,不编造:

• read-seam invention 的「type-discriminated benign branch」计数由 5 → 6、baselined 由 3 → 2,差额就是本 PR 这一处。
• 测试数 132/2180 高于修改前的 131/2167:其中 12 条是本 PR 新增,另 13 条来自合并进来的 main(新增 plugin-metadata-event-outage.test.ts)。
• @objectstack/objectql 有 typecheck 脚本(tsc --noEmit),不属于 [P2] framework: 66 个包用 tsup 构建、无人做类型检查 —— 实测 18 个包共 380 处 code-tier 错误(#4118 的 framework 侧对应) #4311 台账里没有该脚本的包。
• 合并前用 git diff --name-only HEAD origin/main 预检:main 这 15 个提交未触碰 engine.ts / baseline / objectql 的 package.json,合并无冲突;但因 main 动了 packages/objectql(加了测试文件),仍按 AGENTS §9/§10 重装、重建依赖链并完整重跑了上表。

必答项

#5929(同文件 delete() 前置行门恒真)—— 否,未触其面,未改其定价。
依据:本 PR 对 engine.ts 的改动只有两处,git diff 可逐行核对 —— import 区加 1 条 isMissingTableError 导入,以及 seedAutonumber(:2063 起)结尾那个 catch。delete() 及其前置行门区域一行未动。两者也无语义耦合:seedAutonumber 只在 applyAutonumbers 的插入路径上被调用。

#5846(单 id update 三读前置状态)—— 否,同上。
依据:update() 与其前置读同样一行未动;seedAutonumber 不在 update 路径上(调用点 :2049 位于 applyAutonumbers,只由插入路径进入)。

#4825 / #5108 同族收官件 —— seedAutonumber 邻域的残留(只报告,未顺手修):
仓库自己的权威(check-durability-degradation-log-level.mjs)在三个包 64 个读接缝上给出:本 PR 后无未登记违规,baseline 只剩 2 条 ——

1. metadata-protocol/protocol.ts::listCommits —— 真残留,已由 MetadataProtocol.listCommits 把 commit store 读不到答成 [] —— ADR-0067 时间线上「无历史」与「读不到」不可分辨(零日志,JSDoc 里写着这是设计) #5980 单独跟踪(闸门建议的修法与本 PR 同形);
2. objectql/engine.ts::referenceExists —— reviewed-legitimate,Promise< boolean | null > 是声明过的三态,不是编值。

闸门看不到的两处,如实记录供 PM 分诊(均未改动、未开单,因为本单要求只报告):

• engine.ts:3870 catch → return { verified: false, conclusive: false } —— 与 referenceExists 同形的显式三态(conclusive 就是「读没读成」位),看起来站得住;
• engine.ts:4686 catch → return records —— sys_file 读不到时原样返回入参、不记一行日志。它不编造空值(不落在闸门词表内),降级对调用方可见(拿到裸 id 而非 hydrate 后的引用),属功能性降级而非持久性降级;是否值得开单请 PM 定夺。

#4636(loadMetaFromDb packageId,决策箱在途)—— 无任何交叠。
依据:不同包、不同文件(@objectstack/metadata 的 loader vs @objectstack/objectql 的 engine),不同接缝(元数据加载 vs 自增号播种)。本 PR 唯一与 @objectstack/metadata 的接触是从其 /errors 子路径 import 一个纯谓词函数,不触及 loader 的任何代码路径。

---

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 7, 2026 2:17am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql.

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

• 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/runtime-services/examples.mdx (via packages/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql)
• 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)
• 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)

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.

[baozhoutao]

ACCEPT(执行席 PM 验收,rc.4 优先序)

逐项核过:① engine.ts diff 恰好两 hunk(import + seedAutonumber catch),#5929/#5846 区域零接触,与报告一致;② 12 条新用例含「表已有 D-0007 时故障写入失败而非伪造 D-0001、恢复后续 D-0008」的撞号钉子 —— 这是本单要消灭的伤害本身;③ 四肢反向验证(catch 回退 6/12 红名单逐条相符 + baseline 三向)预测/实测全中;④ 依赖路线按三轴论证并实测不成环,方案二未被拍掉、只是不代拍,合规;⑤ changeset 带行为变化升级须知,不触 releases/。

两处 gate-invisible 接缝的裁定::3870 显式三态(conclusive 即读没读成位)—— 同 referenceExists 先例,站得住,不立案;:4686 sys_file 静默返回裸 id —— 已立 finding 交分诊(见 issue 链接,随后补)。

翻 ready + auto-merge,进队列。落地后即触发 #5351+#5696 同批派发(同文件串行解除)。

---

Generated by Claude Code