@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/docs/Testing.md

@@ -1,25 +1,18 @@
 # Testing
 
-Two ways to test, and neither opens a port. `Action.client` calls an implementation in process:
-what its handlers and its `authorize` do. `Testing.layer` answers the real routes in memory,
-through Effect's own `HttpClient`: what a surface adds, such as authentication, statuses,
-challenges and tool results as sent. The examples put a domain's tests in `test/<domain>/` and
-tests of the surfaces beside them, in `it.effect` from `@effect/vitest`, which supplies a
-`Scope`, a `TestClock` and a `TestConsole` (both imported from `effect/testing`).
+Two ways to test, and neither opens a port. `Action.client` calls an implementation in process: what its handlers and its `authorize` do. `Testing.layer` answers the real routes in memory, through Effect's own `HttpClient`: what a surface adds, such as authentication, statuses, challenges and tool results as sent. The examples put a domain's tests in `test/<domain>/` and tests of the surfaces beside them, in `it.effect` from `@effect/vitest`, which supplies a `Scope`, a `TestClock` and a `TestConsole` (both imported from `effect/testing`).
 
 A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [Testing-failures.md](Testing-failures.md). For one symbol, `grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`: each declaration's JSDoc carries its rules and gotchas, and this page only what an example cannot show.
 
 ## Test an implementation in process
 
