@smthrs/notifications 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/AlertRuntime.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The journal-backed alert runtime: one tick per run.
+ *
+ * A tick folds the run's journal into the conditions it leaves open, decides
+ * which have outlived their delay, admits each one as a coalesced system
+ * event, pages the sink, and journals what the sink did with it. The fold is
+ * retained per run, so a tick costs the entries committed since the previous
+ * one rather than the run's whole journal.
+ *
+ * The rules it enforces are `./AlertPolicy.ts` and the channel it pages over
+ * is `./AlertSink.ts`; neither knows this module exists.
+ *
+ * @since 1.0.0
+ */
+import { Journal } from "@smthrs/journal";
+import { Context, Effect, Layer } from "effect";
+import { type Alert, Policy } from "./AlertPolicy.ts";
+import { Sink } from "./AlertSink.ts";
+import { type NotificationError, NotificationQueue } from "./NotificationQueue.ts";
+/**
+ * What one tick decided.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Tick {
+    /** Alerts raised and delivered on this tick. */
+    readonly delivered: ReadonlyArray<Alert>;
+    /** Alerts the sink refused on this tick. They are retried on the next one. */
+    readonly failed: ReadonlyArray<Alert>;
+    /**
+     * Alerts the notification queue refused because the run is at capacity. The
+     * sink was not called for them, and they are retried on the next tick.
+     */
+    readonly refused: ReadonlyArray<Alert>;
+    /** Alerts that had already been delivered, and were not delivered again. */
+    readonly suppressed: ReadonlyArray<Alert>;
+}
+/**
+ * The alert runtime: one tick per run.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface RuntimeService {
+    /**
+     * Reads one run's journal and pages about whatever has waited too long.
+     *
+     * The two failures stay apart because they mean different things to an
+     * operator. A `JournalError` is the alerter's own record channel failing: it
+     * read no entries, or it could not write the delivery record. A
+     * `NotificationError` is the notification queue rejecting the alert outright,
+     * which is a producer or storage fault rather than a full queue. Neither is
+     * a sink failure: a refused page is journaled as `flows.alerts.failed` and
+     * retried on the next tick, and it comes back in {@link Tick.failed}. A queue
+     * at capacity is not a failure either; it comes back in {@link Tick.refused}.
+     */
+    readonly tick: (runId: string) => Effect.Effect<Tick, Journal.JournalError | NotificationError>;
+}
+declare const AlertRuntime_base: Context.ServiceClass<AlertRuntime, "/notifications/AlertRuntime", RuntimeService>;
+/**
+ * The {@link RuntimeService} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class AlertRuntime extends AlertRuntime_base {
+}
+/**
+ * The alert runtime over one policy.
+ *
+ * A tick reads the run's journal, derives the open conditions, decides which
+ * have outlived their delay, and for each one that has not already been
+ * delivered: admits a coalesced system event, sends it to the sink, and
+ * journals the delivery. The admission comes first because it is idempotent
+ * and the send is not: a crash between them costs a duplicate admission, which
+ * the queue drops, while a crash between an accepted send and the delivery
+ * record costs a duplicate PAGE, which is why {@link SinkService.deliver} is
+ * required to dedupe on {@link alertId}.
+ *
+ * The policy is decoded when the layer is built, so a rule with an impossible
+ * delay fails the composition by name instead of mis-paging at 3am.
+ *
+ * @param policy the rules to enforce
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (policy: Policy) => Layer.Layer<AlertRuntime, never, Journal.Journal | NotificationQueue | Sink>;
+export {};
+//# sourceMappingURL=AlertRuntime.d.ts.map

package/dist/esm/AlertRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlertRuntime.d.ts","sourceRoot":"","sources":["../../src/AlertRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAgB,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAS,OAAO,EAAE,MAAM,EAAW,KAAK,EAAkB,MAAM,QAAQ,CAAA;AAC/E,OAAO,EACL,KAAK,KAAK,EAQV,MAAM,EAEP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AAGrC,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAElF;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;IACrC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,GAAG,iBAAiB,CAAC,CAAA;CAChG;;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,iBAEjC;CAAG;AA8CJ;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK,GAChB,QAAQ,MAAM,KACb,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAgI3E,CAAA"}

package/dist/esm/AlertRuntime.js

@@ -0,0 +1,191 @@
+/**
+ * The journal-backed alert runtime: one tick per run.
+ *
+ * A tick folds the run's journal into the conditions it leaves open, decides
+ * which have outlived their delay, admits each one as a coalesced system
+ * event, pages the sink, and journals what the sink did with it. The fold is
+ * retained per run, so a tick costs the entries committed since the previous
+ * one rather than the run's whole journal.
+ *
+ * The rules it enforces are `./AlertPolicy.ts` and the channel it pages over
+ * is `./AlertSink.ts`; neither knows this module exists.
+ *
+ * @since 1.0.0
+ */
+import { Journal, JournalEvent } from "@smthrs/journal";
+import { Clock, Context, Effect, HashSet, Layer, Result, Schema } from "effect";
+import { alertId, decide, deliveredEventType, detectorsOf, failedEventType, observe, payloadRecord, Policy, recordSourceId } from "./AlertPolicy.js";
+import { Sink } from "./AlertSink.js";
+import * as FoldCache from "./internal/foldCache.js";
+import { NotificationQueue } from "./NotificationQueue.js";
+/**
+ * The {@link RuntimeService} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class AlertRuntime extends Context.Service()("/notifications/AlertRuntime") {
+}
+/**
+ * How many runs one alert runtime keeps folded at a time. The retention policy
+ * is scan-resistant, so a sweep of more runs than this reads journal tails for
+ * all but a fixed handful of them.
+ */
+const maximumWatchedRuns = 64;
+const alertNotification = (alert) => ({
+    _tag: "system-event",
+    id: alertId(alert),
+    targetLineageId: alert.runId,
+    delivery: "queue",
+    coalescingKey: alert.coalescingKey,
+    provenance: {
+        sourceRunId: alert.runId,
+        sourceLineageId: alert.runId,
+        sourceTurn: 0,
+        sourceActor: "alerts"
+    },
+    payload: {
+        condition: alert.condition,
+        severity: alert.severity,
+        since: alert.since,
+        firedAt: alert.firedAt,
+        ...(alert.owner === undefined ? {} : { owner: alert.owner }),
+        ...(alert.runbook === undefined ? {} : { runbook: alert.runbook })
+    }
+});
+/**
+ * The alert runtime over one policy.
+ *
+ * A tick reads the run's journal, derives the open conditions, decides which
+ * have outlived their delay, and for each one that has not already been
+ * delivered: admits a coalesced system event, sends it to the sink, and
+ * journals the delivery. The admission comes first because it is idempotent
+ * and the send is not: a crash between them costs a duplicate admission, which
+ * the queue drops, while a crash between an accepted send and the delivery
+ * record costs a duplicate PAGE, which is why {@link SinkService.deliver} is
+ * required to dedupe on {@link alertId}.
+ *
+ * The policy is decoded when the layer is built, so a rule with an impossible
+ * delay fails the composition by name instead of mis-paging at 3am.
+ *
+ * @param policy the rules to enforce
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (policy) => Layer.effect(AlertRuntime, Effect.gen(function* () {
+    const checked = yield* Effect.orDie(Schema.decodeUnknownEffect(Policy)(policy));
+    const detectors = detectorsOf(checked);
+    const journal = yield* Journal.Journal;
+    const queue = yield* NotificationQueue;
+    const sink = yield* Sink;
+    // Folded history per run, so a tick costs the entries committed since
+    // the previous one rather than the run's whole journal.
+    const watched = FoldCache.make(maximumWatchedRuns);
+    const observed = (runId) => Effect.gen(function* () {
+        const base = watched.get(runId) ??
+            { open: new Map(), delivered: HashSet.empty(), cursor: undefined };
+        const fresh = [];
+        let after = base.cursor === undefined ? undefined : JournalEvent.Seq.make(base.cursor);
+        while (true) {
+            const page = yield* journal.entries({ runId, ...(after === undefined ? {} : { after }), limit: 512 });
+            fresh.push(...page.entries);
+            if (!page.hasMore || page.entries.length === 0)
+                break;
+            after = page.entries.at(-1).seq;
+        }
+        if (fresh.length === 0)
+            return base;
+        // `open` is bounded by the policy's rules, so it is copied; the
+        // delivery history is not, so it grows by one persistent node.
+        const open = new Map(base.open);
+        let delivered = base.delivered;
+        let cursor = base.cursor;
+        for (const entry of fresh) {
+            cursor = entry.seq;
+            const payload = payloadRecord(entry.payload);
+            if (payload === undefined)
+                continue;
+            if (entry.eventType === deliveredEventType) {
+                const id = payload["alertId"];
+                // Only a record under the source the alerter writes counts, so
+                // another producer's delivered record cannot suppress a page.
+                // The journal does not bind a source to a writer.
+                if (typeof id === "string" && entry.sourceId === recordSourceId(id, "delivered")) {
+                    delivered = HashSet.add(delivered, id);
+                }
+            }
+            observe(checked, detectors, entry, payload, open);
+        }
+        const next = { open, delivered, cursor };
+        // Published at commit, exactly as `NotificationQueue.load` publishes
+        // its fold. A tick inside an enclosing transaction reads that
+        // transaction's uncommitted rows, and caching them would outlive the
+        // rollback that erased them: the run would page about a condition
+        // durable history never held.
+        yield* journal.whenCommitted(Effect.sync(() => watched.put(runId, next)));
+        return next;
+    });
+    const record = (eventType, alert, source, outcome) => journal.emitDurableUnfenced(new JournalEvent.Input({
+        runId: JournalEvent.RunId.make(alert.runId),
+        sourceId: JournalEvent.SourceId.make(recordSourceId(alertId(alert), source)),
+        sourceSeq: JournalEvent.SourceSeq.make(0),
+        // One record per alert per outcome. Without an explicit identity
+        // the journal allocates a new sequence on every attempt, and a
+        // webhook that stays down appends a row per tick forever.
+        dedupe: "identity",
+        eventType,
+        payload: {
+            runId: alert.runId,
+            condition: alert.condition,
+            since: alert.since,
+            severity: alert.severity,
+            alertId: alertId(alert),
+            ...(outcome.code === undefined ? {} : { code: outcome.code }),
+            ...(outcome.status === undefined ? {} : { status: outcome.status })
+        }
+    })).pipe(Effect.asVoid);
+    return AlertRuntime.of({
+        tick: Effect.fn("AlertRuntime.tick")(function* (runId) {
+            const journalRunId = JournalEvent.RunId.make(runId);
+            const history = yield* observed(journalRunId);
+            const now = yield* Clock.currentTimeMillis;
+            const open = Array.from(history.open, ([condition, since]) => ({ runId, condition, since }));
+            const raised = decide(checked, open, now);
+            const delivered = [];
+            const failed = [];
+            const refused = [];
+            const suppressed = [];
+            for (const alert of raised) {
+                if (HashSet.has(history.delivered, alertId(alert))) {
+                    suppressed.push(alert);
+                    continue;
+                }
+                // Raised unchanged: a queue that rejects the admission outright is
+                // not the journal failing, and calling it `sink_failed` would send
+                // an operator looking at the webhook.
+                const receipt = yield* queue.admit(runId, alertNotification(alert));
+                if (receipt.decision === "rejected-full") {
+                    // The alert has nowhere durable to sit, so paging about it would
+                    // tell an operator about something the run will never read.
+                    yield* record(failedEventType, alert, "refused", { code: "notification_full" });
+                    refused.push(alert);
+                    continue;
+                }
+                const outcome = yield* Effect.result(sink.deliver(alert));
+                if (Result.isFailure(outcome)) {
+                    yield* record(failedEventType, alert, `failed/${outcome.failure.code}`, {
+                        code: outcome.failure.code,
+                        status: outcome.failure.status
+                    });
+                    failed.push(alert);
+                }
+                else {
+                    yield* record(deliveredEventType, alert, "delivered", {});
+                    delivered.push(alert);
+                }
+            }
+            return { delivered, failed, refused, suppressed };
+        })
+    });
+}));
+//# sourceMappingURL=AlertRuntime.js.map

package/dist/esm/AlertRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlertRuntime.js","sourceRoot":"","sources":["../../src/AlertRuntime.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The journal-backed alert runtime: one tick per run.\n *\n * A tick folds the run's journal into the conditions it leaves open, decides\n * which have outlived their delay, admits each one as a coalesced system\n * event, pages the sink, and journals what the sink did with it. The fold is\n * retained per run, so a tick costs the entries committed since the previous\n * one rather than the run's whole journal.\n *\n * The rules it enforces are `./AlertPolicy.ts` and the channel it pages over\n * is `./AlertSink.ts`; neither knows this module exists.\n *\n * @since 1.0.0\n */\n\nimport { Journal, JournalEvent } from \"@smthrs/journal\"\nimport { Clock, Context, Effect, HashSet, Layer, Result, Schema } from \"effect\"\nimport {\n  type Alert,\n  alertId,\n  decide,\n  deliveredEventType,\n  detectorsOf,\n  failedEventType,\n  observe,\n  payloadRecord,\n  Policy,\n  recordSourceId\n} from \"./AlertPolicy.ts\"\nimport { Sink } from \"./AlertSink.ts\"\nimport * as FoldCache from \"./internal/foldCache.ts\"\nimport type * as NotificationModel from \"./Notification.ts\"\nimport { type NotificationError, NotificationQueue } from \"./NotificationQueue.ts\"\n\n/**\n * What one tick decided.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Tick {\n  /** Alerts raised and delivered on this tick. */\n  readonly delivered: ReadonlyArray<Alert>\n  /** Alerts the sink refused on this tick. They are retried on the next one. */\n  readonly failed: ReadonlyArray<Alert>\n  /**\n   * Alerts the notification queue refused because the run is at capacity. The\n   * sink was not called for them, and they are retried on the next tick.\n   */\n  readonly refused: ReadonlyArray<Alert>\n  /** Alerts that had already been delivered, and were not delivered again. */\n  readonly suppressed: ReadonlyArray<Alert>\n}\n\n/**\n * The alert runtime: one tick per run.\n *\n * @category services\n * @since 0.1.0\n */\nexport interface RuntimeService {\n  /**\n   * Reads one run's journal and pages about whatever has waited too long.\n   *\n   * The two failures stay apart because they mean different things to an\n   * operator. A `JournalError` is the alerter's own record channel failing: it\n   * read no entries, or it could not write the delivery record. A\n   * `NotificationError` is the notification queue rejecting the alert outright,\n   * which is a producer or storage fault rather than a full queue. Neither is\n   * a sink failure: a refused page is journaled as `flows.alerts.failed` and\n   * retried on the next tick, and it comes back in {@link Tick.failed}. A queue\n   * at capacity is not a failure either; it comes back in {@link Tick.refused}.\n   */\n  readonly tick: (runId: string) => Effect.Effect<Tick, Journal.JournalError | NotificationError>\n}\n\n/**\n * The {@link RuntimeService} tag.\n *\n * @category services\n * @since 0.1.0\n */\nexport class AlertRuntime extends Context.Service<AlertRuntime, RuntimeService>()(\n  \"/notifications/AlertRuntime\"\n) {}\n\n/**\n * One run's folded alert history: the conditions still open, the alerts\n * already paged, and the sequence the fold stopped at.\n */\ninterface Watched {\n  readonly open: ReadonlyMap<string, number>\n  /**\n   * The alerts already paged, as a persistent set: a tick adds a node and\n   * leaves the fold the previous tick published untouched, where copying the\n   * set would cost the run's whole delivery history on every tick.\n   */\n  readonly delivered: HashSet.HashSet<string>\n  readonly cursor: number | undefined\n}\n\n/**\n * How many runs one alert runtime keeps folded at a time. The retention policy\n * is scan-resistant, so a sweep of more runs than this reads journal tails for\n * all but a fixed handful of them.\n */\nconst maximumWatchedRuns = 64\n\nconst alertNotification = (alert: Alert): NotificationModel.Notification => ({\n  _tag: \"system-event\",\n  id: alertId(alert),\n  targetLineageId: alert.runId,\n  delivery: \"queue\",\n  coalescingKey: alert.coalescingKey,\n  provenance: {\n    sourceRunId: alert.runId,\n    sourceLineageId: alert.runId,\n    sourceTurn: 0,\n    sourceActor: \"alerts\"\n  },\n  payload: {\n    condition: alert.condition,\n    severity: alert.severity,\n    since: alert.since,\n    firedAt: alert.firedAt,\n    ...(alert.owner === undefined ? {} : { owner: alert.owner }),\n    ...(alert.runbook === undefined ? {} : { runbook: alert.runbook })\n  }\n})\n\n/**\n * The alert runtime over one policy.\n *\n * A tick reads the run's journal, derives the open conditions, decides which\n * have outlived their delay, and for each one that has not already been\n * delivered: admits a coalesced system event, sends it to the sink, and\n * journals the delivery. The admission comes first because it is idempotent\n * and the send is not: a crash between them costs a duplicate admission, which\n * the queue drops, while a crash between an accepted send and the delivery\n * record costs a duplicate PAGE, which is why {@link SinkService.deliver} is\n * required to dedupe on {@link alertId}.\n *\n * The policy is decoded when the layer is built, so a rule with an impossible\n * delay fails the composition by name instead of mis-paging at 3am.\n *\n * @param policy the rules to enforce\n * @category layers\n * @since 0.1.0\n */\nexport const layer = (\n  policy: Policy\n): Layer.Layer<AlertRuntime, never, Journal.Journal | NotificationQueue | Sink> =>\n  Layer.effect(\n    AlertRuntime,\n    Effect.gen(function*() {\n      const checked = yield* Effect.orDie(Schema.decodeUnknownEffect(Policy)(policy))\n      const detectors = detectorsOf(checked)\n      const journal = yield* Journal.Journal\n      const queue = yield* NotificationQueue\n      const sink = yield* Sink\n      // Folded history per run, so a tick costs the entries committed since\n      // the previous one rather than the run's whole journal.\n      const watched = FoldCache.make<Watched>(maximumWatchedRuns)\n\n      const observed = (runId: JournalEvent.RunId): Effect.Effect<Watched, Journal.JournalError> =>\n        Effect.gen(function*() {\n          const base: Watched = watched.get(runId) ??\n            { open: new Map(), delivered: HashSet.empty(), cursor: undefined }\n          const fresh: Array<JournalEvent.Entry> = []\n          let after = base.cursor === undefined ? undefined : JournalEvent.Seq.make(base.cursor)\n          while (true) {\n            const page = yield* journal.entries({ runId, ...(after === undefined ? {} : { after }), limit: 512 })\n            fresh.push(...page.entries)\n            if (!page.hasMore || page.entries.length === 0) break\n            after = page.entries.at(-1)!.seq\n          }\n          if (fresh.length === 0) return base\n\n          // `open` is bounded by the policy's rules, so it is copied; the\n          // delivery history is not, so it grows by one persistent node.\n          const open = new Map(base.open)\n          let delivered = base.delivered\n          let cursor = base.cursor\n          for (const entry of fresh) {\n            cursor = entry.seq\n            const payload = payloadRecord(entry.payload)\n            if (payload === undefined) continue\n            if (entry.eventType === deliveredEventType) {\n              const id = payload[\"alertId\"]\n              // Only a record under the source the alerter writes counts, so\n              // another producer's delivered record cannot suppress a page.\n              // The journal does not bind a source to a writer.\n              if (typeof id === \"string\" && entry.sourceId === recordSourceId(id, \"delivered\")) {\n                delivered = HashSet.add(delivered, id)\n              }\n            }\n            observe(checked, detectors, entry, payload, open)\n          }\n          const next: Watched = { open, delivered, cursor }\n          // Published at commit, exactly as `NotificationQueue.load` publishes\n          // its fold. A tick inside an enclosing transaction reads that\n          // transaction's uncommitted rows, and caching them would outlive the\n          // rollback that erased them: the run would page about a condition\n          // durable history never held.\n          yield* journal.whenCommitted(Effect.sync(() => watched.put(runId, next)))\n          return next\n        })\n\n      const record = (\n        eventType: string,\n        alert: Alert,\n        source: string,\n        outcome: { readonly code?: string | undefined; readonly status?: number | undefined }\n      ): Effect.Effect<void, Journal.JournalError> =>\n        journal.emitDurableUnfenced(\n          new JournalEvent.Input({\n            runId: JournalEvent.RunId.make(alert.runId),\n            sourceId: JournalEvent.SourceId.make(recordSourceId(alertId(alert), source)),\n            sourceSeq: JournalEvent.SourceSeq.make(0),\n            // One record per alert per outcome. Without an explicit identity\n            // the journal allocates a new sequence on every attempt, and a\n            // webhook that stays down appends a row per tick forever.\n            dedupe: \"identity\",\n            eventType,\n            payload: {\n              runId: alert.runId,\n              condition: alert.condition,\n              since: alert.since,\n              severity: alert.severity,\n              alertId: alertId(alert),\n              ...(outcome.code === undefined ? {} : { code: outcome.code }),\n              ...(outcome.status === undefined ? {} : { status: outcome.status })\n            }\n          })\n        ).pipe(Effect.asVoid)\n\n      return AlertRuntime.of({\n        tick: Effect.fn(\"AlertRuntime.tick\")(function*(runId: string) {\n          const journalRunId = JournalEvent.RunId.make(runId)\n          const history = yield* observed(journalRunId)\n          const now = yield* Clock.currentTimeMillis\n          const open = Array.from(history.open, ([condition, since]) => ({ runId, condition, since }))\n          const raised = decide(checked, open, now)\n          const delivered: Array<Alert> = []\n          const failed: Array<Alert> = []\n          const refused: Array<Alert> = []\n          const suppressed: Array<Alert> = []\n          for (const alert of raised) {\n            if (HashSet.has(history.delivered, alertId(alert))) {\n              suppressed.push(alert)\n              continue\n            }\n            // Raised unchanged: a queue that rejects the admission outright is\n            // not the journal failing, and calling it `sink_failed` would send\n            // an operator looking at the webhook.\n            const receipt = yield* queue.admit(runId, alertNotification(alert))\n            if (receipt.decision === \"rejected-full\") {\n              // The alert has nowhere durable to sit, so paging about it would\n              // tell an operator about something the run will never read.\n              yield* record(failedEventType, alert, \"refused\", { code: \"notification_full\" })\n              refused.push(alert)\n              continue\n            }\n            const outcome = yield* Effect.result(sink.deliver(alert))\n            if (Result.isFailure(outcome)) {\n              yield* record(failedEventType, alert, `failed/${outcome.failure.code}`, {\n                code: outcome.failure.code,\n                status: outcome.failure.status\n              })\n              failed.push(alert)\n            } else {\n              yield* record(deliveredEventType, alert, \"delivered\", {})\n              delivered.push(alert)\n            }\n          }\n          return { delivered, failed, refused, suppressed }\n        })\n      })\n    })\n  )\n"]}

