@nwire/app 0.12.0 → 0.13.0

package/dist/app-hooks.d.ts

@@ -0,0 +1,96 @@
+/**
+ * App / plugin LIFECYCLE hook registry — an App concern.
+ *
+ * The Runtime is the dispatch substrate; it does not know about plugins or a
+ * boot/shutdown lifecycle. The App owns that, so the lifecycle slots
+ * (`App*` / `Plugin*`) live here, on a per-App `AppHooks` registry that
+ * `AppLifecycle` fires from. Each slot is a `Hook<TPayload>` accessed as a
+ * typed property on the registry.
+ *
+ * The slots are declared by augmenting the `AppHooks` interface exported from
+ * `@nwire/runtime` (the same forward-declaration pattern forge uses for the
+ * runtime's `FrameworkHooks`), so `PluginContext.on` / `PluginContext.defineHook`
+ * stay typed against them.
+ *
+ * Lifecycle hooks still emit `hook.step` telemetry: `AppLifecycle` wires every
+ * slot through `runtime.observe(...)`, the same tap the runtime's own hooks use,
+ * so Studio's plugin live-tap (`hook.step`) keeps working.
+ */
+import { type Hook } from "@nwire/hooks";
+import type { PluginKind } from "@nwire/runtime";
+declare module "@nwire/runtime" {
+    interface AppHooks {
+        AppRegistering: Hook<{
+            readonly appName: string;
+        }>;
+        AppBooting: Hook<{
+            readonly appName: string;
+        }>;
+        AppBooted: Hook<{
+            readonly appName: string;
+            readonly bootedAt: string;
+        }>;
+        AppReady: Hook<{
+            readonly appName: string;
+            readonly readyAt: string;
+        }>;
+        AppShuttingDown: Hook<{
+            readonly appName: string;
+            readonly reason?: string;
+        }>;
+        AppShutdown: Hook<{
+            readonly appName: string;
+        }>;
+        PluginRegistered: Hook<{
+            readonly appName: string;
+            readonly pluginName: string;
+            readonly kind?: PluginKind;
+        }>;
+        PluginBooting: Hook<{
+            readonly appName: string;
+            readonly pluginName: string;
+            readonly kind?: PluginKind;
+        }>;
+        PluginBooted: Hook<{
+            readonly appName: string;
+            readonly pluginName: string;
+            readonly durationMs: number;
+            readonly kind?: PluginKind;
+        }>;
+        PluginShuttingDown: Hook<{
+            readonly appName: string;
+            readonly pluginName: string;
+            readonly kind?: PluginKind;
+        }>;
+        PluginShutdown: Hook<{
+            readonly appName: string;
+            readonly pluginName: string;
+            readonly durationMs: number;
+            readonly kind?: PluginKind;
+        }>;
+    }
+}
+export type { AppHooks } from "@nwire/runtime";
+/** Canonical names for the built-in lifecycle slots — labels the underlying Hooks. */
+declare const BUILT_IN_APP_HOOK_NAMES: {
+    readonly AppRegistering: "nwire.app.registering";
+    readonly AppBooting: "nwire.app.booting";
+    readonly AppBooted: "nwire.app.booted";
+    readonly AppReady: "nwire.app.ready";
+    readonly AppShuttingDown: "nwire.app.shutting-down";
+    readonly AppShutdown: "nwire.app.shutdown";
+    readonly PluginRegistered: "nwire.plugin.registered";
+    readonly PluginBooting: "nwire.plugin.booting";
+    readonly PluginBooted: "nwire.plugin.booted";
+    readonly PluginShuttingDown: "nwire.plugin.shutting-down";
+    readonly PluginShutdown: "nwire.plugin.shutdown";
+};
+export type AppHookSlot = keyof typeof BUILT_IN_APP_HOOK_NAMES;
+/**
+ * Construct a per-App lifecycle registry with every built-in slot
+ * pre-instantiated. Plugin-defined lifecycle slots added via
+ * `ctx.defineHook(name)` land on the same registry instance.
+ */
+export declare function createAppHooks(): import("@nwire/runtime").AppHooks;
+/** True if `slot` is one of the built-in app lifecycle hook keys. */
+export declare function isAppHook(slot: string): slot is AppHookSlot;

