@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

package/docs/Action.md

@@ -1,231 +1,173 @@
 # Action
 
-`Action.make` defines an action, and `Action.implement` binds handlers and an authorizer to
-contracts: every surface takes the implementation it returns, or a list of them.
-
-Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
-When something fails, search [Action-failures.md](Action-failures.md). Reading order:
-[README.md](README.md).
-
-## API
-
-Import `@gjermundgaraba/effect-actions/Action`.
-
-| Export                                         | Purpose                                                      |
-| ---------------------------------------------- | ------------------------------------------------------------ |
-| `make(name, options)`                          | Define a contract.                                           |
-| `byName(actions)`                              | A list of actions keyed by name, each its exact contract.    |
-| `implement(actions, handlers, { authorize })`  | Bind a handler, a record of them, or a builder of either.    |
-| `allowAll`                                     | The authorizer without a rule: any authenticated caller.     |
-| `Anyone`                                       | The `caller` of a public action: anyone, signed in or not.   |
-| `client`, `layer`, `Client`, `ClientOptions`   | In [Action-in-process.md](Action-in-process.md#api).         |
-| `Image`                                        | A media field's schema: `data` bytes and a `mimeType`.       |
-| `InvalidInput`, `Unauthenticated`, `Forbidden` | Built-in errors: 400 with `issues`, 401, 403 with `scopes`.  |
-| `InvalidInput.fromSchemaError(error)`          | What every surface answers a `Schema.SchemaError` with.      |
-| `Issue`                                        | One of `InvalidInput`'s `issues`: a `path` and a `message`.  |
-| `Refusal`                                      | `Unauthenticated \| Forbidden`: an authorizer's failures.    |
-| `BuiltIn`                                      | `InvalidInput \| Refusal`: what any handler may fail with.   |
-| `Errors`                                       | A list of error schemas, as `error` holds it.                |
-| `Action`, `Any`, `Implementation`              | Concrete and erased contracts, and bound implementations.    |
-| `AnyImplementation`, `AnyImplementation<A>`    | Any implementation, or any of actions `A`, erased.           |
-| `BuildServices`, `BuildError`                  | What builders read and fail with at startup.                 |
-| `implementation.actions`                       | Its exact contracts, as `ActionMcp.client` takes them.       |
-| `Handler`, `Handlers`, `Authorize`             | A typed handler, a list's record of them, and an authorizer. |
-| `Options`, `Mcp`                               | What `make` takes, and its `mcp` options.                    |
-
-| Option        | Meaning                                                        |
-| ------------- | -------------------------------------------------------------- |
-| `description` | Required. A model reads it beside the tool; a CLI prints it.   |
-| `readOnly`    | Required: whether the action leaves its resource unchanged.    |
-| `caller`      | Required: `Action.Anyone`, or the caller's identity service.   |
-| `input`       | A schema or struct fields; omitted, no arguments.              |
-| `success`     | A schema or struct fields; omitted, nothing is returned.       |
-| `error`       | The declared errors: one schema or a list; defaults to none.   |
-| `mcp`         | The tool's MCP hints, in MCP's names, its `title` and `_meta`. |
+`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.
 
 ## Define a contract
 
-Write one `Action.make` per action in the domain's contract file, and export the domain's
-actions as one `as const` list: `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";
 
-```ts
-export const GetNote = Action.make("getNote", {
-  description: "Read one of your notes.",
-  input: { id: Schema.String },
-  success: Note,
-  error: NoteNotFound,
+// 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.
+export const Greet = Action.make("greet", {
+  description: "Greet someone by name.",
+  input: { name: Schema.String },
+  success: Schema.String,
   readOnly: true,
-  caller: CurrentUser,
+  caller: Action.Anyone,
 });
 ```
 
-Start from [quickstart/src/greeting/Greeting.ts](../examples/quickstart/src/greeting/Greeting.ts).
 [notes-service/src/notes/Notes.ts](../examples/notes-service/src/notes/Notes.ts) adds declared
-errors and the list, and [kitchen-sink/src/issues/Issues.ts](../examples/kitchen-sink/src/issues/Issues.ts)
-uses every option, sharing some by spreading a constant (`IssueWriteErrors`, `change`).
-
-- **The contract file imports no server code and no transport**, so a browser or a CLI can
-  import it ([setup.md](setup.md#bundle-for-a-browser)).
-- **The name** matches `[A-Za-z0-9_-]{1,128}`, is not `then`, and is unique within each binding,
-  MCP endpoint, Toolkit, CLI and client holding it.
-- **For no arguments, omit `input`.** A `Schema.Struct({})` accepts any value but `null` and `undefined`, and MCP
-  refuses it as a tool's input ([ActionMcp.md](ActionMcp.md#describe-tools-to-a-model)).
-- **A field callers may omit is `Schema.optional`.** On the wire it also takes `null`, read as
-  left out, as a tool's schema lists; a typed client refuses `null`. `Schema.optionalKey` takes
-  omission alone, and `Schema.NullOr` keeps `null` as a value. One with a decoding default (`limit` in
-  `Issues.ts`) is still stated by a typed client given an argument
-  ([ActionHttp.md](ActionHttp.md#call-the-api-from-effect)).
-- **An action's `name`, `input`, `success`, `error` and `readOnly` are public**: reuse them, as
-  in `Schema.Array(SaveLink.input)`.
-- **Annotate each declared error with `httpApiStatus`**, or HTTP answers it as a 422.
-- **Give each declared error its own `_tag`**: a client tells errors sharing one, or having
-  none, apart by their other fields alone, the first that decodes winning.
-- **A contract does not say where it is served**: each surface takes a list of actions. Keep
-  those lists in one file beside the contracts
-  ([kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts)): an action added
-  later is no tool until listed there.
+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.
-- **Surfaces match an implementation to a contract by object identity, never by name**:
-  implement, bind and list the one exported value. A list narrowed at run time, by a filter or a
-  conditional element, is still typed as holding every member.
 
 ## Say who may call an action
 
-`caller: Action.Anyone` makes a public action. An identity service, `caller: CurrentUser`, makes
-a protected one: every surface requires that identity, whether or not the handler reads it. A
-remote surface gets it by authenticating the request
-([Authentication.md](Authentication.md#declare-how-callers-sign-in)); on a local surface the
-host provides it ([ActionToolkit.md](ActionToolkit.md#name-the-caller),
+`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 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).
-
-- **Declare the identity as a `Context.Service`**, in a contract file, apart from its verifier.
-- **Never provide an identity, or a tenant, at startup**: not to a server's layer or root
-  context, not to `Action.layer`, not around the acquisition of a client. A public handler or a
-  route of your own reading the tag would serve every caller as that identity, and the types do
-  not stop it. A test sends each caller's credential instead
-  ([Testing.md](Testing.md#test-as-a-signed-in-caller)).
-- **One identity per action**, and every protected action one remote surface serves declares
-  the same one. A tenant is a request-time requirement of the handler, not a second identity.
-  A second audience takes its own identity, descriptor and binding (`Operator` in
-  [kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts)).
-- **No surface provides a public action an identity.** An action whose answer depends on the
-  caller is protected.
+`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)).
+  ([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, run once at startup, that returns the handler
-or the record. It is how a handler gets a startup service; what differs per call, the caller
-first, the handler reads itself.
-
-```ts
+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 { authorize } from "../identity/authorize.js";
+import { CurrentUser } from "../identity/Identity.js";
+import { Notes } from "./Notes.js";
+import { NoteStore } from "./store.js";
+
+// The builder runs once, at startup, however many surfaces serve these actions: it is where a
+// handler gets the services that last the process, never the caller. `CurrentUser` is read per
+// call, inside each handler. Each handler is a thin step from the contract to the store, and
+// none checks a scope: `authorize` has run before it.
 export const notes = Action.implement(
   Notes,
   Effect.gen(function* () {
-    const store = yield* NoteStore; // a startup service: yielded once
+    const store = yield* NoteStore;
 
     return {
-      // CurrentUser is a request-time requirement: yielded per call
+      listNotes: () =>
+        Effect.gen(function* () {
+          const user = yield* CurrentUser;
+          const owned = yield* store.list(user.id);
+
+          return { notes: owned.map(({ id, title }) => ({ id, title })) };
+        }),
       getNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.get(user.id, id)),
-      // ...one handler per action of the list
+      createNote: ({ requestId, title, body }) =>
+        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.map(
+          Effect.flatMap(CurrentUser, (user) => store.createAll(user.id, notes)),
+          (created) => ({ notes: created }),
+        ),
     };
   }),
   { authorize },
 );
 ```
 
-A plain handler is [quickstart/src/greeting/handlers.ts](../examples/quickstart/src/greeting/handlers.ts),
-and the whole builder above [notes-service/src/notes/handlers.ts](../examples/notes-service/src/notes/handlers.ts).
+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.
-- **What the builder yields is shared by every call; what a handler yields is resolved per
-  call**, as the caller must be.
-- **A builder runs once per layer graph**, however many surfaces serve its implementation. Two
-  servers are two graphs
-  ([Share one build across servers](Action-in-process.md#share-one-build-across-servers)), and
-  two `implement` calls are two builders, even of one builder Effect.
-- **Each call has a scope of its own**, so a resource that must outlive a call is the
-  builder's.
-- **Pass the builder to `implement` itself.** Through `.pipe(...)` or a wrapper such as
-  `Effect.withSpan(builder, name)`, an `Effect.fn` handler it returns takes an `any` input. A
-  builder written apart returns its record `satisfies Action.Handlers<typeof actions>`.
-- **Leave a handler's `Effect.fn` unnamed** unless you need handler-only timing: each action
-  already has a span ([Observe calls](#observe-calls)).
-- **Calling the function you passed to `implement` skips authorization.** Call the
-  implementation through [`Action.client`](Action-in-process.md#call-actions-in-process).
-
-## Observe calls
-
-The span named after an action includes authorization, handler execution and call cleanup.
-Its exit reflects the final dispatch outcome; the span and its logs carry `action.name` and
-`action.read_only`.
-
-Transport credential verification, input decoding and response encoding run outside this span.
-A request rejected by verification or decoding has no action span; response encoding can fail
-after the action span succeeds.
-
-Add a named handler span to measure handler time alone. The named authorizer in
-[notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts)
-similarly measures authorization as a child of the action span.
+- **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. Every surface runs it before the handler, and
-none 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)), and
-the authorizer never runs for a public action.
-
-```ts
+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 { CurrentUser, scopes } from "./Identity.js";
+
+// The one rule, read from each contract: a read needs the read scope, anything else the write
+// scope. Naming the missing scope lets an OAuth client ask for it and retry (`Forbidden`):
+// `scopes` below goes with `protectedResource` in verifier.ts, copy both or neither.
+// This named span measures authorization within the action's span, including a refusal.
 export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
   const scope = action.readOnly ? scopes.read : scopes.write;
   const user = yield* CurrentUser;
 
   if (!user.scopes.includes(scope)) {
-    return yield* new Action.Forbidden({ message: `Requires ${scope}.` });
+    return yield* new Action.Forbidden({ message: `Requires ${scope}.`, scopes: [scope] });
   }
 });
 ```
 
-[notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts)
-is that rule with `scopes: [scope]` added, the OAuth variant: it publishes discovery.
-Derive the rule from `action.readOnly`, never from an `mcp` hint: changing an action's
-`readOnly` then changes who may call it. Actions under another rule go in another
-`Action.implement` with its own `authorize`, or `Action.allowAll`, not a branch on
-`action.name`.
-
-- **A call runs authentication, then over HTTP and RPC the layer's `middleware`, input
-  decoding, the authorizer, then the handler**, each refusing before the next. So a caller the
-  authorizer would refuse can still receive an `InvalidInput` describing the input's schema. To
-  refuse or limit before decoding, use that `middleware`
-  ([ActionHttp.md](ActionHttp.md#serve-the-routes), [ActionRpc.md](ActionRpc.md#serve-the-rpcs)).
-- **Name `scopes` in a `Forbidden` only where re-authorizing can grant them.** An OAuth
-  challenge answers them, which a client follows only where the server publishes discovery
-  ([Authentication.md](Authentication.md#publish-oauth-discovery)); with fixed tokens, such as
-  API keys, leave `scopes` out (it holds at least one: `scopes: []` is a type error). What a
-  refusal answers on each surface is in [guarantees.md](guarantees.md#wire-behavior).
-- **What a plain authorizer yields is a request-time requirement of every surface.** To read a
-  store, make `authorize` an Effect that yields the store once and returns the function, as a
-  builder does
-  ([assistant/src/identity/authorize.ts](../examples/assistant/src/identity/authorize.ts)). It
-  is built once for each implementation stating it: keep state they share in a service it
-  yields.
-- **A limit, such as a rate limit, is the handler's, not the authorizer's.** It fails with an
-  error the action declares, and its 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)):
-  a service is shared wherever it is provided
-  ([kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts)), state kept in a
-  builder only within one layer graph.
+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.
@@ -233,19 +175,45 @@ Derive the rule from `action.readOnly`, never from an `mcp` hint: changing an ac
 ## 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, which every surface declares and every client decodes: never list those. No other
-failure compiles. What each surface answers is in [guarantees.md](guarantees.md#wire-behavior).
-
-- **Fail with `Action.InvalidInput` for input that decodes but cannot be served**, naming
-  `issues` of your own, instead of declaring a second error for bad input
-  ([kitchen-sink/src/attachments/handlers.ts](../examples/kitchen-sink/src/attachments/handlers.ts)).
-- **For input you decode yourself** on the server, such as a header or a route parameter,
-  answer as the surfaces do, with every issue:
-  `Schema.decodeUnknownEffect(schema)(value, { errors: "all" }).pipe(Effect.mapError(Action.InvalidInput.fromSchemaError))`.
-- **Map another service's refusals before failing with them.** A client that decodes the
-  built-in errors, such as `ActionHttp.client`, hands a handler that service's `Unauthenticated`
-  or `Forbidden`. Passed on, it is this server's own refusal: a caller whose token is valid is
-  told to sign in again. Map it to an error the action declares, or to a defect.
-- **Map that 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.
+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.
+
+## 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).
+
+## 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`.

package/docs/ActionCli-failures.md

@@ -5,101 +5,21 @@ The tasks are in [ActionCli.md](ActionCli.md).
 
 ## Flags and input
 
-- `Unrecognized flag: --<field> in command …` for an input field: a field listed in `positional`
-  has no flag. Pass its value as an argument.
-- `Missing value for flag --<flag>`, or `Unrecognized flag: -x`, for a value starting with `-`:
-  Effect's parser reads a value written apart from its flag as a flag itself when it starts with
-  `-`, `-` alone and a number such as `-5` excepted: `--note -x` is a missing value, and
-  `--note --help` prints help. Write `--<flag>=<value>`; `--` does not help, since what follows
-  it is positional.
-- `InvalidInput` naming an unexpected key: `--input` or a flag's JSON holds a field the schema
-  does not declare, such as a misspelling.
-- `InvalidInput` from a command whose input is not a struct, run without `--input`: the schema
-  rejects the default `{}`. Pass `--input`.
-- `InvalidInput` for a flag's value that looks right: a flag takes the encoded value, and reads
-  its text as JSON when the field accepts that kind of JSON value. Quote a string that reads as
-  JSON: `--id '"123"'` for a `String | Number` field. Malformed JSON is taken as text.
-- A command with a `stdin` field waits without output: nothing closes stdin, such as a parent
-  process holding the pipe, or `ssh` run without `-n`. Pipe the value in, or redirect stdin from
-  a file or `/dev/null`.
-
-## Thrown when a command is built
-
-- `Required positional argument after an optional one: <field>`, or
-  `Repeated positional argument before another one: <field>`: `positional` lists every required
-  field before any optional one, and an array field last.
-- `Not an input field: <field>`: `positional` names no field of the input.
-- `Not a flag's input field: <field>`: an `aliases` key names a field that is positional, read
-  from stdin, or no field.
-- `Not a required input field: <field>`: `stdin` names an optional field, or no field.
-- `Positional arguments need named input fields`, `Aliases need named input fields: <fields>`, or
-  `Stdin needs named input fields: <field>`: the action's input is not a struct.
-- `Duplicate flag: --<name>, claimed by ...`: two flags of one command share a name, such as two
-  fields with one kebab-case name (`userId`, `user_id`), a `json` field beside `render`'s
-  `--json`, or an alias another flag's name or alias takes. Rename the field or the alias, or
-  drop `render`. A field named like a global flag (`help`, `version`, `log-level`) is not a
-  clash: its flag shadows the global one on that command.
-- `Duplicate command: <name>, claimed by action ... and action ...`: two actions of an aggregate
-  have the same kebab-case name. Give one a `name` in `commands`, or use separate aggregates.
-- `Duplicate command: <name>, claimed by action ... and subcommands`: a command passed in
-  `subcommands` has a derived command's name. Rename either.
-- `Unknown commands: <keys>`: a `commands` key names no action. Use the action's own name, not
-  its kebab-case command name.
-- `Listed in actions, but no implementation holds it: <names>`, or
-  `but the binding does not hold it`: `actions` lists a contract that the implementations, or the
-  binding, do not hold, by identity. `(another contract)` marks one whose name they hold, as a
-  second copy of the contracts module makes. List the contract they implement or bind.
-- `Action "x" has no implementation here`, or a type error at `command`: no implementation passed
-  has that contract. Pass the implementation, and select with the exact contract value it
-  implements; an equal-looking action does not match.
-- `Action "x" is not in this HTTP binding`, or a type error at `remoteCommand`: the action was not
-  passed to this binding's `ActionHttp.make`. Select with the exact contract value it received.
+- `Unrecognized flag: --<field> in command …` for an input field: a field listed in `positional` has no flag. Pass its value as an argument.
+- `Missing value for flag --<flag>`, or `Unrecognized flag: -x`, for a value starting with `-`: Effect's parser reads a value written apart from its flag as a flag itself when it starts with `-`, `-` alone and a number such as `-5` excepted, so `--note -x` is a missing value and `--note --help` prints help. Write `--<flag>=<value>`; `--` does not help, since what follows it is positional.
 
 ## Types
 
-- An argument of type `Binding<…>` not assignable at `make` or `command`, an implementation not
-  assignable at `remote` or `remoteCommand`, or `client` refused at `make` or `command`: `make`
-  and `command` take implementations; `remote` and `remoteCommand` take a binding, and alone take
-  `client`. To choose by a condition, build a command from each:
-  `remotely ? ActionCli.remote(Http, options) : ActionCli.make(users, options)`.
-- `Type 'HttpClient' is not assignable to type 'never'` in the pipe that runs a remote command:
-  provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`). Another service named there
-  is what its `client` requires: provide it too.
-- An argument of type `Binding<…>` not assignable at `remote` or `remoteCommand`, beside a
-  `client`: the client is another binding's. Make it with `ActionHttp.client` of this one.
-- A local command requires an identity service no handler yields: its action is protected, and
-  requires the identity its contract declares. Provide it on the command
-  ([Name the caller](ActionCli.md#name-the-caller)); do not make the contract public to satisfy
-  the requirement.
-- Type error at `Effect.catchTag("UserNotFound", ...)` after `Command.run`: a command fails with
-  `UserError`. Use `Effect.catchReason("UserError", "UserNotFound", ...)`.
-- Type error at `Effect.catchReason("UserError", "<Tag>", ...)`, its tag typed `never`: a failure
-  of the command has no `_tag`, such as a builder's plain `Error`. Fail with a tagged error, such
-  as a `Schema.TaggedError` or `Data.TaggedError`.
+- An argument of type `Binding<…>` not assignable at `make` or `command`, an implementation not assignable at `remote` or `remoteCommand`, or `client` refused at `make` or `command`: `make` and `command` take implementations, `remote` and `remoteCommand` a binding and alone `client`. To choose by a condition, build a command from each: `remotely ? ActionCli.remote(Http, options) : ActionCli.make(users, options)`.
+- `Type 'HttpClient' is not assignable to type 'never'` in the pipe that runs a remote command: provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`). Another service named there is what its `client` requires: provide it too.
+- An argument of type `Binding<…>` not assignable at `remote` or `remoteCommand`, beside a `client`: the client is another binding's. Make it with `ActionHttp.client` of this one.
+- Type error at `Effect.catchTag("UserNotFound", ...)` after `Command.run`: a command fails with `UserError`. Use `Effect.catchReason("UserError", "UserNotFound", ...)`.
+- Type error at `Effect.catchReason("UserError", "<Tag>", ...)`, its tag typed `never`: a failure of the command has no `_tag`, such as a builder's plain `Error`. Fail with a tagged error, such as a `Schema.TaggedError` or `Data.TaggedError`.
+- `Argument of type 'string | undefined' is not assignable` at a `UserError`'s `userMessage`: it is optional on the type. Read it with `?? ""`, or assert it with `toHaveProperty`.
 
 ## Running
 
-- `--help` or a mistyped flag connects to a database, or fails reading config: services provided
-  around `Command.run` are built before parsing. Provide them on the command,
-  `Command.provide(layer)`.
-- `ConfigError: …` or another error's `Tag: message` on stderr from a remote command, a public
-  one too: its `client` failed, as when a required token is not set. Read an optional one with
-  `Config.option` and add the header only when it is there. Where every command needs it, map
-  the failure to a tagged error whose `message` says what to do:
-  [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts).
-- `HttpClientError` whose `reason._tag` is `InvalidUrlError`, from a remote command: its client
-  has no `baseUrl` and prepends no URL.
-- 401 `Unauthenticated` from a remote command: a remote command adds no headers of its own. Add
-  credentials in its client's `transformClient`.
-- Another command's request goes to the API's URL, or carries its token: an `HttpClient`
-  configured around the whole program rewrites every request the program makes. Configure it in
-  the `client` option.
-- A report with a stack on stdout, `ERROR (#1): ...`, instead of JSON on stderr: a defect, or a
-  failure of a layer the host provides, which `runMain` reports. Fix the defect; apply
-  `ActionCli.logToStderr` to keep such reports off stdout.
-- `ERROR (#n)` with a stack for a declared error, such as `UserNotFound`, from a command built
-  with `Command.make`: a command of your own that calls `Action.client` or `ActionHttp.client`
-  fails with the action's own error. Pipe the command's whole Effect through
-  `ActionCli.toUserError`, given the binding or the actions it calls, or derive the command with `ActionCli.command`.
-- `Argument of type 'string | undefined' is not assignable` at a `UserError`'s `userMessage`: it
-  is optional on the type. Read it with `?? ""`, or assert it with `toHaveProperty`.
+- `ConfigError: …` or another error's `Tag: message` on stderr from a remote command, a public one too: its `client` failed, as when a required token is not set. Read an optional one with `Config.option` and add the header only when it is there; where every command needs it, map the failure to a tagged error whose `message` says what to do ([notes-service/src/commands.ts](../examples/notes-service/src/commands.ts)).
+- `HttpClientError` whose `reason._tag` is `InvalidUrlError`, from a remote command: its client has no `baseUrl` and prepends no URL. Give `ActionHttp.client` a `baseUrl` in the `client` option.
+- A report with a stack on stdout, `ERROR (#1): ...`, instead of JSON on stderr: a defect, or a failure of a layer the host provides, which `runMain` reports. Fix the defect; apply `ActionCli.logToStderr` to keep such reports off stdout.
+- `ERROR (#n)` with a stack for a declared error, such as `UserNotFound`, from a command built with `Command.make`: a command of your own that calls `Action.client` or `ActionHttp.client` fails with the action's own error. Pipe its whole Effect through `ActionCli.toUserError`, given the binding or the actions it calls, or derive the command with `ActionCli.command`.