Commit Graph

68 Commits

Author SHA1 Message Date
姚章浩 a1472ff29f fix(ds03): 早段held断言按发布代次比较整份索引
build / build (push) Successful in 1m25s
首轮到达held时按chunk-target取文档失败:早段数据库阶段失败前索引仍是
发布写入的源码分块,before-image的chunk-target本就不该出现。改为整份
读回等于applied,并显式断言chunk-target未提前回来。
2026-11-02 07:10:56 +08:00
姚章浩 f076c3af9c fix(ds03): 负控行复用声明形状以满足非空列
build / build (push) Successful in 1m25s
首轮真实早段运行在插入 pending=1 负控行时被 knowledges 的 NOT NULL
约束拒绝(enable_status),说明控制行缺少声明形状。改为复制本轮
canonical 来源行再覆盖 id/范围/pending,负控仍由正式结算拒绝。
2026-11-02 07:07:25 +08:00
姚章浩 6ec1821294 test(ds03): 新增合法来源早段PG恢复用例
复用一个已证明的 after:wiki 发布失败入口,唯一新增故障是恢复第一段 database
的真实主键冲突(外部范围同主键 knowledges 行,SQLSTATE 23505)。来源输入改用
R38 专用副本(未删除文档 completed/pending=0),封版前用产品自己的
checkLibrarySourceSettlement 在真实 PG 上结算,并保留原 pending=1 被正式契约
拒绝的负控;共享 ds02SourceRows 与 quiesce 都不改。
2026-11-02 07:04:53 +08:00
姚章浩 e760d85427 test(ds03): 新增PG恢复失败后同窗口续作用例
build / build (push) Successful in 1m25s
为什么:B29.2 的 PG 子断言缺一条真实命中 PG 恢复步骤的失败闭环。故障不改产品
返回值、不停共享 PG、不扩 ACL、不改 schema:恢复最后一段 PG 写入(wiki 阶段)
会把 before-image 的日志行按原 id 插回目标范围;先用一行"外部范围、同主键"的
日志占住这个 id,那条真实 INSERT 就得到 23505。用例记录服务器 SQLSTATE、同一
语句的探针读回(没有多出行)、失败阶段事务回滚,以及真实的部分恢复现场:
database 阶段已提交、wiki 表仍是发布写入、共享 resources 的新增行按设计留到
四阶段全部成功后再清。解除只删这一行,随后走同一 window_job_id 的正式 recover。

同时把夹具的索引登记接通运行器(KG_R38_INDEX 被真实消费),并落实际 namespace,
使 wrapper 在夹具未执行 t.Cleanup 时也只清登记的那一个索引。

验证:make verify 16/16 success(local 档案,identity=skipped 属本地常态);
PG 闭环的真实运行在提交后按同一 SHA 单独执行并留 raw。
2026-11-02 06:29:43 +08:00
姚章浩 98e7279632 test(ds03): 新增对象版本逐条绑定移除回执
build / build (push) Successful in 1m24s
把"发布真实新增的版本在恢复后消失"从"桶里没有这个 key"加强到:每个新增
versionId 都必须有同 key + 同 versionId 的网关 removed 回执,并断言绑定条数>0;
回执/投递的 plan 仍必须等于发布期写集合摘要。

验证:go vet 通过;make verify 在本提交前的同一源码状态已 16 项全 success,
最终证据用提交后的完整 SHA 重跑。
2026-11-02 05:23:43 +08:00
姚章浩 30f223bcc4 test(ds03): 对象恢复补十表全形状与版本字节指纹
build / build (push) Successful in 1m25s
为什么:
- 上一版对象恢复证据里 knowledge_tags/knowledge_tag_relations/wiki_folders/
  wiki_page_issues/wiki_log_entries 五张表 before/source 都是 0,把"空表相等"
  当成全形状恢复,父复验据此不能关整项。
- 对象"字节摘要"只用了 ETag+size,不能称逐字节指纹。

改了什么:
- 复用 DS02 已验的十表声明与独立 oracle(ds02SourceRows/ds02Expected/本地号
  mapping oracle),对象分支改用真实 v071 十表 catalog 建表;目标 before-image
  与来源快照十表全非空,邻库/外部租户哨兵逐表非空。
- 逐种引用承诺(父子分块、标签关系、资源绑定、目录父子、wiki 引用、页面问题、
  日志)在声明来源、发布实际写入、恢复后 before-image 三处都要求 matched>0。
- 对 before-image 每个受保护 versionId 单独 GET 算 SHA256,恢复后同 version
  再独立算一次并比较;真实新增版本消失且必须有网关 removed 回执。
- 发布期写集合摘要与预备份版本证据、网关回执/投递计划一致;恢复意图
  request_digest 独立重算后逐字符比较。
- 重放后的 PG/ES/对象/回执原始读回全部落盘,供父独立比对。
- 运行器写 run-identity.json(主命令/label/完整 SHA/版本/二进制摘要),
  报告头与 raw 统一;label 前缀统一为 ds03-object-*(清理器同步)。

验证:make verify 16 项全 success(RC=0);真实隔离对象故障→held→同窗口
recover 用例已在本地跑通(dev5),最终证据用提交后的完整 SHA 重跑。
2026-11-02 05:16:41 +08:00
姚章浩 2cbeca8d1d test(ds03): 记录对象拒绝的网关原始响应
build / build (push) Successful in 1m26s
拒绝事件补 503 与原始正文,证据可直接引用网关响应,而不只依赖客户端错误文本。
2026-11-02 04:47:26 +08:00
姚章浩 b39902ef90 test(ds03): 修正对象效果文件字段读取
build / build (push) Successful in 1m25s
对象效果 JSON 使用 resource_id/key 小写标签;按 Key 匹配会得到空集合,
导致已发生的 delete-intent 被误报为缺失。
2026-11-02 04:39:37 +08:00
姚章浩 68f03bb30e test(ds03): 对象恢复传输失败后同窗口恢复
build / build (push) Successful in 1m26s
对象分支在对象网关前拒绝一次回滚删除请求(派发前 503、转发 0、无 intent),
让自动回滚真实失败并进入 held;撤障后用同一 recover API/窗口/备份恢复,
并读回十表整行、ES 完整 _source、对象全版本与 delete markers。

