@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -1,10 +1,10 @@
 /**
- * Machine-verifiable apex-cutover READINESS gate (unit u9) — the green
+ * Machine-verifiable apex-cutover READINESS gate — 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:
+ * permitted. It consumes the go-live 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
+ * `s3://.../meta/`), and the HMAC completion callback; this gate 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
@@ -12,7 +12,7 @@
  * `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 +
+ * (`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
@@ -20,24 +20,24 @@
  *
  * 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
+ * record persisted at {@link readinessEvidenceKey} (KV). The gate 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`):
+ * FAIL-CLOSED throughout:
  * 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
+ * is still owner-gated at `apexCutoverGate`/`guardApexCutover` 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
+ * — the CloudFront-vs-baseline structural diff the pending-dns-cutover gate
+ * wants). This shape is consumed here; dual-run is not re-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
@@ -73,7 +73,7 @@ export interface RevertTarget {
 export interface ApexReadinessSignals {
   /**
    * The acting principal holds the OWNER-ONLY apex-cutover capability
-   * (`resolveShipCapabilities(principal).apexCutover`, u10). A `ship-on-behalf`
+   * (`resolveShipCapabilities(principal).apexCutover`). A `ship-on-behalf`
    * developer or an unauthenticated caller is false → denied.
    */
   ownerCapable: boolean;
@@ -96,8 +96,8 @@ export interface ApexReadinessSignals {
   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.
+   * point traffic at). Evidence must be tied to THIS digest to count as fresh.
+   * Null ⇒ freshness fails closed.
    */
   liveDigest: string | null;
   /** The captured revert target — a rollback must have somewhere to restore FROM. */
@@ -122,6 +122,14 @@ export interface ApexReadinessCheck {
   ok: boolean;
   /** Why it passed or, more importantly, why it's blocking — always actionable. */
   detail: string;
+  /**
+   * The concrete action that clears this precondition when it's blocking — the
+   * "how to get ready" guide, carried on the gate itself so the admin panel and
+   * `tot go-live` surface identical remediation (never a divergent side doc). Only
+   * meaningful/shown when `ok` is false; the full operator walkthrough (secret
+   * provisioning, IAM) lives in `docs/runbooks/apex-cutover-readiness.md`.
+   */
+  remedy: string;
 }
 
 /** The full readiness verdict: ready iff EVERY check passed; itemized either way. */
@@ -146,7 +154,7 @@ export interface ApexReadiness {
 export function computeApexReadiness(signals: ApexReadinessSignals): ApexReadiness {
   const checks: ApexReadinessCheck[] = [];
 
-  // 1. Owner-only capability (u10). A non-owner is denied outright — this is the
+  // 1. Owner-only capability. A non-owner is denied outright — this is the
   //    same floor `apexCutoverGate` enforces, surfaced as a readiness item.
   checks.push({
     id: "owner-capability",
@@ -155,6 +163,7 @@ export function computeApexReadiness(signals: ApexReadinessSignals): ApexReadine
     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",
+    remedy: "Sign in as the store owner — apex cutover cannot be delegated to a ship-on-behalf developer.",
   });
 
   // 2. No run in flight — two concurrent DNS mutations is the race DomainState guards.
@@ -165,6 +174,7 @@ export function computeApexReadiness(signals: ApexReadinessSignals): ApexReadine
     detail: signals.runInFlight
       ? "a domain connect/rollback run is already in flight — wait for it to complete"
       : "no domain run is in flight",
+    remedy: "Wait for the in-flight connect/rollback run to finish (watch the run log), then re-check.",
   });
 
   // 3. Dual-run parity — zero CloudFront route failures (the hard gate dual-run.mjs
@@ -186,6 +196,10 @@ export function computeApexReadiness(signals: ApexReadinessSignals): ApexReadine
             (dr.statusMismatches > 0
               ? ` (${dr.statusMismatches} status mismatch(es) surfaced for review — non-blocking)`
               : ""),
+    remedy:
+      "Publish tokenoftrust.com (a www-publish run) so the dual-run records fresh evidence. " +
+      "First time only: provision the WWW_READINESS_EVIDENCE_URL variable + WWW_READINESS_EVIDENCE_SECRET " +
+      "secret (see the apex-cutover-readiness runbook).",
   });
 
   // 4. Target health — the apex target (CloudFront/static origin) is serving.
@@ -196,11 +210,14 @@ export function computeApexReadiness(signals: ApexReadinessSignals): ApexReadine
     detail: signals.targetHealthy
       ? "apex target health check passed"
       : "apex target health check failing or unestablished",
