@openlup/platform 0.28.0 → 0.30.0

package/dist/operations/server/adminPipelineHandlers.js

@@ -0,0 +1,48 @@
+import { createBffResponder } from "../../bff/index.js";
+import { adminPipelineReadRequestSchema, adminPipelineReadResponseSchema, } from "../index.js";
+export function createAdminPipelineReadHandler({ pipelinePort, authorizeAdmin, responseRequestId, }) {
+    const responder = createBffResponder({ responseRequestId });
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        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, res, authorizeAdmin, { sendBffError }) {
+    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/dist/operations/server/adminSettingsHandlers.d.ts

@@ -0,0 +1,14 @@
+import { type BffResponderOptions } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/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 declare function createAdminSettingsReadHandler({ settingsPort, authorizeAdmin, responseRequestId, }: AdminSettingsReadDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAdminSettingsUpdateHandler({ settingsPort, authorizeAdmin, responseRequestId, }: AdminSettingsUpdateDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/operations/server/adminSettingsHandlers.js

@@ -0,0 +1,82 @@
+import { createBffResponder } from "../../bff/index.js";
+import { adminSettingsReadRequestSchema, adminSettingsReadResponseSchema, adminSettingsUpdateRequestSchema, adminSettingsUpdateResponseSchema, } from "../index.js";
+export function createAdminSettingsReadHandler({ settingsPort, authorizeAdmin, responseRequestId, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+    return async function handler(req, res) {
+        if (req.method !== "GET") {
+            sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        let authorization;
+        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, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+    return async function handler(req, res) {
+        if (req.method !== "POST") {
+            sendMethodNotAllowed(res, ["POST"]);
+            return;
+        }
+        let authorization;
+        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/dist/operations/server/controlPlaneHandler.d.ts

@@ -0,0 +1,7 @@
+import { type BffResponderOptions } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { PlatformControlPlanePort } from "../contracts/index.js";
+export declare function createPlatformControlPlaneHandler(deps: {
+    port: PlatformControlPlanePort;
+    authorizeAdmin: () => Promise<boolean>;
+} & BffResponderOptions): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/operations/server/controlPlaneHandler.js

@@ -0,0 +1,54 @@
+import { createBffResponder } from "../../bff/index.js";
+import { platformControlPlaneMutationResponseSchema, platformControlPlaneMutationSchema, platformControlPlaneReadResponseSchema } from "../index.js";
+import { PlatformControlPlaneConflictError } from "../index.js";
+export function createPlatformControlPlaneHandler(deps) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder(deps);
+    return async (req, res) => {
+        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) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function invalidResponse(res, sendBffError) {
+    sendBffError(res, "INVALID_RESPONSE", "Platform control plane returned invalid response");
+}

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

@@ -0,0 +1,12 @@
+import { type PlatformControlPlanePort } from "../contracts/index.js";
+import type { PgQueryExecutor } from "../../data/index.js";
+export declare const platformControlPlaneSql: {
+    readonly active: string;
+    readonly setControl: string;
+    readonly heartbeat: string;
+    readonly controls: string;
+    readonly jobs: string;
+    readonly alerts: string;
+};
+export declare function createPlatformControlPlanePort(client: PgQueryExecutor, operatorId: string): PlatformControlPlanePort;
+export declare function isPlatformControlOperatorActive(client: PgQueryExecutor, principalId: string): Promise<boolean>;

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 {};