@openlup/platform 0.28.0 → 0.30.0

package/src/marketing/server/research/managedSurveyResponseSubmit.ts

@@ -0,0 +1,158 @@
+import type { ResearchSurveySubmitRequest, ResearchSurveySubmitResponse } from "@openlup/core/marketing/research";
+import type { PublicIntakeDeliveryPort, PublicIntakeDeliveryResult } from "../../../communications/contracts/index.js";
+
+type SurveyTable = "survey_responses_producer" | "survey_responses_consumer";
+
+export interface ManagedSurveyResponseGateway {
+  checkRateLimit(input: {
+    table: SurveyTable;
+    ip: string;
+    windowMinutes: number;
+    maxPerIp: number;
+    now: Date;
+  }): Promise<"allowed" | "limited" | "unavailable">;
+  insert(input: {
+    table: SurveyTable;
+    responseData: Record<string, unknown>;
+    ip: string | null;
+    userAgent: string | null;
+  }): Promise<{ id: string } | null>;
+  updateEmailStatus(input: {
+    table: SurveyTable;
+    id: string;
+    sentAt: string | null;
+    error: string | null;
+  }): Promise<void>;
+}
+
+export interface ManagedSurveyResponseSubmitDeps {
+  renderNotificationHtml: (surveyType: "producer" | "consumer", responseData: Record<string, unknown>, id: string) => string;
+  notificationSubject: (surveyType: "producer" | "consumer", now: Date) => string;
+  gateway: ManagedSurveyResponseGateway;
+  delivery: PublicIntakeDeliveryPort;
+  notifyTo: string[];
+  fromEmail: string;
+  windowMinutes: number;
+  maxPerIp: number;
+  now?: () => Date;
+}
+
+export function createManagedSurveyResponseSubmit(deps: ManagedSurveyResponseSubmitDeps) {
+  const now = deps.now ?? (() => new Date());
+  return async (request: ResearchSurveySubmitRequest, headers?: Headers): Promise<ResearchSurveySubmitResponse> => {
+    if (!validRequest(request)) return { ok: false, error: "invalid_response_data" };
+    const table = request.surveyType === "producer" ? "survey_responses_producer" : "survey_responses_consumer";
+    const ip = readIp(headers);
+    const rate = await deps.gateway.checkRateLimit({ table, ip: ip ?? "unknown", windowMinutes: deps.windowMinutes, maxPerIp: deps.maxPerIp, now: now() });
+    if (rate === "unavailable") return { ok: false, error: "survey_rate_limit_unavailable" };
+    if (rate === "limited") return { ok: false, error: "survey_rate_limited" };
+
+    let inserted: { id: string } | null;
+    try {
+      inserted = await deps.gateway.insert({
+        table,
+        responseData: request.responseData,
+        ip,
+        userAgent: headers?.get("user-agent") || null,
+      });
+    } catch {
+      inserted = null;
+    }
+    if (!inserted) return { ok: false, error: "db_insert_failed" };
+
+    if (deps.notifyTo.length === 0) {
+      await updateEmailStatus(deps.gateway, table, inserted.id, null, "notification_recipient_not_configured");
+      return { ok: true, id: inserted.id, email_skipped: "notification_recipient_not_configured" };
+    }
+
+    const templateSlug = `survey_${request.surveyType}_notification`;
+    const policies = await Promise.all(deps.notifyTo.map((recipient, index) => deps.delivery.evaluatePolicy({
+      email: recipient,
+      purpose: "admin_notification",
+      source: "submit-survey-response",
+      recipientKind: "admin_internal",
+      metadata: {
+        template_slug: templateSlug,
+        survey_type: request.surveyType,
+        survey_response_id: inserted.id,
+        recipient_count: deps.notifyTo.length,
+        recipient_index: index,
+      },
+    })));
+    const recipients = deps.notifyTo.map((recipient, index) => ({ recipient, index, policy: policies[index]! }));
+    const allowedRecipients = recipients.filter(({ policy }) => policy.allowed);
+    if (allowedRecipients.length === 0) {
+      const reason = policies[0]?.reason ?? "policy_blocked";
+      await updateEmailStatus(deps.gateway, table, inserted.id, null, reason);
+      return { ok: true, id: inserted.id, email_skipped: reason };
+    }
+
+    const rendered = deps.renderNotificationHtml(request.surveyType, request.responseData, inserted.id);
+    const subject = deps.notificationSubject(request.surveyType, now());
+    const attempts = await Promise.all(allowedRecipients.map(({ recipient, index, policy }) => sendAndRecord(deps, {
+      recipient, source: "submit-survey-response", templateSlug, policyDecisionId: policy.decisionId,
+      policyReason: policy.reason, id: inserted.id, index, subject, html: rendered,
+    })));
+    const notAccepted = attempts.find((attempt) => !attempt.accepted);
+    await updateEmailStatus(
+      deps.gateway,
+      table,
+      inserted.id,
+      notAccepted ? null : now().toISOString(),
+      notAccepted?.error ?? notAccepted?.skip ?? null,
+    );
+    return { ok: true, id: inserted.id };
+  };
+}
+
+function validRequest(request: ResearchSurveySubmitRequest): boolean {
+  return (request.surveyType === "producer" || request.surveyType === "consumer")
+    && Boolean(request.responseData && typeof request.responseData === "object" && !Array.isArray(request.responseData) && Object.keys(request.responseData).length > 0);
+}
+
+function readIp(headers: Headers | undefined): string | null {
+  return headers?.get("x-forwarded-for")?.split(",")[0]?.trim() || headers?.get("cf-connecting-ip") || null;
+}
+
+async function updateEmailStatus(
+  gateway: ManagedSurveyResponseGateway,
+  table: SurveyTable,
+  id: string,
+  sentAt: string | null,
+  error: string | null,
+): Promise<void> {
+  try {
+    await gateway.updateEmailStatus({ table, id, sentAt, error });
+  } catch {
+    // The survey row is durable; email metadata remains explicitly best effort.
+  }
+}
+
+async function sendAndRecord(deps: ManagedSurveyResponseSubmitDeps, input: {
+  recipient: string; source: string; templateSlug: string; policyDecisionId: string | null; policyReason: string;
+  id: string; index: number; subject: string; html: string;
+}): Promise<PublicIntakeDeliveryResult> {
+  try {
+    return await deps.delivery.deliver({
+      source: input.source,
+      templateSlug: input.templateSlug,
+      policyDecisionId: input.policyDecisionId,
+      dedupeKey: `${input.templateSlug}:${input.id}:${input.index}`,
+      purpose: "admin_notification",
+      triggerEvent: "survey_response_submitted",
+      recipientEmail: input.recipient,
+      aggregateType: "survey_response",
+      aggregateId: input.id,
+      metadata: { surveyResponseId: input.id, policyReason: input.policyReason },
+      message: {
+        sender: deps.fromEmail,
+        to: input.recipient,
+        subject: input.subject,
+        html: input.html,
+      },
+    });
+  } catch {
+    return { accepted: false, messageId: null, skip: null, error: "email_ledger_unavailable" };
+  }
+}
+

