@sincpro/client-framework 1.0.0 → 1.2.0

package/dist/common/failures.d.ts

@@ -0,0 +1,83 @@
+import type { FailureKind, NextStep, Problem } from "@sincpro/criteria";
+/**
+ * What kind of failure an error is, whatever raised it — the backend's `common/failures`, read
+ * on a client: a refusal the server explained, a request nobody answered, a run a screen
+ * cancelled, a local domain's own refusal, another backend's error a platform translated.
+ *
+ *     failureOf(new TransportError("/pay", 409, problem))   ->  { kind: "conflict", nextStep: "refresh_and_retry", … }
+ *     failureOf(new TransportError("/pay", null, null))      ->  { kind: "unknown_outcome", fault: true, … }
+ *     failureOf(new CreditExhausted())                       ->  what the class declares (`failureKind`)
+ *     failureOf(new TypeError("x"))                          ->  { kind: "internal", fault: true, … }
+ *
+ * Context: every client decides the same things about a failure — show it or report it, retry it
+ * or set it aside, ask to sign in again —, and each app was deciding them its own way. The words
+ * are the wire's (`FailureKind`, `NextStep`, `Problem` from @sincpro/criteria), the rules the
+ * backend's: a retryable kind is retried after `retryAfter`; a permanent one fails the same way on
+ * every attempt and is set aside; a fault is the system's problem and is reported. An error says
+ * its own kind (`failureKind`, as the backend's errors do), so nothing here knows who raised it:
+ * a platform's adapter translates its backend's errors into errors that declare one.
+ */
+export type Failure = {
+    readonly kind: FailureKind;
+    /** UPPER_SNAKE and stable: what a client switches on. */
+    readonly reason: string;
+    /** What the caller does next. */
+    readonly nextStep: NextStep;
+    /** Whether sending the same thing again — as it is, or after a fresh read — may succeed. */
+    readonly retryable: boolean;
+    /** Seconds to wait before retrying; none when retrying does not help. */
+    readonly retryAfter: number | undefined;
+    /** It fails the same way on every attempt: a queue sets it aside, never retries it. */
+    readonly permanent: boolean;
+    /** The system's problem — a bug, a server down, no answer —, not an answer to the caller. */
+    readonly fault: boolean;
+    /** Whoever asked stopped waiting: not a failure of anyone. */
+    readonly aborted: boolean;
+    /** What the server said, when it said it. */
+    readonly problem: Problem | undefined;
+};
+/**
+ * What an error can say about itself — on the instance or as a static of its class:
+ *
+ *     class CreditExhausted extends Error {
+ *       static readonly failureKind = "exhausted";
+ *       readonly retryAfter = 30;
+ *     }
+ */
+export type DeclaredFailure = {
+    readonly failureKind?: FailureKind;
+    readonly reason?: string;
+    readonly retryAfter?: number;
+};
+/** The kinds that fail the same way on every attempt — set aside at the first failure. */
+export declare const PERMANENT_KINDS: ReadonlySet<FailureKind>;
+/**
+ * The kind each wire's own code stands for, when an answer carries no `Problem` — the backend's
+ * tables, read back, so a transport of any wire (REST, JSON-RPC, gRPC, another backend's) builds
+ * errors that declare the same kinds:
+ *
+ *     class RpcError extends Error {
+ *       constructor(readonly code: number, message: string) { super(message); }
+ *       get failureKind() { return kindOfJsonRpcCode(this.code); }
+ *     }
+ */
+export declare function kindOfHttpStatus(status: number): FailureKind;
+/** The kind a gRPC status code stands for — the backend's gRPC table, read back. */
+export declare function kindOfGrpcCode(code: number): FailureKind;
+/** The kind a JSON-RPC error code stands for — the backend's catalogue, read back. */
+export declare function kindOfJsonRpcCode(code: number): FailureKind;
+/**
+ * The failure `error` is.
+ *
+ * 1. Whoever asked stopped waiting (`AbortError`): aborted — a write may have run, so its kind is
+ *    `unknown_outcome`, but it is nobody's failure.
+ * 2. What the error declares (`failureKind`, `reason`, `retryAfter`), on itself or its class.
+ * 3. What the server said (`problem`, a `Problem` — the same over REST, JSON-RPC and gRPC): its
+ *    kind, reason, next step and wait.
+ * 4. A REST answer (`TransportError`) with a status and no problem: the kind its HTTP status
+ *    stands for. Another wire's transport declares its kind instead (`kindOfGrpcCode`,
+ *    `kindOfJsonRpcCode`).
+ * 5. A request that got no answer (`status: null`): `unknown_outcome` — it may have run.
+ * Final: anything else is `internal`, a fault.
+ */
+export declare function failureOf(error: unknown): Failure;

