stylegallery 0.1.0

package/scripts/profile-record-contract.mjs

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseStrictJson } from "./strict-json.mjs";
+
+const referenceKinds = Object.freeze({
+  component: { field: "component_records", pattern: /^components\/[a-z0-9-]+\.component\.json$/, required: 1 },
+  evidence: { field: "evidence_records", pattern: /^evidence\/[a-z0-9-]+\.evidence\.json$/, required: 1 },
+  fixture: { field: "fixture_records", pattern: /^fixtures\/[a-z0-9-]+\.fixture\.json$/, required: 1 },
+  generated: { field: "generated_records", pattern: /^generated\/[a-z0-9-]+\.md$/, required: 3 },
+  states: { field: "state_records", pattern: /^states\/[a-z0-9-]+\.states\.json$/, required: 1 },
+});
+
+function finding(code, file, message) {
+  return { code, message, path: file };
+}
+
+function isInside(base, target) {
+  const relative = path.relative(base, target);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function isNormalizedRelative(reference) {
+  return typeof reference === "string"
+    && reference.length > 0
+    && !path.posix.isAbsolute(reference)
+    && !path.win32.isAbsolute(reference)
+    && !reference.includes("\\")
+    && !reference.includes("?")
+    && !reference.includes("#")
+    && !/^[A-Za-z][A-Za-z\d+.-]*:/.test(reference)
+    && path.posix.normalize(reference) === reference
+    && !reference.split("/").some((segment) => segment === "." || segment === "..");
+}
+
+function resolveReference(profileRoot, reference, kind, profileFile, failures) {
+  const definition = referenceKinds[kind];
+  if (!isNormalizedRelative(reference)) {
+    failures.push(finding("profile_reference_outside", profileFile, `${definition.field} contains an unsafe reference`));
+    return undefined;
+  }
+  if (!definition.pattern.test(reference)) {
+    failures.push(finding("profile_reference_unknown", profileFile, `${definition.field} contains unknown reference ${reference}`));
+    return undefined;
+  }
+  const target = path.resolve(profileRoot, reference);
+  if (!isInside(profileRoot, target)) {
+    failures.push(finding("profile_reference_outside", profileFile, `${reference} escapes its profile`));
+    return undefined;
+  }
+  if (!fs.existsSync(target)) {
+    failures.push(finding("profile_reference_missing", profileFile, `${reference} does not exist`));
+    return undefined;
+  }
+  const metadata = fs.lstatSync(target);
+  if (metadata.isSymbolicLink()) {
+    failures.push(finding("profile_reference_symlink", profileFile, `${reference} must not be a symlink`));
+    return undefined;
+  }
+  if (!metadata.isFile()) {
+    failures.push(finding("profile_reference_type_invalid", profileFile, `${reference} must be a regular file`));
+    return undefined;
+  }
+  const realRoot = fs.realpathSync(profileRoot);
+  const realTarget = fs.realpathSync(target);
+  if (!isInside(realRoot, realTarget)) {
+    failures.push(finding("profile_reference_outside", profileFile, `${reference} resolves outside its profile`));
+    return undefined;
+  }
+  if (realTarget !== path.join(realRoot, reference)) {
+    failures.push(finding("profile_reference_redirect", profileFile, `${reference} resolves through a redirect`));
+    return undefined;
+  }
+  if (kind === "generated") return { path: realTarget, reference };
+  try {
+    return { path: realTarget, reference, value: parseStrictJson(fs.readFileSync(realTarget, "utf8")) };
+  } catch (error) {
+    failures.push(finding("profile_reference_json_invalid", reference, error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+}
+
+function resolveFixtureLinks(resolved, profileFile, failures) {
+  const fixture = resolved.fixture[0];
+  const component = resolved.component[0];
+  const states = resolved.states[0];
+  if (!fixture || !component || !states) return;
+  for (const [field, expected] of [["component_record", component.path], ["state_record", states.path]]) {
+    const reference = fixture.value[field];
+    const safe = typeof reference === "string"
+      && reference.length > 0
+      && !path.posix.isAbsolute(reference)
+      && !path.win32.isAbsolute(reference)
+      && !reference.includes("\\")
+      && !reference.includes("?")
+      && !reference.includes("#")
+      && !/^[A-Za-z][A-Za-z\d+.-]*:/.test(reference)
+      && path.posix.normalize(reference) === reference;
+    if (!safe) {
+      failures.push(finding("fixture_reference_invalid", fixture.reference, `${field} must be normalized and profile-local`));
+      continue;
+    }
+    const actual = path.resolve(path.dirname(fixture.path), reference);
+    if (actual !== expected) failures.push(finding("fixture_reference_mismatch", fixture.reference, `${field} does not resolve to the profile-declared record`));
+  }
+  if (fixture.value.profile_id !== component.value.profile_id || fixture.value.profile_id !== states.value.profile_id) {
+    failures.push(finding("profile_identity_mismatch", profileFile, "fixture links cross profile identities"));
+  }
+}
+
+export function resolveProfileRecords(profileRoot, failures) {
+  const profileFile = path.join(profileRoot, "profile.json");
+  if (!fs.existsSync(profileFile) || fs.lstatSync(profileFile).isSymbolicLink() || !fs.lstatSync(profileFile).isFile()) {
+    failures.push(finding("profile_file_invalid", profileFile, "profile.json must be a regular non-symlink file"));
+    return undefined;
+  }
+  let profile;
+  try {
+    profile = parseStrictJson(fs.readFileSync(profileFile, "utf8"));
+  } catch (error) {
+    failures.push(finding("profile_json_invalid", profileFile, error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+  const resolved = {};
+  for (const [kind, definition] of Object.entries(referenceKinds)) {
+    const references = profile[definition.field];
+    if (!Array.isArray(references)) {
+      failures.push(finding("profile_reference_required", profileFile, `${definition.field} must contain exactly ${definition.required} references`));
+      resolved[kind] = [];
+      continue;
+    }
+    if (new Set(references).size !== references.length) failures.push(finding("profile_reference_duplicate", profileFile, `${definition.field} must not repeat references`));
+    if (references.length !== definition.required) failures.push(finding("profile_reference_required", profileFile, `${definition.field} must contain exactly ${definition.required} references`));
+    resolved[kind] = references.map((reference) => resolveReference(profileRoot, reference, kind, profileFile, failures)).filter(Boolean);
+  }
+  for (const record of [resolved.component[0], resolved.evidence[0], resolved.fixture[0], resolved.states[0]].filter(Boolean)) {
+    if (record.value.profile_id !== profile.id) failures.push(finding("profile_identity_mismatch", record.reference, `record profile_id must equal ${profile.id}`));
+  }
+  resolveFixtureLinks(resolved, profileFile, failures);
+  return { profile, profileFile, records: resolved };
+}

package/scripts/promotion-attestation-contract.mjs

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isPlainObject } from "./consumer-reference-schema.mjs";
+import { canonicalGovernedProfilePaths, isIndependentPromotionProfile } from "./governed-profile-registry.mjs";
+
+function finding(code, message, recordPath) {
+  return { code, message, path: recordPath };
+}
+
+function safeProfilePath(relative, profileRoot, recordPath, failures) {
+  if (typeof relative !== "string" || !/^(?!\/)(?!.*\/\/)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?![A-Za-z][A-Za-z0-9+.-]*:)[^\\?#]+\.json$/.test(relative)) {
+    failures.push(finding("promotion_profile_path_invalid", "profile_record must be a normalized repository-relative JSON path", recordPath));
+    return undefined;
+  }
+  const target = path.resolve(profileRoot, relative);
+  if (target === profileRoot || !target.startsWith(`${profileRoot}${path.sep}`)) {
+    failures.push(finding("promotion_profile_path_invalid", "profile_record escapes the repository", recordPath));
+    return undefined;
+  }
+  let current = profileRoot;
+  for (const segment of path.relative(profileRoot, target).split(path.sep)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) {
+      failures.push(finding("promotion_profile_missing", `${relative} does not exist`, recordPath));
+      return undefined;
+    }
+    if (fs.lstatSync(current).isSymbolicLink()) {
+      failures.push(finding("promotion_profile_path_symlink", `${relative} traverses a symlink`, recordPath));
+      return undefined;
+    }
+  }
+  if (!fs.lstatSync(target).isFile()) {
+    failures.push(finding("promotion_profile_invalid", `${relative} must be a regular JSON file`, recordPath));
+    return undefined;
+  }
+  const realRoot = fs.realpathSync(profileRoot);
+  const real = fs.realpathSync(target);
+  if (!real.startsWith(`${realRoot}${path.sep}`) || real !== path.join(realRoot, relative)) {
+    failures.push(finding("promotion_profile_path_invalid", `${relative} resolves outside the repository`, recordPath));
+    return undefined;
+  }
+  return relative;
+}
+
+export function validatePromotionAttestations({ inventory, profileRoot, recordPath, value }) {
+  const attestations = Array.isArray(value.attestations) ? value.attestations : [];
+  const consumers = new Set();
+  const countedContexts = new Set();
+  const countedOrganizations = new Set();
+  const failures = [];
+  const identities = new Set();
+  let eligibleCount = 0;
+  for (const attestation of attestations) {
+    if (!isPlainObject(attestation)) continue;
+    const identity = `${attestation.consumer_id ?? ""}:${attestation.context_id ?? ""}:${attestation.organization_id ?? ""}`;
+    if (identities.has(identity) || consumers.has(attestation.consumer_id)) failures.push(finding("promotion_attestation_duplicate", `duplicate consumer or attestation identity ${identity}`, recordPath));
+    identities.add(identity);
+    consumers.add(attestation.consumer_id);
+    const counted = attestation.count_toward_gate === true;
+    if (attestation.profile_record === undefined) {
+      failures.push(finding("promotion_attestation_profile_required", `${identity} has no canonical repository-local profile record`, recordPath));
+      if (counted) failures.push(finding("promotion_independence_unproven", `${identity} cannot establish counted independence without a profile record`, recordPath));
+      continue;
+    }
+    const registeredPath = safeProfilePath(attestation.profile_record, profileRoot, recordPath, failures);
+    if (!registeredPath) continue;
+    const registered = inventory.records.get(registeredPath);
+    if (!canonicalGovernedProfilePaths.includes(registeredPath) || !registered || registered.failures.length > 0 || inventory.failures.length > 0) {
+      failures.push(finding("promotion_independence_unproven", `${attestation.consumer_id} is not a fully validated registered governed profile`, recordPath));
+      continue;
+    }
+    const profile = registered.profile;
+    if (!isPlainObject(profile)) continue;
+    const identityMatches = profile.id === attestation.consumer_id;
+    if (!identityMatches) failures.push(finding("promotion_profile_identity_mismatch", `${attestation.profile_record} does not match ${attestation.consumer_id}`, recordPath));
+    if (!counted) continue;
+    if (attestation.relationship !== "independent") failures.push(finding("promotion_related_consumer_counted", `${identity} is related and cannot count toward the independent gateway`, recordPath));
+    if (countedOrganizations.has(attestation.organization_id) || countedContexts.has(attestation.context_id)) {
+      failures.push(finding("promotion_independence_unproven", `${identity} does not establish a distinct organization and context`, recordPath));
+    }
+    countedOrganizations.add(attestation.organization_id);
+    countedContexts.add(attestation.context_id);
+    const canonicalIndependent = profile.fixture_independence === "independent" && typeof profile.related_fixture_set_id !== "string";
+    if (!canonicalIndependent) failures.push(finding("promotion_related_consumer_counted", `${attestation.consumer_id} is a canonical related fixture and cannot count`, recordPath));
+    if (identityMatches && attestation.relationship === "independent" && canonicalIndependent && isIndependentPromotionProfile(profile)) eligibleCount += 1;
+    else if (identityMatches && canonicalIndependent && !isIndependentPromotionProfile(profile)) {
+      failures.push(finding("promotion_independence_unproven", `${attestation.consumer_id} is not lifecycle- and scope-eligible independent adoption evidence`, recordPath));
+    }
+  }
+  return { eligibleCount, failures };
+}

package/scripts/promotion-boundary-test-contract.mjs

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function copyTreeNoSymlinks(source, target) {
+  fs.cpSync(source, target, { recursive: true, filter: (candidate) => {
+    if (fs.lstatSync(candidate).isSymbolicLink()) throw new Error(`refusing to copy symlink ${candidate}`);
+    return true;
+  } });
+}
+
+function copyFixtureRoot(fixtureRoot, tempRoot, name) {
+  const root = path.join(tempRoot, name);
+  copyTreeNoSymlinks(fixtureRoot, root);
+  return root;
+}
+
+function editJson(file, mutate) {
+  const value = JSON.parse(fs.readFileSync(file, "utf8"));
+  mutate(value);
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function result(runArguments, name, args, expected) {
+  const child = runArguments(args);
+  const codes = child.report.failures.map((failure) => failure.code);
+  return { actual: { codes, status: child.status }, expected, name, ok: child.status > 0 && codes.includes(expected) };
+}
+
+export function testPromotionBoundaries({ fixtureRoot, repositoryRoot, runArguments, tempRoot }) {
+  const results = [];
+  for (const [name, args] of [["file_option_value", ["--file", "--json"]], ["policy_option_value", ["--policy", "--json"]], ["profile_root_option_value", ["--profile-repository-root", "--json"]]]) {
+    results.push(result(runArguments, name, args, "argument_value_required"));
+  }
+  const yamlRfc = path.join(tempRoot, "promotion.yaml");
+  const yamlPolicy = path.join(tempRoot, "policy.yaml");
+  fs.copyFileSync(path.join(fixtureRoot, "valid-deferred-example.json"), yamlRfc);
+  fs.copyFileSync(path.join(repositoryRoot, "consumer-reference/policies/shared-experimental.json"), yamlPolicy);
+  results.push(result(runArguments, "rfc_yaml_extension", ["--file", yamlRfc, "--json"], "promotion_json_path_required"));
+  results.push(result(runArguments, "policy_yaml_extension", ["--policy", yamlPolicy, "--json"], "promotion_json_path_required"));
+
+  const linkedRfc = path.join(tempRoot, "linked-rfc.json");
+  const linkedPolicy = path.join(tempRoot, "linked-policy.json");
+  fs.symlinkSync(path.join(fixtureRoot, "valid-deferred-example.json"), linkedRfc);
+  fs.symlinkSync(path.join(repositoryRoot, "consumer-reference/policies/shared-experimental.json"), linkedPolicy);
+  results.push(result(runArguments, "rfc_symlink", ["--file", linkedRfc, "--json"], "promotion_input_path_invalid"));
+  results.push(result(runArguments, "policy_symlink", ["--policy", linkedPolicy, "--json"], "promotion_input_path_invalid"));
+
+  for (const [name, mutate] of [
+    ["inventory_extra_json", (root) => fs.copyFileSync(path.join(fixtureRoot, "valid-deferred-example.json"), path.join(root, "extra.json"))],
+    ["inventory_extra_yaml", (root) => fs.copyFileSync(path.join(fixtureRoot, "valid-deferred-example.json"), path.join(root, "extra.yaml"))],
+    ["inventory_missing", (root) => fs.rmSync(path.join(root, "invalid-count-only.json"))],
+    ["inventory_duplicate", (root) => editJson(path.join(root, "manifest.json"), (value) => value.valid_records.push(value.valid_records[0]))],
+  ]) {
+    const root = copyFixtureRoot(fixtureRoot, tempRoot, name);
+    mutate(root);
+    results.push(result(runArguments, name, ["--promotion-fixture-root", root, "--json"], "promotion_fixture_inventory_invalid"));
+  }
+
+  const rejectedRoot = copyFixtureRoot(fixtureRoot, tempRoot, "canonical-rejected");
+  editJson(path.join(rejectedRoot, "valid-deferred-example.json"), (value) => { value.decision = "rejected"; });
+  results.push(result(runArguments, "canonical_rejected", ["--promotion-fixture-root", rejectedRoot, "--json"], "promotion_canonical_example_invalid"));
+  const attestedRoot = copyFixtureRoot(fixtureRoot, tempRoot, "canonical-attested");
+  editJson(path.join(attestedRoot, "valid-deferred-example.json"), (value) => { value.attestations = [{ attested_by: "Synthetic", context_id: "test", consumer_id: "fake", count_toward_gate: false, organization_id: "test", relationship: "related" }]; });
+  results.push(result(runArguments, "canonical_attested", ["--promotion-fixture-root", attestedRoot, "--json"], "promotion_canonical_example_invalid"));
+
+  const unbound = path.join(tempRoot, "unbound.json");
+  const duplicateEvidence = path.join(tempRoot, "duplicate-evidence.json");
+  fs.copyFileSync(path.join(fixtureRoot, "valid-deferred-example.json"), unbound);
+  editJson(unbound, (value) => { value.attestations = [{ attested_by: "Synthetic", context_id: "test", consumer_id: "fake", count_toward_gate: false, organization_id: "test", relationship: "related" }]; });
+  fs.copyFileSync(path.join(fixtureRoot, "valid-deferred-example.json"), duplicateEvidence);
+  editJson(duplicateEvidence, (value) => { value.evidence.push(structuredClone(value.evidence[0])); });
+  results.push(result(runArguments, "unbound_uncounted", ["--file", unbound, "--json"], "promotion_attestation_profile_required"));
+  results.push(result(runArguments, "duplicate_evidence_id", ["--file", duplicateEvidence, "--json"], "promotion_evidence_duplicate"));
+  results.push(result(runArguments, "missing_profile_root", ["--file", path.join(fixtureRoot, "valid-deferred-example.json"), "--profile-repository-root", path.join(tempRoot, "missing-root"), "--json"], "promotion_profile_registry_invalid"));
+  const linkedProfileRoot = path.join(tempRoot, "linked-profile-root");
+  fs.symlinkSync(repositoryRoot, linkedProfileRoot);
+  results.push(result(runArguments, "symlink_profile_root", ["--file", path.join(fixtureRoot, "valid-deferred-example.json"), "--profile-repository-root", linkedProfileRoot, "--json"], "promotion_profile_registry_invalid"));
+  const linkedManifestRoot = copyFixtureRoot(fixtureRoot, tempRoot, "linked-manifest-root");
+  fs.rmSync(path.join(linkedManifestRoot, "manifest.json"));
+  fs.symlinkSync(path.join(fixtureRoot, "manifest.json"), path.join(linkedManifestRoot, "manifest.json"));
+  results.push(result(runArguments, "symlink_manifest", ["--promotion-fixture-root", linkedManifestRoot, "--json"], "promotion_fixture_inventory_invalid"));
+
+  const strictRoot = path.join(tempRoot, "strict-profile-root");
+  copyTreeNoSymlinks(path.join(repositoryRoot, "design-engineering/reference-profiles/governed-local"), path.join(strictRoot, "design-engineering/reference-profiles/governed-local"));
+  const foundations = path.join(strictRoot, "design-engineering/reference-profiles/governed-local/editorial/local-foundations.json");
+  fs.writeFileSync(foundations, fs.readFileSync(foundations, "utf8").replace('"identity":', '"identity":"Duplicate",\n  "identity":'));
+  const counted = path.join(tempRoot, "strict-counted.json");
+  fs.copyFileSync(path.join(fixtureRoot, "valid-deferred-example.json"), counted);
+  editJson(counted, (value) => { value.attestations = [{ attested_by: "Synthetic", context_id: "editorial", consumer_id: "editorial-reference-profile", count_toward_gate: true, organization_id: "test", profile_record: "design-engineering/reference-profiles/governed-local/editorial/profile.json", relationship: "independent" }]; });
+  results.push(result(runArguments, "duplicate_foundation_identity", ["--file", counted, "--profile-repository-root", strictRoot, "--json"], "promotion_independence_unproven"));
+  return results;
+}

package/scripts/promotion-fixture-inventory.mjs

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseStrictJson } from "./strict-json.mjs";
+
+const validRecords = Object.freeze(["valid-deferred-example.json", "valid-normative-bypass.json"]);
+const invalidRecords = Object.freeze([
+  ["invalid-blocking-evidence.json", "promotion_blocking_evidence_failed"],
+  ["invalid-count-only.json", "promotion_count_only_forbidden"],
+  ["invalid-missing-owner-migration.json", "promotion_owner_migration_required"],
+  ["invalid-normative-bypass-no-regression.json", "promotion_normative_regression_required"],
+  ["invalid-related-counted-independent.json", "promotion_related_consumer_counted"],
+  ["invalid-stable-ended-support.json", "stable_support_ended"],
+]);
+const policyRecord = "consumer-reference/policies/shared-experimental.json";
+const schemaRecord = "consumer-reference/schema/promotion-rfc.schema.json";
+
+function finding(code, message, recordPath) {
+  return { code, message, path: recordPath };
+}
+
+function isInside(base, target) {
+  const relative = path.relative(base, target);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function resolveContained({ code, expectedType, repositoryRoot, target }, failures) {
+  const root = path.resolve(repositoryRoot);
+  const resolved = path.resolve(target);
+  const recordPath = path.relative(root, resolved) || resolved;
+  if (!isInside(root, resolved) || !fs.existsSync(resolved)) {
+    failures.push(finding(code, "promotion input must exist inside the repository", recordPath));
+    return undefined;
+  }
+  if (fs.realpathSync(root) !== root) {
+    failures.push(finding(code, "repository root must not be a filesystem redirect", recordPath));
+    return undefined;
+  }
+  let current = root;
+  for (const segment of path.relative(root, resolved).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (fs.lstatSync(current).isSymbolicLink()) {
+      failures.push(finding(code, "promotion input must not traverse a symlink", recordPath));
+      return undefined;
+    }
+  }
+  const metadata = fs.lstatSync(resolved);
+  if ((expectedType === "file" && !metadata.isFile()) || (expectedType === "directory" && !metadata.isDirectory()) || fs.realpathSync(resolved) !== resolved) {
+    failures.push(finding(code, `promotion input must be a contained regular ${expectedType}`, recordPath));
+    return undefined;
+  }
+  return resolved;
+}
+
+export function resolvePromotionJsonFile({ file, repositoryRoot }, failures) {
+  const recordPath = path.relative(repositoryRoot, path.resolve(file)) || file;
+  if (path.extname(file) !== ".json") {
+    failures.push(finding("promotion_json_path_required", "promotion records must use the .json extension", recordPath));
+    return undefined;
+  }
+  return resolveContained({ code: "promotion_input_path_invalid", expectedType: "file", repositoryRoot, target: file }, failures);
+}
+
+function sameSet(actual, expected) {
+  return Array.isArray(actual) && actual.length === expected.length && new Set(actual).size === expected.length && expected.every((entry) => actual.includes(entry));
+}
+
+function validManifest(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const keys = ["id", "invalid_records", "policy_record", "schema_record", "schema_version", "valid_records"];
+  if (!sameSet(Object.keys(value), keys) || value.id !== "promotion-fixture-inventory" || value.schema_version !== "1.0" || value.policy_record !== policyRecord || value.schema_record !== schemaRecord || !sameSet(value.valid_records, validRecords)) return false;
+  if (!Array.isArray(value.invalid_records) || value.invalid_records.length !== invalidRecords.length) return false;
+  const encoded = value.invalid_records.map((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry) && sameSet(Object.keys(entry), ["expected_code", "file"]) ? `${entry.file}:${entry.expected_code}` : "");
+  return sameSet(encoded, invalidRecords.map(([file, code]) => `${file}:${code}`));
+}
+
+export function loadPromotionFixtureInventory({ fixtureRoot, repositoryRoot }) {
+  const failures = [];
+  const root = resolveContained({ code: "promotion_fixture_inventory_invalid", expectedType: "directory", repositoryRoot, target: fixtureRoot }, failures);
+  if (!root) return { failures, invalidRecords: [], policyFile: undefined, schema: undefined, validFiles: [] };
+  const manifestFile = resolveContained({ code: "promotion_fixture_inventory_invalid", expectedType: "file", repositoryRoot, target: path.join(root, "manifest.json") }, failures);
+  let manifest;
+  try {
+    if (manifestFile) manifest = parseStrictJson(fs.readFileSync(manifestFile, "utf8"));
+  } catch (error) {
+    failures.push(finding("promotion_fixture_inventory_invalid", error instanceof Error ? error.message : String(error), path.relative(repositoryRoot, manifestFile)));
+  }
+  if (!validManifest(manifest)) failures.push(finding("promotion_fixture_inventory_invalid", "promotion manifest must match the canonical closed inventory", path.relative(repositoryRoot, manifestFile ?? root)));
+  const expectedFiles = ["manifest.json", ...validRecords, ...invalidRecords.map(([file]) => file)];
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  if (!sameSet(entries.map((entry) => entry.name), expectedFiles) || entries.some((entry) => !entry.isFile() || path.extname(entry.name) !== ".json")) {
+    failures.push(finding("promotion_fixture_inventory_invalid", "promotion fixture directory must contain only the declared JSON closed set", path.relative(repositoryRoot, root)));
+  }
+  for (const file of expectedFiles) resolveContained({ code: "promotion_fixture_inventory_invalid", expectedType: "file", repositoryRoot, target: path.join(root, file) }, failures);
+  const policyFile = resolveContained({ code: "promotion_fixture_inventory_invalid", expectedType: "file", repositoryRoot, target: path.join(repositoryRoot, policyRecord) }, failures);
+  const schemaFile = resolveContained({ code: "promotion_fixture_inventory_invalid", expectedType: "file", repositoryRoot, target: path.join(repositoryRoot, schemaRecord) }, failures);
+  let schema;
+  try {
+    if (schemaFile) schema = parseStrictJson(fs.readFileSync(schemaFile, "utf8"));
+  } catch (error) {
+    failures.push(finding("promotion_fixture_inventory_invalid", error instanceof Error ? error.message : String(error), schemaRecord));
+  }
+  return {
+    failures: [...new Map(failures.map((issue) => [`${issue.code}:${issue.path}:${issue.message}`, issue])).values()],
+    invalidRecords: invalidRecords.map(([file, expectedCode]) => ({ expectedCode, file: path.join(root, file) })),
+    policyFile,
+    schema,
+    validFiles: validRecords.map((file) => path.join(root, file)),
+  };
+}

package/scripts/promotion-governance-contract.mjs

@@ -0,0 +1,28 @@
+const requirements = [
+  ["GOVERNANCE.md", "The StyleGallery-local `>=2` independent-consumer gateway applies only to consumer-local → shared-experimental invariant eligibility."],
+  ["GOVERNANCE.md", "Shared stable has no numeric adoption threshold"],
+  ["GOVERNANCE.md", "may waive adoption count only"],
+  ["GOVERNANCE.md", "zero durable adopter attestations and record no promotion"],
+  ["GOVERNANCE.md", "never be silently relabeled shared-experimental"],
+  ["DOMAINS.md", "### Consumer Reference Promotion"],
+  ["DOMAINS.md", "Promotion records are JSON-only"],
+  ["consumer-reference/contract.md", "They are not accepted or promoted RFCs."],
+  ["consumer-reference/contract.md", "boolean aliases are invalid"],
+  ["consumer-reference/index.md", "[Promotion RFC schema](schema/promotion-rfc.schema.json)"],
+  ["consumer-reference/index.md", "[Shared-experimental promotion policy](policies/shared-experimental.json)"],
+  ["consumer-reference/fixtures/promotion/manifest.json", '"id": "promotion-fixture-inventory"'],
+  ["quality/evidence/executable-evidence.md", "Promotion governance remains a closed JSON-only, invariant-scoped, deferred example contract."],
+  ["quality/evidence/executable-evidence.md", "Synthetic validation does not authenticate adoption, organizations, owners, support capacity, provenance, or a promotion decision"],
+  [".github/workflows/validate.yml", "node -c scripts/promotion-fixture-inventory.mjs"],
+  [".github/workflows/validate.yml", "node -c scripts/promotion-boundary-test-contract.mjs"],
+  ["consumer-reference/policies/shared-experimental.json", '"review_independence": "single_account"'],
+  ["consumer-reference/policies/shared-experimental.json", '"promotion_occurred": false'],
+  ["consumer-reference/policies/shared-experimental.json", '"adopter_attestations": 0'],
+  ["consumer-reference/policies/shared-experimental.json", '"stable_numeric_threshold": null'],
+];
+
+export function promotionGovernanceFailures(read) {
+  return requirements
+    .filter(([relative, text]) => !read(relative).includes(text))
+    .map(([relative, text]) => `${relative}: missing ${text}`);
+}

package/scripts/reference-artifact-path-contract.mjs

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function isContained(root, target) {
+  const relative = path.relative(root, target);
+  return relative !== "" && !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+
+export function inspectArtifactPath(root, candidate, allowMissing) {
+  const trustedRoot = fs.realpathSync(root);
+  const target = path.resolve(root, candidate);
+  if (!isContained(trustedRoot, target)) return { ok: false, path: target, reason: "outside_trust_root" };
+
+  const segments = path.relative(trustedRoot, target).split(path.sep);
+  let current = trustedRoot;
+  for (const [index, segment] of segments.entries()) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) {
+      return allowMissing ? { ok: true, path: target } : { ok: false, path: target, reason: "missing" };
+    }
+    const metadata = fs.lstatSync(current);
+    if (metadata.isSymbolicLink()) return { ok: false, path: target, reason: "symbolic_link" };
+    const finalSegment = index === segments.length - 1;
+    if (finalSegment && !metadata.isFile()) return { ok: false, path: target, reason: "not_regular_file" };
+    if (!finalSegment && !metadata.isDirectory()) return { ok: false, path: target, reason: "parent_not_directory" };
+  }
+  return { ok: true, path: target };
+}

package/scripts/reference-profile-contract.mjs

@@ -0,0 +1,114 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { isPlainObject } from "./consumer-reference-schema.mjs";
+import { validatePortableTokens } from "./reference-token-contract.mjs";
+import { parseStrictJson } from "./strict-json.mjs";
+
+const layoutSourceSha = "775430bbaf4ee208a642220f440f6926d79c90a3";
+const requiredResetFields = ["body_margin", "box_sizing", "figure_margin"];
+
+function hash(content) {
+  return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
+}
+
+function finding(code, relative, message) {
+  return { code, message, path: relative };
+}
+
+function isInside(base, target) {
+  const relative = path.relative(base, target);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function readJson({ failures, kind, relative, root }) {
+  const absolute = path.resolve(root, relative);
+  if (!fs.existsSync(absolute)) {
+    failures.push(finding(`${kind}_unresolved`, relative, "profile artifact must exist beside profile.json"));
+    return null;
+  }
+  const realRoot = fs.realpathSync(root);
+  const realTarget = fs.realpathSync(absolute);
+  if (!isInside(realRoot, realTarget)) {
+    failures.push(finding(`${kind}_symlink_escape`, relative, "profile artifact resolves outside the repository root"));
+    return null;
+  }
+  if (realTarget !== path.join(realRoot, relative)) {
+    failures.push(finding(`${kind}_redirect`, relative, "profile artifact must remain at its exact sibling path"));
+    return null;
+  }
+  if (!fs.statSync(realTarget).isFile()) {
+    failures.push(finding(`${kind}_type_invalid`, relative, "profile artifact must be a regular JSON file"));
+    return null;
+  }
+  const bytes = fs.readFileSync(realTarget);
+  try {
+    return { bytes, value: parseStrictJson(bytes.toString("utf8")) };
+  } catch (error) {
+    failures.push(finding(`${kind}_json_invalid`, relative, error instanceof Error ? error.message : String(error)));
+    return null;
+  }
+}
+
+export function validateReferenceProfile({ item, relative, root }) {
+  const failures = [];
+  const add = (code, message) => failures.push(finding(code, relative, message));
+  if (item.profile_kind !== "governed_local") add("profile_kind_governed_local", "profile_kind must be governed_local");
+  if (item.artifact_mode !== "governed_local") add("profile_artifact_mode_governed_local", "governed-local profiles cannot be external consumers");
+  if (item.maturity !== "experimental") add("profile_maturity_experimental", "governed-local profiles must remain experimental");
+  if (item.example_only !== true) add("profile_example_only_required", "governed-local profiles must be example_only");
+  if (item.default !== false) add("profile_default_forbidden", "governed-local profiles cannot be implicit or default");
+  if (item.layout_source_sha !== layoutSourceSha) add("profile_layout_source_sha_required", `layout_source_sha must pin ${layoutSourceSha}`);
+  if (typeof item.related_fixture_set_id !== "string" || item.related_fixture_set_id.length === 0) add("profile_related_fixture_set_required", "related_fixture_set_id is required");
+  if (!isPlainObject(item.selection) || item.selection.required !== true || item.selection.method !== "profile_path") add("profile_explicit_selection_required", "selection must require an explicit profile_path");
+  if (!isPlainObject(item.environment_assumptions) || typeof item.environment_assumptions.user_agent_styles !== "string" || item.environment_assumptions.user_agent_styles.length === 0) {
+    add("profile_ua_assumption_required", "user-agent style assumptions must be explicit");
+  }
+  const reset = isPlainObject(item.environment_assumptions) ? item.environment_assumptions.reset : null;
+  if (!isPlainObject(reset) || requiredResetFields.some((field) => typeof reset[field] !== "string" || reset[field].length === 0)) {
+    add("profile_reset_assumptions_required", "body, box-sizing, and figure reset assumptions must be explicit");
+  }
+  if (item.tokens !== "tokens.dtcg.json") add("profile_tokens_path_required", "tokens must resolve to the sibling tokens.dtcg.json");
+  if (item.local_foundations !== "local-foundations.json") add("profile_foundations_path_required", "foundations must resolve to the sibling local-foundations.json");
+
+  const directory = path.posix.dirname(relative);
+  const tokenRelative = path.posix.join(directory, "tokens.dtcg.json");
+  const foundationRelative = path.posix.join(directory, "local-foundations.json");
+  const tokenDocument = readJson({ failures, kind: "profile_tokens", relative: tokenRelative, root });
+  const foundations = readJson({ failures, kind: "profile_foundations", relative: foundationRelative, root });
+  if (tokenDocument) {
+    for (const tokenFailure of validatePortableTokens(tokenDocument.value).failures) {
+      failures.push(finding(tokenFailure.code, tokenRelative, tokenFailure.message));
+    }
+  }
+  if (foundations) {
+    if (!isPlainObject(foundations.value)
+      || foundations.value.profile_id !== item.id
+      || typeof foundations.value.identity !== "string"
+      || !isPlainObject(foundations.value.bindings)) {
+      failures.push(finding("profile_foundations_invalid", foundationRelative, "foundations require matching profile_id, identity, and bindings"));
+    }
+  }
+
+  const summary = tokenDocument && foundations ? {
+    foundationHash: hash(foundations.bytes),
+    id: item.id,
+    identity: foundations.value.identity,
+    layoutSourceSha: item.layout_source_sha,
+    relatedFixtureSetId: item.related_fixture_set_id,
+    tokenHash: hash(tokenDocument.bytes),
+  } : null;
+  return { failures, summary };
+}
+
+export function validateReferenceProfileSet(summaries) {
+  if (summaries.length < 2) return [];
+  const failures = [];
+  const unique = (field) => new Set(summaries.map((summary) => summary[field])).size;
+  if (unique("layoutSourceSha") !== 1) failures.push(finding("profile_layout_source_mismatch", "<profiles>", "profiles must share one Layout source SHA"));
+  if (unique("relatedFixtureSetId") !== 1) failures.push(finding("profile_related_set_mismatch", "<profiles>", "profiles must share one related fixture set"));
+  if (unique("identity") !== summaries.length) failures.push(finding("profile_identity_not_distinct", "<profiles>", "adversarial profiles must declare distinct identities"));
+  if (unique("tokenHash") !== summaries.length) failures.push(finding("profile_tokens_not_distinct", "<profiles>", "adversarial profiles must have distinct token bytes"));
+  if (unique("foundationHash") !== summaries.length) failures.push(finding("profile_foundations_not_distinct", "<profiles>", "adversarial profiles must have distinct foundation bytes"));
+  return failures;
+}