niceeval 0.12.2-canary.31 → 0.13.0

package/docs-site/zh/explanation/overview.mdx

@@ -1,69 +1,68 @@
 ---
 title: "NiceEval 的评估与报告路径"
 sidebarTitle: "概览"
-description: "理解 Experiment、Record、AnalysisSample 与 ReportExecution 如何组成一次可查看、可分享的评估。"
+description: "理解 Experiment、Record、Analysis 与 Report 如何组成一次可查看、可分享的评估。"
 ---
 
-NiceEval 把评估定义、运行、持久事实与报告分成清楚的职责。你定义评估用例与 Experiment，Runner 执行它们；完整 Run 发布到 Record；查看和分享从 Record 选择 Sample，再投影所需事实并生成报告。
+NiceEval 把评估定义、运行、已发布结果和报告分成清楚的职责。你定义评估用例与 Experiment，Runner 执行它们；完整 Run 发布到 Record；查看和分享时，Analysis 从选中的结果形成闭合值，Report 再把这些值组织成页面。
 
 ```text
 Eval 与 Experiment
         ↓
 Runner
         ↓
-opaque Record
-        ↓  CLI internal selection
-AnalysisSample
-        ↓  official opaque projector
-ProjectedSample → Report → immutable ReportExecution
-                                  ├─ show
-                                  ├─ view
-                                  └─ static export
+Record：已发布结果
+        ↓  选择范围
+Analysis：Sample + Measure + aggregate() / query()
+        ↓
+ClosedRows / MetricValue / DomainView
+        ↓
+Report
+        ├─ show：一个选中的 Page
+        └─ view / static export：完整站点
 ```
 
 ## 评估如何运行
 
 Eval 定义任务、断言和需要的 Fixture。Experiment 选择 Eval，并声明 Agent、模型、并发、预算与其他运行条件。Adapter 连接被测系统；Sandbox 提供隔离的执行位置。
 
-Runner 为每个选中的 Experiment 建立一个 Run。Run 列出本次应有的 slots，因此它定义结果计算的分母。每个 slot 最多有一个 Member。
+Runner 为每个选中的 Experiment 建立一个 Run。Run 列出本次应有的位置，因此它定义结果计算的分母。每个位置最多有一个 Member。
 
-Member 表示这个 slot 被哪个 Attempt 占据。Attempt 的 `origin` 与当前 slot 一致时是 `origin`；采用了其它 Run 的 Attempt 时是 `reference`。Attempt 始终在自己的 origin Run 下保存一次，引用它的 Member 不复制业务事实。
+Member 表示这个位置由哪个 Attempt 占据。Attempt 的 `origin` 与当前位置一致时是 `origin`；采用了其它 Run 的 Attempt 时是 `reference`。采用复用已有结果，不会重新执行这个 Attempt。
 
-## Record 保存已发布的事实
+## Record 保存已发布的结果
 
-Record 位于 `.niceeval/record/`。它可以整体复制或进入 Git，但应用代码不读取其中的内部结构。
-内部 Core 保存 Run、Member、Attempt 与精确关系；Verdict、Usage、断言与诊断等业务事实
-保存在 owner-local Attachment 中。
+Record 是可携带、可复制并可进入 Git 的已发布结果集。应用代码不解析或写入它；通过 `show`、`view`、`clean` 和 `migrate` 操作即可。
 
-writer 写完一个 Run 的 Core 与 Attachments 后，最后创建 `complete`。没有这个标识的目录不是已发布事实；reader 忽略它，并给出 `incomplete-run` warning。需要不同结果时，运行新的 Invocation，生成新的 Run。
+一个 Run 只有完整发布后才可查看或用于后续选择。需要不同结果时，运行新的 Invocation，生成新的 Run；历史结果不会被覆盖。
 
 ## Sample 决定比较范围
 
-用户用不带 locator 或 `--run` 的命令选择身份仍匹配当前项目的全部结果，或用 locator、`--run` 选择历史事实。内部 host 从 frozen Record 形成可以独立
-显示的纯 `AnalysisSample`；reader 与 live handle 不属于公开 API。
+用户用不带 locator 或 `--run` 的命令选择仍匹配当前项目的结果，或用 locator、`--run` 选择历史事实。NiceEval 根据这个选择形成 `Sample`，它保留完整的预期范围和分母，但不允许页面重新选择或重新打开结果。
+
+`project-current` 扫描所有已发布 Run，只保留 Experiment、Eval 和执行身份仍匹配当前项目的位置。它不按时间只留一个 Run。
 
-`project-current` 扫描全部 published Run，并读取 Evaluation 与 Eligibility identity 事实。
-只有 Experiment、Eval、attempt ordinal、evaluation kind、input identity 和 config identity 仍匹配当前项目的 slots 才会进入 Sample；选择不按时间只留一个 Run。
+`--run` 保留具名 Run 的完整预期范围。每个已选位置都是 `included`、`not-recorded`、`core-invalid` 或 `excluded`。选择建立框架后，缺少分析输入不会悄悄缩小分母。
 
