knowledge-governance/docs/library-acceptance-matrix.md

整库同步验收矩阵（真实证据对照，2026-10-29 重排）

本文件是唯一口径：状态只写实际发生的事，四类严格分开，不用"部分通过"含糊过去。

口径	含义
已完成·已验证	有代码 + 真实服务（真实 PG/ES/对象存储/原版 WeKnora API）跑出来的证据，或既有 CI 检查覆盖
缺代码	功能/契约本身没有实现；界面按"未接入"显示，不冒充
已实现·未跑	代码与测试在位，缺真实环境执行证据（不是权限问题）
需授权/需环境	实现所需的动作属于生产写入/读取/恢复，或需要本会话拿不到的资源

A06（内容、问答、引用图片效果、性能报告）已由用户取消，不作为门槛，也不在本表。

---

一、已完成·已验证

ID	要点	承载位置	证据（本轮或前轮，均可回看）
V01	只有对内/对外两个目标，身份来自配置映射	internal/httpapi/library_*.go；web/src/ReleaseTargets.tsx	overview 对非法 scope 返回 400；真实归档 internal/external 各自解析到唯一 KB
V02	解析/索引/Wiki 就绪，验收绑定本版	v071/library_source_settlement.go	结清检查在封存前执行、缺项阻断；页面注明依据哪次快照
V04	完整固定版本：文档+处理结果+资源+索引+完整 Wiki	internal/librarysnapshot/*	真实快照 f992d64e…：4 文档/38 分块/122 索引/21 资源/31 Wiki 页/55,309,044 字节，部件摘要逐项校验
V06	只同步知识数据，不含账号/会话/凭据	导出白名单（10 知识表 + 知识域索引 + 资源 + Wiki）	部件清单无 users/sessions/api_keys
B01	每次生产写入前完整预备份，失败零写入	v071.ProductionBackupStore.Prepare + prebackup 阶段	真实 PG/ES 上预备份 3111e823…；故障注入后用它恢复并校验
B03	每版保存完整 Wiki 与引用关联并校验	library_snapshot wiki 部件 + 摘要	真实快照 31 页逐页摘要；manifest 记录数量/字节
S01	数据库/资源/索引/Wiki 真实落地并校验	v071.ProductionLibraryTarget.Apply/Verify	本轮 sync libsync-internal-…1793221776816380302：database 67 行、resources 21、index 122、wiki 63 行全部 succeeded + verify succeeded；目标库 wiki 31 页
S02	生产不再解析/Embedding/生成 Wiki	index 阶段直接搬运归档 embedding	真实 ES 写入归档 embedding，未调用模型
S04	各阶段失败/超时/重启可追溯可恢复	library_jobs/library_job_stages + ReconcileLibraryJobs	阶段与错误持久化；worker 清理"队列无对应作业"的孤儿
S05	幂等与互斥（多 worker 安全）	幂等表 + active 唯一索引	真实 PG：同目标第二作业被拒；同键同 digest 复用；换 digest 冲突
R01	按指定版本手工恢复	POST /library/restores + library.restore	真实跑通：撤旧授权→503；签发 restore 授权→202→succeeded，内容回到目标版本（evidence/B_restore.json）
R02	恢复失败显式异常、不回退测试库	Outcome.State=rollback_failed + 独立阶段	隔离测试 + 前轮真半写场景（partial.json）
P01	作业阶段与整体状态	library_jobs.state/stage；页面阶段条	阶段勾选只认当前作业证据；无作业显示"尚未开始"
P02	四类分项计数/字节/错误	stageSizesFrom(manifest) + library_job_stages	真实数据：database 67/88086B、resources 21/53490166B、index 122/1624880B、wiki 63/105912B
P03	同步明细与异常	页面"同步明细"读阶段行	行来自持久阶段，刷新/重启可复现
U01	发布管理为主要入口（两库+单作业区）	web/src/ReleaseTargets.tsx	按确认稿布局，父会话已在登录浏览器核验
U02	权限边界	canWrite/canCapture，写操作需 engineer+	无权限不给封存入口；未接线显示通道状态
U03	操作确认	封存按钮 + 作业号 + notice	同一作业号重放返回已存作业并提示
D01	保留策略（数量/天数）	internal/libraryretention	未设置=0 按"全部保留"，不编默认值
D02	占用测量	internal/librarysnapshot/usage.go	版本数/去重内容/blob/未引用/清单；两份真实清单 55,309,693 字节
D03	依赖保护	libraryretention.Build 的 Protected/ProtectedBy	真实归档两版均因"最近测试封存"受保护
D04	清理预览	Build 的 Candidates/ReclaimPreviewBytes	keep=1 时仍 0 候选；回收预览只计独占字节
D05	容量门禁	CheckCapacity + sync gate	预算未设置→阻断；超预算→阻断并给预计字节
D06	测试残留口径	未引用 blob 统计	真实归档未引用 blob 为 0（口径，不等于扫过全部残留）
S03	实例级维护窗口：关入口→排空→静默证明→停写者→写入→校验→开入口	internal/libraryfreeze + librarymaintenance + 迁移 070–072	前轮 7 场景真跑全绿（normal/kill/applyfail/partial/crossscope/recover_refuse/recover_ok），本轮 sync/drain 场景继续复用；quiesce 证据、post_stop_*、journal、gate drain.json 均可回看
V03-a	撤销一份共享贡献后，保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确	由 WeKnora 源侧执行（cleanupWikiOnKnowledgeDelete + EnqueueWikiRetract），治理侧只比对/搬运	本轮真实验收：kgmaint 隔离实例、原版 API 顺序入库两篇文档 → entity/fa-bu-zha-men 同页双来源（2097 字节）→ 真实 DELETE /api/v1/knowledge/{id} → 页面保留、来源只剩保留文档、A 独有正文（ZEBRA-A-7731/9910）清除、B 贡献仍在、引用 2→1 且只剩 B 的分块、目录不变、A 独有页面/摘要整页删除、索引页不再列出、实体边无死链。13/13 检查通过。证据：kg-candidate-e2e/evidence-wiki-final/s8-final-checks-r1.json + 06-wiki-*-r1.json + s3/s6-db-*.json
V03-b	治理侧能把上述语义变化说清楚（不是页面级"无变化"）	internal/librarydiff/wiki.go CompareWiki；GET /library/overview 的 diff.wiki	逐页比对正文/来源/引用/出入边/目录，输出 sources_removed、citations_before→after、changed；单测 wiki_test.go、视图单测 library_wiki_diff_test.go；页面逐行展示（wikiContributionLines + 测试）
U04	维护级别/进度/恢复错误真实呈现	MaintenanceCard（web/src/ReleaseTargets.tsx）、/api/v1/library/maintenance	显示实例级/库级、持有 scope+作业、阶段、入口开/关、服务、开始/释放、进度（阶段名中文化）、恢复错误与处理记录；仅"窗口仍持有且作业失败"时给"按预备份恢复"；无记录时"未接入 + fail closed"。组件测试 6 项

二、缺代码

ID	缺口	现状与影响
R03	存快/恢复快对比	没有测速实现，也未测。不写没有测量的数字
死信解除契约	死信只能靠人工清理，没有"解除/豁免"契约	WeKnora task_dead_letters 无解决标记；导出/封存按"存在即阻断"（library_source_settlement.go）。本轮真实验证：早期错误模型配置产生的 2 条 wiki 死信直接阻断整实例结算，清理方式只能是删除行（记录：deadletters-before-delete.json，sha256 dd4d8f08…）。要变成可运维契约，需要上游给出解决标记或治理侧设计"带证据的解除"——未实现
封存入口接线（本机）	POST /library/captures 需要 LIBRARY_AGENT_SOCKET 指向真实 agent	候选/正式 api 都配置了 socket 路径，但本机没有运行 libraryagent，接口会 503 并明示"未接线"（不是静默失败）
CLI 实例级封存	libraryctl capture 只建库级窗口，不关入口	真跑结果：WeKnora 收到 SIGTERM 固定 exit=1，没有入口排空证明时被拒（未优雅退出（exit=1））。要在"不停共享栈"的前提下封存真实撤销后的库，需要把实例级 + 闸门接进 CLI（或部署 agent）——未实现

三、已实现·未跑

ID	要点	为什么未跑
V05	导出中源变更则拒绝或隔离	预备份导出前后行数静默检查已有（本机验证会拒绝）；真实并发写入的隔离演练未做
B02	资源在测试侧删除后仍可恢复	归档内容寻址已实现；"删测试侧对象再从归档恢复"实测未做
S03-b	死信/孤儿任务阻断的负向演练（本轮只验证了真实死信阻断）	真实阻断已发生并记录；系统化的负向矩阵未跑
V03-c	带"撤销后共享页"的整库封存 → 同步 → 恢复	上游语义已验证、治理差异已实现；但这台机器上 CLI 封存止步于上面的 exit=1 缺口，API 封存未接线，所以"封存一份含撤销结果的 Wiki 版本，再同步/恢复并逐行比对"没有产出真实证据。旧证据 drain-task-new-c（03:39）属于 0ef7984 之前的构建，不能拿来证明当前 SHA
Neo4j 启用场景	代码在 library_export.go 检查 graph_enabled，启用即 Neo4j graph snapshot is not supported 拒绝	本轮没有真跑"启用 Neo4j 的库被拒"：kgmaint 实例 NEO4J_ENABLE=false、测试库 graph_enabled=false。代码路径在，真实执行未做
排空竞态探针（最终构建）	关入口→排空期间产生的真实任务必须等到队列归零才停写者	本轮在最终构建（1faf513）上重跑 6 次（drain-task-final-1faf513{,-r2,-r3,-r4,-r5,-r6}.json），上传请求全部 Broken pipe、队列深度始终 0：闸门在 202 之后 <0.2s 就关监听，客户端来不及把请求送进去。未复现，不记为通过；旧 drain-task-new-c 的时间线仍是旧构建证据
U05	正式 8088 页面验收	正式栈仍是 0.1.114，本轮未替换；维护面板/逐页 Wiki 差异只在测试与候选构建里验证过

四、需授权 / 需环境

ID	事项	缺什么
D07	实际回收（真删对象/版本）	自动清理默认关闭；删除属于真实清理，需单独授权
远程生产	生产写入/恢复/清理	用户授权范围只到本机专用验收实例；远程生产一律未执行
生产目标维护	对共享业务栈开维护窗口	本轮明确不停 WKNFull-app；维护只在 kgmaint 专用实例上跑
生产封存/同步真实链路	需要在生产机部署 libraryagent 并接线	需要用户批准的部署窗口与凭据录入

---

五、本轮新增结论（写在这里而不是报告顶部）

1. Wiki 撤销语义是上游行为，必须用上游 API 验：顺序入库才产生"两篇共贡献一页"（并行入库会各自抽到不同 slug 生成两页，这是上游已知行为）。撤销后页面保留、贡献按文档摘除，12 项检查全部通过。
2. 治理侧不能只报页面级差异：撤销共享贡献时页面仍是"更新"，页面级计数会显示成"无变化"。已改为逐页语义比对，能指出"来源 -1、引用 2→1、正文变了、出边少了一条"。
3. 封存链路是本机当前的真缺口：CLI 封存被 exit=1 + 无入口排空证明挡住，API 封存没有 agent。这不是"Wiki 语义没验"，而是"带撤销结果的版本没法在本机封出来"。正式部署必须先接线 agent（见 docs/formal-8088-deployment-plan.md）。
4. 死信不是可忽略的告警：一条失败的 wiki op 就足以让整实例结不了算。要么上游给解决标记，要么治理侧设计带证据的解除，当前两者都没有。