@nwire/runtime 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  * plus runtime alone is enough to dispatch handlers with envelopes, install
  * capabilities, install middleware, and react to events without any App.
  */
-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 { Runtime, createRuntime, isBuiltInHook, serializeError, type RuntimeOptions, type Telemetry, type TelemetryListener, type HookStepTelemetry, type DispatchHookCtx, type DispatchMiddleware, type SerializedError, type PluginDefinition, type PluginContext, type ListenerContext, } from "./runtime.js";
 export { createFrameworkHooks, type FrameworkHooks, type PluginKind } from "./framework-hooks.js";
 export { defineCapability, type Capability, type CapabilityBase } from "./capability.js";
 export type { OutboundStage, StagePosition, StageContext } from "./sink.js";

package/dist/runtime.d.ts

@@ -10,7 +10,7 @@ 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 type { EventDefinition, EventPayload } from "@nwire/messages";
 import { isBuiltInHook, type FrameworkHooks } from "./framework-hooks.js";
 import type { Capability } from "./capability.js";
 import type { OutboundStage } from "./sink.js";
@@ -292,22 +292,24 @@ export declare class Runtime {
         readonly signal?: AbortSignal;
         readonly parent?: MessageEnvelope;
     }): Promise<void>;
+    /** Resolve a dependency from the runtime's container. */
+    resolve<T = unknown>(name: string): T;
     /**
      * 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 & {
+    when<E extends EventDefinition & {
         readonly name: string;
-    }, listener: (payload: TPayload, envelope: MessageEnvelope) => void | Promise<void>): () => void;
+    }>(event: E, listener: (payload: EventPayload<E>, ctx: ListenerContext) => 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 & {
+    subscribe<E extends EventDefinition & {
         readonly name: string;
-    }, listener: (payload: TPayload, envelope: MessageEnvelope) => void | Promise<void>): () => void;
+    }>(event: E, listener: (payload: EventPayload<E>, ctx: ListenerContext) => void | Promise<void>): () => void;
     /**
      * Broadcast an event to its subscribers. Validates payload against the
      * event's schema, mints a child envelope, fires every registered
@@ -324,6 +326,33 @@ export declare class Runtime {
         readonly parent?: MessageEnvelope;
     }): Promise<void>;
 }
+/**
+ * Context handed to an event listener. A strict SUBSET of the workflow
+ * `when` ctx — so a `when(Event, (payload, ctx) => …)` block written in a
+ * listener moves into a `defineWorkflow` unchanged (the workflow adds
+ * `assign` / state / `schedule` on top). Every verb threads this event's
+ * envelope as the parent, so follow-up dispatches inherit the correlation
+ * chain.
+ */
+export interface ListenerContext {
+    /** This event's envelope — tenant, user, correlation, causation. */
+    readonly envelope: MessageEnvelope;
+    /** Dispatch a follow-up action and await its result. */
+    send<I, O>(handler: HandlerDefinition<any, O, any> | string, input: I, partial?: Partial<MessageEnvelope> & {
+        readonly signal?: AbortSignal;
+    }): Promise<O>;
+    /** Publish another event. */
+    emit<E extends EventDefinition & {
+        readonly name: string;
+        readonly schema: {
+            parse(input: unknown): unknown;
+        };
+    }>(event: E, payload: EventPayload<E>, partial?: Partial<MessageEnvelope>): Promise<void>;
+    /** Resolve a dependency from the container. */
+    resolve<T = unknown>(name: string): T;
+    /** The runtime logger. */
+    readonly logger: Logger;
+}
 /**
  * Canonical factory for a Runtime. Matches the foundation-doc shape
  * (`createRuntime(opts)`) so consumer code stays uniform across
@@ -390,8 +419,12 @@ export interface PluginContext<TOptions = void> {
     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;
+    /**
+     * Observe a framework lifecycle hook — calls `runtime.hooks[name].on(fn)`
+     * under the hood. The payload is typed from the named hook, so
+     * `on("AppBooted", ({ appName, bootedAt }) => …)` is fully inferred.
+     */
+    on<K extends keyof FrameworkHooks>(name: K, fn: (payload: FrameworkHooks[K] extends Hook<infer P> ? P : never) => void): void;
     boot(fn: () => Promise<void> | void): void;
     /** Async cleanup work to run at `runtime.stop()`. */
     dispose(fn: () => Promise<void> | void): void;

package/dist/runtime.js

@@ -477,6 +477,10 @@ export class Runtime {
         });
         return Promise.resolve();
     }
+    /** Resolve a dependency from the runtime's container. */
+    resolve(name) {
+        return this.container.resolve(name);
+    }
     /**
      * Register a listener for an event. Returns an unsubscribe. Listeners are
      * stored per `event.name` and fire in registration order via
@@ -526,9 +530,19 @@ export class Runtime {
         const startedAt = performance.now();
         const subs = this.eventListeners.get(event.name);
         if (subs && subs.size > 0) {
+            // Listener ctx — the documented subset of the workflow `when` ctx,
+            // every verb threaded with this envelope as parent so follow-up
+            // dispatches inherit the correlation chain.
+            const listenerCtx = {
+                envelope,
+                send: (h, i, partial) => this.execute(h, i, { ...partial, parent: envelope }),
+                emit: (ev, p, partial) => this.emit(ev, p, { ...partial, parent: envelope }),
+                resolve: (name) => this.container.resolve(name),
+                logger: this._logger,
+            };
             // 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)));
+            const results = await Promise.allSettled([...subs].map(async (fn) => fn(validated, listenerCtx)));
             for (const r of results) {
                 if (r.status === "rejected") {
                     this.pushTelemetry({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/runtime",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Nwire — envelope-execution substrate. Dispatch + emit + when + sink + capability registry. Extracted from @nwire/app for 0.11. Standalone usable without the App layer.",
   "keywords": [
     "capability",
@@ -27,12 +27,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@nwire/container": "0.11.0",
-    "@nwire/handler": "0.11.0",
-    "@nwire/logger": "0.11.0",
-    "@nwire/messages": "0.11.0",
-    "@nwire/envelope": "0.11.0",
-    "@nwire/hooks": "0.11.0"
+    "@nwire/envelope": "0.12.0",
+    "@nwire/container": "0.12.0",
+    "@nwire/hooks": "0.12.0",
+    "@nwire/logger": "0.12.0",
+    "@nwire/messages": "0.12.0",
+    "@nwire/handler": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",