打开文档导航

Pysolate reuse 机制 taxonomy:固定源码审查

Current update (94fab78...): Prepared Family 新增了一类显式 multi-consumer reuse owner:一份 bounded NumPy input/image,有限个 fresh single-use member;Plan、Broker、Invocation、workspace 与 terminal state 不复用。本文的旧 taxonomy 仍用于区分 cache/single-flight/result/COW/workspace;新增 family 详见 09-prepared-family.md

0. 范围、证据边界与状态词

Scope / status: 固定 target 的只读源码 taxonomy 审查;不做 campaign、不改 source、不做 production-readiness 推断。下文的 Current 仅表示目标源码有实现/合同和测试,不等于默认启用或生产就绪。

审查对象: /Users/yuzhe/projects/agent-python-runtime 的精确 commit b94c989785632d98634cdd5c2a6d4a1de6cc13ac,精确 tree 6b8bb6a8d8274b8329a2aba444d13eac9fac19e9。本文只把该 commit 中可追踪到的源码、测试和已提交材料作为证据;不跟随工作树后续漂移,不运行 campaign,不修改源仓库、不 commit/push。

核心边界: Pysolate 的 reuse 不是一个 generic cache。每一类机制复用的对象、owner、生命周期、copy/alias boundary、authority 与 close authority 不同。尤其:

  • whole-Run result reuse 是完成值留存,不是 call coalescing;
  • single-flight 是并发中的 in-flight work collapse,本身不留存完成值;
  • typed/materialized response 是受限数据对象的跨 Guest 传输/重建,不是 whole-Run 结果 memoization;
  • prepared runtime/image 是初始化成本或内存基线复用,不是结果复用、解释器 continuation 或 VM checkpoint;
  • immutable workspace lineage/private attempt 是目录状态与分支身份,不是文件系统 COW、merge 或零拷贝;
  • private-COW 是 Linux 线性内存映射隔离,不是 prepared-data 的创新,也不是 zero-copy;
  • prepared-data staging 是Host 授权的物理工作提前执行 + 后续 exact logical claim,不是 durable blob cache;
  • proof/identity reuse 复用的是可验证事实/身份,不自动复用 authority 或执行结果。

状态词的含义:

  • Current:目标源码中有可调用实现/合同和相应单测,但不等于 production default;
  • Experimental / research-only:源码或 probe 存在,范围明确受限,不能升级为通用生产保证;
  • Historical:材料有旧的 producer/harness/source identity,不能证明本目标 commit 的实现;
  • Deferred:设计上保留但当前没有被允许/证明;
  • Rejected / no-go:已有边界或经济/权威审查明确拒绝 promotion;
  • Unsupported:当前 backend/平台/输入形状不支持,必须 fail closed 或走 fresh/fallback。

WORKER_BRIEF 要求保留的论文边界仍然成立:Host 可以对显式授权、identity-bound、可丢弃的物理工作做 pre-dispatch;不变的 Guest dynamic occurrence 才能 claim logical effect;未到达/非法工作必须 rejected/orphaned,不能继承后续 authority。


1. Taxonomy 总表

