@openlup/platform 0.28.0 → 0.30.0

package/dist/marketing/validation.js

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

package/dist/migrations/postgresRunner.d.ts

@@ -34,6 +34,15 @@ 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 {
     /** Name of the PostgreSQL advisory lock that serializes migration sessions. */

package/dist/migrations/postgresRunner.js

@@ -6,6 +6,9 @@
 const LEDGER = "public.platform_schema_migrations";
 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, options) {
     const root = options.root ?? process.cwd();
     let pool = null;
@@ -20,8 +23,10 @@ export function createPostgresMigrationRunner(env, options) {
         async status() {
             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 {
@@ -33,8 +38,10 @@ export function createPostgresMigrationRunner(env, options) {
         async apply(opts) {
             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)
@@ -55,7 +62,7 @@ export function createPostgresMigrationRunner(env, options) {
                         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);
@@ -64,14 +71,14 @@ export function createPostgresMigrationRunner(env, options) {
         },
     };
 }
-async function withMigrationSession(pool, lockName, operation) {
+async function withMigrationSession(pool, lockName, catalogBoundSession, operation) {
     const client = await pool.connect();
     let locked = false;
     let failed = false;
     let operationFailure;
     let result;
     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);
     }
@@ -82,7 +89,7 @@ async function withMigrationSession(pool, lockName, operation) {
     let unlockFailure;
     if (locked) {
         try {
-            const unlocked = await client.query(RELEASE_MIGRATION_LOCK, [lockName]);
+            const unlocked = await client.query(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");
         }
@@ -128,8 +135,8 @@ function loadPlan(root, source) {
     }));
     return Object.freeze({ manifest, migrations: catalog.migrations, units: Object.freeze(units) });
 }
-async function readAppliedPrefix(client, units) {
-    const exists = await client.query("SELECT to_regclass($1) IS NOT NULL AS ledger_exists", [LEDGER]);
+async function readAppliedPrefix(client, units, catalogBoundSession) {
+    const exists = await client.query(catalogBoundSession ? CATALOG_BOUND_LEDGER_EXISTENCE : "SELECT to_regclass($1) IS NOT NULL AS ledger_exists", [LEDGER]);
     if (exists.rows[0]?.ledger_exists !== true)
         return [];
     const result = await client.query(`SELECT catalog_path, sha256, position FROM ${LEDGER} ORDER BY position`);

package/dist/operations/adminAlertsSchemas.d.ts

@@ -0,0 +1,153 @@
+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 declare const adminAlertSeveritySchema: z.ZodEnum<{
+    p0: "p0";
+    p1: "p1";
+    p2: "p2";
+    p3: "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 declare const adminAlertLaneSchema: z.ZodEnum<{
+    commerce: "commerce";
+    platform: "platform";
+}>;
+export declare const adminAlertHealthSchema: z.ZodEnum<{
+    unknown: "unknown";
+    ok: "ok";
+    degraded: "degraded";
+    down: "down";
+}>;
+export declare const adminAlertSchema: z.ZodObject<{
+    id: z.ZodString;
+    dedupeKey: z.ZodString;
+    lane: z.ZodEnum<{
+        commerce: "commerce";
+        platform: "platform";
+    }>;
+    owner: z.ZodString;
+    severity: z.ZodEnum<{
+        p0: "p0";
+        p1: "p1";
+        p2: "p2";
+        p3: "p3";
+    }>;
+    status: z.ZodEnum<{
+        open: "open";
+        acknowledged: "acknowledged";
+    }>;
+    pageable: z.ZodBoolean;
+    title: z.ZodString;
+    message: z.ZodString;
+    supportCode: z.ZodNullable<z.ZodString>;
+    runbookUrl: z.ZodNullable<z.ZodString>;
+    firstSeenAt: z.ZodString;
+    lastSeenAt: z.ZodString;
+    snoozedUntil: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const adminAlertsHeartbeatSchema: z.ZodObject<{
+    lastSuccessAt: z.ZodNullable<z.ZodString>;
+    staleAfterSeconds: z.ZodNumber;
+    stale: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const adminAlertsSummarySchema: z.ZodObject<{
+    commercePageableCount: z.ZodNumber;
+    commerceTotalCount: z.ZodNumber;
+    platformPageableCount: z.ZodNumber;
+    snoozedCount: z.ZodNumber;
+    maxOpenSeverity: z.ZodNullable<z.ZodEnum<{
+        p0: "p0";
+        p1: "p1";
+        p2: "p2";
+        p3: "p3";
+    }>>;
+}, z.core.$strict>;
+export declare const adminAlertsOverviewResponseSchema: z.ZodObject<{
+    health: z.ZodEnum<{
+        unknown: "unknown";
+        ok: "ok";
+        degraded: "degraded";
+        down: "down";
+    }>;
+    summary: z.ZodObject<{
+        commercePageableCount: z.ZodNumber;
+        commerceTotalCount: z.ZodNumber;
+        platformPageableCount: z.ZodNumber;
+        snoozedCount: z.ZodNumber;
+        maxOpenSeverity: z.ZodNullable<z.ZodEnum<{
+            p0: "p0";
+            p1: "p1";
+            p2: "p2";
+            p3: "p3";
+        }>>;
+    }, z.core.$strict>;
+    heartbeat: z.ZodObject<{
+        lastSuccessAt: z.ZodNullable<z.ZodString>;
+        staleAfterSeconds: z.ZodNumber;
+        stale: z.ZodBoolean;
+    }, z.core.$strict>;
+    alerts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        dedupeKey: z.ZodString;
+        lane: z.ZodEnum<{
+            commerce: "commerce";
+            platform: "platform";
+        }>;
+        owner: z.ZodString;
+        severity: z.ZodEnum<{
+            p0: "p0";
+            p1: "p1";
+            p2: "p2";
+            p3: "p3";
+        }>;
+        status: z.ZodEnum<{
+            open: "open";
+            acknowledged: "acknowledged";
+        }>;
+        pageable: z.ZodBoolean;
+        title: z.ZodString;
+        message: z.ZodString;
+        supportCode: z.ZodNullable<z.ZodString>;
+        runbookUrl: z.ZodNullable<z.ZodString>;
+        firstSeenAt: z.ZodString;
+        lastSeenAt: z.ZodString;
+        snoozedUntil: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    snoozedAlerts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        dedupeKey: z.ZodString;
+        lane: z.ZodEnum<{
+            commerce: "commerce";
+            platform: "platform";
+        }>;
+        owner: z.ZodString;
+        severity: z.ZodEnum<{
+            p0: "p0";
+            p1: "p1";
+            p2: "p2";
+            p3: "p3";
+        }>;
+        status: z.ZodEnum<{
+            open: "open";
+            acknowledged: "acknowledged";
+        }>;
+        pageable: z.ZodBoolean;
+        title: z.ZodString;
+        message: z.ZodString;
+        supportCode: z.ZodNullable<z.ZodString>;
+        runbookUrl: z.ZodNullable<z.ZodString>;
+        firstSeenAt: z.ZodString;
+        lastSeenAt: z.ZodString;
+        snoozedUntil: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    generatedAt: z.ZodString;
+}, z.core.$strict>;

package/dist/operations/adminAlertsSchemas.js

@@ -0,0 +1,69 @@
+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/dist/operations/adminAlertsView.d.ts

@@ -0,0 +1,73 @@
+import type { AdminAlert, AdminAlertHealth, AdminAlertLane, AdminAlertSeverity, AdminAlertsHeartbeat, AdminAlertsOverviewResponse, AdminAlertsSummary } from "./contracts/adminAlertsContracts.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 declare const GENERIC_JOB_DEDUPE_PREFIXES: readonly ["job_failed:", "job_missed:", "job_never_succeeded:", "job_stuck_running:", "job_ledger_missing:"];
+/**
+ * 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 declare const WATCHDOG_STALE_AFTER_SECONDS: number;
+export declare function isGenericJobAlert(dedupeKey: string): boolean;
+/**
+ * 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 declare function classifyLane(owner: string, dedupeKey: string): AdminAlertLane;
+export declare function isSnoozed(snoozedUntil: string | null, now: Date): boolean;
+/**
+ * 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 declare function isPageable(row: PlatformAlertLedgerRow, now: Date): boolean;
+export declare function toAdminAlert(row: PlatformAlertLedgerRow, now: Date): AdminAlert;
+export declare function worstSeverity(alerts: readonly AdminAlert[]): AdminAlertSeverity | null;
+/**
+ * `commercePageableCount` and `platformPageableCount` partition the pageable set,
+ * so no alert that would page is ever invisible in the popover.
+ */
+export declare function summarizeAlerts(alerts: readonly AdminAlert[]): AdminAlertsSummary;
+export declare function buildHeartbeat(row: WatchdogHeartbeatRow, now: Date): AdminAlertsHeartbeat;
+/**
+ * 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 declare function deriveHealth(summary: AdminAlertsSummary, heartbeat: AdminAlertsHeartbeat): AdminAlertHealth;
+/** Alerts returned to the client; counts above stay accurate even when this is truncated. */
+export declare const ADMIN_ALERTS_LIST_LIMIT = 50;
+export declare function buildAlertsOverview(rows: readonly PlatformAlertLedgerRow[], heartbeatRow: WatchdogHeartbeatRow, now: Date): AdminAlertsOverviewResponse;

package/dist/operations/adminAlertsView.js

@@ -0,0 +1,184 @@
+import { DEFAULT_PAGING_MIN_SEVERITY, shouldPage } from "./alertPagingPolicy.js";
+/**
+ * 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:",
+];
+/**
+ * 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 = { 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) {
+    return shouldPage(severity, DEFAULT_PAGING_MIN_SEVERITY);
+}
+export function isGenericJobAlert(dedupeKey) {
+    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, dedupeKey) {
+    if (isGenericJobAlert(dedupeKey))
+        return "platform";
+    if (!owner.startsWith("commerce/"))
+        return "platform";
+    if (owner === "commerce/platform")
+        return "platform";
+    return "commerce";
+}
+export function isSnoozed(snoozedUntil, now) {
+    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) {
+    return severity in SEVERITY_RANK ? severity : "p0";
+}
+function normalizeIso(value) {
+    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) {
+    if (row.status !== "open" && row.status !== "acknowledged")
+        return false;
+    return true;
+}
+/** Live enough to affect the health badge and paging. */
+function isLive(row, now) {
+    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, now) {
+    return isLive(row, now) && isPageableSeverity(normalizeSeverity(row.severity));
+}
+export function toAdminAlert(row, now) {
+    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) {
+    let worst = 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) {
+    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, now) {
+    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, heartbeat) {
+    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, b) {
+    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, heartbeatRow, now) {
+    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/dist/operations/alertPagingPolicy.d.ts

@@ -0,0 +1,15 @@
+import type { AlertSeverity } from "./contracts/observabilityContracts.js";
+/** Alerts at or above this severity page by default; below it are ledger-only. */
+export declare const DEFAULT_PAGING_MIN_SEVERITY: AlertSeverity;
+/**
+ * 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 declare function shouldPage(severity: string, minSeverity?: AlertSeverity): boolean;
+/**
+ * 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 declare function parsePagingMinSeverity(value: string | null | undefined): AlertSeverity;

package/dist/operations/alertPagingPolicy.js

@@ -0,0 +1,43 @@
+const ALERT_SEVERITIES = ["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 = { 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 = "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, minSeverity = DEFAULT_PAGING_MIN_SEVERITY) {
+    const rank = SEVERITY_RANK[severity];
+    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) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized && ALERT_SEVERITIES.includes(normalized)) {
+        return normalized;
+    }
+    return DEFAULT_PAGING_MIN_SEVERITY;
+}

package/dist/operations/alertThrottlePolicy.d.ts

@@ -0,0 +1,3 @@
+/** Fallback window for an unknown/unparseable severity. */
+export declare const DEFAULT_THROTTLE_SECONDS: number;
+export declare function throttleSecondsForSeverity(severity: string): number;

package/dist/operations/alertThrottlePolicy.js

@@ -0,0 +1,18 @@
+/**
+ * Per-severity re-notification cadence for platform watchdog alerts.
+ *
+ * A firing alert re-pages at most once per this window (keyed off
+ * `last_notified_at`). Lower severities re-page less often so a persistent
+ * low-severity alert cannot flood the channel, while p0 stays loud.
+ */
+const THROTTLE_SECONDS_BY_SEVERITY = {
+    p0: 1 * 60 * 60, // 1h
+    p1: 4 * 60 * 60, // 4h
+    p2: 12 * 60 * 60, // 12h
+    p3: 24 * 60 * 60, // 24h
+};
+/** Fallback window for an unknown/unparseable severity. */
+export const DEFAULT_THROTTLE_SECONDS = 60 * 60;
+export function throttleSecondsForSeverity(severity) {
+    return THROTTLE_SECONDS_BY_SEVERITY[severity] ?? DEFAULT_THROTTLE_SECONDS;
+}