@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.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/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)

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

@@ -0,0 +1,78 @@
+// Client-side polling primitives for the admin Publish tab: a headSha-keyed
+// cache and an overlap coalescer. The tab's `is:inline` island can't import
+// modules, so it hand-mirrors these (see AdminPublishTab.astro `makeKeyedCache`
+// / `makeCoalescer`); this module is the tested source of truth for the
+// behaviour — keep the mirror in sync.
+
+/**
+ * A cache keyed by an opaque string. The Publish tab keys panel data by a
+ * fingerprint that includes candidate head shas + the live version, so a hit
+ * means "this panel's data at this state is already known — don't re-fetch".
+ * A candidate's data at a fixed head sha is immutable, so cached values never
+ * go stale for the same key.
+ */
+export function createKeyedCache<T>() {
+  const store = new Map<string, T>();
+  return {
+    get(key: string): T | undefined {
+      return store.get(key);
+    },
+    has(key: string): boolean {
+      return store.has(key);
+    },
+    set(key: string, value: T): void {
+      store.set(key, value);
+    },
+    delete(key: string): void {
+      store.delete(key);
+    },
+    clear(): void {
+      store.clear();
+    },
+    get size(): number {
+      return store.size;
+    },
+  };
+}
+
+export type KeyedCache<T> = ReturnType<typeof createKeyedCache<T>>;
+
+/**
+ * Coalesce overlapping async runs so rapid re-renders, poll ticks, and user
+ * actions can't stack duplicate/overlapping requests for the same panel. While
+ * a run is in flight, further triggers don't start a second concurrent run —
+ * they mark the run "pending" so exactly ONE trailing run fires after the
+ * current one settles (regardless of how many triggers arrived meanwhile).
+ */
+export function createCoalescer(run: () => Promise<void> | void) {
+  let inFlight = false;
+  let pending = false;
+
+  const tick = async (): Promise<void> => {
+    if (inFlight) {
+      pending = true;
+      return;
+    }
+    inFlight = true;
+    try {
+      await run();
+    } finally {
+      inFlight = false;
+      if (pending) {
+        pending = false;
+        void tick();
+      }
+    }
+  };
+
+  return {
+    trigger(): Promise<void> {
+      return tick();
+    },
+    get busy(): boolean {
+      return inFlight;
+    },
+  };
+}
+
+export type Coalescer = ReturnType<typeof createCoalescer>;

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

