@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/migration-checklist/evaluation/runner-v2.js

@@ -0,0 +1,294 @@
+import { canonicalJson } from '../../canonical-json.js';
+import { AiRuntimeError, isAiRuntimeError } from '../../ai-runtime-error.js';
+import { compareText } from '../../portable.js';
+import {
+  generateMigrationChecklistForContext,
+  generateMigrationExtractiveChecklistForContext
+} from '../generator.js';
+import {
+  MIGRATION_EXTRACTIVE_PLANNING_TASK,
+  MIGRATION_EXTRACTIVE_PROMPT_VERSION
+} from '../extractive-prompt.js';
+import { MIGRATION_PLANNING_PROMPT_VERSION, MIGRATION_PLANNING_TASK } from '../prompt.js';
+import { compareMigrationEvaluationCaseV2 } from './comparator-v2.js';
+import { buildMigrationEvaluationContext, loadMigrationEvaluationDataset } from './dataset.js';
+import {
+  loadMigrationEvaluationDatasetV2,
+  migrationEvaluationDatasetV2Digest,
+  resolveMigrationEvaluationV2Case,
+  validateMigrationEvaluationDatasetV2
+} from './dataset-v2.js';
+import { computeMigrationEvaluationMetricsV2 } from './metrics-v2.js';
+import {
+  qualifyMigrationExtractiveRuntimeV2,
+  qualifyMigrationPlanningRuntimeV2
+} from './qualification-v2.js';
+import { buildMigrationEvaluationScorecardV2 } from './scorecard-v2.js';
+import {
+  classifyMigrationExtractiveOutput,
+  resolveMigrationExtractiveEvaluationV2Case
+} from './extractive-fixtures-v2.js';
+
+export const MIGRATION_EVALUATION_REPORT_V2_VERSION = '2.0.0';
+export const MIGRATION_EXTRACTIVE_EVALUATION_REPORT_V2_VERSION = '2.0.0-extractive';
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function isoTimestamp(value) {
+  const timestamp = value instanceof Date ? value.toISOString() : value;
+  if (typeof timestamp !== 'string' || !Number.isFinite(Date.parse(timestamp))) {
+    throw new TypeError('Migration evaluation v2 requires an injected Date or ISO timestamp.');
+  }
+  return timestamp;
+}
+
+function runtimeIdentity(mode, metadata = {}, fakeDefaults) {
+  const allowed = new Set(['provider', 'model', 'adapter']);
+  const unknown = Object.keys(metadata).filter((field) => !allowed.has(field));
+  if (unknown.length > 0) {
+    throw new TypeError(`Migration evaluation v2 runtime metadata contains unsupported field ${unknown.sort(compareText)[0]}.`);
+  }
+  const defaults = mode === 'fake' ? (fakeDefaults ?? {
+    provider: 'migration-golden-fake',
+    model: '2.0.0',
+    adapter: 'role-routed-recorded-runtime'
+  }) : {};
+  const identity = { mode, ...defaults, ...metadata };
+  for (const field of allowed) {
+    if (typeof identity[field] !== 'string' || identity[field].length === 0) {
+      throw new TypeError(`Migration evaluation v2 requires runtimeMetadata.${field}.`);
+    }
+  }
+  return identity;
+}
+
+function fixedRuntime(output, runtimeErrorCode, identity) {
+  return {
+    async generateStructured() {
+      if (runtimeErrorCode) {
+        throw new AiRuntimeError(runtimeErrorCode, 'Injected sanitized evaluation failure.', {
+          retryable: false
+        });
+      }
+      return {
+        output: structuredClone(output),
+        provider: identity.provider,
+        model: identity.model,
+        latencyMs: 0
+      };
+    }
+  };
+}
+
+async function evaluateCase({
+  dataset,
+  goldenCase,
+  activeRuntime,
+  identity,
+  promptVersion,
+  retainFailureDetails,
+  strategy
+}) {
+  const resolved = strategy.resolveCase(dataset, goldenCase);
+  const context = buildMigrationEvaluationContext(resolved.baseCase);
+  const localRuntime = goldenCase.role === 'LIVE_QUALITY'
+    ? activeRuntime
+    : fixedRuntime(resolved.fixedOutput, resolved.runtimeErrorCode, identity);
+  let rawOutput;
+  let runtimeErrorCode = null;
+  const observedIdentity = {};
+  const capturingRuntime = {
+    async generateStructured(request) {
+      try {
+        const response = await localRuntime.generateStructured(request);
+        rawOutput = structuredClone(response?.output);
+        if (goldenCase.role === 'LIVE_QUALITY') {
+          if (typeof response?.provider === 'string') observedIdentity.provider = response.provider;
+          if (typeof response?.model === 'string') observedIdentity.model = response.model;
+        }
+        return response;
+      } catch (error) {
+        runtimeErrorCode = isAiRuntimeError(error) ? error.code : 'UNKNOWN';
+        throw error;
+      }
+    }
+  };
+  const generation = await strategy.generateContext(context, {
+    aiRuntime: capturingRuntime,
+    runId: `migration-evaluation-v2:${goldenCase.id}`,
+    promptVersion
+  });
+  const replay = await strategy.generateContext(context, {
+    aiRuntime: fixedRuntime(rawOutput, runtimeErrorCode, identity),
+    runId: `migration-evaluation-v2:${goldenCase.id}`,
+    promptVersion
+  });
+  const rawClassification = strategy.classifyRawOutput
+    ? strategy.classifyRawOutput(rawOutput, context, runtimeErrorCode)
+    : null;
+  return {
+    result: compareMigrationEvaluationCaseV2(goldenCase, {
+      baseCase: resolved.baseCase,
+      context,
+      generation,
+      rawOutput,
+      runtimeErrorCode,
+      rawClassification,
+      publishedEvaluationInstructions:
+        strategy.evaluatePublishedSupportFromSelectedSpans
+        && rawClassification?.outcome === 'ACTIONABLE'
+          ? rawClassification.candidate.items.map((item) => item.instruction)
+          : null,
+      deterministicReplayPassed: canonicalJson(generation) === canonicalJson(replay),
+      retainFailureDetails
+    }),
+    observedIdentity
+  };
+}
+
+const FREE_FORM_STRATEGY = Object.freeze({
+  task: MIGRATION_PLANNING_TASK,
+  reportVersion: MIGRATION_EVALUATION_REPORT_V2_VERSION,
+  defaultPromptVersion: MIGRATION_PLANNING_PROMPT_VERSION,
+  fakeRuntime: {
+    provider: 'migration-golden-fake',
+    model: '2.0.0',
+    adapter: 'role-routed-recorded-runtime'
+  },
+  resolveCase: resolveMigrationEvaluationV2Case,
+  generateContext: generateMigrationChecklistForContext,
+  classifyRawOutput: null,
+  qualify: qualifyMigrationPlanningRuntimeV2
+});
+
+const EXTRACTIVE_STRATEGY = Object.freeze({
+  task: MIGRATION_EXTRACTIVE_PLANNING_TASK,
+  reportVersion: MIGRATION_EXTRACTIVE_EVALUATION_REPORT_V2_VERSION,
+  defaultPromptVersion: MIGRATION_EXTRACTIVE_PROMPT_VERSION,
+  fakeRuntime: {
+    provider: 'migration-extractive-golden-fake',
+    model: '2.0.0',
+    adapter: 'extractive-role-routed-recorded-runtime'
+  },
+  resolveCase: resolveMigrationExtractiveEvaluationV2Case,
+  generateContext: generateMigrationExtractiveChecklistForContext,
+  classifyRawOutput: classifyMigrationExtractiveOutput,
+  evaluatePublishedSupportFromSelectedSpans: true,
+  qualify: qualifyMigrationExtractiveRuntimeV2
+});
+
+async function runMigrationEvaluationV2WithStrategy({
+  dataset,
+  datasetPath,
+  mode = 'fake',
+  runtime,
+  runtimeMetadata,
+  generatedAt,
+  promptVersion,
+  retainFailureDetails = true
+}, strategy) {
+  if (!['fake', 'real'].includes(mode)) {
+    throw new TypeError('Migration evaluation v2 mode must be fake or real.');
+  }
+  if (generatedAt === undefined) {
+    throw new TypeError('Migration evaluation v2 requires an injected generatedAt timestamp.');
+  }
+  if (mode === 'real' && !runtime) {
+    throw new TypeError('Real migration evaluation v2 requires an explicitly injected AiRuntime.');
+  }
+  if (typeof retainFailureDetails !== 'boolean') {
+    throw new TypeError('retainFailureDetails must be boolean.');
+  }
+  const loaded = dataset ? {
+    ...structuredClone(dataset),
+    legacyDataset: dataset.legacyDataset ?? await loadMigrationEvaluationDataset()
+  } : await loadMigrationEvaluationDatasetV2(datasetPath);
+  const core = {
+    schemaVersion: loaded.schemaVersion,
+    datasetId: loaded.datasetId,
+    task: loaded.task,
+    baseDataset: structuredClone(loaded.baseDataset),
+    cases: structuredClone(loaded.cases)
+  };
+  validateMigrationEvaluationDatasetV2(core, loaded.legacyDataset);
+  const timestamp = isoTimestamp(generatedAt);
+  const activePromptVersion = promptVersion ?? strategy.defaultPromptVersion;
+  const identity = runtimeIdentity(mode, runtimeMetadata, strategy.fakeRuntime);
+  let providerRequestCount = 0;
+  const liveRuntime = mode === 'real' ? {
+    async generateStructured(request) {
+      providerRequestCount += 1;
+      return runtime.generateStructured(request);
+    }
+  } : null;
+  const cases = [];
+  const observedProviders = new Set();
+  const observedModels = new Set();
+  for (const goldenCase of [...loaded.cases].sort((left, right) => compareText(left.id, right.id))) {
+    const resolved = strategy.resolveCase(loaded, goldenCase);
+    const activeRuntime = goldenCase.role === 'LIVE_QUALITY'
+      ? (liveRuntime ?? fixedRuntime(resolved.fixedOutput, null, identity))
+      : null;
+    const evaluated = await evaluateCase({
+      dataset: loaded,
+      goldenCase,
+      activeRuntime,
+      identity,
+      promptVersion: activePromptVersion,
+      retainFailureDetails,
+      strategy
+    });
+    cases.push(evaluated.result);
+    if (evaluated.observedIdentity.provider) observedProviders.add(evaluated.observedIdentity.provider);
+    if (evaluated.observedIdentity.model) observedModels.add(evaluated.observedIdentity.model);
+  }
+  const observedRuntime = {
+    ...identity,
+    observedProviders: [...observedProviders].sort(compareText),
+    observedModels: [...observedModels].sort(compareText)
+  };
+  const metrics = computeMigrationEvaluationMetricsV2(cases, { providerRequestCount });
+  const datasetIdentity = {
+    datasetId: core.datasetId,
+    schemaVersion: core.schemaVersion,
+    datasetDigest: migrationEvaluationDatasetV2Digest(core, loaded.legacyDataset)
+  };
+  const qualification = strategy.qualify({
+    dataset: datasetIdentity,
+    metrics,
+    runtime: observedRuntime,
+    generatedAt: timestamp,
+    promptVersion: activePromptVersion
+  });
+  const base = {
+    schemaVersion: strategy.reportVersion,
+    generatedAt: timestamp,
+    task: strategy.task,
+    dataset: datasetIdentity,
+    promptVersion: activePromptVersion,
+    runtime: observedRuntime,
+    cases,
+    metrics,
+    qualification
+  };
+  return deepFreeze({ ...base, scorecard: buildMigrationEvaluationScorecardV2(base) });
+}
+
+/**
+ * Historical free-form v2 evaluation. Retained byte-for-byte in identity and behavior.
+ */
+export async function runMigrationEvaluationV2(options = {}) {
+  return runMigrationEvaluationV2WithStrategy(options, FREE_FORM_STRATEGY);
+}
+
+/**
+ * Offline-first production extractive evaluation. Recorded containment and injected
+ * failures always remain local; only LIVE_QUALITY may reach an explicitly injected runtime.
+ */
+export async function runMigrationExtractiveEvaluationV2(options = {}) {
+  return runMigrationEvaluationV2WithStrategy(options, EXTRACTIVE_STRATEGY);
+}

