niceeval 0.12.1-canary.25 → 0.12.1

package/INDEX.md

@@ -28,7 +28,6 @@
 - `docs-site/zh/tutorials/custom-reports.mdx` — 编写自定义报告:用普通 TypeScript 函数计算结果，并同时生成终端与网页报告。
 - `docs-site/zh/tutorials/dataset-fanout.mdx` — 数据驱动测试（dataset fan-out）：用多份数据运行同一套评估用例:从 .eval.ts 文件导出数组或 keyed record，将一套评估逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部测试集，并获得稳定 ID。
 - `docs-site/zh/tutorials/deploy-report-site.mdx` — 把报告站发布上线:把 .niceeval 直接提交进仓库、配一份排除运行时状态的 .gitignore,再用不装整仓依赖的 CI 脚本和 Vercel CLI,在打 tag 时把报告站发布上线。
-- `docs-site/zh/tutorials/docker-in-docker.mdx` — 让 Sandbox 使用 Docker:根据任务信任边界选择 Docker socket、raw privileged DinD 或受管 rootless DinD，并为 Agent 准备 Docker CLI 与 daemon。
 - `docs-site/zh/tutorials/evaluation-kinds.mdx` — 题型、断言、Judge 和成本限制:值断言、作用域断言、LLM-as-judge、严重度怎么折成一个判定、计分制怎么给部分分，以及成本上限怎么写。
 - `docs-site/zh/tutorials/experiments.mdx` — 实验矩阵：用运行矩阵比较 agents 和 models:使用 NiceEval experiments 让同一批评估用例横跨多个 agents、models 和 flags，比较 pass rate、成本和延迟。
 - `docs-site/zh/tutorials/fixtures.mdx` — Sandbox Fixture：用任务评估 coding agents:用 .eval.ts 给 coding agent 准备隔离 workspace、发送真实任务，并用 Sandbox 文件、命令、diff 和 judge 验证结果。
@@ -62,7 +61,7 @@
 - `docs-site/zh/reference/builtin-agents.mdx` — 内置 Agent 能力参考:NiceEval 内置的 claude-code、codex、bub 适配器分别做到了哪些能力，对应哪些断言，以及已知限制。
 - `docs-site/zh/reference/capabilities.mdx` — 能力与证据覆盖参考:Agent 的构造方式、运行时行为与必填的六通道 evidenceCoverage 声明，怎样共同决定 NiceEval 的断言能相信什么。
 - `docs-site/zh/reference/cli.mdx` — NiceEval CLI：命令、flags 和退出码参考:NiceEval CLI 参考：exp、show、view、init、list 和 clean 命令，以及结果下钻、experiment、评估用例过滤、并发、预算和 CI 输出。
-- `docs-site/zh/reference/define-agent.mdx` — defineAgent 和 defineSandboxAgent：Adapter 参考:defineAgent 和 defineSandboxAgent 参考：AgentContext、AgentSession、Sandbox 接口和共享 Sandbox helpers。
+- `docs-site/zh/reference/define-agent.mdx` — defineDirectAgent 和 defineSandboxAgent：Adapter 参考:defineDirectAgent 和 defineSandboxAgent 参考：AgentContext、AgentSession、Sandbox 接口和共享 Sandbox helpers。
 - `docs-site/zh/reference/define-config.mdx` — defineConfig：项目默认配置:defineConfig 参考：judge、reporters、并发、超时和 sandbox 默认值。
 - `docs-site/zh/reference/define-eval.mdx` — defineEval：声明、配置并运行 NiceEval 评估用例:defineEval 参考：选项、test context t、Turn 返回值、Sandbox helper，以及数组和 keyed record 测试集导出。
 - `docs-site/zh/reference/events.mdx` — 标准事件流参考:StreamEvent 的十种事件：每种的字段、什么时候吐、哪些断言消费它。adapter 的核心工作就是产出这条流。

package/bin/niceeval.js

@@ -5,14 +5,12 @@
 // CJS,宿主项目是 CJS 形态(npm init -y 默认)时用户文件落进 Node 的 CJS loader,只注册 ESM
 // hook 就没人转译(见 docs/cli.md「装载用户 .ts」)。
 // 这样框架与被测项目都不需要编译步骤,也不挑宿主的模块形态。
-// NiceEval 自身始终执行已发布的 canonical CJS runtime；tsx 只负责随后动态装载用户项目的
-// TypeScript，绝不把已安装包回跳到 checkout 的 src/。
-const cliUrl = new URL("../dist/cli.cjs", import.meta.url);
-await import(cliUrl.href);
+import { fileURLToPath } from "node:url";
+import { register as registerCjs } from "tsx/cjs/api";
+import { register as registerEsm } from "tsx/esm/api";
 