同时补四类进程 executable/hash 身份与对象清单分页;旧的 ES 分支保持不变。
2026-11-02 04:37:16 +08:00
姚章浩 93c0f34aac test(ds02): 同租户不同知识库十表同输入对照
build / build (push) Successful in 1m26s
跨租户 bundle 的旧侧必须在 wiki 之前省略 resources/resource_bindings,
不能据此声称"同输入已收口"。新增同租户、不同知识库场景:旧 6fe98c9 的
resources 阶段只按 tenant_id 查资源行,同租户下不再提前失败,因此两侧
都能消费完整十表归档。

新增 ds02_identical_input_test.go:导出十表 bundle;两侧在执行前各自导出
逐表来源归档、实际目标种子、完整 DDL、三条序列、ES 文档与对象字节;
唯一 namespace 替换(桶名 %BUCKET%)按同一规范归一,物理身份单列。
2026-11-02 04:05:03 +08:00
姚章浩 98ccb9366e test(ds02): 负控制落盘并修正 gofmt
build / build (push) Successful in 1m26s
为什么:CI 在 07a9caf 上 format 红(ds02_identity_test.go 未 gofmt),本地那次
make verify 跑在文件生成之前,不能算数;同时 /v1/encode 负控制只有断言、没有
落盘证据,复验时无法回看分类结果。

改了什么:gofmt 两个测试文件;负控制把实际出站条目与被判为 embedding 的差异
写进 raw(negative-control),正例仍只对发布段计数。

验证:make verify 16 项全绿;随后以新 SHA 重跑 DS02 隔离套件。
2026-11-02 03:48:52 +08:00
姚章浩 07a9caf22b test(ds02): 收紧映射/引用/哨兵与进程身份 oracle
build / build (push) Failing after 19s
为什么:Astra 复验已独立复现旧 LocalIDs 循环的三种盲区——目标互换、错误来源集合、
不存在的目标都能绿;引用把 pre/next/parent 混在一个 OR 里,parent 分支没有覆盖;
成功路径没有序列非空比对;零 Embedding 只测了一个 client;旧侧对照用 rev-list 的
258 冒充 0.1.258(该工作树 identity 实际是 0.1.148);runner 在异常/超时路径不保证
清理,读回把任何非零退出都当"不存在"。

改了什么:
- 抽出独立语义 mapping checker:三表 (table,column,source,target) 精确集合 + 真实行
  对应;持久账本正例与语义副本变异走同一 checker,digest gate 与语义 gate 分开。
- 测试自带十表 scope 声明并与 schema 列集合对拍;逐种引用非空命中,软导航字段显式
  列为范围外;外围 ES 完整 _source、res-other 字节各补负控制。
- 零 Embedding 改为发布段独立记账:ES + 对象存储两个可达 client,自定义 /v1/encode
  负控制;范围只声明本测试可达 client,正式全链留给 DS03。
- 冻结输入 bundle(十表行/目标种子/序列/ES/对象/DDL,逐表 hash):旧 6fe98c9 与新源码
  同一 bundle 文件;旧侧真实 23505,新侧发布成功 + 独立 oracle。
- 测试进程身份:runner 注入 test-only nonce/commit/树摘要,进程自报 executable hash。
- 历史兼容矩阵改同 catalog 初始化,三条序列显式存在并逐例 before/after。
- runner v2(证据根,不在本仓):失败关闭、finally 清理、所有权重核、keep-failure。

验证:make verify 16 项全绿;ds02_runner_v2 三次隔离运行(含负控制与 keep-failure)
raw 见 handoffs/develop-release-contract/ds02-v2-*;旧侧探针 ds02-bundle-old2。
2026-11-02 03:46:26 +08:00
姚章浩 eea0a0ec3b test(release): 整库发布独立oracle与历史兼容矩阵
build / build (push) Successful in 1m25s
十表全形状夹具补独立 oracle:逐列内容、全部引用、索引正文/向量、对象字节与
零 Embedding 调用;期望由夹具声明推导,不调用被测映射器生成。Wiki 日志本地号
映射断言双射;正文/向量/引用/映射对真实目标变异后 oracle 必须红、改回必须绿。

补历史兼容矩阵:旧 manifest、V1 台账、空作业/目标身份等缺证明组合在正式入口
被拒绝,拒绝前后 PG/索引/对象版本/序列哈希不变;不做 V1→V2 迁移。

旧版对照:0.1.258(6fe98c9)在同一隔离库/桶/索引以相同输入复现
wiki_log_entries_pkey/23505;当前代码同一输入发布成功并分配本地号。
2026-11-02 02:58:50 +08:00
姚章浩 1d2fff8639 test(release): 正式 worker 与维护恢复入口的 held→恢复闭环验收
build / build (push) Successful in 1m25s
真实 publish 在四类写入完成后由校验不一致失败进入回滚;回滚在
restore-finalize-intent 落盘、marker 仍在自身世代时被拒绝 clean 派发,
窗口 held、两个维护记录 needs_restore、写入口 409;撤故障后
POST /library/maintenance/recover 以同一 window/job/backup 续作成功,
PG 逐行/对象版本/ES _source 全量恢复并重开入口。仅新增验收与运行器,
产品行为与判据未改。
2026-11-02 01:44:03 +08:00
姚章浩 066dc45a25 fix(release): 删除型索引恢复不再用 ES 统计计数放行
build / build (push) Successful in 1m34s
- ES `_stats` 写计数是分片生命周期统计(官方文档:分片迁到另一节点时该分片统计清零),
  索引 uuid 不变不绑定统计生命周期,清零后重新累计到同一数值(ABA)无法排除。
  撤销 r36 的"写计数器栅栏"授权:既不落盘也不读取,统计仅作诊断。
- 删除型恢复(独占 `_create`)只有在本次尝试开始时不存在任何恢复意图、且文档确实缺失时
  才可重做;既存 restore-mark-intent 配缺失文档一律 held、零写入。