机制实际复用对象owner / 实际生命周期copy / alias boundaryauthority 与 close authorityadmission / claim适用场景目标 commit 状态主要源码、测试、证据
1. whole-Run result memoizationexact Invocation 的 canonical 完成结果 []byte;包含 whole-Run source/artifact/profile/import/input/root/settings/output/privacy/policy 身份Host 的 agentfunction.Store;worker-local 的绝对目录,可跨同一 project partition 的后续 Run 重开 store;直到显式 Evict、目录被清理或容量拒绝compute 结果先 copy;磁盘 record JSON;get 再 copy;无 Guest/Host backing aliasGuard 只限制 cacheable physical execution;identity/cache hit 不携带 authority、receipt、transcript 或旧 execution control。Store 没有通用 Close,evict/目录 owner 负责关闭边界Admission == CacheableInvocation.Validate、project partition、CacheEnabled、Store;qualified Guest 另需 opaque qualification + runtime zero-Host-call backstop重复且昂贵的纯 whole-Run 计算;不适合 live I/O、shared writes、未知 Python 或一次性便宜工作Current source / Experimental / default-off;arbitrary Guest-Python purity Deferredruntime/agentfunction/cache.go: Invocation.Validate, Invocation.Identity, Engine.execute, Store.get/put/evictguest.go: ExecuteGuest/ExecuteQualifiedGuestcache_test.go, guest_test.go, semantic_test.godocs/content-addressed-agent-functions.md 明确为 bounded Experimental
2. single-flight同一 domain+exact identity 的一个 in-flight physical computation 及其 waiters,不留存 completed valueHost 内存 FlightGroup.flights;从 leader 开始至 done close;entry 随 completion 删除leader result copy 到 flight;waiter append 再 copy,Shared=true;不共享 Guest/数组/底层 slice只决定谁等谁,不授予执行 authority;leader owner 负责 runFlight、panic 转换和删除 entry;无跨进程 close/persistenceAdmission == Cacheable 且 Engine 配有 Flights;key 含 cache domain + Invocation.Identity;waiter context 可独立取消并发完全相同 invocation 的 collapse;不能替代 sequential completed-result retentionCurrent source / Experimental,与 memoization 可独立开关runtime/agentfunction/singleflight.go: FlightGroup.Do, runFlightsingleflight_test.go, singleflight_internal_test.go, cache_test.go;测试覆盖 panic release、cancelled waiter、different identity、no retention
3. typed/materialized response branchbounded typed ndarray descriptor + immutable body;producer response 被 decode/publish 后,每个 consumer 得到一次 materializationruntime/resultblob.Store 是一个 Run-private in-memory typed blob store;numpycodec 是固定 NumPy branch;lease/entry 至 store closeGuest producer → Host response 是 bounded copy/base64 envelope;resultblob.Publish copy body/metadata;Claim 再 copy;consumer request 再 base64 + fresh Guest frombuffer(...).copy(order='C');没有 pointer/heap/allocator aliasHost ProducerAuthority/PublicationGuard 验证 publication binding;typed descriptor/body identity 不等于 authority;Store.Close 将 body/metadata 清零,lease owner 做 terminal transitionProducer execution properties、authority token、closed dtype/shape/size/binding;consumer exact ConsumerIdentity + lease;BuildMaterializationRequest 全 descriptor/body/consumer binding mismatch 即 reject受限 NumPy C-contiguous little-endian numeric array 的 producer/consumer branch;多 consumer 的私有 materializationExperimental / research-only branch;bounded source/codec 当前存在,但不应称为 generic response cache;production default promotion Rejected / Deferred(见 phase 7 负经济结果)runtime/resultblob/store.go: Publish, NewLease, Claim, Consume/Reject/Discard, Closeruntime/numpycodec/codec.go: DecodeProducerValue, Publish, ConsumerIdentity, BuildMaterializationRequestruntime/numpyproducer/admission.go: Admit, ValidateExecutionResponsestore_test.go, codec_test.go, admission_test.godocs/research/numpy-result-reuse-phase7-outcome.md 为旧 campaign evidence,非本 commit 绑定
4. prepared runtime/image已初始化但尚未服务的单个 Guest/module,或供 clone 使用的 canonical linear-memory baseline/image;不是 result、Python frame 或 continuationWazero Engine owner;普通 prepared slot 在 PrepareSemanticRuntime/ensurePrepared 后等待一次 takePrepared,随后 fresh fallback;PreparedRegionFinalCapacity 一次 compile/execute/close;COW image 随 Engine 存活普通 slot 是同一个 initialized module 的一次性消费;COW image 从 canonical linear memory 复制进 sealed memfd,服务时建 private mapping;无 interpreter state reset/poolEngine owns module/image/session;PreparedRegionFinalCapacity.Close 关 module、cancel、release COW/session;Engine close 等待 active COW lease。prepared lane 仍可能有 configured WASI clock/random,不能标为 authority-freePreparedRuntime/SemanticAnalysis 开关;authority-bearing workspace/Broker 被 scratch/final preparation 拒绝;prepared region 另校验 exact selection/decision/capsule/request分摊 instantiate/initialize/runtime_init 成本;分析 scratch、exact prepared region 或 worker-local baselineCurrent / Experimental;one-slot single-use,非 pool;continuation/checkpoint/dirty interpreter restore Deferred / no-goruntime/engine/wazero/engine.go: PrepareSemanticRuntime, ensurePreparedWithResultAndTrustedSource, newPrepared, takePrepared, Closeprepared_region_final_capacity.go: PreparePreparedRegionFinal, Compile, Execute, ExecuteOriginal, Closeprepared_region_scratch.gotrusted_prepare_test.go, prepared_region_scratch_test.go, cow_runtime_test.godocs/full-composable-runtime-mechanism-summary.md 仅支持 mechanism-level framing
5. immutable workspace lineage / private attemptworkspace directory tree、portable Root lineage record、private mutable Branch/Attempt;不是 Guest/module snapshotHost workspace.Manager owns private 0700 roots;Ref 是本地 materialization handle;Root 可 portable;branch/attempt 从创建到 Seal/PublishDiscard;exclusive Lease 期间 owner 占用CreateFromDirectory, ForkBranch, ForkAttempt 都做普通文件复制;Root identity 只 hash manifest/parent/delta,不证明 storage sharing;sealed root 不可 Acquire mutateManager owns refs/leases/root deletion;Lease.Release、Branch.Discard/Seal、Attempt.Discard/Publish;manager close 对 active lease fail closed;Root/Ref 本身不携带 capabilityexpected parent workspace digest、tree scan/limits、exclusive owner;SelectRoot 显式选择,不 merge;import rebind 校验 portable identity + materialized workspace digest跨 Run 保留明确文件状态、子分支、capsule migration、成功/失败/discard dispositionCurrent / Experimental;portable lineage current;filesystem COW/dedup/merge Deferred / unsupportedruntime/workspace/manager.go: Create, Acquire, Lease.Release, NewTemporarybranch_root.go: ForkBranch, Seal, SelectRoot, BindImportedRootattempt.go: ForkAttempt, Publish, Discardbranch_root_test.go, capsule_test.go, manager_test.go, ingress_*_test.godocs/product-direction.md
6. private-COW一个 sealed linear-memory image 的每次 private mapping;复用的是 pages/baseline,不是 workspace/result/Guest frameLinux Wazero cowImage/sealed memfd 由 Engine owner;每个 run 一个 MAP_PRIVATE mapping;mapping 释放后 munmap,image 在 active mappings 清零后 closebaseline bytes 写入 memfd;`mmap(PROT_READWRITE, MAP_PRIVATE);写时页私有;MADV_DONTNEED` 只恢复 serve 前 baseline;declared maximum 之后是 sparse tail;不是 Host→Guest zero-copymemfd sealed F_SEAL_*;Engine cowActive 计数阻止 active close;每个 mapping/slot 必须 close/discard;COW 不携带 Broker/workspace authority仅 Linux build、bounded exported memory/maximum、profile/prepare binding、MemoryCOW 开关;非 Linux stub 直接不可用;shape drift、unbounded memory fail closedworker-local prepared baseline 的低级密度优化,固定/有界 growable Wasm memoryCurrent / Experimental / Linux-only;不等于所有 CPython state 已 reset,不等于 zero-copy;旧 growable artifact MemoryCOWCandidate=false 材料 Historical
7. prepared-data staging固定 .npy physical read → strict typed decode → Run-private sealed StagedObject/materialized body,再由 exact dynamic occurrence claim;不是 durable result cache当前 Runtime 有 Host contract/decision/stream identity;具体 StagedObject、claim guard、fixed fixture 在 research/prepareddataset,其 owner 是 one-Run research object;sealed 到 claim/orphan/cancel/rejectHost read/typed decode 先把 body 放入 object;MaterializeStaging 做 physical copy;普通 Claim copy 后清 body,ClaimBoundMaterialization 在已验证同 body 后清 body;目标 Guest transport 仍是 explicit bounded copy bridge,不是 aliasHost-authored contract/Plan/receipt/Run privacy/budget;Guest occurrence 只能 claim,不能 mint contract;object/table owner 做 Orphan/Cancel/Reject/Close;未 claim 不可继续留 bodyverified np.load facts + explicit PreparedDataContract + exact Plan/pre-dispatch + Host DecisionContext;final source must extend prefix and preserve exact occurrence; no contract must start zero physical reads在 final source seal 前 overlap one authorized immutable .npy read/decode with later source generation;固定 NumPy fixture onlyCurrent contract pieces + Research-only staging prototype;promotion Rejected / not certifiable;generic dataset/blob, durable cross-Run, arbitrary build pre-execution Deferred/no-goruntime/prepareddataset/decision.go: FactsFromVerifiedAnalysis, Decide, PreparationDecision.Claimcontract.goruntime/streaming/observation.go: StagedObservationresearch/prepareddataset/staged.go: StagedObjectresearch/prepareddataset/claim_guard.gopreparedregion/table.goprepareddataset_test.go, staged_test.go, claim_guard_test.godocs/research/authority-preserving-prepared-data-contract-v1.mddocs/evidence/prepared-data-phase3-v2.jsonprepared-data-phase7-closeout-v1.json
8. proof/identity reusecanonical digest、opaque verified analysis/plan/qualification、descriptor/decision/selection/root identity;复用的是 proof/fact/lookup key,不是 body 或 executionHost/contract owner;identity 可被重算并随对应 Run/Plan/Store/lineage 生命周期保存;opaque proof 只由其 constructor/owner mint大多 body-free;canonical JSON/hash;Ref、physical execution ID、lease token 是 relation/handle,不能当 portable content;digest 不代表 shared backing memory身份本身无 authority;只有 Host-owned Plan/Grant/token + exact validation 才能 admit/claim/publish;close/disposition 仍由对应 Store/Engine/Manager/StagedObject owner 执行每个 consumer 重算 exact bindings;mismatch reject;QualifiedGuestInvocation 先 proof/admission 再 lookup;selection/claim 还要 join decision/capsule/patch/source/body防 stale/mixed artifact、跨 partition、parent conflict、wrong consumer、wrong prepared object;支持 dedup/lookup/evidence correlationCurrent cross-cutting invariant;proof reuse 不是 cache;generic durable proof graph/LabStore Experimental/research-onlyagentfunction/semantic.go: NewQualifiedGuestInvocation, SemanticWholeRunDependenciesagentfunction/guest.go: GuestRequestContractSHA256, ImportClosureIdentityprepareddataset/decision.gopreparedregion/selection.go, table.goworkspace/branch_root.goresultblob/store.go, numpycodec/codec.godocs/research/identity-model.md

