@surlymochan/evalid 0.0.0-stage → 0.3.1

package/src/core/atoms/event/ingest.js

@@ -0,0 +1,30 @@
+import { ingestEvent } from '../../mission-state.js';
+import { mutateStore, resolveDataFile } from '../../state-store.js';
+import { resolveBoundMissionId } from '../../bindings.js';
+
+export async function eventIngest(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const dataFile = resolveDataFile({ projectRoot, explicitPath: input.data_file || null });
+  const missionId = resolveBoundMissionId({
+    projectRoot,
+    changeId: context.changeId || null,
+    missionId: input.mission_id || null,
+    runtimeMissionId: context.runtime?.missionId || null,
+  });
+
+  if (!missionId) {
+    throw new Error('mission_id is required for D4.event.ingest');
+  }
+
+  const result = await mutateStore(
+    (state) => ingestEvent(state, { ...input, mission_id: missionId }),
+    dataFile,
+  );
+
+  return {
+    ok: true,
+    data_file: dataFile,
+    mission_id: missionId,
+    ...result,
+  };
+}

package/src/core/atoms/experience/digest.js

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { readJsonFile, resolveChangePath, writeJsonFile } from '../../change-artifacts.js';
+
+export async function experienceDigest(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id;
+  if (!changeId) throw new Error('change_id is required for experience.digest');
+
+  const entries = collectExperienceEntries(projectRoot);
+  const digest = {
+    version: 1,
+    change_id: changeId,
+    generated_at: new Date().toISOString(),
+    advisory_only: true,
+    entry_count: entries.length,
+    entries: entries.map((entry) => ({
+      title: entry.title || entry.summary || 'Untitled experience',
+      category: entry.category || 'workflow',
+      content: entry.content || entry.summary || '',
+      confidence: entry.confidence ?? null,
+      source: entry.source || null,
+    })),
+  };
+  const outputPath = resolveChangePath(projectRoot, changeId, 'experience_digest.json');
+  writeJsonFile(outputPath, digest);
+  return {
+    ok: true,
+    experience_digest_file: outputPath,
+    digest,
+  };
+}
+
+function collectExperienceEntries(projectRoot) {
+  const sources = [];
+  const localDir = resolve(projectRoot, '.xflow', 'experience');
+  if (existsSync(localDir)) {
+    for (const file of readdirSync(localDir)) {
+      if (file.endsWith('.json')) sources.push(resolve(localDir, file));
+    }
+  }
+  const teamExperience = resolve(projectRoot, '.xflow', 'storage', 'team', 'experience.json');
+  if (existsSync(teamExperience)) sources.push(teamExperience);
+
+  const entries = [];
+  for (const source of sources) {
+    const payload = readJsonFile(source, {});
+    const sourceEntries = Array.isArray(payload.entries) ? payload.entries : Array.isArray(payload) ? payload : [];
+    for (const entry of sourceEntries) {
+      entries.push({ ...entry, source });
+    }
+  }
+  return entries;
+}

package/src/core/atoms/gate/artifact-verify.js

@@ -0,0 +1,83 @@
+import { existsSync } from 'node:fs';
+
+import { makeArtifactEnvelope, readJsonFile, resolveChangePath, writeJsonFile } from '../../change-artifacts.js';
+import { resolveBoundMissionId } from '../../bindings.js';
+import { getLatestPhaseEntry, getLatestPhaseRun } from '../../phase-run-read.js';
+import { readStore, resolveDataFile } from '../../state-store.js';
+
+function deriveQaStatus({ verifyProof, qaPacket, phaseEntry }) {
+  const testsPassed = verifyProof?.all_passed === true;
+  const packetStatus = qaPacket?.status || null;
+  const phaseStatus = phaseEntry?.effective_status || phaseEntry?.status || null;
+  const failedChecks = Array.isArray(qaPacket?.failed_checks) ? qaPacket.failed_checks : [];
+  const journeyCovered = qaPacket?.primary_journey_covered === true;
+  const moduleCoverage = qaPacket?.module_coverage || null;
+  const modulesCovered = Number(moduleCoverage?.covered_module_count || 0);
+  const modulesExpected = Number(moduleCoverage?.expected_module_count || 0);
+  const modulesSatisfied = modulesExpected > 0 && modulesCovered >= modulesExpected;
+
+  if (packetStatus === 'accepted' && testsPassed && journeyCovered && modulesSatisfied && failedChecks.length === 0) return 'accepted';
+  if (packetStatus === 'needs_human') return 'needs_human';
+  if (packetStatus === 'rejected') return 'rejected';
+  if (phaseStatus === 'completed' && testsPassed && qaPacket) return 'needs_human';
+  if (testsPassed) return 'needs_human';
+  return 'needs_human';
+}
+
+export async function artifactVerify(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id || null;
+  if (!changeId) {
+    throw new Error('change_id is required for E5.artifact.verify');
+  }
+
+  const phase = input.phase || context.phase?.id || 'qa';
+  const dataFile = resolveDataFile({ projectRoot, explicitPath: input.data_file || null });
+  const missionId = resolveBoundMissionId({
+    projectRoot,
+    changeId,
+    missionId: input.mission_id || null,
+    runtimeMissionId: context.runtime?.missionId || null,
+  });
+
+  if (!missionId) {
+    throw new Error('mission_id is required for E5.artifact.verify');
+  }
+
+  const state = await readStore(dataFile);
+  const phaseRun = getLatestPhaseRun(state, missionId);
+  const phaseEntry = getLatestPhaseEntry(phaseRun, phase);
+  const verifyProofPath = resolveChangePath(projectRoot, changeId, 'verify_proof.json');
+  const verifyProof = readJsonFile(verifyProofPath, null);
+  const qaPacket = phaseEntry?.team_run?.qa_acceptance_packet || null;
+  const status = deriveQaStatus({ verifyProof, qaPacket, phaseEntry });
+  const packet = makeArtifactEnvelope({
+    phase,
+    changeId,
+    missionId,
+    phaseRun,
+    phaseEntry,
+    extra: {
+      verify_proof: verifyProof,
+      qa_acceptance_packet: qaPacket,
+      manifest_valid: existsSync(verifyProofPath),
+      qa_status: status,
+      primary_journey_covered: qaPacket?.primary_journey_covered ?? (verifyProof?.all_passed === true),
+      module_coverage: qaPacket?.module_coverage || null,
+      cross_module_continuity: qaPacket?.cross_module_continuity || null,
+      failed_checks: qaPacket?.failed_checks || [],
+    },
+  });
+
+  const outputPath = resolveChangePath(projectRoot, changeId, 'qa_acceptance.json');
+  writeJsonFile(outputPath, packet);
+
+  return {
+    ok: status === 'accepted',
+    verdict: status,
+    mission_id: missionId,
+    phase_run_id: phaseRun?.phase_run_id || null,
+    qa_acceptance_file: outputPath,
+    packet,
+  };
+}

package/src/core/atoms/gate/competitor-contract-validate.js

@@ -0,0 +1,119 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv from 'ajv';
+
+import { readJsonFile, resolveChangePath } from '../../change-artifacts.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const CONTRACT_SCHEMA = JSON.parse(readFileSync(
+  resolve(__dirname, '../../../../schemas/competitor-reconstruction-contract.schema.json'),
+  'utf8',
+));
+const ajv = new Ajv({ allErrors: true });
+const validateContractSchema = ajv.compile(CONTRACT_SCHEMA);
+
+function ensureNonEmptyArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}
+
+function loadArtifact(projectRoot, changeId, filename) {
+  return readJsonFile(resolveChangePath(projectRoot, changeId, filename), null);
+}
+
+export async function competitorContractValidate(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id || null;
+  if (!changeId) {
+    throw new Error('change_id is required for H2c.design.competitor_contract_validate');
+  }
+
+  const artifactPath = resolveChangePath(projectRoot, changeId, 'competitor_reconstruction_review.json');
+  const artifact = readJsonFile(artifactPath, null);
+  const contract = artifact?.competitor_reconstruction_contract || null;
+  const referenceLockArtifact = loadArtifact(projectRoot, changeId, 'reference_surface_lock.json');
+  const reconstructionPackArtifact = loadArtifact(projectRoot, changeId, 'reconstruction_pack.json');
+  const generationContractArtifact = loadArtifact(projectRoot, changeId, 'generation_contract.json');
+  const referenceLock = referenceLockArtifact?.reference_surface_lock || null;
+  const reconstructionPack = reconstructionPackArtifact?.reconstruction_pack || null;
+  const generationContract = generationContractArtifact?.generation_contract || null;
+  const issues = [];
+
+  if (!artifact) issues.push('competitor_reconstruction_review_missing');
+  if (!contract) issues.push('competitor_reconstruction_contract_missing');
+  if (contract && !validateContractSchema(contract)) {
+    issues.push('competitor_reconstruction_contract_schema_invalid');
+  }
+  if (contract?.status !== 'frozen') issues.push('competitor_reconstruction_contract_not_frozen');
+  if (!contract?.competitor_product || contract.competitor_product === 'required') issues.push('competitor_product_unspecified');
+  if (!ensureNonEmptyArray(contract?.target_surfaces)) issues.push('target_surfaces_missing');
+  if (!contract?.primary_reference_surface || !contract.target_surfaces?.includes(contract.primary_reference_surface)) {
+    issues.push('primary_reference_surface_missing');
+  }
+  if (!ensureNonEmptyArray(contract?.required_modules)) issues.push('required_modules_missing');
+  if (!ensureNonEmptyArray(contract?.primary_journeys)) issues.push('primary_journeys_missing');
+  if (!ensureNonEmptyArray(contract?.business_logic_invariants)) issues.push('business_logic_invariants_missing');
+  if (!contract?.decomposition_requirements || typeof contract.decomposition_requirements !== 'object') {
+    issues.push('decomposition_requirements_missing');
+  }
+
+  if (!referenceLock) issues.push('reference_surface_lock_missing');
+  if (referenceLock?.status !== 'locked') issues.push('reference_surface_lock_not_locked');
+  if (referenceLock?.primary_reference_surface !== contract?.primary_reference_surface) {
+    issues.push('reference_surface_lock_mismatch');
+  }
+
+  if (!reconstructionPack) issues.push('reconstruction_pack_missing');
+  if (reconstructionPack?.status !== 'ready') issues.push('reconstruction_pack_not_ready');
+  if (!ensureNonEmptyArray(reconstructionPack?.surface_map)) issues.push('reconstruction_pack_surface_map_missing');
+  if (!ensureNonEmptyArray(reconstructionPack?.layout_map?.regions)) issues.push('reconstruction_pack_layout_map_missing');
+  if (!ensureNonEmptyArray(reconstructionPack?.component_inventory)) issues.push('reconstruction_pack_component_inventory_missing');
+  if (!ensureNonEmptyArray(reconstructionPack?.component_blueprint)) issues.push('reconstruction_pack_component_blueprint_missing');
+  if (!ensureNonEmptyArray(reconstructionPack?.state_inventory)) issues.push('reconstruction_pack_state_inventory_missing');
+  if (!reconstructionPack?.visual_token_map || typeof reconstructionPack.visual_token_map !== 'object') {
+    issues.push('reconstruction_pack_visual_token_map_missing');
+  }
+  if (!reconstructionPack?.reference_intermediate_model || typeof reconstructionPack.reference_intermediate_model !== 'object') {
+    issues.push('reconstruction_pack_reference_intermediate_model_missing');
+  }
+
+  if (!generationContract) issues.push('generation_contract_missing');
+  if (generationContract?.status !== 'ready') issues.push('generation_contract_not_ready');
+  if (!generationContract?.layout_constraints || typeof generationContract.layout_constraints !== 'object') {
+    issues.push('generation_contract_layout_constraints_missing');
+  }
+  if (!generationContract?.component_constraints || typeof generationContract.component_constraints !== 'object') {
+    issues.push('generation_contract_component_constraints_missing');
+  }
+  if (!ensureNonEmptyArray(generationContract?.component_constraints?.component_blueprint)) {
+    issues.push('generation_contract_component_blueprint_missing');
+  }
+  if (!ensureNonEmptyArray(generationContract?.component_constraints?.staged_generation?.stages)) {
+    issues.push('generation_contract_staged_generation_missing');
+  }
+  if (!generationContract?.state_constraints || typeof generationContract.state_constraints !== 'object') {
+    issues.push('generation_contract_state_constraints_missing');
+  }
+  if (!generationContract?.visual_constraints || typeof generationContract.visual_constraints !== 'object') {
+    issues.push('generation_contract_visual_constraints_missing');
+  }
+  if (!generationContract?.visual_constraints?.geometry_hints || typeof generationContract.visual_constraints.geometry_hints !== 'object') {
+    issues.push('generation_contract_geometry_hints_missing');
+  }
+  if (!generationContract?.visual_constraints?.token_hints || typeof generationContract.visual_constraints.token_hints !== 'object') {
+    issues.push('generation_contract_token_hints_missing');
+  }
+  if (!generationContract?.repair_policy || typeof generationContract.repair_policy !== 'object') {
+    issues.push('generation_contract_repair_policy_missing');
+  }
+
+  return {
+    ok: issues.length === 0,
+    status: issues.length === 0 ? 'accepted' : 'needs_human',
+    artifact_file: artifactPath,
+    issues,
+  };
+}
+
+export default competitorContractValidate;