-`--run` 选择保留具名 Run 的完整 expected-slot 分母；`project-current` 则以匹配的 slots 建立当前分母。每个已选 slot 都是 `included`、`not-recorded`、`core-invalid` 或 `excluded`。selection 建立框架后，其它业务 Attachment 的问题不能再悄悄缩小分母。
+## Analysis 与 Report 各做什么
 
-## Projection 与 Report 组织已选事实
+Analysis 负责解释结果。作者用 `defineMeasure()` 声明总体、分组、分母和缺失规则，再用 `aggregate()` 或 `query()` 得到 `ClosedRows`、`MetricValue` 或领域视图。
 
-官方 opaque projector 把内部事实形成 typed view。Projection 将结果与 Sample 对齐，形成 `ProjectedSample`。Calculation 用这些值计算通过率、成本或诊断分布；Page 与 PageFamily 再把结果组织成报告页面。
+Report 负责页面与显示。Page 和组件只消费这些闭合值：表格读取 rows，图表读取 points，统计卡读取完整 value。需要详情地址时，Page 使用 `params`、`load` 和 `render` 列出实例。报告不会重新计算度量或读取结果存储。
 
-一次 Report 形成一份不可变的 `ReportExecution`。它不保留 reader、路径或延迟 I/O。`show`、`view` 与静态导出只消费这份 execution。
+`show` 在 Sample 存活时只执行选中的 Page，随后交付该页的文字或机器文档。`view` 与静态导出枚举全部 Page 与参数实例，形成一个完整的关闭站点版本。两条路径都不会让页面重新读取结果。
 
-`view` 发生变化时会构造下一份 execution。完整 rebuild 才替换正在显示的结果；rebuild 失败会保留 last-good execution，并显示问题。
+`view` 发生变化时构建下一份完整站点。完整 rebuild 才替换正在显示的结果；rebuild 失败会保留上一份可用站点，并显示问题。
 
 ## 交付报告
 
 `niceeval show` 在终端显示报告。`niceeval view` 在本机显示网页。`niceeval view --out <目录>` 导出自包含静态报告站；需要固定历史范围时可以传一个或多个明确 `--run`。
 
-静态报告站只消费导出时完成的 `ReportExecution`。浏览器不读取源 Record。发布步骤见[发布静态报告](/zh/tutorials/publish-report)。
+静态报告站只消费导出时完成的完整站点版本。浏览器不读取源结果。发布步骤见[发布静态报告](/zh/tutorials/publish-report)。
 
 ## 继续阅读
 
-- [Record](/zh/explanation/record)：理解 Core、Attachment 与演进边界。
+- [Record](/zh/explanation/record)：理解已发布结果的边界。
 - [运行器](/zh/explanation/runner)：理解 Invocation、Run 与当前进程反馈。
 - [查看结果](/zh/tutorials/viewing-results)：选择 Sample 并查看报告。
-- [重跑与沿用](/zh/tutorials/rerun-and-cache)：理解 carry 与 accept。
+- [编写自定义报告](/zh/tutorials/custom-reports)：定义 Measure、Page 和组件。

package/docs-site/zh/explanation/record.mdx

@@ -1,60 +1,50 @@
 ---
-title: "Record：持久事实与报告输入"
+title: "Record：已发布结果"
 sidebarTitle: "Record"
-description: "理解 Record Core、RecordAttachment、完成标识，以及从选择到 ReportExecution 的固定数据路径。"
+description: "理解 Record 如何保存已发布的 Run，以及如何安全地选择、查看和分享结果。"
 ---
 
-import { RecordShape } from '/snippets/diagram-record-shape.jsx';
-import { RecordEvolution } from '/snippets/diagram-record-evolution.jsx';
+Record 是 NiceEval 的已发布结果集。你可以整体复制它、放进 Git，或交给 `show`、`view`、`clean` 与 `migrate`；应用代码不需要也不能解析其中的实现细节。
 
-Record 是 `.niceeval/record/` 下可携带、可进入 Git 的 opaque 运行事实集。可以整体复制它，
-也可以把它交给 `show`、`view`、`clean` 与 `migrate`；应用代码不解析或写入其中的文件，
-也不 import Record reader / writer。一个 Run 发布后不再修改。
+一个 Run 发布后不会修改。重新运行、自动沿用或人工采用都会形成新的 Run，因此历史结果仍可被明确查看和比较。
 
-<RecordShape />
+## Record 保存什么
 
-## Core 保存骨架，Attachment 保存业务事实
+Record 保存每次运行的范围、每个预期位置是否有结果，以及结果实际来自哪个 Attempt。它还保存 NiceEval 收集的断言、诊断、事件、用量、文件变化和来源信息，以便之后在同一份历史结果上查看。
 