2. 分项源码审查

2.1 Whole-Run result memoization:完成值留存,不是 call coalescing

对象与路径。 runtime/agentfunction/cache.goInvocation.Identity 对 canonical JSON 做 digest;字段覆盖 admission、project、function source、artifact、execution profile、import closure、canonical inputs、immutable roots、deterministic settings、output schema、privacy partition、policy epoch,并在 qualified path 加入 semantic analysis/plan/analyzer/region/request-contract。Engine.execute 先做 identity 与 project partition 检查,再在 Store.get(cacheDomain,key) 查完成 record;miss 执行 ComputeFunc,成功且满足 guard 后 Store.putStore.put 写带 schema/domain/key/result/result SHA 的 0600 JSON 文件并原子 rename;get 校验 regular-file、schema、domain/key、size 和 result digest,坏记录删除并按 miss 重算。

owner、生命周期、boundary。 Store 是 Host-owned 的 bounded local directory store;NewBoundedStore 要求绝对路径、0700 目录、project digest,并在启动时扫描现有文件,故它可在同一 project partition 的后续 Host/Run 中读取,但不是 cross-tenant/global cache。结果在 compute 返回时已经是 Host-owned copied []byte;写盘和读回各有 copy。它既不是 Guest memory alias,也不是 persistent Python heap。Store 没有 Close,所以“retention 结束”依靠显式 Evict、目录生命周期或达到 ErrRetentionLimit;这应被视为当前实现的 cleanup limitation,而不是隐含的 automatic TTL。

authority、admission 与失败。 Admission=Cacheable 只是进入严格 gate 的请求分类;GuardHostCall/UndeclaredRead/SharedWrite/Clock/Random/DynamicImport 在 enforce 时令 execution fail。qualified Guest 还需 NewQualifiedGuestInvocation 先完成 opaque semantic proof,ExecuteQualifiedGuest 固定 canonical decoder、拒绝 trusted prepare、校验 runner properties、workspace/Broker absence、request/source/schema identity,并将首个 physical Guest 的 zero-Host-call 作为 publication backstop。cache hit 只返回 bytes、旧 PhysicalExecutionIDCacheHit evidence,不复用旧 receipts、metrics、effect transcript 或执行控制。

