@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/docs/Action.md

@@ -1,24 +1,16 @@
 # Action
 
-`Action.make` defines a contract: what an action takes and answers, whether it changes anything,
-and who may call it. `Action.implement` binds contracts to handlers, behind an authorizer. Every
-surface takes the implementation it returns, or a list of them, and `Action.client` calls one in
-process.
+`Action.make` defines a contract: what an action takes and answers, whether it changes anything, and who may call it. `Action.implement` binds contracts to handlers, behind an authorizer. Every surface takes the implementation it returns, or a list of them, and `Action.client` calls one in process.
 
-A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search
-[Action-failures.md](Action-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.
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [Action-failures.md](Action-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. An action reporting progress or answering a stream is on [Action-streams.md](Action-streams.md); what happens apart from a call, which a subscriber watches, is an event type, on [Event.md](Event.md).
 
 ## Define a contract
 
-One `Action.make` per action, in the domain's contract file. Export the domain's actions as one
-`as const` list ([notes-service/src/notes/Notes.ts](../examples/notes-service/src/notes/Notes.ts)):
-`implement` and every surface take lists.
+One `Action.make` per action, in the domain's contract file. Export the domain's actions as one `as const` list ([notes-service/src/notes/Notes.ts](../examples/notes-service/src/notes/Notes.ts)): `implement` and every surface take lists.
 
 ```ts example=quickstart/src/greeting/Greeting.ts
-import { Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Schema } from "effect";
 
 // A contract: what the action takes and answers, whether it changes anything, and who may
 // call it. It imports no server code, so any client can import it, a browser page included.
@@ -31,48 +23,26 @@ export const Greet = Action.make("greet", {
 });
 ```
 
-[notes-service/src/notes/Notes.ts](../examples/notes-service/src/notes/Notes.ts) adds declared
-errors with their statuses, described fields and the list;
-[kitchen-sink/src/issues/Issues.ts](../examples/kitchen-sink/src/issues/Issues.ts) uses every
-option. The rules of each option, `input`'s optional fields and `error`'s tags included, are on
-`Action.Options`; where an action must be listed to be served, and matching by object identity,
-are on `Action.make`. The list each surface takes lives in one file beside the contracts
-([kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts)).
+[notes-service/src/notes/Notes.ts](../examples/notes-service/src/notes/Notes.ts) adds declared errors with their statuses, described fields and the list; [kitchen-sink/src/issues/Issues.ts](../examples/kitchen-sink/src/issues/Issues.ts) uses every option. The rules of each option, `input`'s optional fields and `error`'s tags included, are on `Action.Options`; where an action must be listed to be served, and matching by object identity, are on `Action.make`. The list each surface takes lives in one file beside the contracts ([kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts)).
 
-- **List an action as a tool only where a model may hold what it takes and returns.** A tool
-  call passes both through the model's context and records its arguments on the current span,
-  a `Schema.Redacted` value included.
+- **List an action as a tool only where a model may hold what it takes and returns.** A tool call passes both through the model's context, and `ActionToolkit`, through Effect's toolkit, records its arguments on the current span, a `Schema.Redacted` value included.
 
 ## Say who may call an action
 
-`caller: Action.Anyone` makes a public action; an identity service, `caller: CurrentUser`, a
-protected one, whose identity a remote surface gets by authenticating the request
-([Authentication.md](Authentication.md#declare-how-callers-sign-in)) and a local surface, which
-has no one to authenticate, from the host ([ActionToolkit.md](ActionToolkit.md#name-the-caller),
-[ActionCli.md](ActionCli.md#name-the-caller), [ActionMcp.md](ActionMcp.md#serve-tools-over-stdio)).
+`caller: Action.Anyone` makes a public action; an identity service, `caller: CurrentUser`, a protected one, whose identity a remote surface gets by authenticating the request ([Authentication.md](Authentication.md#declare-how-callers-sign-in)) and a local surface, which has no one to authenticate, from the host ([ActionToolkit.md](ActionToolkit.md#name-the-caller), [ActionCli.md](ActionCli.md#name-the-caller), [ActionMcp.md](ActionMcp.md#serve-tools-over-stdio)).
 
-`CurrentUser` is declared in
-[notes-service/src/identity/Identity.ts](../examples/notes-service/src/identity/Identity.ts), and
-a public action in [notes-service/src/status/Status.ts](../examples/notes-service/src/status/Status.ts).
-The rules of an identity, never provided at startup, are on `Action.Options.caller`; a test
-sends each caller's credential instead
-([Testing.md](Testing.md#test-as-a-signed-in-caller)).
+`CurrentUser` is declared in [notes-service/src/identity/Identity.ts](../examples/notes-service/src/identity/Identity.ts), and a public action in [notes-service/src/status/Status.ts](../examples/notes-service/src/status/Status.ts). The rules of an identity, never provided at startup, are on `Action.Options.caller`; a test sends each caller's credential instead ([Testing.md](Testing.md#test-as-a-signed-in-caller)).
 
-- **One protected contract serves callers with a token over HTTP and a local host without
-  one**, never a public copy of it: the host provides the caller around `runStdio`
-  ([notes-service/src/stdio.ts](../examples/notes-service/src/stdio.ts)); a second audience is
-  `Operator` in [kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts).
+- **One protected contract serves callers with a token over HTTP and a local host without one**, never a public copy of it: the host provides the caller around `runStdio` ([notes-service/src/stdio.ts](../examples/notes-service/src/stdio.ts)); a second audience is `Operator` in [kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts).
 
 ## Implement actions
 
-`Action.implement` binds a handler to one action, or a record of handlers keyed by name to a
-list. Either may instead be a builder: an Effect returning the handler or the record, whose
-services are startup services. What a handler yields per call, the caller first, is a
-request-time requirement.
+`Action.implement` binds a handler to one action, or a record of handlers keyed by name to a list. Either may instead be a builder: an Effect returning the handler or the record, whose services are startup services. What a handler yields per call, the caller first, is a request-time requirement.
 
 ```ts example=notes-service/src/notes/handlers.ts
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
 import { authorize } from "../identity/authorize.js";
 import { CurrentUser } from "../identity/Identity.js";
 import { Notes } from "./Notes.js";
@@ -95,47 +65,44 @@ export const notes = Action.implement(
 
           return { notes: owned.map(({ id, title }) => ({ id, title })) };
         }),
-      getNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.get(user.id, id)),
+      getNote: ({ id }) =>
+        Effect.flatMap(CurrentUser, (user) => store.get(user.id, id)),
       createNote: ({ requestId, title, body }) =>
-        Effect.flatMap(CurrentUser, (user) => store.create(user.id, title, body, requestId)),
+        Effect.flatMap(CurrentUser, (user) =>
+          store.create(user.id, title, body, requestId)
+        ),
       updateNote: ({ id, body, revision }) =>
-        Effect.flatMap(CurrentUser, (user) => store.update(user.id, id, body, revision)),
-      deleteNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.remove(user.id, id)),
-      importNotes: ({ notes }) =>
+        Effect.flatMap(CurrentUser, (user) =>
+          store.update(user.id, id, body, revision)
+        ),
+      deleteNote: ({ id }) =>
+        Effect.flatMap(CurrentUser, (user) => store.remove(user.id, id)),
+      importNotes: ({ notes: imported }) =>
         Effect.map(
-          Effect.flatMap(CurrentUser, (user) => store.createAll(user.id, notes)),
-          (created) => ({ notes: created }),
+          Effect.flatMap(CurrentUser, (user) =>
+            store.createAll(user.id, imported)
+          ),
+          (created) => ({ notes: created })
         ),
     };
   }),
-  { authorize },
+  { authorize }
 );
 ```
 
-A plain handler, no builder, is
-[quickstart/src/greeting/handlers.ts](../examples/quickstart/src/greeting/handlers.ts). The
-builder's rules, once per layer graph, a scope per call, passing the builder to `implement`
-itself, calling through `Action.client` and never the function you passed, are on
-`Action.implement`.
+A plain handler, no builder, is [quickstart/src/greeting/handlers.ts](../examples/quickstart/src/greeting/handlers.ts). The builder's rules, once per layer graph, a scope per call, passing the builder to `implement` itself, calling through `Action.client` and never the function you passed, are on `Action.implement`.
 
-- **One implementation may hold public and protected actions**, and actions only some
-  surfaces serve: group by domain.
-- **Leave a handler's `Effect.fn` unnamed** unless you need handler-only timing. The span named
-  after the action covers authorization, the handler and call cleanup, carrying `action.name`
-  and `action.read_only` on it and its logs. Credential verification and input decoding run
-  before it, so a request they reject has no action span; response encoding runs after it, so
-  it can fail after a successful one.
+- **One implementation may hold public and protected actions**, and actions only some surfaces serve: group by domain.
+- **Leave a handler's `Effect.fn` unnamed** unless you need handler-only timing. The span named after the action covers authorization, the handler and call cleanup, carrying `action.name` and `action.read_only` on it and its logs. Credential verification and input decoding run before it, so a request they reject has no action span; response encoding runs after it, so it can fail after a successful one.
 
 ## Authorize calls
 
-An implementation holding a protected action states `{ authorize }`: a function of the called
-action that succeeds, or fails with a refusal; no surface has a policy of its own. An
-implementation of public actions alone takes none
-([notes-service/src/status/handlers.ts](../examples/notes-service/src/status/handlers.ts)).
+An implementation holding a protected action states `{ authorize }`: a function of the called action that succeeds, or fails with a refusal; no surface has a policy of its own. An implementation of public actions alone takes none ([notes-service/src/status/handlers.ts](../examples/notes-service/src/status/handlers.ts)).
 
 ```ts example=notes-service/src/identity/authorize.ts
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
 import { CurrentUser, scopes } from "./Identity.js";
 
 // The one rule, read from each contract: a read needs the read scope, anything else the write
@@ -147,73 +114,40 @@ export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
   const user = yield* CurrentUser;
 
   if (!user.scopes.includes(scope)) {
-    return yield* new Action.Forbidden({ message: `Requires ${scope}.`, scopes: [scope] });
+    return yield* new Action.Forbidden({
+      message: `Requires ${scope}.`,
+      scopes: [scope],
+    });
   }
 });
 ```
 
-Actions under another rule go in another `Action.implement` with its own `authorize`, or
-`Action.allowAll`, not a branch on `action.name`. What a `Forbidden` with and without `scopes`
-answers on each surface is on `Forbidden`.
-Reading a store once, by an `authorize` that is an Effect returning the function, is
-[assistant/src/identity/authorize.ts](../examples/assistant/src/identity/authorize.ts); that
-rule, and that a limit is the handler's, are on `Action.implement`.
-
-- **A caller the authorizer would refuse can still receive an `InvalidInput` describing the
-  input's schema**, since input is decoded before the authorizer runs. To refuse or limit before
-  decoding, use the layer's `middleware`
-  ([ActionHttp.md](ActionHttp.md#split-a-binding-across-layers-and-add-middleware),
-  [ActionRpc.md](ActionRpc.md#serve-the-rpcs)).
-- **A limiter is a service the builder yields, apart from the store**
-  ([kitchen-sink/src/issues/write-limit.ts](../examples/kitchen-sink/src/issues/write-limit.ts),
-  [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts)): state kept in a builder
-  lasts only within one layer graph.
-- **A check on one record belongs in the handler's data access**
-  ([notes-service/src/notes/store.ts](../examples/notes-service/src/notes/store.ts)). So does a
-  rule across callers, such as uniqueness.
+Actions under another rule go in another `Action.implement` with its own `authorize`, or `Action.allowAll`, not a branch on `action.name`. What a `Forbidden` with and without `scopes` answers on each surface is on `Forbidden`. Reading a store once, by an `authorize` that is an Effect returning the function, is [assistant/src/identity/authorize.ts](../examples/assistant/src/identity/authorize.ts); that rule, and that a limit is the handler's, are on `Action.implement`.
+
+- **A caller the authorizer would refuse can still receive an `InvalidInput` describing the input's schema**, since input is decoded before the authorizer runs. To refuse or limit before decoding, use the layer's `middleware` ([ActionHttp.md](ActionHttp.md#split-a-binding-across-layers-and-add-middleware), [ActionRpc.md](ActionRpc.md#serve-the-rpcs)).
+- **A limiter is a service the builder yields, apart from the store** ([kitchen-sink/src/issues/write-limit.ts](../examples/kitchen-sink/src/issues/write-limit.ts), [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts)): state kept in a builder lasts only within one layer graph.
+- **A check on one record belongs in the handler's data access** ([notes-service/src/notes/store.ts](../examples/notes-service/src/notes/store.ts)). So does a rule across callers, such as uniqueness.
 
 ## Fail with declared and built-in errors
 
-A handler fails with the errors its action lists in `error`, and with the three built-in
-errors, `InvalidInput`, `Unauthenticated` and `Forbidden`. What a refusal answers on each
-surface is on `Action.Unauthenticated` and `Action.Forbidden`; what a declared error and bad
-input answer, on each surface's `layer`, `layerHttp`, `runStdio`, `make` or `command`; when to
-fail with `InvalidInput` yourself, on that class, as
-[kitchen-sink/src/attachments/handlers.ts](../examples/kitchen-sink/src/attachments/handlers.ts)
-does.
-
-- **Map a client's `HttpClientError` and `SchemaError` to one declared error a caller can act
-  on** ([mcp-tools/src/platform/print-farm.ts](../examples/mcp-tools/src/platform/print-farm.ts)).
-  As defects, a model reads only a generic text.
-- **Internal failures are never sent** over HTTP, MCP and RPC: what reaches the log and the
-  call's `ErrorReporter`s is on `ActionHttp.layer`, `ActionMcp.layerHttp` and `ActionRpc.layer`;
-  a Toolkit and a CLI make a defect the call's.
+A handler fails with the errors its action lists in `error`, and with the three built-in errors, `InvalidInput`, `Unauthenticated` and `Forbidden`. What a refusal answers on each surface is on `Action.Unauthenticated` and `Action.Forbidden`; what a declared error and bad input answer, on each surface's `layer`, `layerHttp`, `runStdio`, `make` or `command`; when to fail with `InvalidInput` yourself, on that class, as [kitchen-sink/src/attachments/handlers.ts](../examples/kitchen-sink/src/attachments/handlers.ts) does.
+
+- **Add the errors a module adds to every action it serves, a proxy's or a store's, to contracts written elsewhere with `Action.withErrors`**, `pipe(action, Action.withErrors([Unavailable]))`, rather than restating each contract. It returns a new contract, which the module then implements and lists; its rules are on `Action.withErrors`.
+- **Map a client's `HttpClientError` and `SchemaError` to one declared error a caller can act on** ([mcp-tools/src/platform/print-farm.ts](../examples/mcp-tools/src/platform/print-farm.ts)). As defects, a model reads only a generic text.
+- **Internal failures are never sent** over HTTP, MCP and RPC: what reaches the log and the call's `ErrorReporter`s is on `ActionHttp.layer`, `ActionMcp.layerHttp` and `ActionRpc.layer`; a Toolkit and a CLI make a defect the call's.
+
+## Answer a retried call once
+
+A write a caller may send again, after a dropped connection or a timeout, names a string field of its input as its `idempotencyKey`. The caller makes the key at random for the call and sends it again on each retry: a repeat with the same input is answered as the first call was, its handler run once, on every surface, since the key travels with the input. An implementation of such an action requires `Action.Idempotency` at startup, where the answers are kept: provide `Action.layerIdempotency` around the surfaces, as `Event.layerMemory` is provided; in a Durable Object, the Cloudflare package's `ActionDurableObject.make` provides it. What is kept, whose a key is, and what a repeat with another input answers, are on the option.
 
 ## Call actions in process
 
-`Action.client(implementations)` gives the methods `ActionHttp.client` gives, for a job, an
-agent or a test, without a transport. It is acquired where builders live:
-[kitchen-sink/src/agent.ts](../examples/kitchen-sink/src/agent.ts) in a scoped program,
-[notes-service/test/notes/in-process.test.ts](../examples/notes-service/test/notes/in-process.test.ts)
-under `it.effect`. The rules are on `Action.client`; testing with it is
-[Testing.md](Testing.md#test-an-implementation-in-process).
+`Action.client(implementations)` gives the methods `ActionHttp.client` gives, for a job, an agent or a test, without a transport. It is acquired where builders live: [kitchen-sink/src/agent.ts](../examples/kitchen-sink/src/agent.ts) in a scoped program, [notes-service/test/notes/in-process.test.ts](../examples/notes-service/test/notes/in-process.test.ts) under `it.effect`. The rules are on `Action.client`; testing with it is [Testing.md](Testing.md#test-an-implementation-in-process).
 
 ## Share one build across servers
 
-Inside one `HttpRouter.serve` or one `Testing.layer`, a builder runs once, however many surfaces
-serve it, a toolkit's `layer` provided to the routes included. Each `HttpRouter.serve` is a layer
-graph of its own, the layers Effect builds together, each once, which shares nothing it builds
-with another graph: a builder's run, a built authorizer, or an in-memory store of yours.
-
-- **With one server, put everything the process runs inside the layer it serves**, a job or an
-  agent beside the routes included; why a job merged beside `HttpRouter.serve` is not enough is
-  on `Action.layer`.
-- **Otherwise, provide `Action.layer(implementations)` and the services they share above the
-  server and its siblings**: a second server, a program beside it, several `Testing.layer`s.
-  [kitchen-sink/src/server.ts](../examples/kitchen-sink/src/server.ts) does it for two ports with
-  the `builders` layer of [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts),
-  and [kitchen-sink/test/routes.test.ts](../examples/kitchen-sink/test/routes.test.ts) with two
-  `Testing.layer`s, asserting one run of a builder both ports serve.
-- **Inside one layer graph, a builder runs with the services of whichever surface builds it
-  first**, and services provided around one surface reach the others: provide startup services
-  once, for every surface. Where two must differ is on `Action.layer`.
+Inside one `HttpRouter.serve` or one `Testing.layer`, a builder runs once, however many surfaces serve it, a toolkit's `layer` provided to the routes included. Each `HttpRouter.serve` is a layer graph of its own, the layers Effect builds together, each once, which shares nothing it builds with another graph: a builder's run, a built authorizer, or an in-memory store of yours.
+
+- **With one server, put everything the process runs inside the layer it serves**, a job or an agent beside the routes included; why a job merged beside `HttpRouter.serve` is not enough is on `Action.layer`.
+- **Otherwise, provide `Action.layer(implementations)` and the services they share above the server and its siblings**: a second server, a program beside it, several `Testing.layer`s. [kitchen-sink/src/server.ts](../examples/kitchen-sink/src/server.ts) does it for two ports with the `builders` layer of [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts), and [kitchen-sink/test/routes.test.ts](../examples/kitchen-sink/test/routes.test.ts) with two `Testing.layer`s, asserting one run of a builder both ports serve.
+- **Inside one layer graph, a builder runs with the services of whichever surface builds it first**, and services provided around one surface reach the others: provide startup services once, for every surface. Where two must differ is on `Action.layer`.

package/docs/ActionCli-failures.md

@@ -1,7 +1,6 @@
 # ActionCli failure modes
 
-What you see when something is wrong, and the fix. Search for a fragment of the message.
-The tasks are in [ActionCli.md](ActionCli.md).
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [ActionCli.md](ActionCli.md).
 
 ## Flags and input
 

package/docs/ActionCli.md

@@ -1,27 +1,24 @@
 # ActionCli
 
-Native Effect CLI commands for actions, with flags derived from each action's input. `make` and
-`command` take implementations and run the handler in the command's own process, behind the same
-`authorize`: for a local tool, or an operator console that has the services itself. `remote` and
-`remoteCommand` take an HTTP binding and call a server, running nothing locally: for users of a
-service you already serve. `make` and `remote` derive one command per action; which actions a
-surface serves is on `Action.make`.
+Native Effect CLI commands for actions, with flags derived from each action's input. `make` and `command` take implementations and run the handler in the command's own process, behind the same `authorize`: for a local tool, or an operator console that has the services itself. `remote` and `remoteCommand` take an HTTP binding and call a server, running nothing locally: for users of a service you already serve. `make` and `remote` derive one command per action; which actions a surface serves is on `Action.make`.
 
 A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [ActionCli-failures.md](ActionCli-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.
 
 ## Run actions as local commands
 
-Pass implementations to `make`; the host provides the services and the caller on the command,
-and runs it with Effect's own `Command.run`:
+Pass implementations to `make`; the host provides the services and the caller on the command, and runs it with Effect's own `Command.run`:
 
 ```ts example=assistant/src/cli.ts
 import { userInfo } from "node:os";
+
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import { Effect, Layer } from "effect";
 import { Command } from "effect/cli";
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+
 import { commands } from "./commands.js";
-import { CurrentCaller, type Operator } from "./identity/Identity.js";
+import { CurrentCaller } from "./identity/Identity.js";
+import type { Operator } from "./identity/Identity.js";
 import { Permissions } from "./identity/permissions.js";
 import { tasksFile } from "./platform/tasks-file.js";
 
@@ -33,7 +30,7 @@ const operator: Operator = { kind: "operator", id: userInfo().username };
 
 const assistant = commands.pipe(
   Command.provide(Layer.mergeAll(tasksFile, Permissions.layerMemory)),
-  Command.provideSync(CurrentCaller, operator),
+  Command.provideSync(CurrentCaller, operator)
 );
 
 // A command's defect, such as a tasks file that does not decode, `runMain` reports on stdout.
@@ -42,81 +39,90 @@ const assistant = commands.pipe(
 Command.run(assistant, { version: "1.0.0" }).pipe(
   Effect.provide(NodeServices.layer),
   ActionCli.logToStderr,
-  NodeRuntime.runMain,
+  NodeRuntime.runMain()
 );
 ```
 
-The aggregate is [assistant/src/commands.ts](../examples/assistant/src/commands.ts), and
-[kitchen-sink/src/ops.ts](../examples/kitchen-sink/src/ops.ts) an operator console. For one
-action, or a tree of your own under native `Command.withSubcommands`, use
-`command(implementations, action, options?)`. Where services go, what each run builds and what a
-command prints on which stream are on `ActionCli.command`; what `runMain` reports, a command's
-defect included, on `ActionCli.logToStderr`; matching a failure after `Command.run`, on
-`ActionCli.UserError`.
+The aggregate is [assistant/src/commands.ts](../examples/assistant/src/commands.ts), and [kitchen-sink/src/ops.ts](../examples/kitchen-sink/src/ops.ts) an operator console. For one action, or a tree of your own under native `Command.withSubcommands`, use `command(implementations, action, options?)`. Where services go, what each run builds and what a command prints on which stream are on `ActionCli.command`; what `runMain` reports, a command's defect included, on `ActionCli.logToStderr`; matching a failure after `Command.run`, on `ActionCli.UserError`.
 
-- **Test commands without a process** with `Command.runWith`, `TestConsole` and
-  `Stdio.layerTest`: [assistant/test/commands.test.ts](../examples/assistant/test/commands.test.ts).
+- **Test commands without a process** with `Command.runWith`, `TestConsole` and `Stdio.layerTest`: [assistant/test/commands.test.ts](../examples/assistant/test/commands.test.ts).
 
 ## Call a server from commands
 
-Pass the HTTP binding to `remote`. The program imports the binding alone, never a handler. The
-connection is the `client` option, an `ActionHttp.client`
-([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)), its rules on `ActionCli.Calling`'s `client`,
-shared by `remote` and `remoteCommand`:
-[notes-service/src/commands.ts](../examples/notes-service/src/commands.ts) requires a token,
-mapping its absence to an error that says what to do, and
-[kitchen-sink/src/cli.ts](../examples/kitchen-sink/src/cli.ts) adds a tenant header, reads an
-optional token for a public command. The host provides
-`HttpClient` (`NodeHttpClient.layerUndici`) in
-[notes-service/src/cli.ts](../examples/notes-service/src/cli.ts).
-
-- **Split one binding into groups of commands**, one `remote` per group with its own `actions`;
-  what each group's `client` needs is on `ActionCli.Calling`'s `client`.
-- **Test a remote command the same way** as a local one, with `Testing.layer(routes)` provided
-  as its `HttpClient` ([Testing.md](Testing.md#test-routes-in-memory)). Export the command from
-  a module apart from the entrypoint that runs it
-  ([notes-service/test/commands.test.ts](../examples/notes-service/test/commands.test.ts)).
+Pass the HTTP binding to `remote`. The program imports the binding alone, never a handler. The connection is the `client` option, an `ActionHttp.client` ([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)), its rules on `ActionCli.Calling`'s `client`, shared by `remote` and `remoteCommand`: [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts) requires a token, mapping its absence to an error that says what to do, and [kitchen-sink/src/cli.ts](../examples/kitchen-sink/src/cli.ts) adds a tenant header, reads an optional token for a public command. The host provides `HttpClient` (`NodeHttpClient.layerUndici`) in [notes-service/src/cli.ts](../examples/notes-service/src/cli.ts).
+
+- **Split one binding into groups of commands**, one `remote` per group with its own `actions`; what each group's `client` needs is on `ActionCli.Calling`'s `client`.
+- **Test a remote command the same way** as a local one, with `Testing.layer(routes)` provided as its `HttpClient` ([Testing.md](Testing.md#test-routes-in-memory)). Export the command from a module apart from the entrypoint that runs it ([notes-service/test/commands.test.ts](../examples/notes-service/test/commands.test.ts)).
+
+## Watch events
+
+`make` and `remote` add `watch <event>` for each [event type](Event.md) among the implementations or in the binding, or each one `actions` lists where it is given. Experimental, as [events](Event.md) are.
+
+```ts example=build-events/src/commands.ts
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Config, Effect } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+
+import { Http } from "./Api.js";
+
+// The binding's client, connected to where the server is and as which member, both read from
+// config when a command runs.
+const api = Effect.gen(function* () {
+  const baseUrl = yield* Config.String("BUILDS_URL").pipe(
+    Config.withDefault("http://127.0.0.1:3000")
+  );
+
+  const token = yield* Config.Redacted("BUILDS_TOKEN");
+
+  return yield* ActionHttp.client(Http, {
+    baseUrl,
+    transformClient: HttpClient.mapRequest(
+      HttpClientRequest.bearerToken(token)
+    ),
+  });
+});
+
+// A command per action, and `watch <event>` per event type: `builds watch build.finished
+// --pipeline api` holds the event's stream open and prints each occurrence as a line of JSON,
+// its `cursor` included, until it is stopped. `--cursor <cursor>` resumes after that line;
+// omitted, the watch starts from now. The lines pipe into `jq` or a script as they come.
+// `builds start-build --pipeline api` prints each step as a line of JSON on stderr as it
+// starts, and the build on stdout, which a pipe reads alone. `builds tail-log --build-id
+// build-1` prints each line of its log as a line of JSON as it arrives.
+export const commands = ActionCli.remote(Http, { name: "builds", client: api });
+```
+
+[build-events/test/commands.test.ts](../examples/build-events/test/commands.test.ts) runs a watch and stops it. What a watch prints and fails with is on `make` and `remote`.
 
 ## Shape flags, input and output
 
 ### Flags from the input
 
-A struct or class input gets one flag per top-level field, named after the field in kebab case,
-with the field's description as its help, annotated before or after its checks. The field's
-encoded JSON value decides the kind of flag:
+A struct or class input gets one flag per top-level field, named after the field in kebab case, with the field's description as its help, annotated before or after its checks. The field's encoded JSON value decides the kind of flag:
 
-| Encoded field                            | Flag, for a field `tags`, `read`, …                             |
-| ---------------------------------------- | --------------------------------------------------------------- |
-| string or template literal               | `--name <string>`                                               |
-| boolean                                  | `--read`, a switch: `--no-read` or `--read=false` sends `false` |
-| union of string literals, or string enum | `--kind <choice>`, one of the values                            |
-| array of strings, numbers or choices     | `--tags <value>`, repeated: one element per occurrence          |
-| anything else, numbers included          | `--owner <value>`: JSON the field accepts, or else the text     |
+| Encoded field | Flag, for a field `tags`, `read`, … |
+| --- | --- |
+| string or template literal | `--name <string>` |
+| boolean | `--read`, a switch: `--no-read` or `--read=false` sends `false` |
+| union of string literals, or string enum | `--kind <choice>`, one of the values |
+| array of strings, numbers or choices | `--tags <value>`, repeated: one element per occurrence |
+| anything else, numbers included | `--owner <value>`: JSON the field accepts, or else the text |
 
 - A switch left out is `false` for a required field, and leaves an optional one out.
-- `--help` adds, after the field's description, `Repeat for each value.` on a repeated flag,
-  `--no-read sends false.` on an optional switch, `Left out, it sends false.` on a required
-  one, and `A JSON array.` or `A JSON object.` on a
-  value that is one, an array of objects with its fields: `A JSON array of {id, approved?}.`
-- A flag takes the encoded value, which the action's schema then decodes: `"21"` for
-  `Schema.FiniteFromString`.
-- A value flag reads its text as JSON when the field accepts that kind of JSON value
-  (`--count 2`, `--owner '{"id":"x"}'`, `--points '[{"x":1}]'`), and keeps it as text otherwise
-  (`--limit auto`): quote a string that would read as JSON, `--id '"123"'` for a
-  `String | Number` field.
-- A repeated flag given no occurrence sends `[]` for a required `Schema.Array` field, and leaves
-  an optional field out, where `--tags '[]'` alone sends an empty list.
-- An input that is not a struct of named fields (a union, a record, a scalar) gets one
-  `--input <value>` flag carrying the whole encoded input. Left off, the input is `{}`.
+- `--help` adds, after the field's description, `Repeat for each value.` on a repeated flag, `--no-read sends false.` on an optional switch, `Left out, it sends false.` on a required one, and `A JSON array.` or `A JSON object.` on a value that is one, an array of objects with its fields: `A JSON array of {id, approved?}.`
+- A flag takes the encoded value, which the action's schema then decodes: `"21"` for `Schema.FiniteFromString`.
+- A value flag reads its text as JSON when the field accepts that kind of JSON value (`--count 2`, `--owner '{"id":"x"}'`, `--points '[{"x":1}]'`), and keeps it as text otherwise (`--limit auto`): quote a string that would read as JSON, `--id '"123"'` for a `String | Number` field.
+- A repeated flag given no occurrence sends `[]` for a required `Schema.Array` field, and leaves an optional field out, where `--tags '[]'` alone sends an empty list.
+- An input that is not a struct of named fields (a union, a record, a scalar) gets one `--input <value>` flag carrying the whole encoded input. Left off, the input is `{}`.
 
 ### Arguments, short flags and stdin
 
-`description`, `render`, `positional`, `aliases` and `stdin` shape one command; in an aggregate
-they go under `commands`, keyed by the action's name. Each one's rules are on its own
-declaration:
+`description`, `render`, `positional`, `aliases` and `stdin` shape one command; in an aggregate they go under `commands`, keyed by the action's name. Each one's rules are on its own declaration:
 
 ```ts example=assistant/src/commands.ts
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+
 import { identity } from "./identity/handlers.js";
 import { tasks } from "./tasks/handlers.js";
 
@@ -130,11 +136,15 @@ export const commands = ActionCli.make([tasks, identity], {
     // per task for a person, and adds `--json` for the JSON a script reads. `description` is the
     // command's help, saying what a line holds; the action's stays what a model reads.
     listTasks: {
-      description: "Print one line per task: [x] when done, then its id, title and assignee.",
+      description:
+        "Print one line per task: [x] when done, then its id, title and assignee.",
       aliases: { assignee: "a" },
-      render: ({ tasks }) =>
-        tasks
-          .map((task) => `${task.done ? "[x]" : "[ ]"} ${task.id} ${task.title} (${task.assignee})`)
+      render: ({ tasks: listed }) =>
+        listed
+          .map(
+            (task) =>
+              `${task.done ? "[x]" : "[ ]"} ${task.id} ${task.title} (${task.assignee})`
+          )
           .join("\n"),
     },
     // `assistant complete-task 2`: an argument instead of `--id 2`.
@@ -147,25 +157,10 @@ export const commands = ActionCli.make([tasks, identity], {
 
 ### Add a command of your own
 
-Work every surface should offer, a bulk import for one, is an action first: a command of your
-own then only reads the file and calls it. For a syntax the options cannot express, such as a
-flag named apart from its field, build the command with native `Command.make`, `Flag` and
-`Argument`, and pass it in `subcommands`, whose rules are on `ActionCli.Options`; pipe its
-Effect through `toUserError` to fail as a derived command does.
-In [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts),
-`notes import <file>` reads `Argument.FileText` and calls `importNotes`, and
-`notes export <file>` takes `Argument.String("file")` and calls two actions.
+Work every surface should offer, a bulk import for one, is an action first: a command of your own then only reads the file and calls it. For a syntax the options cannot express, such as a flag named apart from its field, build the command with native `Command.make`, `Flag` and `Argument`, and pass it in `subcommands`, whose rules are on `ActionCli.Options`; pipe its Effect through `toUserError` to fail as a derived command does. In [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts), `notes import <file>` reads `Argument.FileText` and calls `importNotes`, and `notes export <file>` takes `Argument.String("file")` and calls two actions.
 
 ## Name the caller
 
-`Command.provideSync(CurrentCaller, operator)` names the caller on the command in
-[assistant/src/cli.ts](../examples/assistant/src/cli.ts), or
-`Command.provideEffect(CurrentCaller, load)` reads it when an action runs
-([Action.md](Action.md#say-who-may-call-an-action)).
-
-- **A trusted operator is a type, not a flag.** Give the identity a variant only a host builds,
-  kept out of every verifier's return type, and admit it in the shared `authorize`:
-  [assistant/src/identity/Identity.ts](../examples/assistant/src/identity/Identity.ts) with
-  [assistant/src/identity/authorize.ts](../examples/assistant/src/identity/authorize.ts), or
-  [kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts) with
-  [kitchen-sink/src/ops.ts](../examples/kitchen-sink/src/ops.ts).
+`Command.provideSync(CurrentCaller, operator)` names the caller on the command in [assistant/src/cli.ts](../examples/assistant/src/cli.ts), or `Command.provideEffect(CurrentCaller, load)` reads it when an action runs ([Action.md](Action.md#say-who-may-call-an-action)).
+
+- **A trusted operator is a type, not a flag.** Give the identity a variant only a host builds, kept out of every verifier's return type, and admit it in the shared `authorize`: [assistant/src/identity/Identity.ts](../examples/assistant/src/identity/Identity.ts) with [assistant/src/identity/authorize.ts](../examples/assistant/src/identity/authorize.ts), or [kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts) with [kitchen-sink/src/ops.ts](../examples/kitchen-sink/src/ops.ts).

package/docs/ActionHttp-failures.md

@@ -1,14 +1,14 @@
 # ActionHttp failure modes
 
-What you see when something is wrong, and the fix. Search for a fragment of the message.
-The tasks are in [ActionHttp.md](ActionHttp.md).
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [ActionHttp.md](ActionHttp.md).
 
 ## Binding and serving
 
 - A route returns 404, which a client method reports as an `HttpClientError` with `DecodeError` or `StatusCodeError`: the path lacks the prefix, no `ActionHttp.layer` call serves the action, or the binding does not hold that very action value, as when a test declares the contract again.
-- `Method 'POST' already declared for route '<prefix>/<action>'` when the host builds: two `ActionHttp.layer` calls serve one action; give each layer its own `actions`.
+- `Method 'POST' already declared for route '<prefix>/<action>'`, or `'<prefix>/events/<event>'`, when the host builds: two `ActionHttp.layer` calls serve one action or event type; give each layer its own `actions`.
 - `Duplicate OpenAPI operationId: <name>` from `OpenApi.fromApi`: two bindings combined into one `HttpApi` share an action name; rename one, or document each binding alone.
 - `Type 'Handlers<…>' is not assignable to type '`Endpoint not handled: ${string}`'` at `HttpApiBuilder.group(binding.api, …)`, or `Service not found: effect-actions/Authentication/Security/…` when the host builds: a binding is served with the native `HttpApiBuilder`; serve it with `ActionHttp.layer`.
+- `event: effect/http-api/stream/failure` ends an SSE stream: Effect's failure event, an event's source refusing the subscriber after the stream started, or an action answering progress or a stream failing after its first event; its `data` is the failure as an encoded `Cause`, which `ActionHttp.client`'s `watch` or method fails with as declared.
 - `Unsupported content-type: <type>` as a 415 body: Effect refuses a `Content-Type` other than `application/json`, after authentication and before the handler; send `application/json`.
 
 ## Types