@nwire/app 0.9.2 → 0.10.0

package/dist/runtime/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runtime — Container + dispatch hook + per-runtime FrameworkHooks
+ * registry + telemetry stream + plugin lifecycle.
+ */
+export { Runtime, createRuntime, isBuiltInHook, serializeError, type RuntimeOptions, type Telemetry, type TelemetryListener, type HookStepTelemetry, type DispatchHookCtx, type DispatchMiddleware, type SerializedError, type PluginDefinition, type PluginContext, } from "./runtime.js";
+export { createFrameworkHooks, type FrameworkHooks, type PluginKind, } from "./framework-hooks.js";

package/dist/runtime/index.js

@@ -0,0 +1,6 @@
+/**
+ * Runtime — Container + dispatch hook + per-runtime FrameworkHooks
+ * registry + telemetry stream + plugin lifecycle.
+ */
+export { Runtime, createRuntime, isBuiltInHook, serializeError, } from "./runtime.js";
+export { createFrameworkHooks, } from "./framework-hooks.js";

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,349 @@
+/**
+ * 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";
+/**
+ * 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;
+    /**
+     * Registered plugins (one entry per `registerPlugin(def)` call). Each
+     * carries the captured boot/dispose closures the setup contributed.
+     * Boot fires in FIFO order at `start()`; dispose fires in LIFO order
+     * at `stop()`.
+     */
+    private readonly plugins;
+    /**
+     * Lifecycle state machine. Both `start()` and `stop()` are idempotent
+     * and in-flight-shared: a second call while the first is still pending
+     * returns the same Promise; a second call after completion is a no-op.
+     */
+    private lifecycle;
+    private startPromise;
+    private stopPromise;
+    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;
+    /**
+     * 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;
+    /** Current lifecycle phase. */
+    get state(): "idle" | "starting" | "running" | "stopping" | "stopped";
+    /**
+     * Register a plugin. The setup closure runs synchronously now —
+     * `bind()` calls land on the container immediately; `boot()` /
+     * `dispose()` calls accumulate queues that fire at `start()` /
+     * `stop()`. Returns the registered entry for callers that want it
+     * (rare — most consumers just discard).
+     *
+     * Plugin re-registration with the same `name` throws. Plugin setup
+     * may NOT await — async work belongs in `boot()`.
+     */
+    registerPlugin(plugin: PluginDefinition): RegisteredPlugin;
+    /**
+     * Two-phase boot. Idempotent + in-flight-shared.
+     *
+     *   1. Fire `PluginRegistered` for each registered plugin (observable).
+     *   2. Fire `AppRegistering` chain (vetoable via skip-next).
+     *   3. Fire `AppBooting` chain (vetoable via skip-next).
+     *   4. For each plugin in registration order:
+     *        - fire `PluginBooting` chain (vetoable)
+     *        - await every queued `boot()` fn for that plugin
+     *        - fire `PluginBooted` (observable)
+     *   5. Run container health checks; fail-fast if any throw.
+     *   6. Fire `AppBooted` + `AppReady` (observable).
+     */
+    start(): Promise<void>;
+    /**
+     * Graceful shutdown. Idempotent + in-flight-shared.
+     *
+     *   1. Fire `AppShuttingDown` chain (vetoable via skip-next).
+     *   2. For each plugin in REVERSE registration order:
+     *        - fire `PluginShuttingDown` (chain — refusal skips that
+     *          plugin's dispose so downstream plugins still clean up)
+     *        - run every queued `dispose()` fn in reverse, errors isolated
+     *        - fire `PluginShutdown` (observable)
+     *   3. `container.dispose()` — runs every bind({ dispose }) in LIFO.
+     *   4. Fire `AppShutdown` (observable).
+     */
+    stop(reason?: string): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Subscribe to 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.
+     */
+    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. `setup` runs synchronously at `registerPlugin()`
+ * time — `bind()` calls land on the container immediately; `boot()` /
+ * `dispose()` calls accumulate queues that fire at `start()` / `stop()`.
+ *
+ * Async work belongs in `boot()`. Setup throws abort registration.
+ */
+export interface PluginDefinition {
+    readonly name: string;
+    setup(ctx: PluginContext): void;
+}
+/**
+ * What the setup closure receives. `bind` writes to the container;
+ * `boot` / `dispose` queue async work; `hooks` + `defineHook` expose
+ * the per-runtime framework-hook registry.
+ */
+export interface PluginContext {
+    readonly container: Container;
+    readonly runtime: Runtime;
+    readonly hooks: FrameworkHooks;
+    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;
+    boot(fn: () => Promise<void> | void): void;
+    dispose(fn: () => Promise<void> | void): void;
+    defineHook<TCtx>(name: keyof FrameworkHooks): Hook<TCtx>;
+}
+/** Internal record kept on the runtime for each plugin. */
+interface RegisteredPlugin {
+    readonly name: string;
+    readonly boots: Array<() => Promise<void> | void>;
+    readonly disposes: Array<() => Promise<void> | void>;
+}
+export { isBuiltInHook };