package/dist/esm/AlertSink.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The alert sink port: where a raised alert is sent, and why a send failed.
+ *
+ * The port is a tag and an error so a deployment supplies the transport and
+ * the policy needs none. `./layerWebhook.ts` is the transport this package
+ * ships, and {@link layerNoop} is the one a test composes.
+ *
+ * @since 1.0.0
+ */
+import { Context, Effect, Layer, Schema } from "effect";
+import type { Alert } from "./AlertPolicy.ts";
+/**
+ * Why a sink did not take an alert.
+ *
+ * `sink_rejected` is an answer that refused the page, `sink_unreachable` a
+ * request that never got one, and `sink_timeout` one that got no answer inside
+ * the sink's bound. `sink_misconfigured` is an endpoint the sink may not POST
+ * to at all; it is raised when the layer is built, before any alert exists,
+ * so it never reaches a journal.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const FailureCode: Schema.Literals<readonly ["sink_rejected", "sink_unreachable", "sink_timeout", "sink_misconfigured"]>;
+/**
+ * Why a sink did not take an alert.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type FailureCode = typeof FailureCode.Type;
+declare const AlertError_base: Schema.Class<AlertError, Schema.TaggedStruct<"/notifications/AlertError", {
+    readonly code: Schema.withConstructorDefault<Schema.Literals<readonly ["sink_rejected", "sink_unreachable", "sink_timeout", "sink_misconfigured"]>>;
+    readonly message: Schema.String;
+    /** The HTTP status that refused the page, when the sink speaks HTTP. */
+    readonly status: Schema.optional<Schema.Int>;
+    /** A short, credential-free description of the transport failure. */
+    readonly reason: Schema.optional<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A sink refused or could not take an alert.
+ *
+ * The error carries a code, the answering status when there was one, and a
+ * short reason. It deliberately holds no request: a webhook request carries
+ * the credential the deployment handed {@link layerWebhook}, and an error is
+ * logged, encoded, and journaled in places a credential must never reach.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class AlertError extends AlertError_base {
+}
+/**
+ * Where a raised alert is sent.
+ *
+ * Injected rather than fixed, because who gets paged is a deployment's
+ * decision and the policy is not: the same rules feed a webhook in production
+ * and nothing at all in a test.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface SinkService {
+    /**
+     * Sends one alert, and does so idempotently on {@link alertId}.
+     *
+     * Delivery is at-least-once: the `flows.alerts.delivered` record is written
+     * after this effect succeeds, so a process that dies in between pages again
+     * on the next tick. Every field of the alert, {@link Alert.firedAt}
+     * included, is derived from the journal, so the same alert is byte-identical
+     * on every attempt and `alertId(alert)` is the deduplication key a receiving
+     * system should key on. A sink that cannot dedupe is a sink that will
+     * occasionally page twice about one condition.
+     *
+     * A failure means the page did not go out. Succeeding on a page that was
+     * dropped is the one thing this port must never do.
+     */
+    readonly deliver: (alert: Alert) => Effect.Effect<void, AlertError>;
+}
+declare const Sink_base: Context.ServiceClass<Sink, "/notifications/AlertSink", SinkService>;
+/**
+ * The {@link SinkService} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class Sink extends Sink_base {
+}
+/**
+ * A sink that accepts every alert and sends it nowhere.
+ *
+ * The admission and the delivery record still happen, so a composition without
+ * an outbound channel still has the durable evidence of what it would have
+ * paged about.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<Sink>;
+export {};
+//# sourceMappingURL=AlertSink.d.ts.map

package/dist/esm/AlertSink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlertSink.d.ts","sourceRoot":"","sources":["../../src/AlertSink.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,uGAA+F,CAAA;AAEvH;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;;;;IAkB7C,wEAAwE;;IAExE,qEAAqE;;;AAlBzE;;;;;;;;;;GAUG;AACH,qBAAa,UAAW,SAAQ,eAU/B;CAAG;AAEJ;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;CACpE;;AAED;;;;;GAKG;AACH,qBAAa,IAAK,SAAQ,SAAgE;CAAG;AAE7F;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAuD,CAAA"}

package/dist/esm/AlertSink.js

@@ -0,0 +1,63 @@
+/**
+ * The alert sink port: where a raised alert is sent, and why a send failed.
+ *
+ * The port is a tag and an error so a deployment supplies the transport and
+ * the policy needs none. `./layerWebhook.ts` is the transport this package
+ * ships, and {@link layerNoop} is the one a test composes.
+ *
+ * @since 1.0.0
+ */
+import { Context, Effect, Layer, Schema } from "effect";
+/**
+ * Why a sink did not take an alert.
+ *
+ * `sink_rejected` is an answer that refused the page, `sink_unreachable` a
+ * request that never got one, and `sink_timeout` one that got no answer inside
+ * the sink's bound. `sink_misconfigured` is an endpoint the sink may not POST
+ * to at all; it is raised when the layer is built, before any alert exists,
+ * so it never reaches a journal.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const FailureCode = Schema.Literals(["sink_rejected", "sink_unreachable", "sink_timeout", "sink_misconfigured"]);
+/**
+ * A sink refused or could not take an alert.
+ *
+ * The error carries a code, the answering status when there was one, and a
+ * short reason. It deliberately holds no request: a webhook request carries
+ * the credential the deployment handed {@link layerWebhook}, and an error is
+ * logged, encoded, and journaled in places a credential must never reach.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class AlertError extends Schema.TaggedError()("/notifications/AlertError", {
+    code: FailureCode.pipe(Schema.withConstructorDefault(Effect.succeed("sink_rejected"))),
+    message: Schema.String,
+    /** The HTTP status that refused the page, when the sink speaks HTTP. */
+    status: Schema.optional(Schema.Int),
+    /** A short, credential-free description of the transport failure. */
+    reason: Schema.optional(Schema.String)
+}) {
+}
+/**
+ * The {@link SinkService} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class Sink extends Context.Service()("/notifications/AlertSink") {
+}
+/**
+ * A sink that accepts every alert and sends it nowhere.
+ *
+ * The admission and the delivery record still happen, so a composition without
+ * an outbound channel still has the durable evidence of what it would have
+ * paged about.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = Layer.succeed(Sink)({ deliver: () => Effect.void });
+//# sourceMappingURL=AlertSink.js.map

package/dist/esm/AlertSink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlertSink.js","sourceRoot":"","sources":["../../src/AlertSink.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAGvD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,CAAC,CAAC,CAAA;AAUvH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,UAAW,SAAQ,MAAM,CAAC,WAAW,EAAc,CAC9D,2BAA2B,EAC3B;IACE,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,MAAM,CAAC,OAAO,CAAC,eAAwB,CAAC,CAAC,CAAC;IAC/F,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC;IACnC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CACvC,CACF;CAAG;AA8BJ;;;;;GAKG;AACH,MAAM,OAAO,IAAK,SAAQ,OAAO,CAAC,OAAO,EAAqB,CAAC,0BAA0B,CAAC;CAAG;AAE7F;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,SAAS,GAAsB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA","sourcesContent":["/**\n * The alert sink port: where a raised alert is sent, and why a send failed.\n *\n * The port is a tag and an error so a deployment supplies the transport and\n * the policy needs none. `./layerWebhook.ts` is the transport this package\n * ships, and {@link layerNoop} is the one a test composes.\n *\n * @since 1.0.0\n */\n\nimport { Context, Effect, Layer, Schema } from \"effect\"\nimport type { Alert } from \"./AlertPolicy.ts\"\n\n/**\n * Why a sink did not take an alert.\n *\n * `sink_rejected` is an answer that refused the page, `sink_unreachable` a\n * request that never got one, and `sink_timeout` one that got no answer inside\n * the sink's bound. `sink_misconfigured` is an endpoint the sink may not POST\n * to at all; it is raised when the layer is built, before any alert exists,\n * so it never reaches a journal.\n *\n * @category models\n * @since 1.0.0\n */\nexport const FailureCode = Schema.Literals([\"sink_rejected\", \"sink_unreachable\", \"sink_timeout\", \"sink_misconfigured\"])\n\n/**\n * Why a sink did not take an alert.\n *\n * @category models\n * @since 1.0.0\n */\nexport type FailureCode = typeof FailureCode.Type\n\n/**\n * A sink refused or could not take an alert.\n *\n * The error carries a code, the answering status when there was one, and a\n * short reason. It deliberately holds no request: a webhook request carries\n * the credential the deployment handed {@link layerWebhook}, and an error is\n * logged, encoded, and journaled in places a credential must never reach.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class AlertError extends Schema.TaggedError<AlertError>()(\n  \"/notifications/AlertError\",\n  {\n    code: FailureCode.pipe(Schema.withConstructorDefault(Effect.succeed(\"sink_rejected\" as const))),\n    message: Schema.String,\n    /** The HTTP status that refused the page, when the sink speaks HTTP. */\n    status: Schema.optional(Schema.Int),\n    /** A short, credential-free description of the transport failure. */\n    reason: Schema.optional(Schema.String)\n  }\n) {}\n\n/**\n * Where a raised alert is sent.\n *\n * Injected rather than fixed, because who gets paged is a deployment's\n * decision and the policy is not: the same rules feed a webhook in production\n * and nothing at all in a test.\n *\n * @category services\n * @since 0.1.0\n */\nexport interface SinkService {\n  /**\n   * Sends one alert, and does so idempotently on {@link alertId}.\n   *\n   * Delivery is at-least-once: the `flows.alerts.delivered` record is written\n   * after this effect succeeds, so a process that dies in between pages again\n   * on the next tick. Every field of the alert, {@link Alert.firedAt}\n   * included, is derived from the journal, so the same alert is byte-identical\n   * on every attempt and `alertId(alert)` is the deduplication key a receiving\n   * system should key on. A sink that cannot dedupe is a sink that will\n   * occasionally page twice about one condition.\n   *\n   * A failure means the page did not go out. Succeeding on a page that was\n   * dropped is the one thing this port must never do.\n   */\n  readonly deliver: (alert: Alert) => Effect.Effect<void, AlertError>\n}\n\n/**\n * The {@link SinkService} tag.\n *\n * @category services\n * @since 0.1.0\n */\nexport class Sink extends Context.Service<Sink, SinkService>()(\"/notifications/AlertSink\") {}\n\n/**\n * A sink that accepts every alert and sends it nowhere.\n *\n * The admission and the delivery record still happen, so a composition without\n * an outbound channel still has the durable evidence of what it would have\n * paged about.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop: Layer.Layer<Sink> = Layer.succeed(Sink)({ deliver: () => Effect.void })\n"]}

