Pysolate 执行核心单切片源码审查

基线状态：Historical fixed-target dossier。 本文的 Current 只表示下述 b94c989... snapshot 中的实现事实，不是本科生 guide 的当前 94fab78... 目标。当前目标导航见 implementation/source-map.md。

审查对象：/Users/yuzhe/projects/agent-python-runtime 的精确 commit b94c989785632d98634cdd5c2a6d4a1de6cc13ac，tree 6b8bb6a8d8274b8329a2aba444d13eac9fac19e9。

结论状态：Current 的核心是“Host admission/config → 新鲜 Wazero Guest → Host 投影证据 → terminal cleanup”；placement/native 是 Experimental vertical slice；Runtime observation 是 Host-context-only 的 Current 合约，但 cmd/apyrun 不提供 Recorder 持久化。

1. 范围、状态与证据纪律

1.1 本切片覆盖

本切片只审查一次物理 Run 的执行核心：

1. Run admission/config 与边界校验；
2. Pysolate/Wazero 与 native sandbox 的选择、启动和边界；
3. Guest ABI、请求/响应 framing 与 Host evidence projection；
4. observation lifecycle、terminal disposition、cancel 与 cleanup。

Deferred / Unsupported（明确排除）：semantic speculation、prepared data/COW 的内部机制、prepared region、numpy/prepared dataset、benchmark/campaign 总览、生产调度与任意 Python 支持。它们最多作为“此处的边界或 non-claim”出现，不作为本文件的证明对象。

1.2 固定目标与审查方法

• Current：目标 commit/tree 已由 git cat-file、git rev-parse 与 git status 固定；审查源码通过 git show <commit>:<path> 读取，未跟随 live worktree 漂移。
• Observed：目标工作树当时为 main...origin/main、clean，HEAD 与指定 commit 相同，tree 与指定 tree 相同。
• Framing：仓库当前架构文档将 fresh Wazero Run 标为 Current，将 native placement/OCI vertical slice 标为 Experimental（docs/architecture.md:17-33,263-273；docs/unified-execution-profiles.md:1-3,68-89）。文档状态不替代源码或测试证据。
• Historical：未重新解释或升级任何 campaign/evidence artifact；本次没有运行 campaign、probe、release 流程，也没有写源仓库、commit 或 push。

2. 源码地图与符号锚点

以下行号均是上述 commit 中的行号；符号比行号更稳定。

3. 单次 Run 的调用、数据与状态路径

3.1 Admission/config 路径

Current：入口 cmd/apyrun/main.go:main/execute 读取 Host config 与一个 stdin RunRequest；cmd/apyrun/config.go:operatorConfig.resolve 从 DefaultRunConfig() 开始覆盖 timeout、request/response bytes、WASM memory、program surface 与 execution profile，最后调用 RunConfig.Validate（约 config.go:188-283）。

RunConfig 明确是 Host-owned，不能从 RunRequest JSON 解码（runtime/config.go:22-46）。目标中的默认值是 20 s、request/response 各 1 MiB、8192 WASM pages、direct surface（runtime/config.go:55-64）；硬上限是 5 min、16 MiB request/response、16384 pages（runtime/config.go:8-12,79-127）。programmatic/approval、cold-I/O、deterministic profile 等 mechanism 还要经过相互一致性校验。

Current：DecodeRunRequest 先拒绝重复 key、unknown field、trailing JSON、缺少 run_id/code/inputs 和非法 JSON inputs（runtime/request.go:12-69）。run_id 是诊断标签，不是 authority identity。RunRequest 只允许 code、inputs、output schema、compatibility declaration、requirements；没有 path、credential、mount、budget 或 capability grant。

Unsupported → typed outcome：AdmitRunRequirements 在 workspace、Broker、Guest checkout 之前执行；任意合法的 requirements 都会产生 Host-authored UnsupportedRunError，而不是把 Guest 错误文本升级成 runtime unsupported（runtime/outcome.go:53-87）。NewUnsupportedOutcome 将原始 request digest 与 workspace_disposition=not_started、effect_disposition=not_started 固定进 outcome（runtime/outcome.go:113-144）。

3.2 Wazero 创建与单次 fresh execution

