# Pi Context Compiler Harness：Greenfield 架构设计

> **状态**：供架构评审、原型实验和后续实现使用的 greenfield 设计
>
> **项目暂定名**：`pi-context-compiler`
>
> **核心命题**：通过任务条件下的上下文投影，把领域相关的完整上下文编译为一个表面领域中立、但保留科学和数学推理结构的表示，再交给用户当前选择的模型完成主要推理。
>
> **重要边界**：`semantics-preserving` 是必须通过证据和验证争取的验收目标，不是编译器可以无条件保证的事实。系统不能通过改写来规避安全策略，也不能把高影响的不确定语义伪装成确定知识。
>
> **兼容性策略**：全新架构；不要求兼容旧 Safe Router 的 provider、虚拟模型、命令、配置、manifest 或执行流程。本文件只描述新的 harness，不以旧实现的文件结构或行为作为约束。
>
> **实现状态（2026-08-01）**：仓库已经实现 Phase -1 的确定性核心机制、冻结 synthetic triad corpus、scripted fixture replay、证据边界报告、CLI 和 capability-blocked Pi extension。该 replay 的 `empirical=false`、`productReady=false`、`overallDecision=inconclusive`，不能替代 selected-model 或 native-host 证据。对 Pi 0.83.0 的能力审计仍为 Phase 0 `NO_GO`；本设计要求的 host-managed phase turns、fully materialized request mediation 和 provider-attested identity 尚不可由第三方 extension 实现，因此仓库不会用后台 session、widget、custom message、stream middleware 或虚拟 provider 模拟完整 harness。具体边界见 [`docs/phase-minus-one-gates.md`](./docs/phase-minus-one-gates.md) 与 [`docs/pi-capability-matrix.md`](./docs/pi-capability-matrix.md)。

---

## 1. 设计结论先行

本系统不是普通的 model router，也不是把任务拆给两个模型后拼接两段答案。它是一个运行在 Pi 原生 agent loop 上的 **Context Compiler Harness**：

```text
完整原始上下文 C ＋ 当前问题 q_C
        │
        ▼
source-aware admission / policy gate ──不予受理──▶ 终态合规回答
        │
        ▼
deterministic mode triage（一次性，早于任何 provider 响应）
        ├── passthrough mode ─▶ 单个 Reasoner phase turn（原始上下文 + 当前模型）
        │                              │
        └── compiled mode              ▼
                 │              唯一 terminal answer
                 ▼
        Compiler phase：提取、形式化、记录残余与来源
                 │
                 ▼
        Controller 独立 coverage + CompilationCertificate
                 │
                 ▼
        Reasoner Packet Rendering Pass（确定性）
                 │
                 ▼
        用户当前选择的模型：Primary Reasoning Backend
                 │       （使用投影后的 q_Z、工具和上下文）
                 ▼
        结构化 findings / evidence
                 │
                 ▼
        strict-primary deterministic lift（可选受限 renderer）
                 │
                 ▼
        唯一的终端 assistant answer
```

必须同时满足以下决策：

1. **当前用户模型是默认主要推理模型**。系统不注册虚拟 `auto` 模型，不切换 Pi 主 session 的模型。
2. **科学、数学、算法和因果结构必须进入投影**。形式化不是关键词删除，也不是把领域内容压缩成贫乏的 task packet。
3. **运行时采用一条由 host 管理的原生 AgentSession**。Compiler、Reasoner、Integrator 是同一 session 中的可见 phase turns；中间 thinking、文本和 tool events 按原生事件流显示，只有 Integrator 的终端 prose 是最终回答。
4. **Phase Controller 和 Model Request Projector 是两个不同层次**。Controller 管理 agent 运行；Projector 只对已经完全物化的 outbound request 做确定性选择和投影。单独包装 `streamFunction` 不能证明整个架构成立。
5. **Graph Engineering 由运行图实际驱动 context assembly、provenance、recovery、cache、branch 和预算**，而不是仅仅把 pipeline 改名为 graph。
6. **语义保真必须有证据**。每次编译产出 `CompilationCertificate`、residual、coverage view 和 ordinal assurance；高影响未知语义必须显式 abstain 或 fail closed。
7. **默认采用 `strict-primary`**。所有 substantive final claims 必须由当前选中的 Reasoner 独立产生并被 evidence 支持；Compiler 可以提取、规范化和提出检查，但不能替 Reasoner 直接下最终领域结论。默认 lift 是确定性的。
8. **安全判断先于抽象**。任何 abstraction 都不能改变原始任务的目的、能力边界或安全性质。安全/策略拒绝是终态，不允许通过逐步剥离策略相关语义来重试。
9. **成本由全局预支出预算账本控制**。模型调用、turn、tool、retry、projection reset、时间、费用和 branch 都不能绕过同一账本。
10. **MVP 以只读和结构化 patch proposal 为主**。不支持 projected workspace 自动修改；任何实际源码修改都需要 source handle、preimage hash、anchors 和明确的用户批准。
11. **Mode 决策一次性且确定性**。`passthrough` 与 `compiled` 由 admission 阶段的确定性判据选择，发生在任何 provider 响应之前；系统绝不因为观察到拒绝而把 `passthrough` 升级为 `compiled`。这既提供廉价快路径，又杜绝“先试原文、被拒后改写”的 laundering 回路。
12. **发给 provider 的每个请求必须是 provider-valid chain**。tool_use/tool_result 必须配对，thinking block 的顺序和签名必须完整或整体省略，abort 产生的悬空 tool call 必须由 Controller 用显式 aborted result 修复。投影不得产生 provider 会拒绝或静默截断的消息序列。
13. **Phase model 是显式配置而不是隐式回退**。Compiler/Integrator 使用哪个模型必须来自配置与 admission，实际 provider/model identity 必须被 attested 并在 run manifest 中披露；不允许在失败后静默换模型来“让它通过”。

---

## 2. 背景与要解决的问题

### 2.1 原始问题

某个本来适合当前工程任务的模型，可能因为上下文表面上包含生物、科学计算、数学建模、网络安全或其他敏感领域术语而拒绝、触发 fallback 或停止有效推理。直接删除这些内容又会损失完成任务所必需的语义：

- 公式和递推关系；
- 单位、量纲、数值范围；
- 因果方向、量词、时序和否定；
- 假设、退化情形和边界条件；
- 算法步骤、不变量、约束和可验证断言；
- 代码实现与这些规则之间的绑定。

只留下“函数必须幂等”“结果必须安全”一类空洞描述，模型只能机械地看代码，无法判断实现是否符合背后的科学或数学原理。

### 2.2 朴素 harness 的缺陷

以下结构看似简单，实际会造成大量问题：

```text
Router → Engineering Model → Domain Model → 字符串拼接
```

它通常意味着：

- Router 只做分类而不做深度语义分析；
- 主要工程模型拿不到形式化后的科学推理内容；
- Domain worker 与 Engineering worker 看不到对方的结构化 findings；
- 失败 attempt 被丢弃，recovery 从头开始；
- 用户看不到各阶段的原生 thinking/tool event；
- 最终回答是互不关联的两段文字；
- 为了接管流程而注册虚拟 `auto` model，破坏用户原本选择的模型体验。

### 2.3 新问题定义

系统不再问：

> 任务应该路由给哪个模型？

而是问：

> 给定原始上下文、当前问题、当前模型能力和预算，哪些任务相关语义必须保留，如何用模型可推理的中间表示表达它们，并如何让当前模型在这个表示上完成可审计的主要推理？

---

## 3. 术语与边界

| 术语 | 含义 |
| --- | --- |
| **Source Context (`C`)** | 完整的用户问题、项目内容、附件、工具观察和相关会话材料。默认属于 source-private 数据平面。 |
| **Context Compiler** | 对 source context 做 admission 后的抽取、形式化、残余记录和来源绑定流程。 |
| **Semantic IR** | 由 typed symbols、discriminated `FormalStatement` 和 residuals 构成的中间表示。 |
| **Context Projection** | 根据 query、phase、模型能力、工具权限和预算，从运行图生成的一次具体模型请求视图。 |
| **Reasoning Packet** | `Reasoner Packet Rendering Pass` 生成的、准备发送给主要 Reasoner 的最小完整输入。 |
| **Primary Reasoning Backend** | 默认就是 run 开始时用户当前选择的 Pi 模型。 |
| **Private Source Map** | IR alias、formal statement、projected observation 与原始 source fragment 的私有映射。 |
| **Residual** | 无法可靠形式化、存在歧义、缺信息或需要 source-aware judgment 的部分。 |
| **CompilationCertificate** | Controller 根据 source snapshot、结构检查、coverage 和 fidelity 证据生成的编译验收记录。 |
| **RunEvent Log** | 单一 append-only harness 事件账本；ArtifactGraph 与 ExecutionState 都从它 materialize，不分别持久化两套图。 |
| **ProjectionSnapshot** | 内容寻址的、完整记录一次投影和 outbound request 视图的快照。 |
| **Canonical Session Event Log** | Pi 原生、用户可见的 session 事件历史，也是 `/tree` 的基础。它不等同于某一次 provider request。 |
| **Provider Request View** | 每次 provider dispatch 前完全物化的 system、messages、tools、attachments、options 和 cache lineage 视图。 |
| **strict-primary** | 默认模式；最终 substantive claims 必须追溯到当前 Reasoner 的 findings。 |
| **source-aware-supplement** | 可选模式；允许额外 source-aware 模型处理高影响 residual，但必须单独标注、计量和披露。 |
| **Phase Turn** | host 在一个 user turn 内开启的一段 native agent 循环；它有自己的 model identity、toolset、provider request 序列和终止条件，但与其他 phase turn 共享同一个 session、同一个 abort scope 和同一个预算账本。 |
| **Passthrough Mode** | admission 判定不需要编译时的廉价路径：单个 Reasoner phase turn 直接使用原始上下文，行为等同于普通 Pi 会话。 |
| **Compiled Mode** | 完整的 Compiler / Reasoner / Integrator 三阶段路径。 |
| **Provider Chain** | 一次 provider request 中的 message 序列；必须满足 provider 的配对、顺序和签名约束。 |
| **ClaimObject** | 确定性 lift 的最小单位：一个 typed、带 evidence 和 provenance 的结构化断言；terminal prose 只能是 ClaimObject 集合的渲染。 |
| **Host Capability (H\*)** | Pi host 必须提供的可验证能力项（见 §9.5）；缺失必需能力时项目不得进入下一阶段。 |

建议项目名为：

```text
pi-context-compiler
```

建议用户命令为：

```text
/ctx on            # 开启 harness；不切换会话模型
/ctx off           # 关闭 harness；后续回到普通 Pi 行为
/ctx status        # 当前 mode、phase、model identity、预算剩余
/ctx config        # 预算、phase model、mode 阈值、supplement 开关
/ctx mode auto|compiled|passthrough   # 强制 mode；不影响 admission 拒绝
/ctx inspect [run-id]                 # RunEvent / certificate / provenance
/ctx abort
/ctx feedback good|bad
```

`/ctx mode compiled` 只能在新 run 开始前生效，不允许在看到拒绝后对同一 run 重新指定 mode（见 §11.7）。

`ctx` 是常见的 context 缩写；不使用较少见的 `cxt`。

---

## 4. Goals 与 Non-Goals

### 4.1 Goals

1. 让当前用户模型承担主要的科学、数学、代码和 agentic reasoning；
2. 尽可能保留形式化后仍然有推理价值的领域语义；
3. 把表面领域身份和无关叙事从 Reasoner 请求中移除，但不删除安全相关或答案相关语义；
4. 让每一条进入 Reasoner 的 context edge 都经过可审计的 projection；
5. 用 source refs、coverage、residual、finding evidence 和 event lineage 形成可追溯链路；
6. 让 Compiler、Reasoner 和 Integrator 的中间事件实时显示为正常 Pi agent events；
7. 最终只产生一份 coherent terminal assistant answer；
8. 支持取消、工具调用、usage、RPC、`/tree`、branch 和有限 recovery；
9. 通过请求快照、图选择、cache prefix、增量编译和全局预算控制成本；
10. 在没有现成评测集时，用 synthetic triad、结构不变量、shadow telemetry 和真实失败轨迹建立活的回归集。

### 4.2 Non-Goals

1. 不保证任意领域上下文都能无损或完全可逆地形式化；
2. 不把拒绝率下降单独当作成功标准；
3. 不绕过、削弱或隐藏 provider/model 的安全策略；
4. 不建立跨项目长期知识图谱；run graph 默认只覆盖单次 run 和它的分支；
5. 不使用虚拟 `auto` model 作为 orchestration 入口；
6. 不把 `/tree` 当作内部多依赖 DAG 调度器；
7. 不默认支持任意源码的透明双向重写、projected workspace 或自动 apply；
8. 不把模型自报的 coverage、confidence 或 provenance 当作可信事实；
9. 不把模型的私有 chain-of-thought 当作 correctness 或 provenance 的必要依赖。

---

## 5. 数学模型与可检验义务

### 5.1 基本对象

设：

- `C`：完整、source-aware 的原始上下文；
- `q_C`：在原始语境中表达的用户问题；
- `Z`：Semantic IR；
- `q_Z`：从 `q_C` 和任务目标中渲染出的 projected query；
- `M`：Private Source Map；
- `R`：显式 residual collection；
- `K`：Controller 签发的 `CompilationCertificate`；
- `G_t=(V_t,E_t)`：时刻 `t` 的 materialized run graph；
- `P_b`：预算 `b` 下的确定性 Reasoner Packet Renderer；
- `A_sel`：用户当前选中的 Primary Reasoning Backend；
- `A_ref`：仅用于评测的 source-aware reference；它是裁判之一，不是绝对 oracle；
- `L_det`：默认确定性 lift；
- `F_Z`：Reasoner 产生的结构化 findings；
- `Y`：由带 provenance 的 ClaimObject 构成的最终答案。

编译、推理和提升分别为：

\[
(Z,M,R,K,q_Z)=T(C,q_C)
\]

\[
F_Z\sim \mathcal A_{sel}\!\left(P_b(G_t,Z,q_Z)\right)
\]

\[
Y_{primary}=L_{det}(F_Z,M,R,K)
\]

这里用随机算子 `\mathcal A_sel`，而不是把 LLM 错写成确定性函数。相同 packet 的多次运行可以产生不同 findings；稳定性必须通过重复实验测量。

**不能把 `A_sel(C)` 当成主要正确性参考。** 它可能在原始表示上拒绝或失效。`passthrough` mode 中的 `A_sel(C)` 是 admission 预先选择的产品路径，不是为了获得 baseline 而重新发送 raw context 的评测 oracle。

### 5.2 任务充分性：核细化，而不是不可测的互信息承诺

令 `Ans(C,q)` 表示理想的任务答案语义，并把答案规范化为有限 ClaimObject 集合。对一个固定任务族，定义：

\[
C_1\sim_q C_2
\iff
D\!\left(Ans(C_1,q_1),\tau_{1\to2}Ans(C_2,q_2)\right)\le \varepsilon_q
\]

其中 `τ` 负责实体换名后的答案传输，`D` 是任务相关的非对称差异：至少分别惩罚必需 claim 漏报、无证据 claim 多报、极性/作用域错误和不确定度失配。

在精确情形下，任务充分性的规范定义是核包含：

\[
\ker(T_q)\subseteq \ker(Ans_q)
\]

即：凡是被编译器映射为同一任务表示的两个 source context，它们对该任务的答案必须等价。实际系统无法在开放域证明这一全称命题，因此只对预先声明的 metamorphic transformation family `Γ_test` 做逐对检验：

\[
\forall g\in\Gamma_{test}:\quad
D\!\left(Y(gC,gq),\tau_gY(C,q)\right)\le \varepsilon_g
\]

本架构不宣称对 `Γ_test` 之外的变换保持充分性。

### 5.3 声明级保守抽象与 translation validation

不尝试为任意自然语言建立完整形式语义。只在“source 的合法 readings”与“IR statements 的模型集合”之间建立保守关系。令 `Readings(C)` 是与 source 一致的所有解释，`γ_M(Z,R)` 是借助 Source Map 对 IR 与 residual 的具体化，则目标是：

\[
Readings(C)\subseteq \gamma_M(Z,R)
\]

含义是：source 中的歧义只能被保留、加宽或进入 `R`，不能被 Compiler 静默消解成一个更强结论。

由于 `T` 由模型参与生成，无法证明 Compiler 对所有输入普遍正确。采用 **translation validation**：不证明编译器本身，而验证每次具体编译：

\[
V(C,Z,M,R,K)=pass
\]

端到端保证只能条件化表达：

\[
V=pass
\;\land\;
\forall y\in Y,\ check(\pi_y)=pass
\;\Longrightarrow\;
Y\text{ 在 }Assumptions(K)\text{ 下可接受}
\]

`V`、proof checker、packet render/parse、`L_det` 和 event-log reducer 属于可信计算基；Compiler 与 Reasoner 不属于。

### 5.4 Residual 守恒与不确定性单调

Controller 先把 source 划分为互斥的 primary disposition：

\[
Atoms(C)=Mapped\;\uplus\;Residual\;\uplus\;Discarded
\]

- `Mapped` 必须有可解析 SourceRef；
- `Residual` 必须记录类型、位置、影响和开放状态；
- `Discarded` 只能命中预先定义、可审计的 query-irrelevant 白名单，并记录理由；
- 同一 source atom 可以被多个 statement 引用，但只能有一个 primary disposition，避免 coverage 重复计数。

Residual 只能 append 或通过带证据的 discharge event 改变状态，不能删除：

\[
Open(R_t)\uplus New_{t+1}=Open(R_{t+1})\uplus Discharged_{t+1}
\]

由 residual 污染的 premise 所产生的 claim，其 assurance 只能保持或降低，不能凭 lift 自动增强。任何 declassification/discharge 都必须引用 evidence、规则和授权事件。

### 5.5 Provenance 是证明义务，不是 metadata

每个 final claim `y` 必须带一个可由固定演算检查的 proof object `π_y`。proof leaves 可以是：

- `IR(statementId, certificateId)`；
- `Observation(observationId, digest)`；
- `Finding(findingId, reasonerResponseId)`；
- `Source(sourceRef)`；
- `Residual(residualId, status)`。

规则必须满足：

1. finding 引用的 premise 在该 finding 产生时确实出现在 Reasoner 可见 prefix 中；
2. lift 只允许 alias/source-map 换名、等价模板渲染和不确定度加宽；
3. 演算没有“引入无来源新原子”的规则；
4. strict-primary 下每个 substantive claim 的 proof tree 必须包含 current Reasoner 的 `Finding` leaf。