+    remedy:
+      "Cleared by the same www-publish evidence run as Dual-run parity — every route serving " +
+      "correctly on CloudFront is what proves the target healthy.",
   });
 
-  // 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.
+  // 5. Evidence freshness — the parity evidence is tied to the CURRENT live digest.
+  //    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;
@@ -216,6 +233,8 @@ export function computeApexReadiness(signals: ApexReadinessSignals): ApexReadine
           ? "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)}`,
+    remedy:
+      "Re-publish tokenoftrust.com so the dual-run evidence is re-tied to the current live digest.",
   });
 
   // 6. Captured revert target — a rollback must have persisted prior DNS records to
@@ -230,6 +249,9 @@ export function computeApexReadiness(signals: ApexReadinessSignals): ApexReadine
           signals.revert.capturedAt ? ` @ ${signals.revert.capturedAt}` : ""
         })`
       : "no captured revert target — prior DNS records are not persisted, so there is no tested rollback",
+    remedy:
+      "Run a rehearsal (dry-run connect) from the Domain section — it captures the current DNS " +
+      "records as the rollback target without changing live DNS.",
   });
 
   const blockedReasons = checks.filter((c) => !c.ok).map((c) => c.detail);
@@ -267,9 +289,10 @@ function num(v: unknown): number | null {
 
 /**
  * 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
+ * per tenant. Bundles the three signals the gate
  * 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).
+ * The gate READS it; it does not produce it.
  */
 export interface ReadinessEvidence {
   dualRun: DualRunEvidence | null;
@@ -311,7 +334,7 @@ export interface ReadinessDomainState {
 
 /**
  * Assemble the {@link ApexReadinessSignals} the gate decides over from the three
- * live sources — the owner capability (u10), the per-tenant domain state (revert +
+ * live sources — the owner capability, 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.

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

@@ -0,0 +1,269 @@
+/**
+ * Pure logic for the admin Publish tab's real-time build/check streaming (SSE).
+ *
+ * The build endpoint (`POST /api/preview/build` with `Accept: text/event-stream`)
+ * streams coarse lifecycle PHASES as it materializes a candidate — resolve head →
+ * read+validate tenant files → publish the immutable version → run evidence checks —
+ * then a terminal `result` event carrying the full outcome. This module is the tested
+ * source of truth for:
+ *   - parsing the raw SSE byte-frames into events (partial-chunk safe);
+ *   - mapping a phase to its human label + rail position;
+ *   - reducing the event sequence into a render-ready progress state;
+ *   - assembling the "Copy for your AI agent" prompt from a build FAILURE.
+ * The DOM wiring that drives the dialog from these is verified on a live preview, per
+ * this codebase's client-island convention (see reviewReleaseWorkspace/controller.ts).
+ */
+
+/** One decoded SSE event: its `event:` name and the concatenated `data:` payload. */
+export interface SseEvent {
+  event: string;
+  data: string;
+}
+
+/**
+ * Parse an accumulated SSE text buffer into complete events, returning any trailing
+ * INCOMPLETE frame as `rest` for the next chunk to prepend. Partial-chunk safe: a
+ * frame is complete only once its blank-line terminator (`\n\n`) has arrived.
+ * Lines with no field (`:` comments, stray blanks) are ignored; multiple `data:`
+ * lines in one frame join with `\n` (the SSE spec). A frame with no fields yields
+ * nothing.
+ */
+export function parseSseChunk(buffer: string): { events: SseEvent[]; rest: string } {
+  const normalized = buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const events: SseEvent[] = [];
+  const lastSep = normalized.lastIndexOf("\n\n");
+  if (lastSep === -1) return { events, rest: normalized };
+
+  const complete = normalized.slice(0, lastSep);
+  const rest = normalized.slice(lastSep + 2);
+
+  for (const frame of complete.split("\n\n")) {
+    let eventName = "message";
+    const dataLines: string[] = [];
+    let sawField = false;
+    for (const rawLine of frame.split("\n")) {
+      if (!rawLine || rawLine.startsWith(":")) continue;
+      const colon = rawLine.indexOf(":");
+      const field = colon === -1 ? rawLine : rawLine.slice(0, colon);
+      // Per spec a single leading space after the colon is stripped.
+      let value = colon === -1 ? "" : rawLine.slice(colon + 1);
+      if (value.startsWith(" ")) value = value.slice(1);
+      if (field === "event") {
+        eventName = value;
+        sawField = true;
+      } else if (field === "data") {
+        dataLines.push(value);
+        sawField = true;
+      }
+    }
+    if (sawField) events.push({ event: eventName, data: dataLines.join("\n") });
+  }
+  return { events, rest };
+}
+
+/** The ordered build lifecycle stages the flight rail renders (mirrors the dialog). */
+export const BUILD_STAGES = ["resolve", "read", "publish", "check"] as const;
+export type BuildStage = (typeof BUILD_STAGES)[number];
+
+/** The `phase` values the server emits, in lifecycle order. */
+export type BuildPhase = "resolving" | "reading" | "publishing" | "checking";
+
+const PHASE_TO_STAGE: Record<BuildPhase, BuildStage> = {
+  resolving: "resolve",
+  reading: "read",
+  publishing: "publish",
+  checking: "check",
+};
+
+const PHASE_LABEL: Record<BuildPhase, string> = {
+  resolving: "Locating the pull request's latest commit…",
+  reading: "Reading and validating your store's files…",
+  publishing: "Publishing this version's preview…",
+  checking: "Running the checks on this version…",
+};
+
+const STAGE_LABEL: Record<BuildStage, string> = {
+  resolve: "Locate commit",
+  read: "Read & validate",
+  publish: "Publish version",
+  check: "Run checks",
+};
+
+export function buildPhaseLabel(phase: BuildPhase): string {
+  return PHASE_LABEL[phase];
+}
+
+export function buildStageLabel(stage: BuildStage): string {
+  return STAGE_LABEL[stage];
+}
+
+export function isBuildPhase(value: unknown): value is BuildPhase {
+  return value === "resolving" || value === "reading" || value === "publishing" || value === "checking";
+}
+
+/** The terminal outcome the server reports on its `result` event. */
+export type BuildOutcome = "ok" | "blocked" | "failed";
+
+/** The full terminal payload of a build (mirrors the endpoint's JSON body). */
+export interface BuildResult {
+  ok: boolean;
+  outcome: BuildOutcome;
+  tenantId?: string | null;
+  changeId?: string | null;
+  headSha?: string | null;
+  prNumber?: number | null;
+  previewUrl?: string | null;
+  errors?: string[];
+  error?: string | null;
+  findings?: BuildFinding[];
+}
+
+export interface BuildFinding {
+  id?: string;
+  label?: string;
+  detail?: string;
+  disposition?: string;
+}
+
+/** Render-ready progress the dialog reads. `stageState` is a per-stage rail map. */
+export interface BuildProgress {
+  phase: BuildPhase | null;
+  liveLabel: string;
+  stageState: Record<BuildStage, "pending" | "active" | "done" | "fail">;
+  terminal: boolean;
+  result: BuildResult | null;
+}
+
+export function initialBuildProgress(): BuildProgress {
+  return {
+    phase: null,
+    liveLabel: "Starting…",
+    stageState: { resolve: "pending", read: "pending", publish: "pending", check: "pending" },
+    terminal: false,
+    result: null,
+  };
+}
+
+/**
+ * Advance the flight rail to `stage`: everything before it is `done`, it is `active`,
+ * everything after stays `pending`. A `fail` mark is never un-done. Pure.
+ */
+function railTo(
+  prev: Record<BuildStage, "pending" | "active" | "done" | "fail">,
+  stage: BuildStage,
+): Record<BuildStage, "pending" | "active" | "done" | "fail"> {
+  const idx = BUILD_STAGES.indexOf(stage);
+  const next = { ...prev };
+  BUILD_STAGES.forEach((s, i) => {
+    if (next[s] === "fail") return;
+    next[s] = i < idx ? "done" : i === idx ? "active" : "pending";
+  });
+  return next;
+}
+
+/**
+ * Fold one SSE event into the progress state. A `phase` event advances the rail + live
+ * label; a `result` event is terminal (all reached stages `done` on success, the active
+ * stage `fail` on a blocked/failed outcome). Unknown events are ignored (state
+ * unchanged). Pure — the dialog calls this per event and re-renders from the result.
+ */
+export function reduceBuildProgress(prev: BuildProgress, ev: SseEvent): BuildProgress {
+  if (ev.event === "phase") {
+    const parsed = safeParse(ev.data);
+    const phase = parsed && (parsed as { phase?: unknown }).phase;
+    if (!isBuildPhase(phase)) return prev;
+    const stage = PHASE_TO_STAGE[phase];
+    const label =
+      (parsed && typeof (parsed as { label?: unknown }).label === "string"
+        ? (parsed as { label: string }).label
+        : "") || buildPhaseLabel(phase);
+    return {
+      ...prev,
+      phase,
+      liveLabel: label,
+      stageState: railTo(prev.stageState, stage),
+    };
+  }
+
+  if (ev.event === "result") {
+    const parsed = (safeParse(ev.data) as BuildResult | null) ?? {
+      ok: false,
+      outcome: "failed",
+      errors: ["build ended without a result"],
+    };
+    const result: BuildResult = {
+      ...parsed,
+      outcome: parsed.outcome ?? (parsed.ok ? "ok" : "failed"),
+    };
+    let stageState = prev.stageState;
+    if (result.ok) {
+      stageState = { resolve: "done", read: "done", publish: "done", check: "done" };
+    } else {
+      // Fail the stage that was active (the phase we got furthest into); if none was
+      // active yet, fail the first stage so the rail shows an honest stop point.
+      const active = BUILD_STAGES.find((s) => prev.stageState[s] === "active") ?? BUILD_STAGES[0];
+      stageState = { ...prev.stageState, [active]: "fail" };
+    }
+    return {
+      ...prev,
+      liveLabel: result.ok ? "Done." : "Stopped.",
+      stageState,
+      terminal: true,
+      result,
+    };
+  }
+
+  return prev;
+}
+
+/** The human-readable failure detail (the honest reason), joined from errors/findings. */
+export function buildFailureDetail(result: BuildResult): string {
+  const parts: string[] = [];
+  for (const e of result.errors ?? []) if (e && e.trim()) parts.push(e.trim());
+  if (result.error && result.error.trim()) parts.push(result.error.trim());
+  for (const f of result.findings ?? []) {
+    const line = [f.label || f.id, f.detail].filter(Boolean).join(": ");
+    if (line) parts.push((f.disposition === "blocking-safety" ? "[blocking] " : "") + line);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Assemble the "Copy for your AI agent" prompt from a build FAILURE — the honest,
+ * paste-ready brief an operator hands to a coding agent to diagnose why the preview
+ * build/checks failed. Mirrors the merge-conflict copy pattern (a framed ask + the
+ * system's own words), never a bare error dump.
+ */
+export function assembleBuildFailureCopy(input: {
+  tenant: string;
+  prNumber?: number | null;
+  changeId?: string | null;
+  result: BuildResult;
+}): string {
+  const { tenant, prNumber, changeId, result } = input;
+  const pr = prNumber != null ? `PR #${prNumber}` : changeId ? `change ${changeId}` : "my open candidate PR";
+  const stage = result.outcome === "blocked" ? "was blocked by a check" : "failed to build";
+  const detail = buildFailureDetail(result) || "(no detail was reported)";
+  return [
+    `In my ${tenant} store, the preview build for ${pr} ${stage}. ` +
+      `Diagnose why from the detail below, then tell me the exact file(s) to change and the fix.`,
+    "",
+    "What the build reported:",
+    detail,
+    "",
+    result.headSha ? `Head commit: ${result.headSha}` : "",
+    "Context: this is a Token of Trust storefront tenant repo — customization files are " +
+      "mapped to artifacts and validated against the tenant-editable manifest before the " +
+      "version is published. A blocking finding or a validation error stops the build.",
+  ]
+    .filter((l) => l !== "")
+    .join("\n");
+}
+
+function safeParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * r05 — persist each Publish-tab collapsible section's open/closed state per user,
+ * scoped per store so a power user's layout survives reloads without bleeding across
+ * stores. Pure key/read/write logic, extracted from the DOM wiring in
+ * `adminPublishTab.ts` so it is unit-testable and storage-agnostic.
+ *
+ * The persisted value is the human-legible "open"/"closed" (not a boolean string).
+ * `readPersistedOpen` returns `null` when nothing is stored (or storage is
+ * unreadable) — the caller then leaves the section at its SSR default, so the
+ * default open/closed state is preserved when a user has never toggled a section.
+ */
+
+/** The slice of the Web Storage API this helper needs (localStorage satisfies it). */
+export interface CollapseStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+/** Stable identifiers for the collapsible sections on the Publish tab. */
+export type CollapseSectionId =
+  | "review-queue"
+  | "closed-changes"
+  | "next-release"
+  | "live-site"
+  | "rollback";
+
+const KEY_PREFIX = "tot.publish.collapse";
+const OPEN = "open";
+const CLOSED = "closed";
+
+/**
+ * Per-store, per-section storage key. The store scope (appDomain) keeps one store's
+ * layout from bleeding into another; an empty tenant collapses to a shared "_" scope
+ * rather than producing a dangling key.
+ */
+export function collapseStorageKey(tenant: string, sectionId: CollapseSectionId): string {
+  return `${KEY_PREFIX}.${tenant || "_"}.${sectionId}`;
+}
+
+/**
+ * The stored open/closed state, or `null` when nothing is stored, the value is
+ * unrecognized, or storage throws (private mode / disabled). Never throws.
+ */
+export function readPersistedOpen(
+  storage: CollapseStorage,
+  tenant: string,
+  sectionId: CollapseSectionId,
+): boolean | null {
+  let raw: string | null;
+  try {
+    raw = storage.getItem(collapseStorageKey(tenant, sectionId));
+  } catch {
+    return null;
+  }
+  if (raw === OPEN) return true;
+  if (raw === CLOSED) return false;
+  return null;
+}
+
+/** Persist a section's open/closed state. Swallows storage errors (never throws). */
+export function writePersistedOpen(
+  storage: CollapseStorage,
+  tenant: string,
+  sectionId: CollapseSectionId,
+  open: boolean,
+): void {
+  try {
+    storage.setItem(collapseStorageKey(tenant, sectionId), open ? OPEN : CLOSED);
+  } catch {
+    /* storage unavailable (private mode / disabled) — persistence is best-effort */
+  }
+}

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