- 保留可证明路径:marker 仍在且世代一致的 clean 收尾重试;文档仍是 applied 结果、
  世代一致的 DELETE 补偿重试。
- 新增 ABA 反例(传输层 stats 故障模拟、真实 ES 文档写删、未重启共享 ES);
  B19 / clean / delete 安全正例全回归。

验证(真实 PG/ES/MinIO 隔离夹具):
- ABA 反例:旧代码 RED(restoration must be held, not rebuilt),新代码 PASS
- 索引/恢复回归 13 项 PASS
- 回滚回归 2 项 PASS
- make verify 16 项 success(identity 仅 CI 可核)
未部署、未写生产/云、未重启共享 ES。
2026-11-02 01:19:00 +08:00
姚章浩 ff257064c3 fix(release): 索引恢复用写计数器栅栏与世代证明续作
build / build (push) Successful in 1m31s
- 删除型恢复写入(独占 _create)不再把"文档缺失"当成"证明从未发送":
  marker 写成功、回执丢失、随后被删除与从未写过完全同形。现在在第一次
  派发前把索引写计数器(uuid/index_total/delete_total)与意图一起原子
  落盘;只有栅栏逐位未变才允许重做,推进/缺失/读取失败一律 held。
- restore-finalize-intent 已落盘、干净写入在派发前被拒绝后,标记体仍在
  自己那份世代即可证明干净写入没有落地,按同一 CAS 继续收尾。
- 删除补偿(Before 为空)在派发前被拒绝后可按 applied 世代重放 DELETE;
  文档已变或世代不符仍 held。
- 对象验收证据改用 ListObjectVersions,不再用 ListObjectsV2 冒充版本枚举。

真实 PG/ES/MinIO 隔离夹具:3 个新用例先 RED 后 GREEN;索引/恢复回归 12 项、
回滚回归 2 项全绿;make verify 16 项 success(identity 仅 CI 可核)。
2026-11-02 00:49:30 +08:00
姚章浩 de867078c6 style(release): gofmt 索引恢复验收测试
build / build (push) Successful in 1m39s
CI 的 format 项只在已跟踪文件上扫,提交前测试文件还是未跟踪状态,本机 make verify
没看到它;补一次 gofmt,不改行为。
2026-11-02 00:08:07 +08:00
姚章浩 b15633d37c fix(release): 索引恢复在确定没写进去时按世代证据重做
build / build (push) Failing after 20s
恢复/回滚的索引步骤如果在"持久意图落盘之后、派发之前"确定失败,重试会被判成
unknown restoration lacks exact operation marker/content/CAS 而永久 held:代码
只看标记在不在,没看"这份意图到底发出去没有"。新增 restorationProvablyUnsent:
观察到的内容仍等于自己确认过的 applied 结果(删除即缺失)、且世代与那份回执完全
一致时,成功写入必然产生新世代这一事实就证明恢复写入一次都没到达索引,按原
before-image 重做不会覆盖任何别人的字节。内容对但世代对不上、或应用期停在标记态
却对不上标记体/世代,仍然 held(B19 不放宽)。

新增一次性恢复写入派发边界 restoreMarkerFault(生产恒为 nil),用来把"边界上确定
没写进去"与"写入结果不确定"分开演练。

验:新增 TestContractKnownIndexRecoveryAfterRestoreBoundaryFaultIsolated 在真实
ES/PostgreSQL/MinIO 上跑:故障前 applied 回执已落盘、失败时派发次数 0、状态为
rollback_failed;撤故障后同一 job/预备份恢复完成,PG 逐行字节、索引 ID+字节+新世代、
对象键集合全部回到 before-image,重放不再派发。RED 证据是重试报 held,GREEN 后
TestContract(Index|KnownIndex).*Isolated 11 项与两条 rollback 用例全绿,make verify
success。
2026-11-02 00:06:54 +08:00
姚章浩 943b617b1f test(isolated): 支持保留隔离演练现场供本机 UI/API 验收
build / build (push) Successful in 1m28s
KG_R8_KEEP_SCENE=1 时不删索引与对象桶、落网关审计公钥与派生令牌(0600),
默认行为不变(断言后精确清理)。仅测试侧改动,产品代码与数据契约不动。
2026-11-01 18:26:07 +08:00
姚章浩 99055a582e test(library): 补孤儿校验锚点失败与介质失效的真实隔离用例
孤儿校验:缺 knowledge_id 的索引文档被拒绝、未知 knowledge_id 如实报孤儿、
数据库层中途失败(真实 statement timeout,SQLSTATE 57014)冒泡为错误而不是
"没有孤儿"。

锚点:真实 PG 约束拒绝写版本锚点时,作业在任何阶段写入前失败、目标零写入、
版本表不留本次行;去掉故障后同一请求写满四阶段。

介质失效:归档 part 缺失/摘要不符时恢复停在内容层,保持 held + RestoreBlocked,
服务与入口都不恢复、校验不再跑。
2026-11-01 17:21:42 +08:00
姚章浩 8df19f9368 test(library): 补软删除共享资源与索引 oracle 隔离用例
真实本机 PG/ES/MinIO 上补五组场景:7 张带 deleted_at 表的软删除 before-image 与
恢复逐列复原;同 _id 属其它知识库时外部文档 _source/seq_no/term 逐字节不变;
正文/向量/metadata 任一篡改都让独立 oracle 变红;晚阶段失败后既有对象精确版本
不变;同 ID 共享资源在 handle/定位/字节三类差异下写前拒绝。另在复用用例里补
"no-op 复用不改写对象版本"的断言。