-Record Core 保存所有读取者都要理解的关系：Record 身份、Run 的 `expectedSlots`、Member 对 Attempt 的精确引用，以及 Attempt 的 origin。
-
-业务事实属于 owner-local 的 `RecordAttachment`。Run 可以保存 Evaluations、Membership provenance 与 Sources。Attempt 可以保存 Assertions、Verdict、Score 与 Eligibility。一个 Attachment 的问题只影响请求它的功能，不会把其它完整事实变成无效。
-
-Member 表示一个 expected slot 被哪个 Attempt 占据。Attempt 在自己的 origin Run 下只保存一次；另一个 Run 采用它时，Member 只保留精确引用，不复制业务事实。
-
-没有 `complete` 的目录可能短暂留在 `runs/` 下。它不是已发布的 Run，reader 忽略它并返回 `incomplete-run` warning。`session`、锁和 cache 位于 portable Record 外，也不随 Record 复制或分享。
+这些事实由 NiceEval 写入并验证。应用、Adapter 和 Plugin 没有通用接口去添加任意持久数据、注册自定义数据族或改写历史结果。需要新的长期能力时，应使用已有的 NiceEval API，或让 NiceEval 提供相应支持。
 
 ## 从选择到报告
 
 查看或生成报告时，数据沿一条固定链路前进：
 
 ```text
-opaque Record + CLI selector
-                  ↓ internal host
-            AnalysisSample（纯值）
-                  ↓ official projector declarations
-                  ↓
-           ProjectedSample → Report
-                  ↓
-     immutable ReportExecution → show / view / static export
+Record + CLI 选择条件
+        ↓
+Sample：已选范围与分母
+        ↓
+Analysis：Measure + aggregate() / query()
+        ↓
+ClosedRows / MetricValue / DomainView
+        ↓
+Report
+        ↓
+show：一个选中的 Page；view / static export：完整站点
 ```
 
-用户用不带 locator 或 `--run` 的命令选择身份仍匹配当前项目的结果，或用 locator、`--run` 选择历史事实。内部 host 形成纯
-`AnalysisSample`；它保留完整 expected-slot 分母，并标出 `included`、`not-recorded`、
-`core-invalid` 与 `excluded`，但不暴露 reader 或恢复 I/O 的能力。
-
-官方 opaque projector 把内部 Attachment 形成 typed view。Projection 将它与 Sample 的每一个逻辑位置对齐，形成 `ProjectedSample`。Report 再用投影结果计算并组织页面，得到一次不可变的 `ReportExecution`。
+不带 locator 或 `--run` 的命令选择仍匹配当前项目的结果；使用 locator 或 `--run` 可以查看明确的历史结果。`Sample` 保留完整分母，并标出 `included`、`not-recorded`、`core-invalid` 与 `excluded`，但它不会把底层结果读取能力交给页面。
 
-## 变化停在正确的层
+Analysis 只在某个 Measure 或领域视图实际需要时取得相应事实，并将结果关闭为可显示的值。Report 可以呈现这些值，却不能更改历史结果、扩大选择范围或再次读取原始数据。
 
-<RecordEvolution />
+## 版本与维护
 
-作者 API、matcher 或算法改变时，只要已保存事实的语义不变，磁盘不需要改变。Attachment payload 改变时发布相邻 schema，并通过明确的相邻迁移边处理历史值。只有 Core 的 owner、引用、目录、完成判断或 shape 改变时，才提升 Record major。
+NiceEval 负责识别已支持的结果格式。需要迁移时运行 `niceeval migrate`；无法安全解释的历史数据会在依赖它的查看内容中明确显示问题，而不是被猜成空值或零值。
 
-普通读取不会自动改写磁盘。需要迁移时运行 `niceeval migrate`；无法无损迁移的 Attachment 保留其历史 bytes，并对请求新值的功能显示不可用。
+写入没有完成的结果不会进入查看范围。可以运行 `niceeval clean` 清理这类未完成的残留，再重新运行受影响的评估。
 
 ## 下一步
 
 - [查看结果](/zh/tutorials/viewing-results)：选择 Sample，并查看 `show` 与 `view` 的结果。
-- [结果数据 API](/zh/reference/results-data)：在 Report 中使用 Sample 和官方 Projection。
-- [报告 API](/zh/reference/report-components)：定义 Projection、Calculation、Page 与 Report。
-- [发布静态报告](/zh/tutorials/publish-report)：分享一个已完成的 `ReportExecution`。
+- [结果数据 API](/zh/reference/results-data)：在 Report 中使用 Measure 和闭合结果。
+- [报告 API](/zh/reference/report-components)：定义 Page、组件与 Report。
+- [发布静态报告](/zh/tutorials/publish-report)：分享一份已关闭的完整报告站。

package/docs-site/zh/explanation/runner.mdx

@@ -12,17 +12,17 @@ Runner 把选中的 Experiment 和 Eval 排成一次 Invocation。它在当前
 
 每个 slot 最多有一个 Member。Member 表示这个 slot 被哪个 Attempt 占据：Attempt 的 `origin` 与当前 slot 一致时是 `origin`，采用其它 Run 的 Attempt 时是 `reference`。
 
