@nwire/app 0.8.17 → 0.9.1

package/dist/runtime.js

@@ -0,0 +1,197 @@
+/**
+ * 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 { createContainer } from "@nwire/container";
+import { hook } from "@nwire/hooks";
+import { NoopLogger } from "@nwire/logger";
+import { FrameworkEventBus } from "./framework-event-bus.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;
+    /**
+     * 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;
+    frameworkEvents;
+    telemetryListeners = [];
+    constructor(options = {}) {
+        this.container = options.container ?? createContainer();
+        this.logger = options.logger ?? new NoopLogger();
+        this.appName = options.appName ?? "app";
+        this.frameworkEvents = new FrameworkEventBus(this.logger, {
+            adoptHook: (h) => this.adoptHook(h),
+            events: options.events ?? [],
+        });
+        // Bridge framework-event firings into the telemetry stream so every
+        // existing telemetry consumer (dev logger, Studio Live SSE, OTel
+        // exporter) sees lifecycle activity through the same channel as
+        // domain events. `namespace` = the second dotted segment so dev
+        // logger / Studio can group by phase (app / plugin / wire / …).
+        this.frameworkEvents.onFire((rec) => {
+            const parts = rec.eventName.split(".");
+            const namespace = parts.length >= 2 ? parts[1] : "framework";
+            this.emit({
+                kind: "lifecycle",
+                event: rec.eventName,
+                namespace,
+                payload: rec.payload,
+                phase: rec.phase,
+                appName: this.appName,
+                ts: rec.ts,
+            });
+        });
+        this.dispatchHook = hook("runtime.dispatch");
+        this.dispatchHook.tap((obs) => {
+            this.emit({
+                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 a framework event. Sugar over `runtime.frameworkEvents.on`
+     * so plugins can write `runtime.onFramework(ActionDispatching, ...)`.
+     * Returns an unsubscribe function.
+     */
+    onFramework(event, handler, priority = 0) {
+        return this.frameworkEvents.on(event, handler, priority);
+    }
+    /**
+     * 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 });
+    }
+    /**
+     * 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(hook) {
+        hook.tap((obs) => {
+            this.emit({
+                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)`.
+     */
+    emit(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;
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nwire/app",
-  "version": "0.8.17",
-  "description": "Nwire — managed Container with plugin lifecycle, framework events, and DI hooks. The 'app' in the sealed architecture: composes modules + plugins, boots in order, exposes a Container, fires framework events at every lifecycle transition. Phase 69 extraction in progress; currently ships the framework events + bus.",
+  "version": "0.9.1",
+  "description": "Nwire — managed Container with plugin lifecycle, framework events, and DI hooks. Composes modules + plugins, boots in order, exposes a Container, fires framework events at every lifecycle transition.",
   "keywords": [
     "app",
     "container",
@@ -29,10 +29,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@nwire/container": "0.8.17",
-    "@nwire/hooks": "0.8.17",
-    "@nwire/logger": "0.8.17",
-    "@nwire/messages": "0.8.17"
+    "@nwire/logger": "0.9.1",
+    "@nwire/hooks": "0.9.1",
+    "@nwire/container": "0.9.1",
+    "@nwire/messages": "0.9.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",