需隔离服务的用例继续在 test-scope.json 显式声明:普通 CI 跳过不算通过。
2026-11-01 12:08:55 +08:00
姚章浩 8d838d9cb4 feat(library): 整库发布身份、写集合与收尾边界
build / build (push) Successful in 1m45s
执行时真实时钟与持久授权回读(撤销/过期即停并保留预备份)、写集合写前落盘、
租约与 attempt 身份、恢复队列与原发送身份分离、成功收尾必须释放维护后再登记终态。
2026-11-01 11:35:10 +08:00
姚章浩 8febe12d7d test(library): 隔离数据契约与 r11 身份自然键矩阵
真实本机 PG/ES/MinIO:v071 目录镜像 10 模式、结构引用/游标 15 模式、
8 表×2 外部范围身份矩阵、13 模式自然键(含软删除与合法同 parent 正例)、
备份期间三注入、收尾故障与授权撤销两个真实治理 PG 用例。

需隔离服务的用例在 test-scope.json 显式声明:普通 CI 跳过不算通过。
2026-11-01 11:35:09 +08:00
姚章浩 5eef13b615 feat(object-gateway): 统一对象写网关与不可变治理日志
方案A:所有对象写入经 loopback 网关,持久计划/grant/intent/逐版本 receipt 与
attempt→grant delivery 落在治理 PG;scope 由 provider+endpoint+bucket 决定,
同一物理桶只允许一个写域。版本 append 不等于 CAS,未锚定计划在首笔业务写前拒绝。

本提交只含网关与其适配层接线、协议文档;生产独占、凭据切换与桶设置未改动。
2026-11-01 11:35:05 +08:00
姚章浩 ee9d078794 fix(release): 分配目标分块序列并保持原值恢复
build / build (push) Successful in 1m26s
2026-10-31 06:08:05 +08:00
姚章浩 e6472b0ec6 feat(library): 云测试发布目标接入的角色分离、快照搬运与图谱门禁
为什么改:发布执行链是"与目标同机"假设写死的(本机 docker.sock、本机 drain.json、
本机 Redis/PG),把目标换成云测试不能只改展示 URL;直接搬整套 worker 又会抢走
本机封存/QA/周报队列并按本机配置写错目标。所以先把"谁消费哪段队列"变成显式角色,
再补齐跨主机搬运与目标侧门禁。

角色(LIBRARY_WORKER_ROLE=full/release-executor/capture)不只影响 handler 列表,
还决定是否拥有 DDL(release-executor 只读校验迁移版本,落后即拒绝启动)、
收拾哪些 library_jobs.kind、是否跑 release 接管扫描、是否起 scheduler/QA/周报/探测。
capture 保留本机原有全部业务;release-executor 只挂 sync/restore/recover/baseline。

快照跨主机:新增内容寻址的 bundle(版本清单先落、blob 按 sha256 命名、清单最后
Link 作提交点),pack/unpack 幂等且拒绝覆盖与同名不同内容;执行器使用前仍逐 blob
重算 sha256,因此传输不可变有两道证据。

目标侧门禁:目标知识库 graph_enabled=true 时拒绝发布(发布只写 PG/ES/OSS,不写
Neo4j;未知也拒绝),只读检测、不改目标配置、不做图谱迁移。

云端入口:新增 drain 感知的 ingress 闸门(建连超时与读超时分离,半关闭单向传播,
SIGTERM 排空后写 drain.json 并 exit 0/2)、compose 叠加片段(app 不再发布端口、
frontend 与 adapter 的入口收敛到闸门、指向真实网络 weknora-test-v071-network)、
执行器启动脚本与治理 PG 反向隧道脚本(默认 unix socket,不占 TCP)。

验证:deploy/cloud-test/test_gate.py 13 项全 PASS(含 12 秒静默流、半关闭、2MiB 完整、
排空 exit 0/active_at_close=1、排空超时 exit 2、上游不可达不挂住);go test 相关包全绿;
scripts/ci_checks.py 16 项全部 success(EXIT=0,1241 用例通过/0 失败/191 已声明可选集成跳过);
云测试只读预检 17 项 / 6 FAIL,FAIL 项即当前部署缺口(无闸门、app 仍发布端口、
adapter 与 frontend 仍直连 app、云端归档根未建),未部署、未改云端任何状态。
2026-10-30 18:38:38 +08:00
姚章浩 a7d643635a fix(library): 守卫按行取作业身份、同作业多代次、原作业续作与执行域准入
build / build (push) Successful in 1m27s
R1 维护/发布守卫硬编码 j.id=$1:维护类入口的 $1 是 scope/instance,作业号在 $2,
导致 update/release/ingress 六个入口正常路径全部匹配不到作业。改为按被更新行自己的
owner_job_id 生成条件,并同时要求该代次在 library_attempts 里仍活跃。

R2 认领只改 jobs.attempt_epoch 不改 attempts.epoch,第二次接管即错位;唯一索引
(job_id) 与"每次接管新 attempt 且历史不可变"矛盾。改为同作业多代次:锁作业行与
operation 行、同 owner 幂等续租、活跃未过期者让路、过期/本作业旧代次标 abandoned、
新代次 epoch=max+1,并清同 operation 其它作业行租约。迟到 write/renew/finish 一律
ErrLibraryEpochStale(finish 补了"只能在活跃态进来一次")。

R3 续作不再新建 -resume 作业:PrepareLibraryJobResume 让原业务作业回 pending 并显式
结束上一代,维护窗口/journal/预备份/写集合仍按原作业 id 归属,代次由 worker 起手递增。

R4 执行域准入改为注册 handler 前读事实:目标实况(KB/租户/schema/索引)、旧 release
路由绑定的 KB、未释放维护窗口持有者;未知或重叠即拒绝执行(不做维护动作、不停既有服务)。

同时自纠 5 项设计偏离:current 次序键取意图创建时间(旧意图迟到事实被拒)、首次锚点
改事务 FOR UPDATE + 回读且 NULL≠0、版本事件冲突只做加法且 xmax=0 才算新事实、
恢复作为新 kind=recover 意图推进 current、隔离测试加测试库护栏并清理残留 schema。

