用途与实际影响
这项功能怎样使用
为什么需要它
如果更新索引时逐个覆盖文件，中断后可能一半是今天、一半是昨天。先备好并核对完整新版本，全部齐了才切换；失败继续用上次完整版本。
举个实际例子
我说：“新增仓库后完整更新索引。”系统先生成一整份新索引；生成中途失败，当前仍是旧完整版本。新索引已发布但后续私有登记没跟上时，分别告诉我公开索引和私有登记各到哪一步。
最后我会得到什么
成功时得到完整的新公开索引和更新后的本机导航；失败时知道旧版是否仍在用、哪一步尚未完成。不把一次中断说成“自动回滚成功”，也不把部分新文件拼进旧版。
正常时
整份新索引生成并核对完才采用，后续私有登记另行确认。
发现问题时
切换前失败就继续用旧完整版本；切换后登记失败则分别报告两层结果。
入口不可用或证据不足时
旧索引或恢复来源都读不到时先恢复一份完整版本，不拼接不明文件。
从哪里开始
在已接入 GitHub 总索引的 AI 对话中说“新增仓库后刷新索引”或要求检查现有索引是否完整。
需要准备什么
- 已确认的仓库及远端身份
- 希望刷新或恢复的索引范围
从开始到拿到结果
- 1
先核对现有版本
AI 读取当前完整索引，确认是否只需查差异。
- 2
生成并验新版本
确有变化时从已确认仓库清单生成全套文档，核对全部文件后才切换当前指针。
- 3
报告分层结果
交回新索引和私有基线的各自状态；中断前未切换则继续使用旧完整版本，切换后基线失败也分别说明。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
公开投影完整性保留9月8日历史验收；9月22日当前身份与基线45/45、差异0、问题0，不把本次身份查询当成公开投影全闭包重验关键规则与设计选择
只有仓库 identity、visibility（公开或私有属性）、remote（远端仓库）、clone、默认分支或长期治理等 Owner 事实变化才重建。
普通业务 commit、格式、时间戳或没有改变用户判断的 drift 不触发连锁 refresh。
generation（代际） integrity 通过只证明这一代内部一致，不证明动态事实仍最新。
正常full refresh自动推进已有有效v3基线；零写status、Fast和CheckOnly都不因此变成基线写入口，首次bootstrap/repair仍须显式处理。
partial projection failure（部分投影失败） 不切 current（当前状态）；旧 generation（代际） 继续有效但 projection 标记 stale。
stale `.incoming` 只在名称、路径和 reparse-point（重解析点）检查通过后回收。
本模块用到的名词
- immutable generation（不可变代际）
- 发布后内容集合与 manifest（清单） 固定；下一次变化创建新 id，不原地补丁。
- current pointer（当前指针）
- 唯一指向现行 generation（代际） 的小 JSON；只有完整回读后才切换。
- closed document set（闭合文档集）
- manifest（清单） 只能包含固定预期文档，不能夹带未登记文件或越界 projection。
- stable / volatile drift（稳定 / 易变漂移）
- 身份、visibility（公开或私有属性） 等稳定事实影响一致性；dirty、ahead/behind（领先/落后提交数） 等易变状态可报告但不默认否决。
- recovery material（恢复材料）
- previous generation（代际）、`.incoming`、checkpoint（续作检查点） refs 和 unreachable objects 等可能保存中断前唯一内容，未证明前不清理。
专业定义
总账有实质变化时先生成一整套新快照；中途失败就让 current（当前指针）继续指向旧完整代际，绝不拼出半新半旧的页面。
解决什么
公开看板既要易读，又不能把 generated Markdown 升级成动态权威。一次 refresh 还会读 GitHub、扫描已声明 clone、生成多文档和更新私有导航，必须在中断、网络失败和并发运行时保持一致。
当前怎样实现
- 完整刷新先检查Owner基线：invalid在公开generation（代际）写入前拒绝；missing允许生成公开快照，但后续baseline阶段只返回skipped/owner_baseline_missing_requires_explicit_bootstrap，不伪造首次历史。
- 完整 refresh 在全局 mutex（互斥锁）下运行，generation（代际） 写入同卷 `<id>.incoming`，先校验路径闭合、文件 hash（内容指纹）、bytes 和 provenance（来源说明）。
- 兼容 projection 只能映射到固定八份公开文档；manifest（清单） 或 pointer 有未知字段、大小写变体、额外文件或越界路径就失败关闭。
- 全部投影写入并回读后，current-generation.json 才原子切换；pointer 保存 manifest（清单） hash（内容指纹）、previous id 和 current（当前状态）+previous retention policy。
- Invoke-AtomicGitHubLocalIndexRefresh成功、导航已更新后，同一full refresh调用Invoke-RefreshGitOwnerBaselineAdvance：fresh全量事实完整且无issue才自动advance，回读domain=current（当前状态）、delta=0、issue=0，保留previous→current（当前状态）非阻断历史。公开generation（代际）与私有baseline各自原子，并不是一次跨两层事务。
- consistency checker 在 system temp 重建候选并区分 stable drift 与 volatile drift；默认不 stage、commit 或 push。
- hidden CheckOnly 入口只原子写 ignored（已被版本控制忽略） 私有 consistency receipt（执行回执），供机器 Owner 读取 outcome、drift files 和错误代码。
- full refresh（完整刷新）复用共享 Admission（仓库准入检查） 的 fetch：仅退出128且命中 SSL_read/TLS connect 的 unexpected eof 时以同一参数重试一次，最多两次；其他失败不自动重试，失败保留 fetch_failed。固定提交快照只刷新 metadata（元数据），不声称普通工作树已同步。
执行流程
- 1
读取现有 current（当前状态） pointer 并验证旧 generation（代际）
- 2
获取 GitHub inventory、私有导航和已声明 clone 的现场事实
- 3
生成八份公开安全文档到临时 staging
- 4
写入新的 `.incoming` generation（代际） 和闭合 manifest（清单）
- 5
回读 hash（内容指纹）、bytes、schema（数据结构）、路径、reparse 与文档 provenance（来源说明）
- 6
发布并回读全部兼容 projections
- 7
原子切 current（当前状态） pointer，验证 current（当前状态）/previous 后再清理更旧 generation（代际）
- 8
使用更新后的导航与同一fresh owner inventory，自动推进已有有效v3基线，再回读current（当前状态）、delta=0、issue=0；无变化返回current（当前状态），有变化返回advanced，缺失返回skipped
- 9
一致性检查发现 drift 时只报告；是否 refresh 由 Owner 事实变化决定
边界
- public（公开） projection 标注 authoritative=false、decision_authority=false
- Fast compatibility mode 和 hidden receipt（执行回执） 会写 ignored（已被版本控制忽略） 私有状态，不等于 zero-write Owner status
- refresh、Hook（钩子）、current（当前状态） generation（代际） 或 consistency PASS 都不证明 publication 完成
- 不引入数据库；未来 cache 必须可删除、可重建且不能替代 Git/GitHub/registry
- 不创建 watcher、后台自动 refresh、自动 commit 或自动 push
失败与恢复
- 生成文档、manifest（清单） 或 projection 回读失败
- 不切 current（当前状态）；保留旧 generation（代际），并让 consistency 报告 precise stale reason。
- 残留 `.incoming` 名称、路径或 reparse 检查异常
- 拒绝清理，避免递归删除越出 generations root。
- fetch 在适用的一次重试后仍失败，或错误不适合重试
- 保留 fetch_failed、实际次数与有界诊断；不把旧 refs 冒充 live，不自动 push。
- pointer/manifest（清单） 多字段、大小写漂移或 document closure 破坏
- generation（代际） valid=false，停止基于它的 current（当前状态） 判断。
- Owner baseline与live inventory不同但projection hash（内容指纹）一致
- 保持generation（代际） integrity，同时让零写status报告review_needed；正常完整refresh会自动收敛有效基线。若基线阶段失败，保留真实已发布generation（代际）与实际基线，明确未收口层，不假称整体回滚或成功。
真实入口
E:\GitHub总索引\tools\Refresh-GitHubLocalIndex.ps1mutex、incoming recovery、generation（代际） publish、pointer switch 和 retention
E:\GitHub总索引\tools\Update-GitHubIndex.ps1Git/GitHub 事实到公开安全文档的生成器
E:\GitHub总索引\tools\Test-GitHubLocalIndexConsistency.ps1current（当前状态） generation（代际） 与重建结果的只读比较
E:\GitHub总索引\docs\contracts\git.refresh-consistency.mdowner status、refresh、consistency 与恢复边界
E:\GitHub总索引\tests\Run-UnitTests.ps1原子失败注入、路径闭合、reparse 和 receipt（执行回执） 回归
如何验证
- current-generation.json 声明 schema（数据结构） v1、generation root（代际根目录）、manifest（清单） SHA-256、八份 documents、current（当前状态）+previous 和 pointer-after-readback。
- 单元测试注入 projection 中途失败，验证旧 pointer 保持有效；下一次完整 publish 修复 mixed projections 后才切换。
- 当前源码与git.refresh-consistency合同一致：正常full refresh先generation（代际）/navigation后自动baseline advance；已有断言验证此顺序与invalid基线前置拒绝。本次只读核对，没有再次执行刷新或迁移。
- 测试拒绝越界 projection、额外文件、unknown（未验证）/case-variant schema（数据结构） 字段和 reparse-point 父目录。
- 2026-09-08T08:11:28Z 直接回读 generation（代际） 284f02f94edf4c5584c4f51f680d4f7a：manifest（清单） hash（内容指纹）、8份文档和兼容投影 SHA-256/bytes 全部一致，总计25235字节；previous=9c04651b9fac4c069ce3e746aea5c928。
- generation（代际） integrity（投影完整性）证明9月8日03:15 UTC的不可变投影闭合；08:08 UTC 的 live Owner status（现场身份状态）证明48/48、delta0、issue0。两层观察时间不同，均不替代单仓库同步和发布。
- 本次没有通过 refresh 故障注入重新制造一次中断；恢复行为仍由既有源码回归证明，当前现场验证只覆盖已发布闭包的 read-back（回读）。
与其他模块的关系
它把总账和诊断保存成可重建快照，但不替 Admission（仓库准入检查） 判断单仓库现场，也不替 Publication Gate 批准外部发布。