package/src/marketing/server/research/surveyResponseSubmitHandler.ts

@@ -0,0 +1,57 @@
+import type { HttpRequest, HttpResponse } from "../../../http/index.js";
+import type { BffResponder } from "../../../bff/index.js";
+import {
+  researchSurveySubmitRequestSchema,
+  researchSurveySubmitResponseSchema,
+} from "@openlup/core/marketing/research";
+import type { MarketingResearchSurveySubmitPort } from "@openlup/core/marketing/research";
+
+export interface ResearchSurveySubmitHandlerDeps {
+  respond: BffResponder;
+  submitPort: MarketingResearchSurveySubmitPort;
+}
+
+export function createResearchSurveySubmitHandler({
+  respond,
+  submitPort,
+}: ResearchSurveySubmitHandlerDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    const request = researchSurveySubmitRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid research survey response request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await submitPort.submitSurveyResponse(request.data, {
+        headers: headersFromRequest(req),
+      });
+      const response = researchSurveySubmitResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Research survey submit returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Research survey submit failed");
+    }
+  };
+}
+
+function headersFromRequest(req: HttpRequest): Headers {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (typeof value === "string") headers.set(key, value);
+    else if (Array.isArray(value)) headers.set(key, value.join(", "));
+  }
+  return headers;
+}