-// 先原生加载 CLI，避免 CJS hook 截获已预编译的 canonical graph 形成 require/import 循环；
-// CLI 随后的 config、eval、experiment 与 report 文件仍由两面 hook 动态装载。
-const { register: registerCjs } = await import("tsx/cjs/api");
-const { register: registerEsm } = await import("tsx/esm/api");
 registerCjs();
 registerEsm();
+
+const cliUrl = new URL("../src/cli.ts", import.meta.url);
+await import(fileURLToPath(cliUrl));

package/dist/agents/cache-marker.js

@@ -1,6 +1,2 @@
-import { createRequire as __niceevalCreateRequire } from "node:module";
-const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
-const __niceevalCanonical = __niceevalRequire("./cache-marker.cjs");
-const __niceevalExport0 = __niceevalCanonical["AGENT_DOCKERFILE_CACHE_SAFE"];
-export { __niceevalExport0 as AGENT_DOCKERFILE_CACHE_SAFE };
-//# sourceMappingURL=cache-marker.js.map
+/** Internal-only marker; this module is intentionally not re-exported by any package entrypoint. */
+export const AGENT_DOCKERFILE_CACHE_SAFE = Symbol("niceeval.agent.dockerfile-cache-safe");

package/dist/agents/provisioner.d.ts

@@ -1,6 +1,6 @@
 import { Effect, Option } from "effect";
-import type { SandboxOperations } from "../sandbox/types.js";
-import type { AgentArtifactPlatform, AgentEnsure, AgentIdentity, AgentInstaller, AgentStagedArtifact } from "./types.js";
+import type { SandboxOperations } from "../sandbox/types.ts";
+import type { AgentArtifactPlatform, AgentEnsure, AgentIdentity, AgentInstaller, AgentStagedArtifact } from "./types.ts";
 /** attempt facts:`agent.ensure` / `agent.version.actual`。 */
 export declare const AGENT_ENSURE_FACT: "agent.ensure";
 export declare const AGENT_VERSION_ACTUAL_FACT: "agent.version.actual";

package/dist/agents/types.d.ts

@@ -1,12 +1,12 @@
-import { AGENT_DOCKERFILE_CACHE_SAFE } from "./cache-marker.js";
-import type { DiagnosticInput, JsonValue, ProgressUpdate } from "../shared/types.js";
-import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.js";
-import type { Sandbox } from "../sandbox/types.js";
-import type { AttemptRef, MaybePromise, SandboxCommandTarget, StableSandboxCommand } from "../sandbox/commands.js";
-import type { RegisteredSandboxContent } from "../sandbox/content.js";
-import type { SendFailureClassifier } from "../context/send-failures.js";
-import type { SessionSlot } from "./session-slot.js";
-export type { SessionSlot } from "./session-slot.js";
+import { AGENT_DOCKERFILE_CACHE_SAFE } from "./cache-marker.ts";
+import type { DiagnosticInput, JsonValue, ProgressUpdate } from "../shared/types.ts";
+import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
+import type { Sandbox } from "../sandbox/types.ts";
+import type { AttemptRef, MaybePromise, SandboxCommandTarget, StableSandboxCommand } from "../sandbox/commands.ts";
+import type { RegisteredSandboxContent } from "../sandbox/content.ts";
+import type { SendFailureClassifier } from "../context/send-failures.ts";
+import type { SessionSlot } from "./session-slot.ts";
+export type { SessionSlot } from "./session-slot.ts";
 /**
  * 本地 stdio 形态的 MCP server:沙箱内起子进程,按 stdio 说 MCP 协议。
  * 与 {@link McpHttpServer} 按形状判别(有 `command` 的是 stdio,有 `url` 的是 HTTP)。
@@ -139,7 +139,7 @@ export type EvidenceCoverageEntry = {
 /**
  * 覆盖声明(EvidenceCoverage):完整性不是口头承诺,是随数据走的声明
  * (见 docs/feature/adapters/architecture/evidence.md)。两层:
- * - Agent 级默认(`defineAgent` / `defineSandboxAgent` 的 `evidenceCoverage`)必须逐一声明
+ * - Agent 级默认(`defineDirectAgent` / `defineSandboxAgent` 的 `evidenceCoverage`)必须逐一声明
  *   六个通道；官方 SDK 适配器可使用 `completeEvidenceCoverage`。
  * - Turn 级降级(`Turn.evidenceCoverage`)只用于相对 Agent 默认值降级。
  */
