stylegallery 0.1.0

package/scripts/audit-evidence-freshness.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import { addDateTimeFormat, isRfc3339DateTime } from "./json-schema-formats.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+import { validateCalibration } from "./baseline-contract.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const calibrationSchemaPath = path.join(repositoryRoot, "consumer-reference", "schema", "calibration-record.schema.json");
+const defaultPageSchemaPath = path.join(repositoryRoot, "consumer-reference", "schema", "page-evidence-manifest.schema.json");
+const PAGE_RECORD_KIND = "page_evidence_manifest";
+// This is an advisory warning window only. It never changes an explicit expiry or adds a TTL.
+const DEFAULT_EXPIRING_WINDOW_DAYS = 7;
+
+function failure(code, sourcePath, message, details = undefined) {
+  return details === undefined ? { code, message, path: sourcePath } : { code, message, path: sourcePath, details };
+}
+
+function warning(code, sourcePath, status, thresholdDate, asOf, message) {
+  return { asOf, code, message, source_path: sourcePath, status, threshold_date: thresholdDate };
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseDateTime(value) {
+  return isRfc3339DateTime(value) ? Date.parse(value) : NaN;
+}
+
+function isInside(base, target) {
+  const relative = path.relative(path.resolve(base), path.resolve(target));
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function displayPath(file, root) {
+  const absolute = path.resolve(file);
+  if (isInside(root, absolute)) return path.relative(root, absolute).split(path.sep).join("/") || ".";
+  return absolute;
+}
+
+function readRecord(file, root, failures) {
+  const sourcePath = displayPath(file, root);
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    failures.push(failure("freshness_record_unreadable", sourcePath, `record cannot be read: ${error instanceof Error ? error.message : String(error)}`));
+    return undefined;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    failures.push(failure("freshness_record_unreadable", sourcePath, "record must be a regular non-symlink file"));
+    return undefined;
+  }
+  if (stat.size > 1024 * 1024) {
+    failures.push(failure("freshness_record_unreadable", sourcePath, "record must not exceed 1 MiB"));
+    return undefined;
+  }
+  try {
+    return { sourcePath, value: parseStrictJson(fs.readFileSync(file, "utf8")) };
+  } catch (error) {
+    failures.push(failure("freshness_record_invalid", sourcePath, error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+}
+
+function readSchema(schemaPath, sourcePath, failures) {
+  let stat;
+  try {
+    stat = fs.lstatSync(schemaPath);
+  } catch (error) {
+    failures.push(failure("freshness_schema_missing", sourcePath, `schema cannot be read: ${error instanceof Error ? error.message : String(error)}`));
+    return undefined;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    failures.push(failure("freshness_schema_invalid", sourcePath, "schema must be a regular non-symlink file"));
+    return undefined;
+  }
+  try {
+    return parseStrictJson(fs.readFileSync(schemaPath, "utf8"));
+  } catch (error) {
+    failures.push(failure("freshness_schema_invalid", sourcePath, error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+}
+
+function compileSchema(schema, schemaPath, sourcePath, failures, { strict = true } = {}) {
+  if (!isRecord(schema)) {
+    failures.push(failure("freshness_schema_invalid", sourcePath, "schema must be a JSON object"));
+    return undefined;
+  }
+  try {
+    const ajv = new Ajv2020({ allErrors: true, strict });
+    addDateTimeFormat(ajv);
+    const schemaDirectory = path.dirname(defaultPageSchemaPath);
+    if (path.resolve(schemaPath) === path.resolve(defaultPageSchemaPath) && fs.existsSync(schemaDirectory)) {
+      for (const entry of fs.readdirSync(schemaDirectory, { withFileTypes: true }).filter((item) => item.isFile() && item.name.endsWith(".schema.json"))) {
+        const dependencyPath = path.join(schemaDirectory, entry.name);
+        if (path.resolve(dependencyPath) === path.resolve(schemaPath)) continue;
+        try {
+          const dependency = parseStrictJson(fs.readFileSync(dependencyPath, "utf8"));
+          if (dependency?.$id) ajv.addSchema(dependency, dependency.$id);
+        } catch {
+          // Only schemas reachable from the selected page schema affect this compile.
+        }
+      }
+    }
+    if (schema.$id) ajv.addSchema(schema, schema.$id);
+    else ajv.addSchema(schema, schemaPath);
+    return ajv.getSchema(schema.$id ?? schemaPath) ?? ajv.compile(schema);
+  } catch (error) {
+    failures.push(failure("freshness_schema_invalid", sourcePath, error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+}
+
+function schemaFailures(validate, value, sourcePath) {
+  if (validate(value)) return [];
+  return (validate.errors ?? []).map((error) => failure(
+    "freshness_record_invalid",
+    sourcePath,
+    `${error.instancePath || "/"} ${error.message}`,
+  ));
+}
+
+function validateCalibrationRecord(value, sourcePath, failures) {
+  const schema = readSchema(calibrationSchemaPath, sourcePath, failures);
+  const validate = schema === undefined ? undefined : compileSchema(schema, calibrationSchemaPath, sourcePath, failures, { strict: false });
+  if (validate) failures.push(...schemaFailures(validate, value, sourcePath));
+  for (const finding of validateCalibration(value, sourcePath)) {
+    failures.push(failure("freshness_record_invalid", sourcePath, finding.message, { code: finding.code }));
+  }
+  if (!isRecord(value)) return undefined;
+  const external = value.committed_ci?.external_verification;
+  if (external === null || external === undefined) return { thresholdDate: null, verifiedAt: null };
+  if (!isRecord(external) || !isRecord(external.artifact)) {
+    failures.push(failure("freshness_record_invalid", sourcePath, "calibration external verification must contain artifact metadata"));
+    return undefined;
+  }
+  const thresholdDate = external.artifact.expires_at;
+  const verifiedAt = external.verified_at;
+  if (!Number.isFinite(parseDateTime(thresholdDate)) || !Number.isFinite(parseDateTime(verifiedAt))) {
+    failures.push(failure("freshness_record_invalid", sourcePath, "calibration expiry and verification dates must be RFC 3339 date-time values"));
+    return undefined;
+  }
+  return { thresholdDate, verifiedAt };
+}
+
+function validatePageRecord(value, sourcePath, pageSchemaPath, failures) {
+  const schema = readSchema(pageSchemaPath, sourcePath, failures);
+  if (schema === undefined) return undefined;
+  const validate = compileSchema(schema, pageSchemaPath, sourcePath, failures, { strict: true });
+  if (validate) failures.push(...schemaFailures(validate, value, sourcePath));
+  if (!isRecord(value) || value.record_kind !== PAGE_RECORD_KIND) return undefined;
+  const thresholdDate = value.review_by;
+  if (!Number.isFinite(parseDateTime(thresholdDate))) {
+    failures.push(failure("freshness_record_invalid", sourcePath, "page evidence review_by must be an RFC 3339 date-time value"));
+    return undefined;
+  }
+  return { thresholdDate, verifiedAt: null };
+}
+
+function classify(entry, asOfMs, windowMs) {
+  if (entry.thresholdDate === null) return "fresh";
+  const thresholdMs = Date.parse(entry.thresholdDate);
+  if (entry.kind === PAGE_RECORD_KIND) {
+    if (asOfMs >= thresholdMs) return "review_due";
+    return thresholdMs - asOfMs <= windowMs ? "expiring" : "fresh";
+  }
+  if (asOfMs >= thresholdMs) return "expired";
+  return thresholdMs - asOfMs <= windowMs ? "expiring" : "fresh";
+}
+
+function isBlockingStatus(status) {
+  return status === "expired" || status === "review_due";
+}
+
+function auditOne({ file, asOf, asOfMs, mode, root, pageSchemaPath, expiringWindowMs }) {
+  const failures = [];
+  const sourcePath = displayPath(file, root);
+  const loaded = readRecord(file, root, failures);
+  if (!loaded) return { failures, warnings: [], record: null };
+  const { value } = loaded;
+  if (!isRecord(value)) {
+    failures.push(failure("freshness_record_invalid", sourcePath, "record must be a JSON object"));
+    return { failures, warnings: [], record: null };
+  }
+  let kind;
+  let dates;
+  if (value.record_kind === PAGE_RECORD_KIND) {
+    kind = PAGE_RECORD_KIND;
+    dates = validatePageRecord(value, sourcePath, pageSchemaPath, failures);
+  } else if (value.committed_ci !== undefined || value.required_runs !== undefined || value.runs !== undefined) {
+    kind = "calibration_record";
+    dates = validateCalibrationRecord(value, sourcePath, failures);
+  } else {
+    failures.push(failure("freshness_record_invalid", sourcePath, "record_kind is not a supported evidence record"));
+    return { failures, warnings: [], record: null };
+  }
+  if (dates === undefined || failures.length > 0) return { failures, warnings: [], record: null };
+  const entry = { asOf, kind, source_path: sourcePath, threshold_date: dates.thresholdDate, verified_at: dates.verifiedAt };
+  const status = classify({ kind, thresholdDate: dates.thresholdDate }, asOfMs, expiringWindowMs);
+  const result = { ...entry, status };
+  const warnings = [];
+  if (status !== "fresh") {
+    const code = status === "expiring" ? "evidence_expiring" : status === "expired" ? "evidence_expired" : "evidence_review_due";
+    const message = status === "expiring"
+      ? `evidence expiry is within the advisory window (${dates.thresholdDate})`
+      : status === "expired"
+        ? `evidence expired at ${dates.thresholdDate}`
+        : `evidence review is due at ${dates.thresholdDate}`;
+    warnings.push(warning(code, sourcePath, status, dates.thresholdDate, asOf, message));
+    if (mode === "blocking" && isBlockingStatus(status)) failures.push(failure(code, sourcePath, message, { asOf, threshold_date: dates.thresholdDate }));
+  }
+  return { failures, record: result, warnings };
+}
+
+export function parseArguments(argv = process.argv.slice(2)) {
+  const options = { asOf: null, expiringWindowDays: DEFAULT_EXPIRING_WINDOW_DAYS, json: false, mode: "advisory", pageSchema: defaultPageSchemaPath, records: [] };
+  const failures = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (["--record", "--as-of", "--mode", "--page-schema", "--expiring-within-days"].includes(argument)) {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) {
+        failures.push(failure("argument_value_required", "<cli>", `${argument} requires a value`));
+        continue;
+      }
+      index += 1;
+      if (argument === "--record") options.records.push(value);
+      else if (argument === "--as-of") options.asOf = value;
+      else if (argument === "--mode") options.mode = value;
+      else if (argument === "--page-schema") options.pageSchema = path.resolve(process.cwd(), value);
+      else options.expiringWindowDays = Number(value);
+      continue;
+    }
+    failures.push(failure("argument_unknown", "<cli>", `unsupported argument ${argument}`));
+  }
+  if (options.records.length === 0) failures.push(failure("record_required", "<cli>", "at least one --record is required"));
+  if (options.asOf === null) failures.push(failure("as_of_required", "<cli>", "--as-of is required for deterministic freshness auditing"));
+  else if (!Number.isFinite(parseDateTime(options.asOf))) failures.push(failure("as_of_invalid", "<cli>", "--as-of must be an RFC 3339 date-time value"));
+  if (!["advisory", "blocking"].includes(options.mode)) failures.push(failure("mode_invalid", "<cli>", "--mode must be advisory or blocking"));
+  if (!Number.isFinite(options.expiringWindowDays) || options.expiringWindowDays < 0 || options.expiringWindowDays > 3650) failures.push(failure("expiring_window_invalid", "<cli>", "--expiring-within-days must be a number from 0 through 3650"));
+  return { failures, options };
+}
+
+export function auditEvidenceFreshness({ records, asOf, mode = "advisory", root = repositoryRoot, pageSchema = defaultPageSchemaPath, expiringWindowDays = DEFAULT_EXPIRING_WINDOW_DAYS }) {
+  const asOfMs = parseDateTime(asOf);
+  const failures = [];
+  const warnings = [];
+  const entries = [];
+  if (!Number.isFinite(asOfMs)) failures.push(failure("as_of_invalid", "<cli>", "asOf must be an RFC 3339 date-time value"));
+  for (const record of records) {
+    const file = path.resolve(root, record);
+    const result = auditOne({ asOf, asOfMs, expiringWindowMs: expiringWindowDays * 24 * 60 * 60 * 1000, file, mode, pageSchemaPath: pageSchema, root });
+    failures.push(...result.failures);
+    warnings.push(...result.warnings);
+    if (result.record) entries.push(result.record);
+  }
+  const uniqueFailures = [...new Map(failures.map((item) => [`${item.code}:${item.path}:${item.message}`, item])).values()];
+  const uniqueWarnings = [...new Map(warnings.map((item) => [`${item.code}:${item.source_path}:${item.threshold_date}`, item])).values()];
+  return {
+    asOf,
+    expiring_window_days: expiringWindowDays,
+    failures: uniqueFailures,
+    mode,
+    ok: uniqueFailures.length === 0,
+    records: entries,
+    warnings: uniqueWarnings,
+  };
+}
+
+export function runCli(argv = process.argv.slice(2), root = repositoryRoot) {
+  const parsed = parseArguments(argv);
+  if (parsed.failures.length > 0) return { asOf: parsed.options.asOf, failures: parsed.failures, mode: parsed.options.mode, ok: false, records: [], warnings: [] };
+  return auditEvidenceFreshness({
+    asOf: parsed.options.asOf,
+    expiringWindowDays: parsed.options.expiringWindowDays,
+    mode: parsed.options.mode,
+    pageSchema: parsed.options.pageSchema,
+    records: parsed.options.records,
+    root,
+  });
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const parsed = parseArguments();
+    const report = parsed.failures.length > 0
+      ? { asOf: parsed.options.asOf, failures: parsed.failures, mode: parsed.options.mode, ok: false, records: [], warnings: [] }
+      : runCli();
+    if (parsed.options.json || parsed.failures.length > 0) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    else if (report.ok) process.stdout.write(`ok: audited ${report.records.length} evidence record(s)\n`);
+    else process.stderr.write(`${report.failures.map((item) => `${item.code}: ${item.message}`).join("\n")}\n`);
+    process.exitCode = report.ok ? 0 : 1;
+  } catch (error) {
+    const report = { failures: [failure("freshness_tool_error", "<tool>", error instanceof Error ? error.message : String(error))], ok: false, records: [], warnings: [] };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/baseline-contract.mjs

@@ -0,0 +1,189 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { parseStrictJson } from "./strict-json.mjs";
+
+export const BASELINE_ENVIRONMENT = {
+  architecture: "amd64",
+  browser_revision: "1228",
+  browser_version: "149.0.7827.55",
+  container_image: "mcr.microsoft.com/playwright:v1.61.0-noble@sha256:57b65fdc9ceabe0ef613124c7bbe2babcf9362c4d85e382fe3b03604e84b428a",
+  node: "22",
+  os: "Ubuntu 24.04",
+  platform: "linux/amd64",
+  playwright: "1.61.0",
+  viewport: { height: 768, width: 1024 },
+};
+
+export const BASELINE_REFERENCE = {
+  baseline: { path: "tests/snapshots/consumer-reference-card-grid.png", sha256: "5528358e957a6115793155e501f62716f7db31dc1c86856d9e1234868d672837" },
+  source: { path: "tests/helpers/render-consumer-reference.mjs", sha256: "88802a948909d5e40470be6b5481766ce2de498e59c053ac68af370b46e72ca9" },
+};
+
+export const BASELINE_METADATA_SHA256 = sha256(JSON.stringify({ environment: BASELINE_ENVIRONMENT, reference: BASELINE_REFERENCE }));
+export const CALIBRATION_CANONICAL_REPOSITORY = "changeroa/StyleGallery";
+export const CALIBRATION_EXECUTION_REPOSITORIES = Object.freeze(["ark-jo/StyleGallery", CALIBRATION_CANONICAL_REPOSITORY]);
+export const CALIBRATION_EXTERNAL_VERIFICATION = {
+  artifact: {
+    api_digest: "sha256:3f11a517b447e1b5a1da17d9ee66ba2dd947fc8a0a482c447556ef00652e6074",
+    expires_at: "2026-07-27T15:01:36Z",
+    id: "8283099324",
+    name: "chromium-sentinel-calibration-29260372260-18229be570766d3b42f5600955120bfcba690b76",
+    size_in_bytes: 70310,
+  },
+  repository_relationship: {
+    execution_is_fork: true,
+    parent: CALIBRATION_CANONICAL_REPOSITORY,
+    source: CALIBRATION_CANONICAL_REPOSITORY,
+  },
+  source: "https://github.com/ark-jo/StyleGallery/actions/runs/29260372260",
+  verified_at: "2026-07-13T15:04:41Z",
+};
+
+export function finding(code, file, message) {
+  return { code, message, path: file };
+}
+
+export function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function readJson(file, failures) {
+  if (!fs.existsSync(file)) {
+    failures.push(finding("baseline_file_missing", file, "required baseline record is missing"));
+    return undefined;
+  }
+  try {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024 * 1024) throw new Error("JSON input must be a regular file no larger than 1 MiB");
+    return parseStrictJson(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    failures.push(finding("baseline_json_invalid", file, error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+}
+
+function sameValue(left, right) {
+  return isDeepStrictEqual(left, right);
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+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 isHash(value) {
+  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+export function validateEnvironment(environment, file) {
+  return sameValue(environment, BASELINE_ENVIRONMENT)
+    ? []
+    : [finding("calibration_environment_mismatch", file, "environment must match the immutable linux/amd64 calibration image")];
+}
+
+export function validateCalibration(record, file) {
+  const failures = [];
+  if (!isRecord(record)) return [finding("calibration_record_invalid", file, "calibration record must be an object")];
+  const allowed = new Set(["baseline_owner_approval", "committed_ci", "environment", "reference", "required_runs", "runs", "schema_version", "status"]);
+  rejectUnknown(record, allowed, "calibration_property_unknown", file, failures);
+  if (record.schema_version !== "1.0") failures.push(finding("calibration_schema_version", file, "schema_version must be 1.0"));
+  if (record.baseline_owner_approval !== "pending") failures.push(finding("baseline_owner_approval_invalid", file, "baseline owner approval must remain pending"));
+  if (record.required_runs !== 20) failures.push(finding("calibration_required_runs", file, "required_runs must equal 20"));
+  failures.push(...validateEnvironment(record.environment, file));
+  if (!sameValue(record.reference, BASELINE_REFERENCE)) failures.push(finding("calibration_reference_mismatch", file, "source and baseline hashes must match the proposed reference"));
+  if (!Array.isArray(record.runs)) return [...failures, finding("calibration_runs_invalid", file, "runs must be an array")];
+  if (record.status === "awaiting_committed_ci") {
+    if (record.runs.length !== 0 || record.committed_ci !== null) failures.push(finding("calibration_pending_evidence_forbidden", file, "pending calibration cannot claim runs or committed CI"));
+    return failures;
+  }
+  if (!["awaiting_external_verification", "completed"].includes(record.status)) return [...failures, finding("calibration_status_invalid", file, "status must be awaiting_committed_ci, awaiting_external_verification, or completed")];
+  if (!isRecord(record.committed_ci)) failures.push(finding("calibration_committed_ci_missing", file, "calibrated record requires committed CI metadata"));
+  else {
+    rejectUnknown(record.committed_ci, new Set(["artifact_name", "checkout_sha", "execution_repository", "external_verification", "head_sha", "raw_evidence_sha256", "repository", "run_attempt", "run_id", "sha", "workflow"]), "calibration_committed_ci_property_unknown", file, failures);
+    const expectedArtifact = `chromium-sentinel-calibration-${record.committed_ci.run_id}-${record.committed_ci.sha}`;
+    if (!/^[0-9]+$/.test(record.committed_ci.run_id ?? "")
+      || !/^[0-9]+$/.test(record.committed_ci.run_attempt ?? "")
+      || !/^[0-9a-f]{40}$/.test(record.committed_ci.sha ?? "")
+      || !/^[0-9a-f]{40}$/.test(record.committed_ci.head_sha ?? "")
+      || record.committed_ci.checkout_sha !== record.committed_ci.sha
+      || !CALIBRATION_EXECUTION_REPOSITORIES.includes(record.committed_ci.execution_repository)
+      || !/^[0-9a-f]{64}$/.test(record.committed_ci.raw_evidence_sha256 ?? "")
+      || record.committed_ci.repository !== CALIBRATION_CANONICAL_REPOSITORY
+      || record.committed_ci.workflow !== ".github/workflows/validate.yml"
+      || record.committed_ci.artifact_name !== expectedArtifact) {
+      failures.push(finding("calibration_committed_ci_invalid", file, "canonical and execution repositories, workflow, run, attempt, SHAs, raw evidence, and artifact name must have the canonical identity"));
+    }
+    if (record.status === "awaiting_external_verification" && record.committed_ci.external_verification !== null) {
+      failures.push(finding("calibration_external_verification_preclaim", file, "awaiting calibration must not claim uploaded artifact verification"));
+    }
+    if (record.status === "completed") {
+      if (!("external_verification" in record.committed_ci) || record.committed_ci.external_verification === null) {
+        failures.push(finding("calibration_external_verification_missing", file, "completed calibration requires independently checked run and artifact metadata"));
+      } else {
+        const external = record.committed_ci.external_verification;
+        const expectedSource = `https://github.com/${record.committed_ci.execution_repository}/actions/runs/${record.committed_ci.run_id}`;
+        if (!sameValue(external, CALIBRATION_EXTERNAL_VERIFICATION)
+          || external?.source !== expectedSource
+          || external?.artifact?.name !== record.committed_ci.artifact_name
+          || external?.artifact?.api_digest === `sha256:${record.committed_ci.raw_evidence_sha256}`) {
+          failures.push(finding("calibration_external_verification_invalid", file, "external verification must equal the independently checked GitHub Actions run, fork relationship, and artifact API identity"));
+        }
+      }
+    }
+  }
+  if (record.runs.length !== 20) failures.push(finding("calibration_run_count", file, "calibrated record requires exactly 20 runs"));
+  const runAllowed = new Set(["architecture", "ax_sha256", "completed", "dom_sha256", "metadata_sha256", "png_sha256", "run", "screenshot_diff_pixels"]);
+  for (const run of record.runs) {
+    if (!isRecord(run)) {
+      failures.push(finding("calibration_run_invalid", file, "every run must be an object"));
+      continue;
+    }
+    rejectUnknown(run, runAllowed, "calibration_run_property_unknown", file, failures);
+    if (!Number.isInteger(run.run) || run.run < 1 || run.run > 20) failures.push(finding("calibration_run_number_invalid", file, "run must be an integer from 1 through 20"));
+    if (run.completed !== true) failures.push(finding("calibration_run_incomplete", file, "every calibration run must complete"));
+    if (run.architecture !== "amd64") failures.push(finding("calibration_architecture_variance", file, "every run must record architecture amd64"));
+    if (![run.ax_sha256, run.dom_sha256, run.metadata_sha256, run.png_sha256].every(isHash)) failures.push(finding("calibration_hash_invalid", file, "every artifact hash must be 64 lowercase hexadecimal characters"));
+    if (run.png_sha256 !== BASELINE_REFERENCE.baseline.sha256) failures.push(finding("calibration_baseline_hash_mismatch", file, "every completed PNG must equal the proposed baseline hash"));
+    if (run.metadata_sha256 !== BASELINE_METADATA_SHA256) failures.push(finding("calibration_metadata_hash_mismatch", file, "every completed metadata hash must equal the canonical environment and reference hash"));
+    if (run.screenshot_diff_pixels !== 0) failures.push(finding("calibration_diff_nonzero", file, "every screenshot diff must equal zero"));
+  }
+  const runNumbers = record.runs.map((run) => run?.run);
+  if (new Set(runNumbers).size !== runNumbers.length) failures.push(finding("calibration_run_duplicate", file, "calibration run numbers must be unique"));
+  if (!sameValue([...runNumbers].sort((left, right) => left - right), Array.from({ length: 20 }, (_, index) => index + 1))) failures.push(finding("calibration_run_set", file, "calibration runs must be the complete range 1 through 20"));
+  const architectures = new Set(record.runs.map((run) => run?.architecture));
+  if (architectures.size !== 1 || !architectures.has("amd64")) failures.push(finding("calibration_architecture_variance", file, "every run must record architecture amd64"));
+  if (["png_sha256", "dom_sha256", "ax_sha256"].some((field) => new Set(record.runs.map((run) => run?.[field])).size !== 1)) failures.push(finding("calibration_hash_variance", file, "PNG, DOM, and AX hashes must each be identical across runs"));
+  if (new Set(record.runs.map((run) => run?.metadata_sha256)).size !== 1) failures.push(finding("calibration_metadata_variance", file, "stable environment metadata must be identical across runs"));
+  return failures;
+}
+
+export function validateManifest(manifest, file, root) {
+  const failures = [];
+  if (!isRecord(manifest)) return [finding("baseline_manifest_invalid", file, "baseline manifest must be an object")];
+  const allowed = new Set(["architecture", "baseline", "baseline_owner_approval", "browser_revision", "browser_version", "calibration", "container_image", "node", "os", "platform", "playwright", "schema_version", "source", "status", "viewport"]);
+  rejectUnknown(manifest, allowed, "baseline_manifest_property_unknown", file, failures);
+  if (manifest.schema_version !== "1.0" || manifest.status !== "proposed") failures.push(finding("baseline_manifest_state", file, "manifest must be proposed schema 1.0"));
+  if (manifest.baseline_owner_approval !== "pending") failures.push(finding("baseline_owner_approval_invalid", file, "baseline owner approval must remain pending"));
+  for (const [key, value] of Object.entries(BASELINE_ENVIRONMENT)) if (!sameValue(manifest[key], value)) failures.push(finding("baseline_environment_mismatch", file, `${key} differs from the immutable environment`));
+  rejectUnknown(manifest.calibration, new Set(["record", "required_runs", "workflow_artifact_name"]), "baseline_calibration_property_unknown", file, failures);
+  if (!isRecord(manifest.calibration) || manifest.calibration.required_runs !== 20 || manifest.calibration.record !== "consumer-reference/baselines/calibration.json") failures.push(finding("baseline_calibration_route", file, "manifest must route to the 20-run calibration record"));
+  if (manifest.calibration?.workflow_artifact_name !== "chromium-sentinel-calibration-${run_id}-${sha}") failures.push(finding("baseline_artifact_name", file, "workflow artifact name template is immutable"));
+  for (const [kind, entry] of [["source", manifest.source], ["baseline", manifest.baseline]]) {
+    rejectUnknown(entry, new Set(["path", "sha256"]), `baseline_${kind}_property_unknown`, file, failures);
+    if (!sameValue(entry, BASELINE_REFERENCE[kind])) failures.push(finding(`baseline_${kind}_reference_mismatch`, file, `${kind} identity must equal the proposed reference`));
+    const target = typeof entry?.path === "string" ? path.resolve(root, entry.path) : "";
+    if (!isRecord(entry) || !isHash(entry.sha256)) failures.push(finding(`baseline_${kind}_invalid`, file, `${kind} requires an exact path and 64-character hash`));
+    if (!target || !target.startsWith(`${root}${path.sep}`) || !fs.existsSync(target)) failures.push(finding(`baseline_${kind}_missing`, file, `${kind} path must resolve inside the repository`));
+    else if (fs.lstatSync(target).isSymbolicLink() || !fs.lstatSync(target).isFile() || !fs.realpathSync(target).startsWith(`${fs.realpathSync(root)}${path.sep}`)) failures.push(finding(`baseline_${kind}_file_invalid`, file, `${kind} must be a regular repository file, not a directory or symlink`));
+    else if (entry.sha256 !== sha256(fs.readFileSync(target))) failures.push(finding(`baseline_${kind}_hash_mismatch`, file, `${kind} hash differs from repository bytes`));
+  }
+  return failures;
+}

package/scripts/baseline-schema-parity.mjs

@@ -0,0 +1,40 @@
+import { BASELINE_METADATA_SHA256, BASELINE_REFERENCE } from "./baseline-contract.mjs";
+
+const executionRepositories = ["ark-jo/StyleGallery", "changeroa/StyleGallery"];
+
+export function baselineSchemaParity(schema, canonical, completedEvidence) {
+  const committedSchema = schema.properties.committed_ci.oneOf.find((entry) => entry.type === "object");
+  const externalSchema = committedSchema.properties.external_verification?.oneOf?.find((entry) => entry.type === "object") ?? {};
+  const artifactSchema = externalSchema.properties?.artifact ?? {};
+  const relationshipSchema = externalSchema.properties?.repository_relationship ?? {};
+  const runSchema = schema.properties.runs.items;
+  const runContains = schema.allOf[0].else.properties.runs.allOf;
+  return schema.additionalProperties === false
+    && committedSchema.additionalProperties === false
+    && schema.properties.environment.additionalProperties === false
+    && Object.entries(canonical.environment).every(([key, value]) => key === "viewport"
+      ? JSON.stringify(schema.properties.environment.properties.viewport.properties) === JSON.stringify({ width: { const: value.width }, height: { const: value.height } })
+      : schema.properties.environment.properties[key].const === value)
+    && schema.properties.reference.additionalProperties === false
+    && schema.properties.reference.properties.source.additionalProperties === false
+    && schema.properties.reference.properties.source.properties.sha256.const === BASELINE_REFERENCE.source.sha256
+    && schema.properties.reference.properties.baseline.properties.sha256.const === BASELINE_REFERENCE.baseline.sha256
+    && runSchema.additionalProperties === false
+    && runSchema.properties.png_sha256.const === BASELINE_REFERENCE.baseline.sha256
+    && runSchema.properties.metadata_sha256.const === BASELINE_METADATA_SHA256
+    && committedSchema.properties.repository.const === "changeroa/StyleGallery"
+    && JSON.stringify(committedSchema.properties.execution_repository?.enum ?? []) === JSON.stringify(executionRepositories)
+    && externalSchema.additionalProperties === false
+    && artifactSchema.additionalProperties === false
+    && relationshipSchema.additionalProperties === false
+    && artifactSchema.properties?.api_digest?.const === completedEvidence.artifactApiDigest
+    && artifactSchema.properties?.id?.const === completedEvidence.artifactId
+    && artifactSchema.properties?.name?.const === completedEvidence.artifactName
+    && artifactSchema.properties?.size_in_bytes?.const === completedEvidence.artifactSize
+    && artifactSchema.properties?.expires_at?.const === completedEvidence.artifactExpiresAt
+    && externalSchema.properties?.source?.const === completedEvidence.source
+    && externalSchema.properties?.verified_at?.const === completedEvidence.verifiedAt
+    && JSON.stringify(runContains.map((entry) => entry.contains.properties.run.const).sort((left, right) => left - right)) === JSON.stringify(Array.from({ length: 20 }, (_, index) => index + 1))
+    && runContains.every((entry) => entry.minContains === 1 && entry.maxContains === 1)
+    && JSON.stringify([...committedSchema.required].sort()) === JSON.stringify(["artifact_name", "checkout_sha", "execution_repository", "external_verification", "head_sha", "raw_evidence_sha256", "repository", "run_attempt", "run_id", "sha", "workflow"].sort());
+}