@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/ActionRpc.d.mts

@@ -1,43 +1,102 @@
+import { Codec } from "./contract/codec.mjs";
 import { Anyone } from "./contract/caller.mjs";
-import { BuiltIn, BuiltIns } from "./contract/errors.mjs";
-import { BuildError, Holding, Known, Member, MiddlewareOf, Protected, Selected, Served, Serving } from "./contract/implementation.mjs";
+import { BuiltIn, BuiltIns, Unauthenticated } from "./contract/errors.mjs";
+import { EventBuildError, EventBuildServices, EventServedRequest, HoldingEvents, ServingEvents } from "./contract/feed.mjs";
+import { Any as Any$1, Received, SubscriptionError } from "./Event.mjs";
+import { BuildError, Holding, Known, Member, MiddlewareOf, Selected, SelectedEvents, Served } from "./contract/implementation.mjs";
 import { Call } from "./contract/call.mjs";
-import { Any as Any$1, Errors } from "./Action.mjs";
-import { Any as Any$2, DescriptorOf, Identity, Matching, PublicOnly, RemoteRequest, Required, ServedProvider, ServerBuildServices, VerifierError } from "./authentication/provider.mjs";
+import { Answer, StreamOf } from "./contract/stream.mjs";
+import { WatchArgs } from "./contract/watch.mjs";
+import { Any as Any$2, Errors } from "./Action.mjs";
 import { Certain, ErrorsOf } from "./contract/declared.mjs";
-import { Context, Effect, Layer, Schema, Scope, Types } from "effect";
-import { HttpRouter } from "effect/http";
-import { Rpc, RpcClient, RpcClientError, RpcGroup, RpcMiddleware, RpcServer } from "effect/rpc";
-//#region src/rpc/ActionRpc.d.ts
+import { Any as Any$3, Descriptor, DescriptorOf, LayerIdentity, Matching, ProviderOf, PublicOnly, RemoteRequest, Required, Security, ServedProvider, ServerBuildServices, VerifierError } from "./authentication/provider.mjs";
+import { Only } from "./contract/listed.mjs";
+import { PushedOf, SubscriptionOf } from "./contract/push.mjs";
+import { Context, Effect, Layer, Schedule, Schema, Scope, Stream, Types } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+import { Rpc, RpcClient, RpcClientError, RpcGroup, RpcMessage, RpcMiddleware, RpcSchema, RpcServer } from "effect/rpc";
 type BindingError = Errors[number];
-type ErrorOf<A extends Any$1, E extends Errors, D> = Schema.Union<ReadonlyArray<A["error"][number] | E[number] | VerifierError<A, D> | BuiltIns>>;
-type RpcOf<A extends Any$1, E extends Errors, D> = A extends Any$1 ? Rpc.Rpc<A["name"], A["input"], A["success"], ErrorOf<A, E, D>> : never;
+type ErrorOf<A extends Any$2, E extends Errors, D> = Schema.Union<ReadonlyArray<A["error"][number] | E[number] | VerifierError<A, D> | BuiltIns>>;
 /**
- * An RPC binding: actions, the errors every rpc declares, and the descriptor authenticating
- * its protected ones. Plain data, so a copy of it, or one made by another installed copy of
- * this package, serves the same; `layer` serves it and `client` calls it.
+ * What the stream rpc of an action declaring `progress` sends: a `Progress` for each value its
+ * handler reports, then a `Final` with its answer.
  */
