dsh-harbor-evolution 0.7.2 → 0.8.0

package/lib/dashboard.js

@@ -1,10 +1,13 @@
 import { access, constants, lstat, readdir, readFile, stat } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
 import path from 'node:path'
 
 import { resolveWithin } from './evolution.js'
 
 const SUMMARY_NAME = 'evaluation-summary.json'
-const MAX_JOBS = 50
+const HISTORICAL_COMPLETION_NAME = 'historical-evaluation-complete.json'
+const DEFAULT_JOB_PAGE_SIZE = 20
+const MAX_JOB_PAGE_SIZE = 100
 const MAX_JSON_BYTES = 2 * 1024 * 1024
 const MAX_SOURCE_BYTES = 128 * 1024
 const MAX_PREVIEW_BYTES = 512 * 1024
@@ -12,6 +15,11 @@ const MAX_TRIAL_LIMIT = 100
 const jsonCache = new Map()
 const SENSITIVE_KEY = /authorization|cookie|token|api[_-]?key|secret|password|request[_-]?headers/i
 const SENSITIVE_SOURCE_VALUE = /(authorization|cookie|token|api[_-]?key|secret|password)\s*[:=]\s*([^\s,;]+)/gi
+const WORKSPACE_SKIP_DIRECTORIES = new Set([
+  '.cache', '.git', '.harbor', '.next', '.venv', '__pycache__',
+  'build', 'candidates', 'coverage', 'datasets', 'dist', 'jobs', 'node_modules', 'public', 'vendor', 'venv',
+])
+const MAX_WORKSPACE_DEPTH = 5
 
 function safeSegment(value, label) {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(String(value ?? ''))) throw new Error(`${label} is invalid`)
@@ -100,19 +108,65 @@ function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
 
+const CANDIDATE_JOB_KIND = 'candidate-evaluation'
+const HISTORICAL_JOB_KIND = 'historical-generation-evaluation'
+
+function normalizedJobKind(summary, context) {
+  const declared = summary?.job_kind ?? context?.job_kind
+  if (typeof declared === 'string' && declared) return declared
+  if (context?.protocol === 'historical-generation-evaluation-context/v1') return HISTORICAL_JOB_KIND
+  return CANDIDATE_JOB_KIND
+}
+
+function coverageView(summary) {
+  if (isObject(summary?.coverage)) return summary.coverage
+  const total = Number(summary?.n_trials ?? 0)
+  const scored = Number(summary?.scored_trial_count ?? summary?.n_valid_scores ?? 0)
+  const unscored = Number(
+    summary?.unscored_trial_count
+    ?? summary?.status_counts?.['completed-unscored']
+    ?? 0,
+  )
+  return {
+    scored_trials: scored,
+    unscored_trials: unscored,
+    total_trials: total,
+    trial_rate: total ? scored / total : undefined,
+  }
+}
+
+function evaluatorMetaEvaluation(summary, context) {
+  return summary?.evaluator_meta_evaluation
+    ?? context?.downstream_analysis?.evaluator_meta_evaluation
+    ?? (normalizedJobKind(summary, context) === HISTORICAL_JOB_KIND
+      ? { status: 'not-run', validation_report_ref: null }
+      : undefined)
+}
+
 function capabilityMap(summary, context, lifecycle, registry, stack) {
+  const jobKind = normalizedJobKind(summary, context)
+  const historicalGeneration = jobKind === HISTORICAL_JOB_KIND
   const contextV2 = context?.schema_version === 2
+  const historicalContext = context?.schema_version === 1
+    && context?.protocol === 'historical-generation-evaluation-context/v1'
   const scoreValidity = summary?.schema_version === 3
+    || summary?.schema_version === 4
   return {
+    jobKind,
     contextV2,
+    contextSupported: contextV2 || historicalContext,
+    historicalGeneration,
+    candidateEvaluation: !historicalGeneration,
     trialLifecycle: lifecycle?.schema_version === 1,
     scoreValidity,
     evidenceProvenance: scoreValidity,
-    artifactRegistry: registry?.schema_version === 1,
-    compare: contextV2,
+    artifactRegistry: [1, 2].includes(registry?.schema_version),
+    source: historicalGeneration,
+    compare: contextV2 && !historicalGeneration,
     evaluatorGovernance: stack?.schema_version === 1,
-    gate: contextV2 && summary?.mode === 'promotion-eligible',
-    readOnlyLegacy: !contextV2,
+    evaluatorMetaEvaluation: evaluatorMetaEvaluation(summary, context),
+    gate: contextV2 && !historicalGeneration && summary?.mode === 'promotion-eligible',
+    readOnlyLegacy: !contextV2 && !historicalContext,
   }
 }
 
