oh-my-knowledge 0.48.0 → 0.49.0

package/dist/eval-core/artifact-index.js

@@ -9,10 +9,15 @@
  * 三域共用 `artifactIndexDir(domain)` + tmp-rename 原子写 + 指纹缓存读 的同一套机制,各域只差「投影成卡片」
  * 与「卡片还原成 snapshot」两段域特定逻辑。
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync, unlinkSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { DEFAULT_ARTIFACT_INDEX_DIR } from './default-dirs.js';
 import { globalReportsDir, globalDoctorsDir, globalObserveHealthDir } from './measurement-dirs.js';
+import { setOwnRecordValue, sumRecordCounts } from '../shared/record-count.js';
+import { writeJsonFileAtomic } from '../shared/atomic-json.js';
+import { isRfc3339Timestamp } from '../shared/timestamp.js';
+import { reportFilePath, safeArtifactFileStem } from './artifact-file-names.js';
+import { parseReportDocument, parseReportIndexCard } from './report-document.js';
 // ── 通用机制(域无关)──────────────────────────────────────────────────────────
 /** 索引根:`OMK_ARTIFACT_INDEX_DIR` 覆盖(测试隔离,仿 OMK_TREES_DIR),默认 state/artifact-index。 */
 function artifactIndexRoot() {
@@ -32,22 +37,29 @@ export function shouldIndexReport(outputDir) {
     return shouldIndexDir(outputDir, globalReportsDir());
 }
 function safeFileName(id) {
-    return id.replaceAll(/[/\\:*?"<>|]/g, '_');
+    return safeArtifactFileStem(id);
+}
+function isCanonicalCardId(value) {
+    return typeof value === 'string' && value.length > 0 && safeFileName(value) === value;
+}
+function isCanonicalCardPath(path, id) {
+    return typeof path === 'string'
+        && resolve(path) === path
+        && reportFilePath(dirname(path), id) === path;
 }
 // 卡片读侧小 guard:索引是可重生 scratch,坏卡片(脏文件 / 别域误落 / 字段缺失)读侧从严跳过,
 // 不让 undefined / 非法枚举 / NaN 当可信输入污染 studio。
 const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);
+const isNonNegativeInteger = (v) => Number.isSafeInteger(v) && v >= 0;
+const isRate = (v) => isFiniteNumber(v) && v >= 0 && v <= 1;
 const isDoctorStatus = (v) => v === 'pass' || v === 'warn' || v === 'fail';
 const isHealthBand = (v) => v === 'green' || v === 'yellow' || v === 'red';
 const isConfidence = (v) => v === undefined || v === 'high' || v === 'low' || v === 'underpowered';
 /** 原子写一张卡片(tmp+rename,防半截 JSON 被 reader 读到)。 */
 function writeCard(domain, id, card) {
-    const indexDir = artifactIndexDir(domain);
-    mkdirSync(indexDir, { recursive: true });
-    const target = join(indexDir, `${safeFileName(id)}.json`);
-    const tmp = `${target}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    writeFileSync(tmp, JSON.stringify(card, null, 2));
-    renameSync(tmp, target);
+    if (!isCanonicalCardId(id))
+        throw new Error('invalid artifact index id');
+    writeJsonFileAtomic(join(artifactIndexDir(domain), `${id}.json`), card);
 }
 /** 读某域全部卡片,逐条用 `valid` 谓词过滤坏文件 / 缺字段(索引是 scratch,读侧从严)。 */
 function readArtifactCards(domain, valid) {
@@ -62,12 +74,14 @@ function readArtifactCards(domain, valid) {
         return [];
     }
     const out = [];
-    for (const f of files) {
+    for (const f of files.sort()) {
         if (!f.endsWith('.json') || f.includes('.json.tmp.'))
             continue;
         try {
             const c = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
-            if (valid(c))
+            if (valid(c)
+                && isCanonicalCardId(c.id)
+                && f === `${c.id}.json`)
                 out.push(c);
         }
         catch { /* skip corrupt card */ }
@@ -76,8 +90,10 @@ function readArtifactCards(domain, valid) {
 }
 /** 删某域某 id 的卡片。幂等、best-effort。返回卡片是否曾存在。 */
 function removeArtifactCard(domain, id) {
+    if (!isCanonicalCardId(id))
+        return false;
     try {
-        const p = join(artifactIndexDir(domain), `${safeFileName(id)}.json`);
+        const p = join(artifactIndexDir(domain), `${id}.json`);
         if (!existsSync(p))
             return false;
         unlinkSync(p);
@@ -103,33 +119,20 @@ function liveCards(cards) {
  * 缓存失效 → live 过滤生效。读卡片只为拿 path,字段宽松。
  */
 export function cardTargetSentinel(domain) {
-    const dir = artifactIndexDir(domain);
-    if (!existsSync(dir))
-        return '';
-    let files;
-    try {
-        files = readdirSync(dir);
-    }
-    catch {
-        return '';
-    }
+    const cards = domain === 'report'
+        ? listReportCards()
+        : domain === 'doctor'
+            ? listDoctorCards()
+            : listObserveCards();
     const parts = [];
-    for (const f of files) {
-        if (!f.endsWith('.json') || f.includes('.json.tmp.'))
-            continue;
+    for (const card of cards) {
         try {
-            const c = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
-            if (typeof c.path !== 'string')
-                continue;
-            try {
-                const s = statSync(c.path);
-                parts.push(`${f}=${s.mtimeMs}:${s.size}`);
-            }
-            catch {
-                parts.push(`${f}=gone`);
-            }
+            const stat = statSync(card.path);
+            parts.push(`${card.id}.json=${stat.mtimeMs}:${stat.size}`);
+        }
+        catch {
+            parts.push(`${card.id}.json=gone`);
         }
-        catch { /* skip corrupt */ }
     }
     return parts.sort().join(',');
 }
@@ -137,8 +140,8 @@ export function cardTargetSentinel(domain) {
 /** 报告投影成卡片(剥掉 results 重体)。 */
 function reportCard(report, sourcePath) {
     return report.kind === 'evaluation'
-        ? { domain: 'report', id: report.id, path: sourcePath, kind: 'evaluation', meta: report.meta, summary: report.summary }
-        : { domain: 'report', id: report.id, path: sourcePath, kind: 'batch-evaluation', meta: report.meta, items: report.items };
+        ? { domain: 'report', id: report.id, path: resolve(sourcePath), kind: 'evaluation', meta: report.meta, summary: report.summary }
+        : { domain: 'report', id: report.id, path: resolve(sourcePath), kind: 'batch-evaluation', meta: report.meta, items: report.items };
 }
 /**
  * persistReport 的索引钩子:报告落盘后 best-effort 追加卡片。永不抛、永不阻断报告落盘。
@@ -148,10 +151,10 @@ export function indexReportWrite(report, sourcePath, outputDir) {
     try {
         if (!shouldIndexReport(outputDir))
             return;
-        const doc = report;
-        if (doc.kind !== 'evaluation' && doc.kind !== 'batch-evaluation')
+        const parsed = parseReportDocument(report, report.id, report.id);
+        if (!parsed)
             return;
-        writeCard('report', report.id, reportCard(doc, sourcePath));
+        writeCard('report', report.id, reportCard(parsed, sourcePath));
     }
     catch {
         // 索引可重建,失败静默(可选 stderr warn);正文已落盘不受影响。
@@ -159,24 +162,12 @@ export function indexReportWrite(report, sourcePath, outputDir) {
 }
 /** 读 report 域全部卡片(跳过坏文件 / 缺字段 / 坏 kind)。 */
 export function listReportCards() {
-    return readArtifactCards('report', (c) => {
-        const card = c;
-        // kind 白名单:cardToReportDocument 对任何非 evaluation 一律按 batch 投影,坏 kind(拼错 / 'doctor')
-        // 会污染机器级 list 成空 batch 报告。索引是可重生 scratch,读侧从严跳过坏卡片。
-        const kindOk = card?.kind === 'evaluation' || card?.kind === 'batch-evaluation';
-        return !!card && card.domain === 'report' && kindOk && typeof card.id === 'string' && typeof card.path === 'string' && !!card.meta;
-    });
+    return readArtifactCards('report', (value) => parseReportIndexCard(value) !== null);
 }
 /** report 卡片(过滤悬空真身):供 studio 机器级 list / findBy 展示。 */
 export function listLiveReportCards() {
     return liveCards(listReportCards());
 }
-/** 卡片 → ReportDocument(results:[]):供 studio list / buildSkillIndex / trend 消费(它们不读 results)。 */
-export function cardToReportDocument(card) {
-    return card.kind === 'evaluation'
-        ? { kind: 'evaluation', id: card.id, meta: card.meta, summary: card.summary ?? {}, results: [] }
-        : { kind: 'batch-evaluation', id: card.id, mode: 'skill', meta: card.meta, items: card.items ?? [] };
-}
 /** 删 report 域某 id 的卡片(DELETE 报告时连卡片一起删,使其从机器级 list 消失)。幂等、best-effort。 */
 export function removeReportCard(id) {
     return removeArtifactCard('report', id);
@@ -186,7 +177,11 @@ export function indexDoctorWrite(card, outputDir) {
     try {
         if (!shouldIndexDir(outputDir, globalDoctorsDir()))
             return;
-        writeCard('doctor', card.id, { domain: 'doctor', ...card });
+        writeCard('doctor', card.id, {
+            domain: 'doctor',
+            ...card,
+            path: resolve(card.path),
+        });
     }
     catch { /* 索引可重建,失败静默 */ }
 }
@@ -194,26 +189,30 @@ export function indexDoctorWrite(card, outputDir) {
 export function listDoctorCards() {
     return readArtifactCards('doctor', (c) => {
         const card = c;
-        return !!card && card.domain === 'doctor' && typeof card.id === 'string' && typeof card.path === 'string'
-            && typeof card.skillName === 'string' && typeof card.reportId === 'string' && typeof card.timestamp === 'string'
+        return !!card && card.domain === 'doctor' && isCanonicalCardId(card.id)
+            && isCanonicalCardPath(card.path, card.id)
+            && typeof card.skillName === 'string' && card.skillName.length > 0
+            && typeof card.reportId === 'string' && card.reportId.length > 0
+            && isRfc3339Timestamp(card.timestamp)
             && isDoctorStatus(card.status)
-            && isFiniteNumber(card.passCount) && isFiniteNumber(card.warnCount) && isFiniteNumber(card.failCount);
+            && isNonNegativeInteger(card.passCount)
+            && isNonNegativeInteger(card.warnCount)
+            && isNonNegativeInteger(card.failCount)
+            && (() => {
+                try {
+                    sumRecordCounts(card.passCount, card.warnCount, card.failCount);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            })();
     });
 }
 /** doctor 卡片(过滤悬空真身):供 buildSkillIndex 机器级合并。 */
 export function listLiveDoctorCards() {
     return liveCards(listDoctorCards());
 }
-/** doctor 卡片 → (skillName, SkillDoctorSnapshot)。results:[](逐规则详情需回源项目看)。 */
-export function cardToDoctorSnapshot(card) {
-    return {
-        skillName: card.skillName,
-        snap: {
-            reportId: card.reportId, timestamp: card.timestamp, status: card.status,
-            passCount: card.passCount, warnCount: card.warnCount, failCount: card.failCount, results: [],
-        },
-    };
-}
 /** 删 doctor 域某 id(文件 stem)的卡片。doctor 历史按 50/skill prune,删正文时必须连卡片一起删,
  *  否则被 prune 掉的报告会经卡片合并在本项目 studio「复活」。 */
 export function removeDoctorCard(id) {
@@ -226,13 +225,21 @@ export function indexObserveWrite(report, sourcePath, outputDir, id) {
             return;
         const bySkill = {};
         for (const [name, h] of Object.entries(report.bySkill || {})) {
-            bySkill[name] = {
-                toolFailureRate: h.toolFailureRate, segmentCount: h.segmentCount,
-                gap: { weightedGapRate: h.gap?.weightedGapRate ?? 0 }, confidence: h.confidence,
-            };
+            setOwnRecordValue(bySkill, name, {
+                toolFailureRate: h.toolFailureRate,
+                toolFailureCount: h.toolFailureCount,
+                toolCallCount: h.toolCallCount,
+                toolResolvedCount: h.toolResolvedCount,
+                toolCancelledCount: h.toolCancelledCount,
+                toolUnknownCount: h.toolUnknownCount,
+                segmentCount: h.segmentCount,
+                gap: { weightedGapRate: h.gap?.weightedGapRate ?? 0 },
+                confidence: h.confidence,
+                stability: h.stability,
+            });
         }
         const card = {
-            domain: 'observe-health', id, path: sourcePath,
+            domain: 'observe-health', id, path: resolve(sourcePath),
             meta: { generatedAt: report.meta.generatedAt, sessionCount: report.meta.sessionCount, segmentCount: report.meta.segmentCount },
             overall: { healthBand: report.overall.healthBand, confidence: report.overall.confidence },
             bySkill,
@@ -245,26 +252,78 @@ export function indexObserveWrite(report, sourcePath, outputDir, id) {
 export function listObserveCards() {
     return readArtifactCards('observe-health', (c) => {
         const card = c;
-        if (!card || card.domain !== 'observe-health' || typeof card.id !== 'string' || typeof card.path !== 'string')
+        if (!card
+            || card.domain !== 'observe-health'
+            || !isCanonicalCardId(card.id)
+            || !isCanonicalCardPath(card.path, card.id))
             return false;
         const meta = card.meta;
         const overall = card.overall;
         const bySkill = card.bySkill;
-        if (!meta || !isFiniteNumber(meta.sessionCount) || !isFiniteNumber(meta.segmentCount) || typeof meta.generatedAt !== 'string')
+        if (!meta
+            || !isNonNegativeInteger(meta.sessionCount)
+            || !isNonNegativeInteger(meta.segmentCount)
+            || !isRfc3339Timestamp(meta.generatedAt))
             return false;
         if (!overall || !isHealthBand(overall.healthBand) || !isConfidence(overall.confidence))
             return false;
-        if (!bySkill || typeof bySkill !== 'object')
+        if (!bySkill || typeof bySkill !== 'object' || Array.isArray(bySkill))
             return false;
         // 每个 skill 的标量也校验:坏 toolFailureRate / segmentCount / gap.weightedGapRate 会让 bandFromObserveHealth /
         // 趋势 / 健康快照出 NaN(buildSkillIndex 直接取 h.gap?.weightedGapRate ?? 0 进 gapRate、参与阈值判断)。
-        for (const h of Object.values(bySkill)) {
-            if (!h || !isFiniteNumber(h.toolFailureRate) || !isFiniteNumber(h.segmentCount) || !isConfidence(h.confidence))
+        const segmentCounts = [];
+        for (const [skillName, h] of Object.entries(bySkill)) {
+            if (skillName.length === 0)
+                return false;
+            if (!h || !isRate(h.toolFailureRate) || !isNonNegativeInteger(h.segmentCount) || !isConfidence(h.confidence))
+                return false;
+            segmentCounts.push(h.segmentCount);
+            if (h.toolFailureCount !== undefined && !isNonNegativeInteger(h.toolFailureCount))
+                return false;
+            if (h.toolCallCount !== undefined && !isNonNegativeInteger(h.toolCallCount))
+                return false;
+            if (h.toolResolvedCount !== undefined && !isNonNegativeInteger(h.toolResolvedCount))
+                return false;
+            if (h.toolCancelledCount !== undefined && !isNonNegativeInteger(h.toolCancelledCount))
+                return false;
+            if (h.toolUnknownCount !== undefined && !isNonNegativeInteger(h.toolUnknownCount))
                 return false;
-            if (h.gap !== undefined && h.gap.weightedGapRate !== undefined && !isFiniteNumber(h.gap.weightedGapRate))
+            if (h.toolCallCount === undefined
+                && (h.toolResolvedCount !== undefined
+                    || h.toolCancelledCount !== undefined
+                    || h.toolUnknownCount !== undefined))
+                return false;
+            if (h.toolCallCount !== undefined
+                && ((h.toolResolvedCount ?? 0) > h.toolCallCount
+                    || (h.toolCancelledCount ?? 0) > (h.toolResolvedCount ?? h.toolCallCount)
+                    || (h.toolUnknownCount ?? 0) > h.toolCallCount
+                    || (h.toolResolvedCount !== undefined
+                        && h.toolUnknownCount !== undefined
+                        && h.toolResolvedCount + h.toolUnknownCount !== h.toolCallCount)))
+                return false;
+            if (h.toolFailureCount !== undefined
+                && h.toolCallCount !== undefined) {
+                const resolved = h.toolResolvedCount ?? h.toolCallCount;
+                const comparable = resolved - (h.toolCancelledCount ?? 0);
+                const expectedFailureRate = comparable > 0
+                    ? Number((h.toolFailureCount / comparable).toFixed(4))
+                    : 0;
+                if (h.toolFailureCount > comparable
+                    || Math.abs(h.toolFailureRate - expectedFailureRate) > 0.0001)
+                    return false;
+            }
+            if (h.stability !== undefined
+                && !['stable', 'unstable', 'very-unstable', 'unknown'].includes(h.stability))
+                return false;
+            if (h.gap !== undefined && h.gap.weightedGapRate !== undefined && !isRate(h.gap.weightedGapRate))
                 return false;
         }
-        return true;
+        try {
+            return sumRecordCounts(...segmentCounts) === meta.segmentCount;
+        }
+        catch {
+            return false;
+        }
     });
 }
 /** observe 卡片(过滤悬空真身):供 listAnalyses / buildSkillIndex 机器级合并。 */

package/dist/eval-core/cache.d.ts

@@ -2,8 +2,9 @@
  * Executor result cache.
  *
  * Caches successful executor results to disk to avoid redundant API calls.
- * Cache key v6 = sha256(model + system + prompt + cwd + allowedSkills + executor +
- *                       runtime + mocks + mocksStrict + effort + artifactContentHash).
+ * Cache key v9 = sha256(model + system + prompt + cwd + allowedSkills + executor +
+ *                       runtime + mocks + mocksStrict + effort + artifactContentHash +
+ *                       sampleExecutionDependencyHash).
  * Loaded into memory on init, flushed to disk on save().
  *
  * Prefix bumps intentionally invalidate old entries when construct-validity
@@ -20,6 +21,12 @@
  *       不动 system → 旧 key 会命中旧输出、贴到新 artifactHashes 上,形成静默测量污染。把
  *       contentHash 纳入 key,资产变即重跑。git skill 的 contentHash 只随 SKILL.md 变(其资产不
  *       暴露给 executor、本就不该触发重跑),口径自洽
+ * - v7: executor 返回值进入统一契约校验，且所有未知成本路径显式记录 provenance。
+ *       旧缓存缺少这些语义，不能在新报告中继续复用。
+ * - v8: 所有 executor 的工具身份在统一边界归一化。旧缓存里的 provider-native
+ *       工具名不能继续参与 source-neutral 工具断言与分布统计。
+ * - v9: sample mock 的 `return_file` 内容指纹进入 key。只哈声明路径会在 fixture
+ *       内容变化后错误复用旧执行结果。
  */
 import type { ExecutorCache } from '../types/index.js';
 export declare function createCache(cacheDir: string): ExecutorCache;
@@ -35,4 +42,6 @@ mocksStrict?: boolean,
 effort?: string, 
 /** artifact 内容指纹(整树 / 单文件哈)。本地 dir-skill 改 references/ 资产只动此值、不动 system,
  *  不进 key 会让改资产后命中旧输出 → 静默污染。空(baseline / 无 skill)等价无指纹。 */
-artifactContentHash?: string): string;
+artifactContentHash?: string, 
+/** External sample files that can alter executor output, currently mock return_file fixtures. */
+sampleExecutionDependencyHash?: string): string;

package/dist/eval-core/cache.js

@@ -2,8 +2,9 @@
  * Executor result cache.
  *
  * Caches successful executor results to disk to avoid redundant API calls.
- * Cache key v6 = sha256(model + system + prompt + cwd + allowedSkills + executor +
- *                       runtime + mocks + mocksStrict + effort + artifactContentHash).
+ * Cache key v9 = sha256(model + system + prompt + cwd + allowedSkills + executor +
+ *                       runtime + mocks + mocksStrict + effort + artifactContentHash +
+ *                       sampleExecutionDependencyHash).
  * Loaded into memory on init, flushed to disk on save().
  *
  * Prefix bumps intentionally invalidate old entries when construct-validity
@@ -20,10 +21,19 @@
  *       不动 system → 旧 key 会命中旧输出、贴到新 artifactHashes 上,形成静默测量污染。把
  *       contentHash 纳入 key,资产变即重跑。git skill 的 contentHash 只随 SKILL.md 变(其资产不
  *       暴露给 executor、本就不该触发重跑),口径自洽
+ * - v7: executor 返回值进入统一契约校验，且所有未知成本路径显式记录 provenance。
+ *       旧缓存缺少这些语义，不能在新报告中继续复用。
+ * - v8: 所有 executor 的工具身份在统一边界归一化。旧缓存里的 provider-native
+ *       工具名不能继续参与 source-neutral 工具断言与分布统计。
+ * - v9: sample mock 的 `return_file` 内容指纹进入 key。只哈声明路径会在 fixture
+ *       内容变化后错误复用旧执行结果。
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
+import { executorResultValidationError, normalizeExecResultToolIdentities, parseExecResult, } from '../shared/executor-result.js';
+import { writeJsonFileAtomic } from '../shared/atomic-json.js';
+import { withFileLock } from '../shared/file-lock.js';
 const CACHE_FILE = 'executor-cache.json';
 /** v5 保留 turns / toolCalls 后单 entry 可达 5–50 KB,长期使用会无界膨胀。
  *  Map iteration 是插入序,set() 时若 key 已存在先 delete 再 set 把它移到末尾 → 实现 LRU。
@@ -46,22 +56,9 @@ export function createCache(cacheDir) {
     mkdirSync(cacheDir, { recursive: true });
     const filePath = join(cacheDir, CACHE_FILE);
     const cap = resolveCacheCap();
-    // 用 Map 替代 Record:Map 保证 iteration 顺序 = 插入顺序,LRU 淘汰用得上。
-    // 老 JSON cache 文件仍按 Record<string, ExecResult> 写,反序列化时 Object.entries
-    // 转 Map(Object 字段顺序在主流引擎里也是插入序,所以 LRU 信号不丢)。
-    const store = new Map();
-    if (existsSync(filePath)) {
-        try {
-            const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
-            for (const [k, v] of Object.entries(raw))
-                store.set(k, v);
-            // 加载完也 enforce 一次 cap,处理上次 process exit 前没保存到的极端膨胀。
-            evictUntilWithinCap(store, cap);
-        }
-        catch {
-            // 老 cache 坏了忽略 — 重跑会重建。
-        }
-    }
+    const store = readCacheStore(filePath, cap);
+    const pendingWrites = new Map();
+    const touchedKeys = new Set();
     let dirty = false;
     return {
         get(key) {
@@ -71,6 +68,7 @@ export function createCache(cacheDir) {
             // LRU touch:命中时移到末尾(最新)。这样 evict 时永远从最旧端拿。
             store.delete(key);
             store.set(key, v);
+            touchedKeys.add(key);
             dirty = true;
             return v;
         },
@@ -78,21 +76,51 @@ export function createCache(cacheDir) {
             // 保留完整 ExecResult(含 turns / toolCalls):工具类 assertion (tool_called /
             // tool_input_contains / tools_called)和 diagnostic 要看 trace,砍掉的话 cached
             // rerun 进 grade() 时工具断言为空、diagnostic 没真实证据,跟 cold run 不一致。
+            const validationError = executorResultValidationError(value);
+            if (validationError)
+                throw new Error(`invalid executor cache entry: ${validationError}`);
+            const normalized = normalizeExecResultToolIdentities(value);
             if (store.has(key))
                 store.delete(key);
-            store.set(key, { ...value });
+            store.set(key, normalized);
+            pendingWrites.delete(key);
+            pendingWrites.set(key, normalized);
+            touchedKeys.delete(key);
             evictUntilWithinCap(store, cap);
+            for (const pendingKey of pendingWrites.keys()) {
+                if (!store.has(pendingKey))
+                    pendingWrites.delete(pendingKey);
+            }
             dirty = true;
         },
         save() {
             if (!dirty)
                 return;
-            // 序列化时用普通 object,跟老 cache 文件格式兼容(读老报告不破)。
-            // Map iteration 是插入序,生成的 object 字段顺序也保留 LRU 状态,下次加载继续生效。
-            const obj = {};
-            for (const [k, v] of store)
-                obj[k] = v;
-            writeFileSync(filePath, JSON.stringify(obj, null, 2));
+            withFileLock(`${filePath}.lock`, () => {
+                // Another eval process may have saved after this cache instance loaded.
+                // Merge only local writes and LRU touches into the latest disk state;
+                // replacing it with the whole stale in-memory snapshot loses entries.
+                const merged = readCacheStore(filePath, cap);
+                for (const key of touchedKeys) {
+                    const value = merged.get(key);
+                    if (!value)
+                        continue;
+                    merged.delete(key);
+                    merged.set(key, value);
+                }
+                for (const [key, value] of pendingWrites) {
+                    if (merged.has(key))
+                        merged.delete(key);
+                    merged.set(key, value);
+                }
+                evictUntilWithinCap(merged, cap);
+                writeCacheStore(filePath, merged);
+                store.clear();
+                for (const [key, value] of merged)
+                    store.set(key, value);
+            }, { label: 'executor cache' });
+            pendingWrites.clear();
+            touchedKeys.clear();
             dirty = false;
         },
         size() {
@@ -100,6 +128,36 @@ export function createCache(cacheDir) {
         },
     };
 }
+function readCacheStore(filePath, cap) {
+    // Map guarantees iteration order, which is the persisted LRU order.
+    const store = new Map();
+    if (!existsSync(filePath))
+        return store;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new Error('invalid executor cache root');
+        }
+        for (const [key, value] of Object.entries(raw)) {
+            const parsed = parseExecResult(value);
+            if (parsed)
+                store.set(key, parsed);
+        }
+        evictUntilWithinCap(store, cap);
+    }
+    catch {
+        // A corrupt cache is disposable evidence acceleration, never report data.
+        store.clear();
+    }
+    return store;
+}
+function writeCacheStore(filePath, store) {
+    // Keep the historical JSON object format. Property order carries LRU state.
+    const serialized = {};
+    for (const [key, value] of store)
+        serialized[key] = value;
+    writeJsonFileAtomic(filePath, serialized);
+}
 function evictUntilWithinCap(store, cap) {
     if (!Number.isFinite(cap))
         return;
@@ -122,7 +180,9 @@ mocksStrict,
 effort, 
 /** artifact 内容指纹(整树 / 单文件哈)。本地 dir-skill 改 references/ 资产只动此值、不动 system,
  *  不进 key 会让改资产后命中旧输出 → 静默污染。空(baseline / 无 skill)等价无指纹。 */
-artifactContentHash) {
+artifactContentHash, 
+/** External sample files that can alter executor output, currently mock return_file fixtures. */
+sampleExecutionDependencyHash) {
     // allowedSkills 序列化:undefined → "" / [] → "[]" / [...] → 排序后 JSON。
     // 排序保证 ["a","b"] 和 ["b","a"] 命中同一缓存(语义等价)。
     const isoStr = allowedSkills === undefined
@@ -138,8 +198,8 @@ artifactContentHash) {
     // executor + runtime + effort 进 cache key:同 model 名走不同 executor 或同 executor
     // 换 binary/SDK 版本时输出可能不同,旧 cache 不可复用。
     const hash = createHash('sha256')
-        .update(`${model || ''}\n${system || ''}\n${prompt || ''}\n${cwd || ''}\n${isoStr}\n${executor || ''}\n${runtimeFingerprint || ''}\n${mockStr}\n${strictStr}\n${effortStr}\n${artifactContentHash || ''}`)
+        .update(`${model || ''}\n${system || ''}\n${prompt || ''}\n${cwd || ''}\n${isoStr}\n${executor || ''}\n${runtimeFingerprint || ''}\n${mockStr}\n${strictStr}\n${effortStr}\n${artifactContentHash || ''}\n${sampleExecutionDependencyHash || ''}`)
         .digest('hex')
         .slice(0, 16);
-    return `v6:${hash}`;
+    return `v9:${hash}`;
 }

package/dist/eval-core/comparability.js

@@ -1,3 +1,4 @@
+import { ownRecordValue } from '../shared/record-count.js';
 function stableStringify(value) {
     if (value === null || typeof value !== 'object')
         return JSON.stringify(value);
@@ -88,7 +89,7 @@ function runtimeMapKeys(meta) {
 function reportExecutorRuntimeWarnings(report, warnings) {
     const runtimes = report.meta.executorRuntimes;
     if (runtimes && Object.keys(runtimes).length > 0) {
-        const missing = report.meta.variants.filter((variant) => !runtimes[variant]);
+        const missing = report.meta.variants.filter((variant) => !ownRecordValue(runtimes, variant));
         if (missing.length > 0) {
             push(warnings, 'executor_runtime_missing', `报告缺少部分 variant 的 executor runtime 指纹: ${missing.join(', ')}。`, `Report is missing executor runtime fingerprints for variants: ${missing.join(', ')}.`);
         }
@@ -116,12 +117,14 @@ function countSampleHashMismatches(a, b) {
     let common = 0;
     const ids = new Set([...Object.keys(ah), ...Object.keys(bh)]);
     for (const id of ids) {
-        if (ah[id] == null || bh[id] == null) {
+        const aHash = ownRecordValue(ah, id);
+        const bHash = ownRecordValue(bh, id);
+        if (aHash == null || bHash == null) {
             missing++;
             continue;
         }
         common++;
-        if (ah[id] !== bh[id])
+        if (aHash !== bHash)
             mismatched++;
     }
     return { mismatched, missing, common };
@@ -175,13 +178,14 @@ export function crossReportComparabilityWarnings(before, after) {
     const hasExecutorRuntimeMap = bExecutorRuntimeKeys.length > 0 || aExecutorRuntimeKeys.length > 0;
     if (hasExecutorRuntimeMap) {
         const keys = sorted([...new Set([...b.variants, ...a.variants, ...bExecutorRuntimeKeys, ...aExecutorRuntimeKeys])]);
-        const missing = keys.filter((key) => !b.executorRuntimes?.[key] || !a.executorRuntimes?.[key]);
+        const missing = keys.filter((key) => !ownRecordValue(b.executorRuntimes ?? {}, key)
+            || !ownRecordValue(a.executorRuntimes ?? {}, key));
         if (missing.length > 0) {
             push(warnings, 'executor_runtime_missing', `至少一份报告缺少 per-variant executor runtime 指纹: ${missing.join(', ')}。`, `At least one report is missing per-variant executor runtime fingerprints: ${missing.join(', ')}.`);
         }
         for (const key of keys) {
-            const beforeRuntime = b.executorRuntimes?.[key];
-            const afterRuntime = a.executorRuntimes?.[key];
+            const beforeRuntime = ownRecordValue(b.executorRuntimes ?? {}, key);
+            const afterRuntime = ownRecordValue(a.executorRuntimes ?? {}, key);
             if (beforeRuntime?.fingerprint && afterRuntime?.fingerprint && beforeRuntime.fingerprint !== afterRuntime.fingerprint) {
                 push(warnings, 'executor_runtime_mismatch', `variant ${key} executor runtime 指纹不同: ${runtimeLabel(beforeRuntime)} → ${runtimeLabel(afterRuntime)}。`, `Variant ${key} executor runtime fingerprint changed: ${runtimeLabel(beforeRuntime)} → ${runtimeLabel(afterRuntime)}.`);
             }

package/dist/eval-core/evaluation-execution.d.ts

@@ -49,7 +49,8 @@ export declare function executeTasks({ tasks, executor, executorName, model, noJ
     skipped: number;
     budgetExhausted: boolean;
 }>;
-export declare function preflight(executor: ExecutorFn, model: string, timeoutMs?: number): Promise<void>;
+export declare function preflightRuntimeLabel(executorName: string, model: string): string;
+export declare function preflight(executor: ExecutorFn, model: string, timeoutMs?: number, label?: string): Promise<void>;
 /**
  * Preflight every unique `(executor, model)` judge in `judgeModels`. Used by the
  * eval pipeline to fail fast when any ensemble member is misconfigured (404 model,