@sincpro/client-framework 1.0.0 → 1.2.0

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

@@ -1,13 +1,15 @@
+import type { Execution } from "../../context/domain/execution.js";
 import type { ContextValues } from "../../context/domain/store.js";
 import type { FeatureBus } from "./bus.js";
-import type { Command } from "./dto.js";
+import type { Command, DomainEvent } from "./dto.js";
 import type { LayerLogger } from "../../observability/domain/logging.js";
 import type { Span } from "../../observability/domain/tracing.js";
 /**
  * The services of the application layer, as sincpro_framework's: a Feature executes one
- * registered Command; an ApplicationService composes its context's Features.
+ * registered Command — or domain event, as its subscriber —; an ApplicationService composes its
+ * context's Features.
  *
- *     @project.feature(CommandCancelIssue)
+ *     @projectBoundedContext.feature(CommandCancelIssue)
  *     class CancelIssue extends Feature<CommandCancelIssue, ResponseCancelIssue> {
  *       static readonly serviceName = "CancelIssue";
  *       async execute(command: CommandCancelIssue) {
@@ -20,16 +22,25 @@ import type { Span } from "../../observability/domain/tracing.js";
  * every dependency are that run's (`executeService`). `serviceName` is stable metadata, never
  * `constructor.name`, which a minifier renames.
  */