-Acquire `Action.client(implementation)` and call its methods
-([Action.md](Action.md#call-actions-in-process)), as
-[notes-service/test/notes/in-process.test.ts](../examples/notes-service/test/notes/in-process.test.ts)
-does. The rules are on `Action.client`.
+Acquire `Action.client(implementation)` and call its methods ([Action.md](Action.md#call-actions-in-process)), as [notes-service/test/notes/in-process.test.ts](../examples/notes-service/test/notes/in-process.test.ts) does. The rules are on `Action.client`.
 
 ```ts example=notes-service/test/notes/in-process.test.ts
 import { describe, expect, it } from "@effect/vitest";
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
 import { CurrentUser } from "../../src/identity/Identity.js";
 import { users } from "../../src/identity/users.js";
 import { notes } from "../../src/notes/handlers.js";
@@ -29,31 +22,41 @@ import { NoteStore } from "../../src/notes/store.js";
 // What the implementation does, with no transport: `Action.client` runs the same decoding,
 // `authorize` and handler a server runs. The caller is provided around each call, as a server
 // provides it per request.
-const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
+const as = (user: keyof typeof users) =>
+  Effect.provideService(CurrentUser, users[user]);
 
 describe("notes, in process", () => {
   it.effect("keeps each user's notes their own", () =>
     Effect.gen(function* () {
       const client = yield* Action.client(notes);
-      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
 
-      expect(yield* client.listNotes().pipe(as("ada"))).toEqual({
+      const note = yield* client
+        .createNote({ title: "Plan", body: "Draft" })
+        .pipe(as("ada"));
+
+      expect(yield* client.listNotes().pipe(as("ada"))).toStrictEqual({
         notes: [{ id: note.id, title: "Plan" }],
       });
-      expect(yield* client.listNotes().pipe(as("grace"))).toEqual({ notes: [] });
+      expect(yield* client.listNotes().pipe(as("grace"))).toStrictEqual({
+        notes: [],
+      });
 
       const missing = new NoteNotFound({ id: note.id });
       const update = { id: note.id, body: "Mine now", revision: note.revision };
 
-      expect(yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("grace")))).toEqual(
-        missing,
-      );
-      expect(yield* Effect.flip(client.updateNote(update).pipe(as("grace")))).toEqual(missing);
-      expect(yield* Effect.flip(client.deleteNote({ id: note.id }).pipe(as("grace")))).toEqual(
-        missing,
-      );
-      expect(yield* client.getNote({ id: note.id }).pipe(as("ada"))).toEqual(note);
-    }).pipe(Effect.provide(NoteStore.layerMemory)),
+      expect(
+        yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("grace")))
+      ).toStrictEqual(missing);
+      expect(
+        yield* Effect.flip(client.updateNote(update).pipe(as("grace")))
+      ).toStrictEqual(missing);
+      expect(
+        yield* Effect.flip(client.deleteNote({ id: note.id }).pipe(as("grace")))
+      ).toStrictEqual(missing);
+      expect(
+        yield* client.getNote({ id: note.id }).pipe(as("ada"))
+      ).toStrictEqual(note);
+    }).pipe(Effect.provide(NoteStore.layerMemory))
   );
 
   it.effect("refuses a write from a caller holding the read scope alone", () =>
@@ -64,36 +67,29 @@ describe("notes, in process", () => {
 
       expect(refusal).toBeInstanceOf(Action.Forbidden);
       expect(refusal.message).toBe("Requires notes:write.");
-    }).pipe(Effect.provide(NoteStore.layerMemory)),
+    }).pipe(Effect.provide(NoteStore.layerMemory))
   );
 });
 ```
 
-- Replace the edge, not the service under test:
-  [mcp-tools/test/printers/printers.test.ts](../examples/mcp-tools/test/printers/printers.test.ts)
-  runs the real upstream service over a fake `HttpClient` Layer.
+- Replace the edge, not the service under test: [mcp-tools/test/printers/printers.test.ts](../examples/mcp-tools/test/printers/printers.test.ts) runs the real upstream service over a fake `HttpClient` Layer.
 - `it.effect` runs on a test clock: fork a call that waits, `TestClock.adjust`, then join it.
-- A stdio server runs the same implementations: test them here. A subprocess test adds only what
-  the process adds, stdout carrying nothing but the protocol.
-- A Toolkit and a CLI need no `Testing` export: call `handle` on `yield* toolkit`, or script a
-  `LanguageModel` ([assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts)),
-  and run commands without a process
-  ([ActionCli.md](ActionCli.md#run-actions-as-local-commands)).
+- A stdio server runs the same implementations: test them here. A subprocess test adds only what the process adds, stdout carrying nothing but the protocol.
+- A Toolkit and a CLI need no `Testing` export: call `handle` on `yield* toolkit`, or script a `LanguageModel` ([assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts)), and run commands without a process ([ActionCli.md](ActionCli.md#run-actions-as-local-commands)).
 
 ## Test routes in memory
 
-Export the routes still requiring what an entrypoint chooses, give the test its own services, and
-provide `Testing.layer(routes)` to each test. What it serves, the requests it reaches, a remote
-`ActionCli` command's included, and what it cannot do are on `Testing.layer`.
+Export the routes still requiring what an entrypoint chooses, give the test its own services, and provide `Testing.layer(routes)` to each test. What it serves, the requests it reaches, a remote `ActionCli` command's included, and what it cannot do are on `Testing.layer`.
 
 The smallest test:
 
 ```ts example=quickstart/test/routes.test.ts
 import { expect, it } from "@effect/vitest";
-import { Effect } from "effect";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Effect } from "effect";
+
 import { Http } from "../src/Api.js";
 import { Greet } from "../src/greeting/Greeting.js";
 import { routes } from "../src/routes.js";
@@ -106,72 +102,116 @@ it.effect("greets over HTTP and as an MCP tool", () =>
 
     expect(yield* http.greet({ name: "Ada" })).toBe("Hello, Ada!");
     expect(yield* mcp.greet({ name: "Ada" })).toBe("Hello, Ada!");
-  }).pipe(Effect.provide(Testing.layer(routes))),
+  }).pipe(Effect.provide(Testing.layer(routes)))
 );
 ```
 
-[notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts) provides a
-store a builder yields, calls the host's own routes with `HttpClient.get("/healthz")` and signs
-callers in.
+[notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts) provides a store a builder yields, calls the host's own routes with `HttpClient.get("/healthz")` and signs callers in.
 
-- A service the test reads too:
-  [kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts).
-- Several `layer`s sharing one build:
-  [kitchen-sink/test/routes.test.ts](../examples/kitchen-sink/test/routes.test.ts)
-  ([Action.md](Action.md#share-one-build-across-servers)).
+- A service the test reads too: [kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts).
+- Several `layer`s sharing one build: [kitchen-sink/test/routes.test.ts](../examples/kitchen-sink/test/routes.test.ts) ([Action.md](Action.md#share-one-build-across-servers)).
 - A fake upstream: [mcp-tools/test/routes.test.ts](../examples/mcp-tools/test/routes.test.ts).
-- Raw web `Request`s beside the typed clients, through one web handler the test disposes of,
-  given to `Testing.layer(handler)`:
-  [kitchen-sink/test/request-policy.test.ts](../examples/kitchen-sink/test/request-policy.test.ts).
+- Raw web `Request`s beside the typed clients, through one web handler the test disposes of, given to `Testing.layer(handler)`: [kitchen-sink/test/request-policy.test.ts](../examples/kitchen-sink/test/request-policy.test.ts).
 
 ## Test as a signed-in caller
 
-Serve the routes behind their provider
-([Authentication.md](Authentication.md#verify-credentials)), and give each client its caller's
-credential in `transformClient`, as `as` in
-[notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts) does for
-`ActionHttp.client` and `ActionMcp.client` alike.
+Serve the routes behind their provider ([Authentication.md](Authentication.md#verify-credentials)), and give each client its caller's credential in `transformClient`, as `as` in [notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts) does for `ActionHttp.client` and `ActionMcp.client` alike. An OAuth access token is such a credential: signing in, or again for more scopes, is the MCP client's part, so an application's tests need no MCP client package.
 
-To change what a credential verifies as, replace the service the verifier reads (`servedWith` in
-[kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)),
-or provide a test verifier: another `Authentication.layer` of the same descriptor.
+To change what a credential verifies as, replace the service the verifier reads (`servedWith` in [kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)), or provide a test verifier: another `Authentication.layer` of the same descriptor.
 
-A typed client decodes a refusal to its error. To assert on the answer as sent, its status and
-its `www-authenticate` challenge, send the request with `HttpClient.execute`, as that file does;
-a tool call's request is built with `ActionMcp.request` ([Test MCP tools](#test-mcp-tools)).
-The status and body of each case are on `ActionHttp.layer` and on each built-in error.
+A typed client decodes a refusal to its error. To assert on the answer as sent, its status and its `www-authenticate` challenge, send the request with `HttpClient.execute`, as that file does; a tool call's request is built with `ActionMcp.request` ([Test MCP tools](#test-mcp-tools)). The status and body of each case are on `ActionHttp.layer` and on each built-in error.
 
 ## Test MCP tools
 
-`ActionMcp.client(actions, options?)` gives one method per action, calling its tool. What it
-decodes and how it fails are on `ActionMcp.client` and `McpCallError`
-([ActionMcp-failures.md](ActionMcp-failures.md)).
+`ActionMcp.client(actions, options?)` gives one method per action, calling its tool. What it decodes and how it fails are on `ActionMcp.client` and `McpCallError` ([ActionMcp-failures.md](ActionMcp-failures.md)).
 
-For what the client's types will not send or its decoding hides, build the request with
-`ActionMcp.request`, which says how to send it:
-[kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)
-asserts a 401, and
-[mcp-tools/test/routes.test.ts](../examples/mcp-tools/test/routes.test.ts) reads `tools/list`.
+For what the client's types will not send or its decoding hides, build the request with `ActionMcp.request`, which says how to send it: [kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts) asserts a 401, and [mcp-tools/test/routes.test.ts](../examples/mcp-tools/test/routes.test.ts) reads `tools/list`.
 
 ## Test rpcs
 
-Export the rpc layer without its protocol ([ActionRpc.md](ActionRpc.md#serve-the-rpcs)) and
-serve it under `Testing.layer`, as
-[live-rpc/test/routes.test.ts](../examples/live-rpc/test/routes.test.ts) does; the protocol each
-side takes is on `Testing.layer`.
-[live-rpc/test/browser.test.ts](../examples/live-rpc/test/browser.test.ts) tests a page's client
-the same way, and
-[kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts)
-serves JSON routes and rpcs in one `Testing.layer`.
+Export the rpc layer without its protocol ([ActionRpc.md](ActionRpc.md#serve-the-rpcs)) and serve it under `Testing.layer`, as [live-rpc/test/routes.test.ts](../examples/live-rpc/test/routes.test.ts) does; the protocol each side takes is on `Testing.layer`. [live-rpc/test/browser.test.ts](../examples/live-rpc/test/browser.test.ts) tests a page's client the same way, and [kitchen-sink/test/identity/session.test.ts](../examples/kitchen-sink/test/identity/session.test.ts) serves JSON routes and rpcs in one `Testing.layer`.
+
+## Test events
+
+Watch an event with the client of the implementations, as here, or of the routes under `Testing.layer`, giving each test its own `Event.layerMemory`:
+
+```ts example=build-events/test/builds/events.test.ts
+import { expect, it } from "@effect/vitest";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect, Fiber, Stream } from "effect";
+import { TestClock } from "effect/testing";
+
+import { BuildFinished } from "../../src/builds/Builds.js";
+import { buildEvents } from "../../src/builds/events.js";
+import { builds } from "../../src/builds/handlers.js";
+import { BuildStore } from "../../src/builds/store.js";
+import { as } from "../support/as.js";
+
+it.effect(
+  "delivers each build a member may see as it finishes, as the subscription selects",
+  () =>
+    Effect.gen(function* () {
+      // One client holds both: the action that finishes builds and the event that reports them.
+      const client = yield* Action.client([builds, buildEvents]);
+
+      const failed = yield* client
+        .watch(BuildFinished, { status: "failed" })
+        .pipe(Stream.take(1), Stream.runCollect, as("grace"), Effect.forkChild);
+
+      // The watch starts from now: let it take its first position before builds finish.
+      yield* TestClock.adjust("0 millis");
+      yield* client
+        .finishBuild({ pipeline: "api", status: "failed" })
+        .pipe(as("ada"));
+      yield* client
+        .finishBuild({ pipeline: "web", status: "passed" })
+        .pipe(as("ada"));
+      // Each build finished notifies: the watch reads at once, with no wait for its next poll.
+      yield* client
+        .finishBuild({ pipeline: "web", status: "failed" })
+        .pipe(as("ada"));
+
+      // grace sees only the web pipeline, and asked only for failures.
+      expect(yield* Fiber.join(failed)).toMatchObject([
+        {
+          _tag: "Occurrence",
+          data: { id: "build-3", pipeline: "web", status: "failed" },
+        },
+      ]);
+    }).pipe(Effect.provide([BuildStore.layerMemory, Event.layerMemory]))
+);
+
+it.effect(
+  "sends a gap first to a subscriber resuming from a cursor the store never gave",
+  () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client([builds, buildEvents]);
+
+      yield* client
+        .finishBuild({ pipeline: "web", status: "passed" })
+        .pipe(as("ada"));
+
+      // A cursor of the store before a restart, its offset one this store has too: what it named
+      // is gone, so the watch is told.
+      const resumed = yield* client
+        .watch(BuildFinished, {}, { cursor: "an-earlier-epoch:0" })
+        .pipe(Stream.take(2), Stream.runCollect, as("grace"));
+
+      expect(resumed).toMatchObject([
+        { _tag: "Gap" },
+        { _tag: "Occurrence", data: { id: "build-1", pipeline: "web" } },
+      ]);
+    }).pipe(Effect.provide([BuildStore.layerMemory, Event.layerMemory]))
+);
+```
+
+A watch forked before what it should see starts from now, so let it take its first position before acting, with `TestClock.adjust("0 millis")`. An announcement, `notify` or `publish`, is read at once; without one, a check source is asked again on its own schedule, every 5 seconds unless it says otherwise, which `TestClock.adjust` moves past. Move the clock only past what the test waits for: a webhook's POST still in flight times out after 5 seconds of it.
+
+Webhook delivery needs an `HttpClient` answering for the subscriber and a `Dns` resolving its callback to a public address, as [build-events/test/support/memory.ts](../examples/build-events/test/support/memory.ts) provides: `Testing.layer` of the subscriber's routes or of a handler, and `Dns.layerStatic`. A subscription made through requests in memory runs on promises the test clock does not drive, so wait for it as that file's `settled` does.
 
 ## Assert on errors
 
-Take the failure with `Effect.flip(call)`, which alone asserts only that the call failed, then
-assert its class and its `message` separately, as the last test of
-[notes-service/test/notes/in-process.test.ts](../examples/notes-service/test/notes/in-process.test.ts) does.
+Take the failure with `Effect.flip(call)`, which alone asserts only that the call failed, then assert its class and its `message` separately, as the last test of [notes-service/test/notes/in-process.test.ts](../examples/notes-service/test/notes/in-process.test.ts) does.
 
-`toEqual` never compares a tagged error's `message`, which is not an enumerable property:
-`expect(error).toEqual(new Action.Forbidden({ message: "anything" }))` passes for every message,
-and so does `toStrictEqual`. Other fields are compared, so `toEqual(new NoteNotFound({ id }))`
-asserts the `id`, and `toEqual(new Action.Forbidden({ scopes: ["issues:write"] }))` still needs the
-message asserted beside it.
+`toEqual` never compares a tagged error's `message`, which is not an enumerable property: `expect(error).toEqual(new Action.Forbidden({ message: "anything" }))` passes for every message, and so does `toStrictEqual`. Other fields are compared, so `toEqual(new NoteNotFound({ id }))` asserts the `id`, and `toEqual(new Action.Forbidden({ scopes: ["issues:write"] }))` still needs the message asserted beside it.

package/docs/Webhook-failures.md

@@ -0,0 +1,8 @@
+# Webhook failure modes
+
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [Webhook.md](Webhook.md).
+
+## At startup
+
+- `Type 'Dns | HttpClient' is not assignable to type 'never'`, or `Type 'Dns' is not assignable to type 'never'`, at `Layer.launch` or `it.effect`: `Webhook.layer` needs an `HttpClient` to POST and `Dns` to check callbacks. Provide `FetchHttpClient.layer` and `NodeDns.layer` where the server starts, or in a test `Testing.layer(receiver)` and `Dns.layerStatic`.
+- `Type 'Receiving' is not assignable to type 'never'`, where a watch given `mode: Webhook.delivery(...)` runs: the watch requires this process's receiver. Provide `Webhook.layerReceiver({ path })` to it, the layer that also serves the route (`Layer.provideMerge`).

package/docs/Webhook.md

@@ -0,0 +1,319 @@
+# Webhook
+
+`Webhook.layer` adds webhook delivery to the MCP endpoints and HTTP routes that serve [events](Event.md): a subscriber names a callback URL and a secret, the server checks that the callback asked for them, and POSTs each occurrence the subscriber may see there, signed, until the subscription lapses, is unsubscribed or is refused. A subscriber keeps it by subscribing again before the time each answer gives. It follows SEP-3415's webhook delivery, so it is experimental, as [events](Event.md) are.
+
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [Webhook-failures.md](Webhook-failures.md). For one symbol, `grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`: each declaration's JSDoc carries its rules and gotchas, and this page only what an example cannot show.
+
+## Deliver events by webhook
+
+Provide `Webhook.layer()` to the routes. One layer holds the subscriptions of every surface it is provided to, so a subscription made over MCP is the one HTTP refreshes. Which events it offers is its first gotcha.
+
+```ts example=build-events/src/routes.ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import * as Webhook from "@gjermundgaraba/effect-actions/Webhook";
+import { Layer } from "effect";
+import { RpcSerialization, RpcServer } from "effect/rpc";
+
+import { Http } from "./Api.js";
+import { buildEvents } from "./builds/events.js";
+import { builds } from "./builds/handlers.js";
+import { logs } from "./builds/log.js";
+import { statusEvents } from "./builds/status.js";
+import { deployEvents } from "./deploys/events.js";
+import { deploys } from "./deploys/handlers.js";
+import { Login } from "./identity/Identity.js";
+import { authenticate } from "./identity/verifier.js";
+import { Rpc } from "./Rpc.js";
+
+// Every domain's implementation, once: the events beside the actions, in one list.
+const implementations = [
+  builds,
+  logs,
+  buildEvents,
+  statusEvents,
+  deploys,
+  deployEvents,
+];
+
+// The actions as MCP tools and the events as MCP events, at `/mcp`. A client polls with
+// `events/poll`, or holds `events/stream` open and is pushed each occurrence. Both events are
+// protected, so each request needs a member's token, and each subscriber sees what its token
+// lets it. This long-lived process holds the deploy event's `subscription` hook between polls and
+// its log in memory, and pushes each occurrence: a `requestScoped` endpoint would serve the events
+// by poll and webhook alone, and a serverless host, where no process lasts, check sources alone,
+// without `Webhook.layer`.
+//
+// A tool answers one result, so `tailLog` would collect a whole log before answering, all of it
+// in a model's context: its implementation, `logs`, is left out, and the endpoint serves every
+// other action and every event.
+const mcp = ActionMcp.layerHttp(
+  [builds, buildEvents, statusEvents, deploys, deployEvents],
+  {
+    name: "build-events",
+    version: "1.0.0",
+    authentication: Login,
+  }
+);
+
+// The same implementations as routes under `/api`, for a client that speaks HTTP rather than
+// MCP: one implementation of each event serves every surface.
+const api = ActionHttp.layer(Http, implementations);
+
+// And as Effect RPC at `/rpc`, over HTTP. A watch is a stream rpc that never ends, so the
+// serialization frames each element as it is sent: `layerNdjson` does, where `layerJson` would
+// answer once every stream of the request ended, which a watch never does.
+const rpc = ActionRpc.layer(Rpc, implementations).pipe(
+  Layer.provide(RpcServer.layerProtocolHttp({ path: "/rpc" })),
+  Layer.provide(RpcSerialization.layerNdjson)
+);
+
+// Webhook delivery for MCP and HTTP alike: a member names a callback URL and a secret, with
+// MCP's `events/subscribe` or `POST /api/events/<name>/subscribe`, and each occurrence it may see
+// is POSTed there, signed. One layer holds the subscriptions of both, so either surface refreshes
+// one made over the other. `persist` keeps each in a `KeyValueStore`, so a restart goes on
+// delivering from where it reached, as the subscriber `Login`'s `schema` keeps. It needs an
+// `HttpClient` to POST, `Dns` to check where each callback resolves, and the store, which
+// `server.ts` provides.
+export const routes = Layer.mergeAll(mcp, api, rpc).pipe(
+  Layer.provide(authenticate),
+  Layer.provide(Webhook.layer({ persist: true }))
+);
+```
+
+The layer needs an `HttpClient` to POST, `Dns` to check where each callback resolves, unless `resolveCallbacks` is `false`, and, with `persist`, a `KeyValueStore`: the entrypoint, [build-events/src/server.ts](../examples/build-events/src/server.ts), provides all three.
+
+Its options, how long a subscription is granted, which callbacks skip the handshake and the address check, and how long a failing delivery is retried, are `Webhook.Options`; what each POST holds is on `layer`.
+
+- **Which deployment.** Subscriptions are delivered from the server's memory, so a long-lived process serves them and a serverless host cannot; a Cloudflare Durable Object can, with `@gjermundgaraba/effect-actions-cloudflare`'s `ActionDurableObject.layerWebhooks`. A restart drops them until each subscriber's next refresh, unless the layer keeps them: `Webhook.layer({ persist: true })` writes each to the application's `KeyValueStore`, and each surface restores its own as it builds, the subscriber's identity kept by its authentication's `schema`, as `server.ts` and [build-events/src/identity/Identity.ts](../examples/build-events/src/identity/Identity.ts) show. What a restored delivery lacks is on `Webhook.Options.persist`. The layer is its store's one writer: give each process a store of its own, since replicas sharing one would each deliver every subscription and lose each other's writes.
+
+## Subscribe a callback
+
+Over MCP a subscriber sends SEP-3415's `events/subscribe` and `events/unsubscribe`; over HTTP it POSTs to the binding's `<prefix>/events/<name>/subscribe` and `/unsubscribe`, as below, whose OpenAPI document describes each field. A subscription is one per subscriber, event, input and URL: subscribing again refreshes it, and a new secret replaces the old one, as `Webhook.layer` says.
+
+```ts example=build-events/test/webhooks.test.ts
+import { describe, expect, it } from "@effect/vitest";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Effect, Layer, Queue, Schema } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+
+import { Http } from "../src/Api.js";
+import { routes } from "../src/routes.js";
+import { inMemory } from "./support/memory.js";
+
+// The subscriber's secret: `whsec_` and 24 to 64 random bytes in base64. The server signs each
+// POST with it, and the subscriber checks each POST it receives against it.
+const secret = `whsec_${Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("base64")}`;
+
+// A subscriber's check, as Standard Webhooks defines it: an HMAC-SHA256 of the id, the
+// timestamp and the body exactly as received, among the space-separated `v1,` signatures.
+const signed = async (request: Request, body: string) => {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    Buffer.from(secret.slice("whsec_".length), "base64"),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+
+  const signedContent = [
+    request.headers.get("webhook-id"),
+    request.headers.get("webhook-timestamp"),
+    body,
+  ].join(".");
+
+  const expected = Buffer.from(
+    await crypto.subtle.sign(
+      "HMAC",
+      key,
+      new TextEncoder().encode(signedContent)
+    )
+  ).toString("base64");
+
+  return (request.headers.get("webhook-signature") ?? "")
+    .split(" ")
+    .includes(`v1,${expected}`);
+};
+
+const Delivered = Schema.fromJsonString(
+  Schema.Record(Schema.String, Schema.Json)
+);
+
+interface Received {
+  readonly body: typeof Delivered.Type;
+  readonly signed: boolean;
+}
+
+// grace's server: it answers the verification POST by echoing its challenge, which proves it
+// asked for these deliveries, and acknowledges each delivery with a 2xx.
+const subscriber =
+  (received: Queue.Enqueue<Received>) => async (request: Request) => {
+    const text = await request.text();
+    const body = Schema.decodeSync(Delivered)(text);
+
+    Queue.offerUnsafe(received, { body, signed: await signed(request, text) });
+
+    return body["type"] === "verification"
+      ? Response.json({ challenge: body["challenge"] })
+      : new Response(null);
+  };
+
+const served = (received: Queue.Enqueue<Received>) =>
+  Testing.layer(routes).pipe(
+    Layer.provide(inMemory(Testing.layer(subscriber(received))))
+  );
+
+const Subscribed = Schema.Struct({
+  id: Schema.String,
+  refreshBefore: Schema.NullOr(Schema.String),
+  deliveryStatus: Schema.optional(
+    Schema.Struct({
+      active: Schema.Boolean,
+      lastError: Schema.NullOr(Schema.String),
+    })
+  ),
+});
+
+const subscribe = Effect.flatMap(HttpClient.HttpClient, (client) =>
+  client.execute(
+    HttpClientRequest.post("/api/events/build.finished/subscribe").pipe(
+      HttpClientRequest.bearerToken("grace"),
+      HttpClientRequest.bodyJsonUnsafe({
+        input: { status: "passed" },
+        delivery: { url: "https://hooks.example.com/grace", secret },
+      })
+    )
+  )
+).pipe(
+  Effect.flatMap((response) => response.json),
+  Effect.flatMap(Schema.decodeUnknownEffect(Subscribed))
+);
+
+describe("the service, by webhook", () => {
+  it.effect("POSTs each build a member may see to its callback, signed", () =>
+    Effect.flatMap(Queue.unbounded<Received>(), (received) =>
+      Effect.gen(function* () {
+        const ada = yield* ActionHttp.client(Http, {
+          transformClient: HttpClient.mapRequest(
+            HttpClientRequest.bearerToken("ada")
+          ),
+        });
+
+        // The answer names the subscription, which each POST's `x-mcp-subscription-id`
+        // carries, and when to subscribe again to keep it: one not refreshed by then ends.
+        const subscription = yield* subscribe;
+        const verification = yield* Queue.take(received);
+
+        yield* ada.finishBuild({ pipeline: "api", status: "passed" });
+        // Each build finished notifies `build.finished`: the server asks the store at once, and
+        // POSTs what it answers.
+        yield* ada.finishBuild({ pipeline: "web", status: "passed" });
+
+        // grace sees only the web pipeline.
+        const delivery = yield* Queue.take(received);
+
+        // The same request again refreshes the subscription, and answers how it is going.
+        const refreshed = yield* subscribe;
+
+        expect(verification).toMatchObject({
+          body: { type: "verification" },
+          signed: true,
+        });
+        expect(delivery).toMatchObject({
+          body: {
+            name: "build.finished",
+            data: { id: "build-2", pipeline: "web" },
+          },
+          signed: true,
+        });
+        expect(refreshed).toMatchObject({
+          id: subscription.id,
+          deliveryStatus: { active: true, lastError: null },
+        });
+      }).pipe(Effect.provide(served(received)))
+    )
+  );
+});
+```
+
+## Watch by webhook
+
+A client of an MCP endpoint or of HTTP routes watches by webhook with `mode: Webhook.delivery({ baseUrl })`: the watch keeps a place at `Webhook.layerReceiver`, a route this process serves, subscribes that route's path under `baseUrl` with the place's id and secret, reads what the server POSTs there, refreshes the subscription while it is read, and unsubscribes when it ends. Such a watch requires the receiver in its type; it is built once, the watch given it beside the routes (`Layer.provideMerge`). It is served by the process that watches: behind an edge, route its path there, and where nothing can reach the process, watch by stream or poll instead.
+
+```ts example=build-events/src/notifier/routes.ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Webhook from "@gjermundgaraba/effect-actions/Webhook";
+import { Effect, Layer, Predicate, Stream } from "effect";
+import type { Redacted } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { KeyValueStore } from "effect/persistence";
+
+import { Http } from "../Api.js";
+import { BuildFinished } from "../builds/Builds.js";
+import { Notices } from "./Notices.js";
+
+/** Where build-events is, who the notifier signs in as there, and where it is reached itself. */
+export interface NotifierOptions {
+  readonly buildEvents: string;
+  readonly token: string | Redacted.Redacted;
+  /** This process's public https origin, which build-events POSTs to. */
+  readonly publicUrl: string;
+}
+
+// The route build-events POSTs each failed build to, where the watch below reads them: the
+// watch's delivery appends its path to this process's public URL.
+const receiver = Webhook.layerReceiver({ path: "/hooks/builds" });
+
+// A second service, the notifier: it watches build.finished for failures by webhook, the
+// server POSTing each to it, rather than holding a stream open to build-events.
+const watcher = ({ buildEvents, token, publicUrl }: NotifierOptions) =>
+  Layer.effectDiscard(
+    Effect.gen(function* () {
+      const notices = yield* Notices;
+
+      const builds = yield* ActionHttp.client(Http, {
+        baseUrl: buildEvents,
+        transformClient: HttpClient.mapRequest(
+          HttpClientRequest.bearerToken(token)
+        ),
+      });
+
+      yield* Effect.forkScoped(
+        builds
+          .watch(
+            BuildFinished,
+            { status: "failed" },
+            {
+              mode: Webhook.delivery({ baseUrl: publicUrl }),
+              // Where it reached is kept, so a restart resumes there; failures the server no
+              // longer keeps arrive as a Gap instead.
+              resume: {
+                store: yield* KeyValueStore.KeyValueStore,
+                key: "failed-builds",
+              },
+            }
+          )
+          .pipe(
+            // A Gap says failures were missed, which no notice can name: it is logged, for an
+            // operator to look the builds up.
+            Stream.runForEach((received) =>
+              Predicate.isTagged(received, "Occurrence")
+                ? notices.add(received.data)
+                : Effect.logWarning("Failed builds were missed", received)
+            ),
+            // A failure no reconnect outlasts, such as a wrong PUBLIC_URL or a revoked token,
+            // ends the watch: it is logged here, for a deployment to alert on or restart by.
+            Effect.tapCause(Effect.logError)
+          )
+      );
+    })
+  );
+
+/** The notifier's routes: the receiver, and the watch reading from that same receiver. */
+export const notifier = (options: NotifierOptions) =>
+  watcher(options).pipe(Layer.provideMerge(receiver));
+```
+
+[build-events/test/notifier.test.ts](../examples/build-events/test/notifier.test.ts) runs both services in memory. What the receiver accepts is on `layerReceiver`, and what a watch needs on `delivery`.

package/docs/setup-failures.md

@@ -1,7 +1,6 @@
 # Setup failure modes
 
-What you see when something is wrong, and the fix. Search for a fragment of the message.
-The tasks are in [setup.md](setup.md).
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [setup.md](setup.md).
 
 - `TS1149: File name '…/assistant.ts' differs from already included file name '…/Assistant.ts' only in casing`: a lowercase file is named for its domain beside the domain's contract. Name lowercase files for their role, such as `handlers.ts` or `turns.ts`: on a disk that ignores case the two are one file.
 - `Cannot find module '@gjermundgaraba/effect-actions'`: there is no root export. Import a subpath from [Entry points](setup.md#entry-points), never the root or a `dist/` path.
@@ -9,5 +8,5 @@ The tasks are in [setup.md](setup.md).
 - A page that loads Effect from an import map still bundles a second copy of Effect or of some of its modules, or fails to resolve `effect/Schema` in the browser when its bundler externalizes subpaths, as esbuild's `--external:effect` does: a module of the page imports an Effect specifier the map does not serve. Serve the specifiers [Bundle for a browser](setup.md#bundle-for-a-browser) lists, and import Effect through them in the page's own modules too.
 - A page loading Effect from an import map fails with `Failed to resolve module specifier "effect/Cause"` in Chromium: the map points at Effect's published files and lacks a specifier Effect imports itself. Map `effect/Cause`, `effect/Effect`, `effect/Exit` and `effect/Function` to the same files, or serve Effect from a build that resolves its own imports.
 - A page fails at load with `does not provide an export named …`: it serves only the names it uses of an Effect specifier, from a vendored module or a trimmed bundle, and the package imports another. Serve each specifier whole.
-- Type errors inside `effect/*` modules after install, an unmet peer warning for `effect`, such as `found 4.1.0`, or a start failing with `Cannot find module '…/effect/dist/…'` under an `@effect/*` package: more than one Effect release is installed, or one outside the peer range. Install the `effect` range [Install](setup.md#install) names, with every `@effect/*` package at the version `effect` resolved to, such as `@effect/platform-node@4.0.4` beside `effect@4.0.4`.
+- Type errors inside `effect/*` modules after install, an unmet peer warning for `effect`, such as `found 4.1.0`, or a start failing with `Cannot find module '…/effect/dist/…'` under an `@effect/*` package: more than one Effect release is installed, or one outside the peer range. Install the `effect` range [Install](setup.md#install) names, with every `@effect/*` package at the version `effect` resolved to, such as `@effect/platform-node@4.0.5` beside `effect@4.0.5`.
 - `Cannot find module 'effect/unstable/http'` (or `…/httpapi`, `…/cli`, `…/ai`): these modules are now `effect/http`, `effect/http-api`, `effect/cli` and `effect/ai`.