@nextcommerce/campaigns-os 1.52.0 → 1.53.0

package/src/progress-node.mjs

@@ -5,6 +5,7 @@ import {mkdirSync,readFileSync,writeFileSync,renameSync,rmSync,readdirSync} from
 import {join,resolve,dirname} from 'node:path';
 import {PROGRESS_SCHEMA_VERSION,PROGRESS_STAGES,PROGRESS_STAGE_STATUSES,PROGRESS_CONTINUATIONS,PROGRESS_ACTION_IDS,PROGRESS_GATE_IDS,canonicalProgressJson,progressSnapshotId,verifyProgressSnapshot} from './progress.mjs';
 import {specMaterialHash} from './spec-identity.mjs';
+import {effectiveStageStatus} from './input-currency.mjs';
 import {sameFile} from './fs-identity.mjs';
 import {withDirectoryLock} from './directory-lock.mjs';
 import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefaultOnTelemetry} from './consent.mjs';
@@ -17,7 +18,7 @@ const accepted = (value,values,fallback='unknown')=>values.includes(value)?value
 // A next action that is a variant of a fixed action projects onto it: the
 // order-bump QA run is a QA run. Without this, the closed v0 vocabulary would
 // read it as unknown and mark a ready QA continuation blocked.
-const PROGRESS_ACTION_ALIASES = new Map([['qa_run_bump','qa_run']]);
+const PROGRESS_ACTION_ALIASES = new Map([['qa_run_bump','qa_run'],['refresh_inputs','recheck']]);
 const hash = value=>typeof value==='string'&&/^(?:sha256:)?[0-9a-f]{64}$/i.test(value)?`sha256:${value.replace(/^sha256:/i,'').toLowerCase()}`:null;
 const id = value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(value)?value:null;
 const digest = value=>`sha256:${createHash('sha256').update(value).digest('hex')}`;
@@ -54,7 +55,15 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
   const aligned=contextBound&&mapId&&localMapId===mapId&&baseline?.map_id===mapId&&baseline?.algorithm==='map-store-v1'&&hash(baseline.hash)&&localHash&&localHash===hash(baseline.local_spec_material_hash);
   const build=hash(doctor?.derived?.build_output_fingerprint?.value);
   const recordedBuild=hash(report?.stages?.assembly?.build_fingerprint);
