@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/contract/idempotency.d.mts

@@ -0,0 +1,47 @@
+import "./implementation.mjs";
+import "../Action.mjs";
+import { Context, Effect, Layer, Schema } from "effect";
+declare const Kept: Schema.Struct<{
+  readonly input: Schema.String;
+  readonly outcome: Schema.String;
+  readonly at: Schema.Finite;
+}>;
+type Kept = typeof Kept.Type;
+declare const Idempotency_base: Context.ServiceClass<Idempotency, "effect-actions/Action/Idempotency", {
+  /** What was kept under `id`, or `undefined`; one kept longer than 24 hours may be either. */
+  readonly get: (id: string) => Effect.Effect<Kept | undefined>;
+  /** Keeps `kept` under `id`, replacing what was. */
+  readonly set: (id: string, kept: Kept) => Effect.Effect<void>;
+}>;
+/**
+ * Where the answers of calls given an idempotency key are kept, by the action's name and a
+ * SHA-256 digest in hex of the key and its caller's principal, `<action>/<digest>`, for 24 hours
+ * at least: what an implementation of an action naming `idempotencyKey` requires at startup.
+ * `layerIdempotency` keeps them in memory; a Durable Object's `make` and `handlers` provide one
+ * over its storage; another store, shared by several servers, implements `get` and `set`, keeping
+ * `Idempotency.Kept` at least `Idempotency.keptFor` milliseconds.
+ *
+ * **Gotchas**
+ *
+ * - Provide one per server, around the surfaces: an implementation built in another layer graph keeps its own.
+ * - A server waits for a repeat's first call itself, in memory: two servers sharing a store run a call each, the later answer kept.
+ */
+export declare class Idempotency extends Idempotency_base {
+  /**
+   * What is kept of a call answered under its key: the digest of its input, its outcome as JSON,
+   * and when it was kept, in milliseconds since the epoch.
+   */
+  static readonly Kept: Schema.Struct<{
+    readonly input: Schema.String;
+    readonly outcome: Schema.String;
+    readonly at: Schema.Finite;
+  }>;
+  /** How long, in milliseconds, a kept answer is kept at least: 24 hours. */
+  static readonly keptFor: number;
+}
+/**
+ * `Idempotency` in the server's memory, each answer kept 24 hours after it was kept: lost when
+ * the server stops, and kept apart from every other server's.
+ */
+export declare const layerIdempotency: Layer.Layer<Idempotency>;
+export {};

package/dist/contract/idempotency.mjs