形式化为：

\[
\forall y\in Y_{substantive}:\quad
check(\pi_y)=pass
\;\land\;
containsPrimaryFinding(\pi_y)
\]

这使“当前模型是主要 Reasoner”成为可机检的归因性质，而不是 token 占比或提示词愿望。

### 5.6 Token 预算下的图投影

令每个 artifact node `v` 的渲染成本为 `c(v)`，任务效用为 `U_q(S)`，hard dependency closure 为 `clo(S)`。投影选择可写为：

\[
\max_{S\subseteq V_t} U_q(S)
\]

subject to：

\[
MUST(q,G_t)\subseteq S,
\qquad clo(S)=S,
\qquad \sum_{v\in S}c(v)\le b
\]

`MUST` 至少包括：

- `q_Z` 和输出协议；
- policy-protected semantics；
- 被引用符号的定义闭包；
- 任务相关的公式、量词、单位、边界和前置条件；
- 与任务相关的开放 contradiction；
- high-impact residual 的存在与影响摘要；
- 关闭世界误解所需的 omitted-boundary markers。

如果 `cost(clo(MUST)) > b`，结果是认证的 projection infeasible / abstain，而不是静默截断 mandatory semantics。

一般问题是带前置约束的 knapsack，可能为 NP-hard。实现不追求精确最优：把强耦合节点及其 closure 打包成 bundle，再用确定性 cost-benefit heuristic 选择 optional bundle。只有在离线数据支持时，才把 `U_q` 当作近似单调次模效用；这不是架构定理。

### 5.7 增量、前缀与 Reset

RunEvent log 在 append-only 偏序下单调增长：

\[
G_0\preceq G_1\preceq\cdots\preceq G_t
\]

“撤回”通过追加 `supersedes`、`contradicts` 或 `discharged` event 表达；事实源不删除，当前 believed view 可以非单调。

单个 attempt 的 provider prefix 是 append-only sequence：

\[
P_{i+1}=P_i\cdot \Delta_i
\]

这保证 transcript integrity 和 cache prefix。需要删除或重排时开启新的 bounded `ProjectionReset` attempt；旧 prefix 保留在 event log 中。每个 attempt 的 `MUST` 都重新包含 protected semantics，reset 不能成为削弱它们的路径。

### 5.8 可执行目标：字典序约束，而不是互信息装饰

原式 `min |Z| + λ I(Z;D_s)` 需要未定义的随机变量、分布和不可估的 mutual information，不作为工程目标。采用字典序优先级：

1. admission、certificate、proof、protected semantics 和 hard budget 可行；
2. 最小化 task discrepancy、high-impact residual 和 unsupported claim；
3. 在满足 1–2 后最小化 `DescriptionLength(Z)` 与 source-surface identifiability；
4. 最后最小化 token、延迟和费用。

对预先声明的保义换名/表面变换族 `Γ_id`，离线测试：

\[
d_Z\!\left(Z(gC),Z(C)\right)\le \alpha_Z
\quad\text{and}\quad
Y(gC,gq)\approx \tau_gY(C,q)
\]

中立性与充分性必须同时报告；只降低 source identifiability 会奖励“把信息全部删掉”。这些离线指标不得被用作观察到 provider refusal 后继续改写的 runtime optimization signal。

### 5.9 误差与成本组合

令：

- `η_T`：certificate 通过但 IR 在任务相关原子上仍错误的经验率；
- `η_P`：projection 漏掉必要 optional information 的经验率；
- `η_A`：在充分 packet 上 Reasoner 出错的经验率；
- `η_L`：proof checker / lift / renderer 的实现缺陷率。

不要求独立性，可以使用保守联合界：

\[
Pr[Y\text{ unreliable}]
\le \eta_T+\eta_P+\eta_A+\eta_L
\]

这些是通过 staged audit 得到的经验量，不是先验常数。成本硬上限由 §20.4 的全局 ledger 公式给出；质量目标不能授权突破预算。

### 5.10 明确保留为未证明的问题

以下问题不能在架构文档中伪装成已解决：

- `R` 是否捕获了全部“未知的未知”；
- ClaimObject 语义规范化与等价判定器本身的错误率；
- bundle utility 是否近似次模，以及在线 prefix selection 的竞争比；
- source-neutrality 与 task sufficiency 的可达 Pareto frontier；
- Reference model 与人工裁判何时共同出错；
- 不同模型在同一 packet 上的 stochastic stability；
- 对实际 query language，图互模拟是否足以作为语义等价代理。

互模拟只在 IR 确实表示 transition system、且 `q_Z` 位于对应模态/图逻辑片段时采用；否则不把它作为装饰性保证。范畴论只保留“编译—推理—提升的近似交换图”和 delta composition 直觉，不引入不能产生可检验义务的术语。

如果转换完全可逆，它才接近单纯的换基底；本系统通常是任务条件下、带 residual 和 private inverse relation 的有损投影，因此正式称为 **Task-Conditioned Context Projection**。

---

## 6. 不可违反的架构不变量

1. **Primary Reasoner**：run 开始时 snapshot 的用户当前模型是默认主要 Reasoning Backend；中途模型变更不改变当前 run 的身份。
2. **No Fake Model**：不需要切换到虚拟 `auto` model 或覆盖主 provider registry。
3. **Visible Phase Turns**：compiled mode 下 Compiler、Reasoner、Integrator 都以 host 管理的 native phase turn 运行（passthrough mode 下只有一个 Reasoner phase turn）；中间 thinking/text/tool events 可见且持久化，不能在后台静默完成后一次性吐文本。
4. **One Terminal Answer**：只有最后一个 terminal assistant prose 被标记为用户最终回答；phase transcript 不是最终回答。
5. **Canonical Log Separation**：Pi session event log 是用户可见的规范事件历史；provider request view 是每次 dispatch 的独立投影视图，不可把两者混为一条线性 prompt。
6. **Fully Materialized Mediation**：每次 provider dispatch 必须先得到完整 outbound request，再执行 egress、taint、policy、tool、attachment 和 cache lineage 检查。
7. **Source Admission First**：抽象前进行 source-aware eligibility/policy 判断；投影不能改变任务安全性质。
8. **Task-Sufficient, Not Guaranteed**：只有通过 `CompilationCertificate` 和相应 assurance 的语义才可作为严格主推理输入；未知语义不被静默填补。
9. **Coverage**：每个 source requirement 必须由 controller 派生的 coverage view 关联到一个或多个 FormalStatement，或显式 Residual。
10. **Provenance**：compiled mode 下每个 substantive final claim 都有 current Reasoner finding、approved statement/observation 和 source mapping 链路（passthrough 的退化形式见 §16.1 末段）。
11. **Primary Claims**：strict-primary 下 Compiler 不可直接生成 substantive final claim；Reasoner 必须独立验证或扩展 compiler 提议的检查。
12. **Immutable Transcript**：已签名的 thinking/tool pair 和 canonical phase event 不可原地修改；删除或重排只能通过 bounded `ProjectionReset` 表达。
13. **Cache Prefix Safety**：cache prefix 只能在完全相同的 phase、model/provider identity、system/tool schema、projector/policy version、alias lineage 和 request prefix 下复用。
14. **Append-Only Harness State**：只有一个 RunEvent log；ArtifactGraph 和 ExecutionState 是可重建视图，不分别维护互相漂移的持久化图。
15. **Global Budget**：所有调用、turn、tool、retry、reset、时间、费用和 branch 都从同一个 RunBudgetLedger 预支出。
16. **Policy Refusal Terminal**：安全/策略拒绝不是可以靠换词、删语义或重复重试解决的普通 error。
17. **Conservative Mutation**：MVP 只读或结构化 patch proposal；source handle、preimage hash、anchors 和用户批准缺一不可。
18. **No Lexical Proof Claim**：词法扫描、关键词检查或 alias 检查不能被声称为证明了 non-interference；它们只是 egress defense-in-depth 的一部分。
19. **Provider-Valid Chain**：每个 outbound request 必须通过 chain validator（§8.5）；tool_use 无配对 result、thinking 签名不完整、角色交替非法或空 content block 都是 dispatch 前的硬错误，不是警告。
20. **Mode Immutability**：一个 run 的 mode 在 admission 时确定并写入 RunEvent；任何 provider 行为（包括拒绝）都不能触发 mode 升级或降级。
21. **Attested Phase Identity**：每个 phase turn 必须记录 provider 实际返回的 model identity；声明的模型与实际返回不一致时作废该 attempt，不能把响应归给错误模型。
22. **Finite Worst Case**：每个 run 的 model call、phase turn、tool call、retry、reset 和 correction 都有静态上界，且其总和可在 run 开始前算出（§20.4）；无法给出有限上界的机制不得进入设计。
23. **Terminal Prose Is Rendered, Not Authored**：strict-primary 下终端 prose 只能是 approved ClaimObject 集合的渲染结果，且每一句 substantive 断言都可机械地映射回 claim id（§16.4）。
24. **Proof-Carrying Claims**：每个 substantive final claim 必须带可检查 proof object，且 strict-primary 的 proof tree 必须包含当前 Reasoner 在当时可见 prefix 上产生的 Finding leaf（§5.5）。
25. **Projection Feasibility**：`q_Z`、protected semantics、定义依赖、关键公式/单位/边界、开放冲突和 high-impact residual indicator 属于 `MUST`；`MUST` 的闭包超出预算时必须 abstain，不能静默截断（§5.6）。
26. **Residual Conservation**：每个 source atom 必须有 mapped、residual 或 allowlisted-discarded 的 primary disposition；Residual 只能追加或带证据 discharge，不能从账本中消失（§5.4）。
27. **Translation Validation**：任何具体编译只有在 `V(C,Z,M,R,K)=pass` 后才能进入 strict-primary；系统不把模型生成的 Compiler 普遍正确性当作前提（§5.3）。

---

## 7. 总体运行架构

```text
                         ┌────────────────────────────────┐
                         │ Host-managed native AgentSession│
                         │ canonical visible event log     │
                         │ phase turns / tool events / tree│
                         └────────────────┬───────────────┘
                                          │
                 ┌────────────────────────┴────────────────────────┐
                 │                                                 │
     Host-level Harness Turn/Phase Controller       Deterministic Model Request
     state, tools, abort, retry, budget,              Projector / stream data plane
     compaction, persistence, checkpoints             fully materialized request
                 │                                                 │
        ┌────────┴────────┐                              ┌─────────┴─────────┐
        ▼                 ▼                              ▼                   ▼
   Compiler turn     Reasoner turn                    Integrator turn     provider dispatch
   source-aware      current model                   strict lift/render  actual identity
        │                 │                              │
        └──────────────┬──┴───────────────┬──────────────┘
                       ▼                  ▼
             append-only RunEvent log   ProjectionSnapshots
                       │
          ┌────────────┴────────────┐
          ▼                         ▼
   materialized ArtifactGraph   materialized ExecutionState
```

这里的“同一条 AgentSession”不是“所有 phase 必须共享同一份 provider prompt”。相反：

- **session event log** 保留用户能看到的 canonical phase history；
- **phase provider request view** 每次按 graph、phase 和 policy 重新生成；
- Reasoner 只收到 `q_Z`、Reasoner Packet、projected tools 和 projected observations；
- Compiler/Integrator 可以使用 source-aware request view；
- phase 之间通过 RunEvent、artifact ID 和 checkpoint 连接，而不是把 raw transcript 自动注入每个 provider 请求。

---

## 8. 一条 AgentSession 中的可见 Phase Turns

### 8.1 明确选择：visible phase turns

本设计明确选择 **visible phase turns**，而不是后台 subagent 加最终字符串回传：

```text
agent_start
  ├─ phase turn: Compiler
  │    ├─ thinking/message events
  │    ├─ source-aware tool calls/results
  │    └─ ctx_publish_ir
  ├─ phase turn: Reasoner
  │    ├─ projected thinking/message events
  │    ├─ projected tool calls/results
  │    └─ ctx_submit_findings
  ├─ phase turn: Integrator
  │    ├─ validation/rendering events
  │    └─ terminal assistant prose
agent_end
agent_settled
```

每个 phase turn 都是原生 Pi agent lifecycle 的一部分。用户可以看到当前 phase、模型身份、tool progress 和取消状态；事件不会被 widget 伪造，也不会在后台运行完后才补写。

“可见”不代表系统必须泄露模型内部不可用的 hidden chain-of-thought。它表示 Pi 实际收到的 provider thinking/message/tool events 按正常 Pi event policy 进入 session；如果 provider 不提供 thinking，系统不伪造 thinking。所有 phase 的可见文本都标记为 `intermediate`，只有 Integrator 完成并通过 terminal commit 的 prose 标记为 `final`。

### 8.2 Canonical Session Event Log 与 Provider Request View

两者必须严格分开：

#### Canonical Session Event Log

它是 Pi session 的用户可见规范历史，也是 `/tree` 的依据。它记录：

- user input；
- phase start/end 和 phase metadata；
- provider 实际产生的 thinking/message/tool events；
- tool call、tool result、abort、error、usage 和 final answer；
- 每个事件关联的 `runEventId`、phase、attempt 和 checkpoint。

它不会因为下一次请求需要 projection 就被重写。已经显示给用户的 phase transcript 仍然存在。

#### Provider Request View

它是每一次 provider dispatch 前，由 Controller 和 Projector 完全物化的请求：

```ts
interface MaterializedProviderRequest {
  phase: "compiler" | "reasoner" | "integrator";
  modelIdentity: ModelIdentity;
  system: string;
  messages: Message[];
  tools: ToolDefinition[];
  attachments: ProjectedAttachment[];
  options: ProviderOptions;
  parentSessionEventIds: string[];
  projectionSnapshotId: string;
  cacheLineage: CacheLineage;
  egressDigest: string;
}
```

Provider request view 可以与 canonical session log 不同：它可能只包含某个 graph closure、一个新渲染的 Reasoner Packet 和 projected observations，而不包含之前所有 phase 的 raw messages。它必须有 content-addressed snapshot 和 parent event references，不能成为不可追踪的临时字符串。

因此，“同一 session”不意味着“模型看到同一上下文”；它意味着所有 phase 的生命周期、事件、取消、usage 和分支都由同一个 host-managed native session 负责。

### 8.3 Host 层可见 Phase Turn 的精确语义

一个 user turn 展开为 `1..N` 个 phase turn。phase turn 是 **host 一级对象**，不是 UI 标签：

```ts
interface PhaseTurn {
  phaseTurnId: string;
  runId: string;
  branchId: string;
  phase: "compiler" | "reasoner" | "integrator";
  attemptId: string;
  attemptOrdinal: number;             // 同一 phase 的第几次尝试
  declaredModel: ModelIdentity;       // Controller 选择
  attestedModel?: ModelIdentity;      // provider 实际返回
  toolsetDigest: string;
  cacheNamespace: string;
  budgetReservationId: string;
  stopReason: PhaseStopReason;
}

type PhaseStopReason =
  | "control-tool"        // ctx_publish_ir / ctx_submit_findings / ctx_commit_terminal_answer
  | "completion-predicate"// 无 tool call 且满足 Controller 的 phase 完成判据
  | "budget-exhausted"
  | "abort"
  | "chain-invalid"
  | "protocol-failed"
  | "policy-refusal"
  | "provider-error";
```

Host 必须保证的性质：

1. **单活跃 phase**：同一 branch 上任何时刻最多一个 phase turn 处于 running；不存在隐式并发 phase。
2. **边界即事件**：`PhaseTurnStarted` / `PhaseTurnEnded` 是 canonical session event，带 phase、attempt、model identity、toolset digest 和 projection snapshot id。
3. **循环归 host**：phase turn 内部的 request→stream→tool→request 循环由 host agent loop 驱动，不是扩展自己写的 while 循环；否则 abort、usage、RPC 和 `/tree` 会与原生语义分岔。
4. **终止可判定**：`stopReason` 必须是上表中的有限集合；“模型不再调用工具”不自动等于 phase 成功。
5. **finality 标记**：所有 phase 内的 assistant message 带 `finality: "intermediate"`；只有 `TerminalAnswerCommitted` 关联的那一条带 `finality: "final"`。
6. **客户端契约**：TUI、JSON、RPC 和 headless 均以 `finality` 字段而非“最后一条 assistant message”判定最终回答；run manifest 同时直接给出 `terminalMessageId`，使不读 metadata 的消费者也能定位。
7. **取消域**：一次 abort 取消整个 run（当前 phase turn、inflight tool、待执行 transition 和所有 reservation），而不是只取消当前 provider stream。

如果 host 不能将 phase 作为一级概念提供，可接受的最小替代是：允许扩展在同一 session 内发起多个 native turn，并在每个 turn 上附加不可伪造的 metadata（见 §9.5 的 H2/H3）。“后台跑完再一次性写入事件”不满足本节要求。

### 8.4 每个 phase 的 provider 视图是重建而不是续写

phase 之间不共享 message 历史。每个 phase 的第一个 request 都从 artifact 重新构造：

| | Compiler | Reasoner | Integrator（可选 renderer） |
| --- | --- | --- | --- |
| system | source-aware compiler instruction | neutral reasoning instruction | rendering-only instruction |
| 首条 user message | admitted raw fragments + fragment handles | 确定性渲染的 Reasoning Packet | approved ClaimObject 集合 |
| 后续 messages | 实际 compiler tool 循环 | 实际 reasoner tool 循环（只含 projected observation） | 无（单轮） |
| tools | compiler toolset | reasoner toolset | 仅 `ctx_commit_terminal_answer` |
| attachments | 按 admission 允许的 raw | 仅 projected attachment | 无 |
| cache namespace | `cmp:<sourceSnapshot>` | `rsn:<packetDigest>` | `int:<claimSetDigest>` |
| 可见性上限 | source-private | reasoner-visible | integrator-visible |

硬规则：**一个 phase 的 provider chain 中不得出现另一个 phase 的 message、thinking 或 tool block 原文**。跨 phase 的信息只能以 artifact（IR、observation、certificate、finding、claim）形式流动，并在目标 phase 重新渲染。这条规则同时解决了三件事：避免 raw source 沿 transcript 泄漏、保持 cache prefix 稳定、避免跨 phase 的 thinking 签名失效。

`passthrough` mode 是本表的退化情形：只有一个 Reasoner phase turn，其 provider 视图就是普通 Pi 会话上下文，不做 alias、不做 packet 渲染，egress gate 仍然运行但只做 policy 检查而不做 taint 降级。

