@gjermundgaraba/effect-actions 0.16.0 → 0.17.0

package/examples/mcp-tools/README.md

@@ -91,9 +91,11 @@ and no `name` or `arguments`.
 src/
 ├── printers/
 │   ├── Printers.ts    contract: the printer, the one declared error, the five tools
-│   ├── farm.ts        PrintFarm, the upstream API as a service, and its Layer
-│   ├── fake.ts        DEMO ONLY: the farm's API answered in memory, as an HttpClient
+│   ├── farm.ts        PrintFarm, the upstream as a service: what the handlers call
 │   └── handlers.ts    Action.implement: tool to service
+├── platform/
+│   ├── print-farm.ts  printFarm, PrintFarm's Layer over the farm's HTTP API
+│   └── fake-farm.ts   DEMO ONLY: the farm's API answered in memory, as an HttpClient
 ├── instructions.ts    the server's name, version and its instructions for the model
 ├── routes.ts          the HTTP surface: /mcp and /healthz
 ├── server.ts          entrypoint: MCP over HTTP
@@ -103,13 +105,14 @@ test/
 └── routes.test.ts     over MCP in memory, with Testing.layer
 ```
 
-- **The upstream is a service, built once.** `PrintFarm.layer` 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 `farm.ts`, which knows nothing of tools, so a second caller of the farm, a
-  job or another surface, takes the service alone.
+- **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 `farm.ts` as a `PrintFarmError` with a
+  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
@@ -128,14 +131,14 @@ test/
 | 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/printers/farm.ts`           |
-| An upstream's failures mapped to the declared error             | `src/printers/farm.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/printers/fake.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`            |

package/examples/mcp-tools/src/{printers/fake.ts → platform/fake-farm.ts}

@@ -1,10 +1,10 @@
 import { Buffer } from "node:buffer";
 import { Effect, Layer, Option, Schema } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
-import type { Printer } from "./Printers.js";
+import type { Printer } from "../printers/Printers.js";
 
 // DEMO ONLY: the farm's HTTP API answered in memory, so the example and its tests run without
-// a farm. It is an `HttpClient`, so `PrintFarm.layer` sends it the requests it would send over
+// a farm. It is an `HttpClient`, so `printFarm` sends it the requests it would send over
 // the network. A real application has no such file: its entrypoints provide a real client,
 // `FetchHttpClient.layer` from `effect/http`.
 

package/examples/mcp-tools/src/platform/print-farm.ts

