@openlup/platform 0.29.0 → 0.30.0

package/src/operations/server/adminAlertsHandlers.ts

@@ -0,0 +1,61 @@
+import { createBffResponder, type BffResponderOptions } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import { adminAlertsOverviewResponseSchema } from "../index.js";
+import { buildAlertsOverview } from "../index.js";
+import type {
+  PlatformAlertLedgerRow,
+  WatchdogHeartbeatRow,
+} from "../index.js";
+import type { OperationsAuthorizationResult } from "../contracts/index.js";
+type AuthorizeAdmin = () => Promise<OperationsAuthorizationResult>;
+
+export interface AdminAlertsReadPort {
+  listLiveAlerts(): Promise<PlatformAlertLedgerRow[]>;
+  readWatchdogHeartbeat(): Promise<WatchdogHeartbeatRow>;
+}
+
+export interface AdminAlertsOverviewDeps extends BffResponderOptions {
+  readPort: AdminAlertsReadPort;
+  authorizeAdmin: AuthorizeAdmin;
+  now?: () => Date;
+}
+
+export function createAdminAlertsOverviewHandler({
+  readPort,
+  authorizeAdmin,
+  now = () => new Date(), responseRequestId,
+}: AdminAlertsOverviewDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    const authorization = await authorizeAdmin();
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    try {
+      // Heartbeat and alerts are read together: an empty alert list is only
+      // "healthy" if the watchdog actually reported recently.
+      const [alerts, heartbeat] = await Promise.all([
+        readPort.listLiveAlerts(),
+        readPort.readWatchdogHeartbeat(),
+      ]);
+
+      const overview = buildAlertsOverview(alerts, heartbeat, now());
+      const response = adminAlertsOverviewResponseSchema.safeParse(overview);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin alerts overview returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin alerts overview failed");
+    }
+  };
+}

package/src/operations/server/adminPipelineHandlers.ts

@@ -0,0 +1,73 @@
+import { createBffResponder, type BffResponderOptions, type BffResponder } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import {
+  adminPipelineReadRequestSchema,
+  adminPipelineReadResponseSchema,
+} from "../index.js";
+import type { AdminPipelineReadPort } from "../contracts/index.js";
+import type { OperationsAuthorizationResult } from "../contracts/index.js";
+
+interface AdminPipelineBaseDeps extends BffResponderOptions {
+  authorizeAdmin: (req: HttpRequest) => Promise<OperationsAuthorizationResult>;
+}
+
+export interface AdminPipelineReadDeps extends AdminPipelineBaseDeps {
+  pipelinePort: Pick<AdminPipelineReadPort, "readPipeline">;
+}
+
+export function createAdminPipelineReadHandler({
+  pipelinePort,
+  authorizeAdmin, responseRequestId,
+}: AdminPipelineReadDeps) {
+  const responder = createBffResponder({ responseRequestId });
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    const authorization = await readAuthorization(req, res, authorizeAdmin, responder);
+    if (!authorization) return;
+
+    const request = adminPipelineReadRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin pipeline read request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await pipelinePort.readPipeline(request.data);
+      const response = adminPipelineReadResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin pipeline read returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin pipeline read failed");
+    }
+  };
+}
+
+async function readAuthorization(
+  req: HttpRequest,
+  res: HttpResponse,
+  authorizeAdmin: (req: HttpRequest) => Promise<OperationsAuthorizationResult>,
+  { sendBffError }: BffResponder,
+): Promise<true | null> {
+  try {
+    const authorization = await authorizeAdmin(req);
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return null;
+    }
+    return true;
+  } catch {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+    return null;
+  }
+}

package/src/operations/server/adminSettingsHandlers.ts

