npm - @tokenoftrust/storefront-runner - Versions diffs - 1.3.4-rc.4 → 1.4.1 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (246) hide show

package/apps/storefront/src/layouts/Layout.astro CHANGED Viewed

@@ -5,6 +5,9 @@
  * Every page renders inside this.
  */
 import "@/styles/global.css";
+// Self-hosted web fonts (audit finding 6) — replaces the render-blocking
+// fonts.googleapis.com stylesheet. Bundled by Vite, served same-origin.
+import "@/styles/fonts.css";
 import Seo from "@/components/Seo.astro";
 import AnnouncementBar from "@/components/chrome/AnnouncementBar.astro";
 import SiteHeader from "@/components/chrome/SiteHeader.astro";
@@ -17,10 +20,13 @@ import ShippingRestrictionNotice from "@/components/compliance/ShippingRestricti
 import IsolatedAgeGate from "@/components/islands/IsolatedAgeGate.tsx";
 import AuthBadge from "@/components/auth/AuthBadge.astro";
 import { referenceTheme } from "@/themes/reference";
-import { mergeTheme, themeFontHref } from "@/themes/schema";
+import { mergeTheme } from "@/themes/schema";
 import { organizationLd, websiteLd } from "@/lib/jsonld";
 import { nonceInlineTags, CHROME_BODY_MARKER } from "@/lib/rawMarketingHtml";
 import { readViewerSession } from "@/lib/auth/route";
