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

package/docs/api.md

@@ -0,0 +1,443 @@
+---
+title: "API reference"
+description: "Every public export of @smthrs/notifications: the queue service and its layers, the notification and event schemas, the pure state machine, the steering vocabulary, and the alert policy."
+---
+
+Every module is importable as a namespace from the root entry point and from its
+own subpath:
+
+```ts
+import { Alerts, Notification, NotificationQueue } from "@smthrs/notifications"
+import * as SteerPayload from "@smthrs/notifications/SteerPayload"
+```
+
+Types written below as `Schema` are `effect` schemas; each one exports a value
+and a type of the same name, and the type is the decoded form.
+
+## Example
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+
+const deliver = Effect.gen(function*() {
+  const queue = yield* NotificationQueue.NotificationQueue
+  const receipt = yield* queue.drain({
+    runId: "run-1",
+    targetLineageId: "run-1/root",
+    boundary: "turn-1",
+    wouldIdle: true
+  })
+  return receipt.notifications
+}).pipe(Effect.provide(NotificationQueue.layer))
+```
+
+## NotificationQueue
+
+Journal-backed durable admission and turn-boundary drain. Import from
+`@smthrs/notifications/NotificationQueue`.
+
+### Service
+
+```ts
+interface Service {
+  readonly admit: (
+    runId: string,
+    notification: Notification.Notification,
+    version?: number
+  ) => Effect.Effect<AdmissionReceipt, Journal.JournalError | NotificationError>
+  readonly drain: (
+    input: DrainInput
+  ) => Effect.Effect<DrainReceipt, Journal.JournalError | NotificationError>
+  readonly pending: (
+    runId: string
+  ) => Effect.Effect<ReadonlyArray<Notification.Notification>, Journal.JournalError | NotificationError>
+}
+```
+
+| Method                       | What it does                                                                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `admit(runId, notification)` | Decodes the notification, snapshots it, and records one admission decision for `runId`. Idempotent on `notification.id`.     |
+| `drain(input)`               | Promotes what the boundary named by `input` may deliver, and records the promotion. First writer wins on the drain identity. |
+| `pending(runId)`             | Returns the run's admitted but unpromoted notifications, in admission order, across every lineage.                           |
+
+`NotificationQueue` is the service tag, a `Context.Service` under the key
+`/notifications/NotificationQueue`.
+
+New admissions persist a SHA-256 fingerprint of the validated notification's
+canonical JSON before journal redaction. Identical retries return the committed
+receipt even when redaction changed the stored payload. Different content still
+fails with `notification_id_reused`, including changes to redacted fields.
+Legacy admissions without a fingerprint compare against their persisted content;
+original values removed by redaction cannot be recovered.
+
+The journal-backed layers deeply freeze decoded notifications, including nested
+payload objects and arrays, before `pending` or `drain` exposes them. Outputs
+carry the persisted, possibly redacted content. Consumer mutation cannot change
+later reads or drain receipts.
+
+`admit` and `drain` may run inside an enclosing `journal.transact` while
+standalone queue calls are pending. Both acquire the journal transaction before
+the queue permit. Shared folds are published only after the enclosing commit.
+
+The fold reads only Admitted/Promoted event types through `Journal.entries` and
+keeps the last matching canonical sequence as its cursor. Unrelated run events
+do not require decoding or advance that cursor. A compaction floor that passes
+the cursor causes a conservative `JournalError(compacted)` refusal, including
+for a warm queue. Deployments that compact active notification histories need
+a queue-aware retention or checkpoint policy; the current production
+compositions do not enable compaction.
+
+Admission refuses objects or arrays at depth 256 with `notification_invalid`
+and writes no row. The notification envelope is depth 0; its payload is
+at depth 1. Cyclic payloads receive the same typed refusal.
+
+Admission also refuses a notification larger than 1,048,576 UTF-16 code units
+with `notification_invalid` and writes no row. Every string and object key
+counts at its length and every other value counts as one. The bound is checked
+before the notification is copied, decoded, or fingerprinted.
+
+### AdmissionReceipt
+
+```ts
+interface AdmissionReceipt {
+  readonly notificationId: string
+  readonly decision: NotificationState.AdmissionDecision
+  readonly seq: number | undefined
+  readonly duplicate: boolean
+}
+```
+
+| Field            | Meaning                                                                                                                      |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `notificationId` | The `id` of the notification this receipt answers for.                                                                       |
+| `decision`       | `admitted`, `coalesced`, or `rejected-full`. A caller MUST read it: `rejected-full` means the queue retained nothing.        |
+| `seq`            | The journal sequence the admission committed at. Absent exactly when nothing was written, which today means `rejected-full`. |
+| `duplicate`      | The id had already been admitted. `decision` and `seq` are read back from the committed record rather than recomputed.       |
+
+### DrainInput
+
+```ts
+interface DrainInput {
+  readonly runId: string
+  readonly targetLineageId: string
+  readonly boundary: string
+  readonly wouldIdle: boolean
+  readonly cutoffSeq?: number | undefined
+}
+```
+
+| Field             | Meaning                                                                                                                                                                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runId`           | The run whose journal holds the notifications.                                                                                                                                                                                              |
+| `targetLineageId` | The lineage this boundary belongs to. Notifications for other lineages are left pending.                                                                                                                                                    |
+| `boundary`        | The name of this safe point. With `runId` and `targetLineageId` it is the drain identity.                                                                                                                                                   |
+| `wouldIdle`       | Whether the run would have nothing to do if this boundary delivered nothing. When true and no steer was promoted, one queued notification is promoted.                                                                                      |
+| `cutoffSeq`       | The journal sequence that opened this turn. Steers admitted after it are held for the next boundary. Omitting it delivers everything pending for the lineage. A value that is not a non-negative integer fails with `notification_invalid`. |
+
+### DrainReceipt
+
+```ts
+interface DrainReceipt {
+  readonly notifications: ReadonlyArray<Notification.Notification>
+  readonly boundary: string
+  readonly duplicate: boolean
+}
+```
+
+`notifications` are the ones the committed promotion record names, so two
+processes draining one boundary report the same delivery. `duplicate` is true
+when the boundary had already drained.
+
+### NotificationError
+
+```ts
+class NotificationError extends Schema.TaggedError<NotificationError>()(
+  "/notifications/NotificationError",
+  {
+    code: "notification_unavailable" | "notification_closed" | "notification_full" | "notification_id_reused" | "notification_invalid"
+    message: string
+    notificationId?: string
+    path?: string
+  }
+) {}
+```
+
+| Field            | Meaning                                                                            |
+| ---------------- | ---------------------------------------------------------------------------------- |
+| `code`           | The stable half, and the one to branch on. Defaults to `notification_unavailable`. |
+| `message`        | Human-readable detail. Never carries the offending value.                          |
+| `notificationId` | The notification the failure is about, when one was readable.                      |
+| `path`           | Dotted path of the offending field, for `notification_invalid`.                    |
+
+| Code                       | Means                                                                                                                                     |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `notification_unavailable` | The seam serves nothing, or the journal identity for a drain holds an event this queue did not write.                                     |
+| `notification_closed`      | New public refusal code: this receiver has finished. Start a new request; retrying this message at the closed receiver cannot deliver it. |
+| `notification_full`        | New public refusal code: nothing was retained. Retry the same notification after pending work drains.                                     |
+| `notification_id_reused`   | A stable id was already admitted with different content. A producer bug, not a storage failure.                                           |
+| `notification_invalid`     | The value is not a notification, or a drain's `cutoffSeq` is not a non-negative integer. `path` names the field that failed.              |
+
+Storage failures surface as `Journal.JournalError` instead, so the two stay
+distinguishable.
+
+The queue's ordinary `admit` still returns its existing `rejected-full` receipt.
+`Control.steer` and configured receivers expose that refusal as
+`NotificationError(notification_full)` instead of acknowledging an undeliverable
+message. Configured receiver policies can also emit `notification_closed`.
+Existing notification error fields and older codes are unchanged. Consumers
+with an exhaustive code union must add both new codes. The Control RPC error
+union now carries this existing error class; update remote decoders together
+with the server so they can decode these refusals.
+
+### Constructors and layers
+
+| Export      | Signature                                                                               | What it provides                                                                                                    |
+| ----------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `make`      | `(implementation: Service) => Service`                                                  | The service, from an implementation of its three methods.                                                           |
+| `makeNoop`  | `(overrides?: Partial<Service>) => Service`                                             | A service whose every method fails with `notification_unavailable`, except the ones `overrides` replaces.           |
+| `layerNoop` | `(overrides?: Partial<Service>) => Layer<NotificationQueue>`                            | `makeNoop`, as a layer. Requires nothing.                                                                           |
+| `layerWith` | `(options?: { capacity?: number }) => Layer<NotificationQueue, never, Journal.Journal>` | The journal-backed implementation at the given pending capacity, defaulting to `NotificationState.defaultCapacity`. |
+| `layer`     | `Layer<NotificationQueue, never, Journal.Journal>`                                      | `layerWith()`: the journal-backed implementation at the default capacity.                                           |
+
+Both journal-backed layers write through the journal's unfenced durable channel,
+so `admit` and `drain` return only after the corresponding entry is committed.
+The channel is unfenced on purpose: the notifying process owns no run, so there
+is no ownership fence to hand over, and both records are first-writer-wins on
+their own identity instead.
+
+## Notification
+
+The durable notification payloads and their admission classification. Import
+from `@smthrs/notifications/Notification`.
+
+### Schemas
+
+| Export          | Shape                                                                                                                                     |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `Provenance`    | `{ sourceRunId: string; sourceLineageId: string; sourceTurn: number; sourceActor: string }`. `sourceTurn` is an integer at or above zero. |
+| `HumanSteer`    | Tagged `"human-steer"`. The common fields plus `delivery: "steer"`.                                                                       |
+| `HumanFollowup` | Tagged `"human-followup"`. The common fields plus `delivery: "queue"`.                                                                    |
+| `SystemEvent`   | Tagged `"system-event"`. The common fields plus `delivery: "queue"` and an optional `coalescingKey: string`.                              |
+| `Notification`  | The union of the three.                                                                                                                   |
+
+The common fields on every member are `id` (a non-empty string, and the caller's
+idempotency key), `targetLineageId` (a non-empty string), `provenance`, and
+`payload` (any JSON value).
+
+Provenance travels with the notification because the run that receives one is
+not the run that wrote it. An operator steer, a parent run's event, and a webhook
+all arrive on the same queue, and only these fields say which is which after the
+fact.
+
+### Functions
+
+| Export           | Signature                                            | Returns                                                                                                                                          |
+| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `admissionClass` | `(notification: Notification) => "steer" \| "queue"` | How the notification is allowed to reach the model. Steers are promoted in a batch at turn close; queued notifications one at a time at idle.    |
+| `coalesceKey`    | `(notification: Notification) => string \| null`     | The key the notification coalesces on, or `null` when it must never coalesce. Only a `system-event` that declares a `coalescingKey` returns one. |
+
+## NotificationState
+
+The pure bounded queue: the same rules with no I/O and no journal. Import from
+`@smthrs/notifications/NotificationState`.
+
+### Models
+
+| Export              | Shape                                                                                                    |
+| ------------------- | -------------------------------------------------------------------------------------------------------- |
+| `defaultCapacity`   | `128`. The default maximum pending notifications per run.                                                |
+| `Pending`           | `{ notification: Notification; seq: number }`. `seq` is the journal sequence the admission committed at. |
+| `State`             | `{ capacity: number; items: ReadonlyArray<Pending> }`. Frozen, and every transition returns a new value. |
+| `Admission`         | `{ state: State; decision: AdmissionDecision }`.                                                         |
+| `Promotion`         | `{ state: State; promoted: ReadonlyArray<Pending> }`.                                                    |
+| `AdmissionDecision` | Re-exported from `NotificationEvent`, which owns the single declaration.                                 |
+
+### Operations
+
+| Export           | Signature                                                                                           | What it does                                                                                                                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `empty`          | `(capacity: number) => State`                                                                       | An empty queue. A capacity that is not a finite number becomes zero, so a misconfigured bound refuses everything rather than retaining an unbounded backlog.                                   |
+| `admit`          | `(state: State, notification: Notification, seq: number) => Admission`                              | Admits, coalescing only pending system events with the same key, and keeping the first sequence so replay order stays stable. A queue at capacity decides `rejected-full` and retains nothing. |
+| `applyAdmission` | `(state: State, notification: Notification, seq: number, decision: AdmissionDecision) => State`     | Applies a decision already committed in a journal record. Replay never re-decides.                                                                                                             |
+| `pending`        | `(state: State, admission: "steer" \| "queue", targetLineageId?: string) => ReadonlyArray<Pending>` | Still-pending notifications of one admission class, in durable journal order, for one lineage or for every lineage.                                                                            |
+| `promoteSteers`  | `(state: State, cutoffSeq: number, targetLineageId?: string) => Promotion`                          | Promotes every steer admitted at or before the cutoff. Notifications admitted after it remain pending.                                                                                         |
+| `promoteQueued`  | `(state: State, targetLineageId?: string) => Promotion`                                             | Promotes exactly the oldest pending queued notification, or nothing.                                                                                                                           |
+| `applyPromoted`  | `(state: State, ids: ReadonlyArray<string>) => State`                                               | Removes the ids a durable promotion record names, while replaying history.                                                                                                                     |
+
+## NotificationEvent
+
+The journal event types this package owns. Import from
+`@smthrs/notifications/NotificationEvent`.
+
+| Export              | Value or shape                                                                                                          |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `AdmittedEventType` | `"flows/notifications/Admitted"`. Frozen: the value is already durable in every journal this package has written to.    |
+| `PromotedEventType` | `"flows/notifications/Promoted"`. Frozen for the same reason.                                                           |
+| `AdmissionDecision` | `"admitted" \| "coalesced" \| "rejected-full"`. The one declaration of the admission vocabulary.                        |
+| `Admitted`          | `{ notification: Notification; decision: AdmissionDecision; fingerprint?: string }`.                                    |
+| `Promoted`          | `{ boundary: string; targetLineageId: string; ids: ReadonlyArray<string> }`.                                            |
+| `Event`             | `Admitted \| Promoted`.                                                                                                 |
+| `admissionSourceId` | `(notificationId: string) => JournalEvent.SourceId`. The source every admission of one notification is written under.   |
+| `drainKey`          | `(targetLineageId: string, boundary: string) => string`. One drain's identity, each component percent-encoded.          |
+| `drainSourceId`     | `(targetLineageId: string, boundary: string) => JournalEvent.SourceId`. The source one drain's record is written under. |
+
+A `rejected-full` decision is never written. The queue refuses a full queue in
+the receipt alone, so the notification id stays admissible once a boundary
+drains. The literal remains in `AdmissionDecision` because a reader must stay
+total over a record any writer could have produced.
+
+| Export       | Signature                                             | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isAdmitted` | `(event: Event) => event is Admitted`                 | Whether the owned event is an admission record.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `isPromoted` | `(event: Event) => event is Promoted`                 | Whether the owned event is a promotion record.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `fromEntry`  | `(entry: JournalEvent.Entry) => Option.Option<Event>` | The owned event a journal entry carries. Foreign entries and structurally invalid payloads answer `None`, so a projection over a shared journal stays total. An admission counts only under `admissionSourceId` of the notification it carries, and a promotion only under a `/notifications/drain/` source, so another producer's record with the same event type is ignored. The source scopes records; it does not authenticate the writer. |
+
+## Projection
+
+Import from `@smthrs/notifications/Projection`.
+
+| Export   | Signature                                     | What it does                                                                                                            |
+| -------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `derive` | `Journal.Projection<NotificationState.State>` | Re-derives pending notifications from admitted and promoted journal entries. Foreign entries leave the state unchanged. |
+
+The projection starts at `NotificationState.empty(NotificationState.defaultCapacity)`.
+Capacity gates new admissions; it does not truncate replay. `applyAdmission`
+applies the decision each record committed, so a composition built with
+`NotificationQueue.layerWith` above the default replays every admission it
+wrote. The projected `capacity` stays at the default because no journal record
+carries the bound the layer was built at, so read `items` rather than
+`capacity`.
+
+A versioned edit of a steer that is still pending replaces that item in place
+and keeps its original sequence, the same way the queue reads its own history,
+so an edited steer projects as one pending item.
+
+## SteerPayload
+
+The steering vocabulary carried inside a notification payload. Import from
+`@smthrs/notifications/SteerPayload`.
+
+The vocabulary lives here rather than in either package that uses it: a control
+plane admits a steer and a harness drains it, and neither may depend on the
+other, so the shape they have to agree on belongs beneath both.
+
+| Export            | Shape                                                                                                                                                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Thinking`        | `"none" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh"`. A subset of `ModelRequest.ReasoningEffort` in [`@smthrs/model`](/api/model), which also admits `"max"`; this package deliberately does not depend on it. |
+| `MessagePayload`  | `{ kind: "Message"; body: string }`. The body may be empty.                                                                                                                                                               |
+| `SeatPayload`     | `{ kind: "Seat"; seat: string }`. `seat` is non-empty.                                                                                                                                                                    |
+| `ThinkingPayload` | `{ kind: "Thinking"; thinking: Thinking }`.                                                                                                                                                                               |
+| `ToolsPayload`    | `{ kind: "Tools"; toolNames: ReadonlyArray<string> }`. Non-empty, of non-empty strings. Additive only: steering can widen the active tool set and cannot narrow it.                                                       |
+| `SteerPayload`    | The union of the four.                                                                                                                                                                                                    |
+
+| Export   | Signature                                                   | Returns                                                                                                                                                                                                        |
+| -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `decode` | `(notification: Notification) => SteerPayload \| undefined` | The steering item a notification carries, or `undefined` when it carries none. A `system-event` is never a steer. Inside a human notification, a record with a `body` string and no `kind` reads as a message. |
+| `encode` | `(item: SteerPayload) => SteerPayload`                      | The record the item is stored as. Every item is written with its `kind`, including a message. The result is assignable to `Notification.payload` and shares no mutable structure with `item`.                  |
+
+## Alerts
+
+Run conditions that have lasted too long, turned into durable, coalesced,
+delivered-once notifications. Import from `@smthrs/notifications/Alerts`.
+
+### Policy
+
+| Export             | Shape                                                                                                                                                                                                                                                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Severity`         | `"info" \| "warning" \| "critical"`.                                                                                                                                                                                                                                                               |
+| `Detector`         | `{ field: string; value: string; eventTypes?: ReadonlyArray<string> }`. `field` names a payload key, `value` the value that means the condition holds, and `eventTypes` narrows which entries are consulted; an item ending in `.*`, such as `control.*`, names every event type with that prefix. |
+| `Rule`             | `{ afterMs: number; severity?: Severity; owner?: string; runbook?: string }`. `afterMs` is a whole, non-negative number of milliseconds.                                                                                                                                                           |
+| `Policy`           | `{ defaults?: { severity?; owner?; runbook? }; rules: Record<string, Rule>; detectors?: Record<string, Detector> }`.                                                                                                                                                                               |
+| `defaultDetectors` | `Readonly<Record<string, Detector>>`: `waiting-approval` and `failed` on `status`, `stalled` on `health`, `quota-parked` on `waitingReason`, each consulting only the `control.*` event types.                                                                                                     |
+
+An entry that carries a detector's field with the matching value opens the
+condition; an entry that carries it with any other value closes it. A policy's
+own `detectors` are merged over `defaultDetectors`.
+
+### Decisions
+
+| Export  | Shape                                                                                                                                                              |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Open`  | `{ runId: string; condition: string; since: number }`. `since` is the journal time of the entry that opened the condition.                                         |
+| `Alert` | `{ runId; condition; since; firedAt; severity; coalescingKey; owner?; runbook? }`. `firedAt` is `since + afterMs`, never the wall clock of whichever tick noticed. |
+
+| Export          | Signature                                                                                            | Returns                                                                                                                                                               |
+| --------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `conditions`    | `(policy: Policy, runId: string, entries: ReadonlyArray<JournalEvent.Entry>) => ReadonlyArray<Open>` | Every condition a run's journal leaves open, with the time each opened. `entries` are oldest first.                                                                   |
+| `decide`        | `(policy: Policy, open: ReadonlyArray<Open>, now: number) => ReadonlyArray<Alert>`                   | The alerts the policy raises for the conditions open at `now`. Pure: `now` decides whether an alert is raised and never appears in one.                               |
+| `coalescingKey` | `(runId: string, condition: string) => string`                                                       | The key an alert coalesces on: one open condition on one run. Each component is percent-encoded, so neither can forge another pair's key.                             |
+| `alertId`       | `(alert: Pick<Alert, "coalescingKey" \| "since">) => string`                                         | `alert:<coalescingKey>:<since>`. The identity a delivery is recorded under, stable for the life of one condition. A condition that clears and re-opens gets a new id. |
+
+### Sinks
+
+| Export                  | Signature                                                                                                  | What it is                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SinkService`           | `{ deliver: (alert: Alert) => Effect.Effect<void, AlertError> }`                                           | Where a raised alert is sent. `deliver` MUST be idempotent on `alertId(alert)`, and MUST fail when the page did not go out.                                                                                                                                                                                                                                                                                                                                                                          |
+| `Sink`                  | `Context.Service` under `/notifications/AlertSink`                                                         | The service tag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `layerNoop`             | `Layer<Sink>`                                                                                              | Accepts every alert and sends it nowhere. The admission and the delivery record still happen.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `defaultWebhookTimeout` | `Duration.Duration`                                                                                        | Ten seconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `layerWebhook`          | `(options: { url: string; headers?: Record<string, string>; timeout?: Duration.Duration }) => Layer<Sink>` | POSTs each alert to one webhook using an owned Fetch client with redirects disabled and a scope per delivery. Injected `HttpClient` layers are not used. The body is the alert plus its `alertId`, and the same id is sent as an `Idempotency-Key` header, set after the caller's headers. A non-2xx answer is a failure; an endpoint that never answers fails after `timeout`. The delivery's HTTP span records the method, scheme, host, port and status, never the url's path, query or userinfo. |
+
+| Export        | Shape                                                                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------- |
+| `FailureCode` | `"sink_rejected" \| "sink_unreachable" \| "sink_timeout" \| "sink_misconfigured"`.                              |
+| `AlertError`  | Tagged `/notifications/AlertError`: `{ code: FailureCode; message: string; status?: number; reason?: string }`. |
+
+`sink_misconfigured` is the one code no alert ever carries. `layerWebhook`
+validates its `url` while the layer is built, before any alert exists, and a url
+that is not an absolute `http:` or `https:` one dies there rather than failing
+through the delivery channel: a scheme bound is what keeps a credential set in
+`headers` from being handed to something that is not HTTP.
+
+`AlertError` deliberately holds no request. A webhook request carries the
+credential the deployment handed `layerWebhook`, and an error is logged, encoded,
+and journaled in places a credential must never reach.
+
+### Runtime
+
+| Export           | Shape                                                                                          |
+| ---------------- | ---------------------------------------------------------------------------------------------- |
+| `Tick`           | `{ delivered; failed; refused; suppressed }`, each a `ReadonlyArray<Alert>`.                   |
+| `RuntimeService` | `{ tick: (runId: string) => Effect.Effect<Tick, Journal.JournalError \| NotificationError> }`. |
+| `AlertRuntime`   | `Context.Service` under `/notifications/AlertRuntime`. The service tag.                        |
+
+| Field of `Tick` | Meaning                                                                                                 |
+| --------------- | ------------------------------------------------------------------------------------------------------- |
+| `delivered`     | Raised and accepted by the sink on this tick.                                                           |
+| `failed`        | The sink refused them. Retried on the next tick.                                                        |
+| `refused`       | The notification queue was at capacity. The sink was not called, and they are retried on the next tick. |
+| `suppressed`    | Already delivered, and not delivered again.                                                             |
+
+| Export  | Signature                                                                                      | What it provides                                                                                                                                    |
+| ------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `layer` | `(policy: Policy) => Layer<AlertRuntime, never, Journal.Journal \| NotificationQueue \| Sink>` | The alert runtime over one policy. The policy is decoded when the layer is built, so a rule with an impossible delay fails the composition by name. |
+
+| Export               | Value                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| `deliveredEventType` | `"flows.alerts.delivered"`. One entry per delivered alert.                         |
+| `failedEventType`    | `"flows.alerts.failed"`. One entry per alert per failure code, never one per tick. |
+
+A tick admits the alert, sends it, then journals the delivery. Admission is
+idempotent and the send is not, so a crash between the first two costs a
+duplicate admission the queue drops, while a crash between an accepted send and
+the delivery record costs a duplicate page. That is why `deliver` is required to
+deduplicate on `alertId`.
+
+Both owned event types are excluded from condition detection: they are written
+into the journal the detectors read, and they carry the alert's own vocabulary,
+so reading them as evidence would let a page close the condition it paged about.
+
+A `flows.alerts.delivered` entry suppresses a page only under the source the
+alerter writes, `/notifications/alerts/<alertId>/delivered`. The same entry under
+any other source is ignored. The journal does not bind a source to a writer, so
+this keeps other producers' records out; it does not authenticate the writer.
+
+See [`@smthrs/control`](/api/control) for the run conditions the entries come
+from.
+
+Versioned human steers use a positive safe integer. A higher version replaces the
+pending payload at its original position, with the same owner and delivery
+binding. Promotion consumes the input: a later version returns `consumed: true`
+with the consumed notification, without writing or changing the delivered payload. Older versions are no-ops;
+reusing a version with different content refuses. Replacement and drain share
+the journal transaction, including rollback and cross-process serialization.

package/docs/concepts/admission-and-promotion.md

@@ -0,0 +1,144 @@
+---
+title: "Admission and promotion"
+description: "The two moments a notification passes through: admission by whoever wrote it, and promotion at a boundary the run chose. Delivery classes, coalescing, the capacity bound, the turn cutoff, and the drain identity."
+sidebar:
+  order: 1
+---
+
+A notification passes through two moments, and nothing happens in between.
+
+**Admission** is the writer's moment. Any process may admit at any time: an
+operator steering from a CLI, a parent run signalling a child, a supervisor
+raising an alert. Admission records the notification durably and returns.
+
+**Promotion** is the reader's moment. The run picks it, at a point in its own
+turn where reading a new instruction is safe, and asks the queue what it may
+deliver.
+
+Keeping the two apart is the point of the package. A notification that arrived
+mid-turn and reached the model immediately would change what the model is
+looking at while it is looking at it.
+
+## What a notification is addressed to
+
+Every notification carries `targetLineageId`, and it is the address of the
+reading half: the run itself, or one branch of the run that opens and closes
+turns of its own. The queue treats the value as an opaque string and only ever
+compares it for equality, so its shape is the host's choice. A host with no
+branches passes the run id and is done. A host with branches passes the id of the
+branch the running code belongs to, so a message meant for one branch is not
+consumed by another that never asked for it. The samples on these pages use
+`"run-1/root"`, which keeps the run and the branch visible in one string.
+[`@smthrs/harness`](/api/harness) takes the value as
+`Notifications.layer({ runId, lineageId })` and passes its own.
+
+`provenance` is the other half of the addressing: `targetLineageId` says who
+reads it, and `provenance.sourceActor` says who wrote it.
+
+## Two delivery classes
+
+Every notification declares how it may reach the model, and `Notification.admissionClass`
+reads that declaration back:
+
+| Tag              | Delivery class | When it reaches the model                                       |
+| ---------------- | -------------- | --------------------------------------------------------------- |
+| `human-steer`    | `steer`        | In a batch, at the next turn close.                             |
+| `human-followup` | `queue`        | One at a time, when the run would otherwise have nothing to do. |
+| `system-event`   | `queue`        | The same, and it may coalesce with other events under one key.  |
+
+The class is the whole difference between the first two. A follow-up is not
+urgent enough to interrupt the turn in flight, so it waits for a boundary where
+the run is idle. `DrainInput.wouldIdle` is how the run says it has reached one,
+and a drain promotes a queued notification only when `wouldIdle` is true and no
+steer was promoted at that boundary.
+
+## Admitting is idempotent on the id
+
+`Notification.id` is the caller's idempotency key. Admitting it twice with the
+same content is one notification: the second call reads the committed decision
+back and answers `duplicate: true` with the same `seq`. The comparison is on a
+canonical rendering of the content, with keys sorted and absent values dropped,
+so two encodings that differ only in field order compare equal.
+
+Admitting the same id with different content is a producer bug, and the queue
+refuses it with `notification_id_reused` rather than overwriting either version.
+That refusal is why an alert's fields are all derived from the journal: an alert
+stamped with the wall clock of whichever tick read it would change content
+between retries and become permanently undeliverable.
+
+## Coalescing collapses a chatty producer
+
+Only a `system-event` coalesces, and only when it declares a `coalescingKey`.
+A key is scoped to one `targetLineageId`. While an event with that key is
+pending for that lineage, admitting another one under the same key replaces it
+and answers `coalesced`. Ten updates about one condition are one pending
+notification carrying the latest of them, and two branches reporting the same
+condition under the same ordinary key are two pending notifications, because a
+key names a condition and only the address names a reader.
+
+The replacement substitutes the whole notification, id and provenance included,
+so what a boundary delivers is the latest report rather than the first report's
+envelope around a newer payload. It keeps the first admission's sequence, so
+replay order stays stable: the notification holds the place in the queue that
+the first report earned it. `Notification.coalesceKey` returns `null` for
+everything else, which is what stops two separate human follow-ups from silently
+becoming one.
+
+## The queue is bounded
+
+`NotificationState.defaultCapacity` is 128 pending notifications per run. The
+bound is what makes an undrained run a known quantity rather than a function of
+how long it was ignored.
+
+Admitting past the bound decides `rejected-full`. That decision retains nothing
+and writes no journal entry, so the id stays admissible: once a boundary drains,
+the same call succeeds. `admit` does not fail on a full queue, which is exactly
+why the receipt has to be read. See
+[Handle a full queue](../guides/handle-a-full-queue.md).
+
+`NotificationQueue.layerWith({ capacity })` sets the bound for one composition.
+A capacity that is not a finite number becomes zero, so a misconfigured bound
+refuses everything loudly instead of retaining an unbounded backlog.
+
+## The cutoff holds a mid-turn steer
+
+`DrainInput.cutoffSeq` is the journal sequence that opened the turn now closing.
+`promoteSteers` delivers every steer admitted at or before it and holds the
+rest. A steer that arrived while the turn was running is therefore delivered at
+the next boundary, not the one that is closing around it.
+
+Omitting `cutoffSeq` delivers everything pending for the lineage. That is the
+right default for a caller that has no turn to compare against, and the wrong
+one for a harness closing a turn, which knows the sequence and should pass it.
+
+## The unit of drain is a triple
+
+A drain is identified by `(runId, targetLineageId, boundary)`. Two lineages
+closing a turn under the same boundary name are two drains, recorded separately,
+so neither suppresses the other. Each component is percent-encoded before the
+identity is assembled, so a lineage id containing a slash cannot forge another
+pair's identity and steal its delivery.
+
+The identity is also the deduplication key. The first record committed for a
+triple is the delivery: a second process draining the same boundary reads that
+record back and reports the same notifications with `duplicate: true`, rather
+than deciding a second time and disagreeing. A parked run that walks its
+boundaries looking for one it has not consulted uses exactly that flag.
+
+## The pure state machine underneath
+
+`NotificationState` is the same rules with no I/O and no journal: `empty`,
+`admit`, `promoteSteers`, `promoteQueued`, and `pending` are ordinary functions
+over an immutable `State`. `NotificationQueue` is those functions plus
+durability, and `applyAdmission` and `applyPromoted` are the replay half, which
+applies a committed decision rather than recomputing it.
+
+That split is why the promotion rules can be tested directly, and why the
+capacity bound belongs to `admit` alone. `applyAdmission` retains what a record
+admitted without consulting it, so a deployment that raised the capacity replays
+in full through `Projection.derive`. See
+[the journal records](./journal-records.md).
+
+Reserved `outside_change` payloads fail admission with the typed
+`NotificationError` code `notification_refused` before any journal write.
+They consume no pending capacity and cannot poison another notification’s drain.