@nextcommerce/campaigns-os 1.33.0

package/src/qa-verdict-discovery.mjs

@@ -0,0 +1,192 @@
+// QA verdict discovery: the one walk over the local verdicts a campaign has
+// written, with the projections each reader needs.
+//
+// `qa run` writes full verdicts to `<target repo>/qa-output/<campaign_slug>/
+// <run_id>.json`, and the Assembly Report's qa stage records the paths it
+// produced. Three readers walked that on their own — the ledger-divergence
+// check (repo-relative list), run-record inference (the best candidate by
+// identity score and time) and closeout (digests of the recorded paths) —
+// each with its own copy of the identity rule and the directory spelling.
+//
+// A leaf: node built-ins, the workspace constant and the string leaves only.
+
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { QA_OUTPUT_REL_PATH } from "./campaign-workspace.mjs";
+import { absentOrMalformed } from "./fs-identity.mjs";
+import { isPlainObject as isObject, normalizeString as optionalString } from "./repo-scan.mjs";
+import { normalizePublicRouteSlug } from "./route-identity.mjs";
+
+// The slug as identity, null when absent: the one spelling the identifiers
+// and the candidate score both read.
+function qaVerdictSlug(packet) {
+  return normalizePublicRouteSlug(packet?.campaign?.public_route_slug) || null;
+}
+
+// The names a campaign's verdicts are filed and stamped under: the map id and
+// the slug as identity. A verdict is this campaign's when its campaign_slug
+// is one of them.
+export function qaVerdictIdentifiers(packet) {
+  return [...new Set([optionalString(packet?.spec?.map_id), qaVerdictSlug(packet)].filter(Boolean))];
+}
+
+export function qaVerdictIdentityMatch(verdict, packet) {
+  const slug = optionalString(verdict?.campaign_slug);
+  return Boolean(slug) && qaVerdictIdentifiers(packet).includes(slug);
+}
+
+// `<root>/qa-output/<identifier>` — the directory `qa run` writes under.
+export function qaVerdictDir(root, identifier) {
+  return join(root, QA_OUTPUT_REL_PATH, identifier);
+}
+
+// The verdict paths the Assembly Report's qa stage records (any `*.json`
+// string under a path/file/verdict/output-named key, or inside outputs[] /
+// artifacts[] / qa), relative to the report unless absolute.
+export function qaVerdictPathHints(report) {
+  const paths = [];
+  const visit = (value) => {
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+      return;
+    }
+    if (isObject(value)) {
+      for (const [key, item] of Object.entries(value)) {
+        if (typeof item === "string" && /(?:path|file|verdict|output)$/i.test(key)) visit(item);
+        else if (key === "outputs" || key === "artifacts" || key === "qa") visit(item);
+      }
+      return;
+    }
+    if (typeof value === "string" && /\.json(?:[?#].*)?$/i.test(value.trim())) paths.push(value.trim());
+  };
+  visit(report?.qa || null);
+  visit(report?.stages?.qa || null);
+  return [...new Set(paths)];
+}
+
+function readVerdictFile(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return isObject(parsed) ? parsed : null;
+  } catch (error) {
+    if (absentOrMalformed(error)) return null;
+    throw error;
+  }
+}
+
+function sha256File(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+// Every verdict candidate for a campaign: the files the report records
+// (source "assembly_report", resolved against the report) and every `*.json`
+// under `qa-output/<identifier>/` beneath each root (source "qa_output").
+//   { path, repoRelPath, source, verdict, sha256, mtimeMs, identityMatch, trusted }
+// `verdict` is null for a recorded path that exists but is not a JSON object
+// (it still has a digest: closeout compares bytes, not shape). `trusted` is
+// false only for a verdict the receiver stamped `trusted: false` (an
+// anonymous submission); locally written verdicts never carry the field.
+// An absent directory or file, or a file that is not JSON, is no candidate;
+// any other read failure (a permission error, an I/O error) is the caller's.
+//
+// Lazy per candidate: a directory's names are listed when the walk reaches
+// it, but each file is read (and hashed, when asked) only as the consumer
+// pulls it, so a reader that stops early — closeout after a few digests —
+// pays for what it took, not for every recorded path or every listed file.
+export function* iterateQaVerdicts({ packet = null, report = null, reportPath = null, roots = [], withDigest = false } = {}) {
+  const seen = new Set();
+  const candidate = (path, source, repoRelPath) => {
+    const absolute = resolve(path);
+    if (seen.has(absolute)) return null;
+    let stats;
+    try {
+      stats = statSync(absolute);
+    } catch (error) {
+      if (absentOrMalformed(error)) return null;
+      throw error;
+    }
+    if (!stats.isFile()) return null;
+    seen.add(absolute);
+    const verdict = readVerdictFile(absolute);
+    let sha256 = null;
+    if (withDigest) {
+      try {
+        sha256 = sha256File(absolute);
+      } catch (error) {
+        // The file can vanish between the stat and the read; nothing else may.
+        if (!absentOrMalformed(error)) throw error;
+      }
+    }
+    return {
+      path: absolute,
+      repoRelPath,
+      source,
+      verdict,
+      sha256,
+      mtimeMs: stats.mtimeMs,
+      identityMatch: verdict ? qaVerdictIdentityMatch(verdict, packet) : false,
+      trusted: verdict?.trusted !== false,
+    };
+  };
+
+  const reportBase = reportPath ? dirname(resolve(reportPath)) : null;
+  for (const hint of qaVerdictPathHints(report)) {
+    const found = candidate(reportBase ? resolve(reportBase, hint) : hint, "assembly_report", null);
+    if (found) yield found;
+  }
+
+  const uniqueRoots = [...new Set(roots.filter((root) => typeof root === "string" && root).map((root) => resolve(root)))];
+  for (const root of uniqueRoots) {
+    for (const identifier of qaVerdictIdentifiers(packet)) {
+      const dir = qaVerdictDir(root, identifier);
+      let names = [];
+      try {
+        names = readdirSync(dir, { withFileTypes: true })
+          .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+          .map((entry) => entry.name)
+          .sort();
+      } catch (error) {
+        if (absentOrMalformed(error)) continue;
+        throw error;
+      }
+
+      for (const name of names) {
+        const path = join(dir, name);
+        // Repo-relative on purpose: divergence evidence must read the same
+        // wherever the repo sits on disk.
+        const found = candidate(path, "qa_output", relative(root, path).split("\\").join("/"));
+        if (found) yield found;
+      }
+    }
+  }
+}
+
+export function discoverQaVerdicts(options = {}) {
+  return [...iterateQaVerdicts(options)];
+}
+
+// Run-record inference: how well a candidate answers "this campaign, this
+// deployment". Identity first, then the verdict schema, then a deploy origin
+// the assertions actually visited.
+export function qaVerdictCandidateScore(candidate, packet) {
+  const verdict = candidate?.verdict || {};
+  const mapId = optionalString(packet?.spec?.map_id);
+  const slug = qaVerdictSlug(packet);
+  let score = 0;
+  if (mapId && verdict.campaign_slug === mapId) score += 100;
+  if (slug && verdict.campaign_slug === slug) score += 80;
+  if (verdict.schema_version === "1.0" || verdict.schema_version === "campaigns-os-qa-verdict/v0") score += 10;
+  const deployOrigins = [optionalString(packet?.deploy?.preview_url), optionalString(packet?.deploy?.production_url)].filter(Boolean);
+  const assertionUrls = Array.isArray(verdict.assertions)
+    ? verdict.assertions.map((assertion) => optionalString(assertion?.url)).filter(Boolean)
+    : [];
+  if (deployOrigins.some((origin) => assertionUrls.some((url) => url.startsWith(origin)))) score += 25;
+  return score;
+}
+
+export function qaVerdictCandidateTime(candidate) {
+  const completedAt = Date.parse(candidate?.verdict?.completed_at || "");
+  if (Number.isFinite(completedAt)) return completedAt;
+  return Number(candidate?.mtimeMs || 0);
+}

package/src/qa-verdict-publish.mjs

@@ -0,0 +1,105 @@
+// The one QA-verdict publish rail. `qa run` and `qa publish` both post a
+// verdict to the QA portal through `publishQaVerdict`, and both stamp what
+// came back onto the Run Record through `qaVerdictPublishBlock`, so a verdict
+// published at the end of a run and one published later from disk are
+// classified by the same rule and recorded in the same shape.
+//
+// The outcome is classified the way the Run Record remit is (#397): by what
+// the receiver answered, not by whether the transport threw. A 409 is
+// `already_stored` — the portal already holds this run_id, which is the
+// outcome the send was for — and a 2xx with a non-JSON body is an
+// acknowledgement whose payload could not be read, not a refusal. Only
+// another non-2xx, or a transport failure, is a failed publish.
+
+import { classifyRemitOutcome, describeRemitBaseKind, remit } from "./remit.mjs";
+
+export const QA_VERDICT_PUBLISH_ENDPOINT = "/api/qa/verdicts";
+
+// Who published: the run that produced the verdict, or a later `qa publish`
+// of the stored copy. Carried on the Run Record block so a reader can tell a
+// verdict that went out with its run from one published from disk.
+export const QA_VERDICT_PUBLISHERS = Object.freeze({
+  run: "qa run",
+  publish: "qa publish",
+});
+
+// The durable states the Run Record block carries. `skipped` is a run whose
+// publish was off (`--no-post-verdict`, consent off); `ok` and `failed` are a
+// send the receiver answered or did not, classified in `result`.
+export const QA_VERDICT_PUBLISH_STATES = Object.freeze(["skipped", "ok", "failed"]);
+
+/**
+ * POST `verdict` to `<proxyBase>/api/qa/verdicts` and classify the answer.
+ * Never throws for a receiver or transport failure — the caller decides what
+ * a failed publish means (a `qa run` keeps its local verdict and reports; a
+ * `qa publish` exits non-zero). Returns:
+ *
+ *   { attempted: true, ok, error, endpoint, result, http_status, base_kind, response }
+ *
+ * `response` is the parsed receiver body on a parsed 2xx, else null. The
+ * publish attaches no credential, and says so to the transport gate: plain
+ * http is still refused for anything but a loopback receiver, but the warning
+ * must not claim a credential is travelling in clear.
+ */
+export async function publishQaVerdict(verdict, proxyBase, { fetchImpl = globalThis.fetch, remitImpl = remit } = {}) {
+  let httpStatus = null;
+  let response = null;
+  let failure = null;
+  try {
+    response = await remitImpl(QA_VERDICT_PUBLISH_ENDPOINT, verdict, proxyBase, {
+      fetchImpl,
+      label: "QA verdict publish",
+      credential: null,
+      onResponse: (answer) => {
+        httpStatus = Number(answer?.status) || null;
+      },
+    });
+  } catch (error) {
+    failure = error;
+  }
+  const outcome = classifyRemitOutcome(failure);
+  return {
+    attempted: true,
+    ok: outcome.ok,
+    error: outcome.error,
+    endpoint: QA_VERDICT_PUBLISH_ENDPOINT,
+    result: outcome.result,
+    http_status: outcome.http_status ?? httpStatus,
+    base_kind: describeRemitBaseKind(proxyBase),
+    response: outcome.ok && !failure ? response : null,
+  };
+}
+
+/** The outcome block for a run whose publish was turned off: nothing sent, nothing known. */
+export function skippedQaVerdictPublish() {
+  return { attempted: false, ok: null, error: null, endpoint: null, result: null, http_status: null, base_kind: null, response: null };
+}
+
+/**
+ * The Run Record's `qa_verdict_publish` block for one publish outcome. The
+ * verdict's run_id is the idempotency key a later `qa publish` reads; the
+ * state is derived from the outcome the same way `remit_state` is from a
+ * remit (`ok` when the receiver's answer counts as stored, `failed` when it
+ * refused or never answered, `skipped` when nothing was sent).
+ */
+export function qaVerdictPublishBlock(outcome, { verdictRunId, publisher, publishedAt = null }) {
+  const attempted = Boolean(outcome?.attempted);
+  const ok = attempted ? outcome.ok === true : null;
+  return {
+    verdict_run_id: String(verdictRunId),
+    publisher,
+    attempted,
+    ok,
+    error: attempted && typeof outcome.error === "string" ? outcome.error : null,
+    endpoint: attempted ? outcome.endpoint ?? QA_VERDICT_PUBLISH_ENDPOINT : null,
+    state: attempted ? (ok ? "ok" : "failed") : "skipped",
+    result: attempted ? outcome.result ?? null : null,
+    base_kind: attempted ? outcome.base_kind ?? null : null,
+    published_at: attempted && ok ? publishedAt : null,
+  };
+}
+
+/** The QA portal link for a published verdict. */
+export function qaPortalUrl(proxyBase, mapId, runId) {
+  return `${String(proxyBase).replace(/\/+$/, "")}/qa?slug=${encodeURIComponent(mapId)}&run=${encodeURIComponent(runId)}`;
+}

package/src/qa-verdict.mjs

@@ -0,0 +1,287 @@
+export const QA_SCHEMA_VERSION = "1.0";
+
+export const STATUS = Object.freeze({
+  PASS: "pass",
+  FAIL: "fail",
+  WARN: "warn",
+  SKIPPED: "skipped",
+  MANUAL_REVIEW: "manual_review",
+});
+
+// The dispositions that END a run session, and the single definition of that
+// set. A blocked attempt keeps the session open for repair; these close it.
+//
+// Both sides of the decision read this: autoEndRunSessionAfterTerminalQa, which
+// closes the session and remits under its run_id, and buildQaCloseoutActions,
+// which prints the run-record command an operator runs next. Membership is
+// enumerated rather than excluded so an unrecognised disposition — a newer
+// toolkit's verdict, a foreign one — falls on the session-keeping side for
+// BOTH. Getting that backwards on one side only is the whole bug class: the
+// printed command would spend a run_id the session still holds, and the
+// session's own close would then be refused 409 by the receiver, which stores
+// one record per run_id and has no replace verb.
+export const SESSION_ENDING_DISPOSITIONS = Object.freeze(new Set(["ready", "ready_with_exceptions"]));
+
+export const SEVERITY = Object.freeze({
+  INFO: "info",
+  WARN: "warn",
+  BLOCKER: "blocker",
+});
+
+// Canonical vocabulary of every assertion family the QA runner emits. External
+// consumers (e.g. the portal proxy's verdict allowlist) import this instead of
+// scanning emitter source for `family:` literals. Order is load-bearing:
+// theme_gate first, then the gate-suppressed families in the order a
+// gate-blocked verdict emits its skipped audit assertions —
+// GATE_SUPPRESSED_FAMILIES in qa-node.mjs derives from this list. A drift test
+// in qa-verdict.test.mjs asserts set equality against the literals the
+// emitters actually use.
+export const QA_ASSERTION_FAMILY_VOCABULARY = Object.freeze([
+  "theme_gate",
+  "polish_gate",
+  "funnel-flow",
+  "meta-tags",
+  "api-metadata",
+  "browser-runtime",
+  "template_residue",
+  "pricing",
+  "browser-test-order",
+  "browser-receipt-rendering",
+  "analytics-correctness",
+  "analytics-parity",
+  "parity-capture",
+]);
+
+// A waiver record riding an assertion (packet 01: the `qa waive` lane for
+// analytics-correctness:purchase-fires). Shape mirrors report.theme.waiver:
+// { reason, waived_by, waived_at }.
+function assertionCarriesWaiver(assertion) {
+  const waiver = assertion?.waiver;
+  return !!(waiver && typeof waiver === "object" && !Array.isArray(waiver));
+}
+
+export function computeDisposition(assertions) {
+  let hasBlocker = false;
+  let hasSoftIssue = false;
+  for (const assertion of assertions) {
+    if (assertion.status === STATUS.FAIL && assertion.severity === SEVERITY.BLOCKER) {
+      hasBlocker = true;
+    } else if (
+      assertion.status === STATUS.WARN ||
+      assertion.status === STATUS.MANUAL_REVIEW ||
+      (assertion.status === STATUS.FAIL && assertion.severity === SEVERITY.WARN) ||
+      // Packet 01 / ratified I-9: a waived blocker is an accepted exception,
+      // never a clean pass — any assertion carrying a waiver record keeps the
+      // disposition at ready_with_exceptions, never plain ready. (An unwaived
+      // failing blocker still lands in the branch above and blocks.)
+      assertionCarriesWaiver(assertion)
+    ) {
+      hasSoftIssue = true;
+    }
+  }
+  if (hasBlocker) return "blocked";
+  if (hasSoftIssue) return "ready_with_exceptions";
+  return "ready";
+}
+
+function dispositionWithCommercial(assertions, commercial) {
+  const disposition = computeDisposition(assertions);
+  if (disposition === "blocked") return disposition;
+  return commercial?.status === "mismatch"
+    ? "ready_with_exceptions"
+    : disposition;
+}
+
+export function createVerdict({
+  runId,
+  mapId,
+  publicRouteSlug = null,
+  campaignRefId = null,
+  specVersion,
+  specHash,
+  startedAt,
+  completedAt,
+  runtime,
+  operator = "",
+  baseUrl = null,
+  entryUrls = [],
+  pageUrls = [],
+  testedUrls = [],
+  assertions,
+  testOrders = [],
+  exceptions = null,
+  commercial = null,
+  causeSummary = null,
+  browser = null,
+}) {
+  const normalizedExceptions = Array.isArray(exceptions)
+    ? exceptions
+    : deriveExceptions(assertions);
+  const normalizedBaseUrl = optionalString(baseUrl);
+  const normalizedEntryUrls = Array.isArray(entryUrls) ? entryUrls : [];
+  const normalizedPageUrls = Array.isArray(pageUrls) ? pageUrls : [];
+  const normalizedTestedUrls = Array.isArray(testedUrls) ? testedUrls : [];
+  return {
+    schema_version: QA_SCHEMA_VERSION,
+    run_id: runId,
+    // campaign_slug carries the Map ID for schema back-compat; the true public
+    // route slug rides alongside so consumers stop conflating the two.
+    campaign_slug: mapId,
+    public_route_slug: optionalString(publicRouteSlug),
+    campaign_ref_id: campaignRefId,
+    spec_version: specVersion,
+    spec_hash: specHash,
+    started_at: startedAt,
+    completed_at: completedAt,
+    runtime,
+    operator,
+    ...(normalizedBaseUrl ? { base_url: normalizedBaseUrl } : {}),
+    entry_urls: normalizedEntryUrls,
+    page_urls: normalizedPageUrls,
+    tested_urls: normalizedTestedUrls,
+    disposition: dispositionWithCommercial(assertions, commercial),
+    assertions,
+    test_orders: testOrders,
+    exceptions: normalizedExceptions,
+    ...(commercial && typeof commercial === "object" && !Array.isArray(commercial)
+      ? { commercial }
+      : {}),
+    // Additive, and present ONLY when the run has something to say about a
+    // requested browser pass it did not perform — today, a --browser run a
+    // blocked gate finalized before any page was rendered. Absence therefore
+    // means "this verdict makes no claim about the browser pass", not "the
+    // browser pass ran": consumers read the browser-runtime assertions and
+    // tested_urls for that, exactly as they did before the field existed.
+    ...(browser && typeof browser === "object" && !Array.isArray(browser)
+      ? { browser }
+      : {}),
+    // Additive, and absent on verdicts emitted before per-finding cause
+    // classification existed. Consumers must tolerate its absence rather than
+    // read a missing summary as "nothing was caused by the change".
+    ...(causeSummary && typeof causeSummary === "object" && !Array.isArray(causeSummary)
+      ? { cause_summary: causeSummary }
+      : {}),
+  };
+}
+
+function optionalString(value) {
+  if (value == null) return null;
+  const text = String(value).trim();
+  return text || null;
+}
+
+/**
+ * Is this assertion a FINDING — something the operator has to look at — rather
+ * than a clean pass? One definition, because the exception projection and the
+ * per-finding cause classification must count the same set: a summary that
+ * says "11 findings, 9 pre-existing" is unreadable if "finding" means one
+ * thing in the count and another in the list.
+ */
+export function isFindingAssertion(assertion) {
+  return assertion?.status === STATUS.FAIL
+    || assertion?.status === STATUS.WARN
+    || assertion?.status === STATUS.MANUAL_REVIEW
+    || assertion?.severity === SEVERITY.WARN
+    || assertion?.severity === SEVERITY.BLOCKER;
+}
+
+export function deriveExceptions(assertions = []) {
+  if (!Array.isArray(assertions)) return [];
+  return assertions
+    .filter((assertion) => isFindingAssertion(assertion))
+    .map((assertion) => ({
+      id: assertion.id || null,
+      family: assertion.family || null,
+      page: assertion.page || null,
+      url: assertion.url || null,
+      status: assertion.status || null,
+      severity: assertion.severity || null,
+      expected: assertion.expected,
+      actual: assertion.actual,
+      // Cause rides the projection so the exceptions list — the quick read an
+      // operator or portal actually looks at — answers "was this us?" without
+      // re-joining back to the assertions array.
+      ...(assertion.cause !== undefined ? { cause: assertion.cause } : {}),
+      ...(assertion.cause_reason !== undefined ? { cause_reason: assertion.cause_reason } : {}),
+    }));
+}
+
+export function validateVerdict(verdict) {
+  const errors = [];
+  if (!verdict || typeof verdict !== "object" || Array.isArray(verdict)) {
+    return ["verdict: must be an object"];
+  }
+  for (const field of ["run_id", "campaign_slug", "spec_version", "spec_hash", "started_at", "completed_at", "runtime", "disposition"]) {
+    if (typeof verdict[field] !== "string" || verdict[field].length === 0) errors.push(`${field}: required non-empty string`);
+  }
+  if (verdict.schema_version !== QA_SCHEMA_VERSION) errors.push(`schema_version: expected ${QA_SCHEMA_VERSION}`);
+  if (!Array.isArray(verdict.assertions)) errors.push("assertions: must be an array");
+  if (!Array.isArray(verdict.test_orders)) errors.push("test_orders: must be an array");
+  if (!Array.isArray(verdict.exceptions)) errors.push("exceptions: must be an array");
+  if (verdict.commercial !== undefined
+    && (!verdict.commercial || typeof verdict.commercial !== "object" || Array.isArray(verdict.commercial))) {
+    errors.push("commercial: must be an object when present");
+  }
+  return errors;
+}
+
+// Purchase-proof coverage summary.
+//
+// COUNTS ONLY, deliberately. This summary is written onto the Assembly Report's
+// qa stage, which is committed and rides into the readback bundle. The sidecar
+// projection strips order ids, refs, emails and checkout URLs out of the verdict
+// before it can be published, and sidecar-bundle conformance FAILS a bundle
+// whose projected order arrays are non-empty. So the signal that a purchase
+// actually happened has to be numbers, never the orders themselves.
+export function summarizePurchaseProof({ verdict = null, proofPolicy = null } = {}) {
+  const orders = Array.isArray(verdict?.test_orders) ? verdict.test_orders.filter((order) => order && typeof order === "object") : [];
+  // A real id is a non-empty trimmed string or a POSITIVE number. Numeric `0`
+  // is the conventional placeholder the runner emits when an id was never
+  // received, and `Number.isFinite(0)` is true — counting it would report an
+  // order as created on a run that created nothing. Note the `??` chain stops
+  // at a literal `0` (it is not nullish), so a zero here is never rescued by
+  // the next field either; both facts push the same way, toward not counting.
+  const created = orders.filter((order) => {
+    const id = order.next_order_id ?? order.order_id ?? order.ref_id;
+    if (typeof id === "string") return id.trim().length > 0;
+    return Number.isFinite(id) && id > 0;
+  });
+  return {
+    declared_order_path_depth: optionalString(proofPolicy?.order_path_depth),
+    declared_typed_card_depth: optionalString(proofPolicy?.typed_card_depth),
+    order_paths_executed: orders.length,
+    orders_created: created.length,
+    orders_verified: orders.filter((order) => order.verification?.verified === true).length,
+    // null, not false, when nothing ran: "no order was out of test mode" and
+    // "no order ran at all" are different facts.
+    all_orders_test_mode: orders.length ? orders.every((order) => order.is_test === true) : null,
+  };
+}
+
+// The browser placeholder-text residue gate (H3.1) emits one assertion per
+// page as `template-residue:<page_id>:placeholder-text`. Both the emitter
+// (qa-browser.mjs) and the stage-ledger summary below build the id from this
+// suffix so the two cannot drift.
+export const PLACEHOLDER_TEXT_ASSERTION_SUFFIX = ":placeholder-text";
+
+export function isPlaceholderTextAssertion(assertion) {
+  const id = optionalString(assertion?.id);
+  return Boolean(id && id.startsWith("template-residue:") && id.endsWith(PLACEHOLDER_TEXT_ASSERTION_SUFFIX));
+}
+
+// What the verdict says about the placeholder-text gate, in a shape the
+// Assembly Report's qa stage can carry: `pass` only when the gate ran on at
+// least one page and no page failed; `fail` when any page failed; null when
+// the gate never ran (gate-skipped verdict, a non-browser run, an older
+// toolkit), so a doctor reading the report cannot mistake silence for a pass.
+export function summarizePlaceholderTextGate(verdict) {
+  const assertions = (Array.isArray(verdict?.assertions) ? verdict.assertions : []).filter(isPlaceholderTextAssertion);
+  const evaluated = assertions.filter((assertion) => assertion.status === STATUS.PASS || assertion.status === STATUS.FAIL);
+  if (!evaluated.length) return null;
+  const failed = evaluated.filter((assertion) => assertion.status === STATUS.FAIL);
+  return {
+    status: failed.length ? STATUS.FAIL : STATUS.PASS,
+    pages_checked: evaluated.length,
+    pages_failed: failed.length,
+  };
+}