package/dist/app-hooks.js

@@ -0,0 +1,49 @@
+/**
+ * App / plugin LIFECYCLE hook registry — an App concern.
+ *
+ * The Runtime is the dispatch substrate; it does not know about plugins or a
+ * boot/shutdown lifecycle. The App owns that, so the lifecycle slots
+ * (`App*` / `Plugin*`) live here, on a per-App `AppHooks` registry that
+ * `AppLifecycle` fires from. Each slot is a `Hook<TPayload>` accessed as a
+ * typed property on the registry.
+ *
+ * The slots are declared by augmenting the `AppHooks` interface exported from
+ * `@nwire/runtime` (the same forward-declaration pattern forge uses for the
+ * runtime's `FrameworkHooks`), so `PluginContext.on` / `PluginContext.defineHook`
+ * stay typed against them.
+ *
+ * Lifecycle hooks still emit `hook.step` telemetry: `AppLifecycle` wires every
+ * slot through `runtime.observe(...)`, the same tap the runtime's own hooks use,
+ * so Studio's plugin live-tap (`hook.step`) keeps working.
+ */
+import { hook } from "@nwire/hooks";
+/** Canonical names for the built-in lifecycle slots — labels the underlying Hooks. */
+const BUILT_IN_APP_HOOK_NAMES = {
+    AppRegistering: "nwire.app.registering",
+    AppBooting: "nwire.app.booting",
+    AppBooted: "nwire.app.booted",
+    AppReady: "nwire.app.ready",
+    AppShuttingDown: "nwire.app.shutting-down",
+    AppShutdown: "nwire.app.shutdown",
+    PluginRegistered: "nwire.plugin.registered",
+    PluginBooting: "nwire.plugin.booting",
+    PluginBooted: "nwire.plugin.booted",
+    PluginShuttingDown: "nwire.plugin.shutting-down",
+    PluginShutdown: "nwire.plugin.shutdown",
+};
+/**
+ * Construct a per-App lifecycle registry with every built-in slot
+ * pre-instantiated. Plugin-defined lifecycle slots added via
+ * `ctx.defineHook(name)` land on the same registry instance.
+ */
+export function createAppHooks() {
+    const registry = {};
+    for (const [slot, name] of Object.entries(BUILT_IN_APP_HOOK_NAMES)) {
+        registry[slot] = hook(name);
+    }
+    return registry;
+}
+/** True if `slot` is one of the built-in app lifecycle hook keys. */
+export function isAppHook(slot) {
+    return slot in BUILT_IN_APP_HOOK_NAMES;
+}

package/dist/app.d.ts

@@ -4,11 +4,13 @@
  * capability set. `createRuntime` exposes the raw substrate for cases that
  * need the dispatch core without the App layer on top.
  */
-export { Runtime, createRuntime, serializeError, type DispatchHookCtx, type DispatchMiddleware, type HookStepTelemetry, type RuntimeOptions, type SerializedError, type Telemetry, type TelemetryListener, type FrameworkHooks, type PluginKind, type PluginDefinition, type PluginContext, } from "./runtime/index.js";
+export { Runtime, createRuntime, serializeError, messageRef, type MessageRef, type DispatchHookCtx, type DispatchMiddleware, type HookStepTelemetry, type RuntimeOptions, type SerializedError, type Telemetry, type TelemetryListener, type FrameworkHooks, type PluginKind, type PluginDefinition, type PluginContext, } from "./runtime/index.js";
+export { createAppHooks, isAppHook, type AppHooks, type AppHookSlot } from "./app-hooks.js";
 export { definePlugin, isPlugin } from "./define-plugin.js";
 export { createApp, type App, type CreateAppOptions } from "./create-app.js";
