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

package/docs/guides/report-pending-notifications.md

@@ -0,0 +1,92 @@
+---
+title: "Report what a run is waiting on"
+description: "Read a run's undelivered notifications with NotificationQueue.pending, count steers for a run listing, and choose between the live read and the journal projection."
+sidebar:
+  order: 4
+---
+
+Pending is admitted minus promoted, and the queue owns both halves. A supervisor
+that counted admissions alone would report a steer as waiting forever.
+
+## Read the live answer
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+
+export const pendingSteers = (runId: string) =>
+  Effect.gen(function*() {
+    const queue = yield* NotificationQueue.NotificationQueue
+    const pending = yield* queue.pending(runId)
+    return pending.filter((notification) => notification.delivery === "steer").length
+  })
+```
+
+`pending` returns the notifications in admission order, across every lineage of
+the run. It reads the same fold `drain` uses, so nothing can disagree with what
+the next boundary will see.
+
+The read does not take the queue's operation lock. A count taken while a
+boundary drains is a count taken at some instant either side of it, and blocking
+a supervisor behind a turn boundary would be the worse answer.
+
+## Treat unavailability as unknown, not as zero
+
+A control plane that lists runs annotates each one with its pending steer count.
+When the queue is unavailable, the honest report is that the count is not known:
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+
+export const steeringFor = (runId: string) =>
+  Effect.gen(function*() {
+    const queue = yield* NotificationQueue.NotificationQueue
+    const pending = yield* queue.pending(runId)
+    return Option.some(pending.filter((notification) => notification.delivery === "steer").length)
+  }).pipe(
+    Effect.catchTag("/notifications/NotificationError", () => Effect.succeed(Option.none<number>()))
+  )
+```
+
+Catch the queue's own `NotificationError` and leave the field absent. Do not
+catch the `Journal.JournalError`: a journal that fails is a failed listing, not
+an unknown count, and reporting zero would tell an operator that nobody is
+waiting.
+
+## Live read or projection
+
+Both answer the same question from the same records:
+
+|            | `NotificationQueue.pending`                   | `Projection.derive`                                               |
+| ---------- | --------------------------------------------- | ----------------------------------------------------------------- |
+| Shape      | One `Effect` per call.                        | A `Stream` that replays and then follows.                         |
+| Needs      | The queue service.                            | A journal, and nothing else.                                      |
+| Capacity   | Whatever the layer was built at.              | Reports `NotificationState.defaultCapacity`, and replays past it. |
+| Use it for | An answer now: a listing, an RPC, a decision. | A live view that must stay correct as entries arrive.             |
+
+Use `pending` for a request. Use the projection for a feed: it replays what
+every admission record committed, so it stays correct at a raised bound even
+though the `capacity` it reports is the default. See
+[the journal records](../concepts/journal-records.md).
+
+## Look at a pending notification
+
+The values are full notifications, so a caller can report more than a count:
+
+```ts
+import type { Notification } from "@smthrs/notifications/Notification"
+
+const describe = (notification: Notification) => ({
+  id: notification.id,
+  lineage: notification.targetLineageId,
+  from: notification.provenance.sourceActor,
+  urgent: notification.delivery === "steer",
+  coalescing: notification._tag === "system-event" ? notification.coalescingKey : undefined
+})
+```
+
+A pending alert is a `system-event` whose `coalescingKey` is
+`Alerts.coalescingKey(runId, condition)`, which is how a UI groups repeated
+reports of one condition into one row.

package/docs/guides/send-alerts-to-a-webhook.md

