@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/README.md

@@ -1,12 +1,8 @@
 # effect-actions
 
-Define an Effect action once. Serve it over HTTP, MCP and Effect RPC, hand it to a model as a
-native Toolkit, and run it from a CLI. Same schemas, same handler, Effect's own servers and clients
-underneath.
+Define an Effect action once. Serve it over HTTP, MCP and Effect RPC, hand it to a model as a native Toolkit, and run it from a CLI. Same schemas, same handler, Effect's own servers and clients underneath. Events go the same way: watched over HTTP, MCP, Effect RPC and the CLI, or delivered by webhook. A companion package, [effect-actions-cloudflare](packages/cloudflare/), serves the HTTP, MCP and RPC routes, events and webhooks included, from Cloudflare Durable Objects.
 
-**If you are a coding agent**, start at [docs/README.md](docs/README.md), not here. It routes
-every task, protecting an action and limiting request bodies included, to its page and its
-example.
+**If you are a coding agent**, start at [docs/README.md](docs/README.md), not here. It routes every task, protecting an action and limiting request bodies included, to its page and its example.
 
 ## Looks like this
 
@@ -25,7 +21,9 @@ const Greet = Action.make("greet", {
 An implementation binds it to its handler:
 
 ```ts
-const greeting = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
+const greeting = Action.implement(Greet, ({ name }) =>
+  Effect.succeed(`Hello, ${name}!`)
+);
 ```
 
 A binding gives it a route, for the server to serve and a client to call:
@@ -39,14 +37,11 @@ And the same implementation is served on every surface the host wants:
 ```ts
 const routes = Layer.mergeAll(
   ActionHttp.layer(Http, greeting),
-  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
+  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" })
 );
 ```
 
-Serve `routes` with Effect's `HttpRouter.serve` and a platform server, as
-[examples/quickstart](examples/quickstart) does, file by file, and you have
-`POST /api/greet` and an MCP tool named `greet` at `/mcp`. The same `greeting`
-implementation is also:
+Serve `routes` with Effect's `HttpRouter.serve` and a platform server, as [examples/quickstart](examples/quickstart) does, file by file, and you have `POST /api/greet` and an MCP tool named `greet` at `/mcp`. The same `greeting` implementation is also:
 
 ```ts
 const { toolkit, layer } = ActionToolkit.make(greeting); // native Effect AI Toolkit and its handler layer
@@ -81,41 +76,30 @@ Effect.gen(function* () {
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@~4.0.4
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.5
 ```
 
-It needs TypeScript 7 or newer and is ESM only
-([docs/setup.md](docs/setup.md#install)). Add `@effect/platform-node@~4.0.4` to serve or run a CLI from Node, and `@types/node` for its `node:` imports. Every module is a
-subpath import (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a
-contracts-only bundle never loads a server.
+It needs TypeScript 7 or newer and is ESM only ([docs/setup.md](docs/setup.md#install)). Add `@effect/platform-node@~4.0.5` to serve or run a CLI from Node, and `@types/node` for its `node:` imports. Every module is a subpath import (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a contracts-only bundle never loads a server.
 
 ## Examples
 
-[examples/](examples/README.md) holds complete applications, each a directory you can run, with
-its own tests, laid out the way we recommend for an application: a folder per domain, the
-contract in one file a browser can import, one entrypoint per way of running it. They are
-type-checked and tested with the library and ship in the package.
+[examples/](examples/README.md) holds complete applications, each a directory you can run, with its own tests, laid out the way we recommend for an application: a folder per domain, the contract in one file a browser can import, one entrypoint per way of running it. They are type-checked and tested with the library and ship in the package.
 
 - [quickstart](examples/quickstart/): the program above.
-- [notes-service](examples/notes-service/): a service with bearer authentication, a JSON API
-  and MCP tools from one implementation, a CLI and a browser client. Most applications are this.
+- [notes-service](examples/notes-service/): a service with bearer authentication, a JSON API and MCP tools from one implementation, a CLI and a browser client. Most applications are this.
 - [mcp-tools](examples/mcp-tools/): an MCP server whose tools wrap an upstream HTTP API.
-- [assistant](examples/assistant/): no server, the same implementations as a model's tools
-  and as local commands.
+- [assistant](examples/assistant/): no server, the same implementations as a model's tools and as local commands.
 - [live-rpc](examples/live-rpc/): Effect RPC over a WebSocket.
-- [kitchen-sink](examples/kitchen-sink/): every module and nearly every option in one
-  application, with an index from each to the file that shows it.
+- [build-events](examples/build-events/): events watched over MCP, HTTP, RPC, a command line and webhooks, and actions reporting progress and answering a stream.
+- [kitchen-sink](examples/kitchen-sink/): every module and nearly every option in one application, with an index from each to the file that shows it.
 
 ## Docs
 
-[docs/](docs/README.md) is written for coding agents: one short page per module, organized by
-task, each linking to the example files that show the task working. Start at
-[docs/README.md](docs/README.md).
+[docs/](docs/README.md) is written for coding agents: one short page per module, organized by task, each linking to the example files that show the task working. Start at [docs/README.md](docs/README.md).
 
 ## For agents
 
-The `effect-actions` skill puts the docs in front of a coding agent. With the
-[skills CLI](https://github.com/vercel-labs/skills), for any agent it supports:
+The `effect-actions` skill puts the docs in front of a coding agent. With the [skills CLI](https://github.com/vercel-labs/skills), for any agent it supports:
 
 ```sh
 npx skills add gjermundgaraba/effect-actions --skill effect-actions
@@ -135,16 +119,11 @@ codex plugin marketplace add gjermundgaraba/effect-actions
 codex plugin add effect-actions@effect-actions-marketplace
 ```
 
-The skill is generated from `docs/` on the main branch, which can be ahead of the latest
-release. Its links to the examples are paths into the installed package,
-`node_modules/@gjermundgaraba/effect-actions/examples`, which an agent reads without a network;
-the pages of the installed version are beside them, in
-`node_modules/@gjermundgaraba/effect-actions/docs`.
+The skill is generated from `docs/` on the main branch, which can be ahead of the latest release. Its links to the examples are paths into the installed package, `node_modules/@gjermundgaraba/effect-actions/examples`, which an agent reads without a network; the pages of the installed version are beside them, in `node_modules/@gjermundgaraba/effect-actions/docs`.
 
 ## Status
 
-The `effect` peer range is in [docs/setup.md](docs/setup.md#install). Actions are unary JSON over HTTP, MCP and Effect RPC, whose protocols speak JSON alone: no streaming or uploads.
-Token verification and the authorization rule belong to the application; the library supplies the authentication descriptor and provider, runs the rule, and answers the refusals. See [what the library leaves to you](docs/README.md#what-the-library-leaves-to-you).
+The `effect` peer range is in [docs/setup.md](docs/setup.md#install). Actions are unary JSON over HTTP, MCP and Effect RPC, whose protocols speak JSON alone: no streaming or uploads. Token verification and the authorization rule belong to the application; the library supplies the authentication descriptor and provider, runs the rule, and answers the refusals. See [what the library leaves to you](docs/README.md#what-the-library-leaves-to-you).
 
 ## Acknowledgements
 
@@ -152,5 +131,4 @@ A few ideas (like the native Toolkit and CLI projections) are inspired by the ex
 
 ## Contributing
 
-The rules for changing the library are in
-[AGENTS.md](https://github.com/gjermundgaraba/effect-actions/blob/main/AGENTS.md). MIT licensed.
+The rules for changing the library are in [AGENTS.md](https://github.com/gjermundgaraba/effect-actions/blob/main/AGENTS.md). MIT licensed.

package/dist/Action.d.mts

@@ -1,15 +1,18 @@
+import { Codec, CodecOf, Fields, NoInput } from "./contract/codec.mjs";
 import { Anyone } from "./contract/caller.mjs";
 import { BuiltIn, Forbidden, InvalidInput, Issue, Refusal, Unauthenticated } from "./contract/errors.mjs";
-import { ActionOf, AnyImplementation, Authorize, BuildError, BuildServices, Holding, Implementation, Known, Member, Offered, OptionalUnless, Protected, RequestOf, SelectedOf, Served, Serving } from "./contract/implementation.mjs";
+import { EventBuildError, EventBuildServices, EventOf, EventRequestOf, HoldingEvents, ServingEvents } from "./contract/feed.mjs";
+import { Any as Any$1, Received, SubscriptionError } from "./Event.mjs";
+import { ReportingOf } from "./contract/progress.mjs";
+import { ActionOf, AnyImplementation, Authorize, BuildError, BuildServices, Holding, Implementation, Known, Member, Offered, OptionalUnless, Protected, RequestOf, SelectedEventsOf, SelectedOf, Served, Serving } from "./contract/implementation.mjs";
+import { Authorizer, Deferred as Deferred$1 } from "./contract/authorizer.mjs";
 import { Call } from "./contract/call.mjs";
+import { Idempotency, layerIdempotency } from "./contract/idempotency.mjs";
+import { Answer, Stream, StreamOf } from "./contract/stream.mjs";
+import { WatchArgs } from "./contract/watch.mjs";
 import { Image } from "./contract/media.mjs";
-import { Context, Effect, Layer, Schema, Scope } from "effect";
-type Codec = Schema.Codec<unknown, unknown, never, never>;
-type Fields = {
-  readonly [key: string]: Codec;
-};
-declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
-type CodecOf<S extends Codec | Fields> = S extends Codec ? S : S extends Schema.Struct.Fields ? keyof S extends never ? typeof NoInput : Extract<Schema.Struct<S>, Codec> : never;
+import { InputCheck } from "./contract/input-check.mjs";
+import { Context, Effect, Layer, Schema, Scope, Stream as Stream$1 } from "effect";
 /**
  * How the action's tool presents itself over MCP, in MCP's own names; every field is optional
  * and none enforces anything. A hint left out is MCP's default, but `destructiveHint`, which is
@@ -69,11 +72,28 @@ export interface Options {
    */
   readonly input?: Codec | Fields | undefined;
   /**
-   * A schema or struct fields. Omit for an action that returns nothing, `Schema.Void`; what each
-   * surface answers is on its `layer`, `layerHttp`, `runStdio`, `make` or `command`. A top-level field whose schema is
-   * `Action.Image` is a media field: see `Action.Image`.
+   * A schema or struct fields, or `Action.Stream(element)` for an action answering a stream of
+   * elements. Omit for an action that returns nothing, `Schema.Void`; what each surface answers
+   * is on its `layer`, `layerHttp`, `runStdio`, `make` or `command`. A top-level field whose
+   * schema is `Action.Image` is a media field: see `Action.Image`.
    */
   readonly success?: Codec | Fields | undefined;
+  /**
+   * A schema or struct fields: what the handler reports while it runs, through its second
+   * argument's `progress`, before it answers. Omit for an action that reports nothing; the
+   * handler then takes its input alone. A client's call takes `onProgress` after the input;
+   * how each surface carries progress is on `ActionHttp.layer`, `ActionRpc.make`,
+   * `ActionMcp.layerHttp`, `ActionToolkit.make` and `ActionCli.command`.
+   *
+   * **Gotchas**
+   *
+   * - Progress is a snapshot to show, not an event to count: values a caller falls behind on are dropped, the oldest first, while the answer never is.
+   * - A value breaking the schema is the call's defect, as an answer breaking `success` is.
+   * - A caller's `onProgress` that fails or dies is logged as a warning, and the call goes on and answers: the handler is never interrupted for it.
+   * - In process, `Action.client`, the toolkit and a local command hand `onProgress` each value as reported, checked by the schema and never encoded: a value with no JSON form reaches them, and is the call's defect on a surface sending JSON.
+   * - A value the caller's `progress` schema cannot decode, where client and server differ, is logged and dropped by MCP's client; RPC's and HTTP's clients decode it with the response, so the call fails with a `SchemaError`, `onProgress` given or not.
+   */
+  readonly progress?: Codec | Fields | undefined;
   /**
    * The declared failures: one schema, or a list of them, as `HttpApiEndpoint` takes them;
    * each keeps its own HTTP status annotation, the third argument of
@@ -90,7 +110,7 @@ export interface Options {
    * - An entry that is a `Schema.suspend` whose thunk reads a `const` declared further down throws a `ReferenceError` at `make`, which reads every `_tag` when called: declare the error first.
    * - A failure the schemas reject, undeclared or breaking a check, is the call's defect on every surface, beside the `SchemaError` saying why; a class error built with `disableChecks` is accepted and fails to encode instead.
    */
-  readonly error?: Codec | ReadonlyArray<Codec> | undefined;
+  readonly error?: Codec | readonly Codec[] | undefined;
   /**
    * Whether the action leaves its resource unchanged. Required: an action nobody classified
    * is the one a reviewer must check. An implementation's `authorize` may read it, and MCP's
@@ -101,25 +121,57 @@ export interface Options {
   readonly readOnly: boolean;
   /** How the action's tool presents itself over MCP, and on a native Toolkit's tools. */
   readonly mcp?: Mcp;
+  /**
+   * The input field, a string, holding the call's idempotency key: a call repeated with the key
+   * and the same input is answered as the first was, its handler run once, on every surface, as
+   * the key travels with the input. The caller makes the key at random for the call it means,
+   * and sends it again on each retry; a call without it runs as any other. What is answered
+   * again is kept by `Action.Idempotency`, which an implementation of the action requires at
+   * startup: provide `Action.layerIdempotency`, which a Durable Object's `make` and `handlers`
+   * provide over its storage.
+   *
+   * **Gotchas**
+   *
+   * - Kept are an answer and a failure the action declares or a built-in one; a defect, an interruption and a declared failure whose status is 408, 429, 500, 502, 503 or 504 are not, and the call runs again when retried: at least once, not exactly once.
+   * - A repeat with the key and another input fails with `InvalidInput`, naming the key: the key stands for one call, and a record's keys in another order are the same input.
+   * - A repeat while the first runs waits for its answer, in the same server, traced as an `Idempotency.wait` span; two servers sharing a store run both, the later answer kept.
+   * - A repeat answers without the progress the first reported.
+   * - An answer kept before a deployment changed `success` or an error schema, so that it no longer decodes, is ignored: the call runs again.
+   * - An action answering `Action.Stream` throws at `make`: an answer is kept whole.
+   * - A key is each caller's own only where the surface's authentication has `principal`: without one, as over `Action.client`, `ActionToolkit`, the CLI or a public action, another caller sending it with the same input is given the answer, as a model filling the field in may, so make it at random, never from the input.
+   */
+  readonly idempotencyKey?: string | undefined;
 }
 type UnknownMcp<O> = O extends {
   readonly mcp?: infer H;
 } ? Exclude<H extends unknown ? keyof H : never, keyof Mcp> : never;
-type KnownMcp<O> = {
+interface KnownMcp<O> {
   readonly mcp?: { readonly [K in UnknownMcp<O>]: never; };
-};
+}
+type StringFields<I> = { readonly [F in keyof I]-?: I[F] extends string | undefined ? F : never; }[keyof I] & string;
+type KnownKey<O> = O extends {
+  readonly idempotencyKey: infer K extends string;
+} ? K extends StringFields<SchemaOf<O, "input", typeof NoInput>["Type"]> ? unknown : {
+  readonly idempotencyKey: K & {
+    readonly "~": "idempotencyKey names a string field of the input";
+  };
+} : unknown;
+type KeyOf<O> = O extends {
+  readonly idempotencyKey: infer K extends string;
+} ? K : undefined;
 type ErrorMembers<G> = G extends ReadonlyArray<infer E> ? E : G;
 type OnlyOptions<O> = { readonly [K in Exclude<O extends unknown ? keyof O : never, keyof Options>]: never; };
-type Rules<O> = Options extends O ? unknown : OnlyOptions<O> & KnownMcp<O>;
+type Rules<O> = Options extends O ? unknown : OnlyOptions<O> & KnownMcp<O> & KnownKey<O>;
 type OptionOf<O, K extends keyof Options, Default> = O extends unknown ? K extends keyof O ? Exclude<O[K], undefined> | ({} extends Pick<O, K> ? Default : undefined extends O[K] ? Default : never) : Default : never;
 type SchemaOf<O, K extends "input" | "success", Default extends Codec> = CodecOf<Extract<OptionOf<O, K, Default>, Codec | Fields>>;
-type ErrorSchemasOf<O> = ReadonlyArray<ErrorMembers<Extract<OptionOf<O, "error", []>, Codec | ReadonlyArray<Codec>>>>;
+type ProgressOf<O> = [Extract<OptionOf<O, "progress", never>, Codec | Fields>] extends [never] ? undefined : CodecOf<Extract<OptionOf<O, "progress", never>, Codec | Fields>>;
+type ErrorSchemasOf<O> = ReadonlyArray<ErrorMembers<Extract<OptionOf<O, "error", []>, Codec | readonly Codec[]>>>;
 /**
  * A pure contract: schemas and transport metadata, bound to handlers by `implement`. Its
  * `name`, `input`, `success`, `error` and `readOnly` are public: reuse them, as in
  * `Schema.Array(SaveLink.input)`.
  */
-export interface Action<Name extends string, Input extends Codec, Success extends Codec, Errors extends ReadonlyArray<Codec>, ReadOnly extends boolean = boolean, Caller extends Options["caller"] = Options["caller"]> {
+export interface Action<Name extends string, Input extends Codec, Success extends Codec, ErrorSchemas extends readonly Codec[], ReadOnly extends boolean = boolean, Caller extends Options["caller"] = Options["caller"], Progress extends Codec | undefined = Codec | undefined, Key extends string | undefined = string | undefined> {
   readonly caller: Caller;
   readonly name: Name;
   readonly description: string;
@@ -130,26 +182,33 @@ export interface Action<Name extends string, Input extends Codec, Success extend
   readonly input: Input;
   readonly success: Success;
   /** The declared failures, as a list: one given alone is a list of one. */
-  readonly error: Errors;
+  readonly error: ErrorSchemas;
+  /** What the handler reports while it runs, as a schema; `undefined` where none is declared. */
+  readonly progress: Progress;
   readonly readOnly: ReadOnly;
   /** The `mcp` options as given, none when left out. */
   readonly mcp: Mcp;
+  /** The input field holding the call's idempotency key; `undefined` where none is named. */
+  readonly idempotencyKey: Key;
 }
 /** Any action, with its schemas erased. */
-export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>>;
+export type Any = Action<string, Codec, Codec, readonly Codec[]>;
 /**
  * A list of declared errors, as an action's `error` holds it, and a binding's or an
  * authentication descriptor's: `<E extends Action.Errors>` constrains one.
  */
-export type Errors = ReadonlyArray<Codec>;
-/** Receives decoded input; may fail only with the declared errors and the built-in ones. */
-export type Handler<A extends Any, R = never> = (input: A["input"]["Type"]) => Effect.Effect<A["success"]["Type"], A["error"][number]["Type"] | BuiltIn, R>;
+export type Errors = readonly Codec[];
+/**
+ * Receives decoded input, and what it reports progress by where `A` declares `progress`; may
+ * fail only with the declared errors and the built-in ones.
+ */
+export type Handler<A extends Any, R = never> = (input: A["input"]["Type"], ...reporting: ReportingOf<A>) => Answer<A["success"], A["error"][number]["Type"] | BuiltIn, R>;
 /**
  * The handlers of the actions `A`, keyed by name, as `implement` takes them: what a builder
  * written apart from `implement` returns, `satisfies Action.Handlers<typeof actions>`, so its
  * handlers are typed from their contracts, as another authorizer of the same handlers needs.
  */
-export type Handlers<A extends ReadonlyArray<Any>, R = never> = { readonly [Action in A[number] as Action["name"]]: Handler<Action, R>; };
+export type Handlers<A extends readonly Any[], R = never> = { readonly [Each in A[number] as Each["name"]]: Handler<Each, R>; };
 /**
  * Define an action contract: what it takes and answers, whether it changes anything, and who
  * may call it. The name is also the route segment, the client method and the tool name.
@@ -162,7 +221,23 @@ export type Handlers<A extends ReadonlyArray<Any>, R = never> = { readonly [Acti
  * - Surfaces match an implementation to a contract by object identity, never by name: implement, bind and list the one exported value. A list narrowed at run time is still typed as holding every member.
  * - In a helper whose type parameter stands for `mcp`, `make` refuses the option, since it cannot check the hints: type the parameter `Action.Mcp`, or spread a constant.
  */
-export declare function make<const Name extends string, const O extends Options>(name: Name, options: O & NoInfer<Rules<O>>): Action<Name, SchemaOf<O, "input", typeof NoInput>, SchemaOf<O, "success", typeof Schema.Void>, ErrorSchemasOf<O>, O["readOnly"], O["caller"]>;
+export declare function make<const Name extends string, const O extends Options>(name: Name, options: O & NoInfer<Rules<O>>): Action<Name, SchemaOf<O, "input", typeof NoInput>, SchemaOf<O, "success", typeof Schema.Void>, ErrorSchemasOf<O>, O["readOnly"], O["caller"], ProgressOf<O>, KeyOf<O>>;
+/**
+ * `action` with the errors `more` declared after its own, as if `make` had been given them in
+ * `error`: its handler may fail with them, and every surface answers and every client decodes
+ * them. For errors a module adds to the actions it serves, such as a proxy's or a store's,
+ * whose contracts are written elsewhere: `pipe(action, Action.withErrors([Unavailable]))`, or
+ * `Action.withErrors(action, [Unavailable])`.
+ *
+ * **Gotchas**
+ *
+ * - It returns a new contract with the same name: implement, bind and list the value it returns, since surfaces match a contract by identity; the original and the copy in one surface are one name held twice.
+ * - A `_tag` that `more` shares with the action's own errors or a built-in one throws as `make` throws for one `error` list: reuse the one schema value, which is declared once.
+ */
+export declare const withErrors: {
+  <const More extends Errors>(more: More): <Name extends string, Input extends Codec, Success extends Codec, ErrorSchemas extends Errors, ReadOnly extends boolean, Caller extends Options["caller"], Progress extends Codec | undefined, Key extends string | undefined>(action: Action<Name, Input, Success, ErrorSchemas, ReadOnly, Caller, Progress, Key>) => Action<Name, Input, Success, readonly [...ErrorSchemas, ...More], ReadOnly, Caller, Progress, Key>;
+  <Name extends string, Input extends Codec, Success extends Codec, ErrorSchemas extends Errors, ReadOnly extends boolean, Caller extends Options["caller"], Progress extends Codec | undefined, Key extends string | undefined, const More extends Errors>(action: Action<Name, Input, Success, ErrorSchemas, ReadOnly, Caller, Progress, Key>, more: More): Action<Name, Input, Success, readonly [...ErrorSchemas, ...More], ReadOnly, Caller, Progress, Key>;
+};
 /**
  * `actions` keyed by name, each its exact contract: `byName(actions).getUser`, its schemas
  * where a test or a mock reads them, and its types where a helper takes a name,
@@ -170,22 +245,23 @@ export declare function make<const Name extends string, const O extends Options>
  * `Extract` over the list does not. The list is typed by its members, as every surface types
  * one. A name held twice is refused, as a surface refuses it.
  */
-export declare function byName<const Actions extends ReadonlyArray<Any>>(actions: Actions): { readonly [A in Actions[number] as A["name"]]: A; };
-type Target = Any | ReadonlyArray<Any>;
+export declare function byName<const Actions extends readonly Any[]>(actions: Actions): { readonly [A in Actions[number] as A["name"]]: A; };
+type Target = Any | readonly Any[];
 type TakesNoAuthorize<T extends Target> = [Protected<ActionsOf<T>>] extends [never] ? unknown : "A protected action takes { authorize }: your rule, or Action.allowAll";
-type ActionsOf<T extends Target> = T extends ReadonlyArray<Any> ? T[number] : Extract<T, Any>;
+type ActionsOf<T extends Target> = T extends readonly Any[] ? T[number] : Extract<T, Any>;
 type NamesOf<T extends Target> = ActionsOf<T>["name"];
+type KeepsAnswers<T extends Target> = [Extract<ActionsOf<T>, {
+  readonly idempotencyKey: string;
+}>] extends [never] ? never : Idempotency;
 type NoHandler<R> = {
   readonly "~list": R;
 };
-type Single<T extends Target, R> = T extends Any ? (input: T["input"]["Type"]) => Effect.Effect<T["success"]["Type"], T["error"][number]["Type"] | BuiltIn, R> : NoHandler<R>;
+type Single<T extends Target, R> = T extends Any ? (input: T["input"]["Type"], ...reporting: ReportingOf<T>) => Answer<T["success"], T["error"][number]["Type"] | BuiltIn, R> : NoHandler<R>;
 type Several<T extends Target, RequestServices> = { readonly [K in keyof RequestServices]: K extends NamesOf<T> ? Handler<Extract<ActionsOf<T>, {
   readonly name: K;
 }>, RequestServices[K]> : never; };
 type HandlersOf<T extends Target, R, RequestServices> = Single<T, R> | Several<T, RequestServices>;
-type Deferred<T> = [T][T extends unknown ? 0 : never];
-type Authorizer<A extends Any, RA, EAX, RAX> = ((action: A) => Effect.Effect<void, Refusal, RA>) | Effect.Effect<(action: A) => Effect.Effect<void, Refusal, RA>, EAX, RAX>;
-type Implemented<T extends Target, RequestServices, R, EX, RX, RA, EAX, RAX> = Implementation<ActionsOf<T>, { readonly [K in NamesOf<T>]: Exclude<T extends ReadonlyArray<Any> ? RequestServices[K & keyof RequestServices] : R, Scope.Scope>; }, Deferred<EX>, Deferred<Exclude<RX, Scope.Scope>>, Exclude<RA, Scope.Scope>, Deferred<EAX>, Deferred<Exclude<RAX, Scope.Scope>>>;
+type Implemented<T extends Target, RequestServices, R, EX, RX, RA, EAX, RAX> = Implementation<ActionsOf<T>, { readonly [K in NamesOf<T>]: Exclude<T extends readonly Any[] ? RequestServices[K & keyof RequestServices] : R, Scope.Scope>; }, Deferred$1<EX>, Deferred$1<Exclude<RX, Scope.Scope> | KeepsAnswers<T>>, Exclude<RA, Scope.Scope>, Deferred$1<EAX>, Deferred$1<Exclude<RAX, Scope.Scope>>>;
 /** Every authenticated caller may call a protected action. */
 export declare const allowAll: Authorize<Any>;
 /**
@@ -206,12 +282,12 @@ export declare const allowAll: Authorize<Any>;
  * - What a plain `authorize` yields is a request-time requirement of every surface; to read a store once, make `authorize` an Effect that yields it and returns the function.
  * - An authorizer fails only with `Unauthenticated` or `Forbidden`; a limit callers should see, such as a rate limit, is the handler's, declared in the action's `error`.
  */
-export declare function implement<const T extends Target, RequestServices extends (T extends ReadonlyArray<Any> ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never, RA = never, EAX = never, RAX = never>(actions: T, handlers: HandlersOf<T, R, RequestServices> | Effect.Effect<HandlersOf<T, R, RequestServices>, EX, RX>, options: [Protected<ActionsOf<T>>] extends [never] ? {
+export declare function implement<const T extends Target, RequestServices extends (T extends readonly Any[] ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never, RA = never, EAX = never, RAX = never>(actions: T, handlers: HandlersOf<T, R, RequestServices> | Effect.Effect<HandlersOf<T, R, RequestServices>, EX, RX>, options: [Protected<ActionsOf<T>>] extends [never] ? {
   readonly authorize?: "A public-only target takes no authorize";
 } | undefined : {
   readonly authorize: Authorizer<Protected<ActionsOf<T>>, RA, EAX, RAX>;
 }): Implemented<T, RequestServices, R, EX, RX, RA, EAX, RAX>;
-export declare function implement<const T extends Target, RequestServices extends (T extends ReadonlyArray<Any> ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never>(actions: T & TakesNoAuthorize<T>, handlers: HandlersOf<T, R, RequestServices> | Effect.Effect<HandlersOf<T, R, RequestServices>, EX, RX>): Implemented<T, RequestServices, R, EX, RX, never, never, never>;
+export declare function implement<const T extends Target, RequestServices extends (T extends readonly Any[] ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never>(actions: T & TakesNoAuthorize<T>, handlers: HandlersOf<T, R, RequestServices> | Effect.Effect<HandlersOf<T, R, RequestServices>, EX, RX>): Implemented<T, RequestServices, R, EX, RX, never, never, never>;
 /**
  * The builders of `implementations`, as one layer providing nothing. Surfaces build them
  * themselves, once per layer graph, but routes under `HttpRouter.serve` or `Testing.layer`
@@ -224,26 +300,43 @@ export declare function implement<const T extends Target, RequestServices extend
  * - A job merged beside `HttpRouter.serve` with no `Action.layer` above both shares the server's build only when its own side builds first, which depends on timing: put the job inside the layer the server serves, or provide this layer above both.
  * - Do not wrap a server in `Layer.fresh`: two servers already share no build. It is for two surfaces in one graph that must each have a build of their own; provide what they share, authentication included, outside it.
  */
-export declare function layer<const Apps extends Served>(implementations: Apps): Layer.Layer<never, BuildError<Member<Apps>>, BuildServices<Member<Apps>>>;
-type Method<A extends Any, R> = Call<A, Effect.Effect<A["success"]["Type"], A["error"][number]["Type"] | BuiltIn, R>>;
+export declare function layer<const Apps extends Served>(implementations: Apps): Layer.Layer<never, BuildError<Member<Apps>> | EventBuildError<Member<Apps>>, BuildServices<Member<Apps>> | EventBuildServices<Member<Apps>>>;
+type Method<A extends Any, R> = Call<A, Answer<A["success"], A["error"][number]["Type"] | BuiltIn, R>>;
 /**
- * Every action of the implementations `Apps`, one or a list, as `client.<action>(input)`: what
+ * Every action of the implementations `Apps`, one or a list, as `client.<action>(input)`, or
+ * those of `Listed`, and `watch` for their event types, or those of `ListedEvents`: what
  * `client` gives, each method owing per call what its handler and `authorize` read.
  */
-export type Client<Apps extends Served, Listed extends Any = Extract<ActionOf<Member<Apps>>, Any>> = { readonly [A in Serving<Member<Apps>, Listed> as A["name"]]: Method<A, RequestOf<Member<Apps>, A>>; };
-/** What `client` takes: the actions to call. */
-export interface ClientOptions<A extends Any> {
+export type Client<Apps extends Served, Listed extends Any = Extract<ActionOf<Member<Apps>>, Any>, ListedEvents extends Any$1 = EventOf<Member<Apps>>> = { readonly [A in Serving<Member<Apps>, Listed> as A["name"]]: Method<A, RequestOf<Member<Apps>, A>>; } & Watching<Member<Apps>, ListedEvents>;
+/**
+ * Watch one of the event types of the implementations `App`, or of those among `Listed`: its
+ * occurrences, and the gaps where occurrences were missed, owing per subscription what its
+ * source and `authorize` read.
+ */
+export type Watch<App, Listed extends Any$1 = EventOf<App>> = <E extends ServingEvents<App, Listed>, SE = never>(event: E, ...args: WatchArgs<E, SE>) => Stream$1.Stream<Received<E>, SubscriptionError | BuiltIn | SE, EventRequestOf<App, E>>;
+type Watching<App, Listed extends Any$1> = [ServingEvents<App, Listed>] extends [never] ? unknown : {
+  readonly watch: Watch<App, Listed>;
+};
+/** What `client` takes: the actions to call and the event types to watch. */
+export interface ClientOptions<A extends Any | Any$1> {
   /**
-   * The actions to call, among the implementations': `[GetUser]`. Defaults to every action of
-   * them. Options whose `actions` may be absent are typed as every action, as they may run.
+   * The actions to call and the event types to watch, among the implementations':
+   * `[GetUser, UserRenamed]`, exactly those. Defaults to every one of them. Options whose
+   * `actions` may be absent are typed as every one, as they may run.
+   *
+   * **Gotchas**
+   *
+   * - A list naming actions alone watches no event type: the client has no `watch` until the event types are listed beside them.
    */
-  readonly actions?: ReadonlyArray<A> | undefined;
+  readonly actions?: readonly A[] | undefined;
 }
 /**
  * Call implementations in process: one method per action, taking its input directly as
  * `ActionHttp.client`'s methods do, `client.renameUser({ id, name })`, so moving between the
- * two changes the line acquiring it. A call runs as a remote one does, its input and its answer
- * through their JSON codecs, the implementation's `authorize` and the handler in a scope of
+ * two changes the line acquiring it; given event implementations, `watch(event, input, options)`
+ * too, for their event types or those `actions` lists, as every client of a surface serving
+ * events has it. A call runs as a remote one does, its input and its answer through their JSON
+ * codecs, the implementation's `authorize` and the handler in a scope of
  * their own, failing with the action's errors and the built-in ones. Acquiring it builds the
  * implementations' builders into the layer graph it is acquired in, as a layer does, and its
  * scope holds them: acquire it where builders live.
@@ -256,6 +349,7 @@ export interface ClientOptions<A extends Any> {
  * - 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.
  * - It drops undeclared input fields as it encodes, and fails with `InvalidInput`, running nothing, for an input that does not encode.
  * - A builder acquiring a client of its own implementation is refused by the compiler, TS7022, and with the types bypassed never completes: call the services both use instead.
+ * - `watch` runs as the caller around the stream, authorized when it starts.
  */
-export declare function client<const Apps extends Served, const O extends ClientOptions<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, ClientOptions<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, ClientOptions<Any>>>>): Effect.Effect<Client<Apps, Offered<O, ActionOf<Member<Apps>>>>, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Scope.Scope>;
-export { type AnyImplementation, Anyone, type Authorize, type BuildError, type BuildServices, BuiltIn, Forbidden, Image, type Implementation, InvalidInput, type Issue, Refusal, Unauthenticated };
+export declare function client<const Apps extends Served, const O extends ClientOptions<ActionOf<Member<Apps>> | EventOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, ClientOptions<ActionOf<Member<Apps>> | EventOf<Member<Apps>>> & O & NoInfer<Known<O, ClientOptions<Any>>>>): Effect.Effect<Client<Apps, Offered<O, ActionOf<Member<Apps>>>, Offered<O, EventOf<Member<Apps>>>>, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | EventBuildError<HoldingEvents<Member<Apps>, SelectedEventsOf<O, Apps>>, SelectedEventsOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | EventBuildServices<HoldingEvents<Member<Apps>, SelectedEventsOf<O, Apps>>, SelectedEventsOf<O, Apps>> | Scope.Scope>;
+export { type AnyImplementation, Anyone, type Authorize, type BuildError, type BuildServices, BuiltIn, Forbidden, Idempotency, Image, type Implementation, InputCheck, InvalidInput, type Issue, Refusal, Stream, type StreamOf, Unauthenticated, layerIdempotency };