@sincpro/client-framework 1.0.0 → 1.1.0

package/dist/core/entrypoint/bounded-context.d.ts

@@ -1,30 +1,46 @@
 import type { ContextValues } from "../../context/domain/store.js";
 import { type Context } from "../../context/entrypoint/context.js";
 import { type CommandBus } from "../domain/bus.js";
-import type { Answer, AnyCommand, Command, CommandClass, ResponseClass } from "../domain/dto.js";
+import { type Answer, type AnyCommand, Command, type CommandClass, DomainEvent, type EventClass, type Executable, type ResponseClass } from "../domain/dto.js";
 import type { ErrorClass, ErrorHandler } from "../domain/errors.js";
+import type { Cause, ExecuteOptions, ExecutionCompleted, ExecutionFailed, ExecutionStarted, Extension, Interceptor, Listener } from "../domain/pipeline.js";
+import { type ExecutableClass } from "../services/listening.js";
 import type { LayerLogger } from "../../observability/domain/logging.js";
-interface Executor<C extends AnyCommand, R> {
-    execute(command: C): R | Promise<R>;
+interface Executor<C extends Executable, R> {
+    execute(executable: C): R | Promise<R>;
 }
-type ServiceClass<C extends AnyCommand, R> = {
+type ServiceClass<C extends Executable, R> = {
     new (): Executor<C, R>;
     readonly serviceName: string;
 };
+/** What a service is registered for: a Command's class or a domain event's. */
+type DtoClass = ExecutableClass;
+/** The service a registration takes the place of, as the backend's `replaces=`. */
+export type RegistrationOptions = {
+    replaces?: abstract new (...args: never[]) => object;
+};
+/** What `feature(...)` and `appService(...)` answer: the function that registers the service. */
+export type Registrar<T extends Executable> = <S extends ServiceClass<NoInfer<T>, Answer<NoInfer<T>>>>(Service: S, decorator?: ClassDecoratorContext<S>) => S;
 /**
- * A bounded context: the bus of its Commands, as sincpro_framework's `UseFramework`.
+ * A bounded context: the bus of its Commands and domain events, as sincpro_framework's
+ * `UseFramework`.
  *
  *     const project = new BoundedContext<ProjectDependencies>("project");
  *     project.addDependency("client", clientOf(transport));
  *     project.feature(CommandCancelIssue)(CancelIssue);          // or @project.feature(...)
+ *     project.feature(IssueClosed)(NotifyWatchers);              // a subscriber of an event
+ *     project.feature(CommandCancelIssue, { replaces: CancelIssue })(CancelAndArchive);
  *     project.addFeatureErrorHandler(toEmptyWhenMissing);
- *     project.expectErrors(IssueClosed);                         // refused, never reported
+ *     project.expectErrors(IssueLocked);                         // refused, never reported
  *     await project.execute(new CommandCancelIssue("x"));        // ResponseCancelIssue
+ *     await project.execute(new IssueClosed("x"));               // what its subscriber returns
  *     project.logger.info("Catalog preloaded");
  *
  * Context: registrations, dependencies, handlers and expected errors are snapshotted per
  * generation; a call keeps the generation it started with, and what is added later answers from
- * the next call — as the backend's `build_root_bus`.
+ * the next call — as the backend's `build_root_bus`. A domain event is executed as a Command is:
+ * one subscriber per bounded context, through the same pipeline; carrying it to every bounded
+ * context that hears it (a queue, an outbox) is the platform's.
  */
 export declare class BoundedContext<D extends object = Record<never, never>, C extends object = ContextValues> {
     readonly name: string;
@@ -36,6 +52,8 @@ export declare class BoundedContext<D extends object = Record<never, never>, C e
     private readonly dependencyValues;
     private readonly handlers;
     private readonly expected;
+    private readonly interceptors;
+    private readonly listeners;
     private revision;
     private builtRevision;
     private built;
@@ -44,8 +62,43 @@ export declare class BoundedContext<D extends object = Record<never, never>, C e
     addDependency<K extends keyof D & string>(name: K, dependency: D[K], options?: {
         replaces: D[K];
     }): this;
-    feature<T extends AnyCommand>(command: CommandClass<T>): <S extends ServiceClass<NoInfer<T>, Answer<NoInfer<T>>>>(Service: S, decorator?: ClassDecoratorContext<S> | undefined) => S;
-    appService<T extends AnyCommand>(command: CommandClass<T>): <S extends ServiceClass<NoInfer<T>, Answer<NoInfer<T>>>>(Service: S, decorator?: ClassDecoratorContext<S> | undefined) => S;
+    /**
+     * Registers the Feature that executes a Command — or that subscribes to a domain event. With
+     * `replaces`, it takes the place of the service registered now for it.
+     */
+    feature<T extends AnyCommand>(command: CommandClass<T>, options?: RegistrationOptions): Registrar<T>;
+    feature<E extends DomainEvent>(event: EventClass<E>, options?: RegistrationOptions): Registrar<E>;
+    /** Registers the ApplicationService of a Command or a domain event; `replaces` as `feature`. */
+    appService<T extends AnyCommand>(command: CommandClass<T>, options?: RegistrationOptions): Registrar<T>;
+    appService<E extends DomainEvent>(event: EventClass<E>, options?: RegistrationOptions): Registrar<E>;
+    /** The service registered now for a Command or an event class — what a `replaces` names. */
+    handlerOf(dto: DtoClass): (abstract new (...args: never[]) => object) | undefined;
+    /**
+     * The event class registered here under a wire name, or `undefined` when nothing here hears it
+     * — what a platform's queue rebuilds a stored event as, as the backend's `event_type(name)`.
+     */
+    eventTypeOf(name: string): EventClass<DomainEvent> | undefined;
+    /**
+     * Runs `interceptor` around every execution of these classes — of every one when none is
+     * named —, outermost first in the order registered. It may look, veto (throw), adjust what it
+     * passes on (of the same class) or answer by itself. Registered after a call, it wraps from
+     * the next one.
+     */
+    interceptor<T extends Executable = Executable>(...dtos: (abstract new (...args: never[]) => T)[]): <F extends Interceptor<T>>(interceptor: F) => F;
+    /** Stops `interceptor` wherever it was registered; from the next call. */
+    withoutInterceptor(interceptor: (...args: never[]) => unknown): this;
+    /** Hears every run of these classes (every one when none is named) begin. Answers how to stop. */
+    onStart(listener: Listener<ExecutionStarted>, ...dtos: DtoClass[]): () => void;
+    /** Hears every run of these classes whose service answered — not an answer a handler gave. */
+    onCompletion(listener: Listener<ExecutionCompleted>, ...dtos: DtoClass[]): () => void;
+    /** Hears every failure that escapes a call — after every handler —, once, where it failed. */
+    onFailure(listener: Listener<ExecutionFailed>, ...dtos: DtoClass[]): () => void;
+    /**
+     * Wires a component into this bounded context — its dependencies, services, interceptors,
+     * listeners, handlers — in one place: a module of an application, a plugin. `fresh()` copies
+     * all it registered.
+     */
+    extend(extension: Extension<this>): this;
     /** Answers a failure that reaches `execute` (or a scope's): after every layer's handlers. */
     addGlobalErrorHandler(handler: ErrorHandler): this;
     /** Answers a Feature's failure, wherever it was executed from. */
@@ -57,12 +110,28 @@ export declare class BoundedContext<D extends object = Record<never, never>, C e
      * its span is no error and nothing is reported. They are still thrown — or handled.
      */
     expectErrors(...types: ErrorClass[]): this;
-    execute<R>(command: Command<R>, _returnType?: ResponseClass<NoInfer<R>>): Promise<R>;
+    /**
+     * Executes a Command — its Response, inferred —, or a domain event — its subscriber's answer.
+     * `{ signal }` cancels the run (it ends `aborted`); a delivered event's envelope continues its
+     * flow (`execute(event, envelope)`).
+     */
+    execute<R>(command: Command<R>, returnType?: ResponseClass<NoInfer<R>>): Promise<R>;
+    execute<R>(command: Command<R>, options: ExecuteOptions): Promise<R>;
+    execute(event: DomainEvent, options?: ExecuteOptions | Cause): Promise<unknown>;
     scoped(context: Partial<C>): CommandBus;
     buildRootBus(): void;
     fresh(): BoundedContext<D, C>;
+    /** What escaped a call, told once, from where it first failed. */
+    private escaped;
     private addErrorHandler;
     private registrar;
+    /**
+     * 1. The service is of the layer it is registered in, for a Command or a domain event class.
+     * 2. The class has no service yet — or, with `replaces`, the one it has is that one.
+     * 3. Its `serviceName` is given and no other service has it; an event's `eventName` is given
+     *    and no other event class here has it — the name means one event.
+     * Final: registered, said on its spans when it replaced another; the next call answers with it.
+     */
     private registerService;
     private generation;
     private buildGeneration;

package/dist/core/entrypoint/bounded-context.js

@@ -1,9 +1,13 @@
 import { contextAt, } from "../../context/entrypoint/context.js";
 import { processContext, processStore, } from "../../context/infrastructure/process.js";
-import { executeTyped, FeatureBus, } from "../domain/bus.js";
+import { FeatureBus, optionsOf, } from "../domain/bus.js";
+import { Command, DomainEvent, } from "../domain/dto.js";
 import { ApplicationService, Feature, RESERVED_MEMBERS, } from "../domain/services.js";
+import { processHearing } from "../infrastructure/listeners.js";
 import { handled } from "../services/error-handlers.js";
-import { executeService } from "../services/execution.js";
+import { executeService, failedAt } from "../services/execution.js";
+import { announceTo, concerns, listenIn, } from "../services/listening.js";
+import { observabilityNow } from "../../observability/infrastructure/registry.js";
 import { boundedContextLogger, logHandled, } from "../../observability/services/logging.js";
 function isExecutor(value) {
     return (typeof value === "object" &&
@@ -11,20 +15,33 @@ function isExecutor(value) {
         "execute" in value &&
         typeof value.execute === "function");
 }
+function isEventClass(dto) {
+    return dto.prototype instanceof DomainEvent;
+}
+function nameOf(Service) {
+    const named = Service;
+    return String(named?.serviceName ?? named?.name ?? Service);
+}
 /**
- * A bounded context: the bus of its Commands, as sincpro_framework's `UseFramework`.
+ * A bounded context: the bus of its Commands and domain events, as sincpro_framework's
+ * `UseFramework`.
  *
  *     const project = new BoundedContext<ProjectDependencies>("project");
  *     project.addDependency("client", clientOf(transport));
  *     project.feature(CommandCancelIssue)(CancelIssue);          // or @project.feature(...)
+ *     project.feature(IssueClosed)(NotifyWatchers);              // a subscriber of an event
+ *     project.feature(CommandCancelIssue, { replaces: CancelIssue })(CancelAndArchive);
  *     project.addFeatureErrorHandler(toEmptyWhenMissing);
- *     project.expectErrors(IssueClosed);                         // refused, never reported
+ *     project.expectErrors(IssueLocked);                         // refused, never reported
  *     await project.execute(new CommandCancelIssue("x"));        // ResponseCancelIssue
+ *     await project.execute(new IssueClosed("x"));               // what its subscriber returns
  *     project.logger.info("Catalog preloaded");
  *
  * Context: registrations, dependencies, handlers and expected errors are snapshotted per
  * generation; a call keeps the generation it started with, and what is added later answers from
- * the next call — as the backend's `build_root_bus`.
+ * the next call — as the backend's `build_root_bus`. A domain event is executed as a Command is:
+ * one subscriber per bounded context, through the same pipeline; carrying it to every bounded
+ * context that hears it (a queue, an outbox) is the platform's.
  */
 export class BoundedContext {
     name;
@@ -40,6 +57,12 @@ export class BoundedContext {
         application_service: [],
     };
     expected = [];
+    interceptors = [];
+    listeners = {
+        started: new Set(),
+        completed: new Set(),
+        failed: new Set(),
+    };
     revision = 0;
     builtRevision = -1;
     built;
@@ -89,11 +112,70 @@ export class BoundedContext {
         this.revision++;
         return this;
     }
-    feature(command) {
-        return this.registrar(command, "feature");
+    feature(dto, options) {
+        return this.registrar(dto, "feature", options);
+    }
+    appService(dto, options) {
+        return this.registrar(dto, "application_service", options);
+    }
+    /** The service registered now for a Command or an event class — what a `replaces` names. */
+    handlerOf(dto) {
+        return this.registrations.get(dto)?.Service;
+    }
+    /**
+     * The event class registered here under a wire name, or `undefined` when nothing here hears it
+     * — what a platform's queue rebuilds a stored event as, as the backend's `event_type(name)`.
+     */
+    eventTypeOf(name) {
+        for (const dto of this.registrations.keys()) {
+            if (isEventClass(dto) && dto.eventName === name)
+                return dto;
+        }
+        return undefined;
+    }
+    /**
+     * Runs `interceptor` around every execution of these classes — of every one when none is
+     * named —, outermost first in the order registered. It may look, veto (throw), adjust what it
+     * passes on (of the same class) or answer by itself. Registered after a call, it wraps from
+     * the next one.
+     */
+    interceptor(...dtos) {
+        return (interceptor) => {
+            if (typeof interceptor !== "function")
+                throw new TypeError("An interceptor is a function");
+            // Registered for these classes only, it is called only with them.
+            this.interceptors.push({ what: interceptor, dtos });
+            this.revision++;
+            return interceptor;
+        };
+    }
+    /** Stops `interceptor` wherever it was registered; from the next call. */
+    withoutInterceptor(interceptor) {
+        const kept = this.interceptors.filter((one) => one.what !== interceptor);
+        this.interceptors.splice(0, this.interceptors.length, ...kept);
+        this.revision++;
+        return this;
+    }
+    /** Hears every run of these classes (every one when none is named) begin. Answers how to stop. */
+    onStart(listener, ...dtos) {
+        return listenIn(this.listeners.started, listener, dtos);
+    }
+    /** Hears every run of these classes whose service answered — not an answer a handler gave. */
+    onCompletion(listener, ...dtos) {
+        return listenIn(this.listeners.completed, listener, dtos);
+    }
+    /** Hears every failure that escapes a call — after every handler —, once, where it failed. */
+    onFailure(listener, ...dtos) {
+        return listenIn(this.listeners.failed, listener, dtos);
     }
-    appService(command) {
-        return this.registrar(command, "application_service");
+    /**
+     * Wires a component into this bounded context — its dependencies, services, interceptors,
+     * listeners, handlers — in one place: a module of an application, a plugin. `fresh()` copies
+     * all it registered.
+     */
+    extend(extension) {
+        extension(this);
+        return this;
     }
     /** Answers a failure that reaches `execute` (or a scope's): after every layer's handlers. */
     addGlobalErrorHandler(handler) {
@@ -121,20 +203,21 @@ export class BoundedContext {
         this.revision++;
         return this;
     }
-    execute(command, _returnType) {
-        return executeTyped((one) => this.generation().root(one, {}), command);
+    execute(executable, second) {
+        // As with Python's return_type, the answer is not validated at runtime.
+        return this.generation().root(executable, {}, optionsOf(second));
     }
     scoped(context) {
         const scope = { ...context };
-        return new FeatureBus((command) => this.generation().root(command, scope));
+        return new FeatureBus((executable, options) => this.generation().root(executable, scope, options));
     }
     buildRootBus() {
         this.generation();
     }
     fresh() {
         const fresh = new BoundedContext(this.name);
-        for (const [command, registration] of this.registrations) {
-            fresh.registrations.set(command, registration);
+        for (const [dto, registration] of this.registrations) {
+            fresh.registrations.set(dto, registration);
         }
         for (const [name, dependency] of this.dependencyValues) {
             fresh.dependencyValues.set(name, dependency);
@@ -143,9 +226,35 @@ export class BoundedContext {
             fresh.handlers[where].push(...this.handlers[where]);
         }
         fresh.expected.push(...this.expected);
+        fresh.interceptors.push(...this.interceptors);
+        for (const moment of ["started", "completed", "failed"]) {
+            for (const one of this.listeners[moment])
+                fresh.listeners[moment].add(one);
+        }
         fresh.revision = this.revision;
         return fresh;
     }
+    /** What escaped a call, told once, from where it first failed. */
+    escaped(executable, error, expected) {
+        const at = failedAt(error);
+        let outcome = "failed";
+        try {
+            outcome =
+                at?.outcome ?? (expected(error) ? "refused" : observabilityNow().outcomeOf(error));
+        }
+        catch {
+            // An outcome that cannot be told is a failure.
+        }
+        const heard = {
+            executable: at?.executable ?? executable,
+            execution: at?.execution,
+            layer: at?.layer,
+            error,
+            outcome,
+        };
+        announceTo(this.listeners.failed, heard);
+        announceTo(processHearing().failed, heard);
+    }
     addErrorHandler(where, handler) {
         if (typeof handler !== "function")
             throw new TypeError("An error handler is a function");
@@ -153,9 +262,9 @@ export class BoundedContext {
         this.revision++;
         return this;
     }
-    registrar(command, layer) {
+    registrar(dto, layer, options = {}) {
         return (Service, decorator) => {
-            const register = () => this.registerService(command, Service, layer);
+            const register = () => this.registerService(dto, Service, layer, options.replaces);
             // Standard decorators run before static fields have initialized.
             if (decorator)
                 decorator.addInitializer(register);
@@ -164,23 +273,54 @@ export class BoundedContext {
             return Service;
         };
     }
-    registerService(command, Service, layer) {
+    /**
+     * 1. The service is of the layer it is registered in, for a Command or a domain event class.
+     * 2. The class has no service yet — or, with `replaces`, the one it has is that one.
+     * 3. Its `serviceName` is given and no other service has it; an event's `eventName` is given
+     *    and no other event class here has it — the name means one event.
+     * Final: registered, said on its spans when it replaced another; the next call answers with it.
+     */
+    registerService(dto, Service, layer, replaces) {
         const Base = layer === "feature" ? Feature : ApplicationService;
         if (!(Service.prototype instanceof Base) ||
             (layer === "feature" && Service.prototype instanceof ApplicationService)) {
             throw new TypeError(`The service is not an ${layer}`);
         }
-        if (this.registrations.has(command)) {
+        const event = isEventClass(dto);
+        if (!event && !(dto.prototype instanceof Command)) {
+            throw new TypeError("A service is registered for a Command or a DomainEvent class");
+        }
+        const current = this.registrations.get(dto);
+        if (replaces !== undefined && current?.Service !== replaces) {
+            throw new Error(`Replacement does not match the registration: ${nameOf(replaces)}`);
+        }
+        if (replaces === undefined && current) {
             throw new Error("Command already registered: one executor across both layers");
         }
         const name = Service.serviceName;
         if (typeof name !== "string" || name.trim() === "") {
             throw new Error("A service needs a nonempty registered name");
         }
-        if ([...this.registrations.values()].some((registration) => registration.name === name)) {
-            throw new Error(`Service name already registered: ${name}`);
+        for (const [other, registration] of this.registrations) {
+            if (registration !== current && registration.name === name) {
+                throw new Error(`Service name already registered: ${name}`);
+            }
+            if (event &&
+                other !== dto &&
+                isEventClass(other) &&
+                other.eventName === dto.eventName) {
+                throw new Error(`Event name already registered: ${dto.eventName}`);
+            }
+        }
+        if (event && (typeof dto.eventName !== "string" || dto.eventName.trim() === "")) {
+            throw new Error("A domain event needs a nonempty eventName");
         }
-        this.registrations.set(command, { name, layer, Service });
+        this.registrations.set(dto, {
+            name,
+            layer,
+            Service,
+            ...(current ? { replaces: current.name } : {}),
+        });
         this.revision++;
     }
     generation() {
@@ -202,6 +342,18 @@ export class BoundedContext {
         };
         const expectedTypes = [...this.expected];
         const expected = (error) => expectedTypes.some((type) => error instanceof type);
+        const interceptors = [...this.interceptors];
+        const everyContext = processHearing();
+        const announce = {
+            started: (heard) => {
+                announceTo(this.listeners.started, heard);
+                announceTo(everyContext.started, heard);
+            },
+            completed: (heard) => {
+                announceTo(this.listeners.completed, heard);
+                announceTo(everyContext.completed, heard);
+            },
+        };
         const instances = new Map();
         for (const registration of registrations.values()) {
             const instance = new registration.Service();
@@ -210,9 +362,9 @@ export class BoundedContext {
             }
             instances.set(registration, instance);
         }
-        const dispatch = async (command, parent, featureOnly = false, scope = {}) => {
-            // Exact constructor identity: a subclass of a registered Command is another Command.
-            const target = registrations.get(Object.getPrototypeOf(command)?.constructor);
+        const dispatch = async (executable, parent, featureOnly = false, scope = {}, options = {}) => {
+            // Exact constructor identity: a subclass of a registered class is another one.
+            const target = registrations.get(Object.getPrototypeOf(executable)?.constructor);
             if (!target)
                 throw new Error("No executor registered for this command class");
             if (featureOnly && target.layer !== "feature") {
@@ -222,29 +374,51 @@ export class BoundedContext {
             if (!service) {
                 throw new Error(`Registered service is unavailable: ${target.name}`);
             }
-            return executeService(service, command, {
+            const attributes = {
+                ...(executable instanceof DomainEvent ? { "sincpro.event": executable.name } : {}),
+                ...(target.replaces ? { "sincpro.replaces": target.replaces } : {}),
+            };
+            return executeService(service, executable, {
                 boundedContext: this.name,
                 name: target.name,
                 layer: target.layer,
+                attributes,
                 dependencies,
                 context: () => ({ ...processContext.values, ...this.context.values, ...scope }),
                 ...(parent ? { parent } : {}),
-                featureBus: (execution) => new FeatureBus((child) => dispatch(child, execution, true)),
+                // Only an event comes from outside with a cause; a child continues its parent.
+                ...(options.cause && executable instanceof DomainEvent && !parent
+                    ? { cause: options.cause }
+                    : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+                featureBus: (execution) => new FeatureBus((child, options) => dispatch(child, execution, true, {}, options)),
                 expected,
                 handlers: handlers[target.layer],
+                interceptors: interceptors
+                    .filter((one) => concerns(one.dtos, executable))
+                    .map((one) => one.what),
+                announce,
             });
         };
         return {
-            root: async (command, scope) => {
+            root: async (executable, scope, options) => {
                 try {
-                    return await dispatch(command, undefined, false, scope);
+                    return await dispatch(executable, undefined, false, scope, options);
                 }
                 catch (error) {
-                    if (handlers.global.length === 0)
-                        throw error;
-                    const answer = await handled(handlers.global, error);
-                    logHandled("bounded_context", { boundedContext: this.name });
-                    return answer;
+                    let escaping = error;
+                    if (handlers.global.length > 0) {
+                        try {
+                            const answer = await handled(handlers.global, error);
+                            logHandled("bounded_context", { boundedContext: this.name });
+                            return answer;
+                        }
+                        catch (thrown) {
+                            escaping = thrown;
+                        }
+                    }
+                    this.escaped(executable, escaping, expected);
+                    throw escaping;
                 }
             },
         };

package/dist/core/index.d.ts

@@ -9,9 +9,11 @@
  *   infrastructure/  `configureProcess`, `configureLogger`
  */
 export { type CommandBus, FeatureBus } from "./domain/bus.js";
-export { Command, DataTransferObject, Response, } from "./domain/dto.js";
+export { Command, DataTransferObject, DomainEvent, type EventClass, Response, } from "./domain/dto.js";
 export type { ErrorClass, ErrorHandler } from "./domain/errors.js";
+export type { CallNext, Cause, ExecuteOptions, ExecutionCompleted, ExecutionFailed, ExecutionStarted, Extension, InterceptedRun, Interceptor, Listener, PipelineLayer, } from "./domain/pipeline.js";
 export { ApplicationService, Feature } from "./domain/services.js";
-export { BoundedContext } from "./entrypoint/bounded-context.js";
+export { BoundedContext, type Registrar, type RegistrationOptions, } from "./entrypoint/bounded-context.js";
 export { screensTransport } from "./entrypoint/screens.js";
+export { processListeners } from "./infrastructure/listeners.js";
 export { configureLogger, configureProcess, type LoggerConfiguration, type ProcessOptions, } from "./infrastructure/process.js";

package/dist/core/index.js

@@ -9,8 +9,9 @@
  *   infrastructure/  `configureProcess`, `configureLogger`
  */
 export { FeatureBus } from "./domain/bus.js";
-export { Command, DataTransferObject, Response, } from "./domain/dto.js";
+export { Command, DataTransferObject, DomainEvent, Response, } from "./domain/dto.js";
 export { ApplicationService, Feature } from "./domain/services.js";
-export { BoundedContext } from "./entrypoint/bounded-context.js";
+export { BoundedContext, } from "./entrypoint/bounded-context.js";
 export { screensTransport } from "./entrypoint/screens.js";
+export { processListeners } from "./infrastructure/listeners.js";
 export { configureLogger, configureProcess, } from "./infrastructure/process.js";

package/dist/core/infrastructure/listeners.d.ts

@@ -0,0 +1,28 @@
+import type { ExecutionCompleted, ExecutionFailed, ExecutionStarted, Listener } from "../domain/pipeline.js";
+import { type ExecutableClass, type Hearing } from "../services/listening.js";
+/**
+ * Who hears every bounded context of this process — the backend's process listeners: an
+ * activity indicator, a toast, an audit that must not be wired into each context.
+ *
+ *     const stop = processListeners.onFailure((failed) => toast(failed.execution?.useCase));
+ *
+ * Context: a bounded context's own listeners (`project.onStart`) hear it alone; these hear all of
+ * them, after its own. They live as long as the process — `configureProcess` does not clear
+ * them —, so whoever adds one keeps the function that stops it.
+ */
+declare const hearing: {
+    started: Set<Hearing<Listener<ExecutionStarted>>>;
+    completed: Set<Hearing<Listener<ExecutionCompleted>>>;
+    failed: Set<Hearing<Listener<ExecutionFailed>>>;
+};
+/** @internal — what the bounded contexts announce to, besides their own listeners. */
+export declare function processHearing(): typeof hearing;
+export declare const processListeners: {
+    /** Hears every run of every bounded context begin. Answers how to stop. */
+    onStart(listener: Listener<ExecutionStarted>, ...dtos: ExecutableClass[]): () => void;
+    /** Hears every service that answered, in every bounded context. */
+    onCompletion(listener: Listener<ExecutionCompleted>, ...dtos: ExecutableClass[]): () => void;
+    /** Hears every failure that escapes a call, once, where it failed. */
+    onFailure(listener: Listener<ExecutionFailed>, ...dtos: ExecutableClass[]): () => void;
+};
+export {};

package/dist/core/infrastructure/listeners.js

@@ -0,0 +1,34 @@
+import { listenIn, } from "../services/listening.js";
+/**
+ * Who hears every bounded context of this process — the backend's process listeners: an
+ * activity indicator, a toast, an audit that must not be wired into each context.
+ *
+ *     const stop = processListeners.onFailure((failed) => toast(failed.execution?.useCase));
+ *
+ * Context: a bounded context's own listeners (`project.onStart`) hear it alone; these hear all of
+ * them, after its own. They live as long as the process — `configureProcess` does not clear
+ * them —, so whoever adds one keeps the function that stops it.
+ */
+const hearing = {
+    started: new Set(),
+    completed: new Set(),
+    failed: new Set(),
+};
+/** @internal — what the bounded contexts announce to, besides their own listeners. */
+export function processHearing() {
+    return hearing;
+}
+export const processListeners = {
+    /** Hears every run of every bounded context begin. Answers how to stop. */
+    onStart(listener, ...dtos) {
+        return listenIn(hearing.started, listener, dtos);
+    },
+    /** Hears every service that answered, in every bounded context. */
+    onCompletion(listener, ...dtos) {
+        return listenIn(hearing.completed, listener, dtos);
+    },
+    /** Hears every failure that escapes a call, once, where it failed. */
+    onFailure(listener, ...dtos) {
+        return listenIn(hearing.failed, listener, dtos);
+    },
+};

package/dist/core/services/binding.d.ts

@@ -1,6 +1,6 @@
 import { type Execution } from "../../context/domain/execution.js";
 /**
- * A dependency as the execution should see it: bound when it can be (`BIND`, or a `Transport`),
- * as it is otherwise.
+ * A dependency as the execution should see it: bound when it can be (`BIND`, a `Transport`, an
+ * `OperationTransport`), as it is otherwise.
  */
 export declare function bindDependency<T>(value: T, execution: Execution): T;

package/dist/core/services/binding.js

@@ -1,13 +1,16 @@
-import { bindTransport, isTransport, } from "../../client/services/propagation.js";
+import { isOperationTransport } from "../../client/domain/operation.js";
+import { bindOperations, bindTransport, isTransport, } from "../../client/services/propagation.js";
 import { BIND, isBindable, } from "../../context/domain/execution.js";
 /**
- * A dependency as the execution should see it: bound when it can be (`BIND`, or a `Transport`),
- * as it is otherwise.
+ * A dependency as the execution should see it: bound when it can be (`BIND`, a `Transport`, an
+ * `OperationTransport`), as it is otherwise.
  */
 export function bindDependency(value, execution) {
     if (isBindable(value))
         return value[BIND](execution);
     if (isTransport(value))
         return bindTransport(value, execution);
+    if (isOperationTransport(value))
+        return bindOperations(value, execution);
     return value;
 }