diff --git a/CHANGELOG.md b/CHANGELOG.md index 30c1c1d..6752588 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/docs/agents/traps-index-pending.md b/docs/agents/traps-index-pending.md new file mode 100644 index 0000000..063b90d --- /dev/null +++ b/docs/agents/traps-index-pending.md @@ -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;索引表缺这一行属于**已知未完成项**, +不是遗漏。 \ No newline at end of file diff --git a/docs/agents/traps.md b/docs/agents/traps.md index a82a8cd..71b65cf 100644 --- a/docs/agents/traps.md +++ b/docs/agents/traps.md @@ -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"。