测试:真实 PG(kg-pgtest-writeset,一用例一 schema)新增 8 条集成用例覆盖上述正负例;
go test ./... 全绿(50 包)、go vet/build rc=0、web tsc + vitest 485 通过、make verify 16 项通过。
2026-10-30 17:20:40 +08:00
姚章浩 98294b9583 fix(library): 统一执行身份、终态收尾、准入与数据身份
build / build (push) Failing after 24s
why:审计 19 项(12 P1 / 7 P2)来自同一批根因,逐点试错会把协议撕成十几份:
  · 意图与执行混为一谈(F01/F15):`library.sync:<scope>:<快照>` 是终身幂等键,
    A→B→A 的第三次发布拿到第一次的历史成功作业,什么都不做;
  · 版本行既是实体又是事件(F02/F09):主键只由 (kind,scope,快照) 决定、写入是
    upsert,第二个作业覆盖 `source_job_id`/`evidence`/`created_at`;
  · 接管没有代次(F13):两个 worker 都能认领同一 pending 作业,失租的旧执行还能
    写业务状态、释放别人的维护锁;
  · 早退与终态没有统一政策(F03/F04/F05/F06):半写窗口的前置检查失败会重新开门、
    服务起不来也照样开入口、journal 终态后收尾不可重建、恢复成功不回写 current;
  · 数据身份与准入各写一套(F07/F08/F14/F17):接管丢了复用语义、全库搬运不改
    location_hash、通用入口可造 library.* 作业、目标模型从没被问过;
  · 存储/容量/UI/CI 判据各自为政(F10/F11/F12/F16/F18/F19)。

what:按批准的一套协议集中实施(详见 handoffs/release-consolidated-implementation/
current-contract.md):
  · operation(一次明确意图)/ attempt(epoch 代次)/ 不可变版本事件 / current 指针;
    治理库迁移 76,只动治理库,不碰 WeKnora Schema/源码/镜像;
  · 所有业务状态、阶段、版本事件、维护锁写入带 epoch 守卫(失租代次写不进去);
    心跳失租立刻取消 handler;
  · 半写窗口早退保持关闭;服务未全部健康绝不开入口;journal 终态可从持久事实重建
    收尾;恢复成功登记 recovery 事件并推进 current;
  · worker 在动维护前核对业务行/kind/scope/队列关联;通用入口拒绝 library.*;
  · 全库搬运重算 location_hash 并与文档级导入共用实现;接管消费写集合的复用决定;
    发布前核目标实时模型契约、容量门禁前置;
  · 存储保护闭包改为全量依赖、类型只认显式登记、保护未知则不出可删候选;
  · 页面核 HTTP 状态与结构、恢复纳入轮询、Wiki 差异覆盖标题/摘要/父级。

how:`make verify` rc=0(16 项必需检查全绿,含 go test 全量与前端 485 例);
`go vet ./...` rc=0;`npx tsc -p tsconfig.json --noEmit` rc=0;逐项负例见各包测试
(F03/F04/F08/F12/F13/F14/F16/F18/F19 都有先红后绿记录)。
未执行:治理库迁移到任何已有库、真实 PG/ES/S3/WeKnora 集成、故障注入、部署。
2026-10-30 16:14:54 +08:00
姚章浩 0252492e53 fix(library): 恢复保留下来的资源凭可审计证据复用
同步 A 成功后手工恢复 B,resources 表既不删行也不删对象;再同步 A 时,
resources 里那 21 行以“同租户但不在预备份范围”被判成别人的知识库,整次
同步在写第一笔之前被拒。

“目标里没人引用”不是归属证据:历史孤儿、其它知识库暂未绑定的资源都满足
它。改成唯一放行路径——可审计复用(v071/library_reuse.go):
1. 持久来源:这个目标成功同步过且登记过生效版本的快照,或它自己的预备份,
   且同一资源行在来源里内容一致;
2. 整行内容(除易变时间戳)与本次写入将要落地的行完全一致;
3. 该资源的对象字节与本次快照归档摘要一致。

三条同时成立才允许复用:写入阶段跳过它(不重写行、不重传对象),写集合里
记 existing+reused,恢复不清理;证据单独落盘 reuse/<digest>.json,摘要写进
写集合行,不冒充历史台账。内容不同、来源范围不同、或没有持久来源一律继续
拒绝,且拒绝发生在写入之前。

为什么把预备份也算来源:恢复作业的写集合同样会把“本目标历史状态里已有的
资源”判成跨范围冲突,而它们本来就出自这个目标自己的快照。

验证:隔离 PG+ES+MinIO 真服务下新增 5 个场景用例(复用成功且 xmin 不变、
无来源拒绝、内容不同拒绝、同内容不同来源拒绝、wiki 半写回滚只清本次新建);
v071 整包与全仓 go test 通过;make verify 15 项全绿。
2026-10-30 01:59:32 +08:00
姚章浩 168fc2ecb7 fix(release): 对象存储四个入口共用同一定位符解析
真实资源路径是 storage://<backend>/<provider>://<bucket>/<key>。Open/Put 用
validObjectKey 并拆出裸 key,而 Stat/Delete/Copy 用只认单层的 validObjectLocator
且把整串当对象键——对象在桶里却校验读不到。集成用例只喂裸 key,把这条不一致
藏了过去;写集合用例里那句"读不到也算通过"同样把断言关掉了。

现在四个入口共用 validObjectKey + providerPathFromLocator;集成用例喂真实定位符,
负例覆盖键不存在 / provider 不符 / 路径穿越 / 复制源不存在,并验证 Delete 后再读必失败。
2026-10-30 01:33:45 +08:00
姚章浩 e0768f2caa fix(library): 写集合台账与跨范围冲突预检
build / build (push) Successful in 1m34s
失败恢复会在写完之后按"目标租户里没人引用"清理资源行,于是历史孤儿、同租户其它
知识库暂未绑定的资源、被共享的资源都可能被删掉;而预备份里没有这些行,删了不可
恢复,随后整实例指纹才发现不一致,只能停在 rollback_failed。恢复校验依赖的整实例
证据又只存在内存里,worker 重启后只按快照 id 恢复,等于静默跳过比对。

