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

package/docs/concepts/alerting.md

@@ -0,0 +1,138 @@
+---
+title: "How alerting decides"
+description: "Why an alert is a function of journal time rather than wall time, how a detector opens and closes a condition, and why delivery is at-least-once rather than exactly-once."
+sidebar:
+  order: 3
+---
+
+The queue answers "tell this run something". An alert answers the question
+nobody is around to ask: a run has been waiting an hour for an approval, and the
+person who could grant it does not know.
+
+The two are the same machinery. An alert is admitted as a coalesced system event
+on the same durable queue, under the same idempotency and the same bound. They
+differ only in who decides to write one.
+
+## A condition is a payload field with a value
+
+`Alerts.Detector` names a payload key, the value that means the condition holds,
+and optionally the event types worth consulting at all:
+
+```ts
+import { Alerts } from "@smthrs/notifications"
+
+const detector: Alerts.Detector = { field: "status", value: "waiting-approval" }
+```
+
+An entry that carries the field with the matching value **opens** the condition,
+if it is not open already. An entry that carries the field with any other value
+**closes** it. That symmetry is why a resume clears an approval alert without a
+second vocabulary for "cleared": the run's next status entry says something
+else, and the condition is gone.
+
+An entry that does not carry the field at all is ignored entirely, which is what
+stops a health report from closing an approval wait. `eventTypes` narrows
+further, for a field two different producers write under different meanings. An
+item ending in `.*`, such as `control.*`, names every event type with that
+prefix.
+
+`Alerts.defaultDetectors` ships four conditions, each of them one field and one
+value: `waiting-approval` and `failed` read `status`, `stalled` reads `health`,
+and `quota-parked` reads `waitingReason` for `quota`. Those are the fields
+[`@smthrs/control`](/api/control) writes, and each default consults only the
+`control.*` event types: a flow step or agent trace that writes a `status` field
+into the same run's journal neither opens nor closes a default condition. A policy's own `detectors` are merged
+over them, so a deployment that journals a different vocabulary names its own
+rather than forking the module.
+
+Only a condition the policy has a rule for is watched at all, and only own
+properties count: a detector named `toString` reads no evidence off
+`Object.prototype`.
+
+## Journal time, not wall time
+
+A condition's clock starts at `emittedAtMs` of the entry that opened it.
+`Alerts.decide(policy, open, now)` compares that against the rule's `afterMs`,
+and the alert it produces is stamped `firedAt: since + afterMs`.
+
+`now` decides **whether** an alert is raised. It never appears in one. The same
+journal therefore raises the same alerts in any process, at any instant past the
+delay, and a tick that runs an hour late produces the byte-identical alert the
+on-time tick would have.
+
+That is not a stylistic choice. Retries re-admit the same alert id, and the
+queue refuses a reused id whose content changed. An alert stamped with the
+reading time would become permanently undeliverable the moment one tick was
+refused and time moved on.
+
+## The delay is the policy
+
+`Alerts.Rule.afterMs` is how long a condition must last before it is worth
+paging about. Most stalls clear themselves, and a policy that fired immediately
+would page on every one of them. `afterMs` is a whole, non-negative number of
+milliseconds, checked by the schema when `Alerts.layer` builds, so an impossible
+delay fails the composition by name instead of mis-paging at 3am.
+
+## Delivery is at-least-once
+
+One tick, for each alert past its delay that has not already been delivered:
+
+1. Admits the alert to the notification queue as a coalesced system event.
+2. Calls `Alerts.SinkService.deliver`.
+3. Journals `flows.alerts.delivered` once the sink accepted it.
+
+The order is deliberate. Admission is idempotent, so a crash between steps 1 and
+2 costs a duplicate admission the queue drops. Recording the delivery before the
+send would turn a crash into a page nobody ever receives, which for an alert is
+the worse failure.
+
+The cost of that choice is a duplicate page: a process that dies between an
+accepted send and the delivery record pages again on the next tick. So the sink
+owns the last mile. `deliver` must be idempotent on `Alerts.alertId(alert)`,
+which is `alert:<coalescingKey>:<since>` and stable for the life of one
+condition. A condition that clears and re-opens gets a new id, because the second
+approval wait is not the first one.
+
+## Four outcomes, and only one is a failure
+
+`Alerts.Tick` sorts every alert the tick considered:
+
+| Field        | What it means                                                        |
+| ------------ | -------------------------------------------------------------------- |
+| `delivered`  | The sink accepted the page, and `flows.alerts.delivered` records it. |
+| `suppressed` | A delivery record already exists. The sink was not called.           |
+| `failed`     | The sink refused or could not be reached. Retried on the next tick.  |
+| `refused`    | The notification queue was at capacity. The sink was not called.     |
+
+A refused page is not a delivered page, so it is retried. A refusal from the
+queue pages nobody at all: the alert has nowhere durable to sit, and paging
+about something the run will never read would send an operator looking in the
+wrong place.
+
+Both non-delivery outcomes journal `flows.alerts.failed`, one record per alert
+per failure code, never one per tick. A webhook that stays down for an hour
+leaves one row rather than a hundred and twenty every later tick has to read
+past.
+
+## The alerter never reads its own records
+
+`flows.alerts.delivered` and `flows.alerts.failed` are written into the same
+journal the detectors read. 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. So both event types are excluded
+from condition detection outright. Without that exclusion, a page would close the
+condition it paged about, the next tick would re-open it, and a webhook that
+answered 503 once would alert forever.
+
+A delivery record suppresses a repeat page only under the source the alerter
+writes it with, `/notifications/alerts/<alertId>/delivered`. Another producer's
+record naming the same `alertId` under its own source is ignored. The journal
+does not bind a source to a writer, so this scopes records; it does not
+authenticate the writer.
+
+## Next
+
+- [Alert on a stuck run](../guides/alert-on-a-stuck-run.md): a policy, a tick,
+  and what each field of the result means.
+- [Send alerts to a webhook](../guides/send-alerts-to-a-webhook.md): the shipped
+  sink, its idempotency header, and its timeout.

