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

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

@@ -0,0 +1 @@
+{"version":3,"file":"layerWebhook.d.ts","sourceRoot":"","sources":["../../src/layerWebhook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAS,QAAQ,EAAgB,KAAK,EAAkB,MAAM,QAAQ,CAAA;AAM7E,OAAO,EAAc,IAAI,EAAE,MAAM,gBAAgB,CAAA;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,QAA+B,CAAA;AAoH5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS;IACP,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAA;CACjD,KACA,KAAK,CAAC,KAAK,CAAC,IAAI,CAwD2B,CAAA"}

package/dist/esm/layerWebhook.js

@@ -0,0 +1,186 @@
+/**
+ * The webhook alert sink: one POST per alert, keyed so the receiver can
+ * dedupe on it.
+ *
+ * The transport rules live here rather than beside the policy, because which
+ * endpoint is paged, over which scheme, carrying which credential is a
+ * deployment's decision and the delays are not.
+ *
+ * @since 1.0.0
+ */
+import { Cause, Duration, Effect, Exit, Layer, Option, Tracer } from "effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Headers from "effect/http/Headers";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import { alertId } from "./AlertPolicy.js";
+import { AlertError, Sink } from "./AlertSink.js";
+/**
+ * How long the webhook sink waits for an answer before it calls the page
+ * refused.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const defaultWebhookTimeout = Duration.seconds(10);
+/**
+ * The one check the webhook endpoint gets before an alert is ever built on
+ * it.
+ *
+ * The url is operator config rather than runtime input, so there is no SSRF
+ * vector to close here; the scheme bound is what keeps a credential the
+ * deployment set in `headers` from being handed to a scheme that is not HTTP
+ * at all. A `file:` or `javascript:` url is a config bug, and it fails the
+ * composition the way an impossible policy rule does. The error names no
+ * url: the value can carry basic-auth credentials, and an error is logged.
+ */
+const webhookUrl = (raw) => Effect.suspend(() => {
+    const misconfigured = new AlertError({
+        code: "sink_misconfigured",
+        message: "Alert webhook url must be an absolute http: or https: URL"
+    });
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return Effect.fail(misconfigured);
+    }
+    return parsed.protocol === "http:" || parsed.protocol === "https:"
+        ? Effect.succeed(raw)
+        : Effect.fail(misconfigured);
+});
+/**
+ * Runs a webhook request with redirect following switched off at the fetch
+ * transport.
+ *
+ * The request carries whatever credential the deployment put in `headers`,
+ * and a transport that follows a 3xx re-sends those headers to an origin the
+ * deployment never named. Every other fetch default the composition set is
+ * kept; only the redirect mode is forced. A 3xx therefore surfaces to the
+ * status rule, which calls it `sink_rejected`: a redirecting pager endpoint
+ * is a misconfiguration to fix, not an address to forward credentials to.
+ */
+const followingNoRedirects = (effect) => Effect.flatMap(Effect.serviceOption(FetchHttpClient.RequestInit), (init) => Effect.provideService(effect, FetchHttpClient.RequestInit, {
+    ...(Option.isSome(init) ? init.value : {}),
+    redirect: "manual"
+}));
+const rejected = (status) => new AlertError({ code: "sink_rejected", status, message: `Alert webhook answered ${status}` });
+/**
+ * The span attributes of a delivery that say nothing of the url's path, query
+ * or userinfo: the method, the origin and the answer.
+ */
+const originAttributes = new Set([
+    "http.request.method",
+    "url.scheme",
+    "server.address",
+    "server.port",
+    "http.response.status_code",
+    "error.type"
+]);
+const isHeaderAttribute = (key) => key.startsWith("http.request.header.") || key.startsWith("http.response.header.");
+/**
+ * The headers of a redirect that name where the endpoint moved, which is the
+ * same secret under another address.
+ */
+const redirectHeaderNames = ["location", "content-location"];
+/**
+ * The tracer a delivery opens its HTTP span on: the caller's own, with nothing
+ * of the request left on the span.
+ *
+ * A webhook url is a credential. Slack, Discord and PagerDuty put the secret
+ * in the path, others take it in the query, and a url may carry basic-auth
+ * userinfo. The HTTP client writes the whole url on its span and again in the
+ * failure it ends the span with, and the answer or the transport error it ends
+ * with holds the request. So only the attributes that name the method, the
+ * origin and the answer are kept, with the headers a host chose to record, and
+ * the span ends with the outcome alone: nothing on success, the refusing
+ * status, or that the endpoint could not be reached.
+ */
+const withoutRequest = (tracer) => Tracer.make({
+    ...tracer,
+    span(options) {
+        const span = tracer.span(options);
+        const end = span.end.bind(span);
+        const attribute = span.attribute.bind(span);
+        span.attribute = (key, value) => {
+            if (originAttributes.has(key) || isHeaderAttribute(key))
+                attribute(key, value);
+        };
+        span.end = (endTime, exit) => {
+            if (exit._tag === "Success")
+                return end(endTime, Exit.void);
+            if (Cause.hasInterruptsOnly(exit.cause))
+                return end(endTime, exit);
+            const status = span.attributes.get("http.response.status_code");
+            return end(endTime, Exit.fail(typeof status === "number"
+                ? rejected(status)
+                : new AlertError({ code: "sink_unreachable", message: "Alert webhook could not be reached" })));
+        };
+        return span;
+    }
+});
+/**
+ * A sink that POSTs each alert to one webhook.
+ *
+ * The body is the alert plus its {@link alertId}, and the same id is sent as
+ * an `Idempotency-Key` header, because the package requires the receiver to
+ * dedupe on it and a body without it cannot. The header is set after the
+ * caller's headers, so it is the one this sink sends.
+ *
+ * The endpoint must be an absolute `http:` or `https:` URL, checked when the
+ * layer is built, and the request is made with redirect following disabled:
+ * the caller's headers can carry a credential, and a followed redirect would
+ * re-send them to an origin the deployment never named. A 3xx answer is a
+ * refusal like any other non-2xx, not a forwarding instruction. The sink owns
+ * its Fetch transport; an externally supplied `HttpClient` is not used.
+ * Each delivery has its own scope, which aborts the request and releases any
+ * unread response body on completion, failure, timeout, or interruption.
+ *
+ * The url is treated as a credential, because a webhook's secret usually is
+ * its path or query. The delivery's HTTP span is named for the method and
+ * records the scheme, host, port and answering status, never the path, the
+ * query or userinfo, and it fails with the same url-free reason the sink
+ * returns. A host that records HTTP headers on spans gets every name in
+ * `headers`, and a redirect's `location`, as `<redacted>`.
+ *
+ * A non-2xx response is a failure, not a delivery, and an endpoint that never
+ * answers is a failure after `timeout`. Paging is exactly the case where a
+ * silently dropped request is worse than a retry, and a hung request is worse
+ * than either: it is indistinguishable from silence, so it must not be
+ * possible to wait on one forever.
+ *
+ * @param options the endpoint, any headers it needs, and how long to wait
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerWebhook = (options) => Layer.effect(Sink, Effect.gen(function* () {
+    const url = yield* Effect.orDie(webhookUrl(options.url));
+    const client = HttpClient.withScope(yield* HttpClient.HttpClient);
+    const timeout = options.timeout ?? defaultWebhookTimeout;
+    // `Headers.isRedactedName` compares a string matcher against an
+    // already-lowercased header name without lowercasing the matcher.
+    const redactedNames = [
+        ...Object.keys(options.headers ?? {}).map((name) => name.toLowerCase()),
+        ...redirectHeaderNames
+    ];
+    return {
+        deliver: (alert) => client.execute(HttpClientRequest.post(url).pipe((request) => options.headers === undefined ? request : HttpClientRequest.setHeaders(request, options.headers), HttpClientRequest.setHeader("Idempotency-Key", alertId(alert)), HttpClientRequest.bodyJsonUnsafe({ ...alert, alertId: alertId(alert) }))).pipe(followingNoRedirects, Effect.updateService(Headers.CurrentRedactedNames, (names) => [...names, ...redactedNames]), 
+        // A host may name HTTP spans for their url. This one is named for
+        // its method, as the client names it by default.
+        Effect.provideService(HttpClient.SpanNameGenerator, (request) => request.method), Effect.updateService(Tracer.Tracer, withoutRequest), Effect.flatMap((response) => response.status >= 200 && response.status < 300
+            ? Effect.void
+            : Effect.fail(rejected(response.status))), Effect.timeout(timeout), Effect.scoped, Effect.catchTag("TimeoutError", () => Effect.fail(new AlertError({
+            code: "sink_timeout",
+            message: `Alert webhook did not answer within ${Duration.toMillis(timeout)} ms`
+        }))), 
+        // The transport error holds the request, and the request holds the
+        // caller's headers. Only its reason tag crosses into the failure.
+        Effect.catchTag("HttpClientError", (cause) => Effect.fail(new AlertError({
+            code: "sink_unreachable",
+            reason: cause.reason._tag,
+            message: "Alert webhook could not be reached"
+        }))))
+    };
+})).pipe(Layer.provide(FetchHttpClient.layer));
+//# sourceMappingURL=layerWebhook.js.map

package/dist/esm/layerWebhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layerWebhook.js","sourceRoot":"","sources":["../../src/layerWebhook.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The webhook alert sink: one POST per alert, keyed so the receiver can\n * dedupe on it.\n *\n * The transport rules live here rather than beside the policy, because which\n * endpoint is paged, over which scheme, carrying which credential is a\n * deployment's decision and the delays are not.\n *\n * @since 1.0.0\n */\n\nimport { Cause, Duration, Effect, Exit, Layer, Option, Tracer } from \"effect\"\nimport * as FetchHttpClient from \"effect/http/FetchHttpClient\"\nimport * as Headers from \"effect/http/Headers\"\nimport * as HttpClient from \"effect/http/HttpClient\"\nimport * as HttpClientRequest from \"effect/http/HttpClientRequest\"\nimport { alertId } from \"./AlertPolicy.ts\"\nimport { AlertError, Sink } from \"./AlertSink.ts\"\n\n/**\n * How long the webhook sink waits for an answer before it calls the page\n * refused.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const defaultWebhookTimeout: Duration.Duration = Duration.seconds(10)\n\n/**\n * The one check the webhook endpoint gets before an alert is ever built on\n * it.\n *\n * The url is operator config rather than runtime input, so there is no SSRF\n * vector to close here; the scheme bound is what keeps a credential the\n * deployment set in `headers` from being handed to a scheme that is not HTTP\n * at all. A `file:` or `javascript:` url is a config bug, and it fails the\n * composition the way an impossible policy rule does. The error names no\n * url: the value can carry basic-auth credentials, and an error is logged.\n */\nconst webhookUrl = (raw: string): Effect.Effect<string, AlertError> =>\n  Effect.suspend(() => {\n    const misconfigured = new AlertError({\n      code: \"sink_misconfigured\",\n      message: \"Alert webhook url must be an absolute http: or https: URL\"\n    })\n    let parsed: URL\n    try {\n      parsed = new URL(raw)\n    } catch {\n      return Effect.fail(misconfigured)\n    }\n    return parsed.protocol === \"http:\" || parsed.protocol === \"https:\"\n      ? Effect.succeed(raw)\n      : Effect.fail(misconfigured)\n  })\n\n/**\n * Runs a webhook request with redirect following switched off at the fetch\n * transport.\n *\n * The request carries whatever credential the deployment put in `headers`,\n * and a transport that follows a 3xx re-sends those headers to an origin the\n * deployment never named. Every other fetch default the composition set is\n * kept; only the redirect mode is forced. A 3xx therefore surfaces to the\n * status rule, which calls it `sink_rejected`: a redirecting pager endpoint\n * is a misconfiguration to fix, not an address to forward credentials to.\n */\nconst followingNoRedirects = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n  Effect.flatMap(\n    Effect.serviceOption(FetchHttpClient.RequestInit),\n    (init) =>\n      Effect.provideService(effect, FetchHttpClient.RequestInit, {\n        ...(Option.isSome(init) ? init.value : {}),\n        redirect: \"manual\"\n      })\n  )\n\nconst rejected = (status: number): AlertError =>\n  new AlertError({ code: \"sink_rejected\", status, message: `Alert webhook answered ${status}` })\n\n/**\n * The span attributes of a delivery that say nothing of the url's path, query\n * or userinfo: the method, the origin and the answer.\n */\nconst originAttributes: ReadonlySet<string> = new Set([\n  \"http.request.method\",\n  \"url.scheme\",\n  \"server.address\",\n  \"server.port\",\n  \"http.response.status_code\",\n  \"error.type\"\n])\n\nconst isHeaderAttribute = (key: string): boolean =>\n  key.startsWith(\"http.request.header.\") || key.startsWith(\"http.response.header.\")\n\n/**\n * The headers of a redirect that name where the endpoint moved, which is the\n * same secret under another address.\n */\nconst redirectHeaderNames: ReadonlyArray<string> = [\"location\", \"content-location\"]\n\n/**\n * The tracer a delivery opens its HTTP span on: the caller's own, with nothing\n * of the request left on the span.\n *\n * A webhook url is a credential. Slack, Discord and PagerDuty put the secret\n * in the path, others take it in the query, and a url may carry basic-auth\n * userinfo. The HTTP client writes the whole url on its span and again in the\n * failure it ends the span with, and the answer or the transport error it ends\n * with holds the request. So only the attributes that name the method, the\n * origin and the answer are kept, with the headers a host chose to record, and\n * the span ends with the outcome alone: nothing on success, the refusing\n * status, or that the endpoint could not be reached.\n */\nconst withoutRequest = (tracer: Tracer.Tracer): Tracer.Tracer =>\n  Tracer.make({\n    ...tracer,\n    span(options) {\n      const span = tracer.span(options)\n      const end = span.end.bind(span)\n      const attribute = span.attribute.bind(span)\n      span.attribute = (key, value) => {\n        if (originAttributes.has(key) || isHeaderAttribute(key)) attribute(key, value)\n      }\n      span.end = (endTime, exit) => {\n        if (exit._tag === \"Success\") return end(endTime, Exit.void)\n        if (Cause.hasInterruptsOnly(exit.cause)) return end(endTime, exit)\n        const status = span.attributes.get(\"http.response.status_code\")\n        return end(\n          endTime,\n          Exit.fail(\n            typeof status === \"number\"\n              ? rejected(status)\n              : new AlertError({ code: \"sink_unreachable\", message: \"Alert webhook could not be reached\" })\n          )\n        )\n      }\n      return span\n    }\n  })\n\n/**\n * A sink that POSTs each alert to one webhook.\n *\n * The body is the alert plus its {@link alertId}, and the same id is sent as\n * an `Idempotency-Key` header, because the package requires the receiver to\n * dedupe on it and a body without it cannot. The header is set after the\n * caller's headers, so it is the one this sink sends.\n *\n * The endpoint must be an absolute `http:` or `https:` URL, checked when the\n * layer is built, and the request is made with redirect following disabled:\n * the caller's headers can carry a credential, and a followed redirect would\n * re-send them to an origin the deployment never named. A 3xx answer is a\n * refusal like any other non-2xx, not a forwarding instruction. The sink owns\n * its Fetch transport; an externally supplied `HttpClient` is not used.\n * Each delivery has its own scope, which aborts the request and releases any\n * unread response body on completion, failure, timeout, or interruption.\n *\n * The url is treated as a credential, because a webhook's secret usually is\n * its path or query. The delivery's HTTP span is named for the method and\n * records the scheme, host, port and answering status, never the path, the\n * query or userinfo, and it fails with the same url-free reason the sink\n * returns. A host that records HTTP headers on spans gets every name in\n * `headers`, and a redirect's `location`, as `<redacted>`.\n *\n * A non-2xx response is a failure, not a delivery, and an endpoint that never\n * answers is a failure after `timeout`. Paging is exactly the case where a\n * silently dropped request is worse than a retry, and a hung request is worse\n * than either: it is indistinguishable from silence, so it must not be\n * possible to wait on one forever.\n *\n * @param options the endpoint, any headers it needs, and how long to wait\n * @category layers\n * @since 0.1.0\n */\nexport const layerWebhook = (\n  options: {\n    readonly url: string\n    readonly headers?: Readonly<Record<string, string>> | undefined\n    readonly timeout?: Duration.Duration | undefined\n  }\n): Layer.Layer<Sink> =>\n  Layer.effect(\n    Sink,\n    Effect.gen(function*() {\n      const url = yield* Effect.orDie(webhookUrl(options.url))\n      const client = HttpClient.withScope(yield* HttpClient.HttpClient)\n      const timeout = options.timeout ?? defaultWebhookTimeout\n      // `Headers.isRedactedName` compares a string matcher against an\n      // already-lowercased header name without lowercasing the matcher.\n      const redactedNames = [\n        ...Object.keys(options.headers ?? {}).map((name) => name.toLowerCase()),\n        ...redirectHeaderNames\n      ]\n      return {\n        deliver: (alert) =>\n          client.execute(\n            HttpClientRequest.post(url).pipe(\n              (request) =>\n                options.headers === undefined ? request : HttpClientRequest.setHeaders(request, options.headers),\n              HttpClientRequest.setHeader(\"Idempotency-Key\", alertId(alert)),\n              HttpClientRequest.bodyJsonUnsafe({ ...alert, alertId: alertId(alert) })\n            )\n          ).pipe(\n            followingNoRedirects,\n            Effect.updateService(Headers.CurrentRedactedNames, (names) => [...names, ...redactedNames]),\n            // A host may name HTTP spans for their url. This one is named for\n            // its method, as the client names it by default.\n            Effect.provideService(HttpClient.SpanNameGenerator, (request) => request.method),\n            Effect.updateService(Tracer.Tracer, withoutRequest),\n            Effect.flatMap((response) =>\n              response.status >= 200 && response.status < 300\n                ? Effect.void\n                : Effect.fail(rejected(response.status))\n            ),\n            Effect.timeout(timeout),\n            Effect.scoped,\n            Effect.catchTag(\"TimeoutError\", () =>\n              Effect.fail(\n                new AlertError({\n                  code: \"sink_timeout\",\n                  message: `Alert webhook did not answer within ${Duration.toMillis(timeout)} ms`\n                })\n              )),\n            // The transport error holds the request, and the request holds the\n            // caller's headers. Only its reason tag crosses into the failure.\n            Effect.catchTag(\"HttpClientError\", (cause) =>\n              Effect.fail(\n                new AlertError({\n                  code: \"sink_unreachable\",\n                  reason: cause.reason._tag,\n                  message: \"Alert webhook could not be reached\"\n                })\n              ))\n          )\n      }\n    })\n  ).pipe(Layer.provide(FetchHttpClient.layer))\n"]}