-export interface Binding<Actions extends ReadonlyArray<Any$1>, E extends Errors = [], D extends Any$2 | undefined = undefined> {
+declare const ProgressedOf: <P extends Codec, S extends Codec>(progress: P, success: S) => Schema.Union<readonly [Schema.TaggedStruct<"Progress", {
+  readonly value: P;
+}>, Schema.TaggedStruct<"Final", {
+  readonly value: S;
+}>]>;
+/**
+ * What the stream rpc of an action answering a stream sends: an `Element` for each element, and a
+ * `Progress` for each value its handler reports where it declares `progress`.
+ */
+type ElementedOf<Element extends Schema.Constraint, P> = Schema.Union<readonly [Schema.TaggedStruct<"Element", {
+  readonly value: Element;
+}>, ...(P extends Codec ? [Schema.TaggedStruct<"Progress", {
+  readonly value: P;
+}>] : [])]>;
+type RpcOf<A extends Any$2, E extends Errors, D> = A extends Any$2 ? A["success"] extends StreamOf<infer Element> ? Rpc.Rpc<A["name"], A["input"], RpcSchema.Stream<ElementedOf<Element, A["progress"]>, ErrorOf<A, E, D>>> : A["progress"] extends Codec ? Rpc.Rpc<A["name"], A["input"], RpcSchema.Stream<ReturnType<typeof ProgressedOf<A["progress"], A["success"]>>, ErrorOf<A, E, D>>> : Rpc.Rpc<A["name"], A["input"], A["success"], ErrorOf<A, E, D>> : never;
+type EventRpcOf<V extends Any$1, E extends Errors, D> = V extends Any$1 ? Rpc.Rpc<V["name"], ReturnType<typeof SubscriptionOf<V>>, RpcSchema.Stream<ReturnType<typeof PushedOf<V>>, Schema.Union<ReadonlyArray<E[number] | VerifierError<V, D> | BuiltIns>>>> : never;
+declare const authenticatedKey = "effect-actions/ActionRpc/Authenticated";
+type RefusalOf<E extends Errors> = Schema.Union<ReadonlyArray<typeof Unauthenticated | E[number]>>;
+declare const authenticatedBrand: unique symbol;
+/**
+ * The middleware authenticating a binding's native rpcs, as Effect's server reads it: what it
+ * provides their handlers, and what it fails with.
+ */
+interface Authenticated<I, E extends Errors = Errors> {
+  readonly [authenticatedBrand]: typeof authenticatedBrand;
+  readonly [RpcMiddleware.TypeId]: {
+    readonly provides: I;
+    readonly requires: never;
+    readonly error: RefusalOf<E>;
+    readonly clientError: never;
+  };
+}
+type AuthenticatedOf<D> = D extends Descriptor<infer I, unknown, Security, string, infer E> ? RpcMiddleware.ServiceClass<Authenticated<I, E>, typeof authenticatedKey, I, RefusalOf<E>, never, never, false> : never;
+type NativeOf<N extends Rpc.Any, D> = [D] extends [Any$3] ? Rpc.AddMiddleware<N, AuthenticatedOf<D>> : N;
+/**
+ * An RPC binding: actions, event types, the errors every rpc declares, the descriptor
+ * authenticating its protected ones, and the native rpcs it serves beside them. Plain data, so a
+ * copy of it, or one made by another installed copy of this package, serves the same; `layer`
+ * serves it and `client` calls it.
+ */
+export interface Binding<Actions extends readonly Any$2[], E extends Errors = [], D extends Any$3 | undefined = undefined, Events extends readonly Any$1[] = readonly [], N extends Rpc.Any = never> {
   /** The descriptor authenticating its protected actions, or `undefined` when it names none. */
   readonly authentication: D;
   /** The exact actions bound to this binding. */
   readonly actions: Actions;
+  /** The exact event types bound to this binding, each a stream rpc named after it. */
+  readonly events: Events;
   /** The errors every rpc declares besides its action's own, as a list. */
   readonly error: E;
   /**
-   * The native group of one rpc per action, named after it, as clients see it:
+   * The native rpcs `make`'s `rpcs` gave, as served: under an `authentication`, each runs
+   * behind the middleware authenticating it, which provides its handler the identity. A host
+   * implements them with `rpcs.toLayer`.
+   */
+  readonly rpcs: RpcGroup.RpcGroup<NativeOf<N, D>>;
+  /**
+   * The native group of one rpc per action, named after it, one stream rpc per event type,
+   * taking `{ input, cursor }`, `cursor: null` reading from now, and `rpcs`, as clients see it:
    * `RpcClient.make(Rpc.group)` is the native client.
+   *
+   * **Gotchas**
+   *
+   * - `layer` hands the protocol an action's and an event type's values as their JSON, the native `rpcs`' as they are: under a codec other than a JSON serialization's, such as schema-binary's or a protocol passing values, `RpcClient.make(Rpc.group)` decodes an action's answer or an event's occurrence by its own schema and fails; call actions and watch events through `client`, which hands them over as JSON too.
    */
-  readonly group: RpcGroup.RpcGroup<RpcOf<Actions[number], E, D>>;
+  readonly group: RpcGroup.RpcGroup<RpcOf<Actions[number], E, D> | EventRpcOf<Events[number], E, D> | NativeOf<N, D>>;
 }
 /**
- * Any RPC binding. Its group is any native group here, since native groups are invariant in
+ * Any RPC binding. Its groups are any native groups here, since native groups are invariant in
  * their rpcs; `actions` carries the types.
  */
 export interface Any {
-  readonly authentication?: Any$2 | undefined;
-  readonly actions: ReadonlyArray<Any$1>;
+  readonly authentication?: Any$3 | undefined;
+  readonly actions: readonly Any$2[];
+  readonly events: readonly Any$1[];
   readonly error: Errors;
+  readonly rpcs: RpcGroup.Any;
   readonly group: RpcGroup.Any;
 }
 /** Contract-level configuration shared by servers and clients. */
@@ -51,22 +110,48 @@ export interface Options<E extends Errors = Errors> {
    * `Authentication.make(...)` of the protected actions' identity, which authenticates each of
    * their messages: required when the binding holds a protected action, and of its identity.
    */
-  readonly authentication?: Any$2;
+  readonly authentication?: Any$3;
+  /**
+   * Native rpcs the binding serves beside its actions and event types, with their own schemas
+   * and handlers: `RpcGroup.make(Upload)`. Under an `authentication`, each of their messages
+   * authenticates as a protected action's does: its handler reads the identity, and a refusal
+   * fails the call with `Unauthenticated`.
+   *
+   * **Gotchas**
+   *
+   * - `layer` requires their handlers, which the host provides from the binding's own `rpcs`: `Rpc.rpcs.toLayer(handlers)`, whose types then leave the identity unowed.
+   * - A native rpc runs no implementation's `authorize`: its handler authorizes the identity itself, as an action's `authorize` would, or every authenticated caller is served.
+   * - The layer's `middleware` runs on actions and event types alone: a native rpc runs the native middleware its group adds, inside its authentication.
+   * - Native middleware added to the binding's `rpcs` after `make` runs outside the authentication, before the identity exists; added to the group given here, inside it.
+   * - `layer` refuses a protected binding holding a native rpc without its authentication, such as one added with `rpcs.add` after `make`: add rpcs to the group given here.
+   * - A native rpc named after an action, an event type or a name the client keeps, `then` or `watch`, its method of events, is refused as the binding is made.
+   */
+  readonly rpcs?: RpcGroup.Any;
 }
+type RpcsOf<O> = O extends {
+  readonly rpcs: infer G;
+} ? RpcGroup.Rpcs<G> : never;
 /**
  * Bind actions once, for servers and clients alike, each as an rpc named after it, taking
- * its action's input and answering its success. Every rpc declares its action's errors, the
- * binding's `error`, and the built-in `InvalidInput`, `Unauthenticated` and `Forbidden`, so
- * clients decode each as a typed failure; a protected one also declares what its descriptor's
- * verifier fails with. Browser-safe, as an HTTP binding is.
+ * its action's input and answering its success, and event types, each a stream rpc named after
+ * it, taking `{ input, cursor }`. Every rpc declares its action's errors, the binding's `error`,
+ * and the built-in `InvalidInput`, `Unauthenticated` and `Forbidden`, so clients decode each as
+ * a typed failure; a protected one also declares what its descriptor's verifier fails with.
+ * `rpcs` adds native ones beside them. Browser-safe, as an HTTP binding is.
  * Guide: `docs/ActionRpc.md` in this package; in an application: `examples/live-rpc/`.
+ *
+ * **Gotchas**
+ *
+ * - An action, an event type and a native rpc of one name throw when `make` is called: they would share a client's method.
+ * - An action declaring `progress` is a stream rpc taking its input, streaming `{ _tag: "Progress", value }` for each value its handler reports, then one `{ _tag: "Final", value }` holding its answer: the native client's method of it returns a `Stream`.
+ * - An action answering a stream, `Action.Stream`, is a stream rpc taking its input, streaming `{ _tag: "Element", value }` for each element, beside `{ _tag: "Progress", value }` for each value where it declares `progress`; `client`'s method returns a `Stream` of the elements.
  */
-export declare function make<const Actions extends ReadonlyArray<Any$1 & {
+export declare function make<const Contracts extends ReadonlyArray<(Any$2 | Any$1) & {
   readonly caller: typeof Anyone;
-}>>(actions: Actions): Binding<Actions, [], undefined>;
-export declare function make<const Actions extends ReadonlyArray<Any$1>, const O extends Options = {}>(actions: Actions, options: O & Required<Actions[number]> & Matching<Actions[number], NoInfer<DescriptorOf<O>>> & NoInfer<Known<O, Options>>): Binding<Actions, ErrorsOf<O>, DescriptorOf<O>>;
-export declare function make<const Actions extends ReadonlyArray<Any$1>>(actions: Actions & PublicOnly<Actions>): Binding<Actions, [], undefined>;
-type Middleware = ReadonlyArray<RpcMiddleware.AnyService>;
+}>>(contracts: Contracts): Binding<Only<Contracts, Any$2>, [], undefined, Only<Contracts, Any$1>>;
+export declare function make<const Contracts extends ReadonlyArray<Any$2 | Any$1>, const O extends Options = {}>(contracts: Contracts, options: O & Required<Contracts[number]> & Matching<Contracts[number], NoInfer<DescriptorOf<O>>> & NoInfer<Known<O, Options>>): Binding<Only<Contracts, Any$2>, ErrorsOf<O>, DescriptorOf<O>, Only<Contracts, Any$1>, RpcsOf<O>>;
+export declare function make<const Contracts extends ReadonlyArray<Any$2 | Any$1>>(contracts: Contracts & PublicOnly<Contracts>): Binding<Only<Contracts, Any$2>, [], undefined, Only<Contracts, Any$1>>;
+type Middleware = readonly RpcMiddleware.AnyService[];
 type IdOf<K> = K extends Context.Key<infer I extends RpcMiddleware.AnyId, unknown> ? I : never;
 type Through<M extends Middleware, R> = number extends M["length"] ? R | RpcMiddleware.Requires<IdOf<M[number]>> : M extends readonly [infer K, ...infer Rest extends Middleware] ? Through<Rest, true extends Types.IsUnion<IdOf<K>> ? R | RpcMiddleware.Requires<IdOf<K>> : RpcMiddleware.ApplyServices<IdOf<K>, R>> : R;
 type ForClient<K> = K extends {
@@ -75,19 +160,24 @@ type ForClient<K> = K extends {
 type ServerOnly<M extends Middleware, E extends Errors> = [Exclude<RpcMiddleware.Error<IdOf<M[number]>>, Extract<Certain<E>, BindingError>["Type"] | BuiltIn> | ForClient<M[number]>] extends [never] ? unknown : {
   readonly "Layer middleware fails only with the binding's errors and needs no client": never;
 };
-type LayerRequest<App, A extends Any$1, M extends Middleware> = Exclude<Through<M, RemoteRequest<App, A>>, [Extract<Serving<App, A>, {
-  readonly caller: typeof Anyone;
-}>] extends [never] ? Identity<Protected<Serving<App, A>>> : never>;
-type RpcLayer<B extends Any, Apps extends Served, M extends Middleware, A extends Any$1 = B["actions"][number]> = Layer.Layer<never, BuildError<Holding<Member<Apps>, A>, A>, ServerBuildServices<Holding<Member<Apps>, A>, A> | RpcServer.Protocol | HttpRouter.Request.From<"Requires", LayerRequest<Member<Apps>, A, M>> | ServedProvider<Member<Apps>, A, B extends {
+type LayerRequest<App, A extends Any$2, E extends Any$1, M extends Middleware> = Exclude<Through<M, RemoteRequest<App, A> | EventServedRequest<App, E>>, HttpServerRequest.HttpServerRequest | HttpServerRequest.ParsedSearchParams | LayerIdentity<App, A, E>>;
+type RpcLayer<B extends Any, Apps extends Served, M extends Middleware, A extends Any$2 = B["actions"][number], E extends Any$1 = B["events"][number]> = Layer.Layer<never, BuildError<Holding<Member<Apps>, A>, A> | EventBuildError<HoldingEvents<Member<Apps>, E>, E>, ServerBuildServices<Holding<Member<Apps>, A>, A> | EventBuildServices<HoldingEvents<Member<Apps>, E>, E> | RpcServer.Protocol | HttpRouter.Request.From<"Requires", LayerRequest<Member<Apps>, A, E, M>> | ServedProvider<Member<Apps>, A, B extends {
+  readonly authentication: infer D;
+} ? D : never, ServingEvents<Member<Apps>, E>> | IdOf<M[number]> | NativeServer<RpcGroup.Rpcs<B["rpcs"]>, B extends {
   readonly authentication: infer D;
-} ? D : never> | IdOf<M[number]>>;
+} ? D : never>>;
+type NativeServer<N extends Rpc.Any, D> = [N] extends [never] ? never : Rpc.ToHandler<N> | Exclude<Rpc.Middleware<N>, Authenticated<unknown>> | Rpc.ServicesServer<N> | ProviderOf<D>;
 /** `ActionRpc.layer`'s options. */
-export interface LayerOptions<M extends Middleware = [], A extends Any$1 = never> {
+export interface LayerOptions<M extends Middleware = [], C extends Any$2 | Any$1 = never> {
   /**
-   * The actions it serves, among the binding's actions the implementations hold: `[GetUser]`.
-   * Defaults to every one of them.
+   * The actions and event types it serves, among the binding's the implementations hold:
+   * `[GetUser, UserRenamed]`, exactly those. Defaults to every one of them.
+   *
+   * **Gotchas**
+   *
+   * - A list naming actions alone serves no event type: a client's watch fails with `Event.SubscriptionError`, reason `NotServed`, until the event types are listed beside them.
    */
-  readonly actions?: ReadonlyArray<A> | undefined;
+  readonly actions?: readonly C[] | undefined;
   /**
    * Native rpc middleware every served rpc runs on each message, the first innermost: inside
    * the authentication of a protected rpc, so none provides what a verifier reads, and outside
@@ -96,21 +186,60 @@ export interface LayerOptions<M extends Middleware = [], A extends Any$1 = never
    *
    * **Gotchas**
    *
-   * - A middleware requiring the identity leaves it owed on a layer serving a public action: bind the protected actions apart, or read the identity with `Effect.serviceOption`, which a public rpc's call lacks.
+   * - A middleware requiring the identity leaves it owed on a layer serving a public action or event type: bind the protected ones apart, or read the identity with `Effect.serviceOption`, which a public rpc's call lacks.
    * - A middleware provides a service only to those listed before it and the handlers, and only in a list written in place as a tuple: listed earlier, or in an array-typed list, it leaves the service owed.
    * - Router middleware around the layer runs once per WebSocket, at its upgrade, so its value holds for the whole connection: what differs per message needs a listed middleware.
+   * - On an event's stream rpc, a middleware and the authentication run once, around the subscription's admission, not its stream: one timing the call or releasing something as it ends sees it end as the stream starts, and never sees a later refusal; what it provides lasts the stream.
+   * - On the stream rpc of an action declaring `progress` or answering a stream they run around its start alike, before its handler runs: one timing it sees it end before the handler does, and never sees its failure; what it provides lasts the handler.
    */
   readonly middleware?: M;
 }
 /**
- * Serve the binding's actions among `implementations` with Effect's own `RpcServer`, or those
- * its `actions` lists, as `ActionHttp.layer` selects them, under the protocol and JSON
- * serialization the host provides. Each message of a protected rpc authenticates from its own
- * headers with the binding's descriptor; then the listed `middleware` runs, the input decodes,
- * and the implementation's `authorize` and the handler run, as on every surface. The layer
- * fails as the builders do and needs at startup what they need; per request it owes, as router
- * request markers, what the authorizers and handlers read until its `middleware` provides it,
- * or, over a router-mounted protocol, the route's request context.
+ * One event subscription a `SubscriptionKeeper` keeps, as it arrived: the request a keeper writes
+ * to the server again, once restarted, with the payload `resumeFrom` gave for the last value sent.
+ */
+export interface KeptSubscription {
+  readonly clientId: number;
+  readonly requestId: string | number;
+  readonly tag: string;
+  /** The subscription's payload, an object of its `input` and the `cursor` it resumes from. */
+  readonly payload: Schema.Json;
+  /** The headers the request was authenticated with, which a resumed one is authenticated with again. */
+  readonly headers: ReadonlyArray<readonly [string, string]>;
+  /**
+   * The payload that resumes the subscription after `values`, a chunk sent for it, or
+   * `undefined` where they reach no position.
+   */
+  readonly resumeFrom: (values: RpcMessage.ResponseChunkEncoded["values"]) => Schema.Json | undefined;
+}
+/**
+ * What a protocol keeping event subscriptions across restarts of its server offers under
+ * `subscriptionKeeper`, as the Cloudflare package's `layerWebSocket` does: `layer` hands it each
+ * subscription once admitted, and sends every position the subscription reaches, with no
+ * 30-second heartbeat, whose timer would keep such a host awake.
+ */
+export interface SubscriptionKeeper {
+  readonly keep: (subscription: KeptSubscription) => Effect.Effect<void>;
+}
+/** The key a protocol sets to its `SubscriptionKeeper` on its `RpcServer.Protocol` service. */
+export declare const subscriptionKeeper: unique symbol;
+/**
+ * The key a protocol answering each call once sets to `true` on its `RpcServer.Protocol`
+ * service, as the Cloudflare package's stub protocol does, since Effect's protocol has no flag of
+ * its own for it: `layer` refuses to serve a streaming action, an event type or a native stream
+ * rpc on it, where a stream is answered with a defect at its first element and one with none
+ * waits for good.
+ */
+export declare const unaryProtocol: unique symbol;
+/**
+ * Serve the binding's actions and event types among `implementations` with Effect's own
+ * `RpcServer`, or those its `actions` lists, as `ActionHttp.layer` selects them, under the
+ * protocol and serialization the host provides. Each message of a protected rpc authenticates
+ * from its own headers with the binding's descriptor; then the listed `middleware` runs, the
+ * input decodes, and the implementation's `authorize` and the handler run, as on every surface.
+ * The layer fails as the builders do and needs at startup what they need; per request it owes,
+ * as router request markers, what the authorizers and handlers read until its `middleware`
+ * provides it, or, over a router-mounted protocol, the route's request context.
  * A protected action's identity comes from its authentication alone.
  *
  * **Gotchas**
@@ -121,22 +250,40 @@ export interface LayerOptions<M extends Middleware = [], A extends Any$1 = never
  * - A defect, an undeclared failure, a middleware that throws, or a success or an error that does not encode ends that call with an `Error` whose message is `Internal server error`, its cause logged and reported to the call's `ErrorReporter`s; the connection's other calls go on.
  * - An `ErrorReporter` is given only what ends a call with `Internal server error`, never a declared failure, a refusal or `InvalidInput`, unlike `ActionHttp.layer`'s `Info`: an alert counting declared failures counts none from rpcs.
  * - An rpc's credential is read from its headers alone: an API key `in: "query"` never reaches authentication.
- * - Over a protocol with no router, such as `RpcServer.layerProtocolSocketServer` or `layerProtocolStdio`, there is no HTTP request or route: a provider publishing a `protectedResource` leaves `HttpRouter` owed, and a verifier yielding a request service leaves it owed.
+ * - Over a protocol with no router, such as `RpcServer.layerProtocolSocketServer` or `layerProtocolStdio`, there is no route: a provider publishing a `protectedResource` leaves `HttpRouter` owed; the request a handler or a verifier reads is, on every protocol, one holding the message's headers, at `/`, with no query or body.
+ * - An event's stream rpc takes `{ input, cursor }`, a `cursor` omitted or `null` reading from now, and streams `Checked`, `Occurrence`, `Gap` and `Failed`, a `Checked` every 30 seconds; over `RpcServer.layerProtocolHttp` serialize with `RpcSerialization.layerNdjson`: under `layerJson` a response is sent once its streams end, so a watch never answers.
+ * - A subscription refused when it starts or later ends its stream rpc with the refusal as the typed failure; a source's failure no refusal explains is logged and reported once, sent as a bare `Failed`, and read again from where it reached after 5 seconds.
+ * - A stream is read only as fast as its client reads it: a slow reader of a log source falls behind its log, and receives a `Gap`.
+ * - An action declaring `progress` streams it to every call, a client's call without `onProgress` too, its values handed on one at a time, so a slow reader drops the oldest; under `RpcSerialization.layerJson` over HTTP they arrive with the answer, at the end.
+ * - A failure after an action's progress or its first element ends its stream rpc as it ends any call: a declared failure as the typed failure, a defect as `Internal server error`.
+ * - The binding's native `rpcs` are served on the same protocol with their own schemas, every one, whatever `actions` lists, and their handlers are owed until provided: `Rpc.rpcs.toLayer(handlers)`; a native rpc's defect or undeclared failure is answered as Effect's server answers it, never `Internal server error`, and only its verifier's defect is.
+ * - On a protocol answering each call once, one setting `unaryProtocol`, such as a Durable Object stub's, the build fails while it would serve a streaming action, an event type or a native stream rpc.
  */
 export declare function layer<const B extends Any, const Apps extends Served>(binding: B, implementations: Apps): RpcLayer<B, Apps, []>;
-export declare function layer<const B extends Any, const Apps extends Served, const O extends LayerOptions<Middleware, B["actions"][number]>>(binding: B, implementations: Apps, options: O & ServerOnly<MiddlewareOf<O, Middleware>, B["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): RpcLayer<B, Apps, MiddlewareOf<O, Middleware>, Selected<O, B["actions"][number]>>;
+export declare function layer<const B extends Any, const Apps extends Served, const O extends LayerOptions<Middleware, B["actions"][number] | B["events"][number]>>(binding: B, implementations: Apps, options: O & ServerOnly<MiddlewareOf<O, Middleware>, B["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): RpcLayer<B, Apps, MiddlewareOf<O, Middleware>, Selected<O, B["actions"][number]>, SelectedEvents<O, B["events"][number]>>;
 /**
  * What one call of an action `A` fails with, beside the binding's errors `E`: its declared and
  * built-in errors, and Effect's own `RpcClientError` when the server could not be reached. An
  * answer that does not decode is a defect, as the native client makes it.
  */
-export type MethodError<A extends Any$1, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | RpcClientError.RpcClientError;
-type Method<A extends Any$1, E extends BindingError> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E>>>;
+export type MethodError<A extends Any$2, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | RpcClientError.RpcClientError;
+type Method<A extends Any$2, E extends BindingError> = Call<A, Answer<A["success"], MethodError<A, E>, never>>;
+/**
+ * What a watch of `W` over the binding `B` may fail with: a refusal, when it starts or later,
+ * `InvalidInput`, the binding's errors, an `Event.SubscriptionError` (`Unsupported` for
+ * `mode: "poll"`, which rpcs do not serve, `NotServed` for an event the server does not serve), or
+ * Effect's own `RpcClientError` that no reconnect outlasts. An element that does not decode is a defect, as for a call.
+ */
+export type WatchError<W extends Any$1, B extends Any> = SubscriptionError | BuiltIns["Type"] | B["error"][number]["Type"] | VerifierError<W, B["authentication"]>["Type"] | RpcClientError.RpcClientError;
+type Watching<B extends Any> = [B["events"][number]] extends [never] ? unknown : {
+  readonly watch: <W extends B["events"][number], SE = never>(event: W, ...args: WatchArgs<W, SE>) => Stream.Stream<Received<W>, WatchError<W, B> | SE>;
+};
 /**
  * Every action of the binding `B`, as `client.<action>(input)`: a protected one may also fail
- * with what its descriptor's verifier declares.
+ * with what its descriptor's verifier declares. Where `B` lists event types, `watch(event, input,
+ * options)` streams one; each native rpc of its `rpcs` is the native client's method.
  */
-export type Client<B extends Any> = { readonly [A in B["actions"][number] as A["name"]]: Method<A, B["error"][number] | VerifierError<A, B["authentication"]>>; };
+export type Client<B extends Any> = { readonly [A in B["actions"][number] as A["name"]]: Method<A, B["error"][number] | VerifierError<A, B["authentication"]>>; } & Watching<B> & RpcClient.RpcClient<RpcGroup.Rpcs<B["rpcs"]>, RpcClientError.RpcClientError>;
 /**
  * The native `RpcClient.make` options `client` takes: `spanPrefix`, `spanAttributes`,
  * `generateRequestId` and `disableTracing`. `flatten` changes the client's shape, which the
@@ -148,15 +295,33 @@ export type ClientOptions = Omit<NonNullable<Parameters<typeof RpcClient.make>[1
  * directly: `client.greet({ name })`, as `ActionHttp.client`'s, the argument omitted when `{}`
  * is a valid input, each call failing with its `MethodError`. Requires the native client
  * `Protocol` and a `Scope`, as `RpcClient.make` does; headers set with `RpcClient.withHeaders`
- * around a call go with its message. The native client stays available:
- * `RpcClient.make(Rpc.group)`.
+ * around a call go with its message, and the binding's native `rpcs` are its methods too. The
+ * native client stays available under a JSON serialization: `RpcClient.make(Rpc.group)`.
  *
  * **Gotchas**
  *
  * - It drops undeclared input fields as it encodes, and fails with `InvalidInput`, sending nothing, for an input that does not encode.
  * - A browser WebSocket cannot set an `Authorization` header on its upgrade, so under Bearer a protected call without its own token fails with `Unauthenticated`, `A bearer token is required.`: send the token on each call with `RpcClient.withHeaders`.
  * - The socket belongs to the Layer providing the protocol, not to the `Scope` around the client: provided around one call, it opens a socket for that call alone.
+ * - `watch(event, input, options)` holds the event's stream rpc open, as `Action.client`'s does; `mode: "poll"` fails with `Event.SubscriptionError`, reason `Unsupported`, since rpcs serve no poll, and a watch of an event the server does not serve fails with it, reason `NotServed`, as over HTTP.
+ * - A watch reconnects after the protocol's socket or HTTP transport fails, a response ends before its stream does, as a server's restart ends it, a status a server sends while it recovers, or, over Effect's HTTP protocol, 60 seconds without an element, a socket's own pings telling a dead one, a second later and doubling to 30 seconds, each reconnect logged as a warning; a declared error, a refusal included, or a socket's close with an application's code, 4000 to 4999, ends it.
+ * - A native rpc of the binding's `rpcs` is the native client's method: a stream rpc's is a `Stream`, its headers given as its options' `headers`, since `RpcClient.withHeaders` wraps an Effect.
+ */
+export declare function client<const B extends Any>(binding: B, options?: ClientOptions): Effect.Effect<Client<B>, never, RpcClient.Protocol | Scope.Scope | Rpc.MiddlewareClient<RpcGroup.Rpcs<B["rpcs"]>>>;
+/**
+ * A socket client's `retryPolicy`, for `RpcClient.layerProtocolSocket`, that stops connecting
+ * again once the server closes the socket with one of `codes`, such as a refusal of its upgrade:
+ * until then it is Effect's own default, `Schedule.min([Schedule.exponential(500, 1.5),
+ * Schedule.spaced(5000)])`, which Effect does not export. A page refused with its code stops, its
+ * calls and streams failing with an `RpcClientError` whose `reason` is that `SocketCloseError`,
+ * its `code` the one it closed with.
+ *
+ * **Gotchas**
+ *
+ * - A client without it connects again after a refusal as after any close, every five seconds for good.
+ * - Any other socket error, a drop included, is retried as Effect's default retries it.
  */
-export declare function client<const B extends Any>(binding: B, options?: ClientOptions): Effect.Effect<Client<B>, never, RpcClient.Protocol | Scope.Scope>;
-//#endregion
+export declare const reconnectUntil: (...codes: readonly number[]) => Schedule.Schedule<import("effect/Duration").Duration, {
+  readonly reason: unknown;
+}, never, never>;
 export {};