@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.0

package/apps/storefront/src/lib/monitoring/manifest.ts

@@ -0,0 +1,302 @@
+/**
+ * Monitoring contract (spec §F16 — monitors, alerts, operator runbooks).
+ *
+ * This is the CHECKED-IN source of truth for "what do we watch, at what
+ * threshold, at what severity, and which runbook fires when it trips." It is
+ * deliberately data, not wiring: Phase 1 ships the *contract* so operators can
+ * see coverage and reviewers can diff it; the actual alert providers (Cloudflare
+ * Health Checks / Workers metrics / Logpush alerts / a RUM sink) are provisioned
+ * out-of-band and each monitor records whether it is `in-code` today or still
+ * `needs-external` / `needs-secret`.
+ *
+ * Signal sources are named against real code where it exists in this repo
+ * (`/health` → lib/health.ts, CSP → pages/api/csp-report.ts + CSP_REPORT_PATH,
+ * commerce events → lib/analytics). Signals owned by sibling units are referenced
+ * by CONTRACT NAME, not imported — Core Web Vitals come from F14's RUM beacon,
+ * and age-verification / restricted-state denials come from F12's compliance
+ * evidence signals. This file does not edit or depend on those units; when they
+ * land, point the corresponding monitor's `observe` at the real sink.
+ *
+ * The companion operator doc renders this for humans and lists the external
+ * wiring/secrets checklist: docs/epics/sample-store-migration/monitoring-and-runbooks.md.
+ * RUNBOOK.md §6–§8 hold the incident runbooks these monitors dispatch to.
+ */
+
+/**
+ * Alert severity, in escalation order.
+ * - `page`     — wake someone now; launch-critical, customer-blocking.
+ * - `critical` — same-business-hours; degraded but not fully down, or a
+ *                compliance/legal risk that must be resolved before more sales.
+ * - `warning`  — investigate; a spike or trend that predicts a `critical`.
+ * - `info`     — record only; useful for post-incident context, no alert.
+ */
+export type Severity = "page" | "critical" | "warning" | "info";
+
+/** What each monitor watches, grouped so a dashboard can lane them. */
+export type MonitorCategory =
+  | "availability"
+  | "commerce"
+  | "compliance"
+  | "catalog"
+  | "performance"
+  | "security";
+
+/**
+ * Provisioning status of a monitor — the honest "is this actually alerting?"
+ * flag so a green manifest never implies coverage we don't have.
+ * - `in-code`        — the signal is emitted by code in THIS repo; only a log
+ *                      or metric alert rule needs attaching.
+ * - `needs-external` — depends on an external provider/probe/sink that must be
+ *                      configured (Cloudflare Health Check, Logpush alert, RUM).
+ * - `needs-secret`   — additionally blocked on a credential/token being set.
+ */
+export type WiringStatus = "in-code" | "needs-external" | "needs-secret";
+
+/**
+ * Stable ids for the six incident runbooks (RUNBOOK.md §7). Every monitor names
+ * the runbook an operator opens when it fires, so detection → response is a
+ * lookup, not archaeology.
+ */
+export type RunbookId =
+  | "checkout-down"
+  | "catalog-stale"
+  | "bad-price"
+  | "compliance-provider-down"
+  | "tax-shipping-outage"
+  | "bad-content-policy";
+
+export interface Monitor {
+  /** Stable kebab-case id; also the alert name. Never renamed once shipped. */
+  id: string;
+  /** One-line human title for dashboards/alerts. */
+  title: string;
+  category: MonitorCategory;
+  /** Where the signal comes from and how a monitor reads it. */
+  signal: {
+    /** The emitter — code symbol/path in this repo, or a named sibling contract. */
+    source: string;
+    /** How the alert observes it: probe, Worker metric, log filter, RUM, webhook. */
+    observe: string;
+  };
+  /** The alarm condition in plain, checkable terms (thresholds are launch defaults). */
+  threshold: string;
+  severity: Severity;
+  /** Which incident runbook to run when this fires. */
+  runbook: RunbookId;
+  wiring: WiringStatus;
+  /** External dependency, secret name, or sibling-unit signal reference. */
+  notes?: string;
+}
+
+/**
+ * The ten launch-critical monitors from spec §F16. Order is presentation order.
+ * Thresholds are the go-live defaults; tune against the 24h post-cutover soak
+ * (T10) and record any change here — this file is the audit trail.
+ */
+export const MONITORS: readonly Monitor[] = [
+  {
+    id: "uptime",
+    title: "Storefront uptime / liveness",
+    category: "availability",
+    signal: {
+      source: "GET /health (lib/health.ts — answered before tenant/gate/cache)",
+      observe: "external synthetic probe hits /health across regions; expects 200 {status:'ok'}",
+    },
+    threshold: "2 consecutive probe failures (or >1% of probes failing over 5m)",
+    severity: "page",
+    runbook: "checkout-down",
+    wiring: "needs-external",
+    notes:
+      "Wire a Cloudflare Health Check (or external uptime monitor) per production host. " +
+      "/health also returns the live commit .sha — use it to confirm which build is up during an incident.",
+  },
+  {
+    id: "page-errors",
+    title: "Page / Worker errors (5xx + unhandled exceptions)",
+    category: "availability",
+    signal: {
+      source: "Cloudflare Worker exceptions + non-2xx responses from middleware/index.ts render path",
+      observe: "Workers 'Errors' metric + Logpush; alert on error-rate over the request baseline",
+    },
+    threshold: "5xx rate > 1% over 5m, or any sustained unhandled-exception stream",
+    severity: "critical",
+    runbook: "bad-content-policy",
+    wiring: "needs-external",
+    notes:
+      "A spike isolated to one route usually points at a bad publish/content artifact (see bad-content-policy); " +
+      "a broad spike is an availability event (checkout-down).",
+  },
+  {
+    id: "checkout-failures",
+    title: "Checkout failures (add-to-cart / checkout handoff)",
+    category: "commerce",
+    signal: {
+      source:
+        "Signed add-to-cart + cross-origin checkout POST (F11; lib/checkoutCommerce.ts, checkoutCspAdditions)",
+      observe:
+        "Worker logs on the signed add-to-cart path + checkout-host success beacon; alert on failure ratio",
+    },
+    threshold: "checkout-start error ratio > 2% over 10m, or add-to-cart 5xx > 1% over 5m",
+    severity: "page",
+    runbook: "checkout-down",
+    wiring: "needs-external",
+    notes:
+      "Checkout completes on the store's cross-origin cart/checkout host, so full funnel coverage needs a beacon " +
+      "from that host too. Storefront-side we can only see the signed handoff; a CSP formAction/frameSrc block " +
+      "also surfaces here as csp-violations.",
+  },
+  {
+    id: "age-verification-failures",
+    title: "Age-verification failures",
+    category: "compliance",
+    signal: {
+      source:
+        "F12 compliance 'age-verification' evidence signal (AgeGate / IsolatedAgeGate → ToT verification)",
+      observe: "F12 evidence signal + ToT verification provider errors; alert on error/timeout rate, not on user-declines",
+    },
+    threshold: "verification provider error/timeout rate > 5% over 10m (distinct from legitimate fail-age outcomes)",
+    severity: "critical",
+    runbook: "compliance-provider-down",
+    wiring: "needs-external",
+    notes:
+      "Reference F12's signal by name; do NOT read the compliance internals here. Distinguish PROVIDER failure " +
+      "(page/critical — we can't legally sell) from a shopper genuinely failing age (expected, not an alert). " +
+      "Pre-launch config-coherence gate is in-repo: GET /api/evidence.json (assembleEvidenceReport → age_gate).",
+  },
+  {
+    id: "restricted-state-denials",
+    title: "Restricted-state / shipping denials (anomaly)",
+    category: "compliance",
+    signal: {
+      source:
+        "F12 compliance 'restricted-state denial' signal (StateEligibilityNotice / ShippingRestrictionNotice / complianceFloor)",
+      observe: "F12 evidence signal counted per state; alert on ANOMALOUS spike vs baseline, not on absolute count",
+    },
+    threshold: "denial rate for a state jumps >3x its 7-day baseline over 1h (mis-configured rule, not normal traffic)",
+    severity: "warning",
+    runbook: "bad-content-policy",
+    wiring: "needs-external",
+    notes:
+      "Denials are EXPECTED (that's the control working). This monitor catches a mis-configured restriction " +
+      "rule that suddenly blocks a legal state — a spike, not a level. Reference F12's signal by name. " +
+      "Pre-launch config-coherence gate is in-repo: GET /api/evidence.json (jurisdiction/excise signals).",
+  },
+  {
+    id: "catalog-sync-failures",
+    title: "Catalog sync failures",
+    category: "catalog",
+    signal: {
+      source: "Migration incremental sync (packages/migration) + F17 catalog graduation job",
+      observe: "sync-job exit status + migration report (errors/skipped); alert on failed or missed run",
+    },
+    threshold: "any sync job fails, OR no successful sync within the expected cadence window (default 1h)",
+    severity: "warning",
+    runbook: "catalog-stale",
+    wiring: "needs-external",
+    notes:
+      "Escalate to critical once a store is on a live source (F17): a failed sync means the catalog is drifting " +
+      "from the merchant source. Depends on F17 defining the launch cadence.",
+  },
+  {
+    id: "inventory-mismatch",
+    title: "Inventory mismatch (oversell risk)",
+    category: "catalog",
+    signal: {
+      source: "F17 inventory-freshness mismatch alarm (storefront-shown vs source-of-truth stock)",
+      observe: "reconciliation check comparing served inventory to the merchant/hosted source",
+    },
+    threshold: "any product served in-stock while source says out-of-stock, or staleness > sync cadence + grace",
+    severity: "critical",
+    runbook: "catalog-stale",
+    wiring: "needs-external",
+    notes:
+      "Overselling regulated goods is a launch-blocker. This alarm is the one F16 defines but F17 FEEDS with real " +
+      "data — until F17 lands it is a contract only.",
+  },
+  {
+    id: "payment-failures",
+    title: "Payment failures",
+    category: "commerce",
+    signal: {
+      source: "Payment provider on the checkout host (external to the storefront Worker)",
+      observe: "payment provider dashboard/webhooks; alert on declined/error rate vs baseline",
+    },
+    threshold: "payment error rate (non-decline gateway errors) > 3% over 15m",
+    severity: "page",
+    runbook: "checkout-down",
+    wiring: "needs-external",
+    notes:
+      "Owned by the checkout/payment provider, not this Worker. Separate genuine card declines (expected) from " +
+      "gateway/integration errors (alert). Coordinate the provider webhook wiring with F11/F17 owners.",
+  },
+  {
+    id: "csp-violations",
+    title: "CSP violations",
+    category: "security",
+    signal: {
+      source: "POST /api/csp-report (CSP_REPORT_PATH / CSP_REPORT_GROUP) — logs '[csp-report]'",
+      observe: "log-based alert on '[csp-report]' volume; CSP is ENFORCED in prod (middleware sets Content-Security-Policy)",
+    },
+    threshold: "sustained new-violation stream (> baseline) — esp. on checkout/widget origins after a publish",
+    severity: "warning",
+    runbook: "bad-content-policy",
+    wiring: "in-code",
+    notes:
+      "Emitter already ships (pages/api/csp-report.ts). Only a log-volume alert rule needs attaching. A spike after " +
+      "a tenant publish means a script/style/frame origin needs adding to the allowlist — or a blocked injection.",
+  },
+  {
+    id: "core-web-vitals",
+    title: "Core Web Vitals (LCP / INP / CLS)",
+    category: "performance",
+    signal: {
+      source: "F14 RUM beacon (web-vitals: LCP, INP, CLS) — Real User Monitoring",
+      observe: "RUM sink p75 per metric per key template (home, PLP, PDP, checkout entry)",
+    },
+    threshold: "p75 regresses past 'good': LCP > 2.5s, INP > 200ms, CLS > 0.1 (sustained over 1h)",
+    severity: "warning",
+    runbook: "bad-content-policy",
+    wiring: "needs-external",
+    notes:
+      "Reference F14's RUM signal by name; do NOT edit F14's analytics files. Cloudflare Web Analytics " +
+      "(PUBLIC_CF_ANALYTICS_TOKEN, injected in Layout.astro) gives field CWV today; F14's beacon gives per-template detail.",
+  },
+] as const;
+
+/**
+ * The monitors §F16 requires by name. The test asserts MONITORS covers exactly
+ * these — so dropping or misnaming one fails CI, and adding a new monitor is a
+ * deliberate edit here.
+ */
+export const REQUIRED_MONITOR_IDS = [
+  "uptime",
+  "page-errors",
+  "checkout-failures",
+  "age-verification-failures",
+  "restricted-state-denials",
+  "catalog-sync-failures",
+  "inventory-mismatch",
+  "payment-failures",
+  "csp-violations",
+  "core-web-vitals",
+] as const;
+
+/** The six incident runbooks in RUNBOOK.md §7 that monitors dispatch to. */
+export const RUNBOOK_IDS: readonly RunbookId[] = [
+  "checkout-down",
+  "catalog-stale",
+  "bad-price",
+  "compliance-provider-down",
+  "tax-shipping-outage",
+  "bad-content-policy",
+] as const;
+
+/** Lookup a monitor by id (undefined if absent). */
+export function getMonitor(id: string): Monitor | undefined {
+  return MONITORS.find((m) => m.id === id);
+}
+
+/** Monitors still needing external wiring or a secret before they alert. */
+export function monitorsNeedingWiring(): readonly Monitor[] {
+  return MONITORS.filter((m) => m.wiring !== "in-code");
+}