@@ -0,0 +1,99 @@
+import { CallerKeyed, principalOf } from "./caller.mjs";
+import { InvalidInput } from "./errors.mjs";
+import { declaredStatus, isTransientStatus } from "./status.mjs";
+import { projectedErrors } from "./declared.mjs";
+import { answered } from "./implementation.mjs";
+import { canonicalInput } from "./canonical.mjs";
+import { sha256Hex } from "./digest.mjs";
+import { Cause, Clock, Context, Deferred, Effect, Exit, Layer, Option, Predicate, Schema } from "effect";
+// src/contract/idempotency.ts
+const Kept = Schema.Struct({
+	input: Schema.String,
+	outcome: Schema.String,
+	at: Schema.Finite
+});
+const keptFor = 864e5;
+/**
+* Where the answers of calls given an idempotency key are kept, by the action's name and a
+* SHA-256 digest in hex of the key and its caller's principal, `<action>/<digest>`, for 24 hours
+* at least: what an implementation of an action naming `idempotencyKey` requires at startup.
+* `layerIdempotency` keeps them in memory; a Durable Object's `make` and `handlers` provide one
+* over its storage; another store, shared by several servers, implements `get` and `set`, keeping
+* `Idempotency.Kept` at least `Idempotency.keptFor` milliseconds.
+*
+* **Gotchas**
+*
+* - Provide one per server, around the surfaces: an implementation built in another layer graph keeps its own.
+* - A server waits for a repeat's first call itself, in memory: two servers sharing a store run a call each, the later answer kept.
+*/
+var Idempotency = class extends Context.Service()("effect-actions/Action/Idempotency") {
+	/**
+	* What is kept of a call answered under its key: the digest of its input, its outcome as JSON,
+	* and when it was kept, in milliseconds since the epoch.
+	*/
+	static Kept = Kept;
+	/** How long, in milliseconds, a kept answer is kept at least: 24 hours. */
+	static keptFor = keptFor;
+};
+/**
+* `Idempotency` in the server's memory, each answer kept 24 hours after it was kept: lost when
+* the server stops, and kept apart from every other server's.
+*/
+const layerIdempotency = Layer.sync(Idempotency)(() => {
+	const held = /* @__PURE__ */ new Map();
+	return Idempotency.of({
+		get: (id) => Effect.sync(() => held.get(id)),
+		set: (id, kept) => Effect.sync(() => {
+			held.delete(id);
+			held.set(id, kept);
+			for (const [oldest, { at }] of held) {
+				if (at > kept.at - keptFor) break;
+				held.delete(oldest);
+			}
+		})
+	});
+});
+/**
+* `handle`, answering a call given `action`'s idempotency key as the first call with it and the
+* same input was answered: from `store`, or, while that call runs, once it has.
+*/
+const keyed = (action, store, handle) => {
+	const field = action.idempotencyKey;
+	if (field === void 0) return handle;
+	const Outcome = Schema.fromJsonString(Schema.toCodecJson(Schema.Exit(action.success, Schema.Union(projectedErrors(action)), Schema.Never)));
+	const encodeOutcome = Schema.encodeUnknownEffect(Outcome);
+	const decodeOutcome = Schema.decodeUnknownOption(Outcome);
+	const isTransientFailure = Schema.is(Schema.Union(projectedErrors(action).filter((error) => isTransientStatus(declaredStatus(error)))));
+	const running = /* @__PURE__ */ new Map();
+	const run = (id, key, digest, answer) => Effect.gen(function* () {
+		const first = running.get(id);
+		if (first !== void 0) {
+			yield* Deferred.await(first).pipe(Effect.withSpan("Idempotency.wait", { attributes: { "action.name": action.name } }));
+			return yield* run(id, key, digest, answer);
+		}
+		const claim = Deferred.makeUnsafe();
+		running.set(id, claim);
+		const release = Effect.andThen(Effect.sync(() => running.delete(id)), Deferred.succeed(claim, void 0));
+		return yield* Effect.gen(function* () {
+			const kept = yield* store.get(id);
+			if (kept !== void 0 && kept.input !== digest) return yield* new InvalidInput({ message: `The idempotency key ${key} of ${action.name} was given with another input (send a new key for another call)` });
+			const replayed = kept === void 0 ? Option.none() : decodeOutcome(kept.outcome);
+			if (Option.isSome(replayed)) return yield* replayed.value;
+			const exit = yield* Effect.exit(answer);
+			const json = Exit.isSuccess(exit) || exit.cause.reasons.every((reason) => Cause.isFailReason(reason) && !isTransientFailure(reason.error)) ? yield* Effect.option(encodeOutcome(exit)) : Option.none();
+			if (Option.isSome(json)) yield* store.set(id, {
+				input: digest,
+				outcome: json.value,
+				at: yield* Clock.currentTimeMillis
+			});
+			return yield* exit;
+		}).pipe(Effect.ensuring(release));
+	});
+	return (input, reporting) => {
+		const key = Predicate.hasProperty(input, field) ? input[field] : void 0;
+		if (!Predicate.isString(key)) return handle(input, reporting);
+		const answer = Effect.suspend(() => answered(handle(input, reporting)));
+		return Effect.flatMap(Effect.all([Effect.service(CallerKeyed).pipe(Effect.flatMap((named) => principalOf(action, named)), Effect.flatMap((principal) => sha256Hex(JSON.stringify([principal ?? null, key])))), Effect.flatMap(canonicalInput(action.input, input), sha256Hex)]), ([id, digest]) => run(`${action.name}/${id}`, key, digest, answer));
+	};
+};
+export { Idempotency, keyed, layerIdempotency };

package/dist/contract/implementation.d.mts

@@ -1,27 +1,41 @@
-import { Anyone } from "./caller.mjs";
+import { Anyone, Keyed } from "./caller.mjs";
 import { Refusal } from "./errors.mjs";
-import { Any } from "../Action.mjs";
-import { Context, Effect, Layer, Scope } from "effect";
+import { AnyEventImplementation, EventOf } from "./feed.mjs";
+import { Any } from "../Event.mjs";
+import { Reporting } from "./progress.mjs";
+import { Any as Any$1 } from "../Action.mjs";
+import { Context, Effect, Layer, Scope, Stream } from "effect";
 /** Decoded values at the dispatch boundary every surface shares. */
-export type ErasedValue = Any["input"]["Type"];
+export type ErasedValue = Any$1["input"]["Type"];
 /**
- * A handler, erased. Method extraction makes the argument bivariant: a surface selects the
- * action before it invokes a handler, so its decoded input is the matching handler input, and
- * handlers are not widened at their public API.
+ * A handler as written, erased: its answer, or the stream of an action answering one. Method
+ * extraction makes the argument bivariant: a surface selects the action before it invokes a
+ * handler, so its decoded input is the matching handler input, and handlers are not widened at
+ * their public API.
  */