@@ -1,33 +1,32 @@
 /**
- * Ship operations workspace (unit dg7) — the PURE composer behind the admin
+ * Ship operations workspace — the PURE composer behind the admin
  * Publish tab's operations surface that sits ALONGSIDE the go-live core
  * (AdminPublishTab.astro's change queue + accept/reject + dispatch status).
  *
- * dg7 is DELTA-scoped: the go-live session already delivered the Publish-tab
- * core (the change queue from GET /api/changes, Go-live/Reject, the live-version
- * + dispatch-status panel, and the owner-only Domain section). This module adds
- * the operations workspace BEYOND that core — the three read/act surfaces woven
- * into the same tab:
+ * This module composes the operations workspace ALONGSIDE the Publish-tab core
+ * (the change queue from GET /api/changes, Go-live/Reject, the live-version +
+ * dispatch-status panel, and the owner-only Domain section) — the three read/act
+ * surfaces woven into the same tab:
  *
  *   1. DIFF VIEW  — for one pending candidate, the artifact-level diff of what
  *      changed (its rendered immutable version vs the current live version),
- *      tied to the exact tenant Gitea head SHA, with the u5 immutable
- *      `/preview/<tenant>/rev/<sha>/` link and the dg3 evidence AUTHORITY
+ *      tied to the exact tenant Gitea head SHA, with the immutable
+ *      `/<tenant>/preview/rev/<sha>/` link and the evidence AUTHORITY
  *      (authoritative / stale / missing) — never a diff a reviewer would mistake
  *      for the head when a last-good version actually renders.
  *   2. VERSIONS  — the tenant's published-version / promotion history
- *      (`listPromotions`, u2/u3 promotion_status), each row carrying the tenant
- *      Gitea SHA (`gitea-only-tenant-content-authority`), its promotion time, a
+ *      (`listPromotions`, promotion_status), each row carrying the tenant
+ *      Gitea SHA, its promotion time, a
  *      `/rev/<sha>/` link, and — marking the current live one.
  *   3. ROLLBACK  — pick a prior version and roll back THROUGH the one orchestrator
- *      (`/api/changes/rollback` → `rollbackCandidateAtomic` / u8's
+ *      (`/api/changes/rollback` → `rollbackCandidateAtomic` /
  *      `staticRollbackOrchestrator`), rendering only the HONEST terminal state
  *      (`rolled_back` when VERIFIED; `publish_pending` in flight; `publish_failed`
  *      / `blocked` fail-closed) — never a false "rolled back".
  *
  * COMPOSES, never rebuilds:
- *   - the u5 immutable link is `reviewDashboardRevisionHref` verbatim;
- *   - the dg3 authority is `candidateEvidenceAuthority` /
+ *   - the immutable link is `reviewDashboardRevisionHref` verbatim;
+ *   - the authority is `candidateEvidenceAuthority` /
  *     `classifyCandidateForRender` verbatim;
  *   - the versions come from the SAME `KVVersionStore.listPromotions` the
  *     "one step back" rollback resolution reads;
@@ -38,16 +37,13 @@
  * decision is unit-tested without a Worker/KV — mirroring the reviewDashboard.ts /
  * candidatePreviewState.ts split.
  *
- * HONEST BOUNDARY (surfaced, never faked): a FULLY-STATIC tenant serves its public
- * site from an external `versions/<digest>/` archive whose per-version treeDigests
- * live only in S3 — enumerable by the Node-only `listRollbackTargets`
- * (`scripts/publish/lib/static-rollback.mjs`), NOT by the Worker. So the console
- * can list a static tenant's promotion history + `/rev` links + the CURRENT live
- * digest, but it cannot resolve an ARBITRARY prior version's archive digest, which
- * `/api/changes/rollback` fail-closed requires (`targetDigest`). `rollbackMode`
- * names this: a `control-plane` tenant rolls back one-click (targetVersionId only);
- * a `static-archive` tenant's per-version rollback is honestly deferred to the ship
- * CLI / CI that enumerates the archive — never a one-click that would 400.
+ * `rollbackMode` names the path a rollback is honestly driven by: a `control-plane`
+ * (hosted) tenant and a `pointer` (static-publish) tenant BOTH roll back one-click
+ * via the instant KV `live` pointer flip — the Worker serves whatever bundle the
+ * pointer's digest names (from R2, for a static tenant), so restoring the pointer IS
+ * the rollback. The `publish_pending`/`publish_failed`/`blocked` honesty model from
+ * `interpretRollbackResponse` below applies identically in both modes — only the
+ * digest column (surfaced for a static tenant) differs.
  */
 import { reviewDashboardRevisionHref } from "@/lib/preview/reviewDashboard";
 import {
@@ -60,10 +56,36 @@ import type { ReviewEnvironment, PromotionEvent } from "@tot/public-runtime";
 
 // ── Versions / promotion history ───────────────────────────────────────────
 
-/** One published version in the tenant's promotion history (u2/u3 promotion_status). */
+/** The plain-language "what shipped in this version" model (same shape the staged
+ *  release summary uses — a lead sentence + one highlight per included change). */
+export interface VersionReleaseSummary {
+  lead: string;
+  highlights: { title: string; detail: string }[];
+}
+
+/** One change that shipped in a published version — its PR summary, for the
+ *  version's openable "what shipped" list. Fields degrade to null/`PR #N` when
+ *  candidate_summary didn't cover the PR (best-effort enrichment). */
+export interface WorkspaceVersionChange {
+  changeId: string;
+  prNumber: number | null;
+  headSha: string;
+  title: string | null;
+  description: string | null;
+  fileCount: number | null;
+  linesAdded: number | null;
+  linesRemoved: number | null;
+}
+
+/** Per-version release enrichment, keyed by versionId (== the promoted aggregate sha). */
+export interface VersionReleaseInfo {
+  releaseSummary: VersionReleaseSummary | null;
+  changes: WorkspaceVersionChange[];
+}
+
+/** One published version in the tenant's promotion history (promotion_status). */
 export interface WorkspaceVersion {
-  /** The tenant Gitea SHA the version serves — the content identity
-   *  (`gitea-only-tenant-content-authority`). */
+  /** The tenant Gitea SHA the version serves — the content identity. */
   versionId: string;
   /** How the version was published (a Gitea commit, or a content hash). */
   source: "commit" | "hash" | null;
@@ -80,14 +102,33 @@ export interface WorkspaceVersion {
    * digest lives only in the S3 archive the Worker can't enumerate. Never fabricated.
    */
   digest: string | null;
-  /** The u5 immutable `/preview/<tenant>/rev/<sha>/` deep-link, or `null` without a SHA. */
+  /** The immutable `/<tenant>/preview/rev/<sha>/` deep-link, or `null` without a SHA. */
   revHref: string | null;
   /** The version currently serving live (the one you never roll back TO). */
   isCurrent: boolean;
+  /**
+   * The plain-language "what shipped in this version" summary, composed from the
+   * release receipt's included PRs + their candidate_summary. `null` when no
+   * receipt links this version to a PR set, or none carried summary prose.
+   */
+  releaseSummary: VersionReleaseSummary | null;
+  /**
+   * The PRs that shipped in this version (from its release receipt), each with its
+   * human summary — the version's openable "what shipped" list. Empty when no
+   * receipt links this version to a PR set.
+   */
+  changes: WorkspaceVersionChange[];
+  /** How many changes shipped in this version, or `null` when unknown (no receipt). */
+  changeCount: number | null;
 }
 
-/** How a rollback is honestly driven for this tenant (see the module HONEST BOUNDARY note). */
-export type RollbackMode = "control-plane" | "static-archive";
+/**
+ * How a rollback is honestly driven for this tenant. `control-plane` (hosted) and
+ * `pointer` (static-publish) both roll back one-click via the instant KV `live`
+ * pointer flip; they render identical instant "Roll back" copy, differing only in
+ * whether the static digest column is shown.
+ */
+export type RollbackMode = "control-plane" | "pointer";
 
 /** The versions-panel view model. */
 export interface VersionsView {
@@ -98,9 +139,9 @@ export interface VersionsView {
   /** Whether the tenant publishes its public site to an external static target. */
   staticPublish: boolean;
   /**
-   * `control-plane` → a prior version rolls back one-click via `targetVersionId`.
-   * `static-archive` → per-version rollback is deferred to the ship CLI / CI that
-   * enumerates the `versions/` archive (the Worker can't resolve the archive digest).
+   * `control-plane` (hosted) and `pointer` (static-publish) both roll back
+   * one-click via `targetVersionId` (instant KV pointer flip) and render identical
+   * instant "Roll back" copy.
    */
   rollbackMode: RollbackMode;
 }
@@ -122,6 +163,12 @@ export interface BuildVersionsViewInput {
   currentDigest: string | null;
   /** Per-version manifest facts, keyed by versionId (absent ⇒ unknown facts). */
   manifests: Map<string, VersionManifestFacts>;
+  /**
+   * Per-version release enrichment, keyed by versionId (== the promoted aggregate
+   * sha on the release receipt). Absent ⇒ a version with no linked PR set (an
+   * honest empty release summary + no changes list — never fabricated).
+   */
+  releases?: Map<string, VersionReleaseInfo>;
   staticPublish: boolean;
 }
 
@@ -129,13 +176,22 @@ export interface BuildVersionsViewInput {
  * Assemble the versions panel from the promotion history + per-version manifest
  * facts + the current-live pointer. Pure. The current live row is marked; the
  * digest is populated ONLY for the current live of a static tenant (never faked
- * for priors). `revHref` is the u5 immutable link.
+ * for priors). `revHref` is the immutable link.
  */
 export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
-  const { tenantId, promotions, currentVersionId, currentDigest, manifests, staticPublish } = input;
+  const {
+    tenantId,
+    promotions,
+    currentVersionId,
+    currentDigest,
+    manifests,
+    releases,
+    staticPublish,
+  } = input;
 
   const versions: WorkspaceVersion[] = promotions.map((p) => {
     const facts = manifests.get(p.versionId);
+    const release = releases?.get(p.versionId);
     const isCurrent = currentVersionId != null && p.versionId === currentVersionId;
     return {
       versionId: p.versionId,
@@ -147,6 +203,9 @@ export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
       digest: isCurrent && staticPublish ? currentDigest : null,
       revHref: reviewDashboardRevisionHref(tenantId, p.versionId),
       isCurrent,
+      releaseSummary: release?.releaseSummary ?? null,
+      changes: release?.changes ?? [],
+      changeCount: release ? release.changes.length : null,
     };
   });
 
@@ -154,7 +213,7 @@ export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
     current: { versionId: currentVersionId, digest: staticPublish ? currentDigest : null },
     versions,
     staticPublish,
-    rollbackMode: staticPublish ? "static-archive" : "control-plane",
+    rollbackMode: staticPublish ? "pointer" : "control-plane",
   };
 }
 
@@ -175,13 +234,13 @@ export interface CandidateDiffView {
   headSha: string | null;
   /** The immutable version actually rendered + diffed — the reconcile ACTUAL. */
   versionId: string | null;
-  /** The u5 immutable link to the exact reviewed SHA, or `null` without a head SHA. */
+  /** The immutable link to the exact reviewed SHA, or `null` without a head SHA. */
   revHref: string | null;
-  /** dg3 evidence authority: authoritative (tied to head) / stale (last-good) / missing. */
+  /** Evidence authority: authoritative (tied to head) / stale (last-good) / missing. */
   authority: CandidateEvidenceAuthority;
   /** The artifact-level diff (candidate rendered version vs current live), sorted by path. */
   files: DiffEntry[];
-  /** True when the candidate has a renderable version to diff (dg3 `ready`). */
+  /** True when the candidate has a renderable version to diff (the `ready` classification). */
   renderable: boolean;
   /** When NOT renderable, the honest reason (names why) — never a fake empty diff. */
   blockedReason: string | null;
@@ -199,7 +258,7 @@ export interface BuildCandidateDiffInput {
 /**
  * Diff a candidate's rendered version against the current live version, at the
  * artifact level (each path carries a content hash in its site-version manifest).
- * Composes dg3's `classifyCandidateForRender` (only a `ready` candidate has a
+ * Composes `classifyCandidateForRender` (only a `ready` candidate has a
  * version to diff — a blocked/queued one yields an HONEST `blockedReason`, never a
  * fabricated empty diff) and `candidateEvidenceAuthority` (so a diff of a last-good
  * version that LAGS the head is flagged `stale`, not passed off as the head).
@@ -282,10 +341,9 @@ export interface RollbackOutcome {
  * for BOTH planes without the surface having to know which it hit:
  *   - a HOSTED (control-plane) rollback returns `{ rolledBack: true, toVersionId }`
  *     on success (the pointer flip IS the rollback) or `{ error, reason }` on refusal;
- *   - a STATIC rollback returns the orchestrator's honest `{ state, ... }` (u8).
+ *   - a STATIC rollback returns the orchestrator's honest `{ state, ... }`.
  * The rule the surface depends on: `rolledBack` is true ONLY for a verified
- * `rolled_back` — a `publish_pending` is NEVER rendered as rolled back
- * (`storefront-atomic-accept-is-ship-orchestrator` / `static-publish-fails-closed`).
+ * `rolled_back` — a `publish_pending` is NEVER rendered as rolled back.
  * Pure.
  */
 export function interpretRollbackResponse(