@nextcommerce/campaigns-os 1.60.0 → 1.61.0

package/src/doctor/inspect.mjs

@@ -1,5 +1,6 @@
 // Doctor entry points: the doctor command, packet inspection and built-output inspection.
 import { resolveCampaignIdentity } from "../spec-source-identity.mjs";
+import { assessDoctorCi, doctorCiFailure } from "./ci.mjs";
 import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD } from "../local-preview-policy.mjs";
 import { withHtmlScanSnapshot } from "../html-scan.mjs";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -132,6 +133,13 @@ export async function readDoctorLiveCampaign(args, { fetchImpl = globalThis.fetc
 }
 
 export function doctorCommand(args, { runDoctor = doctorPacket, liveCampaign = undefined, qcStandIns = undefined } = {}) {
+  if (args.ci === true) {
+    try {
+      JSON.parse(readFileSync(resolve(requireArg(args, "packet")), "utf8"));
+    } catch (error) {
+      return doctorCiFailure(error, { usage: true });
+    }
+  }
   // Non-packet mode (learnings L7): doctor a `campaign-build`'d page-kit
   // campaign that has only a built _site/ and no full Build Packet. Resolves
   // scope from the built output and runs the built-output residue/text/
@@ -153,6 +161,16 @@ export function doctorCommand(args, { runDoctor = doctorPacket, liveCampaign = u
     ...(qcStandIns !== undefined ? { qcStandIns } : {}),
   };
   const result = runDoctor(packetPath, doctorOptions);
+  if (args.ci === true) {
+    // Use precisely the context/report selection that inspection used,
+    // including explicit sidecar suppression and the context's report binding.
+    const workspace = resolveCampaignWorkspace(packetPath, {
+      contextPath: doctorOptions.contextPath,
+      reportPath: doctorOptions.reportPath,
+      followContextPointer: true,
+    });
+    result.ci = assessDoctorCi({ packet: workspace.packet, packetPath, report: readJsonIfExists(workspace.reportPath) });
+  }
   // Inspection and recording are separate operations. A laptop's untracked
   // built output can be stale while the delivered build's evidence is valid.
   // Only an explicit producer action may replace the retained proof artifacts;

package/src/doctor/source-provenance.mjs

@@ -18,6 +18,7 @@
 // validity, wrapper policy, screenshot proof) is evaluated elsewhere and is
 // untouched by this gate.
 
+import { SOURCE_HASH_PATTERN } from "../source-html-manifest.mjs";
 import {
   assessCheckpointWaivers,
   checkpointStateFingerprint,
@@ -182,3 +183,76 @@ export function evaluateSourceProvenanceGates({ pages = [], blockingCodes = [],
 
   return { gates, inert: { counts, pages: inertPages } };
 }
+
+// Returns every Figma-provenance finding in emission order, each tagged with
+// its severity: "provenance" (the waivable source_html.producer_provenance*
+// and source_html.files.partial/asset blockers) or "warning".
+export function collectFigmaProvenanceFindings(manifest, provenance = manifest?.producer_provenance || {}, rawProvenance = manifest?.producer_provenance) {
+  const findings = [];
+  const add = (severity, code, message) => findings.push({ severity, code, message });
+  if (!rawProvenance) {
+    add(
+      "provenance",
+      "source_html.producer_provenance",
+      "Figma source manifest is missing producer_provenance. Re-run figma-sections-export handoff so Campaigns OS can gate semantic exporter provenance before assembly."
+    );
+  }
+
+  if (provenance.source_type !== "semantic_figma_export") {
+    add(
+      "provenance",
+      "source_html.producer_provenance.source_type",
+      `Figma source manifest source_type is "${provenance.source_type || "missing"}"; expected "semantic_figma_export". Screenshot or hand-authored fallback output cannot satisfy the Figma provenance gate.`
+    );
+  }
+  if (provenance.screenshot_fallback_used !== false) {
+    add(
+      "provenance",
+      "source_html.producer_provenance.screenshot_fallback_used",
+      "Figma source manifest reports screenshot_fallback_used=true. Re-run semantic figma-sections-export before assembly."
+    );
+  }
+  if (!Number.isInteger(provenance.semantic_section_count) || provenance.semantic_section_count <= 0) {
+    add(
+      "provenance",
+      "source_html.producer_provenance.semantic_section_count",
+      "Figma source manifest must report semantic_section_count > 0."
+    );
+  }
+  if (!SOURCE_HASH_PATTERN.test(String(provenance.material_fingerprint || ""))) {
+    add(
+      "provenance",
+      "source_html.producer_provenance.material_fingerprint",
+      "Figma source manifest must include a 64-character material_fingerprint over the handed-off source package."
+    );
+  }
+
+  const files = Array.isArray(manifest?.files) ? manifest.files : [];
+  if (!files.some((entry) => entry.role === "partial")) {
+    add("provenance", "source_html.files.partial", "Figma source manifest files[] must include section partials.");
+  }
+  if (!files.some((entry) => entry.role === "asset")) {
+    add("provenance", "source_html.files.asset", "Figma source manifest files[] must include exported assets.");
+  }
+
+  const sectionExports = Array.isArray(provenance.section_exports) ? provenance.section_exports : [];
+  if (!sectionExports.length) {
+    add("provenance", "source_html.producer_provenance.section_exports", "Figma source manifest must include section_exports with Figma node IDs and extraction commands.");
+  } else {
+    const withoutNodeIds = sectionExports
+      .filter((entry) => {
+        const nodeIds = isPlainObject(entry?.node_ids) ? entry.node_ids : null;
+        return !nodeIds || !Object.keys(nodeIds).length;
+      })
+      .map((entry) => entry?.section || "unknown");
+    if (withoutNodeIds.length) {
+      add(
+        "warning",
+        "source_html.producer_provenance.section_exports.node_ids",
+        `Some Figma section exports do not list node_ids: ${withoutNodeIds.slice(0, 6).join(", ")}${withoutNodeIds.length > 6 ? ", ..." : ""}.`
+      );
+    }
+  }
+
+  return findings;
+}

package/src/evidence-debt.mjs

@@ -0,0 +1,119 @@
+// Read-only build binding projection, shared by readback and other readers.
+// No stage verdicts, clocks, Git metadata, processes, writes or network calls.
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import {
+  computeBuildFingerprint,
+  describeBuildOutputDrift,
+  pageIdForRoute,
+  resolveBuiltSiteScope,
+  routeForFile,
+} from "./built-site-scope.mjs";
+import { normalizePublicRouteSlug } from "./route-identity.mjs";
+import { isFileReadFailure } from "./cart-placeholders.mjs";
+import { qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "./stage-ledger.mjs";
+
+export const EVIDENCE_DEBT_STATUSES = Object.freeze(["current", "owed", "unknown"]);
+
+const fingerprint = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+const portable = (value) => value.split(sep).join("/");
+
+/**
+ * Compare recorded Polish/QA build bindings with bytes under _site/<slug>.
+ * `changes` is explicitly against the assembly manifest, which need not be
+ * the build an older stage reviewed. We cannot reconstruct an older manifest.
+ * Missing build inputs remain unknown; lifecycle-required stages are owed
+ * even without a stage binding. A matching binding alone is not a verdict.
+ */
+export function assessEvidenceDebt({ packet = null, packetPath = null, report = null } = {}) {
+  const assembly = report?.stages?.assembly;
+  const recordedBuild = fingerprint(assembly?.build_fingerprint);
+  // Match polish-gate's sourceBuildFingerprint precedence without reading the
+  // capture package (often absent in a fresh checkout).
+  const polishBuild = fingerprint(report?.stages?.polish?.source_build_fingerprint)
+    || fingerprint(report?.stages?.polish?.evidence?.source_build_fingerprint);
+  const qaBuild = qaRecordedBuildFingerprint(report);
+  let current = null;
+  let scope = null;
+  let outputRoot = null;
+  let reason = null;
+  let scopeReason = null;
+  const target = fingerprint(packet?.assembly?.target_repo);
+  const slug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  if (!packet || !packetPath) reason = "packet_unavailable";
+  else if (!target || !slug) reason = "build_output_location_unknown";
+  else {
+    const targetRepo = resolve(dirname(resolve(packetPath)), target);
+    outputRoot = join(targetRepo, "_site", slug);
+    try {
+      current = computeBuildFingerprint(outputRoot);
+      if (!current.ok) reason = "build_output_missing";
+      // Resolve only the chosen built directory: never discover another
+      // campaign, or fall back to source HTML when _site is absent.
+      else {
+        scope = resolveBuiltSiteScope(outputRoot);
+        if (!scope.ok) scopeReason = "build_output_pages_unresolved";
+      }
+    } catch (error) {
+      if (!isFileReadFailure(error)) throw error;
+      reason = "build_output_unreadable";
+      current = null;
+    }
+  }
+  const currentBuild = current?.ok ? current.fingerprint : null;
+  const drift = currentBuild ? describeBuildOutputDrift(assembly, current) : null;
+  const manifestKnown = drift?.manifest === "recorded";
+  // A missing manifest hides page changes, never a known stage binding.
+  const bindingReason = reason || (!recordedBuild ? "assembly_build_fingerprint_missing" : null);
+  const changesReason = bindingReason || scopeReason || (!manifestKnown ? "build_manifest_unavailable" : null);
+  const stage = (stageRecord, recorded, matches) => {
+    // src/stage-record.mjs writes required_by: build; the dependency map in
+    // src/input-currency.mjs supplies brief/spec for input-change demotions.
+    // This is lifecycle debt even when retained evidence matches the output.
+    const required = stageRecord?.status === "required";
+    const requiredReason = ["build", "brief", "spec"].includes(stageRecord?.required_by)
+      ? `stage_required_by_${stageRecord.required_by}` : "stage_required";
+    return {
+      status: bindingReason ? "unknown" : required ? "owed" : !recorded ? "unknown" : matches ? "current" : "owed",
+      matches_current_build: recorded && currentBuild ? matches : null,
+      recorded_build_fingerprint: recorded,
+      current_build_fingerprint: currentBuild,
+      reason: bindingReason || (required ? requiredReason : !recorded ? "stage_build_fingerprint_missing" : matches ? null : "build_fingerprint_changed"),
+    };
+  };
+
+  const changes = {
+    status: changesReason ? "unknown" : "known",
+    reason: changesReason,
+    recorded_build_fingerprint: recordedBuild,
+    current_build_fingerprint: currentBuild,
+    changed_pages: [],
+    unmapped_files: [],
+    extra: manifestKnown ? drift.extra : [],
+    missing: manifestKnown ? drift.missing : [],
+    changed: manifestKnown ? drift.changed : [],
+  };
+  if (manifestKnown && scope?.ok) {
+    const pages = new Map((scope?.pages || []).map((page) => [
+      portable(relative(outputRoot, page.built_path)),
+      { page_id: page.page_id, built_path: portable(relative(outputRoot, page.built_path)) },
+    ]));
+    // Deleted HTML no longer appears in the disk map. Reuse its route/id
+    // projection for those manifest entries, without reading nonexistent files.
+    for (const path of drift.missing) {
+      if (!path.toLowerCase().endsWith(".html") || path.split("/").some((part) => part.startsWith(".") || part.startsWith("_") || part === "node_modules")) continue;
+      pages.set(path, { page_id: pageIdForRoute(routeForFile(outputRoot, join(outputRoot, path))), built_path: path });
+    }
+    const paths = [...new Set([...drift.extra, ...drift.missing, ...drift.changed])].sort();
+    for (const path of paths) {
+      const page = pages.get(path);
+      if (page) changes.changed_pages.push(page);
+      else changes.unmapped_files.push(path);
+    }
+  }
+  return {
+    polish: stage(report?.stages?.polish, polishBuild, Boolean(polishBuild && currentBuild && polishBuild === currentBuild)),
+    qa: stage(report?.stages?.qa, qaBuild, qaRecordedForCurrentBuild(report, currentBuild)),
+    changes,
+  };
+}

package/src/parity/compare.mjs

@@ -0,0 +1,316 @@
+// Pure element parity comparison, implemented from Appendix A of the P contract.
+export const PARITY_COMPARATOR_VERSION = "parity-compare/v1";
+export const PARITY_TOLERANCES = Object.freeze({
+  position_px: 6, size_px: 6, gap_px: 6,
+  font_size_px: 0.6, line_height_px: 2, letter_spacing_px: 0.2,
+  color_channel: 3, fuzzy_jaccard: 0.6, missing_copy_min_chars: 4,
+});
+export const PARITY_PROBE_LIMITS = Object.freeze({
+  elements: 1500, text_chars: 500, page_text_chars: 262144, font_faces: 200, selector_path_chars: 2048,
+});
+
+const plain = (v) => v !== null && typeof v === "object"
+  && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+const finite = (v) => typeof v === "number" && Number.isFinite(v);
+const nonnegative = (v) => finite(v) && v >= 0;
+// Rule 0 (A-P4): box values stay within ±1e6 px so drift and distances stay finite.
+const coordinate = (v) => finite(v) && Math.abs(v) <= 1e6;
+const extent = (v) => coordinate(v) && v >= 0;
+const integer = (v, min = 0) => Number.isInteger(v) && v >= min;
+const boundedText = (v, max) => typeof v === "string" && [...v].length <= max;
+const normalOr = (v, numberTest) => v === "normal" || numberTest(v);
+const color = (v) => v === null || (Array.isArray(v) && v.length === 3
+  && [...v].every((n) => finite(n) && n >= 0 && n <= 1));
+
+export function isProbeOutput(v) {
+  if (!plain(v) || !plain(v.viewport) || !integer(v.viewport.width, 1) || !integer(v.viewport.height, 1)
+    || !finite(v.dpr) || v.dpr <= 0 || !Array.isArray(v.elements)
+    || v.elements.length > PARITY_PROBE_LIMITS.elements
+    || !boundedText(v.page_text, PARITY_PROBE_LIMITS.page_text_chars)
+    || !Array.isArray(v.font_faces) || v.font_faces.length > PARITY_PROBE_LIMITS.font_faces
+    || !plain(v.coverage)) return false;
+  if (!["elements_capped", "time_capped", "page_text_truncated", "font_faces_capped"]
+    .every((k) => typeof v.coverage[k] === "boolean")
+    || !integer(v.coverage.closed_shadow_roots) || !integer(v.coverage.frames_not_read)) return false;
+  for (const face of v.font_faces) {
+    if (!plain(face) || typeof face.family !== "string"
+      || !["unloaded", "loading", "loaded", "error"].includes(face.status)) return false;
+  }
+  const indices = new Set();
+  for (const e of v.elements) {
+    if (!plain(e) || !integer(e.index) || indices.has(e.index)
+      || !boundedText(e.selector_path, PARITY_PROBE_LIMITS.selector_path_chars) || e.selector_path === ""
+      || !boundedText(e.text, PARITY_PROBE_LIMITS.text_chars)
+      || !boundedText(e.ftext, PARITY_PROBE_LIMITS.text_chars)
+      || !plain(e.box) || !coordinate(e.box.x) || !coordinate(e.box.y) || !extent(e.box.w) || !extent(e.box.h)
+      || !["font_family", "font_style", "text_transform"].every((k) => typeof e[k] === "string")
+      || !nonnegative(e.font_size_px) || !finite(e.font_weight) || e.font_weight < 1 || e.font_weight > 1000
+      || !normalOr(e.line_height, nonnegative) || !normalOr(e.letter_spacing, finite)
+      || !color(e.fg_srgb) || !color(e.bg_srgb)
+      || !(e.color_review === null || (typeof e.color_review === "string" && e.color_review !== ""))) return false;
+    indices.add(e.index);
+  }
+  return true;
+}
+
+function validOptions(options) {
+  if (options === undefined) return true;
+  if (!plain(options) || Object.keys(options).some((k) => k !== "tolerances")) return false;
+  if (!Object.hasOwn(options, "tolerances")) return true;
+  const t = options.tolerances;
+  const keys = Object.keys(PARITY_TOLERANCES);
+  return plain(t) && Object.keys(t).length === keys.length && keys.every((k) => Object.hasOwn(t, k))
+    && keys.filter((k) => k.endsWith("_px") || k === "color_channel").every((k) => nonnegative(t[k]))
+    && finite(t.fuzzy_jaccard) && t.fuzzy_jaccard > 0 && t.fuzzy_jaccard <= 1
+    && integer(t.missing_copy_min_chars, 1);
+}
+
+function norm(s) {
+  return s.normalize("NFKC").replace(/[\u2018\u2019\u201a\u201b]/gu, "'")
+    .replace(/[\u201c\u201d\u201e]/gu, '"').replace(/[\u2013\u2014\u2212]/gu, "-")
+    .replace(/\s+/gu, " ").trim().toLowerCase();
+}
+
+function key(s) {
+  return norm(s).replace(/[^\p{L}\p{M}\p{N} ]/gu, " ").replace(/ +/g, " ").trim();
+}
+
+const tokens = (s) => new Set(key(s).split(" ").filter(Boolean));
+function jaccard(a, b) {
+  if (!a.size || !b.size) return 0;
+  let common = 0;
+  for (const token of a) if (b.has(token)) common++;
+  return common / (a.size + b.size - common);
+}
+
+function firstFamily(s) {
+  let quote = null;
+  let entry = "";
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === "\\") {
+      if (i + 1 < s.length) entry += s[++i];
+    } else if (ch === quote) {
+      quote = null;
+    } else if (!quote && (ch === '"' || ch === "'")) {
+      quote = ch;
+    } else if (!quote && ch === ",") {
+      const family = norm(entry);
+      if (family) return family;
+      entry = "";
+    } else {
+      entry += ch;
+    }
+  }
+  return norm(entry);
+}
+
+function median(values) {
+  if (!values.length) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+function round2(v) {
+  const rounded = Math.round(v * 100) / 100;
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+const exceeds = (delta, tolerance) => Math.abs(delta) - tolerance > 1e-9;
+const c8 = (v) => Math.round(Math.min(1, Math.max(0, v)) * 255);
+const roundValue = (v) => Array.isArray(v) ? v.map(roundValue) : typeof v === "number" ? round2(v) : v;
+const designOrder = (a, b) => a.e.box.y - b.e.box.y || a.e.box.x - b.e.box.x || a.e.index - b.e.index;
+
+function emptyComparison() {
+  return {
+    comparator_version: PARITY_COMPARATOR_VERSION, status: "compared", invalid: null,
+    drift: { dx: 0, dy: 0, samples: 0 },
+    counts: { design: 0, build: 0, matched: 0,
+      by_pass: { exact_unique: 0, exact_nearest: 0, subtree: 0, fuzzy: 0 },
+      unmatched_present: 0, unmatched_missing: 0, unmatched_unverified: 0, below_min_chars: 0 },
+    pairs: [], findings: [],
+  };
+}
+
+// Cache text before matching so the 1500 × 1500 case does no repeated
+// normalization or font-face/page-text scanning per candidate.
+function prepared(e) {
+  const textKey = key(e.text);
+  return { e, textKey, ftextKey: key(e.ftext), tokens: tokens(e.text !== "" ? e.text : e.ftext) };
+}
+
+function groupedByText(elements) {
+  const groups = new Map();
+  for (const e of elements) {
+    if (!groups.has(e.textKey)) groups.set(e.textKey, []);
+    groups.get(e.textKey).push(e);
+  }
+  return groups;
+}
+
+function faceStatuses(faces) {
+  const map = new Map();
+  const rank = { error: 1, unloaded: 2, loading: 3, loaded: 4 };
+  for (const face of faces) {
+    const family = norm(face.family);
+    if (rank[face.status] > (rank[map.get(family)] ?? 0)) map.set(family, face.status);
+  }
+  return map;
+}
+
+export function compareElementParity(design, build, options) {
+  const out = emptyComparison();
+  const invalid = !validOptions(options) ? "options" : !isProbeOutput(design) ? "design"
+    : !isProbeOutput(build) ? "build" : null;
+  if (invalid) return { ...out, status: "invalid_input", invalid };
+  const t = options?.tolerances ?? PARITY_TOLERANCES;
+  const D = design.elements.map(prepared).filter((d) => d.textKey !== "").sort(designOrder);
+  const B = build.elements.map(prepared);
+  out.counts.design = D.length;
+  out.counts.build = B.length;
+  if (design.viewport.width !== build.viewport.width || design.viewport.height !== build.viewport.height || design.dpr !== build.dpr) {
+    out.status = "viewport_mismatch";
+    return out;
+  }
+  if (!D.length) {
+    out.status = "design_elements_unavailable";
+    return out;
+  }
+
+  const matches = new Map();
+  const used = new Set();
+  const pair = (d, b, via, similarity = null) => {
+    matches.set(d, { b, via, similarity });
+    used.add(b);
+    out.counts.by_pass[via]++;
+  };
+  const dg = groupedByText(D);
+  const bg = groupedByText(B);
+  const xs = [], ys = [];
+  for (const d of D) {
+    const candidates = bg.get(d.textKey);
+    if (dg.get(d.textKey).length === 1 && candidates?.length === 1) {
+      const b = candidates[0];
+      pair(d, b, "exact_unique");
+      xs.push(b.e.box.x - d.e.box.x);
+      ys.push(b.e.box.y - d.e.box.y);
+    }
+  }
+  const dx = median(xs), dy = median(ys);
+  out.drift = { dx: round2(dx), dy: round2(dy), samples: xs.length };
+  const dist = (d, b) => Math.hypot(d.e.box.x + dx - b.e.box.x, d.e.box.y + dy - b.e.box.y);
+  const area = (b) => Math.max(1, b.e.box.w) * Math.max(1, b.e.box.h);
+  for (const via of ["exact_nearest", "subtree", "fuzzy"]) {
+    for (const d of D) {
+      if (matches.has(d)) continue;
+      let best = null, bestPrimary = Infinity, bestDistance = Infinity, similarity = null;
+      const candidates = via === "exact_nearest" ? bg.get(d.textKey) ?? [] : B;
+      for (const b of candidates) {
+        if (used.has(b)) continue;
+        let primary = 0, score = null;
+        if (via === "subtree") {
+          if (!((b.ftextKey !== "" && b.ftextKey === d.textKey)
+            || (d.ftextKey !== "" && b.textKey !== "" && b.textKey === d.ftextKey))) continue;
+          primary = area(b);
+        } else if (via === "fuzzy") {
+          score = jaccard(d.tokens, b.tokens);
+          if (score < t.fuzzy_jaccard) continue;
+          primary = -score;
+        }
+        const distance = dist(d, b);
+        if (best === null || primary < bestPrimary || (primary === bestPrimary
+          && (distance < bestDistance || (distance === bestDistance && b.e.index < best.e.index)))) {
+          best = b;
+          bestPrimary = primary;
+          bestDistance = distance;
+          similarity = score;
+        }
+      }
+      if (best) pair(d, best, via, similarity === null ? null : round2(similarity));
+    }
+  }
+
+  const pageKey = ` ${key(build.page_text)} `;
+  const contains = (k) => pageKey.includes(` ${k} `);
+  const incomplete = build.coverage.page_text_truncated ? "page_text_truncated"
+    : build.coverage.closed_shadow_roots > 0 || build.coverage.frames_not_read > 0 ? "build_text_not_read" : null;
+  const designFaces = faceStatuses(design.font_faces), buildFaces = faceStatuses(build.font_faces);
+  const categories = { copy: [], typography: [], color: [], geometry: [] };
+  const ordinals = new Map();
+  let pred = null;
+  for (const d of D) {
+    const de = d.e;
+    const text = norm(de.text);
+    const identityKey = JSON.stringify([text, de.selector_path]);
+    const ordinal = ordinals.get(identityKey) ?? 0;
+    ordinals.set(identityKey, ordinal + 1);
+    const design_identity = { text, selector_path: de.selector_path, ordinal };
+    const match = matches.get(d);
+    const be = match?.b.e;
+    const members = { copy: [], typography: [], color: [], geometry: [] };
+    const add = (category, property, reason_code, dv, bv, delta = null, result = "warning") => {
+      members[category].push({ property, result, reason_code, design: roundValue(dv), build: roundValue(bv), delta: roundValue(delta) });
+    };
+    const changed = (category, property, dv, bv, tolerance, delta = bv - dv) => {
+      if (exceeds(delta, tolerance)) add(category, property, `${property}_differs`, dv, bv, delta);
+    };
+    const copy = (reason, bv, delta = null) => add("copy", "copy", reason, text, bv, delta,
+      incomplete ? "review" : "warning");
+    if (!match) {
+      if ([...d.textKey].length < t.missing_copy_min_chars) out.counts.below_min_chars++;
+      else if (contains(d.textKey)) out.counts.unmatched_present++;
+      else if (incomplete) {
+        out.counts.unmatched_unverified++;
+        copy(incomplete, null);
+      } else {
+        out.counts.unmatched_missing++;
+        copy("copy_missing", null);
+      }
+    } else {
+      out.pairs.push({ design: de.index, build: be.index, via: match.via, similarity: match.similarity });
+      if (match.via === "fuzzy" && !contains(d.textKey)) {
+        copy(incomplete ?? "copy_changed", norm(be.text !== "" ? be.text : be.ftext), match.similarity);
+      }
+      const df = firstFamily(de.font_family), bf = firstFamily(be.font_family);
+      if (df !== bf) add("typography", "font_family", "font_family_differs", df, bf);
+      changed("typography", "font_size", de.font_size_px, be.font_size_px, t.font_size_px);
+      changed("typography", "font_weight", de.font_weight, be.font_weight, 0);
+      if (de.font_style !== be.font_style) add("typography", "font_style", "font_style_differs", de.font_style, be.font_style);
+      if (typeof de.line_height === "number" && typeof be.line_height === "number") {
+        changed("typography", "line_height", de.line_height, be.line_height, t.line_height_px);
+      } else if (de.line_height !== be.line_height) {
+        add("typography", "line_height", "line_height_unresolved", de.line_height, be.line_height, null, "review");
+      }
+      changed("typography", "letter_spacing", de.letter_spacing, be.letter_spacing, t.letter_spacing_px,
+        (be.letter_spacing === "normal" ? 0 : be.letter_spacing) - (de.letter_spacing === "normal" ? 0 : de.letter_spacing));
+      if (de.text_transform !== be.text_transform) add("typography", "text_transform", "text_transform_differs", de.text_transform, be.text_transform);
+      if (designFaces.get(df) === "loaded" && buildFaces.get(df) !== "loaded") {
+        add("typography", "font_face", build.coverage.font_faces_capped ? "font_face_unverified" : "font_face_unavailable",
+          "loaded", buildFaces.get(df) ?? "absent", null, build.coverage.font_faces_capped ? "review" : "warning");
+      }
+      if (de.color_review !== null || be.color_review !== null || de.fg_srgb === null || be.fg_srgb === null) {
+        add("color", "color", "color_unresolved", de.color_review, be.color_review, null, "review");
+      } else {
+        for (const [property, field] of [["text_color", "fg_srgb"], ["background_color", "bg_srgb"]]) {
+          const dc = de[field]?.map(c8) ?? null, bc = be[field]?.map(c8) ?? null;
+          if (dc === null || bc === null) add("color", property, "color_unresolved", dc, bc, null, "review");
+          else changed("color", property, dc, bc, t.color_channel, Math.max(...dc.map((v, i) => Math.abs(bc[i] - v))));
+        }
+      }
+      const gapD = de.box.y - (pred ? pred.d.box.y + pred.d.box.h : 0);
+      const gapB = be.box.y - (pred ? pred.b.box.y + pred.b.box.h : 0);
+      changed("geometry", "gap", gapD, gapB, t.gap_px);
+      changed("geometry", "x_position", de.box.x, be.box.x, t.position_px, (be.box.x - de.box.x) - dx);
+      changed("geometry", "width", de.box.w, be.box.w, t.size_px);
+      changed("geometry", "height", de.box.h, be.box.h, t.size_px);
+      pred = { d: de, b: be };
+    }
+    for (const category of Object.keys(categories)) {
+      if (members[category].length) categories[category].push({ category, design: de.index, build: be?.index ?? null,
+        design_identity: { ...design_identity }, members: members[category] });
+    }
+  }
+  out.counts.matched = out.pairs.length;
+  out.findings = Object.values(categories).flat();
+  return out;
+}

package/src/parity/design-access.mjs

@@ -0,0 +1,54 @@
+import { normalizeDesignFileReference, resolveDesignFileReferences } from "../design-file-reference.mjs";
+import { buildQcResult } from "../qc-results.mjs";
+
+const array = (value) => Array.isArray(value) ? value : [];
+
+function recordedType(contribution, fileRef) {
+  const type = fileRef?.design_file_type;
+  if (typeof type === "string" && type.trim()) return type;
+  return ["figma_frames", "figma_sections"].includes(contribution?.kind) ? "figma" : "other";
+}
+
+// Recomputed from declarations and package records; a named file never proves
+// access. In particular this evaluator has no pass or accept-eligible path.
+export function evaluateDesignAccess({ activePages = [], mappings = [], manifest = null, designSourcePackage = null, measured_at } = {}) {
+  const contributions = Array.isArray(designSourcePackage?.contributions) ? designSourcePackage.contributions : [];
+  const surfaces = Array.isArray(designSourcePackage?.surface_identity) ? designSourcePackage.surface_identity : [];
+  const recordedPageIds = new Set();
+  const recordedByPage = new Map(activePages.map((page) => {
+    const surfaceIds = new Set(surfaces.filter((surface) => surface?.kind === "page" && surface.mappings?.campaign_spec_page_id === page.id).map((surface) => surface.id));
+    const recorded = contributions.find((contribution) => contribution?.provenance?.source_type === "design_file" && array(contribution.mappings).some((mapping) => surfaceIds.has(mapping?.surface_id)));
+    if (recorded && contributions.some((contribution) => array(contribution?.mappings).some((mapping) => surfaceIds.has(mapping?.surface_id) && mapping?.derived_from === recorded.id))) {
+      recordedPageIds.add(page.id);
+    }
+    return [page.id, recorded];
+  }));
+  const resolved = resolveDesignFileReferences({ activePages, mappings, manifest, specChannel: {
+    mode: "doctor",
+    recordedPageIds,
+  } });
+  const rows = [];
+  for (const page of activePages) {
+    const current = resolved.pages.find((entry) => entry.page_id === page.id);
+    const recorded = recordedByPage.get(page.id);
+    if (!current && !recorded) continue;
+    const fileRef = array(recorded?.source_refs).find((ref) => ref?.role === "design_file");
+    const previous = normalizeDesignFileReference({ type: recordedType(recorded, fileRef), file_url: fileRef?.url }).declaration;
+    const declaredSha = current?.declaration.file_identity_sha256 ?? null;
+    const recordedSha = previous?.file_identity_sha256 ?? null;
+    const reason_code = current?.conflict ? "design_reference_conflict"
+      : recorded && !current ? "design_reference_missing"
+        : recorded && declaredSha !== recordedSha ? "design_reference_changed"
+        : !recorded ? "design_reference_not_recorded" : "design_access_missing";
+    const result = ["design_reference_conflict", "design_reference_missing", "design_reference_changed"].includes(reason_code) ? "review" : "unexercised";
+    const state = { reason_code, recorded_identity_sha256: recordedSha, declared_identity_sha256: declaredSha, conflict_identities: [...(current?.conflict?.identities || [])].sort(), conflict_frames: [...(current?.conflict?.frames || [])].sort() };
+    const observation = {
+      type: current?.declaration.type ?? previous?.type ?? null,
+      kind: current?.conflict?.kind ?? null,
+      declared_by: current?.declared_by ?? null,
+      frames_declared: Object.keys(current?.declaration.frames || {}).sort(), reader: "none", recorded_contribution_id: recorded?.id ?? null,
+    };
+    rows.push({ ...buildQcResult({ check: "design.access", leg: "doctor", subject: { check: "design.access", page: page.id, key: "file" }, result, reason_code, state, observation, accept_eligible: false, measured_at }), state });
+  }
+  return rows;
+}