Source-bound Pass Pipeline：当前实现说明

范围与状态

本文绑定 agent-python-runtime commit 94fab78cb3f44d14f86d293287269b704b11d383、tree a4291f77e59d680f5ef1bd21e39b323afd5c5ecf。该 target 已把既有 source/AST 优化登记为 source-bound pass，加入统一 outcome shell，并提供 compile-time static plugin 与 authority-free whole-program source patch seam。所有 pass 仍默认关闭；semantic pre-dispatch 有 projection adapter 和单测，但当前没有 production caller。

重构后的对象

Registration

runtime/passregistration 将 pass 定义为 name、version、stage、consumer 与 required bindings；绑定 analyzer/config 后生成 immutable Registration 和 identity digest。

当前 registration：

Define(...).Register(...) 允许新 pass 在不修改 built-in New switch 的情况下注册。这个扩展点属于同一 Host build，不是动态 loader。

Outcome shell

runtime/passpipeline.Pipeline 不执行 transform、Agent Python、preparation 或 fallback。它提供四个 stage-specific record 入口：

• RecordPrefixOverlay
• RecordHybridPreparePatch
• RecordWholeProgramPatch
• RecordMultiProgramPatch

当前 pass 只落在 prefix-overlay 与 whole-program-patch；另外两个 typed entry point 不是已实现 optimizer。

pysolate.source-bound-pass-outcome.v1 记录 registration/stage/order、applied|discarded|prepared_awaiting_final|rejected、typed rejection、original/derived source 与 AST identity、required bindings、logical/physical count、result/exception order、workspace disposition 和 bounded usage。Record 不保存 source/result/workspace/prepared body。

Pipeline 拒绝：

• caller stage 与 registration stage 漂移；
• required binding 缺失或 analyzer/config identity 不一致；
• rejected outcome 携带 result、derived identity、work count 或 preparation；
• discarded/awaiting-final outcome 声称 logical event；
• 同一 bound occurrence/region 的第二个 terminal projection；
• caller 放宽 pass count、source/AST growth、preparation 或 reanalysis 上限。

V0 最大值是 16 passes、1 MiB positive source growth、8192 derived AST nodes、8 MiB physical preparation 与 16 次 reanalysis。配置只能收紧。Zero-enabled pipeline 的 record attempt 返回 ErrAllOff 且不追加 record；只有 mixed pipeline 中的 disabled pass attempt 产生 rejected/pass_disabled。

Existing mechanism adapters

runtime/semantic/pass_outcome.go: RecordSemanticPreDispatchPassOutcomes 能在 source 已 seal、controller 已 finalized，且 analysis/source/Plan identity 一致时，把既有 staged observation 映射为 prefix-overlay outcome。Consumed 映射 applied；failed/timed-out/cancelled/late/orphaned/fallback 映射 discarded。函数与 unit tests 已存在，但当前 production code 没有调用点；它也不 start、cancel、claim 或改变 physical/logical work。

prepared_pure_region 保留原有 source-bound decision、derived patch、final-source seal、exact target-Guest compilation、single-use capacity 与 cleanup。它已有 immutable registration 与 static adapter，但没有 equivalent outcome projection adapter。

因此“拆成 pass”有两层：registration/stage vocabulary 已统一，pure AST rewrite 也成为可执行 plugin value；common outcome shell 则是可复用合同，当前没有任何 production path 自动把 semantic/prepared/scalar outcome 汇入总账。它更不是把所有机制重写成同一个 transform callback。

Static source-patch plugins

runtime/passplugin.Registry 保存 ordinary Go values，新 registry all-off。SourcePatchPlugin.Transform 调用 authority-free exact Guest 的 runtime_transform_source_pass。Guest 返回 pysolate.source-pass-patch.v1，包含 original/derived source/AST identity、derived source body 与 replacement count。

Registry.Execute 的顺序：

1. Decode unchanged original RunRequest；
2. 若 pass disabled、transform error 或 not-applicable，在 Agent execution/authority-bearing work 开始前执行 unchanged source；
3. 若 applied，调用 Engine.RunSourcePatchDerived；
4. final fresh Guest 正常验证 original request，再通过 runtime_select_source_pass_execution 重新推导并选择 exact patch；
5. derived execution 开始后不再 fallback/replay original program。

Registry 当前不自动调用 passpipeline.RecordWholeProgramPatch。Scalar plugin 的 exact-Guest correctness/timing 由专门 evidence artifact 记录；不能把存在 pipeline whole-program entry point 写成 live scalar outcome 已自动落账。

Generic patch seam 要求 runner 没有 capability Broker 或 mounted workspace。Effect-owning pass 必须提供有对应 Host lifecycle 的 stage adapter。

Current AST passes

pure_scalar_cse

只处理 closed top-level scalar program 中相邻、相同、静态值一致的 bool/int64 +/-/* RHS，并保持 source byte length 与 line layout。Import、call、attribute、control flow、unsupported assignment、self-reference、unknown-call mutation、introspection 或 identity-observable path 使整个 pass not-applicable。

pure_scalar_fold

吸收 stratum 的 exact constant-fold kernel，只折叠同一 closed bool/signed-int64 lane 中 total +/-/* 表达式。Division、heap value、int64 overflow、import/call/control/introspection 等整条拒绝。它不吸收 stratum 的 DataOp graph、projection、vectorization、cache policy 或 approximate operators。

两个 pass 独立，没有 automatic order、conflict resolution、fixed-point、generic IR 或 cost model。

Evidence 与边界

Real exact-Guest fixtures 证明 static registration、patch re-derivation、unchanged original request、pass-off/pass-on result parity 与 negative not-applicable controls。Timing 是负结果：

• pure_scalar_cse：baseline median 2,428,868,958 ns，treatment 2,783,839,291 ns，慢 14.61%；
• pure_scalar_fold retained run：baseline median 2,385,342,083 ns，treatment 2,492,427,458 ns，慢 4.49%。

这支持 correctness/extensibility，不支持 natural prevalence、general speedup 或 production optimizer。Parallel calls、batch fusion、projection pushdown、prepared literal hoisting、multi-program factoring 等仍 Deferred，因为 source rewrite seam 没有替它们提供 Broker item semantics、workspace law、typed materialization join 或 source-order failure/orphan owner。

Source owners

• runtime/passregistration/registration.go
• runtime/passpipeline/pipeline.go
• runtime/passplugin/registry.go
• runtime/sourcepatch/sourcepatch.go
• runtime/semantic/pass_outcome.go
• runtime/engine/wazero/engine.go: RunSourcePatchDerived
• runtime/engine/wazero/semantic_session.go: TransformSourcePass
• guest/bootstrap/agent_runtime/source_pass.py
• guest/src/runtime.c: runtime_transform_source_pass, runtime_select_source_pass_execution