Current：runtime/engine/wazero/engine.go:47-80 的 Factory.New 先校验 config，检查 mechanism 是否需要 Broker、workspace binding 是否完整；newEngine 再校验 artifact/profile/deterministic identity，创建带 WithCloseOnContextDone(true) 与 memory limit 的 Wazero runtime，安装 WASI 和 capability imports，并编译 wasm（engine.go:218-270）。

Engine.Run 将可选的 Host trustedPrepare 放入内部 prepare channel 后关闭，进入 runWithPrepares（engine.go:807-813）。核心顺序如下：

bounded raw request
  -> DecodeRunRequest
  -> AdmitRunRequirements
  -> EvaluateRunCompatibility / deterministic admission
  -> WithTimeout(ctx, config.Timeout)
  -> lazy workspace acquire
  -> optional Host observation start
  -> fresh module instantiate (or explicitly selected internal prepared seam)
  -> _initialize + runtime_init
  -> runtime_validate_source
  -> create/check per-Run Broker
  -> optional Host trusted prepare chunks
  -> execute
  -> reject Guest stdout bypass
  -> Broker.Finalize(true)
  -> validate Guest response, project Host receipts/metrics/identity
  -> validate final RunResponse
  -> close module and /tmp
  -> final workspace snapshot
  -> observation completed/failed terminal event

上述顺序由 runWithPrepares 的 admission、timeout、workspace、observation、instantiate、Broker、execute 与 finalization 分段直接给出（engine.go:879-1173）。Current invariant 是默认每个物理 Run 都新建/关闭 Guest module；Runner 合约也明确“一次 Run 一个 fresh guest instance”（runtime/engine/runner.go:12-18）。因此一次 Run 的 Python globals、WASM memory、Host-call context 和临时资源不作为下一次 Run 的隐式输入。

3.3 Placement 与 native L1/L2

Experimental：placement.Analyze 对 request digest、state class、静态 imports、requirements、model-risk 和 Host policy 做确定性选择（runtime/placement/placement.go:79-118）：

• portable value + plain shard imports qualified → BackendPysolateWASM；
• native requirement、unknown/unqualified import、indeterminate source、native state 或 model-risk → BackendNativeSandbox；
• 所需 backend 不可用 → typed unavailable，不降级到较弱 backend。

Orchestrator.Execute 先 decode/analyze，再调用选中的 backend（placement.go:185-207）。只有 Wazero backend 返回 *UnsupportedRunError，且 NewUnsupportedOutcome 验证为两个 not_started，才允许创建带 ParentDecisionID 的 native L2 promotion（placement.go:211-227）。普通 Python exception、import error、timeout、OOM、cancel、capability denial 或 ambiguous completion 不触发隐式 replay；这是“机会级 fallback”，不是 post-start equivalence 或 dominance theorem。

Native boundary（Experimental）：Backend.ExecuteWithEvidence 的顺序是 image-config digest 校验 → rootfs tree identity 校验 → request decode → 可选 workspace lease/snapshot → Broker/私有 Unix HTTP channel → OCI bundle → runsc process group → response/evidence → unconditional reconciliation（runtime/engine/native/backend.go:118-339）。OCI config 将 rootfs 设为 readonly，/tmp、/dev 为私有 tmpfs，channel 为 0600 bind mount；workspace 只有 Host-selected lease 才能挂载（runtime/engine/native/oci.go:12-99）。native/python/runner.py:23-50 只接受严格 pysolate.native-run.v1 envelope，在容器内执行 trusted prepare 与 request code，返回 bounded JSON。

Native 不共享 Wazero module、WASM memory、file descriptors、/tmp、heap 或 call stack；共享的是 Host-authored request/Plan/Broker protocol 和 native 自己的结果/evidence seam。runtime/verification/native.go:18-49 独立验证 decision、artifact、image/rootfs、receipt、lifecycle 和 cleanup identity。重要不确定项：native/python/runner.py:19-51 输出的是 status/result/error/readiness JSON；本 commit 的 native backend 没有调用 Wazero 的 projectHostEvidence 或 runtime.DecodeAndValidateRunResponse。因此本切片不能把 native stdout 宣称为与 Wazero RunResponse 字节级同构，标准化上层 response 需要另一个明确 adapter。

4. Host / Guest ownership 与共享边界