### 8.5 Provider-valid chain 构造规则

投影可以自由选择内容，但不能产生 provider 会拒收或静默截断的消息序列。dispatch 前的 chain validator 强制：

1. **Tool 配对**：chain 内每个 `tool_use` 必须有唯一对应的 `tool_result`，位置符合 provider 要求（Anthropic 形式：紧接的 user message；OpenAI 形式：`role=tool` 且 `tool_call_id` 匹配）。
2. **悬空调用修复**：abort、预算耗尽、projection error 或 lowering 失败导致的无结果 tool call，Controller 必须写入显式 `tool_result`（`{status:"aborted"|"error", code}`）。不允许把它留在 transcript 中等待下次分支时爆炸。
3. **Thinking 完整性**：带签名的 thinking block 只能在**同一 phase、同一 model identity、原位置、原签名**下重放；任一条件不满足就**整条 assistant message 的 thinking 整体省略**，而不是部分编辑。redacted thinking 作为不透明单位原样保留或整体丢弃。系统永不合成、改写或翻译 thinking 文本。
4. **已发送不可改写**：已进入某个已 dispatch prefix 的 assistant 文本不得就地修改；必须改变时只能从 checkpoint 开新 attempt，并记一次 `ProjectionReset`。
5. **跨 phase 隔离**：其他 phase 的 thinking/tool block 不得出现（同 §8.4）。
6. **结构合法性**：无空 content block、无非法角色交替、无重复 tool_call_id、attachment 格式在 provider allowlist 内、token 估算不超模型上下文窗。
7. **失败即 fail closed**：chain validator 失败产生 `chain_invalid`，**不发请求**，归类为 controller defect（可进行 §20.2 类型 1 的修复 retry），不归类为模型失败，也不允许“删几条消息再试”。

validator 必须跑在**完全序列化后**的请求上（与 egress gate 同一个对象），而不是跑在构造中间态上。

---

## 9. 两层运行时设计：Phase Controller 与 Request Projector

职责边界先用一张表固定下来，后面的子节只是展开：

| 能力 | Phase Controller（控制平面） | Request Projector（数据平面） |
| --- | --- | --- |
| 创建 run / phase turn / attempt | 具有 | 无 |
| 选择 phase model | 具有 | 只读 |
| 切换 toolset | 具有（原子，turn 边界） | 无 |
| 决定哪些 artifact 可进入本次请求 | 提供 pinned graph view 与 policy | 在该范围内做确定性选择与序列化 |
| chain validator / egress gate | 拥有规则与否决权 | 必须调用并服从否决 |
| 创建 retry / ProjectionReset | 具有 | 无（只能返回 `block`） |
| 预算预支出与 commit | 具有 | 只读剩余额度 |
| 写 RunEvent / canonical event | 具有 | 无（仅产生 snapshot 候选） |
| checkpoint / branch / terminal commit | 具有 | 无 |
| 观察 provider stream / usage | 汇总与记账 | 可观察，不可改变事件语义 |
| 发起模型调用 | 可（仅通过 phase turn） | 不可 |

一句话区分：Controller 决定**什么可以发生**，Projector 决定**已经被允许的东西以什么字节形式离开进程**。

### 9.1 Host-level Harness Turn/Phase Controller

Controller 是受信任的控制平面组件，拥有以下职责：

- 创建 run、phase turn 和 attempt；
- 选择 phase model，但记录真实 provider/model identity；
- 原子切换 phase-specific toolset；
- 管理 phase transition 和 control tools；
- 处理 abort、provider cancellation、tool cancellation 和临时资源清理；
- 维护全局 RunBudgetLedger，执行每次预支出检查；
- 拥有 retry/recovery 决策，模型不能自行授权 retry；
- 决定 compaction policy；
- 将 native provider events 写入 canonical session event log 和 RunEvent log；
- 建立 branch checkpoint、ProjectionReset 和 phase checkpoint；
- 在 terminal answer 前执行 finding、provenance、egress 和 budget 校验；
- 保证每个 run 只有一个 terminal answer commit。

Controller 可以拒绝模型通过 tool 参数修改 phase、预算、cache lineage、visibility、source refs 或 tool permissions。模型输出只是 data-plane proposal。

### 9.2 Deterministic Model Request Projector / Stream Data Plane

Projector 位于 provider dispatch 的数据平面，输入必须是已经完全物化的 request 和当前 phase state。它负责：

- 根据 phase 选择 model/context/tools/attachments；
- 从 ArtifactGraph view 生成确定性的 request projection；
- 套用 stable alias、source visibility、taint 和 residual policy；
- 计算 request、cache prefix 和 provenance digest；
- 将 fully serialized request 交给 egress gate；
- 在不改变事件语义的前提下观察 provider stream 和 usage。

Projector **不能**：

- 直接做 source-aware policy 判断之外的模型推理；
- 自行创建 retry；
- 从 raw source 中临时拼接没有 artifact/provenance 的内容；
- 通过删除语义来让拒绝消失；
- 修改已持久化的 canonical transcript；
- 把 stream wrapper 当作 phase controller。

### 9.3 最小 API（语义固定，命名待 host 评审）

```ts
// ---------- A. 控制平面：host 提供给 harness ----------
interface HarnessRuntime {
  beginRun(plan: RunPlan): Promise<RunHandle>;
  beginPhaseTurn(run: RunHandle, plan: PhaseTurnPlan): Promise<PhaseTurnHandle>;
  endPhaseTurn(turn: PhaseTurnHandle, outcome: PhaseOutcome): Promise<PhaseCheckpoint>;
  abortRun(run: RunHandle, reason: AbortReason): Promise<void>;
  commitTerminalAnswer(run: RunHandle, answer: TerminalAnswer): Promise<SessionEventRef>;
}

interface PhaseTurnPlan {
  phase: Phase;
  attemptOrdinal: number;
  model: ModelIdentity;                 // 仅本 turn 生效，不改会话选中模型
  toolset: ToolDefinition[];            // 原子替换，仅本 phase 可见
  initialRequest: MaterializedProviderRequest;
  loopPolicy: {
    maxProviderCalls: number;
    maxToolCalls: number;
    stopOnControlTools: string[];       // 例如 ["ctx_submit_findings"]
  };
  budgetReservationId: string;
  metadata: PhaseEventMetadata;         // 附着到本 phase 所有 native event
  autoCompaction: "disabled";           // MVP 必须可关
}

interface PhaseTurnHandle {
  phaseTurnId: string;
  events: AsyncIterable<NativeAgentEvent>;   // 原生事件，不是自定义封装
  signal: AbortSignal;
  usage(): Promise<PhaseUsage>;              // 含 nested/tool 子调用
  attestedModel(): Promise<ModelIdentity | undefined>;
}

interface PhaseOutcome {
  stopReason: PhaseStopReason;
  controlToolResultIds: string[];
  producedArtifactIds: string[];
}

// ---------- B. 数据平面：harness 提供给 host ----------
interface MaterializedRequestProjector {
  readonly projectorVersion: string;
  project(request: MaterializedProviderRequest,
          ctx: ProjectorContext): Promise<DispatchDecision>;
  observe?(event: ProviderStreamEvent, ctx: ProjectorContext): void;  // 只读
}

type DispatchDecision =
  | { kind: "dispatch";
      request: MaterializedProviderRequest;   // 已通过 chain validator + egress gate
      projectionSnapshotId: string;
      cacheLineage: CacheLineage }
  | { kind: "block";
      code: "egress-violation" | "chain-invalid" | "budget-denied"
          | "visibility-unknown" | "policy-block";
      detail: string };

interface ProjectorContext {
  runId: string; branchId: string; phase: Phase; attemptId: string;
  aliasMapDigest: string;
  graphViewDigest: string;             // pinned，不可在 project() 内变化
  visibilityPolicyVersion: string;
  remainingBudget: BudgetUsage;        // 只读
  chainValidator: (r: MaterializedProviderRequest) => ChainCheckResult;
  egressGate: (r: MaterializedProviderRequest) => EgressDecision;
}

// ---------- C. 事件与 checkpoint 桥 ----------
interface NativePhaseEventBridge {
  annotate(event: NativeAgentEvent, metadata: PhaseEventMetadata): NativeAgentEvent;
  persist(event: NativeAgentEvent): Promise<SessionEventRef>;
  createCheckpoint(cp: NativeCheckpoint): Promise<{ checkpointId: string; treeEntryId: string }>;
}
```

`project()` 必须是相对 `(request, ctx)` 的纯函数：不发网络请求、不调模型、不写 graph、不读未 pin 的状态、不依赖壁钟。相同输入必须得到相同 `projectionSnapshotId`；这是 §17.5 replay 确定性的前提。

这些接口的关键语义是：

1. **Controller hook 在 host 层**，能管理原生 turn、toolset、phase、abort、retry、budget、compaction、event persistence 和 branch checkpoint。
2. **Projector hook 在 provider dispatch 前**，收到已经 materialized 的完整请求，而不是只收到一个尚未展开的 prompt 参数。
3. **事件桥不创建假的 custom answer**，而是让 phase metadata 附着在正常 native event 上，最终由 Pi session 持久化。
4. Provider 原生 stream、usage、abort signal、RPC、TUI 和 JSON 输出继续走同一事件路径。

`registerModelStreamMiddleware` 如果存在，只能作为 Request Projector/stream data-plane 的一个实现点，**不能被宣称为解决整个 harness 的 API**。一个只做如下事情的 SDK prototype：

```ts
session.agent.streamFunction = wrap(session.agent.streamFunction)
```

最多能验证 request/stream 变换，无法验证：

- visible phase turn 是否由 host 正确持久化；
- toolset 是否在 phase 边界原子切换；
- retry、reset、compaction、budget 和 branch checkpoint 的所有权；
- 完全物化 request 的 egress mediation；
- `/tree` 重放和终端 answer commit；
- provider/cache lineage 与 transcript integrity。

所以 stream-only SDK prototype 不能作为整套架构的有效证明。正式 Phase 0 必须使用 host-level API spike 或 Pi host fork，先验证完整生命周期。

### 9.4 Phase model 选择策略

“哪个模型跑哪个 phase”必须是配置而不是运行时探索：

```ts
interface PhaseModelPolicy {
  reasoner: "session-selected";                 // 固定，不可配置
  compiler: ModelRef | "session-selected";      // 默认读配置；未配置时同会话模型
  integrator: "deterministic" | ModelRef;       // 默认 deterministic（零模型调用）
  supplement?: ModelRef;                        // 仅 supplement mode，默认未设
}
```

规则：

1. Reasoner 永远是 run 开始时 snapshot 的会话选中模型；这是产品承诺，不可因失败而替换。
2. Compiler model 在 run 开始前确定，写入 `RunStarted` 和 manifest。
3. **禁止 provider shopping**：一个 phase 失败后不得换一个模型“再试一次直到有人接受”。尤其是 Compiler 的 policy refusal 是终态（§11.7），换模型重试与换词重试同属 laundering。
4. Integrator 默认不调模型；升级为受限 renderer 需配置并计入预算（§16.4）。
5. 所有 phase model 在 `/ctx status`、run manifest 和最终回答 metadata 中披露；用户不会看到“一个模型完成了全部工作”的假象。

**诚实的局限声明**：当 `A_cmp = A_sel`（未配置独立 compiler）时，对于“当前模型对原始领域表述直接拒绝”这类目标场景，Compiler phase 也会拒绝，整个 run 以合规 refusal 终止。这是正确行为，不是缺陷；但它意味着**发行配置应当提供一个对 admitted source 能正常工作的独立 compiler model**，否则产品价值只剩下“结构化上下文工程”而不包括“避免表面特征触发的拒绝”。评审时应把这两个价值分开评估。

### 9.5 Host 能力清单（H1–H12）与降级策略

Phase 0 的真实工作是逐项探测以下能力，而不是先写业务逻辑：

| ID | 能力 | 级别 | 缺失后果 |
| --- | --- | --- | --- |
| H1 | 在同一 session 内发起多个 native turn，且不修改用户选中模型 | 必需 | 无法实现 visible phase turns |
| H2 | per-turn model override（仅本 turn 生效） | 必需 | 只能切会话模型，违反核心约束 |
| H3 | per-turn toolset override（原子，非全局注册） | 必需 | phase 工具隔离不成立 |
| H4 | provider dispatch 前拿到完全序列化 request 且可阻断 | 必需 | egress/chain 不可验证，安全不得宣称 |
| H5 | native event 上附加不可伪造 metadata 并持久化 | 必需 | 无法区分 intermediate/final |
| H6 | 可关闭 host 内置自动 compaction（session 或 turn 粒度） | 必需 | transcript/cache/replay 均可被静默破坏 |
| H7 | 单一 abort signal 级联到 stream 与 tool | 必需 | Esc 语义不完整，资源泄漏 |
| H8 | 按 turn/请求粒度上报 usage/cost（含 nested） | 必需 | 预算账本不成立 |
| H9 | checkpoint 与 session tree entry 关联且可 replay | 必需 | `/tree` 分支与 recovery 退化 |
| H10 | provider 侧 attested model identity（如 `message_start`） | 必需 | 不可声称“当前模型完成了主推理” |
| H11 | 按请求设置 cache control / prefix 提示 | 可选 | 关闭跨请求缓存，成本上升 |
| H12 | RPC/JSON 输出中透出 phase/finality 字段 | 可选 | headless 消费者只能读 manifest |

降级策略：**H1–H10 缺一不可**。缺失时只有两个合法选项：向 Pi host 提 API，或在 fork 上实现后重跑 Phase 0 gate。禁止的“创造性变通”包括：用后台 session 假装 phase、用 widget 模拟事件、用字符串拼接冒充终端回答、用 stream wrapper 自己写 agent 循环。这些方案已在 §26 完整拒绝，不应在实现阶段因为进度压力重新引入。

---

## 10. Phase Transcript Integrity 与 Cache-Prefix 规则

### 10.1 Transcript 记录和签名

canonical phase transcript 以 host 接收的事件为准。对 provider 实际发送并由 Pi 接收的消息，Controller 在 message/tool 边界生成 canonical record：

```ts
interface SignedPhaseRecord {
  recordId: string;
  runId: string;
  phase: Phase;
  attemptId: string;
  sequence: number;
  kind: "thinking" | "assistant_message" | "tool_call" | "tool_result";
  payloadDigest: string;
  parentDigest: string;
  pairedRecordIds?: string[];
  hostSignature: string;
}
```

“signed thinking/tool pair”指 host 对实际收到且允许持久化的 thinking/message 与对应 tool call/result 做签名或 hash-chain 认证；它不表示模型暴露了 hidden chain-of-thought，也不表示 host 伪造了模型思维。provider 没有提供 thinking 时，系统只签名实际存在的 event。

已签名的 pair 和 canonical event 是 immutable：

- 后续 usage、latency 或诊断信息只能追加 metadata event；
- 不能覆盖 message text、tool arguments、tool result 或 phase identity；
- 不把 provider retry 的新响应写回旧 record，而是新建 attempt/record；
- 任何完整性失败都使对应 attempt 无效，而不是静默修补。

### 10.2 Projection 的单调追加规则

同一 phase 内，provider request projection 必须有单调递增的 lineage：

```text
Projection P0
   └─append tool observation→ P1
        └─append finding/refinement→ P2
             └─append requested scope→ P3
```

默认允许：

- 新增 tool observation；
- 新增经验证的 FormalStatement；
- 新增 residual/known-gap indicator；
- 扩大已批准 scope；
- 新增 Reasoner request 或 clarification。

默认不允许直接删除或重排已进入某个 phase 的 projection 内容。它是单调性的**唯一**合法破口，必须由 Controller 追加：

```ts
interface ProjectionReset {
  resetId: string;
  previousProjectionId: string;
  newProjectionId: string;
  reason: ProjectionResetReason;
  evidenceEventIds: string[];        // 必须指向已存在的 RunEvent，不接受自由文本
  resetOrdinal: number;              // 本 run 内第几次，受 maxProjectionResets 限制
  remainingResetBudget: number;
  policyStatementSetDigestBefore: string;   // 参见 §20.2 单调性检查
  policyStatementSetDigestAfter: string;
}

type ProjectionResetReason =
  | "proven-egress-defect"      // fully serialized 检查证实的未授权内容
  | "chain-invalid"             // §8.5 validator 失败
  | "tool-schema-defect"        // 工具定义与 host 实际不一致
  | "request-assembly-defect"   // Controller/Projector 自身 bug
  | "context-overflow";         // 超窗，只能重新装配而不能静默截断
```

后置条件（全部强制）：

1. 新 projection 必须通过完整的 coverage / certificate / chain / egress 检查，不能继承旧结论；
2. `policyStatementSetDigestAfter` 对应的 policy-sensitive statement 集合不得是 before 的真子集（不得借 reset 剥离风险语义）；
3. 旧 cache prefix 作废（§10.3 规则 4）；
4. 旧 transcript 不删除、不改写，只是不再进入后续 request；
5. reset 配额耗尽时的唯一合法结局是 abstain 或以已有可靠 findings 收束；
6. `policy-refusal` 不在 `ProjectionResetReason` 中，因此它结构上就无法被当作 reset 理由。

### 10.3 Cache-prefix 规则

cache lineage key 是一个显式构造的有序 digest，不是“内容看起来一样”的启发式：

```text
cacheLineageKey = H(
  phase
  ‖ providerIdentity ‖ modelIdentity ‖ modelRevision
  ‖ H(systemInstruction)
  ‖ H(orderedToolSchemas)
  ‖ projectorVersion ‖ policyVersion ‖ admissionVersion
  ‖ irVersion ‖ aliasMapVersion ‖ aliasMapDigest
  ‖ H(orderedAttachmentDigests)
  ‖ H(exactSerializedPrefixBytes)
)
```

为了让前缀真的稳定，请求分为两段：

```text
[ stable prefix ]                              [ volatile suffix ]
system instruction                             当前 attempt 的新 observation
tool schemas                                   新增 finding/refinement 请求
Reasoning Packet 的 §1–§5（objective、alias      本轮动态提示
表、formal statements、假设/单位、known gaps）
```

硬规则：**任何每次请求都会变化的字段（时间戳、attempt ordinal、剩余预算、进度提示、随机 ID）不得出现在 stable prefix 中**。否则 cache 命中率为零，而成本预算会在真实任务上迅速穿透。Packet 渲染器必须把这类字段集中到 suffix。