package/src/migration-checklist/evaluation/runner.js

@@ -0,0 +1,194 @@
+import { canonicalJson } from '../../canonical-json.js';
+import { isAiRuntimeError, AiRuntimeError } from '../../ai-runtime-error.js';
+import { compareText } from '../../portable.js';
+import { generateMigrationChecklistForContext } from '../generator.js';
+import { MIGRATION_PLANNING_PROMPT_VERSION, MIGRATION_PLANNING_TASK } from '../prompt.js';
+import { compareMigrationEvaluationCase } from './comparator.js';
+import {
+  buildMigrationEvaluationContext,
+  createMigrationGoldenFakeRuntime,
+  loadMigrationEvaluationDataset,
+  migrationEvaluationDatasetDigest,
+  validateMigrationEvaluationDataset
+} from './dataset.js';
+import { computeMigrationEvaluationMetrics } from './metrics.js';
+import { qualifyMigrationPlanningRuntime } from './qualification.js';
+import { buildMigrationEvaluationScorecard } from './scorecard.js';
+
+export const MIGRATION_EVALUATION_REPORT_VERSION = '1.0.0';
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function coreDataset(dataset) {
+  return {
+    schemaVersion: dataset.schemaVersion,
+    datasetId: dataset.datasetId,
+    task: dataset.task,
+    cases: structuredClone(dataset.cases)
+  };
+}
+
+function isoTimestamp(value) {
+  const timestamp = value instanceof Date ? value.toISOString() : value;
+  if (typeof timestamp !== 'string' || !Number.isFinite(Date.parse(timestamp))) {
+    throw new TypeError('Migration evaluation generatedAt must be an injected Date or ISO timestamp.');
+  }
+  return timestamp;
+}
+
+function runtimeIdentity(mode, metadata = {}) {
+  const unknownFields = Object.keys(metadata).filter((field) => (
+    !['provider', 'model', 'adapter'].includes(field)
+  ));
+  if (unknownFields.length > 0) {
+    throw new TypeError(`Migration evaluation runtimeMetadata contains unsupported field ${unknownFields.sort(compareText)[0]}.`);
+  }
+  const defaults = mode === 'fake' ? {
+    provider: 'migration-golden-fake',
+    model: '1.0.0',
+    adapter: 'recorded-candidate-runtime'
+  } : {};
+  const identity = { mode, ...defaults, ...metadata };
+  for (const field of ['provider', 'model', 'adapter']) {
+    if (typeof identity[field] !== 'string' || identity[field].length === 0) {
+      throw new TypeError(`Real migration evaluation requires runtimeMetadata.${field}.`);
+    }
+  }
+  return identity;
+}
+
+function replayRuntime(rawOutput, runtimeErrorCode, identity) {
+  return {
+    async generateStructured() {
+      if (runtimeErrorCode) {
+        throw new AiRuntimeError(runtimeErrorCode, 'Recorded sanitized runtime failure.', {
+          retryable: false
+        });
+      }
+      return {
+        output: structuredClone(rawOutput),
+        provider: identity.provider,
+        model: identity.model,
+        latencyMs: 0
+      };
+    }
+  };
+}
+
+async function evaluateCase(goldenCase, activeRuntime, identity, promptVersion) {
+  const context = buildMigrationEvaluationContext(goldenCase);
+  let rawOutput;
+  let runtimeErrorCode = null;
+  const observedIdentity = {};
+  const capturingRuntime = {
+    async generateStructured(request) {
+      try {
+        const result = await activeRuntime.generateStructured(request);
+        rawOutput = structuredClone(result?.output);
+        if (typeof result?.provider === 'string') observedIdentity.provider = result.provider;
+        if (typeof result?.model === 'string') observedIdentity.model = result.model;
+        return result;
+      } catch (error) {
+        runtimeErrorCode = isAiRuntimeError(error) ? error.code : 'UNKNOWN';
+        throw error;
+      }
+    }
+  };
+  const generation = await generateMigrationChecklistForContext(context, {
+    aiRuntime: capturingRuntime,
+    runId: `migration-evaluation:${goldenCase.id}`,
+    promptVersion
+  });
+  const replay = await generateMigrationChecklistForContext(context, {
+    aiRuntime: replayRuntime(rawOutput, runtimeErrorCode, identity),
+    runId: `migration-evaluation:${goldenCase.id}`,
+    promptVersion
+  });
+  const result = compareMigrationEvaluationCase(goldenCase, {
+    context,
+    generation,
+    rawOutput,
+    runtimeErrorCode,
+    deterministicReplayPassed: canonicalJson(generation) === canonicalJson(replay)
+  });
+  return { result, observedIdentity };
+}
+
+/**
+ * Run the migration-specific dataset. Real providers are called only when mode is explicitly `real`.
+ * Raw provider payloads and raw error messages are never included in the returned report.
+ */
+export async function runMigrationEvaluation({
+  dataset,
+  datasetPath,
+  mode = 'fake',
+  runtime,
+  runtimeMetadata,
+  generatedAt,
+  promptVersion = MIGRATION_PLANNING_PROMPT_VERSION
+} = {}) {
+  if (!['fake', 'real'].includes(mode)) {
+    throw new TypeError('Migration evaluation mode must be fake or real.');
+  }
+  if (generatedAt === undefined) {
+    throw new TypeError('Migration evaluation requires an injected generatedAt timestamp.');
+  }
+  if (mode === 'real' && !runtime) {
+    throw new TypeError('Real migration evaluation requires an explicitly injected AiRuntime.');
+  }
+  const loaded = dataset ?? await loadMigrationEvaluationDataset(datasetPath);
+  const value = coreDataset(loaded);
+  validateMigrationEvaluationDataset(value);
+  if (value.task !== MIGRATION_PLANNING_TASK) {
+    throw new TypeError(`Migration evaluation dataset task must be ${MIGRATION_PLANNING_TASK}.`);
+  }
+  const timestamp = isoTimestamp(generatedAt);
+  const identity = runtimeIdentity(mode, runtimeMetadata);
+  const activeRuntime = runtime ?? createMigrationGoldenFakeRuntime(value);
+  const cases = [];
+  const observedProviders = new Set();
+  const observedModels = new Set();
+  for (const goldenCase of [...value.cases].sort((left, right) => compareText(left.id, right.id))) {
+    const evaluated = await evaluateCase(goldenCase, activeRuntime, identity, promptVersion);
+    cases.push(evaluated.result);
+    if (evaluated.observedIdentity.provider) observedProviders.add(evaluated.observedIdentity.provider);
+    if (evaluated.observedIdentity.model) observedModels.add(evaluated.observedIdentity.model);
+  }
+  const observedRuntime = {
+    ...identity,
+    observedProviders: [...observedProviders].sort(compareText),
+    observedModels: [...observedModels].sort(compareText)
+  };
+  const metrics = computeMigrationEvaluationMetrics(cases);
+  const datasetIdentity = {
+    datasetId: value.datasetId,
+    schemaVersion: value.schemaVersion,
+    datasetDigest: migrationEvaluationDatasetDigest(value)
+  };
+  const qualification = qualifyMigrationPlanningRuntime({
+    dataset: datasetIdentity,
+    metrics,
+    runtime: observedRuntime,
+    generatedAt: timestamp,
+    promptVersion
+  });
+  const base = {
+    schemaVersion: MIGRATION_EVALUATION_REPORT_VERSION,
+    generatedAt: timestamp,
+    task: MIGRATION_PLANNING_TASK,
+    dataset: datasetIdentity,
+    promptVersion,
+    runtime: observedRuntime,
+    cases,
+    metrics,
+    qualification
+  };
+  return deepFreeze({
+    ...base,
+    scorecard: buildMigrationEvaluationScorecard(base)
+  });
+}

