Skip to content

fix(docs,scripts): correct a false evidence claim, a dangling doc pointer and a broken import - #27

Merged
Xander-Xai merged 1 commit into
mainfrom
fix/phase1-doc-truth-and-broken-import
Oct 21, 2026
Merged

Xander-Xai merged 1 commit into
mainfrom
fix/phase1-doc-truth-and-broken-import

Conversation

@Xander-Xai

Copy link
Copy Markdown
Owner

三处可复现的错误修正,均不改变运行时行为。

1. docs/limitations.md §9 —— langgraph 版本声明与实际执行环境不符

原文声称「make runtime-chaos artifact 亦记录 langgraph: 1.2.2」。2026-10-21 在 4ed8f96 上重新生成该 artifact,记录的是 langgraph: 1.2.12。

根因:requirements-lock.txt 按本仓 Makefile 的分层约定是 HISTORICAL / NON-AUTHORITATIVE 快照;canonical 生产/CI 契约是 requirements.txt(langgraph>=0.2.0,未锁版本),而 make / CI 用裸 python3 解析解释器 → 实际版本随时间漂移。

语义声明仍然成立:HITL LangGraph interrupt 语义在 1.2.2(.venv,8 passed)与 1.2.12(make/CI 实际解释器,并入 199 passed)上均实测通过。

残留:要在 requirements.txt 固定 langgraph 才能把「已验证于某版本」变成稳定事实。

2. docs/design/security.md —— 悬空交叉引用

原文指向 docs/limitations.md 作为会话加密边界的落点,但该文件对 csae1 / SESSION_ENCRYPTION / 明文 的命中数是 0 → 指针落空。

补上 docs/limitations.md §9 的四条真实边界(provenance 无外部信任锚点 / 生产契约缺 SESSION_ENCRYPTION_KEY / 无迁移工具 / 存储访问控制未验证),并把指针改指 §9。

3. scripts/purge_orphan_checkpoints.py —— 不存在的 import

_load_live_session_ids() 的 dev 模式内存会话回退 import 了 get_session_manager,而 core.session.session_manager 只导出 default_session_manager。ImportError 被随后的宽 except 吞掉 → 该回退路径从未生效,该分支恒定抛 SystemExit 中止 purge。

实测:修复前 SystemExit: 无法枚举现存会话;修复后正确枚举(PROBE_OK=True)。

边界(不夸大)

验证(基线 SHA 4ed8f96)

项 结果
pytest tests/unit/ 3544 passed, 5 skipped
pytest tests/integration/runtime/(真实 PG 15.18 + Redis 7.4.9 + Celery 5.6.3) 199 passed
scripts/audit_doc_consistency.py OK(57 active documents)
scripts/check_public_repository_boundary.py OK
ruff check . + ruff format --check .(canonical 0.4.0) All checks passed

…nter and a broken import

三处**可复现**的错误,均不改变运行时行为。

1. docs/limitations.md §9 —— langgraph 版本声明与实际执行环境不符
   原文声称「`make runtime-chaos` artifact 亦记录 `langgraph: 1.2.2`」。
   2026-10-21 在 4ed8f96 上重新生成该 artifact,记录的是 **1.2.12**。
   根因:requirements-lock.txt 按本仓 Makefile 的分层约定是
   HISTORICAL / NON-AUTHORITATIVE 快照,canonical 生产/CI 契约是
   requirements.txt(langgraph>=0.2.0,**未锁版本**),而 make / CI 用裸
   python3 解析解释器 -> 实际版本随时间漂移。
   语义声明**仍然成立**:HITL LangGraph interrupt 语义在 1.2.2(.venv,
   8 passed)与 1.2.12(make/CI 实际解释器,并入 199 passed)上均实测通过。
   残留:要在 `requirements.txt` 固定 langgraph 才能把「已验证于某版本」
   变成稳定事实。

2. docs/design/security.md —— 悬空交叉引用
   原文指向 docs/limitations.md 作为会话加密边界的落点,但该文件对
   csae1 / SESSION_ENCRYPTION / 明文 的命中数是 0 -> 指针落空。
   补上 limitations.md §9 的四条真实边界(provenance 无外部信任锚点 /
   生产契约缺 SESSION_ENCRYPTION_KEY / 无迁移工具 / 存储访问控制未验证),
   并把指针改指 §9。

3. scripts/purge_orphan_checkpoints.py —— 不存在的 import
   `_load_live_session_ids()` 的 dev 模式内存会话回退 import 了
   `get_session_manager`,而 core.session.session_manager 只导出
   `default_session_manager`。ImportError 被随后的宽 except 吞掉 ->
   该回退路径**从未生效**,该分支恒定抛 SystemExit 中止 purge。
   实测:修复前 SystemExit(无法枚举现存会话),修复后正确枚举。

边界(不夸大):以上均为文档/脚本层修正。**没有**改动加密语义、密钥、
会话存储访问控制,也没有做任何历史重写。Issue #25 保持 OPEN。

验证(SHA 4ed8f96):
- 单元测试 tests/unit/ 3544 passed, 5 skipped
- 真实 PG+Redis 集成 tests/integration/runtime 199 passed
- scripts/audit_doc_consistency.py: OK(57 active documents)
- scripts/check_public_repository_boundary.py: OK
- ruff 0.4.0(requirements-dev.txt 固定版本): All checks passed
@Xander-Xai
Xander-Xai merged commit a362fe1 into main Oct 21, 2026
11 checks passed
@Xander-Xai
Xander-Xai deleted the fix/phase1-doc-truth-and-broken-import branch October 21, 2026 06:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant