stylegallery 0.1.0

package/scripts/create-page-evidence-session.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  addSchemaFindings,
+  canonicalSourceManifest,
+  compilePageEvidenceSchemas,
+  dirtyRelevantSources,
+  finding,
+  gitIdentity,
+  metadata,
+  normalizeReference,
+  PAGE_EVIDENCE_RECEIPT,
+  readJsonFile,
+  resolveContained,
+} from "./page-evidence-contract.mjs";
+
+const styleGalleryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const options = { artifactRoot: undefined, json: false, record: undefined, root: undefined };
+const failures = [];
+
+for (let index = 2; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--json") options.json = true;
+  else if (["--artifact-root", "--record", "--root"].includes(argument)) {
+    const value = process.argv[index + 1];
+    if (!value || value.startsWith("--")) failures.push(finding("argument_value_required", `${argument} requires a value`, "<cli>"));
+    else {
+      if (argument === "--artifact-root") options.artifactRoot = path.resolve(process.cwd(), value);
+      if (argument === "--record") options.record = value;
+      if (argument === "--root") options.root = path.resolve(process.cwd(), value);
+      index += 1;
+    }
+  } else failures.push(finding("argument_unknown", `unsupported argument ${argument}`, "<cli>"));
+}
+
+for (const [name, value] of [["--root", options.root], ["--record", options.record], ["--artifact-root", options.artifactRoot]]) {
+  if (!value) failures.push(finding("argument_value_required", `${name} is required`, "<cli>"));
+}
+
+let schemas;
+try { schemas = compilePageEvidenceSchemas(path.join(styleGalleryRoot, "consumer-reference/schema")); }
+catch (error) { failures.push(finding("page_evidence_schema_invalid", error instanceof Error ? error.message : String(error), "consumer-reference/schema")); }
+
+let artifactReference;
+if (options.root && options.artifactRoot) {
+  artifactReference = normalizeReference(options.root, options.artifactRoot);
+  if (!artifactReference) failures.push(finding("page_evidence_artifact_escape", "artifact root must be inside the consumer repository", options.artifactRoot));
+  else {
+    const resolved = resolveContained({ allowMissing: true, expectedType: "directory", prefix: "page_evidence_artifact", reference: artifactReference, root: options.root }, failures);
+    if (resolved && fs.existsSync(resolved.file) && fs.readdirSync(resolved.file).length > 0) failures.push(finding("page_evidence_session_replay", "artifact root must be empty before session start", artifactReference));
+  }
+}
+
+let record;
+let recordReference;
+if (options.root && options.record) {
+  recordReference = normalizeReference(options.root, options.record);
+  if (!recordReference) failures.push(finding("page_evidence_conformance_escape", "conformance record must be inside the consumer repository", options.record));
+  else record = readJsonFile({ prefix: "page_evidence_conformance", reference: recordReference, root: options.root }, failures);
+}
+
+const consumer = record?.value?.consumer;
+const sourcePaths = consumer?.relevant_sources;
+const browserScenarios = Array.isArray(record?.value?.scenarios)
+  ? record.value.scenarios.filter((scenario) => scenario?.evidence_method === "browser")
+  : [];
+if (!consumer || typeof consumer.repository !== "string" || !/^[a-f0-9]{40}$/.test(consumer.revision ?? "") || !Array.isArray(sourcePaths)) {
+  failures.push(finding("page_evidence_conformance_invalid", "conformance record must declare consumer repository, revision, and relevant_sources", recordReference ?? "<conformance-record>"));
+}
+if (browserScenarios.length === 0) failures.push(finding("page_evidence_intent_missing", "conformance record must declare at least one browser scenario", recordReference ?? "<conformance-record>"));
+
+const scenarioIds = browserScenarios.map((scenario) => scenario.id);
+const sessionIds = new Set(browserScenarios.map((scenario) => scenario.session_id));
+const runIds = new Set(browserScenarios.map((scenario) => scenario.run_id));
+if (new Set(scenarioIds).size !== scenarioIds.length || scenarioIds.some((id) => typeof id !== "string")) failures.push(finding("page_evidence_intent_invalid", "browser scenario IDs must be unique strings", recordReference ?? "<conformance-record>"));
+if (sessionIds.size !== 1 || runIds.size !== 1 || [...sessionIds, ...runIds].some((identity) => typeof identity !== "string" || identity.length === 0)) {
+  failures.push(finding("page_evidence_intent_identity_mismatch", "all page scenarios must use one nonempty session and run identity", recordReference ?? "<conformance-record>"));
+}
+
+const git = options.root ? gitIdentity(options.root, failures) : undefined;
+if (git && consumer) {
+  if (git.revision !== consumer.revision || (process.env.GITHUB_SHA && process.env.GITHUB_SHA !== git.revision)) failures.push(finding("page_evidence_revision_mismatch", "conformance revision must equal checked-out Git HEAD", recordReference));
+  if (git.repository && git.repository !== consumer.repository) failures.push(finding("page_evidence_repository_mismatch", "conformance repository differs from the Git remote identity", recordReference));
+}
+
+let source;
+if (options.root && Array.isArray(sourcePaths)) {
+  source = canonicalSourceManifest(options.root, sourcePaths, failures);
+  if (source) {
+    const dirty = dirtyRelevantSources(options.root, sourcePaths);
+    if (dirty.length > 0) failures.push(finding("page_evidence_source_dirty", `relevant sources must be clean tracked files: ${dirty.join(", ")}`, options.root));
+    if (browserScenarios.some((scenario) => scenario.source_digest !== source.sha256)) failures.push(finding("page_evidence_source_mismatch", "browser scenario source_digest must equal the relevant-source aggregate", recordReference));
+  }
+}
+
+const receipt = record && source && git && sessionIds.size === 1 && runIds.size === 1 ? {
+  attempt: Number(process.env.GITHUB_RUN_ATTEMPT ?? 1),
+  branch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || git.branch,
+  conformance_record: metadata(record.bytes, "application/json", recordReference),
+  environment: {
+    kind: "browser_evidence",
+    node: process.version,
+    platform: `${process.platform}/${process.arch}`,
+    producer: "stylegallery_page_evidence",
+  },
+  intended_scenario_ids: scenarioIds,
+  nonce: crypto.randomBytes(32).toString("hex"),
+  record_kind: "page_evidence_session",
+  repository: consumer.repository,
+  revision: consumer.revision,
+  run_id: [...runIds][0],
+  schema_version: "1.0",
+  session_id: [...sessionIds][0],
+  source,
+  started_at: new Date().toISOString(),
+} : undefined;
+if (receipt && schemas) addSchemaFindings(schemas.session, receipt, PAGE_EVIDENCE_RECEIPT, "page_evidence_session_schema_invalid", failures);
+
+const receiptFile = options.artifactRoot ? path.join(options.artifactRoot, PAGE_EVIDENCE_RECEIPT) : undefined;
+if (failures.length === 0 && receiptFile) {
+  fs.mkdirSync(options.artifactRoot, { recursive: true });
+  fs.writeFileSync(receiptFile, `${JSON.stringify(receipt, null, 2)}\n`, { flag: "wx" });
+}
+const result = {
+  failures,
+  intendedScenarios: receipt?.intended_scenario_ids.length ?? 0,
+  ok: failures.length === 0,
+  receipt: receiptFile,
+  sessionId: receipt?.session_id,
+  sourceSha256: receipt?.source.sha256,
+};
+if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+else if (result.ok) process.stdout.write(`created page evidence session ${result.sessionId}\n`);
+else process.stderr.write(`${failures.map((issue) => `${issue.code}: ${issue.path}: ${issue.message}`).join("\n")}\n`);
+if (!result.ok) process.exitCode = 1;