Framing：runtime/engine/abi.go:9-23 的 decoder 会复制 Guest-owned frame payload；runtime/engine/wazero/engine.go:1269-1359 拒绝 Guest 生成 capability_plan_sha256、execution_ref 和未知字段，再注入 Host receipts/metrics/ref。这证明的是边界与一致性，不是恶意 Host 下的独立信任根。

5. ABI、响应与 terminal semantics

5.1 Guest ABI

Current：guest/include/agent_runtime_v1.h:15-55 固定两个 imported Host functions（host_call、materialize_value）和 exported runtime_init、runtime_validate_source、runtime_analyze_source、runtime_prepare、alloc、dealloc、execute。单切片最终执行只依赖 _initialize、runtime_init、runtime_validate_source、alloc/dealloc 与 execute。

Current：guest/src/runtime.c:67-101 用 little-endian u32 length prefix 写 response frame；write_python_unicode 对 response 上限做检查。runtime.c:313-342,443-475 将 ABI 调用转换为 Python runtime module 调用，并把状态码归一化为 0/1/2 或 bounded internal error。Host 的 callWithBytes 先取 alloc、写 Guest memory、调用 export，在结束或错误时以独立短 timeout 调 dealloc（runtime/engine/wazero/engine.go:1428-1463）；readGuestResponse 再检查 prefix、max response、u32 pointer overflow 和 memory bounds（engine.go:1465-1481）。

Failure semantics：缺少 required export、allocation failure、out-of-bounds write、trap、invalid status、truncated/oversized frame 都是 runtime error；不会被当作成功结果。runtime/engine/abi_test.go:15-37 覆盖合法 frame、短 prefix、超限和截断。

5.2 Guest response 与 Host evidence

callExecute 得到 Guest payload 后，先检查 canonical model response；raw stdout 写入会命中 ErrGuestStdoutBypass（engine.go:1103-1110）。DecodeAndValidateGuestRunResponse 只验证 Guest model-output contract；Host 完成 projectHostEvidence 后，再由 DecodeAndValidateRunResponse 验证 status/result/error、receipts、Host capability plan、workspace receipt、output schema 与 response bounds（runtime/response.go:345-395）。

Current invariant：Guest 的 receipts、capability_plan_sha256、execution_ref 和 Host capability-call metrics 不是权威输入；Host 只接纳 Broker 产出的 receipt，并把 plan/call count 投影到最终 response。runtime/response_test.go:34,54,95,197 覆盖 bounded guest output、Guest host-evidence injection rejection、plan/receipt binding 与 workspace receipt。

5.3 Observation 与 terminal disposition

Current：Wazero 从 context 取得 Host InvocationRef 和 observe.Session（runtime/engine/invocation.go:14-27；runtime/engine/observation.go:14-27）。当 observation 非 Off 时，Session execution ID 必须匹配 InvocationRef；随后发出：

1. execution.started，绑定 artifact/code/profile digest；
2. optional capability.plan、intent/started lifecycle 和最终 capability calls；
3. workspace initial/final snapshot 的 bounded file delta，且 SyscallOrderAvailable=false；
4. 成功结果的 execution.completed，绑定 result digest；
5. 任何未终结 runtime error 的 execution.failed，ErrorClass=runtime_error/guest_error 且 EvidenceComplete=false。

具体状态由 runtime/engine/wazero/observation.go:26-164 管理；runWithPrepares 在 runErr != nil && !observation.terminal 时补发 failure（engine.go:957-967），成功路径在 module/temporary close、workspace finalization 后才发 completed（engine.go:1141-1172）。因此 terminal event 不等于 undo：required Recorder 失败不会回滚已经发生的 Guest mutation 或外部 effect。

observe.Session.Append 串行化 recorder、验证 canonical payload/causal parent，并保证 recorder 失败不消费 sequence；Required 传播错误，BestEffort 标记 incomplete，之后不能伪称 evidence complete（runtime/observe/observe.go:125-175）。这是 Observed 的 evidence completeness 规则，不是事务语义。

