knowledge-governance/docs/library-migration-contract.md

发布身份与不可变计划：开发检查点

本批是统一修复的未完成检查点，不是发布就绪版本。不得依据本地门禁通过开启发布写门或部署云执行器。

已实现边界

• 显式逐表身份解析：字符串稳定身份、关系二元组、Wiki bigint；未知非空表、缺身份、错误整数类型和重复身份拒绝。
• chunks.seq_id、knowledge_tags.seq_id、wiki_log_entries.id 使用目标 sequence 分配并落入不可变写集合。接管校验来源 manifest、映射覆盖及 Wiki 写身份；回滚保留原始编号，不回退共享 sequence。
• 原始目标 before-image 与源候选导出分离，保留范围谓词内的软删除行和关联。resource_access_grants 外部级联入边已保护；尚未证明全部 FK/trigger 级联闭包。
• worker 包装器转发 AdoptWriteSet。不可变证据先同步文件，再同步目录；并发写者不能替换已存在的不同字节。
• ES 写前按全索引 ID 查归属，冻结逐 ID before/after/CAS 并持久化不可变 effect。维护窗口内使用既有 content 字段的暂态操作归属标记，不新增业务 mapping；确认归属后按 CAS 写入干净正文。标记写入成功但响应丢失时，新进程可从计划、完整内容、标记和 CAS 自动确认并补偿。无归属标记、内容或代次不符、清除标记后的未知结果、删除/补偿的未知结果仍拒绝，不能据此宣布完成恢复。
• 同 ID 资源即使在 before-image 内也必须证明等价才能只读复用；差异拒绝。已有 catalog 驱动自然唯一键预检及物理键绑定；完整负例矩阵仍未齐。
• 内容 canonicalization 保留大整数及失效期；孤儿查询错误向上传播。

兼容与回退

不修改旧 manifest/blob，也不改变其 hash。本批未增加或修改业务 schema、治理迁移。

新执行计划使用 V2，历史 V1 canonical 字节保持不变，并拒绝在 V1 中添加新执行字段；旧 V1 仅可读取诊断，不能把缺失副作用证据的旧计划当作安全执行计划。V2 当前仍不是完整跨存储协议：带归属标记的 ES unknown 已有真实跨进程补偿证据，所有无充分证据的分支仍保持维护，原生 OSS 条件创建协议仍未闭合。复用证据的 V2 before-image 等价证明与写集合版本独立。

一旦新计划被用于真实副作用，不得直接降级旧执行器消费新计划；须先证明没有在飞操作并完成原备份恢复和验证。当前没有部署，也未启动任何云作业。

阻止发布的剩余项

1. D0 完整源/目标 schema 指纹、FK 入出边、trigger、应用引用和序列消费者闭合。
2. 对象精确计划/intent/归属回执及版本化 MinIO 清理已局部实现并运行；MinIO 忽略 Delete IfMatch 的反例已记录，改用精确 versionId。业务桶不自动启用版本控制，无版本桶/未经验证的 OSS 适配写前拒绝。对象计划绑定与完整 adapter 隔离回归已复验；原生 OSS 版本协议已在明确授权测试前缀完成两个真实版本的精确写/读/清理，并列举确认版本与删除标记均无残留；严格条件创建与业务集成仍未闭合，不能放行。
3. ES 未记录的干净 finalization、删除与恢复网络结果不明时的进一步对账；不得将 fail-closed 状态算作完成。
4. 自然唯一键、resource_access_grants 与未知引用闭包。
5. 完整执行权续租、失权取消并等待写结束、跨执行域 fencing，以及队列提交补偿。
6. source candidate 精确查询与 API/UI 提交接线已测；旧 seal 显式证据关联已接管理员API/UI：核验原捕获响应/期望指纹与原manifest后只追加治理证据，不改快照hash；四种模式及真实页面闭环仍缺。
7. 两次连续真实 worker 中断，55 项完整验收、最终提交/远端 CI 与父独立复核。

已授权的云专用 KB 发布/恢复及测试 App 短停仍属于父独立审查后的后续阶段，无需重复索要开发授权；宿主重启与生产不在本批范围。

原生 OSS 的具体差异

原生版本协议实现提供 versioning 只读确认、带归属 metadata 的显式 append、精确 versionId 读取、完整回执比对后精确删除及再次读取验证。它不是 conditionalObjectStore 的替代，未接成生产 CreateObject。官方 PutObject 文档说明：桶启用/暂停版本控制时，x-oss-forbid-overwrite 无效。因此不能把版本 append 包装成原子仅新建，也不能用 S3 If-None-Match 的本机 MinIO 测试代替 OSS 证明。

真实测试只在 KG_OSS_VERSION_TEST_ALLOW=1、明确获准的 KG_OSS_VERSION_TEST_PREFIX、私有持久证据目录及测试凭据齐全时运行。默认不发云写；允许的测试桶固定为 dobot-weknora-test，端点固定深圳 OSS，只操作随机子键及精确版本，不改桶配置。未知 append 留下 intent，不盲扫桶猜测孤儿。限定前缀 kg-library-test-r4/ 已获明确授权并完成真实协议测试；生产条件创建的安全协议仍是实现缺口，不以版本 append 冒充严格仅新建，也不请求降低既有保护。

证据目录持久性边界

不可变 sidecar 的目录创建逐级检查真实目录，拒绝祖先软链接，逐级 fsync 父目录并传播错误；文件与最终目录仍同步。已验证祖先软链接写前拒绝、逐级同步调用覆盖和同步错误传播。这不是实际断电/文件系统崩溃测试，也不等于完整 F12：归档初始化现同步根目录及其父目录，任一fsync失败即拒绝返回可用归档，已做故障注入；PG锚点失败和跨节点介质策略仍需单独验收。