-  const reportBound=doctor?.derived?.prepare_build_gate?.binding_failure!==true&&contextBound&&campaignIdentitiesMatch(packet?.spec,campaignSpecIdentity(spec))&&campaignIdentitiesMatch(packet?.spec,report?.identity)&&localHash&&localHash===hash(report?.identity?.spec_material_hash);
+  // The report belongs to this packet and spec: its stages can be read. A
+  // spec edit since the report was bound does not unbind it; the edit makes
+  // the stamped stages owed, which their effective status reports. The
+  // doctor read must have assessed the same spec material this read sees.
+  const inputCurrency=doctor?.derived?.input_currency;
+  const stagesBound=doctor?.derived?.prepare_build_gate?.binding_failure!==true&&contextBound&&campaignIdentitiesMatch(packet?.spec,campaignSpecIdentity(spec))&&campaignIdentitiesMatch(packet?.spec,report?.identity)&&localHash&&(!inputCurrency||hash(inputCurrency.spec?.current)===localHash);
+  // The report is also bound to the spec material on disk now, so output and
+  // verdict evidence recorded against it can match.
+  const reportBound=stagesBound&&localHash===hash(report?.identity?.spec_material_hash);
   const qaSource=hash(report?.stages?.qa?.evidence?.source_build_fingerprint);
   const verdict=qaResult?.verdict;
   const qa=verdict?{
@@ -73,8 +82,11 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
   return {
     schema_version:PROGRESS_SCHEMA_VERSION,package_version:packageVersion,producer:qaResult?'qa':'next',
     identity:{map_id:mapId,...localSpecIdentityFields(packet?.spec),map_revision_hash:mapId?(contextBound&&baseline?.map_id===mapId?hash(baseline?.hash):(localMapId===mapId?hash(spec?.spec_identity?.spec_hash||spec?.spec_hash):null)):null,map_revision_algorithm:'map-store-v1',saved_revision_alignment:aligned?'aligned':'unconfirmed',local_spec_material_hash:localHash,local_spec_material_algorithm:'campaign-spec-material-v1',build_fingerprint:build,build_fingerprint_algorithm:'sha256-manifest/v1'},
+    // Each stage's effective status: a stage owed again by a brief or
+    // CampaignSpec change reads required, one whose inputs cannot be
+    // confirmed reads unknown (src/input-currency.mjs).
     stages:PROGRESS_STAGES.map(stage=>{
-      const status=reportBound?accepted(report?.stages?.[stage]?.status,PROGRESS_STAGE_STATUSES):'unknown';
+      const status=stagesBound?accepted(effectiveStageStatus(stage,report?.stages?.[stage],inputCurrency),PROGRESS_STAGE_STATUSES):'unknown';
       const source=stage==='assembly'?recordedBuild:stage==='qa'?qaSource:null;
       return {stage,status,source_build_fingerprint:source,build_binding:reportBound&&build&&source===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'?'matching':'unconfirmed'};
     }),

package/src/qa-browser.mjs

@@ -6,6 +6,8 @@ const PACKAGE_ROOT = installModeResolve(installModeDirname(installModeFileUrl(im
 import { createHash } from "node:crypto";
 import { runWithDeadline } from "./deadline.mjs";
 import { PLACEHOLDER_TEXT_ASSERTION_SUFFIX, SEVERITY, STATUS } from "./qa-verdict.mjs";
+import { contrastToolkit } from "./contrast.mjs";
+import { generatedTextRenders } from "./polish-readability.mjs";
 import {
   analyticsCaptureError,
   projectAnalyticsCaptureError,
@@ -1300,9 +1302,7 @@ async function primaryCtaVisualAssertions(browserPage, page) {
 }
 
 function primaryCtaCheckEligible(page) {
-  if (!page?.expected_next_url) return false;
-  const pageType = String(page.page_type || "").toLowerCase();
-  return !["checkout", "upsell", "downsell", "thankyou", "receipt"].includes(pageType);
+  return Boolean(page?.expected_next_url);
 }
 
 // Candidate CTAs: anything clickable, plus every SDK action control and the
@@ -1314,10 +1314,12 @@ const PRIMARY_CTA_SELECTOR = ["a[href]", "button", "[role='button']", "[data-nex
 
 // The in-page half of the primary-CTA inspection, as the source text the
 // page evaluates. The route rule it needs (cartEntryHrefFor, unit-tested in
-// qa-cart-entry) is handed in as a function value rather than closed over, so
-// both function bodies must stay free of module-scope references: the text is
-// run in a fresh context by a test (primary-CTA inspection script is
-// self-contained) that would surface a leaked identifier as a ReferenceError.
+// qa-cart-entry), the shared contrast helper (contrastToolkit) and the
+// generated-text rule Polish reads (generatedTextRenders) are handed in as
+// function values rather than closed over, so every function body must
+// stay free of module-scope references: the text is run in a fresh context by
+// a test (primary-CTA inspection script is self-contained) that would surface
+// a leaked identifier as a ReferenceError.
 function primaryCtaInspectionScript(expectedUrl) {
   const args = {
     routeUrl: expectedUrl,
@@ -1326,7 +1328,7 @@ function primaryCtaInspectionScript(expectedUrl) {
     cartEntryRouteAttribute: CART_ENTRY_ROUTE_ATTRIBUTE,
     ignoredRouteAttributes: [...UNDECLARED_ROUTE_ATTRIBUTES],
   };
-  return `(${inspectPrimaryCtaScript.toString()})(${JSON.stringify(args)}, ${cartEntryHrefFor.toString()})`;
+  return `(${inspectPrimaryCtaScript.toString()})(${JSON.stringify(args)}, ${cartEntryHrefFor.toString()}, ${contrastToolkit.toString()}, ${generatedTextRenders.toString()})`;
 }
 
 async function inspectPrimaryCta(browserPage, expectedUrl) {
@@ -1340,8 +1342,9 @@ async function inspectPrimaryCta(browserPage, expectedUrl) {
   }));
 }
 
-function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, cartEntryRouteAttribute, ignoredRouteAttributes }, hrefForImpl) {
+function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, cartEntryRouteAttribute, ignoredRouteAttributes }, hrefForImpl, contrastToolkitImpl, generatedTextImpl) {
   const CTA_SELECTOR = ctaSelector;
+  const toolkit = contrastToolkitImpl();
 
   const trim = (value) => String(value || "").replace(/\s+/g, " ").trim();
   const compactPath = (value) => String(value || "").replace(/\/+$/, "") || "/";
@@ -1352,42 +1355,6 @@ function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, car
       return null;
     }
   })();
-  const parseColor = (value) => {
-    const raw = String(value || "").trim().toLowerCase();
-    if (!raw || raw === "transparent") return null;
-    const rgb = raw.match(/^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})(?:\s*,\s*(\d?(?:\.\d+)?|1(?:\.0+)?))?\s*\)$/);
-    if (!rgb) return null;
-    const parts = rgb.slice(1, 4).map((part) => Number(part));
-    if (parts.some((part) => !Number.isFinite(part) || part < 0 || part > 255)) return null;
-    const alpha = rgb[4] === undefined ? 1 : Number(rgb[4]);
-    return { r: parts[0], g: parts[1], b: parts[2], a: Number.isFinite(alpha) ? alpha : 1 };
-  };
-  const hex = (color) => color ? `#${[color.r, color.g, color.b].map((part) => Math.round(part).toString(16).padStart(2, "0")).join("")}` : null;
-  const luminance = (color) => {
-    const channel = (value) => {
-      const normalized = value / 255;
-      return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
-    };
-    return 0.2126 * channel(color.r) + 0.7152 * channel(color.g) + 0.0722 * channel(color.b);
-  };
-  const contrast = (a, b) => {
-    if (!a || !b) return null;
-    const light = Math.max(luminance(a), luminance(b));
-    const dark = Math.min(luminance(a), luminance(b));
-    return Math.round(((light + 0.05) / (dark + 0.05)) * 100) / 100;
-  };
-  const effectiveBackground = (element) => {
-    let current = element;
-    while (current && current.nodeType === Node.ELEMENT_NODE) {
-      const style = getComputedStyle(current);
-      const color = parseColor(style.backgroundColor);
-      if (color && color.a > 0.05) {
-        return { color, source: current === element ? "element" : current.tagName.toLowerCase() };
-      }
-      current = current.parentElement;
-    }
-    return { color: { r: 255, g: 255, b: 255, a: 1 }, source: "assumed_canvas" };
-  };
   const isVisible = (element) => {
     const rect = element.getBoundingClientRect();
     const style = getComputedStyle(element);
@@ -1440,56 +1407,124 @@ function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, car
   // per-element detail for the listed candidates only.
   const ignoredAttributes = Array.from(new Set(visibleElements.flatMap(ignoredAttributesOn))).sort();
 
-  const candidates = visibleElements
+  // A route candidate's text, read through the shared contrast helper: each
+  // text-bearing element inside it is compared, unrounded, with the
+  // requirement for its own size. An element with a review trigger (or with
+  // no ratio to compare) is a review member and is not compared; an element
+  // whose control is disabled or loading has no colours read. Text whose
+  // control is disabled is inactive: it is not rendered text the check can
+  // read, so it never counts toward text_rendered or toward a pass. A
+  // disabled candidate is not measured at all, whatever text it generates,
+  // and never counts toward a pass. In an enabled candidate, text an element
+  // inside it generates through ::before or ::after (generatedTextImpl) is
+  // never measured, so the candidate is reviewed, never passed on its other
+  // text.
+  const measureCandidate = (element) => {
+    if (element.matches(":disabled, [aria-disabled=\"true\"]")) {
+      return { disabled: true, text_rendered: null, control_loading: null, contrast_ratio: null, elements: [], below: false, review: false, measured: false, inactive: false };
+    }
+    // Every element the page renders inside the candidate: its own subtree,
+    // open shadow roots included.
+    const subtree = toolkit.flatSubtree(element);
+    const reads = subtree
+      .filter((node) => toolkit.isTextBearing(node, window))
+      .map((node) => toolkit.measureTextElement(node, window));
+    const compared = [];
+    let review = subtree.some((node) => generatedTextImpl(node, window));
+    for (const read of reads) {
+      if (read.disabled || read.control_loading) continue;
+      if (read.review_reason !== null || typeof read.ratio !== "number") review = true;
+      else compared.push(read);
+    }
+    const ratios = compared.map((read) => read.ratio);
+    return {
+      disabled: false,
+      text_rendered: reads.some((read) => !read.disabled),
+      control_loading: reads.some((read) => read.control_loading),
+      contrast_ratio: ratios.length ? toolkit.displayRatio(Math.min(...ratios)) : null,
+      elements: reads.map((read) => ({
+        selector_path: read.selector_path,
+        contrast_ratio_exact: read.ratio,
+        required_ratio: read.required,
+        size_class: read.size_class,
+        review_reason: read.review_reason,
+      })),
+      below: compared.some((read) => !toolkit.meetsRequirement(read.ratio, read.required)),
+      review,
+      measured: compared.length > 0,
+      inactive: reads.some((read) => read.disabled),
+    };
+  };
+
+  // Route candidates carry their measurement; other rows are listed for the
+  // route-recognition view only and are not measured.
+  const verdicts = new Map();
+  const rows = visibleElements
     .map((element) => {
       const rect = element.getBoundingClientRect();
-      const style = getComputedStyle(element);
-      const fg = parseColor(style.color);
-      const bg = effectiveBackground(element);
-      const ratio = contrast(fg, bg.color);
       const href = hrefFor(element);
       const label = trim(element.innerText || element.textContent || element.getAttribute("aria-label"));
       return {
-        selector: selectorFor(element),
-        text: label.slice(0, 120),
-        href,
-        route_matches: routeMatches(href),
-        ignored_attributes: ignoredAttributesOn(element),
-        width: Math.round(rect.width),
-        height: Math.round(rect.height),
-        foreground: hex(fg),
-        background: hex(bg.color),
-        background_source: bg.source,
-        contrast_ratio: ratio,
-        readable: typeof ratio === "number" && ratio >= 4.5,
-        size_ok: rect.width >= 40 && rect.height >= 20,
+        element,
+        row: {
+          selector: selectorFor(element),
+          text: label.slice(0, 120),
+          href,
+          route_matches: routeMatches(href),
+          ignored_attributes: ignoredAttributesOn(element),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height),
+          size_ok: rect.width >= 40 && rect.height >= 20,
+        },
       };
     })