Native 路径不接入 observe.Session；它使用 native.Evidence 的 aggregate terminal/lifecycle：Evidence.Lifecycle 只有在 exit=0、ready、delete/cgroup/unmount/scratch/workspace cleanup 全部满足时给 TerminalStatus=ok，否则为 error（runtime/engine/native/backend.go:103-108）。VerifyNativeAttempt 要求 cleanup booleans、zero residual runsc entries 和与 decision/artifact/plan/receipts 的 identity 一致（runtime/verification/native.go:21-49）。

6. Cancel、timeout 与 cleanup 状态机

Wazero

Current invariant：runWithPrepares 为每次 Run 建立 context.WithTimeout（engine.go:911-923），Wazero runtime 使用 WithCloseOnContextDone(true)；等待 workspace slot、prepare channel、Guest calls 或 Broker 都受同一 run context 约束。取消/timeout 后函数返回 context error，不能转成 runtime_unsupported，也不把该 module 放回池中。

资源收尾由多个 deferred/final path 覆盖：

• Broker.Finalize(false)（未正常 finalize 时）；
• module.Close(context.Background())；
• per-Run temporary /tmp close；
• workspace run semaphore release；
• observation failure terminal attempt；
• Engine.Close 的 prepared/COW seam、Wazero runtime、workspace lease 与 prepared table close（engine.go:570-588）。

Observed：正常成功路径显式 close module/temporary 后才计算 workspace final/terminal；失败路径通过 deferred close 汇总 errors。该设计优先保证失败 Guest 不复用，但 cleanup error 可能与原始错误通过 errors.Join 共存，调用方必须按 error 与 evidence 两面处理。

Native

Experimental：ExecuteWithEvidence 将 ctx 绑定到 runsc command，设置 process group；command.Cancel 对负 PID 发送 SIGKILL，WaitDelay=2s（native/backend.go:258-275）。运行后无论成功/失败都执行：

1. revoke/close 私有 capability channel；
2. release workspace lease；
3. runsc delete --force 并轮询空 container list；
4. 检查 cgroup 已消失；
5. unmount runsc control root；
6. remove run directory，并检查 runsc state entries 为 0。

任何 timeout、exit nonzero、stdout/stderr overflow、response decode/ready mismatch 或 reconciliation failure 都返回 native execution error；cleanup evidence 仍保留供 VerifyNativeAttempt 审核（native/backend.go:302-339）。因此 native 的 terminal disposition 是“执行结果 + cleanup reconciliation”联合决定的，不是只看 process exit code。

7. Invariants 与 failure matrix

8. 测试与 machine-readable evidence

8.1 本次实际执行

• Observed / PASS：GOCACHE=/tmp/pysolate-gocache go test -count=1 ./runtime ./runtime/engine/... ./runtime/placement ./runtime/verification，runtime、engine、engine/native、engine/wazero、placement、verification 全部 ok。
• Observed / PASS：GOCACHE=/tmp/pysolate-gocache go test -count=1 ./cmd/apyrun，ok。
• Observed / PASS-with-skips：GOCACHE=/tmp/pysolate-gocache go test -count=1 ./integration/e2e -run 'Test(CoreGuest|RealGuestObservation|NaturalOpenSWEPlacementControlBeforeGuest)' -v 返回 exit 0；真实 Guest 测试因 AGENT_RUNTIME_GUEST 未设置而 skip，natural placement canary 因 private evidence path 未配置而 skip。这个结果只能证明测试可编译/skip 条件成立，不能证明真实 artifact execution。
• Current/Observed：目标仓库复核仍为 HEAD=b94c989785632d98634cdd5c2a6d4a1de6cc13ac、TREE=6b8bb6a8d8274b8329a2aba444d13eac9fac19e9、clean；未运行 campaign 或 native probe。

8.2 证据边界

