@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

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

@@ -12,18 +12,14 @@ class MissingToken extends Schema.TaggedError<MissingToken>()("MissingToken", {
 }) {}
 
 // The binding's typed client, connected to where the server is and as who is calling, both read
-// from config. It is an Effect, not a client: every command here, the derived ones and your own,
-// runs it when it runs, so `--help` and a mistyped flag read nothing. It reaches these commands'
-// requests and no others.
+// from config. Every command here, the derived ones and your own, calls through this one.
 const api = Effect.gen(function* () {
   const baseUrl = yield* Config.String("NOTES_URL").pipe(
     Config.withDefault("http://127.0.0.1:3000"),
   );
 
-  // Required, since every command but `get-status` is refused without one. Left as it is, a
-  // missing token prints as `ConfigError: …`; mapped, it prints the message, which says what to
-  // do. A CLI whose public commands must answer signed out reads the token with `Config.option`
-  // instead and adds the header when it is there.
+  // Required, since every command but `get-status` is refused without one, and mapped so that a
+  // missing one prints what to do.
   const token = yield* Config.Redacted("NOTES_TOKEN").pipe(
     Effect.mapError(
       () =>
@@ -68,15 +64,11 @@ const exportNotes = Command.make(
 
       yield* Console.log(`Wrote ${whole.length} notes to ${file}`);
     }).pipe(
-      // Context of your own for a failure goes to stderr before it, on a line of its own. A
-      // `UserError` wrapped around the failure instead would put its JSON mid-sentence. The
-      // line prints for every failure of the command, a file that cannot be written included,
-      // so it says only what is true of them all.
+      // Context of your own for a failure, on stderr before it. The line prints for every
+      // failure of the command, a file that cannot be written included, so it says only what is
+      // true of them all.
       Effect.tapError(() => Console.error(`The export to ${file} did not finish.`)),
-      // Once, around the whole command: it then fails as a derived command does, an action's
-      // error printed as its JSON on stderr and any other, a file that cannot be written for
-      // one, named. A failure left as it is would be reported as a crash, with an `ERROR (#n)`
-      // line and a stack trace.
+      // So the export fails as a derived command does.
       ActionCli.toUserError(Http),
     ),
 ).pipe(Command.withDescription("Write every note to a file, as Markdown."));
@@ -135,7 +127,5 @@ export const commands = ActionCli.remote(Http, {
     // `notes update-note <id> --revision 1 < draft.md`: an argument, a flag and stdin together.
     updateNote: { positional: ["id"], stdin: "body" },
   },
-  // `Command.withSubcommands` on the result would replace the derived commands, so your own
-  // go here.
   subcommands: [exportNotes, importNotes],
 });

package/examples/notes-service/src/identity/authorize.ts

@@ -3,11 +3,8 @@ import * as Action from "@gjermundgaraba/effect-actions/Action";
 import { CurrentUser, scopes } from "./Identity.js";
 
 // The one rule, read from each contract: a read needs the read scope, anything else the write
-// scope. Every implementation of protected actions states it, so HTTP, MCP and stdio all run it
-// before the handler. Naming the missing scope lets an OAuth client ask for it and retry: it is
-// answered a challenge, which only a server publishing discovery (verifier.ts) can follow up.
-// Where tokens are fixed, such as API keys, name no scope: the refusal is then a plain one.
-// So `scopes` below goes when `protectedResource` in verifier.ts does: copy both or neither.
+// scope. Naming the missing scope lets an OAuth client ask for it and retry (`Forbidden`):
+// `scopes` below goes with `protectedResource` in verifier.ts, copy both or neither.
 // This named span measures authorization within the action's span, including a refusal.
 export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
   const scope = action.readOnly ? scopes.read : scopes.write;

package/examples/notes-service/src/identity/verifier.ts

@@ -17,10 +17,9 @@ const verify = (token: Redacted.Redacted<string>) => {
     : Effect.fail(new Action.Unauthenticated({ message: "Unknown demo token." }));
 };
 
-// Server only: `Login`'s provider. Every layer serving a protected action requires it and
-// authenticates before it decodes the input. As an OAuth protected resource it also publishes
-// discovery, so an MCP client that gets a 401 finds where to sign in, asking for read first.
-// The resource is the server's public URL, known only at startup, so it is read from config.
+// Server only: `Login`'s provider. As an OAuth protected resource it also publishes discovery,
+// so an MCP client that gets a 401 finds where to sign in, asking for read first. The resource
+// 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")),

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

@@ -81,6 +81,7 @@ export const CreateNote = Action.make("createNote", {
   error: RequestConflict,
   readOnly: false,
   caller: CurrentUser,
+  // No `idempotentHint: true`: a call without a `requestId` creates a note each time.
   mcp: { destructiveHint: false },
 });
 
@@ -99,8 +100,7 @@ export const UpdateNote = Action.make("updateNote", {
   readOnly: false,
   caller: CurrentUser,
   // No `destructiveHint`: an update replaces the body, so it is destructive, MCP's default for
-  // a write, as is any update of what is stored, a flag such as "read" included.
-  // `createNote` and `importNotes`, which only add, say `false`.
+  // a write. `createNote` and `importNotes`, which only add, say `false`.
 });
 
 export const DeleteNote = Action.make("deleteNote", {
@@ -111,10 +111,6 @@ export const DeleteNote = Action.make("deleteNote", {
   caller: CurrentUser,
 });
 
-// Work every surface should offer is an action, a bulk import included: the HTTP API, the MCP
-// tools and the CLI then all have it, and the whole list is decoded, so checked, before the
-// handler writes any of it. A command of your own only reads the file and calls this once
-// (commands.ts). `importNotes` only adds notes, so `destructiveHint` is `false`.
 // Imports share note content with `createNote`, but exclude request keys because bulk creation
 // does not deduplicate.
 export const ImportNotes = Action.make("importNotes", {

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

@@ -31,7 +31,11 @@ export class NoteStore extends Context.Service<
     readonly count: Effect.Effect<number>;
   }
 >()("notes-service/NoteStore") {
-  // DEMO ONLY: notes and replay records live in this process's memory, without eviction.
+  // DEMO ONLY: notes and replay records live in this process's memory, without eviction, so
+  // they neither survive a restart nor coordinate separate server instances. A deployed store
+  // commits the mutation and its replay record in one transaction, enforces uniqueness of
+  // caller, operation and key, and defines a retention window: an expired key no longer
+  // protects a retry. A separate network call is not made atomic by a local record.
   static readonly layerMemory = Layer.sync(NoteStore, () => {
     // One map per owner: a note is only ever looked up among its owner's, whatever id is asked.
     const notes = new Map<string, Map<string, Note>>();

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

@@ -13,8 +13,7 @@ import { status } from "./status/handlers.js";
 // Every domain's implementation, once. Each surface below takes the same list.
 const implementations = [status, notes, identity];
 
-// JSON routes at `/api/<action>`, the binding's. A protected route authenticates before it
-// reads its body; `getStatus` answers anyone.
+// JSON routes at `/api/<action>`, the binding's; `getStatus` answers anyone.
 const api = ActionHttp.layer(Http, implementations);
 
 // The host's own routes sit beside the actions' on the same router.
@@ -30,12 +29,11 @@ const openApi = HttpRouter.add(
 );
 
 // What the host serves: the JSON routes, the same actions as MCP tools at `/mcp`, and the host's
-// own routes. Listing the tools and calling `getStatus` need no token, because `getStatus` is
-// public: an endpoint of protected tools alone asks a token for the listing too. Any other call
-// answers 401 with where to sign in, and so does a client of an MCP revision with sessions when
-// it opens one, since a session may call any tool. It still requires `NoteStore`: the entrypoint
-// chooses which one, and a test chooses its own. The entrypoint also chooses how the MCP
-// endpoint runs: one server for every request, or one per request.
+// own routes. The MCP endpoint serves the public `getStatus` beside the protected tools, so a
+// signed-out 2026-07-28 client may list the tools and call `getStatus`; what else needs a token
+// is on `ActionMcp.LayerHttpOptions.authentication`. It still requires `NoteStore`: the
+// entrypoint chooses which one, and a test chooses its own. The entrypoint also chooses how the
+// MCP endpoint runs: one server for every request, or one per request.
 const serving = (requestScoped: boolean) =>
   Layer.mergeAll(
     api,

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

@@ -6,8 +6,7 @@ import { NoteStore } from "./notes/store.js";
 import { routes } from "./routes.js";
 
 // Entrypoint: `node --import tsx examples/notes-service/src/server.ts`.
-// This is the composition root of the server. It chooses the store, reads the configuration
-// and starts Node's HTTP server; nothing below it knows which of those it got.
+// It chooses the store, reads the configuration and starts Node's HTTP server.
 const server = Layer.unwrap(
   Effect.gen(function* () {
     // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
@@ -16,8 +15,10 @@ const server = Layer.unwrap(
 
     return HttpRouter.serve(routes).pipe(
       Layer.provide(NodeHttpServer.layer(createServer, { host, port })),
-      // Request bodies have no size limit unless the host sets one. This covers every route.
+      // Request bodies have no size limit unless the host sets one. This covers every route that
+      // reads its body whole.
       Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))),
+      // DEMO ONLY: notes live in this process's memory; a deployment provides a store that lasts.
       Layer.provide(NoteStore.layerMemory),
     );
   }),

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

@@ -11,11 +11,12 @@ import { status } from "./status/handlers.js";
 
 // Entrypoint: an MCP server a local agent starts as a subprocess, such as
 // `claude mcp add notes -- "$PWD/node_modules/.bin/tsx" "$PWD/examples/notes-service/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.
 // The same implementations as the HTTP server, and the same `authorize`. No token arrives
 // over stdio, so this host names the caller itself. It is a process of its own with services
-// of its own: this in-memory store holds its notes, not the running server's. To share them,
-// both provide a store they both reach, such as a database.
+// of its own. DEMO ONLY: this in-memory store holds its notes, not the running server's. To
+// share them, both provide a store they both reach, such as a database.
 ActionMcp.runStdio([status, notes, identity], { name: "notes-service", version: "1.0.0" }).pipe(
   // DEMO ONLY: a real host reads who started it, from its own login or configuration.
   Effect.provideService(CurrentUser, users.ada),

package/examples/notes-service/test/commands.test.ts

@@ -120,7 +120,7 @@ describe("the commands", () => {
     }).pipe(Effect.provide(served), Effect.provide(NodeServices.layer)),
   );
 
-  it.effect("import a file `export` wrote with one call, all its notes or none", () =>
+  it.effect("import a file `export` wrote, all its notes or none", () =>
     Effect.gen(function* () {
       const files = yield* FileSystem.FileSystem;
       const directory = yield* files.makeTempDirectoryScoped();

package/examples/notes-service/test/notes/as.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import { CurrentUser } from "../../src/identity/Identity.js";
+import { users } from "../../src/identity/users.js";
+
+// The caller of one call, as a server provides it per request.
+export const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);

package/examples/notes-service/test/notes/idempotency.test.ts

@@ -1,13 +1,10 @@
 import { expect, it } from "@effect/vitest";
 import { Arbitrary, Array, Effect, References, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
-import { CurrentUser } from "../../src/identity/Identity.js";
-import { users } from "../../src/identity/users.js";
 import { notes } from "../../src/notes/handlers.js";
 import { CreateNote, RequestConflict } from "../../src/notes/Notes.js";
 import { NoteStore } from "../../src/notes/store.js";
-
-const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
+import { as } from "./as.js";
 
 it.effect("creates a new note on every call without a request key", () =>
   Effect.gen(function* () {

package/examples/notes-service/test/notes/in-process.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentUser } from "../../src/identity/Identity.js";
+import { users } from "../../src/identity/users.js";
+import { notes } from "../../src/notes/handlers.js";
+import { NoteNotFound } from "../../src/notes/Notes.js";
+import { NoteStore } from "../../src/notes/store.js";
+
+// What the implementation does, with no transport: `Action.client` runs the same decoding,
+// `authorize` and handler a server runs. The caller is provided around each call, as a server
+// provides it per request.
+const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
+
+describe("notes, in process", () => {
+  it.effect("keeps each user's notes their own", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+
+      expect(yield* client.listNotes().pipe(as("ada"))).toEqual({
+        notes: [{ id: note.id, title: "Plan" }],
+      });
+      expect(yield* client.listNotes().pipe(as("grace"))).toEqual({ notes: [] });
+
+      const missing = new NoteNotFound({ id: note.id });
+      const update = { id: note.id, body: "Mine now", revision: note.revision };
+
+      expect(yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("grace")))).toEqual(
+        missing,
+      );
+      expect(yield* Effect.flip(client.updateNote(update).pipe(as("grace")))).toEqual(missing);
+      expect(yield* Effect.flip(client.deleteNote({ id: note.id }).pipe(as("grace")))).toEqual(
+        missing,
+      );
+      expect(yield* client.getNote({ id: note.id }).pipe(as("ada"))).toEqual(note);
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+
+  it.effect("refuses a write from a caller holding the read scope alone", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const create = client.createNote({ title: "Plan", body: "Draft" });
+      const refusal = yield* Effect.flip(create.pipe(as("reader")));
+
+      expect(refusal).toBeInstanceOf(Action.Forbidden);
+      expect(refusal.message).toBe("Requires notes:write.");
+    }).pipe(Effect.provide(NoteStore.layerMemory)),
+  );
+});

package/examples/notes-service/test/notes/notes.test.ts

@@ -1,41 +1,15 @@
 import { describe, expect, it } from "@effect/vitest";
 import { Array, Effect, Exit, References } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
-import { CurrentUser } from "../../src/identity/Identity.js";
-import { users } from "../../src/identity/users.js";
 import { notes } from "../../src/notes/handlers.js";
 import { NoteChanged, NoteNotFound } from "../../src/notes/Notes.js";
 import { NoteStore } from "../../src/notes/store.js";
+import { as } from "./as.js";
 
-// What the implementation does, with no transport: `Action.client` runs the same decoding,
-// `authorize` and handler a server runs. Each call names its caller, as a request would.
-const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
+// The store's rules, with no transport, as in-process.test.ts calls the implementation: a
+// revision check, and a race two fibers run under every interleaving.
 
 describe("notes, in process", () => {
-  it.effect("keeps each user's notes their own", () =>
-    Effect.gen(function* () {
-      const client = yield* Action.client(notes);
-      const note = yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
-
-      expect(yield* client.listNotes().pipe(as("ada"))).toEqual({
-        notes: [{ id: note.id, title: "Plan" }],
-      });
-      expect(yield* client.listNotes().pipe(as("grace"))).toEqual({ notes: [] });
-
-      const missing = new NoteNotFound({ id: note.id });
-      const update = { id: note.id, body: "Mine now", revision: note.revision };
-
-      expect(yield* Effect.flip(client.getNote({ id: note.id }).pipe(as("grace")))).toEqual(
-        missing,
-      );
-      expect(yield* Effect.flip(client.updateNote(update).pipe(as("grace")))).toEqual(missing);
-      expect(yield* Effect.flip(client.deleteNote({ id: note.id }).pipe(as("grace")))).toEqual(
-        missing,
-      );
-      expect(yield* client.getNote({ id: note.id }).pipe(as("ada"))).toEqual(note);
-    }).pipe(Effect.provide(NoteStore.layerMemory)),
-  );
-
   it.effect("deletes a note for its owner", () =>
     Effect.gen(function* () {
       const client = yield* Action.client(notes);
@@ -87,17 +61,4 @@ describe("notes, in process", () => {
       expect(succeeded).toEqual(Array.range(3, 60).map(() => 1));
     }).pipe(Effect.provide(NoteStore.layerMemory)),
   );
-
-  it.effect("refuses a write from a caller holding the read scope alone", () =>
-    Effect.gen(function* () {
-      const client = yield* Action.client(notes);
-      const create = client.createNote({ title: "Plan", body: "Draft" });
-      const refusal = yield* Effect.flip(create.pipe(as("reader")));
-
-      // `toEqual` on an error compares its fields and never its message, so the message is
-      // asserted on its own.
-      expect(refusal).toBeInstanceOf(Action.Forbidden);
-      expect(refusal.message).toBe("Requires notes:write.");
-    }).pipe(Effect.provide(NoteStore.layerMemory)),
-  );
 });

package/examples/notes-service/test/routes.test.ts

@@ -22,7 +22,7 @@ const as = (token: string) => ({
 });
 
 describe("the service, over HTTP and MCP", () => {
-  it.effect("answers the public action without a token and refuses the rest", () =>
+  it.effect("answers the public action without a token and refuses a protected one", () =>
     Effect.gen(function* () {
       const anyone = yield* ActionHttp.client(Http);
 
@@ -76,7 +76,7 @@ describe("the service, over HTTP and MCP", () => {
     }).pipe(Effect.provide(served)),
   );
 
-  it.effect("lists every tool to a signed-out MCP client, as one of them is public", () =>
+  it.effect("lists protected tools to a signed-out MCP client, as one tool is public", () =>
     Effect.gen(function* () {
       const response = yield* HttpClient.execute(ActionMcp.request("tools/list"));
 

package/examples/quickstart/README.md

@@ -27,5 +27,5 @@ src/
 ├── routes.ts          the surfaces: POST /api/greet and /mcp
 ├── server.ts          entrypoint
 └── client.ts          entrypoint
-test/greeting/         the routes, called in memory
+test/routes.test.ts    the routes, called in memory
 ```

package/examples/quickstart/src/client.ts

@@ -6,6 +6,7 @@ import { Http } from "./Api.js";
 
 // Entrypoint: `node --import tsx examples/quickstart/src/client.ts`, with the server running.
 // One typed method per action of the binding.
+// DEMO ONLY: a deployed client reads its `baseUrl` from configuration (kitchen-sink/src/seed.ts).
 Effect.gen(function* () {
   const client = yield* ActionHttp.client(Http, { baseUrl: "http://127.0.0.1:3000" });
 

package/examples/quickstart/src/server.ts

@@ -5,10 +5,8 @@ import { HttpRouter } from "effect/http";
 import { routes } from "./routes.js";
 
 // Entrypoint: `node --import tsx examples/quickstart/src/server.ts`.
-// A real server reads its port from config, `Config.Port("PORT")`, and limits request bodies:
-// `Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1)))`.
-// `127.0.0.1` serves this machine alone: a server others reach reads its host from config,
-// `Config.String("HOST").pipe(Config.withDefault("127.0.0.1"))`.
+// DEMO ONLY: a deployed server reads its host and port from config and limits request bodies,
+// as notes-service/src/server.ts does; `127.0.0.1` serves this machine alone.
 HttpRouter.serve(routes).pipe(
   Layer.provide(NodeHttpServer.layer(createServer, { host: "127.0.0.1", port: 3000 })),
   Layer.launch,

package/examples/quickstart/test/{greeting/greeting.test.ts → routes.test.ts}

@@ -3,9 +3,9 @@ import { Effect } from "effect";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
-import { Http } from "../../src/Api.js";
-import { Greet } from "../../src/greeting/Greeting.js";
-import { routes } from "../../src/routes.js";
+import { Http } from "../src/Api.js";
+import { Greet } from "../src/greeting/Greeting.js";
+import { routes } from "../src/routes.js";
 
 // The routes answer in memory: no port, and the same code the server runs.
 it.effect("greets over HTTP and as an MCP tool", () =>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, Effect RPC, native Toolkits, and CLIs.",
   "keywords": [
     "ai-agents",

package/docs/Action-in-process.md

@@ -1,93 +0,0 @@
-# Action in process
-
-Call actions from your own code, such as a job or a test, and share one build of the
-implementations between servers and jobs.
-
-Read [Action.md](Action.md) first, and this page alone, in one tool call. When something fails,
-search [Action-failures.md](Action-failures.md). Reading order: [README.md](README.md).
-
-## API
-
-Import `@gjermundgaraba/effect-actions/Action`. Its other exports are in [Action.md](Action.md#api).
-
-| Export                                  | Purpose                                                                  |
-| --------------------------------------- | ------------------------------------------------------------------------ |
-| `client(implementations, { actions? })` | An Effect of a client running them in process: `client.<action>(input)`. |
-| `layer(implementations)`                | Their builders as one layer: above several servers, each runs once.      |
-| `Client<Apps>`                          | What `client` gives for the implementations `Apps`, one or a list.       |
-| `ClientOptions`                         | What `client` takes: `actions`, the ones to call.                        |
-
-## Call actions in process
-
-`Action.client(implementations)` gives the methods `ActionHttp.client` gives. A call runs what a
-remote call runs, without a transport: the input and the result pass through their JSON codecs,
-and the authorizer runs before the handler.
-
-```ts
-const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
-
-const program = Effect.gen(function* () {
-  const client = yield* Action.client(notes);
-
-  return yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
-}).pipe(Effect.scoped, Effect.provide(NoteStore.layerMemory));
-```
-
-Acquiring a client needs a `Scope`: under `it.effect` the test supplies it, as in
-[notes-service/test/notes/notes.test.ts](../examples/notes-service/test/notes/notes.test.ts);
-elsewhere `Effect.scoped` does, as in [kitchen-sink/src/agent.ts](../examples/kitchen-sink/src/agent.ts).
-
-- **Provide the caller around each call, and startup services around the acquisition.** A call
-  reads its own context, never the one the client was acquired in, so one client serves every
-  caller ([assistant/test/identity/identity.test.ts](../examples/assistant/test/identity/identity.test.ts)).
-- **Acquiring a client runs the builders**, and builds a built authorizer: it owes their startup
-  services. Acquire it once, in a builder, a layer, or a scoped program such as a test. Never in
-  a handler, which builds on every request.
-- **Two acquisitions share a build only inside one layer graph**, such as under a layer provided
-  around the program. With none around them, each builds its own.
-- **Every implemented action has a method**, whether or not a surface serves it. `actions` lists
-  the ones to call, and an implementation holding none of them is left unbuilt
-  ([kitchen-sink/test/issues/issues.test.ts](../examples/kitchen-sink/test/issues/issues.test.ts)).
-- **Test what an implementation does here**, and what a surface adds, its authentication,
-  statuses and codecs, in memory ([Testing.md](Testing.md#test-routes-in-memory)). Assert on a
-  failure as [Testing.md](Testing.md#assert-on-errors) says.
-
-## Share one build across servers
-
-Inside one `HttpRouter.serve` or one `Testing.layer`, a builder runs once, however many surfaces
-serve it, a toolkit's `layer` provided to the routes included. Each builds its routes in a layer graph of its own, as `HttpRouter.provideRequest(layer)` builds its layer, which reuses what is provided from
-outside it and shares nothing it builds itself: a builder's run, a built authorizer, or a
-service of yours such as an in-memory store.
-
-- **With one server, put everything the process runs inside the layer it serves**, a job or an
-  agent beside the routes included.
-- **Otherwise, provide `Action.layer(implementations)` and the services they share above the
-  server and its siblings**: a second server, a program beside it, several `Testing.layer`s.
-
-```ts
-// kitchen-sink/src/routes.ts
-export const builders = Action.layer([status, identity, issues, attachments, admin]);
-
-// kitchen-sink/src/server.ts
-Layer.mergeAll(
-  HttpRouter.serve(Layer.merge(publicRoutes, socket)).pipe(Layer.provide(listen(publicPort))),
-  HttpRouter.serve(adminRoutes).pipe(Layer.provide(listen(adminPort))),
-).pipe(Layer.provide(builders), Layer.provide(memory));
-```
-
-That is [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) and
-[kitchen-sink/src/server.ts](../examples/kitchen-sink/src/server.ts), two ports;
-[kitchen-sink/test/routes.test.ts](../examples/kitchen-sink/test/routes.test.ts) does it with two
-`Testing.layer`s, asserting one run of a builder both ports serve.
-
-- **A job merged beside `HttpRouter.serve`, with no `Action.layer` above both, shares the
-  server's build only when its own side builds first.** Built after the routes, it builds
-  again, with state of its own. Which builds first depends on timing: it can pass in a test and
-  build twice once the job starts later.
-- **`Action.layer` builds every implementation it is given**, those no surface serves included,
-  so it owes their startup services.
-- **Inside one layer graph, a builder runs with the services of whichever surface builds it
-  first**, and services provided around one surface reach the others. Provide startup services
-  once, for every surface.
-- **Do not wrap a server in `Layer.fresh`**: two servers already share no build. It is only for
-  two surfaces in one graph that must each have a build and startup services of their own.

package/docs/CONTEXT.md

@@ -1,46 +0,0 @@
-# Context
-
-Vocabulary for `@gjermundgaraba/effect-actions`. The docs, the examples, the code and the tests
-use these words with these meanings. Module names and Effect's own terms (`HttpApi`, `Tool`,
-`Toolkit`, `McpServer`, `Rpc`, `RpcGroup`, `RpcServer`, `Command`) mean what their modules say.
-
-Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
-Tasks are routed from [README.md](README.md), and each module's failures from its `-failures.md`
-page.
-
-## Terms
-
-### Contracts and calls
-
-- **Action**: one contract: a name, a description, input, success and declared error schemas, `readOnly`, `caller`, and its `mcp` options. Holds no behavior. Made by `Action.make`.
-- **Read-only**: `readOnly`, required on every action: whether it leaves its resource unchanged. It enforces nothing itself.
-- **Caller**: who may call an action, `caller`. `Action.Anyone` makes a **public action**; an identity service, such as `caller: CurrentUser`, makes a **protected action**.
-- **Identity**: the service a protected action names as its caller. A **trusted identity** is one only a host supplies, on a local surface, which no token names.
-- **Handler**: a function from an action's decoded input to an Effect of its decoded success. The services it yields per call, and an authorizer's, are **request-time requirements**.
-- **Implementation**: what `Action.implement` returns: actions bound to their handlers and, where any is protected, their authorizer. Every surface that runs handlers takes one, or a list.
-- **Builder**: an Effect given to `Action.implement` in place of handlers, which returns them, once per layer graph. The services it yields are **build-time requirements**, or **startup services** ([Action.md](Action.md#implement-actions)).
-- **Layer graph**: the layers Effect builds together, each built once ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers)).
-- **Host**: the application that serves the surfaces: it builds their layers, provides their services and runs the server, subprocess or CLI.
-- **Surface**: where callers reach actions. A **remote surface** authenticates its callers (`ActionHttp.layer`, `ActionMcp.layerHttp`, `ActionRpc.layer`). A **local surface** has no one to authenticate (`ActionToolkit`, a local `ActionCli` command, `ActionMcp.runStdio`, `Action.client`): the host provides the identity.
-- **Binding**: what `ActionHttp.make` or `ActionRpc.make` returns: the actions its surface serves, as browser-safe data the server and every client share.
-- **Client**: one method per action, `client.<action>(input)`: `ActionHttp.client`, `ActionRpc.client`, `ActionMcp.client` and, in process, `Action.client`.
-- **Authorizer**: `authorize`, a function of the called action that an implementation of protected actions states. It succeeds or fails with a refusal ([Action.md](Action.md#authorize-calls)).
-- **Authentication descriptor**: what `Authentication.make` returns: a named, browser-safe declaration of how a remote caller proves an identity. A binding or an MCP endpoint serving protected actions names it.
-- **Authentication provider**: what `Authentication.layer` returns for a descriptor, holding its **verifier**: the server-only function from a credential to the identity.
-- **Layer middleware**: native `HttpApiMiddleware` or `RpcMiddleware` given to `ActionHttp.layer` or `ActionRpc.layer` as `middleware`, run around every route or rpc the layer serves.
-- **Mixed endpoint**: an MCP endpoint serving public and protected tools on one URL ([ActionMcp.md](ActionMcp.md#protect-tools)).
-- **Declared error**: an error schema listed in an action's `error`, which its handler may fail with ([guarantees.md](guarantees.md#wire-behavior)).
-- **Built-in errors**: `Action.InvalidInput`, `Action.Unauthenticated` and `Action.Forbidden`, together `Action.BuiltIn`: errors the library produces and every surface declares ([Action.md](Action.md#fail-with-declared-and-built-in-errors)).
-- **Refusal**: `Action.Refusal`, `Unauthenticated | Forbidden`: what authentication or an authorizer refuses a caller with. A **step-up refusal** is one an OAuth client acts on: an `Unauthenticated`, or a `Forbidden` naming `scopes` ([Authentication.md](Authentication.md#publish-oauth-discovery)).
-- **Media field**: a field of an action's success whose schema is a media kind, `Action.Image`, which an MCP tool **lifts** into a content block of its own ([ActionMcp.md](ActionMcp.md#return-images-and-other-media)).
-
-### Layout of an application
-
-The parts of the layout every example uses: [examples/README.md](../examples/README.md#how-they-are-laid-out).
-
-- **Domain**: one subject of the application, such as notes or identity, and the folder holding everything about it. A folder is never a mechanism, such as `contracts/` or `handlers/`, but **Platform**.
-- **Platform**: `platform/`, the one folder named for a mechanism: the adapters, each a service's Layer over a technology, such as a file or an upstream HTTP API. A domain imports none of them; an entrypoint provides them.
-- **Contract file**: the PascalCase file of a domain, such as `notes/Notes.ts`: its schemas, errors and actions, and the identity and descriptor it declares. It imports no server code.
-- **Routes**: `routes.ts`, the host's surfaces as one Layer. A route, singular, is one HTTP route.
-- **Entrypoint**: a file that runs the application one way, such as `server.ts`, `stdio.ts` or `cli.ts`: the **composition root**, the one place that chooses the services, the platform and, on a local surface, the caller.
-- **Demo shortcut**: what an example does in place of what a deployment needs, marked `DEMO ONLY` in a comment.