package/src/marketing/validation.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

package/src/migrations/postgresRunner.ts

@@ -34,6 +34,13 @@ export interface PlatformMigrationSource {
     migrations: readonly PlatformMigrationFile[];
     objectInventoryPayload?: string;
   }): string[];
+  /**
+   * Optional trusted-source observation/refusal after exact-prefix validation, under the
+   * migration session lock. Runs once per operation before any pending SQL or dry-run result.
+   * The canonical source uses read-only observations; the callback shares the caller's existing
+   * database capability and is not a sandbox or a provisioning/per-unit execution hook.
+   */
+  assertSession?(client: PoolClient, applied: readonly (PlatformMigrationManifestEntry & { position: number })[]): Promise<void>;
 }
 
 export interface PostgresMigrationRunnerOptions {
@@ -60,6 +67,9 @@ type LedgerExistenceRow = { ledger_exists: unknown };
 type AdvisoryUnlockRow = { unlocked: unknown };
 const ACQUIRE_MIGRATION_LOCK = "SELECT pg_advisory_lock(hashtextextended($1, 0))";
 const RELEASE_MIGRATION_LOCK = "SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS unlocked";
+const ACQUIRE_CATALOG_BOUND_MIGRATION_LOCK = "SELECT pg_catalog.pg_advisory_lock(pg_catalog.hashtextextended($1::pg_catalog.text, 0::pg_catalog.int8))";
+const RELEASE_CATALOG_BOUND_MIGRATION_LOCK = "SELECT pg_catalog.pg_advisory_unlock(pg_catalog.hashtextextended($1::pg_catalog.text, 0::pg_catalog.int8)) AS unlocked";
+const CATALOG_BOUND_LEDGER_EXISTENCE = "SELECT pg_catalog.to_regclass($1::pg_catalog.text) IS NOT NULL AS ledger_exists";
 
 export function createPostgresMigrationRunner(
   env: PostgresMigrationRunnerEnv,
@@ -79,8 +89,10 @@ export function createPostgresMigrationRunner(
     async status(): Promise<{ pending: string[]; applied: string[] }> {
       assertConnectionString(env);
       const plan = loadPlan(root, options.source);
-      return withMigrationSession(await getPool(), options.lockName, async (client) => {
-        const applied = await readAppliedPrefix(client, plan.units);
+      const catalogBoundSession = options.source.assertSession !== undefined;
+      return withMigrationSession(await getPool(), options.lockName, catalogBoundSession, async (client) => {
+        const applied = await readAppliedPrefix(client, plan.units, catalogBoundSession);
+        await options.source.assertSession?.(client, applied.map((unit) => ({ file: unit.catalogPath, sha256: unit.sha256, position: unit.position })));
         if (applied.length === plan.units.length) await assertObjectInventory(client, plan, options);
         return {
           pending: plan.units.slice(applied.length).map((unit) => unit.catalogPath),
@@ -92,8 +104,10 @@ export function createPostgresMigrationRunner(
     async apply(opts?: { dryRun?: boolean }): Promise<{ applied: string[] }> {
       assertConnectionString(env);
       const plan = loadPlan(root, options.source);
-      return withMigrationSession(await getPool(), options.lockName, async (client) => {
-        const already = await readAppliedPrefix(client, plan.units);
+      const catalogBoundSession = options.source.assertSession !== undefined;
+      return withMigrationSession(await getPool(), options.lockName, catalogBoundSession, async (client) => {
+        const already = await readAppliedPrefix(client, plan.units, catalogBoundSession);
+        await options.source.assertSession?.(client, already.map((unit) => ({ file: unit.catalogPath, sha256: unit.sha256, position: unit.position })));
         const pending = plan.units.slice(already.length);
         if (opts?.dryRun) {
           if (pending.length === 0) await assertObjectInventory(client, plan, options);
@@ -115,7 +129,7 @@ export function createPostgresMigrationRunner(
             throw new Error(`platform migration ${unit.catalogPath} failed: ${errorMessage(error)}`);
           }
         }
-        const complete = await readAppliedPrefix(client, plan.units);
+        const complete = await readAppliedPrefix(client, plan.units, catalogBoundSession);
         if (complete.length !== plan.units.length) throw new Error("platform migration ledger is incomplete after apply");
         await assertObjectInventory(client, plan, options);
         return { applied: appliedNow };
@@ -127,6 +141,7 @@ export function createPostgresMigrationRunner(
 async function withMigrationSession<T>(
   pool: Pool,
   lockName: string,
+  catalogBoundSession: boolean,
   operation: (client: PoolClient) => Promise<T>,
 ): Promise<T> {
   const client = await pool.connect();
@@ -135,7 +150,7 @@ async function withMigrationSession<T>(
   let operationFailure: unknown;
   let result!: T;
   try {
-    await client.query(ACQUIRE_MIGRATION_LOCK, [lockName]);
+    await client.query(catalogBoundSession ? ACQUIRE_CATALOG_BOUND_MIGRATION_LOCK : ACQUIRE_MIGRATION_LOCK, [lockName]);
     locked = true;
     result = await operation(client);
   } catch (error) {
@@ -146,7 +161,7 @@ async function withMigrationSession<T>(
   let unlockFailure: unknown;
   if (locked) {
     try {
-      const unlocked = await client.query<AdvisoryUnlockRow>(RELEASE_MIGRATION_LOCK, [lockName]);
+      const unlocked = await client.query<AdvisoryUnlockRow>(catalogBoundSession ? RELEASE_CATALOG_BOUND_MIGRATION_LOCK : RELEASE_MIGRATION_LOCK, [lockName]);
       if (unlocked.rows[0]?.unlocked !== true) throw new Error("PostgreSQL did not release the advisory lock");
     } catch (error) {
       unlockFailure = error;
@@ -194,9 +209,9 @@ function loadPlan(root: string, source: PlatformMigrationSource): LoadedPlan {
   return Object.freeze({ manifest, migrations: catalog.migrations, units: Object.freeze(units) });
 }
 
-async function readAppliedPrefix(client: PoolClient, units: readonly PlannedMigration[]): Promise<readonly PlannedMigration[]> {
+async function readAppliedPrefix(client: PoolClient, units: readonly PlannedMigration[], catalogBoundSession: boolean): Promise<readonly PlannedMigration[]> {
   const exists = await client.query<LedgerExistenceRow>(
-    "SELECT to_regclass($1) IS NOT NULL AS ledger_exists",
+    catalogBoundSession ? CATALOG_BOUND_LEDGER_EXISTENCE : "SELECT to_regclass($1) IS NOT NULL AS ledger_exists",
     [LEDGER],
   );
   if (exists.rows[0]?.ledger_exists !== true) return [];

package/src/operations/adminAlertsSchemas.ts

@@ -0,0 +1,78 @@
+import { z } from "./validation.js";
+
+/**
+ * Admin-facing projection of the platform alert ledger.
+ *
+ * Only what an operator needs to read; the ledger itself stays service-role only
+ * (platform_alerts REVOKEs ALL from `authenticated`), so this shape is served by
+ * /api/bff/admin/platform/alerts rather than by PostgREST.
+ */
+
+export const adminAlertSeveritySchema = z.enum(["p0", "p1", "p2", "p3"]);
+
+/**
+ * Audience split, derived from `platform_alerts.owner`:
+ *   commerce -> a business operator can act on it
+ *   platform -> engineering owns it; shown for context so the health pill is explainable
+ */
+export const adminAlertLaneSchema = z.enum(["commerce", "platform"]);
+
+export const adminAlertHealthSchema = z.enum(["ok", "degraded", "down", "unknown"]);
+
+const isoDateTimeSchema = z.string().datetime({ offset: true });
+
+export const adminAlertSchema = z
+  .object({
+    id: z.string().min(1).max(128),
+    dedupeKey: z.string().min(1).max(256),
+    lane: adminAlertLaneSchema,
+    // Free text on purpose: platform_alerts.owner has no CHECK constraint, so an
+    // enum here would throw the whole admin shell on the first new owner string.
+    // The open-endedness is absorbed by `lane`.
+    owner: z.string().trim().min(1).max(128),
+    severity: adminAlertSeveritySchema,
+    status: z.enum(["open", "acknowledged"]),
+    // Server-decided so every consumer agrees; the client never re-derives it.
+    pageable: z.boolean(),
+    title: z.string().trim().min(1).max(512),
+    message: z.string().trim().max(4096),
+    supportCode: z.string().trim().max(128).nullable(),
+    runbookUrl: z.string().trim().max(1024).nullable(),
+    firstSeenAt: isoDateTimeSchema,
+    lastSeenAt: isoDateTimeSchema,
+    snoozedUntil: isoDateTimeSchema.nullable(),
+  })
+  .strict();
+
+export const adminAlertsHeartbeatSchema = z
+  .object({
+    lastSuccessAt: isoDateTimeSchema.nullable(),
+    staleAfterSeconds: z.number().int().positive(),
+    stale: z.boolean(),
+  })
+  .strict();
+
+export const adminAlertsSummarySchema = z
+  .object({
+    /** Drives the bell badge. */
+    commercePageableCount: z.number().int().min(0),
+    commerceTotalCount: z.number().int().min(0),
+    platformPageableCount: z.number().int().min(0),
+    /** Visible controlled exceptions; excluded from paging and health degradation. */
+    snoozedCount: z.number().int().min(0),
+    maxOpenSeverity: adminAlertSeveritySchema.nullable(),
+  })
+  .strict();
+
+export const adminAlertsOverviewResponseSchema = z
+  .object({
+    health: adminAlertHealthSchema,
+    summary: adminAlertsSummarySchema,
+    heartbeat: adminAlertsHeartbeatSchema,
+    alerts: z.array(adminAlertSchema).max(50),
+    // Snoozed rows are returned separately from the active-list cap so a
+    // controlled exception never disappears behind routine diagnostics.
+    snoozedAlerts: z.array(adminAlertSchema).max(200),
+    generatedAt: isoDateTimeSchema,
+  })
+  .strict();

package/src/operations/adminAlertsView.ts

@@ -0,0 +1,238 @@
+import type {
+  AdminAlert,
+  AdminAlertHealth,
+  AdminAlertLane,
+  AdminAlertSeverity,
+  AdminAlertsHeartbeat,
+  AdminAlertsOverviewResponse,
+  AdminAlertsSummary,
+} from "./contracts/adminAlertsContracts.js";
+import { DEFAULT_PAGING_MIN_SEVERITY, shouldPage } from "./alertPagingPolicy.js";
+
+/**
+ * Pure projection of platform_alerts rows onto the admin shell's badges.
+ *
+ * All filtering lives here rather than in SQL so the `now` boundary is injectable
+ * and every rule is unit-testable without a database.
+ */
+
+/** Raw ledger row as selected from public.platform_alerts. */
+export type PlatformAlertLedgerRow = {
+  id: string;
+  dedupe_key: string;
+  owner: string;
+  severity: string;
+  status: string;
+  title: string;
+  message: string | null;
+  support_code: string | null;
+  runbook_url: string | null;
+  first_seen_at: string;
+  last_seen_at: string;
+  snoozed_until: string | null;
+};
+
+export type WatchdogHeartbeatRow = {
+  last_success_at: string | null;
+} | null;
+
+/**
+ * Generic scheduled-job alerts inherit `owner` from the job catalog entry, so a
+ * commerce-owned job leaks engineer-only noise ("this cron failed") into what
+ * should be an operator's queue. They still count toward platform health.
+ */
+export const GENERIC_JOB_DEDUPE_PREFIXES = [
+  "job_failed:",
+  "job_missed:",
+  "job_never_succeeded:",
+  "job_stuck_running:",
+  "job_ledger_missing:",
+] as const;
+
+/**
+ * How old a watchdog heartbeat may be before the health pill stops trusting it.
+ *
+ * The development-preview reference uses a conservative six-hour stale window
+ * independent from any scheduler cadence. It is a policy default, not a
+ * scheduling SLA; adopters must review it against their expected maximum
+ * heartbeat delay and queue jitter.
+ */
+export const WATCHDOG_STALE_AFTER_SECONDS = 6 * 60 * 60;
+
+const SEVERITY_RANK: Record<AdminAlertSeverity, number> = { p0: 0, p1: 1, p2: 2, p3: 3 };
+
+/**
+ * Derived from the paging policy's DEFAULT floor, not from the live threshold:
+ * this is a pure projection with no access to PLATFORM_ALERT_PAGING_MIN_SEVERITY,
+ * so an operator who overrides that variable makes panel and pager disagree
+ * again. Threading the parsed floor through the admin BFF is wave-3 work.
+ */
+function isPageableSeverity(severity: AdminAlertSeverity): boolean {
+  return shouldPage(severity, DEFAULT_PAGING_MIN_SEVERITY);
+}
+
+export function isGenericJobAlert(dedupeKey: string): boolean {
+  return GENERIC_JOB_DEDUPE_PREFIXES.some((prefix) => dedupeKey.startsWith(prefix));
+}
+
+/**
+ * Display bucket. `commerce` means "a business operator can act on this".
+ *
+ * `commerce/platform` is deliberately excluded: despite the prefix it owns
+ * engineering-run plumbing (outbox-dispatch, outbox-prune, abandoned-cart,
+ * review-request, reorder-reminder).
+ */
+export function classifyLane(owner: string, dedupeKey: string): AdminAlertLane {
+  if (isGenericJobAlert(dedupeKey)) return "platform";
+  if (!owner.startsWith("commerce/")) return "platform";
+  if (owner === "commerce/platform") return "platform";
+  return "commerce";
+}
+
+export function isSnoozed(snoozedUntil: string | null, now: Date): boolean {
+  if (!snoozedUntil) return false;
+  const until = Date.parse(snoozedUntil);
+  return Number.isFinite(until) && until > now.getTime();
+}
+
+/**
+ * Unknown severities are treated as p0 — mirrors alertPagingPolicy's fail-safe,
+ * where an unrecognised severity always pages rather than silently disappearing.
+ */
+function normalizeSeverity(severity: string): AdminAlertSeverity {
+  return severity in SEVERITY_RANK ? (severity as AdminAlertSeverity) : "p0";
+}
+
+function normalizeIso(value: string): string {
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : value;
+}
+
+/** Unresolved ledger state, including a controlled snoozed exception. */
+function isOpen(row: PlatformAlertLedgerRow): boolean {
+  if (row.status !== "open" && row.status !== "acknowledged") return false;
+  return true;
+}
+
+/** Live enough to affect the health badge and paging. */
+function isLive(row: PlatformAlertLedgerRow, now: Date): boolean {
+  return isOpen(row) && !isSnoozed(row.snoozed_until, now);
+}
+
+/**
+ * Pageable means "this would wake someone up": live and above the paging floor.
+ * Acknowledged rows stay pageable on purpose — acknowledged is not resolved, the
+ * system is still broken.
+ */
+export function isPageable(row: PlatformAlertLedgerRow, now: Date): boolean {
+  return isLive(row, now) && isPageableSeverity(normalizeSeverity(row.severity));
+}
+
+export function toAdminAlert(row: PlatformAlertLedgerRow, now: Date): AdminAlert {
+  return {
+    id: row.id,
+    dedupeKey: row.dedupe_key,
+    lane: classifyLane(row.owner, row.dedupe_key),
+    owner: row.owner,
+    severity: normalizeSeverity(row.severity),
+    status: row.status === "acknowledged" ? "acknowledged" : "open",
+    pageable: isPageable(row, now),
+    title: row.title,
+    message: row.message ?? "",
+    supportCode: row.support_code,
+    runbookUrl: row.runbook_url,
+    firstSeenAt: normalizeIso(row.first_seen_at),
+    lastSeenAt: normalizeIso(row.last_seen_at),
+    snoozedUntil: row.snoozed_until ? normalizeIso(row.snoozed_until) : null,
+  };
+}
+
+export function worstSeverity(alerts: readonly AdminAlert[]): AdminAlertSeverity | null {
+  let worst: AdminAlertSeverity | null = null;
+  for (const alert of alerts) {
+    if (!worst || SEVERITY_RANK[alert.severity] < SEVERITY_RANK[worst]) worst = alert.severity;
+  }
+  return worst;
+}
+
+/**
+ * `commercePageableCount` and `platformPageableCount` partition the pageable set,
+ * so no alert that would page is ever invisible in the popover.
+ */
+export function summarizeAlerts(alerts: readonly AdminAlert[]): AdminAlertsSummary {
+  const pageable = alerts.filter((alert) => alert.pageable);
+  return {
+    commercePageableCount: pageable.filter((alert) => alert.lane === "commerce").length,
+    commerceTotalCount: alerts.filter((alert) => alert.lane === "commerce").length,
+    platformPageableCount: pageable.filter((alert) => alert.lane === "platform").length,
+    snoozedCount: 0,
+    maxOpenSeverity: worstSeverity(alerts),
+  };
+}
+
+export function buildHeartbeat(row: WatchdogHeartbeatRow, now: Date): AdminAlertsHeartbeat {
+  const lastSuccessAt = row?.last_success_at ?? null;
+  const parsed = lastSuccessAt ? Date.parse(lastSuccessAt) : Number.NaN;
+  const stale =
+    !Number.isFinite(parsed) || now.getTime() - parsed > WATCHDOG_STALE_AFTER_SECONDS * 1000;
+  return {
+    lastSuccessAt: Number.isFinite(parsed) ? new Date(parsed).toISOString() : null,
+    staleAfterSeconds: WATCHDOG_STALE_AFTER_SECONDS,
+    stale,
+  };
+}
+
+/**
+ * Staleness beats severity: if the watchdog has not reported recently we do not
+ * know the current state, and "unknown" is the only honest answer. There is no
+ * path here that renders a green "systems ok" from missing data.
+ */
+export function deriveHealth(
+  summary: AdminAlertsSummary,
+  heartbeat: AdminAlertsHeartbeat,
+): AdminAlertHealth {
+  if (heartbeat.stale) return "unknown";
+  if (summary.maxOpenSeverity === "p0") return "down";
+  if (summary.maxOpenSeverity === "p1") return "degraded";
+  return "ok";
+}
+
+/** Alerts returned to the client; counts above stay accurate even when this is truncated. */
+export const ADMIN_ALERTS_LIST_LIMIT = 50;
+
+function compareForDisplay(a: AdminAlert, b: AdminAlert): number {
+  const bySeverity = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+  if (bySeverity !== 0) return bySeverity;
+  return Date.parse(b.lastSeenAt) - Date.parse(a.lastSeenAt);
+}
+
+export function buildAlertsOverview(
+  rows: readonly PlatformAlertLedgerRow[],
+  heartbeatRow: WatchdogHeartbeatRow,
+  now: Date,
+): AdminAlertsOverviewResponse {
+  const openRows = rows.filter(isOpen);
+  const alerts = openRows
+    .filter((row) => isLive(row, now))
+    .map((row) => toAdminAlert(row, now))
+    .sort(compareForDisplay);
+  const snoozedAlerts = openRows
+    .filter((row) => isSnoozed(row.snoozed_until, now))
+    .map((row) => toAdminAlert(row, now))
+    .sort(compareForDisplay);
+  const summary = {
+    ...summarizeAlerts(alerts),
+    snoozedCount: snoozedAlerts.length,
+  };
+  const heartbeat = buildHeartbeat(heartbeatRow, now);
+  return {
+    health: deriveHealth(summary, heartbeat),
+    summary,
+    heartbeat,
+    alerts: alerts.slice(0, ADMIN_ALERTS_LIST_LIMIT),
+    // Deliberately separate from the active list's limit: controlled exceptions
+    // are relevant audit context, but must not turn the health pill red.
+    snoozedAlerts,
+    generatedAt: now.toISOString(),
+  };
+}

package/src/operations/alertPagingPolicy.ts

@@ -0,0 +1,50 @@
+import type { AlertSeverity } from "./contracts/observabilityContracts.js";
+const ALERT_SEVERITIES: readonly AlertSeverity[] = ["p0", "p1", "p2", "p3"];
+
+/**
+ * Paging policy for platform watchdog alerts.
+ *
+ * The alert ledger records every severity, but only sufficiently severe alerts
+ * should page an on-call channel (e.g. ntfy). Lower-severity alerts stay
+ * ledger-only so real incidents are not buried under routine noise.
+ *
+ * The tiering is settled: **p0 pages** (customers cannot buy, renewals cannot
+ * charge, the platform or database is down); **p1 is panel-urgent** and turns
+ * the admin health pill `degraded` without waking anyone; **p2/p3** are the
+ * panel list and the ledger. An unknown severity still pages: the fail-open
+ * rule is unchanged, because silence must never be the result of a
+ * classification error.
+ *
+ * Lower rank == more severe.
+ */
+const SEVERITY_RANK: Record<AlertSeverity, number> = { p0: 0, p1: 1, p2: 2, p3: 3 };
+
+/** Alerts at or above this severity page by default; below it are ledger-only. */
+export const DEFAULT_PAGING_MIN_SEVERITY: AlertSeverity = "p0";
+
+/**
+ * Whether an alert of `severity` should page given the `minSeverity` threshold.
+ *
+ * Fail-safe: an unknown/unparseable severity always pages (treated as most
+ * urgent). Silence must never be the result of a classification error.
+ */
+export function shouldPage(
+  severity: string,
+  minSeverity: AlertSeverity = DEFAULT_PAGING_MIN_SEVERITY,
+): boolean {
+  const rank = SEVERITY_RANK[severity as AlertSeverity];
+  if (rank === undefined) return true;
+  return rank <= SEVERITY_RANK[minSeverity];
+}
+
+/**
+ * Parse a paging threshold from configuration (e.g. an env var), falling back to
+ * {@link DEFAULT_PAGING_MIN_SEVERITY} for any missing or invalid value.
+ */
+export function parsePagingMinSeverity(value: string | null | undefined): AlertSeverity {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized && (ALERT_SEVERITIES as readonly string[]).includes(normalized)) {
+    return normalized as AlertSeverity;
+  }
+  return DEFAULT_PAGING_MIN_SEVERITY;
+}