@@ -0,0 +1,118 @@
+import { Config, Effect, Layer, Redacted, Schema } from "effect";
+import {
+  HttpBody,
+  HttpClient,
+  type HttpClientError,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/http";
+import { PrintFarm } from "../printers/farm.js";
+import { Printer, PrintFarmError } from "../printers/Printers.js";
+
+const fail = (message: string) => Effect.fail(new PrintFarmError({ message }));
+
+const unreadable = "The print farm sent an answer this server could not read.";
+
+// The farm answers a request it refuses with a status that is not 2xx and `{ "error": "..." }`.
+// Its reason is passed on to the model, which can act on "The printer is busy with a job".
+const refuseUnlessOk = HttpClientResponse.matchStatus({
+  "2xx": (response) => Effect.succeed(response),
+  orElse: (response) =>
+    HttpClientResponse.schemaBodyJson(Schema.Struct({ error: Schema.String }))(response).pipe(
+      Effect.matchEffect({
+        onFailure: () => fail(`The print farm refused the request (HTTP ${response.status}).`),
+        onSuccess: ({ error }) => fail(`The print farm refused: ${error}`),
+      }),
+    ),
+});
+
+// Every other way a call to the farm fails, as the same declared error: no connection, an
+// answer of another shape than expected, or none in time. Nothing of the HTTP client's own
+// errors leaves this file, so no tool can fail with something its contract does not declare.
+const asPrintFarmError = <A>(
+  effect: Effect.Effect<A, PrintFarmError | HttpClientError.HttpClientError | Schema.SchemaError>,
+) =>
+  effect.pipe(
+    Effect.catchTag("HttpClientError", ({ response }) =>
+      fail(response === undefined ? "The print farm could not be reached." : unreadable),
+    ),
+    Effect.catchTag("SchemaError", () => fail(unreadable)),
+    Effect.timeoutOrElse({
+      duration: "30 seconds",
+      orElse: () => fail("The print farm did not answer in time."),
+    }),
+  );
+
+const asImage = (response: HttpClientResponse.HttpClientResponse) =>
+  Effect.gen(function* () {
+    const mimeType = response.headers["content-type"];
+
+    if (mimeType === undefined || !mimeType.startsWith("image/")) return yield* fail(unreadable);
+
+    return { data: new Uint8Array(yield* response.arrayBuffer), mimeType };
+  });
+
+// Built once, when the process starts. It requires an `HttpClient` and reads its settings
+// from `Config`: the entrypoint decides which client, and the environment says which farm.
+// Not `fetch`: as a service, a test replaces the network alone and opens no port
+// (test/printers/printers.test.ts).
+export const printFarm = Layer.effect(
+  PrintFarm,
+  Effect.gen(function* () {
+    const { url, user, password } = yield* Config.all({
+      url: Config.URL("FARM_URL"),
+      user: Config.NonEmptyString("FARM_USER"),
+      password: Config.Redacted("FARM_PASSWORD"),
+    });
+
+    const http = (yield* HttpClient.HttpClient).pipe(
+      HttpClient.mapRequest(HttpClientRequest.prependUrl(url.href)),
+      HttpClient.transformResponse(Effect.flatMap(refuseUnlessOk)),
+    );
+
+    // Signs in once, here, and every call below reuses the token, kept `Redacted` so no log
+    // prints it. A farm that refuses the sign-in stops the process at startup, with its
+    // reason, before any tool is listed. A real client also signs in again when a call
+    // answers 401, as tokens expire.
+    const session = yield* http
+      .post("/api/login", {
+        body: HttpBody.jsonUnsafe({ user, password: Redacted.value(password) }),
+      })
+      .pipe(
+        Effect.flatMap(
+          HttpClientResponse.schemaBodyJson(
+            Schema.Struct({ token: Schema.RedactedFromValue(Schema.String) }),
+          ),
+        ),
+        asPrintFarmError,
+      );
+
+    yield* Effect.logInfo(`Signed in to the print farm at ${url.host} as ${user}.`);
+
+    const api = HttpClient.mapRequest(http, HttpClientRequest.bearerToken(session.token));
+
+    // An id is written into the path as it is: the contract admits only letters, digits,
+    // `_` and `-`, so it is always one segment. Encoding would not make other text safe:
+    // `encodeURIComponent` leaves `..` alone, and a URL parser then walks up the path.
+    const at = (id: string, rest = "") => `/api/printers/${id}${rest}`;
+
+    const printer = (answer: ReturnType<typeof api.get>) =>
+      answer.pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(Printer)), asPrintFarmError);
+
+    return PrintFarm.of({
+      printers: api.get("/api/printers").pipe(
+        Effect.flatMap(
+          HttpClientResponse.schemaBodyJson(Schema.Struct({ printers: Schema.Array(Printer) })),
+        ),
+        Effect.map(({ printers }) => printers),
+        asPrintFarmError,
+      ),
+      printer: (id) => printer(api.get(at(id))),
+      snapshot: (id) => api.get(at(id, "/camera")).pipe(Effect.flatMap(asImage), asPrintFarmError),
+      start: (id, file) =>
+        printer(api.post(at(id, "/job"), { body: HttpBody.jsonUnsafe({ file }) })),
+      setPaused: (id, paused) => printer(api.post(at(id, paused ? "/pause" : "/resume"))),
+      cancel: (id) => printer(api.del(at(id, "/job"))),
+    });
+  }),
+);

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

@@ -1,61 +1,11 @@
-import { Config, Context, Effect, Layer, Redacted, Schema } from "effect";
-import {
-  HttpBody,
-  HttpClient,
-  type HttpClientError,
-  HttpClientRequest,
-  HttpClientResponse,
-} from "effect/http";
+import { Context, type Effect } from "effect";
 import type * as Action from "@gjermundgaraba/effect-actions/Action";