-占位怎样形成属于 Run-owned 的 `niceeval.membership-provenance/v1` RecordAttachment。Attempt 始终保存实际执行它的 origin；采用不复制 Verdict、Usage、事件或其他业务事实。
+每个位置是执行、自动沿用还是人工采用，都会随目标 Run 保存为可查看的来源说明。Attempt 始终保留实际执行它的 origin；采用不会复制 Verdict、用量、事件或其他业务事实。
 
 ## 执行前的规划
 
-`niceeval exp --dry` 在停稳的 Record 上列出每个 slot 的计划。它读取规划需要的 Verdict 与 Eligibility RecordAttachment，再决定执行还是采用已有 Attempt。
+`niceeval exp --dry` 根据已发布结果列出每个位置的计划，再决定执行还是采用已有 Attempt。
 
 ```sh
 npx niceeval exp checkout --dry
 ```
 
-carry 只在终态、输入身份、超时和 `--rerun` 条件都合适时发生。资格、身份和采用理由作为事实写入目标 Run 的 Membership provenance Attachment。分析选择与 reuse planning 是两件事：前者建立查看分母，后者决定本次要执行哪些 slot。
+carry 只在终态、输入身份、超时和 `--rerun` 条件都合适时发生。资格、身份和采用理由会随目标 Run 保存。分析选择与 reuse planning 是两件事：前者建立查看分母，后者决定本次要执行哪些位置。
 
 规划完成后，Runner 才启动需要执行的 Attempt。详情见[重跑与沿用](/zh/tutorials/rerun-and-cache)。
 
@@ -53,13 +53,13 @@ receipt 只说明本次调用的身份、Run、时间与完成状态。需要 Ve
 
 ## Run 如何发布
 
-Runner 先写 Run Core、Member、Attempt 和它们的 RecordAttachment。所有 durable 内容写完后，最后创建零字节 `complete`。在此之前退出、I/O 失败或中断会留下未完成目录；它不进入 reader、Sample 或 reuse，可用 `niceeval clean` 清理。
+Runner 只有在一个 Run 的结果完整发布后，才让它进入后续查看和沿用。运行在此之前退出、I/O 失败或中断时，该结果不会进入 Sample 或 reuse；可用 `niceeval clean` 清理未完成的残留。
 
 ## Reporter
 
 Reporter 只接入当前 Invocation。它可以把当前进程已知的结果交给外部系统；`--junit` 也会写出供 CI 平台读取的文件。
 
-这些输出不拥有 Record。Verdict、Usage、断言与诊断仍属于停稳 Record 的 Attachment。需要在后续步骤查看完整结果时，使用 receipt 的 `runIds` 选择 Sample，再运行 `show`、`view` 或 `view --out`。
+这些输出不拥有 Record。Verdict、用量、断言与诊断仍属于已发布结果。需要在后续步骤查看完整结果时，使用 receipt 的 `runIds` 选择 Sample，再运行 `show`、`view` 或 `view --out`。
 
 ## 停稳后查看
 
@@ -70,9 +70,8 @@ npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
 npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
 ```
 
-不带 locator 或 `--run` 的 `show` 和 `view` 读取身份仍匹配当前项目的全部结果；locator 与 `--run` 读取指定历史事实。内部 host 形成纯
-`AnalysisSample`，按 Report 声明投影所需事实，并生成固定的 `ReportExecution`。
-已发布的 Run 不可修改；再次查看会形成新的选择与 execution。
+不带 locator 或 `--run` 的 `show` 和 `view` 读取身份仍匹配当前项目的全部结果；locator 与 `--run` 读取指定历史事实。NiceEval 形成 `Sample`，再按选中 Page 或完整站点所需的 Measure 与领域视图取得闭合值。
+已发布的 Run 不可修改；再次查看会形成新的选择。`show` 只交付目标 Page，`view` 与静态导出交付完整站点。
 
 ## 结束状态
 

package/docs-site/zh/index.mdx

@@ -88,7 +88,7 @@ export default defineEval({
     });
 
     turn.judge.autoevals.closedQA("助手是否基于工具返回的天气数据作答？")
-      .atLeast(0.7)
+      .gate(0.7)
       .label("回答有依据");
   },
 });

package/docs-site/zh/introduction.mdx

@@ -36,7 +36,7 @@ export default defineEval({
     t.check(second.message, includes("上海")).label("第二轮回答上海");
 
     turn.judge.autoevals.closedQA("助手是否基于工具返回的天气数据作答？")
-      .atLeast(0.7)
+      .gate(0.7)
       .label("回答有依据");
   },
 });

package/docs-site/zh/reference/cli.mdx

@@ -28,7 +28,7 @@ description: "NiceEval CLI 参考：exp、debug、show、view、init、list 和
     在终端执行报告。不带 locator 或 `--run` 的命令读取当前项目结果；精确 Attempt 定位符或 Run ID 用于审计历史。
   </Card>
   <Card title="npx niceeval view" icon="eye">
-    打开固定 ReportExecution 的网页结果。选择与 `show` 相同；要看编辑后的 Record，结束后重新运行。
+    构建完整报告站并在浏览器中托管。它与 `show` 共享选择规则，但会枚举全部页面。
   </Card>
 </CardGroup>
 
@@ -166,7 +166,7 @@ E2B template name 与 Vercel snapshot ID 是 Provider 管理的任意字符串
 | `--orphans` | boolean | `sandbox list` 专用:核对强杀(`SIGKILL` / 断电)路径留下的无主沙箱实例(docker + e2b;vercel 无按元数据检索实例的通道,不参与)。只读,不清理;销毁走 `niceeval sandbox prune`。 |
 | `--tag` | string | 只运行带有该 tag 的 eval(见 `defineEval` 的 `tags`)。 |
 | `--junit` | string | 额外写一份 JUnit XML 报告到指定路径,供 CI 消费。 |
-| `--json` | boolean | `exp` 运行在 stdout 输出单一有序的 NDJSON 事件流；`exp --dry` 与 `debug` 输出各自的单个 JSON 计划文档。`show` 输出同一 ReportExecution 的宿主数据与状态，不打开第二条取数路径。 |
+| `--json` | boolean | `exp` 运行在 stdout 输出单一有序的 NDJSON 事件流；`exp --dry` 与 `debug` 输出各自的单个 JSON 计划文档。`show` 输出 Host 拥有的内建或自定义单目标机器文档，不形成完整站点或打开第二条取数路径。 |
 | `--smoke` | boolean | `docker profile doctor` 专用：启动受限 DinD 容器并运行内层容器。 |
 | `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
 | `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
@@ -233,15 +233,15 @@ npx niceeval view @01H...
 npx niceeval view --host 192.168.0.199
 ```
 
