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

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)";
+}

package/apps/storefront/src/lib/publish/dispatchHealth.ts

@@ -0,0 +1,269 @@
+/**
+ * Dispatch-health assessment (dg5) — is the static-publish `repository_dispatch`
+ * path actually WIRED and HEALTHY, or would a "go-live" silently hand the publish
+ * to a dead-end? The Worker fires a `repository_dispatch` and gets a 204 back
+ * having verified NOTHING about the target (see `createRepositoryDispatchSink` —
+ * it is fire-and-forget by construction). This module is the HONEST pre-flight
+ * surface that answers, per binding decision `static-publish-fails-closed-
+ * reviewed-sha`, whether that path can carry a publish at all — reporting each
+ * concrete signal pass/fail/unknown with a reason, never a silent assumption.
+ *
+ * FOUR SIGNALS:
+ *   - `dispatch-cred-present`               — is WWW_PUBLISH_DISPATCH_TOKEN set?
+ *   - `target-config-present`               — does this tenant declare a static
+ *                                             target AND does the dispatch repo resolve?
+ *   - `workflow-registered-on-default-branch` — is the publish workflow visible to
+ *                                             the Actions API? `repository_dispatch`
+ *                                             ONLY triggers workflows on the repo's
+ *                                             DEFAULT branch (main), so a workflow
+ *                                             that lives only on the deploy branch is
+ *                                             NOT yet reachable. A 404 here is the
+ *                                             honest "not yet promoted to main" state
+ *                                             (the HELD main-promotion gate,
+ *                                             `pending-main-promotion-and-production-
+ *                                             publish-activation`) — surfaced, not papered.
+ *   - `target-reachable`                    — does the published `live/manifest.json`
+ *                                             answer? DIAGNOSTIC ONLY: a pre-first-
+ *                                             publish target legitimately has none, so
+ *                                             this never blocks a ship (the post-merge
+ *                                             VERIFY in dg4's orchestrator is the real
+ *                                             no-false-live gate).
+ *
+ * FAIL-CLOSED SEMANTICS:
+ *   - `healthy` is true ONLY when every SHIP-CRITICAL signal (cred, target-config,
+ *     workflow-registration) is `pass`. An `unknown` is NOT healthy.
+ *   - `blockShip` is true only for a DEFINITIVELY-bad critical precondition (cred
+ *     missing, target-config missing, or a workflow 404). An `unknown` (e.g. the
+ *     Actions API is unreachable, or the token lacks read scope) does NOT set
+ *     `blockShip` — so GitHub reachability is never a hard dependency of every
+ *     accept; the orchestrator's post-merge verify still fails closed regardless.
+ */
+
+/** A single signal's honest state. `unknown` = we genuinely could not determine it. */
+export type DispatchHealthStatus = "pass" | "fail" | "unknown";
+
+export type DispatchHealthSignalId =
+  | "dispatch-cred-present"
+  | "target-config-present"
+  | "workflow-registered-on-default-branch"
+  | "target-reachable";
+
+export interface DispatchHealthSignal {
+  id: DispatchHealthSignalId;
+  status: DispatchHealthStatus;
+  /** Human/audit-legible reason for the status. */
+  detail: string;
+  /** Whether this signal gates a ship (false = diagnostic only, e.g. target-reachable). */
+  critical: boolean;
+}
+
+export interface DispatchHealthReport {
+  /** True ONLY when every ship-critical signal is `pass` (fail-closed: unknown ⇒ not healthy). */
+  healthy: boolean;
+  /**
+   * True when a ship should be REFUSED before merge because a critical precondition
+   * is DEFINITIVELY bad (never for an `unknown`). Consumed by the ship path so a
+   * static go-live never merges into a dead-end that could report a false live.
+   */
+  blockShip: boolean;
+  /** The one-line honest reason `blockShip` is set, else null. */
+  blockReason: string | null;
+  signals: DispatchHealthSignal[];
+}
+
+export interface AssessDispatchHealthInput {
+  /** WWW_PUBLISH_DISPATCH_TOKEN (presence only; the value never leaves env). */
+  dispatchToken: string | null;
+  /** `owner/repo` hosting the publish workflow (WWW_PUBLISH_DISPATCH_REPO). */
+  repoSlug: string | null;
+  /** The `repository_dispatch` event type (informational — surfaced for audit). */
+  eventType: string;
+  /** GitHub API base (default https://api.github.com); set for Enterprise. */
+  apiBase?: string;
+  /** The workflow file name the Actions API is probed for (e.g. "www-publish.yml"). */
+  workflowFile: string;
+  /** The tenant's static-publish target label when enabled, else null. */
+  staticPublishTarget: string | null;
+  /** Published-manifest URL for the `target-reachable` probe, or null when unresolved. */
+  manifestUrl: string | null;
+  /** Injectable fetch (Worker/Node global by default) — so this is unit-tested with no network. */
+  fetchImpl?: typeof fetch;
+}
+
+/** Parse `owner/repo`, returning null when it isn't a clean two-part slug. */
+export function parseRepoSlug(slug: string | null): { owner: string; repo: string } | null {
+  if (!slug) return null;
+  const [owner, repo] = slug.split("/", 2);
+  if (!owner || !repo) return null;
+  return { owner, repo };
+}
+
+/**
+ * Probe the Actions API for the publish workflow. A 200 means GitHub has the
+ * workflow REGISTERED — which only happens once it is on the repo's DEFAULT
+ * branch, so `repository_dispatch` can trigger it. A 404 is the honest "not on the
+ * default branch yet" state. A 401/403/other/network error is `unknown` (we can't
+ * tell — often the token has write-only scope), NEVER a false pass or a hard block.
+ */
+async function probeWorkflowRegistered(
+  input: AssessDispatchHealthInput,
+  repo: { owner: string; repo: string },
+): Promise<DispatchHealthSignal> {
+  const base = {
+    id: "workflow-registered-on-default-branch" as const,
+    critical: true,
+  };
+  if (!input.dispatchToken) {
+    return { ...base, status: "unknown", detail: "cannot probe: dispatch credential absent" };
+  }
+  const apiBase = (input.apiBase ?? "https://api.github.com").replace(/\/+$/, "");
+  const url = `${apiBase}/repos/${repo.owner}/${repo.repo}/actions/workflows/${encodeURIComponent(input.workflowFile)}`;
+  const doFetch = input.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(url, {
+      headers: {
+        authorization: `Bearer ${input.dispatchToken}`,
+        accept: "application/vnd.github+json",
+        "user-agent": "tot-storefront-dispatch-health",
+      },
+    });
+  } catch (e) {
+    return { ...base, status: "unknown", detail: `Actions API unreachable: ${(e as Error).message}` };
+  }
+  if (res.status === 200) {
+    return {
+      ...base,
+      status: "pass",
+      detail: `${input.workflowFile} is registered on the default branch (repository_dispatch can trigger it)`,
+    };
+  }
+  if (res.status === 404) {
+    return {
+      ...base,
+      status: "fail",
+      detail:
+        `${input.workflowFile} is NOT registered on ${repo.owner}/${repo.repo}'s default branch ` +
+        `(main) — repository_dispatch cannot trigger it until it is promoted to main ` +
+        `(pending main-promotion gate).`,
+    };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return {
+      ...base,
+      status: "unknown",
+      detail: `Actions API returned HTTP ${res.status} — dispatch token lacks read scope; registration cannot be confirmed`,
+    };
+  }
+  return { ...base, status: "unknown", detail: `Actions API returned HTTP ${res.status}` };
+}
+
+/**
+ * Probe the published-manifest URL. DIAGNOSTIC ONLY (`critical: false`): a
+ * pre-first-publish target has no manifest yet, which is a legitimate bootstrap
+ * state, so this never gates a ship.
+ */
+async function probeTargetReachable(input: AssessDispatchHealthInput): Promise<DispatchHealthSignal> {
+  const base = { id: "target-reachable" as const, critical: false };
+  if (!input.manifestUrl) {
+    return { ...base, status: "unknown", detail: "no published-manifest URL resolved for this target" };
+  }
+  const doFetch = input.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(input.manifestUrl, { headers: { accept: "application/json" } });
+  } catch (e) {
+    return { ...base, status: "unknown", detail: `manifest fetch failed: ${(e as Error).message}` };
+  }
+  if (!res.ok) {
+    return {
+      ...base,
+      status: res.status === 404 ? "fail" : "unknown",
+      detail: `manifest HTTP ${res.status}${res.status === 404 ? " (target not yet published — bootstrap)" : ""}`,
+    };
+  }
+  let hasDigest = false;
+  try {
+    const manifest = (await res.json()) as { treeDigest?: unknown };
+    hasDigest = typeof manifest.treeDigest === "string" && manifest.treeDigest.length > 0;
+  } catch {
+    return { ...base, status: "fail", detail: "manifest was not valid JSON" };
+  }
+  return {
+    ...base,
+    status: "pass",
+    detail: hasDigest ? "target serves a published manifest with a treeDigest" : "target reachable (manifest carries no treeDigest yet)",
+  };
+}
+
+/**
+ * Assess the dispatch path's health. Runs the two network probes concurrently.
+ * Pure w.r.t. its inputs — the caller resolves env/config and injects `fetchImpl`.
+ */
+export async function assessDispatchHealth(
+  input: AssessDispatchHealthInput,
+): Promise<DispatchHealthReport> {
+  const repo = parseRepoSlug(input.repoSlug);
+
+  const credSignal: DispatchHealthSignal = input.dispatchToken
+    ? {
+        id: "dispatch-cred-present",
+        status: "pass",
+        detail: "WWW_PUBLISH_DISPATCH_TOKEN is configured",
+        critical: true,
+      }
+    : {
+        id: "dispatch-cred-present",
+        status: "fail",
+        detail: "WWW_PUBLISH_DISPATCH_TOKEN is not set — the Worker cannot fire repository_dispatch",
+        critical: true,
+      };
+
+  const targetConfigSignal: DispatchHealthSignal =
+    input.staticPublishTarget && repo
+      ? {
+          id: "target-config-present",
+          status: "pass",
+          detail: `static target "${input.staticPublishTarget}" → dispatch repo ${repo.owner}/${repo.repo} (event ${input.eventType})`,
+          critical: true,
+        }
+      : {
+          id: "target-config-present",
+          status: "fail",
+          detail: !input.staticPublishTarget
+            ? "tenant declares no enabled static-publish target"
+            : "dispatch repo (WWW_PUBLISH_DISPATCH_REPO) does not resolve to owner/repo",
+          critical: true,
+        };
+
+  // The workflow probe needs a resolved repo; without one it can't be evaluated.
+  const workflowSignal: DispatchHealthSignal = repo
+    ? await probeWorkflowRegistered(input, repo)
+    : {
+        id: "workflow-registered-on-default-branch",
+        status: "unknown",
+        detail: "cannot probe: dispatch repo does not resolve",
+        critical: true,
+      };
+
+  const reachableSignal = await probeTargetReachable(input);
+
+  const signals: DispatchHealthSignal[] = [
+    credSignal,
+    targetConfigSignal,
+    workflowSignal,
+    reachableSignal,
+  ];
+
+  const critical = signals.filter((s) => s.critical);
+  const healthy = critical.every((s) => s.status === "pass");
+  // Block a ship only for a DEFINITIVELY-bad critical precondition — never an unknown.
+  const blocker = critical.find((s) => s.status === "fail") ?? null;
+
+  return {
+    healthy,
+    blockShip: blocker !== null,
+    blockReason: blocker ? `${blocker.id}: ${blocker.detail}` : null,
+    signals,
+  };
+}