结果过大、Store 缺失、project partition 不匹配、purity violation、context cancellation、损坏 record、retention bound 都拒绝或转 miss;失败、trap、timeout、OOM、非 canonical output 和 Host-call attempt 不 publish。普通 ExecuteGuest 明确拒绝 completed-result retention,只有 qualified path 可以留存。

测试/证据与非 claims。 cache_test.go 覆盖 domains、hits、eviction/partition/record integrity;guest_test.go 覆盖 fresh Guest 的 identity、freshness、retention gate;semantic_test.go 覆盖 qualification;docs/content-addressed-agent-functions.md 标明“Bounded Experimental”,并明确 arbitrary Guest-Python purity、global/cross-tenant cache、durable workflow、live I/O reuse 均不成立。docs/research/numpy-result-reuse-phase7-outcome.md 的 typed ndarray campaign 不能反向证明此 generic whole-Run store 的经济性。

不能声称: 不是任意 Python 纯度检测器,不是 workflow continuation,不是 durable distributed CAS,不是跨隐私 partition 复用,也不是“因为 key 是 content-addressed 所以安全”。

2.2 Single-flight:并发等待合并,不留存完成值

runtime/agentfunction/singleflight.goFlightGroup.Doflights[key] 已存在时登记 waiter,等待 existing.done;leader 运行 runFlight(function),完成后复制 result、删除 map entry、close done。waiter 再复制 Value,标记 Shared=true, Disposition=Waiter;leader 默认 Disposition=LeaderEngine.execute 仅在 Flights != nil && Admission == Cacheable 时接入,key 是 cacheDomain + ":" + Invocation.Identity

它的可复用对象是一个 in-flight computation,不是 Store 中的 completed record。TestSingleFlightCollapsesConcurrentCallsWithoutRetentionCacheEnabled=false 时证明 16 个并发 caller 只执行一次,但 completion 后下一次 invocation 仍然重新计算;同测试还证明 single-flight 与 retention 独立。TestCancelledWaiterDoesNotCancelLeader 证明 waiter cancellation 不取消 leader;TestLeaderPanicReleasesFollowersAndCleansEntry 证明 panic 转 ErrFlightPanic、所有 follower 释放且 InFlight=0singleflight_internal_test.go 针对已完成 channel + canceled waiter 的 select race 做 fail-closed 检查。

边界与非 claims。 每个 waiter 都拿到 copy,不共享 Guest/module/blob backing;没有跨进程、跨 Host 或跨 Run 的 flight registry;没有 retention/eviction/TTL。不要把它写成“call coalescing + cache”或用它解释 sequential cache hit;它只是并发 collapse。

2.3 Typed/materialized response branch:数据复用与消费者私有化

runtime/resultblob/store.go 定义 generic-looking 但 bounded 的 in-memory typed blob lifecycle:Publish 校验 RunID/codec/binding/body digest/limits/PublicationGuard,复制 metadata/body,生成 descriptor identity;NewLease 生成一-shot lease;Claim 校验 lease ready 并返回 metadata/body 的 copies;只有 ConsumeRejectDiscard 可结束 lease;Close 将未终结 lease discard 并把所有 retained bytes 清零。这个 Store 的生命周期是 Run-private,和 agentfunction.Store 的可重开磁盘留存不是同一种 retention。

runtime/numpycodec/codec.go 将 branch 收窄到 numpy_ndarray_c_v1:rank ≤ 8、bounded little-endian numeric dtype、C-contiguous、body ≤ 8 MiB,严格拒绝 duplicate JSON、unknown fields、shape/dtype/body digest 不匹配。Publish 先用 ProducerAuthorityBinding 验证 exact producer response,再 decode、生成 typed descriptor、用 resultblob publication guard 写入 body。BuildMaterializationRequest 验证完整 descriptor/blob/lease/consumer identity,构造带 bounded base64 body 的 fresh-Guest request;Guest 重新验证 base64/body SHA/length/dtype/shape,并 .copy(order='C') 创建私有 ndarray。这里至少有 producer envelope、Host store body、consumer request、Guest array 等明确 copy boundary;不存在 pointer/linear-memory view/allocator reuse。

runtime/numpyproducer/admission.goAdmitValidateExecutionResponse 把 source/AST/analysis/artifact/profile/import/plan/pass identities 绑定到固定 numpy-core producer,禁止 external inputs、Host calls、publish/live observe/suspend 等;它是 typed producer branch 的 admission,不是 whole-Run cache admission。codec_test.gostore_test.goadmission_test.go 覆盖 malformed envelope、dtype/layout/body/binding、lease terminal transition 与 mutation isolation。

状态与证据限制。 源码/contract 是当前存在的 Experimental branch;但它不应被称为 generic materialization service。docs/research/numpy-result-reuse-phase7-outcome.md 明确旧 phase 7 的 240-record 矩阵“no observed cell reached break-even”,拒绝把 typed ndarray reuse 设为 performance default,并拒绝新 fan-out/single-flight expansion。该文档使用旧的 phase source/harness identities,故对本 commit 只能算 Historical evidence,不能作 target-bound production certification。pandas、object dtype、pickle、shared pointer、durable/cross-Run body retention 都是 non-claims。

2.4 Prepared runtime/image:初始化基线的一次性复用

