niceeval 0.12.2-canary.31 → 0.13.0

package/dist/runner/types.d.cts

@@ -10,12 +10,11 @@ import type { EvaluationFactResult, DiffArtifact, JudgeConfig, JudgeDeclaration,
 import type { ScoreTestContext, TestContext } from "../context/types.cjs";
 import type { CapturedEvalSource } from "./eval-source.cjs";
 import type { AttemptLocator } from "../attempt-locator.cjs";
-import type { RecordAttachmentWrite } from "../record/attachment/index.cjs";
-import type { SealedAttemptAssertions } from "../assertions/api.cjs";
+import type { RecordRoot } from "../record/platform/root.cjs";
 import type { CurrentReusedAttemptReadback } from "./reuse-readback.cjs";
 import type { PluginInstance, PluginOnUnavailable } from "../plugin/contracts.cjs";
-import type { Report } from "../report/index.cjs";
-import type { ThemeDefinition } from "../report/host/theme.cjs";
+import type { ReportDefinition } from "../report/index.cjs";
+import type { ThemeDefinition } from "../report/theme.cjs";
 /**
  * 解析后运行配置的**穷尽可序列化投影**——记录这次运行实际生效的值,不是原始 `ExperimentDef`
  * (函数与 hooks 无法忠实落盘,存「原样」只能存谎)。`model` 与 `agent` 只在快照顶层存在,
@@ -152,6 +151,8 @@ export interface SandboxBuildRecord {
 /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/record/architecture.md)。 */
 export interface PhaseTiming {
     name: LifecyclePhase;
+    /** 相对本 attempt 单调时钟起点的阶段起点；与 children 使用同一量化时钟。 */
+    startOffsetMs: number;
     /** 阶段耗时;失败阶段计到抛错或超时中断时。 */
     durationMs: number;
     /** 该阶段抛错或被超时中断。主链至多一条,其后无主链条目;收尾阶段各自独立标记,不改判定。 */
@@ -366,17 +367,16 @@ export interface EvalResult {
     /** 自动重试吸收的物理 send 失败，按发生顺序完整保留。 */
     retryAttempts?: RetryAttemptRecord[];
     usage?: Usage;
+    /**
+     * 价目表估算成本,恒等于 `estimateCost(model, usage, config.pricing)`——永远独立计算,
+     * 与 `usage.costUSD`(网关/adapter 显式回报的 observed 成本)是两个并存事实,互不覆盖、
+     * 互不兜底:observed 存在时 estimatedCostUSD 也照常按 runtime/config price table 估算。
+     */
     estimatedCostUSD?: number;
     /** 使 attempt 进入 `errored` 的唯一致命执行错误(结构化);默认报告显示 `error.message` 一层原因。 */
     error?: AttemptError;
     /** 本 attempt 的诊断(与 verdict 独立);teardown / cleanup 失败等挂在这里,不改判定。 */
     diagnostics?: readonly DiagnosticRecord[];
-    /**
-     * sandbox hook / agent setup·send·teardown 经 `ctx.fact()` 上报的运行事实(同 attempt 内
-     * 后写覆盖先写)。中性环境观测,不参与 verdict / 评分 / 指纹。见
-     * docs/feature/record/architecture.md#facts运行事实。
-     */
-    facts?: globalThis.Record<string, string | number | boolean>;
     /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/record/architecture.md)。 */
     phases?: PhaseTiming[];
     skipReason?: string;
@@ -484,7 +484,9 @@ export interface InvocationSummary {
     /** 环境、超时、adapter、agent runtime 等执行错误数量;与 failed 互斥。 */
     errored: number;
     durationMs: number;
+    /** 本次 Invocation fresh 结果的 token 汇总(只折叠 input/outputTokens);observed costUSD 不在这里汇总,逐条留在 `results[].usage.costUSD`。 */
     usage?: Usage;
+    /** 本次 Invocation fresh 结果的 `estimatedCostUSD` 累计(价目表估算口径,见 EvalResult.estimatedCostUSD);observed cost 不进入本字段。 */
     estimatedCostUSD?: number;
     /** Current Record readbacks adopted by this invocation; these are never recreated EvalResults. */
     reusedAttempts: readonly CurrentReusedAttemptReadback[];
@@ -592,8 +594,6 @@ export type ReporterEvent = {
     reusedAttempts: readonly CurrentReusedAttemptReadback[];
     /** 该 Experiment 域产生的全部诊断;空集合传空数组,不省略字段。 */
     diagnostics: readonly DiagnosticRecord[];
-    /** 该 Experiment 域经 `ctx.fact()` 累计的运行事实(experiment.setup / .teardown,含收尾自愈路径);省略 = 没有上报过。 */
-    facts?: Readonly<globalThis.Record<string, string | number | boolean>>;
     /** Run 级共享工作时间树;与 completedAt 同批封口。省略 = 本 Run 没有共享 activity。 */
     timings?: readonly TimingActivity[];
     /** 共享构建 provenance;与 timings 经 timingNodeId 关联。省略 = 本 Run 没有查询或构建过 BuildKey。 */
@@ -785,14 +785,6 @@ export interface ExperimentHookContext extends ScopedFeedback {
     readonly selectedEvalIds: readonly string[];
     /** 用户中断(Ctrl+C / kill)时 abort;长启动的 setup 应观察它提前退出。 */
     readonly signal: AbortSignal;
-    /**
-     * 写入本 Run 的 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`，
-     * 且不留下部分文件。不影响判定、评分或指纹。形状与归属语义见
-     * docs/feature/record/architecture.md#通用自定义事实。
-     */
-    fact(key: string, value: string | number | boolean): void;
 }
 /** Shared lifecycle callback shape for author and Experiment Plugin hooks. */
 export type ExperimentHook = (ctx: ExperimentHookContext) => void | Promise<void>;
@@ -960,7 +952,7 @@ export interface EvalDescriptor {
 }
 export interface Config {
     /** view/show 的项目默认报告。 */
-    report?: Report;
+    report?: ReportDefinition;
     /** view 的 host-owned closed visual token declaration. */
     theme?: ThemeDefinition;
     /**
@@ -997,7 +989,9 @@ export interface Config {
     /**
      * 内置价格表(`o11y/prices.json`)之上的用户覆盖 / 补充,按 model 查(见 Observability
      * · 用量与成本)。key 支持精确 model 名或 `provider/*` 通配(自托管/网关折扣按 provider 批量覆盖);
-     * 精确 key 优先于通配。只在没有网关实测成本(`usage.costUSD`)时才会用到——实测优先于估算恒成立。
+     * 精确 key 优先于通配。pricing 只驱动 `estimatedCostUSD` 的估算(`estimateCost`),与
+     * `usage.costUSD`(网关实测)无关——两者独立并存,互不兜底。它是 runtime/config 价目表,
+     * 不是 Report 的成本投影:Report 不消费该字段(Report 侧使用自己的 PricingProfile)。
      */
     pricing?: globalThis.Record<string, PriceOverride>;
 }
@@ -1086,25 +1080,6 @@ export interface AgentRun {
      *  生命周期链上排在抛出点声明之后;产出的空间轴由止损闸在 attempt 封口消费。 */
     readonly classifyFailure?: AttemptFailureClassifier;
 }
-/**
- * Linked plugin writes enter the Evaluation Record contract as opaque typed
- * producer values. The Runner never sees attachment names, payloads, or blob
- * paths; the generic writer retains that authority.
- */
-export interface RunnerRecordAttachmentProducers<Error = never, Requirements = never> {
-    readonly runWrites?: (input: {
-        readonly run: AgentRun;
-        readonly evals: readonly DiscoveredEval[];
-    }) => readonly RecordAttachmentWrite<"run", Error, Requirements>[];
-    readonly attemptWrites?: (input: {
-        readonly attempt: Attempt;
-        /** The already sealed runner result; its source snapshot is historical input, never a Record value. */
-        readonly result: EvalResult;
-        readonly sealed: SealedAttemptAssertions;
-        /** Convenience view of the exact material captured before result sealing. */
-        readonly sources: readonly SourceArtifact[];
-    }) => readonly RecordAttachmentWrite<"attempt", Error, Requirements>[];
-}
 export interface RunOptions<RecordError = never, RecordRequirements = never> {
     config: Config;
     evals: readonly DiscoveredEval[];
@@ -1119,8 +1094,16 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     rerun?: "failed" | "all";
     /** `--accept` 本次授权跨过的差异 selector(`config:<字段路径>` 等)。 */
     accept?: readonly string[];
-    /** 结果根目录(.niceeval;留存注册表 `.niceeval/sandboxes/` 挂在它下面)。省略 = cwd/.niceeval。 */
-    niceevalRoot?: string;
+    /**
+     * 本地协调根（默认 `cwd/.niceeval`）。session、execution lock、teardown 登记和
+     * kept-sandbox registry 都在这里；它不是 portable Record 的一部分。
+     */
+    coordinationRoot?: string;
+    /**
+     * 已签发的实际 portable Record root。Record lease sidecar 由这个 root 推导到
+     * `.niceeval/coordination/records/<recordKey>`，不能由 Runner 的执行协调目录代替。
+     */
+    recordRoot: RecordRoot;
     /** CLI 为 `niceeval exp` 提供的持久 Session 索引；只观察调度事件，不参与锁/闸判定。 */
     session?: import("./session.cjs").SessionTracker;
     /**
@@ -1145,8 +1128,6 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     /** Run 级 Sandbox 镜像 lookup/build 并发；省略时安全默认 2。 */
     maxBuildConcurrency?: number;
     signal?: AbortSignal;
-    /** Linked plugin RecordAttachment producers for this invocation. */
-    recordAttachments?: RunnerRecordAttachmentProducers<RecordError, RecordRequirements>;
     /**
      * 非沙箱 tracing agent 的 run 级共享 OTLP 接收池(runEvals 创建并回收;
      * 每个 agent 一个 receiver,attempt 之间共享 —— 被测应用是长驻进程,端点不能随 attempt 换)。
@@ -1328,16 +1309,13 @@ export interface FailureDetail {
     code?: string;
     /** 完整时间归属；attempt 形态同时投影上面的 phase，run 形态保留共享 timing node。 */
     origin?: TimingOrigin;
-    /** 该 attempt 的 `AttemptRecord.facts` 键数；缺失或为空对象时省略。结束反馈的 FAILURES 面板
-     *  只据此给一条行内提示(有才提示),完整键值表留给 `niceeval show @<locator>`。 */
-    factsCount?: number;
 }
 /** 带发生时间的失败通知；复用失败以 FailureDetail 静态进入 plan，不伪装成刚发生的事件。 */
 export interface FailureNotice extends FailureDetail {
     at: number;
 }
 /**
- * 去重后的诊断通知(warning/error):相同 `key` 的诊断只保留一条,`count` 累加受影响次数
+ * 去重后的即时通知(info/warning/error):相同 `key` 的通知只保留一条,`count` 累加受影响次数
  *(见 docs/feature/experiments/cli.md「什么动态更新,什么逐条追加」的去重规则)。
  * `data` 携带结构化字段(如 budget 的 experimentId/spent/unstarted),renderer 直接读取,
  * 不解析 `message`(`message` 只是 human 展示用的一句话)。
@@ -1348,13 +1326,15 @@ export interface FailureNotice extends FailureDetail {
  * profile 的 renderer 共用这一个常量,谁都不在自己这边再写一遍字面量。
  */
 export declare const HALT_DIAGNOSTIC_CODE = "dispatch-halted";
+export declare const COORDINATION_RECOVERED_CODE = "coordination-recovered";
+export type DiagnosticSeverity = "info" | "warning" | "error";
 export interface DiagnosticNotice {
     at: number;
     key: string;
-    /** 对外的稳定词法(`--json` 的 `warning.code`、human 诊断行标题);省略 = 与 `key` 相同。
+    /** 对外的稳定词法(`--json` 的 notice/warning `code`、human 通知行标题);省略 = 与 `key` 相同。
      *  `key` 可以把折叠身份(experimentId / evalId)编进去,`code` 恒是干净字面量。 */
     code?: string;
-    severity: "warning" | "error";
+    severity: DiagnosticSeverity;
     message: string;
     /** 相同 key 累计出现的次数,由 reducer 去重时递增。 */
     count: number;
@@ -1423,6 +1403,7 @@ export interface RunFeedbackState {
     elapsedMs: number;
     /** 仅本次实际派发 attempt 的 token；carry 结果的历史 usage 不进入这里。 */
     newTokenCount?: number;
+    /** 仅本次实际派发 attempt 的 `estimatedCostUSD` 累计(价目表估算口径,与 newTokenCount 同口径);observed cost 不进入这里。 */
     estimatedCostUSD?: number;
     active: ReadonlyMap<AttemptKey, ActiveAttempt>;
     /** 在飞的 judge 预检运行级行(见 `DurableFeedbackEvent` 的 "precheck" 变体):`started` 置位、
@@ -1507,6 +1488,7 @@ export type AttemptLifecycleEvent = {
     verdict: Verdict;
     /** 本次 attempt 的输入 + 输出 token；缺失表示 provider 未报告。 */
     tokenCount?: number;
+    /** 本次 attempt 的价目表估算成本(`EvalResult.estimatedCostUSD` 口径);observed cost 不携带。 */
     estimatedCostUSD?: number;
 } | {
     type: "attempt:early-exit";
@@ -1562,7 +1544,7 @@ export type DurableFeedbackEvent = {
     key: string;
     /** 对外稳定词法(见 `DiagnosticNotice.code`);省略 = 与 `key` 相同。 */
     code?: string;
-    severity: "warning" | "error";
+    severity: DiagnosticSeverity;
     message: string;
     /** attempt 级诊断的归属身份。运行级诊断(实验闸 / eval 闸这类不属于任何单条 attempt 的
      *  事实)不许伪造 identity——它们的 experimentId / evalId 走 `data` 的同名字段,

package/dist/runner/types.d.mts

@@ -10,12 +10,11 @@ import type { EvaluationFactResult, DiffArtifact, JudgeConfig, JudgeDeclaration,
 import type { ScoreTestContext, TestContext } from "../context/types.mjs";
 import type { CapturedEvalSource } from "./eval-source.mjs";
 import type { AttemptLocator } from "../attempt-locator.mjs";
-import type { RecordAttachmentWrite } from "../record/attachment/index.mjs";
-import type { SealedAttemptAssertions } from "../assertions/api.mjs";
+import type { RecordRoot } from "../record/platform/root.mjs";
 import type { CurrentReusedAttemptReadback } from "./reuse-readback.mjs";
 import type { PluginInstance, PluginOnUnavailable } from "../plugin/contracts.mjs";
-import type { Report } from "../report/index.mjs";
-import type { ThemeDefinition } from "../report/host/theme.mjs";
+import type { ReportDefinition } from "../report/index.mjs";
+import type { ThemeDefinition } from "../report/theme.mjs";
 /**
  * 解析后运行配置的**穷尽可序列化投影**——记录这次运行实际生效的值,不是原始 `ExperimentDef`
  * (函数与 hooks 无法忠实落盘,存「原样」只能存谎)。`model` 与 `agent` 只在快照顶层存在,
@@ -152,6 +151,8 @@ export interface SandboxBuildRecord {
 /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/record/architecture.md)。 */
 export interface PhaseTiming {
     name: LifecyclePhase;
+    /** 相对本 attempt 单调时钟起点的阶段起点；与 children 使用同一量化时钟。 */
+    startOffsetMs: number;
     /** 阶段耗时;失败阶段计到抛错或超时中断时。 */
     durationMs: number;
     /** 该阶段抛错或被超时中断。主链至多一条,其后无主链条目;收尾阶段各自独立标记,不改判定。 */
@@ -366,17 +367,16 @@ export interface EvalResult {
     /** 自动重试吸收的物理 send 失败，按发生顺序完整保留。 */
     retryAttempts?: RetryAttemptRecord[];
     usage?: Usage;
+    /**
+     * 价目表估算成本,恒等于 `estimateCost(model, usage, config.pricing)`——永远独立计算,
+     * 与 `usage.costUSD`(网关/adapter 显式回报的 observed 成本)是两个并存事实,互不覆盖、
+     * 互不兜底:observed 存在时 estimatedCostUSD 也照常按 runtime/config price table 估算。
+     */
     estimatedCostUSD?: number;
     /** 使 attempt 进入 `errored` 的唯一致命执行错误(结构化);默认报告显示 `error.message` 一层原因。 */
     error?: AttemptError;
     /** 本 attempt 的诊断(与 verdict 独立);teardown / cleanup 失败等挂在这里,不改判定。 */
     diagnostics?: readonly DiagnosticRecord[];
-    /**
-     * sandbox hook / agent setup·send·teardown 经 `ctx.fact()` 上报的运行事实(同 attempt 内
-     * 后写覆盖先写)。中性环境观测,不参与 verdict / 评分 / 指纹。见
-     * docs/feature/record/architecture.md#facts运行事实。
-     */
-    facts?: globalThis.Record<string, string | number | boolean>;
     /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/record/architecture.md)。 */
     phases?: PhaseTiming[];
     skipReason?: string;
@@ -484,7 +484,9 @@ export interface InvocationSummary {
     /** 环境、超时、adapter、agent runtime 等执行错误数量;与 failed 互斥。 */
     errored: number;
     durationMs: number;
+    /** 本次 Invocation fresh 结果的 token 汇总(只折叠 input/outputTokens);observed costUSD 不在这里汇总,逐条留在 `results[].usage.costUSD`。 */
     usage?: Usage;
+    /** 本次 Invocation fresh 结果的 `estimatedCostUSD` 累计(价目表估算口径,见 EvalResult.estimatedCostUSD);observed cost 不进入本字段。 */
     estimatedCostUSD?: number;
     /** Current Record readbacks adopted by this invocation; these are never recreated EvalResults. */
     reusedAttempts: readonly CurrentReusedAttemptReadback[];
@@ -592,8 +594,6 @@ export type ReporterEvent = {
     reusedAttempts: readonly CurrentReusedAttemptReadback[];
     /** 该 Experiment 域产生的全部诊断;空集合传空数组,不省略字段。 */
     diagnostics: readonly DiagnosticRecord[];
-    /** 该 Experiment 域经 `ctx.fact()` 累计的运行事实(experiment.setup / .teardown,含收尾自愈路径);省略 = 没有上报过。 */
-    facts?: Readonly<globalThis.Record<string, string | number | boolean>>;
     /** Run 级共享工作时间树;与 completedAt 同批封口。省略 = 本 Run 没有共享 activity。 */
     timings?: readonly TimingActivity[];
     /** 共享构建 provenance;与 timings 经 timingNodeId 关联。省略 = 本 Run 没有查询或构建过 BuildKey。 */
@@ -785,14 +785,6 @@ export interface ExperimentHookContext extends ScopedFeedback {
     readonly selectedEvalIds: readonly string[];
     /** 用户中断(Ctrl+C / kill)时 abort;长启动的 setup 应观察它提前退出。 */
     readonly signal: AbortSignal;
-    /**
-     * 写入本 Run 的 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`，
-     * 且不留下部分文件。不影响判定、评分或指纹。形状与归属语义见
-     * docs/feature/record/architecture.md#通用自定义事实。
-     */
-    fact(key: string, value: string | number | boolean): void;
 }
 /** Shared lifecycle callback shape for author and Experiment Plugin hooks. */
 export type ExperimentHook = (ctx: ExperimentHookContext) => void | Promise<void>;
@@ -960,7 +952,7 @@ export interface EvalDescriptor {
 }
 export interface Config {
     /** view/show 的项目默认报告。 */
-    report?: Report;
+    report?: ReportDefinition;
     /** view 的 host-owned closed visual token declaration. */
     theme?: ThemeDefinition;
     /**
@@ -997,7 +989,9 @@ export interface Config {
     /**
      * 内置价格表(`o11y/prices.json`)之上的用户覆盖 / 补充,按 model 查(见 Observability
      * · 用量与成本)。key 支持精确 model 名或 `provider/*` 通配(自托管/网关折扣按 provider 批量覆盖);
-     * 精确 key 优先于通配。只在没有网关实测成本(`usage.costUSD`)时才会用到——实测优先于估算恒成立。
+     * 精确 key 优先于通配。pricing 只驱动 `estimatedCostUSD` 的估算(`estimateCost`),与
+     * `usage.costUSD`(网关实测)无关——两者独立并存,互不兜底。它是 runtime/config 价目表,
+     * 不是 Report 的成本投影:Report 不消费该字段(Report 侧使用自己的 PricingProfile)。
      */
     pricing?: globalThis.Record<string, PriceOverride>;
 }
@@ -1086,25 +1080,6 @@ export interface AgentRun {
      *  生命周期链上排在抛出点声明之后;产出的空间轴由止损闸在 attempt 封口消费。 */
     readonly classifyFailure?: AttemptFailureClassifier;
 }
-/**
- * Linked plugin writes enter the Evaluation Record contract as opaque typed
- * producer values. The Runner never sees attachment names, payloads, or blob
- * paths; the generic writer retains that authority.
- */
-export interface RunnerRecordAttachmentProducers<Error = never, Requirements = never> {
-    readonly runWrites?: (input: {
-        readonly run: AgentRun;
-        readonly evals: readonly DiscoveredEval[];
-    }) => readonly RecordAttachmentWrite<"run", Error, Requirements>[];
-    readonly attemptWrites?: (input: {
-        readonly attempt: Attempt;
-        /** The already sealed runner result; its source snapshot is historical input, never a Record value. */
-        readonly result: EvalResult;
-        readonly sealed: SealedAttemptAssertions;
-        /** Convenience view of the exact material captured before result sealing. */
-        readonly sources: readonly SourceArtifact[];
-    }) => readonly RecordAttachmentWrite<"attempt", Error, Requirements>[];
-}
 export interface RunOptions<RecordError = never, RecordRequirements = never> {
     config: Config;
     evals: readonly DiscoveredEval[];
@@ -1119,8 +1094,16 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     rerun?: "failed" | "all";
     /** `--accept` 本次授权跨过的差异 selector(`config:<字段路径>` 等)。 */
     accept?: readonly string[];
-    /** 结果根目录(.niceeval;留存注册表 `.niceeval/sandboxes/` 挂在它下面)。省略 = cwd/.niceeval。 */
-    niceevalRoot?: string;
+    /**
+     * 本地协调根（默认 `cwd/.niceeval`）。session、execution lock、teardown 登记和
+     * kept-sandbox registry 都在这里；它不是 portable Record 的一部分。
+     */
+    coordinationRoot?: string;
+    /**
+     * 已签发的实际 portable Record root。Record lease sidecar 由这个 root 推导到
+     * `.niceeval/coordination/records/<recordKey>`，不能由 Runner 的执行协调目录代替。
+     */
+    recordRoot: RecordRoot;
     /** CLI 为 `niceeval exp` 提供的持久 Session 索引；只观察调度事件，不参与锁/闸判定。 */
     session?: import("./session.mjs").SessionTracker;
     /**
@@ -1145,8 +1128,6 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     /** Run 级 Sandbox 镜像 lookup/build 并发；省略时安全默认 2。 */
     maxBuildConcurrency?: number;
     signal?: AbortSignal;
-    /** Linked plugin RecordAttachment producers for this invocation. */
-    recordAttachments?: RunnerRecordAttachmentProducers<RecordError, RecordRequirements>;
     /**
      * 非沙箱 tracing agent 的 run 级共享 OTLP 接收池(runEvals 创建并回收;
      * 每个 agent 一个 receiver,attempt 之间共享 —— 被测应用是长驻进程,端点不能随 attempt 换)。
@@ -1328,16 +1309,13 @@ export interface FailureDetail {
     code?: string;
     /** 完整时间归属；attempt 形态同时投影上面的 phase，run 形态保留共享 timing node。 */
     origin?: TimingOrigin;
-    /** 该 attempt 的 `AttemptRecord.facts` 键数；缺失或为空对象时省略。结束反馈的 FAILURES 面板
-     *  只据此给一条行内提示(有才提示),完整键值表留给 `niceeval show @<locator>`。 */
-    factsCount?: number;
 }
 /** 带发生时间的失败通知；复用失败以 FailureDetail 静态进入 plan，不伪装成刚发生的事件。 */
 export interface FailureNotice extends FailureDetail {
     at: number;
 }
 /**
- * 去重后的诊断通知(warning/error):相同 `key` 的诊断只保留一条,`count` 累加受影响次数
+ * 去重后的即时通知(info/warning/error):相同 `key` 的通知只保留一条,`count` 累加受影响次数
  *(见 docs/feature/experiments/cli.md「什么动态更新,什么逐条追加」的去重规则)。
  * `data` 携带结构化字段(如 budget 的 experimentId/spent/unstarted),renderer 直接读取,
  * 不解析 `message`(`message` 只是 human 展示用的一句话)。
@@ -1348,13 +1326,15 @@ export interface FailureNotice extends FailureDetail {
  * profile 的 renderer 共用这一个常量,谁都不在自己这边再写一遍字面量。
  */
 export declare const HALT_DIAGNOSTIC_CODE = "dispatch-halted";
+export declare const COORDINATION_RECOVERED_CODE = "coordination-recovered";
+export type DiagnosticSeverity = "info" | "warning" | "error";
 export interface DiagnosticNotice {
     at: number;
     key: string;
-    /** 对外的稳定词法(`--json` 的 `warning.code`、human 诊断行标题);省略 = 与 `key` 相同。
+    /** 对外的稳定词法(`--json` 的 notice/warning `code`、human 通知行标题);省略 = 与 `key` 相同。
      *  `key` 可以把折叠身份(experimentId / evalId)编进去,`code` 恒是干净字面量。 */
     code?: string;
-    severity: "warning" | "error";
+    severity: DiagnosticSeverity;
     message: string;
     /** 相同 key 累计出现的次数,由 reducer 去重时递增。 */
     count: number;
@@ -1423,6 +1403,7 @@ export interface RunFeedbackState {
     elapsedMs: number;
     /** 仅本次实际派发 attempt 的 token；carry 结果的历史 usage 不进入这里。 */
     newTokenCount?: number;
+    /** 仅本次实际派发 attempt 的 `estimatedCostUSD` 累计(价目表估算口径,与 newTokenCount 同口径);observed cost 不进入这里。 */
     estimatedCostUSD?: number;
     active: ReadonlyMap<AttemptKey, ActiveAttempt>;
     /** 在飞的 judge 预检运行级行(见 `DurableFeedbackEvent` 的 "precheck" 变体):`started` 置位、
@@ -1507,6 +1488,7 @@ export type AttemptLifecycleEvent = {
     verdict: Verdict;
     /** 本次 attempt 的输入 + 输出 token；缺失表示 provider 未报告。 */
     tokenCount?: number;
+    /** 本次 attempt 的价目表估算成本(`EvalResult.estimatedCostUSD` 口径);observed cost 不携带。 */
     estimatedCostUSD?: number;
 } | {
     type: "attempt:early-exit";
@@ -1562,7 +1544,7 @@ export type DurableFeedbackEvent = {
     key: string;
     /** 对外稳定词法(见 `DiagnosticNotice.code`);省略 = 与 `key` 相同。 */
     code?: string;
-    severity: "warning" | "error";
+    severity: DiagnosticSeverity;
     message: string;
     /** attempt 级诊断的归属身份。运行级诊断(实验闸 / eval 闸这类不属于任何单条 attempt 的
      *  事实)不许伪造 identity——它们的 experimentId / evalId 走 `data` 的同名字段,

package/dist/runner/types.d.ts

@@ -10,12 +10,11 @@ import type { EvaluationFactResult, DiffArtifact, JudgeConfig, JudgeDeclaration,
 import type { ScoreTestContext, TestContext } from "../context/types.js";
 import type { CapturedEvalSource } from "./eval-source.js";
 import type { AttemptLocator } from "../attempt-locator.js";
-import type { RecordAttachmentWrite } from "../record/attachment/index.js";
-import type { SealedAttemptAssertions } from "../assertions/api.js";
+import type { RecordRoot } from "../record/platform/root.js";
 import type { CurrentReusedAttemptReadback } from "./reuse-readback.js";
 import type { PluginInstance, PluginOnUnavailable } from "../plugin/contracts.js";
-import type { Report } from "../report/index.js";
-import type { ThemeDefinition } from "../report/host/theme.js";
+import type { ReportDefinition } from "../report/index.js";
+import type { ThemeDefinition } from "../report/theme.js";
 /**
  * 解析后运行配置的**穷尽可序列化投影**——记录这次运行实际生效的值,不是原始 `ExperimentDef`
  * (函数与 hooks 无法忠实落盘,存「原样」只能存谎)。`model` 与 `agent` 只在快照顶层存在,
@@ -152,6 +151,8 @@ export interface SandboxBuildRecord {
 /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/record/architecture.md)。 */
 export interface PhaseTiming {
     name: LifecyclePhase;
+    /** 相对本 attempt 单调时钟起点的阶段起点；与 children 使用同一量化时钟。 */
+    startOffsetMs: number;
     /** 阶段耗时;失败阶段计到抛错或超时中断时。 */
     durationMs: number;
     /** 该阶段抛错或被超时中断。主链至多一条,其后无主链条目;收尾阶段各自独立标记,不改判定。 */
@@ -366,17 +367,16 @@ export interface EvalResult {
     /** 自动重试吸收的物理 send 失败，按发生顺序完整保留。 */
     retryAttempts?: RetryAttemptRecord[];
     usage?: Usage;
+    /**
+     * 价目表估算成本,恒等于 `estimateCost(model, usage, config.pricing)`——永远独立计算,
+     * 与 `usage.costUSD`(网关/adapter 显式回报的 observed 成本)是两个并存事实,互不覆盖、
+     * 互不兜底:observed 存在时 estimatedCostUSD 也照常按 runtime/config price table 估算。
+     */
     estimatedCostUSD?: number;
     /** 使 attempt 进入 `errored` 的唯一致命执行错误(结构化);默认报告显示 `error.message` 一层原因。 */
     error?: AttemptError;
     /** 本 attempt 的诊断(与 verdict 独立);teardown / cleanup 失败等挂在这里,不改判定。 */
     diagnostics?: readonly DiagnosticRecord[];
-    /**
-     * sandbox hook / agent setup·send·teardown 经 `ctx.fact()` 上报的运行事实(同 attempt 内
-     * 后写覆盖先写)。中性环境观测,不参与 verdict / 评分 / 指纹。见
-     * docs/feature/record/architecture.md#facts运行事实。
-     */
-    facts?: globalThis.Record<string, string | number | boolean>;
     /** Runner 阶段计时,按执行顺序;只记录实际发生的阶段(见 docs/feature/record/architecture.md)。 */
     phases?: PhaseTiming[];
     skipReason?: string;
@@ -484,7 +484,9 @@ export interface InvocationSummary {
     /** 环境、超时、adapter、agent runtime 等执行错误数量;与 failed 互斥。 */
     errored: number;
     durationMs: number;
+    /** 本次 Invocation fresh 结果的 token 汇总(只折叠 input/outputTokens);observed costUSD 不在这里汇总,逐条留在 `results[].usage.costUSD`。 */
     usage?: Usage;
+    /** 本次 Invocation fresh 结果的 `estimatedCostUSD` 累计(价目表估算口径,见 EvalResult.estimatedCostUSD);observed cost 不进入本字段。 */
     estimatedCostUSD?: number;
     /** Current Record readbacks adopted by this invocation; these are never recreated EvalResults. */
     reusedAttempts: readonly CurrentReusedAttemptReadback[];
@@ -592,8 +594,6 @@ export type ReporterEvent = {
     reusedAttempts: readonly CurrentReusedAttemptReadback[];
     /** 该 Experiment 域产生的全部诊断;空集合传空数组,不省略字段。 */
     diagnostics: readonly DiagnosticRecord[];
-    /** 该 Experiment 域经 `ctx.fact()` 累计的运行事实(experiment.setup / .teardown,含收尾自愈路径);省略 = 没有上报过。 */
-    facts?: Readonly<globalThis.Record<string, string | number | boolean>>;
     /** Run 级共享工作时间树;与 completedAt 同批封口。省略 = 本 Run 没有共享 activity。 */
     timings?: readonly TimingActivity[];
     /** 共享构建 provenance;与 timings 经 timingNodeId 关联。省略 = 本 Run 没有查询或构建过 BuildKey。 */
@@ -785,14 +785,6 @@ export interface ExperimentHookContext extends ScopedFeedback {
     readonly selectedEvalIds: readonly string[];
     /** 用户中断(Ctrl+C / kill)时 abort;长启动的 setup 应观察它提前退出。 */
     readonly signal: AbortSignal;
-    /**
-     * 写入本 Run 的 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`，
-     * 且不留下部分文件。不影响判定、评分或指纹。形状与归属语义见
-     * docs/feature/record/architecture.md#通用自定义事实。
-     */
-    fact(key: string, value: string | number | boolean): void;
 }
 /** Shared lifecycle callback shape for author and Experiment Plugin hooks. */
 export type ExperimentHook = (ctx: ExperimentHookContext) => void | Promise<void>;
@@ -960,7 +952,7 @@ export interface EvalDescriptor {
 }
 export interface Config {
     /** view/show 的项目默认报告。 */
-    report?: Report;
+    report?: ReportDefinition;
     /** view 的 host-owned closed visual token declaration. */
     theme?: ThemeDefinition;
     /**
@@ -997,7 +989,9 @@ export interface Config {
     /**
      * 内置价格表(`o11y/prices.json`)之上的用户覆盖 / 补充,按 model 查(见 Observability
      * · 用量与成本)。key 支持精确 model 名或 `provider/*` 通配(自托管/网关折扣按 provider 批量覆盖);
-     * 精确 key 优先于通配。只在没有网关实测成本(`usage.costUSD`)时才会用到——实测优先于估算恒成立。
+     * 精确 key 优先于通配。pricing 只驱动 `estimatedCostUSD` 的估算(`estimateCost`),与
+     * `usage.costUSD`(网关实测)无关——两者独立并存,互不兜底。它是 runtime/config 价目表,
+     * 不是 Report 的成本投影:Report 不消费该字段(Report 侧使用自己的 PricingProfile)。
      */
     pricing?: globalThis.Record<string, PriceOverride>;
 }
@@ -1086,25 +1080,6 @@ export interface AgentRun {
      *  生命周期链上排在抛出点声明之后;产出的空间轴由止损闸在 attempt 封口消费。 */
     readonly classifyFailure?: AttemptFailureClassifier;
 }
-/**
- * Linked plugin writes enter the Evaluation Record contract as opaque typed
- * producer values. The Runner never sees attachment names, payloads, or blob
- * paths; the generic writer retains that authority.
- */
-export interface RunnerRecordAttachmentProducers<Error = never, Requirements = never> {
-    readonly runWrites?: (input: {
-        readonly run: AgentRun;
-        readonly evals: readonly DiscoveredEval[];
-    }) => readonly RecordAttachmentWrite<"run", Error, Requirements>[];
-    readonly attemptWrites?: (input: {
-        readonly attempt: Attempt;
-        /** The already sealed runner result; its source snapshot is historical input, never a Record value. */
-        readonly result: EvalResult;
-        readonly sealed: SealedAttemptAssertions;
-        /** Convenience view of the exact material captured before result sealing. */
-        readonly sources: readonly SourceArtifact[];
-    }) => readonly RecordAttachmentWrite<"attempt", Error, Requirements>[];
-}
 export interface RunOptions<RecordError = never, RecordRequirements = never> {
     config: Config;
     evals: readonly DiscoveredEval[];
@@ -1119,8 +1094,16 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     rerun?: "failed" | "all";
     /** `--accept` 本次授权跨过的差异 selector(`config:<字段路径>` 等)。 */
     accept?: readonly string[];
-    /** 结果根目录(.niceeval;留存注册表 `.niceeval/sandboxes/` 挂在它下面)。省略 = cwd/.niceeval。 */
-    niceevalRoot?: string;
+    /**
+     * 本地协调根（默认 `cwd/.niceeval`）。session、execution lock、teardown 登记和
+     * kept-sandbox registry 都在这里；它不是 portable Record 的一部分。
+     */
+    coordinationRoot?: string;
+    /**
+     * 已签发的实际 portable Record root。Record lease sidecar 由这个 root 推导到
+     * `.niceeval/coordination/records/<recordKey>`，不能由 Runner 的执行协调目录代替。
+     */
+    recordRoot: RecordRoot;
     /** CLI 为 `niceeval exp` 提供的持久 Session 索引；只观察调度事件，不参与锁/闸判定。 */
     session?: import("./session.js").SessionTracker;
     /**
@@ -1145,8 +1128,6 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     /** Run 级 Sandbox 镜像 lookup/build 并发；省略时安全默认 2。 */
     maxBuildConcurrency?: number;
     signal?: AbortSignal;
-    /** Linked plugin RecordAttachment producers for this invocation. */
-    recordAttachments?: RunnerRecordAttachmentProducers<RecordError, RecordRequirements>;
     /**
      * 非沙箱 tracing agent 的 run 级共享 OTLP 接收池(runEvals 创建并回收;
      * 每个 agent 一个 receiver,attempt 之间共享 —— 被测应用是长驻进程,端点不能随 attempt 换)。
@@ -1328,16 +1309,13 @@ export interface FailureDetail {
     code?: string;
     /** 完整时间归属；attempt 形态同时投影上面的 phase，run 形态保留共享 timing node。 */
     origin?: TimingOrigin;
-    /** 该 attempt 的 `AttemptRecord.facts` 键数；缺失或为空对象时省略。结束反馈的 FAILURES 面板
-     *  只据此给一条行内提示(有才提示),完整键值表留给 `niceeval show @<locator>`。 */
-    factsCount?: number;
 }
 /** 带发生时间的失败通知；复用失败以 FailureDetail 静态进入 plan，不伪装成刚发生的事件。 */
 export interface FailureNotice extends FailureDetail {
     at: number;
 }
 /**
- * 去重后的诊断通知(warning/error):相同 `key` 的诊断只保留一条,`count` 累加受影响次数
+ * 去重后的即时通知(info/warning/error):相同 `key` 的通知只保留一条,`count` 累加受影响次数
  *(见 docs/feature/experiments/cli.md「什么动态更新,什么逐条追加」的去重规则)。
  * `data` 携带结构化字段(如 budget 的 experimentId/spent/unstarted),renderer 直接读取,
  * 不解析 `message`(`message` 只是 human 展示用的一句话)。
@@ -1348,13 +1326,15 @@ export interface FailureNotice extends FailureDetail {
  * profile 的 renderer 共用这一个常量,谁都不在自己这边再写一遍字面量。
  */
 export declare const HALT_DIAGNOSTIC_CODE = "dispatch-halted";
+export declare const COORDINATION_RECOVERED_CODE = "coordination-recovered";
+export type DiagnosticSeverity = "info" | "warning" | "error";
 export interface DiagnosticNotice {
     at: number;
     key: string;
-    /** 对外的稳定词法(`--json` 的 `warning.code`、human 诊断行标题);省略 = 与 `key` 相同。
+    /** 对外的稳定词法(`--json` 的 notice/warning `code`、human 通知行标题);省略 = 与 `key` 相同。
      *  `key` 可以把折叠身份(experimentId / evalId)编进去,`code` 恒是干净字面量。 */
     code?: string;
-    severity: "warning" | "error";
+    severity: DiagnosticSeverity;
     message: string;
     /** 相同 key 累计出现的次数,由 reducer 去重时递增。 */
     count: number;
@@ -1423,6 +1403,7 @@ export interface RunFeedbackState {
     elapsedMs: number;
     /** 仅本次实际派发 attempt 的 token；carry 结果的历史 usage 不进入这里。 */
     newTokenCount?: number;
+    /** 仅本次实际派发 attempt 的 `estimatedCostUSD` 累计(价目表估算口径,与 newTokenCount 同口径);observed cost 不进入这里。 */
     estimatedCostUSD?: number;
     active: ReadonlyMap<AttemptKey, ActiveAttempt>;
     /** 在飞的 judge 预检运行级行(见 `DurableFeedbackEvent` 的 "precheck" 变体):`started` 置位、
@@ -1507,6 +1488,7 @@ export type AttemptLifecycleEvent = {
     verdict: Verdict;
     /** 本次 attempt 的输入 + 输出 token；缺失表示 provider 未报告。 */
     tokenCount?: number;
+    /** 本次 attempt 的价目表估算成本(`EvalResult.estimatedCostUSD` 口径);observed cost 不携带。 */
     estimatedCostUSD?: number;
 } | {
     type: "attempt:early-exit";
@@ -1562,7 +1544,7 @@ export type DurableFeedbackEvent = {
     key: string;
     /** 对外稳定词法(见 `DiagnosticNotice.code`);省略 = 与 `key` 相同。 */
     code?: string;
-    severity: "warning" | "error";
+    severity: DiagnosticSeverity;
     message: string;
     /** attempt 级诊断的归属身份。运行级诊断(实验闸 / eval 闸这类不属于任何单条 attempt 的
      *  事实)不许伪造 identity——它们的 experimentId / evalId 走 `data` 的同名字段,