package/dist/esm/Alerts.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Alert policy: run conditions that have lasted too long, turned into durable,
+ * coalesced, delivered-once notifications.
+ *
+ * A notification queue answers "tell this run something". An alert answers the
+ * question nobody is around to ask: a run has been waiting for an approval for
+ * an hour, and the person who could grant it does not know. The two are the
+ * same machinery, since an alert is admitted as a coalesced system event, and
+ * they differ only in who decides to write one.
+ *
+ * ## Journal time, not wall time
+ *
+ * A condition's clock starts at the journal entry that opened it, which makes
+ * the decision replayable: the same journal produces the same alerts, whatever
+ * process reads it and whenever. A restart re-derives every open condition
+ * from the entries rather than from a timer it lost.
+ *
+ * ## Delivered at least once
+ *
+ * The admission is idempotent on the notification id, so re-admitting the same
+ * alert writes nothing new, and `flows.alerts.delivered` is journaled AFTER
+ * the sink accepted the page and is checked before the sink is called again.
+ * That ordering is deliberate and it is the reason the guarantee is
+ * at-least-once rather than exactly-once: a process that dies between the
+ * accepted send and the delivery record has paged, left no evidence of it, and
+ * will page again on the next tick. Recording the delivery first turns the
+ * same crash into a page nobody ever receives, which for an alert is the worse
+ * failure.
+ *
+ * So the sink owns the last mile: {@link SinkService.deliver} MUST be
+ * idempotent on {@link alertId}, which is stable for the life of one condition
+ * and reaches the sink on every alert it is handed. A sink that fails journals
+ * `flows.alerts.failed` once per failure code and the alert is retried on the
+ * next tick, because a refused page is not a delivered page.
+ *
+ * ## What a refusal costs
+ *
+ * The queue can refuse the admission when a run already holds its capacity of
+ * pending notifications. A tick that is refused pages nobody: the alert comes
+ * back in {@link Tick.refused}, the refusal is journaled, and the next tick
+ * tries again once a boundary has drained. Calling the sink anyway would page
+ * about an alert the run will never see.
+ *
+ * ## Conditions are data
+ *
+ * A condition is a payload field with a value: `status` is `waiting-approval`,
+ * `health` is `stalled`. Those are the fields control-plane entries and monitor
+ * beats already carry, so a deployment that journals a different vocabulary
+ * supplies its own detectors instead of a fork of this module.
+ *
+ * @since 0.1.0
+ */
+export { type Alert, alertId, coalescingKey, conditions, decide, defaultDetectors, deliveredEventType, Detector, failedEventType, type Open, Policy, Rule, Severity } from "./AlertPolicy.ts";
+export { AlertRuntime, layer, type RuntimeService, type Tick } from "./AlertRuntime.ts";
+export { AlertError, FailureCode, layerNoop, Sink, type SinkService } from "./AlertSink.ts";
+export { defaultWebhookTimeout, layerWebhook } from "./layerWebhook.ts";
+//# sourceMappingURL=Alerts.d.ts.map