package/scripts/domain-document-boundaries.mjs

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isOmoDependency, markdownLinkDestinations } from "./markdown-structure.mjs";
+
+const generatedReference = /^design-engineering\/reference-profiles\/governed-local\/(?:editorial|terminal)\/generated\/(?:state-matrix|keyboard-matrix|evidence-coverage)\.md$/;
+const ignoredDirectories = new Set([".git", ".omo", "node_modules"]);
+
+function walkMarkdown(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (ignoredDirectories.has(entry.name)) return [];
+    const target = path.join(dir, entry.name);
+    if (entry.isDirectory()) return walkMarkdown(target);
+    return entry.isFile() && entry.name.endsWith(".md") ? [target] : [];
+  });
+}
+
+function undeclaredDomainDocumentFailures(root, domains) {
+  return domains.flatMap((domain) => {
+    const declared = new Set([`${domain.slug}/index.md`, ...domain.leaves.map(([leaf]) => leaf), ...(domain.referenceDocuments ?? [])]);
+    return walkMarkdown(path.join(root, domain.slug)).flatMap((absolute) => {
+      const relative = path.relative(root, absolute);
+      if (generatedReference.test(relative) || declared.has(relative)) return [];
+      return [`${relative}: undeclared governed domain document`];
+    });
+  });
+}
+
+function omoDependencyFailures(root) {
+  return walkMarkdown(root).flatMap((absolute) => {
+    const relative = path.relative(root, absolute);
+    const content = fs.readFileSync(absolute, "utf8");
+    if (markdownLinkDestinations(content).some(isOmoDependency)) return [`${relative}: tracked document must not depend on .omo`];
+    return [];
+  });
+}
+
+export function collectDomainBoundaryFailures(root, domains) {
+  return [...undeclaredDomainDocumentFailures(root, domains), ...omoDependencyFailures(root)];
+}