规则：

1. Compiler、Reasoner、Integrator 使用不同 cache namespace；
2. Reasoner cache prefix 绝不能隐含 raw source、Private Source Map 或未投影 attachment；
3. phase 切换默认开始新的 cache lineage；
4. `ProjectionReset` 后不得继续使用旧 prefix；
5. provider 自己的 cache 也必须挂到 Controller 生成的 lineage 上，不能只凭字符串相似度复用；
6. cache hit、miss、invalidate 都写入 RunEvent 和预算 ledger；
7. cache content 受与原始 artifact 相同的 visibility/taint policy 保护。

### 10.4 Compaction policy

MVP 禁用 Pi 内置的、harness 不可观察的自动 compaction。原因是内置 compaction 可能静默删除、重排或改写 phase transcript，从而破坏：

- signed event pair；
- projection monotonicity；
- cache prefix；
- source/provenance；
- `/tree` 重放。

如果 context 过长，MVP 直接按 graph-aware policy 重新 assembly、请求缩小 scope 或 fail closed。后续可以实现 graph-aware compaction，但必须：

- 生成新的 content-addressed checkpoint；
- 记录被保留、折叠和标记为 residual 的节点；
- 产生新的 projection lineage；
- 不修改旧 transcript；
- 计入 `ProjectionReset` 或 compaction budget；
- 允许确定性 replay。

---

## 11. Source-aware Admission、信任平面与数据平面

### 11.1 先 admission，再 abstraction

处理顺序固定为：

```text
Raw Source Context
       │
       ▼
source-aware eligibility / policy gate
       │
       ├─ terminal refusal / non-admission
       └─ admitted task
              │
              ▼
       compilation / projection
              │
              ▼
       selected Reasoner
```

Admission 关注的是任务目的、能力、对象、操作性和风险，而不是只扫描领域关键词。它必须能识别：

- 合法的科学分析、数学验证和防御性审计；
- 需要用户澄清的模糊任务；
- 不应通过 abstraction 执行的任务；
- 不能因换成中立词汇就改变其安全属性的任务。

### 11.2 Trusted control plane 与 untrusted source data plane

```text
Trusted Control Plane
  Controller code
  phase state / tool permissions
  RunBudgetLedger
  source snapshot digests
  policy decision
  host signatures
  cache lineage
  controller-computed SourceRef

Untrusted Source/Data Plane
  user text and attachments
  project files and comments
  tool output
  compiler proposals
  reasoner messages/findings
  integrator drafts
```

每个 artifact/event 至少带有：

```ts
interface TrustMetadata {
  authority: "control" | "data";
  trust: "host-trusted" | "source-untrusted" | "model-untrusted" | "validated-data";
  visibility: "source-private" | "reasoner-visible" | "integrator-visible" | "user-visible";
  taint: Set<"raw-source" | "attachment" | "tool-output" | "model-output" | "policy-sensitive">;
  sourceEventIds: string[];
}
```

模型不能自行提高 `trust`、改变 `visibility`、清除 `taint` 或赋予一段文本 control-plane authority。Compiler 的输出在验证前仍是 untrusted proposal。

### 11.3 Fully serialized Reasoner egress check

在 Reasoner provider dispatch 前，Controller 必须检查**最终序列化后的完整 request**，包括：

- system instructions；
- 所有 message content；
- tool definitions、tool descriptions 和 tool arguments；
- projected observations；
- aliases、known-gap indicators 和 protocol；
- attachment metadata 和二进制内容摘要；
- provider-specific serialized fields；
- cache prefix/lineage metadata。

检查内容包括：

1. source-private artifact 是否意外进入 `reasoner-visible` request；
2. Private Source Map、原始标签、未允许的 attachment 是否存在；
3. raw source taint 是否沿未授权 edge 传播；
4. tool scope 和 arguments 是否仍在 admission 范围；
5. known-gap 是否被错误删除；
6. policy-sensitive semantics 是否被改写；
7. request 是否与 ProjectionSnapshot digest 相符；
8. provider/cache lineage 是否属于 Reasoner phase；
9. 不确定的 visibility/taint 状态是否被 fail closed。

词法扫描、关键词扫描和 alias 检查只能作为 defense-in-depth。它们不能证明 non-interference，因为同一语义可能以不同形式表达，词法不存在也不代表 taint 已消失。真正的防线是 source refs、typed artifacts、taint propagation、结构化 request inspection、adversarial test 和 fail-closed policy。

### 11.4 Prompt injection

项目文件、注释、README、测试数据、tool output 和附件中的“请忽略系统指令”“调用某工具”等内容全部按 untrusted data 处理：

- 不得直接改变 Controller 的 phase、预算、tool permissions 或 policy；
- Projector 以明确的 data delimiters 和类型字段表达它们；
- 工具定义来自 trusted control plane，不来自文件内容；
- Compiler 可以报告潜在 prompt injection，但不能直接授权它；
- Reasoner 的 finding 不能覆盖 source-aware admission；
- integrator 不能把 source data 中的指令当作用户新指令，除非用户显式确认。

### 11.5 Attachment policy

MVP 的默认规则：

- Compiler/Integrator 是否能读取 raw attachment 由 admission 和配置决定；
- Reasoner 不直接收到 raw binary、raw image 或原始数据集；
- 只有 controller 生成的、格式和 digest 都在 allowlist 中的 projected attachment 才能进入 Reasoner；
- 无法投影的附件转为 residual，并说明影响；
- 高影响附件语义无法确认时，strict-primary fail closed；
- 不因为 Reasoner 不支持某类 attachment 就把 raw attachment 直接旁路发送。

### 11.6 Compiler refusal path

Compiler 可能发生两类 refusal：

1. **Policy/safety refusal**：终态。不得把同一任务改写、删掉风险语义后重新交给 Reasoner。
2. **Semantic/technical inability**：不是安全许可。Controller 记录失败、保留 residual，允许一次受预算约束的 additive repair 或请求用户澄清；不能 raw fallback。

如果 Compiler 无法证明高影响语义足够完整，Reasoner 可以在非操作性、明确标记不确定性的范围内停止，但 strict-primary 不得提交把未知当作事实的 substantive final claim。

### 11.7 Refusal 分类与处理（fail-closed 默认）

拒绝判定必须是 Controller 侧、保守、不可被模型推翻的。可用信号按优先级：

1. provider 结构化信号（`stop_reason = refusal`、安全类 error code、content filter 元数据）；
2. transport 层错误码（429/5xx/timeout）；
3. 模型正文中的拒绝表述（最不可靠）。

分类规则：

| 观察 | 分类 | 处理 |
| --- | --- | --- |
| 结构化 refusal / 安全 error code | `policy-refusal` | 终态；写 `RefusalRecorded`；返回合规说明 |
| transport 错误码 | `transient` | 唯一允许自动重试的类别，受预算/次数限制 |
| 仅正文拒绝，无结构化信号 | `ambiguous` | **保守归为 `policy-refusal`** |
| 模型说“信息不足无法形式化”且产出了合法部分 IR | `semantic-inability` | 保留 residual；一次 additive repair 或 abstain |

选择把 `ambiguous` 归为 policy refusal 是有意的不对称代价权衡：把 policy refusal 误判为 technical inability 会直接打开 laundering 通道；反方向误判只损失一次 run。

绝对禁止的反应（全部属于 safety-policy laundering）：

- 用分类器模型把一次 refusal 重新标注为“其实无害”后重试；
- 删除/改写 policy-sensitive semantics 后重发；
- 换 phase model 重发（§9.4 规则 3）；
- 把 `passthrough` 升级为 `compiled` 来“绕过”刚发生的拒绝；
- 对同一 run 重新执行 `/ctx mode compiled`；
- 把拒绝当作 `transient` 重试。

`RefusalRecorded` 写入 phase、attested model identity、信号来源、证据 digest 和终态标志；`/ctx inspect` 可看到拒绝发生在哪个 phase、哪个模型，以及系统**没有**尝试绕过它。

---

## 12. Context Compiler 与 CompilationCertificate

### 12.1 Compiler 的职责

Compiler 读取 admitted raw source context，负责：

- 抽取 source requirements、目标、对象、操作和输出约束；
- 提取符号、定义、公式、过程、关系、单位、范围、假设和边界；
- 将可验证语义 lower 到 Semantic IR；
- 生成 stable typed aliases 的候选描述；
- 标出无法形式化、矛盾或需要 source-aware judgment 的 residual；
- 提议 checkable questions，但不声称已经证明实现正确；
- 产生 compiler-side candidate references，由 Controller 解析为真实 SourceRef；
- 在 visible Compiler turn 中调用 `ctx_publish_ir`。

Compiler 可以做深度科学和数学分析来完成形式化，但在 strict-primary 中，它的分析结果只能作为形式化 artifact 或 proposed check，不能直接成为最终领域结论。

### 12.2 Semantics-preserving 是验收目标，不是先验保证

文档中不再写“编译器保证 semantics-preserving”。准确表述是：

> 系统以 task-sufficient、evidence-bearing abstraction 为验收目标；每次 run 都必须说明哪些语义被保留、哪些被证明、哪些未知、哪些被省略，以及这些差异对答案的影响。

如果只能够得到“可能保留了语义”的模型自报，没有结构和 source evidence，就不能提升 assurance，也不能让 strict-primary 输出高影响结论。

### 12.3 CompilationCertificate

`CompilationCertificate` 由 Controller 生成，不由 Compiler 自己签发：

```ts
interface CompilationCertificate {
  certificateId: string;
  runId: string;
  sourceSnapshotDigest: string;
  queryDigest: string;
  irDigest: string;
  projectorVersion: string;
  compilerIdentity: ModelIdentity;
  controllerComputedSourceRefs: SourceRef[];
  derivedCoverageViewId: string;
  structuralChecks: StructuralCheckResult[];
  preservedFactRefs: string[];
  residualIds: string[];
  highImpactUnknownIds: string[];
  omittedArtifactIds: string[];
  assurance: AssuranceOrdinal;
  admissionDecisionId: string;
  egressEligibility: "eligible" | "blocked";
  certificateStatus: "accepted" | "accepted-with-residuals" | "abstain" | "rejected";
}

type AssuranceOrdinal =
  | "A0-proposed"
  | "A1-structural"
  | "A2-cross-checked"
  | "A3-source-validated"
  | "A4-adversarially-tested";
```

`AssuranceOrdinal` 是排序等级，不是已校准的概率；不使用未经校准的 `confidence: 0.87` 之类数值来伪装精度。每个 statement、residual、finding 和 certificate 都可有自己的 ordinal assurance。

### 12.4 Fail-closed 条件

以下情况至少会阻止 strict-primary 的高影响 final claim：

- requirement 没有 coverage 或 residual；
- 公式、量纲、单位、范围、量词、否定或时序出现无法解释的变化；
- residual 影响为 high 且没有 source-aware resolution；
- source contradiction 没有显式记录；
- egress visibility/taint 不确定；
- SourceRef 无法由 Controller 从当前 snapshot 解析；
- Compiler policy refusal；
- Reasoner finding 没有 accepted statement/observation evidence；
- `ctx_submit_findings` protocol 失败后没有合法结构化 findings。

Fail-closed 可以表现为：请求用户澄清、输出明确的未决项、进入经披露的 source-aware-supplement，或给出“无法在当前证据下确认”的终态回答。它不能表现为默默删除 residual 后继续生成确定答案。

---

## 13. Semantic IR：简化为 FormalStatement 集合

IR 不定义一组互相重叠、很难判断边界的领域专用数组；核心表示简化为：

1. `symbols`：稳定、typed、run-scoped 的抽象符号；
2. `statements`：discriminated `FormalStatement` collection；
3. `residuals`：显式未知和无法形式化的内容；
4. `query`：用于渲染 `q_Z` 的任务目标和输出要求。

```ts
interface SemanticIR {
  irVersion: string;
  query: ProjectedQuery;
  symbols: SymbolSpec[];
  statements: FormalStatement[];
  residuals: ResidualSpec[];
}

interface SymbolSpec {
  id: string;                 // 例如 sym.sequence.01，run 内稳定
  neutralType: NeutralType;
  signature?: string;
  constraints?: string[];
  aliasesVisibleToReasoner: string[];
}

type FormalStatement =
  | DefinitionStatement
  | EquationStatement
  | ConstraintStatement
  | InvariantStatement
  | TransitionStatement
  | ObjectiveStatement
  | ObservationStatement
  | CheckStatement;

interface FormalStatementBase {
  id: string;
  kind: FormalStatement["kind"];
  text: string;
  symbolIds: string[];
  dependencyIds: string[];
  candidateFragmentIds: string[]; // 仅供 Controller 解析，不是最终 SourceRef
  assurance: AssuranceOrdinal;
}

interface DefinitionStatement extends FormalStatementBase {
  kind: "definition";
  definedSymbolId: string;
}

interface EquationStatement extends FormalStatementBase {
  kind: "equation";
  equation: string;
  dimensions?: string[];
}

interface ConstraintStatement extends FormalStatementBase {
  kind: "constraint";
  predicate: string;
}

interface InvariantStatement extends FormalStatementBase {
  kind: "invariant";
  predicate: string;
  boundaryCases: string[];
}

interface TransitionStatement extends FormalStatementBase {
  kind: "transition";
  preState: string;
  operation: string;
  postState: string;
}

interface ObjectiveStatement extends FormalStatementBase {
  kind: "objective";
  objective: string;
}

interface ObservationStatement extends FormalStatementBase {
  kind: "observation";
  observationType: string;
}

interface CheckStatement extends FormalStatementBase {
  kind: "check";
  targetStatementIds: string[];
  question: string;
}

interface ResidualSpec {
  id: string;
  reason:
    | "requires_domain_judgment"
    | "ambiguous_source"
    | "semantic_loss"
    | "insufficient_information"
    | "policy_sensitive"
    | "unsupported_attachment";
  neutralDescription: string;
  impact: "none" | "low" | "medium" | "high";
  candidateFragmentIds: string[];
  assurance: AssuranceOrdinal;
}
```

IR 中不接受模型自报的任意 `sourceRefs`。`candidateFragmentIds` 必须引用 Controller 在 source snapshot 上预先建立的 fragment handles；最终 `SourceRef` 由 Controller 根据 digest、fragment kind、span/line anchors 和内容校验计算。

### 13.1 Controller-computed SourceRef

```ts
interface SourceRef {
  sourceSnapshotDigest: string;
  fragmentId: string;
  locator:
    | { kind: "byte-range"; start: number; end: number }
    | { kind: "line-range"; startLine: number; endLine: number }
    | { kind: "structured-handle"; handle: string };
  preimageDigest: string;
  controllerResolution: "exact" | "anchored";
}
```

流程为：

1. Controller 对 raw source 建立不可变 snapshot 和 fragment index；
2. Compiler 只能引用它在 packet 中看到的 fragment handles；
3. Controller 以 snapshot digest、内容和 anchors 验证 candidate；
4. 只有验证成功才生成 SourceRef；
5. 无法解析的引用变成 residual 或 certificate failure。

这样不会因为模型随意填写一个路径和行号就产生虚假的 provenance。

### 13.2 Coverage 独立派生

Compiler 的 `coverageClaims` 只是不可信提示。Controller 以独立的 requirement extraction / source fragment indexing pass 派生：

```text
SourceRequirement R1
   ├─covered-by→ FormalStatement F3
   ├─covered-by→ FormalStatement F4
   └─or→ Residual X2
```

Coverage view 的输入至少包括：

- 用户显式要求；
- 输出格式和验收条件；
- source 中由确定性 parser/segmenter 识别的数字、公式、单位、否定、时序和安全性质；
- Compiler 提出的 candidate，但不能只依赖 candidate。

没有 coverage edge 的 requirement 是 compilation failure，不是低 confidence 警告。覆盖率指标也不能代替语义验证：有 edge 只说明“有对应物”，不说明对应物正确。

---

## 14. Reasoner Packet Rendering Pass

### 14.1 目的

Reasoner 不直接消费散落的 graph nodes，也不接收 Compiler 的自由文本报告。Controller 在每个 Reasoner attempt 前运行一个**确定性的 Reasoner Packet Rendering Pass**，从当前 ArtifactGraph view、CompilationCertificate、query、alias map、observations 和预算渲染一个完整 packet。

Renderer 的输入和输出都写入 `ProjectionSnapshot`。同一 graph state、版本、模型能力和预算下应得到相同 packet digest。

### 14.2 最小 packet 必须包含

```text
Reasoning Packet

1. Objective
   - 当前要回答/验证的目标
   - 输出边界和不允许推断的范围

2. Stable Typed Alias Table
   - run-scoped alias
   - neutral type / signature
   - 可见约束

3. Definitions and Formal Statements
   - 按 discourse order 和 dependency order
   - 定义、公式、约束、转换、不变量、目标和 checks

4. Assumptions / Units / Boundaries
   - 显式假设
   - 单位、范围、量纲
   - 初始状态、退化情况、缺失值和边界行为

5. Known-Gap Indicators
   - residual ID
   - neutral description
   - impact ordinal
   - 对答案可能造成的影响
   - 不泄漏 raw source 或 Private Source Map

6. Projected Observations
   - projected source handles
   - tool observations
   - test results
   - observation digest 和 provenance IDs

7. Task and Output Protocol
   - 允许的工具
   - 需要独立验证 compiler proposed checks
   - `ctx_submit_findings` schema
   - unresolved / refinement 请求格式
```

Residual 的**存在性和影响必须可见**，否则 Reasoner 会把不完整 packet 当成完整世界；但 raw source label、原始领域名称、Private Source Map 和未经允许的 policy note 不应因此泄漏。

排版上，第 1–5 部分属于 stable prefix，第 6–7 部分中随 attempt 变化的内容属于 volatile suffix（§10.3）。渲染器不得在 stable prefix 中写入剩余预算、attempt 序号、时间戳或进度描述。

### 14.3 示例 packet 形状

