Pysolate Explained

这是面向论文写作、实现复核和答辩准备的独立说明库。它不包含运行时代码，也不把设计意图冒充为已实现能力。

基线

• 历史综合审查：b94c989785632d98634cdd5c2a6d4a1de6cc13ac，tree 6b8bb6a8d8274b8329a2aba444d13eac9fac19e9
• 既有说明文档的审查实现基线：b6458b41f0fa32085fdd4cad0a528d98602569d2，tree 5e8154fc26527181c66e612584d79dd4e620649d
• 当前实现：94fab78cb3f44d14f86d293287269b704b11d383，tree a4291f77e59d680f5ef1bd21e39b323afd5c5ecf；guide validator 只用它核对当前 runtime HEAD，不把它反向写成所有历史 evidence 的 producer。
• correctness-gated optimizer方向的初始source target：8934a0dcf890ef21fe8d84c79bf0d70c214dd6c7，tree 5042779a8cdca835280ecf571115e2e7520b860e；后续 source-pass 与 paper-pass 变更按各自文档中的更新 target 陈述。
• implementation/03和04保留历史发现过程并带post-review note；后续Prepared Family与optimizer方向按各自source/evidence target陈述，不能反向归属到旧审查基线。

不同实验可能来自更早的source commit和固定artifact。证据页分别记录审查target与producer target，不能把当前HEAD写成所有benchmark的producer。

一句话主张

Fresh isolated execution并不要求放弃跨执行优化。只要authority、physical work和effect truth由Host持有，logical effect仍由Guest中的exact dynamic occurrence触发，Host就能安全地提前、复用或丢弃受约束的物理工作。

最短阅读路径

1. claims/main-claim.md：主claim和证据边界。
2. claims/innovation-inventory.md：哪些是核心贡献、次级贡献、substrate和non-claim。
3. claims/eager-comparison.md：为何有额外调度机会，但没有universal dominance。
4. design/abstractions-patterns-and-tradeoffs.md：统一抽象、设计模式和代价。
5. implementation/source-map.md：从source owner回到具体实现。
6. evidence/reproducibility-map.md：哪些可直接重跑，哪些依赖artifact，哪些只是模型。
7. defense/key-questions.md：答辩高频追问。
8. papers/README.md：哪些论文优化能成为source-bound pass，以及它们的correctness/effect边界。

本科生版解释层

• guide/README.md：按理解依赖组织的 8 个模块、27 个独立解释点。
• guide/WRITING-CONTRACT.md：受众、文章结构、证据纪律和单篇完成门。
• guide/TASKS.md：27 个解释点的分波完成记录和全局验证门。

guide/ 是现有审查文档之上的阅读层。它负责建立直觉；具体 claim、实现状态和证据仍以本库原有文档及其绑定的 runtime target 为准。

Astro 文档站

仓库内置一个纯静态 Astro 文档站。Astro content collection 直接读取现有 guide/、claims/、implementation/、evidence/ 等 Markdown；正文仍只有一份，构建期会把相对 .md 链接改写为站内路由。

pnpm install
pnpm test
pnpm dev

pnpm test 依次运行 Astro 类型检查、静态构建和产物合同验证。scripts/validate-site.mjs 会检查 27 个本科生解释路由、页面标题、静态资源和构建后的内部链接。

Cloudflare Pages 初始配置：

• Framework preset：Astro
• Build command：pnpm build
• Build output directory：dist
• Node.js：>=22.12.0

站点使用 Astro static output，不需要 Cloudflare adapter、Pages Functions 或服务端 runtime。public/_headers 会随构建复制到 Pages 产物。

Claims

• claims/main-claim.md：主claim、证据层级和禁止表述。
• claims/innovation-inventory.md：创新分级。
• claims/claim-matrix.md：claim、实现、证据、适用范围与反推边界。
• claims/eager-comparison.md：EAGER对比的正确表述。

Implementation

• implementation/01-execution-core.md：Run入口、Guest生命周期、ABI、response与cleanup。
• implementation/02-authority-spine.md：Spec、Grant、Plan、Broker、approval与receipt。
• implementation/03-streaming-and-source-binding.md：streaming三条seam、source identity与final gate。
• implementation/04-semantic-predispatch.md：candidate、qualification、physical dispatch与logical claim。
• implementation/05-reuse-taxonomy.md：memoization、single-flight、typed reuse、prepared runtime和COW的区别。
• implementation/06-prepared-data.md：fixed NumPy prepared-data与object-bound claim。
• implementation/07-backends-package-profiles-and-placement.md：WASM/native、artifact、profile、placement与non-replay。
• implementation/08a-workspace-lineage.md：Ref、Lease、Attempt、Branch和Root。
• implementation/08b-suspension-and-resume.md：approval、workflow resume和cold-I/O continuation。
• implementation/08c-private-cow-and-prepared-runtime.md：Linux private-COW和fresh consumer。
• implementation/09-prepared-family.md：bounded NumPy family、per-member authority与single-use lifecycle。
• implementation/10-source-bound-pass-pipeline.md：pass registration/stage/outcome、static plugin与exact-Guest source patch。
• implementation/11-split-phase-call-scheduling.md：候选设计；Host-owned pseudo-future、hidden submit/blocking materialize 与 incremental event graph（尚未实现）。
• implementation/source-map.md：source owners与关键symbols导航。

Design, evidence and defense

• design/abstractions-patterns-and-tradeoffs.md：模式、替代方案、fresh与reuse。
• evidence/benchmark-catalog.md：所有重要benchmark/evidence的producer、数字和强度。
• evidence/reproducibility-map.md：A/B/C/D四级复现地图。
• evidence/current-runtime-94fab78.md：Prepared Family与source-bound pass的current证据和producer边界。
• defense/key-questions.md：高频问题与短答。
• defense/limitations.md：平台、Guest、prepared-data、evidence与productization边界。
• review/coverage.md：切片完成度与已关闭缺口。
• papers/README.md：逐篇paper简析、可吸收的optimization kernel和明确排除项。

证据标签

• Current：在命名实现target中可由源码与测试验证。
• Observed：在命名artifact、平台、fixture和证据文件中真实观察。
• Framing：由有限实现和证据支持的研究抽象。
• Historical：由旧提交或旧artifact产生，不自动代表当前HEAD。
• Deferred：明确未实现或不进入当前论文。
• Unsupported：当前证据不能支持的强claim。

写作红线

• AST、callee和literal只能发现candidate，不能产生authority。
• digest证明identity一致性，不证明外部世界语义真值。
• private-COW是既有execution substrate，不是prepared-data主创新。
• matched component timing和schedule model不是observed interval trace。
• 不声称对EAGER有逐workload wall-clock支配。
• 不声称generic cache、generic object ABI、任意Python heap snapshot或production optimizer。