@nwire/runtime 0.11.0

package/dist/runtime.js

@@ -0,0 +1,588 @@
+/**
+ * Runtime — Container, dispatch hook, FrameworkHooks registry, telemetry
+ * stream, plugin lifecycle. The dispatch hook composes user middleware
+ * via `runtime.use(...)` around an inner pinned step that calls the
+ * registered handler. Plugins materialise additional FrameworkHooks
+ * slots via `runtime.defineHook(name)` and TS module augmentation.
+ */
+import { createContainer } from "@nwire/container/awilix";
+import { hook } from "@nwire/hooks";
+import { NoopLogger } from "@nwire/logger";
+import { seedEnvelope, deriveEnvelope } from "@nwire/envelope";
+import { createFrameworkHooks, isBuiltInHook } from "./framework-hooks.js";
+export function serializeError(err) {
+    if (err instanceof Error) {
+        const out = {
+            name: err.name,
+            message: err.message,
+            stack: err.stack,
+        };
+        for (const k of Object.keys(err)) {
+            if (k === "name" || k === "message" || k === "stack")
+                continue;
+            out[k] = err[k];
+        }
+        return out;
+    }
+    return { name: "NonError", message: String(err) };
+}
+export class Runtime {
+    container;
+    _logger;
+    appName;
+    /**
+     * Public accessor — external dispatchers compose runtimes and need the
+     * logger; test-kit harness extensions also swap it in for tap capture.
+     */
+    get logger() {
+        return this._logger;
+    }
+    set logger(value) {
+        this._logger = value;
+    }
+    /** Public accessor — external dispatchers register middleware via this hook. */
+    get dispatchHook$() {
+        return this.dispatchHook;
+    }
+    /**
+     * Dispatch substrate. Subclasses register their pinned `handler` step at
+     * priority `-Infinity` and call `dispatchHook.run(ctx)` from their own
+     * `dispatch` method. The tap forwards every chain step to the canonical
+     * telemetry stream.
+     */
+    dispatchHook;
+    userMiddlewareCount = 0;
+    /**
+     * Per-runtime framework-hook registry. Built-in slots (App*, Plugin*,
+     * Wire*) are pre-instantiated; plugins augment the `FrameworkHooks`
+     * interface and materialise their slots via `defineHook(name)`.
+     */
+    hooks;
+    telemetryListeners = [];
+    /**
+     * Handler registry — keyed by `handler.name`. Populated via
+     * `registerHandler(handler)` so consumers can dispatch by name:
+     * `runtime.execute("orders.place", input)`. Adapters (HTTP, queue, MCP)
+     * also iterate this for their own wire / tool tables.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handlers = new Map();
+    /**
+     * Per-event subscriber registry — keyed by `event.name`. Subscribers
+     * attach via `runtime.subscribe(event, fn)` and fire on `runtime.emit(
+     * event, payload)`. Foundation calls this out as the broadcast verb
+     * distinct from telemetry-push (`runtime.pushTelemetry(record)`).
+     */
+    eventListeners = new Map();
+    /**
+     * Installed capabilities — added via `runtime.add(cap)`. Each entry's
+     * `provideCtx` is invoked once per dispatch and its output spread onto
+     * the handler ctx; `provideRuntime` (if any) was already merged onto
+     * the runtime instance at install time.
+     *
+     * Stored as an array (not a map) — the contract is install-order; a
+     * later capability can shadow an earlier one's ctx key if needed.
+     * Duplicate `name` install throws to surface accidental double-installs.
+     */
+    capabilities = [];
+    capabilityNames = new Set();
+    /**
+     * Outbound sink chain — populated by `runtime.sink(stage)`. Stored as one
+     * array; `sinkDrain` runs them in position order (early → middle → terminal),
+     * and within a position in install order. Terminal stages with a `kind` are
+     * exclusivity-checked at install time so two NATS terminals can't both win.
+     */
+    sinkStages = [];
+    terminalKinds = new Set();
+    constructor(options = {}) {
+        this.container = options.container ?? createContainer();
+        this._logger = options.logger ?? new NoopLogger();
+        this.appName = options.appName ?? "app";
+        this.hooks = createFrameworkHooks();
+        for (const h of Object.values(this.hooks)) {
+            this.observe(h);
+        }
+        this.dispatchHook = hook("runtime.dispatch");
+        this.observe(this.dispatchHook);
+    }
+    /**
+     * Materialise a slot on `runtime.hooks` for a plugin-defined framework
+     * hook. Idempotent — calling twice with the same name returns the same
+     * Hook. The slot is automatically observed for telemetry.
+     *
+     * Pair this with TS module augmentation:
+     *
+     *   declare module "@nwire/app" {
+     *     interface FrameworkHooks {
+     *       MyEvent: Hook<{ tenant: string }>;
+     *     }
+     *   }
+     *
+     *   const h = runtime.defineHook<{ tenant: string }>("MyEvent");
+     */
+    defineHook(name) {
+        const reg = this.hooks;
+        const existing = reg[name];
+        if (existing)
+            return existing;
+        const h = hook(`runtime.${name}`);
+        reg[name] = h;
+        this.observe(h);
+        return h;
+    }
+    /**
+     * Register a dispatch middleware. Outermost first — the order you call
+     * `use()` is the order layers wrap (first `use` is the outermost layer).
+     * Middlewares run once per dispatch, outside the retry loop.
+     *
+     * Each user middleware gets a distinct negative priority so the chain
+     * order matches registration order; the pinned subclass-owned "handler"
+     * step at `-Infinity` stays strictly innermost.
+     */
+    use(middleware) {
+        const priority = -this.userMiddlewareCount;
+        this.userMiddlewareCount += 1;
+        this.dispatchHook.use(async (hctx, next) => {
+            hctx.result = await middleware(async () => {
+                await next();
+                return hctx.result;
+            }, hctx.action, hctx.input, hctx.ctx);
+        }, { name: middleware.name || `middleware#${this.userMiddlewareCount}`, priority });
+    }
+    /**
+     * Install a capability. Adds its `provideRuntime` members to this runtime
+     * instance once, and queues its `provideCtx` so every dispatch sees the
+     * contribution. Duplicate names throw — capability install is meant to be
+     * explicit, and accidental double-installs usually indicate a layering bug
+     * (e.g. two plugins installing the same publish capability).
+     *
+     * `add` is the runtime-layer install verb; `with` belongs to the App
+     * layer, where it also advances the `<TCaps>` phantom type.
+     */
+    add(cap) {
+        if (this.capabilityNames.has(cap.name)) {
+            throw new Error(`Runtime.add: capability "${cap.name}" already installed.`);
+        }
+        this.capabilityNames.add(cap.name);
+        this.capabilities.push(cap);
+        if (cap.provideRuntime) {
+            const members = cap.provideRuntime(this);
+            for (const [key, fn] of Object.entries(members)) {
+                const target = this;
+                if (key in target) {
+                    throw new Error(`Runtime.add: capability "${cap.name}" tried to install runtime member "${key}", but the runtime already has it. Pick a different name.`);
+                }
+                target[key] = fn;
+            }
+        }
+    }
+    /** All installed capability names, in install order. Used by tests + Studio. */
+    listCapabilities() {
+        return this.capabilities.map((c) => c.name);
+    }
+    /**
+     * Internal — called by `execute` to build the ctx contribution from every
+     * installed capability for one dispatch. Public so subclass dispatchers
+     * (forge) can compose; not part of the documented contract.
+     */
+    buildCapabilityCtx(envelope) {
+        if (this.capabilities.length === 0)
+            return {};
+        const merged = {};
+        for (const cap of this.capabilities) {
+            if (!cap.provideCtx)
+                continue;
+            const piece = cap.provideCtx({
+                envelope,
+                container: this.container,
+                runtime: this,
+            });
+            Object.assign(merged, piece);
+        }
+        return merged;
+    }
+    /**
+     * Install an outbound pipeline stage. Position-ordered: early → middle →
+     * terminal. Within a position, install order is run order. Terminal stages
+     * carrying a `kind` are deduplicated — installing a second NATS terminal
+     * throws so silent override never happens.
+     */
+    sink(stage) {
+        if (stage.position === "terminal" && stage.kind) {
+            if (this.terminalKinds.has(stage.kind)) {
+                throw new Error(`Runtime.sink: terminal stage of kind "${stage.kind}" already installed — only one terminal per kind allowed.`);
+            }
+            this.terminalKinds.add(stage.kind);
+        }
+        this.sinkStages.push(stage);
+    }
+    /** All installed sink stages, in install order. Used by tests + Studio. */
+    listSinkStages() {
+        return this.sinkStages;
+    }
+    /**
+     * Drain the outbound chain for one event. Runs every stage in position
+     * order (early → middle → terminal); a stage returning `{ continue: false }`
+     * short-circuits the rest. Errors propagate (the publish capability that
+     * called this owns retry / dead-letter).
+     *
+     * This is the cross-process exit. Local fanout is `runtime.emit()`; the
+     * publish capability composes the two — `emit` for local subscribers,
+     * `sinkDrain` for cross-process delivery.
+     */
+    async sinkDrain(event, payload, envelope) {
+        if (this.sinkStages.length === 0)
+            return;
+        const ordered = this.orderedSinkStages();
+        const ctx = { event, payload, envelope };
+        for (const stage of ordered) {
+            const result = await stage.run(ctx);
+            if (result && result.continue === false)
+                return;
+        }
+    }
+    /** Stable position ordering: early → middle → terminal, install-order within. */
+    orderedSinkStages() {
+        const buckets = {
+            early: [],
+            middle: [],
+            terminal: [],
+        };
+        for (const s of this.sinkStages)
+            buckets[s.position].push(s);
+        return [...buckets.early, ...buckets.middle, ...buckets.terminal];
+    }
+    /**
+     * Wire a hook's per-step tap into the canonical telemetry stream. After
+     * this call, every `.use()` / `.on()` step on the hook emits a
+     * `kind: "hook.step"` record through `runtime.onTelemetry`, the same way
+     * the built-in `runtime.dispatch` hook does.
+     *
+     * The framework calls this for every framework hook in the registry;
+     * plugin authors can call it on their own hooks if they want their
+     * extension points surfaced in Studio / dev-logger / OTel for free.
+     */
+    observe(hk) {
+        hk.tap((obs) => {
+            this.pushTelemetry({
+                kind: "hook.step",
+                hookName: obs.hookName,
+                hookId: obs.hookId,
+                runId: obs.runId,
+                parentRunId: obs.parentRunId,
+                stepId: obs.stepId,
+                stepKind: obs.stepKind,
+                stepName: obs.stepName,
+                phase: obs.phase,
+                durationMs: obs.durationMs,
+                error: obs.error ? serializeError(obs.error) : undefined,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+        });
+    }
+    /**
+     * Subscribe to the canonical telemetry stream. Returns an unsubscribe.
+     * Throwing in a listener is caught and logged; never breaks dispatch.
+     */
+    onTelemetry(listener) {
+        this.telemetryListeners.push(listener);
+        return () => this.offTelemetry(listener);
+    }
+    offTelemetry(listener) {
+        const i = this.telemetryListeners.indexOf(listener);
+        if (i >= 0)
+            this.telemetryListeners.splice(i, 1);
+    }
+    /**
+     * Push a record onto the telemetry stream. Accepts `unknown` so
+     * subclass-widened records (CQRS kinds in forge) don't need cast
+     * gymnastics — listeners narrow with `switch (rec.kind)`.
+     *
+     * Public so external dispatchers (forge's ForgeDispatcher composed
+     * around a Runtime instance) can push records without subclassing.
+     * Misuse risk is low: callers who own a Runtime are by definition
+     * inside the trust boundary.
+     *
+     * Renamed from `emit` to free that name for the canonical event-
+     * broadcast verb (see `Runtime.emit(event, payload, envelope?)`).
+     */
+    pushTelemetry(record) {
+        if (this.telemetryListeners.length === 0)
+            return;
+        for (const listener of this.telemetryListeners) {
+            try {
+                listener(record);
+            }
+            catch (err) {
+                // Best-effort — don't let a bad listener break dispatch.
+                // eslint-disable-next-line no-console
+                console.error("Runtime.onTelemetry listener threw:", err);
+            }
+        }
+    }
+    getContainer() {
+        return this.container;
+    }
+    // ─── Canonical dispatch verbs ──────────────────────────────────────
+    /**
+     * Register a handler so it can be executed by string name. Stamps the
+     * handler into the runtime's registry and into the container under the
+     * key `handler:<name>` so middleware that needs to resolve it can.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registerHandler(handler) {
+        if (this.handlers.has(handler.name)) {
+            throw new Error(`Runtime.registerHandler: "${handler.name}" already registered.`);
+        }
+        this.handlers.set(handler.name, handler);
+    }
+    /**
+     * Look up a handler by name; throws if not registered.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getHandler(name) {
+        const h = this.handlers.get(name);
+        if (!h)
+            throw new Error(`Runtime: no handler registered with name "${name}".`);
+        return h;
+    }
+    /** All registered handler names — used by adapters to build wire tables. */
+    listHandlers() {
+        return [...this.handlers.keys()];
+    }
+    /**
+     * Canonical sync dispatch verb. Validates input via the handler's input
+     * schema, mints a child envelope (or seeds one when no parent is given),
+     * builds a per-request scope on the container, threads the result
+     * through the handler's `.use()` chain (and `.on()` listeners), then
+     * disposes the scope. Returns the handler's `ctx.result`.
+     *
+     * `handler` may be a `HandlerDefinition` reference (preferred) or a
+     * string name registered via `registerHandler()`.
+     */
+    async execute(handler, input, envelopePartial, extras) {
+        // Resolve string names eagerly. HandlerDefinition references and plain
+        // functions both flow through unchanged — the dispatcher below picks
+        // the path based on shape.
+        const target = typeof handler === "string" ? this.getHandler(handler) : handler;
+        // Envelope inheritance: when called from inside a handler chain, the
+        // parent envelope threads through so correlationId stays linked and
+        // causationId records what triggered this dispatch. When called from
+        // an entry point (HTTP adopter, queue subscriber) with no parent, the
+        // envelope is seeded fresh — either from explicit overrides or a fully
+        // new chain.
+        const envelope = envelopePartial?.parent
+            ? deriveEnvelope(envelopePartial.parent, {
+                tenant: envelopePartial.tenant,
+                userId: envelopePartial.userId,
+                user: envelopePartial.user,
+            })
+            : seedEnvelope({
+                tenant: envelopePartial?.tenant,
+                userId: envelopePartial?.userId,
+                user: envelopePartial?.user,
+                causationId: envelopePartial?.causationId,
+                correlationId: envelopePartial?.correlationId,
+            });
+        const scope = this.container.createScope();
+        const signal = envelopePartial?.signal ?? new AbortController().signal;
+        // Capability ctx — every `runtime.add(cap)` contributes per-dispatch
+        // ctx members via `provideCtx`. Spread FIRST so handler-provided extras
+        // and the canonical runtime verbs (execute/enqueue/emit/resolve/scope)
+        // can shadow if there's a name collision.
+        const capCtx = this.buildCapabilityCtx(envelope);
+        // The handler chain expects a ctx with at least `input` on it. We also
+        // expose envelope + the three verbs bound to this runtime, threaded
+        // with this envelope as the parent so child dispatches inherit the
+        // correlation chain automatically. Transport-specific `extras` (e.g.
+        // koa kctx, logger) land on the same ctx so plain http handlers and
+        // forge handlers see one shape.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ctx = {
+            ...capCtx,
+            ...(extras ?? {}),
+            input,
+            envelope,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            execute: (h, i, partial) => this.execute(h, i, { ...partial, parent: envelope }),
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            enqueue: (h, i, partial) => this.enqueue(h, i, { ...partial, parent: envelope }),
+            emit: (event, payload, partial) => this.emit(event, payload, { ...partial, parent: envelope }),
+            resolve: (name) => scope.resolve(name),
+            scope,
+        };
+        // Normalize the dispatch target to a HandlerDefinition. Plain
+        // `(input, ctx) => ...` functions get wrapped in a synthetic
+        // definition so the dispatch path has ONE shape downstream — no
+        // typeof-function branch, no parallel call site.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const def = typeof target === "function" && !("$kind" in target)
+            ? wrapFunctionAsHandlerDef(target)
+            : target;
+        const innerCore = async () => {
+            const out = await def.run(ctx, { signal });
+            return out.result;
+        };
+        try {
+            if (this.userMiddlewareCount > 0) {
+                this.ensureDispatchCorePin();
+                const hctx = {
+                    action: def,
+                    input,
+                    ctx,
+                    coreFn: innerCore,
+                };
+                await this.dispatchHook.run(hctx);
+                return hctx.result;
+            }
+            return await innerCore();
+        }
+        finally {
+            await scope.dispose();
+        }
+    }
+    /** Innermost dispatch step that calls the actual handler. Pinned once. */
+    dispatchCorePinned = false;
+    ensureDispatchCorePin() {
+        if (this.dispatchCorePinned)
+            return;
+        this.dispatchHook.use(async (hc, next) => {
+            hc.result = await hc.coreFn();
+            await next();
+        }, { name: "__nwire_runtime_core__", priority: Number.NEGATIVE_INFINITY });
+        this.dispatchCorePinned = true;
+    }
+    /**
+     * Fire-and-forget dispatch. Default implementation: `setImmediate` →
+     * `execute`. Queue-adapter installation can override this to enqueue
+     * onto an external queue (BullMQ, SQS, etc.). Errors are pushed onto
+     * the telemetry stream as `kind: "enqueue.failed"` — the caller has
+     * already returned.
+     */
+    enqueue(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler, input, envelopePartial) {
+        const name = typeof handler === "string" ? handler : handler.name;
+        setImmediate(() => {
+            void this.execute(handler, input, envelopePartial).catch((err) => {
+                this.pushTelemetry({
+                    kind: "enqueue.failed",
+                    handler: name,
+                    error: serializeError(err),
+                    appName: this.appName,
+                    ts: new Date().toISOString(),
+                });
+            });
+        });
+        return Promise.resolve();
+    }
+    /**
+     * Register a listener for an event. Returns an unsubscribe. Listeners are
+     * stored per `event.name` and fire in registration order via
+     * `Promise.allSettled` when `emit(event, ...)` is called. Throwing
+     * listeners are captured in telemetry but do not break sibling listeners.
+     */
+    when(event, listener) {
+        let set = this.eventListeners.get(event.name);
+        if (!set) {
+            set = new Set();
+            this.eventListeners.set(event.name, set);
+        }
+        set.add(listener);
+        return () => {
+            this.eventListeners.get(event.name)?.delete(listener);
+        };
+    }
+    /**
+     * Alias for {@link when} — same behavior, same return. Preserved for
+     * call sites that prefer the longer name.
+     */
+    subscribe(event, listener) {
+        return this.when(event, listener);
+    }
+    /**
+     * Broadcast an event to its subscribers. Validates payload against the
+     * event's schema, mints a child envelope, fires every registered
+     * subscriber in parallel (allSettled), and records a `kind:
+     * "event.emitted"` telemetry record. Subscriber throws are captured
+     * but do not propagate to the caller.
+     */
+    async emit(event, payload, envelopePartial) {
+        const validated = event.schema.parse(payload);
+        const envelope = envelopePartial?.parent
+            ? deriveEnvelope(envelopePartial.parent, {
+                tenant: envelopePartial.tenant,
+                userId: envelopePartial.userId,
+                user: envelopePartial.user,
+            })
+            : seedEnvelope({
+                tenant: envelopePartial?.tenant,
+                userId: envelopePartial?.userId,
+                user: envelopePartial?.user,
+                causationId: envelopePartial?.causationId,
+                correlationId: envelopePartial?.correlationId,
+            });
+        const startedAt = performance.now();
+        const subs = this.eventListeners.get(event.name);
+        if (subs && subs.size > 0) {
+            // Wrap in async so a SYNC throw inside fn() rejects the wrapper
+            // rather than escaping the .map(). allSettled then captures it.
+            const results = await Promise.allSettled([...subs].map(async (fn) => fn(validated, envelope)));
+            for (const r of results) {
+                if (r.status === "rejected") {
+                    this.pushTelemetry({
+                        kind: "event.listener.failed",
+                        event: event.name,
+                        envelope,
+                        error: serializeError(r.reason),
+                        appName: this.appName,
+                        ts: new Date().toISOString(),
+                    });
+                }
+            }
+        }
+        this.pushTelemetry({
+            kind: "event.emitted",
+            event: event.name,
+            payload: validated,
+            envelope,
+            durationMs: performance.now() - startedAt,
+            subscriberCount: subs?.size ?? 0,
+            appName: this.appName,
+            ts: new Date().toISOString(),
+        });
+    }
+}
+/**
+ * Canonical factory for a Runtime. Matches the foundation-doc shape
+ * (`createRuntime(opts)`) so consumer code stays uniform across
+ * primitives — `createContainer()`, `createInterface()`, `createApp()`,
+ * `createRuntime()`. The `new Runtime(opts)` form remains available for
+ * subclasses + tests that need to override protected members.
+ */
+export function createRuntime(options = {}) {
+    return new Runtime(options);
+}
+/**
+ * Wrap a plain `(input, ctx) => …` function in a minimal HandlerDefinition
+ * so `runtime.execute` has one dispatch path. No hook chain, no validation
+ * — just enough shape for `def.run(ctx)` to call the function and surface
+ * its result on `ctx.result`. Allocated once per execute call; the cost
+ * is one object + two property reads relative to a direct function call.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function wrapFunctionAsHandlerDef(fn) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return {
+        $kind: "handler",
+        name: fn.name || "anonymous",
+        config: { handler: fn },
+        async run(ctx) {
+            ctx.result = await fn(ctx.input, ctx);
+            return ctx;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+}
+export { isBuiltInHook };

package/dist/sink.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Outbound sink chain — the seam between in-process event emission and
+ * cross-process delivery.
+ *
+ * Plugins and endpoint adapters install stages with `runtime.sink(stage)`.
+ * At drain time every stage runs in position order; a stage that returns
+ * `{ continue: false }` stops the chain. Empty chain is a no-op.
+ *
+ * The runtime knows about the chain but nothing about transports — every
+ * terminal (NATS, webhook, OTLP, log file) is installed by an outbound
+ * adapter through `endpoint.use(...)` at boot.
+ */
+import type { MessageEnvelope } from "@nwire/envelope";
+import type { EventDefinition } from "@nwire/messages";
+/**
+ * Where in the pipeline a stage runs. Stages within the same position fire
+ * in install order; positions fire in this order:
+ *
+ *   early    — outbox / dedup / validate (runs before anything else)
+ *   middle   — filter / tee / transform (the bulk of the work)
+ *   terminal — broker / webhook / sink-to-disk (one per kind, asserted at boot)
+ */
+export type StagePosition = "early" | "middle" | "terminal";
+/**
+ * Per-stage context. The drain builder hands every stage the same shape;
+ * a stage may mutate `payload` (transform) or read `envelope` (route).
+ */
+export interface StageContext {
+    readonly event: EventDefinition & {
+        readonly name: string;
+    };
+    payload: unknown;
+    readonly envelope: MessageEnvelope;
+}
+/**
+ * An outbound pipeline stage. Returns nothing to keep going, or
+ * `{ continue: false }` to short-circuit (e.g. visibility filter rejecting
+ * a private event before it hits the terminal broker).
+ */
+export interface OutboundStage {
+    readonly name: string;
+    readonly position: StagePosition;
+    /**
+     * Optional kind tag — `"nats" | "webhook" | "otlp" | ...`. For terminal
+     * stages it enforces uniqueness (one nats terminal per runtime). For
+     * non-terminal stages it's diagnostic only.
+     */
+    readonly kind?: string;
+    run(ctx: StageContext): Promise<{
+        continue?: boolean;
+    } | void> | {
+        continue?: boolean;
+    } | void;
+}

package/dist/sink.js

@@ -0,0 +1,13 @@
+/**
+ * Outbound sink chain — the seam between in-process event emission and
+ * cross-process delivery.
+ *
+ * Plugins and endpoint adapters install stages with `runtime.sink(stage)`.
+ * At drain time every stage runs in position order; a stage that returns
+ * `{ continue: false }` stops the chain. Empty chain is a no-op.
+ *
+ * The runtime knows about the chain but nothing about transports — every
+ * terminal (NATS, webhook, OTLP, log file) is installed by an outbound
+ * adapter through `endpoint.use(...)` at boot.
+ */
+export {};