package/dist/common/failures.js

@@ -0,0 +1,212 @@
+/** The kinds that fail the same way on every attempt — set aside at the first failure. */
+export const PERMANENT_KINDS = new Set([
+    "invalid",
+    "unauthenticated",
+    "permission_denied",
+    "not_found",
+    "key_reused",
+    "domain",
+]);
+/** What the caller does next, by kind — the backend's `NEXT_STEP_OF`. */
+const NEXT_STEP_OF = {
+    invalid: "fix_request",
+    unauthenticated: "authenticate",
+    permission_denied: "ask_for_access",
+    not_found: "do_not_retry",
+    conflict: "refresh_and_retry",
+    in_progress: "retry_later",
+    key_reused: "fix_request",
+    domain: "do_not_retry",
+    exhausted: "retry_later",
+    unavailable: "retry_later",
+    unknown_outcome: "verify_then_retry",
+    internal: "retry_later",
+};
+/** The kinds that are the system's problem: reported, never shown as the caller's answer. */
+const FAULTS = new Set([
+    "internal",
+    "unavailable",
+    "unknown_outcome",
+]);
+const RETRYABLE_STEPS = new Set([
+    "retry_later",
+    "refresh_and_retry",
+]);
+/** A retryable kind that says nothing waits a second, as the backend's `DEFAULT_RETRY_AFTER`. */
+const DEFAULT_RETRY_AFTER = 1;
+const KINDS = new Set(Object.keys(NEXT_STEP_OF));
+function isKind(value) {
+    return typeof value === "string" && KINDS.has(value);
+}
+/**
+ * The kind each wire's own code stands for, when an answer carries no `Problem` — the backend's
+ * tables, read back, so a transport of any wire (REST, JSON-RPC, gRPC, another backend's) builds
+ * errors that declare the same kinds:
+ *
+ *     class RpcError extends Error {
+ *       constructor(readonly code: number, message: string) { super(message); }
+ *       get failureKind() { return kindOfJsonRpcCode(this.code); }
+ *     }
+ */
+export function kindOfHttpStatus(status) {
+    if (status === 401)
+        return "unauthenticated";
+    if (status === 403)
+        return "permission_denied";
+    if (status === 404 || status === 410)
+        return "not_found";
+    if (status === 409 || status === 412)
+        return "conflict";
+    if (status === 429)
+        return "exhausted";
+    if (status === 502 || status === 503)
+        return "unavailable";
+    if (status === 504)
+        return "unknown_outcome";
+    if (status >= 500)
+        return "internal";
+    return "invalid";
+}
+/** The kind a gRPC status code stands for — the backend's gRPC table, read back. */
+export function kindOfGrpcCode(code) {
+    switch (code) {
+        case 3: // INVALID_ARGUMENT
+        case 11: // OUT_OF_RANGE
+            return "invalid";
+        case 16: // UNAUTHENTICATED
+            return "unauthenticated";
+        case 7: // PERMISSION_DENIED
+            return "permission_denied";
+        case 5: // NOT_FOUND
+        case 12: // UNIMPLEMENTED
+            return "not_found";
+        case 6: // ALREADY_EXISTS
+        case 10: // ABORTED — also an idempotent run in flight
+            return "conflict";
+        case 9: // FAILED_PRECONDITION — also a reused idempotency key
+            return "domain";
+        case 8: // RESOURCE_EXHAUSTED
+            return "exhausted";
+        case 14: // UNAVAILABLE
+            return "unavailable";
+        case 1: // CANCELLED
+        case 4: // DEADLINE_EXCEEDED
+            return "unknown_outcome";
+        default: // UNKNOWN, INTERNAL, DATA_LOSS
+            return "internal";
+    }
+}
+/** The kind a JSON-RPC error code stands for — the backend's catalogue, read back. */
+export function kindOfJsonRpcCode(code) {
+    switch (code) {
+        case -32700:
+        case -32600:
+        case -32602:
+            return "invalid";
+        case -32601:
+        case -32004:
+            return "not_found";
+        case -32000:
+            return "unavailable";
+        case -32001:
+            return "unauthenticated";
+        case -32003:
+            return "permission_denied";
+        case -32009:
+            return "conflict";
+        case -32010:
+            return "domain";
+        case -32022:
+            return "key_reused";
+        case -32024:
+            return "unknown_outcome";
+        case -32029: // an idempotent run in flight, or a limit spent — the problem says which
+            return "exhausted";
+        default:
+            return "internal";
+    }
+}
+function upperSnake(kind) {
+    return kind.toUpperCase();
+}
+/** What the error declares: on itself first, then on its class. */
+function declared(error) {
+    const own = error;
+    const type = (error.constructor ?? {});
+    return {
+        ...(isKind(own.failureKind ?? type.failureKind)
+            ? { failureKind: own.failureKind ?? type.failureKind }
+            : {}),
+        ...(typeof (own.reason ?? type.reason) === "string"
+            ? { reason: own.reason ?? type.reason }
+            : {}),
+        ...(typeof (own.retryAfter ?? type.retryAfter) === "number"
+            ? { retryAfter: own.retryAfter ?? type.retryAfter }
+            : {}),
+    };
+}
+function isProblem(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        isKind(value.kind) &&
+        typeof value.next_step === "string");
+}
+function failure(kind, said, aborted = false) {
+    const nextStep = said.nextStep ?? NEXT_STEP_OF[kind];
+    const retryable = RETRYABLE_STEPS.has(nextStep);
+    return {
+        kind,
+        reason: said.reason ?? upperSnake(kind),
+        nextStep,
+        retryable,
+        retryAfter: retryable ? (said.retryAfter ?? DEFAULT_RETRY_AFTER) : undefined,
+        permanent: !aborted && PERMANENT_KINDS.has(kind),
+        fault: !aborted && FAULTS.has(kind),
+        aborted,
+        problem: said.problem,
+    };
+}
+/**
+ * The failure `error` is.
+ *
+ * 1. Whoever asked stopped waiting (`AbortError`): aborted — a write may have run, so its kind is
+ *    `unknown_outcome`, but it is nobody's failure.
+ * 2. What the error declares (`failureKind`, `reason`, `retryAfter`), on itself or its class.
+ * 3. What the server said (`problem`, a `Problem` — the same over REST, JSON-RPC and gRPC): its
+ *    kind, reason, next step and wait.
+ * 4. A REST answer (`TransportError`) with a status and no problem: the kind its HTTP status
+ *    stands for. Another wire's transport declares its kind instead (`kindOfGrpcCode`,
+ *    `kindOfJsonRpcCode`).
+ * 5. A request that got no answer (`status: null`): `unknown_outcome` — it may have run.
+ * Final: anything else is `internal`, a fault.
+ */
+export function failureOf(error) {
+    if (error === null || typeof error !== "object")
+        return failure("internal", {});
+    const named = error.name;
+    if (named === "AbortError")
+        return failure("unknown_outcome", {}, true);
+    const own = declared(error);
+    if (own.failureKind !== undefined)
+        return failure(own.failureKind, {
+            ...(own.reason !== undefined ? { reason: own.reason } : {}),
+            ...(own.retryAfter !== undefined ? { retryAfter: own.retryAfter } : {}),
+        });
+    const answered = error;
+    if (isProblem(answered.problem)) {
+        const problem = answered.problem;
+        return failure(problem.kind, {
+            reason: problem.reason,
+            nextStep: problem.next_step,
+            ...(problem.retry_after !== undefined ? { retryAfter: problem.retry_after } : {}),
+            problem,
+        });
+    }
+    if ("problem" in answered && "status" in answered) {
+        if (typeof answered.status === "number")
+            return failure(kindOfHttpStatus(answered.status), {});
+        if (answered.status === null)
+            return failure("unknown_outcome", {});
+    }
+    return failure("internal", {});
+}

