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

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# @smthrs/notifications
+
+## [Unreleased]
+
+### Breaking Changes
+
+- `SteerPayload.decode` takes the notification instead of its payload and
+  answers `undefined` for every `system-event`. A webhook or system-event
+  producer whose payload carried a `body` string or a `kind` could otherwise be
+  read as an operator message, seat, thinking, or tools steer.
+- `NotificationEvent.fromEntry` reads an `Admitted` entry only under
+  `admissionSourceId` of the notification it carries, and a `Promoted` entry
+  only under a `/notifications/drain/` source, so another producer's record
+  with the same event type stays out of the projection. The source scopes
+  records; it does not authenticate the writer.
+- `NotificationQueue.admit` refuses a notification larger than 1,048,576 UTF-16
+  code units with `notification_invalid`, before copying or fingerprinting it.
+- `Alerts.defaultDetectors` consult only `control.*` event types, and a
+  `Detector.eventTypes` item ending in `.*` names a family. A
+  `flows.alerts.delivered` entry suppresses a page only under the source the
+  alerter writes.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Breaking Changes
+
+- `NotificationQueue.admit` decodes its argument against
+  `Notification.Notification` before it writes anything. A structurally invalid
+  value used to be acknowledged at a real journal sequence and then skipped by
+  every replay, which is acknowledged data loss. It now fails with
+  `notification_invalid` and the dotted path of the field that failed.
+- `NotificationQueue.NotificationError.code` gained
+  `notification_id_reused` and `notification_invalid`, and the error carries
+  `notificationId` and `path`. Reusing a stable id with different content used
+  to be raised as a `Journal.JournalError` with `idempotency_conflict`,
+  borrowing the storage layer's error type for a rule this package decides.
+- A full queue no longer journals its refusal. `admit` returns
+  `rejected-full` in the receipt alone, so the notification id stays admissible
+  once a boundary drains. A recorded refusal matched on every later attempt and
+  burned the id permanently, and no drain could ever free it.
+- `NotificationState.defaultCapacity` replaces `Projection.defaultCapacity`.
+  The bound is the queue's, not the read model's, and the queue no longer
+  depends on the projection module for it.
+- Admission and promotion records are written with `dedupe: "identity"`. Both
+  used to compare payload bytes, so two processes that loaded at different fill
+  levels failed the second writer over `decision`, a derived field neither
+  caller supplied.
+- `Alerts.AlertError` carries `code`, `status`, and `reason` instead of
+  `cause`. The cause was the `HttpClientError`, which holds the request, which
+  holds the credential a deployment handed `layerWebhook`.
+- `Alerts.Rule.afterMs` is a whole, non-negative number of milliseconds, and
+  `Alerts.layer` decodes the whole policy when the layer is built. `NaN` fired
+  on the first tick and stamped a `firedAt` that JSON wrote as `null`; a
+  negative delay fired with a `firedAt` earlier than the condition it described.
+
+### Fixed
+
+- A drain's journal identity is now the lineage and the boundary, each
+  percent-encoded. It was keyed on the boundary alone while the duplicate read
+  required both, so a second lineage draining the same boundary name on one run
+  failed with `idempotency_conflict` and its notifications stayed pending.
+- `admit` and `drain` return the decision the journal committed, read back
+  after the write, rather than the value this process computed before it.
+- `admit`, `drain`, `pending`, and `Alerts.tick` fold a run once and then page
+  only the entries committed since. Every call used to re-page and re-decode
+  the run's entire journal, twice in `admit` and `drain`, making the cost
+  quadratic in journal length. Each layer keeps the 64 most recently read runs.
+- `Alerts` records one journal entry per alert per outcome. Failures were
+  written with no `sourceSeq`, so the journal allocated a new sequence on every
+  attempt and a webhook that stayed down appended a row per tick forever.
+- `Alerts.tick` reads the admission receipt. An alert the queue refused is
+  reported in the new `Alerts.Tick.refused`, the sink is not called, and no
+  delivery is recorded, so nobody is paged about an alert the run cannot read.
+- `Alerts.conditions` tests a detector's field with `Object.hasOwn`. `in` walks
+  `Object.prototype`, so a detector named `toString` or `constructor` read
+  every record-shaped entry in the run as evidence and closed the condition on
+  all of them, silently preventing the alert from ever firing.
+- `Alerts.layerWebhook` bounds its request with `defaultWebhookTimeout`, ten
+  seconds by default. An endpoint that accepted the connection and never
+  answered stalled a run's whole alert runtime.
+- `Alerts.coalescingKey` percent-encodes each component, so a run id or a
+  condition name containing the separator can no longer forge another pair's
+  key and suppress an unrelated page.
+- `SteerPayload.encode` copies a `Tools` item's `toolNames`. The returned
+  record shared the caller's array with an admission that serializes it later.
+
+### Added
+
+- `NotificationQueue.layerWith({ capacity })` serves the same layer at a bound
+  the composition chooses. The capacity used to be a constant no deployment
+  could raise.
+- `NotificationQueue.DrainInput.cutoffSeq` carries the journal sequence that
+  opened a turn. `NotificationState.promoteSteers` documented that a steer
+  admitted after the cutoff is held for the next boundary, and the layer could
+  never express it: the cutoff was the last sequence it had just read, so every
+  pending steer always satisfied it.
+- `NotificationEvent.AdmissionDecision` is the one declaration of the admission
+  vocabulary, exported as both a schema and a type, and `NotificationState`
+  re-exports it. The two used to be independent declarations that a fourth
+  decision could silently desynchronize.
+- `NotificationEvent.isAdmitted` and `NotificationEvent.isPromoted` give the
+  untagged owned-event union one named discriminator, replacing three separate
+  property-presence checks.
+- `Alerts.FailureCode`, `Alerts.coalescingKey`, and
+  `Alerts.defaultWebhookTimeout` are public.
+- The webhook sink sends `alertId` in the body and as an `Idempotency-Key`
+  header. The package requires the receiver to dedupe on that id, and the body
+  did not carry it.
+- Package-owned documentation under `docs/`, generated into
+  `docs/pages/api/notifications.md` by the `docsPages` target, plus this
+  changelog, which `package.json` already declared in `files`.
+
+### Changed
+
+- The durable event types stay spelled `flows/notifications/Admitted` and
+  `flows/notifications/Promoted`, which is slashes and a PascalCase leaf where
+  every other event type in the repository is dot-separated and lowercase. The
+  values are already durable in every engine database and a rename would
+  silently stop matching consumer projections, so both spellings are frozen by
+  `test/WireFormat.test.ts` and the divergence is stated in their JSDoc.
+- `SteerPayload.decode` still reads a record carrying a `body` string and no
+  `kind` as a message, but the reason is now stated correctly: it is the shape
+  a minimal caller writes, and the steer RPC accepts the same one. The previous
+  rationale claimed the branch existed for payloads written before the
+  vocabulary, which rc.0 cannot hold because it never loads a 0.x database.
+- Retired the 45 internal `@slop` review markers that shipped in `src` and in
+  the published `.d.ts`, writing the sentence each one stood in for.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @smthrs/notifications
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact `4.0.5` peer dependency. Install one
+`effect` release at that version so all Smithers packages share one Effect
+runtime.
+
+**Documentation:** https://github.com/smithersai/smithers/tree/main/packages/smithers/notifications/docs
+
+Durable notification queue, admission policy, and journal projection for flows. It models human and system notifications, derives queue state from journal events, and drains eligible work at harness boundaries.
+
+```bash
+npm install @smthrs/notifications@next effect
+```
+
+Node.js 26.4.0 or later. `@smthrs/journal` holds the durable records, and the
+example below imports it directly, so declare it in your own package too.
+
+## Public API
+
+The root entry point exports these namespaces; each is also importable from `@smthrs/notifications/<Module>`.
+
+| Module              | Description                                                                               |
+| ------------------- | ----------------------------------------------------------------------------------------- |
+| `Alerts`            | Turns run conditions that outlive a delay into coalesced, at-least-once alerts.           |
+| `Notification`      | Defines notification schemas, admission classes, and coalescing keys.                     |
+| `NotificationEvent` | Defines journal notification events and decodes them from journal entries.                |
+| `NotificationQueue` | Defines the durable admit/drain/pending service and its journal-backed layer.             |
+| `NotificationState` | Implements the pure notification admission and promotion state machine.                   |
+| `Projection`        | Derives notification state from journal entries.                                          |
+| `SteerPayload`      | Defines the steering vocabulary a control plane and a harness exchange through a payload. |
+
+Every export of every module, with its signature and the meaning of each
+parameter, is on
+[the API reference](https://github.com/smithersai/smithers/blob/main/packages/smithers/notifications/docs/api.md). This file
+deliberately does not repeat it.
+
+## What a caller has to know
+
+- A caller MUST read `AdmissionReceipt.decision`. `rejected-full` means the run
+  already holds `NotificationState.defaultCapacity` pending notifications, so
+  the queue retained nothing and wrote no journal entry. The id stays
+  admissible, and the caller admits it again once a boundary has drained.
+  `admit` does not fail on a full queue. `NotificationQueue.layerWith` raises
+  or lowers the bound for one composition.
+- `targetLineageId` is the address of whatever will read the notification: the
+  run, or one branch of it that closes turns of its own. The queue treats it as
+  an opaque string and only compares it for equality, so pass the run id when a
+  run has one reader and the branch's id when it has several.
+- The unit of drain is the triple `(runId, targetLineageId, boundary)`. Two
+  addresses closing a turn under the same boundary name are two drains, recorded
+  separately. `DrainInput.cutoffSeq` holds a steer admitted mid-turn until the
+  next boundary.
+- `NotificationError.code` is the stable half to branch on:
+  `notification_unavailable`, `notification_id_reused`, and
+  `notification_invalid`. Storage failures arrive as `Journal.JournalError`.
+- `admit` decodes and snapshots its argument, so nothing the caller mutates
+  afterwards changes what was journaled.
+- An alert sink must be idempotent on `Alerts.alertId`, which the webhook sink
+  sends in the body and as an `Idempotency-Key` header. That sink bounds every
+  request with `Alerts.defaultWebhookTimeout`, and `Alerts.AlertError` reports
+  `sink_rejected`, `sink_unreachable`, or `sink_timeout` and never carries the
+  request or its credentials.
+- A layer folds each run's journal once and then pages only what has been
+  committed since, keeping the 64 most recently read runs.
+
+```ts
+import * as TestJournal from "@smthrs/journal/test/TestJournal"
+import { NotificationQueue } from "@smthrs/notifications"
+import { Effect } from "effect"
+
+const program = Effect.gen(function*() {
+  const queue = yield* NotificationQueue.NotificationQueue
+  return yield* queue.drain({
+    runId: "run-1",
+    targetLineageId: "run-1/root",
+    boundary: "turn-1",
+    wouldIdle: true
+  })
+}).pipe(
+  Effect.provide(NotificationQueue.layer),
+  // A real SQLite journal over an in-memory database. Swap in `SqlJournal.layer`
+  // over a file for a deployment.
+  Effect.provide(TestJournal.layer()),
+  Effect.scoped
+)
+```
+
+`NotificationQueue.layerNoop()` provides the same seam with every method failing as
+`notification_unavailable`, for a composition that means to serve nothing.
+`@smthrs/notifications/package.json` is also exported; `internal/*` and nested `*/index` subpaths are blocked.
+
+A replayed drain fails with `notification_unavailable` if a committed notification or its payload can no longer be read. It never reports a successful partial delivery.

package/dist/cjs/AlertPolicy.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Alert policy: what a condition is, when a journal leaves one open, and
+ * which open conditions have outlived their delay.
+ *
+ * Everything here is pure and a function of journal time, so the same entries
+ * decide the same alerts in any process at any instant past the delay. The
+ * transport that pages about them is `./layerWebhook.ts` and the journal-backed
+ * tick that drives them is `./AlertRuntime.ts`; `./Alerts.ts` is the module a
+ * consumer imports.
+ *
+ * @since 1.0.0
+ */
+import type { JournalEvent } from "@smthrs/journal";
+import { Schema } from "effect";
+/**
+ * The journal event type one delivered alert is recorded under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const deliveredEventType = "flows.alerts.delivered";
+/**
+ * The journal event type one failed delivery attempt is recorded under.
+ *
+ * One entry is written per alert per failure code, never one per tick: a
+ * webhook that stays down for an hour leaves one record, not a hundred and
+ * twenty that every later tick has to read past.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const failedEventType = "flows.alerts.failed";
+/**
+ * How loud an alert is.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Severity: Schema.Literals<readonly ["info", "warning", "critical"]>;
+/**
+ * How loud an alert is.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Severity = typeof Severity.Type;
+/**
+ * How a condition is recognized in the journal.
+ *
+ * `field` names a payload key, `value` the value that means the condition
+ * holds, and `eventTypes` narrows which entries are consulted at all. An
+ * `eventTypes` item ending in `.*` names a family: `control.*` consults
+ * `control.run.parked` and `control.monitor.beat` alike. An entry that carries
+ * the field with a different value CLOSES the condition, which is what makes a
+ * resume clear an approval alert without a second vocabulary for "cleared".
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Detector: Schema.Struct<{
+    readonly field: Schema.NonEmptyString;
+    readonly value: Schema.NonEmptyString;
+    readonly eventTypes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>;
+/**
+ * How a condition is recognized in the journal.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Detector = typeof Detector.Type;
+/**
+ * What to do about one condition, and after how long.
+ *
+ * `afterMs` is a whole, non-negative number of milliseconds. The bound is the
+ * schema's job because the delay is also arithmetic on journal time: a `NaN`
+ * delay fires on the first tick and stamps a `firedAt` that JSON writes as
+ * `null`, and a negative one fires with a `firedAt` earlier than the condition
+ * it describes.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Rule: Schema.Struct<{
+    readonly afterMs: Schema.Int;
+    readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+    readonly owner: Schema.optional<Schema.String>;
+    readonly runbook: Schema.optional<Schema.String>;
+}>;
+/**
+ * What to do about one condition, and after how long.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Rule = typeof Rule.Type;
+/**
+ * The conditions a policy alerts on and the delays it alerts after.
+ *
+ * `defaults` fills in what a rule leaves out, so a policy states the delay per
+ * condition and the ownership once.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Policy: Schema.Struct<{
+    readonly defaults: Schema.optional<Schema.Struct<{
+        readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+        readonly owner: Schema.optional<Schema.String>;
+        readonly runbook: Schema.optional<Schema.String>;
+    }>>;
+    readonly rules: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly afterMs: Schema.Int;
+        readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+        readonly owner: Schema.optional<Schema.String>;
+        readonly runbook: Schema.optional<Schema.String>;
+    }>>;
+    /** Detectors for conditions this deployment names itself. */
+    readonly detectors: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly field: Schema.NonEmptyString;
+        readonly value: Schema.NonEmptyString;
+        readonly eventTypes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>>>;
+}>;
+/**
+ * The conditions a policy alerts on and the delays it alerts after.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Policy = typeof Policy.Type;
+/**
+ * The four conditions a control plane journals out of the box.
+ *
+ * `status` rides on every `control.run.*` entry, and `health` on every
+ * `control.monitor.beat`. A deployment whose supervisor journals a park reason
+ * gets `quota-parked` from the same field the run summary reports it under.
+ *
+ * Each consults the `control.*` family only. A run's journal is shared with
+ * flow steps, agent traces, and anything else that writes to the run, and a
+ * `status` or `health` field on one of those entries would otherwise open or
+ * close a condition the control plane never reported.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultDetectors: Readonly<Record<string, Detector>>;
+/**
+ * A condition that is open on a run, and when it opened.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Open {
+    readonly runId: string;
+    readonly condition: string;
+    /** The journal time of the entry that opened the condition. */
+    readonly since: number;
+}
+/**
+ * One alert a policy decided to raise.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Alert {
+    readonly runId: string;
+    readonly condition: string;
+    readonly since: number;
+    /**
+     * The journal instant the condition outlived its delay: `since` plus the
+     * rule's `afterMs`, never the wall clock of whichever tick noticed.
+     */
+    readonly firedAt: number;
+    readonly severity: Severity;
+    readonly coalescingKey: string;
+    readonly owner?: string | undefined;
+    readonly runbook?: string | undefined;
+}
+/**
+ * The journal source the alerter writes one outcome of one alert under.
+ *
+ * A delivery record counts as evidence that an alert went out only under this
+ * source, so another producer's `flows.alerts.delivered` record with a
+ * matching `alertId` does not suppress a page. This scopes records; it does
+ * not authenticate the writer, because the journal does not bind a source to
+ * a writer.
+ *
+ * @param id the alert's {@link alertId}
+ * @param outcome `delivered`, `refused`, or `failed/<code>`
+ * @private
+ * @since 1.0.0
+ */
+export declare const recordSourceId: (id: string, outcome: string) => string;
+/**
+ * The key an alert coalesces on: one open condition on one run.
+ *
+ * Each component is percent-encoded before it is joined, so a run id or a
+ * condition name containing the separator cannot forge another pair's key and
+ * suppress a page that belongs to somebody else. Both components are values a
+ * deployment chooses, which is why the encoding is not optional.
+ *
+ * @param runId the run the condition is open on
+ * @param condition the condition name the policy uses
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const coalescingKey: (runId: string, condition: string) => string;
+/**
+ * The identity a delivery is recorded under.
+ *
+ * The opening time is part of it on purpose. A condition that clears and
+ * re-opens is a NEW alert, because the second approval wait is not the first
+ * one, and a key without the time would suppress it forever.
+ *
+ * @param alert the alert
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const alertId: (alert: Pick<Alert, "coalescingKey" | "since">) => string;
+/**
+ * The detectors one policy decides with: the four this package ships, with
+ * the deployment's own overriding them by name.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const detectorsOf: (policy: Policy) => Readonly<Record<string, Detector>>;
+/**
+ * One entry's payload when it is a record a detector can read a field off,
+ * and `undefined` for the arrays and primitives that carry no fields at all.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const payloadRecord: (payload: unknown) => Readonly<Record<string, unknown>> | undefined;
+/**
+ * Folds one entry into the open-condition map. Shared by {@link conditions}
+ * and the runtime's incremental read, so both decide a condition the same
+ * way.
+ *
+ * The alerter's own records are never evidence about a condition. They are
+ * written into the same journal they are read from, and they carry the alert's
+ * own vocabulary: a refusal reports the answering HTTP `status`, which a
+ * detector watching the run's `status` would read as the condition clearing.
+ * A page would then close the condition it paged about and the next tick would
+ * re-open it, so a webhook that answered 503 once would alert forever.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const observe: (policy: Policy, detectors: Readonly<Record<string, Detector>>, entry: JournalEvent.Entry, payload: Readonly<Record<string, unknown>>, open: Map<string, number>) => void;
+/**
+ * Every condition a run's journal leaves open, with the time each opened.
+ *
+ * An entry that carries a detector's field opens the condition when the value
+ * matches and closes it when it does not. Entries the detector does not name
+ * are ignored entirely, so a monitor beat cannot close an approval wait and an
+ * approval cannot close a stall.
+ *
+ * @param policy the policy whose detectors decide what counts
+ * @param runId the run the entries belong to
+ * @param entries the run's journal, oldest first
+ * @category projections
+ * @since 0.1.0
+ */
+export declare const conditions: (policy: Policy, runId: string, entries: ReadonlyArray<JournalEvent.Entry>) => ReadonlyArray<Open>;
+/**
+ * The alerts a policy raises for the conditions open at `now`.
+ *
+ * Pure, and a function of journal time: the same journal raises the same
+ * alerts in any process, at any instant past the delay. `now` decides WHETHER
+ * an alert is raised; it never appears in one. A condition that has been open
+ * for less than its rule's delay raises nothing, which is the whole point of
+ * the delay, because most stalls clear themselves.
+ *
+ * @param policy the policy
+ * @param open the conditions the journal left open
+ * @param now the instant to judge them at
+ * @category projections
+ * @since 0.1.0
+ */
+export declare const decide: (policy: Policy, open: ReadonlyArray<Open>, now: number) => ReadonlyArray<Alert>;
+//# sourceMappingURL=AlertPolicy.d.ts.map