package/scripts/domain-validation-checks.mjs

@@ -0,0 +1,141 @@
+import path from "node:path";
+import { isOmoDependency, markdownLinkDestinations, stripFencedCodeBlocks, structuralMarkdown } from "./markdown-structure.mjs";
+
+export function createDomainValidationChecks({
+  domains,
+  failures,
+  read,
+  referenceDocuments,
+  repository,
+  revision,
+  revisionPattern,
+  requiredLeafSections,
+  sourceOverrides,
+}) {
+  function parseFrontmatter(relative, content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+    if (!match) {
+      failures.push(`${relative}: missing frontmatter`);
+      return {};
+    }
+    const metadata = {};
+    for (const rawLine of match[1].split("\n")) {
+      if (!rawLine.trim()) continue;
+      const separator = rawLine.indexOf(":");
+      if (separator === -1) {
+        failures.push(`${relative}: malformed frontmatter line`);
+        continue;
+      }
+      const key = rawLine.slice(0, separator).trim();
+      const value = rawLine.slice(separator + 1).trim().replace(/^["']|["']$/g, "");
+      if (Object.hasOwn(metadata, key)) failures.push(`${relative}: duplicate frontmatter key ${key}`);
+      metadata[key] = value;
+    }
+    return metadata;
+  }
+
+  function checkIndex(domain) {
+    const relative = `${domain.slug}/index.md`;
+    const content = structuralMarkdown(read(relative));
+    if (!content) return;
+    if (!content.includes("## Scope Boundary")) failures.push(`${relative}: missing Scope Boundary section`);
+    if (!/^In scope:\s*\S/m.test(content)) failures.push(`${relative}: missing In scope declaration`);
+    if (!/^Out of scope:\s*\S/m.test(content)) failures.push(`${relative}: missing Out of scope declaration`);
+    if (!/^Parent: \[[^\]]+\]\([^)]+\)/m.test(content)) failures.push(`${relative}: missing Parent navigation link`);
+    if (!/^Next: \[[^\]]+\]\([^)]+\)/m.test(content)) failures.push(`${relative}: missing Next navigation link`);
+    for (const leaf of domain.leaves) {
+      const target = path.posix.relative(domain.slug, leaf.path);
+      if (!content.match(new RegExp(`\\[[^\\]]+\\]\\(${target.replaceAll(".", "\\.")}\\)`))) {
+        failures.push(`${relative}: missing leaf route ${target}`);
+      }
+    }
+    if (domain.referenceDocuments?.length > 0 && !content.includes("[Reference Profiles](reference-profiles/index.md)")) {
+      failures.push(`${relative}: missing reference profile route`);
+    }
+  }
+
+  function checkLeaf(domain, leaf, titles) {
+    const { path: relative, provenance, sourcePath: expectedSourcePath } = leaf;
+    const content = read(relative);
+    if (!content) return;
+    const metadata = parseFrontmatter(relative, content);
+    const requiredFields = ["type", "title", "description", "domain", "lifecycle"];
+    if (provenance === "external") requiredFields.push("source_repository", "source_path", "source_revision");
+    if (provenance === "local") requiredFields.push("provenance_kind");
+    for (const field of requiredFields) {
+      if (!metadata[field]) failures.push(`${relative}: missing ${field}`);
+    }
+    const knownDomain = domains.some((candidate) => candidate.slug === metadata.domain);
+    if (metadata.domain && !knownDomain) failures.push(`${relative}: unknown domain ${metadata.domain}`);
+    else if (metadata.domain && metadata.domain !== domain.slug) failures.push(`${relative}: domain ${metadata.domain} does not match ${domain.slug}`);
+    if (metadata.lifecycle && metadata.lifecycle !== "experimental") {
+      const kind = provenance === "local" ? "local leaf" : provenance === "external" ? "external adaptation" : "domain leaf";
+      failures.push(`${relative}: ${kind} lifecycle must be experimental`);
+    }
+    if (provenance === "external") {
+      const expectedSource = sourceOverrides[relative] ?? { repository, revision };
+      if (metadata.source_repository && metadata.source_repository !== expectedSource.repository) failures.push(`${relative}: unexpected source_repository ${metadata.source_repository}`);
+      if (metadata.source_path && metadata.source_path !== expectedSourcePath) failures.push(`${relative}: unexpected source_path ${metadata.source_path}`);
+      if (metadata.source_revision && !revisionPattern.test(metadata.source_revision)) {
+        failures.push(`${relative}: source_revision must be a full 40-character lowercase Git SHA`);
+      } else if (metadata.source_revision && metadata.source_revision !== expectedSource.revision) {
+        failures.push(`${relative}: unexpected source_revision ${metadata.source_revision}`);
+      }
+    } else if (provenance === "local") {
+      if (metadata.provenance_kind && metadata.provenance_kind !== "local") failures.push(`${relative}: local leaf provenance_kind must be local`);
+      for (const field of ["source_repository", "source_path", "source_revision"]) {
+        if (Object.hasOwn(metadata, field)) failures.push(`${relative}: local leaf must not declare ${field}`);
+      }
+    } else {
+      for (const field of ["source_repository", "source_path", "source_revision"]) {
+        if (Object.hasOwn(metadata, field)) failures.push(`${relative}: locally authored leaf must omit ${field}`);
+      }
+    }
+    if (metadata.title) {
+      if (titles.has(metadata.title)) failures.push(`${relative}: duplicate title ${metadata.title}`);
+      titles.add(metadata.title);
+    }
+    const body = structuralMarkdown(content);
+    for (const section of requiredLeafSections) {
+      if (!body.includes(`## ${section}`)) failures.push(`${relative}: missing ${section} section`);
+    }
+    if (!/^Parent: \[[^\]]+\]\([^)]+\)/m.test(body)) failures.push(`${relative}: missing Parent navigation link`);
+    if (!/^Next: \[[^\]]+\]\([^)]+\)/m.test(body)) failures.push(`${relative}: missing Next navigation link`);
+    if (markdownLinkDestinations(content).some(isOmoDependency)) failures.push(`${relative}: tracked document must not depend on .omo`);
+    if (metadata.lifecycle === "experimental" && /canonical universal policy/i.test(body)) {
+      failures.push(`${relative}: experimental document claims canonical authority`);
+    }
+  }
+
+  function checkReferenceDocuments() {
+    const index = stripFencedCodeBlocks(read(referenceDocuments[0]));
+    if (!/Domain classification:\s*design-engineering\./i.test(index)) {
+      failures.push(`${referenceDocuments[0]}: reference profiles must remain in the Design Engineering domain`);
+    }
+    if (!index.includes("[Governed Local Profiles](governed-local/index.md)")) {
+      failures.push(`${referenceDocuments[0]}: missing governed-local route`);
+    }
+    const external = stripFencedCodeBlocks(read(referenceDocuments[2]));
+    if (!external.includes("Synthetic validator coverage only") || !external.includes("no durable adopter record")) {
+      failures.push(`${referenceDocuments[1]}: external adaptation must remain documentation-only`);
+    }
+  }
+
+  function checkPromotionBoundary() {
+    const relative = "DOMAINS.md";
+    const content = stripFencedCodeBlocks(read(relative));
+    const required = [
+      "### Consumer Reference Promotion",
+      "applies only to consumer-local → shared-experimental invariant eligibility",
+      "Editorial and terminal are related examples in one fixture set",
+      "Shared stable has no numeric adoption threshold",
+      "Normative correctness may waive adoption count only",
+      "never silently relabeled experimental",
+      "Promotion records are JSON-only",
+      "zero adopter attestations",
+    ];
+    for (const clause of required) if (!content.includes(clause)) failures.push(`${relative}: missing promotion boundary ${clause}`);
+  }
+
+  return { checkIndex, checkLeaf, checkReferenceDocuments, checkPromotionBoundary };
+}