package/docs/README.md

@@ -0,0 +1,146 @@
+---
+title: "@smthrs/notifications"
+description: "A durable queue for telling a running agent something: admit a message from any process, and deliver it only at a point in the run where reading it is safe."
+---
+
+`@smthrs/notifications` is a durable queue for telling a running agent
+something. Any process admits a message at any time, and the run collects what
+it may deliver at a boundary of its own choosing, so an instruction never lands
+in the middle of a turn.
+
+## The problem it solves
+
+An agent that has been working for twenty minutes is not something you can call
+a function on. An operator wants to redirect it, a supervisor wants to raise an
+alarm, a parent run wants to pass down a result. Writing any of those straight
+into the model's context changes what the model is reading while it is reading
+it, and holding them in memory loses them when the process restarts.
+
+This package pulls the two halves apart and puts a journal between them:
+
+- **Admission** is the writer's moment. Any process admits a notification at any
+  time. The queue records it durably and answers with a receipt.
+- **Promotion** is the reader's moment. The run asks, at a point where reading a
+  new instruction is safe, what this boundary may deliver.
+
+Nothing happens in between, and both halves survive a restart. The queue keeps
+no state of its own: it folds each run's state back out of the two journal
+records it writes, so a second process over the same database answers for a run
+the first one admitted to.
+
+Reach for it when you need durable, attributed delivery into a long-running
+process, and when losing a message or delivering it twice would both be wrong:
+operator steering, an idle-time follow-up queue, coalesced system events, or
+alerts about a run that has been stuck too long.
+
+## Install
+
+```bash
+npm install @smthrs/notifications@next effect
+```
+
+Node.js 26.4.0 or later. `@smthrs/journal` is where the durable records go, and
+the example below imports it directly. See [Installation](./installation.md) for
+the SQLite composition a deployment uses.
+
+## Admit a message, deliver it at a turn boundary
+
+The journal here is the production SQLite one over an in-memory database, so
+nothing is stubbed and nothing needs configuring:
+
+```ts
+import * as TestJournal from "@smthrs/journal/test/TestJournal"
+import { NotificationQueue } from "@smthrs/notifications"
+import type { Notification } from "@smthrs/notifications/Notification"
+import * as Effect from "effect/Effect"
+
+const steer: Notification = {
+  _tag: "human-steer",
+  id: "message-1",
+  delivery: "steer",
+  targetLineageId: "run-1/root",
+  provenance: {
+    sourceRunId: "operator",
+    sourceLineageId: "operator",
+    sourceTurn: 0,
+    sourceActor: "human:will"
+  },
+  payload: { kind: "Message", body: "look at the failing test first" }
+}
+
+const program = Effect.gen(function*() {
+  const queue = yield* NotificationQueue.NotificationQueue
+
+  // Whoever is steering, whenever they say it.
+  yield* queue.admit("run-1", steer)
+
+  // The run, at a point where reading a new instruction is safe.
+  const receipt = yield* queue.drain({
+    runId: "run-1",
+    targetLineageId: "run-1/root",
+    boundary: "turn-1",
+    wouldIdle: true
+  })
+  return receipt.notifications.map((notification) => notification.id)
+})
+
+console.log(
+  await Effect.runPromise(
+    program.pipe(
+      Effect.provide(NotificationQueue.layer),
+      Effect.provide(TestJournal.layer()),
+      Effect.scoped,
+      Effect.orDie
+    )
+  )
+)
+```
+
+```text
+[ 'message-1' ]
+```
+
+`id` is your idempotency key: admitting it twice with the same content is one
+notification. `boundary` is the delivery's identity: draining `turn-1` again
+reads the committed record back and reports the same notifications with
+`duplicate: true`, rather than deciding a second time and disagreeing.
+`targetLineageId` is the address of the reader, which the queue only compares for
+equality: pass the run id when a run has one reader, and the branch's id when it
+has several. See
+[Admission and promotion](./concepts/admission-and-promotion.md).
+
+## How it relates to the smithers CLI
+
+This package is one of the pieces behind [`@smthrs/cli`](/api/cli), the `smthrs`
+command line that plans, runs, and inspects durable flows. Running
+`smthrs runs steer <run-id> --message "..."` admits a `human-steer` notification to
+this queue under a stable message id, and the run reads it when its next turn
+closes. `smthrs runs list` fills in each run's pending steer count from the same fold
+`drain` uses, which is why a listing never reports a delivered message as still
+waiting.
+
+Neither package needs the other. Install `@smthrs/cli` for the operator-facing
+command line and everything under it. Install this package when you are building
+the host on the other side: the code that decides where a turn boundary is and
+asks the queue what it may deliver there. [`@smthrs/harness`](/api/harness)
+is the one Smithers ships, and it drains this queue at every boundary.
+
+## Where to go next
+
+- [Installation](./installation.md): the journal, the HTTP client the webhook
+  sink needs, and the import forms.
+- [Quickstart](./quickstart.md): admit a steer and a follow-up, drain both, and
+  read what each step decided.
+- [Admission and promotion](./concepts/admission-and-promotion.md): delivery
+  classes, coalescing, the capacity bound, the turn cutoff, and the drain
+  identity.
+- [The journal records](./concepts/journal-records.md): the two durable events,
+  why replay never re-decides, and what a projection may assume.
+- [How alerting decides](./concepts/alerting.md): why an alert is a function of
+  journal time, and why delivery is at-least-once.
+- [Steer a run](./guides/steer-a-run.md) and
+  [Drain at a turn boundary](./guides/drain-at-a-turn-boundary.md): the writing
+  half and the reading half.
+- [API reference](./api.md): every export, with its signature.
+- [Troubleshooting](./troubleshooting.md): what each symptom means and what to
+  change.