@@ -0,0 +1,155 @@
+---
+title: "Send alerts to a webhook"
+description: "Point the shipped webhook sink at an endpoint, set its headers and timeout, read the failure codes it reports, and write your own sink when the endpoint is not HTTP."
+sidebar:
+  order: 6
+---
+
+`Alerts.layerWebhook` POSTs each alert to one endpoint. It is the shipped
+implementation of `Alerts.Sink`. It constructs its own Fetch HTTP client.
+
+## Point it at an endpoint
+
+```ts
+import { Alerts, NotificationQueue } from "@smthrs/notifications"
+import * as Duration from "effect/Duration"
+import * as Layer from "effect/Layer"
+
+const sink = (token: string) =>
+  Alerts.layerWebhook({
+    url: "https://pager.example/alerts",
+    headers: { authorization: `Bearer ${token}` },
+    timeout: Duration.seconds(5)
+  })
+
+export const alerting = (policy: Alerts.Policy, token: string) =>
+  Alerts.layer(policy).pipe(
+    Layer.provideMerge(Layer.mergeAll(NotificationQueue.layer, sink(token)))
+  )
+```
+
+`headers` is merged into every request. `timeout` defaults to
+`Alerts.defaultWebhookTimeout`, ten seconds. An endpoint that never answers is a
+failure at that bound, because a hung page is indistinguishable from silence and
+waiting on one forever is not an option a pager may take.
+
+`url` must be an absolute `http:` or `https:` url. It is checked when the layer
+is built, so a `file:` or `javascript:` endpoint is a defect that fails the
+composition with `sink_misconfigured` rather than a delivery failure at 3am. The
+error names no url, because the value can carry basic-auth credentials.
+
+The sink uses the platform's `fetch` and forces `redirect: "manual"`. A 3xx
+response fails with `sink_rejected`; credentials and alert bodies are never
+forwarded to the redirect target. Injected `HttpClient` layers, including clients
+wrapped with `HttpClient.followRedirects`, are not used. Fetch defaults can be
+set with `FetchHttpClient.RequestInit`; the sink overrides its redirect mode.
+A custom `FetchHttpClient.Fetch` must honor the Fetch redirect and abort contracts.
+
+Each delivery has its own scope. Completion, refusal, timeout, and interruption
+abort the request and release any unread response body. Delivery depends on the
+response status, so a body that never ends does not delay completion.
+
+## What a trace shows
+
+A webhook url is a credential: Slack, Discord and PagerDuty put the secret in
+the path, and other receivers take it in the query. The sink keeps it out of
+telemetry. Each delivery opens one HTTP span named `POST` that records:
+
+| Attribute                   | Value                                          |
+| --------------------------- | ---------------------------------------------- |
+| `http.request.method`       | `POST`                                         |
+| `url.scheme`                | `https` or `http`                              |
+| `server.address`            | The endpoint's host name                       |
+| `server.port`               | The endpoint's port                            |
+| `http.response.status_code` | The answering status, when there was an answer |
+| `error.type`                | The status again, for a `4xx` or `5xx` answer  |
+
+The span never records the url's path, query or userinfo. It fails with the
+reason the sink returns: `Alert webhook answered 503`, or
+`Alert webhook could not be reached` when no answer came. A delivery that hit
+`timeout` ends its span as interrupted.
+
+The span records no header. A host that sets `HttpClient.TracerHeaderFilter` to
+record headers gets every name in `headers` as `<redacted>`, and the `location`
+and `content-location` of a redirect too, because they name where the endpoint
+moved.
+
+## What the request looks like
+
+The body is the alert plus its `alertId`, and the same id is sent as an
+`Idempotency-Key` header:
+
+```text
+POST /alerts HTTP/1.1
+authorization: Bearer ...
+idempotency-key: alert:run-1:waiting-approval:1700000000000
+content-type: application/json
+
+{
+  "runId": "run-1",
+  "condition": "waiting-approval",
+  "since": 1700000000000,
+  "firedAt": 1700000900000,
+  "severity": "warning",
+  "coalescingKey": "run-1:waiting-approval",
+  "owner": "oncall",
+  "runbook": "https://runbook.example/approvals",
+  "alertId": "alert:run-1:waiting-approval:1700000000000"
+}
+```
+
+The header is set after your headers, so it is always the one this sink sends.
+The receiver must deduplicate on it: delivery is at-least-once, and every field
+of the alert is derived from the journal, so the same alert is byte-identical on
+every attempt. See [How alerting decides](../concepts/alerting.md).
+
+## Read the failure
+
+Any non-2xx answer is a failure, not a delivery. `Alerts.AlertError.code` is the
+stable half:
+
+| Code               | What happened                                | `status`    |
+| ------------------ | -------------------------------------------- | ----------- |
+| `sink_rejected`    | The endpoint answered, and refused the page. | The answer. |
+| `sink_unreachable` | The request never got an answer.             | Absent.     |
+| `sink_timeout`     | No answer arrived inside the sink's bound.   | Absent.     |
+
+`sink_misconfigured` is the fourth code and never appears here: it is raised
+while the layer is built, before any alert exists. See
+[Point it at an endpoint](#point-it-at-an-endpoint).
+
+A failure is journaled as `Alerts.failedEventType`, one record per alert per
+code, and the alert is retried on the next tick. The error carries the answering
+status and a short `reason`, and never the request: a webhook request holds the
+credential you handed `layerWebhook`, and an error is logged, encoded, and
+journaled in places a credential must never reach.
+
+## Write your own sink
+
+`Alerts.Sink` is an ordinary service with one method, so an endpoint that is not
+HTTP is a layer of your own:
+
+```ts
+import { Alerts } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+export const consoleSink: Layer.Layer<Alerts.Sink> = Layer.succeed(Alerts.Sink)({
+  deliver: (alert) =>
+    alert.owner === undefined
+      ? Effect.fail(new Alerts.AlertError({ code: "sink_rejected", message: "the alert names no owner to page" }))
+      : Effect.log(`[${alert.severity}] ${alert.runId} ${alert.condition} -> ${alert.owner}`)
+})
+```
+
+Two obligations come with the port:
+
+- **Deduplicate on `Alerts.alertId(alert)`.** It is stable for the life of one
+  condition and reaches the sink on every attempt. A sink that cannot deduplicate
+  will occasionally page twice about one condition.
+- **Fail when the page did not go out.** Succeeding on a dropped page is the one
+  thing this port must never do: the delivery record would be written and the
+  alert would never be raised again.
+
+`Alerts.layerNoop` is the deliberate absence: it accepts every alert, sends
+nothing, and still leaves the durable evidence.

package/docs/guides/steer-a-run.md

@@ -0,0 +1,127 @@
+---
+title: "Steer a run"
+description: "Turn an operator instruction into a durable human-steer notification: pick a steering item, encode it into the payload, and admit it with a stable id."
+sidebar:
+  order: 1
+---
+
+A steer is an instruction for a run that is already running. Admit it as a
+`human-steer` notification and the run reads it when its next turn closes.
+
+## Choose a steering item
+
+`SteerPayload.SteerPayload` is the vocabulary a control plane writes and a
+harness reads. Four items, and each one says a different thing to the run:
+
+| Item       | Fields                             | Effect at the boundary                           |
+| ---------- | ---------------------------------- | ------------------------------------------------ |
+| `Message`  | `body: string`                     | Inserted into the transcript.                    |
+| `Seat`     | `seat: string`                     | Changes the model seat from the next turn.       |
+| `Thinking` | `thinking: SteerPayload.Thinking`  | Changes the reasoning effort from the next turn. |
+| `Tools`    | `toolNames: ReadonlyArray<string>` | Widens the active tool set. Additive only.       |
+
+`SteerPayload.Thinking` is `none`, `minimal`, `low`, `medium`, `high`, or
+`xhigh`. An empty `Message` body is allowed on purpose: an operator who steers
+an empty message has still told the run that a human is watching and the turn
+should continue.
+
+## Encode it and admit it
+
+`SteerPayload.encode` writes the item as the record the journal stores. The
+result is typed as the item, so it fills the JSON `payload` field without an
+assertion, and it shares no mutable structure with the item you gave it:
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+import type { Notification } from "@smthrs/notifications/Notification"
+import * as SteerPayload from "@smthrs/notifications/SteerPayload"
+import * as Effect from "effect/Effect"
+
+const steerNotification = (
+  runId: string,
+  messageId: string,
+  operator: string,
+  item: SteerPayload.SteerPayload
+): Notification => ({
+  _tag: "human-steer",
+  id: messageId,
+  delivery: "steer",
+  targetLineageId: runId,
+  provenance: {
+    sourceRunId: runId,
+    sourceLineageId: runId,
+    sourceTurn: 0,
+    sourceActor: `human:${operator}`
+  },
+  payload: SteerPayload.encode(item)
+})
+
+export const steer = (runId: string, messageId: string, body: string) =>
+  Effect.gen(function*() {
+    const queue = yield* NotificationQueue.NotificationQueue
+    return yield* queue.admit(runId, steerNotification(runId, messageId, "will", { kind: "Message", body }))
+  })
+```
+
+Three things carry weight here:
+
+- **`id` is the operator's message id, not a fresh one.** A retried request with
+  the same id and the same content is one steer. A retried request with the same
+  id and different content is refused as `notification_id_reused`, which is the
+  correct answer: two different instructions must not share one identity.
+- **`targetLineageId` names the lineage that will read it.** A child lineage
+  drains its own boundary, so steering the root and steering a child are
+  different notifications.
+- **`provenance.sourceActor` is who said it.** The run that receives a steer is
+  not the run that wrote it, and provenance is the only thing that says which of
+  an operator, a parent run, and a webhook this was.
+
+## Send a follow-up instead
+
+Change `_tag` to `"human-followup"` and `delivery` to `"queue"` and the same
+message waits until the run would otherwise have nothing to do. Use it for
+anything that is worth saying and not worth interrupting a turn for. See
+[Admission and promotion](../concepts/admission-and-promotion.md).
+
+## Read a steer back
+
+`SteerPayload.decode` reads an admitted notification as an item, or answers
+`undefined` when it carries none:
+
+```ts
+import type * as Notification from "@smthrs/notifications/Notification"
+import * as SteerPayload from "@smthrs/notifications/SteerPayload"
+
+declare const notification: Notification.Notification
+
+const item = SteerPayload.decode(notification)
+// { kind: "Message", body: "keep going" } for a human steer whose payload is { body: "keep going" }
+```
+
+A `system-event` always decodes as `undefined`, whatever its payload says.
+System events carry webhook bodies and machine reports, and reading one as a
+steer would let its producer message the model as an operator or change the
+run's seat, thinking level, or tools. Inside a `human-steer` or
+`human-followup`, a record with a `body` string and no `kind` decodes as a
+message, because that is what a minimal caller means by it. Anything the
+vocabulary cannot classify decodes as `undefined` rather than a guess.
+
+## What the run does with each item
+
+[`@smthrs/harness`](/api/harness) drains the queue at each turn boundary and
+sorts the items. A `Message` becomes a transcript insert. `Seat` and `Thinking`
+become changes that apply from the next turn, and are deliberately not announced
+to the model: telling it "your seat changed" would spend a turn on bookkeeping
+when changing the seat is what the operator asked for.
+
+A `Tools` steer is answered out loud rather than dropped. That harness gives the
+model no provider tools at all, so there is nothing to activate; the run is told,
+in the transcript, that an operator asked for those tools and that its authority
+is the flows it can already call. A host that does hand the model provider tools
+decides for itself what the item activates.
+
+## Next
+
+- [Drain at a turn boundary](./drain-at-a-turn-boundary.md): the reading half.
+- [Handle a full queue](./handle-a-full-queue.md): what to do when the receipt
+  says `rejected-full`.

package/docs/guides/testing.md

@@ -0,0 +1,161 @@
+---
+title: "Test against the queue"
+description: "Run the real queue over an in-memory journal, use the explicit noop seams, drive alert delays on the test clock, and test the promotion rules as pure functions."
+sidebar:
+  order: 7
+---
+
+Nothing in this package needs stubbing to be deterministic. The journal is a
+service, the clock is a service, the sink is a service, and the promotion rules
+are pure functions. Swap the services; keep the code under test.
+
+## Run the real queue in memory
+
+`TestJournal.layer()` from [`@smthrs/journal`](/api/journal) is the production
+SQLite journal over an in-memory database, with migrations already run. Compose
+it under `NotificationQueue.layer` and every durable guarantee is real:
+
+```ts
+import { Journal } from "@smthrs/journal"
+import * as TestJournal from "@smthrs/journal/test/TestJournal"
+import { NotificationQueue } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+
+const run = <A, E>(
+  effect: Effect.Effect<A, E, NotificationQueue.NotificationQueue | Journal.Journal>
+): Promise<A> =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(NotificationQueue.layer),
+      Effect.provide(TestJournal.layer()),
+      Effect.scoped
+    )
+  )
+```
+
+Use `NotificationQueue.layerWith({ capacity })` to reach the capacity bound
+without admitting 128 notifications first.
+
+## Prove durability with a file, not a layer
+
+One in-memory journal and one queue cannot separate "the journal records this"
+from "the layer remembered it". To test a claim about what survives a process,
+build the stack over a real file, close it, and build a second stack over the
+same rows:
+
+```ts
+import * as DurableWriter from "@smthrs/database/DurableWriter"
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase"
+import * as Migrations from "@smthrs/journal/Migrations"
+import * as SqlJournal from "@smthrs/journal/SqlJournal"
+import { NotificationQueue } from "@smthrs/notifications"
+import * as Layer from "effect/Layer"
+
+const over = (filename: string, capacity: number) =>
+  NotificationQueue.layerWith({ capacity }).pipe(
+    Layer.provideMerge(
+      SqlJournal.layer({ capacity: 1024, overflow: "reject" }).pipe(
+        Layer.provide(
+          Layer.provideMerge(
+            Migrations.layer,
+            Layer.provideMerge(DurableWriter.layer(), NodeDatabase.layer({ filename }))
+          )
+        )
+      )
+    )
+  )
+```
+
+Build the first stack, admit and drain, close its scope, then build a second
+stack over the same filename and assert on what it reads back. That shape is
+what proves the claims worth proving: the drain identity, the pending fold, and
+a capacity refusal are all properties of what was written, not of a live
+process.
+
+## The explicit absences
+
+Every service in this package ships a stated absence, so a test provides the
+smallest composition that type-checks:
+
+| Service             | Explicit absence                      | What it does                                        |
+| ------------------- | ------------------------------------- | --------------------------------------------------- |
+| `NotificationQueue` | `NotificationQueue.layerNoop()`       | Fails every method with `notification_unavailable`. |
+| `NotificationQueue` | `NotificationQueue.makeNoop({ ... })` | The same, with named methods replaced.              |
+| `Alerts.Sink`       | `Alerts.layerNoop`                    | Accepts every alert and sends nothing.              |
+
+`layerNoop` takes the same overrides, so a test can serve one method and leave
+the rest failing:
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+
+const onlyPending = NotificationQueue.layerNoop({
+  pending: () => Effect.succeed([])
+})
+```
+
+A composition that means to serve nothing says so in writing. That is what makes
+"the queue is unavailable" a case a caller can test, rather than a case it
+discovers in production. See
+[Report what a run is waiting on](./report-pending-notifications.md).
+
+## Drive an alert delay on the test clock
+
+An alert's decision is a comparison against journal time, so a test moves the
+clock instead of waiting:
+
+```ts
+import * as TestJournal from "@smthrs/journal/test/TestJournal"
+import { Alerts, NotificationQueue } from "@smthrs/notifications"
+import * as Layer from "effect/Layer"
+import { TestClock } from "effect/testing"
+
+const stack = (policy: Alerts.Policy, sink: Layer.Layer<Alerts.Sink>) =>
+  Alerts.layer(policy).pipe(
+    Layer.provideMerge(Layer.mergeAll(NotificationQueue.layer, sink)),
+    Layer.provideMerge(TestJournal.layer()),
+    Layer.provideMerge(TestClock.layer())
+  )
+```
+
+`TestClock.adjust("59 seconds")` then `tick` raises nothing for a rule with a
+60 second delay; one more second and it pages. Move the clock between a refusal
+and its retry too, because in production it always moves: an alert whose content
+varied with the reading time would be refused by the queue as a reused id and
+never page at all.
+
+## Test the rules as pure functions
+
+`NotificationState` has no I/O, so the promotion rules need no layers:
+
+```ts
+import { NotificationState } from "@smthrs/notifications"
+import type { Notification } from "@smthrs/notifications/Notification"
+
+export const promotedAtCutoff = (notifications: ReadonlyArray<Notification>, cutoff: number) => {
+  let state = NotificationState.empty(8)
+  notifications.forEach((notification, index) => {
+    state = NotificationState.admit(state, notification, index).state
+  })
+  return NotificationState.promoteSteers(state, cutoff).promoted.map((item) => item.notification.id)
+}
+```
+
+`Alerts.conditions` and `Alerts.decide` are pure in the same way, and take the
+journal entries and the instant as arguments. Assert on them directly before
+reaching for a runtime.
+
+## Assert on the durable evidence
+
+The records are the evidence, and reading them is how a test proves a claim
+about behavior rather than about a return value:
+
+- `flows/notifications/Admitted`, one per retained notification.
+- `flows/notifications/Promoted`, one per drained boundary.
+- `Alerts.deliveredEventType`, one per delivered alert.
+- `Alerts.failedEventType`, one per alert per failure code.
+
+Counting them is what distinguishes "the alert was suppressed" from "the alert
+was never raised", and "the webhook is down" from "the webhook is down and one
+row per tick piled up for an hour".