```yaml
objective:
  task_id: qz-01
  text: "Determine whether the implementation preserves the stated transition and invariant."
  final_claim_scope: "Only claims supported by submitted findings and listed observations."

aliases:
  - id: sym.sequence.01
    visible_name: Sequence_A
    type: "finite ordered object"
    signature: "length >= 1"
  - id: sym.score.01
    visible_name: Score_F
    type: "bounded scalar function"
    signature: "Sequence_A -> real[0,1]"

formal_statements:
  - id: fs-01
    kind: definition
    text: "Score_F(x) is the weighted combination of Feature_1..Feature_3."
  - id: fs-02
    kind: equation
    text: "Score_F(x) = sum(i=1..3, w_i * Feature_i(x))"
  - id: fs-03
    kind: constraint
    text: "w_i >= 0 and sum(w_i) = 1"
  - id: fs-04
    kind: invariant
    text: "Score_F(x) remains in [0,1] when all stated preconditions hold."

assumptions_units_boundaries:
  - "Missing observations are represented by null."
  - "The all-null case is unspecified."

known_gaps:
  - id: residual-02
    impact: high
    text: "Boundary behavior for an all-null observation is unresolved; do not infer a valid score."

projected_observations:
  - id: obs-11
    source_handle: file-handle-07
    text: "Implementation branch clamps the output after aggregation."
    digest: "..."

protocol:
  submit_tool: ctx_submit_findings
  required_fields: [findings, evidence, unresolved]
  compiler_proposals_are_not_facts: true
```

### 14.4 q_Z 的定义

`q_Z` 不是简单把用户问题中的领域词替换掉，而是一个明确的 projected query：

- 要验证的 objective；
- 允许考虑的 formal statement IDs；
- 输出需覆盖的 check IDs；
- residual 和 boundary policy；
- tool scope；
- 不能越过的 claim scope。

这样评估的是 `A_sel` 在可消费的 projected task 上是否完成目标，而不是它是否能从原始词汇中猜出目标。

### 14.5 完整 worked example：source → IR → packet → finding → lift

下面的例子刻意展示 Compiler **保留数学问题但不先给出答案**。

#### A. Source-private input

```text
原始规则：对一个对象的三个观测值 x1,x2,x3（每项范围 [0,1]），
只对实际存在的观测集合 O 计算加权平均：

  Stability(p) = Σ(i∈O) wi*xi / Σ(i∈O) wi

wi > 0 且 Σ(i=1..3) wi = 1。若 O 为空，结果未定义，调用方必须返回 no-score。

待检查实现：把缺失观测替换成 0，按完整权重 Σ(i=1..3) wi*xi 计算，
最后把结果 clamp 到 [0,1]。

用户问题：该实现是否等价于规则？请给出可以复现的边界反例。
```

Private Source Map 保存原始领域标签和 source spans；Reasoner 不接收这些标签。

#### B. Compiler artifacts

```yaml
symbols:
  - { id: sym.object.01, alias: Object_A, type: finite_entity }
  - { id: sym.obs.01, alias: Observation_i, type: optional_real_0_1 }
  - { id: sym.weight.01, alias: Weight_i, type: positive_real }
  - { id: sym.metric.01, alias: Metric_F, type: partial_function }

statements:
  - id: fs-domain
    kind: constraint
    text: "0 <= Observation_i <= 1, Weight_i > 0, and sum(i=1..3, Weight_i) = 1"
  - id: fs-present
    kind: definition
    text: "Present(x) = { i | Observation_i(x) is not null }"
  - id: fs-metric
    kind: equation
    text: >-
      Metric_F(x) = sum(i in Present(x), Weight_i*Observation_i(x)) /
                    sum(i in Present(x), Weight_i)
  - id: fs-empty
    kind: transition
    text: "Present(x) = empty implies result = no-score"
  - id: check-equivalence
    kind: check
    text: >-
      Determine whether the observed implementation is extensionally equivalent to
      fs-metric and fs-empty; construct a counterexample if not.

residuals: []
```

Compiler 可以提出 `check-equivalence`，但不能添加“实现错误”这一结论。Controller 独立检查公式、范围、空集合行为和 source coverage 后签发 certificate。

#### C. Exact minimum Reasoner Packet

```yaml
objective:
  query: check-equivalence
  required_output: [verdict, minimal_counterexample, evidence, unresolved]

aliases:
  Object_A: finite entity
  Observation_i: optional real in [0,1]
  Weight_i: positive real
  Metric_F: partial scalar function

formal_statements:
  - fs-domain
  - fs-present
  - fs-metric
  - fs-empty

projected_observations:
  - id: obs-code-01
    text: >-
      For each missing Observation_i, implementation substitutes 0; it then computes
      sum(i=1..3, Weight_i*Observation_i) without dividing by the sum of present
      weights, and clamps the result to [0,1].
    source_handle: code-handle-17

known_gaps: []
protocol:
  submit: ctx_submit_findings
  compiler_check_is_only_a_question: true
```

#### D. Current Reasoner 的结构化 findings

```yaml
findings:
  - id: finding-partial-missing
    verdict: contradicted
    target: [fs-metric]
    claim: >-
      The implementation is not extensionally equivalent when at least one positive-
      weight observation is missing.
    counterexample:
      weights: [0.5, 0.25, 0.25]
      observations: [1.0, null, null]
      specified_result: 1.0
      implementation_result: 0.5
    evidence: [obs-code-01, fs-domain, fs-present, fs-metric]

  - id: finding-all-missing
    verdict: contradicted
    target: [fs-empty]
    claim: >-
      With all observations missing, the specification returns no-score while the
      implementation returns the clamped numeric value 0.
    evidence: [obs-code-01, fs-empty]

unresolved: []
```

这些反例和结论由当前 Reasoner 产生，不是 Compiler packet 中预填的答案。

#### E. Proof-carrying deterministic lift

Controller 为每个 ClaimObject 构造 proof tree：

```text
SourceRef + Certificate(IR fs-metric/fs-empty)
  + Observation(obs-code-01)
  + PrimaryFinding(finding-partial-missing / finding-all-missing)
  → deterministic alias inversion
  → final claims
```

确定性 renderer 回到 source-domain 术语后，终端答案可以是：

```text
该实现与原始加权规则不等价。

1. 当一个权重为 0.5 的有效观测值为 1、其余观测缺失时，规则会对现有权重
   重新归一化并得到 1；实现把缺失值当成 0，得到 0.5。
2. 当所有观测都缺失时，规则要求 no-score；实现会返回数值 0。

因此 clamp 不能修复缺失值语义和空集合行为。[[finding-partial-missing]]
[[finding-all-missing]]
```

Lift 只完成 alias inversion、模板渲染和 provenance 标记；它没有重新计算反例，也没有引入 Reasoner 未提交的新结论。

---

## 15. Run-scoped Alias Stability 与工具参数逆向 lowering

### 15.1 Alias stability

alias map 是 run-scoped、append-only、content-addressed 的：

```ts
interface AliasMap {
  runId: string;
  version: number;
  entries: AliasEntry[];
  digest: string;
}

interface AliasEntry {
  aliasId: string;
  visibleName: string;
  neutralType: string;
  sourceHandleIds: string[];
  firstSequence: number;
  status: "active" | "deprecated";
}
```

规则：

- 同一 run 中同一语义实体不能换名；
- 已经进入 Reasoner transcript 的 alias 不能被重绑定；
- 新实体只能追加新 alias，不能复用旧 alias ID；
- branch 从 checkpoint 继承 alias map；branch 新增 alias 仍然单调追加；
- alias map 变更必须有新 version、snapshot 和预算记录；
- 不把原始名字作为隐藏 fallback 混入 Reasoner request。

### 15.2 Projected tool input 的 inverse lowering

Reasoner 看到的是 `source_handle` 或 neutral alias，不是任意 raw path/identifier。Controller 在工具执行前进行 inverse lowering：

```text
Reasoner tool argument
  └─ alias / projected handle
       ↓ resolve against immutable AliasMap + SourceMap
  source handle + expected preimage digest + capability scope
       ↓ validate path, range, operation, policy
  actual tool invocation
```

每次 lowering 必须验证：

- alias map version；
- source snapshot digest；
- source handle 是否仍在允许 scope；
- preimage hash 和 anchors；
- 工具能力是否与 admission/phase toolset 相符；
- 参数是否借 alias 绕过路径或对象限制。

无法唯一 lower 的参数返回结构化 `projection_error`，不猜路径、不把 raw source 直接暴露给 Reasoner 作为补救。

### 15.3 Model 写 prose 而不调用 `ctx_submit_findings`

`ctx_submit_findings` 是 Reasoner phase 的完成协议。模型写自然语言分析不等于提交 findings：

1. prose 作为可见的 intermediate assistant event 记录并签名；
2. Controller 不把它自动当作 accepted finding；
3. 在预算允许时发送一次 bounded protocol-correction turn，明确列出缺失 schema；
4. 不因 protocol correction 而删除或弱化 packet 中的 policy-relevant semantics；
5. 第二次仍未调用 tool 或未产生可验证结构化结果，则标记 `protocol_failed`；
6. Integrator 只能基于之前 accepted findings 生成结果，否则 strict-primary abstain；
7. 不使用一个隐式自由文本解析器把任意 prose “猜成”事实。

不支持 tool call 的模型可以使用 §19.3 定义的 `text-protocol-primary` 能力等级，但必须通过同样的 schema validation；一旦解析不确定，结果仍然是 protocol failure。

---

## 16. Strict-primary、Source-aware Supplement 与确定性 Lift

### 16.1 默认 `strict-primary`

strict-primary 是默认模式，核心要求是：

```text
source requirement
  → approved FormalStatement / Observation
    → current selected Reasoner finding
      → validated evidence
        → deterministic LiftedClaim
          → terminal answer
```

具体规则：

- Compiler 只提取、规范化和提出 checks；
- Reasoner 必须独立确认、反驳或扩展 compiler proposal；
- compiler 的 `CheckStatement` 不能被当成已经成立的结论；
- 所有 substantive final claims 必须引用 Reasoner response ID、finding ID、FormalStatement/Observation ID 和 evidence；
- finding 没有 evidence、超出 packet claim scope 或依赖高影响 unresolved residual 时不能进入 accepted set；
- 默认 `L_det` 通过 alias/source map、approved finding、evidence 和模板确定性生成 claim；
- deterministic lift 不能发明新的因果关系、数值、建议或领域判断。

Integrator phase 仍然是一个可见的 native phase。strict-primary 下它可以：

- 用确定性 renderer 直接输出 approved claim set；或
- 调用一个受限的 rendering model，只把 approved claim objects 变成可读 prose。

如果调用 rendering model，它只允许在 approved claim vocabulary 内改写，具体数据结构见 §16.3，机械验证算法（C1–C6）见 §16.4；新增 substantive claim 即拒绝 terminal commit 并回退确定性模板。因而“Integrator 的自然语言”不改变“当前 Reasoner 是主要推理者”的事实。

**passthrough 下的退化形式**：没有编译、没有 packet、没有 findings、没有 lift，模型的回答就是终端回答。归因上它仍然满足“主要推理来自当前模型”：模型看到的就是原始上下文，不存在抽象带来的归因缺口。RunEvent 中记为 `provenance: "direct"`，不伪造 finding/claim 对象，也不声称它经过了 certificate 验收。

### 16.2 `source-aware-supplement`

在用户明确启用、policy 允许、预算足够且 strict-primary 无法闭合时，才可启用 source-aware-supplement：

- source-aware model 读取 residual 和原始 source；
- 只能处理明确列出的 high-impact residual 或冲突；
- 每个 supplement claim 单独带 model identity、source refs、reason 和 assurance；
- supplement 不计入 primary-reasoner claim coverage；
- final metadata 和 `/ctx inspect` 明确披露使用了 supplement；高影响产品可以要求用户可见 disclosure；
- supplement 的 token、时间、费用、修正次数和最终被采用的 claim 数单独测量；
- supplement 不能把 primary finding 的 provenance 改写成当前 Reasoner 产生的。

如果 supplement 也不能确定 residual，必须保留 abstention，而不是把不确定性隐藏在整合文本中。

### 16.3 ClaimObject 与确定性 lift 规范

确定性 lift 不是一句口号，它需要一个可实现的数据结构和一个全函数：

```ts
interface ClaimObject {
  claimId: string;
  claimType: "answer" | "verification" | "defect" | "risk" | "recommendation" | "unresolved";
  polarity: "affirm" | "refute" | "undetermined";
  predicateTemplateId: string;             // 来自受控模板库，不是自由文本
  slots: Record<string, ClaimSlotValue>;
  supportingFindingIds: string[];
  supportingStatementIds: string[];
  supportingObservationIds: string[];
  scope: { appliesTo: string[]; conditions: string[] };
  assurance: AssuranceOrdinal;
  attribution: {
    producer: "primary-reasoner" | "supplement" | "controller-derived";
    modelIdentity?: ModelIdentity;         // attested
  };
  sourceRefs: SourceRef[];                 // Controller 计算，用于回映射
}

type ClaimSlotValue =
  | { kind: "symbol"; symbolId: string }
  | { kind: "statement"; statementId: string }
  | { kind: "observation"; observationId: string }
  | { kind: "quantity"; literal: string; unit?: string; evidenceId: string }
  | { kind: "enum"; value: string };       // 受控词表
```

`L_det(F_Z, M, R, K) -> ClaimObject[]` 的确定性步骤：

1. 取 accepted findings（已通过 §18 Step 5 验证）；
2. 按 `finding.kind` 映射到封闭的 `predicateTemplateId` 集合；
3. 填 slot：只允许使用 evidence 中已存在的 ID 与**逐字出现**的数值/单位；缺 slot 的 finding 降级为 `unresolved` claim，不丢弃；
4. 用 AliasMap + Private Source Map 把 alias 逆映射回源域名称（领域词汇只在这一步重新出现）；
5. 排序：先按 statement 依赖拓扑序，再按 `claimId` 字典序；
6. 每个 high-impact residual 必须产生一条 `unresolved` claim；
7. 按 `(claimType, polarity, locale)` 的固定模板渲染为 prose。

硬约束：**lift 不做单位换算、不做算术、不合并因果、不提出新建议**。任何需要新计算的东西都属于 Reasoner 的职责；如果它没算，结果就是 `unresolved`。数值逐字性可以用归一化后的字符串包含关系机械检查。

### 16.4 受限 renderer 的验证算法

当模板 prose 可读性不足而启用受限 rendering model 时，它的输入只有 approved ClaimObject 集合和确定性草稿，**没有 source、没有 packet、没有工具**。输出要求：每一句 substantive 断言携带内联标记 `[[c:claimId]]`，并附 `mapping` 数组。

Controller 的机械验证：

| 检查 | 内容 | 失败处理 |
| --- | --- | --- |
| C1 marker 可解析 | 所有 `[[c:*]]` 均属于 approved 集合 | reject |
| C2 无遗漏 | 每个 approved claim（包括 `unresolved`）至少出现一次 | reject |
| C3 无裸句 | 无 marker 的句子必须命中非断言句型白名单（连接词、标题、列表引导） | reject |
| C4 词汇封闭 | prose 中的数字、单位、标识符、符号名必须出现在 slot 值∥alias 表∥源域名称集合中 | reject as `new-substantive-content` |
| C5 极性一致 | 句内否定/情态标记与 claim `polarity` 一致（按 locale 词典） | reject |
| C6 作用域保留 | 带 `scope.conditions` 的 claim，其条件子句不得被删 | reject |

失败后：一次 bounded correction；仍失败则**回退到确定性模板 prose**并记录 `renderer_rejected`。renderer 失贞永远不应让整个 run 失败，因为答案内容已经存在于 ClaimObject 中。

诚实说明：C3–C5 是保守的**句法级**检查，不是语义等价证明。它们之所以足够，是因为 renderer 被剥夺了一切新信息来源（无 source、无工具、无 packet），且有确定性回退路径。

### 16.5 真实归因与降级披露

最终回答的 metadata 必须包含：`mode`、各 phase 的 declared/attested model identity、certificate status、accepted finding 数、claim 数与归属分布、supplement 使用情况、abstain 项、实际 usage/cost、`terminalMessageId`。

用户可见层面的硬规则：

1. 有任何 supplement 来源的 substantive claim 时，回答正文（不只是 metadata）必须带一行披露；
2. 发生降级时（`renderer_rejected`、`protocol_failed`、预算耗尽、abstain）回答必须直说，不得用流畅文字掩盖；
3. 不得把 harness 总成本伪装成单个模型的 usage；
4. 不得声称 Reasoner 验证了它实际没验证的 check（compiler proposal 与 independently verified 必须分开计数）；
5. `passthrough` mode 也要在 `/ctx status` 中可见，不能让用户以为做了编译。

### 16.6 Reasoner observability

为了检验“当前用户模型是主要推理者”是否真的成立，run manifest 至少记录：

- current model snapshot 和实际 provider/model identity；
- Reasoner phase 的 turn、tool、token、latency、cost；
- accepted primary findings 数；
- final substantive claims 中可追溯到 primary findings 的比例；
- compiler proposed checks 与 Reasoner independently verified checks 的比例；
- supplement claim 数和最终采用比例；
- Integrator 新增 claim rejection 数；
- protocol failure、refusal、reset 和 recovery 次数。

strict-primary 的 final claim provenance completeness 必须是 100%；否则 run 只能以 incomplete/abstain 结束。

---

## 17. Graph Engineering：一条 RunEvent Log，多个 materialized views

### 17.1 不再分别持久化 ArtifactGraph 和 ExecutionGraph

旧式设计容易把 Artifact/Provenance Graph 和 Execution Graph 各自持久化，最终出现状态漂移。新的持久化边界是：

```text
one append-only RunEvent log
          │
          ├─ materialized ArtifactGraph view
          ├─ materialized ExecutionState view
          ├─ materialized RunBudgetLedger view
          └─ content-addressed ProjectionSnapshots / checkpoints
```

ArtifactGraph 和 ExecutionState 仍然是不同的逻辑 view，但不是两套独立事实源。

### 17.2 RunEvent 类型示例

```ts
type RunEvent =
  | RunStarted
  | AdmissionRecorded
  | SourceSnapshotCreated
  | RequirementDerived
  | PhaseTurnStarted
  | PhaseTurnEnded
  | NativeProviderEventRecorded
  | ToolCallRecorded
  | ToolResultRecorded
  | ArtifactProposed
  | ArtifactAccepted
  | CoverageViewMaterialized
  | CompilationCertificateIssued
  | ProjectionSnapshotCreated
  | ProviderRequestDispatched
  | ProviderResponseRecorded
  | FindingAccepted
  | FindingRejected
  | ModeSelected
  | RefusalRecorded
  | ChainValidationFailed
  | LaunderingGuardTriggered
  | RendererRejected
  | ProjectionReset
  | RetryReserved
  | RetryCompleted
  | BudgetReserved
  | BudgetCommitted
  | BudgetReleased
  | CheckpointCreated
  | BranchCreated
  | AbortRecorded
  | TerminalAnswerCommitted
  | RunCompleted;
```