+export type { PluginContributions } from "./lifecycle.js";
 export { appCompose, containerOf, type AppComposeOptions, type CollisionPolicy, } from "./compose-app.js";
 export { subscribe, isSubscription, type Subscription, type WhenFn } from "./subscribe.js";
 export { publishCapability, publishPlugin, type PublishCaps } from "./publish.js";
-export { defineCapability, type Capability, type CapabilityBase, type OutboundStage, type StagePosition, type StageContext, } from "@nwire/runtime";
+export { defineCapability, type Capability, type CapabilityBase, type OutboundStage, type StagePosition, type StageContext, installTelemetryReporter, type TelemetryReporter, } from "@nwire/runtime";
 export type { HandlerBaseCtx, Ctx } from "@nwire/handler";

package/dist/app.js

@@ -4,7 +4,11 @@
  * capability set. `createRuntime` exposes the raw substrate for cases that
  * need the dispatch core without the App layer on top.
  */
-export { Runtime, createRuntime, serializeError, } from "./runtime/index.js";
+export { Runtime, createRuntime, serializeError, messageRef, } from "./runtime/index.js";
+// App / plugin lifecycle hook registry — App-owned (the runtime has no
+// lifecycle). Importing this module also applies the `AppHooks` augmentation
+// that declares the App* / Plugin* slots.
+export { createAppHooks, isAppHook } from "./app-hooks.js";
 export { definePlugin, isPlugin } from "./define-plugin.js";
 export { createApp } from "./create-app.js";
 export { appCompose, containerOf, } from "./compose-app.js";
@@ -17,4 +21,4 @@ export { subscribe, isSubscription } from "./subscribe.js";
 export { publishCapability, publishPlugin } from "./publish.js";
 // Capability + sink primitives — re-exported from @nwire/runtime so the
 // App surface presents a single import surface.
-export { defineCapability, } from "@nwire/runtime";
+export { defineCapability, installTelemetryReporter, } from "@nwire/runtime";

package/dist/compose-app.js

@@ -90,8 +90,10 @@ export function appCompose(...args) {
         },
         container: head.container,
         runtime: head.runtime,
+        appHooks: head.appHooks,
         interface: mergedInterface,
         plugins: apps.flatMap((a) => a.plugins),