package/docs/installation.md

@@ -0,0 +1,123 @@
+---
+title: "Installation"
+description: "Install @smthrs/notifications, the journal a durable composition provides, the HTTP client the webhook sink needs, and the import forms."
+sidebar:
+  order: 1
+---
+
+## Install the package
+
+```bash
+npm install @smthrs/notifications@next effect
+```
+
+The `next` tag carries the 1.0 release candidates.
+
+The package requires Node.js 26.4.0 or later and ships as both ESM and
+CommonJS with TypeScript declarations. It is built on
+[`effect`](https://effect.website) and [`@smthrs/journal`](/api/journal). Declare
+`@smthrs/journal` in your own package as well: the compositions below import it
+directly, and a strict package manager resolves only the dependencies you have
+named.
+
+## Provide a journal
+
+Every durable operation goes through a `Journal.Journal`. The queue writes one
+admission record per notification and one promotion record per boundary, and it
+rebuilds its state by reading them back, so a composition without a journal has
+no queue. `NotificationQueue.layer` states that requirement in its type:
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+
+// Layer.Layer<NotificationQueue.NotificationQueue, never, Journal.Journal>
+export const queue = NotificationQueue.layer
+```
+
+For a real deployment, the journal is the SQLite one, over a database and a
+migration run:
+
+```ts
+import * as DurableWriter from "@smthrs/database/DurableWriter"
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase"
+import * as Migrations from "@smthrs/journal/Migrations"
+import * as SqlJournal from "@smthrs/journal/SqlJournal"
+import { NotificationQueue } from "@smthrs/notifications"
+import * as Layer from "effect/Layer"
+
+export const durableQueue = (filename: string) =>
+  NotificationQueue.layer.pipe(
+    Layer.provideMerge(
+      SqlJournal.layer({ capacity: 1024, overflow: "reject" }).pipe(
+        Layer.provide(
+          Layer.provideMerge(
+            Migrations.layer,
+            Layer.provideMerge(DurableWriter.layer(), NodeDatabase.layer({ filename }))
+          )
+        )
+      )
+    )
+  )
+```
+
+Point a second process at the same file and it reads the same queue. That is
+the whole reason the state lives in the journal rather than in the layer, and
+[the journal records](./concepts/journal-records.md) explains what is written.
+
+`NotificationQueue.layerWith({ capacity })` is the same layer at a bound the
+composition chooses. `NotificationQueue.layerNoop()` needs no journal at all and
+fails every method; see [Test against the queue](./guides/testing.md).
+
+## What alerting adds
+
+`Alerts.layer(policy)` needs the journal, the queue, and a sink. The noop sink
+needs nothing:
+
+```ts
+import { Alerts, NotificationQueue } from "@smthrs/notifications"
+import * as Layer from "effect/Layer"
+
+export const alerting = (policy: Alerts.Policy) =>
+  Alerts.layer(policy).pipe(
+    Layer.provideMerge(Layer.mergeAll(NotificationQueue.layer, Alerts.layerNoop))
+  )
+```
+
+`Alerts.layerWebhook` POSTs each alert using its own Fetch HTTP client.
+The platform must provide `fetch`; no further install or `HttpClient` layer is
+required:
+
+```ts
+import { Alerts } from "@smthrs/notifications"
+
+export const webhook = Alerts.layerWebhook({ url: "https://pager.example/alerts" })
+```
+
+Injected `HttpClient` layers are not used. The sink controls redirect refusal
+and request cleanup. See [Send alerts to a webhook](guides/send-alerts-to-a-webhook.md)
+for Fetch configuration and delivery behavior.
+
+## Import forms
+
+The root entry point re-exports every module as a namespace:
+
+```ts
+import { Alerts, Notification, NotificationQueue, SteerPayload } from "@smthrs/notifications"
+```
+
+Each module is also importable from its own subpath, which is the form the
+[API reference](./api.md) uses:
+
+```ts
+import * as NotificationQueue from "@smthrs/notifications/NotificationQueue"
+import * as SteerPayload from "@smthrs/notifications/SteerPayload"
+```
+
+Two subpath forms are blocked in the export map: `@smthrs/notifications/internal/*`
+and `@smthrs/notifications/*/index`. `@smthrs/notifications/package.json` is
+exported.
+
+## Next step
+
+Admit and drain a notification end to end in the
+[Quickstart](./quickstart.md).