-import { Printer, PrintFarmError } from "./Printers.js";
-
-const fail = (message: string) => Effect.fail(new PrintFarmError({ message }));
-
-const unreadable = "The print farm sent an answer this server could not read.";
-
-// The farm answers a request it refuses with a status that is not 2xx and `{ "error": "..." }`.
-// Its reason is passed on to the model, which can act on "The printer is busy with a job".
-const refuseUnlessOk = HttpClientResponse.matchStatus({
-  "2xx": (response) => Effect.succeed(response),
-  orElse: (response) =>
-    HttpClientResponse.schemaBodyJson(Schema.Struct({ error: Schema.String }))(response).pipe(
-      Effect.matchEffect({
-        onFailure: () => fail(`The print farm refused the request (HTTP ${response.status}).`),
-        onSuccess: ({ error }) => fail(`The print farm refused: ${error}`),
-      }),
-    ),
-});
-
-// Every other way a call to the farm fails, as the same declared error: no connection, an
-// answer of another shape than expected, or none in time. Nothing of the HTTP client's own
-// errors leaves this file, so no tool can fail with something its contract does not declare.
-const asPrintFarmError = <A>(
-  effect: Effect.Effect<A, PrintFarmError | HttpClientError.HttpClientError | Schema.SchemaError>,
-) =>
-  effect.pipe(
-    Effect.catchTag("HttpClientError", ({ response }) =>
-      fail(response === undefined ? "The print farm could not be reached." : unreadable),
-    ),
-    Effect.catchTag("SchemaError", () => fail(unreadable)),
-    Effect.timeoutOrElse({
-      duration: "30 seconds",
-      orElse: () => fail("The print farm did not answer in time."),
-    }),
-  );
-
-const asImage = (response: HttpClientResponse.HttpClientResponse) =>
-  Effect.gen(function* () {
-    const mimeType = response.headers["content-type"];
-
-    if (mimeType === undefined || !mimeType.startsWith("image/")) return yield* fail(unreadable);
-
-    return { data: new Uint8Array(yield* response.arrayBuffer), mimeType };
-  });
+import type { Printer, PrintFarmError } from "./Printers.js";
 
 /**
- * The print farm's HTTP API, the one upstream of this server. Its methods require nothing and
- * fail only with the error the tools declare: the layer has captured the HTTP client, the
- * farm's URL and the session.
+ * The print farm, the one upstream of this server. Its methods require nothing and fail only
+ * with the error the tools declare: its layer, `printFarm` in src/platform/print-farm.ts, has
+ * captured the HTTP client, the farm's URL and the session.
  */
 export class PrintFarm extends Context.Service<
   PrintFarm,
@@ -67,70 +17,4 @@ export class PrintFarm extends Context.Service<
     readonly setPaused: (id: string, paused: boolean) => Effect.Effect<Printer, PrintFarmError>;
     readonly cancel: (id: string) => Effect.Effect<Printer, PrintFarmError>;
   }
->()("mcp-tools/PrintFarm") {
-  // Built once, when the process starts. It requires an `HttpClient` and reads its settings
-  // from `Config`: the entrypoint decides which client, and the environment says which farm.
-  // Not `fetch`: as a service, a test replaces the network alone and opens no port
-  // (test/printers/printers.test.ts).
-  static readonly layer = Layer.effect(
-    PrintFarm,
-    Effect.gen(function* () {
-      const { url, user, password } = yield* Config.all({
-        url: Config.URL("FARM_URL"),
-        user: Config.NonEmptyString("FARM_USER"),
-        password: Config.Redacted("FARM_PASSWORD"),
-      });
-
-      const http = (yield* HttpClient.HttpClient).pipe(
-        HttpClient.mapRequest(HttpClientRequest.prependUrl(url.href)),
-        HttpClient.transformResponse(Effect.flatMap(refuseUnlessOk)),
-      );
-
-      // Signs in once, here, and every call below reuses the token, kept `Redacted` so no log
-      // prints it. A farm that refuses the sign-in stops the process at startup, with its
-      // reason, before any tool is listed. A real client also signs in again when a call
-      // answers 401, as tokens expire.
-      const session = yield* http
-        .post("/api/login", {
-          body: HttpBody.jsonUnsafe({ user, password: Redacted.value(password) }),
-        })
-        .pipe(
-          Effect.flatMap(
-            HttpClientResponse.schemaBodyJson(
-              Schema.Struct({ token: Schema.RedactedFromValue(Schema.String) }),
-            ),
-          ),
-          asPrintFarmError,
-        );
-
-      yield* Effect.logInfo(`Signed in to the print farm at ${url.host} as ${user}.`);
-
-      const api = HttpClient.mapRequest(http, HttpClientRequest.bearerToken(session.token));
-
-      // An id is written into the path as it is: the contract admits only letters, digits,
-      // `_` and `-`, so it is always one segment. Encoding would not make other text safe:
-      // `encodeURIComponent` leaves `..` alone, and a URL parser then walks up the path.
-      const at = (id: string, rest = "") => `/api/printers/${id}${rest}`;
-
-      const printer = (answer: ReturnType<typeof api.get>) =>
-        answer.pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(Printer)), asPrintFarmError);
-
-      return PrintFarm.of({
-        printers: api.get("/api/printers").pipe(
-          Effect.flatMap(
-            HttpClientResponse.schemaBodyJson(Schema.Struct({ printers: Schema.Array(Printer) })),
-          ),
-          Effect.map(({ printers }) => printers),
-          asPrintFarmError,
-        ),
-        printer: (id) => printer(api.get(at(id))),
-        snapshot: (id) =>
-          api.get(at(id, "/camera")).pipe(Effect.flatMap(asImage), asPrintFarmError),
-        start: (id, file) =>
-          printer(api.post(at(id, "/job"), { body: HttpBody.jsonUnsafe({ file }) })),
-        setPaused: (id, paused) => printer(api.post(at(id, paused ? "/pause" : "/resume"))),
-        cancel: (id) => printer(api.del(at(id, "/job"))),
-      });
-    }),
-  );
-}
+>()("mcp-tools/PrintFarm") {}

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

