PysolateExplained
打开文档导航
本科生解释查看 Markdown 源文件

Prepared data 与一次性 object claim

一句话

在固定 NumPy/NPY 研究 lane 中，Host 可以提前读取并严格解码一个不可变数据集，但 sealed object 只有在最终 Guest 到达完全匹配的 numpy.load occurrence 时才能被一次性 claim；未到达就清理为 orphan。

先看一个例子

Agent 的代码前缀出现：

dataset = np.load("/workspace/input.npy", allow_pickle=False)

读取和解码一个 8 MiB NPY 文件可能需要时间。Host 已经知道这个文件的路径、长度、body digest、dtype 和 shape，也有本次读取的显式 Plan，于是可以在剩余 source 继续生成时准备数据。

但后面的程序可能进入另一个分支，或在 np.load 之前抛异常。Host 不能因为 bytes 已经读完，就把 dataset 说成 Python 已经加载成功。

真实机制

这条 fixed lane 分成三条最后才汇合的路径。

1. Source 与 authority

Exact target Guest 只报告一个唯一、参数固定的 np.load candidate。Host 再提供 HostPreparedDataDeclaration 和 sealed PreparedDataContract，其中绑定：

  • sources.read 与 exact numpy.load occurrence；
  • admitted source prefix、path、workspace root、file/body digest；
  • numpy_npy_c_v1、<i8、[1024, 1024]、C-order 等封闭 schema；
  • artifact/profile/import、Run、privacy、freshness、budget 和 size bounds；
  • exact capability Plan。

Candidate 与 contract、Plan、context 任一处不匹配，都不能启动 physical read。

2. Physical preparation

Host 通过 one-shot pre-dispatch 读取文件，并用受限 Go decoder 检查 NPY magic、version、header、dtype、shape、order、长度及 file/body digest。所有验证通过后，body 才进入 Run-private StagedObject：

Planned → ReadIssued → SourceVerified
        → TypedStaging → Sealed

Sealed 表示物理对象完整并且不可再修改，不表示 Python 已经执行 np.load。

3. Final claim

完整 source 到达后，Host 重新验证它是 admitted prefix 的 append-only extension，并确认 call site、arguments 和 occurrence 没有变化。Fixed bridge 把 owned body copy 交给 fresh Guest；Guest 在申请 token 前重新计算 body digest。

Host 的 claim guard 随后在 table mutex 下同时检查 scalar token 与同一个 sealed StagedObject。两边都匹配才原子消费，object 进入 Claimed，body 被清除，Guest 再用 np.frombuffer(...).reshape(...) 看见 ndarray。Guard 拒绝时 token 和 object 都保持未消费。

未消费对象在 occurrence 未到达、取消、source/body 漂移或验证失败时进入 Orphaned、Cancelled 或 Rejected，logical claims 保持零，retained body 被清理。Replay 会被 claim guard 拒绝；已经成功 claim 的 object 保持 Claimed，不会改写成 Rejected，也不能再次消费。

这条 research lane 与当前 Prepared Family 不同。这里的 object 由一个预测到的 exact numpy.load occurrence 一次性 claim，重点是“提前 physical read、稍后 logical claim”。Prepared Family 则由 Host 先显式提供 bounded ndarray，再创建多个 single-use consumer，重点是“一个 immutable input、多个 authority-private member”。Family 的 binary ABI 也不再把 body 编进 trusted Python source。

为什么重要

技术上： 这个 fixed prototype 证明“提前准备一个真实 typed object”与“Python 逻辑上消费它”可以通过 exact object identity 一次性连接，而不必让长期解释器持有 dataset 和 authority。

产品和业务上： 对身份固定、读取较慢的大型不可变输入，系统有机会把 I/O/decode 与代码生成重叠；未使用的数据只产生可见的准备浪费，不污染最终程序状态。

不能推出什么

  • 当前只覆盖固定 numpy_npy_c_v1、固定 dtype/shape/profile 和 Host-authored copy bridge。
  • Body 会经过 Host staging、copy/base64 bridge 和 Guest reconstruction；这不是 zero-copy。
  • 它不是 generic object ABI、任意 numpy.load、durable cache 或 production optimizer。
  • Prepared Family 的存在不会把这条 numpy.load research lane 自动升级为通用或默认产品路径。
  • Historical schedule model 不是实际 interval trace，也不证明生产性能收益。

术语卡

  • PreparedDataContract：Host 为固定 typed-data preparation 封存的 authority 与 identity 合同。
  • StagedObject：Run-private、带 typed metadata 和 terminal lifecycle 的准备对象。
  • Sealed object：物理内容验证完成、等待 exact claim 的对象。
  • Object-bound claim：同时绑定 token、receipt、body identity 和 occurrence 的一次性消费。
  • Claim token：Host 为一个 exact dynamic occurrence 签发、且只能消费一次的逻辑领取凭证。
  • Copy bridge：当前 fixed lane 将 Host-owned bytes 复制给 Guest 的受限传输方式。

继续阅读