@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

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

@@ -0,0 +1,369 @@
+/**
+ * Pure state-derivation for the publish lifecycle's FAIL-VISIBLE invariant.
+ *
+ * ── The invariant this module enforces ──────────────────────────────────────
+ * "Fail-visible, never fail-silent." Every candidate/PR and every step of its
+ * lifecycle (submitted → reconciled → integrated → built → dispatched) stays
+ * VISIBLE, with an honest state and a concrete next step, from creation until it
+ * is terminally dispatched (shipped) or explicitly discarded by a human. The
+ * three rules below are load-bearing and exhaustively unit-tested here, decoupled
+ * from any DOM/transport:
+ *
+ *   1. DERIVE FROM THE ACTUAL RESULT — a step's success/failure is read from the
+ *      real underlying signal (did the merge land? did the build pass?), never
+ *      from a separate optimistic flag that can disagree with reality. This is
+ *      what killed the false "Integration did not land" modal: the merge HAD
+ *      landed (a real `aggregateSha` was written) while a later build failed, yet
+ *      the UX asserted the whole thing didn't land.
+ *
+ *   2. UNKNOWN STATE = ERROR STATE — if the outcome cannot be positively
+ *      determined (network fault mid-flight, an HTTP error with no honest reason,
+ *      a build sha whose result we can't confirm), render an explicit
+ *      "unknown — needs attention" state with a re-check/rebuild next step. Never
+ *      hide it and never optimistically show success. "Not sure" ⇒ "probably stuck."
+ *
+ *   3. NEVER A DEAD END — every failure carries (a) WHICH step failed, (b) a
+ *      concrete NEXT-STEP action (rebuild / update / re-check), and (c) enough
+ *      identity to act on it. A build that never produced a renderable revision
+ *      must surface as "build failed — rebuild", never a link that 404s.
+ *
+ * All functions are total and side-effect-free.
+ */
+
+/** The next step a human can take on a failed/uncertain step. */
+export type LifecycleActionKind = "rebuild" | "update-change" | "recheck" | "none";
+
+export interface LifecycleAction {
+  kind: LifecycleActionKind;
+  label: string;
+}
+
+// ── Integrate outcome (the "Integration did not land" fix) ───────────────────
+
+/**
+ * The honest classification of ONE accept/integrate attempt. Distinguishes the
+ * cases the UX previously collapsed into a single false "did not land":
+ *
+ *  - `green`                  — merge landed AND the aggregate built green.
+ *  - `already-integrated`     — the candidate had already merged before this click.
+ *  - `merge-conflict`         — the merge itself was refused (nothing landed);
+ *                               offer conflict recovery.
+ *  - `not-base`               — the candidate does not target `preview` (dev fix).
+ *  - `integrated-build-failed`— THE INCIDENT: the merge LANDED (a real
+ *                               `aggregateSha` exists) but the preview build/evidence
+ *                               failed. NOT "did not land" — it landed; the build is
+ *                               what's stuck. Next step: rebuild.
+ *  - `not-landed`             — the merge did not land, for another named reason.
+ *  - `unknown`                — indeterminate (rule 2). Treat as stuck; re-check.
+ */
+export type IntegrateOutcomeKind =
+  | "green"
+  | "already-integrated"
+  | "merge-conflict"
+  | "not-base"
+  | "integrated-build-failed"
+  | "not-landed"
+  | "unknown";
+
+/** The raw facts of an integrate attempt, from the HTTP result + the IntegrateOutcome body. */
+export interface IntegrateOutcomeFacts {
+  /** `res.ok` — the transport succeeded (2xx). */
+  httpOk: boolean;
+  /** The fetch threw (network fault mid-flight) — the outcome is indeterminate. */
+  networkError?: boolean;
+  /** `data.ok` — the aggregate went green. */
+  ok?: boolean;
+  /**
+   * `data.aggregateSha` — THE actual-result signal. The orchestrator writes a
+   * non-null sha IFF the forge merge landed (green OR build-failed-red); it is
+   * null when the merge itself never happened. This is the discriminator between
+   * "did not land" and "landed but build failed".
+   */
+  aggregateSha?: string | null;
+  /** `data.queueState` — the aggregate's honest state after this cycle. */
+  queueState?: string | null;
+  /** `data.reason` — the honest refusal category, when not green. */
+  reason?: string | null;
+  /** `data.statusMessage` — human/audit detail for a non-green outcome. */
+  statusMessage?: string | null;
+  /** `data.error` — a transport/validation error message (non-2xx). */
+  error?: string | null;
+  /** Identity for the copy: "PR #16" / a changeId (rule 3c). */
+  target: string;
+}
+
+export interface IntegrateOutcomeView {
+  kind: IntegrateOutcomeKind;
+  /** Did the forge merge land into the preview aggregate? (The truth, not a flag.) */
+  landed: boolean;
+  /** Did the aggregate end green? */
+  ok: boolean;
+  /** The outcome seal for the ceremony: success vs. attention. */
+  seal: "ok" | "err";
+  /** Which lifecycle step failed, or null on success. */
+  failStage: "merge" | "evidence" | null;
+  /** The outcome title — HONEST about what landed. */
+  title: string;
+  /** The outcome detail copy. */
+  detail: string;
+  /** Show the merge-conflict recovery panel (merge-conflict only). */
+  conflictGuidance: boolean;
+  /** The concrete next step (rule 3b), or null when none applies. */
+  action: LifecycleAction | null;
+  /**
+   * The "Review the preview build" deep-link state (rule 3 / no-404): shown ONLY
+   * when a real, renderable revision exists — i.e. the aggregate went green. A
+   * build-failed sha is NOT renderable, so the link is withheld to avoid a 404.
+   */
+  review: { show: boolean; sha: string | null };
+}
+
+/** Refusal reasons that mean the merge itself never landed (aggregate untouched). */
+const MERGE_NEVER_LANDED_REASONS = new Set(["not_preview_base", "merge_failed", "candidate_not_open"]);
+
+/**
+ * Classify an integrate attempt from its ACTUAL result. Precedence is ordered so a
+ * definite, honest signal always wins over an optimistic one.
+ */
+export function classifyIntegrateOutcome(f: IntegrateOutcomeFacts): IntegrateOutcomeView {
+  const target = f.target || "This change";
+
+  // Rule 2: a network fault mid-flight means we DON'T KNOW whether the merge
+  // landed. Never guess — render the explicit unknown state with a re-check step.
+  if (f.networkError) {
+    return {
+      kind: "unknown",
+      landed: false,
+      ok: false,
+      seal: "err",
+      failStage: null,
+      title: "We couldn't confirm the result",
+      detail:
+        "The connection dropped while adding " + target + " to your next release, so its result " +
+        "could not be confirmed. It may have gone through. Re-check before retrying — do not assume it failed.",
+      conflictGuidance: false,
+      action: { kind: "recheck", label: "Re-check status" },
+      review: { show: false, sha: null },
+    };
+  }
+
+  // Rule 1: green is derived from the real ok signal.
+  if (f.httpOk && f.ok) {
+    const sha = f.aggregateSha ?? null;
+    return {
+      kind: "green",
+      landed: true,
+      ok: true,
+      seal: "ok",
+      failStage: null,
+      title: "Added to your next release",
+      detail:
+        target + " is in. The preview build passed all your store's checks — this is exactly what " +
+        "you review, and what Publish takes live. Nothing is live yet.",
+      conflictGuidance: false,
+      action: null,
+      review: { show: Boolean(sha), sha },
+    };
+  }
+
+  // A non-2xx transport with no honest IntegrateOutcome body is indeterminate.
+  if (!f.httpOk && !f.reason && f.aggregateSha == null) {
+    return {
+      kind: "unknown",
+      landed: false,
+      ok: false,
+      seal: "err",
+      failStage: null,
+      title: "We couldn't confirm the result",
+      detail:
+        (f.error || f.statusMessage || "The server returned an error with no confirmed state.") +
+        " " + target + "'s result could not be confirmed — re-check before retrying.",
+      conflictGuidance: false,
+      action: { kind: "recheck", label: "Re-check status" },
+      review: { show: false, sha: null },
+    };
+  }
+
+  // The candidate had already merged before this click — a success being re-heard,
+  // not a failure (the row went stale). Never conflict guidance.
+  if (f.reason === "candidate_not_open") {
+    return {
+      kind: "already-integrated",
+      landed: true,
+      ok: false,
+      seal: "ok",
+      failStage: null,
+      title: "Already added",
+      detail:
+        target + " was added to your next release earlier — this attempt found nothing left to do. " +
+        "It will drop off the queue on the next refresh; the change is recorded below.",
+      conflictGuidance: false,
+      action: null,
+      review: { show: false, sha: null },
+    };
+  }
+
+  // The merge was refused because the candidate branched off the current preview and
+  // both edit the same content — a fork, not a failure of the change. Nothing landed.
+  if (f.reason === "merge_failed") {
+    return {
+      kind: "merge-conflict",
+      landed: false,
+      ok: false,
+      seal: "err",
+      failStage: "merge",
+      title: "Preview changed while you worked",
+      detail:
+        target + " edits content that also changed on preview after it was created, so it " +
+        "couldn't be added as-is. Nothing was added — your next release is exactly as it was. You can " +
+        "update this change automatically below.",
+      conflictGuidance: true,
+      action: { kind: "update-change", label: "Update this change automatically" },
+      review: { show: false, sha: null },
+    };
+  }
+
+  // The candidate does not target the preview branch — a developer fix, not a retry.
+  if (f.reason === "not_preview_base") {
+    return {
+      kind: "not-base",
+      landed: false,
+      ok: false,
+      seal: "err",
+      failStage: "merge",
+      title: "Couldn't add this change",
+      detail:
+        target + " couldn't be added — it isn't based on your store's preview. " +
+        (f.statusMessage || ""),
+      conflictGuidance: false,
+      action: null,
+      review: { show: false, sha: null },
+    };
+  }
+
+  // THE INCIDENT (rule 1): a real `aggregateSha` was written ⇒ the forge merge
+  // LANDED. If we're here it did not go green, so the preview BUILD/evidence is
+  // what failed. This is NOT "did not land" — say exactly what happened and offer
+  // the rebuild. The review link is WITHHELD (rule 3): the sha never built, so
+  // linking it would 404.
+  if (f.aggregateSha) {
+    return {
+      kind: "integrated-build-failed",
+      landed: true,
+      ok: false,
+      seal: "err",
+      failStage: "evidence",
+      title: "Added, but the preview build didn't pass",
+      detail:
+        target + " was added to your next release, but the preview build didn't pass your store's " +
+        "checks" +
+        (f.statusMessage ? " (" + f.statusMessage + ")" : "") +
+        ". Nothing is live. Rebuild the preview to finish — the change stays in.",
+      conflictGuidance: false,
+      action: { kind: "rebuild", label: "Rebuild the preview build" },
+      review: { show: false, sha: null },
+    };
+  }
+
+  // The merge genuinely did not land (no sha), for a named or generic reason.
+  const reasonKnownNotLanded = f.reason ? MERGE_NEVER_LANDED_REASONS.has(f.reason) : false;
+  return {
+    kind: reasonKnownNotLanded || f.reason ? "not-landed" : "unknown",
+    landed: false,
+    ok: false,
+    seal: "err",
+    failStage: "merge",
+    title: f.reason ? "Couldn't add this change" : "We couldn't confirm the result",
+    detail:
+      (f.statusMessage || f.error ||
+        "The change couldn't be added and your next release is unchanged.") +
+      (f.reason ? "" : " Its result could not be confirmed — re-check the queue."),
+    conflictGuidance: false,
+    action: { kind: f.reason ? "recheck" : "recheck", label: "Re-check status" },
+    review: { show: false, sha: null },
+  };
+}
+
+// ── Build link (the "Open Build" 404 fix) ────────────────────────────────────
+
+/**
+ * Whether a `/preview/rev/<sha>/` deep-link is safe to offer, derived from the
+ * ACTUAL build result — never from the mere presence of a sha. The caller passes
+ * `built`: is THIS sha a genuinely-built, renderable revision? A link is offered
+ * only when it is. Every other case surfaces an honest state + next step instead of
+ * a dead link (rules 1 & 3). Two call-sites, two `built` rules:
+ *
+ *  - The aggregate CARD's own sha is always the last-GREEN materialized sha (a red
+ *    cycle leaves it untouched), so `built = sha exists`. Opening it reaches the
+ *    last-good preview even while the current cycle is red.
+ *  - A specific integration RUN's sha is renderable IFF that run passed, so
+ *    `built = run.state === "passed"`. A failed run's sha never materialized —
+ *    linking it is the exact "Open Build → 404" trap this guards.
+ */
+export type BuildLinkKind = "ready" | "building" | "failed" | "none";
+
+export interface BuildLinkFacts {
+  /** The sha the link would open, or null. */
+  sha?: string | null;
+  /** Is that sha a genuinely-built, renderable revision? */
+  built: boolean;
+  /** A build is in flight right now (so "not ready yet", not "failed"). */
+  building?: boolean;
+  /** A build was attempted (distinguishes "failed" from "never built"). */
+  attempted?: boolean;
+}
+
+export interface BuildLinkView {
+  /** Is the rev deep-link safe to render as a link? */
+  available: boolean;
+  kind: BuildLinkKind;
+  /** Link/label text. */
+  label: string;
+  /** A caption for the non-link states. */
+  note: string;
+  /** The next step when the build failed (rule 3b), else null. */
+  action: LifecycleAction | null;
+}
+
+export function classifyBuildLink(f: BuildLinkFacts): BuildLinkView {
+  const sha = f.sha ?? null;
+
+  // Genuinely built: the sha names a renderable revision — safe to link (even if a
+  // newer cycle is in flight or red, this reaches the last-good preview).
+  if (sha && f.built) {
+    return { available: true, kind: "ready", label: "Open build", note: "", action: null };
+  }
+
+  // No renderable sha, but a build is in flight — not openable yet, not failed.
+  if (f.building) {
+    return {
+      available: false,
+      kind: "building",
+      label: "Build in progress…",
+      note: "The preview build is still running. It'll be openable once it finishes.",
+      action: null,
+    };
+  }
+
+  // A build was attempted but produced no renderable revision — the exact
+  // "Open Build → 404" trap. Surface the failure + the rebuild, never a dead link.
+  if (f.attempted) {
+    return {
+      available: false,
+      kind: "failed",
+      label: "Preview build failed",
+      note:
+        "The last preview build didn't finish, so there's nothing to open yet. Rebuild it to try again.",
+      action: { kind: "rebuild", label: "Rebuild the preview build" },
+    };
+  }
+
+  // Nothing has been built yet.
+  return {
+    available: false,
+    kind: "none",
+    label: "No build yet",
+    note: "No preview build has been produced for this store yet.",
+    action: null,
+  };
+}

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

