niceeval 0.12.1 → 0.12.2-canary.31

package/dist/runner/types.d.ts

@@ -1,17 +1,21 @@
-import type { JsonValue, LocalizedText, ScopedFeedback, SourceArtifact, Verdict } from "../shared/types.ts";
-import type { AttemptFailureClassifier } from "../shared/failure-class.ts";
-import type { O11ySummary, StreamEvent, TraceSpan, Truncation, Usage } from "../o11y/types.ts";
-import type { Agent, AgentSetupManifest } from "../agents/types.ts";
-import type { SandboxLayer } from "../sandbox/layer.ts";
-import type { LinkedRunPlan } from "../sandbox/plan.ts";
-import type { BuildKey } from "../sandbox/identity.ts";
-import type { AssertionResult, DiffArtifact, JudgeConfig, PrimaryAssertionSummary, ScoreEntry } from "../assertions/types.ts";
-import type { ScoreTestContext, TestContext } from "../context/types.ts";
-import type { CapturedEvalSource } from "./eval-source.ts";
-import type { AttemptLocator } from "../record/locator.ts";
-import type { EvalManifest, RunManifests } from "../record/manifest.ts";
-import type { ReportDefinition } from "../report/definition/report.ts";
-import type { ThemeDefinition } from "../report/theme.ts";
+import type { Effect } from "effect";
+import type { JsonValue, LocalizedText, ScopedFeedback, SourceArtifact, Verdict } from "../shared/types.js";
+import type { AttemptFailureClassifier } from "../shared/failure-class.js";
+import type { O11ySummary, StreamEvent, TraceSpan, Truncation, Usage } from "../o11y/types.js";
+import type { Agent, AgentSetupManifest } from "../agents/types.js";
+import type { SandboxLayer } from "../sandbox/layer.js";
+import type { LinkedRunPlan } from "../sandbox/plan.js";
+import type { BuildKey } from "../sandbox/identity.js";
+import type { EvaluationFactResult, DiffArtifact, JudgeConfig, JudgeDeclaration, ResolvedJudgeConfig, PrimaryFactSummary, ScoreFactAttemptOutcome, ScoreFactUseResult, VerdictFactUseResult } from "../assertions/types.js";
+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 { 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";
 /**
  * 解析后运行配置的**穷尽可序列化投影**——记录这次运行实际生效的值,不是原始 `ExperimentDef`
  * (函数与 hooks 无法忠实落盘,存「原样」只能存谎)。`model` 与 `agent` 只在快照顶层存在,
@@ -23,25 +27,21 @@ export interface ExperimentRunInfo {
     flags?: globalThis.Record<string, JsonValue>;
     /** 报告归类标注(ExperimentDef.labels 原样投影);不透传运行时,不参与可比性配置。 */
     labels?: globalThis.Record<string, string | number>;
+    /** Credential-free Plugin lifecycle behavior projection. */
+    plugins?: JsonValue;
     attempts: number;
     earlyExit: boolean;
     timeoutMs?: number;
     budget?: number;
     maxConcurrency?: number;
-    /** 本次运行解析后实际选中的 eval id 全集——evals 过滤器(含函数形式)的求值结果,不存过滤器本身。 */
-    selectedEvalIds: string[];
-    /** evals 过滤器的指纹(数组内容 / 函数体哈希),供「配置没变」判断;与 selectedEvalIds 一起取代原过滤器。 */
-    evalFilterFingerprint?: string;
     /** Experiment SandboxLayer 的纯数据身份；Direct 也以 command-only 的完整身份记录。 */
     sandboxLayer: JsonValue;
     /** 每个已选择 Eval 的完整 pair-owned physical plan；Direct 也有显式投影。 */
     sandboxPlansByEval: globalThis.Record<string, JsonValue>;
     /** Sandbox 是否在同一次 Run 内复用。 */
     sandboxReuse?: boolean;
-    /** strict 与 judge 是配置身份的一部分，供历史结果重算 configHash。 */
-    strict?: boolean;
-    /** 解析后的 Judge 执行身份；apiKeyEnv 是凭据选择器，不落盘。 */
-    judge?: Pick<JudgeConfig, "model" | "baseUrl" | "timeoutMs">;
+    /** 解析后的 Judge 执行身份；只记录凭据选择器名，不记录凭据。 */
+    judge?: Pick<JudgeConfig, "model" | "baseUrl" | "apiKeyEnv" | "timeoutMs">;
     /**
      * Agent Ensure 与精确配对 installer 的静态身份投影；按声明顺序完整落盘。
      * 实际 artifact digest/platform 属运行 provenance，不进入这里。
@@ -59,7 +59,7 @@ export interface SandboxRunInfo {
  * live 当前步骤都由 Runner 绑定这同一个闭集;author、Adapter 与 provider 不能新增成员。
  * 可扩展的工作计时走开放 activity key,不进本词表。
  */
-export type LifecyclePhase = "judge.precheck" | "experiment.setup" | "experiment.teardown" | "sandbox.queue" | "sandbox.create" | "sandbox.prepare" | "sandbox.prepare.eval" | "sandbox.prepare.experiment" | "agent.ensure" | "workspace.baseline" | "agent.setup" | "telemetry.configure" | "eval.run" | "agent.run" | "workspace.diff" | "assertions.evaluate" | "telemetry.collect" | "agent.teardown" | "sandbox.cleanup" | "sandbox.suspend" | "sandbox.stop";
+export type LifecyclePhase = "judge.precheck" | "experiment.setup" | "experiment.teardown" | "sandbox.queue" | "sandbox.create" | "sandbox.prepare" | "sandbox.prepare.eval" | "sandbox.prepare.group" | "sandbox.prepare.experiment" | "agent.ensure" | "workspace.baseline" | "agent.setup" | "telemetry.configure" | "eval.run" | "agent.run" | "workspace.diff" | "assertions.evaluate" | "telemetry.collect" | "agent.teardown" | "sandbox.cleanup" | "sandbox.suspend" | "sandbox.stop";
 /**
  * 开放的工作计时节点,Run 与 attempt 共用同一形状(见 docs/feature/record/architecture.md
  * 「TimingActivity」)。`key` 是非空、以 `.` 分段的稳定机器 key;未知 key 原样保留并可通用展示。
@@ -288,6 +288,17 @@ export interface AcceptedResult {
     /** 新旧 manifest/config 的完整差异清单。 */
     differences: AcceptedDifference[];
 }