runtime/engine/wazero/engine.go 将普通 prepared slot 保存在 Engine.preparednewPrepared 实例化 module、调用 _initializeruntime_init,清理 diagnostic 后返回 preparedInstancetakePrepared 只取一次并置空,之后 PreparedState.FreshFallbackRuns++,因此这里不是 pool,也没有 served Guest reset。PrepareSemanticRuntime 只允许没有 workspace/Broker 的 analyzer lane,但注释明确“configured WASI clock/random substrate”仍可能存在,不能把它当 authority-free interpreter snapshot。

PreparedRegionFinalCapacity 比普通 slot 更严格:PreparePreparedRegionFinal 获得一个 initialized, never-served Guest;Compile 绑定 exact request/decision/capsule/patch/selection;Execute 检查 request bytes 相同、执行一次并在 defer 中 close;ExecuteOriginal 只执行 unchanged source 一次;Close cancel module、release COW lease、release semantic session。没有 fallback 的 capacity 被 consumed/closed 后不能重用。PreparedRegionScratch 同样建立 fresh module 并记录 instantiate/initialize/runtime-init/execute/close evidence,workspace/Broker authority 直接拒绝。

对象与 boundary。 prepared runtime 复用的是 module initialization work 或 COW image 的 baseline;formal request、response、workspace、Broker receipts 都仍走一次 fresh/isolated execution boundary。它不保存 Python frames、open FDs、Broker state、/tmp、Wasm continuation 或 arbitrary module globals 作为 workflow continuation。故 docs/wait-suspension-and-reuse-tradeoffs.md 所述 dirty-page checkpoint/restore 是 Deferred/no-go,不能从“prepared”推导“resumed interpreter”。

2.5 Immutable workspace lineage / private attempt:目录状态身份与完整复制

runtime/workspace/manager.goManager 维护 Host-private 0700 roots;Ref 是 opaque local handle,Acquire 校验树并给一个 exclusive writer LeaseLease.FS 只暴露 rooted WASI adapter,NewTemporary 创建绑定 lease、无 continuation identity 的 scratch tree,Release 要求所有 temporary 先关闭。CreateFromDirectoryForkBranchForkAttempt 都通过 copySourceDirectory 将普通文件复制进新 root;不能把它描述成 filesystem COW 或 “zero-copy branch”。

runtime/workspace/branch_root.goRoot.IdentityDocument 只包含 schema、workspace digest、parent identity、depth、changed entries/bytes;故 root identity portable、刻意不包含 local Ref/Host path。ForkBranch 记录 expected parent digest;Seal 在 base 未变化时将 child 标为 immutable 并生成 parent-linked root identity;expected parent drift 返回 ErrWorkspaceConflict,child 仍可作为 private branch 后续 acquire/discard。SelectRoot 验证候选都是 expected parent 的 sealed children,只选一个,不 merge;BindImportedRoot 重算 portable identity,并要求 imported materialization 的 workspace digest 一致。attempt.goAttempt.Publish 是独立地址的完整 private copy,Discard 删除其 tree。

authority 与失败。 Ref/Root/Branch/Attempt 不含 capability、Guest、temporary 或 Broker authority;Manager/Lease/Branch/Attempt 负责 close/discard。busy、immutable、root scan、limits、parent conflict、source drift 均 fail closed;测试 branch_root_test.gocapsule_test.gomanager_test.goingress_unix_test.go 覆盖 sibling isolation、portable import、select conflict、sealed immutability、discard 与 path/source race。当前没有 storage-layer COW、chunk dedup、merge 或 cross-root alias evidence。

2.6 Private-COW:Linux page isolation,不是 prepared-data 或 zero-copy

runtime/engine/wazero/cow_memory_linux.gonewCOWImageWithMaximum 从 canonical baseline 建 memfdFtruncate 到 declared maximum,写入 non-zero pages,然后加入 F_SEAL_SEAL | F_SEAL_SHRINK | F_SEAL_GROW | F_SEAL_WRITEmapPrivate 使用 unix.Mmap(..., MAP_PRIVATE);每次 allocator 只允许一次 allocation,cowLinearMemory.Reallocate 不得超过 maximum;restoreBaselineBeforeServeMADV_DONTNEED 清除 pre-serve 私有写入;Free/closeMunmap 并 decrement mapping count。

cow_runtime_linux.go 从 compiled module 的 exported memory 读取 canonical baseline,要求 bounded declared maximum,再为每次 prepared/COW run 建 private mapping;prepare 重新 _initialize,检查 growth shape,恢复 baseline,再将 module交给一次 run。derive 以 immutable package parent 为基础建立 dataset child image;Engine.cowParentRuntime 保留 package parent,避免第二次 derivation 继承上一个 dataset。acquireCOWRuntime 增加 active lease,closeCOWRuntime 在 active 为零后才 close image;COW selected 时出错是 fail closed,不隐式把错误当作另一个成功机制。

平台与非 claims。 cow_runtime_stub.go 对非 Linux 返回“memory COW is only available on Linux”。因此 COW 是 Linux-only worker-local optimization;workspace portability 不依赖它。cow_memory_linux_test.go 覆盖 sealed image、private sibling isolation、growable zero tail、maximum rejection、pre-serve restoration、mapping leak cleanup;trusted_prepare_test.go 覆盖 profile/source/parent identity。COW 只覆盖线性 memory mapping;不能证明 mutable globals/tables、WASI host state、native extension state、Python heap 或 external effects 完整 reset。MAP_PRIVATE 也不等于 Host-to-Guest zero-copy:baseline 已写入 memfd,Guest 仍得到自己的 mapping,request/result/data transport 仍可能复制。