@@ -0,0 +1,114 @@
+import { createBffResponder, type BffResponderOptions } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import {
+  adminSettingsReadRequestSchema,
+  adminSettingsReadResponseSchema,
+  adminSettingsUpdateRequestSchema,
+  adminSettingsUpdateResponseSchema,
+} from "../index.js";
+import type { AdminSettingsOperationsPort } from "../contracts/index.js";
+import type { OperationsAuthorizationResult } from "../contracts/index.js";
+
+export interface AdminSettingsReadDeps extends BffResponderOptions {
+  settingsPort: Pick<AdminSettingsOperationsPort, "readSettings">;
+  authorizeAdmin: (req: HttpRequest) => Promise<OperationsAuthorizationResult>;
+}
+
+export interface AdminSettingsUpdateDeps extends BffResponderOptions {
+  settingsPort: Pick<AdminSettingsOperationsPort, "updateSetting">;
+  authorizeAdmin: (req: HttpRequest) => Promise<OperationsAuthorizationResult>;
+}
+
+export function createAdminSettingsReadHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminSettingsReadDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    let authorization: OperationsAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminSettingsReadRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin settings read request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.readSettings(request.data);
+      const response = adminSettingsReadResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin settings read returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin settings read failed");
+    }
+  };
+}
+
+export function createAdminSettingsUpdateHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminSettingsUpdateDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    let authorization: OperationsAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminSettingsUpdateRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin settings update request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.updateSetting(request.data);
+      const response = adminSettingsUpdateResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin settings update returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin settings update failed");
+    }
+  };
+}

package/src/operations/server/controlPlaneHandler.ts

@@ -0,0 +1,56 @@
+import { createBffResponder, type BffResponderOptions, type BffResponder } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import { platformControlPlaneMutationResponseSchema, platformControlPlaneMutationSchema, platformControlPlaneReadResponseSchema } from "../index.js";
+import { PlatformControlPlaneConflictError } from "../index.js";
+import type { PlatformControlPlanePort } from "../contracts/index.js";
+
+export function createPlatformControlPlaneHandler(deps: {
+  port: PlatformControlPlanePort;
+  authorizeAdmin: () => Promise<boolean>;
+} & BffResponderOptions) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder(deps);
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (!(await deps.authorizeAdmin())) {
+      sendBffError(res, "UNAUTHORIZED", "Admin session required");
+      return;
+    }
+    try {
+      if (req.method === "GET") {
+        const parsed = platformControlPlaneReadResponseSchema.safeParse(
+          await deps.port.readControlPlane({}),
+        );
+        if (!parsed.success) return invalidResponse(res, sendBffError);
+        sendBffSuccess(res, parsed.data);
+        return;
+      }
+      if (req.method === "POST") {
+        const parsed = platformControlPlaneMutationSchema.safeParse(body(req.body));
+        if (!parsed.success) {
+          sendBffError(res, "BAD_REQUEST", "Invalid platform control-plane request");
+          return;
+        }
+        const response = platformControlPlaneMutationResponseSchema.safeParse(
+          await deps.port.mutateControlPlane(parsed.data),
+        );
+        if (!response.success) return invalidResponse(res, sendBffError);
+        sendBffSuccess(res, response.data);
+        return;
+      }
+      sendMethodNotAllowed(res, ["GET", "POST"]);
+    } catch (error) {
+      if (error instanceof PlatformControlPlaneConflictError) {
+        sendBffError(res, "CONFLICT", error.message);
+        return;
+      }
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Platform control plane unavailable");
+    }
+  };
+}
+
+function body(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try { return JSON.parse(value); } catch { return null; }
+}
+function invalidResponse(res: HttpResponse, sendBffError: BffResponder["sendBffError"]): void {
+  sendBffError(res, "INVALID_RESPONSE", "Platform control plane returned invalid response");
+}

package/src/operations/server/controlPlaneStore.ts