package/src/core/atoms/gate/evidence-collect.js

@@ -0,0 +1,64 @@
+import { resolveBoundMissionId } from '../../bindings.js';
+import { collectExistingFiles, makeArtifactEnvelope, resolveChangePath, writeJsonFile } from '../../change-artifacts.js';
+import { getLatestPhaseEntry, getLatestPhaseRun } from '../../phase-run-read.js';
+import { readStore, resolveDataFile } from '../../state-store.js';
+
+export async function gateEvidenceCollect(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id || null;
+  if (!changeId) {
+    throw new Error('change_id is required for J5.gate.evidence_collect');
+  }
+
+  const phase = input.phase || context.phase?.id || null;
+  const dataFile = resolveDataFile({ projectRoot, explicitPath: input.data_file || null });
+  const missionId = resolveBoundMissionId({
+    projectRoot,
+    changeId,
+    missionId: input.mission_id || null,
+    runtimeMissionId: context.runtime?.missionId || null,
+  });
+
+  const state = missionId ? await readStore(dataFile) : null;
+  const phaseRun = missionId ? getLatestPhaseRun(state, missionId) : null;
+  const phaseEntry = phase ? getLatestPhaseEntry(phaseRun, phase) : null;
+  const baseFiles = collectExistingFiles([
+    resolveChangePath(projectRoot, changeId, 'proposal.json'),
+    resolveChangePath(projectRoot, changeId, 'proposal.md'),
+    resolveChangePath(projectRoot, changeId, 'plan.json'),
+    resolveChangePath(projectRoot, changeId, 'plan.md'),
+    resolveChangePath(projectRoot, changeId, 'verify_proof.json'),
+    resolveChangePath(projectRoot, changeId, 'qa_acceptance.json'),
+    resolveChangePath(projectRoot, changeId, 'review.json'),
+    resolveChangePath(projectRoot, changeId, 'gate_final.json'),
+  ]);
+
+  if (phaseRun?.phase_run_file) {
+    baseFiles.push(phaseRun.phase_run_file);
+  }
+
+  const packet = makeArtifactEnvelope({
+    phase,
+    changeId,
+    missionId,
+    phaseRun,
+    phaseEntry,
+    extra: {
+      evidence_refs: [...new Set(baseFiles)],
+      evidence_count: baseFiles.length,
+      phase_run_session_id: context.runtime?.phaseRunSessionId || null,
+    },
+  });
+
+  const outputPath = resolveChangePath(projectRoot, changeId, `evidence/${phase || 'latest'}.json`);
+  writeJsonFile(outputPath, packet);
+
+  return {
+    ok: true,
+    mission_id: missionId,
+    phase_run_id: phaseRun?.phase_run_id || null,
+    evidence_file: outputPath,
+    evidence_count: packet.evidence_count,
+    packet,
+  };
+}

