@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

package/examples/kitchen-sink/src/browser.ts

@@ -25,9 +25,8 @@ export const protocol = (url: string) =>
     Layer.provide([RpcSerialization.layerJson, Socket.layerWebSocketConstructorGlobal]),
   );
 
-// `open("wss://tracker.example.com/rpc")`: one run on a socket of its own. The socket belongs
-// to the Layer providing the protocol: it opens when that Layer is built, and closes when this
-// `Effect.provide` ends. `Effect.scoped` only holds the client. A page that stays connected
-// builds the Layer once, such as in a `ManagedRuntime`, and runs its programs in it.
+// `open("wss://tracker.example.com/rpc")`: one run on a socket of its own, closed when it ends.
+// A page that stays connected builds the protocol's Layer once, such as in a `ManagedRuntime`,
+// and runs its programs in it.
 export const open = (url: string) =>
   Effect.runPromise(board.pipe(Effect.scoped, Effect.provide(protocol(url))));

package/examples/kitchen-sink/src/cli.ts

@@ -15,8 +15,10 @@ const tracker = ActionCli.remote(Http, {
   // Each command's options, keyed by its action's name and typed by that action.
   commands: {
     // `tracker list-issues -n 5 -s open`: short flags, and text instead of JSON (`--json` gives
-    // the JSON back).
+    // the JSON back). Its help says so: the action's description, which HTTP and MCP keep, says
+    // what the JSON holds.
     listIssues: {
+      description: "List your workspace's issues, newest first, one line each: id, status, title.",
       aliases: { limit: "n", status: "s" },
       render: ({ issues }) =>
         issues.map(({ id, status, title }) => `${id}  ${status}  ${title}`).join("\n"),
@@ -42,10 +44,9 @@ const tracker = ActionCli.remote(Http, {
         `${attachment.name}: ${image.mimeType}, ${image.data.byteLength} bytes`,
     },
   },
-  // The connection, read from `Config` when a command runs, so `--help` needs none of it. It is
-  // these commands' client, so it reaches their requests and no others. The token and the
-  // workspace are optional: `tracker get-status` is public and needs neither, and any other
-  // command without them gets the server's 401.
+  // The connection. The token and the workspace are optional: `tracker get-status` is public
+  // and needs neither, and any other command without a token gets the server's 401, and without
+  // a workspace its 403.
   client: Effect.gen(function* () {
     const baseUrl = yield* Config.String("TRACKER_URL").pipe(
       Config.withDefault("http://127.0.0.1:3000"),
@@ -74,8 +75,6 @@ const tracker = ActionCli.remote(Http, {
   }),
 });
 
-// A result is printed on stdout. A failure goes to stderr, under an `ERROR` heading, as the JSON
-// HTTP sends, such as `{"_tag":"IssueNotFound","id":"ACME-9"}`, and the command exits 1.
 Command.run(tracker, { version: "1.0.0" }).pipe(
   Effect.provide([NodeHttpClient.layerUndici, NodeServices.layer]),
   ActionCli.logToStderr,

package/examples/kitchen-sink/src/config.ts

@@ -14,5 +14,7 @@ export const publicUrl = Config.String("PUBLIC_URL").pipe(
  */
 export const allowedOrigins = Config.all([
   publicUrl,
+  // DEMO ONLY: the default is the MCP Inspector's local origin. A page of any origin listed
+  // passes the request policy and CORS, so a deployment names its own client's.
   Config.String("MCP_ORIGIN").pipe(Config.withDefault("http://localhost:6274")),
 ]).pipe(Config.map(([url, mcp]) => [new URL(url).origin, mcp]));

package/examples/kitchen-sink/src/identity/Identity.ts

@@ -22,8 +22,8 @@ export class CurrentMember extends Context.Service<CurrentMember, Member>()(
   "tracker/CurrentMember",
 ) {}
 
-// What a verifier may fail with besides a refusal. It is not the caller's fault, so it is no
-// 401: signing in again cannot help. Every protected route declares it, so clients decode it.
+// What a verifier may fail with besides a refusal: the issuer it checks tokens with is down.
+// It is not the caller's fault, so it is no 401: signing in again cannot help.
 export class IssuerUnavailable extends Schema.TaggedError<IssuerUnavailable>()(
   "IssuerUnavailable",
   { retryAfterSeconds: Schema.Finite },
@@ -31,21 +31,21 @@ export class IssuerUnavailable extends Schema.TaggedError<IssuerUnavailable>()(
 ) {}
 
 // How an API client, the CLI and an MCP client prove they are CurrentMember: a bearer token,
-// the default scheme, and the only one that speaks OAuth (discovery, challenges, step-up).
+// the default scheme.
 export const Login = Authentication.make("tracker.Login", CurrentMember, {
   error: IssuerUnavailable,
 });
 
-// How the web app proves the same identity: the session cookie its sign-in page set. A
-// descriptor names one scheme, so a host accepting two credentials has two descriptors, each
-// named by what accepts it: here `Rpc`, the web app's socket, and the route its pages load an
+// How the web app proves the same identity: the session cookie its sign-in page set. It is
+// named by what accepts it: `Rpc`, the web app's socket, and the route its pages load an
 // attachment's image from.
 export const Session = Authentication.make("tracker.Session", CurrentMember, {
   security: HttpApiSecurity.apiKey({ in: "cookie", key: "tracker_session" }),
 });
 
 // What the API's request quota answers with. It is the bindings' error, not an action's:
-// middleware sends it before any action is chosen, and only HTTP and RPC have that middleware.
+// middleware sends it on any action's route, before its input is decoded. Only HTTP and RPC
+// have that middleware.
 export class QuotaExceeded extends Schema.TaggedError<QuotaExceeded>()(
   "QuotaExceeded",
   { retryAfterSeconds: Schema.Finite },

package/examples/kitchen-sink/src/identity/authenticate.ts

@@ -26,10 +26,8 @@ const inService = Effect.gen(function* () {
   });
 });
 
-// As an OAuth protected resource the provider publishes discovery (RFC 9728) and names it in
-// every challenge, so an MCP client that gets a 401 finds where to sign in, asking for the read
-// scope first. The resource is the public URL, known only to the deployment: an Effect, read
-// when the provider is built.
+// The OAuth protected resource whose discovery the provider publishes, so an MCP client that
+// gets a 401 finds where to sign in, asking for the read scope first.
 const protectedResource = Effect.map(
   publicUrl,
   (url) =>
@@ -74,7 +72,7 @@ export const authenticateBearer = Authentication.layer(
 
 // `Session`'s provider: the same identity from another credential. Its verifier receives what
 // its scheme decodes, the cookie's value. A session belongs to one workspace, so it reads no
-// `Tenant`, and under a scheme other than Bearer there is no discovery and no step-up.
+// `Tenant`.
 export const authenticateSession = Authentication.layer(
   Session,
   Effect.gen(function* () {

package/examples/kitchen-sink/src/identity/authorize.ts

@@ -3,9 +3,10 @@ import * as Action from "@gjermundgaraba/effect-actions/Action";
 import { CurrentMember, scopes } from "./Identity.js";
 
 // The members' rule, read from each contract: a read needs the read scope, anything else the
-// write scope. Every implementation of the members' actions states it, so every surface runs
-// it before the handler: HTTP, MCP, RPC, stdio, the assistant's tools and a test alike.
-// Naming the missing scope turns the 403 into the challenge an OAuth client re-authorizes on.
+// write scope. The implementations of issues and attachments state it, so every surface serving
+// them runs it before the handler: HTTP, MCP, RPC, stdio, the assistant's tools and a test alike.
+// For a bearer token, naming the missing scope turns the 403 into the challenge an OAuth client
+// re-authorizes on.
 export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
   const scope = action.readOnly ? scopes.read : scopes.write;
   const member = yield* CurrentMember;

package/examples/kitchen-sink/src/identity/quota.ts

@@ -43,7 +43,7 @@ const spend = Effect.gen(function* () {
           "RateLimitExceeded",
           ({ retryAfter }) =>
             Effect.fail(new QuotaExceeded({ retryAfterSeconds: Duration.toSeconds(retryAfter) })),
-          // Any other reason is the limiter's store failing: a defect, an empty 500.
+          // Any other reason is the limiter's store failing: a defect, never the caller's.
           Effect.die,
         ),
       );

package/examples/kitchen-sink/src/issues/Issues.ts

@@ -32,13 +32,13 @@ export class RateLimited extends Schema.TaggedError<RateLimited>()(
 ) {}
 
 // A shared error list: what any write to an existing issue may fail with. Each such action
-// spreads this one array into its `error`, here and in attachments/Attachments.ts, so an error
+// names this one array as its `error`, here and in attachments/Attachments.ts, so an error
 // added to the list is declared by all of them.
 export const IssueWriteErrors = [IssueNotFound, RateLimited] as const;
 
 // An option bundle. What the two actions changing an issue share is one constant object spread
 // into `Action.make`, typed as if written inline. `readOnly` and `description` stay on each
-// action: authorization and an MCP client's hints read them.
+// action.
 const change = {
   caller: CurrentMember,
   error: IssueWriteErrors,

package/examples/kitchen-sink/src/issues/assistant.ts

@@ -3,8 +3,8 @@ import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
 import { issues } from "./handlers.js";
 import { CloseIssue, CommentOnIssue, GetIssue, ListIssues } from "./Issues.js";
 
-// The actions a model may call, listed here, where they are served: an action added to the
-// contracts later is no tool until it is listed. Filing issues is left to people.
+// The actions a model may call, listed here, where they are served. Filing issues is left to
+// people.
 const tools = [ListIssues, GetIssue, CommentOnIssue, CloseIssue] as const;
 
 // Some of the issue actions as a model's tools: Effect's native `Toolkit`, in process, with no
@@ -19,5 +19,5 @@ export const { toolkit, layer } = ActionToolkit.make(issues, {
 });
 
 // One turn of the assistant. The caller provides the model, and the member it acts for around
-// the whole turn: approval, `authorize` and the handlers all read that one caller.
+// the whole turn: `authorize` and the handlers read that one caller.
 export const triage = (prompt: string) => LanguageModel.generateText({ prompt, toolkit });

package/examples/kitchen-sink/src/issues/guide.ts

@@ -15,9 +15,8 @@ const guide = `# Triage
 const tools = Action.byName(Issues);
 
 // Effect's own MCP resources and prompts, served beside the actions' tools as an endpoint's
-// `features`. They are native, not actions: no `authorize` runs for them, and they run with
-// the services they were built with, never a request's, so they cannot read the caller.
-// Content that depends on the caller is an action.
+// `features`: native, not actions. This guide is the same for every caller, so it reads no
+// caller, which `features` never receive.
 export const features = Layer.mergeAll(
   McpServer.resource({
     uri: "tracker://guides/triage",

package/examples/kitchen-sink/src/ops.ts

@@ -9,10 +9,8 @@ import { WorkspaceRegistry } from "./workspaces/registry.js";
 
 // Entrypoint: `node --import tsx examples/kitchen-sink/src/ops.ts list-workspaces`.
 // The operators' console: the admin actions run in this process, on the host's own services,
-// with no server and no key. A local command is no bypass: the implementation's `authorize`
-// runs here as on the admin port, and admits the operator this host supplies.
+// with no server and no key.
 
-// Only a host can name the trusted operator: no verifier's return type includes it.
 const operator: TrustedOperator = { id: "console", trusted: true };
 
 const ops = ActionCli.make(admin, {
@@ -28,9 +26,8 @@ const ops = ActionCli.make(admin, {
     resumeWorkspace: { positional: ["workspace"] },
   },
 }).pipe(
-  // Services go on the command: built when an action runs, never for `--help` or a mistyped
-  // flag. Only what these actions are built from. DEMO ONLY: memory, so this console sees its
-  // own process, not the server's data. A real one provides the database Layers the server does.
+  // Only what these actions are built from. DEMO ONLY: memory, so this console sees its own
+  // process, not the server's data. A real one provides the database Layers the server does.
   Command.provide(Layer.merge(WorkspaceRegistry.layerMemory, Grants.layerDemo)),
   Command.provideSync(Operator, operator),
 );

package/examples/kitchen-sink/src/request-policy.ts

@@ -5,12 +5,12 @@ import { allowedOrigins, publicUrl } from "./config.js";
 const loopback = ["localhost", "127.0.0.1"];
 
 // Which Host and Origin a request may carry: not the library's concern, but every request of
-// both ports passes it first. The web app signs in with a cookie, which a browser attaches to
+// both ports passes it first. A Host that is neither loopback nor the public URL's is refused,
+// against DNS rebinding. The web app signs in with a cookie, which a browser attaches to
 // any page's request, so a foreign Origin must be refused before authentication reads it.
 // That is why this is global router middleware (`global: true`): it runs before routing, so
 // before every route's authentication. As a layer's own `middleware` it would run inside the
-// authentication, too late. Whether it also runs before the discovery the Bearer provider
-// publishes, global middleware too, is decided where it is provided: last, in routes.ts.
+// authentication, too late.
 export const requestPolicy = HttpRouter.middleware(
   Effect.gen(function* () {
     const hosts = [...loopback, new URL(yield* publicUrl).hostname];

package/examples/kitchen-sink/src/routes.ts

@@ -32,15 +32,14 @@ const implementations = [status, identity, issues, attachments, assistant];
 
 // JSON routes at `/api/v1/<action>`, in two layers of one binding, each naming its `actions`.
 // The quota requires the caller, and a public route has none, so `getStatus` is served by a
-// layer without it. The middleware runs inside authentication and before the input is decoded.
+// layer without it.
 const api = Layer.mergeAll(
   ActionHttp.layer(Http, implementations, { actions: [GetStatus] }),
   ActionHttp.layer(Http, implementations, { actions: MemberActions, middleware: [HttpQuota] }),
 );
 
-// The same actions as MCP tools at `/mcp`: a mixed endpoint. Listing the tools and calling
-// `getStatus` need no token; any other request answers the 401 an MCP client signs in on, the
-// one opening a session included, since a session may call any tool.
+// The same actions as MCP tools at `/mcp`: a mixed endpoint, serving the public `getStatus`
+// beside the members' tools.
 const mcp = Layer.unwrap(
   Effect.map(allowedOrigins, (origins) =>
     ActionMcp.layerHttp(implementations, {
@@ -85,8 +84,7 @@ const health = HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok"));
 // before them. Two things follow from that order.
 //
 // - `resolveTenant`, in a `Layer.provide` of its own after the authentication, gives the
-//   `Tenant` the Bearer verifier reads per request. In one array with `authenticateBearer` it
-//   would leave `Tenant` owed: an array's members provide to the routes, not to one another.
+//   `Tenant` the Bearer verifier reads per request; tenant.ts says why not in one array.
 // - Global middleware runs in the order it registers, and it registers when its layer is
 //   built. The request policy, provided last, is built first, so it runs before everything:
 //   before CORS, and before the OAuth discovery the Bearer provider registers when it is

package/examples/kitchen-sink/src/seed.ts

@@ -46,7 +46,6 @@ const seed = Effect.gen(function* () {
 
   yield* tracker.commentOnIssue({ id: issue.id, text: "Reproduced on 2.4.1." });
 
-  // No argument: `{}` is a valid input here, so `limit` takes its default and `status` none.
   const { issues } = yield* tracker.listIssues();
 
   yield* Console.log(`Filed ${issue.id} with attachment ${attachment.id}. Issues:`, issues);

package/examples/kitchen-sink/src/server.ts

@@ -7,7 +7,7 @@ import { memory } from "./memory.js";
 import { adminRoutes, builders, publicRoutes, rpc } from "./routes.js";
 
 // Entrypoint: `node --import tsx examples/kitchen-sink/src/server.ts`.
-// The composition root of the server: two listeners over one set of builders and services.
+// The entrypoint of the server: two listeners over one set of builders and services.
 
 // The web app's rpcs over a WebSocket at `/rpc`: Node's HTTP server answers the upgrade. The
 // protocol is this entrypoint's choice, as the ports are. `rpc` leaves it open, so a test
@@ -37,21 +37,20 @@ const server = Layer.unwrap(
       });
 
     return Layer.mergeAll(
-      // Two audiences, two listeners. Each `HttpRouter.serve` builds its routes in a layer
-      // graph of its own, with a router of its own: the public port can only ever reach the
-      // members' routes, and nothing built inside one is shared with the other. The socket
-      // is merged into the public port's graph, so it is a route of that router: the request
-      // policy, global to the router, refuses a foreign Origin's upgrade as it does a request,
-      // and the rpcs spend the quota the routes spend, built once.
+      // Two audiences, two listeners, each with a router of its own: the public port can only
+      // ever reach the members' routes. The socket is merged into the public port's routes, so
+      // it is a route of that router: the request policy, global to the router, refuses a
+      // foreign Origin's upgrade as it does a request, and the rpcs spend the quota the routes
+      // spend, built once.
       HttpRouter.serve(Layer.merge(publicRoutes, socket)).pipe(Layer.provide(listen(publicPort))),
       HttpRouter.serve(adminRoutes).pipe(Layer.provide(listen(adminPort))),
     ).pipe(
-      // Request bodies have no size limit unless the host sets one. This covers every HTTP
-      // route of both ports, the MCP endpoint included.
+      // Request bodies have no size limit unless the host sets one. This covers every route
+      // that reads its body whole, on both ports, the MCP endpoint included.
       Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, limit)),
-      // So what both ports share is provided outside both, once: the builders, then the
-      // services the builders, the verifiers and the quota are built from. A workspace an
-      // operator suspends on one port is thereby refused on the other.
+      // What both ports share is provided outside both: the builders, as routes.ts says, then
+      // the services the verifiers and the quota are built from, so a workspace an operator
+      // suspends on one port is refused on the other.
       Layer.provide(builders),
       Layer.provide(memory),
     );

package/examples/kitchen-sink/src/stdio.ts

@@ -15,7 +15,8 @@ import { WorkspaceRegistry } from "./workspaces/registry.js";
 
 // Entrypoint: an MCP server a local agent starts as a subprocess, such as
 // `claude mcp add tracker -- "$PWD/node_modules/.bin/tsx" "$PWD/examples/kitchen-sink/src/stdio.ts"`
-// from the repository root: mcp-tools' README says why the paths are full.
+// from the repository root. The host starts the process in a directory it chooses, so `tsx`
+// and the file are named by full path.
 // It lists the implementations it serves itself, and imports nothing of the HTTP router. They
 // are those of the `/mcp` endpoint, with its tools and features and the same `authorize`.
 // stdio is a local surface: it takes no `authentication`, since no token arrives.
@@ -29,7 +30,7 @@ ActionMcp.runStdio([status, identity, issues, attachments], {
   // started it, from its own login or configuration.
   Effect.provideService(CurrentMember, members.ada),
   Effect.provide([NodeStdio.layer, stores, limiter, WorkspaceRegistry.layerMemory]),
-  // stdout carries the protocol alone, so logs and failures go to stderr. Applied last.
+  // stdout carries the protocol alone, so logs and failures go to stderr.
   ActionCli.logToStderr,
   NodeRuntime.runMain,
 );

package/examples/kitchen-sink/src/workspaces/tenant.ts

@@ -9,7 +9,9 @@ import { HttpRouter, HttpServerRequest } from "effect/http";
 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 (see routes.ts).
+// 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"])),

package/examples/kitchen-sink/test/admin/admin.test.ts

@@ -28,7 +28,6 @@ describe("the operators", () => {
 
       expect((yield* support.listWorkspaces()).workspaces).toHaveLength(2);
 
-      // A key cannot step up, so the refusal names no scope: a plain 403.
       const refused = yield* Effect.flip(support.suspendWorkspace({ workspace: "acme" }));
 
       expect(refused).toBeInstanceOf(Action.Forbidden);

package/examples/kitchen-sink/test/assistant/assistant.test.ts

@@ -311,7 +311,7 @@ describe("the assistant, behind a route", () => {
     ),
   );
 
-  it.effect("runs what its member approves in each turn of the demo model", () =>
+  it.effect("runs what its member approves in a later turn of the demo model", () =>
     Effect.gen(function* () {
       const ada = yield* asAda;
 

package/examples/kitchen-sink/test/attachments/attachments.test.ts

@@ -39,7 +39,7 @@ const attached = Effect.gen(function* () {
 });
 
 describe("attachments, over HTTP and MCP", () => {
-  it.effect("sends an image as JSON over HTTP, and as an image block from the tool", () =>
+  it.effect("decodes an image over HTTP, and reads it as an image block from the tool", () =>
     Effect.gen(function* () {
       const attachment = yield* attached;
       const http = yield* ActionHttp.client(Http, as("ada", "acme"));
@@ -128,7 +128,6 @@ describe("attachments, over HTTP and MCP", () => {
 
       expect(mine.status).toBe(200);
       expect(Buffer.from(yield* mine.arrayBuffer).equals(screenshot)).toBe(true);
-      // The route states its own caching; everything else authentication covers is `no-store`.
       expect(mine.headers["cache-control"]).toBe("private, max-age=31536000, immutable");
       // An uploaded image opened by its URL is a document on this origin: it gets no scripts.
       expect([

package/examples/kitchen-sink/test/identity/identity.test.ts

@@ -68,7 +68,6 @@ describe("a bearer token", () => {
 
         const refused = yield* Effect.flip(reader.createIssue({ title: "Crash", body: "" }));
 
-        // `toEqual` compares an error's own fields, here `scopes`; never its `message`.
         expect(refused).toEqual(new Action.Forbidden({ scopes: ["issues:write"] }));
         expect(refused.message).toBe("Requires issues:write.");
 

package/examples/kitchen-sink/test/issues/issues.test.ts

@@ -47,7 +47,6 @@ describe("issues, in process", () => {
       );
       yield* client.closeIssue({ id: "ACME-2" }).pipe(as("ada"));
 
-      // No argument is the input `{}`: `status` is absent and `limit` its default.
       const all = yield* client.listIssues().pipe(as("ada"));
       const closed = yield* client.listIssues({ status: "closed", limit: 20 }).pipe(as("ada"));
       const newest = yield* client.listIssues({ limit: 1 }).pipe(as("ada"));
@@ -69,7 +68,6 @@ describe("issues, in process", () => {
 
       const refused = yield* Effect.flip(create.pipe(as("linus")));
 
-      // `toEqual` compares an error's own fields, here `scopes`; never its `message`.
       expect(refused).toEqual(new Action.Forbidden({ scopes: ["issues:write"] }));
       expect(refused.message).toBe("Requires issues:write.");
     }).pipe(Effect.provide(services)),

package/examples/kitchen-sink/test/request-policy.test.ts

@@ -103,7 +103,7 @@ describe("the request policy", () => {
     expect(preflight.headers.get("access-control-allow-headers")).toContain("Mcp-Session-Id");
   });
 
-  it("covers the admin port too, whatever key a request carries", async () => {
+  it("covers the admin port too, a valid key included", async () => {
     const key = { "x-operator-key": "ops-key" };
     const here = await adminWeb.handler(post("http://localhost/admin/listWorkspaces", key));
 

package/examples/kitchen-sink/test/routes.test.ts

@@ -10,9 +10,9 @@ import { AdminHttp, Http } from "../src/Api.js";
 import { memory } from "../src/memory.js";
 import { adminRoutes, builders, publicRoutes } from "../src/routes.js";
 
-// The host's surfaces, as routes.ts builds them, answering in memory: no port is opened. Two
-// ports are two `Testing.layer`s, each a layer graph of its own, as two servers are. What they
-// share is provided above both, as server.ts does: the builders, then the services.
+// The host's surfaces, as routes.ts builds them, answering in memory: no port is opened. Each
+// port is a `Testing.layer` of its own, and what they share is provided above both, as
+// server.ts does.
 const shared = builders.pipe(Layer.provideMerge(memory));
 
 const onPublicPort = Effect.provide(Testing.layer(publicRoutes));

package/examples/live-rpc/README.md

@@ -2,15 +2,9 @@
 
 A chat served as Effect RPC over a WebSocket: one connection per page, many calls on it.
 Members post, read and delete messages in the rooms they belong to; anyone may list the rooms.
-Each message on the socket carries its own token and names its room, so a socket has no
-identity of its own. A message naming no room is about the default one, `lobby`.
-
-Start here if a client keeps a connection open and calls often, or if the application already
-speaks Effect RPC. For a JSON API or MCP tools, start from [notes-service](../notes-service/).
+Each message on the socket carries its own token and names its room.
 To serve these same actions as JSON too, see
-[ActionRpc.md](../../docs/ActionRpc.md#serve-the-rpcs): kitchen-sink's `src/routes.ts` and
-`src/server.ts` merge both.
-Actions are unary, so nothing streams: the page reads again, passing the last id it holds.
+[ActionRpc.md](../../docs/ActionRpc.md#serve-the-rpcs).
 
 ## Run it
 
@@ -24,26 +18,9 @@ node --import tsx examples/live-rpc/src/client.ts     # CHAT_URL to change, ws:/
 vp test examples/live-rpc
 ```
 
-`client.ts` runs the browser's client from Node: two members on one socket, then each failure
-a page handles. `browser.ts` is imported by a page, not run: `openChat` for a page that is an
-Effect program, `connect(url)` for one that calls with promises. The tokens are fixed names (`ada`,
-`grace`) and the store is memory: replace both before deploying anything.
-
-## When you copy this
-
-Four choices here show a feature. Decide each for your application before keeping it:
-
-- **`listRooms` is public** to show a public rpc beside protected ones. It tells a signed-out
-  caller every room's name and how many messages it holds; a room appears once someone posts.
-- **A message naming no room is about `lobby`**, to show a default in request context. Yours may
-  refuse instead.
-- **The room is a header, not an input**, because `authorize` sees the action and not its input:
-  the membership rule reads the room from request context. With the room in the input, the
-  check belongs in the store, never in a helper each handler must remember to call: the store's
-  method takes the member and refuses, as `MessageStore.remove` in `src/chat/store.ts` takes the
-  author and refuses with `NotAuthor`.
-- **`browser.ts` takes a message already gone as removed**, `MessageNotFound` included, since
-  that is what the page asked for. Yours may tell the user it was not there.
+`client.ts` runs the browser's client from Node: two members on one socket, then each declared
+error and refusal a page handles. `browser.ts` is imported by a page, not run: `openChat` for a
+page that is an Effect program; `page.ts` wraps it as `connect(url)` for one that calls with promises.
 
 ## Layout
 
@@ -62,7 +39,8 @@ src/
 ├── Rpc.ts             the RPC binding of every action
 ├── routes.ts          the rpcs, authenticated and with their middleware, not yet on a protocol
 ├── server.ts          entrypoint: the rpcs over a WebSocket at /rpc, its messages bounded
-├── browser.ts         client module: the connection and the chat, as Effects and as promises
+├── browser.ts         client module: the connection and the chat, as one Effect program
+├── page.ts            the same chat as promises, for a page that is not one
 └── client.ts          entrypoint: that client, run from Node
 test/
 ├── chat/              in process, with Action.client
@@ -71,24 +49,6 @@ test/
 └── server.test.ts     the socket itself: a listening port, connect(url), the bound on a message
 ```
 
-- **The PascalCase files are what a page imports.** `Chat.ts`, `Identity.ts` and `Rpc.ts` import
-  no server code. `browser.ts` imports them, the library's `ActionRpc`, and `effect`,
-  `effect/rpc` and `effect/socket`, nothing else, so it bundles for a browser.
-- **A request-time service is never a startup service.** `CurrentMember` comes from
-  authentication and `CurrentRoom` from middleware, both per message. Neither has a Layer, and
-  no entrypoint provides one: a value provided at startup would serve every caller as one
-  member in one room.
-- **The entrypoint chooses the protocol.** `routes.ts` exports the rpcs without one. `server.ts`
-  gives them a WebSocket, its only route. `browser.ts` leaves the WebSocket constructor to its
-  host: a page provides the browser's, `client.ts` provides Node's.
-- **The socket belongs to the Layer providing it.** `connection(url)` opens it when it is built
-  and closes it when it is released: provide it once around the page's program, or keep it in
-  a `ManagedRuntime`, as `connect(url)` does. The scope `openChat` needs holds only the client.
-- **One test file opens a port.** `Testing.layer` answers HTTP requests and cannot upgrade a
-  WebSocket, so `routes.test.ts` and `browser.test.ts` give the same rpcs Effect's HTTP protocol,
-  in memory. `server.test.ts` covers what that leaves out: it serves them over a WebSocket on a
-  port the system picks, calls with `connect(url)`, and sends a message over the server's bound.
-
 ## Where to look
 
 | To see                                                                 | Read                                            |
@@ -96,13 +56,12 @@ test/
 | An RPC binding naming its authentication descriptor                    | `src/Rpc.ts`                                    |
 | The rpcs on Effect's `RpcServer`, before a protocol is chosen          | `src/routes.ts`                                 |
 | Serving them over a WebSocket, speaking JSON                           | `src/server.ts`                                 |
-| The same rpcs over Effect's HTTP protocol, for a test                  | `test/routes.test.ts`                           |
 | A verifier that runs for every message, not once per connection        | `src/identity/verifier.ts`                      |
 | Native `RpcMiddleware` providing a per-request service, with a default | `src/chat/room.ts`                              |
 | Handlers reading that service, and the rule that reads it              | `src/chat/handlers.ts`, `src/chat/authorize.ts` |
 | A public rpc beside protected ones                                     | `src/chat/Chat.ts`                              |
 | A socket client sending its token and room on each message             | `src/browser.ts`                                |
-| Who owns the socket, and how a promise page keeps it open              | `src/browser.ts`                                |
+| Who owns the socket, and how a promise page keeps it open              | `src/browser.ts`, `src/page.ts`                 |
 | A declared error and the built-in refusals handled by tag              | `src/browser.ts`                                |
 | Running that client from Node, two callers on one socket               | `src/client.ts`                                 |
 | Testing handlers and authorization with no transport                   | `test/chat/chat.test.ts`                        |