+        pluginContributions: () => apps.flatMap((a) => a.pluginContributions()),
         with(plugin) {
             // Composites install through the head app — multi-runtime install is
             // out of scope. The composite's runtime is the head's runtime, so

package/dist/create-app.d.ts

@@ -21,8 +21,9 @@ import { type Container } from "@nwire/container/awilix";
 import { type Logger } from "@nwire/logger";
 import { type Binding, type HandlerDef, type Interface, type WireCtxBuilder } from "@nwire/wires";
 import type { EventDefinition, EventPayload } from "@nwire/messages";
-import type { ListenerContext } from "@nwire/runtime";
+import type { AppHooks, ListenerContext } from "@nwire/runtime";
 import { type PluginDefinition, type Runtime } from "./runtime/index.js";
+import { type PluginContributions } from "./lifecycle.js";
 import { type Subscription } from "./subscribe.js";
 export interface CreateAppOptions {
     /** App name — surfaces in framework-hook payloads + dev logger output. */
@@ -60,6 +61,13 @@ export interface App<TCaps = {}> {
     readonly name: string;
     readonly container: Container;
     readonly runtime: Runtime;
+    /**
+     * App / plugin lifecycle hook registry (`App*` / `Plugin*` slots). Owned by
+     * the App, not the runtime — the runtime is a stateless dispatch substrate.
+     * Plugins observe lifecycle via `ctx.on(...)`; advanced callers can `.use()`
+     * a chain step (e.g. veto shutdown) directly on these slots.
+     */
+    readonly appHooks: AppHooks;
     /**
      * Wire collection — the same shape as `createInterface()` standalone.
      * Adopters consume `app.interface.forAdapter(kind)`; foundation-form
@@ -67,6 +75,13 @@ export interface App<TCaps = {}> {
      */
     readonly interface: Interface;
     readonly plugins: readonly PluginDefinition[];
+    /**
+     * Per-plugin contribution attribution captured at boot — which DI bindings,
+     * capabilities, stages, handlers, and hooks each plugin added. Empty until
+     * the plugin phases have run. Read by `captureTopology` to emit the
+     * `contributes` graph edge (Studio's Plugins page).
+     */
+    pluginContributions(): readonly PluginContributions[];
     /** Phantom marker — never read at runtime. */
     readonly __caps?: TCaps;
     /**

package/dist/create-app.js

@@ -20,6 +20,7 @@
 import { createContainer } from "@nwire/container/awilix";
 import { NoopLogger } from "@nwire/logger";
 import { createInterface, } from "@nwire/wires";
+import { autoInstallFileReporter, installTopologyEmit } from "@nwire/telemetry";
 import { createRuntime } from "./runtime/index.js";
 import { AppLifecycle } from "./lifecycle.js";
 import { isSubscription } from "./subscribe.js";
@@ -42,6 +43,15 @@ export function createApp(options) {
     for (const p of plugins) {
         lifecycle.enqueue(p);
     }
+    // Dev telemetry persistence — userland-unaware. When the process runs inside
+    // a project (a `.nwire` dir or `NWIRE_CWD` set), install the local file
+    // reporter so every run lands in `.nwire/telemetry/*.jsonl` for Studio
+    // history. No-op in unit tests / library imports (no project cwd). The
+    // detach runs at shutdown so the stream closes cleanly.
+    const detachTelemetry = autoInstallFileReporter(runtime);
+    if (detachTelemetry) {
+        lifecycle.appHooks.AppShutdown.on(() => detachTelemetry());
+    }
     const app = {
         $nwireApp: true,
         $kind: "app",
@@ -49,8 +59,10 @@ export function createApp(options) {
         name: appName,
         container,
         runtime,
+        appHooks: lifecycle.appHooks,
         interface: iface,
         plugins,
+        pluginContributions: () => lifecycle.pluginContributions(),
         get state() {
             return lifecycle.currentState;
         },
@@ -99,13 +111,20 @@ export function createApp(options) {
         boot: (appConfig) => app.start(appConfig),
         shutdown: () => lifecycle.stop(),
         dispatchFrameworkEvent: async (slot, payload) => {
-            const hooks = runtime.hooks;
-            const h = hooks[slot];
+            const appReg = lifecycle.appHooks;
+            const rtReg = runtime.hooks;
+            const h = appReg[slot] ?? rtReg[slot];
             if (!h)
                 return true;
             const result = await h.runDetailed(payload);
             return result.outcome === "completed";
         },
     };
+    // Topology self-emit — userland-unaware, same project-cwd gate as the
+    // telemetry auto-install. When the app boots inside a project, it captures its
+    // own runtime wiring on `AppReady` and writes `.nwire/topology.json` so the
+    // static scanner can fold it in without booting the app itself. The file is
+    // removed on shutdown. No-op in unit tests / library imports (no project cwd).
+    installTopologyEmit(app);
     return app;
 }

package/dist/define-plugin.d.ts

@@ -18,7 +18,6 @@
  * Both produce a `PluginDefinition<TOptions, TMark>` that the Runtime's
  * `registerPlugin` runs as register-then-setup.
  */
-import { type SourceLocation } from "@nwire/messages";
 import type { PluginContext, PluginDefinition } from "./runtime/index.js";
 /** Body for the object call form. */
 export interface DefinePluginBody<TOptions = void, TMark = unknown> {
@@ -28,12 +27,8 @@ export interface DefinePluginBody<TOptions = void, TMark = unknown> {
     readonly __mark?: TMark;
 }
 /** Single-phase form — receives a setup closure directly. */
-export declare function definePlugin(name: string, setup: (ctx: PluginContext) => void): PluginDefinition & {
-    readonly $source?: SourceLocation;
-};
+export declare function definePlugin(name: string, setup: (ctx: PluginContext) => void): PluginDefinition;
 /** Two-phase form — accepts options + register + setup as a body object. */
-export declare function definePlugin<TMark = unknown, TOptions = void>(name: string, body: DefinePluginBody<TOptions, TMark>): PluginDefinition<TOptions, TMark> & {
-    readonly $source?: SourceLocation;
-};
+export declare function definePlugin<TMark = unknown, TOptions = void>(name: string, body: DefinePluginBody<TOptions, TMark>): PluginDefinition<TOptions, TMark>;
 /** Discriminator for runtime-side checks. */
 export declare function isPlugin(x: unknown): x is PluginDefinition;

package/dist/define-plugin.js

@@ -18,12 +18,10 @@
  * Both produce a `PluginDefinition<TOptions, TMark>` that the Runtime's
  * `registerPlugin` runs as register-then-setup.
  */
-import { captureSourceLocation } from "@nwire/messages";
 // ─── Implementation ───────────────────────────────────────────────────────
 export function definePlugin(name, setupOrBody) {
-    const $source = captureSourceLocation();
     if (typeof setupOrBody === "function") {
-        return { name, setup: setupOrBody, $source };
+        return { name, setup: setupOrBody };
     }
     return {
         name,
@@ -31,7 +29,6 @@ export function definePlugin(name, setupOrBody) {
         register: setupOrBody.register,
         setup: setupOrBody.setup,
         __mark: setupOrBody.__mark,
-        $source,
     };
 }
 /** Discriminator for runtime-side checks. */

package/dist/lifecycle.d.ts

@@ -8,7 +8,23 @@
  * App composes the Runtime with this orchestrator to get plugin lifecycle.
  */
 import type { Container } from "@nwire/container";
-import type { PluginDefinition, Runtime } from "@nwire/runtime";
+import type { AppHooks, PluginDefinition, Runtime } from "@nwire/runtime";
+/**
+ * What a plugin contributed to the app during its register + setup phases:
+ * DI bindings, capabilities, source/sink stages, registered handlers, and
+ * lifecycle hooks. Captured by diffing the runtime + global hook registry
+ * around each plugin's phase, so Studio can attribute every topology entry to
+ * the plugin that added it (the `contributes` graph edge).
+ */
+export interface PluginContributions {
+    readonly plugin: string;
+    readonly bindings: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly sourceStages: readonly string[];
+    readonly sinkStages: readonly string[];
+    readonly handlers: readonly string[];
+    readonly hooks: readonly string[];
+}
 /** Lifecycle state. */
 export type LifecycleState = "idle" | "starting" | "running" | "stopping" | "stopped";
 export interface AppLifecycleOptions {
@@ -23,16 +39,27 @@ export declare class AppLifecycle {
     private readonly appName;
     private readonly container;
     private readonly runtime;
+    /**
+     * App / plugin lifecycle hook registry. Owned by the App, not the runtime —
+     * the runtime has no lifecycle. Wired through `runtime.observe(...)` so each
+     * slot emits `hook.step` telemetry exactly like the runtime's own hooks
+     * (Studio's plugin live-tap consumes these).
+     */
+    private readonly hooks;
     /** Plugins enqueued via `enqueue` whose phases haven't run yet. */
     private readonly pendingPlugins;
     /** Plugins whose register + setup have run. Ordered by registration. */
     private readonly plugins;
+    /** What each plugin contributed, captured during `runPluginPhases`. */
+    private readonly contributions;
     private state;
     private startPromise;
     private stopPromise;
     constructor(opts: AppLifecycleOptions);
     /** Current lifecycle phase. */
     get currentState(): LifecycleState;
+    /** The app's lifecycle hook registry (App* / Plugin* slots). */
+    get appHooks(): AppHooks;
     /** Names of every plugin queued or registered, in registration order. */
     pluginNames(): readonly string[];
     /**
@@ -47,6 +74,17 @@ export declare class AppLifecycle {
      * idempotent (no-op once the queue is empty).
      */
     runPluginPhases(): void;
+    /** A snapshot of the app's current registered surface — for contribution diffs. */
+    private snapshot;
+    /** Global hook registry names — best-effort (tolerate an absent registry). */
+    private hookNames;
+    /**
+     * Fold the surface added since `before` into the named plugin's contribution
+     * record, merging across the register + setup phases.
+     */
+    private recordContribution;
+    /** Per-plugin contribution attribution — read by `captureTopology`. */
+    pluginContributions(): readonly PluginContributions[];
     /**
      * Boot the app:
      *
@@ -76,4 +114,10 @@ export declare class AppLifecycle {
     stop(reason?: string): Promise<void>;
     /** Build the plugin context — same shape across register and setup. */
     private buildPluginContext;
+    /**
+     * Materialise a plugin-defined slot on the app lifecycle registry.
+     * Idempotent; the new slot is observed for `hook.step` telemetry like the
+     * built-in ones. Mirrors `Runtime.defineHook` but for app hooks.
+     */
+    private defineAppHook;
 }

package/dist/lifecycle.js

@@ -7,6 +7,8 @@
  * events, middleware, telemetry). It does not know about plugins. The
  * App composes the Runtime with this orchestrator to get plugin lifecycle.
  */
+import { hook as hookFactory, listHooks } from "@nwire/hooks";
+import { createAppHooks } from "./app-hooks.js";
 /**
  * The orchestrator. Each App owns one of these.
  */
@@ -14,10 +16,19 @@ export class AppLifecycle {
     appName;
     container;
     runtime;
+    /**
+     * App / plugin lifecycle hook registry. Owned by the App, not the runtime —
+     * the runtime has no lifecycle. Wired through `runtime.observe(...)` so each
+     * slot emits `hook.step` telemetry exactly like the runtime's own hooks
+     * (Studio's plugin live-tap consumes these).
+     */
+    hooks = createAppHooks();
     /** Plugins enqueued via `enqueue` whose phases haven't run yet. */
     pendingPlugins = [];
     /** Plugins whose register + setup have run. Ordered by registration. */
     plugins = [];
+    /** What each plugin contributed, captured during `runPluginPhases`. */
+    contributions = [];
     state = "idle";
     startPromise;
     stopPromise;
@@ -25,11 +36,21 @@ export class AppLifecycle {
         this.appName = opts.appName;
         this.container = opts.container;
         this.runtime = opts.runtime;
+        // Route every lifecycle hook's step telemetry through the runtime's
+        // canonical stream — same tap the runtime's own hooks use — so the
+        // `hook.step` records Studio's plugin live-tap relies on keep flowing.
+        for (const h of Object.values(this.hooks)) {
+            this.runtime.observe(h);
+        }
     }
     /** Current lifecycle phase. */
     get currentState() {
         return this.state;
     }
+    /** The app's lifecycle hook registry (App* / Plugin* slots). */
+    get appHooks() {
+        return this.hooks;
+    }
     /** Names of every plugin queued or registered, in registration order. */
     pluginNames() {
         return [...this.plugins.map((p) => p.name), ...this.pendingPlugins.map((p) => p.def.name)];
@@ -66,17 +87,85 @@ export class AppLifecycle {
             const ctx = this.buildPluginContext(p.def, boots, disposes);
             return { def: p.def, ctx, boots, disposes };
         });
+        // Attribute every binding/capability/stage/handler/hook a plugin adds by
+        // diffing the runtime + hook registry around each of its phases. Snapshot
+        // immediately before each call so the diff is that one plugin's delta —
+        // even though all registers run before all setups.
         for (const p of prepared) {
-            if (p.def.register)
+            if (p.def.register) {
+                const before = this.snapshot();
                 p.def.register(p.ctx);
+                this.recordContribution(p.def.name, before);
+            }
         }
         for (const p of prepared) {
+            const before = this.snapshot();
             p.def.setup(p.ctx);
+            this.recordContribution(p.def.name, before);
         }
         for (const p of prepared) {
             this.plugins.push({ name: p.def.name, boots: p.boots, disposes: p.disposes });
         }
     }
+    /** A snapshot of the app's current registered surface — for contribution diffs. */
+    snapshot() {
+        const rt = this.runtime;
+        const names = (xs, key) => new Set((xs ?? []).map(key));
+        return {
+            bindings: names(this.container.list?.(), (b) => b.name),
+            capabilities: new Set(rt.listCapabilities?.() ?? []),
+            sourceStages: names(rt.listSourceStages?.(), (s) => s.name),
+            sinkStages: names(rt.listSinkStages?.(), (s) => s.name),
+            handlers: new Set(rt.listHandlers?.() ?? []),
+            hooks: this.hookNames(),
+        };
+    }
+    /** Global hook registry names — best-effort (tolerate an absent registry). */
+    hookNames() {
+        try {
+            return new Set(listHooks().map((h) => h.name));
+        }
+        catch {
+            return new Set();
+        }
+    }
+    /**
+     * Fold the surface added since `before` into the named plugin's contribution
+     * record, merging across the register + setup phases.
+     */
+    recordContribution(plugin, before) {
+        const after = this.snapshot();
+        const added = (a, b) => [...b].filter((x) => !a.has(x));
+        const delta = {
+            plugin,
+            bindings: added(before.bindings, after.bindings),
+            capabilities: added(before.capabilities, after.capabilities),
+            sourceStages: added(before.sourceStages, after.sourceStages),
+            sinkStages: added(before.sinkStages, after.sinkStages),
+            handlers: added(before.handlers, after.handlers),
+            hooks: added(before.hooks, after.hooks),
+        };
+        const existing = this.contributions.find((c) => c.plugin === plugin);
+        if (!existing) {
+            this.contributions.push(delta);
+            return;
+        }
+        const merge = (a, b) => [
+            ...new Set([...a, ...b]),
+        ];
+        Object.assign(existing, {
+            bindings: merge(existing.bindings, delta.bindings),
+            capabilities: merge(existing.capabilities, delta.capabilities),
+            sourceStages: merge(existing.sourceStages, delta.sourceStages),
+            sinkStages: merge(existing.sinkStages, delta.sinkStages),
+            handlers: merge(existing.handlers, delta.handlers),
+            hooks: merge(existing.hooks, delta.hooks),
+        });
+    }
+    /** Per-plugin contribution attribution — read by `captureTopology`. */
+    pluginContributions() {
+        return this.contributions;
+    }
     /**
      * Boot the app:
      *
@@ -100,7 +189,7 @@ export class AppLifecycle {
         }
         this.state = "starting";
         const appName = this.appName;
-        const hooks = this.runtime.hooks;
+        const hooks = this.hooks;
         this.startPromise = (async () => {
             try {
                 this.runPluginPhases();
@@ -183,7 +272,7 @@ export class AppLifecycle {
         }
         this.state = "stopping";
         const appName = this.appName;
-        const hooks = this.runtime.hooks;
+        const hooks = this.hooks;
         this.stopPromise = (async () => {
             const errors = [];
             const shuttingDown = await hooks.AppShuttingDown.runDetailed({ appName, reason });
@@ -250,17 +339,11 @@ export class AppLifecycle {
             bind: (name, factory, opts) => {
                 this.container.register(name, factory, opts);
             },
-            add: (cap) => {
-                this.runtime.add(cap);
-            },
-            sink: (stage) => {
-                this.runtime.sink(stage);
-            },
             on: (name, fn) => {
-                const reg = this.runtime.hooks;
+                const reg = this.hooks;
                 const h = reg[name];
                 if (!h) {
-                    throw new Error(`PluginContext.on: framework hook "${String(name)}" does not exist — call defineHook first if it's a plugin-defined slot.`);
+                    throw new Error(`PluginContext.on: app lifecycle hook "${String(name)}" does not exist — call defineHook first if it's a plugin-defined slot.`);
                 }
                 h.on(fn);
             },
@@ -273,7 +356,22 @@ export class AppLifecycle {
             shutdown: (fn) => {
                 disposes.push(fn);
             },
-            defineHook: (name) => this.runtime.defineHook(name),
+            defineHook: (name) => this.defineAppHook(name),
         };
     }
+    /**
+     * Materialise a plugin-defined slot on the app lifecycle registry.
+     * Idempotent; the new slot is observed for `hook.step` telemetry like the
+     * built-in ones. Mirrors `Runtime.defineHook` but for app hooks.
+     */
+    defineAppHook(name) {
+        const reg = this.hooks;
+        const existing = reg[name];
+        if (existing)
+            return existing;
+        const h = hookFactory(`nwire.${name}`);
+        reg[name] = h;
+        this.runtime.observe(h);
+        return h;
+    }
 }

package/dist/publish.js

@@ -54,8 +54,8 @@ export const publishCapability = defineCapability({
  */
 export function publishPlugin() {
     return definePlugin("publish", {
-        setup: ({ add }) => {
-            add(publishCapability);
+        setup: ({ runtime }) => {
+            runtime.add(publishCapability);
         },
     });
 }

package/dist/runtime/index.d.ts

@@ -5,5 +5,5 @@
  * Re-exports the canonical Runtime surface from `@nwire/runtime` so
  * `@nwire/app` consumers can import everything from a single package.
  */
-export { Runtime, createRuntime, isBuiltInHook, serializeError, type RuntimeOptions, type Telemetry, type TelemetryListener, type HookStepTelemetry, type DispatchHookCtx, type DispatchMiddleware, type SerializedError, type PluginDefinition, type PluginContext, } from "@nwire/runtime";
+export { Runtime, createRuntime, isBuiltInHook, serializeError, messageRef, type MessageRef, type RuntimeOptions, type Telemetry, type TelemetryListener, type HookStepTelemetry, type DispatchHookCtx, type DispatchMiddleware, type SerializedError, type PluginDefinition, type PluginContext, } from "@nwire/runtime";
 export { createFrameworkHooks, type FrameworkHooks, type PluginKind } from "@nwire/runtime";

package/dist/runtime/index.js

@@ -5,5 +5,5 @@
  * Re-exports the canonical Runtime surface from `@nwire/runtime` so
  * `@nwire/app` consumers can import everything from a single package.
  */
-export { Runtime, createRuntime, isBuiltInHook, serializeError, } from "@nwire/runtime";
+export { Runtime, createRuntime, isBuiltInHook, serializeError, messageRef, } from "@nwire/runtime";
 export { createFrameworkHooks } from "@nwire/runtime";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nwire/app",
-  "version": "0.12.0",
-  "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.",
+  "version": "0.13.0",
+  "description": "Nwire — managed Container with plugin lifecycle, framework hooks, and DI. Composes apps + plugins, boots in order, exposes a Container, fires framework hooks at every lifecycle transition.",
   "keywords": [
     "app",
     "container",
@@ -29,14 +29,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@nwire/container": "0.12.0",
-    "@nwire/envelope": "0.12.0",
-    "@nwire/hooks": "0.12.0",
-    "@nwire/logger": "0.12.0",
-    "@nwire/messages": "0.12.0",
-    "@nwire/handler": "0.12.0",
-    "@nwire/wires": "0.12.0",
-    "@nwire/runtime": "0.12.0"
+    "@nwire/container": "0.13.0",
+    "@nwire/handler": "0.13.0",
+    "@nwire/logger": "0.13.0",
+    "@nwire/hooks": "0.13.0",
+    "@nwire/telemetry": "0.13.0",
+    "@nwire/wires": "0.13.0",
+    "@nwire/runtime": "0.13.0",
+    "@nwire/messages": "0.13.0",
+    "@nwire/envelope": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",