docs: 记录接管身份陷阱与演练判据变化
build / build (push) Successful in 1m20s

trap-18:快照相等 ≠ 本作业完成。写清真实现场(只写 database 阶段却被判成功)、
根因(版本行主键由 kind+scope+快照决定,登记是 upsert 会改写 source_job_id)、
判据(负例优先:内存 + 真实 PG 两个方向)与修法(effectiveOwnedBy 一份实现,
foreign_effective 走拒绝接管出口)。

AGENTS.md 是受保护文件,索引表那一行没有落盘:批准稿放在
docs/agents/traps-index-pending.md,列为已知未完成项。
CHANGELOG 记录本轮 Fixed/Changed 两条。
This commit is contained in:
姚章浩
2026-10-30 03:40:23 +08:00
parent 1d70059d32
commit d0fe257531
3 changed files with 72 additions and 0 deletions
+27
View File
@@ -1,5 +1,32 @@
# Changelog
## 开发快照(接管身份判据 + 真实中断演练的杀法与期望)
### Fixed
- **同一个快照由别的作业登记成生效版本时,接管会把它当成本作业"只差收尾"**:
`classifyTakeover` 原先只看"当前生效版本的目标快照是否等于我的目标快照",而版本行
主键由 `(kind, scope, 快照)` 决定、写入是 upsert(会改写 `source_job_id`),
所以"生产上有这个快照"被误当成"本作业写完了"。2026-10-29T19:16Z 的真实后果:
作业只写完了 `database` 阶段(`resources/index/wiki/verify` 仍 pending),
人工拉起后被判 `succeeded`,并把生效版本归属改写成自己。现在分类带作业身份
(`effectiveOwnedBy`):归属别的作业 ⇒ `foreign_effective`,走拒绝接管的失败出口
(不写目标、不释放维护、终态失败并指明预备份),不再按同快照收尾。
同一份身份判定与基线共用,快照相等不再单独构成"完成"证据。
### Changed
- **中断演练脚本改用"进程崩溃"语义,并把期望内容按快照推导**:
`scripts/library-kill-takeover.sh` 不再 `docker kill`(那是 Docker 手动停止,
`unless-stopped` 也不拉起,上一轮就因此空等 420s、最后靠人工 `docker start`)。
现在向容器 PID1 从宿主机发 SIGKILL,用 `docker events` 的 `exitCode=137` 作证据,
限期等 restart policy 拉起;策略没起来才显式 `docker start`,并在证据里记成
`restart_source=manual_start`,绝不当自动恢复。期望内容按目标快照的 manifest 推导
(`knowledges/chunks/wiki_pages`),`resources` 不进默认期望(同租户其它知识库的
资源会保留)。新增:`--kind sync|restore`、`--snapshot` 强校验、目标快照等于中断前
生效版本时**杀之前就拒绝**、五个写入阶段全部 `succeeded` 才算完整续作、
独立写集合校验器缺失即失败、首屏证据读回用 `owner_scope`。
## 开发快照(当前生效版本精确查询 + 真实中断演练的固定屏障)
### Fixed
+13
View File
@@ -0,0 +1,13 @@
# 待主人批准:AGENTS.md 陷阱索引补第 18 行
`AGENTS.md` 是受写入保护的 agent 指令文件(本机写入需要主人在 UI 上批准)。
本批次新增了 trap-18,全文已写进 `docs/agents/traps.md`,但索引表那一行**没有**落盘。
批准后请把下面这一行追加到 `AGENTS.md` §5 的表格末尾(第 17 行之后):
```
| 18 | 快照相等 ≠ 本作业完成:接管判据必须绑 `source_job_id` | `docs/agents/traps.md` |
```
现状:`docs/agents/traps.md` 已有全文 §18;索引表缺这一行属于**已知未完成项**,
不是遗漏。
+32
View File
@@ -442,3 +442,35 @@ scheme)。`validObjectKey` 认这种形状并把它拆成裸 key,`ValidObjec
**反例**:把窗口上限调大、或在内存里 `for` 一遍再 `break`——那是换了个数字,
不是换了判据。
## 18. 快照相等 ≠ 本作业完成:接管判据必须绑作业身份
**症状**(2026-10-29T19:16Z 真实现场):作业只写完了写入链路的**第一个阶段**
(`database`,`resources/index/wiki/verify` 还是 `pending`),worker 被杀、人工拉起后
又被判成"succeeded / finalize succeeded",阶段证据写"已登记生效版本(仅收尾,未重写生产)",
并且把生效版本的归属改写成这个作业自己。
**为什么它看起来是合理的**:分类只看一个事实——"当前生效版本的目标快照是不是我的目标快照"。
是 ⇒ `pending_final`(只差收尾,只做校验+登记)。而这个环境里同一个快照会被**多个作业**
发布(同一份冻结候选重复同步),于是"生产上有这个快照"被当成"我这个作业写完了"。
**根因**:`library_versions` 的主键由 `(kind, scope, 快照)` 决定
(`LibraryVersionID`),登记是 `ON CONFLICT (id) DO UPDATE`,会改写 `source_job_id`。
所以"快照相等"里没有作业身份这一维;只看快照就永远分不清"我发的"和"别人发的"。
**判据**(负例优先):
- 内存:当前生效快照 == 目标快照,但 `source_job_id` 是别的作业 ⇒ 必须是
`foreign_effective`(不是 `pending_final`);把归属改成本作业才允许 `pending_final`;
- 真实 PG:先 `RecordLibraryVersion` 一个 `source_job_id=别的作业` 的生效行,再
`loadLibraryVersionFacts` + `classifyTakeover`,断言 `foreign_effective`;
再用本作业登记同一快照(upsert 改写归属),断言 `pending_final`;
- 撤掉身份判定后这两条必须红(实测:`classify = "pending_final"`)。
**修法**:`effectiveOwnedBy(version, jobID, snapshotID)` 一份实现,接管与基线共用;
`foreign_effective` 走"拒绝接管"的失败出口(`failLibraryTakeover`):**不写目标**、
**不释放维护**、终态失败并指明预备份基线——目标可能半写,释放等于谎称已恢复。
**演练侧的同一条**:不同快照才证明完整续作。目标快照 == 中断前的生效版本时,
脚本在**杀之前**就拒绝(`--allow-same-snapshot` 只用于诊断,不算验收证据);
成功判据里必须包含"`database/resources/index/wiki/verify` 五个阶段全部 succeeded"。