旧的 docs/evidence/full-composable-linux-prepared-cow.json 来自 commit 4d774960...,其 fixture 的 MemoryCOWCandidate=falsecow_selected=falsefallback=true,只能作为 growable artifact 的 Historical negative baseline。当前源码的 bounded-growable low-level tests 不能被该旧 JSON 反向否定,也不能从旧 JSON 宣称当前 target campaign 已通过。

2.7 Prepared-data staging:物理准备与逻辑 claim 必须分开

当前 Runtime 的 runtime/prepareddataset/decision.go 只承认一个窄面:target Guest 通过 FactsFromVerifiedAnalysis 产生 authority-free np.load syntax facts;Decide 再把 facts 与 Host-authored PreparedDataContract、sealed capability Plan、Host DecisionContext(workspace/file/body/artifact/profile/import/run/privacy/budget/size)逐项 join。没有 contract、Plan pre-dispatch 或 context exact match,不能发起 sources.read,且 candidate discovery 不能自己创建 authority。PreparationDecision 的 identity 绑定 stream epoch、admitted prefix、span、canonical arguments、occurrence;Claim 才添加 final source digest,并要求 final source 扩展 prefix 且 exact occurrence 不变。

具体 physical object 位于 research/prepareddataset/staged.go,这决定了它的 status:StagedObjectresearch-only 的 one-Run Host object。生命周期为 Planned → ReadIssued → SourceVerified → TypedStaging → Sealed → Claimed,或在对应阶段 Cancelled/Rejected/Orphaned。它只在 decode 到 claim/orphan decision 间持有 bounded body;MaterializeStaging 是 physical copy,不推进 logical state;普通 Claim copy 后清 body;ClaimBoundMaterialization 在 body digest/size 与 receipt 一致时不再额外复制,仅推进 lifecycle 并清 body。research/prepareddataset/claim_guard.go 以 decision/capsule/receipt join object;runtime/preparedregion/table.go 在 claim guard 失败时不消费 token/capsule,成功才将 prepared-region entry 置为 consumed。`

这条 lane 的失败语义非常重要:branch-not-taken、earlier exception、later syntax/error、cancellation、late/mismatch、decode/source drift 都只能进入 orphan/cancel/reject/failed;不能 fallback 到第二次未绑定的 physical read,也不能让无效 physical result变成 logical load。runtime/streaming/observation.goStagedObservation 是另一种 local one-shot observation;它明确说明 durable/global memoization 属于 Agent Functions,不应与 prepared-data object 混称。

证据降级。 docs/research/authority-preserving-prepared-data-contract-v1.md 明确是 Phase 0 frozen、research prototype、not promoted;docs/evidence/prepared-data-phase7-closeout-v1.jsonpromotion.status=rejected,原因包括 no object-bound Host materialization join、CPython preparation residual WASI clock/random、phase 6 projected-not-observed timing,而且其 reviewed target/tree 是旧 commit。目标 commit 中的 prepared-data-phase3-v2.json 虽有 negative controls 和 staged_object_claim_joined 字段,但其 source_commit/object_join_commit 不是本 target。更严重的是 cmd/prepared-data-claim-probe/main.go 的 probe 将 body 以 base64 放进 trusted Guest source,并 monkeypatch np.load,再调用 Host token;它可以测试 token/object lifecycle 的 fixture invariants,却不能证明真实 Host-owned typed staging 已通过生产 ABI join。故应写成 source contract current + research prototype / evidence historical and not certifiable,绝不能写成“prepared-data 已生产化”“Host zero-copy staging”。

2.8 Proof/identity reuse:可重算事实,不是 authority 或结果

identity 复用在多条 lane 出现,但含义不同:

  • agentfunction.Invocation.Identity 是 whole-Run lookup key;QualifiedGuestInvocation 是只能由 NewQualifiedGuestInvocation 构造的 opaque Host-minted proof,先验证 exact VerifiedWholeRunPlan、analysis/plan identity、runner properties、request contract、input/root dependencies,再允许 completed-result retention;
  • GuestRequestContractSHA256ImportClosureIdentity 绑定 untrusted request compatibility 与 exact available/qualified imports;它们用于 admission/partition,不携带 Guest pointer 或 old execution authority;
  • preparedregion.PreparedRegionExecutionSelection 的 identity 是 decision+capsule+patch+final-source+derived-AST 的 canonical digest;PreparedRegionTable 还要 ready/consumed/discarded state 和 optional claim guard,selection 自己不能 claim body;
  • workspace.Root.IdentityDocument 是 portable lineage identity,Ref 只是 Host-local materialization handle;root digest 不意味着 COW/dedup/merge;
  • resultblob.Descriptor/numpycodec.Descriptor 的 body/metadata/binding digest 证明 canonical bytes equality,不能单凭 digest 获得 producer authority;publication token/lease/Plan 是另外的 Host-owned relation;
  • prepared-data 的 PreparationIdentity 不含 final-source digest,ClaimIdentity 才含 final source + exact occurrence;这正是“可提前做物理准备但不能提前 claim logical effect”的边界。

docs/research/identity-model.md 的总规则是“digest proves equality of canonical bytes, not correctness, safety, authorship or meaning”。因此 identity 可用来 lookup、dedup、stale/mixed-input rejection、privacy-preserving comparison 和 evidence correlation;authority 必须由 Host Plan/Grant/token/lease 的独立 admission 提供。identity 的 copy/alias boundary 通常是 body-free canonical JSON/hash;不应把 same digest 写成 same backing memory。其 close/disposition 也不能替代对应 object owner 的 Evict/Close/Release/Discard/Reject


3. 关键 design patterns 与 trade-offs

Pattern A:把“复用什么”与“为什么能复用”拆开

复用类省掉的成本仍然必须支付的成本不能替代
whole-Run memoization重复完整 Guest computationcanonical key、admission、disk I/O、result decode/size check、fresh result materializationconcurrent collapse、typed data ABI、authority proof
single-flight同时发生的重复 computationwaiter coordination、leader lifetime、每 caller result copy后续 call 的 completed hit
typed responseproducer 结果或 dataset 的重复计算decode/descriptor validation、body copies/base64、每 consumer fresh Guest materializationarbitrary result ABI、whole-Run state reuse
prepared runtime/imageinstantiate/init/runtime-initprovision、one-shot lifecycle、close、fresh request executionresult memoization、frame continuation
workspace lineage/attempt重建明确文件状态或重复 ingestfull directory copy、hash/scan、lease/dispositionfilesystem COW、merge
private-COWpage allocation/initialization densityLinux memfd/seals、MAP_PRIVATE faults、module init、unmap/active leasecross-platform isolation、zero-copy、Python state snapshot
prepared-data stagingfinal source seal 之前的 immutable read/decode latencyHost contract/Plan、read/decode/copy、source claim join、orphan cleanupdurable cache、generic blob、authority escalation
proof/identity重复重新计算/传递 canonical relationshipdigest/canonicalization/verificationexecution result、authority、backing-memory sharing

Pattern B:authority-free discovery、Host admission、Guest claim 三段式

prepared-data、semantic reuse 和 prepared-region 都采用相似但不能互相替代的三段式:

Guest/analysis facts (authority-free)
    → Host contract + exact Plan/profile/root/privacy/budget admission
    → physical attempt / prepared object
    → unchanged exact Guest occurrence + final identity
    → one-shot claim or terminal discard/orphan

把第一段直接当成第二段会把 candidate discovery 升格为 authority;把第三段省略会把 speculative physical work 误报成 logical effect。

Pattern C:fresh fallback 是语义 oracle,不是低效实现

普通 fresh Guest 仍是每种优化的 fallback:cache off、flight off、prepared slot exhausted、COW unsupported、workspace branch discarded,都必须回到 fresh/ordinary path,而不是保留 hidden interpreter state。EAGER 对比只能是 opportunity-level comparator;不能从某个 prepared/COW 或 memo hit 断言 dominance/speedup。

Pattern D:每种 owner 都要有自己的 close authority

  • Store:Evict/directory owner;agentfunction.Store 当前没有 generic Close,所以不可声称完整 retention cleanup;
  • FlightGroup:leader completion 删除 entry,no durable close;
  • resultblob:Consume/Reject/Discard + Store.Close 清零 body;
  • Engine/prepared capacity:module/session/COW active lease 由 Engine/Capacity Close;
  • workspace:Lease/Temporary/Branch/Attempt/Manager 分层 close/discard;
  • prepared object/table:claim/orphan/cancel/reject/close;
  • identity/proof:本身不是资源,不拥有 close authority,必须回到其关联 owner。

Pattern E:所有“shared”都要落到 copy/alias 证据

本文只在证据明确时使用 shared:Flight waiter 共享的是 completion event/result lineage,但 byte value 仍 copy;COW sibling 共享 sealed memfd/page-cache lineage,但 private writes 分离;workspace roots 共享 parent identity,但目录实际完整复制;typed blob consumers 共享 descriptor/body identity,但 materialization 进入各自 fresh Guest。没有 mmap/FD、slice backing、lease/close 证据时,digest/descriptor 只代表 equality,不代表 zero-copy。

Pattern F:经济 gate 与机制 gate 分开

源码 tests 证明 correctness/lifecycle;旧 composable summaries 或 phase campaigns 可能证明 bounded mechanism relation,但不自动证明生产 latency/economics。尤其:

  • docs/composable-runtime-mechanism-summary.md 自称 mechanism-only deterministic evidence;
  • typed ndarray Phase 7 的旧报告明确没有 observed break-even,拒绝 default promotion;
  • prepared-data Phase 7 closeout 明确 not certifiable、productionized=false;
  • projected overlap/timing 不能替代 read/decode/finalization/claim 的 observed intervals;
  • old producer/harness/checker commit 的 artifact 只能 historical,不能替代 target-bound evidence。

4. 适用性决策与明确 no-go

可以在当前边界内 carry

  1. exact invocation/descriptor/selection/root identities 与 canonical JSON/hash;
  2. Host-owned opaque qualification + independent runtime backstop;
  3. local completed-result memoization 与 independent single-flight;
  4. one-shot prepared slot / prepared-region capacity;
  5. Linux bounded private-COW low-level primitive;
  6. portable workspace root/lineage、private full-copy branch/attempt;
  7. fixed NumPy typed descriptor/lease/materialization contract 作为 research lane;
  8. body-safe counters、terminal dispositions、source/receipt/claim identity joins。

不能从本文实现推出,需要新边界设计

  • arbitrary Python purity、general region extraction、SSA/CFG/alias/resource algebra;
  • persistent Python heap/frame/checkpoint/restore;
  • filesystem COW、chunk-level dedup、general merge;
  • native/VM snapshot restore,或跨 backend 的 prepared image;
  • Guest ABI 的真实 zero-copy pointer/FD-backed ndarray view;
  • generic typed object ABI、pandas/pickle/object dtype;
  • durable/cross-Run blob store without explicit privacy, leases, crash and cleanup semantics;
  • generic prepared dataset/build-dataset pre-execution;
  • production fan-out/single-flight expansion based only on old negative/under-bound campaigns;
  • “COW = prepared-data innovation” 或 “memoization = call coalescing”。

当前应判为 rejected/deferred/unsupported 的组合

  • Prepared-data promotion:Rejected/not certifiable。 当前有 contract/decision/lifecycle source,但 production object/claim join 的 target-bound proof 不足,probe 还存在 trusted Guest base64/monkeypatch transport;
  • Typed ndarray reuse as performance default:Rejected。 旧 phase-7 evidence 的 measured matrix 未达到 break-even,且 source/harness 不是本 target;mechanism 可保留为 research-only;
  • Dirty interpreter persistence:Deferred/no-go。 线性 memory/COW 不覆盖 CPython frames/heap/WASI/Host state;
  • Private-COW on non-Linux:Unsupported。 build-tag stub 明确 fail closed;应使用 fresh/prepared fallback;
  • Filesystem COW/zero-copy lineage:Unsupported by current workspace code。 当前 ForkBranch/ForkAttempt 是普通文件复制;
  • Identity-only authority:Rejected。 digest/identity 必须与 Host Plan/Grant/token/lease 独立 join。

5. 答辩解释(defense-ready)

问:Pysolate 有没有一个 cache?

答:没有可把所有机制合并成一个 generic cache。完成值 memoization、in-flight single-flight、typed body materialization、prepared module/image、workspace lineage、private-COW、prepared-data staging 和 proof/identity reuse 复用的是八种不同对象,owner、lifetime、copy/alias 与 close authority 也不同。把它们混称会丢失 authority 和 terminal-disposition 语义。

问:single-flight 和 whole-Run reuse 的差别是什么?

答:single-flight 只在相同 invocation 同时执行时让一个 leader 工作,done 后 entry 删除;它没有 completed retention。whole-Run memoization 把成功 canonical result 写入 Host Store,后续 sequential call 可以命中。两者在代码中由 FlightGroupStore 分开,也有独立 off-switch 和独立测试。

问:prepared runtime/COW 是否等于保留了同一个 Python 解释器?

答:不等于。普通 prepared slot 是一个初始化后、尚未服务、只消费一次的 module;COW 是 Linux sealed linear-memory baseline 的每请求 private mapping。它们不提供 Python frame/heap/module-global/WASI/FD/Broker 的通用 checkpoint/restore;fresh Guest 仍是语义 fallback。

问:workspace branch 是否是 COW?

答:不是。ForkBranch/ForkAttempt 通过 copySourceDirectory 做完整文件复制;Root identity 只表达 portable parent/changed-tree 关系。它提供 private attempt、expected-parent conflict、seal/select/discard,但没有 storage COW、merge 或 zero-copy 结论。

问:prepared-data 的 novelty 是什么?

答:严格说是物理/逻辑分离:Host 用 explicit contract + exact Plan + verified syntax facts 提前做一次 bounded immutable read/decode;最终未改变的 exact dynamic occurrence 才能 claim;未到达/错误/取消的 object orphan/cancel/reject。它不是 generic cache,也不是 COW;当前目标源码的合同/decision 是可审查的,但 StagedObject/ClaimGuard 在 research lane,旧 evidence/probe 尚不足以做 production certification。

问:为什么不能说 zero-copy?

答:typed branch 有 producer response/body copy、Host store copy、consumer request/base64、fresh Guest reconstruction copy;COW 有 baseline-to-memfd 和 MAP_PRIVATE mapping;workspace branch 是 full directory copy。digest/descriptor 只证明 identity/equality,不能证明 backing memory alias。

问:identity digest 是不是 authority token?

答:不是。digest 证明 canonical bytes equality,不能证明 correctness、safety、authorship 或 meaning。authority 来自 Host-owned Plan/Grant/publication token/lease/claim guard,并且要与 exact source/profile/root/privacy/budget/consumer identity join。qualified proof 允许 admission,但不会自动携带旧执行 authority。

问:现有 benchmark 是否证明优化更快?

答:不能泛化。composable summary 自己标注 mechanism-only;typed ndarray phase-7 的旧矩阵没有 observed break-even;prepared-data closeout 明确 not certifiable。当前最多能答辩 correctness、isolation、terminal lifecycle 和 bounded opportunity,不能宣称 dominance、普遍 speedup、生产 readiness 或 arbitrary Python 支持。


6. 审查结论

在固定 target 上,最稳妥的架构叙述是:Pysolate 有多个正交、可关闭、owner 明确的局部 reuse primitive;真正可复用的不是“一个 cache”,而是完成值、in-flight work、typed bytes、initialized runtime/image、immutable file lineage、private memory baseline、Run-private staged object 或 proof/identity 各自的 bounded object。所有物理提前工作都必须有独立 Host admission,所有 logical effect 都必须经过 unchanged exact Guest occurrence 的 one-shot claim,所有未采用对象都必须有 orphan/discard/close 语义。

当前最重要的不确定项不是 taxonomy,而是 target-bound evidence provenance:若要把 typed/materialized branch 或 prepared-data staging 从 Experimental/research-only 提升为 production claim,必须重新绑定 producer、harness、checker、artifact、raw report 到目标 commit/tree,并移除 probe 中以 trusted Guest source/base64/monkeypatch 代替真实 Host-owned transport 的论证缺口;同时必须提供 observed timing intervals 与独立 cleanup/privacy/crash semantics。此前不应把 COW 写成 zero-copy,不应把 prepared-data 写成创新性的 COW,不应把 whole-Run memoization 写成 call coalescing。