-打开本地记录查看器。它和 `show` 共用默认 Report 与选择规则。不带 locator 或 `--run` 的命令从默认 Record 读取所有身份仍匹配当前项目的结果；精确 `@<AttemptLocator>` 显示该 Attempt 的默认概览；`--run` 读取指定历史 Run。随后内部 host 投影所需事实，并执行一次 Report。
+打开本地结果查看器。它和 `show` 共用默认 Report 与选择规则。不带 locator 或 `--run` 的命令读取所有身份仍匹配当前项目的结果；精确 `@<AttemptLocator>` 显示该 Attempt 的默认概览；`--run` 读取指定历史 Run。NiceEval 随后形成固定 Sample、枚举全部 Page 与参数实例，并构建完整站点。
 
 没有显式 `--report` 时，`--run` 使用内建 `run-membership-overview`，精确 locator 使用 `attempt-overview`。`project-current` 才使用配置里的 Report，并在没有配置时回退到通用 `default-overview`。显式 `--report` 始终优先。Config 仍会为 Theme 和 `view` rebuild 加载；这里只说明配置里的 Report 不参与显式 Run 的默认选择。
 
 省略 `--host` 时，`view` 只监听 `127.0.0.1`。传入具体 hostname / IP 会显式监听该地址；只写 `--host` 时则监听全部 IPv4 接口。wildcard listener 先打印 loopback URL，再打印可用接口 URL；`--page` 应用到每条 URL，自动打开浏览器只使用第一条。
 
-非 loopback 模式是无认证、无加密的开发服务器。所有网络可达客户端都能读取报告、execution JSON 和 downloads，所以只能在可信网络使用；启动时也会打印同样的警告。server 只接受已公布的 Host authority 与只读 `GET` / `HEAD` 请求；未来写端点必须另行设计认证与 CSRF 边界。
+非 loopback 模式是无认证、无加密的开发服务器。所有网络可达客户端都能读取报告页面、下载和公开 JSON 文档，所以只能在可信网络使用；启动时也会打印同样的警告。server 只接受已公布的 Host authority 与只读 `GET` / `HEAD` 请求；未来写端点必须另行设计认证与 CSRF 边界。
 
-此前的局部执行可能让部分 slot 以 `reference` 采用已有 Attempt。这些是当时的采用事实，不是补跑状态。同一份 `AnalysisSample` 不会在页面请求时重新选择。`--experiment` 可按完整 ID 收窄当前项目目标；`--record` 只在主动读取其它 Record root 时使用。
+此前的局部执行可能让部分 slot 以 `reference` 采用已有 Attempt。这些是当时的采用事实，不是补跑状态。同一份 `Sample` 不会在页面请求时重新选择。`--experiment` 可按完整 ID 收窄当前项目目标；`--record` 只在主动读取其它 Record root 时使用。
 
 ## `show`
 
@@ -250,21 +250,18 @@ npx niceeval show
 npx niceeval show --run 01H...
 npx niceeval show --run 01H... --run 01J...
 npx niceeval show @01H...