改法:写第一笔之前把"本次明确写集合 + 写前存在状态 + 预备份时刻整实例内容证据"
算出来并按内容寻址落盘(文件名与治理库里的引用都是 sha256),摘要登记在预备份
版本证据里;恢复只删"写前不存在 ∧ 由本次写入 ∧ 不在恢复内容里"的精确 ID,并对
资源额外要求仍无绑定/正文引用;缺记录、记录被改、绑定对不上都直接失败、维护保持。
resources 的 upsert 补租户限定,跨范围同 ID 在写入之前就被预检拒绝。
整实例指纹从"身份集合"改成"逐行内容摘要",别的知识库同 ID 行被覆盖写坏也会暴露。

本地验证(已跑):
- make verify 15 项全 success(identity 因本地档案 skipped)
- go test ./internal/releaseadapter/v071/ -run Isolated(真实 PG + 真实 ES +
  真实 MinIO 对象存储,写失败按定位符注入):目标非空/同租户其它知识库/共享资源/
  历史孤儿/跨租户数据在失败恢复后逐行字节不变、本次残留 0;缺写集合拒绝恢复;
  跨范围 ID 冲突在写入前拒绝;wiki 阶段半写回滚干净
- SIGKILL 子进程后按盘上写集合接管恢复,目标原有数据逐行不变
- go test ./internal/libraryrelease/:写集合先于第一笔、规划失败/登记失败都不写目标、
  接管不重新规划
2026-10-29 23:55:13 +08:00
姚章浩 5defe238e0 fix(library): 跨范围同步按目标范围改写并校验残留
build / build (push) Successful in 1m34s
真实事故:源 KB(10000/0c84a098) 同步到目标 KB(10001/e64e82b5) 时,归档行被原样
插入目标库,落在来源租户/知识库;资源阶段随即报"生产缺少资源 ... 的存储路径"
(资源查询按目标租户过滤,看不见刚写进去的行)。回滚只按目标范围回放,于是页面
报"已恢复到预备份",目标却多出 4 文件/38 分块/21 资源/4 绑定。

改:
- 写入与校验共用 retargetRow:tenant_id / knowledge_base_id / 资源定位符(后端、
  provider、桶、租户前缀) / storage_backend_id / provider / embedding_model_id
  统一映射到目标范围;行里的来源身份对不上就失败,宁可不写。
- Verify 增加"本次写集合仍以来源身份残留"判定;Restore 增加整库指纹比对(预备份
  时刻 vs 恢复后)与孤儿资源清理,回滚后用 Verify 复核,恢复工具退出 0 不再等于
  恢复完成。
- 新增 cmd/libraryresidue:按归档身份精确、可备份、可复核地清理已知的范围外残留。

验证:make verify 全绿;真实 PG+ES 用例复现"源目标 KB 不同 + 目标非空 + 资源阶段
失败",断言回滚后无来源范围残留、其它租户行未动、恢复后内容=预备份;正向用例断言
行落在目标范围且资源定位符指向目标存储。
2026-10-29 22:11:59 +08:00
姚章浩 517d5f862d feat(library): 首次发布接上目标权威基线与整库空判定
目标非空又没有生效版本时,首次发布以前只能停在"权威版本未知"。现在有了
真实入口:管理员发起 baseline 作业,worker 在维护隔离下把目标整库捕获成
归档快照,再用同一套 Verify 证明目标与快照逐类一致,最后登记
production_effective(证据写明 origin=target_baseline、快照 ID、逐表行数、
目标索引映射)。不写目标内容、不清空目标、不手写版本。

同时修两处会误导人的判定:
- productionScopeEmpty 原来只数 knowledges,"文档删了但分块/Wiki/资源还在"
  的目标会被当成空库;改用适配层同一份表清单与范围过滤逐表计数。
- 概览里的"测试封存候选"原来取该 scope 最新一份归档,而归档里还有生产
  预备份与目标基线快照;改为只认版本登记里 kind=test_sealed 的那一份。

迁移 075 放开 kind='baseline' 并把它并入 sync/restore 的写互斥索引;
worker 重启时用同一作业 id 接管未完成的基线窗口。维护接口补 capability,
页面才能区分"未运行维护"与"维护能力没接线"。

验证:go build ./... / go vet ./... 通过;新增用例覆盖管理员校验、已有生效
版本拒绝、目标读不到时零作业零版本、候选来自登记、缺项文案指向基线入口、
capability 逐项缺失;反向自检(把候选改回按最新归档取、把文案改回旧句、
去掉管理员判断)三项均按预期变红后复原。
2026-10-29 18:16:21 +08:00
姚章浩 c14dd01f08 fix(library): 封存读资源失败带上资源行与底层原因
build / build (push) Successful in 1m18s
真实封存卡在 `read library resource` 时没有任何可判断信息:对象缺失、桶写错、
宿主机解析不到端点都会走到同一个字符串。现在错误带资源行 id 与底层原因
(不含凭据),本轮就是用它在候选栈定位到"源对象被上一次 B02 演练删掉后没真正写回"。
2026-10-29 13:32:55 +08:00
姚章浩 c542a1333a fix(library): 资源行的存储后端列也改到目标实例
build / build (push) Successful in 1m17s
原版应用先按 resources.storage_backend_id 找文件服务;只改定位符不改这一列,
目标仍报 storage backend not found 并拒绝整条路径(真实下载 500 code1007)。
行变换同时改写该列,写入与校验共用。

试过:目标同步后 /api/v1/knowledge/{id}/download 500 → 修后复测读回 507B 且
sha256 与源对象一致;go test ./internal/releaseadapter/v071 与 make verify 全绿。
2026-10-29 07:08:39 +08:00
姚章浩 1aecd9d6af fix(library): 资源定位符同时改到目标存储后端
build / build (push) Successful in 1m16s
storage://<id> 是来源实例 storage_backends 的主键;只换桶不改 id 时,目标原版
应用以 storage backend not found 落回默认服务并拒绝整条路径(真实下载 500
code1007)。写入前按租户+目标桶解析目标后端,写入与校验共用同一份行变换;
解析不到就拒绝写入,不再产出目标读不出来的定位符。

