pipework 0.68.0 → 0.69.0

package/dist/infra/alerts/sinks.d.ts

@@ -0,0 +1,60 @@
+import type { WebhookSignatureOptions } from '../webhook/sign.js';
+/** What a sink receives, and what the webhook sink POSTs as its body. */
+export interface AlertPayload {
+    readonly kind: 'raise' | 'repeat' | 'resolve';
+    readonly key: string;
+    readonly severity: 'info' | 'warning' | 'error' | 'critical';
+    readonly message: string;
+    readonly subject: {
+        readonly tenantId?: string;
+        readonly entity?: string;
+        readonly entityId?: string;
+    } | null;
+    readonly count: number;
+    readonly firstSeenAt: string;
+    readonly lastSeenAt: string;
+    readonly resolvedAt: string | null;
+    /** The latest traces that raised it, newest first. */
+    readonly traceIds: readonly string[];
+}
+export interface AlertDelivery {
+    readonly id: string;
+    readonly kind: AlertPayload['kind'];
+    readonly key: string;
+    readonly sink: string;
+    readonly payload: AlertPayload;
+    /** 1 on the first try. */
+    readonly attempt: number;
+}
+/**
+ * A place alerts are sent. `send` throwing is a failed attempt; so is running past 10 s, which is all the
+ * handle gives a send (the row is leased for 30 s). `delivery.id` is the same on every attempt, so a receiver can dedupe on it.
+ */
+export interface AlertSink {
+    readonly name: string;
+    send(delivery: AlertDelivery): Promise<void>;
+}
+export interface AlertWebhookConfig {
+    /** Sink name; default `'webhook'`. Two sinks on one handle need distinct names. */
+    readonly name?: string;
+    readonly url: string;
+    readonly secret: string;
+    /** Request timeout; default 10 000, at most 20 000 (the handle gives a send 10 s and leases the row for 30 s). */
+    readonly timeoutMs?: number;
+    readonly signing?: WebhookSignatureOptions;
+}
+/**
+ * POSTs the payload as JSON with `X-Webhook-Id`, `X-Webhook-Timestamp` and `X-Webhook-Signature`
+ * (`X-Webhook-Id` is the delivery id, the same on every attempt; HMAC over `<id>.<timestamp>.<body>`, as `webhook.sign` makes them). Any non-2xx status fails the attempt.
+ */
+export declare function webhookSink(config: AlertWebhookConfig): AlertSink;
+export interface MemoryAlertSink extends AlertSink {
+    /** Every delivery received, in order. */
+    readonly delivered: AlertDelivery[];
+    clear(): void;
+}
+/** A sink that keeps what it receives, for tests. */
+export declare function memorySink(options?: {
+    name?: string;
+}): MemoryAlertSink;
+//# sourceMappingURL=sinks.d.ts.map

package/dist/infra/alerts/sinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.d.ts","sourceRoot":"","sources":["../../../src/infra/alerts/sinks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAEjE,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAA;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC7G,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,kHAAkH;IAClH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAA;CAC3C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CA8BjE;AAED,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,aAAa,EAAE,CAAA;IACnC,KAAK,IAAI,IAAI,CAAA;CACd;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,eAAe,CAS3E"}

package/dist/infra/alerts/sinks.js

