@openlup/platform 0.29.0 → 0.30.0

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

package/dist/operations/clients.d.ts

@@ -0,0 +1,17 @@
+import type { z } from "zod";
+import type { AdminSettingsReadResponse, AdminSettingsUpdateRequest, AdminSettingsUpdateResponse, AdminPipelineReadResponse } from "./contracts/admin.js";
+import type { AdminAlertsOverviewResponse } from "./contracts/adminAlertsContracts.js";
+/** The existing BFF requester owns fetch, envelope validation, cancellation and diagnostics. */
+export interface OperationsRequestOptions extends Omit<RequestInit, "body"> {
+    body?: unknown;
+    fetcher?: typeof fetch;
+    timeoutMs?: number;
+}
+export type OperationsRequestBff = <T>(path: string, schema: z.ZodType<T>, options?: OperationsRequestOptions) => Promise<T>;
+/** Bind the existing browser calls without installing an ambient fetch implementation. */
+export declare function createOperationsClients(requestBff: OperationsRequestBff): {
+    getAdminSettings(accessToken: string, options?: OperationsRequestOptions): Promise<AdminSettingsReadResponse>;
+    updateAdminSetting(accessToken: string, request: AdminSettingsUpdateRequest, options?: OperationsRequestOptions): Promise<AdminSettingsUpdateResponse>;
+    getAdminPipeline(accessToken: string, options?: OperationsRequestOptions): Promise<AdminPipelineReadResponse>;
+    getAdminAlertsOverview(accessToken: string, options?: OperationsRequestOptions): Promise<AdminAlertsOverviewResponse>;
+};

package/dist/operations/clients.js

@@ -0,0 +1,32 @@
+import { adminSettingsReadResponseSchema, adminSettingsUpdateResponseSchema, adminPipelineReadResponseSchema } from "./schemas.js";
+import { adminAlertsOverviewResponseSchema } from "./adminAlertsSchemas.js";
+/** Bind the existing browser calls without installing an ambient fetch implementation. */
+export function createOperationsClients(requestBff) {
+    return {
+        getAdminSettings(accessToken, options = {}) {
+            return requestBff("/api/bff/admin/platform/settings", adminSettingsReadResponseSchema, {
+                ...options, method: "GET", headers: authHeaders(accessToken, options),
+            });
+        },
+        updateAdminSetting(accessToken, request, options = {}) {
+            return requestBff("/api/bff/admin/platform/settings/update", adminSettingsUpdateResponseSchema, {
+                ...options, method: "POST", headers: authHeaders(accessToken, options), body: request,
+            });
+        },
+        getAdminPipeline(accessToken, options = {}) {
+            return requestBff("/api/bff/admin/platform/pipeline", adminPipelineReadResponseSchema, {
+                ...options, method: "GET", headers: authHeaders(accessToken, options),
+            });
+        },
+        getAdminAlertsOverview(accessToken, options = {}) {
+            return requestBff("/api/bff/admin/platform/alerts", adminAlertsOverviewResponseSchema, {
+                ...options, method: "GET", headers: authHeaders(accessToken, options),
+            });
+        },
+    };
+}
+function authHeaders(accessToken, options) {
+    const headers = new Headers(options.headers);
+    headers.set("Authorization", `Bearer ${accessToken}`);
+    return headers;
+}

package/dist/operations/contracts/admin.d.ts

