@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/docs/ActionToolkit.md

@@ -1,24 +1,21 @@
 # ActionToolkit
 
-Implementations as Effect's native AI `Toolkit`: one tool per action, run in the process that
-calls the model, with no server. Reach for it when a `LanguageModel` or a `Chat` in your program
-calls your actions. Nothing authenticates: the host names the caller. Code of your own calls
-the same implementations typed, with `Action.client`
-([Action.md](Action.md#call-actions-in-process)).
+Implementations as Effect's native AI `Toolkit`: one tool per action, run in the process that calls the model, with no server. Reach for it when a `LanguageModel` or a `Chat` in your program calls your actions. Nothing authenticates: the host names the caller. Code of your own calls the same implementations typed, with `Action.client` ([Action.md](Action.md#call-actions-in-process)).
 
 A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search [ActionToolkit-failures.md](ActionToolkit-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.
 
 ## Give a model tools
 
-`ActionToolkit.make` projects implementations into `{ toolkit, layer }`. Pass `toolkit` to
-`LanguageModel.generateText` or a `Chat`, and provide `layer` once, around the program:
+`ActionToolkit.make` projects implementations into `{ toolkit, layer }`. Pass `toolkit` to `LanguageModel.generateText` or a `Chat`, and provide `layer` once, around the program:
 
 ```ts example=assistant/src/toolkit.ts
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
 import { Effect, Option } from "effect";
 import { Tool, Toolkit } from "effect/ai";
-import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+
 import { identity } from "./identity/handlers.js";
-import { CurrentCaller, type Member } from "./identity/Identity.js";
+import { CurrentCaller } from "./identity/Identity.js";
+import type { Member } from "./identity/Identity.js";
 import { tasks } from "./tasks/handlers.js";
 
 // `actions.layer` holds the handlers, and requires the startup services their builders read;
@@ -33,8 +30,9 @@ const actions = ActionToolkit.make([tasks, identity], {
       Effect.serviceOption(CurrentCaller),
       Option.match({
         onNone: () => true,
-        onSome: (caller) => call.name !== "addTask" || call.input.assignee !== caller.id,
-      }),
+        onSome: (caller) =>
+          call.name !== "addTask" || call.input.assignee !== caller.id,
+      })
     ),
 });
 
@@ -42,104 +40,49 @@ const actions = ActionToolkit.make([tasks, identity], {
 // The later definition wins; annotating the generated tool keeps its handler and approval rule.
 export const toolkit = Toolkit.merge(
   actions.toolkit,
-  Toolkit.make(actions.toolkit.tools.addTask.annotate(Tool.Title, "Add a task")),
+  Toolkit.make(actions.toolkit.tools.addTask.annotate(Tool.Title, "Add a task"))
 );
 
-export const layer = actions.layer;
+export const { layer } = actions;
 
 // One toolkit serves every member, so who a turn runs as is provided around that turn. This is
 // how this example names a model's caller, and it takes a `Member`. The tools themselves accept
 // any `CurrentCaller`, so keeping the operator away from a model is this function's doing, and
 // that of every host using it.
-export const actingFor = (member: Member) => Effect.provideService(CurrentCaller, member);
+export const actingFor = (member: Member) =>
+  Effect.provideService(CurrentCaller, member);
 ```
 
-[assistant/src/agent.ts](../examples/assistant/src/agent.ts) runs the turns and provides `layer`
-with its startup services, with a scripted model in
-[assistant/src/scripted.ts](../examples/assistant/src/scripted.ts). What a call returns, a
-refusal and arguments that do not decode included, is on `ActionToolkit.make`; the options'
-rules are on `ActionToolkit.Options`.
-
-- **Let the model read its tools' results** by asking again:
-  [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts).
-- Where a model must not get every action, list the tools
-  ([Action.md](Action.md#define-a-contract)):
-  [kitchen-sink/src/issues/assistant.ts](../examples/kitchen-sink/src/issues/assistant.ts).
-- A turn's tool calls, the approved calls of an answering turn included, run concurrently unless
-  `generateText` is given a `concurrency`:
-  [assistant/src/tasks/store.ts](../examples/assistant/src/tasks/store.ts) locks each change.
-- **A model loop behind a route.** Yield `toolkit` and the model in the implementation's
-  builder, and provide `layer` to the route's layer,
-  `ActionHttp.layer(Http, ask).pipe(Layer.provide(layer))`, so the tools share the routes' build
-  ([Action.md](Action.md#share-one-build-across-servers)):
-  [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts),
-  keeping each caller's `Chat` in
-  [conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts), with a scripted
-  model in [demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts) that the
-  entrypoint provides through [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts),
-  tested over HTTP in
-  [kitchen-sink/test/assistant/assistant.test.ts](../examples/kitchen-sink/test/assistant/assistant.test.ts).
-  Name the files as it does, the route's contract `Assistant.ts` and the loop `handlers.ts`,
-  from the first one written.
-- **The real model comes later?** Provide a scripted one from the entrypoint until then, as the
-  kitchen-sink does. Reading the model with `Effect.serviceOption` hides the requirement: the
-  server builds without one and every request fails.
+[assistant/src/agent.ts](../examples/assistant/src/agent.ts) runs the turns and provides `layer` with its startup services, with a scripted model in [assistant/src/scripted.ts](../examples/assistant/src/scripted.ts). What a call returns, a refusal and arguments that do not decode included, is on `ActionToolkit.make`; the options' rules are on `ActionToolkit.Options`.
+
+- **Let the model read its tools' results** by asking again: [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts).
+- Where a model must not get every action, list the tools ([Action.md](Action.md#define-a-contract)): [kitchen-sink/src/issues/assistant.ts](../examples/kitchen-sink/src/issues/assistant.ts).
+- A turn's tool calls, the approved calls of an answering turn included, run concurrently unless `generateText` is given a `concurrency`: [assistant/src/tasks/store.ts](../examples/assistant/src/tasks/store.ts) locks each change.
+- **A model loop behind a route.** Yield `toolkit` and the model in the implementation's builder, and provide `layer` to the route's layer, `ActionHttp.layer(Http, ask).pipe(Layer.provide(layer))`, so the tools share the routes' build ([Action.md](Action.md#share-one-build-across-servers)): [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts), keeping each caller's `Chat` in [conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts), with a scripted model in [demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts) that the entrypoint provides through [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts), tested over HTTP in [kitchen-sink/test/assistant/assistant.test.ts](../examples/kitchen-sink/test/assistant/assistant.test.ts). Name the files as it does, the route's contract `Assistant.ts` and the loop `handlers.ts`, from the first one written.
+- **The real model comes later?** Provide a scripted one from the entrypoint until then, as the kitchen-sink does. Reading the model with `Effect.serviceOption` hides the requirement: the server builds without one and every request fails.
 
 ### Customize the native tools
 
-Give a generated tool a title, or other annotations, with native `Tool` and `Toolkit` from
-`effect/ai`, as `toolkit` above does; [agent.ts](../examples/assistant/src/agent.ts) reads the
-title when printing approval requests.
+Give a generated tool a title, or other annotations, with native `Tool` and `Toolkit` from `effect/ai`, as `toolkit` above does; [agent.ts](../examples/assistant/src/agent.ts) reads the title when printing approval requests.
 
-- To add other native tools, use `Toolkit.merge(toolkit, others)` and provide both handler layers
-  with `Layer.mergeAll(layer, othersHandlers)`.
+- To add other native tools, use `Toolkit.merge(toolkit, others)` and provide both handler layers with `Layer.mergeAll(layer, othersHandlers)`.
 
 ### Call a tool by hand
 
-`yield* toolkit` gives `tools.handle(name, arguments)`:
-[assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts). Its rules, where
-to provide the caller among them, are on `ActionToolkit.Tools`.
+`yield* toolkit` gives `tools.handle(name, arguments)`: [assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts). Its rules, where to provide the caller among them, are on `ActionToolkit.Tools`.
 
 ## Name the caller
 
-Provide the identity around each turn, or each call made by hand, as `actingFor` does in
-[assistant/src/toolkit.ts](../examples/assistant/src/toolkit.ts). Why never to `layer`, and that
-a protected tool owes it whatever its handler reads, are on `Action.Options.caller`
-([Action.md](Action.md#say-who-may-call-an-action)).
+Provide the identity around each turn, or each call made by hand, as `actingFor` does in [assistant/src/toolkit.ts](../examples/assistant/src/toolkit.ts). Why never to `layer`, and that a protected tool owes it whatever its handler reads, are on `Action.Options.caller` ([Action.md](Action.md#say-who-may-call-an-action)).
 
 ## Ask for approval
 
-To ask before every write: `needsApproval: (call) => !call.action.readOnly`
-([kitchen-sink/src/issues/assistant.ts](../examples/kitchen-sink/src/issues/assistant.ts)). A
-rule reading the call's input and its caller is `toolkit` above; its rules are on
-`ActionToolkit.Options`.
-
-A call that needs approval does not run: the turn ends with a `tool-approval-request` part in
-`response.content` in place of its result. Start the next turn with the person's answers, in a
-`Chat`, as the caller who was asked:
-[assistant/src/agent.ts](../examples/assistant/src/agent.ts) shows both and says why, tested in
-[assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts).
-
-- **Each request is answered on its own**: an approved call runs, a denied one does not, and one
-  left unanswered stays open for a later turn; to require every answer at once, check it in the
-  host. List the open ones with `ActionToolkit.openApprovals(yield* Ref.get(chat.history))`.
-  The kitchen-sink refuses an `approvalId` answered twice
-  ([Assistant.ts](../examples/kitchen-sink/src/assistant/Assistant.ts)), gives each call its own
-  id ([demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts)) and lets only its
-  owner reach a conversation
-  ([conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)).
-- A denied call's result, `{ type: "execution-denied", reason }`, has `reason` `undefined` unless
-  the answer gives one, so it is not JSON: a route answering it as a `Schema.Unknown` success
-  answers an empty 500.
-- **If a turn fails or is interrupted once an approved call has started**, the call may have
-  run: end the conversation and say so in the error, as
-  [kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)
-  and [handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts) do. What a failed
-  `streamText` leaves is on `ActionToolkit.openApprovals`.
-- **Show the person what is asked**: [assistant/src/agent.ts](../examples/assistant/src/agent.ts)
-  joins each request to its call by `toolCallId`; how to read the arguments is on
-  `ActionToolkit.Approval`.
-- **If repeating a write would create an unwanted additional effect, retries need
-  application-owned deduplication.** Keep the same operation key across attempts, as in
-  [notes-service's creation example](../examples/notes-service/README.md#retry-a-creation).
-  Approval history alone does not make the mutation and its result record atomic.
+To ask before every write: `needsApproval: (call) => !call.action.readOnly` ([kitchen-sink/src/issues/assistant.ts](../examples/kitchen-sink/src/issues/assistant.ts)). A rule reading the call's input and its caller is `toolkit` above; its rules are on `ActionToolkit.Options`.
+
+A call that needs approval does not run: the turn ends with a `tool-approval-request` part in `response.content` in place of its result. Start the next turn with the person's answers, in a `Chat`, as the caller who was asked: [assistant/src/agent.ts](../examples/assistant/src/agent.ts) shows both and says why, tested in [assistant/test/toolkit.test.ts](../examples/assistant/test/toolkit.test.ts).
+
+- **Each request is answered on its own**: an approved call runs, a denied one does not, and one left unanswered stays open for a later turn; to require every answer at once, check it in the host. List the open ones with `ActionToolkit.openApprovals(yield* Ref.get(chat.history))`. The kitchen-sink refuses an `approvalId` answered twice ([Assistant.ts](../examples/kitchen-sink/src/assistant/Assistant.ts)), gives each call its own id ([demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts)) and lets only its owner reach a conversation ([conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)).
+- A denied call's result, `{ type: "execution-denied", reason }`, has `reason` `undefined` unless the answer gives one, so it is not JSON: a route answering it as a `Schema.Unknown` success answers an empty 500.
+- **If a turn fails or is interrupted once an approved call has started**, the call may have run: end the conversation and say so in the error, as [kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts) and [handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts) do. What a failed `streamText` leaves is on `ActionToolkit.openApprovals`.
+- **Show the person what is asked**: [assistant/src/agent.ts](../examples/assistant/src/agent.ts) joins each request to its call by `toolCallId`; how to read the arguments is on `ActionToolkit.Approval`.
+- **If repeating a write would create an unwanted additional effect, retries need application-owned deduplication.** Keep the same operation key across attempts, as in [notes-service's creation example](../examples/notes-service/README.md#retry-a-creation). Approval history alone does not make the mutation and its result record atomic.

package/docs/Authentication-advanced.md

@@ -1,17 +1,12 @@
 # Authentication beyond a bearer token
 
-A verifier reading the request, an API key or a cookie, a route of your own, a policy before
-authentication, and a refusal outside the router.
+A verifier reading the request, an API key or a cookie, a route of your own, a policy before authentication, and a refusal outside the router.
 
-A message the library throws says its fix; for a compiler diagnostic or Effect's own error,
-search [Authentication-failures.md](Authentication-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 [Authentication-failures.md](Authentication-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.
 
 ## Read request context in a verifier
 
-A verifier may read per-request services: the request, or one of your own, such as the tenant a
-request addresses, which native router middleware provides:
+A verifier may read per-request services: the request, or one of your own, such as the tenant a request addresses, which native router middleware provides:
 
 ```ts example=kitchen-sink/src/workspaces/tenant.ts
 import { Context, Effect, Option } from "effect";
@@ -22,51 +17,43 @@ import { HttpRouter, HttpServerRequest } from "effect/http";
  * an identity: the verifier reads it to decide which of an account's memberships the caller
  * acts in. Handlers never read it; they read the workspace of the authenticated member.
  */
-export class Tenant extends Context.Service<Tenant, Option.Option<string>>()("tracker/Tenant") {}
+export class Tenant extends Context.Service<Tenant, Option.Option<string>>()(
+  "tracker/Tenant"
+) {}
 
 // Native router middleware. It provides `Tenant` to whatever it is provided to, per request:
 // to the verifier too, when it is provided after the authentication, in a `Layer.provide` of
 // its own: in one array with the authentication it would leave `Tenant` owed, since an array's
 // layers provide to the routes, not to one another.
-export const resolveTenant = HttpRouter.middleware<{ provides: Tenant }>()((route) =>
-  Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) =>
-    Effect.provideService(route, Tenant, Option.fromNullishOr(request.headers["x-workspace"])),
-  ),
+export const resolveTenant = HttpRouter.middleware<{ provides: Tenant }>()(
+  (route) =>
+    Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) =>
+      Effect.provideService(
+        route,
+        Tenant,
+        Option.fromNullishOr(request.headers["x-workspace"])
+      )
+    )
 );
 ```
 
-The verifier reading it is `authenticateBearer` in
-[kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts),
-and `publicRoutes` in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts)
-provides the middleware.
+The verifier reading it is `authenticateBearer` in [kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts), and `publicRoutes` in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) provides the middleware.
 
 ## Use a scheme other than Bearer
 
-Name the scheme in `Authentication.Options.security`, whose JSDoc says what each scheme gives
-up. See `Session` in
-[kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts) and
-`authenticateSession` in
-[kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts)
-for a session cookie beside Bearer, and
-[kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts) and
-[kitchen-sink/src/admin/authenticate.ts](../examples/kitchen-sink/src/admin/authenticate.ts)
-for an API key in a header.
-
-For a cookie covering rpcs over a WebSocket, see
-[ActionRpc.md](ActionRpc.md#send-request-context-with-a-call). A scheme the deployment decides,
-such as a cookie name a framework prefixes over HTTPS, is still one declaration, as
-`Authentication.layer` says.
+Name the scheme in `Authentication.Options.security`, whose JSDoc says what each scheme gives up. See `Session` in [kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts) and `authenticateSession` in [kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts) for a session cookie beside Bearer, and [kitchen-sink/src/admin/Admin.ts](../examples/kitchen-sink/src/admin/Admin.ts) and [kitchen-sink/src/admin/authenticate.ts](../examples/kitchen-sink/src/admin/authenticate.ts) for an API key in a header.
+
+For a cookie covering rpcs over a WebSocket, see [ActionRpc.md](ActionRpc.md#send-request-context-with-a-call). A scheme the deployment decides, such as a cookie name a framework prefixes over HTTPS, is still one declaration, as `Authentication.layer` says.
 
 ## Protect a route of your own
 
-A route of the host's own, such as a download or a WebSocket upgrade, takes
-`Authentication.protect(descriptor)`, whose rules, authorization and caching included, are on
-its JSDoc:
+A route of the host's own, such as a download or a WebSocket upgrade, takes `Authentication.protect(descriptor)`, whose rules, authorization and caching included, are on its JSDoc:
 
 ```ts example=kitchen-sink/src/attachments/download.ts
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 import { Effect, Layer } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
-import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+
 import { authorize } from "../identity/authorize.js";
 import { CurrentMember, Session } from "../identity/Identity.js";
 import { GetAttachment } from "./Attachments.js";
@@ -104,26 +91,24 @@ export const download = Layer.unwrap(
         });
       }).pipe(
         Effect.catchTag("AttachmentNotFound", () =>
-          Effect.succeed(HttpServerResponse.empty({ status: 404 })),
-        ),
-      ),
-    ).pipe(Layer.provide(Authentication.protect(Session).layer)),
-  ),
+          Effect.succeed(HttpServerResponse.empty({ status: 404 }))
+        )
+      )
+    ).pipe(Layer.provide(Authentication.protect(Session).layer))
+  )
 );
 ```
 
-[kitchen-sink/test/attachments/attachments.test.ts](../examples/kitchen-sink/test/attachments/attachments.test.ts)
-asserts what it answers.
+[kitchen-sink/test/attachments/attachments.test.ts](../examples/kitchen-sink/test/attachments/attachments.test.ts) asserts what it answers.
 
 ## Run a request policy before authentication
 
-For a check that must refuse a request before its credential is read, such as a `Host` or
-`Origin` allowlist, make global router middleware, `HttpRouter.middleware(check, { global: true })`,
-and provide it in the last `Layer.provide`:
+For a check that must refuse a request before its credential is read, such as a `Host` or `Origin` allowlist, make global router middleware, `HttpRouter.middleware(check, { global: true })`, and provide it in the last `Layer.provide`:
 
 ```ts example=kitchen-sink/src/request-policy.ts
 import { Effect, Layer, Option } from "effect";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+
 import { allowedOrigins, publicUrl } from "./config.js";
 
 const loopback = ["localhost", "127.0.0.1"];
@@ -137,28 +122,39 @@ const loopback = ["localhost", "127.0.0.1"];
 // authentication, too late.
 export const requestPolicy = HttpRouter.middleware(
   Effect.gen(function* () {
-    const hosts = [...loopback, new URL(yield* publicUrl).hostname];
+    const hosts = new Set([...loopback, new URL(yield* publicUrl).hostname]);
     const origins = yield* allowedOrigins;
 
     return (httpEffect) =>
       Effect.gen(function* () {
         const request = yield* HttpServerRequest.HttpServerRequest;
-        const url = HttpServerRequest.toURL(request.modify({ url: request.originalUrl }));
 
-        if (Option.isNone(url) || !hosts.includes(url.value.hostname)) {
+        const url = HttpServerRequest.toURL(
+          request.modify({ url: request.originalUrl })
+        );
+
+        if (Option.isNone(url) || !hosts.has(url.value.hostname)) {
           return HttpServerResponse.text("Host not allowed", { status: 403 });
         }
 
-        const origin = request.headers.origin;
-
-        if (origin !== undefined && origin !== url.value.origin && !origins.includes(origin)) {
+        const { origin } = request.headers;
+
+        // The request's own origin is that of a page served from this port directly. Behind a
+        // proxy ending TLS it is an `http:` one from Effect 4.0.6, whose `originalUrl` takes the
+        // scheme of the connection, whatever `X-Forwarded-Proto` says, so the public URL's
+        // origin is among `origins`.
+        if (
+          origin !== undefined &&
+          origin !== url.value.origin &&
+          !origins.includes(origin)
+        ) {
           return HttpServerResponse.text("Origin not allowed", { status: 403 });
         }
 
         return yield* httpEffect;
       });
   }),
-  { global: true },
+  { global: true }
 );
 
 // CORS for the one cross-origin caller, a browser MCP client. `HttpRouter.cors` is global to
@@ -181,18 +177,18 @@ export const cors = Layer.unwrap(
         "MCP-Name",
         "Mcp-Session-Id",
       ],
-      exposedHeaders: ["WWW-Authenticate", "MCP-Protocol-Version", "Mcp-Session-Id"],
-    }),
-  ),
+      exposedHeaders: [
+        "WWW-Authenticate",
+        "MCP-Protocol-Version",
+        "Mcp-Session-Id",
+      ],
+    })
+  )
 );
 ```
 
-See `publicRoutes` in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts);
-[kitchen-sink/test/request-policy.test.ts](../examples/kitchen-sink/test/request-policy.test.ts)
-asserts it.
+See `publicRoutes` in [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts); [kitchen-sink/test/request-policy.test.ts](../examples/kitchen-sink/test/request-policy.test.ts) asserts it.
 
 ## Refuse outside the router
 
-For a caller the router never routes, such as a Node `upgrade` handler admitting a socket, read
-the token with `Authentication.bearerTokenOf` and answer a refusal with
-`Authentication.refusalResponse`, whose JSDoc holds the rest.
+For a caller the router never routes, such as a Node `upgrade` handler admitting a socket, read the token with `Authentication.bearerTokenOf` and answer a refusal with `Authentication.refusalResponse`, whose JSDoc holds the rest.

package/docs/Authentication-failures.md

@@ -1,9 +1,6 @@
 # Authentication failure modes
 
-What you see when something is wrong, and the fix: compiler diagnostics and errors the library
-does not word. Search for a fragment of the message. A message the library throws says its
-fix itself. Tasks: [Authentication.md](Authentication.md),
-[Authentication-advanced.md](Authentication-advanced.md).
+What you see when something is wrong, and the fix: compiler diagnostics and errors the library does not word. Search for a fragment of the message. A message the library throws says its fix itself. Tasks: [Authentication.md](Authentication.md), [Authentication-advanced.md](Authentication-advanced.md).
 
 ## Types and startup
 
@@ -13,6 +10,10 @@ fix itself. Tasks: [Authentication.md](Authentication.md),
 - `is not assignable to type 'Forbidden | Unauthenticated'`, or `Property '…' is missing in type`, at `layer`'s verifier: it fails with an error that is neither a refusal nor one its descriptor declares, or succeeds with a value that is not the identity. Declare the error in the descriptor's `error`, or map it to a refusal where it is the caller's.
 - `Request<"Requires", Tenant>` still owed although the tenant middleware's layer is provided: it is in one `Layer.provide([...])` array with the provider, and an array's layers provide to the routes, not to one another. Provide it in a later `Layer.provide` of its own ([Read request context in a verifier](Authentication-advanced.md#read-request-context-in-a-verifier)).
 
+## Signing in
+
+- An MCP client reports `Protected resource … does not match expected …` and requests no token: the published `protectedResource.resource` is neither the endpoint's public URL nor its origin. Give one of them.
+
 ## Scopes
 
 - `Schema validation failed` thrown by `new Action.Forbidden({ scopes })`: a scope is no OAuth scope token, being empty or holding a space, `"`, `\` or a character outside printable ASCII. Give each scope as its own element.

package/docs/Authentication.md

@@ -1,24 +1,17 @@
 # Authentication
 
-How a remote caller proves the identity a protected action declares. `Authentication.make`
-declares it, as a browser-safe descriptor; `Authentication.layer` is that descriptor's provider,
-running the verifier you write. Verifying a token, login and consent stay in the application.
+How a remote caller proves the identity a protected action declares. `Authentication.make` declares it, as a browser-safe descriptor; `Authentication.layer` is that descriptor's provider, running the verifier you write. Verifying a token, login and consent stay in the application.
 
-A message the library throws says its fix; for a compiler diagnostic or Effect's own error,
-search [Authentication-failures.md](Authentication-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 [Authentication-failures.md](Authentication-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.
 
 ## Declare how callers sign in
 
-A protected action declares its identity service, `caller: CurrentUser`
-([Action.md](Action.md#say-who-may-call-an-action)). Declare the descriptor beside that
-service, in the contract file every client of the binding imports:
+A protected action declares its identity service, `caller: CurrentUser` ([Action.md](Action.md#say-who-may-call-an-action)). Declare the descriptor beside that service, in the contract file every client of the binding imports:
 
 ```ts example=notes-service/src/identity/Identity.ts
-import { Context, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Context, Schema } from "effect";
 
 export const scopes = { read: "notes:read", write: "notes:write" } as const;
 
@@ -34,7 +27,7 @@ export interface User {
  * provides it per request, and a local host, such as the stdio server, provides it itself.
  */
 export class CurrentUser extends Context.Service<CurrentUser, User>()(
-  "notes-service/CurrentUser",
+  "notes-service/CurrentUser"
 ) {}
 
 // How a remote caller proves it is CurrentUser: a bearer token, the default scheme. Clients
@@ -49,45 +42,36 @@ export const WhoAmI = Action.make("whoAmI", {
 });
 ```
 
-Name it in every binding and MCP endpoint that serves a protected action: an HTTP binding
-([notes-service/src/Api.ts](../examples/notes-service/src/Api.ts)), an MCP endpoint
-([notes-service/src/routes.ts](../examples/notes-service/src/routes.ts)) and an RPC binding
-([live-rpc/src/Rpc.ts](../examples/live-rpc/src/Rpc.ts)); a local surface takes none
-([Action.md](Action.md#say-who-may-call-an-action)). The name's rules are on
-`Authentication.make`, the scheme's on `Authentication.Options.security`; a second credential
-for one identity is in
-[kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts).
+Name it in every binding and MCP endpoint that serves a protected action: an HTTP binding ([notes-service/src/Api.ts](../examples/notes-service/src/Api.ts)), an MCP endpoint ([notes-service/src/routes.ts](../examples/notes-service/src/routes.ts)) and an RPC binding ([live-rpc/src/Rpc.ts](../examples/live-rpc/src/Rpc.ts)); a local surface takes none ([Action.md](Action.md#say-who-may-call-an-action)). The name's rules are on `Authentication.make`, the scheme's on `Authentication.Options.security`; a second credential for one identity is in [kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts). A descriptor of protected [events](Event.md) may also say which subscriber an identity is, its `principal`, for what a surface holds between one subscriber's requests: [build-events/src/identity/Identity.ts](../examples/build-events/src/identity/Identity.ts). When it is required is on `Authentication.Options.principal`; its `schema`, which keeps an identity past a restart, on `Authentication.Options.schema`.
 
-- **Protecting an action that tests already call breaks them**, at compile time
-  ([Testing-failures.md](Testing-failures.md),
-  [Authentication-failures.md](Authentication-failures.md#types-and-startup)), and a call over
-  HTTP without a credential gets `Unauthenticated` at run time.
+- **Protecting an action that tests already call breaks them**, at compile time ([Testing-failures.md](Testing-failures.md), [Authentication-failures.md](Authentication-failures.md#types-and-startup)), and a call over HTTP without a credential gets `Unauthenticated` at run time.
 
 ## Verify credentials
 
-Write the verifier in a server-only module, give it to `Authentication.layer` and provide that
-layer as [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts) does. What the
-verifier takes, fails with and must check itself is on `Authentication.Verify`; where its layer
-goes, on `Authentication.layer`.
+Write the verifier in a server-only module, give it to `Authentication.layer` and provide that layer as [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts) does. What the verifier takes, fails with and must check itself is on `Authentication.Verify`; where its layer goes, on `Authentication.layer`.
 
 ```ts example=notes-service/src/identity/verifier.ts
-import { Config, Effect, Redacted } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Config, Effect, Redacted } from "effect";
+
 import { Login, scopes } from "./Identity.js";
 import { users } from "./users.js";
 
-const isToken = (token: string): token is keyof typeof users => Object.hasOwn(users, token);
+const isToken = (token: string): token is keyof typeof users =>
+  Object.hasOwn(users, token);
 
 // DEMO ONLY: a token is a user's name. A real verifier checks a signed token with your
 // authorization server's library, its audience included. An unknown token is the built-in
 // `Unauthenticated`: a 401 every client decodes.
-const verify = (token: Redacted.Redacted<string>) => {
+const verify = (token: Redacted.Redacted) => {
   const name = Redacted.value(token);
 
   return isToken(name)
     ? Effect.succeed(users[name])
-    : Effect.fail(new Action.Unauthenticated({ message: "Unknown demo token." }));
+    : Effect.fail(
+        new Action.Unauthenticated({ message: "Unknown demo token." })
+      );
 };
 
 // Server only: `Login`'s provider. As an OAuth protected resource it also publishes discovery,
@@ -95,7 +79,9 @@ const verify = (token: Redacted.Redacted<string>) => {
 // is the server's public URL, known only at startup, so it is read from config.
 export const authenticate = Authentication.layer(Login, verify, {
   protectedResource: Effect.map(
-    Config.String("PUBLIC_URL").pipe(Config.withDefault("http://localhost:3000")),
+    Config.String("PUBLIC_URL").pipe(
+      Config.withDefault("http://localhost:3000")
+    ),
     (url) =>
       ({
         resource: `${url}/mcp`,
@@ -103,38 +89,17 @@ export const authenticate = Authentication.layer(Login, verify, {
         authorizationServers: ["https://auth.example.com"],
         scopesSupported: [scopes.read, scopes.write],
         scopesRequired: [scopes.read],
-      }) satisfies Authentication.ProtectedResource,
+      }) satisfies Authentication.ProtectedResource
   ),
 });
 ```
 
-For a verifier built from startup services, see `authenticateBearer` in
-[kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts);
-for a failure that is not the caller's, `Authentication.Options.error` and `IssuerUnavailable` in
-[kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts); to
-test as a signed-in caller, [Testing.md](Testing.md#test-as-a-signed-in-caller). What each
-surface answers a missing or refused credential with is on `Action.Unauthenticated` and
-`Action.Forbidden`, as
-[kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)
-asserts, status and challenge included.
+For a verifier built from startup services, see `authenticateBearer` in [kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts); for a failure that is not the caller's, `Authentication.Options.error` and `IssuerUnavailable` in [kitchen-sink/src/identity/Identity.ts](../examples/kitchen-sink/src/identity/Identity.ts); to test as a signed-in caller, [Testing.md](Testing.md#test-as-a-signed-in-caller). What each surface answers a missing or refused credential with is on `Action.Unauthenticated` and `Action.Forbidden`, as [kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts) asserts, status and challenge included.
 
 ## Publish OAuth discovery
 
-For an MCP endpoint whose users sign in through OAuth, give the Bearer descriptor's `layer` a
-`protectedResource`, as the verifier above does. Its rules are on
-`Authentication.LayerOptions.protectedResource` and on each field of
-`Authentication.ProtectedResource`;
-[kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts)
-asserts the discovery it serves. To restrict who reads it, see
-[Run a request policy before authentication](Authentication-advanced.md#run-a-request-policy-before-authentication).
+For an MCP endpoint whose users sign in through OAuth, give the Bearer descriptor's `layer` a `protectedResource`, as the verifier above does. Its rules are on `Authentication.LayerOptions.protectedResource` and on each field of `Authentication.ProtectedResource`; [kitchen-sink/test/identity/identity.test.ts](../examples/kitchen-sink/test/identity/identity.test.ts) asserts the discovery it serves. To restrict who reads it, see [Run a request policy before authentication](Authentication-advanced.md#run-a-request-policy-before-authentication).
 
 ### Step up for a scope
 
-To have an OAuth client sign in again, or re-authorize with more scopes, fail the authorizer, a
-handler or the verifier with `Action.Unauthenticated`, or with `Action.Forbidden` naming
-`scopes`
-([notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts));
-`inService` in
-[kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts)
-refuses with none. What each answers on each surface, and when to name scopes, are on those two
-classes.
+To have an OAuth client sign in again, or re-authorize with more scopes, fail the authorizer, a handler or the verifier with `Action.Unauthenticated`, or with `Action.Forbidden` naming `scopes` ([notes-service/src/identity/authorize.ts](../examples/notes-service/src/identity/authorize.ts)); `inService` in [kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts) refuses with none. What each answers on each surface, and when to name scopes, are on those two classes.

package/docs/Event-failures.md

@@ -0,0 +1,15 @@
+# Event failure modes
+
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [Event.md](Event.md).
+
+## At `implement`
+
+- `is not assignable to parameter of type '... & "A protected event takes { authorize }: your rule, or Event.allowAll"'`: the list holds a protected event type, which takes `{ authorize }`. Give your rule, or `Event.allowAll`.
+- `Type '{ authorize: ... }' is not assignable to type '{ readonly authorize?: "A public-only target takes no authorize" }'`: every event type in the list is public, and no authorizer runs for one. Remove `authorize`.
+- `Object literal may only specify known properties, and 'log' does not exist`, or `Type '{}' is not assignable to type 'undefined'` at a source: it holds both `check` and `log`. Keep one: `check` where a store can be asked what happened since a cursor, `log` where nothing else keeps the occurrences.
+- `Parameter 'input' implicitly has an 'any' type` at a check, a `match` or a `transform`: the builder is wrapped, as in `Effect.gen(…).pipe(Effect.provide(layer))`, and its sources are no longer typed from the contracts. Give `implement` the builder itself.
+
+## At `watch`
+
+- `Property 'watch' does not exist on type`: the client was given no event implementation. Pass the event implementations beside the action ones, `Action.client([builds, buildEvents])`.
+- `Argument of type 'Event<...>' is not assignable to parameter of type` at `watch`: the client holds no implementation of that event type. Add its implementation to the list.