@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/docs/Event.md

@@ -0,0 +1,281 @@
+# Event
+
+`Event.make` defines an event type: something that happens, which subscribers receive as it happens, each subscription selecting with its own arguments. `Event.implement` binds it to the source its occurrences come from, behind an authorizer. Event implementations go in the same list as action implementations: `Action.client` watches them in process; an MCP endpoint ([ActionMcp.md](ActionMcp.md#serve-events)), HTTP routes ([ActionHttp.md](ActionHttp.md#serve-and-watch-events)) and rpcs ([ActionRpc-events.md](ActionRpc-events.md)) serve them; a server POSTs them to a subscriber's callback by webhook ([Webhook.md](Webhook.md)); and a CLI watches them ([ActionCli.md](ActionCli.md#watch-events)). Events are experimental: their surfaces follow MCP's events extension, SEP-3415, a draft, and may change with it.
+
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [Event-failures.md](Event-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.
+
+## Define an event type
+
+One `Event.make` per event type, in the domain's contract file, beside its actions: `input` is what a subscription takes, `payload` what each occurrence carries, and `caller` who may subscribe, as on an action ([Action.md](Action.md#say-who-may-call-an-action)).
+
+```ts example=build-events/src/builds/Builds.ts
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Schema } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+
+const Pipeline = Schema.String.annotate({
+  description: "A pipeline's name, such as api.",
+});
+
+const Status = Schema.Literals(["passed", "failed"]).annotate({
+  description: "How the build ended.",
+});
+
+export const Build = Schema.Struct({
+  id: Schema.String,
+  pipeline: Pipeline,
+  status: Status,
+});
+
+export type Build = typeof Build.Type;
+
+// DEMO ONLY: a CI runner reports finished builds; here a member does, so the example can
+// cause the event it watches.
+export const FinishBuild = Action.make("finishBuild", {
+  description: "Record that a build of a pipeline finished.",
+  input: { pipeline: Pipeline, status: Status },
+  success: Build,
+  readOnly: false,
+  caller: CurrentMember,
+});
+
+// A build run here, which reports each step as it starts, before it answers how the build ended.
+// A caller reads the steps only if it asks, with `onProgress`; each surface carries them its
+// own way. They are a snapshot to show: a caller falling behind misses some, never the answer.
+// What a caller must see every time is the answer, or `build.finished`, which this build causes.
+export const StartBuild = Action.make("startBuild", {
+  description:
+    "Run a build of a pipeline, reporting each step, and record how it ended.",
+  input: { pipeline: Pipeline },
+  success: Build,
+  progress: {
+    step: Schema.String.annotate({
+      description: "The step that started, such as test.",
+    }),
+    done: Schema.Finite.annotate({
+      description: "How many steps finished before it.",
+    }),
+    total: Schema.Finite.annotate({
+      description: "How many steps the build has.",
+    }),
+  },
+  readOnly: false,
+  caller: CurrentMember,
+});
+
+// A build this member may not see is not found, as one that never ran: its id tells nothing.
+export class BuildNotFound extends Schema.TaggedError<
+  BuildNotFound,
+  { readonly brand: unique symbol }
+>()("BuildNotFound", { buildId: Schema.String }, { httpApiStatus: 404 }) {}
+
+// An action answering a stream: its handler returns a `Stream` of lines, and every client's
+// call returns one, each line arriving as the server sends it. HTTP, RPC and a command carry a
+// stream; an MCP tool answers one result, the lines collected once the stream ends, so the MCP
+// endpoint in `routes.ts` leaves it out rather than put a whole log in a model's context.
+export const TailLog = Action.make("tailLog", {
+  description: "Stream a build's log, line by line.",
+  input: {
+    buildId: Schema.String.annotate({
+      description: "The build's id, such as build-1.",
+    }),
+  },
+  success: Action.Stream({ line: Schema.String }),
+  error: BuildNotFound,
+  readOnly: true,
+  caller: CurrentMember,
+});
+
+// An event type: what a subscription takes, what each occurrence carries, and who may
+// subscribe. Like an action's contract, it imports no server code.
+export const BuildFinished = Event.make("build.finished", {
+  description: "A build of a pipeline you may see finished.",
+  input: {
+    pipeline: Schema.optional(Pipeline).annotate({
+      description: "Only this pipeline's builds.",
+    }),
+    status: Schema.optional(Status).annotate({
+      description: "Only builds that ended so.",
+    }),
+  },
+  payload: Build,
+  caller: CurrentMember,
+});
+
+// An event whose occurrence is the whole value: how a pipeline's last build ended, `null` before
+// its first. A subscriber is sent it as it is, then again each time a build of it finishes.
+export const PipelineStatus = Event.make("pipeline.status", {
+  description:
+    "How a pipeline's last build ended: first as it is, then each time one finishes.",
+  input: { pipeline: Pipeline },
+  payload: {
+    status: Schema.NullOr(Status).annotate({
+      description: "How it ended; null before any did.",
+    }),
+  },
+  caller: CurrentMember,
+});
+```
+
+The name's form is in the message `Invalid event name` throws. A contract says nothing about how it is delivered: each surface decides that, as it decides an action's route.
+
+## Read from an upstream you can ask
+
+When the upstream can be asked what happened since a position, such as a table with a sequence column, a change feed or a history API, give `check`: one function, from the subscription's input and a cursor to the occurrences since it and the cursor after them. It answers every subscriber, one that polls and one that holds a stream open alike, running as that subscriber.
+
+```ts example=build-events/src/builds/events.ts
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { BuildFinished } from "./Builds.js";
+import { BuildStore } from "./store.js";
+
+// A check source: one function answers "what finished since this cursor?" for every
+// subscriber, whether it polls or holds a stream open, on every surface. The builder runs once,
+// at startup; the check runs per subscriber, as that subscriber.
+export const buildEvents = Event.implement(
+  BuildFinished,
+  Effect.gen(function* () {
+    const store = yield* BuildStore;
+
+    return {
+      check: ({ pipeline, status }, cursor) =>
+        Effect.gen(function* () {
+          const member = yield* CurrentMember;
+
+          // A first subscription asks with `null`: the store answers the current position, so
+          // the subscriber starts from now.
+          const page = yield* store.finishedSince(
+            member.pipelines,
+            cursor,
+            100
+          );
+
+          return {
+            cursor: page.cursor,
+            hasMore: page.hasMore,
+            // A cursor the store cannot resume from: the subscriber is sent a gap first.
+            truncated: page.truncated,
+            events: page.builds
+              .filter(
+                (build) => pipeline === undefined || build.pipeline === pipeline
+              )
+              .filter(
+                (build) => status === undefined || build.status === status
+              )
+              // The store's own id, within its epoch: a subscriber that sees a build twice,
+              // after a reconnect, drops the second, and never drops a build of a restarted store
+              // as one it saw before.
+              .map((build) => ({
+                eventId: `${page.epoch}/${build.id}`,
+                data: build,
+              })),
+          };
+        }),
+    };
+  }),
+  // Every member may watch; which builds each sees is the store's check, by pipeline.
+  { authorize: Event.allowAll }
+);
+```
+
+[build-events/src/builds/store.ts](../examples/build-events/src/builds/store.ts) is the store. What a check answers for a first subscription and a stale cursor is on `Event.Page`; the rest of a check's rules are on `Event.Check`.
+
+A subscriber holding a stream open is read again every 5 seconds. Where the application writes the store itself, it wakes them at once: after the write, `Event.Events`' `notify`, as [build-events/src/builds/handlers.ts](../examples/build-events/src/builds/handlers.ts) does after each build finishes. A store another process writes is read at the next poll; when a Durable Object reads it is on the Cloudflare package's `ActionDurableObject.handlers`.
+
+- **Check what a subscriber may see where the data is read**, as an action's handler does: `authorize` decides whether it may subscribe at all, and receives the event type, not the subscription's input.
+
+## Send a value whole
+
+When an occurrence is the whole value, such as a status or a list small enough to send whole, give `current`: the value as it is, for the subscription's input. A subscriber is sent it first, then again after each `notify` that reaches its key, never each change it missed one by one: the library keeps the revision that is its cursor, so the store keeps none.
+
+```ts example=build-events/src/builds/status.ts
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { PipelineStatus } from "./Builds.js";
+import { BuildStore } from "./store.js";
+
+// A current source: the value as it is, which the library sends first and again after each
+// notify reaching the subscriber's key, keeping the revision that tells them apart, so the store
+// keeps no cursor for it. The key is the pipeline: a build of another wakes no one here.
+export const statusEvents = Event.implement(
+  PipelineStatus,
+  Effect.gen(function* () {
+    const store = yield* BuildStore;
+
+    return {
+      current: ({ pipeline }) =>
+        Effect.gen(function* () {
+          const member = yield* CurrentMember;
+
+          return { status: yield* store.statusOf(member.pipelines, pipeline) };
+        }),
+      key: ({ pipeline }) => pipeline,
+    };
+  }),
+  // Every member may watch; which pipelines each sees is the store's check.
+  { authorize: Event.allowAll }
+);
+```
+
+[build-events/src/builds/handlers.ts](../examples/build-events/src/builds/handlers.ts) notifies after each build with its pipeline as the key, so a build wakes only that pipeline's subscribers. What a notify without a change sends, and why a value written as it is read is not missed, is on `Event.Current`.
+
+## Keep what nothing else keeps
+
+When no store keeps the occurrences, such as a request made and answered at once or an upstream that only pushes, give `log`: the library keeps each occurrence published to it for subscribers resuming from a cursor, and gives each subscriber what its `match` accepts, shaped by its `transform`.
+
+```ts example=build-events/src/deploys/events.ts
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { Approvers } from "./approvers.js";
+import { DeployRequested } from "./Deploys.js";
+
+// A log source, for occurrences nothing else keeps: the library keeps each one `requestDeploy`
+// publishes, for 10 minutes and at most 10,000 of them by default, and gives each subscriber
+// what its `match` accepts. A subscriber resuming from a cursor gets what the log still holds:
+// after a restart, or once its occurrences are dropped, a gap first. An upstream you can ask
+// "what since?", such as a table, is a check source.
+export const deployEvents = Event.implement(
+  DeployRequested,
+  Effect.gen(function* () {
+    const approvers = yield* Approvers;
+
+    return {
+      log: {},
+      match: ({ environment }, deploy) =>
+        environment === undefined || deploy.environment === environment,
+      // Set up while each subscription lasts, as the subscriber: a stream's as long as it is
+      // read, a poll's until 5 minutes after its last poll. It may run again for one
+      // subscription, after a restart, so standing by twice must be harmless.
+      subscription: ({ environment }) =>
+        Effect.flatMap(CurrentMember, (member) =>
+          approvers.standBy(environment, member.id)
+        ),
+    };
+  }),
+  { authorize: Event.allowAll }
+);
+```
+
+The action publishes each request with `Event.Events`' `publish`, in [build-events/src/deploys/handlers.ts](../examples/build-events/src/deploys/handlers.ts). An upstream that is a stream, such as a message bus, gives it as `log.emit`, each occurrence with the `key` `publish` would take, which the library consumes from the start of a surface serving its event type: kitchen-sink's [issues/events.ts](../examples/kitchen-sink/src/issues/events.ts). How much the log keeps, and what a cursor from another process or a restart reads as, are on `Event.Log`.
+
+- **Prefer `check` wherever the upstream keeps a cursor of its own**: a subscriber then resumes after a restart without a gap.
+
+## Set up a subscription upstream
+
+When each subscription needs something set up upstream while it lasts, such as joining the channel it watches, give the source a `subscription`, as `deployEvents` above does: a scoped Effect, whose finalizer tears it down, run as the subscriber. How long it lasts is on the `subscription` option of `Event.Check` and `Event.Log`.
+
+## Announce to the subscribers
+
+`Event.Events` is where occurrences are announced as they happen: `notify` for a check source, `publish` for a log source. Domain code yields it as it yields a store, and the entrypoint provides one, `Event.layerMemory`, around both the handlers that announce and the surfaces that serve, as [build-events/src/server.ts](../examples/build-events/src/server.ts) does; a host keeping logs elsewhere builds its own with `Event.makeEvents`, as the Cloudflare package's `ActionDurableObject.make` does. A source's `key`, such as the room a subscriber follows, lets an announcement given that key reach that room's subscribers alone, as [live-rpc/src/chat/events.ts](../examples/live-rpc/src/chat/events.ts) keys its messages by room. The rules are on `Event.Events`.
+
+## Watch in process
+
+`Action.client` given event implementations has `watch(event, input, options)`: a `Stream` of `Event.Received`, the occurrences and a `Gap` wherever some were missed, owing per subscription what an action's call owes. [Testing.md](Testing.md#test-events) watches one in a test.

package/docs/README.md

@@ -1,103 +1,72 @@
 # effect-actions
 
-`@gjermundgaraba/effect-actions` defines an Effect action once, as a contract with one
-implementation, and serves it over HTTP, MCP and Effect RPC, gives it to a model as a native
-Toolkit, and runs it from a CLI. Every surface is Effect's own server or client, running the
-same schemas, handler and authorization.
+`@gjermundgaraba/effect-actions` defines an Effect action once, as a contract with one implementation, and serves it over HTTP, MCP and Effect RPC, gives it to a model as a native Toolkit, and runs it from a CLI. Every surface is Effect's own server or client, running the same schemas, handler and authorization.
 
 ## How to read these pages
 
 **Arriving with an error?** A message the library throws says its fix; for any other, step 5.
 
-1. **Open one page per tool call, with your file-reading tool.** Pages are kept small to reduce
-   truncation. Several in one call, however many commands it runs, can be cut by its output
-   limit, with no mark or with one that understates what is lost. If an output says it was
-   truncated, read that page again alone.
-2. **Start from the example closest to what you are building** ([Examples](#examples)). Its
-   README has a layout tree, and all but quickstart's a "Where to look" table naming the file
-   for each thing. Copy its layout and idioms: the examples are the reference for how code is
-   written, and its comments carry the traps it shows. An example shows one way, not the rules
-   or the alternatives: read steps 3 and 4 even when it fits.
+1. **Open one page per tool call, with your file-reading tool.** Pages are kept small to reduce truncation. Several in one call, however many commands it runs, can be cut by its output limit, with no mark or with one that understates what is lost. If an output says it was truncated, read that page again alone.
+2. **Start from the example closest to what you are building** ([Examples](#examples)). Its README has a layout tree, and all but quickstart's a "Where to look" table naming the file for each thing. Copy its layout and idioms: the examples are the reference for how code is written, and its comments carry the traps it shows. An example shows one way, not the rules or the alternatives: read steps 3 and 4 even when it fits.
 3. **Read [Action.md](Action.md) completely.** Every surface builds on it.
-4. **Read the page of each surface you serve** ([Pages](#pages)), and the example files its task
-   sections link.
-5. **For a compiler diagnostic or Effect's own error, search the `*-failures.md` pages** for a
-   fragment of the message without quotes, your own code's first compile error included:
-   `grep -rnF "<fragment>" node_modules/@gjermundgaraba/effect-actions/docs/*-failures.md`. Each
-   module page has one beside it, such as [Action-failures.md](Action-failures.md).
-
-A service others call is [notes-service](../examples/notes-service/) plus
-[Action.md](Action.md), [ActionHttp.md](ActionHttp.md), [ActionMcp.md](ActionMcp.md),
-[Authentication.md](Authentication.md) and [Testing.md](Testing.md).
-
-Where things are, in a project that installs the package: these pages in
-`node_modules/@gjermundgaraba/effect-actions/docs/`, the examples in `examples/` beside them, and
-the declarations with their JSDoc, the reference for signatures, under `dist/`, all at
-the installed version. Install first ([setup.md](setup.md#install)).
+4. **Read the page of each surface you serve** ([Pages](#pages)), and the example files its task sections link.
+5. **For a compiler diagnostic or Effect's own error, search the `*-failures.md` pages** for a fragment of the message without quotes, your own code's first compile error included: `grep -rnF "<fragment>" node_modules/@gjermundgaraba/effect-actions/docs/*-failures.md`. Each module page has one beside it, such as [Action-failures.md](Action-failures.md).
+
+A service others call is [notes-service](../examples/notes-service/) plus [Action.md](Action.md), [ActionHttp.md](ActionHttp.md), [ActionMcp.md](ActionMcp.md), [Authentication.md](Authentication.md) and [Testing.md](Testing.md).
+
+Where things are, in a project that installs the package: these pages in `node_modules/@gjermundgaraba/effect-actions/docs/`, the examples in `examples/` beside them, and the declarations with their JSDoc, the reference for signatures, under `dist/`, all at the installed version. Install first ([setup.md](setup.md#install)).
 
 ## Pages
 
-| Read                                                     | When you need to                                                                                                                                                      |
-| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [setup.md](setup.md)                                     | install, write `tsconfig.json`, import the modules, write the minimal program, lay out an application, bundle a browser client                                        |
-| [Action.md](Action.md)                                   | define a contract and who may call it, implement it, authorize calls, fail with declared and built-in errors, call actions from a job, share one build across servers |
-| [ActionHttp.md](ActionHttp.md)                           | bind actions to JSON routes, serve them, limit request bodies, split a binding across layers and add middleware, publish OpenAPI, call them from Effect or a browser  |
-| [ActionMcp.md](ActionMcp.md)                             | serve MCP tools over HTTP or stdio, describe them to a model, return images, protect them, allow browser clients, add prompts and resources, send notifications       |
-| [ActionRpc.md](ActionRpc.md)                             | bind actions to Effect rpcs, serve them on a protocol, call them, send request context with a call                                                                    |
-| [ActionToolkit.md](ActionToolkit.md)                     | give a model actions as a native Effect AI `Toolkit`, name the caller, ask for approval                                                                               |
-| [ActionCli.md](ActionCli.md)                             | run actions as local commands, or call a server from commands; shape flags, input and output; name the caller; add a command of your own                              |
-| [Authentication.md](Authentication.md)                   | declare how callers sign in, verify credentials, publish OAuth discovery, step up for a scope                                                                         |
-| [Authentication-advanced.md](Authentication-advanced.md) | use an API key or a cookie, read the request in a verifier, protect a route of your own, run a request policy before authentication                                   |
-| [Testing.md](Testing.md)                                 | test an implementation in process, and routes, tools and rpcs in memory, as a signed-in caller; assert on errors                                                      |
+| Read | When you need to |
+| --- | --- |
+| [setup.md](setup.md) | install, write `tsconfig.json`, import the modules, write the minimal program, lay out an application, bundle a browser client |
+| [Action.md](Action.md) | define a contract and who may call it, implement it, authorize calls, fail with declared and built-in errors, answer a retried call once, call actions from a job, share one build across servers |
+| [Action-streams.md](Action-streams.md) | report progress while an action runs, answer a stream of elements |
+| [Event.md](Event.md) | define an event type, read it from an upstream you can ask or one that pushes, set up a subscription upstream, watch events in process |
+| [ActionHttp.md](ActionHttp.md) | bind actions to JSON routes, serve them, limit request bodies, split a binding across layers and add middleware, publish OpenAPI, call them from Effect or a browser, serve and watch events |
+| [ActionMcp.md](ActionMcp.md) | serve MCP tools over HTTP or stdio, describe them to a model, return images, protect them, serve events, allow browser clients, add prompts and resources, send notifications |
+| [ActionRpc.md](ActionRpc.md) | bind actions to Effect rpcs, serve them on a protocol, call them, add native rpcs, send request context with a call |
+| [ActionRpc-events.md](ActionRpc-events.md) | serve and watch events over rpcs, follow what a request names, such as a room |
+| [ActionToolkit.md](ActionToolkit.md) | give a model actions as a native Effect AI `Toolkit`, name the caller, ask for approval |
+| [ActionCli.md](ActionCli.md) | run actions as local commands, or call a server from commands; watch events; shape flags, input and output; name the caller; add a command of your own |
+| [Webhook.md](Webhook.md) | deliver events to a subscriber's callback by webhook, signed, and watch by webhook |
+| [Authentication.md](Authentication.md) | declare how callers sign in, verify credentials, publish OAuth discovery, step up for a scope |
+| [Authentication-advanced.md](Authentication-advanced.md) | use an API key or a cookie, read the request in a verifier, protect a route of your own, run a request policy before authentication |
+| [Testing.md](Testing.md) | test an implementation in process, and routes, tools and rpcs in memory, as a signed-in caller; test events and webhooks; assert on errors |
+| `@gjermundgaraba/effect-actions-cloudflare`'s `docs/README.md` | serve actions, events and Effect rpcs from Cloudflare Durable Objects: install that package; its pages and example are in its own `node_modules` folder |
 
 ## Examples
 
-| Example                                     | What it is                                                                                                       | Start from it when                                                      |
-| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [quickstart](../examples/quickstart/)       | One action, served as a JSON route and an MCP tool, called with its typed client.                                | You want the smallest thing that runs.                                  |
-| [notes-service](../examples/notes-service/) | A service with bearer authentication: a JSON API and MCP tools from one implementation, a CLI, a browser client. | You are building a service others call. Most applications are this.     |
-| [mcp-tools](../examples/mcp-tools/)         | An MCP server whose tools wrap an upstream HTTP API, over stdio and over HTTP, with an image result.             | You are putting an existing API in front of a model.                    |
-| [assistant](../examples/assistant/)         | No server: the same implementations as a model's tools, with approval of writes, and as local commands.          | A model calls your code in process, or you are building a local CLI.    |
-| [live-rpc](../examples/live-rpc/)           | Effect RPC over a WebSocket with a browser-shaped client, each message carrying its own token.                   | A client keeps a connection open, or the application speaks Effect RPC. |
-| [kitchen-sink](../examples/kitchen-sink/)   | The reference: a multi-tenant issue tracker using every module and nearly every option, with an index.           | You need a working use of one specific feature.                         |
+| Example | What it is | Start from it when |
+| --- | --- | --- |
+| [quickstart](../examples/quickstart/) | One action, served as a JSON route and an MCP tool, called with its typed client. | You want the smallest thing that runs. |
+| [notes-service](../examples/notes-service/) | A service with bearer authentication: a JSON API and MCP tools from one implementation, a CLI, a browser client. | You are building a service others call. Most applications are this. |
+| [mcp-tools](../examples/mcp-tools/) | An MCP server whose tools wrap an upstream HTTP API, over stdio and over HTTP, with an image result. | You are putting an existing API in front of a model. |
+| [assistant](../examples/assistant/) | No server: the same implementations as a model's tools, with approval of writes, and as local commands. | A model calls your code in process, or you are building a local CLI. |
+| [live-rpc](../examples/live-rpc/) | Effect RPC over a WebSocket with a browser-shaped client, each message carrying its own token. | A client keeps a connection open, or the application speaks Effect RPC. |
+| [build-events](../examples/build-events/) | A CI service whose members watch events over MCP, HTTP, RPC and a CLI: one read by cursor, one pushed upstream. | Something happens that subscribers should hear about. |
+| [kitchen-sink](../examples/kitchen-sink/) | The reference: a multi-tenant issue tracker using every module and nearly every option, with an index. | You need a working use of one specific feature. |
 
-The index in [kitchen-sink](../examples/kitchen-sink/README.md#index) maps every export and
-option it uses to a file.
+The index in [kitchen-sink](../examples/kitchen-sink/README.md#index) maps every export and option it uses to a file.
 
 ## Choose a surface
 
-| Callers                                                        | Use                                                                                                                |
-| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| Speak JSON over HTTP                                           | `ActionHttp`; clients use `ActionHttp.client`, or `ActionHttp.fetchClient` outside an Effect                       |
-| Are Effect programs, such as a page over one WebSocket         | `ActionRpc`; clients use `ActionRpc.client`                                                                        |
-| Are MCP clients                                                | `ActionMcp.layerHttp` for a hosted endpoint, `ActionMcp.runStdio` for a subprocess, which runs the handlers itself |
-| Are a model in the same process                                | `ActionToolkit`                                                                                                    |
-| Are people or scripts in a terminal                            | `ActionCli`: `make` runs handlers locally, `remote` calls a server through its HTTP binding                        |
-| Are your own code in the same process, such as a job or a test | `Action.client`                                                                                                    |
-
-Surfaces combine: every one that runs handlers takes the same implementations, one or a list,
-and enforces each contract's `caller` and its implementation's `authorize`
-([Action.md](Action.md#authorize-calls)). What a call answers on each surface, a success, bad
-input, a declared error, a refusal or a defect, is on `ActionHttp.layer`, `ActionMcp.layerHttp`
-and `runStdio`, `ActionRpc.layer`, `ActionToolkit.make`, `ActionCli.command`, each typed client,
-and each built-in error: grep the symbol.
+| Callers | Use |
+| --- | --- |
+| Speak JSON over HTTP | `ActionHttp`; clients use `ActionHttp.client`, or `ActionHttp.fetchClient` outside an Effect |
+| Are Effect programs, such as a page over one WebSocket | `ActionRpc`; clients use `ActionRpc.client` |
+| Are MCP clients | `ActionMcp.layerHttp` for a hosted endpoint, `ActionMcp.runStdio` for a subprocess, which runs the handlers itself |
+| Are a model in the same process | `ActionToolkit` |
+| Are people or scripts in a terminal | `ActionCli`: `make` runs handlers locally, `remote` calls a server through its HTTP binding |
+| Are your own code in the same process, such as a job or a test | `Action.client` |
+
+Surfaces combine: every one that runs handlers takes the same implementations, one or a list, and enforces each contract's `caller` and its implementation's `authorize` ([Action.md](Action.md#authorize-calls)). What a call answers on each surface, a success, bad input, a declared error, a refusal or a defect, is on `ActionHttp.layer`, `ActionMcp.layerHttp` and `runStdio`, `ActionRpc.layer`, `ActionToolkit.make`, `ActionCli.command`, each typed client, and each built-in error: grep the symbol.
 
 ## What the library leaves to you
 
-- **Verify credentials or issue them.** The application writes the verifier
-  ([Authentication.md](Authentication.md#verify-credentials)), and login, consent and token
-  issuance are its own. The library defines no scopes: a `Forbidden` names the scopes a call
-  needs, and the library answers with the OAuth challenge
-  ([Authentication.md](Authentication.md#step-up-for-a-scope)); which scheme speaks OAuth is on
-  `Authentication.Options`'s `security`.
-- **Decide who may do what.** It runs the `authorize` an implementation states and writes no rule
-  of its own ([Action.md](Action.md#authorize-calls)).
-- **Filter tool discovery by caller.** What `tools/list` shows a signed-out caller, and the
-  endpoint split that hides protected tools, are on `ActionMcp.LayerHttpOptions`'s
-  `authentication`.
-- **Limit requests.** A rate limit is the handler's, failing with an error its action declares, or
-  middleware's ([Action.md](Action.md#authorize-calls)); the request body limit is the host's
-  ([ActionHttp.md](ActionHttp.md#serve-the-routes)).
-- **Allow browsers across origins.** CORS for JSON routes is the host's, with `HttpRouter.cors`;
-  an MCP endpoint refuses a browser `Origin` it does not list
-  ([ActionMcp.md](ActionMcp.md#allow-browser-clients)).
+- **Verify credentials or issue them.** The application writes the verifier ([Authentication.md](Authentication.md#verify-credentials)), and login, consent and token issuance are its own. The library defines no scopes: a `Forbidden` names the scopes a call needs, and the library answers with the OAuth challenge ([Authentication.md](Authentication.md#step-up-for-a-scope)); which scheme speaks OAuth is on `Authentication.Options`'s `security`.
+- **Decide who may do what.** It runs the `authorize` an implementation states and writes no rule of its own ([Action.md](Action.md#authorize-calls)).
+- **Filter tool discovery by caller.** What `tools/list` shows a signed-out caller, and the endpoint split that hides protected tools, are on `ActionMcp.LayerHttpOptions`'s `authentication`.
+- **Limit requests.** A rate limit is the handler's, failing with an error its action declares, or middleware's ([Action.md](Action.md#authorize-calls)); the request body limit is the host's ([ActionHttp.md](ActionHttp.md#serve-the-routes)).
+- **Allow browsers across origins.** CORS for JSON routes is the host's, with `HttpRouter.cors`; an MCP endpoint refuses a browser `Origin` it does not list ([ActionMcp.md](ActionMcp.md#allow-browser-clients)).

package/docs/Testing-failures.md

@@ -1,10 +1,6 @@
 # Testing failure modes
 
-What you see when something is wrong, and the fix. Search for a fragment of the message.
-A missing service's error can start
-`… with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined'`: search a line
-beneath it, `is missing the following properties from type 'Scope'`, instead.
-The tasks are in [Testing.md](Testing.md).
+What you see when something is wrong, and the fix. Search for a fragment of the message. A missing service's error can start `… with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined'`: search a line beneath it, `is missing the following properties from type 'Scope'`, instead. The tasks are in [Testing.md](Testing.md).
 
 - A route answers an empty 500, which a client method reports as `HttpClientError: Decode error (500 …)`: a defect, or a result that does not encode. `Testing.layer(routes)` logs its cause on the process console, under `it.effect` too: read the test's output, or collect it with a `Logger` provided around the layer.
 - `Type 'Provider<CurrentUser, "notes-service.Login">' is missing the following properties from type 'Scope'` at `it.effect`, or `… is not assignable to type 'never'` at `Effect.runPromise`: the routes serve a protected action without a provider of its descriptor. Provide the real one or a test verifier to the routes; a caller provided around `Testing.layer` does not satisfy them.