package/docs/concepts/journal-records.md

@@ -0,0 +1,132 @@
+---
+title: "The journal records"
+description: "The two durable events this package owns, why their spelling is frozen, how a queue folds a run's history back into state, and what a projection over a shared journal may assume."
+sidebar:
+  order: 2
+---
+
+The queue keeps no state of its own. Everything it knows comes from two journal
+records, and rebuilding from them is what lets a second process answer for a run
+the first one admitted to.
+
+## Two event types
+
+| Constant                              | Event type                     | What it records                                               |
+| ------------------------------------- | ------------------------------ | ------------------------------------------------------------- |
+| `NotificationEvent.AdmittedEventType` | `flows/notifications/Admitted` | One notification and the decision the queue made about it.    |
+| `NotificationEvent.PromotedEventType` | `flows/notifications/Promoted` | Which notification ids one boundary of one lineage delivered. |
+
+Both spellings are frozen wire format. The values are already durable in every
+database that has run this package, and renaming them would silently stop
+matching the projections that consumers key on. Treat both strings, and the JSON
+stored under them, as fixed.
+
+An `Admitted` payload is `{ notification, decision }`. A `Promoted` payload is
+`{ boundary, targetLineageId, ids }`.
+
+## Replay never re-decides
+
+The decision is recorded because it is a fact, not a derivation. When a queue
+folds history, `NotificationState.applyAdmission` applies the committed decision
+whatever this process's state would have chosen. A run that filled up under a
+capacity of 128 and is now folded by a layer built at 512 replays as what
+happened, not as what would happen today.
+
+`rejected-full` is the decision that is never written. The queue refuses a full
+queue in the receipt alone, because a rejection recorded as an admission would
+match on every later attempt and burn the id forever. The literal stays in
+`NotificationEvent.AdmissionDecision` so that a reader is total over a record any
+writer could have produced.
+
+## Folding is incremental
+
+A layer folds each run once and then pages only the entries committed since its
+last read. It keeps at most 64 folds at a time, and a run evicted from that set
+is folded again from the beginning on its next call. Reading a run's history
+therefore costs what has been journaled since the previous call, not the run's
+whole journal.
+
+Eviction sacrifices the newest fold no later read has come back for, never the
+fold an ordered sweep is about to want. Dropping the least recently folded run
+instead drops the run the next read wants, so a supervisor polling 65 or more
+runs in order would replay every journal from sequence zero on every pass. A
+sweep of any width instead refolds a fixed handful of runs and pages the tail
+of the rest. When every retained fold has been read a second time the oldest is
+evicted and the reuse marks are cleared, so no fold holds a slot on one ancient
+read forever.
+
+A fold retains the run's pending state, the sequence it stopped at, and the
+identities it has seen: a notification id with the fingerprint and sequence of
+its admission, and a drain identity with the sequence of its record. It retains
+no admitted payload and no drain record, so a run's memory does not grow with
+the notifications it has already drained, and a queue of any capacity costs the
+same per event however long the run has been running. The two paths that must
+report an already committed notification, a replayed drain and the content
+comparison for a legacy admission with no fingerprint, read the record back at
+its sequence.
+
+Eviction is always safe, and so is an interleaved fold: a fold reads the cached
+value, pages what has been committed since, and writes a fresh, self-consistent
+pair back, so the worst case is one extra page on the next call. No fold can
+report a state the journal does not hold: a fold taken inside a transaction is
+published through `Journal.whenCommitted`, so a rollback leaves behind neither
+the condition it observed nor the cursor it stopped at.
+
+## Foreign entries are not errors
+
+Journals are shared. `NotificationEvent.fromEntry` answers `Option.none()` for
+an entry this package does not own, and for an owned entry whose payload does
+not decode, so a projection over a busy journal stays total instead of failing
+on somebody else's record.
+
+An event type alone does not make an entry owned, because any producer on a
+shared journal can choose one. An `Admitted` entry counts only under
+`NotificationEvent.admissionSourceId` of the notification it carries, and a
+`Promoted` entry only under a `/notifications/drain/` source. Another producer's
+record with the same event type therefore stays out of the projection. The
+check scopes records by source; it does not authenticate the writer. The journal
+fences writes on run ownership, not on source, so a writer that sets this
+package's source id is read as this package. The drain check is a prefix because
+drain records written before the lineage joined the identity carry the boundary
+alone.
+
+`NotificationEvent.isAdmitted` and `NotificationEvent.isPromoted` tell the two
+owned events apart. They are refinements over the decoded shape rather than a
+stored discriminant, because a discriminant would be a durable field this
+vocabulary does not have.
+
+## Projections
+
+`Projection.derive` is a `Journal.Projection` that replays the same fold and
+emits the state after every entry:
+
+```ts
+import { Journal, JournalEvent } from "@smthrs/journal"
+import { Projection } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+import * as Stream from "effect/Stream"
+
+const watchPending = (runId: string) =>
+  Effect.flatMap(
+    Journal.Journal,
+    (journal) =>
+      journal.project(Projection.derive, { runId: JournalEvent.RunId.make(runId) }).pipe(
+        Stream.runForEach((state) => Effect.log(`${state.items.length} pending`))
+      )
+  )
+```
+
+`journal.project` replays the run's history and then follows its committed
+tail, so the stream does not end on its own. That is what a projection is for:
+a live view that stays correct as entries arrive. Bound it with `Stream.take`
+when you want a snapshot, or fork it into a scope when you want a follower.
+
+`Projection.derive` starts at `NotificationState.empty(NotificationState.defaultCapacity)`.
+That bound is the initial state's, not the run's: replay applies committed
+decisions rather than re-deciding, so a deployment that raised the bound with
+`NotificationQueue.layerWith` sees every admission it wrote replayed, past 128.
+No journal record carries the layer's bound, so the projected `capacity` stays
+at the default and `items` is the field to read.
+
+For the live answer rather than a replay, use `NotificationQueue.pending`; see
+[Report what a run is waiting on](../guides/report-pending-notifications.md).