package/dist/esm/Alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Alerts.d.ts","sourceRoot":"","sources":["../../src/Alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EACL,KAAK,KAAK,EACV,OAAO,EACP,aAAa,EACb,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,KAAK,IAAI,EACT,MAAM,EACN,IAAI,EACJ,QAAQ,EACT,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,cAAc,EAAE,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACvF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC3F,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/esm/Alerts.js

@@ -0,0 +1,57 @@
+/**
+ * Alert policy: run conditions that have lasted too long, turned into durable,
+ * coalesced, delivered-once notifications.
+ *
+ * A notification queue answers "tell this run something". An alert answers the
+ * question nobody is around to ask: a run has been waiting for an approval for
+ * an hour, and the person who could grant it does not know. The two are the
+ * same machinery, since an alert is admitted as a coalesced system event, and
+ * they differ only in who decides to write one.
+ *
+ * ## Journal time, not wall time
+ *
+ * A condition's clock starts at the journal entry that opened it, which makes
+ * the decision replayable: the same journal produces the same alerts, whatever
+ * process reads it and whenever. A restart re-derives every open condition
+ * from the entries rather than from a timer it lost.
+ *
+ * ## Delivered at least once
+ *
+ * The admission is idempotent on the notification id, so re-admitting the same
+ * alert writes nothing new, and `flows.alerts.delivered` is journaled AFTER
+ * the sink accepted the page and is checked before the sink is called again.
+ * That ordering is deliberate and it is the reason the guarantee is
+ * at-least-once rather than exactly-once: a process that dies between the
+ * accepted send and the delivery record has paged, left no evidence of it, and
+ * will page again on the next tick. Recording the delivery first turns the
+ * same crash into a page nobody ever receives, which for an alert is the worse
+ * failure.
+ *
+ * So the sink owns the last mile: {@link SinkService.deliver} MUST be
+ * idempotent on {@link alertId}, which is stable for the life of one condition
+ * and reaches the sink on every alert it is handed. A sink that fails journals
+ * `flows.alerts.failed` once per failure code and the alert is retried on the
+ * next tick, because a refused page is not a delivered page.
+ *
+ * ## What a refusal costs
+ *
+ * The queue can refuse the admission when a run already holds its capacity of
+ * pending notifications. A tick that is refused pages nobody: the alert comes
+ * back in {@link Tick.refused}, the refusal is journaled, and the next tick
+ * tries again once a boundary has drained. Calling the sink anyway would page
+ * about an alert the run will never see.
+ *
+ * ## Conditions are data
+ *
+ * A condition is a payload field with a value: `status` is `waiting-approval`,
+ * `health` is `stalled`. Those are the fields control-plane entries and monitor
+ * beats already carry, so a deployment that journals a different vocabulary
+ * supplies its own detectors instead of a fork of this module.
+ *
+ * @since 0.1.0
+ */
+export { alertId, coalescingKey, conditions, decide, defaultDetectors, deliveredEventType, Detector, failedEventType, Policy, Rule, Severity } from "./AlertPolicy.js";
+export { AlertRuntime, layer } from "./AlertRuntime.js";
+export { AlertError, FailureCode, layerNoop, Sink } from "./AlertSink.js";
+export { defaultWebhookTimeout, layerWebhook } from "./layerWebhook.js";
+//# sourceMappingURL=Alerts.js.map