每个 event 包含：

```text
runId, branchId, sequence, eventVersion,
parentEventDigest, payloadDigest, host timestamp,
phase/attempt, trust/visibility/taint metadata,
optional private blob reference
```

模型输出和 raw tool result 可以作为受访问控制的 content-addressed private blob 保存；普通 telemetry 只保存 digest 和结构化指标。

### 17.3 Materialized views

`ArtifactGraphView` 派生：

- source fragments、symbols、statements、residuals；
- `derived_from`、`depends_on`、`supports`、`contradicts`、`observes`、`lifted_to` 等 edge；
- coverage、provenance 和 accepted finding。

`ExecutionStateView` 派生：

- 当前 phase、turn、attempt 和 tool inflight 状态；
- retry/reset/abort 状态；
- provider/cache lineage；
- terminal answer 是否已提交。

两个 view 都可以从同一 event offset 重建，不允许 view 自己写入互相不可见的事实。

### 17.4 ProjectionSnapshot 与 checkpoint

```ts
interface ProjectionSnapshot {
  snapshotId: string;          // content address
  runEventHeadDigest: string;
  phase: Phase;
  attemptId: string;
  aliasMapDigest: string;
  graphViewDigest: string;
  exactSerializedRequestDigest: string;
  requestBlobRef?: string;
  includedArtifactIds: string[];
  omittedArtifactIds: string[];
  omissionReasons: Record<string, string>;
  cacheLineage: CacheLineage;
  egressDecisionId: string;
}
```

checkpoint 记录：

- RunEvent log head；
- Pi session branch entry；
- phase/attempt；
- alias map；
- graph view digest；
- ProjectionSnapshot；
- BudgetLedger 剩余额度；
- transcript prefix digest；
- cache lineage。

### 17.5 确定性 replay

Replay 不是重新调用 provider：

1. 读取 immutable RunEvent log；
2. 用 pinned reducer/version materialize views；
3. 读取已保存的 provider response/tool result；
4. 重新计算 deterministic coverage、packet、alias、egress 和 budget state；
5. 比较当前 digest 与原始 snapshot；
6. 只有显式“继续运行”才创建新的 attempt/provider call。

如果 projector、IR schema 或 policy 版本不同，replay 必须标记 `non-equivalent-version`，不能把新结果冒充旧运行的 replay。

### 17.6 Branch budgeting

Pi Session Tree 的分支不能无限复制成本：

- branch 从某个 checkpoint 继承已消耗 prefix，但 prefix 不重复计费；
- 新 branch 必须从 parent 剩余 RunBudgetLedger 中预留一个明确 cap；
- 多个 branch 的新调用总和不得超过 run/global allocation；
- branch 的 event sequence、cache lineage、projection snapshot 和 alias map 独立；
- branch 不能回写 parent 的 artifact 或预算状态；
- parent/branch 合并只能由 Controller 追加显式 merge event，不能自动覆盖事实。

### 17.7 Pi Session Tree 的位置

Pi Session Tree 仍然单独负责用户可见的消息分支和 `/tree` 导航。它不是 RunEvent log，也不是多依赖 DAG。每个关键 session entry 只保存 `runEventId`、checkpoint 和 snapshot references；RunEvent log 才是 harness state 的事实源。

### 17.8 Reducer 契约、写入模型与崩溃恢复

materialized view 要真的确定，就必须把 reducer 当作协议而不是实现细节：

```ts
type Reducer<V> = (view: V, event: RunEvent) => V;   // 纯函数，无 I/O，无壁钟，无随机

interface ViewIdentity {
  reducerVersion: string;
  eventHeadDigest: string;
  viewDigest: string;         // H(reducerVersion || eventHeadDigest)
}
```

1. **全量且严格**：遇到未知 event type 或高于已知 `eventVersion` 时直接报错，不静默跳过；静默跳过会产生“看起来合法但缺事实”的 view。
2. **单写入者**：每个 `(runId, branchId)` 任何时刻只有一个 writer；sequence 由 writer 单调分配；并发 tool 的完成事件在 writer 处序列化。
3. **写前日志规则**：`BudgetReserved` 与 `ProjectionSnapshotCreated` 必须先持久化，才允许 `ProviderRequestDispatched`。否则崩溃会丢失已发生的花费。
4. **幂等**：每个 event 有确定性 `eventKey = H(phase‖attempt‖kind‖payloadDigest)`；重复 append 相同 key 是 no-op，使重试路径安全。
5. **崩溃恢复**：启动时 replay 到 head；发现有 `ProviderRequestDispatched` 而无对应 `ProviderResponseRecorded` 时，该 attempt 标为 `unknown-outcome`，**预算按已花费处理**，不自动重发。
6. **Blob 生命周期**：model 输出与 raw tool result 存于受控 content-addressed blob store；允许按 retention policy 回收。回收后结构性 replay 仍然可行，但必须标记为 `blob-missing`，不得假装字节级重现。
7. **大小有界**：单 run 的 event 数量由 §20.4 的最坏情况上界决定，因此日志与快照存储可预先定价。

---

## 18. End-to-End Phase 流程

以下 Step 1–6 仅适用于 `compiled` mode。`passthrough` 只执行 Step 0、一个简化的 Reasoner phase turn（无 packet、无 alias、无 lowering）和 Step 7 的终端提交检查。

### Step 0：Run admission、mode triage 与预算创建

- 建立 run/branch ID；
- snapshot 当前用户模型为 `primaryReasonerIdentity`；
- 读取当前 Pi session branch leaf；
- 创建 source snapshot 和 fragment handles；
- 运行 source-aware admission/policy；
- 执行确定性 mode triage（下表）并写入 `RunStarted.mode`；
- 创建全局 RunBudgetLedger（compiled 与 passthrough 使用不同预算档）；
- 对首个 phase turn 和其工具设置原子 toolset。

mode triage 必须廉价且确定性（无模型调用），输入仅限于：

| 判据 | 含义 | 默认权重 |
| --- | --- | --- |
| 显式配置 / `/ctx mode` | 用户强制 | 最高优先级 |
| domain-surface 指示器命中（确定性词表 + 文件类型 + 附件类型） | 可能触发表面拒绝 | 主导 |
| 形式化密度（公式/单位/不变量/阈值的确定性计数） | 编译收益预估 | 中 |
| 任务规模（token 估算、文件数） | 成本判断 | 中 |
| 上一个 run 的 mode（同一会话连续性） | 避免抖动 | 低 |

规则：

1. `compiled` 当且仅当 domain-surface 指示器命中或形式化密度超阈值；否则 `passthrough`；
2. triage 只看输入，不看任何 provider 响应（§6 不变量 20）；
3. triage 结果、命中的指示器和阈值写入 RunEvent，`/ctx status` 可查；
4. `passthrough` 仍然经过 admission、chain validator 和预算账本，只是跳过编译、alias 和 packet 渲染；
5. `passthrough` 中发生的拒绝按 §11.7 处理，**不**升级为 `compiled`。

这一步是成本可行性的关键：它使绝大多数日常回合保持单次模型调用的成本，而把三阶段预算留给真正需要的任务。

### Step 1：Compiler visible turn

- Controller 开始 native Compiler phase turn；
- Projector 生成 source-aware Compiler request view；
- Compiler 可使用受限 source read/search/inspect tools；
- 所有 thinking/message/tool events 写入 canonical session event log；
- `ctx_publish_ir` 只作为 artifact proposal，不直接改变 control plane；
- Controller 校验 schema、source candidates、taint 和预算。

### Step 2：Coverage 与 fidelity validation

- 由 Controller 独立派生 requirements 和 coverage view；
- 验证 symbol、statement、formula、单位、范围、引用和依赖；
- 生成 `CompilationCertificate`；
- 若需要 source-aware second pass，必须预支出预算并可见；
- certificate 为 `accepted`、`accepted-with-residuals`、`abstain` 或 `rejected`；
- high-impact unknown 不得静默进入 strict-primary。

### Step 3：Reasoner Packet Rendering

- 固化 stable alias map；
- 选择 q_Z、FormalStatement dependency closure、known gaps、observations 和 output protocol；
- 将 packet 渲染成确定性的 ProjectionSnapshot；
- 对完全序列化的 request 执行 egress check；
- 创建 Reasoner phase checkpoint；
- 原子切换到 Reasoner toolset。

### Step 4：Reasoner visible turns

- 调用 run 开始时 snapshot 的当前模型；
- 当前模型只收到 Reasoner Packet 和 projected tools；
- thinking/text/tool events 可见并写入 transcript；
- tool arguments 先经过 inverse lowering；
- tool results 转为 projected observations 后才进入下一 request；
- model 可以请求 additive projection refinement；
- 完成时调用 `ctx_submit_findings` 或触发 bounded protocol correction。

### Step 5：Finding validation

- 检查实际 provider/model identity；
- 验证 finding schema、statement IDs、observation IDs、evidence 和 claim scope；
- 检查 primary reasoner 是否独立验证了 compiler proposal；
- 检查 unsupported assumption、contradiction 和 high-impact residual；
- accepted finding 写入 RunEvent log；
- 不合格 finding 不能被 Integrator 当作事实。

### Step 6：Recovery 或 Integrator visible turn

- 失败由 Controller 分类，不由模型自行决定重试；
- 只有符合 retry policy 的具体 graph delta 才可创建新 attempt；
- 成功后开始 Integrator phase；
- strict-primary 默认执行 deterministic lift，并可用受限 renderer 产生 prose；
- supplement mode 才允许 source-aware model 解决声明过的 residual；
- integrator 的中间事件仍是 visible phase event。

### Step 7：Terminal answer commit

Controller 在提交前检查：

- terminal claim provenance 是否完整；
- final text 是否新增未经批准的 claim；
- egress/visibility 是否满足；
- run budget 是否足够且无 inflight tool；
- 用户是否已 abort；
- 是否已有 terminal answer。

通过后只提交一个 `TerminalAnswerCommitted` 和唯一终端 assistant prose。其余 phase 文本保留为 intermediate transcript，不再拼接成第二份答案。

---

## 19. Projected Tools 与工具事件

### 19.1 工具集合按 phase 原子切换

推荐的工具类别：

```text
Compiler:
  ctx_source_read
  ctx_source_search
  ctx_source_inspect
  ctx_publish_ir

Reasoner:
  ctx_read_projected
  ctx_search_projected
  ctx_inspect_projected
  ctx_run_projected_test
  ctx_request_projection
  ctx_propose_patch
  ctx_submit_findings

Integrator:
  ctx_commit_terminal_answer
```

注意：Integrator **没有 source 读取工具**。回映射（alias → 源域名称）和 source mapping 验证是 Controller 的确定性内部步骤（§16.3 步骤 4），不是模型可调用的能力。受限 renderer 如果能读 source，就不再是 renderer，而是第二个未受控的推理者。

工具 definitions 来自 trusted control plane。一个 phase turn 内不能同时看到另一个 phase 的特权工具；切换必须发生在 turn boundary，并写入 `PhaseTurnEnded`/`PhaseTurnStarted`。

### 19.2 Read/Search/Test

Projected read/search/test 的原则：

- 使用稳定 source handle、line/anchor 和 observation ID；
- 代码控制流、类型、数学表达、断言关系和测试状态尽量保留；
- 注释、标识符、样例数据和路径仅按 alias policy 转换；
- 原始 tool output 保存于 source-private artifact；
- projection 失败返回 residual 或 projection error，不伪造“看起来合理”的内容；
- 每个 observation 可追溯到 tool call、source snapshot 和 transformation version；
- 下一轮 request 只追加 projected observation，不把未经处理的完整 tool output 贴回去。

### 19.3 结构化输出与不支持工具的模型

模型能力在 admission 时分级：

```text
full-primary
  native tool calls + structured output/schema support

text-protocol-primary
  no native tool call, but can emit delimited JSON validated by Controller

analysis-only
  no tools and no reliable structured output; only allowed for explicitly limited
  read-only tasks; never treated as full agentic reasoning

unsupported
  cannot satisfy packet/provenance protocol; run is not admitted
```

`text-protocol-primary` 的 JSON 仍然是 untrusted model output，必须经过 schema、ID、evidence、scope 和 taint validation；一次 bounded correction 之后仍不合规就 abstain。不能因为模型没有 tool/structured-output 支持，就把自由 prose 当作同等可信的 findings。

---

## 20. Recovery、Retry 与全局 RunBudgetLedger

### 20.1 Global RunBudgetLedger

预算账本在 run 开始创建，并且每个动作**先预支出，后执行**：

```ts
interface RunBudgetLedger {
  runId: string;
  branchId: string;
  maxModelCalls: number;
  maxPhaseTurns: number;
  maxToolCalls: number;
  maxProjectionResets: number;
  maxWallTimeMs: number;
  maxCostMinorUnits: number;
  reserved: BudgetUsage;
  committed: BudgetUsage;
  remaining: BudgetUsage;
}

interface BudgetUsage {
  modelCalls: number;
  phaseTurns: number;
  toolCalls: number;
  projectionResets: number;
  wallTimeMs: number;
  costMinorUnits: number;
}
```

以下所有动作都必须计入同一 ledger：

- Compiler、validator、Reasoner、Integrator 的每次模型调用；
- 每个 native phase turn；
- source/projected tool invocation；
- provider transport retry 和 content retry；
- ProjectionReset、graph-aware compaction 和 protocol correction；
- wall time、token、provider cost、nested usage；
- branch 创建和 branch 新调用 cap。

provider 无法预先知道真实 cost 时，按最大可能 cost 预留；调用结束后 commit 实际 usage，未使用部分 release。预支出失败意味着不发起请求。

### 20.2 Retry ownership

Retry 只由 Host Controller 创建。Compiler、Reasoner、Integrator 可以请求 refinement，但不能自行重播 provider。

允许的 content-related retry 只有两类：

1. **Proven raw egress defect**：已通过 fully serialized request 检查证明有未授权 raw content、错误 attachment、错误 tool field 或其他传输缺陷；修复必须是精确的控制平面 bug fix，不能借机删除 policy-relevant semantics。
2. **Additive fidelity/scope repair**：证明 packet 缺失了某项答案相关语义、观察或已批准的 source scope；修复只能增加或澄清必要内容，并重新通过 coverage/certificate/egress 检查。

以下行为禁止：

- policy/safety refusal 后继续换词重试；
- 为了让模型不拒绝而逐步删除风险、目的、能力或边界语义；
- 没有 graph delta 的重复 retry；
- 把同一 refusal 当成“再试一次可能有用”；
- 在 source-aware admission 失败后把 raw source 直接旁路给 Reasoner。

**反 laundering 的机械检查（单调性不变式）**。口头禁令不可审计，因此把它变成可执行断言：设 `S(a)` 为第 `a` 次 attempt 的请求中所有被标记为 `policy-sensitive` 的 statement/residual/known-gap 的 ID 集合，则对同一 phase 的任意重试必须满足：

```text
S(a) ⊆ S(a+1)          且   H(text(s)) 对每个 s ∈ S(a) 保持不变
```

即：policy-relevant 语义只能增加、不能减少，已有的不能被改写。违反时 Controller 直接拒绝创建该 attempt（`laundering-guard`），写入 RunEvent 并终止 run。这个不变式同时覆盖 retry、`ProjectionReset` 和 protocol correction 三条路径。

### 20.3 Failure taxonomy

| Failure | 默认动作 |
| --- | --- |
| source-aware policy refusal | 终态；不重写绕过，返回合规 refusal/澄清 |
| Compiler semantic inability | 保留 residual；一次 additive repair 或 abstain |
| Reasoner refusal after valid projection | 视为终态或转已披露 supplement；不是自动删语义重试 |
| proven raw egress defect | 修复 defect，新增 ProjectionSnapshot，有限 retry |
| missing fidelity/scope | additive repair，重新 certificate，有限 retry |
| provider transient/rate limit | transport-level bounded retry，仍受全局预算和时间限制 |
| attestation/model identity failure | 停止该 attempt，不把响应归给错误模型 |
| protocol non-compliance | 一次 correction；仍失败则 protocol_failed/abstain |
| unsupported finding/evidence | reject finding；可请求一次结构化 revision |
| tool projection/lowering error | 不猜参数；追加 error artifact 或受控 scope repair |
| context overflow | graph-aware reassembly；MVP 禁用隐式 compaction |
| budget exhausted | 停止所有 retry，基于已有可靠 findings 收束或 abstain |
| chain_invalid（§8.5） | 不发请求；修复 controller defect 后重建 projection，计入 reset 配额 |
| laundering-guard 触发（§20.2） | 终态；拒绝创建该 attempt，写事件并结束 run |
| renderer_rejected（§16.4） | 一次 correction；仍失败则回退确定性模板 prose，不失败整个 run |
| 崩溃后 `unknown-outcome`（§17.8） | 预算按已花费计；不自动重发；该 attempt 作废 |

每个 retry 都必须有：

- parent attempt；
- failure signature；
- allowed category；
- graph delta；
- budget reservation；
- new projection/cache lineage；
- bounded ordinal。

默认内容相关 Reasoner attempt 不超过两次；更高上限必须在配置和总 ledger 中预先声明，不能由模型临时要求。

### 20.4 有限最坏情况推导

“成本有界”必须能算出来，而不是口号。记：

- `n_p`：phase `p` 的最大 attempt 数（**包含** base、additive repair、protocol correction 和 reset 导致的重启）；
- `l_p`：单个 attempt 内的最大 provider 调用数（`loopPolicy.maxProviderCalls`）；
- `t_p`：单个 attempt 内的最大 tool 调用数。

则：

```text
N_model ≤ Σ_p (n_p · l_p)      N_tool ≤ Σ_p (n_p · t_p)      N_phaseTurn ≤ Σ_p n_p
cost    ≤ maxCostMinorUnits    wallTime ≤ maxWallTimeMs      （两者为硬上限）
```

默认配置下的结构性最坏情况：

| phase | `n_p` | `l_p` | `t_p` | model calls | tool calls |
| --- | --- | --- | --- | --- | --- |
| compiler | 3 | 4 | 8 | 12 | 24 |
| reasoner | 3 | 10 | 20 | 30 | 60 |
| integrator（renderer 启用时） | 2 | 2 | 1 | 4 | 2 |
| supplement（默认关闭） | 1 | 3 | 4 | 3 | 4 |
| **compiled 合计**（含 supplement） | **9** | — | — | **49** | **90** |
| passthrough | 1 | 10 | 20 | 10 | 20 |