package/src/migration-checklist/evaluation/scorecard-v2.js

@@ -0,0 +1,106 @@
+import { compareText } from '../../portable.js';
+
+const METRIC_SECTIONS = Object.freeze({
+  liveProviderQuality: [
+    'actionSupportPrecision', 'publishedUnsupportedActionRate', 'ambiguousPublishedActionRate',
+    'actionSpecificityRate', 'identifierSpecificityRate', 'versionScopePreservationRate',
+    'abstentionPrecision', 'abstentionRecall', 'falseAbstentionRate',
+    'safeCandidateAcceptanceRate', 'liveProviderCompletionRate'
+  ],
+  trustContainment: [
+    'unsafeCandidateContainmentRate', 'inventedIdentifierContainmentRate',
+    'prohibitedCapabilityContainmentRate', 'invalidEvidenceContainmentRate',
+    'wholeCandidateContainmentRate', 'recordedSafeCandidateAcceptanceRate'
+  ],
+  runtimeFailureHandling: [
+    'injectedFailureFallbackRate', 'providerFailureIsolationRate',
+    'schemaFailureContainmentRate', 'sanitizedFailureRate'
+  ],
+  sharedInvariants: [
+    'stepEvidenceReferencePrecision', 'exactExcerptPassRate', 'locationPreservationRate',
+    'identityPreservationRate', 'humanReviewCorrectnessRate',
+    'versionUncertaintyPreservationRate', 'deterministicPostProcessingPassRate'
+  ]
+});
+
+function formatRate(metric) {
+  return metric.value === null
+    ? `n/a (${metric.numerator}/${metric.denominator})`
+    : `${(metric.value * 100).toFixed(2)}% (${metric.numerator}/${metric.denominator})`;
+}
+
+export function buildMigrationEvaluationScorecardV2(evaluation) {
+  const section = (name) => Object.fromEntries(METRIC_SECTIONS[name]
+    .filter((key) => evaluation.metrics.metrics[key])
+    .map((key) => [key, structuredClone(evaluation.metrics.metrics[key])]));
+  return Object.freeze({
+    schemaVersion: '2.0.0',
+    identity: structuredClone(evaluation.qualification.identity),
+    coverage: structuredClone(evaluation.metrics.coverage),
+    providerRequestCount: evaluation.metrics.runtime.providerRequestCount,
+    sections: {
+      liveProviderQuality: section('liveProviderQuality'),
+      trustContainment: section('trustContainment'),
+      runtimeFailureHandling: section('runtimeFailureHandling'),
+      sharedInvariants: section('sharedInvariants')
+    },
+    criticalGates: structuredClone(evaluation.metrics.criticalGates),
+    thresholdResults: structuredClone(evaluation.qualification.thresholdResults),
+    limitations: structuredClone(evaluation.qualification.limitations),
+    retainedFailureDetails: evaluation.cases.flatMap((item) => (
+      structuredClone(item.retainedFailureDetails)
+    )),
+    verdict: evaluation.qualification.verdict
+  });
+}
+
+export function renderMigrationEvaluationScorecardV2(scorecard) {
+  const lines = [
+    '# Migration Planning Evaluation Scorecard v2',
+    '',
+    `- Task: ${scorecard.identity.task}`,
+    `- Dataset: ${scorecard.identity.datasetId}@${scorecard.identity.datasetVersion}`,
+    `- Evaluation criteria: ${scorecard.identity.evaluationCriteriaId}@${scorecard.identity.evaluationCriteriaVersion}`,
+    `- Comparator/normalization: ${scorecard.identity.comparatorVersion}/${scorecard.identity.normalizationVersion}`,
+    `- Provider/model: ${scorecard.identity.runtime.provider}/${scorecard.identity.runtime.model}`,
+    `- Runtime mode/adapter: ${scorecard.identity.runtime.mode}/${scorecard.identity.runtime.adapter}`,
+    `- Real provider calls: ${scorecard.providerRequestCount}`,
+    `- Verdict: ${scorecard.verdict}`,
+    '',
+    '## Fixture Coverage',
+    '',
+    `- Roles: ${JSON.stringify(scorecard.coverage.roles)}`,
+    `- Live ecosystems: ${scorecard.coverage.ecosystems.join(', ')}`,
+    `- Live actionable/abstention: ${scorecard.coverage.liveActionableCases}/${scorecard.coverage.liveAbstentionCases}`,
+    `- Recorded unsafe/safe: ${scorecard.coverage.recordedUnsafeCases}/${scorecard.coverage.recordedSafeCases}`,
+    `- Injected failures: ${scorecard.coverage.injectedFailureCases}`
+  ];
+  const headings = {
+    liveProviderQuality: 'Live Provider Quality',
+    trustContainment: 'Trust Containment',
+    runtimeFailureHandling: 'Runtime Failure Handling',
+    sharedInvariants: 'Shared Invariants'
+  };
+  for (const sectionName of Object.keys(headings)) {
+    lines.push('', `## ${headings[sectionName]}`, '');
+    for (const name of Object.keys(scorecard.sections[sectionName]).sort(compareText)) {
+      const metric = scorecard.sections[sectionName][name];
+      lines.push(`- ${name}: ${formatRate(metric)}; role=${metric.caseRole}; cases=${metric.applicableCaseCount}`);
+    }
+  }
+  lines.push('', '## Critical Gates', '');
+  for (const gate of scorecard.criticalGates) {
+    lines.push(`- ${gate.id}: ${gate.passed ? 'PASS' : `FAIL (${gate.violations.join(', ')})`}`);
+  }
+  lines.push('', '## Thresholds', '');
+  for (const item of scorecard.thresholdResults) {
+    lines.push(`- ${item.metric}: ${item.passed ? 'PASS' : 'FAIL'}; actual=${item.actual ?? 'n/a'}; ${item.operator}=${item.threshold}`);
+  }
+  lines.push('', '## Limitations', '');
+  if (scorecard.limitations.length === 0) lines.push('- None.');
+  else for (const item of scorecard.limitations) lines.push(`- ${item.code}: ${item.message}`);
+  lines.push('', '## Retained Sanitized Failure Details', '');
+  lines.push(scorecard.retainedFailureDetails.length === 0
+    ? '- None.' : `- ${scorecard.retainedFailureDetails.length} bounded record(s).`);
+  return `${lines.join('\n')}\n`;
+}

