@sincpro/client-framework 0.6.0 → 1.1.0

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

@@ -0,0 +1,56 @@
+import type { ContextStore } from "../../context/domain/store.js";
+import { type ConsoleLoggerOptions } from "../../observability/adapters/console.js";
+import type { ErrorReporter } from "../../observability/domain/errors.js";
+import type { Logger } from "../../observability/domain/logging.js";
+import { type Outcome, type Tracer } from "../../observability/domain/tracing.js";
+/**
+ * Where logs go: the console by default, any `Logger` otherwise, or nowhere.
+ *
+ *     { mode: "development", level: "info", layers: { adapter: false } }   // the console, filtered
+ *     { mode: "production" }                                               // the console, silent
+ *     { engine: combineLoggers(consoleLogger({ mode }), lokiLogger) }       // the platform's sinks
+ *     { engine: false }                                                    // no logs
+ *
+ * Context: one shape for both doors — `configureProcess({ logger })`, which replaces everything,
+ * and `configureLogger(...)`, which replaces only logging (a debug switch on a phone). `mode`,
+ * `level` and `layers` configure the console engine; a supplied `engine` owns its own policy.
+ */
+export type LoggerConfiguration = Partial<ConsoleLoggerOptions> & {
+    engine?: Logger | false;
+};
+/**
+ * What every bounded context of this process runs with — set once, in `main`, the way
+ * sincpro_framework's process is: who traces, who reports, where logs go, where the context lives.
+ *
+ *     // entrypoints/main.tsx — the platform's pieces, built from the application's settings
+ *     configureProcess({
+ *       tracer: browserTracer({ endpoint: settings.otlp, service: "forge-web" }),
+ *       reporter: glitchtipReporter({ dsn: settings.glitchtip }),
+ *       logger: { mode: settings.production ? "production" : "development" },
+ *       context: memoryContexts(),
+ *     });
+ *
+ * Context: everything is optional, and nothing breaks without it. A process that never configures
+ * runs untraced and unreported, with memory context and development console logging — so a bounded
+ * context is usable the moment it is imported, and `main` adds what it watches with. The bounded
+ * contexts read the process on every call, never at import: `project` may be defined before `main`
+ * runs.
+ *
+ * It replaces everything at once: what is not given goes back to its default — a test calls it
+ * with its own tracer and starts from a clean context.
+ */
+export type ProcessOptions = {
+    /** The platform's (OpenTelemetry in a browser, a queue on a phone, memory in a test). */
+    tracer?: Tracer;
+    /** The platform's (GlitchTip, Sentry, memory in a test). Only what nobody expected reaches it. */
+    reporter?: ErrorReporter;
+    /** Where logs go (`LoggerConfiguration`); the console in development mode by default. */
+    logger?: LoggerConfiguration;
+    /** Where the context lives (`memoryContexts()` by default). */
+    context?: ContextStore;
+    /** How an error ended a use case (`outcomeOf` by default). Only `failed` is reported. */
+    outcomeOf?: (error: unknown) => Outcome;
+};
+export declare function configureProcess(options?: ProcessOptions): void;
+/** Replace logging only; tracing, reporting and the context stay as they are. */
+export declare function configureLogger(options?: LoggerConfiguration): void;

package/dist/core/infrastructure/process.js

@@ -0,0 +1,35 @@
+import { memoryContexts } from "../../context/adapters/memory.js";
+import { replaceProcessStore } from "../../context/infrastructure/process.js";
+import { consoleLogger, } from "../../observability/adapters/console.js";
+import { NO_TRACER, } from "../../observability/domain/tracing.js";
+import { replaceObservability } from "../../observability/infrastructure/registry.js";
+import { outcomeOf } from "../../observability/services/outcome.js";
+function loggingEngine(options) {
+    if (options.engine === false)
+        return undefined;
+    if (options.engine !== undefined) {
+        if (!options.engine || typeof options.engine.log !== "function") {
+            throw new TypeError("Logger engine must implement log(record)");
+        }
+        return options.engine;
+    }
+    return consoleLogger({
+        mode: options.mode ?? "development",
+        ...(options.level ? { level: options.level } : {}),
+        ...(options.layers ? { layers: options.layers } : {}),
+    });
+}
+export function configureProcess(options = {}) {
+    const logger = loggingEngine(options.logger ?? {});
+    replaceObservability({
+        tracer: options.tracer ?? NO_TRACER,
+        reporter: options.reporter,
+        logger,
+        outcomeOf: options.outcomeOf ?? outcomeOf,
+    });
+    replaceProcessStore(options.context ?? memoryContexts());
+}
+/** Replace logging only; tracing, reporting and the context stay as they are. */
+export function configureLogger(options = {}) {
+    replaceObservability({ logger: loggingEngine(options) });
+}

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

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

