Pysolate 本科生版解释目录

这个目录是现有实现审查文档之上的阅读层。它不替代 claims/、implementation/ 或 evidence/，而是把 Pysolate 拆成一次只需要理解一个问题的短篇。

阅读架构

为什么存在、系统里有谁
        ↓
权限怎样被授予和消费
        ↓
fresh execution 怎样管理状态
        ↓
怎样安全地提前、复用或丢弃物理工作
        ↓
怎样选择 backend 且避免重放 effect
        ↓
证据能证明什么，以及谁会从中受益
        ↓
较新的 Prepared Family 与 source-bound pass 怎样复用前述边界

01-orientation

先回答 Pysolate 为何存在，以及最小系统图。

02-authority

解释谁能授权、谁能调用、谁记录结果。

03-fresh-state

解释 fresh execution 如何管理运行状态和等待。

04-safe-optimization

解释 Pysolate 如何在不提前提交逻辑 effect 的情况下优化。

05-backends-placement

解释代码在哪运行，以及何时绝不能自动重放。

06-evidence-and-value

解释性能、证据、限制与实际价值。

07-prepared-families

解释同一份 bounded NumPy input 怎样服务多个 fresh、single-use consumer，同时保持每个 member 的 authority 与 workspace 私有。

08-source-bound-passes

解释纯 AST/source 优化怎样被重构为有 registration、stage、outcome 和 exact-Guest execution contract 的 pass。

推荐阅读路径

快速主线

• Pysolate 为什么存在
• Host、Guest 与 Run
• 权限为什么有生命周期
• Candidate、Qualified、Physical 与 Logical
• Semantic pre-dispatch
• 为什么纯 AST 优化现在真的是 Pass
• 业务价值与适用场景

完整主线

按目录编号和文件编号顺序阅读。后续篇章可以引用早期篇章的术语，但不得要求读者先阅读实现审查文档。

实现复核

先读对应解释点，再沿文末的现有说明文档与 agent-python-runtime source owner 下钻。

写作者入口

• 写作合同
• 任务与执行顺序

验证

在仓库根目录运行：

python3 scripts/validate-guide.py

脚本检查 27 个解释点、必需章节、本地链接、runtime source owner，以及根 README 声明的冻结 runtime commit。默认读取相邻的 ../agent-python-runtime；若该 live checkout 已前进，可把 detached/pinned worktree 显式传入。下面的 /path/to/... 是示例占位路径，需要替换为真实目录：

python3 scripts/validate-guide.py --runtime-root /path/to/runtime-at-94fab78c