@@ -210,7 +210,7 @@ export interface Turn {
  * 启动期配置(`defineConfig({ telemetry: { port } } )`)固定的,不从这里传。
  */
 export interface Telemetry {
-    /** 接收端点(完整路径,形如 http://127.0.0.1:PORT/v1/traces)。 */
+    /** 接收端点(完整路径,形如 http://host.docker.internal:PORT/v1/traces)。 */
     readonly endpoint: string;
     /**
      * env-based 导出的 env(= AgentTracing.env(endpoint) 的结果),ready-to-spread。
@@ -562,7 +562,7 @@ export interface SandboxAgentDef {
      * 在 finally 里跑一次。 */
     teardown?: AgentTeardown;
 }
-/** `defineAgent()` 的入参形状(见 src/define.ts)——`kind: "direct"` 由 define 固定填入,不由用户声明。 */
+/** `defineDirectAgent()` 的入参形状(见 src/define.ts)——`kind: "direct"` 由 define 固定填入,不由用户声明。 */
 export interface DirectAgentDef {
     /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */
     name: string;

package/dist/agents/types.js

@@ -1,4 +1,2 @@
-import { createRequire as __niceevalCreateRequire } from "node:module";
-const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
-const __niceevalCanonical = __niceevalRequire("./types.cjs");
-//# sourceMappingURL=types.js.map
+// agent 域类型:Agent / Adapter 契约、会话与 tracing 导出配置。
+import { AGENT_DOCKERFILE_CACHE_SAFE } from "./cache-marker.js";

package/dist/assertions/coverage.d.ts

@@ -1,4 +1,4 @@
-import type { EvidenceCoverage, EvidenceCoverageEntry, EvidenceCoverageStatus, TurnEvidenceCoverage } from "../agents/types.js";
+import type { EvidenceCoverage, EvidenceCoverageEntry, EvidenceCoverageStatus, TurnEvidenceCoverage } from "../agents/types.ts";
 /** 证据通道全集(EvidenceCoverage 的键)。 */
 export declare const EVIDENCE_COVERAGE_CHANNELS: readonly ["events", "actions", "messages", "usage", "status", "data"];
 export type EvidenceCoverageChannel = (typeof EVIDENCE_COVERAGE_CHANNELS)[number];

package/dist/assertions/coverage.js

@@ -1,14 +1,94 @@
-import { createRequire as __niceevalCreateRequire } from "node:module";
-const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
-const __niceevalCanonical = __niceevalRequire("./coverage.cjs");
-const __niceevalExport0 = __niceevalCanonical["EVIDENCE_COVERAGE_CHANNELS"];
-export { __niceevalExport0 as EVIDENCE_COVERAGE_CHANNELS };
-const __niceevalExport1 = __niceevalCanonical["assertEvidenceCoverage"];
-export { __niceevalExport1 as assertEvidenceCoverage };
-const __niceevalExport2 = __niceevalCanonical["completeEvidenceCoverage"];
-export { __niceevalExport2 as completeEvidenceCoverage };
-const __niceevalExport3 = __niceevalCanonical["downgradeEvidenceCoverage"];
-export { __niceevalExport3 as downgradeEvidenceCoverage };
-const __niceevalExport4 = __niceevalCanonical["worstEvidenceCoverage"];
-export { __niceevalExport4 as worstEvidenceCoverage };
-//# sourceMappingURL=coverage.js.map
+// 证据覆盖的解析与折叠:Agent 级默认 + Turn 级降级 → attempt 级聚合
+// (见 docs/feature/adapters/architecture/evidence.md「覆盖声明」)。
+// 消费规则(正/负断言的三值折叠)在 scoped.ts;这里只管状态代数:
+// unavailable < partial < complete,Turn 只能降级、聚合取最差。
+/** 证据通道全集(EvidenceCoverage 的键)。 */
+export const EVIDENCE_COVERAGE_CHANNELS = ["events", "actions", "messages", "usage", "status", "data"];
+/**
+ * 官方 SDK 适配器用的「全通道 complete」常量:完整事件流、完整 steps/output、经过生命周期
+ * fixture 验证的 transcript 才可以声明它(见 docs/feature/adapters/architecture/evidence.md)。
+ */
+const COMPLETE_ENTRY = Object.freeze({ status: "complete" });
+export const completeEvidenceCoverage = Object.freeze({
+    events: COMPLETE_ENTRY,
+    actions: COMPLETE_ENTRY,
+    messages: COMPLETE_ENTRY,
+    usage: COMPLETE_ENTRY,
+    status: COMPLETE_ENTRY,
+    data: COMPLETE_ENTRY,
+});
+const RANK = {
+    complete: 3,
+    partial: 2,
+    unavailable: 1,
+};
+function worseOf(a, b) {
+    const ra = RANK[a.status];
+    const rb = RANK[b.status];
+    if (ra < rb)
+        return a;
+    if (rb < ra)
+        return b;
+    return a;
+}
+function assertEvidenceCoverageEntry(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${path} must be an evidence coverage entry.`);
+    }
+    const entry = value;
+    if (entry.status !== "complete" && entry.status !== "partial" && entry.status !== "unavailable") {
+        throw new Error(`${path}.status must be complete, partial, or unavailable.`);
+    }
+    if (entry.status === "complete") {
+        if (entry.reason !== undefined) {
+            throw new Error(`${path} cannot include reason when status is complete.`);
+        }
+    }
+    else if (typeof entry.reason !== "string" || entry.reason.trim().length === 0) {
+        throw new Error(`${path} requires a non-empty reason when status is ${entry.status}.`);
+    }
+}
+/** JavaScript 调用同样必须在 Agent 构造期兑现六通道与 reason 契约。 */
+export function assertEvidenceCoverage(value, owner) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${owner} requires evidenceCoverage with all six evidence channels.`);
+    }
+    const coverage = value;
+    for (const channel of EVIDENCE_COVERAGE_CHANNELS) {
+        const raw = coverage[channel];
+        if (raw === undefined) {
+            throw new Error(`${owner} requires evidenceCoverage.${channel}.`);
+        }
+        assertEvidenceCoverageEntry(raw, `${owner} evidenceCoverage.${channel}`);
+    }
+}
+/**
+ * Turn 级降级:相对 base(Agent 默认)只能变差,不能升格——Turn 声明比 base 更好的状态
+ * 直接被 base 压住(min 语义天然满足「不能把 Agent 未声明的通道升格成 complete」)。
+ */
+export function downgradeEvidenceCoverage(base, turn) {
+    if (!turn)
+        return base;
+    const out = {};
+    for (const ch of EVIDENCE_COVERAGE_CHANNELS) {
+        const d = turn[ch];
+        if (d !== undefined)
+            assertEvidenceCoverageEntry(d, `Turn.evidenceCoverage.${ch}`);
+        out[ch] = d ? worseOf(base[ch], d) : base[ch];
+    }
+    return out;
+}
+/** attempt / session 级聚合:各 turn 的最差值(unavailable < partial < complete)。 */
+export function worstEvidenceCoverage(list) {
+    if (list.length === 0)
+        return completeEvidenceCoverage;
+    let acc = list[0];
+    for (let i = 1; i < list.length; i++) {
+        const next = list[i];
+        const out = {};
+        for (const ch of EVIDENCE_COVERAGE_CHANNELS)
+            out[ch] = worseOf(acc[ch], next[ch]);
+        acc = out;
+    }
+    return acc;
+}