package/dist/core/services/binding.js

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

package/dist/core/services/error-handlers.d.ts

@@ -0,0 +1,11 @@
+import type { ErrorHandler } from "../domain/errors.js";
+/**
+ * The answer of a chain of error handlers to `error`, or what its last handler threw.
+ *
+ *     await handled([toEmpty, logAndRethrow], new IssueNotFound())   ->  toEmpty's answer
+ *
+ * 1. Each handler, first-registered-first, receives what the one before it threw.
+ * Final: the first answer; when every handler threw, the last thrown — the original error when
+ *    there is no handler at all.
+ */
+export declare function handled(handlers: readonly ErrorHandler[], error: unknown): Promise<unknown>;

package/dist/core/services/error-handlers.js

@@ -0,0 +1,21 @@
+/**
+ * The answer of a chain of error handlers to `error`, or what its last handler threw.
+ *
+ *     await handled([toEmpty, logAndRethrow], new IssueNotFound())   ->  toEmpty's answer
+ *
+ * 1. Each handler, first-registered-first, receives what the one before it threw.
+ * Final: the first answer; when every handler threw, the last thrown — the original error when
+ *    there is no handler at all.
+ */
+export async function handled(handlers, error) {
+    let current = error;
+    for (const handler of handlers) {
+        try {
+            return await handler(current);
+        }
+        catch (thrown) {
+            current = thrown;
+        }
+    }
+    throw current;
+}

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

@@ -0,0 +1,66 @@
+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 = 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. */
+    readonly handlers: readonly ErrorHandler[];
+}
+/**
+ * One pipeline for every registered Feature and ApplicationService.
+ *
+ * 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.
+ *    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,
+ *    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 — announced —, or its handlers'.
+ */
+export declare function executeService(target: RuntimeService, command: Executable, options: ExecutionOptions): Promise<unknown>;
+export {};

package/dist/core/services/execution.js

@@ -0,0 +1,216 @@
+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 {
+        return work();
+    }
+    catch {
+        return fallback;
+    }
+}
+function serviceView(target, options, execution) {
+    const dependencies = new Map();
+    const logger = executionLogger(options.layer, execution);
+    let features;
+    return new Proxy(target, {
+        get(held, property, receiver) {
+            if (property === "context")
+                return execution.context;
+            if (property === "span")
+                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));
+            }
+            if (typeof property === "string" && options.dependencies.has(property)) {
+                if (!dependencies.has(property)) {
+                    dependencies.set(property, bindDependency(options.dependencies.get(property), execution));
+                }
+                return dependencies.get(property);
+            }
+            if (Reflect.has(held, property))
+                return Reflect.get(held, property, receiver);
+            if (typeof property === "string") {
+                throw new Error(`${options.boundedContext}: dependency or member is not registered: ${property}`);
+            }
+            return undefined;
+        },
+        set(held, property, value) {
+            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)}`);
+            }
+            return Reflect.set(held, property, value);
+        },
+    });
+}
+/**
+ * One pipeline for every registered Feature and ApplicationService.
+ *
+ * 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.
+ *    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,
+ *    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 — announced —, or its handlers'.
+ */
+export async function executeService(target, command, options) {
+    const ports = observabilityNow();
+    const startedAt = Date.now();
+    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 } : {}),
+        attributes,
+    }), NO_TRACER.start(useCase, {}));
+    const execution = {
+        id,
+        useCase,
+        boundedContext: options.boundedContext,
+        parent: options.parent,
+        correlationId,
+        causationId,
+        signal: options.signal ?? options.parent?.signal,
+        span,
+        context,
+    };
+    const reported = options.parent
+        ? (REPORTED_BY_EXECUTION.get(options.parent) ?? new Set())
+        : 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")
+            : "ok";
+        observe(() => span.end(outcome, error?.value), undefined);
+        logExecution(options.layer, execution, {
+            outcome,
+            durationMs: Math.max(0, Date.now() - startedAt),
+        });
+        if (outcome === "failed" && error && ports.reporter && !reported.has(error.value)) {
+            reported.add(error.value);
+            // Mark for reportError outside the call; a different root may report the same Error.
+            firstReport(error.value);
+            observe(() => ports.reporter?.report(error.value, {
+                useCase,
+                traceId: span.traceId,
+                executionId: id,
+                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 {
+        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 });
+        if (options.handlers.length === 0)
+            throw error;
+        const recovered = await handled(options.handlers, error);
+        logHandled(options.layer, { execution });
+        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;