-export type ErasedHandler<R> = {
-  handle(input: ErasedValue): Effect.Effect<ErasedValue, ErasedValue, R>;
+export type WrittenHandler<R> = {
+  handle(input: ErasedValue, reporting?: Reporting): Effect.Effect<ErasedValue, ErasedValue, R> | Stream.Stream<ErasedValue, ErasedValue, R>;
 }["handle"];
+/**
+ * A handler behind its action's authentication, authorization and declared errors, as a surface
+ * calls it. For an action answering a stream it succeeds at once with the call's stream, which
+ * `elementsOf` reads, the refusals included. `reporting` is where its progress goes, ignored for
+ * an action declaring no `progress`, so a surface may hand one to every call.
+ */
+export type ErasedHandler<R> = (input: ErasedValue, reporting?: Reporting) => Effect.Effect<ErasedValue, ErasedValue, R>;
 /**
  * Authorization for protected contracts: it refuses, and fails with nothing else. It runs only for
  * protected actions, after authentication and before the handler.
  */
-export type Authorize<A extends Any, R = never> = (action: A) => Effect.Effect<void, Refusal, R>;
-/** An implementation's authorizer, erased. */
-export type ErasedAuthorize = (action: Any) => Effect.Effect<void, unknown, unknown>;
-/** Each action of an implementation with its handler, as its builder made them. */
-export type Bound = ReadonlyArray<readonly [Any, ErasedHandler<unknown>]>;
-interface Memoized<S, E, R> {
+export type Authorize<A extends Any$1, R = never> = (action: A) => Effect.Effect<void, Refusal, R>;
+/** An authorization rule over contracts `C`, erased: it refuses, or lets the call run. */
+export type ErasedAuthorize<C = Any$1> = (contract: C) => Effect.Effect<void, unknown, unknown>;
+/** Each action of an implementation with its handler, as `dispatch` makes it. */
+export type Bound = ReadonlyArray<readonly [Any$1, ErasedHandler<unknown>]>;
+/** Each action of an implementation with its handler as written, as its builder made them. */
+export type Written = ReadonlyArray<readonly [Any$1, WrittenHandler<unknown>]>;
+/** A build shared by every layer an implementation reaches, through the one key it is provided under. */
+export interface Memoized<S, E, R> {
   readonly key: Context.Key<S, S>;
   readonly layer: Layer.Layer<S, E, R>;
 }
@@ -34,7 +48,7 @@ interface Memoized<S, E, R> {
  * its handlers' builder, `RA` what its authorizer reads per request, and `EAX` and `RAX` the
  * failures and services of the authorizer's builder.
  */
-export declare class Implementation<A extends Any, RequestServices extends {
+export declare class Implementation<A extends Any$1, RequestServices extends {
   readonly [name: string]: unknown;
 }, EX, RX, RA = never, EAX = never, RAX = never> {
   #private;
@@ -51,14 +65,14 @@ export declare class Implementation<A extends Any, RequestServices extends {
   /** Type-only: what building its authorizer needs. */
   readonly "~authorizeBuildServices": RAX;
   /** The contracts this implementation answers. */
-  readonly actions: ReadonlyArray<A>;
-  constructor(actions: ReadonlyArray<A>,
+  readonly actions: readonly A[];
+  constructor(actions: readonly A[],
   /** Builds each action paired with its handler: its own builder, or the one it shares. */
-  handlers: Memoized<Bound, EX, RX>,
+  handlers: Memoized<Written, EX, RX>,
   /** Builds its authorizer. */
   authorizer: Memoized<ErasedAuthorize, EAX, RAX>);
   /** Select contracts while retaining their handlers, authorization and shared builder. */
-  static share(actions: ReadonlyArray<Any>, app: AnyImplementation): AnyImplementation;
+  static share(actions: readonly Any$1[], app: AnyImplementation): AnyImplementation;
   /**
    * The key of what runs a call of `app`'s actions: its handlers' memoized layer's, which each
    * `implement` makes, so it is unique to the implementation. Every selection retains it.
@@ -74,7 +88,7 @@ export declare class Implementation<A extends Any, RequestServices extends {
    * The actions of `app` with their handlers, behind its authorizer, from the context
    * `layerOf(app)` provides.
    */
-  static boundOf(app: AnyImplementation): Effect.Effect<Bound, never, unknown>;
+  static boundOf(app: AnyImplementation, keyed: Keyed | undefined): Effect.Effect<Bound, never, unknown>;
   /** `app`, if this copy of the module made it; another installed copy's cannot be read. */
   private static own;
 }
@@ -85,43 +99,55 @@ export declare class Implementation<A extends Any, RequestServices extends {
  * admits every implementation, while a value of this type owes `unknown`, which no surface can be
  * given.
  */
-export type AnyImplementation<A extends Any = Any> = Implementation<A, {
+export type AnyImplementation<A extends Any$1 = Any$1> = Implementation<A, {
   readonly [name: string]: unknown;
 }, unknown, unknown, unknown, unknown, unknown>;
-/** What a surface serves: one implementation, or a list of them. */
-export type Served = AnyImplementation | ReadonlyArray<AnyImplementation>;
+/** What a surface serves: one implementation, of actions or of events, or a list of them. */
+export type Served = AnyImplementation | AnyEventImplementation | ReadonlyArray<AnyImplementation | AnyEventImplementation>;
+/** What a surface serving no events takes: one action implementation, or a list of them. */
+export type ServedActions = AnyImplementation | readonly AnyImplementation[];
 /** The implementations `S` stands for. */
 export type Member<S> = S extends ReadonlyArray<infer App> ? App : S;
-/** Options that may list actions of `A`, the shape every selecting surface's options share. */
-export interface Selection<A extends Any> {
-  readonly actions?: ReadonlyArray<A> | undefined;
+/**
+ * Options that may list actions and event types of `C`, the shape every selecting surface's
+ * options share.
+ */
+export interface Selection<C extends Any$1 | Any> {
+  readonly actions?: readonly C[] | undefined;
 }
 /**
  * The actions options `O` select, of `All`: those its `actions` lists when it always lists
- * them, and every one otherwise. Options whose `actions` may be absent, being optional or
- * a union with options lacking it, select every action at run time, so they narrow nothing.
+ * them, none where it lists event types alone, and every one otherwise. Options whose `actions`
+ * may be absent, being optional or a union with options lacking it, select every action at run
+ * time, so they narrow nothing.
  */
-export type Selected<O, All extends Any> = O extends {
-  readonly actions: ReadonlyArray<infer A extends Any>;
-} ? A : All;
+export type Selected<O, All extends Any$1> = O extends {
+  readonly actions: ReadonlyArray<infer C>;
+} ? Extract<C, Any$1> : All;
+/** The event types options `O` select, of `All`, as `Selected` selects actions. */
+export type SelectedEvents<O, All extends Any> = O extends {
+  readonly actions: ReadonlyArray<infer C>;
+} ? Extract<C, Any> : All;
 /**
  * The middleware options `O` install, each a member of `L`: its `middleware` when always given,
  * an array of unknown length when it may be absent, which installs none or all of them, and
  * none otherwise.
  */
-export type MiddlewareOf<O, L extends ReadonlyArray<unknown>> = O extends {
+export type MiddlewareOf<O, L extends readonly unknown[]> = O extends {
   readonly middleware: infer M extends L;
 } ? M : O extends {
   readonly middleware?: infer M extends L | undefined;
 } ? "middleware" extends keyof O ? ReadonlyArray<NonNullable<M>[number]> : [] : [];
 /** The actions options `O` select of the implementations `Apps` stand for. */
 export type SelectedOf<O, Apps extends Served> = Selected<O, ActionOf<Member<Apps>>>;
+/** The event types options `O` select of the implementations `Apps` stand for. */
+export type SelectedEventsOf<O, Apps extends Served> = SelectedEvents<O, EventOf<Member<Apps>>>;
 /**
- * The actions a client of options `O` offers methods for, of `All`: those `actions` may
+ * The actions or event types a client of options `O` offers, of `All`: those `actions` may
  * list, wherever some member of `O` may list them, as each is present whether the list is
  * given or not; every one where no member lists any.
  */
-export type Offered<O, All extends Any> = [Listing<O>] extends [never] ? All : Extract<All, Listing<O> extends ReadonlyArray<infer A extends Any> ? A : never>;
+export type Offered<O, All extends Any$1 | Any> = [Listing<O>] extends [never] ? All : Extract<All, Listing<O> extends ReadonlyArray<infer C> ? C : never>;
 type Listing<O> = O extends unknown ? NonNullable<O["actions" & keyof O]> : never;
 /**
  * No key of any member of `O` beyond those of `Keys`, so a misspelled option is refused
@@ -139,7 +165,7 @@ export type OptionalUnless<O, Given> = {} extends O ? [options?: Given] : [optio
 export type ActionOf<App> = App extends {
   readonly actions: ReadonlyArray<infer A>;
 } ? A : never;
-type Matches<A extends Any, Listed extends Any> = Listed extends Any ? [A] extends [Listed] ? true : [Listed] extends [A] ? true : never : never;
+type Matches<A extends Any$1, Listed extends Any$1> = Listed extends Any$1 ? [A] extends [Listed] ? true : [Listed] extends [A] ? true : never : never;
 /**
  * The actions of `App` a surface given the actions `Listed` may serve, as `select` selects
  * them by identity: an action whose type either is assignable to, or is assigned by, one
@@ -147,34 +173,34 @@ type Matches<A extends Any, Listed extends Any> = Listed extends Any ? [A] exten
  * actions, an erased one included, still counts, and another contract of a listed name, which
  * the surface leaves out beside an action it serves, does not.
  */
-export type Serving<App, Listed extends Any> = ActionOf<App> extends (infer A extends Any) ? A extends unknown ? [A] extends [Listed] ? A : string extends A["name"] ? A : [Extract<A["name"], Listed["name"]>] extends [never] ? never : [Matches<A, Listed>] extends [never] ? never : A : never : never;
+export type Serving<App, Listed extends Any$1> = ActionOf<App> extends (infer A extends Any$1) ? A extends unknown ? [A] extends [Listed] ? A : string extends A["name"] ? A : [Extract<A["name"], Listed["name"]>] extends [never] ? never : [Matches<A, Listed>] extends [never] ? never : A : never : never;
 /**
  * What each implementation among `App` owes per request where a surface serving the actions
  * `Listed` serves it: its authorizer's services, and the handlers' of the actions it serves.
  */
-export type ServedRequest<App, Listed extends Any> = App extends unknown ? RequestOf<App, Serving<App, Listed>> : never;
+export type ServedRequest<App, Listed extends Any$1> = App extends unknown ? RequestOf<App, Serving<App, Listed>> : never;
 /** The implementations among `App` holding an action of `Listed`: those a surface builds. */
-export type Holding<App, Listed extends Any> = App extends unknown ? [Serving<App, Listed>] extends [never] ? never : App : never;
-/** The protected members of a contract union. */
-export type Protected<A extends Any> = A extends unknown ? A["caller"] extends typeof Anyone ? never : A : never;
+export type Holding<App, Listed extends Any$1> = App extends unknown ? [Serving<App, Listed>] extends [never] ? never : App : never;
+/** The protected members of a contract union, of actions or of events. */
+export type Protected<A extends Pick<Any$1, "caller">> = A extends unknown ? A["caller"] extends typeof Anyone ? never : A : never;
 type ServiceOf<K> = K extends Context.Key<infer I, unknown> ? I : never;
-type AuthenticationOf<A extends Any> = A["caller"] extends typeof Anyone ? never : ServiceOf<A["caller"]>;
+type AuthenticationOf<A extends Any$1> = A["caller"] extends typeof Anyone ? never : ServiceOf<A["caller"]>;
 /**
  * Per-request requirements of `App`'s authorization and handler for each `A` it
  * implements: those of every name `A`'s may be, so a union or an erased name owes each it may
  * stand for.
  */
-export type RequestOf<App, A extends Any> = App extends {
+export type RequestOf<App, A extends Any$1> = App extends {
   readonly "~request": infer R;
   readonly "~authorizeRequest": infer RA;
-} ? A extends Any ? [A["name"] & keyof R] extends [never] ? never : R[A["name"] & keyof R] | (A["caller"] extends typeof Anyone ? never : RA) | AuthenticationOf<A> : never : never;
-type OwnActions<App> = Extract<ActionOf<App>, Any>;
+} ? A extends Any$1 ? [A["name"] & keyof R] extends [never] ? never : R[A["name"] & keyof R] | (A["caller"] extends typeof Anyone ? never : RA) | AuthenticationOf<A> : never : never;
+type OwnActions<App> = Extract<ActionOf<App>, Any$1>;
 /**
  * What a surface serving the actions `Listed` of the implementations `App` fails with at startup:
  * their builders' and built authorizers' failures, an authorizer's only if a selected protected
  * action needs it.
  */
-export type BuildError<App, Listed extends Any = OwnActions<App>> = App extends {
+export type BuildError<App, Listed extends Any$1 = OwnActions<App>> = App extends {
   readonly "~buildError": infer EX;
   readonly "~authorizeBuildError": infer EAX;
 } ? EX | ([Protected<Serving<App, Listed>>] extends [never] ? never : EAX) : never;
@@ -182,7 +208,7 @@ export type BuildError<App, Listed extends Any = OwnActions<App>> = App extends
  * What a surface serving the actions `Listed` of the implementations `App` reads at startup: their
  * builders' and built authorizers' services.
  */
-export type BuildServices<App, Listed extends Any = OwnActions<App>> = App extends {
+export type BuildServices<App, Listed extends Any$1 = OwnActions<App>> = App extends {
   readonly "~buildServices": infer RX;
   readonly "~authorizeBuildServices": infer RAX;
 } ? RX | ([Protected<Serving<App, Listed>>] extends [never] ? never : RAX) : never;

package/dist/contract/implementation.mjs

@@ -1,10 +1,23 @@
-import { Anyone, assertAuthentication } from "./caller.mjs";
+import { Anyone, CallerKeyed } from "./caller.mjs";
 import { Unauthenticated } from "./errors.mjs";
-import { assertDistinct, assertOnce, heldOnce } from "./names.mjs";
 import { projectedErrors } from "./declared.mjs";
-import { Array, Cause, Context, Effect, Exit, Layer, Option, Schema } from "effect";
+import { checkInput } from "./input-check.mjs";
+import { assertOnce, heldOnce } from "./names.mjs";
+import { reportedTo, streamReportedTo } from "./progress.mjs";
+import { elementOf } from "./stream.mjs";
+import { Array, Cause, Context, Effect, Exit, Layer, Option, Predicate, References, Schema, Stream } from "effect";
 // src/contract/implementation.ts
 const uniqueKey = () => Math.random().toString(36).slice(2);
+const notAStream = /* @__PURE__ */ new Error("A handler answered otherwise than its action's success declares");
+/** The stream of a call of an action answering one, from its `ErasedHandler`'s answer. */
+const elementsOf = (answer) => Stream.unwrap(Effect.filterOrElse(answer, Stream.isStream, () => Effect.die(notAStream)));
+/** The answer of a handler of an action answering one value, a stream refused as a defect. */
+const answered = (answer) => Stream.isStream(answer) ? Effect.die(notAStream) : answer;
+/**
+* `run` as a tool calls it, a tool answering one result: the elements of an action answering a
+* stream collected, in order, into one array once the stream ends.
+*/
+const answeringWhole = (action, run) => elementOf(action.success) === void 0 ? run : (input, reporting) => Stream.runCollect(elementsOf(run(input, reporting)));
 const memoized = (build) => {
 	const key = Context.Service(`effect-actions/Implementation/${uniqueKey()}`);
 	return {
@@ -13,6 +26,48 @@ const memoized = (build) => {
 	};
 };
 /**
+* The builders of an implementation of `contracts` as one layer: what its builder made, and its
+* authorizer where a contract is protected, as only those need one.
+*/
+const builderLayer = (contracts, built, authorizer) => contracts.some((contract) => contract.caller !== Anyone) ? Layer.merge(built.layer, authorizer.layer) : built.layer;
+/** What a surface throws for an implementation some other copy of this module made. */
+const notMadeHere = (module) => /* @__PURE__ */ new Error(`Not an implementation made by this ${module}.implement: pass the value implement returned, not a copy such as a spread; or effect-actions is installed twice`);
+const asDefects = (reason, rejected) => {
+	const trace = Context.makeUnsafe(reason.annotations);
+	return [Cause.makeDieReason(reason.error).annotate(trace), Cause.makeDieReason(Cause.squash(rejected)).annotate(trace)];
+};
+const dispatch = (action, handle, before, keyed) => {
+	const actionAttributes = {
+		"action.name": action.name,
+		"action.read_only": action.readOnly
+	};
+	const authentication = action.caller === Anyone ? Effect.void : Effect.flatMap(Effect.serviceOption(action.caller), (actor) => Option.isSome(actor) ? Effect.void : Effect.fail(new Unauthenticated()));
+	const authorization = action.caller === Anyone ? Effect.void : Effect.suspend(() => before(action));
+	const validate = Schema.decodeUnknownEffect(Schema.toType(Schema.Union(projectedErrors(action))));
+	const declaredOrDefect = Effect.fnUntraced(function* (cause) {
+		const reasons = [];
+		for (const reason of cause.reasons) if (Cause.isFailReason(reason)) {
+			const validated = yield* Effect.exit(validate(reason.error));
+			reasons.push(...Exit.isSuccess(validated) ? [reason] : asDefects(reason, validated.cause));
+		} else reasons.push(reason);
+		return yield* Effect.failCause(Cause.fromReasons(reasons));
+	});
+	const admitted = (input) => Effect.andThen(authentication, Effect.andThen(checkInput(action, input), authorization));
+	const span = { attributes: actionAttributes };
+	const trace = { captureStackTrace: false };
+	if (elementOf(action.success) !== void 0) {
+		const streamed = (answer) => Stream.isStream(answer) ? Stream.scoped(answer) : Stream.die(notAStream);
+		return (input, sink) => Effect.succeed(Stream.unwrap(Effect.map(admitted(input), () => streamReportedTo(action.progress, sink, (reporting) => streamed(handle(input, reporting))))).pipe(Stream.catchCause((cause) => Stream.fromEffect(declaredOrDefect(cause))), Stream.updateService(References.CurrentLogAnnotations, (annotations) => ({
+			...annotations,
+			...actionAttributes
+		})), Stream.withSpan(action.name, {
+			...span,
+			...trace
+		})));
+	}
+	return (input, sink) => Effect.scoped(admitted(input).pipe(Effect.andThen(Effect.suspend(() => reportedTo(action.progress, sink, (reporting) => answered(handle(input, reporting))))), Effect.provideService(CallerKeyed, keyed), Effect.catchCause(declaredOrDefect))).pipe(Effect.annotateLogs(actionAttributes), Effect.withSpan(action.name, span, trace));
+};
+/**
 * Actions bound to their handlers and their authorizer: everything one `Action.implement` call
 * produced, one builder serving every surface. The private fields make this class nominal: a structurally similar object, including one made by
 * spreading an implementation, is not an implementation. Its type parameters may be written
@@ -50,28 +105,32 @@ var Implementation = class Implementation {
 	*/
 	static layerOf(app) {
 		const source = Implementation.own(app);
-		return app.actions.some((action) => action.caller !== Anyone) ? Layer.merge(source.#handlers.layer, source.#authorizer.layer) : source.#handlers.layer;
+		return builderLayer(app.actions, source.#handlers, source.#authorizer);
 	}
 	/**
 	* The actions of `app` with their handlers, behind its authorizer, from the context
 	* `layerOf(app)` provides.
 	*/
-	static boundOf(app) {
+	static boundOf(app, keyed) {
 		const { actions } = app;
 		const source = Implementation.own(app);
 		return Effect.gen(function* () {
 			const bound = yield* source.#handlers.key;
 			const before = actions.some((action) => action.caller !== Anyone) ? yield* source.#authorizer.key : () => Effect.void;
-			return actions.flatMap((action) => bound.flatMap(([held, handle]) => held === action ? [[action, dispatch(action, handle, before)]] : []));
+			return actions.flatMap((action) => bound.flatMap(([held, handle]) => held === action ? [[action, dispatch(action, handle, before, keyed)]] : []));
 		});
 	}
 	/** `app`, if this copy of the module made it; another installed copy's cannot be read. */
 	static own(app) {
-		if (!(#handlers in app)) throw new Error("Not an implementation made by this Action.implement: pass the value implement returned, not a copy such as a spread; or effect-actions is installed twice");
+		if (!(#handlers in app)) throw notMadeHere("Action");
 		return app;
 	}
 };
-const toList = (served) => Array.ensure(served);
+/**
+* The action implementations among what a surface is given; `eventsOf` reads the event
+* implementations, by their tag.
+*/
+const toList = (served) => Array.ensure(served).filter((app) => !Predicate.isTagged(app, "EventImplementation"));
 const notHeld = {
 	byImplementation: {
 		why: "no implementation holds it",
@@ -94,15 +153,22 @@ const assertHeld = ({ why, fix, holder }, listed, held) => {
 		throw new Error(`Listed in actions, but ${why}: ${markingOthers(missing, names)} (${fix}${sameName ? `; one marked (another contract) is a contract of that name ${holder}` : ""})`);
 	}
 };
-const select = (apps, listed) => {
+/**
+* The implementations among `apps` holding what `listed` lists, each sharing its builder to hold
+* those alone, or every one where it lists none: action and event implementations alike, by the
+* contracts each `holds` and how it `share`s them.
+*/
+const selectHeld = (apps, listed, holds, share) => {
 	if (listed === void 0) return apps;
-	assertHeld(notHeld.byImplementation, listed, apps.flatMap((app) => app.actions));
+	assertHeld(notHeld.byImplementation, listed, apps.flatMap(holds));
 	return apps.flatMap((app) => {
-		const own = app.actions.filter((action) => listed.includes(action));
+		const held = holds(app);
+		const own = held.filter((contract) => listed.includes(contract));
 		if (own.length === 0) return [];
-		return own.length === app.actions.length ? [app] : [Implementation.share(own, app)];
+		return own.length === held.length ? [app] : [share(own, app)];
 	});
 };
+const select = (apps, listed) => selectHeld(apps, listed, (app) => app.actions, (own, app) => Implementation.share(own, app));
 const servedBy = (what, bound, apps, listed) => {
 	if (listed !== void 0) assertHeld(notHeld.byBinding, listed, bound);
 	const held = apps.flatMap((app) => app.actions);
@@ -115,58 +181,26 @@ const servedBy = (what, bound, apps, listed) => {
 	assertOnce("served action", actions, heldOnce);
 	return served;
 };
-/**
-* What `ActionHttp.layer` and `ActionRpc.layer` serve, with the checks they share;
-* `authentication` is the binding's where a served action is protected.
-*/
-const servingOf = (what, binding, served, options) => {
-	const apps = servedBy(what, binding.actions, toList(served), options.actions);
-	const actions = apps.flatMap((app) => app.actions);
-	assertAuthentication(actions, binding.authentication);
-	assertDistinct("middleware", options.middleware ?? [], (key) => key.key, { fix: "list each middleware once" });
-	return {
-		apps,
-		actions,
-		authentication: actions.some((action) => action.caller !== Anyone) ? binding.authentication : void 0
-	};
-};
-const provideHandlers = (apps) => (layer) => {
-	const [first, ...rest] = apps.map((app) => Implementation.layerOf(app));
+/** Provide `builders`, implementations' builder layers, to a surface's layer. */
+const provideBuilders = (builders) => (layer) => {
+	const [first, ...rest] = builders;
 	return first === void 0 ? layer : Layer.provide(layer, Layer.mergeAll(first, ...rest));
 };
-const builders = (apps) => Layer.empty.pipe(provideHandlers(apps));
-const acquire = (apps) => Effect.map(Effect.forEach(apps, (app) => Implementation.boundOf(app)), (bound) => bound.flat());
-const built = (apps) => {
-	const [first, ...rest] = apps.map((app) => Implementation.layerOf(app));
+const provideHandlers = (apps) => provideBuilders(apps.map((app) => Implementation.layerOf(app)));
+const acquire = (apps, keyed) => Effect.map(Effect.forEach(apps, (app) => Implementation.boundOf(app, keyed)), (bound) => bound.flat());
+/**
+* What `acquisition` reads, once `builders` are built into the layer graph around the caller, and
+* held by its scope.
+*/
+const builtWith = (builders, acquisition) => {
+	const [first, ...rest] = builders;
 	return Effect.gen(function* () {
-		if (first === void 0) return [];
+		if (first === void 0) return yield* acquisition;
 		const current = yield* Effect.serviceOption(Layer.CurrentMemoMap);
 		const memoMap = Option.getOrElse(current, Layer.makeMemoMapUnsafe);
 		const scope = yield* Effect.scope;
 		const context = yield* Layer.buildWithMemoMap(Layer.mergeAll(first, ...rest), memoMap, scope);
-		return yield* Effect.provideContext(acquire(apps), context);
-	});
-};
-const dispatch = (action, handle, before) => {
-	const actionAttributes = {
-		"action.name": action.name,
-		"action.read_only": action.readOnly
-	};
-	const authentication = action.caller === Anyone ? Effect.void : Effect.flatMap(Effect.serviceOption(action.caller), (actor) => Option.isSome(actor) ? Effect.void : Effect.fail(new Unauthenticated()));
-	const authorization = action.caller === Anyone ? Effect.void : Effect.suspend(() => before(action));
-	const validate = Schema.decodeUnknownEffect(Schema.toType(Schema.Union(projectedErrors(action))));
-	const asDefects = (reason, rejected) => {
-		const trace = Context.makeUnsafe(reason.annotations);
-		return [Cause.makeDieReason(reason.error).annotate(trace), Cause.makeDieReason(Cause.squash(rejected)).annotate(trace)];
-	};
-	const declaredOrDefect = Effect.fnUntraced(function* (cause) {
-		const reasons = [];
-		for (const reason of cause.reasons) if (Cause.isFailReason(reason)) {
-			const validated = yield* Effect.exit(validate(reason.error));
-			reasons.push(...Exit.isSuccess(validated) ? [reason] : asDefects(reason, validated.cause));
-		} else reasons.push(reason);
-		return yield* Effect.failCause(Cause.fromReasons(reasons));
+		return yield* Effect.provideContext(acquisition, context);
 	});
-	return (input) => Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(Effect.suspend(() => handle(input))), Effect.catchCause(declaredOrDefect))).pipe(Effect.annotateLogs(actionAttributes), Effect.withSpan(action.name, { attributes: actionAttributes }, { captureStackTrace: false }));
 };
-export { Implementation, acquire, assertHeld, builders, built, memoized, notHeld, provideHandlers, select, servingOf, toList };
+export { Implementation, acquire, answered, answeringWhole, assertHeld, builderLayer, builtWith, elementsOf, markingOthers, memoized, notHeld, notMadeHere, provideBuilders, provideHandlers, select, selectHeld, servedBy, toList, uniqueKey };

package/dist/contract/input-check.d.mts

@@ -0,0 +1,15 @@
+import { Forbidden } from "./errors.mjs";
+import { Any } from "../Event.mjs";
+import { Any as Any$1 } from "../Action.mjs";
+import { Context, Effect } from "effect";
+/**
+ * A check every call and every subscription runs on its decoded input, on every surface, once the
+ * surface has verified its caller and before its authorizer: what a host provides, as a Durable
+ * Object refuses an input naming another object, to refuse an input it does not serve. Defaults
+ * to none.
+ *
+ * **Gotchas**
+ *
+ * - Provide it to the layer graph the surfaces are built in, as `Layer.succeed(Action.InputCheck)(check)`: provided per request, it misses a socket's later calls.
+ */
+export declare const InputCheck: Context.Reference<(contract: Any$1 | Any, input: Any$1["input"]["Type"]) => Effect.Effect<void, Forbidden>>;

package/dist/contract/input-check.mjs

@@ -0,0 +1,16 @@
+import { Context, Effect } from "effect";
+// src/contract/input-check.ts
+/**
+* A check every call and every subscription runs on its decoded input, on every surface, once the
+* surface has verified its caller and before its authorizer: what a host provides, as a Durable
+* Object refuses an input naming another object, to refuse an input it does not serve. Defaults
+* to none.
+*
+* **Gotchas**
+*
+* - Provide it to the layer graph the surfaces are built in, as `Layer.succeed(Action.InputCheck)(check)`: provided per request, it misses a socket's later calls.
+*/
+const InputCheck = Context.Reference("effect-actions/Action/InputCheck", { defaultValue: () => () => Effect.void });
+/** `contract`'s `input`, as the provided `InputCheck` judges it. */
+const checkInput = (contract, input) => Effect.flatMap(Effect.service(InputCheck), (check) => check(contract, input));
+export { InputCheck, checkInput };