@@ -0,0 +1,150 @@
+import { PlatformControlPlaneConflictError, PlatformControlPlaneUnavailableError } from "../index.js";
+import { createHash } from "node:crypto";
+
+import type {
+  PlatformControlPlaneMutation,
+  PlatformControlPlaneMutationResponse,
+  PlatformControlPlaneReadResponse,
+} from "../contracts/index.js";
+import {
+  type PlatformControlPlanePort,
+} from "../contracts/index.js";
+import type { PgQueryExecutor } from "../../data/index.js";
+
+const rpc = (name: string, types: string[]) =>
+  `SELECT * FROM public.${name}(${types.map((type, index) => `$${index + 1}::${type}`).join(", ")})`;
+
+export const platformControlPlaneSql = {
+  active: rpc("platform_control_operator_is_active", ["uuid"]),
+  setControl: rpc("platform_control_set_control", ["uuid", "text", "text", "text", "boolean"]),
+  heartbeat: rpc("platform_control_record_heartbeat", ["uuid", "text", "text", "text", "integer", "text", "boolean"]),
+  controls: rpc("platform_control_list_controls", ["uuid"]),
+  jobs: rpc("platform_control_list_jobs", ["uuid"]),
+  alerts: rpc("platform_control_list_alerts", ["uuid"]),
+} as const;
+
+export function createPlatformControlPlanePort(
+  client: PgQueryExecutor,
+  operatorId: string,
+): PlatformControlPlanePort {
+  return {
+    async readControlPlane() {
+      try {
+        const [controls, jobs, alerts] = await Promise.all([
+          client.query(platformControlPlaneSql.controls, [operatorId]),
+          client.query(platformControlPlaneSql.jobs, [operatorId]),
+          client.query(platformControlPlaneSql.alerts, [operatorId]),
+        ]);
+        return {
+          controls: controls.rows.map((row) => ({
+            controlKey: text(row.control_key), enabled: bool(row.enabled),
+            revision: positive(row.revision), updatedAt: timestamp(row.updated_at),
+          })),
+          jobs: jobs.rows.map((row) => ({
+            jobName: text(row.job_name), enabled: bool(row.enabled),
+            activeDriver: driver(row.active_driver), lastStatus: jobStatus(row.last_status),
+            lastStartedAt: nullableTimestamp(row.last_started_at),
+            lastFinishedAt: nullableTimestamp(row.last_finished_at),
+            lastSuccessAt: nullableTimestamp(row.last_success_at),
+          })),
+          alerts: alerts.rows.map((row) => ({
+            dedupeKey: text(row.dedupe_key), severity: severity(row.severity),
+            status: alertStatus(row.status), owner: text(row.owner), title: text(row.title),
+            firstSeenAt: timestamp(row.first_seen_at), lastSeenAt: timestamp(row.last_seen_at),
+            resolvedAt: nullableTimestamp(row.resolved_at),
+          })),
+        } satisfies PlatformControlPlaneReadResponse;
+      } catch (error) {
+        throw mapError(error);
+      }
+    },
+
+    async mutateControlPlane(request) {
+      try {
+        const fingerprint = digest(JSON.stringify(request));
+        const result = request.action === "set-control"
+          ? await client.query(platformControlPlaneSql.setControl, [
+              operatorId, request.idempotencyKey, fingerprint, request.controlKey, request.enabled,
+            ])
+          : await client.query(platformControlPlaneSql.heartbeat, [
+              operatorId, request.idempotencyKey, fingerprint, request.health,
+              request.firingCount, request.maxSeverity, request.promotionReady,
+            ]);
+        return mutation(first(result.rows), request.action);
+      } catch (error) {
+        throw mapError(error);
+      }
+    },
+  };
+}
+
+export async function isPlatformControlOperatorActive(
+  client: PgQueryExecutor,
+  principalId: string,
+): Promise<boolean> {
+  try {
+    return first((await client.query(platformControlPlaneSql.active, [principalId])).rows)
+      ?.platform_control_operator_is_active === true;
+  } catch (error) {
+    throw mapError(error);
+  }
+}
+
+function mutation(
+  row: Record<string, unknown> | undefined,
+  expected: PlatformControlPlaneMutation["action"],
+): PlatformControlPlaneMutationResponse {
+  if (!row || row.action !== expected) throw new PlatformControlPlaneUnavailableError();
+  return {
+    action: expected,
+    replayed: bool(row.replayed),
+    revision: row.revision == null ? null : positive(row.revision),
+    recordedAt: timestamp(row.recorded_at),
+  };
+}
+
+function digest(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+function first(rows: Record<string, unknown>[]): Record<string, unknown> | undefined { return rows[0]; }
+function text(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0) throw new PlatformControlPlaneUnavailableError();
+  return value;
+}
+function bool(value: unknown): boolean {
+  if (typeof value !== "boolean") throw new PlatformControlPlaneUnavailableError();
+  return value;
+}
+function positive(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throw new PlatformControlPlaneUnavailableError();
+  return value;
+}
+function timestamp(value: unknown): string {
+  const result = text(value);
+  if (!Number.isFinite(Date.parse(result))) throw new PlatformControlPlaneUnavailableError();
+  return result;
+}
+function nullableTimestamp(value: unknown): string | null { return value == null ? null : timestamp(value); }
+function driver(value: unknown): "worker" | "scheduler" | "operator" {
+  if (value === "worker" || value === "scheduler" || value === "operator") return value;
+  throw new PlatformControlPlaneUnavailableError();
+}
+function jobStatus(value: unknown): "running" | "success" | "failed" | "skipped" | null {
+  if (value == null) return null;
+  if (value === "running" || value === "success" || value === "failed" || value === "skipped") return value;
+  throw new PlatformControlPlaneUnavailableError();
+}
+function severity(value: unknown): "p0" | "p1" | "p2" | "p3" {
+  if (value === "p0" || value === "p1" || value === "p2" || value === "p3") return value;
+  throw new PlatformControlPlaneUnavailableError();
+}
+function alertStatus(value: unknown): "open" | "acknowledged" | "resolved" {
+  if (value === "open" || value === "acknowledged" || value === "resolved") return value;
+  throw new PlatformControlPlaneUnavailableError();
+}
+function mapError(error: unknown): Error {
+  if (error instanceof PlatformControlPlaneUnavailableError || error instanceof PlatformControlPlaneConflictError) return error;
+  const code = typeof error === "object" && error && "code" in error ? (error as { code?: unknown }).code : undefined;
+  if (code === "23505") return new PlatformControlPlaneConflictError("platform_control_idempotency_conflict");
+  return new PlatformControlPlaneUnavailableError("platform_control_plane_unavailable");
+}