-npx niceeval show @01H... --source
-npx niceeval show @01H... --execution
-npx niceeval show @01H... --timing
-npx niceeval show @01H... --timing=full
-npx niceeval show --run 01H... --page attempt-0123456789ABCDEFGHJKMNPQRS
-npx niceeval show --run 01H... --report ./reports/summary.ts --page overview
+npx niceeval show --run 01H... --page /
+npx niceeval show --run 01H... --report ./reports/summary.tsx --page /overview
+npx niceeval show --run 01H... --report ./reports/summary.tsx --json
 ```
 
-`show` 是终端报告入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。它不接受模糊的位置选择。精确 `@<AttemptLocator>` 默认显示该 Attempt 的 Evaluation identity、evaluation kind、四态 Verdict、Assertions 和适用的 Score。
+`show` 是终端报告入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。它不接受模糊的位置选择。省略 `--page` 时选择默认 Page；提供 `--page <route>` 时只执行这个精确 route。
 
-加 `--source`、`--execution` 或 `--timing` 可查看对应的专用证据面。`--timing` 默认显示精简阶段树；`--timing=full` 还显示 interval identity、parent 和 offset。三种证据面互斥，并且都要求一个精确 Attempt 定位符。
+参数 Page 的 show 路径只对请求 key 调用 `decode()`、canonical `encode()`、`load()` 与 `render()`。它不调用 `enumerate()`，也不为了查找成员资格而执行其它 Page。通过 Page 的关闭 Evidence 边界验证的 locator、identity 或 key 不属于当前 Sample 时，命令返回类型化错误。
 
 不带 locator 或 `--run` 的 `show` 规划当前项目身份，并扫描默认 Record 中全部 published Run。只有 Experiment、Eval、Attempt 序号、evaluation kind、input identity 与 config identity 仍匹配的 slot 才进入 Sample；命令不会按时间只留一个 Run。没有匹配结果时显示空 Sample，过期结果仍可用完整 `--run` 读取。
 
-`--run` 可重复，只读取这些显式历史 Run。`--experiment <id>` 可重复，按完整 ExperimentId 收窄当前项目目标，不能与 `--run` 合用。`exp`、不带 `--record` 的 `show` 与 `view` 默认使用同一个 `.niceeval/record`。
+`--run` 可重复，只读取这些显式历史 Run。`--experiment <id>` 可重复，按完整 ExperimentId 收窄当前项目目标，不能与 `--run` 合用。`exp`、不带 `--record` 的 `show` 与 `view` 默认使用同一份结果集。
 
 单个 `--run` 用于核对这一轮的 expected-slot 分母与 membership；多个 `--run` 用同一表形状比较多个固定历史边界。即使两个 Run 指向同一个 Attempt，它们也可能分别由实际执行、自动沿用或人工采用形成。`exp --json` 最后一条 receipt 的 `runIds` 是机器稳定出口；TTY 完成反馈也显示 Run ID。`accept` 的成功反馈会显示新 Run ID，但这行人读文本不是 JSON receipt 或自动化输入契约。
 
@@ -278,13 +275,13 @@ npx niceeval show --run 01H... --report ./reports/summary.ts --page overview
 
 单 Run 和多 Run 都按 `runId`、`slotId` 排序；表在排序后最多显示 200 rows，并显示省略数量。
 
-`membershipOutcome` 来自公开 projector，值为 `carried`、`accepted`、`executed`、`not-dispatched` 或 `interrupted`。它不是持久 payload 的 raw `action` 字段。内建表是 bounded summary；已知 Attempt 的身份与证据用 `show @<AttemptLocator>` 下钻，需要其它 Run 字段时显式选择自定义 Report。
+`membershipOutcome` 是内建报告给出的来源结果，值为 `carried`、`accepted`、`executed`、`not-dispatched` 或 `interrupted`。它用于说明本次位置如何得到结果。内建表是 bounded summary；已知 Attempt 的身份与证据用 `show @<AttemptLocator>` 下钻，需要其它 Run 字段时显式选择自定义 Report。
 
-选择完成后，`show` 用已选 handle 读取 Report 声明的 Projection，并形成一次 `ReportExecution`。请求的 Attachment 为 unavailable、migration-required、unsupported、partial 或 invalid 时，命令会原样显示状态；未请求的未知或损坏 Attachment 不影响当前页面。完整契约见[查看结果](/zh/tutorials/viewing-results)。
+选择完成后，`show` 只执行目标 Page 需要的 Measure 与领域视图。`partial`、`unsupported`、`failed` 等 Analysis 状态会随结果显示；未使用的数据问题不影响当前页面。`show --json` 是同一个单目标读取：内建 Report 返回 Host-owned 领域文档，自定义 Report 返回一个 Page 的 rendered text manifest。完整契约见[查看结果](/zh/tutorials/viewing-results)。
 
-`view --out <目录>`（或显式 `--run`）使用同一份 ReportExecution 预渲染自包含静态站。目标目录必须不存在；全部页面、下载项与静态资产路径先通过校验。写完全部文件后，exporter 最后创建 `complete` marker。导出过程不会把 Record 路径或 blob 路径交给用户 Report。
+`view --out <目录>`（或显式 `--run`）构建完整自包含静态站。目标目录必须不存在；全部页面、下载项与静态资产路径先通过校验。导出完成后，站点即可独立查看。导出过程不会把底层结果存储交给用户 Report。
 
-命令在持有 sample handle 时完成所需 Projection 和 Report execution。返回的 ReportExecution 不再访问 Record。运行中的 `view` 对变化构造新的固定 execution；成功后替换当前 revision，失败保留 last-good execution。静态 export 只消费已经完成的 execution。
+view 与静态导出都从同一完整站点版本读取 bytes。运行中的 view 对变化构造候选站点；成功后原子替换当前 revision，失败保留 last-good。静态 export 只写出已完成的完整站点。
 
 ## `--early-exit`
 
@@ -305,4 +302,4 @@ npx niceeval show --run 01H... --report ./reports/summary.ts --page overview
 | `2` | 运行时崩溃（未捕获异常），CLI 顶层捕获后退出。 |
 | `130` | 收到中断信号（Ctrl-C / SIGTERM）后退出。 |
 
-CI 的退出码直接来自 Pass Eval 的 Boolean conditions 与最终 Verdict；JUnit 使用同一份 sealed projection。
+CI 的退出码直接来自 Pass Eval 的 Boolean conditions 与最终 Verdict；JUnit 使用同一份已封口的断言结果。

package/docs-site/zh/reference/define-agent.mdx

@@ -366,14 +366,6 @@ diagnostic(input: DiagnosticInput): void;
 永久事件,落进 attempt 的 diagnostics 并进各 profile 的永久输出;`dedupeKey` 去重。
 即使 level 为 "error" 也不改变 Turn.status / verdict——无法继续时抛异常。
 
-#### `fact`
-
-```ts
-fact(name: string, value: JsonValue): void;
-```
-
-写入本 Attempt 的 generic custom fact document。name 使用反向域格式且不能以 `niceeval.` 开头；同一 owner/name 只允许写一次，第二次写入是 typed error，不替换也不追加。value 可以是任意 JsonValue。`{ observedAt, value }` 经 JSON.stringify 后最多 65,536 UTF-8 bytes；超限同步抛出 `record-custom-fact-too-large`，且不留下部分文件。不影响 Turn status、verdict、评分或指纹。形状与归属语义见 docs/feature/record/architecture.md。
-
 #### `log`
 
 ```ts