@@ -2,8 +2,8 @@ import { createServer } from "node:http";
 import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
 import { ByteSize, Config, Effect, Layer } from "effect";
 import { HttpRouter, HttpServerRequest } from "effect/http";
-import { fakeFarm } from "./printers/fake.js";
-import { PrintFarm } from "./printers/farm.js";
+import { fakeFarm } from "./platform/fake-farm.js";
+import { printFarm } from "./platform/print-farm.js";
 import { routes } from "./routes.js";
 
 // Entrypoint: `node --import tsx examples/mcp-tools/src/server.ts`, with FARM_URL, FARM_USER
@@ -22,8 +22,8 @@ const server = Layer.unwrap(
       // short fields, so anything larger is not one.
       Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.kibibytes(64))),
       // DEMO ONLY: `fakeFarm` answers the farm's API in memory. A real server provides
-      // `FetchHttpClient.layer` in its place, and `PrintFarm.layer` calls the farm at FARM_URL.
-      Layer.provide(PrintFarm.layer.pipe(Layer.provide(fakeFarm))),
+      // `FetchHttpClient.layer` in its place, and `printFarm` calls the farm at FARM_URL.
+      Layer.provide(printFarm.pipe(Layer.provide(fakeFarm))),
     );
   }),
 );

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

@@ -3,8 +3,8 @@ import { Effect, Layer } from "effect";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { serverInfo } from "./instructions.js";
-import { fakeFarm } from "./printers/fake.js";
-import { PrintFarm } from "./printers/farm.js";
+import { fakeFarm } from "./platform/fake-farm.js";
+import { printFarm } from "./platform/print-farm.js";
 import { printers } from "./printers/handlers.js";
 
 // Entrypoint: an MCP server a local agent starts as a subprocess, with FARM_URL, FARM_USER and
@@ -17,10 +17,10 @@ ActionMcp.runStdio(printers, serverInfo).pipe(
     NodeStdio.layer,
     // DEMO ONLY: `fakeFarm` answers the farm's API in memory. A real server provides
     // `FetchHttpClient.layer` in its place.
-    PrintFarm.layer.pipe(Layer.provide(fakeFarm)),
+    printFarm.pipe(Layer.provide(fakeFarm)),
   ]),
   // stdout carries the protocol alone. Applied last, this sends every log to stderr, the
-  // sign-in line `PrintFarm.layer` logs included, and a startup failure too.
+  // sign-in line `printFarm` logs included, and a startup failure too.
   ActionCli.logToStderr,
   NodeRuntime.runMain,
 );

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

@@ -8,8 +8,8 @@ import {
 } from "effect/http";
 import { TestClock } from "effect/testing";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
-import { fakeFarm } from "../../src/printers/fake.js";
-import { PrintFarm } from "../../src/printers/farm.js";
+import { fakeFarm } from "../../src/platform/fake-farm.js";
+import { printFarm } from "../../src/platform/print-farm.js";
 import { printers } from "../../src/printers/handlers.js";
 import { PrintFarmError } from "../../src/printers/Printers.js";
 