package/src/migration-checklist/evaluation/scorecard.js

@@ -0,0 +1,86 @@
+import { compareText } from '../../portable.js';
+
+function formatRate(metric) {
+  return metric.value === null
+    ? `n/a (${metric.numerator}/${metric.denominator})`
+    : `${(metric.value * 100).toFixed(2)}% (${metric.numerator}/${metric.denominator})`;
+}
+
+/** Build a presentation-only scorecard from already computed results. */
+export function buildMigrationEvaluationScorecard(evaluation) {
+  const metrics = evaluation.metrics;
+  return Object.freeze({
+    schemaVersion: '1.0.0',
+    identity: structuredClone(evaluation.qualification.identity),
+    coverage: structuredClone(metrics.coverage),
+    rawOutcomes: Object.fromEntries(
+      ['ACTIONABLE', 'ABSTAIN', 'INVALID', 'RUNTIME_FAILURE'].map((outcome) => [
+        outcome,
+        evaluation.cases.filter((item) => item.raw.outcome === outcome).length
+      ])
+    ),
+    trustOutcomes: Object.fromEntries(
+      ['ACCEPTED', 'REJECTED', 'NOT_EVALUATED'].map((outcome) => [
+        outcome,
+        evaluation.cases.filter((item) => item.raw.trustDecision === outcome).length
+      ])
+    ),
+    publishedOutcomes: {
+      generated: metrics.runtime.generated,
+      abstained: metrics.runtime.abstained,
+      rejected: metrics.runtime.rejected,
+      failed: metrics.runtime.failed
+    },
+    metrics: structuredClone(metrics.metrics),
+    criticalGates: structuredClone(metrics.criticalGates),
+    thresholdResults: structuredClone(evaluation.qualification.thresholdResults),
+    limitations: structuredClone(evaluation.qualification.limitations),
+    verdict: evaluation.qualification.verdict
+  });
+}
+
+/** Render only precomputed scorecard data; this function never derives a verdict. */
+export function renderMigrationEvaluationScorecard(scorecard) {
+  const lines = [
+    '# Migration Planning Evaluation Scorecard',
+    '',
+    `- Task: ${scorecard.identity.task}`,
+    `- Dataset: ${scorecard.identity.datasetId}@${scorecard.identity.datasetVersion}`,
+    `- Provider/model: ${scorecard.identity.runtime.provider}/${scorecard.identity.runtime.model}`,
+    `- Runtime mode/adapter: ${scorecard.identity.runtime.mode}/${scorecard.identity.runtime.adapter}`,
+    `- Verdict: ${scorecard.verdict}`,
+    '',
+    '## Coverage',
+    '',
+    `- Ecosystems: ${scorecard.coverage.ecosystems.join(', ')}`,
+    `- Cases by ecosystem: ${JSON.stringify(scorecard.coverage.casesByEcosystem)}`,
+    `- Cases by scenario group: ${JSON.stringify(scorecard.coverage.scenarioGroups)}`,
+    `- Actionable quality cases: ${scorecard.coverage.actionableQualityCases}`,
+    `- Abstention quality cases: ${scorecard.coverage.abstentionQualityCases}`,
+    `- Adversarial policy probes: ${scorecard.coverage.adversarialPolicyProbes}`,
+    '',
+    '## Raw / Trust / Published',
+    '',
+    `- Raw: ${JSON.stringify(scorecard.rawOutcomes)}`,
+    `- Trust: ${JSON.stringify(scorecard.trustOutcomes)}`,
+    `- Published: ${JSON.stringify(scorecard.publishedOutcomes)}`,
+    '',
+    '## Metrics',
+    ''
+  ];
+  for (const name of Object.keys(scorecard.metrics).sort(compareText)) {
+    lines.push(`- ${name}: ${formatRate(scorecard.metrics[name])}`);
+  }
+  lines.push('', '## Critical Gates', '');
+  for (const gate of scorecard.criticalGates) {
+    lines.push(`- ${gate.id}: ${gate.passed ? 'PASS' : `FAIL (${gate.violations.join(', ')})`}`);
+  }
+  lines.push('', '## Thresholds', '');
+  for (const item of scorecard.thresholdResults) {
+    lines.push(`- ${item.metric}: ${item.passed ? 'PASS' : 'FAIL'}; actual=${item.actual ?? 'n/a'}; ${item.operator}=${item.threshold}`);
+  }
+  lines.push('', '## Limitations', '');
+  if (scorecard.limitations.length === 0) lines.push('- None.');
+  else for (const item of scorecard.limitations) lines.push(`- ${item.code}: ${item.message}`);
+  return `${lines.join('\n')}\n`;
+}