stylegallery 0.1.0 → 0.1.2

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

@@ -1,139 +0,0 @@
-#!/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

@@ -1,40 +0,0 @@
-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

@@ -1,141 +0,0 @@
-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

@@ -1,191 +0,0 @@
-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;
-}