package/docs/guides/alert-on-a-stuck-run.md

@@ -0,0 +1,140 @@
+---
+title: "Alert on a stuck run"
+description: "Write an alert policy, add a detector for a condition your deployment journals itself, tick the runtime, and read the four outcomes it reports."
+sidebar:
+  order: 5
+---
+
+An alert policy watches a run's journal for a condition that has stayed open too
+long, admits it to the notification queue, and pages a sink.
+
+## Write the policy
+
+A policy is delays plus ownership. `rules` names the conditions to watch and how
+long each one may last:
+
+```ts
+import { Alerts } from "@smthrs/notifications"
+
+export const policy: Alerts.Policy = {
+  defaults: { severity: "warning", owner: "oncall" },
+  rules: {
+    "waiting-approval": { afterMs: 900_000, runbook: "https://runbook.example/approvals" },
+    stalled: { afterMs: 300_000, severity: "critical" }
+  }
+}
+```
+
+`defaults` fills in what a rule leaves out, so the delay is stated per condition
+and the ownership once. `afterMs` must be a whole, non-negative number of
+milliseconds; `Alerts.layer` decodes the policy when it builds, so an impossible
+delay fails the composition rather than mis-paging later.
+
+`waiting-approval` and `stalled` are two of the four conditions
+`Alerts.defaultDetectors` recognizes out of the box, alongside `failed` and
+`quota-parked`. A rule for a condition with no detector raises nothing.
+
+## Add a detector for your own condition
+
+A condition is a payload field with a value. To alert on something your own
+supervisor journals, name the field, the value, and the entries worth reading:
+
+```ts
+import { Alerts } from "@smthrs/notifications"
+
+export const wedged: Alerts.Policy = {
+  defaults: { severity: "warning", owner: "oncall" },
+  rules: { "wedged-node": { afterMs: 900_000, runbook: "https://runbook.example/wedged-runs" } },
+  detectors: {
+    "wedged-node": {
+      field: "health",
+      value: "wedged-node",
+      eventTypes: ["supervisor.heartbeat"]
+    }
+  }
+}
+```
+
+`eventTypes` matters more than it looks. Without it, every entry in the run's
+journal carrying a `health` field is evidence, including entries some other
+writer keys the same way for its own reasons, and any value other than
+`wedged-node` closes the condition. One unrelated writer between two heartbeats
+therefore restarts the clock, and a run that is wedged the whole time never
+outlives the delay. Narrow to the entries that actually report the condition.
+
+Your `detectors` are merged over `Alerts.defaultDetectors`, so naming one of the
+four built-in conditions replaces its detector and leaves the rest alone.
+
+## Compose the runtime
+
+`Alerts.layer(policy)` needs the journal, the notification queue, and a sink:
+
+```ts
+import { Alerts, NotificationQueue } from "@smthrs/notifications"
+import * as Layer from "effect/Layer"
+
+export const alerting = Alerts.layer(policy).pipe(
+  Layer.provideMerge(Layer.mergeAll(NotificationQueue.layer, Alerts.layerNoop))
+)
+```
+
+`Alerts.layerNoop` accepts every alert and sends it nowhere. The admission and
+the delivery record still happen, so a deployment with no outbound channel keeps
+the durable evidence of what it would have paged about, and keeps the detection
+path exercised rather than switched off. For a real pager, see
+[Send alerts to a webhook](./send-alerts-to-a-webhook.md).
+
+## Tick it
+
+One tick reads one run:
+
+```ts
+import { Alerts } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+
+export const check = (runId: string) =>
+  Effect.gen(function*() {
+    const alerts = yield* Alerts.AlertRuntime
+    const tick = yield* alerts.tick(runId)
+    return {
+      paged: tick.delivered.map((alert) => alert.condition),
+      retrying: tick.failed.map((alert) => alert.condition),
+      noRoom: tick.refused.map((alert) => alert.condition),
+      alreadySent: tick.suppressed.map((alert) => alert.condition)
+    }
+  })
+```
+
+Call it on whatever schedule suits the deployment. A tick costs the journal
+entries committed since the previous one, because the runtime keeps each run's
+folded history for the 64 most recently watched runs.
+
+Only two things make `tick` fail. A `Journal.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. A sink that refuses the page is
+neither: it comes back in `failed` and is retried.
+
+## Decide without a runtime
+
+`Alerts.conditions` and `Alerts.decide` are pure, so a report can answer "what
+would page, and when" without admitting anything:
+
+```ts
+import type { JournalEvent } from "@smthrs/journal"
+import { Alerts } from "@smthrs/notifications"
+
+export const wouldPage = (entries: ReadonlyArray<JournalEvent.Entry>, runId: string, now: number) =>
+  Alerts.decide(policy, Alerts.conditions(policy, runId, entries), now)
+```
+
+`now` decides whether an alert is raised and never appears in one: every field of
+the result, `firedAt` included, comes from the journal. See
+[How alerting decides](../concepts/alerting.md).
+
+## A worked example
+
+[`examples/src/38-monitor-and-alert.ts`](https://github.com/smithersai/smithers/blob/main/examples/src/38-monitor-and-alert.ts)
+runs the whole supervision loop over one SQLite file: two durable runs, a monitor
+that beats over them, and the same policy at a production delay and at a zero
+delay, so the quiet case and the paging case are visible side by side.

package/docs/guides/drain-at-a-turn-boundary.md

@@ -0,0 +1,95 @@
+---
+title: "Drain at a turn boundary"
+description: "Ask the queue what one boundary may deliver: naming the boundary, setting the turn cutoff, reporting idleness, and reading a duplicate receipt."
+sidebar:
+  order: 2
+---
+
+A run drains when it reaches a point where reading a new instruction is safe.
+The queue decides what that boundary may deliver, records the decision, and
+answers with it.
+
+## Call drain at the safe point
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+
+export const atTurnClose = (runId: string, lineageId: string, turn: number, turnOpenedAt: number) =>
+  Effect.gen(function*() {
+    const queue = yield* NotificationQueue.NotificationQueue
+    const receipt = yield* queue.drain({
+      runId,
+      targetLineageId: lineageId,
+      boundary: `turn-${turn}`,
+      wouldIdle: false,
+      cutoffSeq: turnOpenedAt
+    })
+    return receipt.notifications
+  })
+```
+
+Each field decides something:
+
+- **`boundary`** names this safe point. With `runId` and `targetLineageId` it
+  forms the drain identity, so the name must be stable for one boundary and
+  distinct between boundaries. A turn number is the usual choice.
+- **`cutoffSeq`** is the journal sequence that opened the turn now closing. A
+  steer admitted after it is held for the next boundary, which keeps a message
+  that arrived mid-turn out of the turn already in flight. Omit it only when you
+  have no turn to compare against; omitting it delivers everything pending for
+  the lineage.
+- **`wouldIdle`** says whether the run would have nothing to do if this boundary
+  delivered nothing. When it is `true` and no steer was promoted, the drain also
+  promotes exactly one queued notification.
+
+Legacy journal admissions with an `outside_change` payload remain pending at
+coding park boundaries (`<frame>:<64-character lowercase hex digest>:park:<index>`).
+An ordinary boundary promotes them at its cutoff even when `wouldIdle` is false.
+New admissions of these reserved payloads are refused.
+
+## Read the receipt
+
+`DrainReceipt.notifications` are the notifications the committed promotion
+record names, in admission order. Render them, and act on the steering items
+they carry with `SteerPayload.decode`:
+
+```ts
+import type * as NotificationQueue from "@smthrs/notifications/NotificationQueue"
+import * as SteerPayload from "@smthrs/notifications/SteerPayload"
+
+const messages = (receipt: NotificationQueue.DrainReceipt) =>
+  receipt.notifications.flatMap((notification) => {
+    const item = SteerPayload.decode(notification)
+    return item?.kind === "Message" ? [item.body] : []
+  })
+```
+
+`DrainReceipt.duplicate` is `true` when this boundary had already drained. The
+notifications are still the right ones: they are read back from the committed
+record rather than decided again, so two processes draining one boundary report
+the same delivery instead of two divergent guesses. A resumed run that walks its
+boundaries looking for the first one it has not consulted branches on exactly
+this flag.
+
+## Drain the lineage you are
+
+`targetLineageId` is not decoration. Two lineages closing a turn under the same
+boundary name are two separate drains, so a child lineage that passes its
+parent's id drains the parent's notifications and leaves its own pending. Pass
+the lineage the running code belongs to.
+
+## The harness does this for you
+
+[`@smthrs/harness`](/api/harness) already implements this loop. Its
+`Notifications.layer({ runId, lineageId })` captures the queue as the harness
+steering source, calls `drain` at each boundary, and folds the result into the
+inserts, seat changes, and thinking changes the turn controller acts on. Write
+your own drain only when you are building a host that is not that harness.
+
+## Next
+
+- [Handle a full queue](./handle-a-full-queue.md): the writer-side contract that
+  keeps the boundary from having nothing to read.
+- [Report what a run is waiting on](./report-pending-notifications.md): the same
+  fold, without promoting anything.

