@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

package/examples/live-rpc/src/browser.ts

@@ -1,4 +1,4 @@
-import { Context, Effect, Layer, ManagedRuntime } from "effect";
+import { Effect, Layer } from "effect";
 import { RpcClient, RpcSerialization } from "effect/rpc";
 import { Socket } from "effect/socket";
 import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
@@ -9,18 +9,16 @@ import { Rpc } from "./Rpc.js";
 // bundler gets the contracts and Effect's RPC client, no handler and nothing of Node.
 
 // Effect's own client protocol: one WebSocket, speaking the server's JSON. This layer owns
-// the socket: it opens when the layer is built and closes when the layer is released, so
-// provide it once, around the page's whole program, never around one call. Which WebSocket is
-// left to the host: a page provides `Socket.layerWebSocketConstructorGlobal`, the browser's
-// own, and client.ts provides Node's.
+// the socket, so a page provides it once, around its whole program, and every call shares
+// that one socket. Which WebSocket is left to the host: a page provides
+// `Socket.layerWebSocketConstructorGlobal`, the browser's own, and client.ts provides Node's.
 export const connection = (url: string) =>
   RpcClient.layerProtocolSocket().pipe(
     Layer.provide(Socket.layerWebSocket(url)),
     Layer.provide(RpcSerialization.layerJson),
   );
 
