oh-my-knowledge 1.0.0-beta.2 → 1.0.0-beta.3

package/README.md

@@ -228,7 +228,7 @@ The full docs are published at **[oh-my-knowledge.pages.dev](https://oh-my-knowl
 - **[CLI reference](docs/reference/cli.md)** — all top-level commands with bash examples and flag tables
 - **[Migrate to the 1.0 preview](docs/guides/v1-preview-migration.md)** — install channel, storage reset, sample protocol, CLI automation, and embedded API changes since 0.54
 - **[Evaluation Core cutover](docs/guides/eval-core-cutover.md)** — `BREAKING-SCHEMA` storage, resume, Studio, Gold, managed-evidence, and evolve migration
-- **[Embed OMK in a service](docs/guides/eval-runtime.md)** — lightweight `eval-runtime` assembly for Node.js and FaaS hosts
+- **[Embed OMK in a service](docs/guides/eval-runtime.md)** — one `evaluate()` API for Node.js and FaaS hosts
 - **[Storage layout v2](docs/specs/storage-layout-spec.md)** — project/global domains, compatibility boundary, and Git policy
 - **[Executors](docs/reference/executors.md)** & **[artifact layout](docs/reference/artifact-layout.md)** — built-in / custom executors; how `variant` resolves to an artifact + runtime context
 - **[How-to guides](docs/guides/agent-eval.md)** — [evaluate an agent](docs/guides/agent-eval.md) (project runtime context) and [use non-Claude models](docs/guides/non-claude-models.md) (GLM / Qwen / DeepSeek / Moonshot / Ollama)

package/README.zh.md

@@ -157,7 +157,7 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 
 | 特性 | 说明 |
 |------|------|
-| **Core 发布决定** | 六种结论 + 稳定 reason code + exit code 路由；Studio 投影同一份经过认证的 Decision |
+| **Core 发布决定** | 六种判定 + 稳定 reason code + exit code 路由；Studio 投影同一份经过认证的 Decision |
 | **五层 evidence graph** | Assertion / LLM / Judge / Dimension / Composite 保持独立，coverage、成本、状态与 lineage 与分数正交 |
 | **多执行器** | 支持 Claude CLI / Claude SDK / Codex CLI / Codex SDK / DeepSeek Harness / OpenAI / Anthropic API 及自定义命令 |
 | **30+ 种断言** | 包含子串、正则、JSON Schema、ROUGE/BLEU/Levenshtein 相似度、Agent 工具调用、语义相似度、自定义函数等 |
@@ -228,7 +228,7 @@ omk-mcp
 - **[CLI 参考](docs/zh/reference/cli.md)** —— 顶层命令的 bash 示例和 flag 表
 - **[迁移到 1.0 预览版](docs/zh/guides/v1-preview-migration.md)** —— 从 `0.54` 升级时的安装渠道、存储重建、用例协议、CLI 自动化与嵌入式 API 变化
 - **[Evaluation Core 生产切换](docs/zh/guides/eval-core-cutover.md)** —— `BREAKING-SCHEMA` 存储、resume、Studio、Gold、受管证据与 evolve 迁移
-- **[在服务中嵌入 OMK](docs/zh/guides/eval-runtime.md)** —— 面向 Node.js 与 FaaS 宿主的轻量 `eval-runtime` 装配
+- **[在服务中嵌入 OMK](docs/zh/guides/eval-runtime.md)** —— 面向 Node.js 与 FaaS 宿主的单一 `evaluate()` API
 - **[存储布局 v2](docs/zh/specs/storage-layout-spec.md)** —— 项目／全局领域、迁移兼容与 Git 策略
 - **[执行器](docs/zh/reference/executors.md)** & **[知识载体布局](docs/zh/reference/artifact-layout.md)** —— 内置 / 自定义执行器；variant 如何解析为 artifact + runtime context
 - **[操作指南](docs/zh/guides/agent-eval.md)** —— [评测 agent](docs/zh/guides/agent-eval.md)（项目 runtime context）与[使用非 Claude 模型](docs/zh/guides/non-claude-models.md)（GLM / 通义 / DeepSeek / Moonshot / Ollama）

package/dist/assets/agent-skills/omk/references/commands.md

@@ -63,7 +63,7 @@ omk doctor --json --gate
 
 ## omk eval
 
-跑评测：对一个 control vs 多个 treatment skill 做对照试验，产 verdict 报告。
+跑评测：用一个对照组与多个实验组 skill 做对照试验，生成判定报告。
 
 **用法:**
 
@@ -73,16 +73,16 @@ omk eval [flags]
 
 **Flags:**
 
-- `--batch` `boolean`:batch 模式:baseline vs 每个 skill
+- `--batch` `boolean`:batch 模式：baseline 作为对照组，逐个 skill 作为实验组
 - `--bootstrap` `boolean`:加 bootstrap CI
 - `--bootstrap-samples` `option`:bootstrap 重采样次数，默认 1000
-- `--budget-per-sample-ms` `option`:单 sample 时长上限 ms（必须 > 0，不传则无上限）
-- `--budget-per-sample-usd` `option`:单 sample 预算上限 USD（必须 > 0，不传则无上限）
+- `--budget-per-sample-ms` `option`:单用例时长上限 ms（必须 > 0，不传则无上限）
+- `--budget-per-sample-usd` `option`:单用例预算上限 USD（必须 > 0，不传则无上限）
 - `--budget-usd` `option`:总预算上限 USD（必须 > 0，不传则无上限）
 - `--concurrency` `option`:并发数，默认 1
 - `--config` `option`:eval.yaml 路径
-- `--control` `option`:control variant 表达式（仅 artifact 身份）
-- `--control-cwd` `option`:control 的 runtime context 目录
+- `--control` `option`:对照组（control）的 variant 表达式（仅 artifact 身份）
+- `--control-cwd` `option`:对照组（control）的 runtime context 目录
 - `--dry-run` `boolean`:只 plan 不实跑
 - `--effort` `option`:被测 LLM 扩展思考预算 low/medium/high/xhigh/max（默认 low；跨 effort 报告不严格可比）。
 - `--executor` `option`:执行器：claude / claude-sdk / codex / codex-sdk / anthropic-api / openai-api / 自定义命令。Codex 任务内自动用 codex；也可用 OMK_EXECUTOR 设置环境偏好。
@@ -90,7 +90,7 @@ omk eval [flags]
 - `--gold-dir` `option`:gold dataset 目录
 - `--holdout-ratio` `option`:留出比例 0-1（如 0.3）；切出 holdout 子集，对比 train/holdout 综合分检测过拟合
 - `--judge-models` `option`:评委配置，格式 executor:model[,...]，例 claude:haiku 或 codex:<model>（≥ 2 个 = ensemble）。默认跟随所选执行器；Codex 沿用被测模型。
-- `--judge-repeat` `option`:每个 dim 评 N 次
+- `--judge-repeat` `option`:每个维度由评委评价 N 次
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--layered-stats` `boolean`:输出分层统计
 - `--mcp-config` `option`:MCP 配置文件路径
@@ -99,30 +99,30 @@ omk eval [flags]
 - `--no-debias-length` `boolean`:关 length-debias（默认开）
 - `--no-diagnostic` `boolean`:关闭基于 Core 失败、缺失、排除与稳定 reason code 的诊断投影。
 - `--no-evidence` `boolean`:不把本次评测写成证据追加进受管记录(默认会为已 install 的 skill 自动写)。
-- `--no-gate` `boolean`:关 verdict gate
-- `--no-judge` `boolean`:跳过 LLM judge
+- `--no-gate` `boolean`:关闭判定门禁
+- `--no-judge` `boolean`:跳过 LLM 评委
 - `--no-serve` `boolean`:不启 report server
 - `--no-strict-baseline` `boolean`:关闭 baseline 隔离
 - `--output-dir` `option`:报告输出目录（默认项目级 .omk/eval）
-- `--repeat` `option`:每个 sample 重复跑 N 次
-- `--report-only` `boolean`:生成报告并打印 verdict，但始终 exit 0(不参与 CI gate）。
+- `--repeat` `option`:每个用例重复运行 N 次
+- `--report-only` `boolean`:生成报告并打印判定，但始终 exit 0(不参与 CI gate）。
 - `--resume` `option`:复用经过完整契约校验的 Core runId；拒绝时失败关闭
-- `--retry` `option`:失败 sample 重试次数
-- `--samples` `option`:用例路径。自动发现项目级或单 treatment 目录 skill 下的 eval-samples.json / eval-samples.yaml；显式路径可为 JSON / YAML 文件或分片目录。
+- `--retry` `option`:单用例失败重试次数
+- `--samples` `option`:用例路径。自动发现项目级或单个实验组（treatment）目录 skill 下的 eval-samples.json / eval-samples.yaml；显式路径可为 JSON / YAML 文件或分片目录。
 - `--skill-dir` `option`:skill 目录，默认 skills
 - `--skip-connectivity` `boolean`:跳 LLM 连通性预检
 - `--skip-doctor` `boolean`:escape hatch:跳 doctor 健康检查门禁（默认强制启用）。沙箱 mock 提供依赖时绕开 doctor 物理路径误报；garbage-in 风险自负。
 - `--strict-baseline` `boolean`:强制 baseline 隔离（default true）
-- `--threshold` `option`:verdict 阈值，默认 3.5
+- `--threshold` `option`:判定阈值，默认 3.5
 - `--timeout` `option`:单用例超时秒，默认 120
-- `--treatment` `option`:treatment variant 列表，逗号分隔（仅 artifact 身份）
-- `--treatment-cwd` `option`:treatment 的 runtime context 目录列表，逗号分隔、与 --treatment 按序对齐（空位 = 无 cwd）
+- `--treatment` `option`:实验组（treatment）的 variant 列表，逗号分隔（仅 artifact 身份）
+- `--treatment-cwd` `option`:实验组（treatment）的 runtime context 目录列表，逗号分隔、与 --treatment 按序对齐（空位 = 无 cwd）
 - `--trivial-diff` `option`:可忽略 diff 容差，0 表示不启用容差
 - `--verbose` `boolean`:详细日志
 
 **示例:**
 
-> 最简对照:baseline vs my-skill
+> 最简对照：baseline 作为对照组，my-skill 作为实验组
 
 ```bash
 omk eval --control baseline --treatment my-skill

package/dist/cli/commands/eval/index.js

@@ -174,13 +174,13 @@ async function runEval(_args, flags, lang) {
 }
 export default class Eval extends BaseCommand {
     static description = bilingual({
-        zh: '跑评测：对一个 control vs 多个 treatment skill 做对照试验，产 verdict 报告。',
+        zh: '跑评测：用一个对照组与多个实验组 skill 做对照试验，生成判定报告。',
         en: 'Run evaluation: control vs treatment(s) comparison, produce verdict report.',
     });
     static examples = [
         {
             description: bilingual({
-                zh: '最简对照:baseline vs my-skill',
+                zh: '最简对照：baseline 作为对照组，my-skill 作为实验组',
                 en: 'Minimal A/B: baseline vs my-skill',
             }),
             command: '<%= config.bin %> eval --control baseline --treatment my-skill',
@@ -197,23 +197,23 @@ export default class Eval extends BaseCommand {
         lang: LANG_FLAG,
         // ── 实验角色 ──
         control: Flags.string({
-            description: bilingual({ zh: 'control variant 表达式（仅 artifact 身份）', en: 'Control variant expr (artifact identity only)' }),
+            description: bilingual({ zh: '对照组（control）的 variant 表达式（仅 artifact 身份）', en: 'Control variant expr (artifact identity only)' }),
         }),
         treatment: Flags.string({
             description: bilingual({
-                zh: 'treatment variant 列表，逗号分隔（仅 artifact 身份）',
+                zh: '实验组（treatment）的 variant 列表，逗号分隔（仅 artifact 身份）',
                 en: 'Treatment variants, comma-separated (artifact identity only)',
             }),
         }),
         'control-cwd': Flags.string({
             description: bilingual({
-                zh: 'control 的 runtime context 目录',
+                zh: '对照组（control）的 runtime context 目录',
                 en: 'Runtime context dir for control',
             }),
         }),
         'treatment-cwd': Flags.string({
             description: bilingual({
-                zh: 'treatment 的 runtime context 目录列表，逗号分隔、与 --treatment 按序对齐（空位 = 无 cwd）',
+                zh: '实验组（treatment）的 runtime context 目录列表，逗号分隔、与 --treatment 按序对齐（空位 = 无 cwd）',
                 en: 'Runtime context dirs for treatments, comma-separated, index-aligned with --treatment (blank = none)',
             }),
         }),
@@ -222,7 +222,7 @@ export default class Eval extends BaseCommand {
         }),
         samples: Flags.string({
             description: bilingual({
-                zh: '用例路径。自动发现项目级或单 treatment 目录 skill 下的 eval-samples.json / eval-samples.yaml；显式路径可为 JSON / YAML 文件或分片目录。',
+                zh: '用例路径。自动发现项目级或单个实验组（treatment）目录 skill 下的 eval-samples.json / eval-samples.yaml；显式路径可为 JSON / YAML 文件或分片目录。',
                 en: 'Samples path. Auto-discovers eval-samples.json / eval-samples.yaml at project scope or for a single directory-skill treatment; an explicit path may be a JSON / YAML file or split directory.',
             }),
         }),
@@ -256,7 +256,7 @@ export default class Eval extends BaseCommand {
         }),
         // ── 评测 toggle ──
         'no-judge': Flags.boolean({
-            description: bilingual({ zh: '跳过 LLM judge', en: 'Skip LLM judge' }),
+            description: bilingual({ zh: '跳过 LLM 评委', en: 'Skip LLM judge' }),
         }),
         'no-cache': Flags.boolean({
             description: bilingual({ zh: '跳过 executor cache', en: 'Skip executor cache' }),
@@ -277,7 +277,7 @@ export default class Eval extends BaseCommand {
         }),
         batch: Flags.boolean({
             description: bilingual({
-                zh: 'batch 模式:baseline vs 每个 skill',
+                zh: 'batch 模式：baseline 作为对照组，逐个 skill 作为实验组',
                 en: 'Batch mode: baseline vs each skill',
             }),
         }),
@@ -300,7 +300,7 @@ export default class Eval extends BaseCommand {
             description: bilingual({ zh: '详细日志', en: 'Verbose logging' }),
         }),
         retry: Flags.string({
-            description: bilingual({ zh: '失败 sample 重试次数', en: 'Per-sample retry count' }),
+            description: bilingual({ zh: '单用例失败重试次数', en: 'Per-sample retry count' }),
             parse: integerStringParser('--retry', { min: 0 }),
         }),
         resume: Flags.string({
@@ -333,7 +333,7 @@ export default class Eval extends BaseCommand {
         }),
         // ── eval-runner extra ──
         repeat: Flags.string({
-            description: bilingual({ zh: '每个 sample 重复跑 N 次', en: 'Repeat each sample N times' }),
+            description: bilingual({ zh: '每个用例重复运行 N 次', en: 'Repeat each sample N times' }),
             parse: integerStringParser('--repeat', { min: 1 }),
         }),
         'holdout-ratio': Flags.string({
@@ -344,7 +344,7 @@ export default class Eval extends BaseCommand {
             parse: numberStringParser('--holdout-ratio', { min: 0, max: 1 }),
         }),
         'judge-repeat': Flags.string({
-            description: bilingual({ zh: '每个 dim 评 N 次', en: 'Judge each dim N times' }),
+            description: bilingual({ zh: '每个维度由评委评价 N 次', en: 'Judge each dim N times' }),
             parse: integerStringParser('--judge-repeat', { min: 1 }),
         }),
         bootstrap: Flags.boolean({
@@ -365,16 +365,16 @@ export default class Eval extends BaseCommand {
             parse: numberStringParser('--budget-usd', { minExclusive: 0 }),
         }),
         'budget-per-sample-usd': Flags.string({
-            description: bilingual({ zh: '单 sample 预算上限 USD（必须 > 0，不传则无上限）', en: 'Per-sample budget cap USD (must be > 0; omit for no cap)' }),
+            description: bilingual({ zh: '单用例预算上限 USD（必须 > 0，不传则无上限）', en: 'Per-sample budget cap USD (must be > 0; omit for no cap)' }),
             parse: numberStringParser('--budget-per-sample-usd', { minExclusive: 0 }),
         }),
         'budget-per-sample-ms': Flags.string({
-            description: bilingual({ zh: '单 sample 时长上限 ms（必须 > 0，不传则无上限）', en: 'Per-sample time cap ms (must be > 0; omit for no cap)' }),
+            description: bilingual({ zh: '单用例时长上限 ms（必须 > 0，不传则无上限）', en: 'Per-sample time cap ms (must be > 0; omit for no cap)' }),
             parse: integerStringParser('--budget-per-sample-ms', { min: 1 }),
         }),
         threshold: Flags.string({
             description: bilingual({
-                zh: `verdict 阈值，默认 ${DEFAULT_GATE_THRESHOLD}`,
+                zh: `判定阈值，默认 ${DEFAULT_GATE_THRESHOLD}`,
                 en: `Verdict threshold, default ${DEFAULT_GATE_THRESHOLD}`,
             }),
             parse: numberStringParser('--threshold'),
@@ -385,12 +385,12 @@ export default class Eval extends BaseCommand {
         }),
         'report-only': Flags.boolean({
             description: bilingual({
-                zh: '生成报告并打印 verdict，但始终 exit 0(不参与 CI gate）。',
+                zh: '生成报告并打印判定，但始终 exit 0(不参与 CI gate）。',
                 en: 'Produce the report and print verdict, but always exit 0 (no CI gate).',
             }),
         }),
         'no-gate': Flags.boolean({
-            description: bilingual({ zh: '关 verdict gate', en: 'Disable verdict gate' }),
+            description: bilingual({ zh: '关闭判定门禁', en: 'Disable verdict gate' }),
         }),
         'no-evidence': Flags.boolean({
             description: bilingual({

package/dist/eval-core/contracts/comparability.d.ts

@@ -7,7 +7,7 @@ import { type Sha256Digest } from './json.js';
 import { type SealedRunPlan } from '../internal/sealed-run-plan.js';
 export type ComparabilityRunPlan = SealedRunPlan;
 export declare const COMPARABILITY_POLICY_SCHEMA_VERSION: "omk.comparability-policy/v1";
-export declare const COMPARABILITY_ASSESSMENT_SCHEMA_VERSION: "omk.comparability-assessment/v1";
+export declare const COMPARABILITY_ASSESSMENT_SCHEMA_VERSION: "omk.comparability-assessment/v2";
 export declare const ComparisonScopeSchema: z.ZodEnum<{
     evaluation: "evaluation";
     analysis: "analysis";
@@ -123,7 +123,7 @@ export declare const ComparabilityArtifactIdentitySchema: z.ZodObject<{
     }>;
     artifactDigest: z.ZodString;
 }, z.core.$strict>;
-export declare const ComparabilityCandidateIdentitySchema: z.ZodObject<{
+export declare const ComparabilityRunIdentitySchema: z.ZodObject<{
     runContractDigest: z.ZodString;
     planDigests: z.ZodObject<{
         datasetRevisionDigest: z.ZodString;
@@ -222,7 +222,7 @@ export declare const ComparabilityCandidateIdentitySchema: z.ZodObject<{
         }>;
         verifiedByAttestationDigest: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
-    candidateDigest: z.ZodString;
+    runIdentityDigest: z.ZodString;
 }, z.core.$strict>;
 export declare const COMPARABILITY_REASON_CODES: readonly ["comparability-identity-declared-subject-change", "comparability-design-subject-mapping-invalid", "comparability-design-undeclared-subject-change", "comparability-design-evaluation-input-mismatch", "comparability-design-evaluation-instrument-mismatch", "comparability-design-sampling-mismatch", "comparability-design-randomization-mismatch", "comparability-design-analysis-mismatch", "comparability-design-comparison-mismatch", "comparability-design-decision-mismatch", "comparability-design-schema-mismatch", "comparability-design-projection-mismatch", "comparability-evidence-source-absent", "comparability-evidence-verification-indeterminate", "comparability-evidence-assurance-unverified", "comparability-evidence-source-untrusted", "comparability-evidence-runtime-identity-opaque"];
 export declare const ComparabilityReasonCodeSchema: z.ZodEnum<{
@@ -282,7 +282,7 @@ export declare const ComparabilityReasonSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ComparabilityReasonCode = z.infer<typeof ComparabilityReasonCodeSchema>;
 export declare const ComparabilityAssessmentSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<"omk.comparability-assessment/v1">;
+    schemaVersion: z.ZodLiteral<"omk.comparability-assessment/v2">;
     policyDigest: z.ZodString;
     designMode: z.ZodLiteral<"exact-measurement-design">;
     comparisonScope: z.ZodEnum<{
@@ -389,7 +389,7 @@ export declare const ComparabilityAssessmentSchema: z.ZodObject<{
             }>;
             verifiedByAttestationDigest: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
-        candidateDigest: z.ZodString;
+        runIdentityDigest: z.ZodString;
     }, z.core.$strict>;
     right: z.ZodObject<{
         runContractDigest: z.ZodString;
@@ -490,7 +490,7 @@ export declare const ComparabilityAssessmentSchema: z.ZodObject<{
             }>;
             verifiedByAttestationDigest: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
-        candidateDigest: z.ZodString;
+        runIdentityDigest: z.ZodString;
     }, z.core.$strict>;
     designStatus: z.ZodEnum<{
         incompatible: "incompatible";
@@ -550,10 +550,10 @@ export type ComparabilitySubject = z.infer<typeof ComparabilitySubjectSchema>;
 export type ComparabilityPolicy = z.infer<typeof ComparabilityPolicySchema>;
 export type ComparabilitySourceVerificationFact = z.infer<typeof ComparabilitySourceVerificationFactSchema>;
 export type RuntimeQualificationFact = z.infer<typeof RuntimeQualificationFactSchema>;
-export type ComparabilityCandidateIdentity = z.infer<typeof ComparabilityCandidateIdentitySchema>;
+export type ComparabilityRunIdentity = z.infer<typeof ComparabilityRunIdentitySchema>;
 export type ComparabilityReason = z.infer<typeof ComparabilityReasonSchema>;
 export type ComparabilityAssessment = z.infer<typeof ComparabilityAssessmentSchema>;
-export type ComparabilityValidationErrorCode = 'COMPARABILITY_POLICY_DIGEST_MISMATCH' | 'COMPARABILITY_CANDIDATE_DIGEST_MISMATCH' | 'COMPARABILITY_ASSESSMENT_DIGEST_MISMATCH' | 'COMPARABILITY_ASSESSMENT_RECOMPUTATION_MISMATCH' | 'COMPARABILITY_SOURCE_PREFIX_INVALID' | 'COMPARABILITY_DECISION_SOURCE_PLAN_MISMATCH' | 'COMPARABILITY_VERIFICATION_CONTEXT_INVALID';
+export type ComparabilityValidationErrorCode = 'COMPARABILITY_POLICY_DIGEST_MISMATCH' | 'COMPARABILITY_RUN_IDENTITY_DIGEST_MISMATCH' | 'COMPARABILITY_ASSESSMENT_DIGEST_MISMATCH' | 'COMPARABILITY_ASSESSMENT_RECOMPUTATION_MISMATCH' | 'COMPARABILITY_SOURCE_PREFIX_INVALID' | 'COMPARABILITY_DECISION_SOURCE_PLAN_MISMATCH' | 'COMPARABILITY_VERIFICATION_CONTEXT_INVALID';
 export declare class ComparabilityValidationError extends TypeError {
     readonly code: ComparabilityValidationErrorCode;
     constructor(code: ComparabilityValidationErrorCode, message: string);
@@ -583,8 +583,8 @@ export interface ComparabilityVerificationContext {
 export interface ComparabilityAssessmentPlanVerification {
     readonly assessmentComputationStatus: 'verified';
     readonly policyDigest: Sha256Digest;
-    readonly leftCandidateDigest: Sha256Digest;
-    readonly rightCandidateDigest: Sha256Digest;
+    readonly leftRunIdentityDigest: Sha256Digest;
+    readonly rightRunIdentityDigest: Sha256Digest;
 }
 export interface ComparabilityAssessmentSource {
     readonly assessment: ComparabilityAssessment;

package/dist/eval-core/contracts/comparability.js

@@ -12,7 +12,7 @@ import { canonicalizeJson, deepFreezeCanonicalJson, digestCanonicalJson, parseWi
 import { ANALYSIS_PLAN_SCHEMA_VERSION, DECISION_PLAN_SCHEMA_VERSION, EVALUATION_PLAN_SCHEMA_VERSION, EXECUTION_PLAN_SCHEMA_VERSION, PlanDigestsSchema, RUN_PLAN_SCHEMA_VERSION, } from './plans.js';
 import { assertSealedRunPlan, } from '../internal/sealed-run-plan.js';
 export const COMPARABILITY_POLICY_SCHEMA_VERSION = 'omk.comparability-policy/v1';
-export const COMPARABILITY_ASSESSMENT_SCHEMA_VERSION = 'omk.comparability-assessment/v1';
+export const COMPARABILITY_ASSESSMENT_SCHEMA_VERSION = 'omk.comparability-assessment/v2';
 export const ComparisonScopeSchema = z.enum(['evaluation', 'analysis', 'decision']);
 export const ComparabilityStageSchema = z.enum([
     'execution',
@@ -224,41 +224,41 @@ function compareRuntimeQualifications(left, right) {
 function runtimeQualificationKey(fact) {
     return `${fact.stage}\u0000${fact.runtimeKind}\u0000${fact.referenceId}`;
 }
-export const ComparabilityCandidateIdentitySchema = z.object({
+export const ComparabilityRunIdentitySchema = z.object({
     runContractDigest: Sha256DigestSchema,
     planDigests: PlanDigestsSchema,
     randomizationDesignDigest: Sha256DigestSchema,
     artifacts: z.array(ComparabilityArtifactIdentitySchema),
     sourceVerification: z.array(ComparabilitySourceVerificationFactSchema),
     runtimeQualification: z.array(RuntimeQualificationFactSchema),
-    candidateDigest: Sha256DigestSchema,
-}).strict().superRefine((candidate, context) => {
-    if (!isCanonicalArray(candidate.artifacts, compareArtifacts)
-        || new Set(candidate.artifacts.map((artifact) => artifact.stage)).size
-            !== candidate.artifacts.length) {
+    runIdentityDigest: Sha256DigestSchema,
+}).strict().superRefine((runIdentity, context) => {
+    if (!isCanonicalArray(runIdentity.artifacts, compareArtifacts)
+        || new Set(runIdentity.artifacts.map((artifact) => artifact.stage)).size
+            !== runIdentity.artifacts.length) {
         context.addIssue({ code: 'custom', path: ['artifacts'], message: 'Artifacts must be canonical.' });
     }
-    if (candidate.runContractDigest !== candidate.planDigests.runContractDigest
-        || candidate.randomizationDesignDigest
-            !== candidate.planDigests.randomizationDesignDigest) {
+    if (runIdentity.runContractDigest !== runIdentity.planDigests.runContractDigest
+        || runIdentity.randomizationDesignDigest
+            !== runIdentity.planDigests.randomizationDesignDigest) {
         context.addIssue({
             code: 'custom',
             path: ['planDigests'],
-            message: 'Candidate summary digests must equal their Plan digest entries.',
+            message: 'Run identity digests must equal their Plan digest entries.',
         });
     }
-    if (!isCanonicalArray(candidate.sourceVerification, compareSourceFacts)
-        || new Set(candidate.sourceVerification.map(sourceFactKey)).size
-            !== candidate.sourceVerification.length) {
+    if (!isCanonicalArray(runIdentity.sourceVerification, compareSourceFacts)
+        || new Set(runIdentity.sourceVerification.map(sourceFactKey)).size
+            !== runIdentity.sourceVerification.length) {
         context.addIssue({
             code: 'custom',
             path: ['sourceVerification'],
             message: 'Source verification facts must be unique and canonical.',
         });
     }
-    if (!isCanonicalArray(candidate.runtimeQualification, compareRuntimeQualifications)
-        || new Set(candidate.runtimeQualification.map(runtimeQualificationKey)).size
-            !== candidate.runtimeQualification.length) {
+    if (!isCanonicalArray(runIdentity.runtimeQualification, compareRuntimeQualifications)
+        || new Set(runIdentity.runtimeQualification.map(runtimeQualificationKey)).size
+            !== runIdentity.runtimeQualification.length) {
         context.addIssue({
             code: 'custom',
             path: ['runtimeQualification'],
@@ -318,8 +318,8 @@ export const ComparabilityAssessmentSchema = z.object({
     policyDigest: Sha256DigestSchema,
     designMode: z.literal('exact-measurement-design'),
     comparisonScope: ComparisonScopeSchema,
-    left: ComparabilityCandidateIdentitySchema,
-    right: ComparabilityCandidateIdentitySchema,
+    left: ComparabilityRunIdentitySchema,
+    right: ComparabilityRunIdentitySchema,
     designStatus: z.enum(['compatible', 'incompatible']),
     evidenceQualificationStatus: z.enum(['verified', 'conditional', 'rejected']),
     comparabilityStatus: z.enum(['compatible', 'conditional', 'incompatible']),
@@ -398,13 +398,13 @@ export function parseComparabilityPolicyDocument(value) {
     }
     return policy;
 }
-function computeCandidateDigest(candidate) {
-    return digestCanonicalJson(candidate);
+function computeRunIdentityDigest(runIdentity) {
+    return digestCanonicalJson(runIdentity);
 }
-function assertCandidateDigest(candidate) {
-    const { candidateDigest, ...payload } = candidate;
-    if (computeCandidateDigest(payload) !== candidateDigest) {
-        throw new ComparabilityValidationError('COMPARABILITY_CANDIDATE_DIGEST_MISMATCH', 'Comparability candidate digest does not match its canonical payload.');
+function assertRunIdentityDigest(runIdentity) {
+    const { runIdentityDigest, ...payload } = runIdentity;
+    if (computeRunIdentityDigest(payload) !== runIdentityDigest) {
+        throw new ComparabilityValidationError('COMPARABILITY_RUN_IDENTITY_DIGEST_MISMATCH', 'Comparability Run identity digest does not match its canonical payload.');
     }
 }
 function computeAssessmentDigest(assessment) {
@@ -412,8 +412,8 @@ function computeAssessmentDigest(assessment) {
 }
 export function parseComparabilityAssessmentDocument(value) {
     const assessment = parseWireDocument(ComparabilityAssessmentSchema, value);
-    assertCandidateDigest(assessment.left);
-    assertCandidateDigest(assessment.right);
+    assertRunIdentityDigest(assessment.left);
+    assertRunIdentityDigest(assessment.right);
     const { assessmentDigest, ...payload } = assessment;
     if (computeAssessmentDigest(payload) !== assessmentDigest) {
         throw new ComparabilityValidationError('COMPARABILITY_ASSESSMENT_DIGEST_MISMATCH', 'ComparabilityAssessment digest does not match its canonical payload.');
@@ -1081,7 +1081,7 @@ function requiredStages(scope) {
         return ['execution', 'evaluation', 'analysis'];
     return ['execution', 'evaluation', 'analysis', 'decision'];
 }
-function candidateIdentity(plan, scope, source, attestations) {
+function comparabilityRunIdentity(plan, scope, source, attestations) {
     const artifacts = requiredStages(scope)
         .filter((stage) => source[stage] !== undefined)
         .map((stage) => ({ stage, artifactDigest: sourceDigest(source, stage) }))
@@ -1096,18 +1096,18 @@ function candidateIdentity(plan, scope, source, attestations) {
     };
     return {
         ...payload,
-        candidateDigest: computeCandidateDigest(payload),
+        runIdentityDigest: computeRunIdentityDigest(payload),
     };
 }
-function evidenceReasons(scope, leftCandidate, rightCandidate, leftProjection, rightProjection) {
+function evidenceReasons(scope, leftRunIdentity, rightRunIdentity, leftProjection, rightProjection) {
     const codes = new Set();
     const required = requiredStages(scope);
-    const leftStages = new Set(leftCandidate.artifacts.map((artifact) => artifact.stage));
-    const rightStages = new Set(rightCandidate.artifacts.map((artifact) => artifact.stage));
+    const leftStages = new Set(leftRunIdentity.artifacts.map((artifact) => artifact.stage));
+    const rightStages = new Set(rightRunIdentity.artifacts.map((artifact) => artifact.stage));
     if (required.some((stage) => !leftStages.has(stage) || !rightStages.has(stage))) {
         addReason(codes, 'comparability-evidence-source-absent');
     }
-    const facts = [...leftCandidate.sourceVerification, ...rightCandidate.sourceVerification];
+    const facts = [...leftRunIdentity.sourceVerification, ...rightRunIdentity.sourceVerification];
     if (facts.some((fact) => fact.verificationFactKind === 'verification-axis'
         && fact.verificationStatus === 'indeterminate')) {
         addReason(codes, 'comparability-evidence-verification-indeterminate');
@@ -1117,17 +1117,17 @@ function evidenceReasons(scope, leftCandidate, rightCandidate, leftProjection, r
         addReason(codes, 'comparability-evidence-source-untrusted');
     }
     const runtimes = [
-        ...leftCandidate.runtimeQualification,
-        ...rightCandidate.runtimeQualification,
+        ...leftRunIdentity.runtimeQualification,
+        ...rightRunIdentity.runtimeQualification,
     ];
     if (trustFacts.some((fact) => fact.trust === 'declared' || fact.trust === 'unknown')
         || runtimes.some((runtime) => runtime.effectiveAssuranceLevel !== 'verified')) {
         addReason(codes, 'comparability-evidence-assurance-unverified');
     }
-    const opaqueInvariantRuntime = (candidate, projection) => candidate.runtimeQualification.some((runtime) => (runtime.fingerprintBasis === 'opaque'
+    const opaqueInvariantRuntime = (runIdentity, projection) => runIdentity.runtimeQualification.some((runtime) => (runtime.fingerprintBasis === 'opaque'
         && !(runtime.runtimeKind === 'executor' && projection.mappedTargetIds.has(runtime.referenceId))));
-    if (opaqueInvariantRuntime(leftCandidate, leftProjection)
-        || opaqueInvariantRuntime(rightCandidate, rightProjection)) {
+    if (opaqueInvariantRuntime(leftRunIdentity, leftProjection)
+        || opaqueInvariantRuntime(rightRunIdentity, rightProjection)) {
         addReason(codes, 'comparability-evidence-runtime-identity-opaque');
     }
     return codes;
@@ -1145,8 +1145,8 @@ function makeAssessmentSource(assessment) {
         planVerification: {
             assessmentComputationStatus: 'verified',
             policyDigest: assessment.policyDigest,
-            leftCandidateDigest: assessment.left.candidateDigest,
-            rightCandidateDigest: assessment.right.candidateDigest,
+            leftRunIdentityDigest: assessment.left.runIdentityDigest,
+            rightRunIdentityDigest: assessment.right.runIdentityDigest,
         },
     });
     comparabilityAssessmentSources.add(source);
@@ -1160,8 +1160,8 @@ export function assessComparability(policyInput, leftPlan, rightPlan, leftSource
     const normalizedLeftSource = validateSourcePrefix(leftPlan, policy.comparisonScope, leftSource);
     const normalizedRightSource = validateSourcePrefix(rightPlan, policy.comparisonScope, rightSource);
     const design = designReasons(policy, leftPlan, rightPlan);
-    const left = candidateIdentity(leftPlan, policy.comparisonScope, normalizedLeftSource, attestations);
-    const right = candidateIdentity(rightPlan, policy.comparisonScope, normalizedRightSource, attestations);
+    const left = comparabilityRunIdentity(leftPlan, policy.comparisonScope, normalizedLeftSource, attestations);
+    const right = comparabilityRunIdentity(rightPlan, policy.comparisonScope, normalizedRightSource, attestations);
     const codes = new Set(design.codes);
     for (const code of evidenceReasons(policy.comparisonScope, left, right, design.left, design.right))
         codes.add(code);