@sincpro/client-framework 1.0.0 → 1.1.0

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

@@ -1,18 +1,45 @@
 import type { Execution } from "../../context/domain/execution.js";
 import type { ContextValues } from "../../context/domain/store.js";
+import type { Executable } from "../domain/dto.js";
 import type { ErrorHandler } from "../domain/errors.js";
+import type { Cause, ExecutionCompleted, ExecutionStarted, Interceptor, PipelineLayer } from "../domain/pipeline.js";
+import { type Attributes, type Outcome } from "../../observability/domain/tracing.js";
 export interface RuntimeService {
     execute(command: object): unknown;
 }
-type Layer = "feature" | "application_service";
+type Layer = PipelineLayer;
+/** Where a failure first happened: the run, its executable, its layer and how it ended. */
+export type FailedAt = {
+    readonly execution: Execution;
+    readonly executable: Executable;
+    readonly layer: Layer;
+    readonly outcome: Outcome;
+};
+/** Where `error` first failed, when it is an object a run threw; `undefined` otherwise. */
+export declare function failedAt(error: unknown): FailedAt | undefined;
+/** Who hears the moments of a run: read when they happen, so a listener added later hears. */
+export interface Announcer {
+    started(heard: ExecutionStarted): void;
+    completed(heard: ExecutionCompleted): void;
+}
 export interface ExecutionOptions {
     readonly boundedContext: string;
     readonly name: string;
     readonly layer: Layer;
+    /** What else its span says: the event it executes, the service it replaced. */
+    readonly attributes?: Attributes;
     readonly dependencies: ReadonlyMap<string, unknown>;
     readonly context: () => ContextValues;
     readonly parent?: Execution;
+    /** What caused a root run from outside: a delivered event's envelope continues its chain. */
+    readonly cause?: Cause;
+    /** What cancels a root run; a child inherits its parent's. */
+    readonly signal?: AbortSignal;
     readonly featureBus: (execution: Execution) => object;
+    /** What runs around the service, outermost first. */
+    readonly interceptors: readonly Interceptor[];
+    /** Who hears it start and answer. */
+    readonly announce: Announcer;
     /** The bounded context's expected errors: they end `refused`, never reported. */
     readonly expected: (error: unknown) => boolean;
     /** The bounded context's handlers for this layer: what answers a failure instead of raising it. */
@@ -23,13 +50,17 @@ export interface ExecutionOptions {
  *
  * 1. A span `<bounded context>/<serviceName>`, a child of the parent run when there is one, and
  *    the execution every dependency, `this.logger` and child Feature are bound to.
- * 2. The service runs, seeing that execution through its own view of the instance.
+ *    Its chain: the parent's correlation (or the cause's, or its own id for a root), caused by
+ *    the parent run or the delivered event.
+ * 2. Its start is announced; the interceptors run around the service, which sees the
+ *    execution through its own view of the instance.
  * 3. A failure is observed where it happened: its outcome (expected by the bounded context →
- *    `refused`, else the process's `outcomeOf`), the span closed with it, its log line and —
- *    when `failed`, and only once per error along the run — its report.
+ *    `refused`, else the process's `outcomeOf`), the span closed with it, its log line,
+ *    where it first failed and — when `failed`, and only once per error along the run — its
+ *    report.
  * 4. Then the layer's error handlers answer it, in order; with none, or when the last throws,
  *    the error reaches the caller.
- * Final: the service's answer, or its handlers'.
+ * Final: the service's answer — announced —, or its handlers'.
  */
-export declare function executeService(target: RuntimeService, command: object, options: ExecutionOptions): Promise<unknown>;
+export declare function executeService(target: RuntimeService, command: Executable, options: ExecutionOptions): Promise<unknown>;
 export {};

package/dist/core/services/execution.js

@@ -1,11 +1,44 @@
 import { newEntityId } from "../../common/ids.js";
 import { bindDependency } from "./binding.js";
 import { handled } from "./error-handlers.js";
+import { runAround } from "./interceptors.js";
 import { NO_TRACER, } from "../../observability/domain/tracing.js";
 import { observabilityNow } from "../../observability/infrastructure/registry.js";
 import { executionLogger, logExecution, logHandled, } from "../../observability/services/logging.js";
 import { firstReport } from "../../observability/services/reporting.js";
+const FAILED_AT = new WeakMap();
+/** Where `error` first failed, when it is an object a run threw; `undefined` otherwise. */
+export function failedAt(error) {
+    return error !== null && typeof error === "object" ? FAILED_AT.get(error) : undefined;
+}
 const REPORTED_BY_EXECUTION = new WeakMap();
+/** What a cancelled run fails with: an `AbortError`, whatever the signal was aborted with. */
+function abortedBy(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error && reason.name === "AbortError")
+        return reason;
+    return Object.assign(new Error("The run was cancelled"), {
+        name: "AbortError",
+        cause: reason,
+    });
+}
+/**
+ * What `running` answers — or the cancellation, the moment `signal` aborts: the caller stops
+ * waiting even when the service does not look at its signal.
+ */
+function untilAborted(running, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(abortedBy(signal));
+        signal.addEventListener("abort", abort, { once: true });
+        running.then((answer) => {
+            signal.removeEventListener("abort", abort);
+            resolve(answer);
+        }, (error) => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+    });
+}
 /** Observability adapters are best-effort; their failures must not replace a business result. */
 function observe(work, fallback) {
     try {
@@ -27,6 +60,10 @@ function serviceView(target, options, execution) {
                 return execution.span;
             if (property === "logger")
                 return logger;
+            if (property === "signal")
+                return execution.signal;
+            if (property === "execution")
+                return execution;
             if (property === "featureBus" && options.layer === "application_service") {
                 return (features ??= options.featureBus(execution));
             }
@@ -47,6 +84,8 @@ function serviceView(target, options, execution) {
             if (property === "context" ||
                 property === "span" ||
                 property === "logger" ||
+                property === "signal" ||
+                property === "execution" ||
                 property === "featureBus" ||
                 (typeof property === "string" && options.dependencies.has(property))) {
                 throw new Error(`Execution dependencies and context are read-only: ${String(property)}`);
@@ -60,13 +99,17 @@ function serviceView(target, options, execution) {
  *
  * 1. A span `<bounded context>/<serviceName>`, a child of the parent run when there is one, and
  *    the execution every dependency, `this.logger` and child Feature are bound to.
- * 2. The service runs, seeing that execution through its own view of the instance.
+ *    Its chain: the parent's correlation (or the cause's, or its own id for a root), caused by
+ *    the parent run or the delivered event.
+ * 2. Its start is announced; the interceptors run around the service, which sees the
+ *    execution through its own view of the instance.
  * 3. A failure is observed where it happened: its outcome (expected by the bounded context →
- *    `refused`, else the process's `outcomeOf`), the span closed with it, its log line and —
- *    when `failed`, and only once per error along the run — its report.
+ *    `refused`, else the process's `outcomeOf`), the span closed with it, its log line,
+ *    where it first failed and — when `failed`, and only once per error along the run — its
+ *    report.
  * 4. Then the layer's error handlers answer it, in order; with none, or when the last throws,
  *    the error reaches the caller.
- * Final: the service's answer, or its handlers'.
+ * Final: the service's answer — announced —, or its handlers'.
  */
 export async function executeService(target, command, options) {
     const ports = observabilityNow();
@@ -74,11 +117,16 @@ export async function executeService(target, command, options) {
     const useCase = `${options.boundedContext}.${options.name}`;
     const context = options.parent?.context ?? options.context();
     const id = newEntityId();
+    const correlationId = options.parent?.correlationId ?? options.cause?.correlationId ?? id;
+    const causationId = options.parent?.id ?? options.cause?.id;
     const attributes = {
         "sincpro.use_case": useCase,
         "sincpro.layer": options.layer,
         "sincpro.context": options.boundedContext,
         "sincpro.execution_id": id,
+        "sincpro.correlation_id": correlationId,
+        ...(causationId ? { "sincpro.causation_id": causationId } : {}),
+        ...options.attributes,
     };
     const span = observe(() => ports.tracer.start(`${options.boundedContext}/${options.name}`, {
         ...(options.parent ? { parent: options.parent.span } : {}),
@@ -89,6 +137,9 @@ export async function executeService(target, command, options) {
         useCase,
         boundedContext: options.boundedContext,
         parent: options.parent,
+        correlationId,
+        causationId,
+        signal: options.signal ?? options.parent?.signal,
         span,
         context,
     };
@@ -97,6 +148,7 @@ export async function executeService(target, command, options) {
         : new Set();
     REPORTED_BY_EXECUTION.set(execution, reported);
     logExecution(options.layer, execution);
+    observe(() => options.announce.started({ executable: command, execution, layer: options.layer }), undefined);
     const finish = (error) => {
         const outcome = error
             ? observe(() => (options.expected(error.value) ? "refused" : ports.outcomeOf(error.value)), "failed")
@@ -117,12 +169,32 @@ export async function executeService(target, command, options) {
                 context,
             }), undefined);
         }
+        if (error?.value !== null &&
+            typeof error?.value === "object" &&
+            !FAILED_AT.has(error.value))
+            FAILED_AT.set(error.value, {
+                execution,
+                executable: command,
+                layer: options.layer,
+                outcome,
+            });
+        return outcome;
     };
+    const view = serviceView(target, options, execution);
+    const service = (current) => Promise.resolve(Reflect.apply(target.execute, view, [current]));
     let answer;
     try {
-        answer = await Reflect.apply(target.execute, serviceView(target, options, execution), [
-            command,
-        ]);
+        const signal = execution.signal;
+        if (signal?.aborted)
+            throw abortedBy(signal);
+        const running = runAround(options.interceptors, service, command, {
+            boundedContext: options.boundedContext,
+            useCase,
+            layer: options.layer,
+            execution,
+            logger: executionLogger(options.layer, execution),
+        });
+        answer = signal === undefined ? await running : await untilAborted(running, signal);
     }
     catch (error) {
         finish({ value: error });
@@ -133,5 +205,12 @@ export async function executeService(target, command, options) {
         return recovered;
     }
     finish();
+    observe(() => options.announce.completed({
+        executable: command,
+        execution,
+        layer: options.layer,
+        answer,
+        durationMs: Math.max(0, Date.now() - startedAt),
+    }), undefined);
     return answer;
 }

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

@@ -0,0 +1,15 @@
+import type { Executable } from "../domain/dto.js";
+import type { InterceptedRun, Interceptor } from "../domain/pipeline.js";
+/**
+ * `handler` run on `executable`, wrapped by `interceptors` — the first the outermost.
+ *
+ *     runAround([], service, command, run)              ->  the service's answer
+ *     runAround([audit, credit], service, command, run) ->  audit(credit(service))
+ *     runAround([<passes another class on>], …)         ->  TypeError, naming both classes
+ *
+ * 1. Each interceptor gets a `next` bound to the position after it.
+ * 2. What reaches `next` must be of the class the call started with: the bus routes by class,
+ *    so another class would be another use case under this one's name.
+ * Final: the outermost interceptor's answer — the service's, when none answers by itself.
+ */
+export declare function runAround(interceptors: readonly Interceptor[], handler: (executable: Executable) => Promise<unknown>, executable: Executable, run: InterceptedRun): Promise<unknown>;

package/dist/core/services/interceptors.js

@@ -0,0 +1,25 @@
+/**
+ * `handler` run on `executable`, wrapped by `interceptors` — the first the outermost.
+ *
+ *     runAround([], service, command, run)              ->  the service's answer
+ *     runAround([audit, credit], service, command, run) ->  audit(credit(service))
+ *     runAround([<passes another class on>], …)         ->  TypeError, naming both classes
+ *
+ * 1. Each interceptor gets a `next` bound to the position after it.
+ * 2. What reaches `next` must be of the class the call started with: the bus routes by class,
+ *    so another class would be another use case under this one's name.
+ * Final: the outermost interceptor's answer — the service's, when none answers by itself.
+ */
+export function runAround(interceptors, handler, executable, run) {
+    const started = Object.getPrototypeOf(executable)?.constructor;
+    const at = async (position, current) => {
+        if (Object.getPrototypeOf(current)?.constructor !== started) {
+            throw new TypeError(`An interceptor of ${run.useCase} passed on a ${current?.constructor?.name} where it received a ${started?.name}`);
+        }
+        const interceptor = interceptors[position];
+        if (interceptor === undefined)
+            return handler(current);
+        return interceptor(current, (next) => at(position + 1, next), run);
+    };
+    return at(0, executable);
+}

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

@@ -0,0 +1,17 @@
+import type { Executable } from "../domain/dto.js";
+import type { Listener } from "../domain/pipeline.js";
+/** A class a service, an interceptor or a listener is for. */
+export type ExecutableClass = abstract new (...args: never[]) => Executable;
+/** An interceptor or a listener, and the classes it is for — every class when it names none. */
+export type Hearing<F> = {
+    readonly what: F;
+    readonly dtos: readonly ExecutableClass[];
+};
+/** Whether something registered for `dtos` concerns `executable`: by its exact class. */
+export declare function concerns(dtos: readonly ExecutableClass[], executable: Executable): boolean;
+/** Each listener that hears it, in turn; one that fails is ignored. */
+export declare function announceTo<E extends {
+    executable: Executable;
+}>(hearing: ReadonlySet<Hearing<Listener<E>>>, heard: E): void;
+/** `listener` added to `hearing` for `dtos`; answers how to stop. */
+export declare function listenIn<E>(hearing: Set<Hearing<Listener<E>>>, listener: Listener<E>, dtos: readonly ExecutableClass[]): () => void;

package/dist/core/services/listening.js

@@ -0,0 +1,25 @@
+/** Whether something registered for `dtos` concerns `executable`: by its exact class. */
+export function concerns(dtos, executable) {
+    return dtos.length === 0 || dtos.includes(Object.getPrototypeOf(executable)?.constructor);
+}
+/** Each listener that hears it, in turn; one that fails is ignored. */
+export function announceTo(hearing, heard) {
+    for (const one of [...hearing]) {
+        if (!concerns(one.dtos, heard.executable))
+            continue;
+        try {
+            one.what(heard);
+        }
+        catch {
+            // Hearing never changes the answer, as tracing, reporting and logging never do.
+        }
+    }
+}
+/** `listener` added to `hearing` for `dtos`; answers how to stop. */
+export function listenIn(hearing, listener, dtos) {
+    if (typeof listener !== "function")
+        throw new TypeError("A listener is a function");
+    const one = { what: listener, dtos };
+    hearing.add(one);
+    return () => void hearing.delete(one);
+}

package/dist/event_driven/adapters/memory-event-store.d.ts

@@ -0,0 +1,10 @@
+import type { EventStore, StoredEvent } from "../domain/store.js";
+/** A memory store, and what it holds — in the order added — for whoever inspects it. */
+export type MemoryEventStore = EventStore & {
+    readonly events: readonly StoredEvent[];
+};
+/**
+ * The events of a stored queue in this process's memory: what a browser tab or a test keeps.
+ * Gone with the process — a phone's store is a table.
+ */
+export declare function memoryEventStore(): MemoryEventStore;

package/dist/event_driven/adapters/memory-event-store.js

@@ -0,0 +1,23 @@
+/**
+ * The events of a stored queue in this process's memory: what a browser tab or a test keeps.
+ * Gone with the process — a phone's store is a table.
+ */
+export function memoryEventStore() {
+    const held = [];
+    return {
+        get events() {
+            return [...held];
+        },
+        add(stored) {
+            held.push(stored);
+        },
+        next(skip) {
+            return held.find((one) => one.state === "pending" && !skip.has(one.envelope.id));
+        },
+        save(stored) {
+            const at = held.findIndex((one) => one.envelope.id === stored.envelope.id);
+            if (at >= 0)
+                held[at] = stored;
+        },
+    };
+}

package/dist/event_driven/adapters/stored-queue.d.ts

@@ -0,0 +1,67 @@
+import { type JsonValue } from "../../common/serialization.js";
+import type { DomainEvent, EventClass } from "../../core/domain/dto.js";
+import type { EventQueue, Subscribes } from "../domain/queue.js";
+import type { EventStore, StoredEvent } from "../domain/store.js";
+export type StoredQueueOptions = {
+    /** Where the events wait: memory, a phone's SQLite, a browser's IndexedDB. */
+    readonly store: EventStore;
+    /** Who executes them: every bounded context that hears each one. */
+    readonly subscriber: Subscribes;
+    /**
+     * How a stored payload becomes its class again. By default, `static fromJSON` when the class
+     * has one, else its values set on an instance of it — as JSON gave them: an event that carries
+     * a `Money`, a `Decimal` or a date declares `fromJSON` to read them back as such.
+     */
+    readonly rebuild?: (type: EventClass<DomainEvent>, payload: JsonValue) => DomainEvent;
+    /**
+     * Whether an event may be delivered now — a phone asks for a connection, or a session. One
+     * that is not waits while the rest go on; `drain()` again when what it waits for comes back.
+     */
+    readonly ready?: (stored: StoredEvent) => boolean | Promise<boolean>;
+    /** The first wait after a failed attempt, in ms (1 s); doubled each time, never past `longestWait`. */
+    readonly wait?: number;
+    /** The longest wait between attempts, in ms (one minute). */
+    readonly longestWait?: number;
+    /**
+     * How many attempts an event gets before it is set aside although a retry might still fix it
+     * (10): a bug of this process (`internal`) or a dependency gone for good must not hold the line
+     * forever. `Infinity` keeps trying.
+     */
+    readonly maxAttempts?: number;
+    /** Told each time an event settles — delivered, set aside, or waiting to retry —: a screen's activity. */
+    readonly onSettled?: (stored: StoredEvent) => void;
+};
+/** A stored queue, and the door to deliver what waits — on a timer, back online, in the foreground. */
+export type StoredQueue = EventQueue & {
+    drain(): Promise<void>;
+};
+/**
+ * The queue that stores an event before delivering it, and delivers it until every bounded
+ * context that hears it has it — the backend's store-and-forward (`Forwarding`), over a store
+ * each platform plugs.
+ *
+ *     const queue = storedQueue({ store: sqliteEventStore(db), subscriber, ready: online });
+ *     shop.addDependency("publisher", new Publisher(queue));
+ *     connectivity.onBack(() => queue.drain());
+ *
+ * Context: what a phone did by hand in its event bus, the same on every platform. `publish`
+ * returns once the event is stored — nobody waits for the delivery. Then, one at a time and in
+ * the order stored:
+ *
+ * 1. An event not ready (`ready`) waits while the rest go on.
+ * 2. Nobody hears its name: delivered — a fact recorded, nobody's to act on.
+ * 3. Rebuilt as its class; one that cannot be is set aside.
+ * 4. Executed in every bounded context that hears it and does not have it yet (`reached`).
+ * 5. A failure every attempt would repeat (`PERMANENT_KINDS`: a refusal, invalid, not found) sets
+ *    that context aside; any other is tried again after the backoff — or what the failure asks
+ *    for (`retryAfter`, an open circuit's time left) —, and what comes after waits, so the
+ *    order holds; after `maxAttempts`, it is set aside too.
+ * Final: delivered when every context has it, set aside — the dead-letter queue — when one
+ *    refused it for good or ran out of attempts; `onSettled` hears either.
+ *
+ * Delivery is at least once: a process that stops after a context executed an event and before
+ * the store saved it executes it there again on the next drain. A subscriber that must not act
+ * twice keys what it does by the envelope's id — `this.execution.causationId` in its run. And one
+ * process drains a store: two tabs over one IndexedDB claim it first (the Web Locks API).
+ */
+export declare function storedQueue(options: StoredQueueOptions): StoredQueue;

package/dist/event_driven/adapters/stored-queue.js

@@ -0,0 +1,192 @@
+import { failureOf } from "../../common/failures.js";
+import { readValues, rebuilt, valuesOf, } from "../../common/serialization.js";
+import { loggerAdapter } from "../../observability/services/logging.js";
+function rebuildEvent(type, payload) {
+    const values = readValues(payload);
+    if (typeof type.fromJSON === "function")
+        return rebuilt(values, type);
+    return Object.assign(Object.create(type.prototype), values);
+}
+function described(boundedContext, error) {
+    const failure = failureOf(error);
+    return {
+        boundedContext,
+        kind: failure.kind,
+        reason: failure.reason,
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+/**
+ * The queue that stores an event before delivering it, and delivers it until every bounded
+ * context that hears it has it — the backend's store-and-forward (`Forwarding`), over a store
+ * each platform plugs.
+ *
+ *     const queue = storedQueue({ store: sqliteEventStore(db), subscriber, ready: online });
+ *     shop.addDependency("publisher", new Publisher(queue));
+ *     connectivity.onBack(() => queue.drain());
+ *
+ * Context: what a phone did by hand in its event bus, the same on every platform. `publish`
+ * returns once the event is stored — nobody waits for the delivery. Then, one at a time and in
+ * the order stored:
+ *
+ * 1. An event not ready (`ready`) waits while the rest go on.
+ * 2. Nobody hears its name: delivered — a fact recorded, nobody's to act on.
+ * 3. Rebuilt as its class; one that cannot be is set aside.
+ * 4. Executed in every bounded context that hears it and does not have it yet (`reached`).
+ * 5. A failure every attempt would repeat (`PERMANENT_KINDS`: a refusal, invalid, not found) sets
+ *    that context aside; any other is tried again after the backoff — or what the failure asks
+ *    for (`retryAfter`, an open circuit's time left) —, and what comes after waits, so the
+ *    order holds; after `maxAttempts`, it is set aside too.
+ * Final: delivered when every context has it, set aside — the dead-letter queue — when one
+ *    refused it for good or ran out of attempts; `onSettled` hears either.
+ *
+ * Delivery is at least once: a process that stops after a context executed an event and before
+ * the store saved it executes it there again on the next drain. A subscriber that must not act
+ * twice keys what it does by the envelope's id — `this.execution.causationId` in its run. And one
+ * process drains a store: two tabs over one IndexedDB claim it first (the Web Locks API).
+ */
+export function storedQueue(options) {
+    const { store, subscriber } = options;
+    const firstWait = options.wait ?? 1000;
+    const longestWait = options.longestWait ?? 60_000;
+    const maxAttempts = options.maxAttempts ?? 10;
+    if (!(maxAttempts >= 1))
+        throw new TypeError("A stored queue needs one attempt at least");
+    const rebuild = options.rebuild ?? rebuildEvent;
+    let draining;
+    let again = false;
+    let timer;
+    const settle = async (stored) => {
+        await store.save(stored);
+        try {
+            options.onSettled?.(stored);
+        }
+        catch {
+            // Telling a screen never changes a delivery.
+        }
+    };
+    const wakeAt = (at) => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            void queue.drain();
+        }, Math.max(0, at - Date.now()));
+        // A timer of its own must not keep a process alive that has nothing else to do.
+        timer.unref?.();
+    };
+    /** One pass over what waits; it stops at an event that must wait its turn. */
+    const pass = async () => {
+        const skip = new Set();
+        for (;;) {
+            const head = await store.next(skip);
+            if (head === undefined)
+                return;
+            const id = head.envelope.id;
+            if (head.retryAt !== null && Date.parse(head.retryAt) > Date.now()) {
+                wakeAt(Date.parse(head.retryAt));
+                return;
+            }
+            if (options.ready && !(await options.ready(head))) {
+                skip.add(id);
+                continue;
+            }
+            const attempts = head.attempts + 1;
+            const type = subscriber.eventTypeOf(head.envelope.name);
+            if (type === undefined) {
+                await settle({ ...head, state: "delivered", attempts, retryAt: null, failures: [] });
+                continue;
+            }
+            let event;
+            try {
+                event = rebuild(type, head.payload);
+            }
+            catch (error) {
+                await settle({
+                    ...head,
+                    state: "set_aside",
+                    attempts,
+                    retryAt: null,
+                    failures: [described("", error)],
+                });
+                continue;
+            }
+            const handled = await subscriber.handle(event, head.envelope, head.reached);
+            const reached = [...head.reached];
+            const failures = [];
+            let retryAfter = 0;
+            let repeat = false;
+            for (const one of handled) {
+                if (!("error" in one)) {
+                    reached.push(one.boundedContext);
+                    continue;
+                }
+                failures.push(described(one.boundedContext, one.error));
+                const failure = failureOf(one.error);
+                if (failure.permanent)
+                    reached.push(one.boundedContext);
+                else {
+                    repeat = true;
+                    retryAfter = Math.max(retryAfter, (failure.retryAfter ?? 0) * 1000);
+                }
+            }
+            if (repeat && attempts < maxAttempts) {
+                const backoff = Math.min(longestWait, firstWait * 2 ** (attempts - 1));
+                const at = Date.now() + Math.max(backoff, retryAfter);
+                await settle({
+                    ...head,
+                    state: "pending",
+                    attempts,
+                    retryAt: new Date(at).toISOString(),
+                    reached,
+                    failures,
+                });
+                wakeAt(at);
+                return;
+            }
+            await settle({
+                ...head,
+                state: failures.length === 0 ? "delivered" : "set_aside",
+                attempts,
+                retryAt: null,
+                reached,
+                failures,
+            });
+        }
+    };
+    const queue = {
+        async put(event, envelope) {
+            await store.add({
+                envelope,
+                payload: valuesOf(event),
+                state: "pending",
+                attempts: 0,
+                retryAt: null,
+                reached: [],
+                failures: [],
+            });
+            queue.drain().catch((error) => loggerAdapter.error("The stored queue could not deliver", {
+                reason: failureOf(error).reason,
+            }));
+        },
+        drain() {
+            if (draining !== undefined) {
+                again = true;
+                return draining;
+            }
+            draining = (async () => {
+                try {
+                    do {
+                        again = false;
+                        await pass();
+                    } while (again);
+                }
+                finally {
+                    draining = undefined;
+                }
+            })();
+            return draining;
+        },
+    };
+    return queue;
+}

package/dist/event_driven/adapters/sync-queue.d.ts

@@ -0,0 +1,11 @@
+import type { EventQueue, Subscribes } from "../domain/queue.js";
+/**
+ * The queue that delivers in the call, in memory — the backend's `SyncQueue`: `publish` returns
+ * once every bounded context that hears the event executed it. What a web application starts
+ * with, and what a test proves a flow with.
+ *
+ * Context: nothing is stored, so nothing outlives the process — a phone's queue is durable and
+ * the platform's. Every subscriber runs; then the first failure, if any, reaches the publisher,
+ * as an in-process call would.
+ */
+export declare function syncQueue(subscriber: Subscribes): EventQueue;

package/dist/event_driven/adapters/sync-queue.js

@@ -0,0 +1,19 @@
+/**
+ * The queue that delivers in the call, in memory — the backend's `SyncQueue`: `publish` returns
+ * once every bounded context that hears the event executed it. What a web application starts
+ * with, and what a test proves a flow with.
+ *
+ * Context: nothing is stored, so nothing outlives the process — a phone's queue is durable and
+ * the platform's. Every subscriber runs; then the first failure, if any, reaches the publisher,
+ * as an in-process call would.
+ */
+export function syncQueue(subscriber) {
+    return {
+        async put(event, envelope) {
+            const handled = await subscriber.handle(event, envelope);
+            const failed = handled.find((one) => "error" in one);
+            if (failed && "error" in failed)
+                throw failed.error;
+        },
+    };
+}