@nextcommerce/campaigns-os 1.33.0

package/src/polish-gate.mjs

@@ -0,0 +1,739 @@
+import { HIDDEN_EAGER_MEDIA_SCOPE } from "./polish-page-load.mjs";
+import { HIDDEN_EAGER_MEDIA_ACTIONS } from "./gate-actions.mjs";
+
+export const POLISH_GATE_REQUIRED_EVIDENCE = Object.freeze([
+  "visual_review",
+  "brand_review",
+  "checkout_review",
+  "template_residue_review",
+  "commerce_flow_review",
+  "issues",
+  "commands",
+]);
+
+export const POLISH_PRODUCER = "next-campaigns-polish";
+
+const SUCCESS_STATUS_PREFIXES = Object.freeze(["completed"]);
+
+function isObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function normalizeString(value) {
+  return nonEmptyString(value) ? value.trim() : null;
+}
+
+function normalizeStringArray(value) {
+  return Array.isArray(value) ? value.map((entry) => normalizeString(entry)).filter(Boolean) : [];
+}
+
+function stageStatus(stage) {
+  return String(stage?.status || "");
+}
+
+function stageSucceeded(stage) {
+  const status = stageStatus(stage);
+  return SUCCESS_STATUS_PREFIXES.some((prefix) => status.startsWith(prefix));
+}
+
+function terminalAssembly(report) {
+  return String(report?.stages?.assembly?.status || "").startsWith("completed");
+}
+
+export function currentBuildFingerprint(report) {
+  return normalizeString(report?.stages?.assembly?.build_fingerprint)
+    || normalizeString(report?.stages?.assembly?.artifact_fingerprint)
+    || normalizeString(report?.build_fingerprint)
+    || normalizeString(report?.artifact_fingerprint)
+    || null;
+}
+
+export function currentSourcePackageMaterialFingerprint(report) {
+  return normalizeString(report?.design_source_package?.material_fingerprint)
+    || normalizeString(report?.inputs?.design_source_package?.material_fingerprint)
+    || normalizeString(report?.source_package?.material_fingerprint)
+    || normalizeString(report?.source_package_material_fingerprint)
+    || null;
+}
+
+export function assemblySourcePackageMaterialFingerprint(report) {
+  const assembly = report?.stages?.assembly;
+  return normalizeString(assembly?.source_package_material_fingerprint)
+    || normalizeString(assembly?.evidence?.source_package_material_fingerprint)
+    || normalizeString(report?.assembly?.source_package_material_fingerprint)
+    || null;
+}
+
+// One predicate for "this report claims a Design Source Package but Build never
+// tied itself to it". The polish gate, `doctor`/`next` (through the gate) and
+// the standalone `validate-assembly-report` all answer that question from here,
+// so the three paths cannot drift: before this existed the gate blocked and the
+// validator stayed silent on the same report.
+//
+// It carries the gate's own preconditions, not just the fingerprint
+// comparison. A report still pending Assembly (the shape `prepare-build` and
+// `start` emit, which records the package fingerprint before any build has
+// consumed it) and a report with no build fingerprint yet are both outside
+// this finding: the gate answers not_applicable or blocks on
+// polish.build_fingerprint_missing there, and so the validator must not fail
+// them on freshness.
+//
+// Callers that have already assessed the freshness waivers pass that
+// assessment in rather than paying for a second scan of the same records; the
+// gate does. A malformed waiver is a separate finding — the gate's
+// polish.waiver_expires_at_invalid, mirrored by the validator — and both
+// callers report it before asking this question, so a report whose only
+// waiver record is malformed fails on that finding alone. Asked directly, this
+// predicate treats a malformed record as no active waiver.
+export function assemblySourcePackageFingerprintMissing(report, now = Date.now(), waiverAssessment = null) {
+  if (!terminalAssembly(report)) return false;
+  if (!currentBuildFingerprint(report)) return false;
+  if (!currentSourcePackageMaterialFingerprint(report)) return false;
+  if (assemblySourcePackageMaterialFingerprint(report)) return false;
+  const assessment = waiverAssessment || assessAssemblySourcePackageFreshnessWaivers(report, now);
+  return !assessment.active;
+}
+
+export function assessAssemblySourcePackageFreshnessWaivers(report, now = Date.now()) {
+  const candidates = [
+    ...(Array.isArray(report?.waivers) ? report.waivers : []),
+    report?.assembly_source_package_freshness_waiver,
+    report?.source_package_freshness_waiver,
+  ].filter(Boolean);
+  const assessment = { active: null, expired: [], invalid: [] };
+  for (const waiver of candidates) {
+    if (!isObject(waiver) || !normalizeString(waiver.reason)) continue;
+    const scope = normalizeString(waiver.scope);
+    const appliesTo = normalizeStringArray(waiver.applies_to);
+    const scopeMatches = [
+      "assembly_source_package_freshness",
+      "source_package_after_build",
+      "source_package_stale_after_build",
+    ].includes(scope);
+    const appliesToMatches = appliesTo.some((entry) => [
+      "stages.assembly.source_package_material_fingerprint",
+      "design_source_package.material_fingerprint",
+      "polish.assembly_source_package_fingerprint_missing",
+      "polish.assembly_source_package_stale",
+    ].includes(entry));
+    const attributed = Boolean(normalizeString(waiver.waived_by) || normalizeString(waiver.owner));
+    const timestamped = Boolean(normalizeString(waiver.waived_at) || normalizeString(waiver.created_at));
+    if (!(scopeMatches || appliesToMatches) || !attributed || !timestamped) continue;
+    const expiresAt = normalizeString(waiver.expires_at);
+    if (expiresAt !== null) {
+      // expires_at must parse as a real timestamp: an unparseable value is a
+      // malformed record the gate refuses to honor, and an explicit expiry
+      // that has passed dominates any review_condition on the same record.
+      // The boundary is inclusive — expires_at exactly equal to now is
+      // expired. Selection is first-valid-wins: expired and invalid records
+      // are never selected regardless of position, so order only matters
+      // between multiple currently-valid waivers.
+      const parsed = Date.parse(expiresAt);
+      if (Number.isNaN(parsed)) {
+        assessment.invalid.push(waiver);
+        continue;
+      }
+      if (parsed <= now) {
+        assessment.expired.push(waiver);
+        continue;
+      }
+      if (!assessment.active) assessment.active = waiver;
+      continue;
+    }
+    if (normalizeString(waiver.review_condition) && !assessment.active) assessment.active = waiver;
+  }
+  return assessment;
+}
+
+function polishEvidence(stage, report) {
+  if (isObject(stage?.evidence)) return stage.evidence;
+  if (isObject(report?.polish?.evidence)) return report.polish.evidence;
+  return null;
+}
+
+function fieldHasEvidence(value, field) {
+  if (field === "issues") return Array.isArray(value);
+  if (field === "commands") {
+    if (!Array.isArray(value) || value.length === 0) return false;
+    return value.some((entry) => nonEmptyString(entry) || isObject(entry));
+  }
+  if (field === "visual_review") {
+    if (!isObject(value)) return false;
+    const screenshots = value.screenshots || value.screenshot_paths || value.paths || value.urls;
+    return Array.isArray(screenshots) && screenshots.some(nonEmptyString);
+  }
+  if (Array.isArray(value)) return value.length > 0;
+  if (isObject(value)) return Object.keys(value).length > 0;
+  return nonEmptyString(value);
+}
+
+function textFragments(value) {
+  if (Array.isArray(value)) return value.flatMap(textFragments);
+  if (isObject(value)) return Object.values(value).flatMap(textFragments);
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return [String(value)];
+  return [];
+}
+
+function reviewText(value) {
+  return textFragments(value).join(" ");
+}
+
+function hasNegativeEvidence(value, pattern) {
+  const text = reviewText(value);
+  if (/\bnot\s+found\b|\bnone\s+found\b|\bnot\s+present\b|\bno\s+(?:starter|template)\b/i.test(text)) return false;
+  return pattern.test(text);
+}
+
+function buildBriefBlocksTemplateFavicon(report) {
+  // Canonical Build Brief location after prepare-build normalization.
+  const policy = report?.build_brief?.artifact?.template_residue_policy || null;
+  return policy?.block_template_favicon === true;
+}
+
+const STARTER_FAVICON_LEAK_RE = /\b(?:starter|template)\s+favicon\s+(?:found|present|matched|leaked|retained|kept|remaining)|images\/favicon\.png\b/i;
+
+function faviconRecordCertifiesOk(record) {
+  return isObject(record) && (
+    record.byte_match === true
+    || ["matched_source", "promoted_source", "confirmed_non_template", "no_source_candidate"].includes(String(record.status || record.result || ""))
+  );
+}
+
+function faviconTextConfirmsSourceMatch(text) {
+  return /(?:byte[-_\s]?match|matched|matches|matching).{0,40}(?:source|brand|candidate)|(?:source|brand|candidate).{0,40}(?:matched|matches|matching|byte[-_\s]?match)|promoted.{0,40}source|confirmed.{0,40}(?:non[-_\s]?template|not[-_\s]?template)|\b(?:no|none)\s+source\s+candidate\b/i.test(text);
+}
+
+function hasNegativeBumpCompareEvidence(value) {
+  const text = reviewText(value);
+  if (/\b(?:no|none)\s+(?:equal|same|duplicate|doubled|no[-_\s]?discount).{0,24}(?:compare|strike|original|price)\s*(?:found|present|rendered|shown|visible)?\b/i.test(text)) return false;
+  return hasNegativeEvidence(value, /\b(?:equal|same)\s+(?:compare|strike|original)\s+price\s+(?:found|present|rendered|shown|visible)\b|\b(?:equal|same)\s+price\s+(?:compare|strike|original)\s+(?:found|present|rendered|shown|visible)\b|\b(?:compare|strike|original)\s+price\s+(?:equals|===|same\s+as)\s+(?:list|full|retail|original)\b|\b(?:doubled|duplicate)\s+(?:compare|strike|original|price)(?:\s+(?:row|price))?\s+(?:found|present|rendered|shown|visible)\b|\bno[-_\s]?discount\s+(?:compare|strike|original)\s+(?:rendered|shown|visible|present|found)\b/i);
+}
+
+function semanticEvidenceProblems(evidence, report) {
+  const problems = [];
+  const brandReview = evidence?.brand_review;
+  const checkoutReview = evidence?.checkout_review;
+  const residueReview = evidence?.template_residue_review;
+
+  const favicon = isObject(brandReview) ? brandReview.favicon : null;
+  const faviconCertifiedOk = faviconRecordCertifiesOk(favicon);
+  if (buildBriefBlocksTemplateFavicon(report)) {
+    const faviconText = reviewText(favicon);
+    const faviconTextOk = faviconTextConfirmsSourceMatch(faviconText);
+    if (!faviconCertifiedOk && !faviconTextOk) {
+      problems.push("stages.polish.evidence.brand_review.favicon must confirm source/brand favicon matching or a documented no-source-candidate outcome when block_template_favicon is true.");
+    }
+    if (isObject(favicon) && favicon.byte_match === false) {
+      problems.push("stages.polish.evidence.brand_review.favicon records byte_match=false while block_template_favicon is true.");
+    }
+  }
+  // A structured record that explicitly certifies the favicon (byte_match /
+  // accepted status) is authoritative — do not let a note that merely mentions
+  // the starter path (e.g. "copied over assets/images/favicon.png") read as
+  // leakage. Free-text-only evidence still gets the negative scan.
+  if (!faviconCertifiedOk && hasNegativeEvidence(favicon, STARTER_FAVICON_LEAK_RE)) {
+    problems.push("stages.polish.evidence.brand_review.favicon still indicates starter-template favicon leakage.");
+  }
+  if (!faviconRecordCertifiesOk(residueReview?.starter_favicon) && hasNegativeEvidence(residueReview?.starter_favicon, STARTER_FAVICON_LEAK_RE)) {
+    problems.push("stages.polish.evidence.template_residue_review.starter_favicon still indicates starter-template favicon leakage.");
+  }
+
+  const fieldEvidence = checkoutReview?.field_labels ?? checkoutReview?.initial_field_hints ?? checkoutReview?.visible_labels;
+  if (!fieldEvidence) {
+    problems.push("stages.polish.evidence.checkout_review must confirm initial checkout field labels/placeholders/hints.");
+  } else if (hasNegativeEvidence(fieldEvidence, /\b(?:missing|absent|blank|unlabeled|unlabelled|placeholder[-_\s]?stripped|not\s+legible)\b/i)) {
+    problems.push("stages.polish.evidence.checkout_review.field_labels must confirm a legible initial field hint/label state.");
+  }
+
+  const bumpEvidence = checkoutReview?.bump_compare_price_rule ?? checkoutReview?.bump_compare_price;
+  if (!bumpEvidence) {
+    problems.push("stages.polish.evidence.checkout_review must confirm the order-bump compare-price rule.");
+  } else if ((isObject(bumpEvidence) && (bumpEvidence.equal_compare_price_found === true || bumpEvidence.same_price_compare_rendered === true)) || hasNegativeBumpCompareEvidence(bumpEvidence)) {
+    problems.push("stages.polish.evidence.checkout_review.bump_compare_price_rule must confirm no equal/no-discount compare price renders.");
+  }
+
+  // Brand bleed: when a campaign is cloned from a proven sibling, the sibling's
+  // brand defaults ride along — a default promo/sale banner with a fake code,
+  // hardcoded non-token colors (e.g. next-core's #C670FE pill), scaffold fonts
+  // (Plus Jakarta), and the prior favicon. Polish must affirmatively certify
+  // the de-brand pass cleared them. See the Shield build learnings (A3).
+  // Field precedence: `brand_bleed` is canonical; `brand_bleed_review` and
+  // `debrand` are accepted aliases (in that order) for forward compat.
+  const bleedEvidence = brandReview?.brand_bleed ?? brandReview?.brand_bleed_review ?? brandReview?.debrand;
+  if (bleedEvidence === undefined || bleedEvidence === null) {
+    problems.push("stages.polish.evidence.brand_review.brand_bleed must confirm the cloned-source de-brand pass: no residual promo/sale code or copy, no prior-campaign favicon, no scaffold/non-design fonts, no hardcoded non-token colors.");
+  } else {
+    const kinds = brandBleedResidualKinds(bleedEvidence);
+    if (kinds.length) {
+      problems.push(`stages.polish.evidence.brand_review.brand_bleed still indicates cloned-source brand bleed (${kinds.join(", ")}).`);
+    }
+  }
+
+  return problems;
+}
+
+// Per-kind brand-bleed residue detection. Returns the kinds that still leaked,
+// so the gate message names the actual residue. Each kind has its own phrase
+// vocabulary rather than one monolithic regex.
+const BRAND_BLEED_RESIDUE_PATTERNS = [
+  ["residual promo/sale code or copy", /\b(?:promo|sale|discount|coupon)\b[^.;]{0,40}\b(?:code|copy|banner|sale)\b[^.;]{0,40}\b(?:found|present|remain(?:s|ing)?|leaked|retained|kept|still)\b|\b(?:found|present|remain(?:s|ing)?|leaked|retained|kept|still)\b[^.;]{0,40}\b(?:promo|sale|discount|coupon)\b[^.;]{0,40}\b(?:code|copy|banner)\b|\bfake\s+(?:code|sale|coupon)\b/i],
+  ["prior-campaign favicon", /\bprior[-_\s]?campaign\b|\bsibling[-_\s]?(?:brand|campaign|source)\b/i],
+  ["scaffold/non-design fonts", /\bscaffold\s+fonts?\b|\bplus\s+jakarta\b|\bnon[-_\s]?design\s+fonts?\b/i],
+  ["hardcoded non-token color", /(?:^|[^\w])#?c670fe(?:[^\w]|$)|\bhardcoded\s+(?:non[-_\s]?token\s+)?(?:colou?r|hex|purple)\b|\bnon[-_\s]?token\s+colou?r\s+(?:found|present|remain(?:s|ing)?)\b/i],
+];
+
+function brandBleedResidualKinds(value) {
+  if (isObject(value)) {
+    if (value.cleared === false || value.bleed_found === true || value.residual_found === true) return ["de-brand pass not cleared"];
+    if (value.cleared === true || value.bleed_found === false || value.residual_found === false) return [];
+  }
+  const text = reviewText(value);
+  // Explicit "not cleared" wording blocks first — a free-form "cleared: false"
+  // must not slip through just because no residue *kind* phrase happens to match.
+  // Tightened to avoid over-blocking benign clearances: the boolean form
+  // requires a literal "false" (not "no", which collides with "cleared: no
+  // bleed"), and bleed/residual "found" is excluded when preceded by "no" (so
+  // "no bleed found" reads as cleared, not as residue).
+  if (/\bnot\s+cleared\b|\bcleared\s*[:=-]\s*false\b|\b(?<!no\s)(?:bleed|residual)\s+(?:found|present|detected|remain(?:s|ing)?)\b|\bnot\s+de[-_\s]?branded\b/i.test(text)) {
+    return ["de-brand pass not cleared"];
+  }
+  // Otherwise an explicit cleared/none statement short-circuits the phrase scan.
+  if (/\bcleared\b|\bno\s+(?:bleed|residue|residual)\b|\bde[-_\s]?brand(?:ed|\s+pass)\b/i.test(text)) {
+    return [];
+  }
+  const kinds = [];
+  for (const [label, pattern] of BRAND_BLEED_RESIDUE_PATTERNS) {
+    if (hasNegativeEvidence(value, pattern)) kinds.push(label);
+  }
+  return kinds;
+}
+
+function evidenceProblems(evidence, report) {
+  if (!isObject(evidence)) {
+    return ["stages.polish.evidence must be an object with the required polish evidence categories."];
+  }
+  const problems = [];
+  for (const field of POLISH_GATE_REQUIRED_EVIDENCE) {
+    if (!fieldHasEvidence(evidence[field], field)) {
+      problems.push(`stages.polish.evidence.${field} is missing or incomplete.`);
+    }
+  }
+  problems.push(...semanticEvidenceProblems(evidence, report));
+  return problems;
+}
+
+function performedBy(stage, evidence) {
+  return normalizeString(stage?.performed_by)
+    || normalizeString(stage?.command_identity)
+    || normalizeString(evidence?.performed_by)
+    || null;
+}
+
+function sourceBuildFingerprint(stage, evidence) {
+  return normalizeString(stage?.source_build_fingerprint)
+    || normalizeString(evidence?.source_build_fingerprint)
+    || null;
+}
+
+function sourcePackageMaterialFingerprint(stage, evidence) {
+  return normalizeString(stage?.source_package_material_fingerprint)
+    || normalizeString(evidence?.source_package_material_fingerprint)
+    || null;
+}
+
+function completedAt(stage, evidence) {
+  return normalizeString(stage?.completed_at)
+    || normalizeString(evidence?.completed_at)
+    || null;
+}
+
+function commandMentionsBuild(stage, evidence) {
+  const commands = [
+    ...(Array.isArray(stage?.commands) ? stage.commands : []),
+    ...(Array.isArray(evidence?.commands) ? evidence.commands : []),
+  ];
+  return commands.some((entry) => /next-campaigns-build|campaigns-os\s+next\s+build/i.test(String(isObject(entry) ? entry.command || entry.name || "" : entry)));
+}
+
+function evaluateStructuredPolishGate({ report, required = false, now = Date.now(), currentOutputFingerprint = null } = {}) {
+  if (!isObject(report)) {
+    return required
+      ? {
+          status: "blocked",
+          code: "polish.report_missing",
+          reason: "Polish evidence missing for current build. Run next-campaigns-polish before QA.",
+          required_actions: [{ id: "run_polish", kind: "skill", command: "next-campaigns-polish", description: "Run the distinct Polish stage and record structured evidence on stages.polish." }],
+        }
+      : { status: "not_applicable", code: "polish.not_applicable", reason: "No assembly report is available to evaluate polish evidence." };
+  }
+
+  if (!terminalAssembly(report)) {
+    return {
+      status: "not_applicable",
+      code: "polish.not_applicable",
+      reason: "Assembly is not completed yet; polish evidence is required after build completion.",
+    };
+  }
+
+  const buildFingerprint = currentBuildFingerprint(report);
+  const currentSourcePackageFingerprint = currentSourcePackageMaterialFingerprint(report);
+  const assemblySourcePackageFingerprint = assemblySourcePackageMaterialFingerprint(report);
+  const waiverAssessment = assessAssemblySourcePackageFreshnessWaivers(report, now);
+  const sourcePackageFreshnessWaiver = waiverAssessment.active;
+  const expiredWaiver = waiverAssessment.expired[0] || null;
+  const stage = report.stages?.polish;
+  const evidence = polishEvidence(stage, report);
+  const buildRequiredActions = [
+    {
+      id: "rerun_build",
+      kind: "skill",
+      command: "next-campaigns-build",
+      description: "Re-run Build/Assembly against the current Design Source Package and record stages.assembly.source_package_material_fingerprint before Polish.",
+    },
+  ];
+  const requiredActions = [
+    {
+      id: "run_polish",
+      kind: "skill",
+      command: "next-campaigns-polish",
+      description: "Run the distinct Polish stage and record stages.polish.performed_by, source_build_fingerprint, source_package_material_fingerprint when available, completed_at, and structured evidence.",
+    },
+  ];
+
+  if (waiverAssessment.invalid.length) {
+    const invalid = waiverAssessment.invalid[0];
+    return {
+      status: "blocked",
+      code: "polish.waiver_expires_at_invalid",
+      reason: `Source freshness waiver has an unparseable expires_at (${JSON.stringify(invalid.expires_at)}). Record a valid ISO 8601 timestamp, or remove the malformed waiver, before Polish/QA.`,
+      build_fingerprint: buildFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      waiver: invalid,
+      required_actions: [
+        {
+          id: "repair_waiver",
+          kind: "manual",
+          command: null,
+          description: "Correct the waiver's expires_at to a valid ISO 8601 timestamp (or remove the malformed waiver record) on the assembly report.",
+        },
+      ],
+    };
+  }
+
+  if (!buildFingerprint) {
+    return {
+      status: "blocked",
+      code: "polish.build_fingerprint_missing",
+      reason: "Current build artifact fingerprint is missing. Build must record stages.assembly.build_fingerprint before Polish/QA handoff.",
+      required_actions: requiredActions,
+    };
+  }
+
+  if (assemblySourcePackageFingerprintMissing(report, now, waiverAssessment)) {
+    return {
+      status: "blocked",
+      code: "polish.assembly_source_package_fingerprint_missing",
+      reason: expiredWaiver
+        ? `Assembly is not tied to the current Design Source Package material fingerprint, and the recorded source freshness waiver expired at ${expiredWaiver.expires_at}. Re-run Build before Polish (or record a new waiver).`
+        : "Assembly is not tied to the current Design Source Package material fingerprint. Re-run Build before Polish.",
+      build_fingerprint: buildFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      ...(expiredWaiver ? { expired_waiver: expiredWaiver } : {}),
+      required_actions: buildRequiredActions,
+    };
+  }
+  if (currentSourcePackageFingerprint && assemblySourcePackageFingerprint !== currentSourcePackageFingerprint && !sourcePackageFreshnessWaiver) {
+    return {
+      status: "blocked",
+      code: "polish.assembly_source_package_stale",
+      reason: expiredWaiver
+        ? `The Design Source Package changed after Build, and the recorded source freshness waiver expired at ${expiredWaiver.expires_at}. Re-run Build against the current source package before Polish (or record a new waiver).`
+        : "The Design Source Package changed after Build. Re-run Build against the current source package before Polish.",
+      build_fingerprint: buildFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      ...(expiredWaiver ? { expired_waiver: expiredWaiver } : {}),
+      required_actions: buildRequiredActions,
+    };
+  }
+
+  if (!isObject(stage)) {
+    return {
+      status: "blocked",
+      code: "polish.evidence_missing",
+      reason: "Polish evidence missing for current build. Run next-campaigns-polish before QA.",
+      build_fingerprint: buildFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+
+  const status = stageStatus(stage);
+  if (status === "blocked") {
+    return {
+      status: "blocked",
+      code: "polish.blocked",
+      reason: "Polish is recorded as blocked. Resolve the Polish blockers before QA.",
+      build_fingerprint: buildFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+  if (!stageSucceeded(stage)) {
+    return {
+      status: "blocked",
+      code: "polish.evidence_missing",
+      reason: "Polish evidence missing for current build. Run next-campaigns-polish before QA.",
+      build_fingerprint: buildFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+
+  const producer = performedBy(stage, evidence);
+  if (producer !== POLISH_PRODUCER || commandMentionsBuild(stage, evidence)) {
+    return {
+      status: "blocked",
+      code: "polish.self_certified",
+      reason: `Polish success must be produced by ${POLISH_PRODUCER}, not ${producer || "an unspecified or build-owned producer"}. Run a distinct Polish stage before QA.`,
+      build_fingerprint: buildFingerprint,
+      performed_by: producer,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+
+  const sourceFingerprint = sourceBuildFingerprint(stage, evidence);
+  if (!sourceFingerprint) {
+    return {
+      status: "blocked",
+      code: "polish.source_build_fingerprint_missing",
+      reason: "Polish evidence is not tied to the current build artifact fingerprint. Re-run next-campaigns-polish against the current build before QA.",
+      build_fingerprint: buildFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+  // The value the evidence must match is the fingerprint of the output on
+  // disk when the caller could recompute it (doctor, QA), not the string build
+  // recorded: evidence that matches a recorded value the output has since
+  // drifted from is stale in exactly the same way.
+  const outputFingerprint = normalizeString(currentOutputFingerprint);
+  if (outputFingerprint && outputFingerprint !== buildFingerprint) {
+    return {
+      status: "blocked",
+      code: "polish.output_drift",
+      reason: `Built output no longer matches stages.assembly.build_fingerprint (recorded ${buildFingerprint}, current ${outputFingerprint}); polish evidence is bound to a build that no longer exists. Re-run build, then next-campaigns-polish before QA.`,
+      build_fingerprint: buildFingerprint,
+      current_output_fingerprint: outputFingerprint,
+      source_build_fingerprint: sourceFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: mergeRequiredActions([
+        {
+          id: "rerun_build",
+          kind: "skill",
+          command: "next-campaigns-build",
+          description: "Re-run Build (page-kit build) and record the current output fingerprint (doctor --json derived.build_output_fingerprint.value) on stages.assembly.build_fingerprint before Polish.",
+        },
+      ], requiredActions),
+    };
+  }
+  if (sourceFingerprint !== buildFingerprint) {
+    return {
+      status: "blocked",
+      code: "polish.stale",
+      reason: "Polish evidence is stale for the current build artifact fingerprint. Re-run next-campaigns-polish before QA.",
+      build_fingerprint: buildFingerprint,
+      source_build_fingerprint: sourceFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+
+  const polishSourcePackageFingerprint = sourcePackageMaterialFingerprint(stage, evidence);
+  if (currentSourcePackageFingerprint && !polishSourcePackageFingerprint) {
+    return {
+      status: "blocked",
+      code: "polish.source_package_material_fingerprint_missing",
+      reason: "Polish evidence is not tied to the current Design Source Package material fingerprint. Re-run next-campaigns-polish against the current source package before QA.",
+      build_fingerprint: buildFingerprint,
+      source_build_fingerprint: sourceFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+  if (currentSourcePackageFingerprint && polishSourcePackageFingerprint !== currentSourcePackageFingerprint) {
+    return {
+      status: "blocked",
+      code: "polish.source_package_stale",
+      reason: "Polish evidence is stale for the current Design Source Package material fingerprint. Re-run next-campaigns-polish before QA.",
+      build_fingerprint: buildFingerprint,
+      source_build_fingerprint: sourceFingerprint,
+      source_package_material_fingerprint: polishSourcePackageFingerprint,
+      current_source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+
+  if (!completedAt(stage, evidence)) {
+    return {
+      status: "blocked",
+      code: "polish.completed_at_missing",
+      reason: "Polish evidence is missing completed_at. Re-run or repair the Polish stage record before QA.",
+      build_fingerprint: buildFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      required_actions: requiredActions,
+    };
+  }
+
+  const problems = evidenceProblems(evidence, report);
+  if (problems.length) {
+    return {
+      status: "blocked",
+      code: "polish.evidence_incomplete",
+      reason: "Polish evidence is incomplete for the current build. Run next-campaigns-polish before QA.",
+      build_fingerprint: buildFingerprint,
+      source_package_material_fingerprint: currentSourcePackageFingerprint,
+      assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+      waiver: sourcePackageFreshnessWaiver,
+      problems,
+      required_actions: requiredActions,
+    };
+  }
+
+  const warnings = [];
+  if (!currentSourcePackageFingerprint) {
+    warnings.push({
+      code: "polish.source_package_material_fingerprint_unavailable",
+      message: "No current Design Source Package material fingerprint is available; Polish freshness is using legacy build-fingerprint-only behavior.",
+    });
+  }
+
+  const waivedAssemblyFreshness = Boolean(sourcePackageFreshnessWaiver);
+  return {
+    status: waivedAssemblyFreshness ? "waived" : "pass",
+    code: waivedAssemblyFreshness ? "polish.assembly_source_package_waived" : "polish.evidence_current",
+    reason: waivedAssemblyFreshness
+      ? `Polish evidence is current, structured, and produced by next-campaigns-polish under source freshness waiver: ${sourcePackageFreshnessWaiver.reason}`
+      : "Polish evidence is current, structured, and produced by next-campaigns-polish.",
+    build_fingerprint: buildFingerprint,
+    source_build_fingerprint: sourceFingerprint,
+    source_package_material_fingerprint: polishSourcePackageFingerprint || null,
+    current_source_package_material_fingerprint: currentSourcePackageFingerprint,
+    assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
+    performed_by: producer,
+    waiver: sourcePackageFreshnessWaiver,
+    warnings,
+  };
+}
+
+function mergeRequiredActions(...groups) {
+  const actions = [];
+  const seen = new Set();
+  for (const action of groups.flat()) {
+    if (!isObject(action) || !nonEmptyString(action.id) || seen.has(action.id)) continue;
+    seen.add(action.id);
+    actions.push(action);
+  }
+  return actions;
+}
+
+function ownedCheckpointBlock(hiddenEagerMediaGate) {
+  if (isObject(hiddenEagerMediaGate)
+    && hiddenEagerMediaGate.id === HIDDEN_EAGER_MEDIA_SCOPE
+    && hiddenEagerMediaGate.status === "blocked"
+    && nonEmptyString(hiddenEagerMediaGate.code)
+    && nonEmptyString(hiddenEagerMediaGate.reason)) {
+    return {
+      code: hiddenEagerMediaGate.code,
+      reason: hiddenEagerMediaGate.reason,
+      required_actions: mergeRequiredActions(hiddenEagerMediaGate.required_actions || []),
+    };
+  }
+  return {
+    code: "polish.hidden_eager_media.capture_malformed",
+    reason: "Package-owned page-load evidence is missing or malformed; run polish capture before completing Polish.",
+    required_actions: [HIDDEN_EAGER_MEDIA_ACTIONS.capture],
+  };
+}
+
+// The hidden eager-media checkpoint is a package-owned category of Polish,
+// but its authority depends on the current packet route plan. Callers compute
+// that checkpoint from their one packet/report snapshot and inject it here;
+// this evaluator never self-reads a second, potentially inconsistent snapshot.
+export function evaluatePolishGate({
+  report,
+  required = false,
+  now = Date.now(),
+  hiddenEagerMediaGate = undefined,
+  currentOutputFingerprint = null,
+} = {}) {
+  const base = evaluateStructuredPolishGate({ report, required, now, currentOutputFingerprint });
+  if (!terminalAssembly(report)) return base;
+  if (hiddenEagerMediaGate === undefined && !required) return base;
+
+  const ownedId = HIDDEN_EAGER_MEDIA_SCOPE;
+  const hiddenStatus = hiddenEagerMediaGate?.id === ownedId
+    ? hiddenEagerMediaGate.status
+    : null;
+  if (hiddenStatus !== "pass" && hiddenStatus !== "waived") {
+    const owned = ownedCheckpointBlock(hiddenEagerMediaGate);
+    if (base.status === "blocked") {
+      return {
+        ...base,
+        required_actions: mergeRequiredActions(base.required_actions || [], owned.required_actions),
+        owned_checkpoint_id: ownedId,
+        owned_checkpoint_status: "blocked",
+        owned_checkpoint_only: false,
+      };
+    }
+    return {
+      ...base,
+      status: "blocked",
+      code: owned.code,
+      reason: owned.reason,
+      required_actions: owned.required_actions,
+      owned_checkpoint_id: ownedId,
+      owned_checkpoint_status: "blocked",
+      owned_checkpoint_only: true,
+    };
+  }
+
+  if (hiddenStatus === "waived" && base.status !== "blocked") {
+    const hiddenOnly = base.status === "pass";
+    return {
+      ...base,
+      status: "waived",
+      code: hiddenOnly ? hiddenEagerMediaGate.code : base.code,
+      reason: `${base.reason} ${hiddenEagerMediaGate.reason}`,
+      ...(hiddenOnly && hiddenEagerMediaGate.waiver ? { waiver: hiddenEagerMediaGate.waiver } : {}),
+      owned_checkpoint_id: ownedId,
+      owned_checkpoint_status: "waived",
+      owned_checkpoint_only: hiddenOnly,
+    };
+  }
+
+  return {
+    ...base,
+    owned_checkpoint_id: ownedId,
+    owned_checkpoint_status: hiddenStatus,
+    owned_checkpoint_only: false,
+  };
+}