package/docs-site/zh/reference/define-config.mdx

@@ -29,7 +29,7 @@ export default defineConfig({
 #### `report`
 
 ```ts
-report?: Report;
+report?: ReportDefinition;
 ```
 
 view/show 的项目默认报告。
@@ -122,8 +122,12 @@ pricing?: globalThis.Record<string, PriceOverride>;
 
 内置价格表(`o11y/prices.json`)之上的用户覆盖 / 补充,按 model 查(见 Observability
 · 用量与成本)。key 支持精确 model 名或 `provider/*` 通配(自托管/网关折扣按 provider 批量覆盖);
-精确 key 优先于通配。只在没有网关实测成本(`usage.costUSD`)时才会用到——实测优先于估算恒成立。
+精确 key 优先于通配。pricing 只驱动 `estimatedCostUSD` 的估算(`estimateCost`),与
+`usage.costUSD`(网关实测)无关——两者独立并存,互不兜底。它是 runtime/config 价目表,
+不是 Report 的成本投影:Report 不消费该字段(Report 侧使用自己的 PricingProfile)。
 
 {/* GENERATED:END config-fields */}
 
+> 成本边界：这里的 `pricing` 只提供 Runner 的 Config/runtime price table 输入，Runner 会独立产生 `estimatedCostUSD`，不论是否已有 `Usage.costUSD`。`maxCost` 只使用该 estimate。Report 不读取此配置；它必须在 Report module 以 `definePricingProfile()` 显式声明自己的 USD Profile，并只对 sealed Usage 做 Analysis 投影。
+
 [NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：评估用例自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 setup。`Config` 刻意没有 `sandbox` 字段，也不自动探测 provider。请在 Eval 或 Experiment 上声明 template-bearing `SandboxLayer`，让 link planning 在创建任何资源前确定它的 owner 与配对结果。

package/docs-site/zh/reference/define-eval.mdx

@@ -114,9 +114,11 @@ test(t: TestContext): EvalTestReturn;
 
 ## Test context: `t`
 
-`t`（`TestContext`）是评估用例作者拿到的高层上下文。每一次作者入口调用都直接登记一条 Assertion。`t.check(value, match)` 严格接收两个参数。`t.succeeded()`、`session.succeeded()`、`turn.succeeded()`、`calledTool(...)`、`notCalledTool(...)` 与 Judge recipe 也直接登记 Assertion。handle 只配置同一条 entry 的 `key`、`label`、`.atLeast(n)` 与 `.score(n)`。`.orStop()` 也只作用于此 entry，绝不登记第二条 Assertion。
+`t`（`TestContext`）是评估用例作者拿到的高层上下文。每一次作者入口调用都直接登记一条 Assertion。`t.check(value, match)` 严格接收两个参数。`t.succeeded()`、`session.succeeded()`、`turn.succeeded()`、`calledTool(...)`、`notCalledTool(...)` 与 Judge recipe 也直接登记 Assertion。handle 只配置同一条 entry 的 `key`、`label`、`.atLeast(n)`、`.gate(n)` 与 `.score(n)`。`.orStop()` 也只作用于此 entry，绝不登记第二条 Assertion。
 
-Pass Eval 用 Boolean condition 折叠 Attempt Verdict。measurement 必须 `.atLeast(n)`；`await handle.orStop()` 在 mismatch 或 below 时停止当前 continuation。`defineScoreEval` 的 `ScoreTestContext` 额外提供 `t.score(n)` 直接登记 contribution，`n` 必须 finite 且不小于零；已有 Assertion 用 `.score(n)` 贡献分数，`n` 必须 finite 且大于零。`calledTool` 与 `notCalledTool` 的完整契约见 [Scoped assertions](https://github.com/NiceEval/NiceEval/blob/main/docs/feature/assertions/library/scoped-assertions.md)。全部成员：
+Pass Eval 用 Boolean condition 折叠 Attempt Verdict。measurement 用 `.gate(n)` 才进入 failed，`.atLeast(n)` 只增加局部 condition；`await handle.orStop()` 在 mismatch 或 below 时停止当前 continuation。
+
+`defineScoreEval` 的 `ScoreTestContext` 额外提供 `t.score(n)` 直接登记 contribution，`n` 必须 finite 且不小于零；已有 Assertion 用 `.score(n)` 贡献分数，`n` 必须 finite 且大于零。`calledTool` 与 `notCalledTool` 的完整契约见 [Scoped assertions](https://github.com/NiceEval/NiceEval/blob/main/docs/feature/assertions/library/scoped-assertions.md)。全部成员：
 
 {/* GENERATED:BEGIN test-context */}
 
@@ -325,12 +327,12 @@ readonly judge: RootJudge<Kind>;
 
 ```ts
 const turn = await t.send("总结需求。");
-turn.judge.autoevals.factuality(expected).atLeast(0.8).label("事实一致");
-turn.judge.autoevals.closedQA(question).atLeast(0.7).label("回答质量");
+turn.judge.autoevals.factuality(expected).gate(0.8).label("事实一致");
+turn.judge.autoevals.closedQA(question).gate(0.7).label("回答质量");
 turn.judge.autoevals.summarizes(sourceText).score(20).label("摘要质量");
 ```
 
-`t.judge.autoevals` 的根级 recipe 额外接收 `{ input, output }` 字符串材料。`turn.judge` 已绑定 immutable Turn 材料。模型配置按 Eval、Experiment、项目配置解析一次；没有单次模型覆盖或 `{ on }` 选项。Pass Eval 必须 `.atLeast(n)`；Score Eval 直接 `.score(n)`。
+`t.judge.autoevals` 的根级 recipe 额外接收 `{ input, output }` 字符串材料。`turn.judge` 已绑定 immutable Turn 材料。模型配置按 Eval、Experiment、项目配置解析一次；没有单次模型覆盖或 `{ on }` 选项。Pass Eval 使用 `.gate(n)`；Score Eval 直接 `.score(n)`。
 
 ## `Turn` 返回类型
 

package/docs-site/zh/reference/events.mdx

@@ -80,12 +80,15 @@ costUSD?: number;
 ```
 
 网关/adapter 实测的真实美元成本(只能由 `Turn.usage.costUSD` 显式带回,从不从
-token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个事实:
-存在时优先于按价格表(`defineConfig({ pricing })`)估算的成本——见 `estimateCost` 的
-`usage.costUSD ?? estimateCost(...)` 兜底顺序。
+token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个
+相互独立的事实,单向字段契约:本字段只存 observed 值;`estimatedCostUSD` 恒等于
+`estimateCost(model, usage, pricing)` 的估算,即使 observed 存在也照常独立计算——
+两者互不覆盖、互不兜底；observed 值从不替代或触发 estimate。
 
 {/* GENERATED:END usage-fields */}
 
+> 成本边界：`Usage.costUSD` 只表示 provider / adapter 返回的 USD observed 成本，绝不由 token、模型目录或本地价目表推导。Runner 从 Config/runtime price table 独立计算 `estimatedCostUSD`，即使 observed 成本存在也照常计算，且只有 `maxCost` 消费它。Report 成本投影只接受显式 `PricingProfile` 与 sealed Usage，不读取 Runner estimate。
+
 ## StreamEvent 变体一览
 
 `StreamEvent` 的十种变体，逐字段列出（消费它们的断言 / 使用细节见下面的「事件总表」和「逐事件说明」）：