+import AppWidgetFrame from "@/components/apps/AppWidgetFrame.astro";
+import { getRegistryService } from "@/lib/apps/adminService.js";
+import { renderWidgetSlot } from "@/lib/apps/widgets/renderSlot.js";
 interface Props {
   title: string;
@@ -49,7 +55,6 @@ const allJsonLd = [
 ];
 const theme = mergeTheme(referenceTheme, tenant.theme_tokens);
-const fontHref = themeFontHref(theme);
 const chrome = await Astro.locals.content.getChrome();
@@ -92,12 +97,22 @@ const compliance = tenant.compliance;
 // open hosts where the gate never ran. Signed-out "Sign in" carries the current
 // path as `next`, so after the email-code round-trip the visitor lands back
 // where they were instead of the site root.
-const viewer = Astro.locals.viewer ?? (await readViewerSession(Astro));
-const nextParam = encodeURIComponent(Astro.url.pathname + Astro.url.search);
-const authLink = {
-  label: viewer ? "Dashboard" : "Sign in",
-  href: viewer ? "/dashboard" : `/auth/login?next=${nextParam}`,
-};
+//
+// Marketing tenants (siteType:"marketing" → features.catalog === false) have no
+// shopper/vendor account surface to link to: /auth/login + /dashboard are also
+// excluded outright from the static-publish route set (routeClassifier's
+// auth/+dashboard/ prefixes), so a marketing-only site can never resolve either
+// URL. Skip the affordance rather than render a dangling link — mirrors the
+// same commerce/marketing split index.astro already keys off `!features.catalog`.
+let authLink: { label: string; href: string } | undefined;
+if (features.catalog) {
+  const viewer = Astro.locals.viewer ?? (await readViewerSession(Astro));
+  const nextParam = encodeURIComponent(Astro.url.pathname + Astro.url.search);
+  authLink = {
+    label: viewer ? "Dashboard" : "Sign in",
+    href: viewer ? "/dashboard" : `/auth/login?next=${nextParam}`,
+  };
+}
 // Per-vendor header treatment from the theme file: a "dark" header renders the
 // bar in the primary color carrying the light logo (e.g. Giant Vapes' navy +
@@ -121,6 +136,23 @@ const legalLine = `© ${new Date().getFullYear()} ${tenant.displayName}${
 const analyticsToken = import.meta.env.PUBLIC_CF_ANALYTICS_TOKEN;
 const analyticsEnabled =
   analyticsToken && !/REPLACE|PLACEHOLDER/i.test(analyticsToken);
+// Private-app widgets (D5) — global.footer slot. Resolved once here so it
+// renders for BOTH footer paths below (the tenant-owned chrome.html splice
+// and the generic <Footer>) instead of being owned by either. No dark-mode
+// preference infra exists yet — "light" is the only theme hint until it does.
+const footerWidgets = await renderWidgetSlot(
+  {
+    registry: await getRegistryService(),
+    tenantId: tenant.tenant_id,
+    customizationEnv: Astro.locals.customizationEnv,
+    slot: "global.footer",
+    route: path,
+    locale: tenant.locale,
+    theme: "light",
+  },
+  Astro.locals.activeWidgetPlacements,
+);
 ---
 <!doctype html>
@@ -130,27 +162,20 @@ const analyticsEnabled =
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <link rel="icon" type="image/svg+xml" href={theme.brand.favicon} />
-    {/* Per-tenant theme tokens injected at the edge (brief §7). */}
-    <style set:html={themeStyle} nonce={cspNonce}></style>
+    {/* Per-tenant theme tokens injected at the edge (brief §7). The id is the
+        dev-loop hot-patch target: tenant-hot-reload.mjs recomputes this same
+        `:root{...}` block on a theme.json save and the script below swaps its
+        textContent in place — no full reload. Inert in production (no listener
+        attaches there). */}
+    <style id="tot-theme-vars" set:html={themeStyle} nonce={cspNonce}></style>
     {/* Shared chrome's own stylesheet(s) — the tenant theme (/tenants/...) plus
         either the tenant's own mkt.css or the platform /shared/commerce-chrome.css
         — so the ported chrome renders in-brand on Layout (commerce) pages too. */}
     {sharedChrome?.css.map((href) => <link rel="stylesheet" href={href} />)}
-    {
-      fontHref && (
-        <>
-          <link rel="preconnect" href="https://fonts.googleapis.com" />
-          <link
-            rel="preconnect"
-            href="https://fonts.gstatic.com"
-            crossorigin
-          />
-          <link rel="stylesheet" href={fontHref} />
-        </>
-      )
-    }
+    {/* Web fonts are self-hosted (audit finding 6) via `@/styles/fonts.css`,
+        imported above — no third-party font stylesheet / preconnects. */}
     <Seo
       title={title}
@@ -230,6 +255,20 @@ const analyticsEnabled =
       </>
     )}
+    {/* Private-app widgets (D5, global.footer) — sandboxed per install; one
+        resolution above covers both footer paths. */}
+    {footerWidgets.map((w) => (
+      <div class="container-prose py-6">
+        <AppWidgetFrame
+          endpoint={w.endpoint}
+          launchToken={w.launchToken}
+          appOrigin={w.appOrigin}
+          installId={w.installId}
+          title={w.title ?? "App widget"}
+        />
+      </div>
+    ))}
     {capabilities.ageVerification.enabled && compliance?.minAge && (
       <IsolatedAgeGate client:load minAge={compliance.minAge} brand={tenant.displayName} />
     )}
@@ -342,6 +381,31 @@ const analyticsEnabled =
       </script>
     )}
+    {/* Dev-loop theme hot-patch (D1): tenant-hot-reload.mjs broadcasts a
+        `tot:theme-vars` HMR custom event on every theme.json save instead of
+        forcing a full reload; swap the CSS var block in place so edits repaint
+        instantly with no lost scroll position. import.meta.hot is undefined in
+        production builds, so this is a no-op there. */}
+    {import.meta.env.DEV && (
+      <script>
+        if (import.meta.hot) {
+          import.meta.hot.on("tot:theme-vars", (data: { css?: string }) => {
+            const el = document.getElementById("tot-theme-vars");
+            if (el && typeof data?.css === "string") el.textContent = data.css;
+          });
+        }
+      </script>
+    )}
+    {/* Private-app widget postMessage bridge (D5) — mounted unconditionally
+        (cheap no-op with zero tracked iframes); scans for
+        `[data-tot-widget-origin]` frames itself, so it doesn't need to know
+        which slots rendered above. */}
+    <script>
+      import { mountWidgetPostMessageBridge } from "@tot/public-runtime";
+      mountWidgetPostMessageBridge();
+    </script>
     {/* Scroll-reveal + analytics pageview hook. ~0.5KB, no framework. */}
     <script>
       // Reveal-on-scroll (respects reduced motion via CSS).
@@ -366,5 +430,15 @@ const analyticsEnabled =
         els.forEach((el) => el.classList.add("is-in"));
       }
     </script>
+    {/* Field Web Vitals (F14 RUM) — measures LCP/INP/CLS for real visitors and
+        beacons per-route samples to the RUM sink. ~1KB, no framework; no-ops
+        where PerformanceObserver is absent. This is the per-route-template
+        signal F16's `core-web-vitals` monitor consumes (the CF Web Analytics
+        beacon above only gives aggregate field CWV). */}
+    <script>
+      import { startWebVitals } from "@/lib/analytics/webVitals";
+      startWebVitals();
+    </script>
   </body>
 </html>

package/apps/storefront/src/lib/activity/alerts.ts ADDED Viewed

@@ -0,0 +1,428 @@
+/**
+ * Operational-activity ALERT conditions (card D7) — the detection layer on top of
+ * the D5 query surface.
+ *
+ * D1–D5 make operational activity queryable; D7 turns four specific, high-value
+ * conditions in that stream into ALERTS. It deliberately follows the SAME shape as
+ * this repo's only other alert contract, F14's `analytics/rumAlert.ts`: a set of
+ * PURE, transport-agnostic detectors that take a window of activity and return a
+ * structured `ActivityAlert[]`. WHERE the alerts go (a log line, a future
+ * PagerDuty/Slack sink, a polled endpoint) is the sink's job — there is NO outbound
+ * notification transport in this repo today (rumAlert is likewise detection-only),
+ * so D7 does not invent one. It also does NOT add a cron: the checker is on-demand
+ * (computed when `/admin/ops-timeline` loads, or when the read-only alerts endpoint
+ * is polled), exactly as the card scopes it.
+ *
+ * THE FOUR CONDITIONS (and how each avoids false-positive noise):
+ *
+ *   1. silent-terminal — a `reconcile.terminal` with status `failed` (errorClass
+ *      `reconcile_fault` = an unexpected crash → critical, or `reconcile_blocked` =
+ *      a safety gate refused the candidate → warning). A single failure is worth an
+ *      alert (a reviewer's PR silently didn't materialize), so there is no count
+ *      threshold; noise is bounded by (a) status = `failed` only, never `succeeded`,
+ *      and (b) collapsing repeat failures for one changeId into one alert.
+ *
+ *   2. recurring-preview-miss — a REPEATED `preview.serve`/`failed`/`miss_no_env`
+ *      for the SAME changeId. One miss is an expected race (a reviewer opened the
+ *      preview before its ReviewEnvironment finished materializing), so a single
+ *      miss NEVER alerts; only `threshold`+ misses (default 3) for one changeId
+ *      inside a short `window` (default 15m) do — that pattern means a LIVE PR whose
+ *      preview never came up, not a transient.
+ *
+ *   3. reconcile-hang — a `webhook.reconcile.received` for a changeId with NO
+ *      `reconcile.terminal` (any status) at-or-after it, once a `grace` period
+ *      (default 10m) has elapsed. This is an ABSENCE detector (architecturally
+ *      unlike 1/2, which fire on a bad event's PRESENCE): it correlates two action
+ *      types by changeId + time. Noise is bounded by the grace window — a reconcile
+ *      still legitimately in flight (received < grace ago) never fires; a terminal
+ *      after the received (any status) clears it.
+ *
+ *   4. deploy-skew — promotes D5's visibility-only `deriveDeploySkew()` into an
+ *      alert. `skewDetected` is true on EVERY normal rollout (two isolates coexist
+ *      briefly), so alerting on it directly would page on every deploy. Instead this
+ *      fires ONLY when the build serving this request differs from the newest
+ *      observed build AND that newest build has been latest for longer than a `grace`
+ *      period (default 15m) — i.e. THIS isolate failed to roll to a deploy that
+ *      finished long ago (a persistent stale isolate), not a rollout in progress.
+ *
+ * DATA DEPENDENCY (honest wiring status, mirroring F16's `WiringStatus`). The
+ * detectors read the D1 `activity_events` timeline through the D5 `queryActivity`
+ * seam, so they alert on whatever is in that timeline. Getting SERVER-emitted
+ * lifecycle events INTO D1 is the D1/D4 fan-out wiring (today `recordActivity()` is
+ * logs-only; `deployVersion.ts` notes the swap to a timeline-fanning emitter is
+ * pending) — NOT D7's job. `preview.serve` stays `analytics`-sink by design (too
+ * high-volume to timeline wholesale); detector 2 is source-agnostic (the rumAlert
+ * precedent) and fires against an Analytics-Engine-sourced or seeded feed. See
+ * `ALERT_CONDITIONS` for the per-condition source + wiring note.
+ */
+import {
+  queryActivity,
+  deriveDeploySkew,
+  type ActivityTimelineRow,
+  type DeploySkewSummary,
+} from "./query.js";
+import type { Queryable } from "../d1/catalog.js";
+/** Severity, mirroring F14's `rumAlert.AlertSeverity` / F16's `manifest.Severity`. */
+export type AlertSeverity = "page" | "critical" | "warning" | "info";
+/** The four D7 conditions. Stable ids — a downstream sink/dashboard keys on them. */
+export type ActivityAlertType =
+  | "silent-terminal"
+  | "recurring-preview-miss"
+  | "reconcile-hang"
+  | "deploy-skew";
+/** One active alert. `details` is low-cardinality + already-redacted-safe (it is
+ *  built only from CORE fields — action/status/errorClass/changeId/at/version —
+ *  never from the payload zone), so it is safe to log or serialize verbatim. */
+export interface ActivityAlert {
+  type: ActivityAlertType;
+  severity: AlertSeverity;
+  /** Stable human title for the condition. */
+  title: string;
+  /** One-line human summary for a banner / log line / notification body. */
+  summary: string;
+  /** The change this alert concerns, when it is change-scoped. */
+  changeId?: string;
+  /** Structured, low-cardinality specifics (safe to serialize). */
+  details: Record<string, string | number>;
+  /** ISO-8601 instant the condition has been active SINCE (earliest evidence). */
+  since: string;
+}
+// ─── Thresholds (the launch defaults; every one is overridable per call) ──────
+export const DEFAULTS = {
+  /** How far back the on-demand checker scans the timeline. */
+  lookbackMs: 24 * 60 * 60 * 1000,
+  /** recurring-preview-miss: misses of the SAME changeId before it alerts. */
+  previewMissThreshold: 3,
+  /** recurring-preview-miss: the window those misses must fall inside. */
+  previewMissWindowMs: 15 * 60 * 1000,
+  /** reconcile-hang: how long a `received` may sit un-terminated before alerting. */
+  reconcileHangGraceMs: 10 * 60 * 1000,
+  /** deploy-skew: how long the newest build must have been latest before a
+   *  still-stale serving isolate is a persistent (not rollout-transient) skew. */
+  deploySkewGraceMs: 15 * 60 * 1000,
+} as const;
+const SEVERITY_RANK: Record<AlertSeverity, number> = { page: 0, critical: 1, warning: 2, info: 3 };
+/** Deterministic ordering: most-severe first, then most-recently-active first. */
+export function sortAlerts(alerts: ActivityAlert[]): ActivityAlert[] {
+  return [...alerts].sort(
+    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || (a.since < b.since ? 1 : a.since > b.since ? -1 : 0),
+  );
+}
+// ─── Detector 1: silent-terminal ─────────────────────────────────────────────
+/**
+ * Alert on `reconcile.terminal`/`failed` rows. Pass ONLY failed terminals (the
+ * orchestrator queries `status: "failed"`). Repeat failures for one changeId
+ * collapse into a single alert carrying the count, so a flapping PR does not spam.
+ */
+export function detectSilentTerminals(failedTerminals: readonly ActivityTimelineRow[]): ActivityAlert[] {
+  const byChange = new Map<string, ActivityTimelineRow[]>();
+  for (const r of failedTerminals) {
+    if (r.status !== "failed") continue; // defensive: only failures
+    const key = r.changeId ?? r.id;
+    (byChange.get(key) ?? byChange.set(key, []).get(key)!).push(r);
+  }
+  const out: ActivityAlert[] = [];
+  for (const [key, group] of byChange) {
+    const sorted = [...group].sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+    const latest = sorted[sorted.length - 1]!;
+    const errorClass = latest.errorClass ?? "unknown";
+    // reconcile_fault = an UNEXPECTED crash of the reconcile → critical; a
+    // reconcile_blocked = a safety gate correctly refused the candidate, an
+    // operator should look but nothing crashed → warning.
+    const severity: AlertSeverity = errorClass === "reconcile_fault" ? "critical" : "warning";
+    out.push({
+      type: "silent-terminal",
+      severity,
+      title: "Reconcile terminated in failure",
+      summary:
+        `Candidate ${latest.changeId ?? key} reconcile ${errorClass}` +
+        (group.length > 1 ? ` (${group.length}× in window)` : "") +
+        ` — its preview did not materialize.`,
+      ...(latest.changeId ? { changeId: latest.changeId } : {}),
+      details: { errorClass, failures: group.length, lastAt: latest.at },
+      since: sorted[0]!.at,
+    });
+  }
+  return out;
+}
+// ─── Detector 2: recurring preview.serve miss_no_env ─────────────────────────
+export interface PreviewMissOptions {
+  /** "now" as epoch ms (injected for testing). */
+  now: number;
+  threshold?: number;
+  windowMs?: number;
+}
+/**
+ * Alert when the SAME changeId has `threshold`+ `preview.serve`/`failed`/
+ * `miss_no_env` events inside `windowMs`. Pass `preview.serve`/`failed` rows (the
+ * orchestrator queries them); this filters to `miss_no_env` and groups by changeId.
+ * A single miss (an expected pre-materialization race) is below threshold → silent.
+ */
+export function detectRecurringPreviewMisses(
+  serveFailures: readonly ActivityTimelineRow[],
+  opts: PreviewMissOptions,
+): ActivityAlert[] {
+  const threshold = opts.threshold ?? DEFAULTS.previewMissThreshold;
+  const windowMs = opts.windowMs ?? DEFAULTS.previewMissWindowMs;
+  const floor = opts.now - windowMs;
+  const byChange = new Map<string, ActivityTimelineRow[]>();
+  for (const r of serveFailures) {
+    if (r.errorClass !== "miss_no_env" || !r.changeId) continue;
+    const t = Date.parse(r.at);
+    if (Number.isNaN(t) || t < floor || t > opts.now) continue; // only misses inside the window
+    (byChange.get(r.changeId) ?? byChange.set(r.changeId, []).get(r.changeId)!).push(r);
+  }
+  const out: ActivityAlert[] = [];
+  for (const [changeId, misses] of byChange) {
+    if (misses.length < threshold) continue; // below threshold ⇒ transient, not an alert
+    const sorted = [...misses].sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+    out.push({
+      type: "recurring-preview-miss",
+      severity: "warning",
+      title: "Preview repeatedly missing for a live change",
+      summary:
+        `Change ${changeId} has ${misses.length} preview.serve misses (miss_no_env) in ` +
+        `${Math.round(windowMs / 60000)}m — reviewers are hitting a preview that never came up.`,
+      changeId,
+      details: { misses: misses.length, windowMinutes: Math.round(windowMs / 60000), lastAt: sorted[sorted.length - 1]!.at },
+      since: sorted[0]!.at,
+    });
+  }
+  return out;
+}
+// ─── Detector 3: reconcile-hang watchdog (ABSENCE correlation) ───────────────
+export interface ReconcileHangOptions {
+  /** "now" as epoch ms (injected for testing). */
+  now: number;
+  graceMs?: number;
+}
+/**
+ * Alert on a `webhook.reconcile.received` for a changeId that has NO
+ * `reconcile.terminal` at-or-after it, once `graceMs` has elapsed. Correlates the
+ * two action streams by changeId + time and reports the ABSENCE of a terminal.
+ *
+ * Per changeId we take the LATEST received (a PR pushed N times → only the newest
+ * cycle matters) and look for ANY terminal (succeeded/failed/blocked) with
+ * `at >= received.at`. None + past-grace ⇒ hang. A terminal after the received, OR
+ * a received still inside the grace window, clears it (the true-negative cases).
+ */
+export function detectReconcileHangs(
+  received: readonly ActivityTimelineRow[],
+  terminals: readonly ActivityTimelineRow[],
+  opts: ReconcileHangOptions,
+): ActivityAlert[] {
+  const graceMs = opts.graceMs ?? DEFAULTS.reconcileHangGraceMs;
+  // Latest `received` per changeId.
+  const latestReceived = new Map<string, ActivityTimelineRow>();
+  for (const r of received) {
+    if (!r.changeId) continue;
+    const prev = latestReceived.get(r.changeId);
+    if (!prev || r.at > prev.at) latestReceived.set(r.changeId, r);
+  }
+  // Latest terminal `at` per changeId (any status).
+  const latestTerminalAt = new Map<string, string>();
+  for (const t of terminals) {
+    if (!t.changeId) continue;
+    const prev = latestTerminalAt.get(t.changeId);
+    if (!prev || t.at > prev) latestTerminalAt.set(t.changeId, t.at);
+  }
+  const out: ActivityAlert[] = [];
+  for (const [changeId, r] of latestReceived) {
+    const terminalAt = latestTerminalAt.get(changeId);
+    if (terminalAt && terminalAt >= r.at) continue; // terminated after this receive ⇒ not hung
+    const receivedMs = Date.parse(r.at);
+    if (Number.isNaN(receivedMs)) continue;
+    const elapsedMs = opts.now - receivedMs;
+    if (elapsedMs <= graceMs) continue; // still legitimately in flight ⇒ no alert
+    out.push({
+      type: "reconcile-hang",
+      severity: "critical",
+      title: "Reconcile received but never terminated",
+      summary:
+        `Change ${changeId} got a reconcile webhook ${Math.round(elapsedMs / 60000)}m ago with no ` +
+        `terminal state — the review loop is stuck.`,
+      changeId,
+      details: { receivedAt: r.at, minutesElapsed: Math.round(elapsedMs / 60000), graceMinutes: Math.round(graceMs / 60000) },
+      since: r.at,
+    });
+  }
+  return out;
+}
+// ─── Detector 4: deploy-skew (persistent, not rollout-transient) ─────────────
+export interface DeploySkewAlertOptions {
+  /** "now" as epoch ms (injected for testing). */
+  now: number;
+  graceMs?: number;
+}
+/**
+ * Promote D5's visibility-only `DeploySkewSummary` into an alert, WITHOUT firing on
+ * every normal rollout. Fires only when the build serving this request differs from
+ * the newest observed build AND that newest build has been latest for longer than
+ * `graceMs` — i.e. THIS isolate never rolled to a deploy that finished long ago.
+ * A fresh rollout (newest observed < grace old) is the expected transient → silent.
+ */
+export function detectDeploySkew(skew: DeploySkewSummary, opts: DeploySkewAlertOptions): ActivityAlert[] {
+  const graceMs = opts.graceMs ?? DEFAULTS.deploySkewGraceMs;
+  const { runningVersion, latestObservedVersion } = skew;
+  // Need to know BOTH the serving build and the newest observed build to judge skew.
+  if (!runningVersion || !latestObservedVersion) return [];
+  if (runningVersion === latestObservedVersion) return []; // this isolate is current ⇒ fine
+  const latest = skew.observedVersions[0];
+  if (!latest) return [];
+  const latestAgeMs = opts.now - Date.parse(latest.lastObservedAt);
+  if (Number.isNaN(latestAgeMs) || latestAgeMs <= graceMs) return []; // rollout still in its grace window
+  return [
+    {
+      type: "deploy-skew",
+      severity: "warning",
+      title: "Stale build still serving after rollout",
+      summary:
+        `This isolate serves build ${runningVersion} but ${latestObservedVersion} has been the ` +
+        `latest for ${Math.round(latestAgeMs / 60000)}m — a stale isolate never rolled forward.`,
+      details: {
+        runningVersion,
+        latestObservedVersion,
+        minutesStale: Math.round(latestAgeMs / 60000),
+        graceMinutes: Math.round(graceMs / 60000),
+      },
+      since: latest.lastObservedAt,
+    },
+  ];
+}
+// ─── The on-demand orchestrator ──────────────────────────────────────────────
+export interface CheckAlertsOptions {
+  /** Injected clock (tests). Defaults to `new Date()`. */
+  now?: Date;
+  lookbackMs?: number;
+  previewMissThreshold?: number;
+  previewMissWindowMs?: number;
+  reconcileHangGraceMs?: number;
+  deploySkewGraceMs?: number;
+  /** Pin the serving build for deploy-skew (tests); real callers omit it. */
+  runningOverride?: string;
+}
+/**
+ * Run all four detectors for a tenant against the D1 timeline and return the active
+ * alerts, most-severe-first. Tenant-scoped through `queryActivity`/`deriveDeploySkew`
+ * (the same isolation invariant covers the whole check). On-demand: called when the
+ * ops-timeline page loads and by the read-only alerts endpoint — no cron.
+ */
+export async function checkActivityAlerts(
+  db: Queryable,
+  tenantId: string,
+  opts: CheckAlertsOptions = {},
+): Promise<ActivityAlert[]> {
+  const now = opts.now ?? new Date();
+  const nowMs = now.getTime();
+  const lookbackMs = opts.lookbackMs ?? DEFAULTS.lookbackMs;
+  const since = new Date(nowMs - lookbackMs).toISOString();
+  const [failedTerminals, allTerminals, received, serveFailures, skew] = await Promise.all([
+    queryActivity(db, { tenantId, action: "reconcile.terminal", status: "failed", since, order: "desc" }),
+    queryActivity(db, { tenantId, action: "reconcile.terminal", since, order: "desc" }),
+    queryActivity(db, { tenantId, action: "webhook.reconcile.received", since, order: "desc" }),
+    queryActivity(db, { tenantId, action: "preview.serve", status: "failed", since, order: "desc" }),
+    deriveDeploySkew(db, tenantId, { since, ...(opts.runningOverride ? { runningOverride: opts.runningOverride } : {}) }),
+  ]);
+  return sortAlerts([
+    ...detectSilentTerminals(failedTerminals),
+    ...detectRecurringPreviewMisses(serveFailures, {
+      now: nowMs,
+      ...(opts.previewMissThreshold != null ? { threshold: opts.previewMissThreshold } : {}),
+      ...(opts.previewMissWindowMs != null ? { windowMs: opts.previewMissWindowMs } : {}),
+    }),
+    ...detectReconcileHangs(received, allTerminals, {
+      now: nowMs,
+      ...(opts.reconcileHangGraceMs != null ? { graceMs: opts.reconcileHangGraceMs } : {}),
+    }),
+    ...detectDeploySkew(skew, {
+      now: nowMs,
+      ...(opts.deploySkewGraceMs != null ? { graceMs: opts.deploySkewGraceMs } : {}),
+    }),
+  ]);
+}
+/** One-line alert summary for a log line / notification body (rumAlert parity). */
+export function formatActivityAlert(a: ActivityAlert): string {
+  return `[${a.severity}] ${a.type}: ${a.summary} (since ${a.since})`;
+}
+// ─── Coherent surface descriptor (F16 `MONITORS` parity) ─────────────────────
+/** Honest per-condition source + wiring note — the audit trail for "is this
+ *  actually alerting?", mirroring F16's `WiringStatus`. */
+export interface AlertCondition {
+  type: ActivityAlertType;
+  title: string;
+  defaultSeverity: AlertSeverity;
+  threshold: string;
+  /** Which timeline signal(s) it reads. */
+  source: string;
+  /** Honest wiring status. */
+  wiring: "in-code" | "needs-timeline-fanout" | "needs-external";
+  notes?: string;
+}
+export const ALERT_CONDITIONS: readonly AlertCondition[] = [
+  {
+    type: "silent-terminal",
+    title: "Reconcile terminated in failure",
+    defaultSeverity: "critical",
+    threshold: "any reconcile.terminal/failed (reconcile_fault ⇒ critical, reconcile_blocked ⇒ warning)",
+    source: "reconcile.terminal (timeline sink)",
+    wiring: "needs-timeline-fanout",
+    notes: "Emitted by candidate-reconcile.ts via recordActivity() (logs-only today); reaches D1 once the D1/D4 server→timeline fan-out lands.",
+  },
+  {
+    type: "recurring-preview-miss",
+    title: "Preview repeatedly missing for a live change",
+    defaultSeverity: "warning",
+    threshold: "≥3 preview.serve/failed/miss_no_env for one changeId within 15m",
+    source: "preview.serve (analytics sink — high volume)",
+    wiring: "needs-external",
+    notes: "preview.serve stays analytics-sink by design; detector is source-agnostic (rumAlert precedent) and fires against an Analytics-Engine-sourced or seeded feed.",
+  },
+  {
+    type: "reconcile-hang",
+    title: "Reconcile received but never terminated",
+    defaultSeverity: "critical",
+    threshold: "webhook.reconcile.received with no reconcile.terminal at-or-after it, past a 10m grace",
+    source: "webhook.reconcile.received + reconcile.terminal (both timeline sink)",
+    wiring: "needs-timeline-fanout",
+    notes: "D7 promoted webhook.reconcile.received to the timeline sink and emits it at reconcile start; reaches D1 once server→timeline fan-out lands.",
+  },
+  {
+    type: "deploy-skew",
+    title: "Stale build still serving after rollout",
+    defaultSeverity: "warning",
+    threshold: "serving build ≠ newest observed AND newest has been latest > 15m",
+    source: "deploy.version_observed (timeline sink) + this build's __GIT_SHA__",
+    wiring: "needs-timeline-fanout",
+    notes: "Promotes D5's deriveDeploySkew from visibility to an alert; grace period suppresses normal-rollout noise.",
+  },
+] as const;