@nwire/runtime 0.11.0

package/dist/runtime.d.ts

@@ -0,0 +1,402 @@
+/**
+ * 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 { type Container } from "@nwire/container/awilix";
+import { type Hook } from "@nwire/hooks";
+import { type Logger } from "@nwire/logger";
+import { type MessageEnvelope } from "@nwire/envelope";
+import type { HandlerDefinition } from "@nwire/handler";
+import type { EventDefinition } from "@nwire/messages";
+import { isBuiltInHook, type FrameworkHooks } from "./framework-hooks.js";
+import type { Capability } from "./capability.js";
+import type { OutboundStage } from "./sink.js";
+/**
+ * Serialized form of any thrown value — `Error` instances keep `name` /
+ * `message` / `stack` plus any own enumerable properties; non-Error throws
+ * round-trip as `{ name: "NonError", message: String(err) }`. Used by every
+ * telemetry record that carries an error payload.
+ */
+export type SerializedError = {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly [k: string]: unknown;
+};
+export declare function serializeError(err: unknown): SerializedError;
+/**
+ * `hook.step` — one record per chain/listener phase on any adopted hook.
+ * `runId` / `parentRunId` link nested hook invocations into a causal tree —
+ * that's what Studio's Trace page uses.
+ */
+export interface HookStepTelemetry {
+    readonly kind: "hook.step";
+    readonly hookName: string;
+    readonly hookId: string;
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly stepId: number;
+    readonly stepKind: "chain" | "listener";
+    readonly stepName?: string;
+    readonly phase: "start" | "end" | "error";
+    readonly durationMs?: number;
+    readonly error?: SerializedError;
+    readonly appName: string;
+    readonly ts: string;
+}
+/**
+ * Base `Telemetry` union — generic kinds only. Subclasses (forge) WIDEN
+ * this with their own domain kinds and re-export the wider union as their
+ * own `Telemetry` alias. Consumers that listen on the base accept
+ * everything; consumers that care about discriminants narrow with
+ * `switch (rec.kind)`.
+ */
+export type Telemetry = HookStepTelemetry;
+export type TelemetryListener<T = Telemetry> = (record: T) => void;
+/**
+ * Per-dispatch context passed through the `runtime.dispatch` hook. Subclass
+ * dispatchers populate `coreFn` with their retry-loop + handler-invocation
+ * closure; the pinned innermost chain step calls it and writes `result`.
+ * User middlewares attached via `runtime.use()` see this ctx via adapters
+ * that re-expose the legacy `(next, action, input, ctx)` shape.
+ *
+ * Types here are deliberately structural / unknown — the base runtime
+ * doesn't know what an "action" or "context" looks like; forge tightens
+ * the generics in its own re-export.
+ */
+export interface DispatchHookCtx {
+    readonly action: unknown;
+    readonly input: unknown;
+    readonly ctx: unknown;
+    readonly coreFn: () => Promise<unknown>;
+    result?: unknown;
+}
+/**
+ * Onion-style extension point around action dispatch. Outermost first;
+ * registration order is execution order (matches Koa/express semantics).
+ * Middlewares run OUTSIDE any retry loop — one pass per dispatch.
+ */
+export type DispatchMiddleware = (next: () => Promise<unknown>, action: unknown, input: unknown, ctx: unknown) => Promise<unknown>;
+export interface RuntimeOptions {
+    readonly container?: Container;
+    readonly logger?: Logger;
+    /**
+     * App / service name. Stamped on every telemetry record so a single
+     * multi-tenant observer can demux records by origin.
+     */
+    readonly appName?: string;
+}
+export declare class Runtime {
+    protected readonly container: Container;
+    protected readonly _logger: Logger;
+    readonly appName: string;
+    /**
+     * Public accessor — external dispatchers compose runtimes and need the
+     * logger; test-kit harness extensions also swap it in for tap capture.
+     */
+    get logger(): Logger;
+    set logger(value: Logger);
+    /** Public accessor — external dispatchers register middleware via this hook. */
+    get dispatchHook$(): Hook<DispatchHookCtx>;
+    /**
+     * 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.
+     */
+    protected readonly dispatchHook: Hook<DispatchHookCtx>;
+    private userMiddlewareCount;
+    /**
+     * 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)`.
+     */
+    readonly hooks: FrameworkHooks;
+    private readonly 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.
+     */
+    private readonly handlers;
+    /**
+     * 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)`).
+     */
+    private readonly eventListeners;
+    /**
+     * 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.
+     */
+    private readonly capabilities;
+    private readonly capabilityNames;
+    /**
+     * 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.
+     */
+    private readonly sinkStages;
+    private readonly terminalKinds;
+    constructor(options?: RuntimeOptions);
+    /**
+     * 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<TPayload>(name: keyof FrameworkHooks): Hook<TPayload>;
+    /**
+     * 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: DispatchMiddleware): void;
+    /**
+     * 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: Capability<unknown>): void;
+    /** All installed capability names, in install order. Used by tests + Studio. */
+    listCapabilities(): readonly string[];
+    /**
+     * 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: MessageEnvelope): Record<string, unknown>;
+    /**
+     * 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: OutboundStage): void;
+    /** All installed sink stages, in install order. Used by tests + Studio. */
+    listSinkStages(): readonly OutboundStage[];
+    /**
+     * 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.
+     */
+    sinkDrain(event: EventDefinition & {
+        readonly name: string;
+    }, payload: unknown, envelope: MessageEnvelope): Promise<void>;
+    /** Stable position ordering: early → middle → terminal, install-order within. */
+    private orderedSinkStages;
+    /**
+     * 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<TCtx>(hk: Hook<TCtx>): void;
+    /**
+     * Subscribe to the canonical telemetry stream. Returns an unsubscribe.
+     * Throwing in a listener is caught and logged; never breaks dispatch.
+     */
+    onTelemetry<T = Telemetry>(listener: TelemetryListener<T>): () => void;
+    offTelemetry<T = Telemetry>(listener: TelemetryListener<T>): void;
+    /**
+     * 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: unknown): void;
+    getContainer(): Container;
+    /**
+     * 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.
+     */
+    registerHandler(handler: HandlerDefinition<any, any, any>): void;
+    /**
+     * Look up a handler by name; throws if not registered.
+     */
+    getHandler(name: string): HandlerDefinition<any, any, any>;
+    /** All registered handler names — used by adapters to build wire tables. */
+    listHandlers(): readonly string[];
+    /**
+     * 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()`.
+     */
+    execute<TInput = unknown, TOutput = unknown>(handler: HandlerDefinition<any, TOutput, any> | string | ((input: TInput, ctx: any) => TOutput | Promise<TOutput>), input: TInput, envelopePartial?: Partial<MessageEnvelope> & {
+        readonly signal?: AbortSignal;
+        readonly parent?: MessageEnvelope;
+    }, extras?: Record<string, unknown>): Promise<TOutput>;
+    /** Innermost dispatch step that calls the actual handler. Pinned once. */
+    private dispatchCorePinned;
+    private ensureDispatchCorePin;
+    /**
+     * 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<TInput = unknown>(handler: HandlerDefinition<any, any, any> | string, input: TInput, envelopePartial?: Partial<MessageEnvelope> & {
+        readonly signal?: AbortSignal;
+        readonly parent?: MessageEnvelope;
+    }): Promise<void>;
+    /**
+     * 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<TPayload>(event: EventDefinition & {
+        readonly name: string;
+    }, listener: (payload: TPayload, envelope: MessageEnvelope) => void | Promise<void>): () => void;
+    /**
+     * Alias for {@link when} — same behavior, same return. Preserved for
+     * call sites that prefer the longer name.
+     */
+    subscribe<TPayload>(event: EventDefinition & {
+        readonly name: string;
+    }, listener: (payload: TPayload, envelope: MessageEnvelope) => void | Promise<void>): () => void;
+    /**
+     * 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.
+     */
+    emit<TPayload>(event: EventDefinition & {
+        readonly name: string;
+        readonly schema: {
+            parse(input: unknown): unknown;
+        };
+    }, payload: TPayload, envelopePartial?: Partial<MessageEnvelope> & {
+        readonly parent?: MessageEnvelope;
+    }): Promise<void>;
+}
+/**
+ * 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 declare function createRuntime(options?: RuntimeOptions): Runtime;
+/**
+ * Plugin definition. Two synchronous phases:
+ *
+ *   - `register?` runs first — bindings declared here are guaranteed
+ *     available when any plugin's setup runs.
+ *   - `setup` runs second — capabilities, middleware, sinks, hook
+ *     observers, and boot/shutdown queues land here.
+ *
+ * Plugins that only need wiring satisfy the interface with `setup` alone;
+ * `register` is optional.
+ *
+ * `TOptions` is the construction option type that plugin factories close
+ * over (e.g. `queuePlugin({ connection })`). The same value is surfaced
+ * on the context as `ctx.options` so plugin bodies can be written without
+ * relying on JS closure capture.
+ *
+ * `TMark` is the phantom carrier that the App's `<TCaps>` accumulates
+ * across `.with(plugin)`. Never read at runtime.
+ */
+export interface PluginDefinition<TOptions = void, TMark = unknown> {
+    readonly name: string;
+    /** Options closed at construction. Surfaced as `ctx.options`. */
+    readonly options?: TOptions;
+    /** Declaration phase — bindings + hook materialisation. */
+    register?(ctx: PluginContext<TOptions>): void;
+    /** Wiring phase — capabilities, middleware, listeners, boot/shutdown queues. */
+    setup(ctx: PluginContext<TOptions>): void;
+    /** Phantom marker for App<TCaps> accumulation. Pure type-level. */
+    readonly __mark?: TMark;
+}
+/**
+ * What register/setup closures receive. One context type is used by both
+ * phases. Members:
+ *
+ *   - `container` / `runtime` / `hooks` — the layer references
+ *   - `options`     — the typed value the plugin was constructed with
+ *   - `bind`        — write a binding into the container
+ *   - `add(cap)`    — install a capability (proxies to `runtime.add`)
+ *   - `sink(stage)` — install an outbound pipeline stage
+ *   - `use(mw)`     — wrap dispatch in middleware (via runtime)
+ *   - `on(hook, fn)` — observe a framework hook
+ *   - `boot(fn)` / `shutdown(fn)` — async lifecycle queues
+ *   - `defineHook(name)` — materialise a plugin-defined framework hook slot
+ */
+export interface PluginContext<TOptions = void> {
+    readonly container: Container;
+    readonly runtime: Runtime;
+    readonly hooks: FrameworkHooks;
+    /** Options the plugin was constructed with. `undefined` for option-less plugins. */
+    readonly options: TOptions;
+    bind<T>(name: string, factory: T | (() => T) | (new (cradle: unknown) => T), opts?: {
+        dispose?: (v: T) => void | Promise<void>;
+        check?: (v: T) => void | Promise<void>;
+    }): void;
+    /** Install a capability — same as `runtime.add(cap)` but routed through this plugin. */
+    add(cap: Capability<unknown>): void;
+    /** Install an outbound pipeline stage. */
+    sink(stage: OutboundStage): void;
+    /** Observe a framework hook — calls `runtime.hooks[name].on(fn)` under the hood. */
+    on<K extends keyof FrameworkHooks>(name: K, fn: (payload: unknown) => void): void;
+    boot(fn: () => Promise<void> | void): void;
+    /** Async cleanup work to run at `runtime.stop()`. */
+    dispose(fn: () => Promise<void> | void): void;
+    /** Alias for {@link dispose}. */
+    shutdown(fn: () => Promise<void> | void): void;
+    defineHook<TCtx>(name: keyof FrameworkHooks): Hook<TCtx>;
+}
+export { isBuiltInHook };