diff --git a/AGENTS.md b/AGENTS.md index d719fdf..c8958c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -71,3 +71,4 @@ python3 ~/.hermes/scripts/gitea_api.py GET "/api/v1/repos/Weknora/knowledge-gove | 14 | 包一层装饰器就丢掉可选接口 ⇒ 写集合台账被静默跳过 | `docs/agents/traps.md` | | 15 | Stat/Delete/Copy 与 Open/Put 吃不同的定位符形状 | `docs/agents/traps.md` | | 16 | "资源不在预备份范围"≠"属于别的知识库",复用只认可审计证据 | `docs/agents/traps.md` | +| 17 | 分页窗口当索引:"当前生效版本"不能按最近 N 条找 | `docs/agents/traps.md` | diff --git a/CHANGELOG.md b/CHANGELOG.md index fc6ecd1..30c1c1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,35 @@ # Changelog +## 开发快照(当前生效版本精确查询 + 真实中断演练的固定屏障) + +### Fixed + +- **"当前生效版本"靠最近 50 条找,历史一长就把已生效读成没有**:接管分类 + (`classifyTakeover`)、基线判定(`classifyBaselineVersions`)与"已知索引映射" + 都把分页窗口当索引;窗口之外的生效版本被读成"不存在"之后,接管会把已经上线的 + 目标重写一遍,基线入口会为已有权威版本的目标再建一次基线。现在统一走两条精确 + 查询:`LibraryCurrentVersion`(`kind='production_effective' AND superseded_at IS NULL`, + 每 scope 至多一行)与 `LibraryVersionOfSnapshot`(按快照身份取回"已顶替"证据)。 + 同一含义只保留一份实现:同步与恢复共用 `knownIndexMapping`。 +- **同一判断在接口侧也要改,不是"只是展示"**:整库页的生产版本、生产同步闸口 + (这是**创建**判据:读错会放行一次不必要的覆盖)、建立基线入口(读错会覆盖 + 别人的版本)、归档保留里"生产生效版本"的保护标记,全部改用精确查询;查询失败 + 一律 fail closed(500/拒绝),不猜。历史列表仍是分页展示,`LibraryVersions` + 的 1..100 上限没动。 + +### Added + +- **真实 worker 中断演练的固定同步屏障**(`internal/testbarrier`,默认关闭): + 只有 `KG_TEST_BARRIER_DIR` 与 `KG_TEST_BARRIER_POINTS` 同时在场才生效,且只在 + 本机测试栈通过 compose overlay 注入。worker 每个阶段写完后写现场文件并停在固定 + 点位,演练方看到它再 SIGKILL——命中是确定的,不是靠 sleep 猜时间。进程被杀后 + 重启的 worker 看到同一份现场文件直接通过,不会把接管再拦住。 +- `scripts/library-kill-takeover.sh`:前置体检(目标拓扑、无在飞作业、无未释放 + 维护窗口、镜像真的带屏障代码)→ 注入屏障 → 等命中 → 锁住这一个作业 → 读回写 + 集合台账并独立校验摘要 → SIGKILL 容器 → 等同一作业被接管 → 校对目标内容、 + 维护释放与服务恢复 → 撤掉注入。只有整条链路成立才 exit 0;missed / 超时 / + 接管失败分别用不同退出码,**"没做"与"做成"分开**。 + ## 开发快照(真实同步/恢复后的页面修正与写集合转发) ### Fixed diff --git a/docs/agents/traps.md b/docs/agents/traps.md index 69d1e81..a82a8cd 100644 --- a/docs/agents/traps.md +++ b/docs/agents/traps.md @@ -410,3 +410,35 @@ scheme)。`validObjectKey` 认这种形状并把它拆成裸 key,`ValidObjec 证据单独落盘在 `reuse/.json`,摘要在写集合行里 —— 不冒充历史台账。 **反例**:为了"让同步能过"把"不在预备份范围"直接放行,或者恢复时按"没被引用就删"清理。 + +## trap-17:分页窗口当索引 —— "当前生效版本"不能按最近 N 条找 + +**症状**(比 trap-14 更隐蔽:它不报错,只是判错): + +- 接管时把一个"其实已经生效"的作业判成 `fresh`,于是把已经上线的目标**重写一遍**; +- 基线入口为一个已经有权威版本的目标放行"建基线"(会覆盖别人的版本); +- 页面上"生产当前版本"显示成"没有生效版本记录",同步闸口据此要求先建基线; +- 只有把窗口 N 从 50 调到 100/200 才"暂时好一点",再长一点又复发。 + +**根因**:`LibraryVersions(scope, N)` 是**分页展示**用的窗口(真实上限 1..100), +它按 `created_at DESC` 截断。可"当前生效版本"是每 scope 唯一一行、可能很久以前 +登记的事实;"本快照是否生效过"更是身份查询。用窗口当索引,历史一长就把**存在** +读成**不存在**——而且读成"没有"不会报错,只会让错误的选择看起来合理。 + +**判据**:把生效版本登记在 48 小时前、再灌 250 条更新的版本记录,然后: + +- `LibraryVersions(scope, 100)` 里**看不到**它(用例先断言这一点,否则夹具失效); +- `LibraryCurrentVersion`(`kind='production_effective' AND superseded_at IS NULL`) + 仍精确命中,接管判定是 `pending_final` 而不是 `fresh`; +- 换个更新的快照生效后,旧快照 `LibraryVersionOfSnapshot` 仍取回并带 + `superseded_at`,接管判定 `superseded`(拒绝用旧快照覆盖); +- 台账被写坏(同一身份两行、未顶替却不是当前生效、已顶替却是当前生效)⇒ + **拒绝挑选** / 判 `unknown`,不许挑一条"看起来对"的继续写。 + +**修法**:身份/当前状态一律走精确查询(`LibraryCurrentVersion`、 +`LibraryVersionOfSnapshot`、`LibraryVersionByRef`),窗口只用于列表展示; +同一含义的判定(worker 接管、基线、同步闸口的创建判据、归档保留的保护标记) +共用同一份实现,别各写一份"取最近几条再筛"。 + +**反例**:把窗口上限调大、或在内存里 `for` 一遍再 `break`——那是换了个数字, +不是换了判据。 diff --git a/scripts/test-scope.json b/scripts/test-scope.json index 465ff92..1677d15 100644 --- a/scripts/test-scope.json +++ b/scripts/test-scope.json @@ -227,6 +227,11 @@ "package": "knowledge-governance/cmd/worker", "test": "TestLibraryRunAnchorsWriteSetAndKeepsLookingItUpBeyondHistoryWindow", "reason": "必须在真实 PostgreSQL(TEST_DATABASE_URL 指向可销毁测试库)上跑:要证明的正是 Store 的『版本列表 1..100 上限』与按身份精确查询的差别,假版本库不实现该上限(本轮缺陷就是这样一路绿的);默认 CI 无库 ⇒ 跳过,本机一次性 PG 已实跑:原码红(library version limit out of range)、只改 200→100 仍红(超出窗口找不到)、修后绿" + }, + { + "package": "knowledge-governance/cmd/worker", + "test": "TestTakeoverClassificationUsesExactCurrentVersionBeyondHistoryWindow", + "reason": "必须在真实 PostgreSQL(TEST_DATABASE_URL 指向可销毁测试库)上跑:要证明的是『当前生效版本』不能按最近 N 条找——先灌 250 条历史把窗口挤满,再断言接管判定仍是 pending_final / superseded;假 store 不实现窗口语义,默认 CI 无库 ⇒ 跳过(补验路径:起一次性 PG 后设 TEST_DATABASE_URL 单跑这条)" } ] }