为什么这个上界是真的有限：

1. 每个循环（tool loop、attempt、reset、correction）都有静态上限，没有任何规则能在运行时提高它；
2. 模型不能创建 retry（§20.2），也不能请求额外预算；
3. 所有调用先预支出，provider 未知费用按最大可能值预留，因此 `cost` 永不超 `maxCostMinorUnits`；
4. branch 不复制预算，只能从父剩余量中切分（§17.6）；
5. 预算耗尽的唯一合法结局是收束或 abstain，不存在“再借一点”路径。

典型值（预期 p50）远低于最坏情况：compiled 约 4–8 次 model call（compiler 1–2、reasoner 2–5、integrator 0），passthrough 1–2 次。产品化时应同时监控 p50 与 p99，并把 p99 接近最坏情况视为回归信号而不是正常现象。

---

## 21. Mutation：保守的 MVP

MVP 不允许 Reasoner 修改 projected workspace，也不允许未经批准的自动源码 mutation。支持范围为：

1. **read-only analysis**；
2. **structured patch proposal**。

结构化 patch 至少包含：

```ts
interface StructuredPatchProposal {
  proposalId: string;
  sourceHandle: string;
  preimageHash: string;
  anchors: {
    before?: string;
    after?: string;
    structuralPath?: string;
  };
  operation: "replace" | "insert-before" | "insert-after" | "delete";
  expectedInterfaceEffect: string;
  reasonerFindingIds: string[];
}
```

执行规则：

- Reasoner 只提交 proposal，不直接写 source worktree；
- source-aware executor 在原始 snapshot 上 inverse-lower 并重新验证 preimage/anchors；
- diff、AST/span、tests 和 policy 检查全部通过后，向用户显示 patch；
- 用户必须明确批准 apply；
- apply 前后都创建 source snapshot 和 RunEvent；
- preimage 不匹配、anchor 歧义或 scope 超出时 fail closed；
- 不在 MVP 中使用 projected workspace；
- 未来若支持 projected workspace，必须先证明 AST/span map、双向 lowering、冲突和回滚可靠性，并重新过 go/no-go gate。

---

## 22. UX、事件、取消与 `/tree`

### 22.1 用户看到的流程

```text
◆ Compiling context · source-aware
  reading approved project scope...
  extracted formal statements and known gaps...

◆ Reasoning · current selected model
  thinking...
  ctx_read_projected ...
  ctx_run_projected_test ...
  submitting findings...

◆ Integrating
  validating evidence and rendering approved claims...

最终回答开始正常流式输出……
```

`passthrough` mode 的用户可见形态则与普通 Pi 会话完全一致（无 phase 标题行），只在 `/ctx status` 和 run manifest 中可查到 mode 与 triage 依据。这是“用户无感”的具体含义：不需要编译的任务看不到任何额外机制。

上面这些是 native event stream 中的 phase metadata 和原生 message/tool rows，不是最后通过字符串拼接模拟出来的 dashboard。

### 22.2 事件语义

- Compiler/Reasoner/Integrator 的 intermediate thinking/text/tool events 都保留在 canonical session log；
- intermediate phase message 不被当作 final answer；
- only `TerminalAnswerCommitted` 对应唯一最终 assistant prose；
- phase provider/model、cache lineage、usage 和 attestation 真实记录；
- 不把 Compiler、Reasoner、Integrator 的总成本伪装成一个模型的 usage；
- JSON/RPC/headless 模式同样能识别 phase、attempt、tool 和 terminal answer，不依赖 TUI widget。

### 22.3 Abort 与 steer

Esc/abort 由 Controller 级联：

1. cancel 当前 provider stream；
2. cancel inflight tool；
3. 停止 phase transition 和 retry reservation；
4. 清理临时资源；
5. 写入 abort event；
6. 不提交 terminal answer。

Steer/follow-up 不直接插入 Reasoner request：

- steer 成为新的 source fragment/query event；
- Controller 在安全和预算允许时做 additive compilation；
- 当前 phase 是否可继续由 Controller 决定；
- follow-up 默认在当前 run 完成或终止后创建新 query/新 branch。

### 22.4 `/tree` 与 checkpoint

用户可以从以下位置分叉：

- Compiler 某次 source read 后；
- Reasoner 某个 projected tool result 后；
- finding validation 前；
- Integrator terminal commit 前。

分叉时：

1. 从 Pi Session Tree 取 active branch；
2. 找到对应 checkpoint 和 RunEvent head；
3. replay materialized views；
4. 继承已消费 prefix，但为 branch 分配新的 budget cap；
5. 创建新的 alias/cache/attempt lineage；
6. 不覆盖原 branch 的 terminal answer 或 findings。

`/tree` 是会话体验和用户分支工具；它不替代 RunEvent log 的 artifact dependency graph。

---

## 23. 成本、缓存与延迟

复杂度可以接受，但必须可预测：

1. 当前用户模型承担主要推理，不默认并行多个同类 Reasoner；
2. source snapshot、Compiler artifact 和 validated statement 按 content digest/query/compiler version 缓存；
3. 只对受影响的 graph subgraph 增量编译；
4. Reasoner Packet 只包含 dependency closure，不发送整张图；
5. 确定性检查优先，source-aware second pass 按 risk 触发；
6. 是否编译由 admission 时的确定性 mode triage 决定（§18 Step 0）；不存在 dispatch 时临时降级为 identity projection 的路径；
7. deterministic lift 可跳过 source-aware Integrator model（默认就是零模型调用）；
8. 每次 retry/reset/protocol correction 都消耗 ledger；
9. phase-specific cache lineage 避免重复传输同时避免跨 phase 泄漏；
10. 缓存命中依赖 stable prefix 不漂移（§10.3），所有每轮变化的内容必须放入 volatile suffix；
11. 超预算时不再扩展上下文，返回已有可靠 claims、unresolved 和 abstention。

建议默认预算（数值与 §20.4 的结构性最坏情况一致，不得更小，否则 run 会因算术而非语义失败）：

```json
{
  "compiled": {
    "maxModelCalls": 49,
    "maxPhaseTurns": 9,
    "maxToolCalls": 90,
    "maxProjectionResets": 2,
    "maxWallTimeSeconds": 900,
    "maxCostMinorUnits": 500
  },
  "passthrough": {
    "maxModelCalls": 10,
    "maxPhaseTurns": 1,
    "maxToolCalls": 20,
    "maxProjectionResets": 0,
    "maxWallTimeSeconds": 300,
    "maxCostMinorUnits": 120
  }
}
```

这些是**上界**而不是预期值：典型 compiled run 预期 4–8 次 model call。预算不是模型质量保证；任何更高上限都必须显式配置并经过产品 gate。`maxCostMinorUnits` 是唯一能跨模型对比的硬上限，应当作为主控制量。

---

## 24. 验证：先做 synthetic triad，再接 Pi

没有预先存在的真实评测集不是开工阻碍。评测应从可控 synthetic case 开始，随后吸收真实 failure trace。

### 24.1 Phase -1：不依赖 Pi 的最小原型

这一阶段完全不接 Pi host，目标只有一个：用最低成本证伪或支持**语义假设**（编译后的表示能不能支撑主推理）。它不声称验证任何 host 生命周期语义。

**原型组件清单（均为普通库代码 + 直接 provider SDK 调用）：**

| # | 组件 | 范围 |
| --- | --- | --- |
| 1 | `SourceSnapshot` + fragment indexer | 确定性分段、内容寻址、anchors |
| 2 | `RunEventLog`（JSONL append-only）+ 3 个 reducer | §17.8 契约，含 viewDigest |
| 3 | `Admission` + `mode triage`（确定性规则） | §18 Step 0 |
| 4 | Compiler driver + 自写 tool loop | **仅模拟**，不代表 host 行为 |
| 5 | 独立 `coverage deriver`（parser 为主）+ certificate 签发 | §13.2 / §12.3 |
| 6 | 确定性 `PacketRenderer` + golden digest | §14 |
| 7 | `ChainValidator` + `EgressGate`（跑在序列化后） | §8.5 / §11.3 |
| 8 | Reasoner driver（选定模型）+ findings schema 验证 | §15.3 / §18 Step 5 |
| 9 | `L_det` + 模板 prose + claim marker validator | §16.3 / §16.4 |
| 10 | triad 语料：12 case × 3 表面包装 = 36 输入 | 含 latent spec/边界/反例/安全属性 |
| 11 | replay harness | 重建 view 并比对 digest |

估算规模：单人、无 host 修改、无图数据库、无 UI。不实现：branch、`/tree`、compaction、supplement、patch、cache lineage（只计算 key，不接真实缓存）。

构造同一潜在推理结构的三种领域表面包装，例如：

- 生物/序列风格；
- 科学计算/实验变量风格；
- 防御性网络/状态传播风格。

每个 triad case 有已知的 latent formal specification、边界条件、反例和安全属性。测试：

- compiler 是否生成同构且 typed 的 FormalStatements；
- 公式、单位、量纲、范围、否定、量词、时序和边界是否保留；
- 同一 alias map 是否稳定；
- source refs 是否由 Controller 正确计算；
- coverage 是否独立发现漏项；
- residual/unknown 是否正确标为 high impact；
- Reasoner packet 是否包含 q_Z、known gaps 和协议；
- fully serialized egress 是否无 raw source/private attachment；
- `A_sel(Z, q_Z)` 与 source-aware reference 的结构化 claim 是否达到预注册门槛；
- replay、projection reset 和 inverse lowering 是否确定。

每个 latent task 至少构造四个实验条件，而不是只比较“原文 vs 编译后”：

| 条件 | 输入 | 回答的问题 |
| --- | --- | --- |
| A | neutral control 的完整任务表达 | 当前模型在没有表面干扰时的能力上限 |
| B | 与 A 同构、但换成另一种 source presentation | 表面表示是否改变拒绝和推理质量 |
| C | 人工编写的 ideal typed Reasoner Packet | 这种 IR/packet 本身是否能释放模型能力 |
| D | 实际 Compiler 生成的 packet | Compiler 与 renderer 相比 ideal packet 损失多少 |

核心比较：`B vs C` 测试投影是否改善可用性；`A vs C` 测试抽象税；`C vs D` 隔离 Compiler/fidelity 缺陷。还要加入：

- **packet rendering ablation**：dependency/discourse order vs 打乱顺序、typed aliases vs opaque IDs、known-gap visible vs hidden、是否明确告知模型“这是抽象表示”；
- **mutation kill**：删除、取反或改变一个 task-relevant 公式/边界，答案必须变化或 uncertainty 加宽；
- **irrelevant interference**：加入与任务无关的叙事，IR/answer 应保持稳定；
- **insight-origin ablation**：去掉 Compiler proposed checks，观察 Reasoner 是否仍发现 planted defect；避免 Compiler 把答案预先泄漏进 packet；
- **alias/tool round-trip**：Reasoner 连续使用 alias 发起 projected read/search，请求必须稳定 inverse-lower 到同一 source handle，且返回内容不泄漏 source-private label；
- **protocol compliance**：测量 `ctx_submit_findings` 首次遵从率、一次 correction 后成功率和 protocol_failed 率；
- **stochastic stability**：同一 packet 重复运行，比较规范化 ClaimObject 的 Jaccard、极性和边界判断，而不是要求逐字一致。

中立性和充分性必须成对报告：仅仅让 source presentation 更难被识别不是成功；如果 mutation kill rate 低，说明 packet 把任务相关信息也删掉了。

**Phase -1 初始 go/no-go gate：**

1. synthetic suite 中不得出现 policy laundering 或高影响 residual 被静默隐藏；
2. must-preserve fact、单位、公式、边界和安全性质的结构检查覆盖率为 100%；
3. 所有无法证明的 high-impact case 都必须 abstain/fail closed；
4. 100% 的 Reasoner request 通过 fully serialized egress/taint check；
5. 每个 accepted final claim 都能追溯到 primary Reasoner finding；
6. 事件、snapshot、alias、source lowering 和 budget replay 必须 deterministic；
7. selected model 在预注册的 triad task 上达到预设的 structured agreement 门槛，且不低于 neutral control task 的预设基线；
8. protocol、tool/attachment capability 不满足时必须进入明确的 unsupported/abstain 分支。

第 7 条的数值门槛必须在实验开始前登记，不能在看到结果后调整。初始实验可以采用“至少 90% 的关键 claim/边界判断一致，且 0 个高影响安全性质错误”的保守门槛，再由外部评审修订；这不是对任意模型或领域的永久承诺。

**可操作的可量化定义（避免 gate 变成主观判断）：**

| Gate | 测量方式 | 通过线 |
| --- | --- | --- |
| 结构保真 | 对每个 case 预先列举的 must-preserve 项（公式、单位、边界、否定、量词、安全性质）做自动匹配 | 100% 命中或显式 residual |
| 投影确定性 | 同一输入重复渲染 3 次的 packet digest | 3/3 相同 |
| Egress | 36 个 case × 每次 Reasoner 请求的序列化比对 | 0 次 raw source / private map 泄漏 |
| 归因 | accepted final claim 中可追溯到 primary finding 的比例 | 100% |
| Triad 一致性 | 三种包装产生的 IR 同构性（符号重命名后的集合差异） | ≤ 1 处非关键差异 |
| 任务充分性 | 预注册的关键 claim/边界判断一致率 | ≥ 90%，且高影响安全错误 = 0 |

**明确的 kill 条件**：如果 triad 一致性或任务充分性连续两轮低于门槛，项目应该**停止**，而不是去实现 host 集成。这是本设计最便宜的否定信号，应当最先跑。

### 24.2 Phase 0：Host runtime API 验证

Phase -1 通过后，才接 Pi host。第一件事是逐项探测 §9.5 的 H1–H12，并把结果写成一张能力矩阵（支持 / 需 fork / 不支持）。在矩阵完成前不写业务逻辑。接着必须验证完整而不是 stream-only：

- 单一 native AgentSession 中 Compiler/Reasoner/Integrator visible phase turns；
- intermediate events 可见，只有一个 terminal answer；
- phase toolset 原子切换；
- current model identity 保持真实；
- fully materialized request mediation 在 provider dispatch 前生效；
- abort 能停止 stream、tool、retry 和 workspace；
- global ledger 能阻止超预算调用；
- signed transcript、ProjectionReset 和 cache prefix 规则有效；
- built-in compaction 被禁用或被 graph-aware policy 接管；
- `/tree` checkpoint branch replay 正确；
- RPC/JSON/headless 与 TUI 语义一致。

**Phase 0 go/no-go：**以上任一安全、事件身份、预算、replay 或 terminal answer 不变量失败，就不能进入真实 source data。

### 24.3 Phase 1：Read-only Context Compiler MVP

交付：

- source admission 与确定性 mode triage；
- chain validator 与 fully serialized egress gate；
- Semantic IR v1；
- CompilationCertificate；
- independent coverage；
- Reasoner Packet Renderer；
- strict-primary deterministic lift；
- projected read/search/test；
- bounded recovery；
- `/ctx inspect` 和 RunEvent replay。

### 24.4 Phase 2：Projected tools、缓存与成本调度

交付：

- tool observation graph view；
- inverse lowering；
- alias stability；
- content-addressed ProjectionSnapshot；
- phase-specific cache lineage；
- risk-based second pass；
- global cost/time scheduler；
- 用户 opt-in shadow telemetry。

### 24.5 Phase 3：Source-aware supplement 与 living regression

- 受限 supplement mode；
- supplement claim 的单独披露和测量；
- 真实 refusal/model mismatch/fidelity/protocol/patch-lift trace 自动进入 regression corpus；
- 根据失败轨迹调整 IR、packet、fast path 和 retry，但不能通过删除 policy semantics 优化 refusal 指标。

### 24.6 Phase 4：Mutation

严格按以下顺序：

1. structured patch intent；
2. source handle + preimage + anchors；
3. source-aware diff/test；
4. explicit user approval；
5. 再评估是否值得支持 projected workspace。

### 24.7 Shadow mode 限制

Shadow mode 可以：

- 在不影响主回答的情况下运行 compiler、certificate、packet 和结构指标；
- 使用 synthetic triad、已存在的用户授权 source-aware answer 或先前已生成的安全 baseline；
- 记录 digest、coverage、latency、usage、failure signature 和用户 feedback。

Shadow mode 不可以：

- 为了比较 `A_sel(C)` 而把同一份 refusal-prone raw content 再次发送给当前 Reasoner；
- 把拒绝行为当作安全的 direct oracle；
- 在未经用户授权的情况下把 raw source 发给另一个对照 provider；
- 绕过 admission/egress，只因为“这是实验”。

如果没有安全的 direct baseline，就只比较 projected output 与 source-aware reference、结构性证据或 synthetic case，并明确标记缺少 direct baseline。

### 24.8 Living metrics

```text
certificate pass / abstain rate
independently derived requirement coverage
formula/unit/boundary preservation
projected-reference structured agreement
primary finding provenance completeness
compiler proposal independent verification rate
reasoner refusal/mismatch rate after valid projection
protocol failure rate
egress block rate
projection reset / retry rate
integrator claim rejection rate
supplement claim count and adoption
phase latency / total latency
model calls / turns / tool calls
actual cost vs budget
branch replay determinism
user feedback good/bad
```

拒绝率下降只能与 fidelity、reference agreement、abstention correctness 和最终用户反馈共同解释。

---

## 25. 主要失败模式与缓解