package/src/operations/server/controlPlaneWatchdog.ts

@@ -0,0 +1,28 @@
+import type { PlatformControlPlanePort } from "../contracts/index.js";
+
+export type DirectPlatformWatchdogResult = { status: number; body: Record<string, unknown> };
+
+/** Existing public-bundle evaluation of persisted neutral job facts. No provider calls. */
+export async function runControlPlaneWatchdogTick(
+  port: PlatformControlPlanePort,
+  now: Date,
+  checkOnly: boolean,
+): Promise<DirectPlatformWatchdogResult> {
+  const snapshot = await port.readControlPlane({});
+  const failedJobs = snapshot.jobs.filter((job) => job.enabled && job.lastStatus === "failed");
+  const health = failedJobs.length > 0 ? "degraded" as const : "healthy" as const;
+  const recorded = checkOnly ? null : await port.mutateControlPlane({
+    action: "record-heartbeat",
+    idempotencyKey: `platform-watchdog:${now.toISOString()}`,
+    health,
+    firingCount: failedJobs.length,
+    maxSeverity: failedJobs.length > 0 ? "p2" : null,
+    promotionReady: failedJobs.length === 0,
+  });
+  return { status: 200, body: {
+    ok: true, health, firingCount: failedJobs.length,
+    failedJobs: failedJobs.map((job) => job.jobName),
+    checkedAt: now.toISOString(), heartbeatRecorded: recorded != null,
+    replayed: recorded?.replayed ?? false,
+  } };
+}

package/src/operations/server/index.ts

@@ -0,0 +1,12 @@
+/** Server mechanisms; authorization, persistence and provider transports are injected. */
+export * from "./adminSettingsHandlers.js";
+export * from "./adminPipelineHandlers.js";
+export * from "./adminAlertsHandlers.js";
+export * from "./controlPlaneHandler.js";
+export * from "./controlPlaneStore.js";
+export * from "./platformWatchdogService.js";
+export * from "./platformWatchdogDecision.js";
+export * from "./platformWatchdogDeliveryPolicy.js";
+export * from "./platformWatchdogQueue.js";
+export * from "./controlPlaneWatchdog.js";
+export * from "./migrations.js";

package/src/operations/server/migrations.ts

@@ -0,0 +1,7 @@
+/** Sparse projection only: install the complete canonical native prefix, never this unit alone. */
+export const OPERATIONS_MIGRATIONS = {
+  native: { units: [{ position: 28, catalogPath: "db/platform/migrations/20260814010000_platform_control_plane.sql",
+    sha256: "b0c8ef6424ebc6f1a84cb132c37908f4831fa40484a729c3713cfb35936559c9",
+    url: new URL("../../../sql/20260814010000_platform_control_plane.sql", import.meta.url) }] },
+  managed: { verified: false },
+} as const;

package/src/operations/server/platformWatchdogDecision.ts