-    .filter((candidate) => candidate.text || candidate.href);
-
-  const routeCandidates = candidates
-    .filter((candidate) => candidate.route_matches)
-    .sort((a, b) => {
-      if (a.readable !== b.readable) return a.readable ? -1 : 1;
-      if (a.size_ok !== b.size_ok) return a.size_ok ? -1 : 1;
-      return (b.contrast_ratio || 0) - (a.contrast_ratio || 0);
+    .filter(({ row }) => row.text || row.href)
+    .map(({ element, row }) => {
+      if (!row.route_matches) return { ...row, disabled: null, text_rendered: null, control_loading: null, contrast_ratio: null, elements: null };
+      const { below, review, measured, inactive, ...read } = measureCandidate(element);
+      const candidate = { ...row, ...read };
+      verdicts.set(candidate, { below, review, measured, inactive });
+      return candidate;
     });
-  const primary = routeCandidates[0] || null;
-  const ok = Boolean(primary?.readable && primary?.size_ok);
-  const reason = ok
-    ? "ok"
-    : !routeCandidates.length
-      ? "missing_route_cta"
-      : primary?.size_ok === false
-        ? "cta_too_small"
-        : "low_contrast";
+
+  // Every route candidate counts, in document order; none is preferred.
+  // The page outcome is the first that applies. An enabled candidate whose
+  // only text is inactive (its control is disabled) has no rendered text;
+  // cta_disabled is only for every candidate disabled. The page passes only
+  // when every enabled candidate had at least one element compared, so text
+  // that was skipped never stands in for a measurement.
+  const routeCandidates = rows.filter((candidate) => candidate.route_matches);
+  const enabled = routeCandidates.filter((candidate) => !candidate.disabled);
+  const measurability = routeCandidates.length ? toolkit.documentMeasurability(document) : { measurable: true };
+  const reason = !routeCandidates.length
+    ? "missing_route_cta"
+    : !measurability.measurable
+      ? measurability.reason
+      : enabled.some((candidate) => verdicts.get(candidate).below)
+        ? "low_contrast"
+        : !routeCandidates.some((candidate) => candidate.size_ok)
+          ? "cta_too_small"
+          : enabled.some((candidate) => !candidate.text_rendered)
+            ? "text_not_rendered"
+            : enabled.some((candidate) => candidate.control_loading)
+              ? "control_loading"
+              : enabled.some((candidate) => verdicts.get(candidate).review)
+                ? "contrast_review"
+                : !enabled.length || enabled.some((candidate) => !verdicts.get(candidate).measured)
+                  ? "cta_disabled"
+                  : "ok";
+
+  // Rows are capped at eight, except that every route candidate is listed.
+  const listed = [];
+  for (const row of rows) if (row.route_matches || listed.length < 8) listed.push(row);
 
   return {
-    ok,
+    ok: reason === "ok",
     reason,
     expected_url: routeUrl,
-    primary,
-    candidates: candidates.slice(0, 8),
+    // The first route candidate in document order, for display only.
+    primary: routeCandidates[0] || null,
+    candidates: listed,
     // Every route-shaped attribute seen on a visible CTA-shaped element and
     // not consulted (see above), so a missing-route verdict on a page spelled
     // that way reads as a vocabulary gap, not as a removed CTA.
@@ -1497,8 +1532,20 @@ function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, car
   };
 }
 
+// The outcomes the page itself earns as a failure. Every other outcome that
+// is not a pass could not be observed completely (the page was not
+// measurable, text or a control was not ready, a review trigger, every CTA
+// disabled, or an inspection the page rejected): manual review, never a pass
+// and never a contrast failure.
+const PRIMARY_CTA_FAIL_REASONS = Object.freeze([
+  "missing_route_cta",
+  "low_contrast",
+  "cta_too_small",
+]);
+
 function primaryCtaAssertionFromEvidence(page, evidence) {
   const ok = evidence?.ok === true;
+  const review = !ok && !PRIMARY_CTA_FAIL_REASONS.includes(evidence?.reason);
   const ignored = Array.isArray(evidence?.ignored_attributes) ? evidence.ignored_attributes.filter(Boolean) : [];
   // Named on every verdict the page earns, passing or not: a passing page
   // spelled with an undeclared route attribute is still one an operator
@@ -1509,7 +1556,7 @@ function primaryCtaAssertionFromEvidence(page, evidence) {
     id: `browser-primary-cta:${page.page_id}`,
     family: "browser-runtime",
     page,
-    status: ok ? STATUS.PASS : STATUS.FAIL,
+    status: ok ? STATUS.PASS : review ? STATUS.MANUAL_REVIEW : STATUS.FAIL,
     severity: ok ? undefined : SEVERITY.WARN,
     expected: "visible readable primary CTA linked to the expected next route",
     actual: ok

package/src/qa-node.mjs

@@ -2,6 +2,7 @@ import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch
 import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD, starterResidueIsExpected } from "./local-preview-policy.mjs";
 import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion, scriptParseAssertion } from './qa-binding-evidence.mjs';
 import { shellToken } from "./shell-token.mjs";
+import { currentBriefMaterial } from "./input-currency.mjs";
 import { applyQaBuildScope, specForQaScope } from "./qa-build-scope.mjs";
 import { requiredActionText } from "./gate-actions.mjs";
 import { parseOrderPathDepthFlag } from "./proof-policy.mjs";
@@ -468,6 +469,9 @@ async function resolveQaInputs(args, {
     routeRootNote: routeRootNotes[0] || null,
   });
   const specHash = computeSpecHash(rawSpec);
+  // The brief material this run is judged against, bound at run start beside
+  // the spec hash: the QA stage write stamps it, not the material at write time.
+  const sourceBriefMaterial = packet ? currentBriefMaterial({ packet, packetPath }) : null;
   const templateFamily = stringArg(packet?.assembly?.template_family)
     || stringArg(normalized?.spec_identity?.preferred_template_family)
     || stringArg(normalized?.campaign?.preferred_template_family)
@@ -524,6 +528,7 @@ async function resolveQaInputs(args, {
     spec: normalized,
     specVersion: String(rawSpec.schema_version || rawSpec.schemaVersion || "unknown"),
     specHash,
+    sourceBriefMaterial,
     templateFamily,
     commerceStructureContract,
     topologies: qaScope.topologies,
@@ -583,7 +588,7 @@ function resolvePacketCheckpointPreflight(args, {
   }
   if (packet?.spec?.local_spec_id != null && (!reportMatchesPacketIdentity(report, packet)
     || (specStatus === "ok" && !specHashesMatch(report.identity?.spec_material_hash, computeSpecHash(rawSpec))))) {
-    throw new Error("Local-spec QA requires the matching Assembly Report and current spec material hash. Re-run prepare-build after a material revision; do not reuse foreign or stale proof.");
+    throw new Error("Local-spec QA requires the matching Assembly Report and current spec material hash. Run `record spec` after a material revision (it keeps stage history); do not reuse foreign or stale proof.");
   }
   const checkpointGates = [
     evaluatePageKitStoreProfile({
@@ -1585,6 +1590,12 @@ function reportPathField(resolved) {
   return reportPath ? { report_path: reportPath } : {};
 }
 
+// The verdict with the brief material qa run bound at run start, when the
+// run had a packet to bind it from.
+function withSourceBriefMaterial(verdict, sourceBriefMaterial) {
+  return sourceBriefMaterial ? { ...verdict, source_brief_material: sourceBriefMaterial } : verdict;
+}
+
 function resolvePayload(resolved, { routeProbe = null } = {}) {
   const entryUrls = deriveEntryUrls(resolved.topologies);
   const pageUrls = derivePageUrls(resolved.topologies);
@@ -2598,7 +2609,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
   // The verdict as it is persisted: the local file, the committed sidecar and
   // the published copy all read this one projection (no URL query in any
   // string or key), whichever runner, return path or field produced a value.
-  const verdict = redactPersisted(createVerdict({
+  const verdict = redactPersisted(withSourceBriefMaterial(createVerdict({
     runId,
     mapId: resolved.mapId,
     localSpecId: resolved.localSpecId,
@@ -2619,7 +2630,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
     commercial,
     causeSummary,
     browser,
-  }));
+  }), resolved.sourceBriefMaterial));
 
   const validationErrors = validateVerdict(verdict);
   if (validationErrors.length) throw new Error(`QA verdict failed local validation:\n- ${validationErrors.join("\n- ")}`);

package/src/qc-accept.mjs

@@ -14,6 +14,7 @@ import { isNamedHuman, validateWaiverAttribution } from "./checkpoint-waiver.mjs
 import { DOCTOR_SIDECAR_SCHEMA } from "./doctor-sidecar.mjs";
 import { cmd } from "./install-invocation.mjs";
 import { canonicalJson } from "./polish-capture.mjs";
+import { QC_CHECK_REGISTRY } from "./qc-check-registry.mjs";
 import { QC_LEGS, QC_REASON, fingerprint12, qcResultRef } from "./qc-results.mjs";
 import { shellToken } from "./shell-token.mjs";
 
@@ -22,7 +23,18 @@ export const QC_ACCEPT_SCOPE = "qc_accept";
 export const QC_ACCEPT_RECORDER = "campaigns-os checkpoint accept";
 export const QC_ACCEPT_STATUSES = Object.freeze(["active", "lapsed", "orphaned", "expired", "inert"]);
 export const QC_DISPOSITION = Object.freeze({ OPEN: "open", OPERATOR_ACCEPTED: "operator_accepted" });
-export const QC_MEASURED_SOURCES = Object.freeze({ doctor: "doctor_sidecar", polish: "polish_media_weight", qa: "qa_full_verdict" });
+// The evidence an accept's measurement came from: the doctor sidecar, the
+// full QA verdict, or, on the Polish leg, the package-owned record the
+// accepted check is read from (QC_CHECK_REGISTRY `record`).
+const QC_LEG_SOURCES = Object.freeze({ doctor: "doctor_sidecar", qa: "qa_full_verdict" });
+export const QC_POLISH_RECORD_SOURCES = Object.freeze({ media_weight: "polish_media_weight", readability: "polish_readability" });
+
+// Null for a Polish check with no record, or a leg with no source.
+export function measuredSourceFor(leg, check) {
+  if (leg !== "polish") return Object.hasOwn(QC_LEG_SOURCES, leg) ? QC_LEG_SOURCES[leg] : null;
+  const entry = Object.hasOwn(QC_CHECK_REGISTRY, check) ? QC_CHECK_REGISTRY[check] : null;
+  return entry?.leg === "polish" && Object.hasOwn(QC_POLISH_RECORD_SOURCES, entry.record) ? QC_POLISH_RECORD_SOURCES[entry.record] : null;
+}
 
 // The command's closed refusal list.
 export const QC_ACCEPT_REFUSALS = Object.freeze({
@@ -100,7 +112,7 @@ export function createQcAccept(result, { measuredAt, attribution }) {
     state_fingerprint: result.state_fingerprint,
     result_at_accept: "warning",
     measured_at: measuredAt,
-    measured_source: QC_MEASURED_SOURCES[result.leg],
+    measured_source: measuredSourceFor(result.leg, result.check),
     ...attribution,
     recorded_by: QC_ACCEPT_RECORDER,
   };
@@ -119,7 +131,8 @@ function malformed(record) {
     && FINGERPRINT.test(record.state_fingerprint || "")
     && record.result_at_accept === "warning"
     && validTime(record.measured_at)
-    && record.measured_source === QC_MEASURED_SOURCES[record.leg]
+    && isNonEmptyString(record.measured_source)
+    && record.measured_source === measuredSourceFor(record.leg, record.check)
     && typeof record.reason === "string"
     && typeof record.accepted_by === "string"
     && typeof record.accepted_at === "string"
@@ -291,7 +304,29 @@ export function planQcAccepts({ refs, results, sidecarPath, now, attribution })
 const LEG_ORDER = Object.freeze({ doctor: 0, polish: 1, qa: 2 });
 const compareText = (a, b) => String(a ?? "").localeCompare(String(b ?? ""));
 
+// A readability colour pair reads as its roles, colours, ratio and
+// requirement: `<roles>: <fg8> on <bg8>, <ratio>:1, needs <required>:1
+// (<size_class> text)`, from the row's observation (the lowest ratio of the
+// rows given). Null for any other row.
+function readabilityPairSummary(rows) {
+  const pairs = rows.map((row) => (row?.check === "readability.contrast" && String(row.subject?.key ?? "").startsWith("pair:") && isPlainObject(row.observation) ? row.observation : null));
+  if (!pairs.length || pairs.some((observation) => observation === null)) return null;
+  const roles = [...new Set(pairs.flatMap((observation) => (Array.isArray(observation.roles) ? observation.roles : [])))].sort(compareText);
+  const lowest = pairs.reduce((low, observation) => (observation.ratio < low.ratio ? observation : low));
+  return `${roles.join(", ")}: ${lowest.fg8} on ${lowest.bg8}, ${lowest.display_ratio}:1, needs ${lowest.required}:1 (${lowest.size_class} text)`;
+}
+
+// The crop path of a readability review row: its first member's crop.
+// Undefined for a review row with no crop, and for any other row.
+function readabilityReviewCrop(row) {
+  if (row?.check !== "readability.contrast" || row.result !== "review") return undefined;
+  const members = Array.isArray(row.observation?.members) ? row.observation.members : [];
+  const ref = members.find((member) => isPlainObject(member?.crop_ref))?.crop_ref;
+  return typeof ref?.path === "string" ? ref.path : undefined;
+}
+
 function handoffEntry(row) {
+  const crop = readabilityReviewCrop(row);
   return {
     result_ref: qcResultRef(row),
     check: row.check,
@@ -303,7 +338,8 @@ function handoffEntry(row) {
     reason_code: row.reason_code,
     accept_eligible: row.accept_eligible === true,
     members: Array.isArray(row.members) ? row.members : [],
-    summary: `${row.check} ${row.result}${row.reason_code ? ` (${row.reason_code})` : ""} on ${row.subject?.page ?? "(no page)"}${row.subject?.key == null ? "" : `: ${row.subject.key}`}`,
+    summary: readabilityPairSummary([row]) ?? `${row.check} ${row.result}${row.reason_code ? ` (${row.reason_code})` : ""} on ${row.subject?.page ?? "(no page)"}${row.subject?.key == null ? "" : `: ${row.subject.key}`}`,
+    ...(crop === undefined ? {} : { crop }),
   };
 }
 
@@ -315,7 +351,7 @@ const byCheckKeyPage = (a, b) => compareText(a.check, b.check) || compareText(a.
 // first page's fields, `pages`, and `results`, which keeps every page's result
 // with its own ref, accept eligibility and members, so every member stays
 // visible. The entry is accept-eligible only when every result in it is.
-function groupOpenWarnings(entries) {
+function groupOpenWarnings(entries, rows = []) {
   const groups = new Map();
   for (const entry of [...entries].sort(byCheckKeyPage)) {
     const key = JSON.stringify([entry.check, entry.key]);
@@ -330,7 +366,7 @@ function groupOpenWarnings(entries) {
       pages,
       accept_eligible: results.every((entry) => entry.accept_eligible),
       summary: results.length > 1
-        ? `${lead.check} ${lead.result}${lead.reason_code ? ` (${lead.reason_code})` : ""} on ${pages.join(", ")}${lead.key == null ? "" : `: ${lead.key}`}`
+        ? readabilityPairSummary(results.map((entry) => rows.find((row) => qcResultRef(row) === entry.result_ref))) ?? `${lead.check} ${lead.result}${lead.reason_code ? ` (${lead.reason_code})` : ""} on ${pages.join(", ")}${lead.key == null ? "" : `: ${lead.key}`}`
         : lead.summary,
       results,
     };
@@ -401,7 +437,7 @@ export function buildQcHandoff({ results, coverage = [], accepts, now = new Date
   const coverageEntries = [...grouped.values(), ...coverage]
     .map((entry) => ({ ...entry, pages: [...entry.pages].sort(compareText) }))
     .sort((a, b) => (LEG_ORDER[a.leg] ?? 9) - (LEG_ORDER[b.leg] ?? 9) || compareText(a.check, b.check) || compareText(a.reason_code, b.reason_code) || compareText(a.result, b.result));
-  const openGroups = groupOpenWarnings(open);
+  const openGroups = groupOpenWarnings(open, results);
   review.sort(byCheckKeyPage);
   lapsed.sort(byCheckKeyPage);
   accepted.sort(byCheckKeyPage);
@@ -435,7 +471,7 @@ export function qcHandoffTextLines(handoff) {
   section("Open warnings", handoff.open, (entry) => (entry.results?.length > 1
     ? [entry.summary, ...entry.results.map((result) => `      ${openLine(result)}`)]
     : openLine(entry)));
-  section("Review", handoff.review, (entry) => `${entry.result_ref} ${entry.summary}${members(entry)}`);
+  section("Review", handoff.review, (entry) => `${entry.result_ref} ${entry.summary}${entry.crop ? ` crop: ${entry.crop}` : ""}${members(entry)}`);
   section("Lapsed accepts", handoff.lapsed, (entry) => `${entry.result_ref} ${entry.summary}; accepted by ${entry.accepted_by} at ${entry.accepted_at}; lapsed: ${entry.why}`);
   section("Coverage", handoff.coverage, (entry) => `${entry.leg} ${entry.check}: ${entry.result} (${entry.reason_code})${entry.count ? ` x${entry.count}` : ""}${entry.pages.length ? ` on ${entry.pages.join(", ")}` : ""}`);
   section("Accepted", handoff.accepted, (entry) => `${entry.result_ref} accepted by ${entry.accepted_by} at ${entry.accepted_at}: ${entry.reason}${members(entry)}`);

package/src/qc-check-registry.mjs

@@ -1,15 +1,19 @@
 // The one map from a QC check id to the check module that re-derives its
-// results. The QC readers
-// (src/qc-results.mjs) reach every check's rules through here, so a check
-// lands by adding its module, never by editing the readers.
+// results. The QC readers (src/qc-results.mjs) reach every check's rules
+// through here. A QA check lands by adding its module; a Polish check reads
+// one package-owned visual_review record, named by `record`, and each record
+// has its own reader in the Polish dispatch (POLISH_RECORDS), so a check for
+// a new record also adds that reader.
 //
 // Each entry names a module specifier, imported lazily and relative to this
 // file, and the export the reader calls:
 // - QA checks: `rederiveQcResult(observation)` returns a Derived result
 //   ({check, subject, result, reason_code, members, accept_eligible, coverage,
 //   state}) or null when the observation cannot be re-derived.
-// - Polish checks: `MEDIA_WEIGHT_QC_RULES` is {thresholds, vocabulary,
-//   evaluate(cell, thresholds) => Derived[]}.
+// - Polish checks: the record's rules, {thresholds, vocabulary,
+//   evaluate(cell, thresholds) => Derived[]} (MEDIA_WEIGHT_QC_RULES for
+//   media_weight; READABILITY_QC_RULES for readability, which also carries
+//   the record's fixed producer values, limits and route set).
 // - Doctor checks recompute from the built HTML on every read and are called
 //   by doctor itself; their entries name the evaluator for completeness.
 //
@@ -23,11 +27,13 @@ export const QC_CHECK_REGISTRY = Object.freeze({
   // Content params
   content_param: Object.freeze({ leg: "qa", unit: "1.2", module: "./qa-content-params.mjs", rederive: "rederiveQcResult" }),
   // Media weight and oversizing
-  "media.weight": Object.freeze({ leg: "polish", unit: "1.3", module: "./polish-media-weight.mjs", rederive: "MEDIA_WEIGHT_QC_RULES" }),
-  "media.oversize": Object.freeze({ leg: "polish", unit: "1.3", module: "./polish-media-weight.mjs", rederive: "MEDIA_WEIGHT_QC_RULES" }),
+  "media.weight": Object.freeze({ leg: "polish", unit: "1.3", module: "./polish-media-weight.mjs", rederive: "MEDIA_WEIGHT_QC_RULES", record: "media_weight" }),
+  "media.oversize": Object.freeze({ leg: "polish", unit: "1.3", module: "./polish-media-weight.mjs", rederive: "MEDIA_WEIGHT_QC_RULES", record: "media_weight" }),
   // Policy links
   "policy.presence": Object.freeze({ leg: "qa", unit: "1.4", module: "./qa-policy-links.mjs", rederive: "rederiveQcResult" }),
   "policy.availability": Object.freeze({ leg: "qa", unit: "1.4", module: "./qa-policy-links.mjs", rederive: "rederiveQcResult" }),
+  // Text readability
+  "readability.contrast": Object.freeze({ leg: "polish", unit: "2.4", module: "./polish-readability.mjs", rederive: "READABILITY_QC_RULES", record: "readability" }),
   // Cart placeholders
   cart_placeholders: Object.freeze({ leg: "doctor", unit: "1.5", module: "./cart-placeholders.mjs", rederive: "evaluateCartPlaceholders" }),
   // Built-output smoke checks
@@ -35,6 +41,8 @@ export const QC_CHECK_REGISTRY = Object.freeze({
 });
 
 export const qcChecksForLeg = (leg) => Object.keys(QC_CHECK_REGISTRY).filter((check) => QC_CHECK_REGISTRY[check].leg === leg);
+// The Polish checks read from one visual_review record.
+export const qcChecksForRecord = (record) => Object.keys(QC_CHECK_REGISTRY).filter((check) => QC_CHECK_REGISTRY[check].leg === "polish" && QC_CHECK_REGISTRY[check].record === record);
 
 // A module "does not exist yet" only when Node reports ERR_MODULE_NOT_FOUND
 // for that exact specifier. A missing transitive import names another URL,