@@ -0,0 +1,29 @@
+export type LiveReleaseSummaryView =
+  | { kind: "current"; label: string }
+  | { kind: "publish"; label: string; disabled: boolean; title: string }
+  | { kind: "empty"; label: string };
+
+/**
+ * Derive the collapsed release panel's single status/action affordance.
+ * Public-target freshness is deliberately absent: only staged-vs-live equality
+ * is allowed to claim that the next release is current.
+ */
+export function liveReleaseSummaryState(input: {
+  matchesLive: boolean;
+  hasStagedRelease: boolean;
+  publishDisabled: boolean;
+  publishTitle: string;
+}): LiveReleaseSummaryView {
+  if (input.matchesLive) {
+    return { kind: "current", label: "Live is up to date with next release" };
+  }
+  if (input.hasStagedRelease) {
+    return {
+      kind: "publish",
+      label: "Publish next release",
+      disabled: input.publishDisabled,
+      title: input.publishTitle,
+    };
+  }
+  return { kind: "empty", label: "No release staged" };
+}

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

@@ -0,0 +1,78 @@
+/**
+ * mergeDoctorOnFailure — the admin#publish half of C5 (the merge-doctor PUSH).
+ *
+ * When an accept/integrate or an aggregate ship ACTION FAILS in the Publish tab, the
+ * developer shouldn't have to go read the top-of-tab health banner or a per-row chip
+ * to understand WHY — the diagnosis should show up right where the failure surfaced.
+ * These pure reducers turn the SAME `/api/changes` payload the tab already fetches
+ * (via {@link mergeRowFindings} / {@link mergeHealthBanner}) into a compact one-line
+ * hint the client island appends to the failure's own status/outcome copy.
+ *
+ * No new fetch and no new analyzer: this is the SAME analysis {@link mergeRowFindings}
+ * and {@link mergeHealthBanner} already run for the banner + row chips — reduced to
+ * "the one thing this failure means". Pure + unit-tested; the DOM wiring in
+ * `adminPublishTab.ts` is thin glue over these.
+ */
+import { mergeRowFindings, mergeRowKey, type MergeRowFinding } from "./mergeRowFindings";
+import { mergeHealthBanner } from "./mergeHealthBanner";
+
+// The `/api/changes` body shape, derived from the analyzers that consume it — so this
+// module stays inside lib/publish and never imports the control-plane moat
+// (lib/preview) directly (the renderer-no-controlplane depcruise fence).
+type ChangesBody = Parameters<typeof mergeRowFindings>[0];
+
+export interface DoctorFailureHint {
+  /** Whether there's anything to append (false ⇒ the failure's own copy stands alone). */
+  show: boolean;
+  /** The compact one-line diagnosis to append at the failure moment ("" when !show). */
+  text: string;
+  /** The dominant row finding when the failure maps to a specific candidate (else null). */
+  finding: MergeRowFinding | null;
+}
+
+const NONE: DoctorFailureHint = { show: false, text: "", finding: null };
+
+/** The compact one-liner for a single candidate row's finding — ownership tag +
+ *  what's wrong + the remedy, the same three facts the row chip's tooltip carries. */
+export function formatRowHint(f: MergeRowFinding): string {
+  return `Merge doctor (${f.ownershipLabel}): ${f.detail} → ${f.remedy}`;
+}
+
+/**
+ * Diagnosis appended when an accept/integrate FAILS on ONE candidate row. Looks that
+ * candidate's dominant finding up in the SAME per-row index the queue renders (built
+ * rows keyed by changeId, not-built PRs by number). Returns {@link NONE} when the row
+ * carries no finding (e.g. a transient/network failure the doctor can't see) — so a
+ * failure the analyzer has no opinion on gets no misleading hint.
+ */
+export function integrateFailureDoctor(
+  changesBody: ChangesBody,
+  target: { changeId?: string | null; prNumber?: number | null },
+  opts: { nowMs?: number } = {},
+): DoctorFailureHint {
+  const findings = mergeRowFindings(changesBody, { nowMs: opts.nowMs });
+  const changeKey = target.changeId != null ? mergeRowKey(target.changeId, null) : null;
+  const prKey = target.prNumber != null ? mergeRowKey(null, target.prNumber) : null;
+  const finding =
+    (changeKey ? findings.get(changeKey) : undefined) ??
+    (prKey ? findings.get(prKey) : undefined) ??
+    null;
+  if (!finding) return NONE;
+  return { show: true, text: formatRowHint(finding), finding };
+}
+
+/**
+ * Diagnosis appended when the aggregate SHIP (publish) is refused/fails. A ship
+ * failure is an aggregate-level event (most tellingly "not green"), so it uses the
+ * SAME roll-up the top-of-tab health banner shows — "what's keeping the aggregate
+ * from going green" — rather than a single row. Returns {@link NONE} when the queue
+ * is clean of developer/platform work (nothing the doctor can add).
+ */
+export function shipFailureDoctor(
+  changesBody: ChangesBody,
+  opts: { nowMs?: number } = {},
+): DoctorFailureHint {
+  const banner = mergeHealthBanner(changesBody, { nowMs: opts.nowMs });
+  if (!banner.show) return NONE;
+  return { show: true, text: `Merge doctor: ${banner.text}`, finding: null };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * mergeHealthBanner — the wiring seam between the mergeDoctor analyzer (the
+ * PURE brain, `lib/preview/mergeDoctor.ts`) and the admin Publish tab's
+ * top-of-page health banner. Runs the analyzer over the SAME `/api/changes`
+ * body the queue already fetched (no extra read) and reduces it to the three
+ * things the DOM toggle needs: whether to show at all, the one-line text, and
+ * the severity tone.
+ *
+ * `show` is FALSE whenever nothing is developer-actionable and no platform
+ * blocker is outstanding — i.e. exactly when {@link attentionBanner} would
+ * return its "Nothing needs your attention." sentinel — so a healthy queue
+ * renders no empty banner chrome.
+ */
+import {
+  analyzeMerge,
+  attentionBanner,
+  OWNERSHIP,
+  type ChangesInput,
+  type BranchesInput,
+} from "@/lib/preview/mergeDoctor";
+
+export interface MergeHealthBanner {
+  /** Render the banner? False when the queue is clean of developer/platform work. */
+  show: boolean;
+  /** The one-line attention summary (empty string when `show` is false). */
+  text: string;
+  /** Highest outstanding severity — drives the amber (warn) vs red (blocker) look. */
+  tone: "blocker" | "warn";
+}
+
+/**
+ * Reduce a `/api/changes` body (the queue payload the tab already holds) to the
+ * merge-health banner state. `branchesBody` is optional; the banner only counts
+ * developer-actionable + platform-blocker findings, none of which come from the
+ * branch plane, so it is safe to omit when the branches panel hasn't loaded.
+ */
+export function mergeHealthBanner(
+  changesBody: ChangesInput["body"],
+  opts: { branchesBody?: BranchesInput["body"]; nowMs?: number } = {},
+): MergeHealthBanner {
+  const result = analyzeMerge({
+    changes: { status: 200, body: changesBody ?? {} },
+    branches: opts.branchesBody ? { status: 200, body: opts.branchesBody } : {},
+    tenant: changesBody?.owner ?? null,
+    nowMs: opts.nowMs,
+  });
+
+  const devActionable = result.findings.filter(
+    (f) => f.ownership === OWNERSHIP.developer && f.severity !== "info",
+  );
+  const platformBlockers = result.findings.filter(
+    (f) => f.ownership === OWNERSHIP.platform && f.severity === "blocker",
+  );
+
+  const show = devActionable.length > 0 || platformBlockers.length > 0;
+  const tone: "blocker" | "warn" =
+    platformBlockers.length > 0 || devActionable.some((f) => f.severity === "blocker")
+      ? "blocker"
+      : "warn";
+
+  return { show, text: show ? attentionBanner(result) : "", tone };
+}

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

@@ -0,0 +1,124 @@
+/**
+ * mergeRowFindings — the per-row companion to {@link mergeHealthBanner}. Both
+ * reduce the SAME `/api/changes` body (the queue payload the tab already holds)
+ * through the SAME pure analyzer (`lib/preview/mergeDoctor.ts`); the banner rolls
+ * findings up into one top-of-tab line, this one indexes them BY ROW so each
+ * candidate can carry its own ownership-tagged chip + the mapped action.
+ *
+ * It emits no new fetch and no per-row analysis call: one `analyzeMerge` pass over
+ * the already-fetched body, then a `Map` keyed by {@link mergeRowKey} so the queue
+ * renderer can look a row's finding up in O(1). A row with no per-row finding
+ * (healthy, or a banner/branch-plane finding that names no candidate) is simply
+ * absent from the map — the renderer shows no chip.
+ *
+ * The `cta` this exposes is the finding's OWN mapped action reduced to what the DOM
+ * needs to light up an EXISTING queue button (resolve → the conflict-recovery
+ * button, build/retry → the build button) — never a re-declared API path.
+ */
+import {
+  analyzeMerge,
+  type ChangesInput,
+  type BranchesInput,
+  type Finding,
+  type FindingAction,
+  type FindingCode,
+  type OwnershipKind,
+  type Severity,
+} from "@/lib/preview/mergeDoctor";
+
+/** A single candidate row's dominant merge-doctor finding, DOM-ready. */
+export interface MergeRowFinding {
+  code: FindingCode;
+  severity: Severity;
+  ownership: OwnershipKind;
+  /** The chip's ownership tag — the ticket-deflection axis, in operator words. */
+  ownershipLabel: string;
+  /** Chip tone in this repo's convention (`""` = neutral); driven by severity. */
+  tone: "red" | "amber" | "";
+  detail: string;
+  remedy: string;
+  /**
+   * The mapped next step, or null for an informational-only finding (chip, no
+   * button). `kind` selects WHICH existing button to light up; `label` is the
+   * finding's own action label (used only for the fallback CTA when no inline
+   * button exists to prime).
+   */
+  cta: { kind: FindingAction["kind"]; label: string } | null;
+}
+
+/** Ownership tag copy — developer self-serves; platform is "on us"; operator tidies. */
+const OWNERSHIP_LABEL: Record<OwnershipKind, string> = {
+  developer: "You",
+  platform: "On us",
+  operator: "Housekeeping",
+};
+
+const TONE_BY_SEVERITY: Record<Severity, "red" | "amber" | ""> = {
+  blocker: "red",
+  warn: "amber",
+  info: "",
+};
+
+const SEVERITY_RANK: Record<Severity, number> = { blocker: 0, warn: 1, info: 2 };
+
+/**
+ * The stable per-row key shared by producer (this module) and consumer (the queue
+ * renderer). A built candidate is keyed by its `changeId`; a not-built forge PR has
+ * no changeId, so it is keyed by `prNumber`. Returns null when a finding names
+ * neither (a banner/branch-plane finding that belongs to no single row).
+ */
+export function mergeRowKey(changeId: string | null, prNumber: number | null): string | null {
+  if (changeId != null) return "change:" + changeId;
+  if (prNumber != null) return "pr:" + prNumber;
+  return null;
+}
+
+function toRowFinding(f: Finding): MergeRowFinding {
+  return {
+    code: f.code,
+    severity: f.severity,
+    ownership: f.ownership,
+    ownershipLabel: OWNERSHIP_LABEL[f.ownership] ?? f.ownership,
+    tone: TONE_BY_SEVERITY[f.severity],
+    detail: f.detail,
+    remedy: f.remedy,
+    cta: f.action ? { kind: f.action.kind, label: f.action.label } : null,
+  };
+}
+
+/**
+ * When two findings land on the same row, the more severe one wins; on a tie, the
+ * one that carries an action (a CTA to light up) beats a purely informational one.
+ */
+function candidateWins(current: MergeRowFinding, candidate: Finding): boolean {
+  const rc = SEVERITY_RANK[candidate.severity];
+  const rk = SEVERITY_RANK[current.severity];
+  if (rc !== rk) return rc < rk;
+  return Boolean(candidate.action) && !current.cta;
+}
+
+/**
+ * Index a `/api/changes` body's merge findings by row. `branchesBody` is optional
+ * and only feeds branch-plane findings, none of which name a candidate row, so it
+ * never changes the per-row map — accepted for parity with {@link mergeHealthBanner}.
+ */
+export function mergeRowFindings(
+  changesBody: ChangesInput["body"],
+  opts: { branchesBody?: BranchesInput["body"]; nowMs?: number } = {},
+): Map<string, MergeRowFinding> {
+  const result = analyzeMerge({
+    changes: { status: 200, body: changesBody ?? {} },
+    branches: opts.branchesBody ? { status: 200, body: opts.branchesBody } : {},
+    tenant: changesBody?.owner ?? null,
+    nowMs: opts.nowMs,
+  });
+
+  const byRow = new Map<string, MergeRowFinding>();
+  for (const f of result.findings) {
+    const key = mergeRowKey(f.changeId, f.prNumber);
+    if (key === null) continue; // banner/branch-plane finding — belongs to no row
+    const current = byRow.get(key);
+    if (!current || candidateWins(current, f)) byRow.set(key, toRowFinding(f));
+  }
+  return byRow;
+}