package/src/core/atoms/gate/payload-from-phase-run.js

@@ -0,0 +1,78 @@
+import {
+  makeArtifactEnvelope,
+  renderMarkdownArtifact,
+  resolveChangePath,
+  writeJsonFile,
+  writeTextFile,
+} from '../../change-artifacts.js';
+import { resolveBoundMissionId } from '../../bindings.js';
+import { getLatestPhaseEntry, getLatestPhaseRun } from '../../phase-run-read.js';
+import { readStore, resolveDataFile } from '../../state-store.js';
+
+function titleForPhase(phase) {
+  if (phase === 'proposal') return 'Proposal';
+  if (phase === 'plan') return 'Plan';
+  return phase ? phase.replace(/_/g, ' ').replace(/\b\w/g, (m) => m.toUpperCase()) : 'Phase';
+}
+
+export async function gatePayloadFromPhaseRun(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id || null;
+  if (!changeId) {
+    throw new Error('change_id is required for E4.gate.payload_from_phase_run');
+  }
+
+  const phase = input.phase || context.phase?.id || null;
+  if (!phase) {
+    throw new Error('phase is required for E4.gate.payload_from_phase_run');
+  }
+
+  const dataFile = resolveDataFile({ projectRoot, explicitPath: input.data_file || null });
+  const missionId = resolveBoundMissionId({
+    projectRoot,
+    changeId,
+    missionId: input.mission_id || null,
+    runtimeMissionId: context.runtime?.missionId || null,
+  });
+
+  if (!missionId) {
+    throw new Error('mission_id is required for E4.gate.payload_from_phase_run');
+  }
+
+  const state = await readStore(dataFile);
+  const phaseRun = getLatestPhaseRun(state, missionId);
+  if (!phaseRun) {
+    throw new Error(`No phase run found for mission ${missionId}`);
+  }
+
+  const phaseEntry = getLatestPhaseEntry(phaseRun, phase);
+  const envelope = makeArtifactEnvelope({
+    phase,
+    changeId,
+    missionId,
+    phaseRun,
+    phaseEntry,
+    extra: {
+      qa_acceptance_packet: phaseEntry?.team_run?.qa_acceptance_packet || null,
+      workspace_evidence: phaseEntry?.team_run?.workspace_evidence || phaseRun.workspace_evidence || null,
+    },
+  });
+
+  const jsonPath = resolveChangePath(projectRoot, changeId, `${phase}.json`);
+  writeJsonFile(jsonPath, envelope);
+
+  let mdPath = null;
+  if (phase === 'proposal' || phase === 'plan') {
+    mdPath = resolveChangePath(projectRoot, changeId, `${phase}.md`);
+    writeTextFile(mdPath, renderMarkdownArtifact({ title: titleForPhase(phase), phase, envelope }));
+  }
+
+  return {
+    ok: true,
+    mission_id: missionId,
+    phase_run_id: phaseRun.phase_run_id,
+    json_file: jsonPath,
+    markdown_file: mdPath,
+    payload: envelope,
+  };
+}

package/src/core/atoms/gate/visual-benchmark-validate.js