@@ -19,7 +19,7 @@ import { PrintFarmError } from "../../src/printers/Printers.js";
 // The real `PrintFarm` over an upstream of the test's: its requests, its sign-in and its error
 // mapping all run, and only the network is replaced. Its settings come from a Layer too.
 const farmOver = (upstream: Layer.Layer<HttpClient.HttpClient>) =>
-  PrintFarm.layer.pipe(
+  printFarm.pipe(
     Layer.provide(upstream),
     Layer.provide(
       ConfigProvider.layer(

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

@@ -3,8 +3,8 @@ import { ConfigProvider, Effect, Layer, Schema } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
-import { fakeFarm, picture } from "../src/printers/fake.js";
-import { PrintFarm } from "../src/printers/farm.js";
+import { fakeFarm, picture } from "../src/platform/fake-farm.js";
+import { printFarm } from "../src/platform/print-farm.js";
 import { PrintFarmError, Printers } from "../src/printers/Printers.js";
 import { routes } from "../src/routes.js";
 
@@ -15,10 +15,10 @@ import { routes } from "../src/routes.js";
 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.layer` alone.
+// fake farm is another `HttpClient`, provided to `printFarm` alone.
 const servedWith = (environment: Record<string, string>) =>
   Testing.layer(routes).pipe(
-    Layer.provide(PrintFarm.layer.pipe(Layer.provide(fakeFarm))),
+    Layer.provide(printFarm.pipe(Layer.provide(fakeFarm))),
     Layer.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(environment))),
   );
 

package/examples/notes-service/README.md

@@ -50,6 +50,37 @@ 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.
 
+## Retry a creation
+
+`createNote({ title, body })` creates a new note on every call. To retry safely, add an optional
+`requestId`. Generate it once for a new creation, for example with `crypto.randomUUID()`, and
+keep it with the pending operation outside any retry loop. After a lost response, send the
+same key and content again. For the CLI, pass `--request-id` and keep it when repeating the
+command:
+
+```sh
+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.
+
 ## Layout
 
 ```text
@@ -102,6 +133,7 @@ test/
 | A contract with declared errors and their statuses            | `src/notes/Notes.ts`             |
 | Input fields described, for `--help` and a tool's schema      | `src/notes/Notes.ts`             |
 | Handlers getting a service once and the caller per call       | `src/notes/handlers.ts`          |
+| A write safe to retry with the same caller and request key    | `src/notes/store.ts`             |
 | A public action beside protected ones                         | `src/status/`                    |
 | Authorization from `readOnly`, refusing with a scope          | `src/identity/authorize.ts`      |
 | A token verifier and OAuth discovery read from config         | `src/identity/verifier.ts`       |

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

@@ -8,6 +8,7 @@ import { CurrentUser, scopes } from "./Identity.js";
 // 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.
+// This named span measures authorization within the action's span, including a refusal.
 export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
   const scope = action.readOnly ? scopes.read : scopes.write;
   const user = yield* CurrentUser;

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

@@ -25,6 +25,12 @@ export class NoteChanged extends Schema.TaggedError<NoteChanged>()(
   { httpApiStatus: 409 },
 ) {}
 
+export class RequestConflict extends Schema.TaggedError<RequestConflict>()(
+  "RequestConflict",
+  { requestId: Schema.String },
+  { httpApiStatus: 409 },
+) {}
+
 // A description on an input field is that field's help on every surface: beside its flag or
 // argument in a command's `--help`, and in the input schema a model reads from the MCP tool
 // listing and the OpenAPI document. A field without one has a flag with no help.
@@ -43,6 +49,8 @@ const Title = Schema.String.check(
 
 const Body = Schema.String.annotate({ description: "The note's whole text." });
 
+const Content = Schema.Struct({ title: Title, body: Body });
+
 export const ListNotes = Action.make("listNotes", {
   description: "List your notes, without their bodies.",
   success: { notes: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })) },
@@ -60,9 +68,17 @@ export const GetNote = Action.make("getNote", {
 });
 
 export const CreateNote = Action.make("createNote", {
-  description: "Create a note.",
-  input: { title: Title, body: Body },
+  description:
+    "Create a note. To retry safely, supply a requestId and reuse it with the same content.",
+  input: {
+    requestId: Schema.optionalKey(Schema.NonEmptyString).annotate({
+      description:
+        "An optional key for this creation. Keep it for retries; without one, every call creates a note.",
+    }),
+    ...Content.fields,
+  },
   success: Note,
+  error: RequestConflict,
   readOnly: false,
   caller: CurrentUser,
   mcp: { destructiveHint: false },
@@ -98,14 +114,15 @@ export const DeleteNote = Action.make("deleteNote", {
 // 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` adds and removes nothing, so `destructiveHint` is `false`.
-// Each note is `createNote`'s input: an action's `input` is a schema already, used as it is.
+// (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", {
   description:
     "Create several notes at once, such as those `notes export` wrote. Every note is checked " +
     "before any is written: an import holding one that is not valid writes none.",
   input: {
-    notes: Schema.Array(CreateNote.input)
+    notes: Schema.Array(Content)
       .check(
         Schema.isMinLength(1, { message: "An import holds at least one note." }),
         Schema.isMaxLength(100, { message: "An import holds at most 100 notes." }),

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

@@ -23,8 +23,8 @@ export const notes = Action.implement(
           return { notes: owned.map(({ id, title }) => ({ id, title })) };
         }),
       getNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.get(user.id, id)),
-      createNote: ({ title, body }) =>
-        Effect.flatMap(CurrentUser, (user) => store.create(user.id, title, body)),
+      createNote: ({ requestId, title, body }) =>
+        Effect.flatMap(CurrentUser, (user) => store.create(user.id, title, body, requestId)),
       updateNote: ({ id, body, revision }) =>
         Effect.flatMap(CurrentUser, (user) => store.update(user.id, id, body, revision)),
       deleteNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.remove(user.id, id)),

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

@@ -1,5 +1,5 @@
 import { Context, Effect, Layer } from "effect";
-import { type Note, NoteChanged, NoteNotFound } from "./Notes.js";
+import { type Note, NoteChanged, NoteNotFound, RequestConflict } from "./Notes.js";
 
 /**
  * Where notes live, each owned by one user. Ownership is checked here, in the data access, so no
@@ -10,7 +10,12 @@ export class NoteStore extends Context.Service<
   {
     readonly list: (owner: string) => Effect.Effect<ReadonlyArray<Note>>;
     readonly get: (owner: string, id: string) => Effect.Effect<Note, NoteNotFound>;
-    readonly create: (owner: string, title: string, body: string) => Effect.Effect<Note>;
+    readonly create: (
+      owner: string,
+      title: string,
+      body: string,
+      requestId?: string,
+    ) => Effect.Effect<Note, RequestConflict>;
     /** Every note or none: a database does this in one transaction. */
     readonly createAll: (
       owner: string,
@@ -26,12 +31,14 @@ export class NoteStore extends Context.Service<
     readonly count: Effect.Effect<number>;
   }
 >()("notes-service/NoteStore") {
-  // DEMO ONLY: memory, lost when the process stops. A real store is another Layer of this
-  // service, chosen by the entrypoint.
+  // DEMO ONLY: notes and replay records live in this process's memory, without eviction.
   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>>();
 
+    // Keep the original result even after the note is updated or deleted.
+    const creations = new Map<string, Map<string, Note>>();
+
     const ownedBy = (owner: string) => notes.get(owner) ?? new Map<string, Note>();
 
     const save = (owner: string, note: Note) => {
@@ -51,8 +58,31 @@ export class NoteStore extends Context.Service<
     return NoteStore.of({
       list: (owner) => Effect.sync(() => Array.from(ownedBy(owner).values())),
       get,
-      create: (owner, title, body) =>
-        Effect.sync(() => save(owner, { id: crypto.randomUUID(), title, body, revision: 1 })),
+      create: Effect.fn("NoteStore.create")(function* (owner, title, body, requestId) {
+        if (requestId !== undefined) {
+          const recorded = creations.get(owner)?.get(requestId);
+
+          if (recorded !== undefined) {
+            if (recorded.title !== title || recorded.body !== body) {
+              return yield* new RequestConflict({ requestId });
+            }
+
+            return recorded;
+          }
+        }
+
+        // No yield between lookup, mutation and recording: concurrent calls cannot interleave
+        // or interruption leave a note without its result.
+        const note = save(owner, { id: crypto.randomUUID(), title, body, revision: 1 });
+
+        if (requestId !== undefined) {
+          const requests = creations.get(owner) ?? new Map<string, Note>();
+          requests.set(requestId, note);
+          creations.set(owner, requests);
+        }
+
+        return note;
+      }),
       createAll: (owner, all) =>
         Effect.sync(() =>
           all.map(({ title, body }) =>