package/apps/storefront/src/lib/privacy/emailHint.ts

@@ -6,7 +6,16 @@ function maskPart(part: string): string {
   return `${part.slice(0, 1)}...${part.slice(-1)}`;
 }
 
-/** Display-only email hint for URLs/log-safe UX. Never returns the full address. */
+/**
+ * Display-only email hint for URLs/log-safe UX. Never returns the full address:
+ * the LOCAL part — the personal identifier — is always masked. The DOMAIN is shown
+ * in full for recognition value ("that's my work address"): a corporate domain is
+ * org-level, not personal data on its own, and the masked local part keeps this from
+ * being a clean, greppable address in a URL/log. Kept within the current GDPR posture
+ * (see the mask-level decision in auth/magic + the signed-in cockpit, which shows the
+ * FULL address from the validated session — never from a URL). Masks with `.` (not `*`)
+ * so the hint round-trips back through normalizeEmailHint's SAFE_HINT_RE.
+ */
 export function redactEmailForHint(email: string): string | null {
   const raw = String(email || "").trim().toLowerCase();
   const at = raw.indexOf("@");
@@ -15,10 +24,9 @@ export function redactEmailForHint(email: string): string | null {
   const domain = raw.slice(at + 1);
   const parts = domain.split(".").filter(Boolean);
   if (parts.length < 2) return null;
-  const suffix = parts.pop();
-  const registrable = parts.join(".");
-  if (!suffix || !registrable) return null;
-  return `${maskPart(local)}@${maskPart(registrable)}.${suffix}`;
+  const suffix = parts[parts.length - 1];
+  if (!suffix || !local) return null;
+  return `${maskPart(local)}@${domain}`;
 }
 
 /**

package/apps/storefront/src/lib/publish/apex-readiness.ts

@@ -0,0 +1,337 @@
+/**
+ * Machine-verifiable apex-cutover READINESS gate (unit u9) — the green
+ * preconditions that MUST all pass before an owner apex (DNS) cutover is
+ * permitted. This is the DELTA on top of the go-live session's apex machinery:
+ * go-live owns the admin Domain Connect/Rollback button, the DNS cutover/rollback
+ * CI (`www-domain.yml` → `cutover-dns.mjs`, prior-records persisted to
+ * `s3://.../meta/`), and the HMAC completion callback; u9 CONSUMES those and
+ * GATES them. Nothing here mutates DNS — it decides whether a cutover is ALLOWED.
+ *
+ * The gate is a PURE function over a signals bundle so the exact policy is
+ * unit-testable independent of the runtime (mirrors `shipReadiness` in
+ * `change/ship`'s CLI and the `acceptGate`/`apexCutoverGate` pure decisions). The
+ * server endpoint (`GET /api/domain/readiness`) assembles the signals from the
+ * live sources via {@link assembleApexReadinessSignals} — the owner capability
+ * (u10 `resolveShipCapabilities`), the per-tenant `DomainState` (in-flight run +
+ * the CAPTURED revert target), and the consumed dual-run parity / target-health /
+ * live-digest evidence record — and the admin Domain display + the `tot go-live`
+ * CLI both read the SAME endpoint, so the enforcement gate and the surfaces never
+ * diverge.
+ *
+ * EVIDENCE CONTRACT (the seam the go-live dual-run/health CI feeds): the parity,
+ * target-health and live-digest signals are CONSUMED from a per-tenant evidence
+ * record persisted at {@link readinessEvidenceKey} (KV). u9 does not RE-RUN
+ * dual-run — it reads the record `scripts/publish/dual-run.mjs` + the health
+ * probe produce. An absent/garbage record normalises fail-closed (no parity, no
+ * digest, unhealthy), so readiness BLOCKS until the go-live CI writes real
+ * evidence — never a false "ready" from a missing feed.
+ *
+ * FAIL-CLOSED throughout (decision `static-publish-fails-closed-reviewed-sha`):
+ * a missing, stale, or failed signal BLOCKS the cutover with an honest,
+ * itemized reason — never a false "ready". Absence denies. The gate is
+ * ADVISORY-vs-authoritative honest: it reports readiness, but the actual cutover
+ * is still owner-gated at `apexCutoverGate`/`guardApexCutover` (u10) and executed
+ * only by the go-live CI — a green readiness verdict never bypasses those.
+ */
+
+/**
+ * The consumed dual-run parity evidence (produced by `scripts/publish/dual-run.mjs`
+ * — the T7 CloudFront-vs-baseline structural diff the pending-dns-cutover gate
+ * wants). u9 CONSUMES this shape; it does not re-run dual-run. Green = the hard
+ * gate dual-run itself enforces: zero CloudFront route failures. `statusMismatches`
+ * are surfaced for review (content legitimately differs during a migration) but do
+ * NOT block, exactly as `dual-run.mjs` treats them. `digest` ties the evidence to
+ * the published bundle it validated, so freshness can be checked against the live
+ * digest; `capturedAt` dates it.
+ */
+export interface DualRunEvidence {
+  /** Number of routes that FAILED on CloudFront (the hard gate — must be 0). */
+  cfFailures: number;
+  /** Status mismatches vs the baseline — surfaced for review, non-blocking. */
+  statusMismatches: number;
+  /** Total routes probed (context for the itemization; 0 ⇒ no real run). */
+  routes: number;
+  /** The published-bundle digest this evidence was produced against, or null. */
+  digest: string | null;
+  /** When the dual-run evidence was produced (ISO), or null. */
+  capturedAt: string | null;
+}
+
+/** The captured revert target — prior DNS records persisted by a connect/rehearsal run. */
+export interface RevertTarget {
+  /** S3 key of the persisted prior DNS records (`meta/dns-prior-records.*.json`), or null. */
+  key: string | null;
+  /** When they were captured (ISO), or null if never. */
+  capturedAt: string | null;
+}
+
+/**
+ * The concrete signals the readiness gate decides over. Assembled server-side
+ * from the live sources; every field is fail-closed by construction (a null /
+ * false / absent value denies its check).
+ */
+export interface ApexReadinessSignals {
+  /**
+   * The acting principal holds the OWNER-ONLY apex-cutover capability
+   * (`resolveShipCapabilities(principal).apexCutover`, u10). A `ship-on-behalf`
+   * developer or an unauthenticated caller is false → denied.
+   */
+  ownerCapable: boolean;
+  /**
+   * A domain connect/rollback run is currently in flight (`runInFlight(state)`).
+   * A cutover cannot start while one is pending its CI callback — the exact race
+   * `DomainState` exists to prevent.
+   */
+  runInFlight: boolean;
+  /**
+   * The consumed dual-run parity evidence, or null when none has been produced
+   * (fail-closed: no evidence ⇒ not green).
+   */
+  dualRun: DualRunEvidence | null;
+  /**
+   * The apex target's health probe passed (the CloudFront/static origin is
+   * serving). Distinct from parity; a false/failed probe blocks. Fail-closed
+   * default false when it could not be established.
+   */
+  targetHealthy: boolean;
+  /**
+   * The digest currently published live (the reviewed tree the cutover would
+   * point traffic at). Evidence must be tied to THIS digest to count as fresh
+   * (`static-publish-fails-closed-reviewed-sha`). Null ⇒ freshness fails closed.
+   */
+  liveDigest: string | null;
+  /** The captured revert target — a rollback must have somewhere to restore FROM. */
+  revert: RevertTarget;
+}
+
+/** A stable id per readiness check, so surfaces can label/order them consistently. */
+export type ApexReadinessCheckId =
+  | "owner-capability"
+  | "no-run-in-flight"
+  | "dual-run-parity"
+  | "target-health"
+  | "evidence-fresh"
+  | "revert-captured";
+
+/** One itemized readiness check — ok/blocked plus an honest human-legible detail. */
+export interface ApexReadinessCheck {
+  id: ApexReadinessCheckId;
+  /** Short label for the surface (admin chip / CLI line). */
+  label: string;
+  /** True when this precondition is satisfied. */
+  ok: boolean;
+  /** Why it passed or, more importantly, why it's blocking — always actionable. */
+  detail: string;
+}
+
+/** The full readiness verdict: ready iff EVERY check passed; itemized either way. */
+export interface ApexReadiness {
+  /** True only when all checks pass — fail-closed on any missing/failed signal. */
+  ready: boolean;
+  /** Every check, in a stable order, whether it passed or blocked. */
+  checks: ApexReadinessCheck[];
+  /** The details of the blocking checks only (empty ⇒ ready). Convenience for surfaces. */
+  blockedReasons: string[];
+}
+
+/**
+ * Compute apex-cutover readiness from the signals — PURE, total, fail-closed. The
+ * order is deliberate (owner → in-flight → parity → health → freshness → revert)
+ * so the most fundamental blocker surfaces first, mirroring `shipReadiness`.
+ *
+ * The cutover is READY only when ALL checks pass. Any missing signal (null
+ * evidence, null digest, absent revert key) is a BLOCK with an honest reason,
+ * never a silent pass.
+ */
+export function computeApexReadiness(signals: ApexReadinessSignals): ApexReadiness {
+  const checks: ApexReadinessCheck[] = [];
+
+  // 1. Owner-only capability (u10). A non-owner is denied outright — this is the
+  //    same floor `apexCutoverGate` enforces, surfaced as a readiness item.
+  checks.push({
+    id: "owner-capability",
+    label: "Owner capability",
+    ok: signals.ownerCapable,
+    detail: signals.ownerCapable
+      ? "you hold the owner-only apex-cutover capability"
+      : "apex cutover is owner-only — a ship-on-behalf developer cannot cut over the apex",
+  });
+
+  // 2. No run in flight — two concurrent DNS mutations is the race DomainState guards.
+  checks.push({
+    id: "no-run-in-flight",
+    label: "No run in flight",
+    ok: !signals.runInFlight,
+    detail: signals.runInFlight
+      ? "a domain connect/rollback run is already in flight — wait for it to complete"
+      : "no domain run is in flight",
+  });
+
+  // 3. Dual-run parity — zero CloudFront route failures (the hard gate dual-run.mjs
+  //    itself enforces). Missing evidence fails closed. Status mismatches are
+  //    surfaced but do NOT block (content legitimately differs mid-migration).
+  const dr = signals.dualRun;
+  const parityOk = !!dr && dr.routes > 0 && dr.cfFailures === 0;
+  checks.push({
+    id: "dual-run-parity",
+    label: "Dual-run parity",
+    ok: parityOk,
+    detail: !dr
+      ? "no dual-run parity evidence — run the CloudFront-vs-baseline dual-run first"
+      : dr.routes === 0
+        ? "dual-run evidence covered 0 routes — not a real parity run"
+        : dr.cfFailures > 0
+          ? `dual-run parity failing: ${dr.cfFailures} CloudFront route failure(s) of ${dr.routes}`
+          : `dual-run green: 0 CloudFront failures across ${dr.routes} route(s)` +
+            (dr.statusMismatches > 0
+              ? ` (${dr.statusMismatches} status mismatch(es) surfaced for review — non-blocking)`
+              : ""),
+  });
+
+  // 4. Target health — the apex target (CloudFront/static origin) is serving.
+  checks.push({
+    id: "target-health",
+    label: "Target health",
+    ok: signals.targetHealthy,
+    detail: signals.targetHealthy
+      ? "apex target health check passed"
+      : "apex target health check failing or unestablished",
+  });
+
+  // 5. Evidence freshness — the parity evidence is tied to the CURRENT live digest
+  //    (`static-publish-fails-closed-reviewed-sha`). Stale evidence (a different
+  //    digest) or a missing digest on either side fails closed.
+  const evidenceDigest = dr?.digest ?? null;
+  const freshOk =
+    !!evidenceDigest && !!signals.liveDigest && evidenceDigest === signals.liveDigest;
+  checks.push({
+    id: "evidence-fresh",
+    label: "Evidence fresh",
+    ok: freshOk,
+    detail: freshOk
+      ? `evidence is tied to the live digest (${short(signals.liveDigest)})`
+      : !signals.liveDigest
+        ? "no live digest to tie the evidence to"
+        : !evidenceDigest
+          ? "parity evidence carries no digest — cannot confirm it matches the live tree"
+          : `parity evidence is stale: it was produced against ${short(evidenceDigest)}, ` +
+            `not the live digest ${short(signals.liveDigest)}`,
+  });
+
+  // 6. Captured revert target — a rollback must have persisted prior DNS records to
+  //    restore FROM. No captured target ⇒ the cutover has no tested one-line revert.
+  const revertOk = !!signals.revert.key;
+  checks.push({
+    id: "revert-captured",
+    label: "Revert captured",
+    ok: revertOk,
+    detail: revertOk
+      ? `captured revert target present (prior DNS records${
+          signals.revert.capturedAt ? ` @ ${signals.revert.capturedAt}` : ""
+        })`
+      : "no captured revert target — prior DNS records are not persisted, so there is no tested rollback",
+  });
+
+  const blockedReasons = checks.filter((c) => !c.ok).map((c) => c.detail);
+  return { ready: blockedReasons.length === 0, checks, blockedReasons };
+}
+
+/** Normalise a raw `dual-run.mjs --json` summary into {@link DualRunEvidence}. Pure.
+ *  Tolerant of the shape the script prints (`{ summary: { routes, cfFailures,
+ *  statusMismatches } }`) as well as a flattened record; returns null for anything
+ *  unrecognisable so the gate fails closed on garbage. `digest`/`capturedAt` are
+ *  read from the wrapping evidence record (the script itself doesn't stamp them). */
+export function normalizeDualRunEvidence(raw: unknown): DualRunEvidence | null {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw as Record<string, unknown>;
+  const summary =
+    o.summary && typeof o.summary === "object" ? (o.summary as Record<string, unknown>) : o;
+  const cfFailures = num(summary.cfFailures);
+  const routes = num(summary.routes);
+  const statusMismatches = num(summary.statusMismatches);
+  if (cfFailures === null || routes === null) return null;
+  return {
+    cfFailures,
+    routes,
+    statusMismatches: statusMismatches ?? 0,
+    digest: typeof o.digest === "string" ? o.digest : null,
+    capturedAt: typeof o.capturedAt === "string" ? o.capturedAt : null,
+  };
+}
+
+function num(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+// ─── Evidence record + signal assembly (the endpoint's non-pure boundary) ─────────
+
+/**
+ * The consumed readiness-evidence record the go-live dual-run/health CI persists
+ * per tenant. u9 READS it; it does not produce it. Bundles the three signals u9
+ * cannot derive from `DomainState` alone: the dual-run parity result, the apex
+ * target's health, and the digest currently live (so freshness can be checked).
+ */
+export interface ReadinessEvidence {
+  dualRun: DualRunEvidence | null;
+  targetHealthy: boolean;
+  liveDigest: string | null;
+}
+
+/** KV key for a tenant's consumed readiness-evidence record. */
+export function readinessEvidenceKey(tenantId: string): string {
+  return `www-domain:readiness-evidence:${tenantId}`;
+}
+
+/**
+ * Normalise a raw persisted evidence record into {@link ReadinessEvidence},
+ * FAIL-CLOSED: anything unrecognisable yields no parity, an unhealthy target, and
+ * no live digest — so the gate blocks rather than trusting a malformed feed. Pure.
+ */
+export function normalizeReadinessEvidence(raw: unknown): ReadinessEvidence {
+  if (!raw || typeof raw !== "object") {
+    return { dualRun: null, targetHealthy: false, liveDigest: null };
+  }
+  const o = raw as Record<string, unknown>;
+  return {
+    dualRun: normalizeDualRunEvidence(o.dualRun ?? o),
+    targetHealthy: o.targetHealthy === true,
+    liveDigest: typeof o.liveDigest === "string" ? o.liveDigest : null,
+  };
+}
+
+/** The state fields the readiness signals draw from `DomainState` (structural, no import). */
+export interface ReadinessDomainState {
+  /** True when the last run is still awaiting its CI callback (`runInFlight`). */
+  runInFlight: boolean;
+  /** The captured prior-DNS-records pointer (`priorRecordsKey`), or null. */
+  priorRecordsKey: string | null;
+  /** When those prior records were captured (`priorCapturedAt`), or null. */
+  priorCapturedAt: string | null;
+}
+
+/**
+ * Assemble the {@link ApexReadinessSignals} the gate decides over from the three
+ * live sources — the owner capability (u10), the per-tenant domain state (revert +
+ * in-flight), and the consumed evidence record — PURE so the endpoint's mapping is
+ * unit-testable without KV/session I/O. The endpoint does the reads; this does the
+ * mapping.
+ */
+export function assembleApexReadinessSignals(input: {
+  ownerCapable: boolean;
+  state: ReadinessDomainState;
+  evidence: ReadinessEvidence;
+}): ApexReadinessSignals {
+  return {
+    ownerCapable: input.ownerCapable,
+    runInFlight: input.state.runInFlight,
+    dualRun: input.evidence.dualRun,
+    targetHealthy: input.evidence.targetHealthy,
+    liveDigest: input.evidence.liveDigest,
+    revert: { key: input.state.priorRecordsKey, capturedAt: input.state.priorCapturedAt },
+  };
+}
+
+/** Short 12-char digest for legible details (full digest stays in the raw signal). */
+function short(digest: string | null): string {
+  return digest ? digest.slice(0, 12) : "(none)";
+}