package/dist/esm/Alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Alerts.js","sourceRoot":"","sources":["../../src/Alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAEL,OAAO,EACP,aAAa,EACb,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,eAAe,EAEf,MAAM,EACN,IAAI,EACJ,QAAQ,EACT,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,KAAK,EAAkC,MAAM,mBAAmB,CAAA;AACvF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAoB,MAAM,gBAAgB,CAAA;AAC3F,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA","sourcesContent":["/**\n * Alert policy: run conditions that have lasted too long, turned into durable,\n * coalesced, delivered-once notifications.\n *\n * A notification queue answers \"tell this run something\". An alert answers the\n * question nobody is around to ask: a run has been waiting for an approval for\n * an hour, and the person who could grant it does not know. The two are the\n * same machinery, since an alert is admitted as a coalesced system event, and\n * they differ only in who decides to write one.\n *\n * ## Journal time, not wall time\n *\n * A condition's clock starts at the journal entry that opened it, which makes\n * the decision replayable: the same journal produces the same alerts, whatever\n * process reads it and whenever. A restart re-derives every open condition\n * from the entries rather than from a timer it lost.\n *\n * ## Delivered at least once\n *\n * The admission is idempotent on the notification id, so re-admitting the same\n * alert writes nothing new, and `flows.alerts.delivered` is journaled AFTER\n * the sink accepted the page and is checked before the sink is called again.\n * That ordering is deliberate and it is the reason the guarantee is\n * at-least-once rather than exactly-once: a process that dies between the\n * accepted send and the delivery record has paged, left no evidence of it, and\n * will page again on the next tick. Recording the delivery first turns the\n * same crash into a page nobody ever receives, which for an alert is the worse\n * failure.\n *\n * So the sink owns the last mile: {@link SinkService.deliver} MUST be\n * idempotent on {@link alertId}, which is stable for the life of one condition\n * and reaches the sink on every alert it is handed. A sink that fails journals\n * `flows.alerts.failed` once per failure code and the alert is retried on the\n * next tick, because a refused page is not a delivered page.\n *\n * ## What a refusal costs\n *\n * The queue can refuse the admission when a run already holds its capacity of\n * pending notifications. A tick that is refused pages nobody: the alert comes\n * back in {@link Tick.refused}, the refusal is journaled, and the next tick\n * tries again once a boundary has drained. Calling the sink anyway would page\n * about an alert the run will never see.\n *\n * ## Conditions are data\n *\n * A condition is a payload field with a value: `status` is `waiting-approval`,\n * `health` is `stalled`. Those are the fields control-plane entries and monitor\n * beats already carry, so a deployment that journals a different vocabulary\n * supplies its own detectors instead of a fork of this module.\n *\n * @since 0.1.0\n */\n\nexport {\n  type Alert,\n  alertId,\n  coalescingKey,\n  conditions,\n  decide,\n  defaultDetectors,\n  deliveredEventType,\n  Detector,\n  failedEventType,\n  type Open,\n  Policy,\n  Rule,\n  Severity\n} from \"./AlertPolicy.ts\"\nexport { AlertRuntime, layer, type RuntimeService, type Tick } from \"./AlertRuntime.ts\"\nexport { AlertError, FailureCode, layerNoop, Sink, type SinkService } from \"./AlertSink.ts\"\nexport { defaultWebhookTimeout, layerWebhook } from \"./layerWebhook.ts\"\n"]}