package/dist/cjs/AlertPolicy.d.ts.map

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

package/dist/cjs/AlertPolicy.js

@@ -0,0 +1,124 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var AlertPolicy_exports = {};
+__export(AlertPolicy_exports, {
+  Detector: () => Detector,
+  Policy: () => Policy,
+  Rule: () => Rule,
+  Severity: () => Severity,
+  alertId: () => alertId,
+  coalescingKey: () => coalescingKey,
+  conditions: () => conditions,
+  decide: () => decide,
+  defaultDetectors: () => defaultDetectors,
+  deliveredEventType: () => deliveredEventType,
+  detectorsOf: () => detectorsOf,
+  failedEventType: () => failedEventType,
+  observe: () => observe,
+  payloadRecord: () => payloadRecord,
+  recordSourceId: () => recordSourceId
+});
+module.exports = __toCommonJS(AlertPolicy_exports);
+var import_effect = require("effect");
+const deliveredEventType = "flows.alerts.delivered";
+const failedEventType = "flows.alerts.failed";
+const Severity = import_effect.Schema.Literals(["info", "warning", "critical"]);
+const Detector = import_effect.Schema.Struct({
+  field: import_effect.Schema.NonEmptyString,
+  value: import_effect.Schema.NonEmptyString,
+  eventTypes: import_effect.Schema.optional(import_effect.Schema.Array(import_effect.Schema.NonEmptyString))
+});
+const Rule = import_effect.Schema.Struct({
+  afterMs: import_effect.Schema.Int.pipe(import_effect.Schema.check(import_effect.Schema.isGreaterThanOrEqualTo(0))),
+  severity: import_effect.Schema.optional(Severity),
+  owner: import_effect.Schema.optional(import_effect.Schema.String),
+  runbook: import_effect.Schema.optional(import_effect.Schema.String)
+});
+const Policy = import_effect.Schema.Struct({
+  defaults: import_effect.Schema.optional(import_effect.Schema.Struct({
+    severity: import_effect.Schema.optional(Severity),
+    owner: import_effect.Schema.optional(import_effect.Schema.String),
+    runbook: import_effect.Schema.optional(import_effect.Schema.String)
+  })),
+  rules: import_effect.Schema.Record(import_effect.Schema.String, Rule),
+  /** Detectors for conditions this deployment names itself. */
+  detectors: import_effect.Schema.optional(import_effect.Schema.Record(import_effect.Schema.String, Detector))
+});
+const defaultDetectors = {
+  "waiting-approval": { field: "status", value: "waiting-approval", eventTypes: ["control.*"] },
+  failed: { field: "status", value: "failed", eventTypes: ["control.*"] },
+  stalled: { field: "health", value: "stalled", eventTypes: ["control.*"] },
+  "quota-parked": { field: "waitingReason", value: "quota", eventTypes: ["control.*"] }
+};
+const names = (eventTypes, eventType) => eventTypes.some((named) => named.endsWith(".*") ? eventType.startsWith(named.slice(0, -1)) : named === eventType);
+const recordSourceId = (id, outcome) => `/notifications/alerts/${id}/${outcome}`;
+const coalescingKey = (runId, condition) => `${encodeURIComponent(runId)}:${encodeURIComponent(condition)}`;
+const alertId = (alert) => `alert:${alert.coalescingKey}:${alert.since}`;
+const detectorsOf = (policy) => ({
+  ...defaultDetectors,
+  ...policy.detectors
+});
+const payloadRecord = (payload) => typeof payload === "object" && payload !== null && !Array.isArray(payload) ? payload : void 0;
+const observe = (policy, detectors, entry, payload, open) => {
+  if (entry.eventType === deliveredEventType || entry.eventType === failedEventType) return;
+  for (const condition of Object.keys(policy.rules)) {
+    const detector = detectors[condition];
+    if (detector === void 0) continue;
+    if (detector.eventTypes !== void 0 && !names(detector.eventTypes, entry.eventType)) continue;
+    if (!Object.hasOwn(payload, detector.field)) continue;
+    if (payload[detector.field] === detector.value) {
+      if (!open.has(condition)) open.set(condition, entry.emittedAtMs);
+    } else {
+      open.delete(condition);
+    }
+  }
+};
+const conditions = (policy, runId, entries) => {
+  const detectors = detectorsOf(policy);
+  const open = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const payload = payloadRecord(entry.payload);
+    if (payload === void 0) continue;
+    observe(policy, detectors, entry, payload, open);
+  }
+  return Array.from(open, ([condition, since]) => ({ runId, condition, since }));
+};
+const decide = (policy, open, now) => open.flatMap((condition) => {
+  const rule = policy.rules[condition.condition];
+  if (rule === void 0) return [];
+  if (now - condition.since < rule.afterMs) return [];
+  const severity = rule.severity ?? policy.defaults?.severity ?? "warning";
+  const owner = rule.owner ?? policy.defaults?.owner;
+  const runbook = rule.runbook ?? policy.defaults?.runbook;
+  return [{
+    runId: condition.runId,
+    condition: condition.condition,
+    since: condition.since,
+    // Derived from the journal, not read off the clock. The alert id is
+    // stable across ticks, and the queue refuses a reused id whose content
+    // changed, so an alert stamped with the reading time would become
+    // permanently undeliverable the moment a tick refused and time moved on.
+    firedAt: condition.since + rule.afterMs,
+    severity,
+    coalescingKey: coalescingKey(condition.runId, condition.condition),
+    ...owner === void 0 ? {} : { owner },
+    ...runbook === void 0 ? {} : { runbook }
+  }];
+});
+//# sourceMappingURL=AlertPolicy.js.map