package/dist/common/index.d.ts

@@ -4,6 +4,7 @@
  */
 export { collectionOf, type EntityCollection, type HeldCollection, isCollection, isPartial, relatedCriteria, type RelationKeys, totalOf, } from "./collection.js";
 export { Decimal, type DecimalLike } from "./decimal.js";
+export { type DeclaredFailure, type Failure, failureOf, kindOfGrpcCode, kindOfHttpStatus, kindOfJsonRpcCode, PERMANENT_KINDS, } from "./failures.js";
 export { isEntityId, momentOf, newEntityId } from "./ids.js";
 export { Money } from "./money.js";
 export { BYTES, type JsonValue, pack, readValues, type Rebuild, rebuilt, unpack, valuesOf, } from "./serialization.js";

package/dist/common/index.js

@@ -4,6 +4,7 @@
  */
 export { collectionOf, isCollection, isPartial, relatedCriteria, totalOf, } from "./collection.js";
 export { Decimal } from "./decimal.js";
+export { failureOf, kindOfGrpcCode, kindOfHttpStatus, kindOfJsonRpcCode, PERMANENT_KINDS, } from "./failures.js";
 export { isEntityId, momentOf, newEntityId } from "./ids.js";
 export { Money } from "./money.js";
 export { BYTES, pack, readValues, rebuilt, unpack, valuesOf, } from "./serialization.js";

