stylegallery 0.1.0

package/scripts/build-reference-artifacts.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import StyleDictionary from "style-dictionary";
+import { adapter, createStyleDictionaryConfig } from "../consumer-reference/adapters/style-dictionary.config.mjs";
+import { inspectArtifactPath } from "./reference-artifact-path-contract.mjs";
+import { validatePortableTokens } from "./reference-token-contract.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+
+const root = process.cwd();
+const defaults = {
+  adapter: "style-dictionary",
+  manifest: "consumer-reference/generated/manifest.json",
+  output: "consumer-reference/generated/tokens.css",
+  source: "consumer-reference/fixtures/token-portability/valid-reference.json",
+};
+
+function parseArguments() {
+  const options = { ...defaults, failOnWarning: false, json: false };
+  for (let index = 2; index < process.argv.length; index += 1) {
+    const argument = process.argv[index];
+    if (argument === "--json") options.json = true;
+    else if (argument === "--fail-on-warning") options.failOnWarning = true;
+    else if (["--adapter", "--manifest", "--output", "--source"].includes(argument)) {
+      const value = process.argv[index + 1];
+      if (!value) return { failure: { code: "argument_value_required", message: `${argument} requires a value`, path: "<cli>" }, options };
+      options[argument.slice(2)] = value;
+      index += 1;
+    } else return { failure: { code: "argument_unknown", message: `unsupported argument ${argument}`, path: "<cli>" }, options };
+  }
+  return { options };
+}
+
+function hash(content) {
+  return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
+}
+
+function declarations(css) {
+  return [...css.matchAll(/^\s*(--[a-z0-9-]+):\s*([^;]+);\s*$/gm)].map((match) => ({ name: match[1], value: match[2].trim() }));
+}
+
+function emit(report, json) {
+  const text = json ? JSON.stringify(report, null, 2) : report.ok ? `ok: ${report.outputCount} token declarations` : report.failures.map((item) => `${item.code}: ${item.message}`).join("\n");
+  (json || report.ok ? console.log : console.error)(text);
+}
+
+const parsed = parseArguments();
+const options = parsed.options;
+const source = path.resolve(root, options.source);
+const output = path.resolve(root, options.output);
+const manifestPath = path.resolve(root, options.manifest);
+const failures = parsed.failure ? [parsed.failure] : [];
+const warnings = [];
+if (!parsed.failure) {
+  for (const [code, target] of [
+    ["token_source_untrusted", source],
+    ["artifact_output_untrusted", output],
+    ["artifact_manifest_untrusted", manifestPath],
+  ]) {
+    const inspection = inspectArtifactPath(root, target, code !== "token_source_untrusted");
+    if (!inspection.ok) failures.push({ code, message: `${target} must be a contained regular non-symlink file`, path: path.relative(root, target) || "." });
+  }
+}
+let sourceBytes;
+let document;
+if (failures.length === 0) {
+  try {
+    sourceBytes = fs.readFileSync(source);
+    document = parseStrictJson(sourceBytes.toString("utf8"));
+  } catch (error) {
+    const code = error instanceof SyntaxError ? "token_json_invalid" : "token_source_unresolved";
+    failures.push({ code, message: error instanceof Error ? error.message : String(error), path: options.source });
+  }
+}
+let contract = { failures: [], tokens: [] };
+if (document !== undefined) {
+  contract = validatePortableTokens(document);
+  failures.push(...contract.failures);
+}
+if (options.adapter !== adapter.name) failures.push({ code: "adapter_unsupported", message: `adapter must be ${adapter.name}`, path: "<cli>" });
+if (failures.length === 0) {
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  const dictionary = new StyleDictionary(createStyleDictionaryConfig(source, output), { verbosity: "silent", warnings: options.failOnWarning ? "error" : "warn" });
+  try {
+    await dictionary.buildAllPlatforms();
+  } catch (error) {
+    failures.push({ code: "adapter_build_failed", message: error instanceof Error ? error.message : String(error), path: options.source });
+  }
+}
+let css = "";
+if (failures.length === 0 && !fs.existsSync(output)) failures.push({ code: "artifact_output_missing", message: "adapter produced no CSS output", path: options.output });
+if (failures.length === 0) {
+  css = fs.readFileSync(output, "utf8");
+  const emitted = declarations(css);
+  const expected = contract.tokens.map((token) => `--${token.path.replaceAll(".", "-")}`);
+  const names = emitted.map((item) => item.name);
+  if (emitted.length === 0) failures.push({ code: "artifact_zero_count", message: "adapter produced zero declarations", path: options.output });
+  if (new Set(names).size !== names.length) failures.push({ code: "artifact_declaration_duplicate", message: "adapter produced a duplicate declaration", path: options.output });
+  for (const name of expected.filter((name) => !names.includes(name))) failures.push({ code: "artifact_declaration_missing", message: `adapter omitted ${name}`, path: options.output });
+  if (css.includes("[object Object]")) failures.push({ code: "artifact_object_sentinel", message: "adapter emitted [object Object]", path: options.output });
+  if (/\{[a-z0-9.-]+\}|\b(?:null|undefined)\b/.test(css)) failures.push({ code: "artifact_unresolved_value", message: "adapter emitted an unresolved value", path: options.output });
+  if (contract.tokens.length !== emitted.length) failures.push({ code: "artifact_count_mismatch", message: "source and output token counts differ", path: options.output });
+  if (warnings.length > 0 && options.failOnWarning) failures.push({ code: "adapter_warning", message: "adapter emitted a warning", path: options.output });
+  if (failures.length === 0) {
+    const manifest = {
+      adapter,
+      declarations: emitted,
+      inputHash: hash(sourceBytes),
+      outputCount: emitted.length,
+      outputFile: path.relative(path.dirname(manifestPath), output).replaceAll(path.sep, "/"),
+      outputHash: hash(css),
+      schemaVersion: "1.0",
+      sourceCount: contract.tokens.length,
+      sourceFile: path.relative(path.dirname(manifestPath), source).replaceAll(path.sep, "/"),
+      warnings,
+    };
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+}
+const report = parsed.failure
+  ? { failures: [parsed.failure], ok: false, warnings }
+  : { adapter, failures, manifest: options.manifest, ok: failures.length === 0, output: options.output, outputCount: failures.length === 0 ? contract.tokens.length : 0, warnings };
+emit(report, options.json);
+process.exitCode = report.ok ? 0 : 1;

package/scripts/calibration-raw-contract.mjs

@@ -0,0 +1,172 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { BASELINE_ENVIRONMENT, BASELINE_METADATA_SHA256, BASELINE_REFERENCE, finding, sha256 } from "./baseline-contract.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+
+const EXPECTED_TEST = "canonical consumer reference preserves computed layout before its locator screenshot";
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+const REQUIRED_FILES = new Set(["actual.png", "ax.txt", "comparison.json", "dom.html", "exit.json", "metadata.json", "playwright.json"]);
+const ALLOWED_FILES = new Set([...REQUIRED_FILES, "playwright.stderr"]);
+const FILE_LIMITS = new Map([
+  ["actual.png", 5 * 1024 * 1024], ["ax.txt", 1024 * 1024], ["comparison.json", 1024 * 1024],
+  ["dom.html", 1024 * 1024], ["exit.json", 1024 * 1024], ["metadata.json", 1024 * 1024],
+  ["playwright.json", 10 * 1024 * 1024], ["playwright.stderr", 1024 * 1024],
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function readJson(file, code, failures) {
+  if (!fs.existsSync(file)) {
+    failures.push(finding(code, file, "required raw calibration JSON is missing"));
+    return undefined;
+  }
+  try {
+    const stat = fs.lstatSync(file);
+    const limit = FILE_LIMITS.get(path.basename(file)) ?? 1024 * 1024;
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > limit) throw new Error(`JSON evidence must be a regular file no larger than ${limit} bytes`);
+    return parseStrictJson(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    failures.push(finding(`${code}_invalid`, file, error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+}
+
+function rejectUnknown(value, allowed, code, file, failures) {
+  if (!isRecord(value)) return;
+  for (const key of Object.keys(value).filter((key) => !allowed.has(key))) {
+    failures.push(finding(code, file, `unsupported property ${key}`));
+  }
+}
+
+function validateExit(exit, expectedRun, file, failures) {
+  if (!isRecord(exit)) {
+    failures.push(finding("calibration_exit_invalid", file, "exit record must be an object"));
+    return false;
+  }
+  rejectUnknown(exit, new Set(["exit_code", "run", "schema_version"]), "calibration_exit_property_unknown", file, failures);
+  if (exit.schema_version !== "1.0" || exit.run !== expectedRun || exit.exit_code !== 0) {
+    failures.push(finding("calibration_exit_unsuccessful", file, "exit record must identify this run with exit code zero"));
+    return false;
+  }
+  return true;
+}
+
+function validatePlaywright(report, file, failures) {
+  if (!isRecord(report)) {
+    failures.push(finding("calibration_playwright_result_invalid", file, "Playwright result must be an object"));
+    return false;
+  }
+  const project = report.config?.projects?.[0];
+  const suite = report.suites?.[0];
+  const spec = suite?.specs?.[0];
+  const test = spec?.tests?.[0];
+  const result = test?.results?.[0];
+  const identityMatches = report.config?.version === "1.61.0"
+    && report.config?.workers === 1
+    && report.config?.projects?.length === 1
+    && project?.id === "chromium"
+    && project?.name === "chromium"
+    && report.suites?.length === 1
+    && suite?.file === "consumer-reference-sentinels.spec.mjs"
+    && suite?.specs?.length === 1
+    && spec?.title === EXPECTED_TEST
+    && spec?.tests?.length === 1
+    && test?.projectId === "chromium"
+    && test?.projectName === "chromium";
+  if (!identityMatches) failures.push(finding("calibration_playwright_identity", file, "result must contain exactly the canonical Chromium sentinel test"));
+  const completionMatches = spec?.ok === true
+    && test?.expectedStatus === "passed"
+    && test?.status === "expected"
+    && test?.results?.length === 1
+    && result?.status === "passed"
+    && Array.isArray(result?.errors)
+    && result.errors.length === 0
+    && Array.isArray(report.errors)
+    && report.errors.length === 0
+    && report.stats?.expected === 1
+    && report.stats?.skipped === 0
+    && report.stats?.unexpected === 0
+    && report.stats?.flaky === 0;
+  if (!completionMatches) failures.push(finding("calibration_playwright_incomplete", file, "canonical test must pass once with no skipped, flaky, interrupted, or unexpected result"));
+  return identityMatches && completionMatches;
+}
+
+function validateMetadata(metadata, expectedRun, file, failures) {
+  if (!isRecord(metadata)) {
+    failures.push(finding("calibration_metadata_invalid", file, "metadata must be an object"));
+    return false;
+  }
+  const allowed = new Set(["architecture", "ax_sha256", "dom_sha256", "environment", "metadata_sha256", "png_sha256", "reference", "run", "schema_version"]);
+  rejectUnknown(metadata, allowed, "calibration_metadata_property_unknown", file, failures);
+  const hashesValid = [metadata.ax_sha256, metadata.dom_sha256, metadata.metadata_sha256, metadata.png_sha256].every((value) => typeof value === "string" && HASH_PATTERN.test(value));
+  const valid = metadata.schema_version === "1.0"
+    && metadata.run === expectedRun
+    && metadata.architecture === "amd64"
+    && hashesValid
+    && metadata.metadata_sha256 === BASELINE_METADATA_SHA256
+    && isDeepStrictEqual(metadata.environment, BASELINE_ENVIRONMENT)
+    && isDeepStrictEqual(metadata.reference, BASELINE_REFERENCE);
+  if (!valid) failures.push(finding("calibration_metadata_mismatch", file, "metadata shape, identity, hashes, environment, and reference must be canonical"));
+  return valid;
+}
+
+function validateComparison(comparison, expectedRun, actualHash, file, failures) {
+  if (!isRecord(comparison)) {
+    failures.push(finding("calibration_comparison_invalid", file, "comparison proof must be an object"));
+    return false;
+  }
+  const allowed = new Set(["actual_sha256", "assertion", "diff_pixels", "expected_sha256", "max_diff_pixels", "run", "schema_version", "status", "threshold"]);
+  rejectUnknown(comparison, allowed, "calibration_comparison_property_unknown", file, failures);
+  const valid = comparison.schema_version === "1.0"
+    && comparison.run === expectedRun
+    && comparison.assertion === "visual_geometry_matches_proposed_baseline"
+    && comparison.status === "passed"
+    && comparison.threshold === 0
+    && comparison.max_diff_pixels === 0
+    && comparison.diff_pixels === 0
+    && comparison.actual_sha256 === actualHash
+    && comparison.expected_sha256 === BASELINE_REFERENCE.baseline.sha256
+    && comparison.actual_sha256 === comparison.expected_sha256;
+  if (!valid) failures.push(finding("calibration_comparison_mismatch", file, "comparison must prove the exact zero-diff baseline assertion"));
+  return valid;
+}
+
+export function parseCalibrationRun(root, expectedRun, failures) {
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !ALLOWED_FILES.has(entry.name)) failures.push(finding("calibration_raw_file_unknown", path.join(root, entry.name), "run directory contains unsupported or duplicate evidence"));
+    else if (fs.lstatSync(path.join(root, entry.name)).size > FILE_LIMITS.get(entry.name)) failures.push(finding("calibration_raw_file_oversized", path.join(root, entry.name), `${entry.name} exceeds its calibration evidence byte limit`));
+  }
+  for (const name of REQUIRED_FILES) if (!entries.some((entry) => entry.isFile() && entry.name === name)) failures.push(finding("calibration_raw_file_missing", path.join(root, name), `${name} is required exactly once`));
+  const metadata = readJson(path.join(root, "metadata.json"), "calibration_metadata_missing", failures);
+  const exit = readJson(path.join(root, "exit.json"), "calibration_exit_missing", failures);
+  const report = readJson(path.join(root, "playwright.json"), "calibration_playwright_missing", failures);
+  const comparison = readJson(path.join(root, "comparison.json"), "calibration_comparison_missing", failures);
+  const metadataValid = validateMetadata(metadata, expectedRun, path.join(root, "metadata.json"), failures);
+  const exitValid = validateExit(exit, expectedRun, path.join(root, "exit.json"), failures);
+  const reportValid = validatePlaywright(report, path.join(root, "playwright.json"), failures);
+  const artifactFields = [["actual.png", "png_sha256"], ["dom.html", "dom_sha256"], ["ax.txt", "ax_sha256"]];
+  let artifactsValid = metadataValid;
+  for (const [name, field] of artifactFields) {
+    const file = path.join(root, name);
+    if (!fs.existsSync(file) || fs.lstatSync(file).isSymbolicLink() || !fs.lstatSync(file).isFile() || fs.lstatSync(file).size > FILE_LIMITS.get(name) || !metadata || sha256(fs.readFileSync(file)) !== metadata[field]) {
+      failures.push(finding("calibration_artifact_hash_mismatch", file, `${field} differs from raw artifact bytes`));
+      artifactsValid = false;
+    }
+  }
+  const comparisonValid = validateComparison(comparison, expectedRun, metadata?.png_sha256, path.join(root, "comparison.json"), failures);
+  if (!(metadataValid && exitValid && reportValid && artifactsValid && comparisonValid)) return undefined;
+  return {
+    architecture: metadata.architecture,
+    ax_sha256: metadata.ax_sha256,
+    completed: true,
+    dom_sha256: metadata.dom_sha256,
+    metadata_sha256: metadata.metadata_sha256,
+    png_sha256: metadata.png_sha256,
+    run: expectedRun,
+    screenshot_diff_pixels: comparison.diff_pixels,
+  };
+}

package/scripts/capture-session-contract.mjs

@@ -0,0 +1,187 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { resolveProfileRecords } from "./profile-record-contract.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+
+const captureSourcePaths = Object.freeze([
+  "package-lock.json",
+  "package.json",
+  "playwright.config.mjs",
+  "consumer-reference/schema/ax-evidence.schema.json",
+  "consumer-reference/schema/capture-session.schema.json",
+  "consumer-reference/schema/component-state.schema.json",
+  "consumer-reference/schema/dom-evidence.schema.json",
+  "consumer-reference/schema/evidence-record.schema.json",
+  "consumer-reference/schema/fixture-manifest.schema.json",
+  "consumer-reference/schema/runtime-evidence-manifest.schema.json",
+  "consumer-reference/schema/visual-evidence.schema.json",
+  "scripts/artifact-metadata.mjs",
+  "scripts/capture-session-contract.mjs",
+  "scripts/component-state-contract.mjs",
+  "scripts/component-state-semantics.mjs",
+  "scripts/create-component-state-session.mjs",
+  "scripts/profile-record-contract.mjs",
+  "scripts/strict-json.mjs",
+  "scripts/visual-expectation-contract.mjs",
+  "tests/component-state-evidence.spec.mjs",
+  "tests/helpers/render-component-state.mjs",
+]);
+
+function finding(code, file, message) {
+  return { code, message, path: file };
+}
+
+export function sha256(bytes) {
+  return `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+export function repositoryGitArgs(repositoryRoot, ...args) {
+  return ["-c", `safe.directory=${repositoryRoot}`, ...args];
+}
+
+function compare(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function profileSourceFiles(profileRoot) {
+  if (!fs.existsSync(profileRoot)) return [];
+  const sources = [];
+  const profiles = fs.readdirSync(profileRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(profileRoot, entry.name, "profile.json")))
+    .sort((left, right) => compare(left.name, right.name));
+  for (const profile of profiles) {
+    const profileFile = path.join(profileRoot, profile.name, "profile.json");
+    const record = parseStrictJson(fs.readFileSync(profileFile, "utf8"));
+    const references = [
+      "profile.json",
+      record.local_foundations,
+      record.tokens,
+      ...(record.component_records ?? []),
+      ...(record.fixture_records ?? []),
+      ...(record.state_records ?? []),
+    ];
+    for (const reference of references) {
+      if (typeof reference !== "string") continue;
+      if (path.posix.isAbsolute(reference) || path.win32.isAbsolute(reference) || reference.includes("\\") || path.posix.normalize(reference) !== reference || reference.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`unsafe profile source reference ${profile.name}/${reference}`);
+      }
+      sources.push({
+        file: path.join(profileRoot, profile.name, reference),
+        logicalPath: `profiles/${profile.name}/${reference.split(path.sep).join("/")}`,
+      });
+    }
+  }
+  return sources;
+}
+
+export function relevantSourceFiles(repositoryRoot, profileRoot) {
+  return [
+    ...captureSourcePaths.map((reference) => ({ file: path.join(repositoryRoot, reference), logicalPath: reference })),
+    ...profileSourceFiles(profileRoot),
+  ].sort((left, right) => compare(left.logicalPath, right.logicalPath));
+}
+
+export function canonicalSourceManifest(repositoryRoot, profileRoot) {
+  const files = relevantSourceFiles(repositoryRoot, profileRoot).map(({ file, logicalPath }) => {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`capture source must be a regular non-symlink file: ${logicalPath}`);
+    const bytes = fs.readFileSync(file);
+    return { byte_length: bytes.length, path: logicalPath, sha256: sha256(bytes) };
+  });
+  return { files, sha256: sha256(Buffer.from(JSON.stringify(files))) };
+}
+
+export function sourceManifestMatches(source, repositoryRoot, profileRoot) {
+  try {
+    return sameJson(source, canonicalSourceManifest(repositoryRoot, profileRoot));
+  } catch {
+    return false;
+  }
+}
+
+export function dirtyRelevantSources(repositoryRoot, profileRoot) {
+  const repositoryPrefix = `${path.resolve(repositoryRoot)}${path.sep}`;
+  const tracked = relevantSourceFiles(repositoryRoot, profileRoot)
+    .map(({ file }) => path.resolve(file))
+    .filter((file) => file.startsWith(repositoryPrefix))
+    .map((file) => path.relative(repositoryRoot, file));
+  if (tracked.length === 0) return [];
+  const output = execFileSync("git", repositoryGitArgs(repositoryRoot, "status", "--porcelain=v1", "--untracked-files=all", "--", ...tracked), { cwd: repositoryRoot, encoding: "utf8" });
+  return output.split("\n").filter(Boolean).sort(compare);
+}
+
+export function sessionLink(receipt, receiptSha256) {
+  return {
+    attempt: receipt.attempt,
+    branch: receipt.branch,
+    environment: receipt.environment,
+    nonce: receipt.nonce,
+    receipt_sha256: receiptSha256,
+    revision: receipt.revision,
+    session_id: receipt.session_id,
+    source: receipt.source,
+    started_at: receipt.started_at,
+  };
+}
+
+export function readCaptureSession(file, validate, failures) {
+  if (!fs.existsSync(file)) {
+    failures.push(finding("capture_session_missing", file, "capture session receipt is missing"));
+    return undefined;
+  }
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    failures.push(finding("capture_session_type_invalid", file, "capture session receipt must be a regular non-symlink file"));
+    return undefined;
+  }
+  const bytes = fs.readFileSync(file);
+  let receipt;
+  try {
+    receipt = parseStrictJson(bytes.toString("utf8"));
+  } catch (error) {
+    failures.push(finding("capture_session_json_invalid", file, error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+  if (!validate(receipt)) {
+    for (const error of validate.errors ?? []) failures.push(finding("capture_session_schema_invalid", file, `${error.instancePath || "/"} ${error.message}`));
+  }
+  const digest = sha256(bytes);
+  return {
+    artifact: { byte_length: bytes.length, media_type: "application/json", path: "capture-session.json", sha256: digest },
+    bytes,
+    digest,
+    link: sessionLink(receipt, digest),
+    receipt,
+  };
+}
+
+export function canonicalIntended(profileRoot, failures) {
+  if (!fs.existsSync(profileRoot)) return [];
+  const intended = [];
+  for (const entry of fs.readdirSync(profileRoot, { withFileTypes: true }).filter((item) => item.isDirectory()).sort((left, right) => compare(left.name, right.name))) {
+    const root = path.join(profileRoot, entry.name);
+    if (!fs.existsSync(path.join(root, "profile.json"))) continue;
+    const resolved = resolveProfileRecords(root, failures);
+    const fixture = resolved?.records.fixture[0]?.value;
+    if (!resolved || !fixture) continue;
+    intended.push({
+      profile_id: resolved.profile.id,
+      profile_name: entry.name,
+      scenarios: fixture.scenarios.map((scenario) => ({ channels: [...scenario.required_channels].sort(compare), id: scenario.id })).sort((left, right) => compare(left.id, right.id)),
+    });
+  }
+  return intended;
+}
+
+export function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function withinSession(capturedAt, startedAt, completedAt) {
+  const captured = Date.parse(capturedAt);
+  const started = Date.parse(startedAt);
+  const completed = Date.parse(completedAt);
+  return Number.isFinite(captured) && Number.isFinite(started) && Number.isFinite(completed) && captured >= started && captured <= completed;
+}

package/scripts/component-state-artifact-fixture.mjs

@@ -0,0 +1,44 @@
+import zlib from "node:zlib";
+
+function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type, data) {
+  const name = Buffer.from(type, "ascii");
+  const output = Buffer.alloc(12 + data.length);
+  output.writeUInt32BE(data.length, 0);
+  name.copy(output, 4);
+  data.copy(output, 8);
+  output.writeUInt32BE(crc32(Buffer.concat([name, data])), 8 + data.length);
+  return output;
+}
+
+export function makePng(red) {
+  const width = 64;
+  const height = 64;
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 6;
+  const row = Buffer.alloc(1 + (width * 4));
+  for (let pixel = 0; pixel < width; pixel += 1) row.set([red, 64, 128, 255], 1 + (pixel * 4));
+  return Buffer.concat([
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    pngChunk("IHDR", header),
+    pngChunk("IDAT", zlib.deflateSync(Buffer.concat(Array.from({ length: height }, () => row)))),
+    pngChunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+const canonicalPng = makePng(32);
+
+export function syntheticImage(profile, scenario) {
+  return Buffer.concat([canonicalPng, Buffer.from(`${profile}:${scenario}`)]);
+}

package/scripts/component-state-contract.mjs

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import Ajv2020 from "ajv/dist/2020.js";
+import {
+  validateComponentSemantics,
+  validateEvidenceSemantics,
+  validateFixtureSemantics,
+  validateStateSemantics,
+} from "./component-state-semantics.mjs";
+import { validateEvidenceArtifacts as validateArtifactSet } from "./evidence-artifact-contract.mjs";
+import { resolveProfileRecords } from "./profile-record-contract.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+
+function finding(code, file, message) {
+  return { code, message, path: file };
+}
+
+export function readRecord(file, failures) {
+  try {
+    return parseStrictJson(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    failures.push(finding(error instanceof SyntaxError ? "record_invalid_json" : "record_unreadable", file, error.message));
+    return undefined;
+  }
+}
+
+function readSchema(schemaRoot, name) {
+  const file = path.join(schemaRoot, name);
+  try {
+    return parseStrictJson(fs.readFileSync(file, "utf8"));
+  } catch (cause) {
+    const error = new Error(`component schema is not strict JSON: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    error.code = "component_schema_json_invalid";
+    error.path = file;
+    throw error;
+  }
+}
+
+export function compileSchemas(schemaRoot) {
+  const ajv = new Ajv2020({ allErrors: true, formats: { "date-time": true }, strict: false });
+  const captureSchema = readSchema(schemaRoot, "capture-session.schema.json");
+  ajv.addSchema(captureSchema);
+  const evidenceSchema = readSchema(schemaRoot, "evidence-record.schema.json");
+  const validateEvidence = ajv.compile(evidenceSchema);
+  return {
+    ax: ajv.compile(readSchema(schemaRoot, "ax-evidence.schema.json")),
+    capture: ajv.getSchema(captureSchema.$id),
+    component: ajv.compile(readSchema(schemaRoot, "component-state.schema.json")),
+    dom: ajv.compile(readSchema(schemaRoot, "dom-evidence.schema.json")),
+    evidence: validateEvidence,
+    fixture: ajv.compile(readSchema(schemaRoot, "fixture-manifest.schema.json")),
+    item: ajv.compile(readSchema(schemaRoot, "item.schema.json")),
+    runtime: ajv.compile(readSchema(schemaRoot, "runtime-evidence-manifest.schema.json")),
+    visual: ajv.compile(readSchema(schemaRoot, "visual-evidence.schema.json")),
+  };
+}
+
+function addSchemaFailures(validate, value, file, code, failures) {
+  if (validate(value)) return;
+  for (const error of validate.errors ?? []) failures.push(finding(code, file, `${error.instancePath || "/"} ${error.message}`));
+}
+
+export function validateProfile(profileRoot, schemas) {
+  const failures = [];
+  const resolved = resolveProfileRecords(profileRoot, failures);
+  if (!resolved) return failures;
+  addSchemaFailures(schemas.item, resolved.profile, resolved.profileFile, "profile_schema_invalid", failures);
+  const files = Object.fromEntries(["component", "evidence", "fixture", "states"].map((kind) => [kind, resolved.records[kind][0]?.path ?? resolved.profileFile]));
+  const records = Object.fromEntries(["component", "evidence", "fixture", "states"].map((kind) => [kind, resolved.records[kind][0]?.value]));
+  if (records.component) addSchemaFailures(schemas.component, records.component, files.component, "component_schema_invalid", failures);
+  if (records.states) addSchemaFailures(schemas.component, records.states, files.states, "state_schema_invalid", failures);
+  if (records.fixture) addSchemaFailures(schemas.fixture, records.fixture, files.fixture, "fixture_schema_invalid", failures);
+  if (records.evidence) {
+    addSchemaFailures(schemas.evidence, records.evidence, files.evidence, "evidence_schema_invalid", failures);
+  }
+  if (records.component) validateComponentSemantics(records.component, files.component, failures);
+  if (records.states && records.component) validateStateSemantics(records.states, records.component, files.states, failures);
+  if (records.fixture && records.states && records.component) validateFixtureSemantics(records.fixture, records.states, records.component, files.fixture, failures);
+  if (records.fixture && records.states && records.evidence) validateEvidenceSemantics(records.evidence, records.fixture, records.states, files.evidence, failures);
+  return failures;
+}
+
+export function validateEvidenceArtifacts(profileRoot, artifactRoot, evidenceOverride, schemas, session) {
+  const failures = [];
+  const resolved = resolveProfileRecords(profileRoot, failures);
+  const evidenceRecord = resolved?.records.evidence[0];
+  const file = evidenceRecord?.path ?? resolved?.profileFile ?? path.join(profileRoot, "profile.json");
+  const evidence = evidenceOverride ?? evidenceRecord?.value;
+  const fixture = resolved?.records.fixture[0]?.value;
+  const states = resolved?.records.states[0]?.value;
+  if (evidence && fixture && states) {
+    if (evidenceOverride) {
+      addSchemaFailures(schemas.evidence, evidence, file, "evidence_schema_invalid", failures);
+      validateEvidenceSemantics(evidence, fixture, states, file, failures);
+    }
+    failures.push(...validateArtifactSet({ artifactRoot, evidence, evidenceFile: file, fixture, profileId: resolved.profile.id, schemas, session, states }));
+  }
+  return failures;
+}