@@ -0,0 +1,93 @@
+/** DTOs for the existing operational settings, pipeline and control-plane surfaces. */
+export type AdminPipelineTester = {
+    id: string;
+    status: string;
+    email_sequence_step: number | null;
+    email_sequence_paused: boolean | null;
+};
+export type AdminPipelineEmailTemplate = {
+    id: string;
+    name: string;
+    sequence_order: number | null;
+};
+export type AdminPipelineEmailEvent = {
+    event_type: string;
+};
+export type AdminPipelineReadRequest = Record<string, never>;
+export type AdminPipelineReadResponse = {
+    testers: AdminPipelineTester[];
+    templates: AdminPipelineEmailTemplate[];
+    emailSendCount: number;
+    emailEvents: AdminPipelineEmailEvent[];
+};
+export type AdminPipelineDhlTrackingRefreshRequest = Record<string, never>;
+export type AdminPipelineDhlTrackingRefreshResponse = {
+    checked: number;
+    updated: number;
+};
+export type AdminSettingsAdminUser = {
+    id: string;
+    email: string | null;
+    role: string | null;
+};
+export type AdminSettingsReadRequest = Record<string, never>;
+export type AdminSettingsReadResponse = {
+    settings: Record<string, unknown>;
+    adminUsers: AdminSettingsAdminUser[];
+};
+export type AdminSettingWriteValue = string | number | boolean | null;
+export type AdminSettingsUpdateRequest = {
+    key: string;
+    value: AdminSettingWriteValue;
+};
+export type AdminSettingsUpdateResponse = {
+    key: string;
+    saved: true;
+};
+export type PlatformControlPlaneReadRequest = Record<string, never>;
+export type PlatformControlPlaneReadResponse = {
+    controls: {
+        controlKey: string;
+        enabled: boolean;
+        revision: number;
+        updatedAt: string;
+    }[];
+    jobs: {
+        jobName: string;
+        enabled: boolean;
+        activeDriver: "worker" | "scheduler" | "operator";
+        lastStatus: "running" | "success" | "failed" | "skipped" | null;
+        lastStartedAt: string | null;
+        lastFinishedAt: string | null;
+        lastSuccessAt: string | null;
+    }[];
+    alerts: {
+        dedupeKey: string;
+        severity: "p0" | "p1" | "p2" | "p3";
+        status: "open" | "acknowledged" | "resolved";
+        owner: string;
+        title: string;
+        firstSeenAt: string;
+        lastSeenAt: string;
+        resolvedAt: string | null;
+    }[];
+};
+export type PlatformControlPlaneMutation = {
+    action: "set-control";
+    idempotencyKey: string;
+    controlKey: string;
+    enabled: boolean;
+} | {
+    action: "record-heartbeat";
+    idempotencyKey: string;
+    health: "healthy" | "degraded" | "failed";
+    firingCount: number;
+    maxSeverity: "p0" | "p1" | "p2" | "p3" | null;
+    promotionReady: boolean;
+};
+export type PlatformControlPlaneMutationResponse = {
+    action: "set-control" | "record-heartbeat";
+    replayed: boolean;
+    revision: number | null;
+    recordedAt: string;
+};

package/dist/operations/contracts/admin.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/adminAlertsContracts.d.ts

@@ -0,0 +1,40 @@
+/** Operator projection; persistence and read authority remain host-owned. */
+export type AdminAlertSeverity = "p0" | "p1" | "p2" | "p3";
+export type AdminAlertLane = "commerce" | "platform";
+export type AdminAlertHealth = "ok" | "degraded" | "down" | "unknown";
+export type AdminAlert = {
+    id: string;
+    dedupeKey: string;
+    lane: AdminAlertLane;
+    owner: string;
+    severity: AdminAlertSeverity;
+    status: "open" | "acknowledged";
+    pageable: boolean;
+    title: string;
+    message: string;
+    supportCode: string | null;
+    runbookUrl: string | null;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    snoozedUntil: string | null;
+};
+export type AdminAlertsHeartbeat = {
+    lastSuccessAt: string | null;
+    staleAfterSeconds: number;
+    stale: boolean;
+};
+export type AdminAlertsSummary = {
+    commercePageableCount: number;
+    commerceTotalCount: number;
+    platformPageableCount: number;
+    snoozedCount: number;
+    maxOpenSeverity: AdminAlertSeverity | null;
+};
+export type AdminAlertsOverviewResponse = {
+    health: AdminAlertHealth;
+    summary: AdminAlertsSummary;
+    heartbeat: AdminAlertsHeartbeat;
+    alerts: AdminAlert[];
+    snoozedAlerts: AdminAlert[];
+    generatedAt: string;
+};

package/dist/operations/contracts/adminAlertsContracts.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/alertHumanContext.d.ts

@@ -0,0 +1,7 @@
+export type AlertIncidentClass = "customer_communication_failure" | "scheduled_job_failed" | "scheduled_job_missed" | "fulfillment_tracking_stalled" | "configuration_drift" | "data_integrity" | "queue_backlog" | "recipient_configuration_failure" | "platform_watchdog";
+export type AlertHumanContext = {
+    incidentClass: AlertIncidentClass;
+    impact: string;
+    firstAction: string;
+    urgency: string;
+};

package/dist/operations/contracts/alertHumanContext.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./admin.js";
+export * from "./adminAlertsContracts.js";
+export * from "./ports.js";
+export * from "./observabilityContracts.js";
+export * from "./observabilityPorts.js";
+export * from "./alertHumanContext.js";

package/dist/operations/contracts/index.js

@@ -0,0 +1,6 @@
+export * from "./admin.js";
+export * from "./adminAlertsContracts.js";
+export * from "./ports.js";
+export * from "./observabilityContracts.js";
+export * from "./observabilityPorts.js";
+export * from "./alertHumanContext.js";

package/dist/operations/contracts/observabilityContracts.d.ts