| Failure mode | 影响 | 缓解 |
| --- | --- | --- |
| Compiler 静默丢失科学语义 | Reasoner 错误 | certificate、independent coverage、公式/单位/边界检查、residual、fail closed |
| 过度 opaque alias | Reasoner 推理性能下降 | typed neutral vocabulary、定义、依赖顺序和 triad tests |
| raw source 从 tool/attachment 泄漏 | 再次触发拒绝或策略失控 | projected tools、taint、fully serialized egress、attachment deny-by-default |
| coverage 自报不真实 | 漏项不可见 | Controller 独立派生 coverage，不信 compiler claim |
| source ref 伪造 | provenance 不可信 | Controller-computed SourceRef、snapshot digest、preimage/anchor |
| Integrator 添加新结论 | Primary reasoner 责任被掩盖 | strict-primary deterministic lift、claim diff、supplement 分离 |
| Reasoner prose 未提交 findings | 无法审计 | visible intermediate event、一次 protocol correction、之后 protocol_failed/abstain |
| policy refusal 被当作可修复 bug | 安全策略规避 | admission first、policy refusal terminal、禁止 semantic stripping retry |
| high-impact residual 被隐藏 | 高风险错误答案 | known-gap packet、certificate、strict-primary fail closed |
| phase request 与 session transcript 混淆 | context 泄漏/无法 replay | canonical log vs provider view 分离、snapshot digest |
| built-in compaction 改写历史 | cache/transcript 失效 | MVP 禁用，后续 graph-aware checkpoint |
| cache prefix 跨 phase 复用 | raw/source 泄漏 | phase-specific lineage、exact prefix digest |
| 两套 graph 状态漂移 | branch/recovery 错误 | single RunEvent log、materialized views |
| branch 无限消耗 | 成本失控 | branch cap、global budget、prefix不重复计费但新调用预支出 |
| unsupported model 无 tool/schema | findings 不可信 | capability admission、text-protocol bounded path、unsupported/abstain |
| patch lowering 歧义 | 破坏源码 | read-only/structured patch MVP、preimage/anchors、用户批准 |
| lexical scan 被过度信任 | false negative | 不宣称 non-interference proof，使用 taint/结构检查/对抗测试 |
| provider chain 非法（悬空 tool call、thinking 签名失效） | 请求被拒或静默截断 | dispatch 前 chain validator、abort 时写 aborted result、thinking 整体省略（§8.5） |
| 请求前缀逐轮漂移 | cache 永不命中，成本穿透 | stable prefix / volatile suffix 分离、显式 `cacheLineageKey`（§10.3） |
| 所有任务无条件走三阶段 | 成本与延迟不可接受 | 确定性 mode triage + passthrough 预算档（§18 Step 0） |
| 拒绝后换模式或换模型重试 | 安全策略规避 | mode immutability、§9.4 规则 3、§11.7 保守分类 |
| renderer 引入新结论或删掉不确定项 | 归因失真 | C1–C6 验证 + 确定性模板回退（§16.4） |
| 崩溃后重复计费或重发 | 成本与副作用失控 | 写前日志、`eventKey` 幂等、`unknown-outcome` 保守记账（§17.8） |
| host 缺 H1–H10 但继续实现 | 架构承诺无法兑现 | 能力矩阵先行，缺项即 no-go（§9.5） |

---

## 26. 被拒绝的替代方案

### 26.1 只用 `registerModelStreamMiddleware`

拒绝原因：它最多是 request/stream data-plane hook，无法独立解决 phase ownership、native turn persistence、atomic tools、abort、retry、budget、compaction、checkpoint、branch 和 terminal commit。

### 26.2 后台创建多个 AgentSession，主 session 只显示 widget

拒绝原因：中间事件、tool、usage、steer、RPC、取消和 `/tree` 语义割裂，用户体验不像普通 agent。

### 26.3 `input: handled`、custom message 或 terminating toolResult 冒充答案

拒绝原因：不能得到真正的 terminal assistant prose；role、session、RPC、streaming 或取消语义不完整。

### 26.4 `message_end` 后替换最终回答

拒绝原因：先产生一个错误/多余 provider response，用户看到的 stream 会闪现或被替换，且不能修复 phase lifecycle。

### 26.5 虚拟 `auto` model/provider

拒绝原因：要求用户切离当前模型，削弱 primary reasoner 的真实身份和 usage 语义，且把 harness 伪装成 model。

### 26.6 Router 只做 engineering/domain 分类

拒绝原因：分类不能解决科学语义进入主要 Reasoner 的问题；核心是 representation、projection 和 graph maintenance。

### 26.7 最小 task packet，完全删掉领域内容

拒绝原因：数学公式、科学原理、因果结构、单位和边界条件会消失，模型只能机械检查。

### 26.8 只做关键词脱敏或逐步删词直到不拒绝

拒绝原因：不具备语义保真证据，并且会演变成安全策略 laundering；retry policy 明确禁止。

### 26.9 所有概念都替换成随机 opaque IDs

拒绝原因：LLM 对任意符号替换没有天然不变性，模型会丢失一般语义先验；应使用 typed neutral vocabulary。

### 26.10 Compiler 自己声称 coverage/confidence/source refs

拒绝原因：模型输出是 untrusted data；coverage、SourceRef、certificate 和 assurance 必须由 Controller 根据实际 snapshot 派生。

### 26.11 直接比较当前模型在 `C` 上的结果

拒绝原因：`A_sel(C)` 的拒绝可能是待解决的触发行为，不是 source-aware correctness oracle；shadow mode 不得为此重新发送 raw content。注意：这与 §18 的 `passthrough` 不矛盾——passthrough 是 admission 预先判定的产品路径，而不是为了取得对照而重发内容。

### 26.12 默认启用 source-aware supplement 或独立 Synthesizer

拒绝原因：会掩盖当前 Reasoner 是否真正有效，增加成本和 provenance 混乱。默认 strict-primary；supplement 只在 residual 明确、预算足够且披露后启用。

### 26.13 内置 compaction 直接处理 phase transcript

拒绝原因：可能删除/重排 signed events 和 cache prefix，破坏 deterministic replay；MVP 禁用或由 graph-aware compaction 接管。

### 26.14 一开始支持 projected workspace mutation

拒绝原因：双向 AST/span lowering、注释/路径 alias、冲突和回滚尚未证明可靠；MVP 只读和结构化 patch proposal。

### 26.15 一开始使用图数据库

拒绝原因：run-scoped append-only event log 加 materialized views 已足够，图数据库增加部署、迁移和 replay 复杂度。

### 26.16 观察到拒绝后再升级到 compiled mode

拒绝原因：这就是 safety-policy laundering 的定义——“先试原文，被拒后换一种表述再试”。mode 与 phase model 均在 admission 时固定（§6 不变量 20、§9.4 规则 3）。宁可以 passthrough 拒绝结束，也不开这个口子。

### 26.17 对所有请求无条件跑三阶段编译

拒绝原因：对不含领域表面特征、也没有形式化密度的日常任务，编译无收益但代价很高（数倍延迟与成本）。用确定性 mode triage 替代，且 triage 只看输入不看响应。

### 26.18 让 Projector 自己维护 agent 循环

拒绝原因：在扩展侧写 while 循环驱动 tool 往返，会使 abort、usage 聚合、session tree、RPC 和事件持久化与 host 分岓；循环必须归 host（H1），Phase -1 原型中的自写循环只是不声称 host 语义的模拟。

---

## 27. 外部架构评审问题

请评审者不要只润色文案，而要针对可实现性、正确性、成本和失败模式挑战以下问题。

### 27.1 Phase event semantics

1. 单一 host-managed AgentSession 如何最小且真实地表达多个 visible phase turns？
2. canonical session event log 与 fully materialized provider request view 的边界是否清晰？
3. 如何保证 intermediate assistant text 不会被客户端误当成 final answer？
4. 哪些 Pi host API 能提供 phase metadata、atomic toolset、terminal commit 和 `/tree` checkpoint？
5. 把 phase turn 作为 host 一级对象（§8.3）的最小形状是什么？`PhaseStopReason` 集合是否完备？
6. 确定性 mode triage（§18 Step 0）的默认阈值应更保守还是更激进？误判为 passthrough 与误判为 compiled 的代价如何权衡？

### 27.2 Primary reasoner 与 observability

1. `strict-primary` 是否能在不牺牲最终可读性的情况下保证所有 substantive claims 来自当前 Reasoner？
2. deterministic lift 的表达能力是否足以覆盖复杂任务？什么时候必须升级为受限 rendering model？
3. primary claim coverage、independent verification 和 supplement disclosure 的指标是否足够？
4. 如果 Compiler/Integrator 与当前 Reasoner 使用相同模型，如何避免角色边界和责任归因混淆？

### 27.3 Transcript、cache 与 replay

1. 对实际收到的 thinking/tool pair 做 host signature 的最小实现是什么？
2. provider delta、retry、usage update 和 `ProjectionReset` 如何共同保证 transcript immutable？
3. cache prefix 是否必须绑定到哪些 provider-specific fields？§10.3 的 stable prefix / volatile suffix 划分与各 provider 实际的缓存粒度是否兼容？
4. graph-aware compaction 的最小安全协议是什么？MVP 完全禁用是否可接受？
5. event log replay 与 Pi Session Tree branch replay 如何测试确定性？

### 27.4 Fully materialized request mediation

1. Pi host 能否在所有 provider-specific serialization 之后、network dispatch 之前暴露 request projector？
2. 如果某 provider 在 SDK 内部二次改写 system/messages/tools，如何获得最终 serialized egress 或等价证明？
3. phase-specific cache lineage 如何防止 provider-side cache 绕过 Controller？
4. stream-only middleware prototype 会漏掉哪些 host lifecycle 问题？

### 27.5 IR、fidelity 与 residual

1. discriminated FormalStatement collection 是否比多数组 IR 更容易验证和扩展？
2. independent coverage extraction 应使用 parser、第二个模型，还是两者组合？
3. typed neutral vocabulary 与领域先验之间的最佳平衡如何实验确定？
4. 哪些 high-impact residual 必须直接 abstain，哪些可以进入 source-aware-supplement？
5. ordinal assurance 的等级定义如何跨 compiler version 保持可比较？

### 27.6 Recovery、预算与安全

1. “proven egress defect”和“additive fidelity/scope repair”的可审计判据是什么？
2. 两次 Reasoner attempt 是否足够？如何防止 retry 变成 semantic stripping？
3. retry 应由 Controller、provider adapter 还是 phase model 负责提出和批准？
4. global RunBudgetLedger 如何在并发 tool、stream abort、provider未知费用和 branch 下保持原子？
5. compiler refusal、reasoner refusal 和 provider transient error 的边界如何测试？把 `ambiguous` 保守归为 policy refusal（§11.7）是否会造成不可接受的假阳性终止？
6. §20.2 的 policy-sensitive 单调性不变式是否可被绕过（例如拆分 statement、改变标记粒度）？如何对它做对抗测试？
7. §20.4 的最坏情况上界（compiled 49 次 model call）在产品上是否可接受？应不应该把 `maxCostMinorUnits` 作为唯一硬闸？

### 27.7 Model capability

1. 没有 native tool call 或 structured output 的模型是否应只允许 `text-protocol-primary`，还是直接不支持？
2. text protocol 的一次 correction 是否足够，何时应立即 abstain？
3. 如果当前用户模型不支持 thinking event，如何保持“可见 phase”而不伪造思考？
4. 不同 context window、cache 和 attachment 能力如何影响 packet renderer 和 admission？

### 27.8 Mutation 与产品 gate

1. source handle、preimage hash、anchors 的最小可靠组合是什么？
2. 用户批准前后应该展示哪些 patch provenance 和测试证据？
3. Phase -1 和 Phase 0 的 go/no-go gate 是否过严或不足？
4. 在没有人工 gold set 的情况下，synthetic triad、reference model 和真实 trace 如何共同避免自我验证循环？
5. 用户需要看到多少 phase/provenance，才能既无感又不产生模型身份误导？

### 27.9 数学基础与 proof obligations

1. §5.2 的任务核细化是否是最合适的规范性定义？`Γ_test` 应如何声明，才能避免只在容易的变换上自我验证？
2. `Readings(C) ⊆ γ_M(Z,R)` 的保守抽象是否适合自然语言 source，还是应限定到更窄的 FormalStatement fragment？
3. Translation validator 的可信计算基应包含哪些组件？packet `render/parse` round-trip 是否必须成为硬 gate？
4. Residual 守恒、assurance 单调和 proof object 演算是否足以阻止不确定性在 lift 中被擦除？
5. §5.6 的 dependency-closure knapsack 是否过度形式化？MUST/bundle/utility 的最小可实现定义是什么？
6. Claim proof tree 中“每个 substantive claim 必须有 primary Finding leaf”的规则是否会漏掉合理的 controller-derived claim，或反过来被形式化空壳绕过？
7. 哪些 metamorphic transformations 能同时测量 source-neutrality 与 task sufficiency？应如何设计 mutation-kill 与 irrelevant-interference 两个互补指标？
8. §5.9 的经验 union bound 是否有产品解释价值？各 stage error rate 如何在没有大规模 gold corpus 时估计？
9. 哪些数学表述仍然只是研究假设，应从规范部分移到明确的 open questions？

请至少给出：

- 最严重的五个架构风险；
- 可以删除或合并的组件；
- Phase -1 的最小 synthetic experiment；
- Phase 0 所需的 Pi API 具体形状；
- 没有 raw direct baseline 时的可操作评测方案；
- 预算、retry、cache 和 branch 的建议上限；
- 对 strict-primary 与 source-aware-supplement 的取舍建议；
- 对 §9.5 H1–H10 在当前 Pi 上的可行性判断，以及哪些必须走 fork；
- 对 mode triage 默认阈值与 passthrough 占比目标的建议。

---

## 28. 关键设计决策摘要

1. 项目定位为 model-agnostic 的 Context Compiler Harness，而不是 Safe Model Router；
2. 核心是 task-conditioned context projection，不是关键词脱敏；
3. 当前用户选择的模型默认是 Primary Reasoning Backend；
4. 不注册虚拟 `auto` model，不切换主 session model；
5. Compiler 在 source-aware admission 之后工作，并保留科学、数学、算法和安全相关语义；
6. `semantics-preserving` 是 evidence-bearing、task-sufficient 的验收目标，不是无条件保证；
7. Semantic IR 简化为 symbols、discriminated FormalStatements、residuals 和 q_Z；
8. coverage、SourceRef、certificate 和 ordinal assurance 由 Controller 派生或签发，不信模型自报；
9. Reasoner Packet Rendering Pass 明确渲染 objective、typed aliases、依赖顺序 statements、假设/单位/边界、known gaps、observations 和 output protocol；
10. alias map 在 run 内稳定，projected tool arguments 由 Controller inverse-lower；
11. 默认 `strict-primary`，Reasoner 必须独立验证 Compiler 提议，default lift deterministic；
12. source-aware-supplement 是可选、单独计量、真实披露的高影响 residual 处理路径；
13. 一个 host-managed native AgentSession 承载 visible Compiler/Reasoner/Integrator phase turns；
14. canonical session event log 与每次 fully materialized provider request view 分离；
15. Host-level Phase Controller 和 deterministic Request Projector 是两个不同层次；stream-only middleware 不足以验证架构；
16. signed thinking/tool pair immutable；projection 单调追加；删除/重排只能通过 bounded ProjectionReset；cache prefix 严格绑定 phase lineage；
17. MVP 禁用不可观察的内置 compaction，后续只允许 graph-aware compaction；
18. 一条 append-only RunEvent log materialize ArtifactGraph、ExecutionState、BudgetLedger；ProjectionSnapshot 和 checkpoint 内容寻址；
19. `/tree` 只负责用户会话树和分支，RunEvent log 负责 harness replay 和 provenance；
20. 所有 model calls、turns、tools、retries、resets、时间、费用和 branches 共用 global pre-spend RunBudgetLedger；
21. policy/safety refusal terminal；内容 retry 只能是已证明的 raw egress defect 或 additive fidelity/scope repair；
22. Projected tool、attachment、prompt injection 和 compiler refusal 都采用 trusted control/data plane、taint、fully serialized egress、fail-closed；
23. mutation MVP 只读和 structured patch proposal，带 source handle、preimage hash、anchors 和显式用户批准；
24. Phase -1 先做 synthetic triad 和 compiler fidelity，Phase 0 再验证完整 Pi host API；
25. shadow mode 不为比较而重新发送 refusal-prone raw content；
26. 最终产品只提交一份 terminal assistant answer，所有中间事件仍可见、可审计、可从 `/tree` 分支；
27. `passthrough` / `compiled` 由 admission 阶段的确定性 triage 选定，早于任何 provider 响应，且不可因拒绝而改变；
28. 每个 outbound request 必须通过 provider-valid chain validator（tool 配对、thinking 签名完整性、abort 修复、跨 phase 隔离）；
29. cache 稳定性靠显式 `cacheLineageKey` 与 stable prefix / volatile suffix 分离，而不靠字符串相似度；
30. 终端 prose 是 approved ClaimObject 集合的渲染结果，受限 renderer 经 C1–C6 机械验证，失败则回退确定性模板；
31. Host 能力 H1–H10 是硬性 gate，缺项只能提 API 或 fork，不得用后台 session / widget / 字符串拼接变通；
32. 每个 run 的最坏情况调用量可在开始前算出（默认 compiled ≤ 49 次 model call），预算只减不增；
33. task sufficiency 用任务核细化与预声明 metamorphic family 审计，不再依赖不可测的 mutual-information 目标；
34. 每次模型生成的编译都走 translation validation，系统只提供 certificate/proof/assumption 成立下的条件保证；
35. final claims 是 proof-carrying artifacts，strict-primary 的 substantive proof 必须包含当前 Reasoner finding；
36. graph projection 是带 `MUST` dependency closure 的预算选择；mandatory closure 不可行时 abstain，不做静默截断；
37. residual、discard 和 mapped source atom 服从守恒账本，未知语义不能在 lift 中无痕消失。

---

## 29. 最终定位

> **Pi Context Compiler Harness 是一个 graph-engineered、model-agnostic 的上下文运行时。它先在 source-aware admission 之后，把完整领域上下文编译为带 typed symbols、FormalStatements、residuals、controller-computed provenance 和 CompilationCertificate 的 Semantic IR；再由确定性的 Reasoner Packet Renderer 生成包含 projected query `q_Z`、稳定 alias、科学/数学结构、已知缺口和工具协议的请求视图；用户当前选择的模型在该视图上承担主要推理并产生结构化 findings；最后通过 strict-primary 的确定性 lift（或明确披露的 source-aware-supplement）生成唯一的 terminal assistant answer。整个过程由 host-level Phase Controller 在一条 Pi 原生 AgentSession 中管理，Compiler、Reasoner、Integrator 的中间事件实时可见，canonical session event log、RunEvent log、ProjectionSnapshot、cache lineage、global budget 和 `/tree` branch 都保持可验证和可重放。**

它的目标不是让模型“看不到某个领域”，而是让模型看到一个**足够完成当前任务、带证据说明其边界、且不改变原始安全性质的语义表示**。当这一目标无法被证明时，系统必须诚实地暴露 residual、请求补充信息或 fail closed，而不是用更激进的上下文重写换取表面上的成功率。

同样重要的是它在什么时候**不**工作：当确定性 triage 判定任务不需要编译时，它就是一次普通的 Pi 回合，不多花一分钱、不多一次延迟。完整的三阶段机制只为真正需要它的任务付费。