@@ -0,0 +1,183 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+
+import Ajv from 'ajv';
+
+import { readJsonFile, resolveChangePath } from '../../change-artifacts.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const VISUAL_BENCHMARK_SCHEMA = JSON.parse(readFileSync(
+  resolve(__dirname, '../../../../schemas/visual-benchmark.schema.json'),
+  'utf8',
+));
+const ajv = new Ajv({ allErrors: true });
+const validateBenchmarkSchema = ajv.compile(VISUAL_BENCHMARK_SCHEMA);
+
+function resolveEvidencePath(projectRoot, filePath) {
+  if (!filePath) return null;
+  return isAbsolute(filePath) ? filePath : resolve(projectRoot, filePath);
+}
+
+function sameResolvedEvidencePath(projectRoot, left, right) {
+  const leftPath = resolveEvidencePath(projectRoot, left);
+  const rightPath = resolveEvidencePath(projectRoot, right);
+  if (!leftPath || !rightPath) return false;
+  if (leftPath === rightPath) return true;
+  if (!existsSync(leftPath) || !existsSync(rightPath)) return false;
+  return hashFile(leftPath) === hashFile(rightPath);
+}
+
+function hashFile(filePath) {
+  return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+}
+
+export async function visualBenchmarkValidate(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id || null;
+  const advisory = String(input.mode || '').toLowerCase() === 'advisory';
+  if (!changeId) {
+    throw new Error('change_id is required for H6b.visual.benchmark_validate');
+  }
+
+  const artifactPath = resolveChangePath(projectRoot, changeId, 'visual_benchmark.json');
+  const artifact = readJsonFile(artifactPath, null);
+  const issues = [];
+
+  if (!artifact) {
+    issues.push('visual_benchmark_missing');
+  } else {
+    if (!validateBenchmarkSchema(artifact)) {
+      issues.push('visual_benchmark_schema_invalid');
+    }
+    const scenarios = Array.isArray(artifact.scenarios) ? artifact.scenarios : [];
+    const requiredModules = Array.isArray(artifact.required_modules) ? artifact.required_modules : [];
+    if (!artifact.competitor_product) issues.push('visual_benchmark_competitor_missing');
+    if (requiredModules.length === 0) issues.push('visual_benchmark_required_modules_missing');
+    if (artifact.benchmark_mode !== 'reference_backed') issues.push('visual_benchmark_not_reference_backed');
+    if (!['reference_scenarios', 'capture_url'].includes(artifact.benchmark_input_mode)) {
+      issues.push('visual_benchmark_input_contract_missing');
+    }
+    if (artifact.report_file) {
+      const reportPath = resolveEvidencePath(projectRoot, artifact.report_file);
+      if (!reportPath || !existsSync(reportPath)) issues.push('visual_benchmark_report_unresolved');
+    }
+    if (scenarios.length === 0) issues.push('visual_benchmark_scenarios_missing');
+    if (scenarios.some((scenario) => !scenario.viewport)) issues.push('visual_benchmark_viewport_missing');
+    if (scenarios.some((scenario) => !scenario.reference_image)) issues.push('visual_benchmark_reference_image_missing');
+    if (scenarios.some((scenario) => !scenario.screenshot_image)) issues.push('visual_benchmark_screenshot_image_missing');
+    if (scenarios.some((scenario) => sameResolvedEvidencePath(projectRoot, scenario.reference_image, scenario.screenshot_image))) {
+      issues.push('visual_benchmark_self_referential_scenario');
+    }
+    if (scenarios.some((scenario) => {
+      const referencePath = resolveEvidencePath(projectRoot, scenario.reference_image);
+      return !referencePath || !existsSync(referencePath);
+    })) {
+      issues.push('visual_benchmark_reference_image_unresolved');
+    }
+    if (scenarios.some((scenario) => {
+      const screenshotPath = resolveEvidencePath(projectRoot, scenario.screenshot_image);
+      return !screenshotPath || !existsSync(screenshotPath);
+    })) {
+      issues.push('visual_benchmark_screenshot_image_unresolved');
+    }
+    if (scenarios.some((scenario) => !scenario.diff_metrics || typeof scenario.diff_metrics !== 'object')) {
+      issues.push('visual_benchmark_diff_metrics_missing');
+    }
+    if (scenarios.some((scenario) => scenario.diff_metrics?.status !== 'pass')) {
+      issues.push('visual_benchmark_diff_metrics_unresolved');
+    }
+    if (scenarios.some((scenario) => !Array.isArray(scenario.structure_checks) || scenario.structure_checks.length === 0)) {
+      issues.push('visual_benchmark_structure_checks_missing');
+    }
+    if (scenarios.some((scenario) =>
+      Array.isArray(scenario.structure_checks) && scenario.structure_checks.some((check) => check?.status !== 'pass')
+    )) {
+      issues.push('visual_benchmark_structure_checks_unresolved');
+    }
+    if (scenarios.some((scenario) =>
+      scenario.visual_token_contract
+      && (!Array.isArray(scenario.token_checks) || scenario.token_checks.length === 0)
+    )) {
+      issues.push('visual_benchmark_token_checks_missing');
+    }
+    if (scenarios.some((scenario) =>
+      scenario.visual_token_contract
+      && Array.isArray(scenario.token_checks)
+      && scenario.token_checks.some((check) => check?.status !== 'pass')
+    )) {
+      issues.push('visual_benchmark_token_checks_unresolved');
+    }
+    if (scenarios.some((scenario) =>
+      Array.isArray(scenario.state_evidence)
+      && scenario.state_evidence.length > 0
+      && (!Array.isArray(scenario.state_transition_checks) || scenario.state_transition_checks.length === 0)
+    )) {
+      issues.push('visual_benchmark_state_transition_checks_missing');
+    }
+    if (scenarios.some((scenario) =>
+      Array.isArray(scenario.state_transition_checks)
+      && scenario.state_transition_checks.some((check) => check?.status !== 'pass')
+    )) {
+      issues.push('visual_benchmark_state_transition_checks_unresolved');
+    }
+    if (scenarios.some((scenario) =>
+      Array.isArray(scenario.state_evidence)
+      && scenario.state_evidence.some((state) => Array.isArray(state?.frame_screenshot_images) && state.frame_screenshot_images.length > 0)
+      && (!Array.isArray(scenario.motion_transition_checks) || scenario.motion_transition_checks.length === 0)
+    )) {
+      issues.push('visual_benchmark_motion_transition_checks_missing');
+    }
+    if (scenarios.some((scenario) =>
+      Array.isArray(scenario.motion_transition_checks)
+      && scenario.motion_transition_checks.some((check) => check?.status !== 'pass')
+    )) {
+      issues.push('visual_benchmark_motion_transition_checks_unresolved');
+    }
+    if (scenarios.some((scenario) =>
+      scenario.state_contract
+      && (!Array.isArray(scenario.state_contract_checks) || scenario.state_contract_checks.length === 0)
+    )) {
+      issues.push('visual_benchmark_state_contract_checks_missing');
+    }
+    if (scenarios.some((scenario) =>
+      scenario.state_contract
+      && Array.isArray(scenario.state_contract_checks)
+      && scenario.state_contract_checks.some((check) => check?.status !== 'pass')
+    )) {
+      issues.push('visual_benchmark_state_contract_checks_unresolved');
+    }
+    if (scenarios.some((scenario) =>
+      scenario.state_family_contract
+      && (!Array.isArray(scenario.state_family_checks) || scenario.state_family_checks.length === 0)
+    )) {
+      issues.push('visual_benchmark_state_family_checks_missing');
+    }
+    if (scenarios.some((scenario) =>
+      scenario.state_family_contract
+      && Array.isArray(scenario.state_family_checks)
+      && scenario.state_family_checks.some((check) => check?.status !== 'pass')
+    )) {
+      issues.push('visual_benchmark_state_family_checks_unresolved');
+    }
+    if (artifact.benchmark_matrix_contract && (!Array.isArray(artifact.matrix_checks) || artifact.matrix_checks.length === 0)) {
+      issues.push('visual_benchmark_matrix_checks_missing');
+    }
+    if (Array.isArray(artifact.matrix_checks) && artifact.matrix_checks.some((check) => check?.status !== 'pass')) {
+      issues.push('visual_benchmark_matrix_checks_unresolved');
+    }
+    if (scenarios.some((scenario) => scenario.status !== 'pass')) issues.push('visual_benchmark_has_unresolved_scenarios');
+  }
+
+  return {
+    ok: advisory ? true : issues.length === 0,
+    status: issues.length === 0 ? 'accepted' : 'needs_human',
+    artifact_file: artifactPath,
+    issues,
+    advisory,
+  };
+}
+
+export default visualBenchmarkValidate;