@nwire/app 0.8.17 → 0.9.1

package/dist/framework-event-bus.d.ts

@@ -5,25 +5,29 @@
  * and modules subscribe with `bus.on(Event, handler)`; the runtime fires
  * events at the appropriate lifecycle points with `bus.fire(Event, payload)`.
  *
- * Dispatch semantics come from the event's `mode`:
+ * Internals: every event delegates to a `hook<TPayload>(name)` from
+ * `@nwire/hooks`. Subscribers attach as hook chain steps (series /
+ * series-bail) or hook listeners (parallel). Dispatch is `hook.run()` —
+ * no parallel subscription map. Telemetry, replay, .tap observation,
+ * cancellation all come from hooks substrate by construction.
  *
- *   parallel    → all handlers concurrently; one failing doesn't affect
- *                 others; errors are logged via the supplied logger.
- *   series      → sequential await; one failing stops the chain and throws.
- *   series-bail → sequential await; a handler returning `false` stops the
- *                 chain cleanly (no throw) and `fire` returns false to
- *                 signal "prevented". Returning anything else (including
- *                 undefined/void) is treated as "ok, continue".
+ * Dispatch semantics come from the event's `mode`:
  *
- * The series-bail mode is the interceptable hook — `*-ing` events use it
- * so plugins can veto an action, refuse a shutdown, etc.
+ *   parallel    → handlers fire as hook listeners (Promise.allSettled);
+ *                 one failing doesn't affect others; errors are logged.
+ *   series      → handlers fire as chain steps in priority order;
+ *                 one throwing stops the chain.
+ *   series-bail → handlers fire as chain steps in priority order;
+ *                 returning `false` short-circuits (don't call next()).
+ *                 `fire()` returns false to signal "prevented".
  *
  * The bus lives in `@nwire/app` (the "managed Container with lifecycle"
  * layer). `@nwire/forge` re-exports the same surface so consumers that
  * pull from forge get one import line.
  */
-import type { FrameworkEventDefinition } from "./framework-events.js";
+import { type Hook } from "@nwire/hooks";
 import type { Logger } from "@nwire/logger";
+import type { FrameworkEventDefinition } from "./framework-events.js";
 /**
  * Handler signature. The handler MAY:
  *   - return nothing                            → "continue"
@@ -56,18 +60,14 @@ export type FrameworkEventObserver = (record: FrameworkEventObservation) => void
  * focused on the domain pipeline. Designed to be reusable — Studio, the
  * orchestrator, and external plugins all hit the same surface.
  */
-import { type Hook } from "@nwire/hooks";
 export declare class FrameworkEventBus {
-    private readonly subs;
     private readonly observers;
     private readonly logger;
     /**
-     * One hook per event name, lazily created on first `fire()`. Each hook has
-     * a single no-op chain step named "dispatch" so every fire emits start +
-     * end taps under `framework.event:<eventName>`. The dispatch logic in
-     * `fire()` is unchanged — these hooks are an observation surface so
-     * `listHooks()` + scan + Studio see every framework event in the
-     * registry, not a replacement for the existing dispatcher.
+     * One hook per event name. Each event's subscribers attach as chain
+     * steps (series / series-bail) or listeners (parallel) on its hook;
+     * dispatch is `hook.run()`. `listHooks()` + scan + Studio see every
+     * framework event in the registry by construction.
      *
      * Runtime can pass an `adoptHook` callback in the constructor; each
      * lazily-created hook is adopted so taps flow into the canonical
@@ -87,7 +87,7 @@ export declare class FrameworkEventBus {
             readonly name: string;
         }>;
     });
-    /** Lazily create + adopt the per-event hook. Called from `fire()`. */
+    /** Lazily create + adopt the per-event hook. Bus dispatches through these. */
     private ensureEventHook;
     /**
      * Subscribe to EVERY framework-event firing on this bus. Used by the
@@ -103,15 +103,27 @@ export declare class FrameworkEventBus {
      * series-bail / series modes (higher runs first; default 0). Framework
      * built-ins should subscribe at priority 100+; debug/observer plugins
      * at -100 so they see the final post-mutation state.
+     *
+     * Attaches to the per-event hook: as a listener (parallel mode) or as
+     * a chain step (series / series-bail). The returned handle calls
+     * `hook.off()` to detach.
      */
     on<TPayload>(event: FrameworkEventDefinition<TPayload>, handler: FrameworkEventHandler<TPayload>, priority?: number): () => void;
     /**
      * Fire a framework event. Resolves to `false` when a series-bail handler
      * vetoed; `true` otherwise. The boolean is irrelevant for parallel /
-     * series modes and always returns `true` there for them.
+     * series modes and always returns `true` there.
+     *
+     * Internally: delegates to the per-event hook's `.run()` (parallel /
+     * series) or `.runDetailed()` (series-bail, to detect "prevented"
+     * outcome from short-circuit). The hook's observability surface (.tap,
+     * StepObservation) lights up automatically.
      */
     fire<TPayload>(event: FrameworkEventDefinition<TPayload>, payload: TPayload): Promise<boolean>;
-    /** Count subscribers for an event — diagnostic surface (Studio, tests). */
+    /**
+     * Count subscribers for an event — diagnostic surface (Studio, tests).
+     * Sums chain steps and listeners attached to the per-event hook.
+     */
     subscriberCount(event: FrameworkEventDefinition): number;
 }
 //# sourceMappingURL=framework-event-bus.d.ts.map

package/dist/framework-event-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"framework-event-bus.d.ts","sourceRoot":"","sources":["../src/framework-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,CAAC,QAAQ,IAAI,CAC5C,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC;AAO9C;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AACD,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,yBAAyB,KAAK,IAAI,CAAC;AAEjF;;;;GAIG;AACH,OAAO,EAAQ,KAAK,IAAI,EAAE,MAAM,cAAc,CAAC;AAE/C,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8C;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA6B;gBAGtD,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;QACvC;;;;;WAKG;QACH,MAAM,CAAC,EAAE,aAAa,CAAC;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC9C;IASR,sEAAsE;IACtE,OAAO,CAAC,eAAe;IAevB;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAQpD,OAAO,CAAC,MAAM;IAgBd;;;;;OAKG;IACH,EAAE,CAAC,QAAQ,EACT,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EACzC,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EACxC,QAAQ,GAAE,MAAU,GACnB,MAAM,IAAI;IAgBb;;;;OAIG;IACG,IAAI,CAAC,QAAQ,EACjB,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EACzC,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;IAmEnB,2EAA2E;IAC3E,eAAe,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM;CAGzD"}
+{"version":3,"file":"framework-event-bus.d.ts","sourceRoot":"","sources":["../src/framework-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAQ,KAAK,IAAI,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,CAAC,QAAQ,IAAI,CAC5C,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AACD,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,yBAAyB,KAAK,IAAI,CAAC;AAEjF;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA6B;gBAGtD,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;QACvC;;;;;WAKG;QACH,MAAM,CAAC,EAAE,aAAa,CAAC;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC9C;IASR,8EAA8E;IAC9E,OAAO,CAAC,eAAe;IASvB;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAQpD,OAAO,CAAC,MAAM;IAgBd;;;;;;;;;OASG;IACH,EAAE,CAAC,QAAQ,EACT,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EACzC,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EACxC,QAAQ,GAAE,MAAU,GACnB,MAAM,IAAI;IAiCb;;;;;;;;;OASG;IACG,IAAI,CAAC,QAAQ,EACjB,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EACzC,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;IAgCnB;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM;CAMzD"}

package/dist/framework-event-bus.js

@@ -5,40 +5,40 @@
  * and modules subscribe with `bus.on(Event, handler)`; the runtime fires
  * events at the appropriate lifecycle points with `bus.fire(Event, payload)`.
  *
- * Dispatch semantics come from the event's `mode`:
+ * Internals: every event delegates to a `hook<TPayload>(name)` from
+ * `@nwire/hooks`. Subscribers attach as hook chain steps (series /
+ * series-bail) or hook listeners (parallel). Dispatch is `hook.run()` —
+ * no parallel subscription map. Telemetry, replay, .tap observation,
+ * cancellation all come from hooks substrate by construction.
  *
- *   parallel    → all handlers concurrently; one failing doesn't affect
- *                 others; errors are logged via the supplied logger.
- *   series      → sequential await; one failing stops the chain and throws.
- *   series-bail → sequential await; a handler returning `false` stops the
- *                 chain cleanly (no throw) and `fire` returns false to
- *                 signal "prevented". Returning anything else (including
- *                 undefined/void) is treated as "ok, continue".
+ * Dispatch semantics come from the event's `mode`:
  *
- * The series-bail mode is the interceptable hook — `*-ing` events use it
- * so plugins can veto an action, refuse a shutdown, etc.
+ *   parallel    → handlers fire as hook listeners (Promise.allSettled);
+ *                 one failing doesn't affect others; errors are logged.
+ *   series      → handlers fire as chain steps in priority order;
+ *                 one throwing stops the chain.
+ *   series-bail → handlers fire as chain steps in priority order;
+ *                 returning `false` short-circuits (don't call next()).
+ *                 `fire()` returns false to signal "prevented".
  *
  * The bus lives in `@nwire/app` (the "managed Container with lifecycle"
  * layer). `@nwire/forge` re-exports the same surface so consumers that
  * pull from forge get one import line.
  */
+import { hook } from "@nwire/hooks";
 /**
  * The bus. Subscriptions and dispatch live here so an app's runtime stays
  * focused on the domain pipeline. Designed to be reusable — Studio, the
  * orchestrator, and external plugins all hit the same surface.
  */
-import { hook } from "@nwire/hooks";
 export class FrameworkEventBus {
-    subs = new Map();
     observers = [];
     logger;
     /**
-     * One hook per event name, lazily created on first `fire()`. Each hook has
-     * a single no-op chain step named "dispatch" so every fire emits start +
-     * end taps under `framework.event:<eventName>`. The dispatch logic in
-     * `fire()` is unchanged — these hooks are an observation surface so
-     * `listHooks()` + scan + Studio see every framework event in the
-     * registry, not a replacement for the existing dispatcher.
+     * One hook per event name. Each event's subscribers attach as chain
+     * steps (series / series-bail) or listeners (parallel) on its hook;
+     * dispatch is `hook.run()`. `listHooks()` + scan + Studio see every
+     * framework event in the registry by construction.
      *
      * Runtime can pass an `adoptHook` callback in the constructor; each
      * lazily-created hook is adopted so taps flow into the canonical
@@ -53,15 +53,12 @@ export class FrameworkEventBus {
             this.ensureEventHook(event.name);
         }
     }
-    /** Lazily create + adopt the per-event hook. Called from `fire()`. */
+    /** Lazily create + adopt the per-event hook. Bus dispatches through these. */
     ensureEventHook(eventName) {
         let h = this.eventHooks.get(eventName);
         if (h)
             return h;
         h = hook(`framework.event:${eventName}`);
-        h.use(async (_, next) => {
-            await next();
-        }, { name: "dispatch" });
         this.eventHooks.set(eventName, h);
         this.adoptHook?.(h);
         return h;
@@ -102,38 +99,54 @@ export class FrameworkEventBus {
      * series-bail / series modes (higher runs first; default 0). Framework
      * built-ins should subscribe at priority 100+; debug/observer plugins
      * at -100 so they see the final post-mutation state.
+     *
+     * Attaches to the per-event hook: as a listener (parallel mode) or as
+     * a chain step (series / series-bail). The returned handle calls
+     * `hook.off()` to detach.
      */
     on(event, handler, priority = 0) {
-        const list = this.subs.get(event.name) ?? [];
-        const sub = { handler, priority };
-        list.push(sub);
-        // Sort by priority desc so higher-priority handlers run first.
-        list.sort((a, b) => b.priority - a.priority);
-        this.subs.set(event.name, list);
-        return () => {
-            const current = this.subs.get(event.name);
-            if (!current)
+        const eventHook = this.ensureEventHook(event.name);
+        if (event.mode === "parallel") {
+            const listener = async (payload) => {
+                try {
+                    await handler(payload);
+                }
+                catch (err) {
+                    this.logger.error?.("framework-event handler threw (parallel)", {
+                        event: event.name,
+                        error: err?.message ?? String(err),
+                    });
+                }
+            };
+            eventHook.on(listener, { priority });
+            return () => eventHook.off(listener);
+        }
+        // series + series-bail both run as chain steps; series-bail returning
+        // false short-circuits by not calling next().
+        const step = async (ctx, next) => {
+            const result = await handler(ctx);
+            if (event.mode === "series-bail" && result === false) {
+                // Don't call next() — short-circuits the chain. fire() sees
+                // outcome === "prevented" via runDetailed.
                 return;
-            const i = current.indexOf(sub);
-            if (i >= 0)
-                current.splice(i, 1);
+            }
+            await next();
         };
+        eventHook.use(step, { priority });
+        return () => eventHook.off(step);
     }
     /**
      * Fire a framework event. Resolves to `false` when a series-bail handler
      * vetoed; `true` otherwise. The boolean is irrelevant for parallel /
-     * series modes and always returns `true` there for them.
+     * series modes and always returns `true` there.
+     *
+     * Internally: delegates to the per-event hook's `.run()` (parallel /
+     * series) or `.runDetailed()` (series-bail, to detect "prevented"
+     * outcome from short-circuit). The hook's observability surface (.tap,
+     * StepObservation) lights up automatically.
      */
     async fire(event, payload) {
-        const handlers = (this.subs.get(event.name) ?? []);
-        // Observation surface — emit start + end taps via the per-event hook.
-        // Cheap (one closure invocation per fire) and adds the event to
-        // `listHooks()` for scan + Studio + CLI visibility.
         const eventHook = this.ensureEventHook(event.name);
-        await eventHook.run(payload);
-        // Always notify observers — even when no subscribers exist for this
-        // event. The lifecycle is the signal worth recording; subscribers are
-        // an orthogonal concern (could be none in dev, several in prod).
         const ts = new Date().toISOString();
         const obsRec = (phase) => ({
             eventName: event.name,
@@ -142,50 +155,34 @@ export class FrameworkEventBus {
             phase,
             ts,
         });
-        if (handlers.length === 0) {
-            this.notify(obsRec("fired"));
-            return true;
-        }
-        switch (event.mode) {
-            case "parallel": {
-                const settled = await Promise.allSettled(handlers.map(({ handler }) => Promise.resolve().then(() => handler(payload))));
-                for (const r of settled) {
-                    if (r.status === "rejected") {
-                        this.logger.error?.("framework-event handler threw (parallel)", {
-                            event: event.name,
-                            error: r.reason?.message ?? String(r.reason),
-                        });
-                    }
-                }
-                this.notify(obsRec("fired"));
-                return true;
-            }
-            case "series": {
-                for (const { handler } of handlers) {
-                    await handler(payload);
-                }
-                this.notify(obsRec("fired"));
-                return true;
-            }
-            case "series-bail": {
-                for (const { handler } of handlers) {
-                    const result = await handler(payload);
-                    if (result === false) {
-                        this.logger.info?.("framework-event prevented by handler", {
-                            event: event.name,
-                        });
-                        this.notify(obsRec("prevented"));
-                        return false;
-                    }
-                }
-                this.notify(obsRec("fired"));
-                return true;
+        if (event.mode === "series-bail") {
+            const result = await eventHook.runDetailed(payload);
+            const fired = result.outcome === "completed";
+            if (!fired) {
+                this.logger.info?.("framework-event prevented by handler", {
+                    event: event.name,
+                });
             }
+            this.notify(obsRec(fired ? "fired" : "prevented"));
+            return fired;
         }
+        // parallel + series: hook.run handles dispatch; listener errors in
+        // parallel mode are swallowed by the listener wrapper in on(); chain
+        // errors in series mode propagate (matches old behaviour).
+        await eventHook.run(payload);
+        this.notify(obsRec("fired"));
+        return true;
     }
-    /** Count subscribers for an event — diagnostic surface (Studio, tests). */
+    /**
+     * Count subscribers for an event — diagnostic surface (Studio, tests).
+     * Sums chain steps and listeners attached to the per-event hook.
+     */
     subscriberCount(event) {
-        return this.subs.get(event.name)?.length ?? 0;
+        const h = this.eventHooks.get(event.name);
+        if (!h)
+            return 0;
+        const counts = h.stepCounts();
+        return counts.chain + counts.listeners;
     }
 }
 //# sourceMappingURL=framework-event-bus.js.map

package/dist/framework-event-bus.js.map

@@ -1 +1 @@
-{"version":3,"file":"framework-event-bus.js","sourceRoot":"","sources":["../src/framework-event-bus.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"framework-event-bus.js","sourceRoot":"","sources":["../src/framework-event-bus.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Runtime — generic dispatch + observation substrate.
+ *
+ * The "app" half of the runtime: a managed Container, a hooks-backed
+ * dispatch chain, a framework-event bus, and a canonical telemetry stream.
+ * Domain engines (`@nwire/forge.Runtime`) extend this class and layer their
+ * own registries (actors, workflows, projections, queries, event store)
+ * on top.
+ *
+ * What this class owns:
+ *   - A Container (default `createContainer()`).
+ *   - The `runtime.dispatch` hook from `@nwire/hooks` — middleware substrate
+ *     for any sub-class's per-action pipeline. Subclasses register the
+ *     pinned innermost step that calls their handler; this base only owns
+ *     the hook itself, the user-middleware adapter, and the tap into the
+ *     telemetry stream.
+ *   - The `FrameworkEventBus` — lifecycle events (`AppBooting`,
+ *     `PluginRegistered`, …). Subclasses add per-action / per-actor events
+ *     by registering more event definitions.
+ *   - `onTelemetry` / `offTelemetry` / `emit` — the canonical observation
+ *     stream every consumer (dev logger, Studio Live SSE, OTel exporter)
+ *     listens on. Subclasses widen the `Telemetry` union with their own
+ *     domain kinds (e.g. `action.dispatched`, `actor.transitioned`) and
+ *     call `this.emit(record)` to push them through the same channel.
+ */
+import { type Container } from "@nwire/container";
+import { type Hook } from "@nwire/hooks";
+import { type Logger } from "@nwire/logger";
+import { FrameworkEventBus, type FrameworkEventHandler } from "./framework-event-bus.js";
+import type { FrameworkEventDefinition } from "./framework-events.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;
+}
+/**
+ * `lifecycle` — one record per framework-event firing on the bus. The
+ * runtime bridges every fire into the telemetry stream so dev logger,
+ * Studio Live, and OTel exporter all see lifecycle activity through the
+ * same channel as domain events. `phase: "prevented"` flags series-bail
+ * handlers that vetoed.
+ */
+export interface LifecycleTelemetry {
+    readonly kind: "lifecycle";
+    readonly event: string;
+    readonly namespace: string;
+    readonly payload: unknown;
+    readonly phase: "fired" | "prevented";
+    readonly appName: string;
+    readonly ts: string;
+}
+/**
+ * Base `Telemetry` union — generic kinds only. Subclasses (forge) WIDEN
+ * this with their own domain kinds (`action.dispatched`, `event.published`,
+ * `actor.transitioned`, …) 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 | LifecycleTelemetry;
+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;
+    /**
+     * Framework events to pre-create hooks for. The bus also lazily creates
+     * a hook the first time `bus.on(Event, …)` or `bus.fire(Event, …)` runs
+     * — but eager creation surfaces every known event in `listHooks()` +
+     * scan + Studio before any subscription has happened.
+     */
+    readonly events?: readonly FrameworkEventDefinition<unknown>[];
+}
+export declare class Runtime {
+    protected readonly container: Container;
+    protected readonly logger: Logger;
+    readonly appName: string;
+    /**
+     * 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;
+    readonly frameworkEvents: FrameworkEventBus;
+    private readonly telemetryListeners;
+    constructor(options?: RuntimeOptions);
+    /**
+     * Subscribe to a framework event. Sugar over `runtime.frameworkEvents.on`
+     * so plugins can write `runtime.onFramework(ActionDispatching, ...)`.
+     * Returns an unsubscribe function.
+     */
+    onFramework<TPayload>(event: FrameworkEventDefinition<TPayload>, handler: FrameworkEventHandler<TPayload>, priority?: number): () => void;
+    /**
+     * 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 per-plugin / per-module lifecycle
+     * hook; plugin authors can call it on their own hooks if they want their
+     * extension points surfaced in Studio / dev-logger / OTel for free.
+     */
+    adoptHook<TCtx>(hook: 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)`.
+     */
+    protected emit(record: unknown): void;
+    getContainer(): Container;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}