@@ -124,7 +178,7 @@ function primaryMetric(summary, contract) {
 }
 
 function progressView(summary, lifecycle, updatedAt) {
-  const total = Number(lifecycle?.dataset_total ?? summary?.n_trials ?? 0)
+  const total = Number(lifecycle?.dataset_total ?? summary?.n_trials ?? summary?.coverage?.total_trials ?? 0)
   const lifecycleTrials = selectedLifecycleTrials(lifecycle)
   const completed = lifecycle
     ? lifecycleTrials.filter(item => item.terminal).length
@@ -144,19 +198,53 @@ function progressView(summary, lifecycle, updatedAt) {
   }
 }
 
-function jobStatus(summary, lifecycle, progress) {
+const HISTORICAL_COVERAGE_KEYS = [
+  'scored_trials', 'unscored_trials', 'total_trials', 'trial_rate',
+  'criterion_scored', 'criterion_total', 'criterion_rate',
+]
+
+function historicalCompletionValid(summary, completion, jobName) {
+  return (
+    summary?.schema_version === 4
+    && summary?.job === jobName
+    && summary?.job_kind === HISTORICAL_JOB_KIND
+    && summary?.mode === 'diagnostic'
+    && summary?.execution_mode === 'observe-existing'
+    && summary?.artifact_validation?.valid === true
+    && summary?.candidate === undefined
+    && completion?.schema_version === 1
+    && completion?.job_kind === HISTORICAL_JOB_KIND
+    && completion?.status === 'completed'
+    && completion?.valid === true
+    && completion?.job === jobName
+    && completion?.summary_path === SUMMARY_NAME
+    && completion?.artifact_registry_path === 'artifact-registry.json'
+    && HISTORICAL_COVERAGE_KEYS.every(key => (
+      typeof summary?.coverage?.[key] === 'number'
+      && summary.coverage[key] === completion?.coverage?.[key]
+    ))
+  )
+}
+
+function jobStatus(summary, lifecycle, progress, jobKind, completion, jobName) {
   if (summary?.__readError) return 'failed'
   if (!summary && !lifecycle) return 'pending'
   if (progress.active) return 'running'
   if (!summary && lifecycle) return 'running'
+  if (summary?.artifact_validation?.valid === false) return 'failed'
+  if (
+    jobKind === HISTORICAL_JOB_KIND
+    && !historicalCompletionValid(summary, completion, jobName)
+  ) return 'failed'
   if (Number(summary.n_infrastructure_exceptions ?? summary.n_exceptions ?? 0) > 0 || Number(summary.n_evaluation_exceptions ?? 0) > 0) return 'partial'
-  if (Number(summary.n_invalid_scores ?? 0) > 0) return 'attention'
+  const invalidScores = Number(summary.n_invalid_scores ?? 0)
+  if (invalidScores > 0) return 'attention'
   return 'completed'
 }
 
 async function readJob(jobsDir, entry, details) {
   const directory = path.join(jobsDir, entry.name)
-  const [summary, contextFile, promotion, contract, lifecycle, registry, stack] = await Promise.all([
+  const [summary, contextFile, promotion, contract, lifecycle, registry, stack, completion] = await Promise.all([
     readJson(path.join(directory, SUMMARY_NAME)),
     readJson(path.join(directory, 'evaluation-context.json')),
     readJson(path.join(directory, 'promotion-report.json')),
@@ -164,25 +252,38 @@ async function readJob(jobsDir, entry, details) {
     readJson(path.join(directory, 'trial-lifecycle.json')),
     readJson(path.join(directory, 'artifact-registry.json')),
     readJson(path.join(directory, 'evaluation-stack-manifest.json')),
+    readJson(path.join(directory, HISTORICAL_COMPLETION_NAME)),
   ])
   const evaluationContext = summary?.evaluation_context ?? contextFile
   if (!evaluationContext && !summary && !lifecycle) return undefined
   const updatedAt = details.mtime.toISOString()
   const progress = progressView(summary, lifecycle, updatedAt)
+  const jobKind = normalizedJobKind(summary, evaluationContext)
   const capabilities = capabilityMap(summary, evaluationContext, lifecycle, registry, stack)
+  const evaluationTarget = summary?.evaluation_target ?? evaluationContext?.evaluation_target
+  const generationSource = summary?.generation_source ?? evaluationContext?.generation_source
+  const coverage = coverageView(summary)
   return {
     name: entry.name,
     updatedAt,
-    status: jobStatus(summary, lifecycle, progress),
+    status: jobStatus(summary, lifecycle, progress, jobKind, completion, entry.name),
+    jobKind,
     mode: summary?.mode ?? evaluationContext?.mode,
+    executionMode: summary?.execution_mode ?? evaluationContext?.execution_mode,
     nTrials: progress.total,
     nDiscoveredTrials: Number(summary?.n_discovered_trials ?? lifecycle?.attempt_count ?? 0),
     nValidScores: summary?.n_valid_scores,
     nInvalidScores: summary?.n_invalid_scores,
+    nUnscoredTrials: Number(coverage.unscored_trials ?? 0),
     nExceptions: Number(summary?.n_exceptions ?? 0),
     primaryMetric: primaryMetric(summary, contract),
     metrics: summary?.metrics ?? {},
     candidate: summary?.candidate ?? evaluationContext?.candidate,
+    evaluationTarget,
+    generationSource,
+    generatorPopulation: evaluationTarget?.generator_population,
+    coverage,
+    evaluatorMetaEvaluation: evaluatorMetaEvaluation(summary, evaluationContext),
     dataset: evaluationContext?.dataset,
     evaluationContext,
     progress,
@@ -193,19 +294,96 @@ async function readJob(jobsDir, entry, details) {
   }
 }
 
-async function listJobs(jobsDir) {
+async function listJobs(jobsDir, { offset = 0, limit = DEFAULT_JOB_PAGE_SIZE } = {}) {
   let entries
   try {
     entries = await readdir(jobsDir, { withFileTypes: true })
   } catch (error) {
-    if (error.code === 'ENOENT') return []
+    if (error.code === 'ENOENT') return { items: [], total: 0, offset, limit, hasMore: false }
     throw error
   }
   const directories = entries.filter(entry => entry.isDirectory() && !entry.isSymbolicLink())
   const recent = await Promise.all(directories.map(async entry => ({ entry, details: await stat(path.join(jobsDir, entry.name)) })))
   recent.sort((left, right) => right.details.mtimeMs - left.details.mtimeMs)
-  const jobs = await Promise.all(recent.map(({ entry, details }) => readJob(jobsDir, entry, details)))
-  return jobs.filter(Boolean).slice(0, MAX_JOBS)
+  const page = recent.slice(offset, offset + limit)
+  const jobs = await Promise.all(page.map(({ entry, details }) => readJob(jobsDir, entry, details)))
+  return { items: jobs.filter(Boolean), total: recent.length, offset, limit, hasMore: offset + limit < recent.length }
+}
+
+function relativePath(root, value) {
+  return path.relative(root, value).split(path.sep).join('/') || '.'
+}
+
+function workspaceIdentity(projectRoot, workspaceRoot, jobsDir, preferred) {
+  const digest = createHash('sha256').update(`${projectRoot}\0${workspaceRoot}\0${jobsDir}`).digest('hex').slice(0, 12)
+  const label = String(preferred || path.basename(workspaceRoot) || 'root').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'root'
+  return `${label}-${digest}`
+}
+
+async function regularFile(pathname) {
+  try {
+    const details = await lstat(pathname)
+    return details.isFile() && !details.isSymbolicLink()
+  } catch (error) {
+    if (error.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+/** Discover root and namespaced Harbor workspaces without interpreting YAML. */
+export async function discoverWorkspaceConfigs(config) {
+  const projectRoot = path.resolve(config.projectRoot)
+  const found = []
+  async function visit(directory, depth) {
+    const harborDirectory = path.join(directory, '.harbor')
+    const descriptorPath = path.join(harborDirectory, 'workspace.json')
+    const stackPath = path.join(harborDirectory, 'evaluation-stack.yml')
+    const descriptor = await readJson(descriptorPath)
+    if (descriptor?.schema_version === 1 && descriptor.jobs && descriptor.stack) {
+      const jobs = relativePath(projectRoot, resolveWithin(projectRoot, path.resolve(directory, descriptor.jobs), 'workspace.jobs'))
+      const stack = relativePath(projectRoot, resolveWithin(projectRoot, path.resolve(directory, descriptor.stack), 'workspace.stack'))
+      const workspaceRoot = relativePath(projectRoot, directory)
+      found.push({
+        ...config,
+        jobsDir: jobs,
+        stackPath: stack,
+        workspaceRoot,
+        workspaceLabel: descriptor.workspace_id ?? workspaceRoot,
+        workspaceId: workspaceIdentity(projectRoot, directory, jobs, descriptor.workspace_id),
+      })
+    } else if (await regularFile(stackPath)) {
+      const workspaceRoot = relativePath(projectRoot, directory)
+      const jobs = relativePath(projectRoot, path.join(directory, 'jobs'))
+      found.push({
+        ...config,
+        jobsDir: jobs,
+        stackPath: relativePath(projectRoot, stackPath),
+        workspaceRoot,
+        workspaceLabel: workspaceRoot,
+        workspaceId: workspaceIdentity(projectRoot, directory, jobs, workspaceRoot),
+      })
+    }
+    if (depth >= MAX_WORKSPACE_DEPTH) return
+    let entries
+    try { entries = await readdir(directory, { withFileTypes: true }) } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'EACCES') return
+      throw error
+    }
+    await Promise.all(entries
+      .filter(entry => entry.isDirectory() && !entry.isSymbolicLink() && !WORKSPACE_SKIP_DIRECTORIES.has(entry.name))
+      .map(entry => visit(path.join(directory, entry.name), depth + 1)))
+  }
+  await visit(projectRoot, 0)
+  if (!found.some(item => item.workspaceRoot === '.')) {
+    found.unshift({
+      ...config,
+      stackPath: '.harbor/evaluation-stack.yml',
+      workspaceRoot: '.',
+      workspaceLabel: path.basename(projectRoot) || 'root',
+      workspaceId: workspaceIdentity(projectRoot, projectRoot, config.jobsDir, path.basename(projectRoot)),
+    })
+  }
+  return found.sort((left, right) => left.workspaceRoot.localeCompare(right.workspaceRoot))
 }
 
 function jobsDirectory(config) {
@@ -216,32 +394,39 @@ function jobDirectory(config, job) {
   return path.join(jobsDirectory(config), safeSegment(job, 'job'))
 }
 
-export async function readDashboardSnapshot(config, metadata = {}) {
+export async function readDashboardSnapshot(config, metadata = {}, args = {}) {
   const projectRoot = path.resolve(config.projectRoot)
   const jobsDir = jobsDirectory(config)
-  const [jobs, projectRootCheck, jobsDirCheck, harborCheck, harborDshCheck, stackCheck] = await Promise.all([
-    listJobs(jobsDir),
+  const offset = Math.max(0, Number.parseInt(args.offset ?? 0, 10) || 0)
+  const limit = Math.min(MAX_JOB_PAGE_SIZE, Math.max(1, Number.parseInt(args.limit ?? DEFAULT_JOB_PAGE_SIZE, 10) || DEFAULT_JOB_PAGE_SIZE))
+  const [jobPage, projectRootCheck, jobsDirCheck, harborCheck, harborDshCheck, stackCheck] = await Promise.all([
+    listJobs(jobsDir, { offset, limit }),
     directoryCheck(projectRoot),
     directoryCheck(jobsDir, { optional: true }),
     executableCheck(config.harborBin),
     executableCheck(config.harborDshBin),
-    fileCheck(path.join(projectRoot, '.harbor', 'evaluation-stack.yml')),
+    fileCheck(resolveWithin(projectRoot, config.stackPath ?? '.harbor/evaluation-stack.yml', 'stackPath')),
   ])
+  const jobs = jobPage.items
   const counts = jobs.reduce((result, job) => ({ ...result, [job.status]: (result[job.status] ?? 0) + 1 }), {})
   const latestMetric = jobs.find(job => job.primaryMetric)?.primaryMetric
   return {
     schemaVersion: 3,
     generatedAt: new Date().toISOString(),
     pluginVersion: metadata.pluginVersion ?? 'development',
-    config: { jobsDir: config.jobsDir, dshVersion: config.dshVersion, agentImportPath: config.agentImportPath, pluginImportPath: config.pluginImportPath },
+    workspace: { id: config.workspaceId, label: config.workspaceLabel, root: config.workspaceRoot ?? '.', stackPath: config.stackPath },
+    workspaces: metadata.workspaces ?? [],
+    config: { projectRoot, projectRootSource: metadata.projectRootSource ?? 'configured', jobsDir: config.jobsDir, runtimePolicy: config.runtimePolicy ?? 'follow-latest', agentImportPath: config.agentImportPath, pluginImportPath: config.pluginImportPath },
     checks: { projectRoot: projectRootCheck, jobsDir: jobsDirCheck, harbor: harborCheck, harborDsh: harborDshCheck, evaluationStack: stackCheck },
     overview: {
-      totalJobs: jobs.length,
+      totalJobs: jobPage.total,
+      visibleJobs: jobs.length,
       completedJobs: (counts.completed ?? 0) + (counts.partial ?? 0) + (counts.attention ?? 0),
       activeJobs: (counts.pending ?? 0) + (counts.running ?? 0),
       failedJobs: counts.failed ?? 0,
       latestMetric,
     },
+    jobPagination: { offset: jobPage.offset, limit: jobPage.limit, total: jobPage.total, hasMore: jobPage.hasMore },
     jobs,
   }
 }
@@ -252,6 +437,7 @@ const DETAIL_ARTIFACTS = {
   dataset: 'dataset-manifest.json',
   datasetPreview: 'dataset-preview.json',
   stack: 'evaluation-stack-manifest.json',
+  stackSources: 'evaluation-stack-sources.json',
   context: 'evaluation-context.json',
   contract: 'evaluation-contract.json',
   doctor: 'architecture-doctor.json',
@@ -261,6 +447,7 @@ const DETAIL_ARTIFACTS = {
   diagnosis: 'diagnosis-report.json',
   optimization: 'optimization-report.json',
   promotion: 'promotion-report.json',
+  completion: HISTORICAL_COMPLETION_NAME,
 }
 
 function schemaIssue(key, value) {
@@ -268,17 +455,21 @@ function schemaIssue(key, value) {
   if (value?.__readError) return value.__readError
   if (!isObject(value)) return 'artifact must be an object'
   const versions = {
-    summary: [2, 3], candidate: [1], dataset: [1], datasetPreview: [1], stack: [1], context: [1, 2], contract: [1],
-    doctor: [1], population: [1, 2], lifecycle: [1], registry: [1], diagnosis: [1], optimization: [1, 2], promotion: [2],
+    summary: [2, 3, 4], candidate: [1], dataset: [1], datasetPreview: [1], stack: [1], stackSources: [1], context: [1, 2], contract: [1],
+    doctor: [1], population: [1, 2, 3], lifecycle: [1], registry: [1, 2], diagnosis: [1, 2], optimization: [1, 2, 3], promotion: [2], completion: [1],
   }[key]
   if (versions && !versions.includes(value.schema_version)) return `schema_version must be one of ${versions.join(', ')}`
   const required = {
     summary: ['job', 'metrics'], candidate: ['candidate_id', 'version', 'digest'], dataset: ['dataset_id', 'version', 'source_digest', 'tasks'], datasetPreview: ['dataset_id', 'version', 'source_digest', 'tasks'],
-    stack: ['stack_id', 'version', 'digest', 'components', 'judge'], context: ['digest'], contract: ['contract_id', 'version', 'primary_metric', 'metrics'],
+    stack: ['stack_id', 'version', 'digest', 'components', 'judge'], stackSources: ['stack_digest', 'components'], context: ['digest'], contract: ['contract_id', 'version', 'primary_metric', 'metrics'],
     doctor: ['promotion_ready', 'findings'], population: ['population_size', 'groups', 'metrics'], lifecycle: ['dataset_total', 'trials'],
     registry: ['artifacts'], diagnosis: ['diagnoses'], optimization: ['hypotheses'], promotion: ['decision', 'reasons', 'policy_digest'],
+    completion: ['job_kind', 'status', 'valid', 'job', 'summary_path', 'artifact_registry_path', 'coverage'],
   }[key] ?? []
-  const missing = required.filter(field => value[field] === undefined)
+  const requiredFields = key === 'population' && value.schema_version === 3
+    ? ['population_size', 'coverage', 'metrics']
+    : required
+  const missing = requiredFields.filter(field => value[field] === undefined)
   return missing.length ? `missing fields: ${missing.join(', ')}` : undefined
 }
 
@@ -298,10 +489,35 @@ export async function readJobDetail(config, args) {
     return [key, value === undefined ? { status: 'unavailable', reason: 'capability-not-produced' } : issue ? { status: 'invalid', error: issue } : { status: 'valid' }]
   }))
   const context = artifacts.context ?? values[Object.keys(DETAIL_ARTIFACTS).indexOf('context')]
+  const summary = values[Object.keys(DETAIL_ARTIFACTS).indexOf('summary')]
+  const jobKind = normalizedJobKind(summary, context)
+  if (
+    jobKind === HISTORICAL_JOB_KIND
+    && !historicalCompletionValid(summary, artifacts.completion, job)
+  ) {
+    validation.completion = {
+      status: 'invalid',
+      error: 'Historical completion sentinel is missing, stale, or inconsistent with the Summary',
+    }
+  }
   const capabilities = capabilityMap(
-    values[Object.keys(DETAIL_ARTIFACTS).indexOf('summary')], context, artifacts.lifecycle, artifacts.registry, artifacts.stack,
+    summary, context, artifacts.lifecycle, artifacts.registry, artifacts.stack,
   )
-  return { schemaVersion: 2, job, capabilities, artifacts, validation }
+  const evaluationTarget = summary?.evaluation_target ?? context?.evaluation_target
+  return {
+    schemaVersion: 3,
+    job,
+    jobKind,
+    evaluationTarget,
+    generationSource: summary?.generation_source ?? context?.generation_source,
+    generatorPopulation: evaluationTarget?.generator_population,
+    executionMode: summary?.execution_mode ?? context?.execution_mode,
+    coverage: coverageView(summary),
+    evaluatorMetaEvaluation: evaluatorMetaEvaluation(summary, context),
+    capabilities,
+    artifacts,
+    validation,
+  }
 }
 
 function selectedLifecycleTrials(lifecycle) {
@@ -316,13 +532,15 @@ function selectedLifecycleTrials(lifecycle) {
 function normalizeTrial(trial, order) {
   const score = trial.score ?? { value: undefined, valid: trial.exception ? false : true, invalid_reasons: trial.exception ? ['infrastructure-error'] : [] }
   const datasetOrder = Number(trial.datasetOrder ?? trial.dataset_order ?? order)
+  const status = trial.status ?? trial.phase ?? (trial.exception ? 'infrastructure-error' : 'completed')
   return {
     id: trial.id ?? trial.execution_id ?? `dataset-${datasetOrder}`,
     name: trial.name ?? trial.trial_name ?? trial.dataset_trial ?? trial.trial,
     datasetTrial: trial.datasetTrial ?? trial.dataset_trial ?? trial.trial,
     datasetOrder,
     attempt: Number(trial.attempt ?? 1),
-    status: trial.status ?? trial.phase ?? (trial.exception ? 'infrastructure-error' : 'completed'),
+    status,
+    scoringStatus: status === 'completed-unscored' ? 'unscored' : score.valid ? 'scored' : 'invalid',
     terminal: trial.terminal ?? true,
     updatedAt: trial.updatedAt ?? trial.updated_at,
     score,
@@ -574,11 +792,22 @@ export async function readJobProgress(config, args) {
 
 export async function readMetaEvaluation(config, args = {}) {
   const evaluationRoot = resolveWithin(config.projectRoot, args.evaluationRoot ?? '.', 'evaluationRoot')
-  const groundTruth = await readJson(path.join(evaluationRoot, '.harbor', 'ground-truth.json'), { maxText: 64_000 })
-  const report = await readJson(path.join(evaluationRoot, '.harbor', 'meta-evaluation-report.json'), { maxText: 64_000 })
+  const index = await readJson(path.join(evaluationRoot, '.harbor', 'meta-artifacts.json'))
+  const registered = index?.schema_version === 1 ? index.artifacts ?? {} : {}
+  const groundTruthPath = resolveWithin(evaluationRoot, registered.ground_truth ?? '.harbor/ground-truth.json', 'groundTruthPath')
+  const reportPath = resolveWithin(evaluationRoot, registered.meta_evaluation_report ?? '.harbor/meta-evaluation-report.json', 'metaEvaluationReportPath')
+  const groundTruth = await readJson(groundTruthPath, { maxText: 64_000 })
+  const report = await readJson(reportPath, { maxText: 64_000 })
   const availableGroundTruth = groundTruth && !groundTruth.__readError
   const availableReport = report && !report.__readError
   const cases = availableGroundTruth && Array.isArray(groundTruth.cases) ? groundTruth.cases : []
+  const disagreementOffset = Math.max(0, Number.parseInt(args.offset ?? 0, 10) || 0)
+  const disagreementLimit = Math.min(100, Math.max(1, Number.parseInt(args.limit ?? 20, 10) || 20))
+  const disagreements = availableReport && Array.isArray(report.disagreements) ? report.disagreements : []
+  const pagedReport = availableReport ? {
+    ...report,
+    disagreements: disagreements.slice(disagreementOffset, disagreementOffset + disagreementLimit),
+  } : undefined
   return {
     schemaVersion: 1,
     evaluationRoot: path.relative(config.projectRoot, evaluationRoot) || '.',
@@ -590,9 +819,16 @@ export async function readMetaEvaluation(config, args = {}) {
       criteria: groundTruth.criteria ?? [],
       caseCount: cases.length,
       badcaseCount: cases.filter(item => item?.badcase).length,
-      path: path.relative(config.projectRoot, path.join(evaluationRoot, '.harbor', 'ground-truth.json')),
+      path: path.relative(config.projectRoot, groundTruthPath),
     } : undefined,
-    report: availableReport ? report : undefined,
+    report: pagedReport,
+    artifactIndex: index?.schema_version === 1 ? path.relative(config.projectRoot, path.join(evaluationRoot, '.harbor', 'meta-artifacts.json')) : undefined,
+    disagreementPagination: {
+      offset: disagreementOffset,
+      limit: disagreementLimit,
+      total: disagreements.length,
+      hasMore: disagreementOffset + disagreementLimit < disagreements.length,
+    },
     workflow: {
       candidate: 'Evaluator / Rubric / Judge identity',
       dataset: 'Fixed artifacts plus independent Ground Truth',
@@ -627,6 +863,32 @@ export async function readComparison(config, args) {
   if (!baseline || baseline.__readError || !candidate || candidate.__readError) throw new Error('Both Job summaries are required')
   const baselineContext = baseline.evaluation_context ?? await readJson(path.join(jobDirectory(config, baselineJob), 'evaluation-context.json'))
   const candidateContext = candidate.evaluation_context ?? await readJson(path.join(jobDirectory(config, candidateJob), 'evaluation-context.json'))
+  const baselineKind = normalizedJobKind(baseline, baselineContext)
+  const candidateKind = normalizedJobKind(candidate, candidateContext)
+  if (baselineKind !== CANDIDATE_JOB_KIND || candidateKind !== CANDIDATE_JOB_KIND) {
+    const error = {
+      code: 'UNSUPPORTED_JOB_KIND_FOR_PROMOTION',
+      message: 'Historical Generation Evaluation Jobs are diagnostic evidence and cannot be used as a Candidate baseline, comparison, or Promotion Gate input.',
+    }
+    return {
+      schemaVersion: 1,
+      baselineJob,
+      candidateJob,
+      baselineJobKind: baselineKind,
+      candidateJobKind: candidateKind,
+      comparable: false,
+      comparabilityReasons: [error],
+      metrics: {},
+      population: {},
+      improvedTrials: [],
+      regressedTrials: [],
+      newExceptions: [],
+      artifactRegressions: [],
+      gateEligibility: 'not-applicable',
+      error,
+      note: 'Convert reviewed badcases into a fixed regression Dataset before running Candidate comparison or Gate.',
+    }
+  }
   const reasons = []
   if (baselineContext?.schema_version !== 2 || candidateContext?.schema_version !== 2) reasons.push('Context v2 is required')
   if (!baselineContext?.digest || baselineContext.digest !== candidateContext?.digest) reasons.push('Evaluation Context differs; establish a fresh baseline')
@@ -668,16 +930,27 @@ export async function readComparison(config, args) {
 export async function readEvaluatorGovernance(config, args) {
   const job = safeSegment(args.job, 'job')
   const directory = jobDirectory(config, job)
-  const [stack, contract, context] = await Promise.all([
+  const [stack, sources, contract, context] = await Promise.all([
     readJson(path.join(directory, 'evaluation-stack-manifest.json')),
+    readJson(path.join(directory, 'evaluation-stack-sources.json'), { maxText: MAX_SOURCE_BYTES }),
     readJson(path.join(directory, 'evaluation-contract.json')),
     readJson(path.join(directory, 'evaluation-context.json')),
   ])
   if (!stack || stack.__readError) throw new Error('Evaluation Stack is unavailable')
+  const historicalSources = sources?.schema_version === 1 && sources.stack_digest === stack.digest
+    ? sources
+    : undefined
   const components = {}
   for (const [role, component] of Object.entries(stack.components ?? {})) {
     const entry = component?.entry
-    const source = entry ? await readSafeText(resolveWithin(config.projectRoot, entry, `${role}.entry`), config.projectRoot) : { error: 'entry unavailable' }
+    const snapshot = historicalSources?.components?.[role]
+    const snapshotFile = snapshot?.files?.find(item => item.path === entry && item.text)
+      ?? snapshot?.files?.find(item => item.text)
+    const source = snapshotFile
+      ? { ...snapshotFile, source: 'job-snapshot', readOnly: true }
+      : entry
+        ? { ...(await readSafeText(resolveWithin(config.projectRoot, entry, `${role}.entry`), config.projectRoot)), source: 'historical-live-fallback', readOnly: true }
+        : { error: 'entry unavailable', source: 'unavailable', readOnly: true }
     components[role] = { ...component, source }
   }
   let comparison
@@ -697,7 +970,7 @@ export async function readEvaluatorGovernance(config, args) {
     }
   }
   return {
-    schemaVersion: 1, job, stackIdentity: { id: stack.stack_id, version: stack.version, digest: stack.digest },
+    schemaVersion: 1, job, stackIdentity: { id: stack.stack_id, version: stack.version, digest: stack.digest, comparisonDigest: stack.comparison_digest },
     judge: stack.judge, contract, contextDigest: context?.digest, components, comparison,
     editingPolicy: {
       browserWriteEnabled: false,