package/dist/context/domain/execution.d.ts

@@ -17,6 +17,18 @@ export type Execution = {
     readonly boundedContext: string;
     /** The run that executed this one: an ApplicationService, for its Features. */
     readonly parent: Execution | undefined;
+    /**
+     * The chain it belongs to: the id of what started it all — the root run, or the first event
+     * of a flow it continues. Every run and event of one flow share it.
+     */
+    readonly correlationId: string;
+    /** What directly caused it: its parent run, or the event it executes; none for a root. */
+    readonly causationId: string | undefined;
+    /**
+     * What cancels it: the signal it was executed with, inherited by its Features — and by every
+     * request its bound transport sends.
+     */
+    readonly signal: AbortSignal | undefined;
     readonly span: Span;
     /** What it runs with, read once where the gesture started and inherited by every child. */
     readonly context: Readonly<Record<string, unknown>>;

package/dist/context/entrypoint/context.d.ts

@@ -1,18 +1,19 @@
 import type { ContextStore, ContextValues } from "../domain/store.js";
 /**
  * One level of the context: the process's (`processContext`) or a bounded context's
- * (`project.context`), read and written the same way on every platform.
+ * (`projectBoundedContext.context`), read and written the same way on every platform.
  *
  *     processContext.set({ tenant_id: "acme" });      the company changed — every screen hears it
  *     processContext.get("tenant_id")                  →  "acme"
- *     project.context.set({ warehouse_id: 4 });        only what `project` runs
+ *     projectBoundedContext.context.set({ warehouse_id: 4 });   only what it runs
  *     const stop = processContext.watch(() => redraw());
  *
  * Context: sincpro_framework reads its context from a tree — the process, the bounded context,
  * the scope, the execution — and the nearest wins. A client has the same levels: a use case runs
  * with the process's values, under them its bounded context's, under them a scope's
- * (`project.scoped({...})`), read once where the gesture starts and inherited by every Feature
- * it runs. That snapshot is `this.context` and what travels to the server in `sincpro-context`.
+ * (`projectBoundedContext.scoped({...})`), read once where the gesture starts and inherited by
+ * every Feature it runs. That snapshot is `this.context` and what travels to the server in
+ * `sincpro-context`.
  *
  * Where the values live is the platform's (`ContextStore`): this is only the door. `values` is
  * the same object until something changes it, so a screen can hand it straight to React's

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

@@ -1,12 +1,19 @@
-import type { AnyCommand, Command, ResponseClass } from "./dto.js";
-/** What executes a Command: the bounded context, a scope of it, an ApplicationService's features. */
+import type { Command, DomainEvent, Executable, ResponseClass } from "./dto.js";
+import type { Cause, ExecuteOptions } from "./pipeline.js";
+/** What the second argument of `execute` is: options, a delivered event's cause, or a type. */
+export declare function optionsOf(second: unknown): ExecuteOptions;
+/**
+ * What executes a Command or a domain event: the bounded context, a scope of it, an
+ * ApplicationService's features. A Command answers its Response; an event, whatever its
+ * subscriber returns.
+ */
 export interface CommandBus {
     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>;
 }
-/** @internal — how a bus hands a Command to its generation. */
-export type Dispatch = (command: AnyCommand) => Promise<unknown>;
-/** @internal — the heterogeneous registry erases the type; registration checks the association. */
-export declare function executeTyped<R>(dispatch: Dispatch, command: Command<R>): Promise<R>;
+/** @internal — how a bus hands what it executes to its generation. */
+export type Dispatch = (executable: Executable, options: ExecuteOptions) => Promise<unknown>;
 /**
  * What an ApplicationService composes its context's Features through (`this.featureBus`): the
  * same pipeline, as a child of the running execution, and Features only.
@@ -14,5 +21,7 @@ export declare function executeTyped<R>(dispatch: Dispatch, command: Command<R>)
 export declare class FeatureBus implements CommandBus {
     private readonly dispatch;
     constructor(dispatch: Dispatch);
-    execute<R>(command: Command<R>, _returnType?: ResponseClass<NoInfer<R>>): Promise<R>;
+    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>;
 }

package/dist/core/domain/bus.js

@@ -1,7 +1,14 @@
-/** @internal — the heterogeneous registry erases the type; registration checks the association. */
-export async function executeTyped(dispatch, command) {
-    // As with Python's return_type, this does not validate the returned data at runtime.
-    return (await dispatch(command));
+/** What the second argument of `execute` is: options, a delivered event's cause, or a type. */
+export function optionsOf(second) {
+    if (second === null || typeof second !== "object")
+        return {};
+    const given = second;
+    if (typeof given.id === "string" && typeof given.correlationId === "string")
+        return { cause: { id: given.id, correlationId: given.correlationId } };
+    return {
+        ...(given.signal ? { signal: given.signal } : {}),
+        ...(given.cause ? { cause: given.cause } : {}),
+    };
 }
 /**
  * What an ApplicationService composes its context's Features through (`this.featureBus`): the
@@ -12,7 +19,8 @@ export class FeatureBus {
     constructor(dispatch) {
         this.dispatch = dispatch;
     }
-    execute(command, _returnType) {
-        return executeTyped(this.dispatch, command);
+    execute(executable, second) {
+        // As with Python's return_type, the answer is not validated at runtime.
+        return this.dispatch(executable, optionsOf(second));
     }
 }

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

@@ -5,7 +5,7 @@
  *     class CommandCancelIssue extends Command<ResponseCancelIssue> {
  *       constructor(readonly issue_id: string) { super(); }
  *     }
- *     const answer = await project.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
+ *     const answer = await projectBoundedContext.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
  *
  * Context: the backend asks `bus(dto, ResponseType)` for the type; here the Command carries it, so
  * `execute` infers it with no second argument. The association is type-only: absent from a
@@ -22,11 +22,41 @@ export declare abstract class Command<R> extends DataTransferObject {
     /** Type-only association: absent from serialized DTOs and not a runtime validator. */
     readonly [responseType]: R;
 }
+/**
+ * A fact that already happened, as sincpro_framework's `DomainEvent`: executed like a Command, by
+ * the Feature or ApplicationService registered for its class — its subscriber in this bounded
+ * context —, through the same pipeline. Delivering it (a queue, an outbox) is the platform's.
+ *
+ *     class OrderPaid extends DomainEvent {
+ *       static readonly eventName = "shop.order.v1.paid";
+ *       constructor(readonly order_id: string) { super(); }
+ *     }
+ *     projectBoundedContext.feature(OrderPaid)(NotifyCustomer);
+ *     await projectBoundedContext.execute(new OrderPaid("o-1"));
+ *
+ * Context: the backend names an event on the wire by `name`, `<context>.<aggregate>.vN.<fact>`,
+ * and defaults it to the class's name; a client is minified, so the name is declared, as
+ * `serviceName` is. `name` is reserved, as the backend reserves it: every event reads its class's
+ * `eventName` there, and a subclass cannot make it a field.
+ */
+export declare abstract class DomainEvent extends DataTransferObject {
+    protected readonly eventBrand: void;
+    /** Its wire name: its class's `eventName`. */
+    get name(): string;
+}
+/** What an event class declares: the name it is known by on the wire. */
+type EventNamed = {
+    readonly eventName: string;
+};
 export type AnyCommand = Command<unknown>;
-/** What a Command answers. */
-export type Answer<C extends AnyCommand> = C[typeof responseType];
+/** What a service is registered for and executes: a Command, or a domain event. */
+export type Executable = AnyCommand | DomainEvent;
+/** What it answers: a Command's Response; whatever its subscriber returns, for an event. */
+export type Answer<T> = T extends Command<infer R> ? R : unknown;
 /** A Command's class: what a service is registered for, by exact constructor identity. */
 export type CommandClass<C extends AnyCommand> = abstract new (...args: never[]) => C;
+/** A domain event's class, with its wire name. */
+export type EventClass<E extends DomainEvent> = (abstract new (...args: never[]) => E) & EventNamed;
 /** A Response's class: the backend's `return_type`, accepted for the same reading. */
 export type ResponseClass<R> = abstract new (...args: never[]) => R;
 export {};

package/dist/core/domain/dto.js

@@ -5,7 +5,7 @@
  *     class CommandCancelIssue extends Command<ResponseCancelIssue> {
  *       constructor(readonly issue_id: string) { super(); }
  *     }
- *     const answer = await project.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
+ *     const answer = await projectBoundedContext.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
  *
  * Context: the backend asks `bus(dto, ResponseType)` for the type; here the Command carries it, so
  * `execute` infers it with no second argument. The association is type-only: absent from a
@@ -18,3 +18,26 @@ export class Response extends DataTransferObject {
 }
 export class Command extends DataTransferObject {
 }
+/**
+ * A fact that already happened, as sincpro_framework's `DomainEvent`: executed like a Command, by
+ * the Feature or ApplicationService registered for its class — its subscriber in this bounded
+ * context —, through the same pipeline. Delivering it (a queue, an outbox) is the platform's.
+ *
+ *     class OrderPaid extends DomainEvent {
+ *       static readonly eventName = "shop.order.v1.paid";
+ *       constructor(readonly order_id: string) { super(); }
+ *     }
+ *     projectBoundedContext.feature(OrderPaid)(NotifyCustomer);
+ *     await projectBoundedContext.execute(new OrderPaid("o-1"));
+ *
+ * Context: the backend names an event on the wire by `name`, `<context>.<aggregate>.vN.<fact>`,
+ * and defaults it to the class's name; a client is minified, so the name is declared, as
+ * `serviceName` is. `name` is reserved, as the backend reserves it: every event reads its class's
+ * `eventName` there, and a subclass cannot make it a field.
+ */
+export class DomainEvent extends DataTransferObject {
+    /** Its wire name: its class's `eventName`. */
+    get name() {
+        return this.constructor.eventName ?? "";
+    }
+}

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

@@ -1,12 +1,12 @@
 /**
  * What answers a use case's failure instead of raising it — sincpro_framework's error handlers.
  *
- *     project.addFeatureErrorHandler((error) => {
+ *     projectBoundedContext.addFeatureErrorHandler((error) => {
  *       if (error instanceof IssueNotFound) return new ResponseEmpty();   // the answer
  *       throw error;                                                     // the next handler
  *     });
  *
- * Context: three chains per bounded context — global (around `project.execute`), feature and
+ * Context: three chains per bounded context — global (around `projectBoundedContext.execute`), feature and
  * application service —, each run first-registered-first. A handler that throws hands what it
  * threw to the next; the last one's throw reaches the caller. The failure was already recorded
  * where it happened (its span, its log line and, when unexpected, its report): a handler decides

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

@@ -0,0 +1,89 @@
+import type { Execution } from "../../context/domain/execution.js";
+import type { Executable } from "./dto.js";
+import type { LayerLogger } from "../../observability/domain/logging.js";
+import type { Outcome } from "../../observability/domain/tracing.js";
+/**
+ * Where the execution pipeline is extended — as sincpro_framework's `bus_pipeline`, in two kinds:
+ *
+ *     control       interceptors   wrap the service: look, veto, adjust or answer
+ *     observation   listeners      a run started, answered, or a failure escaped: heard, never changed
+ *
+ *     projectBoundedContext.interceptor(CommandPay)(async (command, next, run) => {
+ *       if (!credit.allows(command.customer_id)) throw new NoCredit();   // veto
+ *       return next(command);                                             // the next, or the service
+ *     });
+ *     projectBoundedContext.onCompletion((done) => activity.succeeded(done.execution.useCase));
+ *
+ * Context: the core owns the flow — context, span, log lines, outcome, report, handlers — and
+ * these are the places an application changes it from outside, without touching a service. An
+ * interceptor runs inside the run: its veto is the use case's failure, observed and answered by
+ * the error handlers like any other. A listener that fails is ignored: hearing never changes
+ * the answer.
+ */
+export type PipelineLayer = "feature" | "application_service";
+/** What caused a run from outside: an event delivered with its envelope continues its chain. */
+export type Cause = {
+    /** The id of what caused it — a delivered event's. */
+    readonly id: string;
+    /** The chain it continues. */
+    readonly correlationId: string;
+};
+/**
+ * How a Command or an event is executed: what cancels it, and — for a delivered event — what
+ * caused it.
+ *
+ *     await salesBoundedContext.execute(new CommandQuote(3), { signal: screen.signal });
+ *
+ * Context: a screen that closes, a navigation that leaves, a user who gives up stop waiting; the
+ * run ends `aborted` (not reported), its Features inherit the signal, and the requests its
+ * transport sends are cancelled with it.
+ */
+export type ExecuteOptions = {
+    readonly signal?: AbortSignal;
+    readonly cause?: Cause;
+};
+/** The run an interceptor wraps: who runs, inside which execution, writing where. */
+export type InterceptedRun = {
+    readonly boundedContext: string;
+    /** `<bounded context>.<serviceName>`. */
+    readonly useCase: string;
+    readonly layer: PipelineLayer;
+    /** Its id, span, context and chain. */
+    readonly execution: Execution;
+    /** The run's logger, bound to it. */
+    readonly logger: LayerLogger;
+};
+/** The rest of the chain: the next interceptor, or the service. */
+export type CallNext<T extends Executable> = (executable: T) => Promise<unknown>;
+/**
+ * Runs around the service of a Command or an event. It passes on what it received — or another
+ * of the same class: the bus routes by class, so another class would be another use case — and
+ * returns what the next answered, or an answer of its own; it throws to veto.
+ */
+export type Interceptor<T extends Executable = Executable> = (executable: T, next: CallNext<T>, run: InterceptedRun) => unknown;
+/** A run began. */
+export type ExecutionStarted = {
+    readonly executable: Executable;
+    readonly execution: Execution;
+    readonly layer: PipelineLayer;
+};
+/** A run's service answered. */
+export type ExecutionCompleted = ExecutionStarted & {
+    readonly answer: unknown;
+    readonly durationMs: number;
+};
+/**
+ * A failure escaped a call — after every handler —, said once, where it first failed. No
+ * execution when it reached none: nothing is registered for the class.
+ */
+export type ExecutionFailed = {
+    readonly executable: Executable;
+    readonly execution: Execution | undefined;
+    readonly layer: PipelineLayer | undefined;
+    readonly error: unknown;
+    readonly outcome: Outcome;
+};
+/** Who hears a moment of the pipeline. */
+export type Listener<E> = (heard: E) => void;
+/** A component wired into a bounded context: its interceptors, listeners, services. */
+export type Extension<B> = (context: B) => void;

package/dist/core/domain/pipeline.js

@@ -0,0 +1 @@
+export {};