@@ -0,0 +1,41 @@
+export type AlertSeverity = "p0" | "p1" | "p2" | "p3";
+/** Opaque host-owned transport key; this module declares no vendor capability. */
+export type AlertChannel = string;
+export type WatchdogSnapshot = {
+    checkedAt: string;
+};
+export type AlertDecision<Channel extends string = AlertChannel> = {
+    dedupeKey: string;
+    severity: AlertSeverity;
+    owner: string;
+    runbookUrl: string;
+    title: string;
+    message: string;
+    humanContext?: import("./alertHumanContext.js").AlertHumanContext;
+    channels: Channel[];
+    payload: Record<string, unknown>;
+    paging?: "default" | "never";
+};
+export type OpenAlert = {
+    id: string;
+    dedupeKey: string;
+    status: "open" | "acknowledged";
+    severity: AlertSeverity;
+    lastNotifiedAt: string | null;
+    /** Most recent watchdog delivery decision, including skipped/failed attempts. */
+    lastNotificationAttemptAt?: string | null;
+    lastNotificationStatus?: AlertNotificationOutcome["status"] | null;
+    /** Earliest time the watchdog may create another delivery-attempt ledger row. */
+    nextNotificationAttemptAt?: string | null;
+    /** Consecutive failed webhook attempts; reset by sent/skipped outcomes. */
+    notificationFailureCount?: number;
+    /** Operator silence window; when set and in the future, paging is suppressed. */
+    snoozedUntil?: string | null;
+};
+export type AlertNotificationOutcome<Channel extends string = AlertChannel> = {
+    channel: Channel;
+    status: "sent" | "failed" | "skipped";
+    provider?: string | null;
+    providerResponse?: Record<string, unknown> | null;
+    error?: string | null;
+};

package/dist/operations/contracts/observabilityContracts.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/observabilityPorts.d.ts

@@ -0,0 +1,18 @@
+import type { AlertDecision, AlertNotificationOutcome, WatchdogSnapshot, OpenAlert } from "./observabilityContracts.js";
+export type ObservabilityEvidencePort<Snapshot extends WatchdogSnapshot = WatchdogSnapshot> = {
+    collectSnapshot(now: Date): Promise<Snapshot>;
+};
+export type AlertLedgerPort<Channel extends string = string> = {
+    listOpenAlerts(): Promise<OpenAlert[]>;
+    upsertOpenAlert: (decision: AlertDecision<Channel>, now: Date) => Promise<OpenAlert>;
+    resolveAlert(dedupeKey: string, now: Date): Promise<void>;
+    recordNotification: (alertId: string, 
+    /** The kernel retains its existing webhook-keyed skipped-attempt audit rows. */
+    outcome: AlertNotificationOutcome<Channel | "webhook">, now: Date, schedule: {
+        nextAttemptAt: Date;
+        failureCount: number;
+    }) => Promise<void>;
+};
+export type AlertSinkPort<Channel extends string = string> = {
+    send: (decision: AlertDecision<Channel>, alert: OpenAlert) => Promise<AlertNotificationOutcome<Channel>>;
+};

package/dist/operations/contracts/observabilityPorts.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/ports.d.ts

@@ -0,0 +1,19 @@
+import type { AdminPipelineReadRequest, AdminPipelineReadResponse, AdminSettingsReadRequest, AdminSettingsReadResponse, AdminSettingsUpdateRequest, AdminSettingsUpdateResponse, PlatformControlPlaneReadRequest, PlatformControlPlaneReadResponse, PlatformControlPlaneMutation, PlatformControlPlaneMutationResponse } from "./admin.js";
+export interface AdminPipelineReadPort {
+    readPipeline(request: AdminPipelineReadRequest): Promise<AdminPipelineReadResponse>;
+}
+export interface AdminSettingsOperationsPort {
+    readSettings(request: AdminSettingsReadRequest): Promise<AdminSettingsReadResponse>;
+    updateSetting(request: AdminSettingsUpdateRequest): Promise<AdminSettingsUpdateResponse>;
+}
+export interface PlatformControlPlanePort {
+    readControlPlane(request: PlatformControlPlaneReadRequest): Promise<PlatformControlPlaneReadResponse>;
+    mutateControlPlane(request: PlatformControlPlaneMutation): Promise<PlatformControlPlaneMutationResponse>;
+}
+export type OperationsAuthorizationResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: "UNAUTHORIZED" | "FORBIDDEN";
+    message: string;
+};

package/dist/operations/contracts/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class PlatformControlPlaneConflictError extends Error {
+    readonly name = "PlatformControlPlaneConflictError";
+}
+export declare class PlatformControlPlaneUnavailableError extends Error {
+    readonly name = "PlatformControlPlaneUnavailableError";
+}