试过:目标实例真实同步后 /api/v1/knowledge/{id}/download 读回 500 → 修后复测;
go test ./internal/releaseadapter/v071 与 make verify 15 项全绿。
2026-10-29 07:04:45 +08:00
姚章浩 c2402947a9 feat(library): 死信按精确指纹解除,保留上游记录
build / build (push) Successful in 1m26s
上游 task_dead_letters 没有解决标记,purge/DELETE 会销毁"失败过"的唯一证据。
治理侧新增解除记录(迁移 073):绑定实时行逐字节指纹、重放引用、源侧观测摘要与
操作人;行被改过、重放后又出现新死信、源侧未结清都不命中,封存照旧阻断。
指纹先压紧空白再摘要,避免 PG to_jsonb::text 与 json.Marshal 的空白差异。

试过:go test ./internal/{librarydeadletter,libraryagent,httpapi,releaseadapter/v071,
platform/postgres},make verify 15 项全绿。
2026-10-29 06:55:13 +08:00
姚章浩 b061a9686c fix(v071): 资源换桶的变换在校验时同用
build / build (push) Successful in 1m17s
只改写入侧会让"行内容摘要"对不上:校验拿变换前的归档行与目标里的变换后行比较,
真实同步在 verify 阶段报"生产 resources 内容与快照不一致"并回滚。
把行变换抽成 rowTransform,写入与校验共用同一份。