package/dist/assertions/diff.d.ts

@@ -1,4 +1,4 @@
-import type { DiffArtifact, DiffData, WindowChange } from "./types.js";
+import type { DiffArtifact, DiffData, WindowChange } from "./types.ts";
 /** 从窗口序列派生 DiffData:files 摘要(net / 触及窗口)+ get(最后触及窗口的终态)。 */
 export declare function deriveDiffData(windows: DiffArtifact): DiffData;
 /** DiffArtifact 里是否有任何窗口触及过任何文件。 */
@@ -17,4 +17,4 @@ export declare function elidedContentPaths(diff: DiffData): string[];
 export declare function describeElided(elided: NonNullable<WindowChange["elided"]>): string;
 /** 空 diff(remote / skipped attempt)。 */
 export declare function emptyDiffData(): DiffData;
-export type { DiffArtifact, DiffData, DiffWindow, WindowChange } from "./types.js";
+export type { DiffArtifact, DiffData, DiffWindow, WindowChange } from "./types.ts";

package/dist/assertions/diff.js

@@ -1,18 +1,116 @@
-import { createRequire as __niceevalCreateRequire } from "node:module";
-const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
-const __niceevalCanonical = __niceevalRequire("./diff.cjs");
-const __niceevalExport0 = __niceevalCanonical["deriveDiffData"];
-export { __niceevalExport0 as deriveDiffData };
-const __niceevalExport1 = __niceevalCanonical["describeElided"];
-export { __niceevalExport1 as describeElided };
-const __niceevalExport2 = __niceevalCanonical["diffIsEmpty"];
-export { __niceevalExport2 as diffIsEmpty };
-const __niceevalExport3 = __niceevalCanonical["diffMatches"];
-export { __niceevalExport3 as diffMatches };
-const __niceevalExport4 = __niceevalCanonical["elidedContentAt"];
-export { __niceevalExport4 as elidedContentAt };
-const __niceevalExport5 = __niceevalCanonical["elidedContentPaths"];
-export { __niceevalExport5 as elidedContentPaths };
-const __niceevalExport6 = __niceevalCanonical["emptyDiffData"];
-export { __niceevalExport6 as emptyDiffData };
-//# sourceMappingURL=diff.js.map
+// agent 归因 diff 的派生视图:从落盘事实(DiffWindow[])派生文件级摘要与终态读取。
+// 派生物可随时重算、不落盘——符合「聚合在消费方」铁律(docs/feature/record/architecture.md「diff.json」)。
+/** 从窗口序列派生 DiffData:files 摘要(net / 触及窗口)+ get(最后触及窗口的终态)。 */
+export function deriveDiffData(windows) {
+    const touched = new Map();
+    for (const window of windows) {
+        for (const [path, change] of Object.entries(window.changes)) {
+            const entry = touched.get(path);
+            const reason = change.elided?.reason;
+            if (entry) {
+                entry.last = change;
+                entry.windows.push(window.window);
+                // 任一窗口省略过内容,这个文件的内容视图就不完整;binary 压过 oversized-text——
+                // 一个文件不会因为某一窗口恰好小于阈值就变回可内联的文本。
+                if (reason !== undefined && (entry.elided === undefined || reason === "binary"))
+                    entry.elided = reason;
+            }
+            else {
+                touched.set(path, { first: change, last: change, windows: [window.window], ...(reason ? { elided: reason } : {}) });
+            }
+        }
+    }
+    const files = {};
+    for (const [path, entry] of touched) {
+        files[path] = {
+            net: computeNet(entry.first, entry.last),
+            windows: entry.windows,
+            ...(entry.elided ? { elided: entry.elided } : {}),
+        };
+    }
+    return {
+        windows,
+        files,
+        get(path) {
+            const entry = touched.get(path);
+            if (!entry)
+                return undefined;
+            if (entry.last.status === "deleted")
+                return undefined;
+            return entry.last.after;
+        },
+    };
+}
+/** 净效果:首个触及窗口的起点 vs 最后触及窗口的终点。 */
+function computeNet(first, last) {
+    const existedBefore = first.status !== "added";
+    const existsAfter = last.status !== "deleted";
+    if (!existedBefore && !existsAfter)
+        return "none"; // 创建又删除
+    if (!existedBefore && existsAfter)
+        return "added";
+    if (existedBefore && !existsAfter)
+        return "deleted";
+    // 改回原样 = none;比较首窗口起点与末窗口终点的内容(内容被省略的条目按字节数近似)。
+    const beforeContent = first.before ?? first.elided?.beforeBytes;
+    const afterContent = last.after ?? last.elided?.afterBytes;
+    if (beforeContent !== undefined && afterContent !== undefined && beforeContent === afterContent)
+        return "none";
+    return "modified";
+}
+/** DiffArtifact 里是否有任何窗口触及过任何文件。 */
+export function diffIsEmpty(diff) {
+    return Object.keys(diff.files).length === 0;
+}
+/** 正则是否命中任何被触及的路径或任何窗口的 before/after 内容。 */
+export function diffMatches(diff, re) {
+    for (const path of Object.keys(diff.files)) {
+        if (re.test(path))
+            return true;
+    }
+    for (const window of diff.windows) {
+        for (const change of Object.values(window.changes)) {
+            if (change.after !== undefined && re.test(change.after))
+                return true;
+            if (change.before !== undefined && re.test(change.before))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 该文件最后一个触及窗口的内容有没有被省略——`get(path)` 返回 undefined 的两个原因
+ * (净删除 / 从未触及,与内容被省略)由它区分:内容断言据此如实报证据不可用,
+ * 不把「读不到内容」静默折成判过或判败(docs/feature/sandbox/architecture.md「导出往返是常数次」)。
+ */
+export function elidedContentAt(diff, path) {
+    for (let i = diff.windows.length - 1; i >= 0; i--) {
+        const change = diff.windows[i].changes[path];
+        if (change !== undefined)
+            return change.elided;
+    }
+    return undefined;
+}
+/** 全部内容被省略的路径(任一窗口),按路径序;内容扫描类断言用它说明缺口。 */
+export function elidedContentPaths(diff) {
+    const paths = new Set();
+    for (const window of diff.windows) {
+        for (const [path, change] of Object.entries(window.changes)) {
+            if (change.elided)
+                paths.add(path);
+        }
+    }
+    return [...paths].sort();
+}
+/** 内容被省略的条目怎么向人交代:reason + 已知字节数。 */
+export function describeElided(elided) {
+    const bytes = [
+        elided.beforeBytes === undefined ? undefined : `before ${elided.beforeBytes} bytes`,
+        elided.afterBytes === undefined ? undefined : `after ${elided.afterBytes} bytes`,
+    ].filter((part) => part !== undefined);
+    return bytes.length > 0 ? `${elided.reason} (${bytes.join(", ")})` : elided.reason;
+}
+/** 空 diff(remote / skipped attempt)。 */
+export function emptyDiffData() {
+    return deriveDiffData([]);
+}

package/dist/assertions/display.d.ts

@@ -1,5 +1,5 @@
-import type { AssertionResult, PrimaryAssertionSummary } from "./types.js";
-import type { Verdict } from "../shared/types.js";
+import type { AssertionResult, PrimaryAssertionSummary } from "./types.ts";
+import type { Verdict } from "../shared/types.ts";
 /**
  * 剥离 ANSI 转义与其余不可打印控制字节,保留可打印字符与结构性空白(换行 / 制表)。给需要
  * 完整多行值的面(报告详情)直接用;`summaryText` 在此基础上再折单行 + 截断。jest 合法打印的

package/dist/assertions/display.js

@@ -1,18 +1,200 @@
-import { createRequire as __niceevalCreateRequire } from "node:module";
-const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
-const __niceevalCanonical = __niceevalRequire("./display.cjs");
-const __niceevalExport0 = __niceevalCanonical["assertionSummaryDetail"];
-export { __niceevalExport0 as assertionSummaryDetail };
-const __niceevalExport1 = __niceevalCanonical["assertionSummaryLines"];
-export { __niceevalExport1 as assertionSummaryLines };
-const __niceevalExport2 = __niceevalCanonical["compactAssertionSummary"];
-export { __niceevalExport2 as compactAssertionSummary };
-const __niceevalExport3 = __niceevalCanonical["fitCompactAssertionSummary"];
-export { __niceevalExport3 as fitCompactAssertionSummary };
-const __niceevalExport4 = __niceevalCanonical["primaryAssertionSummary"];
-export { __niceevalExport4 as primaryAssertionSummary };
-const __niceevalExport5 = __niceevalCanonical["stripControl"];
-export { __niceevalExport5 as stripControl };
-const __niceevalExport6 = __niceevalCanonical["summaryText"];
-export { __niceevalExport6 as summaryText };
-//# sourceMappingURL=display.js.map
+// assertion evaluation 结果的摘要投影。这里仅决定「摘要面显示哪一条、显示哪些事实」；完整诊断面继续
+// 消费 AssertionResult[]，不复用这个有损投影。
+/**
+ * 计分制挣分标注:"+1 pt" / "+0.8 pts"(单复数随数值)。与 report/model/format.ts 的
+ * formatPointsSuffix 同规则,assertions 层不依赖 report 层,这里独立实现同一条格式化规则。
+ */
+function pointsSuffix(points) {
+    const n = Math.round(points * 10) / 10;
+    const trimmed = Number.isInteger(n) ? String(n) : n.toFixed(1);
+    return `+${trimmed} ${n === 1 ? "pt" : "pts"}`;
+}
+/**
+ * Human/JSON 失败摘要是一条终端事实行，不是完整证据面。压成单行并设字符上限，避免 received
+ * 恰好是源码/工具输出时把多页内容灌进 scrollback；完整 AssertionResult 仍原样留给 show/view。
+ */
+const SUMMARY_TEXT_MAX_CHARS = 240;
+/**
+ * Human/JSON 永久失败行的单行事实预算，与 SUMMARY_TEXT_MAX_CHARS（单值上限）分开计:一条
+ * `matcher · expected · received` 拼起来很容易超过一屏宽,这里给的是「一行」的上限，不依赖
+ * 终端 columns——JSON 机器流不是 TTY，不能按运行时宽度变化。
+ */
+const DETAIL_LINE_MAX_CHARS = 100;
+// 捕获内容(received=命令输出 / expected=源码 / evidence)常带被测工具的着色:jest/vitest 的
+// 代码帧、行号、✕ 都由 ANSI 转义(ESC[…m 等)上色。这些 ESC(U+001B)不是 \s,若原样落进任何
+// 面,终端会重新解释它们(被单行截断从序列中间切开时尤其乱),HTML 报告则把 ESC[2m28|ESC[22m
+// 当字面文本渲染。所以任何展示面在渲染捕获内容前先剥控制字节;剥的是展示投影,不改存进
+// AssertionResult / artifact 的原始字节(完整证据仍在 events.json / diff.json)。
+// CSI(ESC[…,含 SGR 着色 / 光标控制)与 OSC(ESC]…,以 BEL 或 ST 收尾);OSC 的 payload 一并吃掉,
+// 不让它作为裸文本泄漏。没配成序列的裸 ESC 由 OTHER_CONTROL 兜底。
+// eslint-disable-next-line no-control-regex
+const ANSI_ESCAPE = /\u001B(?:\[[0-9;:?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\))/g;
+// 其余不可打印 C0/C1(含裸 ESC);保留 \t\n\f\r 交给下游折空白规则,不在这里塌成空。
+// eslint-disable-next-line no-control-regex
+const OTHER_CONTROL = /[\u0000-\u0008\u000B\u000E-\u001F\u007F-\u009F]/g;
+/**
+ * 剥离 ANSI 转义与其余不可打印控制字节,保留可打印字符与结构性空白(换行 / 制表)。给需要
+ * 完整多行值的面(报告详情)直接用;`summaryText` 在此基础上再折单行 + 截断。jest 合法打印的
+ * `✕ ✓ › ❯ ↓ │`(均 ≥ U+2020)在保留范围内,不误删。
+ */
+export function stripControl(value) {
+    return value.replace(ANSI_ESCAPE, "").replace(OTHER_CONTROL, "");
+}
+/** 摘要面的单值收口:剥控制字节 + 折单行 + 240 字符上限。任何把断言事实放进「行」里的面共用这一条。 */
+export function summaryText(value) {
+    const singleLine = stripControl(value).replace(/\s+/g, " ").trim();
+    return singleLine.length <= SUMMARY_TEXT_MAX_CHARS
+        ? singleLine
+        : `${singleLine.slice(0, SUMMARY_TEXT_MAX_CHARS - 1)}…`;
+}
+/**
+ * 按公开展示契约选择主失败断言：failed gate 优先；只有 soft 促成 failed verdict 时才取 soft；
+ * errored 且没有结构化 error 时可由第一条非 optional unavailable 解释；计分制（`evaluationKind:
+ * "points"`）`passed` 存在丢分得分点（`.points` 断言 outcome 为 failed）时取记录顺序第一条
+ * （docs/feature/assertions/library/display.md「主失败断言怎样选」规则 6）。`evaluationKind` 必填而非
+ * 默认 "pass"：调用方必须显式表态，避免漏传导致这条规则悄悄失效。
+ */
+export function primaryAssertionSummary(assertions, verdict, evaluationKind) {
+    if (verdict === "failed") {
+        const failedGates = assertions.filter((assertion) => assertion.outcome === "failed" && assertion.severity === "gate");
+        if (failedGates.length > 0)
+            return summaryOf(failedGates[0], failedGates.length - 1);
+        const failedSoft = assertions.filter((assertion) => assertion.outcome === "failed" && assertion.severity === "soft");
+        if (failedSoft.length > 0)
+            return summaryOf(failedSoft[0], failedSoft.length - 1);
+    }
+    if (verdict === "errored") {
+        const unavailable = assertions.filter((assertion) => assertion.outcome === "unavailable" && assertion.optional !== true);
+        if (unavailable.length > 0)
+            return summaryOf(unavailable[0], unavailable.length - 1);
+    }
+    if (verdict === "passed" && evaluationKind === "points") {
+        const lostPoints = assertions.filter((assertion) => assertion.outcome === "failed" && assertion.points !== undefined);
+        if (lostPoints.length > 0)
+            return summaryOf(lostPoints[0], lostPoints.length - 1);
+    }
+    return undefined;
+}
+function summaryOf(assertion, additionalFailures) {
+    const rawTitle = assertion.groupPath?.length ? assertion.groupPath.join(" > ") : assertion.name;
+    const rawMatcher = assertion.detail ?? assertion.name;
+    const title = summaryText(rawTitle);
+    return {
+        severity: assertion.severity,
+        assertion: title,
+        ...(rawMatcher !== rawTitle ? { matcher: summaryText(rawMatcher) } : {}),
+        ...(assertion.outcome === "unavailable"
+            ? { reason: summaryText(assertion.reason) }
+            : {
+                ...(assertion.expected !== undefined ? { expected: summaryText(assertion.expected) } : {}),
+                ...(assertion.received !== undefined ? { received: summaryText(assertion.received) } : {}),
+                ...(assertion.severity === "soft" || assertion.threshold !== undefined ? { score: assertion.score } : {}),
+                ...(assertion.threshold !== undefined ? { threshold: assertion.threshold } : {}),
+                ...(assertion.points !== undefined ? { points: assertion.points } : {}),
+            }),
+        additionalFailures,
+    };
+}
+/** 摘要的事实层；human/JSON renderer 用作失败事实行，表格可把它接在标题后。 */
+export function assertionSummaryDetail(summary) {
+    const parts = [];
+    if (summary.matcher !== undefined)
+        parts.push(summary.matcher);
+    if (summary.expected !== undefined)
+        parts.push(`expected ${summary.expected}`);
+    if (summary.received !== undefined)
+        parts.push(`received ${summary.received}`);
+    if (summary.score !== undefined)
+        parts.push(`score ${summary.score}`);
+    if (summary.threshold !== undefined)
+        parts.push(`threshold ${summary.threshold}`);
+    if (summary.reason !== undefined)
+        parts.push(`reason ${summary.reason}`);
+    if (summary.points !== undefined)
+        parts.push(pointsSuffix(summary.points));
+    if (summary.additionalFailures > 0)
+        parts.push(`+${summary.additionalFailures} more failures`);
+    return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+/**
+ * Human/JSON 永久失败行的排版：标题独占一行；`matcher · expected`（含 score/threshold/reason）
+ * 独占下一行；`received` 能跟这行拼在一起仍在 DETAIL_LINE_MAX_CHARS 内就合并，放不下就单独
+ * 再起一行并硬截断。`+N more failures` 永远是独立尾行，不参与截断，也不拼进被截断的值——
+ * 截断处的 `…` 后面只会是值本身，不会被人误读成计数的一部分。
+ */
+export function assertionSummaryLines(summary) {
+    const lines = [`${summary.severity}: ${summary.assertion}`];
+    const factParts = [];
+    if (summary.matcher !== undefined)
+        factParts.push(summary.matcher);
+    if (summary.expected !== undefined)
+        factParts.push(`expected ${summary.expected}`);
+    if (summary.score !== undefined)
+        factParts.push(`score ${summary.score}`);
+    if (summary.threshold !== undefined)
+        factParts.push(`threshold ${summary.threshold}`);
+    if (summary.reason !== undefined)
+        factParts.push(`reason ${summary.reason}`);
+    if (summary.points !== undefined)
+        factParts.push(pointsSuffix(summary.points));
+    const facts = factParts.length > 0 ? factParts.join(" · ") : undefined;
+    if (summary.received !== undefined) {
+        const combined = facts !== undefined ? `${facts} · received ${summary.received}` : `received ${summary.received}`;
+        if (combined.length <= DETAIL_LINE_MAX_CHARS) {
+            lines.push(combined);
+        }
+        else {
+            if (facts !== undefined)
+                lines.push(facts);
+            lines.push(shrinkTo(`received: ${summary.received}`, DETAIL_LINE_MAX_CHARS));
+        }
+    }
+    else if (facts !== undefined) {
+        lines.push(facts);
+    }
+    if (summary.additionalFailures > 0)
+        lines.push(`+${summary.additionalFailures} more failures`);
+    return lines;
+}
+/** 比较列表的单元格投影；无 group 时不重复 `gate:` 前缀。 */
+export function compactAssertionSummary(summary) {
+    const hasDistinctTitle = summary.matcher !== undefined;
+    const head = hasDistinctTitle ? `${summary.severity}: ${summary.assertion}` : summary.assertion;
+    const detail = assertionSummaryDetail(summary);
+    return detail === undefined ? head : `${head} · ${detail}`;
+}
+/** 收口用的截断:目标长度容不下时截到 target-1 并补 `…`。 */
+function shrinkTo(text, target) {
+    return text.length <= target ? text : `${text.slice(0, Math.max(0, target - 1))}…`;
+}
+/**
+ * 单元格投影的宽度收口。空间不足时按解释力从低到高让位:先截语义标题、再截 matcher,
+ * `expected / received` 与 `+N more failures` 最后截——它们直接解释为什么红。
+ * maxChars 由渲染面按可用宽度给(如两行单元格 = 2 × 列宽);字符数口径与
+ * SUMMARY_TEXT_MAX_CHARS 一致,显示宽度的精确裁剪仍归渲染面。
+ */
+export function fitCompactAssertionSummary(summary, maxChars) {
+    const budget = Math.max(24, Math.floor(maxChars));
+    let full = compactAssertionSummary(summary);
+    if (full.length <= budget)
+        return full;
+    const TITLE_FLOOR = 24;
+    let fitted = {
+        ...summary,
+        assertion: shrinkTo(summary.assertion, Math.max(TITLE_FLOOR, summary.assertion.length - (full.length - budget))),
+    };
+    full = compactAssertionSummary(fitted);
+    if (full.length <= budget)
+        return full;
+    const MATCHER_FLOOR = 16;
+    if (fitted.matcher !== undefined) {
+        fitted = {
+            ...fitted,
+            matcher: shrinkTo(fitted.matcher, Math.max(MATCHER_FLOOR, fitted.matcher.length - (full.length - budget))),
+        };
+        full = compactAssertionSummary(fitted);
+        if (full.length <= budget)
+            return full;
+    }
+    return shrinkTo(full, budget);
+}

package/dist/assertions/types.d.ts

@@ -1,7 +1,7 @@
-import type { Severity, SourceLoc } from "../shared/types.js";
-import type { DerivedFacts, StreamEvent, Usage } from "../o11y/types.js";
-import type { ResolvedEvidenceCoverage } from "./coverage.js";
-export type { EvidenceCoverageChannel, ResolvedEvidenceCoverage, ResolvedEvidenceCoverageEntry, ResolvedEvidenceCoverageStatus, } from "./coverage.js";
+import type { Severity, SourceLoc } from "../shared/types.ts";
+import type { DerivedFacts, StreamEvent, Usage } from "../o11y/types.ts";
+import type { ResolvedEvidenceCoverage } from "./coverage.ts";
+export type { EvidenceCoverageChannel, ResolvedEvidenceCoverage, ResolvedEvidenceCoverageEntry, ResolvedEvidenceCoverageStatus, } from "./coverage.ts";
 /** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值 / optional。 */
 export interface ValueAssertion {
     readonly name: string;
@@ -241,7 +241,7 @@ export interface DiffData {
     /** 该文件最后一个触及窗口结束时的内容;净删除或从未触及返回 undefined。t.sandbox.diff.get 同一语义。 */
     get(path: string): string | undefined;
 }
-export type { Verdict } from "../shared/types.js";
+export type { Verdict } from "../shared/types.ts";
 export interface JudgeConfig {
     /** 可由更低优先级层补齐；四层都未解析到时，实际 assertion 记 judge-model-unresolved。 */
     model?: string;