-export declare abstract class Feature<C extends Command<R>, R, Context extends object = ContextValues> {
+export declare abstract class Feature<C extends Command<R> | DomainEvent, R, Context extends object = ContextValues> {
     /** What this run reads: the process's context, its bounded context's, its scope's. */
     readonly context: Readonly<Partial<Context>>;
     /** This run's span: `this.span.set({...})` says more about the use case. */
     readonly span: Span;
     /** This run's logger: every line carries its use case, execution and trace. */
     readonly logger: LayerLogger;
+    /** What cancels this run, when it was executed with one: check it in a long loop. */
+    readonly signal: AbortSignal | undefined;
+    /**
+     * This run: its id, use case, flow (`correlationId`) and cause. A use case of a delivered event
+     * finds the envelope's id as `causationId` — the key that makes executing it twice harmless; a
+     * use case an `EventSubscriber` executes finds the subscriber's run, so the subscriber hands the
+     * envelope's id in the Command when the effect must not repeat.
+     */
+    readonly execution: Execution;
     abstract execute(command: C): R | Promise<R>;
 }
-export declare abstract class ApplicationService<C extends Command<R>, R, Context extends object = ContextValues> extends Feature<C, R, Context> {
+export declare abstract class ApplicationService<C extends Command<R> | DomainEvent, R, Context extends object = ContextValues> extends Feature<C, R, Context> {
     /** The context's Features, run as children of this execution. */
     protected readonly featureBus: FeatureBus;
 }

package/dist/core/domain/services.js

@@ -1,8 +1,9 @@
 /**
  * The services of the application layer, as sincpro_framework's: a Feature executes one
- * registered Command; an ApplicationService composes its context's Features.
+ * registered Command — or domain event, as its subscriber —; an ApplicationService composes its
+ * context's Features.
  *
- *     @project.feature(CommandCancelIssue)
+ *     @projectBoundedContext.feature(CommandCancelIssue)
  *     class CancelIssue extends Feature<CommandCancelIssue, ResponseCancelIssue> {
  *       static readonly serviceName = "CancelIssue";
  *       async execute(command: CommandCancelIssue) {
@@ -25,4 +26,6 @@ export const RESERVED_MEMBERS = new Set([
     "context",
     "span",
     "logger",
+    "signal",
+    "execution",
 ]);

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

@@ -1,30 +1,49 @@
+import { BIND, type Execution } from "../../context/domain/execution.js";
 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.addFeatureErrorHandler(toEmptyWhenMissing);
- *     project.expectErrors(IssueClosed);                         // refused, never reported
- *     await project.execute(new CommandCancelIssue("x"));        // ResponseCancelIssue
- *     project.logger.info("Catalog preloaded");
+ *     const projectBoundedContext = new BoundedContext<ProjectDependencies>("project");
+ *     projectBoundedContext.addDependency("client", clientOf(operations));
+ *     projectBoundedContext.feature(CommandCancelIssue)(CancelIssue);   // or a decorator
+ *     projectBoundedContext.feature(IssueClosed)(ArchiveIssue);         // a use case of an event
+ *     projectBoundedContext.feature(CommandCancelIssue, { replaces: CancelIssue })(CancelAndArchive);
+ *     projectBoundedContext.addFeatureErrorHandler(toEmptyWhenMissing);
+ *     projectBoundedContext.expectErrors(IssueLocked);                  // refused, never reported
+ *     await projectBoundedContext.execute(new CommandCancelIssue("x")); // ResponseCancelIssue
+ *     await projectBoundedContext.execute(new IssueClosed("x"));        // what its use case returns
+ *     projectBoundedContext.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 may be the input of a use
+ * case, executed as a Command is: one per bounded context, through the same pipeline. Carrying
+ * it to whoever hears it (a queue, an outbox) is the platform's; an entrypoint that hears it and
+ * calls use cases is an `EventSubscriber`. Injected into another run — an `EventSubscriber`, a
+ * Feature of another bounded context — it is bound to that run (`BIND`).
  */
 export declare class BoundedContext<D extends object = Record<never, never>, C extends object = ContextValues> {
     readonly name: string;
@@ -36,6 +55,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 +65,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 +113,36 @@ 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;
+    /**
+     * This bounded context as `execution` calls it — what it is as a dependency of another run (an
+     * `EventSubscriber`, a Feature of another bounded context): what it executes is a child of
+     * that run — its span under the caller's, the same flow (`correlationId`), caused by it,
+     * cancelled with it, its errors reported once along it. It still runs with its own
+     * dependencies, context, interceptors and handlers.
+     */
+    [BIND](execution: Execution): this;
     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,14 @@
+import { BIND } from "../../context/domain/execution.js";
 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 +16,35 @@ 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.addFeatureErrorHandler(toEmptyWhenMissing);
- *     project.expectErrors(IssueClosed);                         // refused, never reported
- *     await project.execute(new CommandCancelIssue("x"));        // ResponseCancelIssue
- *     project.logger.info("Catalog preloaded");
+ *     const projectBoundedContext = new BoundedContext<ProjectDependencies>("project");
+ *     projectBoundedContext.addDependency("client", clientOf(operations));
+ *     projectBoundedContext.feature(CommandCancelIssue)(CancelIssue);   // or a decorator
+ *     projectBoundedContext.feature(IssueClosed)(ArchiveIssue);         // a use case of an event
+ *     projectBoundedContext.feature(CommandCancelIssue, { replaces: CancelIssue })(CancelAndArchive);
+ *     projectBoundedContext.addFeatureErrorHandler(toEmptyWhenMissing);
+ *     projectBoundedContext.expectErrors(IssueLocked);                  // refused, never reported
+ *     await projectBoundedContext.execute(new CommandCancelIssue("x")); // ResponseCancelIssue
+ *     await projectBoundedContext.execute(new IssueClosed("x"));        // what its use case returns
+ *     projectBoundedContext.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 may be the input of a use
+ * case, executed as a Command is: one per bounded context, through the same pipeline. Carrying
+ * it to whoever hears it (a queue, an outbox) is the platform's; an entrypoint that hears it and
+ * calls use cases is an `EventSubscriber`. Injected into another run — an `EventSubscriber`, a
+ * Feature of another bounded context — it is bound to that run (`BIND`).
  */
 export class BoundedContext {
     name;
@@ -40,6 +60,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 +115,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);
     }
-    appService(command) {
-        return this.registrar(command, "application_service");
+    /** 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);
+    }
+    /**
+     * 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 +206,46 @@ 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));
+    }
+    /**
+     * This bounded context as `execution` calls it — what it is as a dependency of another run (an
+     * `EventSubscriber`, a Feature of another bounded context): what it executes is a child of
+     * that run — its span under the caller's, the same flow (`correlationId`), caused by it,
+     * cancelled with it, its errors reported once along it. It still runs with its own
+     * dependencies, context, interceptors and handlers.
+     */
+    [BIND](execution) {
+        const caller = execution;
+        const execute = (executable, second) => this.generation().root(executable, {}, { ...optionsOf(second), caller });
+        const scoped = (context) => {
+            const scope = { ...context };
+            return new FeatureBus((executable, options) => this.generation().root(executable, scope, { ...options, caller }));
+        };
+        return new Proxy(this, {
+            get(target, property) {
+                if (property === "execute")
+                    return execute;
+                if (property === "scoped")
+                    return scoped;
+                const value = Reflect.get(target, property, target);
+                return typeof value === "function" ? value.bind(target) : value;
+            },
+        });
     }
     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 +254,36 @@ 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,
+            // Listeners hear use cases: a failure an entrypoint's run started says no layer.
+            layer: at?.layer === "entrypoint" ? undefined : 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 +291,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 +302,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}`);
+            }
         }
-        this.registrations.set(command, { name, layer, Service });
+        if (event && (typeof dto.eventName !== "string" || dto.eventName.trim() === "")) {
+            throw new Error("A domain event needs a nonempty eventName");
+        }
+        this.registrations.set(dto, {
+            name,
+            layer,
+            Service,
+            ...(current ? { replaces: current.name } : {}),
+        });
         this.revision++;
     }
     generation() {
@@ -202,6 +371,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 +391,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 +403,53 @@ 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)),
+                // A root called from another run continues it; a child continues its parent.
+                ...(options.caller && !parent ? { caller: options.caller } : {}),
+                // Only an event comes from outside with a cause.
+                ...(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";