-// The chat as a page uses it, on the connection provided around it. The scope it needs holds
-// only the typed client built on that connection, not the socket.
+// The chat as a page uses it, on the connection provided around it.
 export const openChat = Effect.gen(function* () {
   // One typed method per action of the binding, all on the one connection.
   const client = yield* ActionRpc.client(Rpc);
@@ -30,14 +28,13 @@ export const openChat = Effect.gen(function* () {
     rooms: Effect.map(client.listRooms(), ({ rooms }) => rooms),
 
     room: (name: string, token: string) => {
-      // A browser WebSocket sets no header when it connects, so the token travels on each
-      // message, and the room beside it. A refreshed token needs no new socket.
+      // A browser WebSocket cannot set an `Authorization` header on its upgrade, so the token
+      // travels on each message, and the room beside it. A refreshed token needs no new socket.
       const here = RpcClient.withHeaders({ authorization: `Bearer ${token}`, [roomHeader]: name });
 
       return {
         // Called again and again while the page is open, with the last id it holds. A token
-        // may expire under a socket that stays up, so the refusals are handled here. Each is
-        // a typed failure matched by its tag, and only that call fails: the socket stays open.
+        // may expire while the page stays open, so each refusal becomes what the page shows.
         read: (after: number) =>
           client.readMessages({ after }).pipe(
             here,
@@ -66,33 +63,3 @@ export const openChat = Effect.gen(function* () {
     },
   };
 });
-
-// The chat for a page that is not one Effect program: the same client, each call a promise.
-// A `ManagedRuntime` keeps the protocol's layer, and so the socket, between calls. It builds
-// the layer on the first call, which is when the socket opens, and `close` releases it. A
-// failure `openChat` does not handle, such as `InvalidInput`, rejects the promise.
-class Chat extends Context.Service<Chat, Effect.Success<typeof openChat>>()("live-rpc/Chat") {}
-
-export const chatOver = <E>(protocol: Layer.Layer<RpcClient.Protocol, E>) => {
-  const runtime = ManagedRuntime.make(Layer.effect(Chat, openChat).pipe(Layer.provide(protocol)));
-
-  const call = <A, E2>(use: (chat: Chat["Service"]) => Effect.Effect<A, E2>) =>
-    runtime.runPromise(Effect.flatMap(Chat, use));
-
-  return {
-    rooms: () => call((chat) => chat.rooms),
-
-    room: (name: string, token: string) => ({
-      read: (after: number) => call((chat) => chat.room(name, token).read(after)),
-      post: (text: string) => call((chat) => chat.room(name, token).post(text)),
-      remove: (id: number) => call((chat) => chat.room(name, token).remove(id)),
-    }),
-
-    close: () => runtime.dispose(),
-  };
-};
-
-// What a page calls: `const chat = connect("wss://chat.example/rpc")`, on the browser's own
-// WebSocket, then `await chat.room("lobby", token).post("Hello")`.
-export const connect = (url: string) =>
-  chatOver(connection(url).pipe(Layer.provide(Socket.layerWebSocketConstructorGlobal)));

package/examples/live-rpc/src/chat/Chat.ts

@@ -30,13 +30,19 @@ export class NotAuthor extends Schema.TaggedError<NotAuthor>()(
 ) {}
 
 // Which room a call is about is not an input of any action: it travels beside the call, in
-// this header, as the token does. The client sets it; on the server, room.ts reads it. A call
-// without the header is about the default room, so `listRooms`, which is about none, sends none.
+// this header, as the token does, because `authorize` sees the action and not its input, and
+// the membership rule needs the room. With the room in the input, that check belongs in the
+// store, as `MessageStore.remove` takes the author and refuses with `NotAuthor`, never in a
+// helper each handler must remember to call. The client sets the header; on the server,
+// room.ts reads it. A call without it is about the default room, so `listRooms`, which is
+// about none, sends none; yours may refuse such a call instead.
 export const roomHeader = "x-room";
 
 export const defaultRoom = "lobby";
 
-// Public: `caller: Action.Anyone`. A page shows the rooms before anyone has signed in.
+// Public: `caller: Action.Anyone`, so a page shows the rooms before anyone has signed in. It
+// tells a signed-out caller every room's name and how many messages it holds, a room appearing
+// once someone posts: decide whether yours may.
 export const ListRooms = Action.make("listRooms", {
   description: "List the rooms someone has posted in, and how many messages each holds.",
   success: {

package/examples/live-rpc/src/chat/room.ts

@@ -9,7 +9,7 @@ import { defaultRoom, roomHeader } from "./Chat.js";
 export class CurrentRoom extends Context.Service<CurrentRoom, string>()("live-rpc/CurrentRoom") {}
 
 // Native Effect RPC middleware, declared as providing `CurrentRoom`. Listed in
-// `ActionRpc.layer`'s `middleware`, it runs around every rpc, once per message.
+// `ActionRpc.layer`'s `middleware`, it runs once per message.
 export class ResolveRoom extends RpcMiddleware.Service<ResolveRoom, { provides: CurrentRoom }>()(
   "live-rpc/ResolveRoom",
 ) {}

package/examples/live-rpc/src/client.ts

@@ -7,7 +7,7 @@ import { connection, openChat } from "./browser.js";
 const visit = Effect.gen(function* () {
   const chat = yield* openChat;
 
-  // Two members on the one socket: each call is whoever its token says.
+  // Two members on the one socket.
   const ada = chat.room("lobby", "ada");
   const grace = chat.room("lobby", "grace");
 
@@ -26,8 +26,7 @@ const visit = Effect.gen(function* () {
 const main = Effect.gen(function* () {
   const url = yield* Config.String("CHAT_URL").pipe(Config.withDefault("ws://127.0.0.1:3000/rpc"));
 
-  // The socket belongs to `connection(url)`: provided once around the whole visit, it opens
-  // for it and closes when this `Effect.provide` ends. `Effect.scoped` holds the client alone.
+  // One socket for the whole visit, so both members' calls share it.
   yield* visit.pipe(
     Effect.scoped,
     Effect.provide(connection(url).pipe(Layer.provide(NodeSocket.layerWebSocketConstructor))),

package/examples/live-rpc/src/page.ts

@@ -0,0 +1,34 @@
+import { Context, Effect, Layer, ManagedRuntime } from "effect";
+import { RpcClient } from "effect/rpc";
+import { Socket } from "effect/socket";
+import { connection, openChat } from "./browser.js";
+
+// The chat for a page that is not one Effect program: the same client, each call a promise.
+// A `ManagedRuntime` keeps the protocol's layer, and so the socket, between calls. It builds
+// the layer on the first call, which is when the socket opens, and `close` releases it. A
+// failure `openChat` does not handle, such as `InvalidInput`, rejects the promise.
+class Chat extends Context.Service<Chat, Effect.Success<typeof openChat>>()("live-rpc/Chat") {}
+
+export const chatOver = <E>(protocol: Layer.Layer<RpcClient.Protocol, E>) => {
+  const runtime = ManagedRuntime.make(Layer.effect(Chat, openChat).pipe(Layer.provide(protocol)));
+
+  const call = <A, E2>(use: (chat: Chat["Service"]) => Effect.Effect<A, E2>) =>
+    runtime.runPromise(Effect.flatMap(Chat, use));
+
+  return {
+    rooms: () => call((chat) => chat.rooms),
+
+    room: (name: string, token: string) => ({
+      read: (after: number) => call((chat) => chat.room(name, token).read(after)),
+      post: (text: string) => call((chat) => chat.room(name, token).post(text)),
+      remove: (id: number) => call((chat) => chat.room(name, token).remove(id)),
+    }),
+
+    close: () => runtime.dispose(),
+  };
+};
+
+// What a page calls: `const chat = connect("wss://chat.example/rpc")`, on the browser's own
+// WebSocket, then `await chat.room("lobby", token).post("Hello")`.
+export const connect = (url: string) =>
+  chatOver(connection(url).pipe(Layer.provide(Socket.layerWebSocketConstructorGlobal)));

package/examples/live-rpc/src/routes.ts

@@ -5,14 +5,13 @@ import { ResolveRoom, resolveRoom } from "./chat/room.js";
 import { authenticate } from "./identity/verifier.js";
 import { Rpc } from "./Rpc.js";
 
-// The binding's rpcs on Effect's own RpcServer. A protected rpc authenticates every message
-// with `Login`'s verifier, so one connection may carry several callers; `listRooms` needs no
-// token.
+// The binding's rpcs on Effect's own RpcServer, the protected ones behind `Login`'s verifier;
+// `listRooms` needs no token.
 //
-// `middleware` runs around every rpc, inside authentication and before the input is decoded.
-// `ResolveRoom` provides `CurrentRoom`, which the handlers and `authorize` read. Only something
-// that runs per message can: `Layer.succeed(CurrentRoom, "lobby")` provided here would leave
-// the layer still requiring it, in its type.
+// `ResolveRoom`, listed in `middleware`, provides `CurrentRoom`, which the handlers and
+// `authorize` read. Only something that runs per message can, since each message names its own
+// room: `Layer.succeed(CurrentRoom, "lobby")` provided here would leave the layer still
+// requiring it, in its type.
 //
 // It still requires three things, each chosen by whoever serves it. The protocol and its
 // serialization: server.ts gives it a WebSocket, and a test Effect's HTTP protocol, which

package/examples/live-rpc/src/server.ts

@@ -7,12 +7,12 @@ import { MessageStore } from "./chat/store.js";
 import { rpc } from "./routes.js";
 
 // Entrypoint: `node --import tsx examples/live-rpc/src/server.ts`.
-// The composition root of the server. It chooses the protocol, the store and the port, and
-// starts Node's HTTP server. It provides no caller and no room: those arrive with each message.
+// It chooses the protocol, the store and the port, and starts Node's HTTP server. It provides
+// no caller and no room: those arrive with each message.
 
 // The rpcs over a WebSocket at `/rpc`, the router's one route: Node's HTTP server answers the
-// upgrade. `ActionRpc.layer` serves a protocol speaking JSON, and the client must speak the
-// same one.
+// upgrade. JSON, because a page's client speaks it: browser.ts gives its socket the same
+// serialization.
 const socket = rpc.pipe(
   Layer.provide(RpcServer.layerProtocolWebsocket({ path: "/rpc" })),
   Layer.provide(RpcSerialization.layerJson),
@@ -35,6 +35,8 @@ const server = Layer.unwrap(
           websocket: { maxPayload: 64 * 1024 },
         }),
       ),
+      // DEMO ONLY: messages live in this process's memory; a deployment provides a store that
+      // lasts.
       Layer.provide(MessageStore.layerMemory),
     );
   }),

package/examples/live-rpc/test/browser.test.ts

@@ -3,13 +3,14 @@ import { Effect, Layer } from "effect";
 import { RpcClient, RpcSerialization, RpcServer } from "effect/rpc";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
-import { chatOver, openChat } from "../src/browser.js";
+import { openChat } from "../src/browser.js";
+import { chatOver } from "../src/page.js";
 import { MessageStore } from "../src/chat/store.js";
 import { rpc } from "../src/routes.js";
 
-// The page's client against the real rpcs, in memory. `openChat` needs a client protocol and
-// does not care which: a page gives it `connection(url)`, a WebSocket, and this test Effect's
-// HTTP protocol, answered by `Testing.layer`, which cannot upgrade a WebSocket.
+// The page's client against the real rpcs, in memory, served as in routes.test.ts. `openChat`
+// needs a client protocol and does not care which: a page gives it `connection(url)`, a
+// WebSocket, and this test Effect's HTTP protocol.
 const served = RpcClient.layerProtocolHttp({ url: "/rpc" }).pipe(
   Layer.provide(RpcSerialization.layerJson),
   Layer.provide(
@@ -78,7 +79,7 @@ describe("the page's client", () => {
 
   // `connect(url)` is this with a WebSocket. Each test's runtime builds its own layer, and so
   // its own store.
-  it("answers a page that is not an Effect program with promises, on one connection", async () => {
+  it("answers a page that is not an Effect program with promises, until it closes", async () => {
     const chat = chatOver(served);
 
     const posted = await chat.room("lobby", "ada").post("Deploying at noon.");

package/examples/live-rpc/test/routes.test.ts

@@ -10,9 +10,8 @@ import { rpc } from "../src/routes.js";
 import { Rpc } from "../src/Rpc.js";
 
 // What the wire adds: the real rpcs, behind their real authentication and middleware,
-// answering in memory. The server gives them a WebSocket, which `Testing.layer` cannot
-// upgrade: it answers HTTP requests alone. So the test gives the same layer Effect's HTTP
-// protocol, and its client posts to it. No port is opened.
+// answering in memory. The test gives them Effect's HTTP protocol, not the server's WebSocket,
+// because `Testing.layer` answers HTTP requests; no port is opened.
 const server = rpc.pipe(
   Layer.provide(RpcServer.layerProtocolHttp({ path: "/rpc" })),
   Layer.provide(RpcSerialization.layerJson),
@@ -30,18 +29,20 @@ const as = (token: string) => RpcClient.withHeaders({ authorization: `Bearer ${t
 const inRoom = (room: string) => RpcClient.withHeaders({ [roomHeader]: room });
 
 describe("the chat, over RPC", () => {
-  it.effect("answers the public rpc without a token and refuses the rest", () =>
-    Effect.gen(function* () {
-      const client = yield* ActionRpc.client(Rpc);
-      const signedOut = yield* Effect.flip(client.readMessages({ after: 0 }));
-      const stranger = yield* Effect.flip(client.readMessages({ after: 0 }).pipe(as("mallory")));
-
-      expect(yield* client.listRooms()).toEqual({ rooms: [] });
-      expect(signedOut).toBeInstanceOf(Action.Unauthenticated);
-      expect(signedOut.message).toBe("A bearer token is required.");
-      expect(stranger).toBeInstanceOf(Action.Unauthenticated);
-      expect(stranger.message).toBe("Unknown demo token.");
-    }).pipe(Effect.provide(served)),
+  it.effect(
+    "answers the public rpc without a token and refuses a protected rpc without a known token",
+    () =>
+      Effect.gen(function* () {
+        const client = yield* ActionRpc.client(Rpc);
+        const signedOut = yield* Effect.flip(client.readMessages({ after: 0 }));
+        const stranger = yield* Effect.flip(client.readMessages({ after: 0 }).pipe(as("mallory")));
+
+        expect(yield* client.listRooms()).toEqual({ rooms: [] });
+        expect(signedOut).toBeInstanceOf(Action.Unauthenticated);
+        expect(signedOut.message).toBe("A bearer token is required.");
+        expect(stranger).toBeInstanceOf(Action.Unauthenticated);
+        expect(stranger.message).toBe("Unknown demo token.");
+      }).pipe(Effect.provide(served)),
   );
 
   it.effect("authenticates each call by its own token: two callers on one client", () =>

package/examples/live-rpc/test/server.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from "@effect/vitest";
 import { Effect, Layer } from "effect";
 import { HttpRouter, HttpServer } from "effect/http";
 import { RpcSerialization, RpcServer } from "effect/rpc";
-import { connect } from "../src/browser.js";
+import { connect } from "../src/page.js";
 import { MessageStore } from "../src/chat/store.js";
 import { rpc } from "../src/routes.js";
 

package/examples/mcp-tools/README.md

@@ -5,11 +5,6 @@ authentication of its own. It signs in to the farm once, with its own account, a
 reach it may call every tool, so it runs as a local subprocess of an agent or on a network only
 trusted clients are on.
 
-Start here if you are putting an existing API in front of a model, then read
-[ActionMcp.md](../../docs/ActionMcp.md). For tools that need a token, its "Protect tools" shows
-the verifier, and [notes-service](../notes-service/) is a server whose tools belong to the
-signed-in user.
-
 ## Run it
 
 From the repository root, after `vp install` (from an installed package, see
@@ -28,8 +23,7 @@ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":
 vp test examples/mcp-tools
 ```
 
-The farm is a fake, answered in memory, so any URL, user and password work: replace it with a
-real HTTP client before deploying anything. `ALLOWED_ORIGINS` lists the browser origins the HTTP
+The farm is a fake, answered in memory, so any URL, user and password work. `ALLOWED_ORIGINS` lists the browser origins the HTTP
 endpoint accepts and answers with CORS headers, comma-separated; `HOST` is the interface it
 listens on.
 
@@ -80,9 +74,9 @@ curl http://127.0.0.1:3000/mcp \
 ```
 
 It answers `{"jsonrpc":"2.0","id":1,"result":{…,"structuredContent":{"printers":[…]},"isError":false}}`.
-Every header is needed: without `Accept` naming both types the answer is an empty 406, without
-`Content-Type` a 415, and without an `MCP-` header, or with one that differs from the body, a
-400 saying which. `tools/list` takes the same request with that method, no `MCP-Name` header,
+Every header is needed, as `ActionMcp.request` builds it, and
+[ActionMcp-failures.md](../../docs/ActionMcp-failures.md) lists what a missing one answers.
+`tools/list` takes the same request with that method, no `MCP-Name` header,
 and no `name` or `arguments`.
 
 ## Layout
@@ -105,40 +99,23 @@ test/
 └── routes.test.ts     over MCP in memory, with Testing.layer
 ```
 
-- **The upstream is a service, built once.** `farm.ts` declares what the handlers need of the
-  farm, and `platform/print-farm.ts` is its Layer over the farm's HTTP API: it reads its URL and
-  credentials from `Config`, takes whichever `HttpClient` the entrypoint provides, and signs in
-  while it is built. The handlers get it already signed in and only delegate: `handlers.ts`
-  maps each tool onto a method of `PrintFarm`, which knows nothing of tools or HTTP, so a second
-  caller of the farm, a job or another surface, takes the service alone.
-- **One declared error, mapped in one place.** A refusal, an unreachable farm, an answer of
-  another shape and one that never comes each leave `platform/print-farm.ts` as a `PrintFarmError` with a
-  message a model can act on. No handler catches anything.
-- **What a model sends is checked by the contract.** A printer id becomes part of the farm's
-  URL, so its schema admits only what is safe there, and anything else is refused before a
-  handler runs.
-- **One implementation, two transports.** `server.ts` and `stdio.ts` serve the same `printers`
-  with the same `serverInfo`; they differ in what they provide around it.
-- **The contract is the tool.** A tool's name, description, input schema, hints and title all
-  come from `Printers.ts`.
-
 ## Where to look
 
-| To see                                                          | Read                             |
-| --------------------------------------------------------------- | -------------------------------- |
-| Public tools described for a model, with field descriptions     | `src/printers/Printers.ts`       |
-| `readOnly`, `title`, `destructiveHint` and `idempotentHint`     | `src/printers/Printers.ts`       |
-| One declared error shared by every tool                         | `src/printers/Printers.ts`       |
-| An input a model cannot use to reach another URL                | `src/printers/Printers.ts`       |
-| A tool answering an image beside other fields                   | `src/printers/Printers.ts`       |
-| An upstream client reading `Config`, signing in once            | `src/platform/print-farm.ts`     |
-| An upstream's failures mapped to the declared error             | `src/platform/print-farm.ts`     |
-| A builder yielding a service, and handlers that only delegate   | `src/printers/handlers.ts`       |
-| Server `instructions`, shared by both transports                | `src/instructions.ts`            |
-| Allowed origins from `Config`, their CORS, and `/healthz`       | `src/routes.ts`                  |
-| A request body limit, and where an unauthenticated server binds | `src/server.ts`                  |
-| A stdio server whose logs go to stderr                          | `src/stdio.ts`                   |
-| A fake upstream provided as a Layer, to a test or an entrypoint | `src/platform/fake-farm.ts`      |
-| Testing tools and each upstream failure's message in process    | `test/printers/printers.test.ts` |
-| Testing listed hints, an image and the origin check in memory   | `test/routes.test.ts`            |
-| Testing CORS for one configured origin and for several          | `test/routes.test.ts`            |
+| To see                                                                  | Read                             |
+| ----------------------------------------------------------------------- | -------------------------------- |
+| Public tools described for a model, with field descriptions             | `src/printers/Printers.ts`       |
+| `readOnly`, `title`, `idempotentHint`, and destructive as MCP's default | `src/printers/Printers.ts`       |
+| One declared error shared by every tool                                 | `src/printers/Printers.ts`       |
+| An input a model cannot use to reach another URL                        | `src/printers/Printers.ts`       |
+| A tool answering an image beside other fields                           | `src/printers/Printers.ts`       |
+| An upstream client reading `Config`, signing in once                    | `src/platform/print-farm.ts`     |
+| An upstream's failures mapped to the declared error                     | `src/platform/print-farm.ts`     |
+| A builder yielding a service, and handlers that only delegate           | `src/printers/handlers.ts`       |
+| Server `instructions`, shared by both transports                        | `src/instructions.ts`            |
+| Allowed origins from `Config`, their CORS, and `/healthz`               | `src/routes.ts`                  |
+| A request body limit, and where an unauthenticated server binds         | `src/server.ts`                  |
+| A stdio server whose logs go to stderr                                  | `src/stdio.ts`                   |
+| A fake upstream provided as a Layer, to a test or an entrypoint         | `src/platform/fake-farm.ts`      |
+| Testing tools and the upstream's failure messages in process            | `test/printers/printers.test.ts` |
+| Testing listed hints, an image and the origin check in memory           | `test/routes.test.ts`            |
+| Testing CORS for one configured origin and for several                  | `test/routes.test.ts`            |

package/examples/mcp-tools/src/printers/Printers.ts

@@ -40,8 +40,7 @@ const tool = { caller: Action.Anyone, error: PrintFarmError } as const;
 // commands names them in camelCase, as notes-service does.
 //
 // A description is written for the model that picks the tool: what it does, when to call it,
-// and what it answers. `readOnly` is sent as the tool's read-only hint; `mcp` holds the other
-// hints and the title a client shows its user.
+// and what it answers.
 export const ListPrinters = Action.make("list_printers", {
   ...tool,
   description:
@@ -53,8 +52,7 @@ export const ListPrinters = Action.make("list_printers", {
   mcp: { title: "List printers" },
 });
 
-// `image` is an `Action.Image` beside an ordinary field. Over MCP it is sent as an image block
-// the model can look at, after the JSON of `{ printer }`.
+// `image` is an `Action.Image`, so a model sees the picture rather than reading its base64.
 export const GetCameraSnapshot = Action.make("get_camera_snapshot", {
   ...tool,
   description:
@@ -95,12 +93,10 @@ export const SetPaused = Action.make("set_paused", {
   },
   success: Printer,
   readOnly: false,
-  // Destructive, MCP's default for a write: a pause interrupts a running print. Only a write
-  // that only adds, such as creating a record, says `destructiveHint: false`.
+  // Destructive, MCP's default for a write: a pause interrupts a running print.
   mcp: { title: "Pause or resume a print", idempotentHint: true },
 });
 
-// Destructive, which is MCP's default for a write, so no `destructiveHint` is stated.
 export const CancelPrint = Action.make("cancel_print", {
   ...tool,
   description:

package/examples/mcp-tools/src/routes.ts

@@ -20,13 +20,6 @@ export const routes = Layer.unwrap(
     // no origin, allows every one, so it is added only where an origin is configured. The
     // methods are the endpoint's, the headers those an MCP client sends and must be able to
     // read; an endpoint with authentication adds `Authorization` and exposes `WWW-Authenticate`.
-    //
-    // Given several origins it names the request's own in `Access-Control-Allow-Origin` when
-    // it is listed, and sends no such header otherwise. Given exactly one it compares nothing:
-    // every answer names that origin, a preflight from elsewhere included. Both refuse a page
-    // elsewhere, whose browser allows a call only where the header names the page's own origin,
-    // and the Origin check above has answered its request 403 either way. So a test of one
-    // configured origin asserts which origin is named, never that the header is absent.
     const cors =
       allowedOrigins.length === 0
         ? Layer.empty

package/examples/mcp-tools/src/server.ts

@@ -10,7 +10,7 @@ import { routes } from "./routes.js";
 // and FARM_PASSWORD set. MCP over HTTP, for clients that connect to a URL.
 // These tools are public: no route asks for a token, so where the server listens is its access
 // control, the loopback interface by default or a network only trusted clients are on. Tools
-// that need a caller take a verifier, as docs/ActionMcp.md's "Protect tools" shows.
+// that need a caller are protected as docs/ActionMcp.md's "Protect tools" shows.
 const server = Layer.unwrap(
   Effect.gen(function* () {
     const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));

package/examples/mcp-tools/test/printers/printers.test.ts

@@ -63,7 +63,7 @@ const farmThat = (
 const door = { id: "mk4-1", name: "MK4 by the door" };
 
 describe("printers, in process", () => {
-  it.effect("pauses, resumes and cancels a job, each call safe to repeat", () =>
+  it.effect("pauses, resumes and cancels a job, pause and cancel safe to repeat", () =>
     Effect.gen(function* () {
       const client = yield* Action.client(printers);
       const pause = client.set_paused({ printer_id: "mk4-1", paused: true });
@@ -115,8 +115,7 @@ describe("printers, in process", () => {
     }).pipe(Effect.provide(farmOver(noting(sent))));
   });
 
-  // The message is all a model gets of a failure, so each test asserts it. `toEqual` with an
-  // expected error would not: an error's `message` is not among the properties it compares.
+  // The message is all a model gets of a failure, so each test asserts it.
   it.effect("fails with the declared error, carrying the farm's own reason", () =>
     Effect.gen(function* () {
       const client = yield* Action.client(printers);

package/examples/mcp-tools/test/routes.test.ts

@@ -14,8 +14,7 @@ import { routes } from "../src/routes.js";
 // What the entrypoint reads from the environment, given to the test as a Layer.
 const farm = { FARM_URL: "https://farm.example.test", FARM_USER: "agent", FARM_PASSWORD: "secret" };
 
-// `Testing.layer` gives the test an `HttpClient` of its own, which reaches the routes. The
-// fake farm is another `HttpClient`, provided to `printFarm` alone.
+// The fake farm goes to `printFarm` alone, so the test's own requests still reach the routes.
 const servedWith = (environment: Record<string, string>) =>
   Testing.layer(routes).pipe(
     Layer.provide(printFarm.pipe(Layer.provide(fakeFarm))),
@@ -57,7 +56,7 @@ const Listed = Schema.Struct({
 });
 
 describe("the tools, over MCP", () => {
-  it.effect("lists every tool with the hints its contract states", () =>
+  it.effect("lists every tool with its title and hints as sent", () =>
     Effect.gen(function* () {
       // A raw request, for what no typed client shows: here, the listing itself.
       const response = yield* HttpClient.execute(ActionMcp.request("tools/list"));

package/examples/notes-service/README.md

@@ -5,11 +5,6 @@ implementation, served as a JSON API and as MCP tools, with a CLI and a browser
 same binding. Notes belong to the signed-in user; reading needs the `notes:read` scope and
 writing `notes:write`.
 
-Start here if you are building a service. The other examples follow the same layout. Then read
-[Action.md](../../docs/Action.md) and the page of each surface you serve, which
-[docs/README.md](../../docs/README.md) routes, one page per tool call. An error's message is
-quoted in a `docs/*-failures.md`.
-
 ## Run it
 
 From the repository root, after `vp install` (from an installed package, see
@@ -44,11 +39,10 @@ codex mcp add notes --url http://127.0.0.1:3000/mcp --bearer-token-env-var NOTES
 Cloudflare Workers ([ActionMcp.md](../../docs/ActionMcp.md#serve-tools-over-http)).
 
 The server reads `HOST` (default `127.0.0.1`), `PORT` (default 3000) and `PUBLIC_URL`, the
-address it tells OAuth clients it is at; the CLI reads `NOTES_URL` and `NOTES_TOKEN`. Change the port and set all three to match.
-Every command asks for `NOTES_TOKEN`, the public `get-status` included: without it a command
-prints one message on stderr saying to set it, and exits 1. `--help` needs none.
-
-The tokens are fixed names and the store is memory: replace both before deploying anything.
+address it tells OAuth clients it is at; the CLI reads `NOTES_URL` and `NOTES_TOKEN`. Change the
+port and set `PORT`, `PUBLIC_URL` and `NOTES_URL` to match. Every command asks for
+`NOTES_TOKEN`, the public `get-status` included: without it a command prints one message on
+stderr saying to set it, and exits 1. `--help` needs none.
 
 ## Retry a creation
 
@@ -62,24 +56,8 @@ command:
 echo "First draft" | node --import tsx examples/notes-service/src/cli.ts create-note --request-id plan-1 --title Plan
 ```
 
-The key belongs to the signed-in caller and the `createNote` operation. Another caller can use
-it independently. The same caller repeating the key and content gets the original result;
-different content fails with `RequestConflict`. A new key creates a new note, even when its
-content is identical. Every attempt still runs authorization.
-
-The replay result is a snapshot of the creation. Updating or deleting the note leaves that
-snapshot intact: replay neither changes the note back nor recreates it. `importNotes` has no
-request key; each import creates new notes. Calls without a key are not idempotent, so the
-creation tool does not advertise `idempotentHint: true`.
-
-[src/notes/store.ts](src/notes/store.ts) owns creation and replay recording.
-
-**DEMO ONLY:** notes and replay records live in this process's memory, without eviction. They
-do not survive a restart or coordinate separate server instances. A deployed store must commit
-the mutation and replay record in one transaction, enforce uniqueness of caller, operation and
-key, and define a retention window. An expired key no longer protects a retry. External side
-effects need the upstream system's cooperation: a local record cannot make a separate network
-call atomic. The library supplies neither replay storage nor automatic retries.
+What a key promises, per caller, for changed content and after the note changes, is what
+[test/notes/idempotency.test.ts](test/notes/idempotency.test.ts) asserts.
 
 ## Layout
 
@@ -113,19 +91,6 @@ test/
 └── commands.test.ts   the commands and their connection, against the same routes in memory
 ```
 
-- **A folder per domain, not per mechanism.** Everything about notes is in `notes/`; there is no
-  `contracts/` or `handlers/` folder.
-- **The PascalCase file is the contract.** `Notes.ts`, `Identity.ts`, `Status.ts` and `Api.ts`
-  import no server code, so a browser or a CLI imports them. The lowercase files beside them run
-  on the server, each named for its role, never the domain: `notes.ts` beside `Notes.ts` is one
-  file on a disk that ignores case (TS1149).
-- **One entrypoint per way of running it.** Each chooses its own implementations: `server.ts`
-  picks the store and the HTTP server, `worker.ts` the routes for a serverless host, `stdio.ts`
-  names the local user, a test provides its own store. Nothing below an entrypoint knows which
-  it got.
-- **In a monorepo** the contract files and `Api.ts` are the package the server, the CLI and the
-  website all depend on; the lowercase files and `routes.ts` are the server.
-
 ## Where to look
 
 | To see                                                        | Read                             |
@@ -146,8 +111,9 @@ test/
 | A bulk import as one action, its command reading a file       | `src/notes/`, `src/commands.ts`  |
 | The CLI's connection, read from config when a command runs    | `src/commands.ts`                |
 | A missing token as one message, not a `ConfigError` report    | `src/commands.ts`                |
-| A promise client handling each declared error by its tag      | `src/browser.ts`                 |
-| Testing handlers and authorization with no transport          | `test/notes/notes.test.ts`       |
+| A promise client handling a declared error by its tag         | `src/browser.ts`                 |
+| Testing handlers and authorization with no transport          | `test/notes/in-process.test.ts`  |
+| Testing a revision race, two fibers taking turns              | `test/notes/notes.test.ts`       |
 | Testing routes, tools and refusals in memory                  | `test/routes.test.ts`            |
 | Testing commands against the routes in memory                 | `test/commands.test.ts`          |
 | Testing `--help` and the connection with config as a Layer    | `test/commands.test.ts`          |

package/examples/notes-service/src/cli.ts

@@ -6,9 +6,6 @@ import { commands } from "./commands.js";
 
 // Entrypoint: `node --import tsx examples/notes-service/src/cli.ts list-notes`.
 // The commands of commands.ts, which read where the server is and the token when one runs.
-
-// A result is printed on stdout. A failure goes to stderr, under an `ERROR` heading, as the JSON
-// HTTP sends, such as `{"_tag":"NoteNotFound","id":"9"}`, and the command exits 1.
 Command.run(commands, { version: "1.0.0" }).pipe(
   Effect.provide([NodeHttpClient.layerUndici, NodeServices.layer]),
   ActionCli.logToStderr,