@@ -0,0 +1,50 @@
+import { signPayload } from '../webhook/sign.js';
+/**
+ * POSTs the payload as JSON with `X-Webhook-Id`, `X-Webhook-Timestamp` and `X-Webhook-Signature`
+ * (`X-Webhook-Id` is the delivery id, the same on every attempt; HMAC over `<id>.<timestamp>.<body>`, as `webhook.sign` makes them). Any non-2xx status fails the attempt.
+ */
+export function webhookSink(config) {
+    const timeoutMs = config.timeoutMs ?? 10_000;
+    if (timeoutMs > 20_000) {
+        throw new Error(`[pipework] alerts.webhook: timeoutMs ${String(timeoutMs)} is over 20000. A delivery is leased for 30 s while it is sent; a longer send could be picked up and sent twice.`);
+    }
+    return {
+        name: config.name ?? 'webhook',
+        async send(delivery) {
+            const signed = signPayload(delivery.payload, config.secret, { ...config.signing, messageId: delivery.id });
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = await fetch(config.url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Webhook-Id': signed.messageId,
+                        'X-Webhook-Timestamp': signed.timestamp.toString(),
+                        'X-Webhook-Signature': signed.signature,
+                    },
+                    body: signed.body,
+                    signal: controller.signal,
+                });
+                await response.text().catch(() => '');
+                if (response.status < 200 || response.status >= 300)
+                    throw new Error(`webhook answered HTTP ${String(response.status)}`);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+/** A sink that keeps what it receives, for tests. */
+export function memorySink(options = {}) {
+    const delivered = [];
+    return {
+        name: options.name ?? 'memory',
+        delivered,
+        // eslint-disable-next-line @typescript-eslint/require-await -- the sink contract is async
+        async send(delivery) { delivered.push(delivery); },
+        clear() { delivered.length = 0; },
+    };
+}
+//# sourceMappingURL=sinks.js.map

package/dist/infra/alerts/sinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.js","sourceRoot":"","sources":["../../../src/infra/alerts/sinks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AA+ChD;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAA0B;IACpD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAA;IAC5C,IAAI,SAAS,GAAG,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,wCAAwC,MAAM,CAAC,SAAS,CAAC,kHAAkH,CAAC,CAAA;IAC9L,CAAC;IACD,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,SAAS;QAC9B,KAAK,CAAC,IAAI,CAAC,QAAQ;YACjB,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAA;YAC1G,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;YACxC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAA;YAC7D,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE;oBACvC,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE;wBACP,cAAc,EAAE,kBAAkB;wBAClC,cAAc,EAAE,MAAM,CAAC,SAAS;wBAChC,qBAAqB,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE;wBAClD,qBAAqB,EAAE,MAAM,CAAC,SAAS;qBACxC;oBACD,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,MAAM,EAAE,UAAU,CAAC,MAAM;iBAC1B,CAAC,CAAA;gBACF,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;gBACrC,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG;oBAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YAC1H,CAAC;oBAAS,CAAC;gBACT,YAAY,CAAC,KAAK,CAAC,CAAA;YACrB,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAQD,qDAAqD;AACrD,MAAM,UAAU,UAAU,CAAC,UAA6B,EAAE;IACxD,MAAM,SAAS,GAAoB,EAAE,CAAA;IACrC,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ;QAC9B,SAAS;QACT,0FAA0F;QAC1F,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA,CAAC,CAAC;QACjD,KAAK,KAAK,SAAS,CAAC,MAAM,GAAG,CAAC,CAAA,CAAC,CAAC;KACjC,CAAA;AACH,CAAC"}

package/dist/infra/alerts/sources.d.ts

@@ -0,0 +1,55 @@
+import type { HealthCheck } from '../../core/lifecycle/types.js';
+import type { AlertSeverity } from './handle.js';
+/** A condition a source finds true right now. */
+export interface AlertCondition {
+    readonly key: string;
+    readonly severity: AlertSeverity;
+    readonly message: string;
+    readonly subject?: {
+        tenantId?: string;
+        entity?: string;
+        entityId?: string;
+    };
+}
+/**
+ * Evaluated on every tick. Each returned condition is raised (so an ongoing one groups). When
+ * `owns` is given, an open alert the source owns that it no longer returns is resolved.
+ */
+export interface AlertSource {
+    readonly name: string;
+    owns?(key: string): boolean;
+    evaluate(): Promise<AlertCondition[]>;
+}
+interface TableOption {
+    readonly table?: string;
+    readonly database?: string;
+}
+/**
+ * Raises `job-dead-letter:<jobType>` for jobs that exhausted their attempts since the last
+ * evaluation (any process: the position is kept in `pipework_alert_source_state`; the first
+ * evaluation starts from now, so history is not replayed). The condition clears only by the
+ * handle's quiet period, so set `resolveAfterQuietMs` on `alerts.create`.
+ */
+export declare function deadLetterSource(options?: TableOption & {
+    severity?: AlertSeverity;
+}): AlertSource;
+/** Raises `job-long-running:<jobType>` while a job of that type has been claimed for longer than `olderThanMs`; resolves when none is. */
+export declare function longRunningSource(options: TableOption & {
+    olderThanMs: number;
+    severity?: AlertSeverity;
+}): AlertSource;
+/**
+ * Raises `queue-backlog:<jobType>` while more than `maxPending` jobs of a type are ready to claim, or the
+ * oldest has waited more than `maxOldestAgeMs`; resolves when the type is under both.
+ */
+export declare function backlogSource(options: TableOption & {
+    maxPending?: number;
+    maxOldestAgeMs?: number;
+    severity?: AlertSeverity;
+}): AlertSource;
+/** Raises `health:<name>` while a check reports unhealthy or throws; resolves when it is healthy again. Degraded is not a fault. */
+export declare function healthSource(checks: readonly HealthCheck[], options?: {
+    severity?: AlertSeverity;
+}): AlertSource;
+export {};
+//# sourceMappingURL=sources.d.ts.map

package/dist/infra/alerts/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../../src/infra/alerts/sources.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7E;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAC3B,QAAQ,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAA;CACtC;AAED,UAAU,WAAW;IAAG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;AAQ7E;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,WAAW,GAAG;IAAE,QAAQ,CAAC,EAAE,aAAa,CAAA;CAAO,GAAG,WAAW,CAiCtG;AAED,0IAA0I;AAC1I,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;CAAE,GAAG,WAAW,CAqBvH;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;CAAE,GAAG,WAAW,CA8B5I;AAED,oIAAoI;AACpI,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,aAAa,CAAA;CAAO,GAAG,WAAW,CAqBpH"}

package/dist/infra/alerts/sources.js

@@ -0,0 +1,134 @@
+import { sql } from '../../data/db/sql.js';
+import { pipeSystem } from '../../data/db/db.js';
+import { assertValidIdentifier, quoteIdentifier } from '../../data/db/identifiers.js';
+function jobsTable(table) {
+    const name = table ?? 'pipework_jobs';
+    assertValidIdentifier(name, 'queue table');
+    return quoteIdentifier(name, 'queue table');
+}
+/**
+ * Raises `job-dead-letter:<jobType>` for jobs that exhausted their attempts since the last
+ * evaluation (any process: the position is kept in `pipework_alert_source_state`; the first
+ * evaluation starts from now, so history is not replayed). The condition clears only by the
+ * handle's quiet period, so set `resolveAfterQuietMs` on `alerts.create`.
+ */
+export function deadLetterSource(options = {}) {
+    const jobs = jobsTable(options.table);
+    const severity = options.severity ?? 'error';
+    const name = 'job-dead-letter';
+    return {
+        name,
+        async evaluate() {
+            const db = pipeSystem(options.database);
+            const first = await db.execute(sql `
+        INSERT INTO pipework_alert_source_state (name, cursor_at) VALUES (${name}, clock_timestamp())
+        ON CONFLICT (name) DO NOTHING RETURNING name`);
+            if (first.length > 0)
+                return [];
+            const rows = await db.execute(sql `
+        WITH cur AS (SELECT cursor_at FROM pipework_alert_source_state WHERE name = ${name} FOR UPDATE),
+        found AS (
+          SELECT j.job_type, count(*)::int AS n, max(j.completed_at) AS hi,
+                 (array_agg(j.error_payload->>'message' ORDER BY j.completed_at DESC))[1] AS last_error
+          FROM ${sql.raw(jobs)} j, cur
+          WHERE j.status = 'dead_letter' AND j.completed_at > cur.cursor_at
+          GROUP BY j.job_type),
+        moved AS (
+          UPDATE pipework_alert_source_state s SET cursor_at = GREATEST(s.cursor_at, (SELECT max(hi) FROM found))
+          WHERE s.name = ${name} AND EXISTS (SELECT 1 FROM found) RETURNING 1)
+        SELECT job_type, n, last_error, (SELECT count(*) FROM moved) AS moved FROM found ORDER BY job_type`);
+            return rows.map(r => ({
+                key: `job-dead-letter:${String(r['job_type'])}`,
+                severity,
+                message: `${String(r['n'])} ${String(r['job_type'])} job(s) dead-lettered`
+                    + (r['last_error'] !== null && r['last_error'] !== undefined ? `; last error: ${String(r['last_error'])}` : ''),
+                subject: { entity: 'job', entityId: String(r['job_type']) },
+            }));
+        },
+    };
+}
+/** Raises `job-long-running:<jobType>` while a job of that type has been claimed for longer than `olderThanMs`; resolves when none is. */
+export function longRunningSource(options) {
+    const jobs = jobsTable(options.table);
+    const severity = options.severity ?? 'warning';
+    return {
+        name: 'job-long-running',
+        owns: key => key.startsWith('job-long-running:'),
+        async evaluate() {
+            const rows = await pipeSystem(options.database).execute(sql `
+        SELECT job_type, count(*)::int AS n, (extract(epoch FROM clock_timestamp() - min(claimed_at)) * 1000)::bigint AS oldest_ms
+        FROM ${sql.raw(jobs)}
+        WHERE status IN ('claimed', 'running')
+          AND claimed_at < clock_timestamp() - ${options.olderThanMs} * interval '1 millisecond'
+        GROUP BY job_type ORDER BY job_type`);
+            return rows.map(r => ({
+                key: `job-long-running:${String(r['job_type'])}`,
+                severity,
+                message: `${String(r['n'])} ${String(r['job_type'])} job(s) running for more than ${String(options.olderThanMs)} ms (oldest ${String(r['oldest_ms'])} ms)`,
+                subject: { entity: 'job', entityId: String(r['job_type']) },
+            }));
+        },
+    };
+}
+/**
+ * Raises `queue-backlog:<jobType>` while more than `maxPending` jobs of a type are ready to claim, or the
+ * oldest has waited more than `maxOldestAgeMs`; resolves when the type is under both.
+ */
+export function backlogSource(options) {
+    if (options.maxPending === undefined && options.maxOldestAgeMs === undefined) {
+        throw new Error('[pipework] alerts.source.backlog needs maxPending, maxOldestAgeMs or both.');
+    }
+    const jobs = jobsTable(options.table);
+    const severity = options.severity ?? 'warning';
+    const maxPending = options.maxPending ?? null;
+    const maxAge = options.maxOldestAgeMs ?? null;
+    return {
+        name: 'queue-backlog',
+        owns: key => key.startsWith('queue-backlog:'),
+        async evaluate() {
+            const rows = await pipeSystem(options.database).execute(sql `
+        SELECT job_type, n, oldest_ms FROM (
+          SELECT job_type, count(*)::int AS n,
+                 (extract(epoch FROM clock_timestamp() - min(queued_at)) * 1000)::bigint AS oldest_ms
+          FROM ${sql.raw(jobs)}
+          WHERE status = 'pending' AND (next_retry_at IS NULL OR next_retry_at <= clock_timestamp())
+          GROUP BY job_type) p
+        WHERE (${maxPending}::int IS NOT NULL AND n > ${maxPending}::int)
+           OR (${maxAge}::bigint IS NOT NULL AND oldest_ms > ${maxAge}::bigint)
+        ORDER BY job_type`);
+            return rows.map(r => ({
+                key: `queue-backlog:${String(r['job_type'])}`,
+                severity,
+                message: `${String(r['n'])} ${String(r['job_type'])} job(s) waiting, the oldest for ${String(r['oldest_ms'])} ms`,
+                subject: { entity: 'job', entityId: String(r['job_type']) },
+            }));
+        },
+    };
+}
+/** Raises `health:<name>` while a check reports unhealthy or throws; resolves when it is healthy again. Degraded is not a fault. */
+export function healthSource(checks, options = {}) {
+    const severity = options.severity ?? 'error';
+    const keys = new Set(checks.map(c => `health:${c.name}`));
+    return {
+        name: 'health',
+        owns: key => keys.has(key),
+        async evaluate() {
+            const found = [];
+            for (const check of checks) {
+                let message = null;
+                try {
+                    const result = await check.check();
+                    if (result.status === 'unhealthy')
+                        message = `${check.name} is unhealthy${result.message !== undefined ? `: ${result.message}` : ''}`;
+                }
+                catch (err) {
+                    message = `${check.name} check threw: ${err instanceof Error ? err.message : String(err)}`;
+                }
+                if (message !== null)
+                    found.push({ key: `health:${check.name}`, severity, message, subject: { entity: 'health', entityId: check.name } });
+            }
+            return found;
+        },
+    };
+}
+//# sourceMappingURL=sources.js.map

package/dist/infra/alerts/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../../src/infra/alerts/sources.ts"],"names":[],"mappings":"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"}

package/dist/infra/email/sns.d.ts

@@ -18,7 +18,7 @@ export declare function snsStringToSign(msg: SnsMessage): string;
  * `pipework_email_suppressions`, which the send job checks; a transient or undetermined
  * bounce is only logged. Each one is a trace step with an `Email:bounce` / `Email:complaint`
  * audit record whose `after` carries `messageTraceId`, the trace of the original send.
- * A suppression is logged at warn as `email suppressed`; the alert condition (#458) is not built yet.
+ * A suppression is logged at warn as `email suppressed`; an app raises an alert for it with `alerts.create(...).raise`.
  *
  * Only messages from the configured `topicArns` are accepted (401 otherwise, before any subscription is
  * confirmed or event processed): SNS signs every topic, including an attacker's own.

package/dist/infra/email/sns.js

@@ -86,7 +86,7 @@ const processEvent = __flowStep({ ref: 'pipework/email:notification' }, async (e
  * `pipework_email_suppressions`, which the send job checks; a transient or undetermined
  * bounce is only logged. Each one is a trace step with an `Email:bounce` / `Email:complaint`
  * audit record whose `after` carries `messageTraceId`, the trace of the original send.
- * A suppression is logged at warn as `email suppressed`; the alert condition (#458) is not built yet.
+ * A suppression is logged at warn as `email suppressed`; an app raises an alert for it with `alerts.create(...).raise`.
  *
  * Only messages from the configured `topicArns` are accepted (401 otherwise, before any subscription is
  * confirmed or event processed): SNS signs every topic, including an attacker's own.

package/dist/infra/webhook/sign.d.ts

@@ -1,6 +1,8 @@
 export interface WebhookSignatureOptions {
     algorithm?: string;
     encoding?: 'hex' | 'base64';
+    /** Message id to sign and return; default a fresh UUID. Pass a stable id so a retry is recognisable as the same message. */
+    messageId?: string;
 }
 export interface SignedPayload {
     body: string;

package/dist/infra/webhook/sign.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../../src/infra/webhook/sign.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,aAAa,CAWf"}
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../../src/infra/webhook/sign.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IAC3B,4HAA4H;IAC5H,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,aAAa,CAWf"}

package/dist/infra/webhook/sign.js

@@ -2,7 +2,7 @@ import { createHmac, randomUUID } from 'node:crypto';
 export function signPayload(payload, secret, options = {}) {
     const algorithm = options.algorithm ?? 'sha256';
     const encoding = options.encoding ?? 'hex';
-    const messageId = randomUUID();
+    const messageId = options.messageId ?? randomUUID();
     const timestamp = Math.floor(Date.now() / 1000);
     const body = typeof payload === 'string' ? payload : JSON.stringify(payload);
     const toSign = `${messageId}.${timestamp}.${body}`;

package/dist/infra/webhook/sign.js.map

@@ -1 +1 @@
-{"version":3,"file":"sign.js","sourceRoot":"","sources":["../../../src/infra/webhook/sign.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAcpD,MAAM,UAAU,WAAW,CACzB,OAAgB,EAChB,MAAc,EACd,UAAmC,EAAE;IAErC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAA;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAA;IAE1C,MAAM,SAAS,GAAG,UAAU,EAAE,CAAA;IAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;IAC/C,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IAC5E,MAAM,MAAM,GAAG,GAAG,SAAS,IAAI,SAAS,IAAI,IAAI,EAAE,CAAA;IAClD,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAE/E,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,CAAA;AAClD,CAAC"}
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../../../src/infra/webhook/sign.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAgBpD,MAAM,UAAU,WAAW,CACzB,OAAgB,EAChB,MAAc,EACd,UAAmC,EAAE;IAErC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAA;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAA;IAE1C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,EAAE,CAAA;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;IAC/C,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IAC5E,MAAM,MAAM,GAAG,GAAG,SAAS,IAAI,SAAS,IAAI,IAAI,EAAE,CAAA;IAClD,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAE/E,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,CAAA;AAClD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipework",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "TypeScript framework for multi-tenant SaaS applications. PostgreSQL-only.",
   "type": "module",
   "license": "MIT",