package/docs/guides/handle-a-full-queue.md

@@ -0,0 +1,102 @@
+---
+title: "Handle a full queue"
+description: "Read AdmissionReceipt.decision, tell rejected-full apart from a failure, and retry the same notification once a boundary has drained."
+sidebar:
+  order: 3
+---
+
+`admit` does not fail when the queue is full. It succeeds, and says so in the
+receipt. A caller that treats the receipt as an acknowledgement loses the
+notification in silence, which is the one failure this queue must never hide.
+
+## Branch on the decision
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+import type { Notification } from "@smthrs/notifications/Notification"
+import * as Effect from "effect/Effect"
+
+export const tell = (runId: string, notification: Notification) =>
+  Effect.gen(function*() {
+    const queue = yield* NotificationQueue.NotificationQueue
+    const receipt = yield* queue.admit(runId, notification)
+    switch (receipt.decision) {
+      case "admitted":
+      case "coalesced":
+        // The queue retained it. `receipt.seq` is the sequence it committed at.
+        return { retained: true as const, seq: receipt.seq }
+      case "rejected-full":
+        // Nothing was retained and nothing was journaled. The id is still free.
+        return { retained: false as const, seq: undefined }
+    }
+  })
+```
+
+| Decision        | Retained | Journaled | `seq`       |
+| --------------- | -------- | --------- | ----------- |
+| `admitted`      | Yes      | Yes       | present     |
+| `coalesced`     | Yes      | Yes       | present     |
+| `rejected-full` | No       | No        | `undefined` |
+
+`receipt.seq` is absent exactly when nothing was written, so an absent sequence
+and a `rejected-full` decision are the same fact reported twice.
+
+## Retry the same notification, unchanged
+
+Because nothing was journaled, the id stays admissible. Once a boundary drains
+and the run drops below its capacity, the identical call succeeds:
+
+```ts
+import * as Effect from "effect/Effect"
+import * as Schedule from "effect/Schedule"
+
+export const tellEventually = (runId: string, notification: Notification) =>
+  Effect.gen(function*() {
+    const result = yield* tell(runId, notification)
+    if (result.retained) return result
+    return yield* Effect.fail("queue-full" as const)
+  }).pipe(Effect.retry({ schedule: Schedule.spaced("1 second"), times: 5 }))
+```
+
+Retry with the same `id` and the same content. Changing either turns the retry
+into a different notification, and changing only the content is refused as
+`notification_id_reused`.
+
+## Choose the bound deliberately
+
+`NotificationState.defaultCapacity` is 128 pending notifications per run.
+`NotificationQueue.layerWith({ capacity })` sets a different bound for one
+composition:
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+
+export const roomyQueue = NotificationQueue.layerWith({ capacity: 512 })
+```
+
+Raising it makes a run absorb more before it refuses, and makes an undrained run
+hold more. Two things follow from a non-default bound:
+
+- `Projection.derive` replays every admission the run committed, whatever bound
+  it was built at, but the state it projects still carries the default
+  `capacity`. Read `items`, not `capacity`. See
+  [the journal records](../concepts/journal-records.md).
+- A capacity that is not a finite number becomes zero, which refuses everything.
+  That is deliberate: a misconfigured bound fails loudly rather than retaining an
+  unbounded backlog.
+
+## What a refusal is not
+
+A `rejected-full` decision is not an error, and no `NotificationError` is
+raised. The typed failures mean something else entirely:
+`notification_unavailable` is the seam reporting that it serves nothing,
+`notification_id_reused` is a producer bug, and `notification_invalid` is a value
+that is not a notification. Storage problems arrive as a `Journal.JournalError`.
+See [Troubleshooting](../troubleshooting.md).
+
+## When the alerter is refused
+
+`Alerts` implements exactly this contract. A tick whose admission is refused
+returns the alert in `Alerts.Tick.refused`, journals the refusal, and does not
+call the sink, because paging about an alert the run will never read would send
+an operator looking in the wrong place. The next tick tries again.