• runtime/*_test.go 和 runtime/engine/*_test.go 提供 deterministic contract/unit evidence；它们不能替代带真实 Guest artifact 的 E2E。
• integration/e2e/core_guest_test.go 与 observation_test.go 明确要求 AGENT_RUNTIME_GUEST；因此本审查不把真实 CPython/WASI execution、raw stdout、timeout recovery 或 observation lifecycle 宣称为本次现场 Observed。
• docs/architecture.md:96-111 与 docs/operator-cli.md:221-228 支持“Runtime observation 是 Host-context-only，apyrun 不持久化 stream”的 Framing；不是本次额外运行出来的 machine-readable result。
• native 的 Evidence/lifecycle.Evidence 是可机读的 Host aggregate；当前源码测试验证字段绑定与 cleanup predicate，但没有在本机启动 runsc，因此不把 Linux OCI gate 说成本次 Observed。

9. 设计 trade-offs 与 rejected alternatives

1. Fresh Guest 而非 served-instance reuse：牺牲启动/初始化成本，换取 globals、WASM memory、temporary 与 Host-call context 不跨 Run 泄漏。回收失败显式暴露，不把 dirty module 复用。
2. Host config 与 untrusted request 分离：拒绝 request 自带 budget/path/credential/grant，牺牲部分调用便利，保住 authority boundary。兼容性 declaration 仍需 Host profile 独立绑定。
3. 保守双层 source admission：Host 的静态 import inference 不是完整 Python parser，可能 false reject；Guest 再做 source validation，优先避免 broad admission，而不是最大化 Python coverage。
4. length-prefixed copy ABI 而非 zero-copy：增加 copy 与 alloc/dealloc 成本，但 pointer/length bounds、response limit、frame copy 和 deallocation 责任清晰。
5. placement 前置 + 只允许 not-started promotion：避免把 post-start exception 当成未执行而 replay；代价是普通失败没有兼容性 fallback，native 需要单独 identity/lifecycle evidence。
6. Wazero observe.Session 与 native aggregate evidence 分开：保持两种 backend 的真实可观测边界，不伪装 syscall/heap/stack 等跨 backend 等价性；代价是上层需要理解两种 evidence schema。
7. required/best-effort/off 三档 Recorder：允许产品路径不被 observation sink 阻断，同时让 required 研究路径 fail closed；但 required failure 不是事务 rollback。

10. Non-claims

• Unsupported：本切片不证明任意 Python、任意 package/native extension、shell/network、dynamic import 或 native compatibility 的生产可用性；成功 fixture execution 不等于 arbitrary Python support。
• Unsupported：不证明 Wazero 与 native sandbox 的隔离、determinism、ABI 或 latency 等价；native placement/OCI 路径仍是 Experimental vertical slice。
• Deferred：不证明 semantic speculation、prepared data/COW、prepared-region authority 或 benchmark/campaign 的 novelty、throughput、latency dominance。
• Framing：Pysolate 的核心安全主张是 Host 保留 authority、Guest dynamic occurrence 才能产生逻辑结果；本文件不把 candidate discovery、receipt、execution evidence 或 placement decision升级为 external-world truth。
• Current limitation：observation 只覆盖 lifecycle、Host Broker calls、initial/final workspace delta；不覆盖 syscall order、unchanged-file reads、Python bytecode/locals、heap/stack、WASM memory 全景（docs/architecture.md:96-111）。
• Current limitation：workspace snapshot/disposition 与 required observation failure 不是 transaction；已发生的文件 mutation/external read 不会被 terminal error 自动撤销。
• Historical：任何未在本次命令中重跑的 checked-in evidence/campaign 只可作为历史或设计背景，不能证明此精确 commit 的现场行为。

11. 答辩口语解释

这一刀的关键不是“让 Guest 提前做更多事”，而是先把 authority 留在 Host：request 只能带 code 和 data，Host 独立校验配置、artifact、profile、预算和 requirements。普通路径每次都启动一个新鲜 Wazero Guest，用固定的 alloc/length-prefixed ABI 传入请求；Guest 只能通过 Host Broker 做受控调用，最终 receipts、plan identity、metrics 和 execution reference 都由 Host 投影，Guest 自己写的 evidence 不算数。成功、失败、超时和取消都要关闭该 Guest；观察系统只记录 Host 能看见的 lifecycle、Broker call 和 workspace 前后差异。Native 是单独的 Experimental backend：只有 preflight 或 Host 明确证明 workspace/effect 都还没开始时才允许升级，启动后失败不透明 replay；native 的 image/rootfs、runsc、cgroup、channel、workspace 和 cleanup 都有独立 evidence。因而这里能答辩的是“authority-preserving、fresh-run、bounded ABI、fail-closed cleanup”，不能答辩成任意 Python、WASM/native 等价或生产 benchmark 优势。