+/** `niceeval exp rename` 写入新结果的来源与身份审计记录。 */
+export interface RenamedResult {
+    /** 被重绑结果原属的 experimentId。 */
+    experimentId: string;
+    /** 被重绑结果在旧结果树中的 locator。 */
+    locator: string;
+    /** 迁移前结果的 fingerprint。 */
+    fingerprint: string;
+    /** 发生重绑的时刻。 */
+    at: string;
+}
 /** 自动重试吸收的一次物理 send 失败；不进入逻辑会话事件流。 */
 export interface RetryAttemptRecord {
     sessionIndex: number;
@@ -322,15 +333,15 @@ export interface EvalResult {
     model?: string;
     verdict: Verdict;
     fingerprint?: string;
+    /** 产生本 Attempt 判定与计分结果的固定求值算法。 */
+    evaluationAlgorithm: EvaluationAlgorithm;
     /** 产出该结果时的 Run 级配置身份。 */
     configHash?: string;
     attempt: number;
     /** 本 attempt 开始的墙钟时刻(ISO);view 按 eval 粒度展示「何时跑的」。 */
     startedAt?: string;
     /**
-     * 不透明的 Attempt 定位符(`@` 前缀短确定性编码,见 `src/record/locator.ts` 的 AttemptLocator),
-     * 由 {runId, evalId, attempt} 身份元组派生。非携带条目由 writer 在落盘时算出;
-     * 携带条目(`--resume` 合入)原样复制上一轮的值,从不按承载它的新 Run 重算。
+     * 不透明的 Attempt 定位符；由完整 durable AttemptId 确定性派生。
      */
     locator?: string;
     /**
@@ -342,18 +353,16 @@ export interface EvalResult {
     durationMs: number;
     /** 自 sandbox.create 起、排除并发排队和收尾的执行耗时；旧记录缺失时携带保守回退 durationMs。 */
     executionMs?: number;
-    assertions: AssertionResult[];
-    /**
-     * 题型:`defineEval` → `"pass"`,`defineScoreEval` → `"points"`,定义期事实,与
-     * `EvalDescriptor.evaluationKind` 同源。省略等价于 `"pass"`——兼容此字段引入前写入的落盘与未声明它的
-     * 第三方 harness(见 docs/feature/record/architecture.md「result.json」)。
-     */
-    evaluationKind?: EvaluationKind;
+    /** The complete native Fact graph, persisted directly in result.json. */
+    factResults: readonly EvaluationFactResult[];
+    factUses: readonly (VerdictFactUseResult | ScoreFactUseResult)[];
+    /** Structured Score Fact outcome for score Eval terminal semantics. */
+    scoreResult?: ScoreFactAttemptOutcome;
     /**
-     * `t.score(label, n)` 的直接给分记录,只在 `evaluationKind: "points"` 时出现;省略等价于空数组。
-     * 与 `assertions[].points` 共同构成分数面(见 docs/feature/experiments/score-points.md)。
+     * 题型:`defineEval` → `"pass"`,`defineScoreEval` → `"score"`,定义期事实,与
+     * `EvalDescriptor.evaluationKind` 同源。schema 18 必填。
      */
-    scoreEntries?: ScoreEntry[];
+    evaluationKind: EvaluationKind;
     /** 自动重试吸收的物理 send 失败，按发生顺序完整保留。 */
     retryAttempts?: RetryAttemptRecord[];
     usage?: Usage;
@@ -382,7 +391,7 @@ export interface EvalResult {
     /**
      * attempt 级聚合的证据覆盖(各 turn 的最差值,unavailable < partial < complete)；必填。
      */
-    evidenceCoverage: import("../agents/types.ts").EvidenceCoverage;
+    evidenceCoverage: import("../agents/types.js").EvidenceCoverage;
     /**
      * 沙箱型 attempt 的执行环境标识:provider 名与实例 id,用于关联 provider 侧日志与留存现场;
      * remote 型 agent 无此字段。`kept` 表示运行收尾时按 --keep-sandbox 留存了沙箱;之后的存活
@@ -420,6 +429,8 @@ export interface EvalResult {
      * 读取旧记录时不做迁移。
      */
     acceptedFrom?: AcceptedResult;
+    /** 实验身份改变但 fingerprint 保持不变时的重绑来源审计。 */
+    renamedFrom?: RenamedResult;
     /**
      * writer 实际写出的按需 artifact 词干列表(词表与全部横切属性单源在
      * docs/feature/record/architecture.md「证据 registry」,如 ["commands", "events", "sources"])。
@@ -455,8 +466,11 @@ export declare const RECORD_FORMAT = "niceeval.results";
  * 旧版快照按格式规则整份判为不兼容并在扫描时列为占位条目,不迁移不降级。
  * `15` = commands.json 的命令退出事实新增 `checked`，区分公开 checked/unchecked 调用；
  * 旧版 commands.json 不做兼容读取。
+ * `18` = Fact/use 原子记录、`evaluationAlgorithm: "fact-use/v3"`；旧格式完全不支持读取。
+ * `renamedFrom` 是可选审计字段，删除运行期选题投影也不改变当前 reader 对旧结果的读取；
+ * 两者都不是破坏性格式变化，因此不递增版本。
  */
-export declare const RECORD_SCHEMA_VERSION = 15;
+export declare const RECORD_SCHEMA_VERSION = 18;
 /** 一次 Invocation 的纯运行时内存聚合(reporter 契约用);落盘格式契约在 niceeval/record 的 RunMeta / AttemptRecord,见 docs/feature/record/architecture.md。不携带顶层 `agent`/`model`——一次 Invocation 可能横跨多个 `(agent, model, flags)` 配置,塞一个顶层单值只能代表其中一份配置;需要时从 `results` 里逐条 `EvalResult.agent`/`.model` 去重派生。 */
 export interface InvocationSummary {
     /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
@@ -472,8 +486,22 @@ export interface InvocationSummary {
     durationMs: number;
     usage?: Usage;
     estimatedCostUSD?: number;
+    /** Current Record readbacks adopted by this invocation; these are never recreated EvalResults. */
+    reusedAttempts: readonly CurrentReusedAttemptReadback[];
     results: EvalResult[];
 }
+/**
+ * The only invocation-level durable hand-off. Record Runs retain every
+ * result, diagnostic, and artifact; this receipt only identifies those Runs
+ * and records the invocation lifecycle fact.
+ */
+export interface InvocationReceipt {
+    readonly invocationId: string;
+    readonly runIds: readonly string[];
+    readonly startedAt: string;
+    readonly completedAt?: string;
+    readonly completion: "completed" | "interrupted" | "failed";
+}
 /** onInvocationStart 的运行规模:去重后 eval 数 × 配置(agent×model×flags)数 → 总 attempt 数。 */
 export interface InvocationShape {
     /** 去重后实际要跑的 eval 数(= evals.length)。 */
@@ -486,34 +514,10 @@ export interface InvocationShape {
      *  实验级 maxConcurrency 只在该实验内部限流,不改这个全局值。 */
     maxConcurrency: number;
     /**
-     * 本次 Invocation 的快照时间(ISO 时间戳),在调度任何 attempt 前确定。
-     * Artifacts writer 把它写入 `run.json.startedAt`；Attempt locator 另由持久化 Run 的
-     * `runId` 与 `evalId` / attempt 下标派生，不把时间戳当身份。`runEvals()` 恒在
-     * `onInvocationStart` 触发前填入该值；省略只出现在测试/第三方手写
-     * `InvocationShape` 的直调场景。
-     */
-    snapshotStartedAt?: string;
-    /**
-     * 调度前为每个 Experiment 分配的持久化 Run 身份。Artifacts writer 必须把同一值写进
-     * run.json；其它 reporter 可用它关联 plan 期 attempt locator 与最终 Run。
+     * 调度前由 Record v1 draft 分配的真实持久化 Run 身份。其它 reporter 可用它关联
+     * plan 期的 attempt locator 与最终 Run，但不能替换或重新生成它。
      */
     runIds?: ReadonlyMap<string, string>;
-    /**
-     * 本次规划期算出的指纹输入清单,按 experimentId 分组(evalId → 清单)。落盘面据此在建 Run
-     * 目录时与 `run.json` 同批写出 `manifests.json`(见 record/writer.ts 的 `WriterOptions`)。
-     * 与 `snapshotStartedAt` 同一条路径:runner 显式递给 reporter,不由落盘面自己猜。
-     * 省略只出现在没有携带规划的直调场景。
-     */
-    manifests?: ReadonlyMap<string, RunManifests>;
-    /**
-     * 本次规划期按 experimentId 算好的 Run 级配置身份(见
-     * `config-identity.ts` 的 `configIdentityForRun` / `hashConfigHash`)。同一 experiment 内
-     * 全部 eval 共享一个值(configHash 只依赖 run 与 Experiment 作者 layer,不依赖逐 eval 的
-     * 物理 provider plan);落盘面据此在建 Run 目录时把它写进 `run.json.configHash`,不再只有
-     * `niceeval accept` 显式声明。与 `manifests` 同一条路径:runner 显式递给 reporter,
-     * 不由落盘面自己猜。省略只出现在没有携带规划的直调场景。
-     */
-    configHashes?: ReadonlyMap<string, string>;
 }
 export interface Reporter {
     onEvent?(event: ReporterEvent): void | Promise<void>;
@@ -533,8 +537,8 @@ export interface Reporter {
  * 诊断消息里的次要上下文,不参与去重身份。
  *
  * `required` 语义(见 docs/feature/experiments/cli.md「运行完成状态不只看 verdict 计数」):
- * - 默认 Artifacts reporter、CLI 显式 `--json` / `--junit`:`required: true`——它们的产物是
- *   agent/CI 读取权威结果的唯一入口,写失败必须让 `InvocationCompletion` 判红、CI 退出码非零。
+ * - CLI 显式 `--junit`:`required: true`——这是调用者要求的附加聚合文件,写失败必须让
+ *   `InvocationCompletion` 判红、CI 退出码非零。CLI `--json` 是终端 receipt 流，不是 Reporter。
  * - 用户 `Config.reporters` / `EvalDef.reporters`:`required: false`——失败只折成一条
  *   diagnostic,不影响 completion,也不阻断其它 reporter 收尾或后续 attempt。
  *
@@ -579,17 +583,13 @@ export type ReporterEvent = {
     type: "invocation:summary";
     summary: InvocationSummary;
 } | {
-    /**
-     * 该 Experiment 的 teardown(若声明)完成之后、invocation:summary 之前触发,标记它
-     * 已经彻底跑完;供内建 Artifacts 精确地在这一刻封口对应的 Run,不必等到整个
-     * Invocation 结束才一次性封全部快照(见 docs/runner.md「Experiment 收尾协议」)。
-     */
+    /** 该 Experiment 的 teardown(若声明)完成之后、invocation:summary 之前触发。 */
     type: "experiment:complete";
     experimentId: string;
     /** 该 Experiment 封口时刻,即它的 Run completedAt。 */
     completedAt: string;
-    /** 本次携带合入(fingerprint 命中、未真实执行)的历史终态结果,收尾时一并落盘。 */
-    carriedResults: EvalResult[];
+    /** 当前 Record 读取出的精确复用 Attempt；不伪造成历史 EvalResult。 */
+    reusedAttempts: readonly CurrentReusedAttemptReadback[];
     /** 该 Experiment 域产生的全部诊断;空集合传空数组,不省略字段。 */
     diagnostics: readonly DiagnosticRecord[];
     /** 该 Experiment 域经 `ctx.fact()` 累计的运行事实(experiment.setup / .teardown,含收尾自愈路径);省略 = 没有上报过。 */
@@ -603,10 +603,14 @@ export type ReporterEvent = {
 };
 /**
  * 计分粒度题型:`defineEval` 恒 `"pass"`(通过制,一题一分,读通过率),`defineScoreEval` 恒
- * `"points"`(计分制,题内叠加挣分,读总分)。定义期事实,发现期从 `EvalDefinition.evaluationKind` 直接读取,
+ * `"score"`(计分制,题内叠加挣分,读总分)。定义期事实,发现期从 `EvalDefinition.evaluationKind` 直接读取,
  * 不靠执行 `test()` 推断(见 docs/feature/experiments/score-points.md)。
  */
-export type EvaluationKind = "pass" | "points";
+export type EvaluationKind = "pass" | "score";
+/** The live Runner derives Pass and Score from one sealed Assert-first entry sequence. */
+export declare const EVALUATION_ALGORITHM: "assert-first/v2";
+/** `fact-use/v3` remains only as the historical Record reader/writer bridge. */
+export type EvaluationAlgorithm = typeof EVALUATION_ALGORITHM | "assert-first/v1" | "fact-use/v3";
 /**
  * 作者输入里的派生字段用模块私有诊断类型，而不是 `never`：错误会说明字段属于哪个阶段。
  * 这些 symbol 不从包入口导出，因此包外没有可写入的同类值。
@@ -638,13 +642,15 @@ export interface EvalAuthorFields {
      * 每个实际 Eval x Experiment 配对必须恰好一方提供 template-bearing layer。
      */
     sandbox?: SandboxLayer;
-    /** 覆盖项目级 Config.judge,只对这一条评估用例生效(如换个更贵的评审模型)。 */
-    judge?: JudgeConfig;
+    /** Explicit, immutable Eval Plugin occurrences; no directory inheritance exists. */
+    plugins?: readonly PluginInstance<"eval">[];
+    /** 声明 Judge capability；true 继承 Experiment/Config，对象同时声明并覆盖它们。 */
+    judge?: JudgeDeclaration;
     /** 覆盖 / 追加项目级 Config.reporters,只对这一条评估用例生效。 */
     reporters?: Reporter[];
     /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这一条评估用例生效。 */
     timeoutMs?: number;
-    /** 任意附加元数据,原样透传进 EvalResult,不参与调度或打分;供自定义 reporter 消费。 */
+    /** 任意附加元数据,作为 Attempt Provenance 保存,不参与调度或打分;供自定义 reporter 消费。 */
     metadata?: globalThis.Record<string, JsonValue>;
     /**
      * 调整 agent diff 的归因排除清单(仅 Sandbox 型;见 docs/feature/eval/README.md):两个数组都是
@@ -657,30 +663,35 @@ export interface EvalAuthorFields {
         ignore?: string[];
     };
 }
+/** Authors may return an Effect; Runner executes it in the Attempt's owning fiber. */
+type EvalTestReturn = void | Promise<void> | Effect.Effect<void, unknown, never>;
 /** 作者输入：id 归 discovery、evaluationKind 归 factory、configHash 归 planning，作者都不能填写。 */
-export type EvalInput = EvalAuthorFields & {
+export type EvalInput<Sandbox extends SandboxLayer | undefined = SandboxLayer | undefined> = Omit<EvalAuthorFields, "sandbox"> & {
+    sandbox?: Sandbox;
     id?: IdComesFromFilePath;
     evaluationKind?: EvaluationKindComesFromFactory;
     configHash?: ConfigHashComesFromPlanning;
-    test(t: TestContext): Promise<void> | void;
+    test(t: TestContext): EvalTestReturn;
 };
 /** 计分制作者输入，只有 test 的上下文不同。 */
-export type ScoreEvalInput = EvalAuthorFields & {
+export type ScoreEvalInput<Sandbox extends SandboxLayer | undefined = SandboxLayer | undefined> = Omit<EvalAuthorFields, "sandbox"> & {
+    sandbox?: Sandbox;
     id?: IdComesFromFilePath;
     evaluationKind?: EvaluationKindComesFromFactory;
     configHash?: ConfigHashComesFromPlanning;
-    test(t: ScoreTestContext): Promise<void> | void;
+    test(t: ScoreTestContext): EvalTestReturn;
 };
 /** Factory 完成默认归一后的 Eval 字段；Definition 不再复用作者输入的 optional 半状态。 */
-export interface EvalDefinitionFields {
+export interface EvalDefinitionFields<Sandbox extends SandboxLayer | undefined = SandboxLayer | undefined> {
     readonly description?: string;
     readonly tags: readonly string[];
     /**
      * 保留“作者省略”和“作者显式声明空 layer”的来源差异：Direct Agent 只允许前者，
      * Sandbox link 则把省略侧视为 command-only。不能在 factory 阶段补成 sandboxLayer()。
      */
-    readonly sandbox?: SandboxLayer;
-    readonly judge?: JudgeConfig;
+    readonly sandbox?: Sandbox;
+    readonly plugins: readonly PluginInstance<"eval">[];
+    readonly judge?: JudgeDeclaration;
     readonly reporters: readonly Reporter[];
     readonly timeoutMs?: number;
     readonly metadata: Readonly<globalThis.Record<string, JsonValue>>;
@@ -690,17 +701,33 @@ export interface EvalDefinitionFields {
     };
 }
 /** Factory 产物保留精确 evaluationKind / context，并带模块私有品牌，不能由对象字面量伪造。 */
-export interface EvalDefinition<Kind extends EvaluationKind, Context> extends EvalDefinitionFields {
+export interface EvalDefinition<Kind extends EvaluationKind, Context, Sandbox extends SandboxLayer | undefined = SandboxLayer | undefined> extends EvalDefinitionFields<Sandbox> {
     readonly evaluationKind: Kind;
-    test(t: Context): Promise<void> | void;
+    test(t: Context): EvalTestReturn;
     readonly [EVAL_DEFINITION]: true;
 }
-export type AnyEvalDefinition = EvalDefinition<"pass", TestContext> | EvalDefinition<"points", ScoreTestContext>;
+export type AnyEvalDefinition = EvalDefinition<"pass", TestContext, SandboxLayer | undefined> | EvalDefinition<"score", ScoreTestContext, SandboxLayer | undefined>;
+declare const EVAL_GROUP_DEFINITION: unique symbol;
+/** A group member must not own a Sandbox template or instance lifecycle. Runtime discovery revalidates this. */
+export type EvalGroupMemberSandbox = SandboxLayer<"command-only", "prepare-only"> | undefined;
+export type EvalGroupMember = EvalDefinition<"pass", TestContext, EvalGroupMemberSandbox> | EvalDefinition<"score", ScoreTestContext, EvalGroupMemberSandbox>;
+export interface EvalGroupInput<Sandbox extends SandboxLayer | undefined = SandboxLayer | undefined> {
+    readonly evals: readonly [EvalGroupMember, ...EvalGroupMember[]];
+    readonly sandbox?: Sandbox;
+    /** Required physical-instance policy when a grouped Sandbox becomes unavailable. */
+    readonly onUnavailable: PluginOnUnavailable;
+    readonly plugins?: readonly PluginInstance<"group">[];
+}
+export interface EvalGroupDefinition extends EvalGroupInput {
+    readonly [EVAL_GROUP_DEFINITION]: true;
+}
+export declare function brandEvalGroupDefinition(value: EvalGroupInput): EvalGroupDefinition;
+export declare function isEvalGroupDefinition(value: unknown): value is EvalGroupDefinition;
 /** @internal 唯一写入 Definition 私有品牌的构造辅助；不从公共入口导出。 */
-export declare function brandEvalDefinition<Kind extends EvaluationKind, Context>(value: EvalDefinitionFields & {
+export declare function brandEvalDefinition<Kind extends EvaluationKind, Context, Sandbox extends SandboxLayer | undefined>(value: EvalDefinitionFields<Sandbox> & {
     evaluationKind: Kind;
-    test(t: Context): Promise<void> | void;
-}): EvalDefinition<Kind, Context>;
+    test(t: Context): EvalTestReturn;
+}): EvalDefinition<Kind, Context, Sandbox>;
 /** Definition 之后由 discovery 一次性补齐的不可变事实。 */
 export interface DiscoveredEvalFacts {
     readonly id: string;
@@ -725,9 +752,22 @@ export interface DiscoveredEvalFacts {
      * 同一文件里多个 eval(数组默认导出)共享同一份引用——哈希与内容天然相同,不重复读盘。
      */
     readonly source: CapturedEvalSource;
+    /** @internal Original factory object, used only for Eval Group identity resolution. */
+    readonly definition: AnyEvalDefinition;
+    /** Eval Group planning facts, present only for discovered group members. */
+    readonly evalGroup?: {
+        readonly id: string;
+        readonly evalIds: readonly string[];
+        readonly definitionHash: string;
+        readonly sandbox?: SandboxLayer;
+        readonly onUnavailable: PluginOnUnavailable;
+        readonly plugins: readonly PluginInstance<"group">[];
+        readonly sourcePath: string;
+        readonly baseDir: string;
+    };
 }
 /** discovery 保留 factory 的 evaluationKind 判别、私有品牌与对应 test context。 */
-export type DiscoveredEval = (EvalDefinition<"pass", TestContext> & DiscoveredEvalFacts) | (EvalDefinition<"points", ScoreTestContext> & DiscoveredEvalFacts);
+export type DiscoveredEval = (EvalDefinition<"pass", TestContext> & DiscoveredEvalFacts) | (EvalDefinition<"score", ScoreTestContext> & DiscoveredEvalFacts);
 /** @internal discovery 动态边界的品牌守卫；普通对象即使字段同形也不通过。 */
 export declare function isEvalDefinition(value: unknown): value is AnyEvalDefinition;
 /** @internal discovery 构造唯一的不可变阶段三值，不回写 Definition。 */
@@ -746,23 +786,22 @@ export interface ExperimentHookContext extends ScopedFeedback {
     /** 用户中断(Ctrl+C / kill)时 abort;长启动的 setup 应观察它提前退出。 */
     readonly signal: AbortSignal;
     /**
-     * 第三条反馈通道:上报整场实验的环境观测,与 `completedAt` 同批在快照封口补写进
-     * `RunMeta.facts`。key 匹配 `[a-z0-9._-]{1,64}`,value 是标量;同 key 后写覆盖先写,
-     * 非法 key 或非标量 value 抛错。不影响判定,不参与 verdict / 评分 / 指纹。形状与归属语义见
-     * docs/feature/record/architecture.md#facts运行事实。`niceeval exp --teardown` 的独立收尾
-     * 路径不派发 attempt、不落任何 Run,没有 `RunMeta.facts` 可写——该路径下这个方法仍然
-     * 校验入参(非法 key / 非标量 value 照样抛错),校验通过后丢弃写入(no-op:诚实优于
-     * 静默——非法调用照样报错、不被这条路径悄悄吞掉,但也不假装有地方落盘),见 cli.ts 的
-     * `--teardown` 构造点。
+     * 写入本 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>;
 /** Experiment 作者自行选择的字段；不包含路径 id 与 factory 品牌。 */
 export interface ExperimentAuthorFields {
     /** 一句话描述,展示在 view / CLI 里;纯说明,不影响调度或打分。 */
     description?: string;
     /**
-     * 必填:这个实验跑哪个 agent(defineSandboxAgent / defineDirectAgent 的产物)。运行配置的
+     * 必填:这个实验跑哪个 agent(defineSandboxAgent / defineAgent 的产物)。运行配置的
      * agent 归属完全由这里决定——EvalDefinition 不声明 agent。
      */
     agent: Agent;
@@ -772,7 +811,7 @@ export interface ExperimentAuthorFields {
     reasoningEffort?: string;
     /**
      * 本实验的 Judge 执行配置。只覆盖 model / endpoint / credential selector / 调用预算，
-     * rubric、材料、severity 与 threshold 仍由 Eval assertion 拥有。各字段按
+     * rubric、材料与消费阈值仍由 Eval 的 Fact/use 声明拥有。各字段按
      * Experiment → Eval → Config 解析。
      */
     judge?: JudgeConfig;
@@ -797,7 +836,7 @@ export interface ExperimentAuthorFields {
     /**
      * 这个实验覆盖哪些 eval:`"*"` 全部、字符串数组按 id 前缀、或自定义谓词(逐条收到发现并扇出后的
      * 只读 `EvalDescriptor`,不暴露路径 / 执行字段);省略等价于 `"*"`。谓词对本次 invocation 的
-     * 候选 eval 各求值一次,解析结果作为 `selectedEvalIds` 落进快照——不是运行时反复调用的过滤器
+     * 候选 eval 各求值一次,解析结果作为内存中的 `selectedEvalIds` 计划——不是运行时反复调用的过滤器
      * (见 docs/feature/eval/library.md「EvalDescriptor」、docs/feature/experiments/library.md
      * 「evals:遍历发现结果,自定义选择」)。
      */
@@ -809,6 +848,8 @@ export interface ExperimentAuthorFields {
      * 每个配对恰好一方提供 template-bearing layer。
      */
     sandbox?: SandboxLayer;
+    /** Explicit Experiment Plugin occurrences, normalized by defineExperiment(). */
+    plugins?: readonly PluginInstance<"experiment">[];
     /** 同一 Run 内复用沙箱；这种运行与历史携带双向隔离。 */
     sandboxReuse?: boolean;
     /**
@@ -839,19 +880,19 @@ export interface ExperimentAuthorFields {
      * 共享」的宿主机资源(隧道、mock server、license 租约)。本实验第一个通过派发许可的
      * attempt 触发(memoized,并发 attempt 等同一个结果;全部结果被 carry 携入时不执行)。
      * setup 不返回值;产物写模块级变量,`teardown` 与同文件 agent / sandbox 钩子从闭包读,
-     * runner 不做值的中介。setup 抛错 → 本实验所有 attempt 记 `errored`
+     * runner 不做值的中介。setup 抛错 → 本实验所有 Attempt 形成 `errored` Verdict
      * (code `"experiment-setup-failed"`、phase `"experiment.setup"`),同批其它实验不受影响。
-     * 函数体不进 fingerprint,改了钩子逻辑用 `--force` 强制重跑。
+     * 函数体不进 fingerprint,改了钩子逻辑用 `--rerun all` 明确全部重跑。
      * 见 docs/feature/experiments/architecture.md「实验级生命周期」。
      */
-    setup?: (ctx: ExperimentHookContext) => void | Promise<void>;
+    setup?: ExperimentHook;
     /**
      * 实验级生命周期钩子对的 teardown 侧:本实验全部 attempt 收尾后执行(运行被中断也执行),
      * 当且仅当 setup 时点走到过——setup 抛错不豁免(半初始化现场同样要扫尾,teardown 对可能
      * 未赋值的闭包变量做防御),未声明 setup 不影响触发;一个 attempt 都不派发则跳过。
      * 抛错或超 30s 清理上限只记运行级 diagnostic(`experiment-teardown-failed`),不改判定。
      */
-    teardown?: (ctx: ExperimentHookContext) => void | Promise<void>;
+    teardown?: ExperimentHook;
 }
 /** 作者输入：id 只能由发现阶段从文件路径推导。 */
 export type ExperimentInput = ExperimentAuthorFields & {
@@ -872,12 +913,13 @@ export interface ExperimentDefinition {
     readonly timeoutMs?: number;
     /** 省略本身是 link 阶段需要的来源事实，不能在 Definition 中归一成显式空 layer。 */
     readonly sandbox?: SandboxLayer;
+    readonly plugins: readonly PluginInstance<"experiment">[];
     readonly sandboxReuse: boolean;
     readonly budget?: number;
     readonly maxConcurrency?: number;
     readonly classifyFailure?: AttemptFailureClassifier;
-    readonly setup?: (ctx: ExperimentHookContext) => void | Promise<void>;
-    readonly teardown?: (ctx: ExperimentHookContext) => void | Promise<void>;
+    readonly setup?: ExperimentHook;
+    readonly teardown?: ExperimentHook;
     readonly [EXPERIMENT_DEFINITION]: true;
 }
 /** @internal 仅 defineExperiment 写入私有品牌。 */
@@ -909,7 +951,7 @@ export interface EvalDescriptor {
     readonly description?: string;
     readonly tags: readonly string[];
     /**
-     * 计分粒度题型,`defineEval` → `"pass"`,`defineScoreEval` → `"points"`。定义期事实,
+     * 计分粒度题型,`defineEval` → `"pass"`,`defineScoreEval` → `"score"`。定义期事实,
      * 每条发现出的 eval 上都有确定值。供 `ExperimentDefinition.evals` 谓词按题型过滤(见
      * docs/feature/experiments/score-points.md「横截面聚合:同型实验,各读各的」)。
      */
@@ -918,19 +960,14 @@ export interface EvalDescriptor {
 }
 export interface Config {
     /** view/show 的项目默认报告。 */
-    report?: ReportDefinition;
-    /** view 的项目默认主题。 */
+    report?: Report;
+    /** view 的 host-owned closed visual token declaration. */
     theme?: ThemeDefinition;
     /**
      * 项目名,显示在 `niceeval view` 顶部 hero(`<h1>`),省略则回退到通用标题。
      * 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
      */
     name?: LocalizedText;
-    /**
-     * CLI 与运行时文案的界面语言(BCP 47,如 `"en"` / `"zh-CN"`);CI 里想让日志恒定一种语言就写这个。
-     * 省略则按系统 locale(`LC_ALL` / `LC_MESSAGES` / `LANG`)判定,都没有时用 `zh-CN`。
-     */
-    locale?: string;
     /** 上传进 Sandbox 的工作区根目录,省略则用项目根;评估用例的 sandbox 视图从这里起步。 */
     workspace?: string;
     /** 项目级默认 judge 配置(model / baseUrl / apiKeyEnv);EvalDef.judge 可按评估用例覆盖。 */
@@ -950,8 +987,8 @@ export interface Config {
      * 临时端口(经 ctx.telemetry 交给 adapter)。代价:固定端口下同机同时只能跑一个 niceeval 进程,
      * 且该端口被别的进程占用时会报错——换一个空闲端口写回这里即可。
      * `host` 是报给 adapter 的接收端 hostname(而非监听地址,监听地址恒为 0.0.0.0):默认
-     * "127.0.0.1";docker Sandbox 型 tracing 需要 "host.docker.internal" 之类的场景,或配了隧道
-     * 的远程接入,在这里覆盖。
+     * "127.0.0.1"。只有作者已经提供受控 tunnel / 可达路由时才在这里覆盖；Docker Sandbox
+     * 默认把 receiver 放在 Sandbox 内，不依赖隐式宿主 gateway。
      */
     telemetry?: {
         host?: string;
@@ -1004,6 +1041,10 @@ export interface AgentRun {
     readonly earlyExit: boolean;
     /** Experiment 的作者 layer；省略在 link 输入归一为 command-only。 */
     readonly sandbox?: SandboxLayer;
+    /** Experiment Plugin occurrences carried into zero-resource pair link. */
+    readonly plugins?: readonly PluginInstance<"experiment">[];
+    /** Canonical, credential-free Experiment Plugin behavior projection. */
+    readonly pluginBehavior?: JsonValue;
     readonly sandboxReuse?: boolean;
     /** Experiment 声明的 judge 覆盖；与 Eval/Config 的逐字段解析在 pair 规划期完成。 */
     readonly judge?: JudgeConfig;
@@ -1026,8 +1067,6 @@ export interface AgentRun {
     readonly description?: string;
     /** 报告归类标注(ExperimentDef.labels),原样进 ExperimentRunInfo.labels;不透传 ctx / t。 */
     readonly labels?: Readonly<globalThis.Record<string, string | number>>;
-    /** evals 过滤器的指纹(数组内容 / 函数体哈希),进 ExperimentRunInfo.evalFilterFingerprint。 */
-    readonly evalFilterFingerprint?: string;
     /**
      * 本次 invocation 解析后实际选中的 eval id 全集——CLI 在构造 AgentRun 时对候选 eval 各求值
      * 一次算好(见 `eval-selection.ts` 的 `resolveExperimentEvals()`),下游(dry-run、sandbox 查表、
@@ -1035,20 +1074,38 @@ export interface AgentRun {
      * 保持顺序 = discovery 稳定顺序,去重。
      */
     readonly selectedEvalIds: readonly string[];
-    readonly strict?: boolean;
     /** 本配置自己的并发上限(来自 ExperimentDef.maxConcurrency):调度器为它单建信号量,
      *  attempt 先过这道闸再占全局并发位;省略则只受全局并发约束。 */
     readonly maxConcurrency?: number;
     /** 实验级生命周期钩子对(来自 ExperimentDef.setup / .teardown):setup 整场至多一次,
      *  调度器 memoize 执行;teardown 在全部 attempt 收尾后执行,当且仅当 setup 时点走到过
      *  (语义见 ExperimentDef 对应字段)。 */
-    readonly setup?: (ctx: ExperimentHookContext) => void | Promise<void>;
-    readonly teardown?: (ctx: ExperimentHookContext) => void | Promise<void>;
+    readonly setup?: ExperimentHook;
+    readonly teardown?: ExperimentHook;
     /** 实验声明的失败分类器(来自 ExperimentDef.classifyFailure):turn 链上排在 adapter 之前,
      *  生命周期链上排在抛出点声明之后;产出的空间轴由止损闸在 attempt 封口消费。 */
     readonly classifyFailure?: AttemptFailureClassifier;
 }
-export interface RunOptions {
+/**
+ * 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[];
     agentRuns: readonly AgentRun[];
@@ -1062,22 +1119,24 @@ export interface RunOptions {
     rerun?: "failed" | "all";
     /** `--accept` 本次授权跨过的差异 selector(`config:<字段路径>` 等)。 */
     accept?: readonly string[];
-    /**
-     * 历史侧的指纹输入清单(`${experimentId}|${evalId}` → 清单),差异解释与 `--accept` 的授权
-     * 判据读它;缺席的 key 差异算不出,如实是 `opaque:no-manifest`。调用方已经算好 `carryPlan`
-     * 时这个字段不参与——那份计划里的差异已经定了。
-     */
-    priorManifests?: ReadonlyMap<string, EvalManifest>;
     /** 结果根目录(.niceeval;留存注册表 `.niceeval/sandboxes/` 挂在它下面)。省略 = cwd/.niceeval。 */
     niceevalRoot?: string;
     /** CLI 为 `niceeval exp` 提供的持久 Session 索引；只观察调度事件，不参与锁/闸判定。 */
-    session?: import("./session.ts").SessionTracker;
-    /** @internal 测试/嵌入式编排可预分配 Run 身份；CLI 省略时 runner 为每个 Experiment 生成 UUID。 */
-    runIds?: ReadonlyMap<string, string>;
+    session?: import("./session.js").SessionTracker;
+    /**
+     * The current Record coordinator calls this after its frozen-view readback
+     * has established the exact reusable attempts. The CLI uses this one-way
+     * Effect hand-off to emit the invocation plan; callers cannot provide or
+     * alter Record reuse authority through it.
+     */
+    onCurrentRecordReusePlan?: (input: {
+        readonly reused: number;
+        readonly reusedFailures: readonly FailureDetail[];
+    }) => Effect.Effect<void, never>;
     /**
      * 已注册的 reporter,携带 name/required 元数据(见 `ReporterRegistration`)。这是内部编排
-     * 通道——调用方(今天只有 `cli.ts`)按来源(默认 artifacts / 显式 --json·--junit / 用户
-     * `Config.reporters`)把裸 `Reporter` 各自包一层元数据后传进来;eval 级 `EvalDef.reporters`
+     * 通道——调用方(今天只有 `cli.ts`)按来源(显式 --junit / 用户 `Config.reporters`)把裸
+     * `Reporter` 各自包一层元数据后传进来;eval 级 `EvalDef.reporters`
      * 不经过这里,由 `runEvals()` 自己按 `scopeReporter()` 包装、统一记作 `required: false`
      *(见 run.ts 的 scopedSets 处理)。
      */
@@ -1086,20 +1145,13 @@ export interface RunOptions {
     /** Run 级 Sandbox 镜像 lookup/build 并发；省略时安全默认 2。 */
     maxBuildConcurrency?: number;
     signal?: AbortSignal;
-    /** 上次运行的结果。verdict 为 passed/failed 的 (experimentId, evalId) 组合跳过重跑,结果直接合入本次汇总。 */
-    priorResults?: EvalResult[];
-    /**
-     * 预算好的携入计划(见 fingerprint.ts 的 planCarry)。cli.ts 为了让 live 表格提前知道
-     * 哪些行会被携入,必须在构建 liveRows 之前算一次;传进来后 runEvals 直接复用,不重算
-     * 一遍(否则两处各自算一次,不仅重复 I/O,还留下"两边判断可能不一致"的隐患)。
-     * 省略时 runEvals 自己算(测试直调等场景)。
-     */
-    carryPlan?: import("./fingerprint.ts").CarryPlan;
+    /** Linked plugin RecordAttachment producers for this invocation. */
+    recordAttachments?: RunnerRecordAttachmentProducers<RecordError, RecordRequirements>;
     /**
      * 非沙箱 tracing agent 的 run 级共享 OTLP 接收池(runEvals 创建并回收;
      * 每个 agent 一个 receiver,attempt 之间共享 —— 被测应用是长驻进程,端点不能随 attempt 换)。
      */
-    otelPool?: import("../o11y/otlp/turn-otel.ts").OtelReceiverPool;
+    otelPool?: import("../o11y/otlp/turn-otel.js").OtelReceiverPool;
     /**
      * Run 级共享构建准备。只含携带规划后仍需 fresh 执行的 BuildKey;
      * 省略时 runEvals 从 pair-owned ProviderPlan 自动收集
@@ -1107,8 +1159,8 @@ export interface RunOptions {
      * 共享构建不占 attempt 并发位,不计入 executionMs。
      */
     buildPreparation?: {
-        readonly works: readonly import("../sandbox/build-coordinator.ts").SandboxBuildWork[];
-        readonly provider: import("../sandbox/build-coordinator.ts").SandboxBuildProvider;
+        readonly works: readonly import("../sandbox/build-coordinator.js").SandboxBuildWork[];
+        readonly provider: import("../sandbox/build-coordinator.js").SandboxBuildProvider;
         /** `${experimentId}|${evalId}` → 该 pair 的 fresh attempt 依赖的 BuildKey。 */
         readonly pairBuildKeys: Readonly<globalThis.Record<string, readonly BuildKey[]>>;
         readonly maxConcurrency?: number;
@@ -1119,7 +1171,7 @@ export interface RunOptions {
      * Run 级 Agent artifact prepare 协调器。省略时 runEvals 为有 staged installer 的
      * sandbox agent 新建并接真 Run timing recorder;测试可注入。
      */
-    artifactPrepare?: import("../agents/provisioner.ts").ArtifactPrepareCoordinator;
+    artifactPrepare?: import("../agents/provisioner.js").ArtifactPrepareCoordinator;
 }
 /** 调度器内部的一次尝试:eval × run × 第几轮。 */
 export interface Attempt {
@@ -1130,6 +1182,8 @@ export interface Attempt {
     readonly key: string;
     readonly fingerprint: string;
     readonly configHash: string;
+    /** Planning 时唯一解析并冻结的 Judge capability/config。 */
+    readonly judge: ResolvedJudgeConfig | undefined;
     /** 该 pair 的唯一、不可变规划产物；fingerprint / create / reuse 全部消费同一份值。 */
     readonly plan: LinkedRunPlan;
     /** 同一 Experiment 本次选中 Eval 的完整 plan 映射；run.json 不从当前 pair 猜全局默认值。 */
@@ -1139,7 +1193,7 @@ export interface Attempt {
      * 预分配 runId 与 attempt 身份派生,贯穿执行、留存登记与落盘——登记项、run 收尾反馈与
      * result.json 从第一次写入起就用同一个值。裸 run(无 experimentId)不产出。
      */
-    readonly locator: AttemptLocator;
+    locator?: AttemptLocator;
 }
 /** 两种反馈形态(见 docs/feature/experiments/cli.md「每条命令一个人读 text 面,`--json` 是机器面」):
  *  `--json` 即机器面,否则人读文本(TTY live 面板 / 非 TTY 追加流,由渲染层内部按 `io.stderr.isTTY`
@@ -1162,7 +1216,7 @@ export interface AttemptRef {
     attempt: number;
 }
 /** `AttemptRef` 的确定性字符串编码,只作 `RunFeedbackState.active` 的 Map key 使用 ——
- *  不是展示文本(那是 `who`),也不是 `AttemptLocator`(那需要额外的 `snapshotStartedAt`)。 */
+ *  不是展示文本(那是 `who`),也不是 `AttemptLocator`(后者是 Record 的持久化身份)。 */
 export type AttemptKey = string & {
     readonly __brand: "AttemptKey";
 };
@@ -1258,14 +1312,15 @@ export interface ActiveRunActivity {
  * 解析 `reason` 之外的任何文本就能拼出机器可读的输出。
  */
 export interface FailureDetail {
-    locator: AttemptLocator;
+    /** Canonical current Record Attempt locator. */
+    locator: string;
     identity: AttemptRef;
     who: string;
     verdict: "failed" | "errored";
     /** 一层可行动摘要(gate 断言名、error 消息……),不是完整 stack/transcript;详情走 `niceeval show`。 */
     reason: string;
-    /** failed / assertion-unavailable 时的结构化主断言摘要；机器 renderer 直接读字段。 */
-    assertion?: PrimaryAssertionSummary;
+    /** failed / unavailable 时的结构化主 Fact/use 摘要。 */
+    fact?: PrimaryFactSummary;
     /** 仅 errored 使用：结构化执行错误发生时所在的阶段。failed 是断言 outcome，不带 phase。 */
     phase?: LifecyclePhase;
     /** 仅 errored 且没有结构化主断言摘要（真正的执行错误，而非 assertion-unavailable）时携带：
@@ -1491,12 +1546,13 @@ export type DurableFeedbackEvent = {
 } | {
     type: "failure";
     at: number;
-    locator: AttemptLocator;
+    /** Writer-issued short alias for the exact durable AttemptId. */
+    locator: string;
     identity: AttemptRef;
     who: string;
     verdict: "failed" | "errored";
     reason: string;
-    assertion?: PrimaryAssertionSummary;
+    fact?: PrimaryFactSummary;
     phase?: LifecyclePhase;
     code?: string;
     origin?: TimingOrigin;
@@ -1634,17 +1690,9 @@ export type DurableFeedbackEvent = {
     summary: InvocationSummary;
     completion: InvocationCompletion;
 } | {
-    type: "saved";
+    type: "receipt";
     at: number;
-    /** 本次 invocation 实际落盘的快照结果路径。不含 `--junit` 聚合文件——那个由 `junit`
-     *  独立字段单独携带,而不是塞进这个数组后靠猜文件后缀去反推「哪个是聚合报告、哪些是
-     *  快照目录」。`exp` 没有 JSON 聚合文件出口(`--json` 是布尔:整条事件流本身就是机器面,
-     *  见 docs/feature/experiments/cli.md「机器怎么读:--json」);需要 JSON 聚合文件时
-     *  重定向事件流,或运行后 `niceeval show --json`。 */
-    paths: readonly string[];
-    /** 实际写出的 `--junit` 聚合报告路径;未传 `--junit`,或写入失败(见 required reporter
-     *  语义),都省略这个字段——省略表示「不打印这一行」,不是打印一个空路径。 */
-    junit?: string;
+    receipt: InvocationReceipt;
 };
 /**
  * runner → feedback coordinator 的内部事件通道,与公共 `Reporter` / `ReporterEvent` 分开: