stylegallery 0.1.0

package/scripts/validate-promotion-rfc.mjs

@@ -0,0 +1,224 @@
+#!/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 { isPlainObject } from "./consumer-reference-schema.mjs";
+import { validateGovernedProfileInventory } from "./governed-profile-registry.mjs";
+import { validatePromotionAttestations } from "./promotion-attestation-contract.mjs";
+import { loadPromotionFixtureInventory, resolvePromotionJsonFile } from "./promotion-fixture-inventory.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const options = {
+  files: [],
+  fixtureRoot: path.join(repositoryRoot, "consumer-reference/fixtures/promotion"),
+  json: false,
+  policies: [],
+  profileRepositoryRoot: repositoryRoot,
+  profileRepositoryRootExplicit: false,
+};
+const argumentFailures = [];
+
+for (let index = 2; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--json") options.json = true;
+  else if (argument === "--file") {
+    const value = process.argv[index + 1];
+    if (!value || value.startsWith("--")) argumentFailures.push({ code: "argument_value_required", message: "--file requires a JSON path", path: "<cli>" });
+    else {
+      options.files.push(path.resolve(process.cwd(), value));
+      index += 1;
+    }
+  } else if (argument === "--policy") {
+    const value = process.argv[index + 1];
+    if (!value || value.startsWith("--")) argumentFailures.push({ code: "argument_value_required", message: "--policy requires a JSON path", path: "<cli>" });
+    else {
+      options.policies.push(path.resolve(process.cwd(), value));
+      index += 1;
+    }
+  } else if (argument === "--profile-repository-root") {
+    const value = process.argv[index + 1];
+    if (!value || value.startsWith("--")) argumentFailures.push({ code: "argument_value_required", message: "--profile-repository-root requires a repository path", path: "<cli>" });
+    else {
+      options.profileRepositoryRoot = path.resolve(process.cwd(), value);
+      options.profileRepositoryRootExplicit = true;
+      index += 1;
+    }
+  } else if (argument === "--promotion-fixture-root") {
+    const value = process.argv[index + 1];
+    if (!value || value.startsWith("--")) argumentFailures.push({ code: "argument_value_required", message: "--promotion-fixture-root requires a repository path", path: "<cli>" });
+    else {
+      options.fixtureRoot = path.resolve(process.cwd(), value);
+      index += 1;
+    }
+  } else argumentFailures.push({ code: "argument_unknown", message: `unsupported argument ${argument}`, path: "<cli>" });
+}
+
+const failures = [...argumentFailures];
+const warnings = [];
+const fixtureInventory = loadPromotionFixtureInventory({ fixtureRoot: options.fixtureRoot, repositoryRoot });
+failures.push(...fixtureInventory.failures);
+let validateSchema = () => false;
+try {
+  if (fixtureInventory.schema) validateSchema = new Ajv2020({ allErrors: true, strict: true }).compile(fixtureInventory.schema);
+} catch (error) {
+  failures.push({ code: "promotion_fixture_inventory_invalid", message: error instanceof Error ? error.message : String(error), path: "consumer-reference/schema/promotion-rfc.schema.json" });
+}
+const files = options.files.length > 0
+  ? options.files
+  : options.policies.length > 0
+    ? []
+    : fixtureInventory.validFiles;
+const policies = options.files.length === 0 && options.policies.length === 0
+  ? [fixtureInventory.policyFile].filter(Boolean)
+  : options.policies;
+
+function finding(code, message, recordPath) {
+  return { code, message, path: recordPath };
+}
+
+function sameStringSet(actual, expected) {
+  return Array.isArray(actual) && actual.length === expected.length && actual.every((item) => typeof item === "string") && new Set(actual).size === expected.length && expected.every((item) => actual.includes(item));
+}
+
+function validateSemantics({ canonicalExample, value, recordPath, failures, warnings }) {
+  if (!isPlainObject(value)) return;
+  if (canonicalExample && (value.decision !== "deferred" || !Array.isArray(value.attestations) || value.attestations.length !== 0)) {
+    failures.push(finding("promotion_canonical_example_invalid", "canonical examples must remain deferred with zero attestations", recordPath));
+  }
+  if (typeof value.review_independence === "boolean") failures.push(finding("review_independence_boolean", "review_independence must use the canonical single_account enum", recordPath));
+  if (!isPlainObject(value.owner) || typeof value.owner.migration !== "string" || !isPlainObject(value.migration)) {
+    failures.push(finding("promotion_owner_migration_required", "promotion proposals require migration ownership and a migration plan", recordPath));
+  }
+  if (value.compatibility?.breaking === true && value.migration?.required !== true) {
+    failures.push(finding("promotion_migration_required", "breaking compatibility changes require an enabled migration plan", recordPath));
+  }
+  if (value.eligibility_basis === "consumer_count_only") failures.push(finding("promotion_count_only_forbidden", "consumer count cannot replace evidence and lifecycle duties", recordPath));
+  if (isPlainObject(value.support) && value.transition?.to === "stable" && value.support.status === "ended") {
+    failures.push(finding("stable_support_ended", "stable promotion requires active support", recordPath));
+  }
+  if (value.support?.status !== "active" || value.support?.capacity !== "committed") {
+    failures.push(finding("promotion_support_required", "promotion eligibility requires active, affirmative support capacity", recordPath));
+  }
+  if (value.transition?.from === "stable" && value.transition?.to === "shared_experimental") {
+    failures.push(finding("promotion_stable_relabel_forbidden", "a stable contract must be maintained, rolled back, or deprecated with migration", recordPath));
+  }
+  const transition = `${value.transition?.from ?? ""}->${value.transition?.to ?? ""}`;
+  if (!["consumer_local->shared_experimental", "shared_experimental->stable", "stable->shared_experimental"].includes(transition)) {
+    failures.push(finding("promotion_transition_invalid", `${transition} is not a governed promotion transition`, recordPath));
+  }
+  const evidence = Array.isArray(value.evidence) ? value.evidence.filter(isPlainObject) : [];
+  const evidenceIds = evidence.map((entry) => entry.id).filter((id) => typeof id === "string");
+  if (new Set(evidenceIds).size !== evidenceIds.length) failures.push(finding("promotion_evidence_duplicate", "evidence IDs must be unique", recordPath));
+  if (evidence.some((entry) => entry.kind === "blocking" && entry.status === "failed")) {
+    failures.push(finding("promotion_blocking_evidence_failed", "failed blocking evidence prevents eligibility", recordPath));
+  }
+  const regressionPassed = evidence.some((entry) => entry.kind === "regression" && entry.status === "passed");
+  const claimScopedPassed = evidence.some((entry) => entry.kind === "claim_scoped" && entry.status === "passed");
+  if (value.normative_bypass === "normative_correctness" && !regressionPassed) {
+    failures.push(finding("promotion_normative_regression_required", "normative bypass waives adoption count only and requires passing regression evidence", recordPath));
+  }
+  if (value.normative_bypass === "normative_correctness" && value.scope?.kind !== "normative_correctness") {
+    failures.push(finding("promotion_normative_scope_required", "normative bypass requires a normative correctness scope", recordPath));
+  }
+  if (value.transition?.to === "stable" && (!claimScopedPassed || !regressionPassed)) {
+    failures.push(finding("promotion_stable_evidence_required", "stable requires passing claim-scoped and regression evidence", recordPath));
+  }
+  const attestationResult = validatePromotionAttestations({ inventory: governedProfileInventory, profileRoot: options.profileRepositoryRoot, recordPath, value });
+  failures.push(...attestationResult.failures);
+  const counted = attestationResult.eligibleCount;
+  if (value.transition?.from === "consumer_local" && value.transition?.to === "shared_experimental" && value.normative_bypass === "none" && counted < 2) {
+    warnings.push(finding("promotion_consumer_count_below_gateway", "deferred proposal has fewer than two independent consumers", recordPath));
+  }
+  if (value.transition?.to === "stable" && (value.stable_scope_decision !== true || value.provenance?.debt_resolved !== true)) {
+    failures.push(finding("promotion_stable_readiness_required", "stable requires explicit scope decision and resolved provenance debt; no numeric count substitutes", recordPath));
+  }
+}
+
+function validatePolicy(value, recordPath, failures) {
+  if (!isPlainObject(value)) {
+    failures.push(finding("promotion_policy_shape_invalid", "promotion policy must be an object", recordPath));
+    return;
+  }
+  const allowed = ["artifact_mode", "boundaries", "claims", "gateway", "id", "lifecycle", "normative_bypass", "owner", "review_independence", "schema_version", "status"];
+  if (Object.keys(value).some((key) => !allowed.includes(key))) failures.push(finding("promotion_policy_shape_invalid", "promotion policy contains an unknown field", recordPath));
+  const nestedShapes = [
+    [value.boundaries, ["excluded_content", "promoted_content"], "boundaries"],
+    [value.claims, ["adopter_attestations", "promotion_occurred"], "claims"],
+    [value.gateway, ["applies_to", "minimum_independent_consumers", "stable_numeric_threshold", "transition"], "gateway"],
+    [value.gateway?.transition, ["from", "to"], "gateway.transition"],
+    [value.lifecycle, ["failure_actions", "stable_relabel"], "lifecycle"],
+    [value.normative_bypass, ["categories", "retains", "waives"], "normative_bypass"],
+    [value.owner, ["enforcement", "name"], "owner"],
+  ];
+  for (const [candidate, keys, label] of nestedShapes) {
+    if (!isPlainObject(candidate) || Object.keys(candidate).some((key) => !keys.includes(key))) failures.push(finding("promotion_policy_shape_invalid", `promotion policy ${label} shape is invalid`, recordPath));
+  }
+  if (value.review_independence !== "single_account") failures.push(finding(typeof value.review_independence === "boolean" ? "review_independence_boolean" : "promotion_policy_shape_invalid", "policy review_independence must be single_account", recordPath));
+  if (value.gateway?.transition?.from !== "consumer_local" || value.gateway?.transition?.to !== "shared_experimental" || value.gateway?.applies_to !== "invariant_eligibility_only" || value.gateway?.minimum_independent_consumers !== 2) {
+    failures.push(finding("promotion_gateway_invalid", "the >=2 gateway applies only to consumer-local invariant eligibility for shared-experimental", recordPath));
+  }
+  if (value.gateway?.stable_numeric_threshold !== null) failures.push(finding("promotion_stable_numeric_threshold_forbidden", "stable has no numeric adoption threshold", recordPath));
+  const categories = ["accessibility", "correctness", "security", "standards"];
+  const retained = ["compatibility", "deprecation", "migration", "owner_acceptance", "regression_proof", "rollback", "scope_control", "support_capacity"];
+  if (!sameStringSet(value.normative_bypass?.categories, categories) || !sameStringSet(value.normative_bypass?.waives, ["adoption_count"]) || !sameStringSet(value.normative_bypass?.retains, retained)) {
+    failures.push(finding("promotion_normative_bypass_overreach", "normative bypass may waive adoption count only", recordPath));
+  }
+  if (value.claims?.promotion_occurred !== false || value.claims?.adopter_attestations !== 0) failures.push(finding("promotion_claim_forbidden", "the policy records no promotion and zero adopter attestations", recordPath));
+  if (value.status !== "active") failures.push(finding("promotion_claim_forbidden", "the policy status must remain active governance, not a promoted decision", recordPath));
+  if (value.schema_version !== "1.0" || value.id !== "shared-experimental-policy" || value.artifact_mode !== "schema_only") failures.push(finding("promotion_policy_identity_invalid", "promotion policy identity and artifact mode are canonical", recordPath));
+  if (value.owner?.enforcement !== "placeholder" || value.owner?.name !== "Repository governance owner") failures.push(finding("promotion_policy_owner_invalid", "promotion policy must preserve placeholder owner truth", recordPath));
+  const excluded = ["component_skin", "imagery", "motion_character", "palette", "typography"];
+  const promoted = ["claim_scoped_evidence", "invariant_behavior", "invariant_semantics"];
+  if (!sameStringSet(value.boundaries?.excluded_content, excluded)) {
+    failures.push(finding("promotion_aesthetic_boundary_required", "aesthetic identity must remain excluded from promotion", recordPath));
+  }
+  if (!sameStringSet(value.boundaries?.promoted_content, promoted)) failures.push(finding("promotion_aesthetic_boundary_required", "promoted content must be the invariant-only canonical set", recordPath));
+  if (value.lifecycle?.stable_relabel !== "forbidden" || !sameStringSet(value.lifecycle?.failure_actions, ["deprecate_with_migration", "maintain", "restrict", "rollback"])) {
+    failures.push(finding("promotion_lifecycle_invalid", "failed stable contracts require explicit lifecycle action and migration", recordPath));
+  }
+}
+
+const governedProfileInventory = validateGovernedProfileInventory({ root: options.profileRepositoryRoot });
+if (options.profileRepositoryRootExplicit && governedProfileInventory.failures.length > 0) {
+  failures.push(finding("promotion_profile_registry_invalid", "explicit governed profile repository must fully validate", "<profile-repository-root>"));
+}
+let checked = 0;
+for (const file of files) {
+  const recordPath = path.relative(repositoryRoot, file) || file;
+  const resolvedFile = resolvePromotionJsonFile({ file, repositoryRoot }, failures);
+  if (!resolvedFile) continue;
+  let value;
+  try {
+    value = parseStrictJson(fs.readFileSync(resolvedFile, "utf8"));
+    checked += 1;
+  } catch (error) {
+    failures.push(finding("promotion_json_invalid", error instanceof Error ? error.message : "promotion JSON is invalid", recordPath));
+    continue;
+  }
+  validateSemantics({ canonicalExample: fixtureInventory.validFiles.includes(resolvedFile), failures, recordPath, value, warnings });
+  if (!validateSchema(value)) {
+    for (const error of validateSchema.errors ?? []) failures.push(finding("promotion_schema_invalid", `${error.instancePath || "/"} ${error.message}`, recordPath));
+  }
+}
+for (const file of policies) {
+  const recordPath = path.relative(repositoryRoot, file) || file;
+  const resolvedFile = resolvePromotionJsonFile({ file, repositoryRoot }, failures);
+  if (!resolvedFile) continue;
+  try {
+    const value = parseStrictJson(fs.readFileSync(resolvedFile, "utf8"));
+    checked += 1;
+    validatePolicy(value, recordPath, failures);
+  } catch (error) {
+    failures.push(finding("promotion_json_invalid", error instanceof Error ? error.message : "promotion policy JSON is invalid", recordPath));
+  }
+}
+
+const uniqueFailures = [...new Map(failures.map((entry) => [`${entry.code}:${entry.path}:${entry.message}`, entry])).values()];
+const result = { checked, failures: uniqueFailures, ok: uniqueFailures.length === 0, warnings };
+if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+else if (result.ok) process.stdout.write(`ok: ${checked} promotion proposal records\n`);
+else process.stderr.write(`${result.failures.map((entry) => `${entry.code}: ${entry.path}: ${entry.message}`).join("\n")}\n`);
+if (!result.ok) process.exitCode = 1;

package/scripts/validate-reference-artifacts.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { adapter } 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";
+
+function hash(content) {
+  return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
+}
+
+function cssDeclarations(css) {
+  return [...css.matchAll(/^\s*(--[a-z0-9-]+):\s*([^;]+);\s*$/gm)].map((match) => ({ name: match[1], value: match[2].trim() }));
+}
+
+function parseArguments() {
+  let json = false;
+  let manifest = "consumer-reference/generated/manifest.json";
+  const failures = [];
+  for (let index = 2; index < process.argv.length; index += 1) {
+    const argument = process.argv[index];
+    if (argument === "--json") json = true;
+    else if (argument === "--manifest") {
+      manifest = process.argv[index + 1];
+      if (!manifest) failures.push({ code: "argument_value_required", message: "--manifest requires a value", path: "<cli>" });
+      else index += 1;
+    } else failures.push({ code: "argument_unknown", message: `unsupported argument ${argument}`, path: "<cli>" });
+  }
+  return { failures, json, manifest };
+}
+
+const options = parseArguments();
+const failures = [...options.failures];
+const warnings = [];
+const trustRoot = process.cwd();
+const manifestPath = path.resolve(trustRoot, options.manifest || "missing.json");
+let manifest;
+const manifestInspection = inspectArtifactPath(trustRoot, manifestPath, false);
+if (!manifestInspection.ok && manifestInspection.reason === "missing") {
+  failures.push({ code: "artifact_manifest_missing", message: "manifest does not exist", path: options.manifest });
+  failures.push({ code: "artifact_output_missing", message: "output cannot be located without a manifest", path: options.manifest });
+} else if (!manifestInspection.ok) {
+  failures.push({ code: "artifact_manifest_untrusted", message: "manifest must be a contained regular non-symlink file", path: options.manifest });
+} else {
+  try {
+    manifest = parseStrictJson(fs.readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    failures.push({ code: "artifact_manifest_invalid", message: error instanceof Error ? error.message : String(error), path: options.manifest });
+  }
+}
+if (manifest !== undefined) {
+  const allowedManifestProperties = new Set(["adapter", "declarations", "inputHash", "outputCount", "outputFile", "outputHash", "schemaVersion", "sourceCount", "sourceFile", "warnings"]);
+  if (manifest.scaffold === true) failures.push({ code: "artifact_scaffold_forbidden", message: "manifest must not contain a scaffold success sentinel", path: options.manifest });
+  for (const key of Object.keys(manifest).filter((key) => !allowedManifestProperties.has(key))) failures.push({ code: "artifact_manifest_property_unknown", message: `manifest contains unsupported property ${key}`, path: options.manifest });
+  if (manifest.schemaVersion !== "1.0") failures.push({ code: "artifact_schema_version", message: "manifest schemaVersion must be 1.0", path: options.manifest });
+  if (manifest.adapter?.name !== adapter.name || manifest.adapter?.version !== adapter.version) failures.push({ code: "artifact_adapter_mismatch", message: "manifest adapter pin is invalid", path: options.manifest });
+  if (!Number.isInteger(manifest.sourceCount) || !Number.isInteger(manifest.outputCount) || manifest.sourceCount <= 0 || manifest.outputCount <= 0) failures.push({ code: "artifact_zero_count", message: "source and output counts must be positive integers", path: options.manifest });
+  if (manifest.sourceCount !== manifest.outputCount) failures.push({ code: "artifact_count_mismatch", message: "source and output counts differ", path: options.manifest });
+  if (!Array.isArray(manifest.warnings)) failures.push({ code: "artifact_warnings_invalid", message: "warnings must be an array", path: options.manifest });
+  else if (manifest.warnings.length > 0) failures.push({ code: "artifact_warning", message: "manifest contains adapter warnings", path: options.manifest });
+  const declared = Array.isArray(manifest.declarations) ? manifest.declarations : [];
+  if (!Array.isArray(manifest.declarations)) failures.push({ code: "artifact_declarations_invalid", message: "declarations must be an array", path: options.manifest });
+  const declarationNames = declared.map((item) => item?.name).filter((name) => typeof name === "string");
+  if (new Set(declarationNames).size !== declarationNames.length) failures.push({ code: "artifact_declaration_duplicate", message: "manifest contains duplicate declarations", path: options.manifest });
+  const sourcePath = typeof manifest.sourceFile === "string" ? path.resolve(path.dirname(manifestPath), manifest.sourceFile) : "";
+  const outputPath = typeof manifest.outputFile === "string" ? path.resolve(path.dirname(manifestPath), manifest.outputFile) : "";
+  const sourceInspection = sourcePath ? inspectArtifactPath(trustRoot, sourcePath, false) : { ok: false, reason: "missing" };
+  const outputInspection = outputPath ? inspectArtifactPath(trustRoot, outputPath, false) : { ok: false, reason: "missing" };
+  if (!sourceInspection.ok && sourceInspection.reason === "missing") failures.push({ code: "artifact_source_missing", message: "manifest source file does not exist", path: options.manifest });
+  else if (!sourceInspection.ok) failures.push({ code: "token_source_untrusted", message: "manifest source must be a contained regular non-symlink file", path: options.manifest });
+  else {
+    const sourceBytes = fs.readFileSync(sourcePath);
+    if (manifest.inputHash !== hash(sourceBytes)) failures.push({ code: "artifact_input_hash_mismatch", message: "input hash does not match source", path: options.manifest });
+    try {
+      const contract = validatePortableTokens(parseStrictJson(sourceBytes.toString("utf8")));
+      failures.push(...contract.failures);
+      if (contract.tokens.length !== manifest.sourceCount) failures.push({ code: "artifact_source_count_mismatch", message: "source count does not match canonical tokens", path: options.manifest });
+      const expected = contract.tokens.map((token) => `--${token.path.replaceAll(".", "-")}`);
+      for (const name of expected.filter((name) => !declarationNames.includes(name))) failures.push({ code: "artifact_declaration_missing", message: `manifest omitted ${name}`, path: options.manifest });
+    } catch (error) {
+      failures.push({ code: "artifact_source_invalid", message: error instanceof Error ? error.message : String(error), path: options.manifest });
+    }
+  }
+  if (!outputInspection.ok && outputInspection.reason === "missing") failures.push({ code: "artifact_output_missing", message: "manifest output file does not exist", path: options.manifest });
+  else if (!outputInspection.ok) failures.push({ code: "artifact_output_untrusted", message: "manifest output must be a contained regular non-symlink file", path: options.manifest });
+  else {
+    const css = fs.readFileSync(outputPath, "utf8");
+    const emitted = cssDeclarations(css);
+    const emittedNames = emitted.map((item) => item.name);
+    if (manifest.outputHash !== hash(css)) failures.push({ code: "artifact_output_hash_mismatch", message: "output hash does not match CSS", path: options.manifest });
+    if (emitted.length === 0) failures.push({ code: "artifact_zero_count", message: "CSS contains zero declarations", path: options.manifest });
+    if (new Set(emittedNames).size !== emittedNames.length) failures.push({ code: "artifact_declaration_duplicate", message: "CSS contains duplicate declarations", path: options.manifest });
+    for (const name of declarationNames.filter((name) => !emittedNames.includes(name))) failures.push({ code: "artifact_declaration_missing", message: `CSS omitted ${name}`, path: options.manifest });
+    for (const declaration of declared) {
+      const actual = emitted.find((item) => item.name === declaration?.name);
+      if (actual && actual.value !== declaration.value) failures.push({ code: "artifact_declaration_mismatch", message: `CSS value for ${declaration.name} differs from the manifest`, path: options.manifest });
+    }
+    if (emitted.length !== manifest.outputCount || emitted.length !== declarationNames.length) failures.push({ code: "artifact_count_mismatch", message: "CSS, manifest count, and declarations differ", path: options.manifest });
+    if (css.includes("[object Object]")) failures.push({ code: "artifact_object_sentinel", message: "CSS contains [object Object]", path: options.manifest });
+    if (/\{[a-z0-9.-]+\}|\b(?:null|undefined)\b/.test(css)) failures.push({ code: "artifact_unresolved_value", message: "CSS contains an unresolved value", path: options.manifest });
+    if (sourceInspection.ok) {
+      const rebuildRoot = fs.mkdtempSync(path.join(trustRoot, ".tmp-stylegallery-reference-validation-"));
+      try {
+        const expectedOutput = path.join(rebuildRoot, "tokens.css");
+        const expectedManifest = path.join(rebuildRoot, "manifest.json");
+        const builder = path.join(path.dirname(fileURLToPath(import.meta.url)), "build-reference-artifacts.mjs");
+        const child = spawnSync(process.execPath, [builder, "--source", sourcePath, "--output", expectedOutput, "--manifest", expectedManifest, "--adapter", "style-dictionary", "--fail-on-warning", "--json"], { cwd: process.cwd(), encoding: "utf8" });
+        if (child.status !== 0 || !fs.existsSync(expectedOutput)) failures.push({ code: "artifact_canonical_rebuild_failed", message: "canonical source could not be rebuilt with the pinned adapter", path: options.manifest });
+        else if (fs.readFileSync(expectedOutput, "utf8") !== css) failures.push({ code: "artifact_source_output_mismatch", message: "CSS differs from the pinned adapter output derived from canonical source", path: options.manifest });
+      } finally {
+        fs.rmSync(rebuildRoot, { force: true, recursive: true });
+      }
+    }
+  }
+}
+const uniqueFailures = [...new Map(failures.map((item) => [`${item.code}:${item.path}:${item.message}`, item])).values()];
+const report = { failures: uniqueFailures, manifest: options.manifest, ok: uniqueFailures.length === 0, warnings };
+const text = options.json ? JSON.stringify(report, null, 2) : report.ok ? "ok: reference artifacts" : uniqueFailures.map((item) => `${item.code}: ${item.message}`).join("\n");
+(options.json || report.ok ? console.log : console.error)(text);
+process.exitCode = report.ok ? 0 : 1;

package/scripts/validate-renderer-purity.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+let renderer = "tests/helpers/render-consumer-reference.mjs";
+let json = false;
+const failures = [];
+for (let index = 2; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--json") json = true;
+  else if (argument === "--renderer" && process.argv[index + 1]) {
+    renderer = process.argv[index + 1];
+    index += 1;
+  } else failures.push({ code: "argument_unknown", message: `unsupported argument ${argument}`, path: "<cli>" });
+}
+
+function hashProtectedSources() {
+  const files = [path.join(repositoryRoot, "CATALOG.md")];
+  const queue = [path.join(repositoryRoot, "patterns")];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) queue.push(target);
+      else if (entry.isFile()) files.push(target);
+    }
+  }
+  const hash = crypto.createHash("sha256");
+  for (const file of files.sort()) hash.update(path.relative(repositoryRoot, file)).update(fs.readFileSync(file));
+  return hash.digest("hex");
+}
+
+const rendererPath = path.resolve(repositoryRoot, renderer);
+if (!fs.existsSync(rendererPath)) failures.push({ code: "renderer_missing", message: "renderer helper does not exist", path: renderer });
+else {
+  const source = fs.readFileSync(rendererPath, "utf8");
+  const imports = [...source.matchAll(/^import\s+[^;]+?\s+from\s+["']([^"']+)["'];?$/gm)].map((match) => match[1]);
+  if (imports.length !== 1 || imports[0] !== "../../scripts/pattern-data.mjs") failures.push({ code: "renderer_import_boundary", message: "renderer may import only scripts/pattern-data.mjs", path: renderer });
+  if (/generate-patterns|build-reference-artifacts/.test(source)) failures.push({ code: "renderer_generator_dependency", message: "renderer must not import or call generators", path: renderer });
+  if (/node:(?:fs|child_process)|\b(?:writeFile|appendFile|rmSync|renameSync|spawnSync|execSync)\b/.test(source)) failures.push({ code: "renderer_side_effect_capability", message: "renderer must not hold filesystem or process mutation capability", path: renderer });
+  if (failures.length === 0) {
+    const before = hashProtectedSources();
+    await import(`${pathToFileURL(rendererPath).href}?purity=${Date.now()}`);
+    const after = hashProtectedSources();
+    if (after !== before) failures.push({ code: "renderer_protected_source_mutation", message: "renderer import changed patterns or CATALOG.md", path: renderer });
+  }
+}
+
+const result = { failures, ok: failures.length === 0, warnings: [] };
+if (json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+else if (!result.ok) process.stderr.write(`${failures.map((failure) => `${failure.code}: ${failure.message}`).join("\n")}\n`);
+if (!result.ok) process.exitCode = 1;

package/scripts/validate-unity-org-wiki.mjs

@@ -0,0 +1,146 @@
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+const root = process.cwd();
+const trackedInventorySha256 = "b1438e6e8d438bab3eff2ff02f5a10e9374fdfb89b0581ffb936a42920fa2e05";
+const sourceInventorySha256 = "8291b471251053a8921651eb7c791d13a4794984b73670a51cdb1116deb49657";
+const snapshotTimestamp = "2026-07-14T12:59:16Z";
+const expectedCounts = new Map([
+  ["meta-forks-mirrors", 356],
+  ["meta-archived-historical", 32],
+  ["game-ui-primary", 9],
+  ["graphics-rendering", 38],
+  ["ecs-dots", 22],
+  ["networking", 21],
+  ["xr-ar", 25],
+  ["ml-ai", 23],
+  ["robotics", 6],
+  ["2d", 7],
+  ["animation", 10],
+  ["audio", 3],
+  ["physics", 1],
+  ["editor-tooling", 29],
+  ["ci-infra", 2],
+  ["language-runtime", 3],
+  ["services-cloud", 3],
+  ["platform-mobile", 9],
+  ["samples-templates", 30],
+  ["other-mixed-or-insufficient-metadata", 175],
+]);
+
+function parseArguments(arguments_) {
+  const options = {
+    inventory: path.join(root, "game-ui", "unity", "data", "unity-technologies-public-repositories.json"),
+    map: path.join(root, "game-ui", "unity", "repository-map.md"),
+    wiki: path.join(root, "game-ui", "unity", "org-wiki.md"),
+  };
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (argument === "--json") continue;
+    if (argument === "--inventory" || argument === "--map" || argument === "--wiki") {
+      const value = arguments_[index + 1];
+      if (!value) throw new Error(`${argument} requires a path`);
+      options[argument.slice(2)] = path.resolve(value);
+      index += 1;
+      continue;
+    }
+    throw new Error(`unknown argument: ${argument}`);
+  }
+  return options;
+}
+
+function requireCondition(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function validateInventory(inventory) {
+  requireCondition(Array.isArray(inventory), "inventory must be a JSON array");
+  requireCondition(inventory.length === 804, `expected 804 repositories, got ${inventory.length}`);
+  const ids = new Set();
+  const names = new Set();
+  const counts = new Map([...expectedCounts.keys()].map((cluster) => [cluster, 0]));
+  let archivedCount = 0;
+  let forkCount = 0;
+  let templateCount = 0;
+
+  for (const repository of inventory) {
+    requireCondition(repository && typeof repository === "object", "repository row must be an object");
+    requireCondition(Number.isSafeInteger(repository.id), "repository id must be an integer");
+    requireCondition(typeof repository.full_name === "string", "repository full_name must be a string");
+    requireCondition(!ids.has(repository.id) && !names.has(repository.full_name), `duplicate repository identity: ${repository.full_name}`);
+    requireCondition(repository.full_name !== "tasharen/ngui", "NGUI must remain external to the Unity-Technologies inventory");
+    requireCondition(repository.full_name.startsWith("Unity-Technologies/"), `repository outside Unity-Technologies: ${repository.full_name}`);
+    requireCondition(repository.html_url === `https://github.com/${repository.full_name}`, `repository URL mismatch: ${repository.full_name}`);
+    requireCondition(repository.capture_timestamp === snapshotTimestamp, `snapshot timestamp mismatch: ${repository.full_name}`);
+    requireCondition(expectedCounts.has(repository.primary_cluster), `invalid primary_cluster: ${repository.primary_cluster}`);
+    requireCondition(typeof repository.ui_relevance === "string" && repository.ui_relevance.length > 0, `UI relevance missing: ${repository.full_name}`);
+    requireCondition(typeof repository.ui_disposition_reason === "string" && repository.ui_disposition_reason.length > 0, `UI disposition reason missing: ${repository.full_name}`);
+    requireCondition(Array.isArray(repository.representative_ui_paths), `representative UI paths must be an array: ${repository.full_name}`);
+    ids.add(repository.id);
+    names.add(repository.full_name);
+    counts.set(repository.primary_cluster, counts.get(repository.primary_cluster) + 1);
+    if (repository.archived) archivedCount += 1;
+    if (repository.fork) forkCount += 1;
+    if (repository.is_template) templateCount += 1;
+  }
+
+  for (const [cluster, expected] of expectedCounts) {
+    requireCondition(counts.get(cluster) === expected, `cluster count mismatch for ${cluster}: expected ${expected}, got ${counts.get(cluster)}`);
+  }
+  requireCondition(archivedCount === 59, `archived repository count mismatch: expected 59, got ${archivedCount}`);
+  requireCondition(forkCount === 356, `fork repository count mismatch: expected 356, got ${forkCount}`);
+  requireCondition(templateCount === 4, `template repository count mismatch: expected 4, got ${templateCount}`);
+  return { archivedCount, counts: Object.fromEntries(counts), forkCount, templateCount };
+}
+
+function validatePublication(content, label) {
+  requireCondition(content.includes("804"), `${label} must state the 804-row boundary`);
+  const sourceHashes = [...content.matchAll(/(?:pre-projection|before tracked projection)[^`\n]*SHA-256(?: was)? `([0-9a-f]{64})`/g)].map((match) => match[1]);
+  const trackedHashes = [...content.matchAll(/tracked JSON[^`\n]*SHA-256(?: is)? `([0-9a-f]{64})`/g)].map((match) => match[1]);
+  requireCondition(sourceHashes.length > 0 && sourceHashes.every((hash) => hash === sourceInventorySha256), `${label} source inventory hash drift`);
+  requireCondition(trackedHashes.length > 0 && trackedHashes.every((hash) => hash === trackedInventorySha256), `${label} tracked inventory hash drift`);
+  requireCondition(content.includes(snapshotTimestamp), `${label} snapshot timestamp drift`);
+  requireCondition(content.includes("59 archived") && content.includes("356 forks") && content.includes("4 templates"), `${label} lifecycle totals drift`);
+}
+
+function validateWiki(wiki) {
+  requireCondition(wiki.includes("**804**"), "wiki must state the 804-row boundary");
+  requireCondition(wiki.includes("Independent research — not affiliated with or endorsed by Unity Technologies"), "wiki must state the non-affiliation boundary");
+  requireCondition(wiki.includes("tasharen/ngui") && wiki.includes("outside the Unity-Technologies 804-repository inventory"), "wiki must keep NGUI external");
+  requireCondition(wiki.includes("data/unity-technologies-public-repositories.json"), "wiki must link the tracked inventory");
+  requireCondition(!wiki.includes(".omo/"), "tracked wiki must not depend on .omo research paths");
+  requireCondition(!/(?:\/Users\/|\/home\/|[A-Za-z]:\\Users\\)/.test(wiki), "absolute home path found in wiki");
+  for (const [cluster, count] of expectedCounts) {
+    requireCondition(wiki.includes(`| \`${cluster}\` | ${count} |`), `wiki cluster table drift: ${cluster}`);
+  }
+  validatePublication(wiki, "wiki");
+}
+
+function validateMap(map) {
+  requireCondition(map.includes("data/unity-technologies-public-repositories.json"), "repository map must link the tracked inventory");
+  requireCondition(map.includes("804 classified rows"), "repository map must state the 804-row boundary");
+  validatePublication(map, "repository map");
+}
+
+async function main() {
+  try {
+    const options = parseArguments(process.argv.slice(2));
+    const [inventoryText, map, wiki] = await Promise.all([
+      readFile(options.inventory, "utf8"),
+      readFile(options.map, "utf8"),
+      readFile(options.wiki, "utf8"),
+    ]);
+    const stats = validateInventory(JSON.parse(inventoryText));
+    const inventorySha256 = createHash("sha256").update(inventoryText).digest("hex");
+    requireCondition(inventorySha256 === trackedInventorySha256, `tracked inventory SHA-256 mismatch: expected ${trackedInventorySha256}, got ${inventorySha256}`);
+    validateMap(map);
+    validateWiki(wiki);
+    console.log(JSON.stringify({ ok: true, repositories: 804, uniqueIds: 804, uniqueNames: 804, inventorySha256, clusterTotal: Object.values(stats.counts).reduce((sum, value) => sum + value, 0), ...stats }, null, 2));
+  } catch (error) {
+    console.error(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+    process.exitCode = 1;
+  }
+}
+
+await main();