@@ -0,0 +1,93 @@
+import type {
+  AlertDecision,
+  AlertNotificationOutcome,
+  AlertSeverity,
+} from "../contracts/index.js";
+import type { AlertLedgerPort, AlertSinkPort } from "../contracts/index.js";
+import { shouldPage } from "../index.js";
+import { throttleSecondsForSeverity } from "../index.js";
+import {
+  isActionabilitySuppressed,
+  isDeliveryBackoff,
+  isPagingSuppressed,
+  notificationSchedule,
+  shouldAttemptNotification,
+} from "./platformWatchdogDeliveryPolicy.js";
+
+const BELOW_PAGING_SEVERITY_OUTCOME: AlertNotificationOutcome<"webhook"> = {
+  channel: "webhook", status: "skipped", provider: "webhook", error: "below_paging_severity",
+};
+const NON_PAGEABLE_DIAGNOSTIC_OUTCOME: AlertNotificationOutcome<"webhook"> = {
+  channel: "webhook", status: "skipped", provider: "webhook", error: "non_pageable_diagnostic",
+};
+
+export function emptyWatchdogDecisionCounts() {
+  return {
+    notified: 0,
+    notificationFailures: 0,
+    deliveryBackoffCount: 0,
+    throttledNotifications: 0,
+    skippedNotifications: 0,
+    belowThreshold: 0,
+    suppressed: 0,
+    actionableCriticalCount: 0,
+    suppressedCriticalCount: 0,
+    actionablePageableCount: 0,
+  };
+}
+
+/** One complete ledger transition; callers must serialize the same dedupe key. */
+export async function processWatchdogDecision<Channel extends string>(
+  decision: AlertDecision<Channel>,
+  {
+    ledgerPort, sinkPort, now, pagingMinSeverity, notificationThrottleSeconds,
+  }: {
+    ledgerPort: AlertLedgerPort<Channel>;
+    sinkPort: AlertSinkPort<Channel>;
+    now: Date;
+    pagingMinSeverity: AlertSeverity;
+    notificationThrottleSeconds?: number;
+  },
+) {
+  const counts = emptyWatchdogDecisionCounts();
+  const alert = await ledgerPort.upsertOpenAlert(decision, now);
+  const critical = isCriticalDecision(decision);
+  const actionableSuppressed = isActionabilitySuppressed(alert, now);
+  const pagingSuppressed = isPagingSuppressed(alert, now);
+  const pageable = decision.paging !== "never" && shouldPage(decision.severity, pagingMinSeverity);
+
+  // Acknowledgement silences pages, but only a snooze suppresses actionability.
+  if (critical) {
+    if (actionableSuppressed) counts.suppressedCriticalCount += 1;
+    else counts.actionableCriticalCount += 1;
+  }
+  if (pageable && !pagingSuppressed) counts.actionablePageableCount += 1;
+  if (pageable && !pagingSuppressed && isDeliveryBackoff(alert, now)) counts.deliveryBackoffCount += 1;
+  if (pagingSuppressed) {
+    counts.suppressed += 1;
+    return counts;
+  }
+
+  const throttleSeconds = notificationThrottleSeconds ?? throttleSecondsForSeverity(decision.severity);
+  if (!shouldAttemptNotification(alert, now, throttleSeconds)) {
+    counts.throttledNotifications += 1;
+    return counts;
+  }
+
+  // Non-pageable and below-threshold alerts retain their skipped-attempt audit.
+  const nonPageable = decision.paging === "never";
+  const paging = !nonPageable && shouldPage(decision.severity, pagingMinSeverity);
+  const outcome = paging
+    ? await sinkPort.send(decision, alert)
+    : nonPageable ? NON_PAGEABLE_DIAGNOSTIC_OUTCOME : BELOW_PAGING_SEVERITY_OUTCOME;
+  if (outcome.status === "sent") counts.notified += 1;
+  else if (outcome.status === "failed") counts.notificationFailures += 1;
+  else counts.skippedNotifications += 1;
+  if (!paging) counts.belowThreshold += 1;
+  await ledgerPort.recordNotification(alert.id, outcome, now, notificationSchedule(alert, outcome, now, throttleSeconds));
+  return counts;
+}
+
+export function isCriticalDecision(decision: AlertDecision): boolean {
+  return decision.paging !== "never" && (decision.severity === "p0" || decision.severity === "p1");
+}