@@ -1,11 +1,10 @@
 /**
- * Dispatch-health assessment (dg5) — is the static-publish `repository_dispatch`
+ * Dispatch-health assessment — 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
+ * surface that answers 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:
@@ -19,14 +18,13 @@
  *                                             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.
+ *                                             (the HELD main-promotion gate) —
+ *                                             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
+ *                                             VERIFY in the orchestrator is the real
  *                                             no-false-live gate).
  *
  * FAIL-CLOSED SEMANTICS:

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

@@ -1,5 +1,5 @@
 /**
- * Apex domain-connect state + dispatch (handoff 2026-08-05-domain-connect-ux).
+ * Apex domain-connect state + dispatch.
  *
  * The admin Publish tab's "Domain" section drives the apex DNS cutover
  * (tokenoftrust.com → CloudFront) and its rollback as PRODUCT actions, not a
@@ -212,8 +212,11 @@ export interface DomainRunCallback {
  *              overwrite an existing pointer with null — the FIRST capture is
  *              the true pre-platform state)
  *   rollback → `pantheon`
- * Rehearsal (wire: dryRun) runs never move state — only the run outcome is
- * recorded.
+ * Rehearsal (wire: dryRun) runs never move `state` — but a rehearsal CONNECT
+ * that reports a `priorKey` DOES record the revert target (prior-records pointer),
+ * because persisting a metadata capture mutates no live DNS, and it's what lets
+ * the apex-cutover readiness gate's "revert captured" precondition go green BEFORE
+ * the real cutover. Capturing the revert target is decoupled from moving state.
  */
 export function completeDomainRun(
   state: DomainState,
@@ -245,19 +248,25 @@ export function completeDomainRun(
   };
 
   let next: DomainState = { ...state, lastRun: updatedRun };
-  if (cb.status === "succeeded" && !run.rehearsal) {
-    const reported =
-      cb.state === "cloudfront" || cb.state === "pantheon" ? cb.state : null;
-    next = {
-      ...next,
-      state: reported ?? (run.action === "connect" ? "cloudfront" : "pantheon"),
-      since: updatedRun.finishedAt,
-    };
+  if (cb.status === "succeeded") {
+    // Platform state flips only on a REAL (non-rehearsal) run — a rehearsal
+    // changes no DNS, so it must never claim the apex moved.
+    if (!run.rehearsal) {
+      const reported =
+        cb.state === "cloudfront" || cb.state === "pantheon" ? cb.state : null;
+      next = {
+        ...next,
+        state: reported ?? (run.action === "connect" ? "cloudfront" : "pantheon"),
+        since: updatedRun.finishedAt,
+      };
+    }
+    // Capturing the revert target is DECOUPLED from moving state: any successful
+    // connect that carries a priorKey records it — a rehearsal included — so the
+    // readiness gate can confirm a tested rollback before the real cutover. Never
+    // regress an existing pointer to null (the FIRST capture is the true origin).
     if (run.action === "connect") {
       next = {
         ...next,
-        // Keep the FIRST capture if the callback carries none — never regress
-        // the pointer to null once a real capture exists.
         priorRecordsKey: cb.priorKey ?? state.priorRecordsKey,
         priorCapturedAt: cb.priorKey
           ? (cb.completedAt ?? at)