package/scripts/evidence-artifact-contract.mjs

@@ -0,0 +1,191 @@
+import fs from "node:fs";
+import path from "node:path";
+import { artifactMetadata } from "./artifact-metadata.mjs";
+import { sameJson, withinSession } from "./capture-session-contract.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+import { visualExpectationFor } from "./visual-expectation-contract.mjs";
+
+function finding(code, file, message) {
+  return { code, message, path: file };
+}
+
+function isInside(base, target) {
+  const relative = path.relative(base, target);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function isSafeArtifactPath(reference) {
+  return typeof reference === "string"
+    && reference.length > 0
+    && !path.posix.isAbsolute(reference)
+    && !path.win32.isAbsolute(reference)
+    && !reference.includes("\\")
+    && !reference.includes("?")
+    && !reference.includes("#")
+    && !/^[A-Za-z][A-Za-z\d+.-]*:/.test(reference)
+    && path.posix.normalize(reference) === reference
+    && !reference.split("/").some((segment) => segment === "." || segment === "..");
+}
+
+function validateIntegrity(pass, bytes, evidenceFile, failures) {
+  const actual = artifactMetadata(bytes, pass.artifact.media_type);
+  if (actual.sha256 !== pass.artifact.sha256 || actual.byte_length !== pass.artifact.byte_length) failures.push(finding("evidence_artifact_integrity", evidenceFile, `${pass.id} hash or byte length does not match`));
+  if (pass.channel === "visual") {
+    if (!actual.width || !actual.height) failures.push(finding("evidence_png_invalid", evidenceFile, `${pass.id} is not a valid PNG with IHDR dimensions`));
+    else if (actual.width !== pass.artifact.width || actual.height !== pass.artifact.height) failures.push(finding("evidence_png_dimensions_mismatch", evidenceFile, `${pass.id} PNG dimensions do not match`));
+  }
+  return actual;
+}
+
+function observedDomValue(document, key) {
+  if (key === "active") return String(document.active);
+  if (key === "role") return document.role;
+  return document.attributes?.[key];
+}
+
+function validateDom(document, pass, scenario, fixture, profileId, evidenceFile, failures) {
+  if (document.schema_version !== "1.0" || document.channel !== "dom" || document.profile_id !== profileId || document.scenario_id !== pass.scenario_id || document.semantic_mode !== scenario.semantic_mode) {
+    failures.push(finding("evidence_dom_identity_mismatch", evidenceFile, `${pass.id} DOM identity does not match its pass`));
+  }
+  if (document.activation_key !== fixture.activation_key) failures.push(finding("evidence_runtime_identity_mismatch", evidenceFile, `${pass.id} activation key differs from the canonical fixture`));
+  for (const [key, expected] of Object.entries(scenario.expected.dom)) if (observedDomValue(document, key) !== expected) failures.push(finding("evidence_dom_content_mismatch", evidenceFile, `${pass.id} DOM ${key} differs from canonical state`));
+  const visual = JSON.stringify([...(document.visual_states ?? [])].sort());
+  if (visual !== JSON.stringify([...scenario.expected.visual].sort())) failures.push(finding("evidence_dom_content_mismatch", evidenceFile, `${pass.id} visual states differ from canonical state`));
+  const expectedActivations = scenario.expected.activation === "allowed" ? 1 : 0;
+  if (document.activation_count !== expectedActivations) failures.push(finding("evidence_dom_content_mismatch", evidenceFile, `${pass.id} activation result differs from canonical state`));
+}
+
+function validateAx(document, pass, scenario, fixture, profileId, evidenceFile, failures) {
+  if (document.schema_version !== "1.0" || document.channel !== "ax" || document.profile_id !== profileId || document.scenario_id !== pass.scenario_id || document.semantic_mode !== scenario.semantic_mode || document.name !== fixture.label) {
+    failures.push(finding("evidence_ax_identity_mismatch", evidenceFile, `${pass.id} AX identity does not match its pass`));
+  }
+  if (document.role !== scenario.expected.ax.role) failures.push(finding("evidence_ax_content_mismatch", evidenceFile, `${pass.id} AX role differs from canonical state`));
+  for (const [key, expected] of Object.entries(scenario.expected.ax)) {
+    const actual = key === "role" ? document.role : document.properties?.[key];
+    if (actual !== expected) failures.push(finding("evidence_ax_content_mismatch", evidenceFile, `${pass.id} AX ${key} differs from canonical state`));
+  }
+}
+
+function validateVisual(document, pass, scenario, profileId, actual, visualEnvironments, evidenceFile, failures) {
+  if (document.schema_version !== "1.0" || document.channel !== "visual" || document.profile_id !== profileId || document.scenario_id !== pass.scenario_id || document.semantic_mode !== scenario.semantic_mode) {
+    failures.push(finding("evidence_visual_identity_mismatch", evidenceFile, `${pass.id} visual identity does not match its pass`));
+  }
+  if (document.source_sha256 !== pass.session?.source?.sha256) failures.push(finding("capture_source_mismatch", evidenceFile, `${pass.id} visual source digest differs from its capture session`));
+  const expectedImage = { path: path.posix.basename(pass.artifact.path), ...actual };
+  if (!sameJson(document.image, expectedImage)) failures.push(finding("evidence_visual_image_mismatch", evidenceFile, `${pass.id} visual metadata does not match its PNG`));
+  try {
+    const expectation = visualExpectationFor(scenario, pass.environment, visualEnvironments);
+    if (actual.sha256 !== expectation.sha256 || actual.width !== expectation.width || actual.height !== expectation.height) failures.push(finding("evidence_visual_expectation_mismatch", evidenceFile, `${pass.id} PNG differs from its pre-capture approved visual expectation`));
+  } catch (error) {
+    failures.push(finding("evidence_visual_expectation_invalid", evidenceFile, error instanceof Error ? error.message : String(error)));
+  }
+}
+
+function parseArtifactJson(bytes, pass, scenario, fixture, profileId, evidenceFile, failures, schemas, session) {
+  let document;
+  try {
+    document = parseStrictJson(bytes.toString("utf8"));
+  } catch (error) {
+    failures.push(finding("evidence_json_invalid", evidenceFile, `${pass.id} is not structured JSON: ${error instanceof Error ? error.message : String(error)}`));
+    return undefined;
+  }
+  const validate = pass.channel === "dom" ? schemas.dom : pass.channel === "ax" ? schemas.ax : undefined;
+  if (validate && !validate(document)) {
+    const code = pass.channel === "dom" ? "evidence_dom_schema_invalid" : "evidence_ax_schema_invalid";
+    for (const error of validate.errors ?? []) failures.push(finding(code, evidenceFile, `${pass.id} ${error.instancePath || "/"} ${error.message}`));
+    return undefined;
+  }
+  if (!sameJson(document.capture_session, pass.session)) failures.push(finding("capture_session_mismatch", evidenceFile, `${pass.id} artifact session differs from its pass`));
+  if (document.captured_at !== pass.recorded_at) failures.push(finding("evidence_recorded_at_mismatch", evidenceFile, `${pass.id} recorded_at is not derived from artifact content`));
+  if (session && !withinSession(document.captured_at, session.started_at, session.completed_at)) failures.push(finding("capture_session_time_outside", evidenceFile, `${pass.id} was not captured within its session`));
+  if (pass.channel === "dom") validateDom(document, pass, scenario, fixture, profileId, evidenceFile, failures);
+  else if (pass.channel === "ax") validateAx(document, pass, scenario, fixture, profileId, evidenceFile, failures);
+  else failures.push(finding("evidence_channel_content_unknown", evidenceFile, `${pass.id} has no structured content contract`));
+  return document;
+}
+
+function readArtifact(pass, artifactRoot, evidenceFile, failures) {
+  const reference = pass.artifact?.path;
+  if (!isSafeArtifactPath(reference)) {
+    failures.push(finding("evidence_artifact_escape", evidenceFile, `${pass.id} artifact path is unsafe`));
+    return undefined;
+  }
+  const root = path.resolve(artifactRoot);
+  const target = path.resolve(root, reference);
+  if (!isInside(root, target) || !fs.existsSync(target)) {
+    failures.push(finding("evidence_artifact_missing", evidenceFile, `${pass.id} artifact is missing`));
+    return undefined;
+  }
+  const metadata = fs.lstatSync(target);
+  if (metadata.isSymbolicLink()) {
+    failures.push(finding("evidence_artifact_symlink", evidenceFile, `${pass.id} artifact must not be a symlink`));
+    return undefined;
+  }
+  if (!metadata.isFile()) {
+    failures.push(finding("evidence_artifact_type_invalid", evidenceFile, `${pass.id} artifact must be a regular file`));
+    return undefined;
+  }
+  const realRoot = fs.realpathSync(root);
+  const realTarget = fs.realpathSync(target);
+  if (!isInside(realRoot, realTarget) || realTarget !== path.join(realRoot, reference)) {
+    failures.push(finding("evidence_artifact_redirect", evidenceFile, `${pass.id} artifact resolves through a redirect`));
+    return undefined;
+  }
+  return fs.readFileSync(realTarget);
+}
+
+function parseVisualMetadata(pass, artifactRoot, scenario, profileId, actual, visualEnvironments, evidenceFile, failures, schemas, session) {
+  const reference = pass.artifact.path.replace(/\.png$/, ".visual.json");
+  const bytes = readArtifact({ artifact: { path: reference }, id: `${pass.id}-metadata` }, artifactRoot, evidenceFile, failures);
+  if (!bytes) return undefined;
+  let document;
+  try {
+    document = parseStrictJson(bytes.toString("utf8"));
+  } catch (error) {
+    failures.push(finding("evidence_visual_json_invalid", evidenceFile, `${pass.id} visual metadata is not structured JSON: ${error instanceof Error ? error.message : String(error)}`));
+    return undefined;
+  }
+  if (!schemas.visual(document)) {
+    for (const error of schemas.visual.errors ?? []) failures.push(finding("evidence_visual_schema_invalid", evidenceFile, `${pass.id} ${error.instancePath || "/"} ${error.message}`));
+    return undefined;
+  }
+  if (!sameJson(document.capture_session, pass.session)) failures.push(finding("capture_session_mismatch", evidenceFile, `${pass.id} visual metadata session differs from its pass`));
+  if (document.captured_at !== pass.recorded_at) failures.push(finding("evidence_recorded_at_mismatch", evidenceFile, `${pass.id} recorded_at is not derived from visual metadata`));
+  if (session && !withinSession(document.captured_at, session.started_at, session.completed_at)) failures.push(finding("capture_session_time_outside", evidenceFile, `${pass.id} visual metadata was not captured within its session`));
+  validateVisual(document, pass, scenario, profileId, actual, visualEnvironments, evidenceFile, failures);
+  return document;
+}
+
+export function validateEvidenceArtifacts({ artifactRoot, evidence, evidenceFile, fixture, profileId, schemas, session, states }) {
+  const failures = [];
+  const scenarios = new Map(states.scenarios.map((scenario) => [scenario.id, scenario]));
+  const fixtures = new Map(fixture.scenarios.map((scenario) => [scenario.id, scenario]));
+  const capturedTimes = new Map();
+  for (const pass of evidence.passes ?? []) {
+    const scenario = scenarios.get(pass.scenario_id);
+    const runtimeFixture = fixtures.get(pass.scenario_id);
+    if (!scenario || !runtimeFixture || !pass.artifact?.media_type) continue;
+    const bytes = readArtifact(pass, artifactRoot, evidenceFile, failures);
+    if (!bytes) continue;
+    const actual = validateIntegrity(pass, bytes, evidenceFile, failures);
+    if (pass.artifact.media_type === "application/json") {
+      const document = parseArtifactJson(bytes, pass, scenario, runtimeFixture, profileId, evidenceFile, failures, schemas, session);
+      if (document?.captured_at) {
+        if (!capturedTimes.has(pass.scenario_id)) capturedTimes.set(pass.scenario_id, new Set());
+        capturedTimes.get(pass.scenario_id).add(document.captured_at);
+      }
+    } else if (pass.channel === "visual") {
+      const document = parseVisualMetadata(pass, artifactRoot, scenario, profileId, actual, states.visual_environments, evidenceFile, failures, schemas, session);
+      if (document?.captured_at) {
+        if (!capturedTimes.has(pass.scenario_id)) capturedTimes.set(pass.scenario_id, new Set());
+        capturedTimes.get(pass.scenario_id).add(document.captured_at);
+      }
+    }
+  }
+  for (const [scenarioId, times] of capturedTimes) {
+    if (times.size !== 1) failures.push(finding("capture_session_time_mismatch", evidenceFile, `${scenarioId} visual, DOM, and AX captured_at values differ`));
+    const capturedAt = [...times][0];
+    for (const pass of evidence.passes.filter((entry) => entry.scenario_id === scenarioId)) if (pass.recorded_at !== capturedAt) failures.push(finding("evidence_recorded_at_mismatch", evidenceFile, `${pass.id} recorded_at is not derived from its scenario artifacts`));
+  }
+  return failures;
+}