@openlup/platform 0.29.0 → 0.30.0

package/dist/operations/server/controlPlaneStore.js

@@ -0,0 +1,138 @@
+import { PlatformControlPlaneConflictError, PlatformControlPlaneUnavailableError } from "../index.js";
+import { createHash } from "node:crypto";
+const rpc = (name, types) => `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"]),
+};
+export function createPlatformControlPlanePort(client, operatorId) {
+    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),
+                    })),
+                };
+            }
+            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, principalId) {
+    try {
+        return first((await client.query(platformControlPlaneSql.active, [principalId])).rows)
+            ?.platform_control_operator_is_active === true;
+    }
+    catch (error) {
+        throw mapError(error);
+    }
+}
+function mutation(row, expected) {
+    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) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function first(rows) { return rows[0]; }
+function text(value) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new PlatformControlPlaneUnavailableError();
+    return value;
+}
+function bool(value) {
+    if (typeof value !== "boolean")
+        throw new PlatformControlPlaneUnavailableError();
+    return value;
+}
+function positive(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1)
+        throw new PlatformControlPlaneUnavailableError();
+    return value;
+}
+function timestamp(value) {
+    const result = text(value);
+    if (!Number.isFinite(Date.parse(result)))
+        throw new PlatformControlPlaneUnavailableError();
+    return result;
+}
+function nullableTimestamp(value) { return value == null ? null : timestamp(value); }
+function driver(value) {
+    if (value === "worker" || value === "scheduler" || value === "operator")
+        return value;
+    throw new PlatformControlPlaneUnavailableError();
+}
+function jobStatus(value) {
+    if (value == null)
+        return null;
+    if (value === "running" || value === "success" || value === "failed" || value === "skipped")
+        return value;
+    throw new PlatformControlPlaneUnavailableError();
+}
+function severity(value) {
+    if (value === "p0" || value === "p1" || value === "p2" || value === "p3")
+        return value;
+    throw new PlatformControlPlaneUnavailableError();
+}
+function alertStatus(value) {
+    if (value === "open" || value === "acknowledged" || value === "resolved")
+        return value;
+    throw new PlatformControlPlaneUnavailableError();
+}
+function mapError(error) {
+    if (error instanceof PlatformControlPlaneUnavailableError || error instanceof PlatformControlPlaneConflictError)
+        return error;
+    const code = typeof error === "object" && error && "code" in error ? error.code : undefined;
+    if (code === "23505")
+        return new PlatformControlPlaneConflictError("platform_control_idempotency_conflict");
+    return new PlatformControlPlaneUnavailableError("platform_control_plane_unavailable");
+}

package/dist/operations/server/controlPlaneWatchdog.d.ts

@@ -0,0 +1,7 @@
+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 declare function runControlPlaneWatchdogTick(port: PlatformControlPlanePort, now: Date, checkOnly: boolean): Promise<DirectPlatformWatchdogResult>;

package/dist/operations/server/controlPlaneWatchdog.js

@@ -0,0 +1,20 @@
+/** Existing public-bundle evaluation of persisted neutral job facts. No provider calls. */
+export async function runControlPlaneWatchdogTick(port, now, checkOnly) {
+    const snapshot = await port.readControlPlane({});
+    const failedJobs = snapshot.jobs.filter((job) => job.enabled && job.lastStatus === "failed");
+    const health = failedJobs.length > 0 ? "degraded" : "healthy";
+    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/dist/operations/server/index.d.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/dist/operations/server/index.js

@@ -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/dist/operations/server/migrations.d.ts

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

package/dist/operations/server/migrations.js

@@ -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 },
+};

package/dist/operations/server/platformWatchdogDecision.d.ts

@@ -0,0 +1,34 @@
+import type { AlertDecision, AlertSeverity } from "../contracts/index.js";
+import type { AlertLedgerPort, AlertSinkPort } from "../contracts/index.js";
+export declare function emptyWatchdogDecisionCounts(): {
+    notified: number;
+    notificationFailures: number;
+    deliveryBackoffCount: number;
+    throttledNotifications: number;
+    skippedNotifications: number;
+    belowThreshold: number;
+    suppressed: number;
+    actionableCriticalCount: number;
+    suppressedCriticalCount: number;
+    actionablePageableCount: number;
+};
+/** One complete ledger transition; callers must serialize the same dedupe key. */
+export declare 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;
+}): Promise<{
+    notified: number;
+    notificationFailures: number;
+    deliveryBackoffCount: number;
+    throttledNotifications: number;
+    skippedNotifications: number;
+    belowThreshold: number;
+    suppressed: number;
+    actionableCriticalCount: number;
+    suppressedCriticalCount: number;
+    actionablePageableCount: number;
+}>;
+export declare function isCriticalDecision(decision: AlertDecision): boolean;

package/dist/operations/server/platformWatchdogDecision.js

@@ -0,0 +1,71 @@
+import { shouldPage } from "../index.js";
+import { throttleSecondsForSeverity } from "../index.js";
+import { isActionabilitySuppressed, isDeliveryBackoff, isPagingSuppressed, notificationSchedule, shouldAttemptNotification, } from "./platformWatchdogDeliveryPolicy.js";
+const BELOW_PAGING_SEVERITY_OUTCOME = {
+    channel: "webhook", status: "skipped", provider: "webhook", error: "below_paging_severity",
+};
+const NON_PAGEABLE_DIAGNOSTIC_OUTCOME = {
+    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(decision, { ledgerPort, sinkPort, now, pagingMinSeverity, notificationThrottleSeconds, }) {
+    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) {
+    return decision.paging !== "never" && (decision.severity === "p0" || decision.severity === "p1");
+}

package/dist/operations/server/platformWatchdogDeliveryPolicy.d.ts

@@ -0,0 +1,10 @@
+import type { AlertDecision, AlertNotificationOutcome, OpenAlert } from "../contracts/index.js";
+export declare function shouldAttemptNotification(alert: Pick<OpenAlert, "lastNotifiedAt" | "lastNotificationStatus" | "nextNotificationAttemptAt" | "snoozedUntil">, now: Date, throttleSeconds: number): boolean;
+export declare function notificationSchedule(alert: Pick<OpenAlert, "notificationFailureCount">, outcome: AlertNotificationOutcome, now: Date, throttleSeconds: number): {
+    nextAttemptAt: Date;
+    failureCount: number;
+};
+export declare function isActionabilitySuppressed(alert: Pick<OpenAlert, "snoozedUntil">, now: Date): boolean;
+export declare function isPagingSuppressed(alert: Pick<OpenAlert, "status" | "snoozedUntil">, now: Date): boolean;
+export declare function isDeliveryBackoff(alert: Pick<OpenAlert, "lastNotificationStatus" | "nextNotificationAttemptAt">, now: Date): boolean;
+export declare function isSeverityEscalation(decision: Pick<AlertDecision, "severity">, alert: Pick<OpenAlert, "severity">): boolean;

package/dist/operations/server/platformWatchdogDeliveryPolicy.js

@@ -0,0 +1,53 @@
+const FAILURE_RETRY_INITIAL_SECONDS = 10 * 60;
+const FAILURE_RETRY_MAX_SECONDS = 60 * 60;
+export function shouldAttemptNotification(alert, now, throttleSeconds) {
+    const snoozeExpiry = alert.snoozedUntil ? Date.parse(alert.snoozedUntil) : Number.NaN;
+    const lastSentAt = alert.lastNotifiedAt ? Date.parse(alert.lastNotifiedAt) : Number.NaN;
+    if (alert.lastNotificationStatus !== "failed"
+        && Number.isFinite(snoozeExpiry)
+        && snoozeExpiry <= now.getTime()
+        && (!Number.isFinite(lastSentAt) || snoozeExpiry > lastSentAt)) {
+        return true;
+    }
+    const nextAttemptAt = alert.nextNotificationAttemptAt
+        ? Date.parse(alert.nextNotificationAttemptAt)
+        : Number.NaN;
+    if (Number.isFinite(nextAttemptAt) && nextAttemptAt > now.getTime())
+        return false;
+    if (!alert.lastNotifiedAt)
+        return true;
+    return now.getTime() - new Date(alert.lastNotifiedAt).getTime() >= throttleSeconds * 1000;
+}
+export function notificationSchedule(alert, outcome, now, throttleSeconds) {
+    if (outcome.status === "failed") {
+        const failureCount = (alert.notificationFailureCount ?? 0) + 1;
+        const exponent = Math.max(0, Math.min(failureCount - 1, 16));
+        const retrySeconds = Math.min(FAILURE_RETRY_MAX_SECONDS, FAILURE_RETRY_INITIAL_SECONDS * 2 ** exponent);
+        return {
+            nextAttemptAt: new Date(now.getTime() + retrySeconds * 1000),
+            failureCount,
+        };
+    }
+    return {
+        // Sent uses the severity cadence. Skipped uses the same due field only to
+        // avoid duplicate audit rows; last_notified_at still advances on sent only.
+        nextAttemptAt: new Date(now.getTime() + throttleSeconds * 1000),
+        failureCount: 0,
+    };
+}
+export function isActionabilitySuppressed(alert, now) {
+    return alert.snoozedUntil != null && new Date(alert.snoozedUntil).getTime() > now.getTime();
+}
+export function isPagingSuppressed(alert, now) {
+    return alert.status === "acknowledged" || isActionabilitySuppressed(alert, now);
+}
+export function isDeliveryBackoff(alert, now) {
+    if (alert.lastNotificationStatus !== "failed" || !alert.nextNotificationAttemptAt)
+        return false;
+    const nextAttemptAt = Date.parse(alert.nextNotificationAttemptAt);
+    return Number.isFinite(nextAttemptAt) && nextAttemptAt > now.getTime();
+}
+export function isSeverityEscalation(decision, alert) {
+    const rank = { p0: 0, p1: 1, p2: 2, p3: 3 };
+    return rank[decision.severity] < rank[alert.severity];
+}

package/dist/operations/server/platformWatchdogQueue.d.ts

@@ -0,0 +1,11 @@
+import type { AlertDecision } from "../contracts/index.js";
+import type { AlertSinkPort } from "../contracts/index.js";
+type WatchdogQueueItem = Pick<AlertDecision, "dedupeKey" | "severity" | "paging">;
+/**
+ * Only each key's first unfinished item is eligible. A head heap prioritizes
+ * normalized severity without reordering the caller's decisions or duplicates.
+ */
+export declare function runWatchdogQueue(items: readonly WatchdogQueueItem[], process: (index: number) => Promise<void>): Promise<void>;
+/** Per-tick transport limit; admitted waiters still run if an earlier send throws. */
+export declare function createSerialWatchdogSink<Channel extends string>(sinkPort: AlertSinkPort<Channel>): AlertSinkPort<Channel>;
+export {};

package/dist/operations/server/platformWatchdogQueue.js

@@ -0,0 +1,94 @@
+const WATCHDOG_CONCURRENCY = 4;
+const SEVERITY_RANK = { p0: 0, p1: 1, p2: 2, p3: 3 };
+/**
+ * Only each key's first unfinished item is eligible. A head heap prioritizes
+ * normalized severity without reordering the caller's decisions or duplicates.
+ */
+export async function runWatchdogQueue(items, process) {
+    const next = new Array(items.length).fill(-1);
+    const lastByKey = new Map();
+    const ready = [];
+    for (let index = 0; index < items.length; index += 1) {
+        const previous = lastByKey.get(items[index].dedupeKey);
+        if (previous === undefined)
+            push(index);
+        else
+            next[previous] = index;
+        lastByKey.set(items[index].dedupeKey, index);
+    }
+    let failed = false;
+    let firstError;
+    async function worker() {
+        while (!failed) {
+            const index = pop();
+            if (index === undefined)
+                return;
+            try {
+                await process(index);
+            }
+            catch (error) {
+                if (!failed)
+                    firstError = error;
+                failed = true;
+                return;
+            }
+            if (!failed && next[index] !== -1)
+                push(next[index]);
+        }
+    }
+    // Workers catch their own errors so every admitted chain settles before reject.
+    await Promise.all(Array.from({ length: WATCHDOG_CONCURRENCY }, () => worker()));
+    if (failed)
+        throw firstError;
+    function compare(left, right) {
+        const a = items[left];
+        const b = items[right];
+        return SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
+            || Number(a.paging === "never") - Number(b.paging === "never")
+            || a.dedupeKey.localeCompare(b.dedupeKey)
+            || left - right;
+    }
+    function push(index) {
+        let position = ready.length;
+        ready.push(index);
+        while (position > 0) {
+            const parent = Math.floor((position - 1) / 2);
+            if (compare(ready[parent], index) <= 0)
+                break;
+            ready[position] = ready[parent];
+            position = parent;
+        }
+        ready[position] = index;
+    }
+    function pop() {
+        if (ready.length === 0)
+            return undefined;
+        const first = ready[0];
+        const last = ready.pop();
+        if (ready.length === 0)
+            return first;
+        let position = 0;
+        while (position * 2 + 1 < ready.length) {
+            let child = position * 2 + 1;
+            if (child + 1 < ready.length && compare(ready[child + 1], ready[child]) < 0)
+                child += 1;
+            if (compare(last, ready[child]) <= 0)
+                break;
+            ready[position] = ready[child];
+            position = child;
+        }
+        ready[position] = last;
+        return first;
+    }
+}
+/** Per-tick transport limit; admitted waiters still run if an earlier send throws. */
+export function createSerialWatchdogSink(sinkPort) {
+    let tail = Promise.resolve();
+    return {
+        send(decision, alert) {
+            const attempt = tail.then(() => sinkPort.send(decision, alert));
+            tail = attempt.then(() => undefined, () => undefined);
+            return attempt;
+        },
+    };
+}

package/dist/operations/server/platformWatchdogService.d.ts

@@ -0,0 +1,47 @@
+import type { AlertDecision, AlertSeverity, WatchdogSnapshot } from "../contracts/index.js";
+import type { AlertLedgerPort, AlertSinkPort, ObservabilityEvidencePort } from "../contracts/index.js";
+export type PlatformWatchdogResult<Channel extends string = string> = {
+    ok: boolean;
+    health: "healthy" | "firing";
+    checkOnly: boolean;
+    checkedAt: string;
+    alertCount: number;
+    firingCount: number;
+    /** P0/P1 incidents not covered by an active snooze and still requiring ownership. */
+    actionableCriticalCount: number;
+    /** P0/P1 incidents covered by an active snooze; acknowledged alerts stay actionable. */
+    suppressedCriticalCount: number;
+    /** Alerts that meet the current paging threshold and are not currently page-suppressed. */
+    actionablePageableCount: number;
+    maxSeverity: string | null;
+    decisions: AlertDecision<Channel>[];
+    notified: number;
+    notificationFailures: number;
+    /** Failed deliveries held until their persisted bounded retry time. */
+    deliveryBackoffCount: number;
+    throttledNotifications: number;
+    skippedNotifications: number;
+    belowThreshold: number;
+    suppressed: number;
+    muted: number;
+    resolved: number;
+};
+export declare function runPlatformWatchdog<Snapshot extends WatchdogSnapshot, CatalogEntry, Channel extends string = string>({ evidencePort, evaluate, ledgerPort, sinkPort, catalog, now, checkOnly, notificationThrottleSeconds, pagingMinSeverity, mutedDedupePrefixes, normalizeDecision, }: {
+    evidencePort: ObservabilityEvidencePort<Snapshot>;
+    evaluate: (snapshot: Snapshot, catalog: readonly CatalogEntry[], now: Date) => AlertDecision<Channel>[];
+    ledgerPort: AlertLedgerPort<Channel>;
+    sinkPort: AlertSinkPort<Channel>;
+    catalog: readonly CatalogEntry[];
+    now?: Date;
+    checkOnly: boolean;
+    /** Flat override; when omitted, the throttle is scaled per alert severity. */
+    notificationThrottleSeconds?: number;
+    pagingMinSeverity?: AlertSeverity;
+    /**
+     * Dedupe-key prefixes fully muted for this environment (e.g. `job_missed` on a
+     * staging host with no real crons). Muted signals are not recorded, not paged,
+     * and existing open rows for them auto-resolve — keeping the ledger clean.
+     */
+    mutedDedupePrefixes?: readonly string[];
+    normalizeDecision?: (decision: AlertDecision<Channel>) => AlertDecision<Channel>;
+}): Promise<PlatformWatchdogResult<Channel>>;

package/dist/operations/server/platformWatchdogService.js

@@ -0,0 +1,105 @@
+import { DEFAULT_PAGING_MIN_SEVERITY, shouldPage, } from "../index.js";
+import { isActionabilitySuppressed, isDeliveryBackoff, isPagingSuppressed, isSeverityEscalation, } from "./platformWatchdogDeliveryPolicy.js";
+import { emptyWatchdogDecisionCounts, isCriticalDecision, processWatchdogDecision, } from "./platformWatchdogDecision.js";
+import { createSerialWatchdogSink, runWatchdogQueue } from "./platformWatchdogQueue.js";
+export async function runPlatformWatchdog({ evidencePort, evaluate, ledgerPort, sinkPort, catalog, now = new Date(), checkOnly, notificationThrottleSeconds, pagingMinSeverity = DEFAULT_PAGING_MIN_SEVERITY, mutedDedupePrefixes = [], normalizeDecision, }) {
+    const snapshot = await evidencePort.collectSnapshot(now);
+    const allDecisions = evaluate(snapshot, catalog, now);
+    const decisions = allDecisions
+        .filter((decision) => !isMuted(decision.dedupeKey, mutedDedupePrefixes))
+        .map((decision) => normalizeDecision ? normalizeDecision(decision) : decision);
+    const muted = allDecisions.length - decisions.length;
+    const firingDecisions = decisions.filter((decision) => decision.paging !== "never");
+    const firingCount = firingDecisions.length;
+    const maxSeverity = maxSeverityOf(firingDecisions);
+    const openAlerts = await ledgerPort.listOpenAlerts();
+    if (checkOnly) {
+        const alertsByDedupeKey = new Map(openAlerts.map((alert) => [alert.dedupeKey, alert]));
+        let actionableCriticalCount = 0;
+        let suppressedCriticalCount = 0;
+        let actionablePageableCount = 0;
+        let deliveryBackoffCount = 0;
+        let suppressed = 0;
+        for (const decision of decisions) {
+            const alert = alertsByDedupeKey.get(decision.dedupeKey);
+            // The mutating path clears acknowledgement, snooze and delivery cadence on
+            // escalation. Mirror that transition here so a read-only probe cannot
+            // report a stale suppression that the next real tick will remove.
+            const suppressionSurvives = alert ? !isSeverityEscalation(decision, alert) : false;
+            const actionableSuppressed = alert && suppressionSurvives
+                ? isActionabilitySuppressed(alert, now)
+                : false;
+            const pagingSuppressed = alert && suppressionSurvives
+                ? isPagingSuppressed(alert, now)
+                : false;
+            const critical = isCriticalDecision(decision);
+            const pageable = decision.paging !== "never" && shouldPage(decision.severity, pagingMinSeverity);
+            if (critical) {
+                if (actionableSuppressed)
+                    suppressedCriticalCount += 1;
+                else
+                    actionableCriticalCount += 1;
+            }
+            if (pageable && !pagingSuppressed)
+                actionablePageableCount += 1;
+            if (alert && pageable && !pagingSuppressed && isDeliveryBackoff(alert, now)) {
+                deliveryBackoffCount += 1;
+            }
+            if (pagingSuppressed)
+                suppressed += 1;
+        }
+        return result({ checkOnly, checkedAt: snapshot.checkedAt, decisions, firingCount, actionableCriticalCount, suppressedCriticalCount, actionablePageableCount, notified: 0, notificationFailures: 0, deliveryBackoffCount, throttledNotifications: 0, skippedNotifications: 0, belowThreshold: 0, suppressed, muted, resolved: 0, maxSeverity });
+    }
+    const firingKeys = new Set(decisions.map((decision) => decision.dedupeKey));
+    const counts = emptyWatchdogDecisionCounts();
+    const serialSink = createSerialWatchdogSink(sinkPort);
+    await runWatchdogQueue(decisions, async (index) => {
+        const contribution = await processWatchdogDecision(decisions[index], {
+            ledgerPort, sinkPort: serialSink, now, pagingMinSeverity, notificationThrottleSeconds,
+        });
+        for (const key of Object.keys(contribution)) {
+            counts[key] += contribution[key];
+        }
+    });
+    // A rejected decision queue drains before throwing, so it never enters resolution.
+    const staleAlerts = openAlerts.filter((alert) => !firingKeys.has(alert.dedupeKey));
+    await runWatchdogQueue(staleAlerts, async (index) => {
+        await ledgerPort.resolveAlert(staleAlerts[index].dedupeKey, now);
+    });
+    return result({ checkOnly, checkedAt: snapshot.checkedAt, decisions, firingCount, ...counts, muted, resolved: staleAlerts.length, maxSeverity });
+}
+function isMuted(dedupeKey, mutedPrefixes) {
+    return mutedPrefixes.some((prefix) => prefix.length > 0 && dedupeKey.startsWith(prefix));
+}
+function severityRank(severity) {
+    return { p0: 0, p1: 1, p2: 2, p3: 3 }[severity];
+}
+function maxSeverityOf(decisions) {
+    return decisions.reduce((current, decision) => current == null || severityRank(decision.severity) < severityRank(current) ? decision.severity : current, null);
+}
+function result({ checkOnly, checkedAt, decisions, firingCount, actionableCriticalCount, suppressedCriticalCount, actionablePageableCount, notified, notificationFailures, deliveryBackoffCount, throttledNotifications, skippedNotifications, belowThreshold, suppressed, muted, resolved, maxSeverity, }) {
+    return {
+        // Evaluation success is separate from the incident state. HTTP binding may
+        // still fail the request for evidence, notification transport, or config.
+        ok: true,
+        health: firingCount === 0 ? "healthy" : "firing",
+        checkOnly,
+        checkedAt,
+        alertCount: decisions.length,
+        firingCount,
+        actionableCriticalCount,
+        suppressedCriticalCount,
+        actionablePageableCount,
+        maxSeverity,
+        decisions,
+        notified,
+        notificationFailures,
+        deliveryBackoffCount,
+        throttledNotifications,
+        skippedNotifications,
+        belowThreshold,
+        suppressed,
+        muted,
+        resolved,
+    };
+}

package/dist/operations/validation.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export { z };

package/dist/operations/validation.js

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