试过:make verify 15 项全绿;真实同步复现该失败后修复(下一轮重跑验证)。
2026-10-29 06:24:14 +08:00
姚章浩 cb0090802b fix(v071): 同步资源行时把定位符的桶换成目标桶
build / build (push) Has been cancelled
同步把资源字节写进目标桶,但 resources.physical_path 是从快照原样搬的,
里面还写着来源桶(storage://…/minio://kgmaint-1028a/…)。目标实例之后按这一行
取图/附件就会指向测试环境的桶,或直接取不到——跨环境引用,必须在本轮修掉:
写入前换桶、键不变,定位符解析不出来就报错(不写指向别处的行)。

试过:make verify 15 项全绿;新增定位符用例(嵌套/单层/裸键/非法);
真实同步后目标桶里对象键与行内定位符一致。
2026-10-29 06:21:53 +08:00
姚章浩 7d4ffdbfe5 fix(v071): 全新目标实例的空索引按空基线处理
build / build (push) Successful in 1m15s
全新 WeKnora 会用空映射({})先建好索引,范围字段等第一次写入才动态生成。
首次同步在读目标当前状态时就报 "missing release scope fields" 并失败,等于
"往空的生产实例做第一次同步"这条路根本走不通。

现在:"没有范围字段 + 索引确实 0 篇文档" = 空基线;有文档却看不出归属仍然报错
(绝不把无法归属的文档当空库覆盖)。Count 与整库导出共用同一判断。

试过:make verify 15 项全绿;新增空/非空两种索引的用例;真实 sync 复现原错误。
2026-10-29 06:17:26 +08:00
姚章浩 37a8370f7b fix(v071): 索引范围过滤接受未写 tenant_id 的文档
build / build (push) Successful in 1m15s
真实 v0.7.1 的 app 自己写索引时不带 tenant_id,治理侧同步写入时才补齐。
原来只按 term tenant_id 过滤,等于把 app 写入的正文整库漏掉:真跑时索引里有
2 条文档,导出 0 条,候选校验报 legacy coverage,封存被拒。

改为"显式本租户 或 完全没写租户字段"(写了别的租户仍然排除),知识库身份
仍是独立 term,范围没有放宽。Count/PruneScope/整库导出共用同一写法。

试过:make verify 15 项全绿;新增 3 个过滤条件用例;真实 preflight 由
candidate-invalid(0 条) 变为 candidate-valid(2 条)。
2026-10-29 06:00:30 +08:00
姚章浩 c7dafe987e fix(library): 恢复校验按归档身份核对共享资源表
build / build (push) Successful in 1m12s
resources 是多库共享表:采集看正文里的 resource://handle,校验只看 chunks 重算可见集,
两边口径不同,恢复得一字不差也会被判 15/19 而拒绝开放。改成按归档 id 核对存在性与内容摘要。
2026-10-29 02:03:55 +08:00
姚章浩 c72b71d78a fix(library): 预备份硬门禁 + 崩溃接管 + 五项入口验收
build / build (push) Failing after 17s
为什么:父审指出预备份引用持久化失败仍继续写目标、接管依赖启动扫描且漏掉租约未过期、
恢复失败被标成"无需恢复"、版本登记与作业状态分叉。

- BackupPrepared 返回 error,持久化失败即零写入;预备份同时登记 production_prebackup 版本。
- 接管改为按队列租约判定 + 运行期 30s 扫描 + 原子抢占 + 固定幂等键 + attempt 归零。
- 接管场景保留预备份、不再宣称"未写无需恢复"。
- 恢复/重放同一快照重新激活 production_effective(清 superseded_at)。
- finalize 续作只做校验+登记(finalize_only),不重写生产。
- 索引映射基线缺失时采用首次观察值并登记;索引校验加孤儿文档检查(按 knowledge_id)。

真实验收(候选 API :18089 + 真实 PG/ES/MinIO):
A0 首次发布、A1 撤销、B 按版本恢复、C 写阶段 SIGKILL 接管、
D 跨 kind 互斥与多 worker 单次执行、E1 登记失败、E2 finalize 续作、E3 预备份失败零写入。
2026-10-28 19:11:37 +08:00
姚章浩 ac3b395102 fix(library): 对齐真实 WeKnora Schema + 入口级真实服务验收
build / build (push) Successful in 1m21s
为什么:候选环境改用真实 WeKnora 表结构后,暴露出多处"按猜的列名/形状"的假设,
以及若干 varchar 长度、对象定位符、空索引基线问题,导致真实链路跑不通。

- knowledge_tag_relations 无 tenant_id/KB 列 → 归属走父表;resources 作用域=绑定+chunk 引用。
- 写入顺序按真实外键;无代理键表用内容摘要核对。
- 队列作业 ID / 版本记录 ID 改固定长度摘要(列宽 varchar(36)/varchar(64))。
- 对象定位符拆 storage://<backend>/oss://<bucket>/<key>;provider 可配置。
- 空索引基线全链路一致(Current/Export/Backup/Archive),非空仍严格比对映射。
- finalize 阶段:版本登记失败不报成功;崩溃接管复用已持久化预备份。
- 迁移 000069:同一目标的 sync/restore 跨 kind 互斥。
2026-10-28 17:53:43 +08:00
姚章浩 0b9dbe12cf fix(library): 资源范围精确关联 + 内容级校验 + 真实对象存储验收
build / build (push) Successful in 1m13s
为什么:父审指出资源范围未关联外层 resources,会把别的库/租户资源算进来;
Verify 只看行数与 ID,同 ID 改正文/改向量/损坏对象都能通过;集成测试还在用假对象存储。

- scopeWhere(resources)/resourcePaths 用 resource_bindings.resource_id=resources.id 精确关联,
  覆盖 knowledge/chunk 绑定并限制租户;资源部件名与资源 ID 对齐。
- Verify 增加逐行内容摘要、索引文档摘要、对象字节 SHA256 校验。
- 预备份一致性改为内容指纹(数量+摘要),同数量改写也会失败。
- 新增真实 MinIO 对象存储的本机验收用例,覆盖隔离/损坏/独立恢复。
2026-10-28 16:23:28 +08:00
姚章浩 8da4666e76 test(library): 端到端编排在本机真实 PG/ES 上跑通
build / build (push) Successful in 1m14s
为什么:只验证单阶段写入还不够,完整链路(授权→预备份→四类写入→校验)也要在真实服务上跑。
本机 WeKnora 测试栈一次性库与随机索引已通过,CI 无这些服务故在 test-scope 声明为可选。
2026-10-28 15:58:06 +08:00
姚章浩 281699a431 feat(library): 生产整库真实读写/校验/恢复与本机真实服务验收
build / build (push) Successful in 1m21s
为什么:生产目标此前是"无条件失败"的占位,编排再完整也不能落地;本轮把它做成真实实现,
并在本机 WeKnora 测试栈的真实 PG/ES 上跑通导入、撤销、预备份与故障恢复。

- ProductionLibraryTarget:Current 读行数+身份摘要;Apply 按阶段真实写入(database/wiki
  同事务先删本库再插、resources 传对象、index 搬运原始文档与向量);Verify 比对身份摘要;
  Restore 按预备份快照回放。
- 撤销真正生效:索引阶段写入后 PruneScope 删除快照里没有的文档。
- ProductionBackupStore:导出前独立完整预备份,导出前后行数不一致即失败。
- worker 用注入配置装配目标与预备份;缺项把变量名写进阶段并失败,不再有占位对象。
- capacity 安全加法防溢出;保留策略组合语义明确(各维度都超限才候选)。
- 新增本机真实服务集成测试(一次性 kg_library_test_* 库 + 随机 ES 索引),
  覆盖导入/校验/撤销/预备份/故障注入/恢复。
2026-10-28 15:54:01 +08:00
姚章浩 7b8cc0384b feat(library): 生产发布授权与同步/恢复编排,worker 接线
build / build (push) Successful in 1m19s
为什么:同步入口此前只会拒绝;授权、预备份、四类写入、验证与失败恢复都没有代码。
本轮把编排与授权实现出来,真实生产执行仍按授权闸口关闭。

- internal/libraryrelease:预备份 → 数据库/资源/索引/Wiki → 验证 → 失败恢复;
  授权过期/目标不符/快照不符/参数变化在动生产前拒绝;恢复失败单独上报。
- 迁移 000067 library_release_authorizations(目标+快照+参数摘要+有效期,可撤销)。
- POST/GET /api/v1/library/authorizations 与 /{id}/revoke,仅管理员签发,5–1440 分钟。
- worker library.sync 接编排:先闸口再授权,阶段落库,只有编排成功才标成功。
- 生产目标适配器未配置时显式失败(不返回零值状态),预备份存储同。
- overview 返回授权状态,页面"生产保护与恢复"显示签发人与有效期。
- 验收矩阵区分"已实现·隔离测试通过"与"真实执行未授权"。
2026-10-28 15:11:27 +08:00
姚章浩 c5e033dd0e fix(library): 幂等重放、跨版本去重用量与契约复核
build / build (push) Failing after 15s
- 同作业号重跑读持久日志+已封存清单按首次请求重放(source_read=false,
  writers_stopped=false),换范围/绑定库或清单校验失败即拒绝
- 归档用量按跨版本去重统计内容字节,清单/未引用 blob/实际分配单列,
  不再用各版本 unique 之和冒充归档占用
- 冻结窗口内复核来源契约,不一致即中止;拒绝组外同镜像运行容器
- 补齐整库只读接口的 OpenAPI 契约
- 按用户确认取消 A06:文档/页面/接口不再把效果测试列为封版门槛
2026-10-28 12:01:09 +08:00
姚章浩 045fc44f0e feat(library): 接通整库封存真实入口与只读版本页
build / build (push) Failing after 19s
- libraryctl:status/preflight/capture/list/verify/recover,只读来源会话、
  结清检查、契约推导、维护窗口内停写者、导出十表+索引+对象+Wiki、封存候选后恢复
- libraryfreeze.ProjectController:按 Compose 项目逐服务声明固定身份,
  未声明服务/容器重建即拒绝,仅 SIGTERM,恢复后必须 healthy
- httpapi:GET /api/v1/library/snapshots[/{id}] 只读列出封存产物
- web:「整库版本」页(只读、未接线显示原因、无假按钮)
- api:LIBRARY_ARCHIVE_ROOT + 归档根只读挂载
- docs/library-capture.md:运维手册与 2026-10-28 两次真实封存实测

不代表整库业务验收通过:内容/问答/性能验收、跨系统切点、Wiki 删除语义重算、
生产预备份/恢复演练/双闸/同步协调仍未完成。
2026-10-28 11:39:50 +08:00