@nwire/app 0.10.1 → 0.11.0

package/README.md

@@ -16,10 +16,9 @@ import { z } from "zod";
 
 const app = createApp({ appName: "api" });
 
-app.wire(
-  post("/hello", { body: z.object({ name: z.string() }) }),
-  async (input) => ({ message: `Hello, ${input.name}!` }),
-);
+app.wire(post("/hello", { body: z.object({ name: z.string() }) }), async (input) => ({
+  message: `Hello, ${input.name}!`,
+}));
 ```
 
 `createApp` builds an **App** — a bounded context with its container,
@@ -64,10 +63,7 @@ const ordersApp = createApp({ appName: "orders" /* ... */ });
 const inventoryApp = createApp({ appName: "inventory" /* ... */ });
 
 const monolith = appCompose(ordersApp, inventoryApp);
-await endpoint("monolith", { port: 3000 })
-  .use(httpKoa())
-  .mount(monolith)
-  .run();
+await endpoint("monolith", { port: 3000 }).use(httpKoa()).mount(monolith).run();
 ```
 
 ## Framework events

package/dist/app.d.ts

@@ -1,10 +1,14 @@
 /**
  * `@nwire/app` — composition root. `createApp` constructs a Runtime, runs
- * plugin setup, and drives start/stop. `createRuntime` exposes the raw
- * substrate for advanced cases.
+ * plugin lifecycle, and exposes the fluent verbs that move the App's typed
+ * 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 { definePlugin, isPlugin } from "./define-plugin.js";
 export { createApp, type App, type CreateAppOptions } from "./create-app.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 type { HandlerBaseCtx, Ctx } from "@nwire/handler";

package/dist/app.js

@@ -1,9 +1,20 @@
 /**
  * `@nwire/app` — composition root. `createApp` constructs a Runtime, runs
- * plugin setup, and drives start/stop. `createRuntime` exposes the raw
- * substrate for advanced cases.
+ * plugin lifecycle, and exposes the fluent verbs that move the App's typed
+ * 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 { definePlugin, isPlugin } from "./define-plugin.js";
 export { createApp } from "./create-app.js";
 export { appCompose, containerOf, } from "./compose-app.js";
+// Listener primitive — `subscribe((when) => …)` creates a Subscription
+// value the App registers through `app.subscribe(sub | subs)`.
+export { subscribe, isSubscription } from "./subscribe.js";
+// Publish capability — contributes `ctx.publish`. Composes
+// `runtime.emit` (local fanout) with `runtime.sinkDrain` (outbound chain),
+// gated on the event's `$public` marker.
+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";

package/dist/compose-app.js

@@ -38,10 +38,7 @@ function bindingKey(wire) {
     return `${adapter}:${verb ? `${verb}:` : ""}${id}`;
 }
 function isComposeOptions(x) {
-    return (typeof x === "object" &&
-        x !== null &&
-        !("interface" in x) &&
-        "onCollision" in x);
+    return (typeof x === "object" && x !== null && !("interface" in x) && "onCollision" in x);
 }
 export function appCompose(...args) {
     // Trailing options arg?
@@ -79,8 +76,8 @@ export function appCompose(...args) {
     // The composite presents as an App. It re-uses the FIRST child's
     // runtime / container / start / stop / etc. — the composite is for
     // wire surface, not for runtime fan-out. Multi-runtime composition is
-    // not supported in 0.10; if you want it, mount each app under its own
-    // endpoint instead.
+    // out of scope; to run more than one runtime in the same process,
+    // mount each app under its own endpoint.
     const head = apps[0];
     const compositeName = apps.map((a) => a.appName).join("+");
     const composite = {
@@ -88,10 +85,28 @@ export function appCompose(...args) {
         $kind: "app",
         appName: compositeName,
         name: compositeName,
+        get state() {
+            return head.state;
+        },
         container: head.container,
         runtime: head.runtime,
         interface: mergedInterface,
         plugins: apps.flatMap((a) => a.plugins),
+        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
+            // anything added on the composite lands there.
+            head.with(plugin);
+            return composite;
+        },
+        subscribe(sub) {
+            head.subscribe(sub);
+            return composite;
+        },
+        when(event, fn) {
+            head.when(event, fn);
+            return composite;
+        },
         wire(binding, handler) {
             mergedInterface.wire(binding, handler);
             return composite;

package/dist/create-app.d.ts

@@ -1,21 +1,44 @@
 /**
- * `createApp` — composition root. Constructs a Runtime, registers
- * plugins, and exposes the lifecycle the runtime owns.
+ * `createApp` — composition root. Constructs a Runtime, registers plugins,
+ * and exposes the fluent verbs that move the App's typed capability set:
+ *
+ *   - `App<TCaps>` is generic. Each `.with(plugin)` intersects the plugin's
+ *     `__mark` into `TCaps`, so handler ctx narrows automatically.
+ *
+ *   - `.with(plugin)` is the typed plugin-install verb. Equivalent to
+ *     `runtime.registerPlugin(plugin)` at runtime but moves the type.
+ *
+ *   - `.subscribe(sub | subs)` registers `Subscription` values — closures
+ *     produced by the module-level `subscribe(fn)` primitive. The pattern
+ *     for organised listener files under `app/listeners/`.
+ *
+ *   - `.when(event, fn)` is the inline shortcut over `runtime.when`.
+ *
+ * Plugins passed via `createApp({ plugins })` install identically to those
+ * installed via `.with()`.
  */
 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 } from "@nwire/messages";
+import type { MessageEnvelope } from "@nwire/envelope";
 import { type PluginDefinition, type Runtime } from "./runtime/index.js";
+import { type Subscription } from "./subscribe.js";
 export interface CreateAppOptions {
     /** App name — surfaces in framework-hook payloads + dev logger output. */
     readonly appName: string;
-    /** Plugins. Setup runs synchronously at construction. */
+    /**
+     * Plugins to install at construction. Setup runs synchronously. Equivalent
+     * to chaining `.with(plugin)` after `createApp({...})`; the array form is
+     * untyped (TCaps stays `{}`), so prefer `.with(plugin)` when the App's
+     * capability set should narrow handler ctx.
+     */
     readonly plugins?: readonly PluginDefinition[];
     /**
-     * Handlers — registered on the runtime at construction so any plugin
-     * (forge, queue, …) can pick them up during boot. Each handler must
-     * satisfy the structural shape `runtime.registerHandler` accepts
-     * (`name`, `input`, `run(ctx, opts?)` returning `{ result }`).
+     * Handlers registered on the runtime at construction so any plugin can
+     * pick them up during boot. Each handler must satisfy the structural
+     * shape `runtime.registerHandler` accepts: `name`, `input`, and
+     * `run(ctx, opts?)` returning `{ result }`.
      */
     readonly handlers?: readonly any[];
     /** Override the container — defaults to a fresh `createContainer()`. */
@@ -25,7 +48,11 @@ export interface CreateAppOptions {
     /** Logger override. */
     readonly logger?: Logger;
 }
-export interface App {
+/**
+ * The App. `TCaps` is the phantom carrier of every capability contributed
+ * by plugins via `.with()`. Defaults to `{}`.
+ */
+export interface App<TCaps = {}> {
     readonly $nwireApp: true;
     readonly $kind: "app";
     readonly appName: string;
@@ -40,15 +67,48 @@ export interface App {
      */
     readonly interface: Interface;
     readonly plugins: readonly PluginDefinition[];
+    /** Phantom marker — never read at runtime. */
+    readonly __caps?: TCaps;
+    /**
+     * Install a plugin and advance the App's type. Same runtime effect as
+     * passing the plugin in `createApp({plugins})`; the difference is the
+     * type-level move — `TCaps` intersects the plugin's __mark so handler
+     * ctx narrows to the new shape.
+     */
+    with<TMark>(plugin: PluginDefinition<void, TMark>): App<TCaps & TMark>;
+    with<TOpts, TMark>(plugin: PluginDefinition<TOpts, TMark>): App<TCaps & TMark>;
+    /**
+     * Register Subscription values. Each subscription's `install(when)` is
+     * called with the App's `runtime.when`. Pass a single sub or an array.
+     */
+    subscribe(sub: Subscription | readonly Subscription[]): this;
+    /**
+     * Inline listener shortcut over `runtime.when`. Use for one-offs where
+     * pulling a dedicated listener file feels heavy. For organised codebases,
+     * prefer `.subscribe([...])` from `app/listeners/`.
+     */
+    when<TPayload>(event: EventDefinition & {
+        readonly name: string;
+        readonly schema: {
+            parse(input: unknown): unknown;
+        };
+    }, fn: (payload: TPayload, envelope: MessageEnvelope) => Promise<void> | void): this;
     /** Sugar for `app.interface.wire(b, h)`. Returns the app for chaining. */
     wire(binding: Binding, handler: HandlerDef): this;
     /** Sugar for `app.interface.provide(builder)`. Returns the app for chaining. */
     provide<TExtras extends object>(builder: WireCtxBuilder<TExtras>): this;
-    start(): Promise<void>;
+    /** Current lifecycle phase. */
+    readonly state: "idle" | "starting" | "running" | "stopping" | "stopped";
+    /**
+     * Boot the app. Optional `appConfig` is bound on the container as
+     * `"config"` so plugin boot callbacks can resolve it. Idempotent —
+     * concurrent / repeat calls return the same Promise.
+     */
+    start(appConfig?: unknown): Promise<void>;
     stop(reason?: string): Promise<void>;
-    /** Endpoint alias. */
-    boot(): Promise<void>;
-    /** Endpoint alias. */
+    /** Endpoint alias for {@link start}. */
+    boot(appConfig?: unknown): Promise<void>;
+    /** Endpoint alias for {@link stop}. */
     shutdown(): Promise<void>;
     /**
      * Run a built-in framework hook by registry-slot name. Resolves `false`
@@ -56,4 +116,4 @@ export interface App {
      */
     dispatchFrameworkEvent(slot: string, payload: unknown): Promise<boolean>;
 }
-export declare function createApp(options: CreateAppOptions): App;
+export declare function createApp(options: CreateAppOptions): App<{}>;

package/dist/create-app.js

@@ -1,23 +1,46 @@
 /**
- * `createApp` — composition root. Constructs a Runtime, registers
- * plugins, and exposes the lifecycle the runtime owns.
+ * `createApp` — composition root. Constructs a Runtime, registers plugins,
+ * and exposes the fluent verbs that move the App's typed capability set:
+ *
+ *   - `App<TCaps>` is generic. Each `.with(plugin)` intersects the plugin's
+ *     `__mark` into `TCaps`, so handler ctx narrows automatically.
+ *
+ *   - `.with(plugin)` is the typed plugin-install verb. Equivalent to
+ *     `runtime.registerPlugin(plugin)` at runtime but moves the type.
+ *
+ *   - `.subscribe(sub | subs)` registers `Subscription` values — closures
+ *     produced by the module-level `subscribe(fn)` primitive. The pattern
+ *     for organised listener files under `app/listeners/`.
+ *
+ *   - `.when(event, fn)` is the inline shortcut over `runtime.when`.
+ *
+ * Plugins passed via `createApp({ plugins })` install identically to those
+ * installed via `.with()`.
  */
 import { createContainer } from "@nwire/container/awilix";
 import { NoopLogger } from "@nwire/logger";
 import { createInterface, } from "@nwire/wires";
 import { createRuntime } from "./runtime/index.js";
+import { AppLifecycle } from "./lifecycle.js";
+import { isSubscription } from "./subscribe.js";
 export function createApp(options) {
     const appName = options.appName;
     const container = options.container ?? createContainer();
     const logger = options.logger ?? new NoopLogger();
     const runtime = options.runtime ?? createRuntime({ container, logger, appName });
-    const plugins = options.plugins ?? [];
+    const plugins = [...(options.plugins ?? [])];
     const iface = createInterface();
     for (const h of options.handlers ?? []) {
         runtime.registerHandler(h);
     }
+    // The orchestrator owns plugin queueing, register/setup phase
+    // execution, and the boot/shutdown state machine. Plugins passed in
+    // `options.plugins` enqueue immediately; `.with(plugin)` enqueues on
+    // top. Both fire at `app.start()`, in register-then-setup order across
+    // all plugins.
+    const lifecycle = new AppLifecycle({ appName, container, runtime });
     for (const p of plugins) {
-        runtime.registerPlugin(p);
+        lifecycle.enqueue(p);
     }
     const app = {
         $nwireApp: true,
@@ -28,6 +51,30 @@ export function createApp(options) {
         runtime,
         interface: iface,
         plugins,
+        get state() {
+            return lifecycle.currentState;
+        },
+        with(plugin) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            lifecycle.enqueue(plugin);
+            plugins.push(plugin);
+            // Phantom type advance — runtime identity stays the same.
+            return app;
+        },
+        subscribe(sub) {
+            const subs = isSubscription(sub) ? [sub] : sub;
+            const whenFn = (event, fn) => {
+                runtime.when(event, fn);
+            };
+            for (const s of subs) {
+                s.install(whenFn);
+            }
+            return app;
+        },
+        when(event, fn) {
+            runtime.when(event, fn);
+            return app;
+        },
         wire(binding, handler) {
             iface.wire(binding, handler);
             // Tag the just-appended wire with its source app so adopters can
@@ -40,10 +87,17 @@ export function createApp(options) {
             iface.provide(builder);
             return app;
         },
-        start: () => runtime.start(),
-        stop: (reason) => runtime.stop(reason),
-        boot: () => runtime.start(),
-        shutdown: () => runtime.stop(),
+        start: (appConfig) => {
+            // Bind appConfig as "config" so plugin register, setup, and boot
+            // callbacks can resolve it. Skipped when no config is passed.
+            if (appConfig !== undefined && !container.has("config")) {
+                container.register("config", appConfig);
+            }
+            return lifecycle.start();
+        },
+        stop: (reason) => lifecycle.stop(reason),
+        boot: (appConfig) => app.start(appConfig),
+        shutdown: () => lifecycle.stop(),
         dispatchFrameworkEvent: async (slot, payload) => {
             const hooks = runtime.hooks;
             const h = hooks[slot];

package/dist/define-plugin.d.ts

@@ -1,14 +1,39 @@
 /**
  * Plugin factory — wraps the canonical `PluginDefinition` shape with
- * source-location capture so Studio + scan can render where a plugin
- * was declared. Setup runs synchronously at `runtime.registerPlugin`
- * time and contributes container bindings, hook subscriptions, and
- * boot/dispose queues.
+ * source-location capture so tooling (Studio, scan) can render where a
+ * plugin was declared.
+ *
+ * Two call forms produce the same returned shape:
+ *
+ *   // Single-phase: pass a setup closure directly.
+ *   definePlugin("name", (ctx) => { ... setup body ... });
+ *
+ *   // Two-phase: pass a body object with options + register + setup.
+ *   definePlugin("name", {
+ *     options: opts,
+ *     register: (ctx) => { ... bindings + hook slots ... },
+ *     setup:    (ctx) => { ... capabilities + listeners + boots ... },
+ *   });
+ *
+ * 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> {
+    readonly options?: TOptions;
+    register?(ctx: PluginContext<TOptions>): void;
+    setup(ctx: PluginContext<TOptions>): void;
+    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;
 };
+/** 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;
+};
 /** Discriminator for runtime-side checks. */
 export declare function isPlugin(x: unknown): x is PluginDefinition;

package/dist/define-plugin.js

@@ -1,16 +1,36 @@
 /**
  * Plugin factory — wraps the canonical `PluginDefinition` shape with
- * source-location capture so Studio + scan can render where a plugin
- * was declared. Setup runs synchronously at `runtime.registerPlugin`
- * time and contributes container bindings, hook subscriptions, and
- * boot/dispose queues.
+ * source-location capture so tooling (Studio, scan) can render where a
+ * plugin was declared.
+ *
+ * Two call forms produce the same returned shape:
+ *
+ *   // Single-phase: pass a setup closure directly.
+ *   definePlugin("name", (ctx) => { ... setup body ... });
+ *
+ *   // Two-phase: pass a body object with options + register + setup.
+ *   definePlugin("name", {
+ *     options: opts,
+ *     register: (ctx) => { ... bindings + hook slots ... },
+ *     setup:    (ctx) => { ... capabilities + listeners + boots ... },
+ *   });
+ *
+ * Both produce a `PluginDefinition<TOptions, TMark>` that the Runtime's
+ * `registerPlugin` runs as register-then-setup.
  */
 import { captureSourceLocation } from "@nwire/messages";
-export function definePlugin(name, setup) {
+// ─── Implementation ───────────────────────────────────────────────────────
+export function definePlugin(name, setupOrBody) {
     const $source = captureSourceLocation();
+    if (typeof setupOrBody === "function") {
+        return { name, setup: setupOrBody, $source };
+    }
     return {
         name,
-        setup,
+        options: setupOrBody.options,
+        register: setupOrBody.register,
+        setup: setupOrBody.setup,
+        __mark: setupOrBody.__mark,
         $source,
     };
 }

package/dist/lifecycle.d.ts

@@ -0,0 +1,79 @@
+/**
+ * App lifecycle orchestrator — owns the plugin queue, register/setup phase
+ * execution, the boot/shutdown state machine, and the firing of
+ * `AppRegistering` / `AppBooting` / `AppReady` / `AppShutdown` hooks.
+ *
+ * The Runtime is the dispatch substrate (container, capabilities, sinks,
+ * events, middleware, telemetry). It does not know about plugins. The
+ * App composes the Runtime with this orchestrator to get plugin lifecycle.
+ */
+import type { Container } from "@nwire/container";
+import type { PluginDefinition, Runtime } from "@nwire/runtime";
+/** Lifecycle state. */
+export type LifecycleState = "idle" | "starting" | "running" | "stopping" | "stopped";
+export interface AppLifecycleOptions {
+    readonly appName: string;
+    readonly container: Container;
+    readonly runtime: Runtime;
+}
+/**
+ * The orchestrator. Each App owns one of these.
+ */
+export declare class AppLifecycle {
+    private readonly appName;
+    private readonly container;
+    private readonly runtime;
+    /** 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;
+    private state;
+    private startPromise;
+    private stopPromise;
+    constructor(opts: AppLifecycleOptions);
+    /** Current lifecycle phase. */
+    get currentState(): LifecycleState;
+    /** Names of every plugin queued or registered, in registration order. */
+    pluginNames(): readonly string[];
+    /**
+     * Queue a plugin for the next `start()`. Throws if a plugin of the same
+     * name is already enqueued or registered, or if the lifecycle has
+     * advanced past `idle` (queue is closed once start begins).
+     */
+    enqueue<TOptions = void>(plugin: PluginDefinition<TOptions>): void;
+    /**
+     * Drain queued plugins: all `register`s first, then all `setup`s, then
+     * record their boot/dispose queues for the lifecycle to run. Synchronous;
+     * idempotent (no-op once the queue is empty).
+     */
+    runPluginPhases(): void;
+    /**
+     * Boot the app:
+     *
+     *   1. Drain queued plugins (registers, then setups).
+     *   2. Fire `PluginRegistered` for each registered plugin.
+     *   3. Fire `AppRegistering` chain (vetoable).
+     *   4. Fire `AppBooting` chain (vetoable).
+     *   5. For each plugin: `PluginBooting` chain → boot queue → `PluginBooted`.
+     *   6. Run container health checks; fail-fast if any throw.
+     *   7. Fire `AppBooted` + `AppReady`.
+     *
+     * Idempotent + in-flight-shared.
+     */
+    start(): Promise<void>;
+    /**
+     * Graceful shutdown:
+     *
+     *   1. Fire `AppShuttingDown` chain (vetoable).
+     *   2. For each plugin in reverse order: `PluginShuttingDown` chain →
+     *      dispose queue (LIFO, errors isolated) → `PluginShutdown`.
+     *   3. `container.dispose()` — runs `bind({ dispose })` callbacks LIFO.
+     *   4. Fire `AppShutdown`.
+     *
+     * Idempotent + in-flight-shared. The first thrown error during plugin
+     * dispose or container dispose is rethrown after the sequence completes.
+     */
+    stop(reason?: string): Promise<void>;
+    /** Build the plugin context — same shape across register and setup. */
+    private buildPluginContext;
+}

package/dist/lifecycle.js

@@ -0,0 +1,279 @@
+/**
+ * App lifecycle orchestrator — owns the plugin queue, register/setup phase
+ * execution, the boot/shutdown state machine, and the firing of
+ * `AppRegistering` / `AppBooting` / `AppReady` / `AppShutdown` hooks.
+ *
+ * The Runtime is the dispatch substrate (container, capabilities, sinks,
+ * events, middleware, telemetry). It does not know about plugins. The
+ * App composes the Runtime with this orchestrator to get plugin lifecycle.
+ */
+/**
+ * The orchestrator. Each App owns one of these.
+ */
+export class AppLifecycle {
+    appName;
+    container;
+    runtime;
+    /** Plugins enqueued via `enqueue` whose phases haven't run yet. */
+    pendingPlugins = [];
+    /** Plugins whose register + setup have run. Ordered by registration. */
+    plugins = [];
+    state = "idle";
+    startPromise;
+    stopPromise;
+    constructor(opts) {
+        this.appName = opts.appName;
+        this.container = opts.container;
+        this.runtime = opts.runtime;
+    }
+    /** Current lifecycle phase. */
+    get currentState() {
+        return this.state;
+    }
+    /** 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)];
+    }
+    /**
+     * Queue a plugin for the next `start()`. Throws if a plugin of the same
+     * name is already enqueued or registered, or if the lifecycle has
+     * advanced past `idle` (queue is closed once start begins).
+     */
+    enqueue(plugin) {
+        if (this.state !== "idle") {
+            throw new Error(`App.with: cannot enqueue "${plugin.name}" — app is "${this.state}".`);
+        }
+        if (this.plugins.some((p) => p.name === plugin.name)) {
+            throw new Error(`App.with: plugin "${plugin.name}" already registered.`);
+        }
+        if (this.pendingPlugins.some((p) => p.def.name === plugin.name)) {
+            throw new Error(`App.with: plugin "${plugin.name}" already enqueued.`);
+        }
+        this.pendingPlugins.push({ def: plugin });
+    }
+    /**
+     * Drain queued plugins: all `register`s first, then all `setup`s, then
+     * record their boot/dispose queues for the lifecycle to run. Synchronous;
+     * idempotent (no-op once the queue is empty).
+     */
+    runPluginPhases() {
+        if (this.pendingPlugins.length === 0)
+            return;
+        const drained = this.pendingPlugins.splice(0, this.pendingPlugins.length);
+        const prepared = drained.map((p) => {
+            const boots = [];
+            const disposes = [];
+            const ctx = this.buildPluginContext(p.def, boots, disposes);
+            return { def: p.def, ctx, boots, disposes };
+        });
+        for (const p of prepared) {
+            if (p.def.register)
+                p.def.register(p.ctx);
+        }
+        for (const p of prepared) {
+            p.def.setup(p.ctx);
+        }
+        for (const p of prepared) {
+            this.plugins.push({ name: p.def.name, boots: p.boots, disposes: p.disposes });
+        }
+    }
+    /**
+     * Boot the app:
+     *
+     *   1. Drain queued plugins (registers, then setups).
+     *   2. Fire `PluginRegistered` for each registered plugin.
+     *   3. Fire `AppRegistering` chain (vetoable).
+     *   4. Fire `AppBooting` chain (vetoable).
+     *   5. For each plugin: `PluginBooting` chain → boot queue → `PluginBooted`.
+     *   6. Run container health checks; fail-fast if any throw.
+     *   7. Fire `AppBooted` + `AppReady`.
+     *
+     * Idempotent + in-flight-shared.
+     */
+    start() {
+        if (this.startPromise)
+            return this.startPromise;
+        if (this.state === "running")
+            return Promise.resolve();
+        if (this.state !== "idle") {
+            return Promise.reject(new Error(`App.start: cannot start from lifecycle state "${this.state}".`));
+        }
+        this.state = "starting";
+        const appName = this.appName;
+        const hooks = this.runtime.hooks;
+        this.startPromise = (async () => {
+            try {
+                this.runPluginPhases();
+                for (const p of this.plugins) {
+                    await hooks.PluginRegistered.run({ appName, pluginName: p.name, kind: "plugin" });
+                }
+                const registering = await hooks.AppRegistering.runDetailed({ appName });
+                if (registering.outcome === "failed")
+                    throw registering.error;
+                if (registering.outcome !== "completed") {
+                    throw new Error(`App.start("${appName}"): AppRegistering vetoed by chain step.`);
+                }
+                const booting = await hooks.AppBooting.runDetailed({ appName });
+                if (booting.outcome === "failed")
+                    throw booting.error;
+                if (booting.outcome !== "completed") {
+                    throw new Error(`App.start("${appName}"): AppBooting vetoed by chain step.`);
+                }
+                for (const p of this.plugins) {
+                    const pre = await hooks.PluginBooting.runDetailed({
+                        appName,
+                        pluginName: p.name,
+                        kind: "plugin",
+                    });
+                    if (pre.outcome === "failed")
+                        throw pre.error;
+                    if (pre.outcome !== "completed") {
+                        throw new Error(`App.start("${appName}"): plugin "${p.name}" boot vetoed by chain step.`);
+                    }
+                    const startedAt = performance.now();
+                    for (const fn of p.boots) {
+                        await fn();
+                    }
+                    await hooks.PluginBooted.run({
+                        appName,
+                        pluginName: p.name,
+                        durationMs: performance.now() - startedAt,
+                        kind: "plugin",
+                    });
+                }
+                const checks = await this.container.runChecks();
+                const failed = checks.filter((c) => !c.ok);
+                if (failed.length > 0) {
+                    const summary = failed
+                        .map((c) => `${c.name}: ${c.error?.message ?? "check failed"}`)
+                        .join("; ");
+                    throw new Error(`App.start("${appName}"): container check(s) failed — ${summary}`);
+                }
+                await hooks.AppBooted.run({ appName, bootedAt: new Date().toISOString() });
+                await hooks.AppReady.run({ appName, readyAt: new Date().toISOString() });
+                this.state = "running";
+            }
+            catch (err) {
+                this.state = "idle";
+                this.startPromise = undefined;
+                throw err;
+            }
+        })();
+        return this.startPromise;
+    }
+    /**
+     * Graceful shutdown:
+     *
+     *   1. Fire `AppShuttingDown` chain (vetoable).
+     *   2. For each plugin in reverse order: `PluginShuttingDown` chain →
+     *      dispose queue (LIFO, errors isolated) → `PluginShutdown`.
+     *   3. `container.dispose()` — runs `bind({ dispose })` callbacks LIFO.
+     *   4. Fire `AppShutdown`.
+     *
+     * Idempotent + in-flight-shared. The first thrown error during plugin
+     * dispose or container dispose is rethrown after the sequence completes.
+     */
+    stop(reason) {
+        if (this.stopPromise)
+            return this.stopPromise;
+        if (this.state === "stopped")
+            return Promise.resolve();
+        if (this.state !== "running") {
+            return Promise.reject(new Error(`App.stop: cannot stop from lifecycle state "${this.state}".`));
+        }
+        this.state = "stopping";
+        const appName = this.appName;
+        const hooks = this.runtime.hooks;
+        this.stopPromise = (async () => {
+            const errors = [];
+            const shuttingDown = await hooks.AppShuttingDown.runDetailed({ appName, reason });
+            if (shuttingDown.outcome !== "completed") {
+                this.state = "running";
+                this.stopPromise = undefined;
+                if (shuttingDown.outcome === "failed")
+                    throw shuttingDown.error;
+                throw new Error(`App.stop("${appName}"): AppShuttingDown vetoed by chain step.`);
+            }
+            for (let i = this.plugins.length - 1; i >= 0; i--) {
+                const p = this.plugins[i];
+                const pre = await hooks.PluginShuttingDown.runDetailed({
+                    appName,
+                    pluginName: p.name,
+                    kind: "plugin",
+                });
+                if (pre.outcome !== "completed") {
+                    // eslint-disable-next-line no-console
+                    console.warn(`App.stop("${appName}"): PluginShuttingDown vetoed for "${p.name}" — skipping dispose.`);
+                    continue;
+                }
+                const startedAt = performance.now();
+                for (let j = p.disposes.length - 1; j >= 0; j--) {
+                    try {
+                        await p.disposes[j]();
+                    }
+                    catch (err) {
+                        errors.push(err);
+                        // eslint-disable-next-line no-console
+                        console.error(`App.stop("${appName}"): plugin "${p.name}" dispose threw:`, err);
+                    }
+                }
+                await hooks.PluginShutdown.run({
+                    appName,
+                    pluginName: p.name,
+                    durationMs: performance.now() - startedAt,
+                    kind: "plugin",
+                });
+            }
+            try {
+                await this.container.dispose();
+            }
+            catch (err) {
+                errors.push(err);
+                // eslint-disable-next-line no-console
+                console.error(`App.stop("${appName}"): container.dispose threw:`, err);
+            }
+            await hooks.AppShutdown.run({ appName });
+            this.state = "stopped";
+            if (errors.length > 0) {
+                throw errors[0];
+            }
+        })();
+        return this.stopPromise;
+    }
+    /** Build the plugin context — same shape across register and setup. */
+    buildPluginContext(plugin, boots, disposes) {
+        return {
+            container: this.container,
+            runtime: this.runtime,
+            hooks: this.runtime.hooks,
+            options: plugin.options,
+            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 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.`);
+                }
+                h.on(fn);
+            },
+            boot: (fn) => {
+                boots.push(fn);
+            },
+            dispose: (fn) => {
+                disposes.push(fn);
+            },
+            shutdown: (fn) => {
+                disposes.push(fn);
+            },
+            defineHook: (name) => this.runtime.defineHook(name),
+        };
+    }
+}

package/dist/publish.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `publishCapability` + `publishPlugin` — cross-process publish as a
+ * capability composition.
+ *
+ *   import { createApp, publishPlugin } from "@nwire/app";
+ *
+ *   const app = createApp({ appName: "shop" }).with(publishPlugin());
+ *
+ *   // inside a handler:
+ *   await ctx.publish(OrderShipped, { orderId, customerId });
+ *
+ * The capability composes `runtime.emit` (local fan-out to subscribers)
+ * with `runtime.sinkDrain` (outbound chain delivery). For events marked
+ * public via `defineEvent(...).public()` the call fires both; for
+ * private events only local subscribers fire and the sink is skipped.
+ *
+ * ## When to use this vs forge
+ *
+ * Forge ships its own bundled publish path inside `ForgeDispatcher` —
+ * projections fold, actors transition, workflows fire, and the bus
+ * publishes in one atomic sequence with defined order. That sequence
+ * cannot be decomposed without breaking saga ordering guarantees.
+ *
+ * `publishCapability` is the non-forge path: same emit + sink-drain
+ * shape, no projection/actor/workflow integration. Apps that aren't
+ * doing CQRS but still need cross-process broadcast install this; apps
+ * with forge use the forge path.
+ */
+import { type Capability } from "@nwire/runtime";
+import type { EventDefinition } from "@nwire/messages";
+import type { PluginDefinition } from "./runtime/index.js";
+/** Ctx shape contributed by `publishCapability`. */
+export interface PublishCaps {
+    publish<TPayload>(event: EventDefinition & {
+        readonly name: string;
+        readonly schema: {
+            parse(input: unknown): unknown;
+        };
+        /** Set by `defineEvent(...).public()`. */
+        readonly $public?: boolean;
+    }, payload: TPayload): Promise<void>;
+}
+/**
+ * The capability. Provides `ctx.publish`; the runtime methods it composes
+ * (`emit`, `sinkDrain`) are already exposed.
+ *
+ * Sink drain fires only when `event.$public === true`. Private events
+ * stay intra-bounded-context — they fan out to local subscribers but
+ * never cross the process membrane.
+ */
+export declare const publishCapability: Capability<PublishCaps>;
+/**
+ * `app.with(publishPlugin())` installs `publishCapability`. Stateless;
+ * no options. The capability's `__mark` carries `PublishCaps` so the
+ * App's `<TCaps>` learns about `ctx.publish`.
+ */
+export declare function publishPlugin(): PluginDefinition<void, PublishCaps>;

package/dist/publish.js

@@ -0,0 +1,61 @@
+/**
+ * `publishCapability` + `publishPlugin` — cross-process publish as a
+ * capability composition.
+ *
+ *   import { createApp, publishPlugin } from "@nwire/app";
+ *
+ *   const app = createApp({ appName: "shop" }).with(publishPlugin());
+ *
+ *   // inside a handler:
+ *   await ctx.publish(OrderShipped, { orderId, customerId });
+ *
+ * The capability composes `runtime.emit` (local fan-out to subscribers)
+ * with `runtime.sinkDrain` (outbound chain delivery). For events marked
+ * public via `defineEvent(...).public()` the call fires both; for
+ * private events only local subscribers fire and the sink is skipped.
+ *
+ * ## When to use this vs forge
+ *
+ * Forge ships its own bundled publish path inside `ForgeDispatcher` —
+ * projections fold, actors transition, workflows fire, and the bus
+ * publishes in one atomic sequence with defined order. That sequence
+ * cannot be decomposed without breaking saga ordering guarantees.
+ *
+ * `publishCapability` is the non-forge path: same emit + sink-drain
+ * shape, no projection/actor/workflow integration. Apps that aren't
+ * doing CQRS but still need cross-process broadcast install this; apps
+ * with forge use the forge path.
+ */
+import { defineCapability } from "@nwire/runtime";
+import { definePlugin } from "./define-plugin.js";
+/**
+ * The capability. Provides `ctx.publish`; the runtime methods it composes
+ * (`emit`, `sinkDrain`) are already exposed.
+ *
+ * Sink drain fires only when `event.$public === true`. Private events
+ * stay intra-bounded-context — they fan out to local subscribers but
+ * never cross the process membrane.
+ */
+export const publishCapability = defineCapability({
+    name: "publish",
+    provideCtx: ({ runtime, envelope }) => ({
+        publish: async (event, payload) => {
+            await runtime.emit(event, payload, { parent: envelope });
+            if (event.$public === true) {
+                await runtime.sinkDrain(event, payload, envelope);
+            }
+        },
+    }),
+});
+/**
+ * `app.with(publishPlugin())` installs `publishCapability`. Stateless;
+ * no options. The capability's `__mark` carries `PublishCaps` so the
+ * App's `<TCaps>` learns about `ctx.publish`.
+ */
+export function publishPlugin() {
+    return definePlugin("publish", {
+        setup: ({ add }) => {
+            add(publishCapability);
+        },
+    });
+}

package/dist/runtime/index.d.ts

@@ -1,6 +1,9 @@
 /**
  * Runtime — Container + dispatch hook + per-runtime FrameworkHooks
  * registry + telemetry stream + plugin lifecycle.
+ *
+ * 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 "./runtime.js";
-export { createFrameworkHooks, type FrameworkHooks, type PluginKind, } from "./framework-hooks.js";
+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 { createFrameworkHooks, type FrameworkHooks, type PluginKind } from "@nwire/runtime";

package/dist/runtime/index.js

@@ -1,6 +1,9 @@
 /**
  * Runtime — Container + dispatch hook + per-runtime FrameworkHooks
  * registry + telemetry stream + plugin lifecycle.
+ *
+ * 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 "./runtime.js";
-export { createFrameworkHooks, } from "./framework-hooks.js";
+export { Runtime, createRuntime, isBuiltInHook, serializeError, } from "@nwire/runtime";
+export { createFrameworkHooks } from "@nwire/runtime";

package/dist/runtime/runtime.d.ts

@@ -268,6 +268,9 @@ export declare class Runtime {
         readonly signal?: AbortSignal;
         readonly parent?: MessageEnvelope;
     }, extras?: Record<string, unknown>): Promise<TOutput>;
+    /** Innermost dispatch step that calls the actual handler. Pinned once. */
+    private dispatchCorePinned;
+    private ensureDispatchCorePin;
     /**
      * Fire-and-forget dispatch. Default implementation: `setImmediate` →
      * `execute`. Queue-adapter installation can override this to enqueue

package/dist/runtime/runtime.js

@@ -516,25 +516,47 @@ export class Runtime {
             resolve: (name) => scope.resolve(name),
             scope,
         };
-        try {
-            if (typeof target === "function" && !("$kind" in target)) {
-                // Plain function path — the wire holds a bare `(input, ctx) => ...`
-                // value. No hook chain to run; call directly with the unified ctx so
-                // plain handlers see the same surface as defineHandler ones (the
-                // three verbs, envelope, scope, transport extras).
-                return (await target(input, ctx));
-            }
-            // HandlerDefinition path — runs the hook chain (telemetry, .use()
-            // middleware, terminal step that validates + calls the handler body).
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const def = target;
+        // Normalize the dispatch target to a HandlerDefinition. Plain
+        // `(input, ctx) => ...` functions get wrapped in a synthetic
+        // definition so the dispatch path has ONE shape downstream — no
+        // typeof-function branch, no parallel call site.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const def = typeof target === "function" && !("$kind" in target)
+            ? wrapFunctionAsHandlerDef(target)
+            : target;
+        const innerCore = async () => {
             const out = await def.run(ctx, { signal });
             return out.result;
+        };
+        try {
+            if (this.userMiddlewareCount > 0) {
+                this.ensureDispatchCorePin();
+                const hctx = {
+                    action: def,
+                    input,
+                    ctx,
+                    coreFn: innerCore,
+                };
+                await this.dispatchHook.run(hctx);
+                return hctx.result;
+            }
+            return await innerCore();
         }
         finally {
             await scope.dispose();
         }
     }
+    /** Innermost dispatch step that calls the actual handler. Pinned once. */
+    dispatchCorePinned = false;
+    ensureDispatchCorePin() {
+        if (this.dispatchCorePinned)
+            return;
+        this.dispatchHook.use(async (hc, next) => {
+            hc.result = await hc.coreFn();
+            await next();
+        }, { name: "__nwire_runtime_core__", priority: Number.NEGATIVE_INFINITY });
+        this.dispatchCorePinned = true;
+    }
     /**
      * Fire-and-forget dispatch. Default implementation: `setImmediate` →
      * `execute`. Queue-adapter installation can override this to enqueue
@@ -639,4 +661,25 @@ export class Runtime {
 export function createRuntime(options = {}) {
     return new Runtime(options);
 }
+/**
+ * Wrap a plain `(input, ctx) => …` function in a minimal HandlerDefinition
+ * so `runtime.execute` has one dispatch path. No hook chain, no validation
+ * — just enough shape for `def.run(ctx)` to call the function and surface
+ * its result on `ctx.result`. Allocated once per execute call; the cost
+ * is one object + two property reads relative to a direct function call.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function wrapFunctionAsHandlerDef(fn) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return {
+        $kind: "handler",
+        name: fn.name || "anonymous",
+        config: { handler: fn },
+        async run(ctx) {
+            ctx.result = await fn(ctx.input, ctx);
+            return ctx;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+}
 export { isBuiltInHook };

package/dist/subscribe.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `subscribe((when) => …)` — the listener primitive.
+ *
+ * A `Subscription` is a plain value: a closure that receives a `when`
+ * function and registers listeners through it. The closure binds late —
+ * at registration the App passes its own runtime's `when`, so each
+ * subscription targets the right runtime. No ambient state, no
+ * side-effect imports, multi-app safe.
+ *
+ *   // app/listeners/welcome-mail.ts
+ *   import { subscribe } from "@nwire/app";
+ *   import { UserRegistered } from "../events";
+ *
+ *   export default subscribe((when) => {
+ *     when(UserRegistered, async (payload, env) => {
+ *       await sendWelcomeEmail(payload.email);
+ *     });
+ *   });
+ *
+ * Subscriptions are registered through `app.subscribe(sub | subs)`.
+ */
+import type { EventDefinition } from "@nwire/messages";
+import type { MessageEnvelope } from "@nwire/envelope";
+/**
+ * Late-bound listener registration handed to a subscribe closure.
+ */
+export type WhenFn = <TPayload>(event: EventDefinition & {
+    readonly name: string;
+}, fn: (payload: TPayload, envelope: MessageEnvelope) => Promise<void> | void) => void;
+/**
+ * A subscription is a closure waiting for an App's `when` to be handed in.
+ * `install(when)` is the contract: the App passes its runtime's `when` and
+ * the closure registers everything it knows.
+ */
+export interface Subscription {
+    readonly $kind: "subscription";
+    install(when: WhenFn): void;
+}
+/**
+ * Wrap a registration closure as a Subscription value. The closure is
+ * held by reference — when an App later `subscribe(sub)`s it, the closure
+ * runs with the App's `when` injected.
+ */
+export declare function subscribe(fn: (when: WhenFn) => void): Subscription;
+/** True if `value` looks like a Subscription. */
+export declare function isSubscription(value: unknown): value is Subscription;

package/dist/subscribe.js

@@ -0,0 +1,39 @@
+/**
+ * `subscribe((when) => …)` — the listener primitive.
+ *
+ * A `Subscription` is a plain value: a closure that receives a `when`
+ * function and registers listeners through it. The closure binds late —
+ * at registration the App passes its own runtime's `when`, so each
+ * subscription targets the right runtime. No ambient state, no
+ * side-effect imports, multi-app safe.
+ *
+ *   // app/listeners/welcome-mail.ts
+ *   import { subscribe } from "@nwire/app";
+ *   import { UserRegistered } from "../events";
+ *
+ *   export default subscribe((when) => {
+ *     when(UserRegistered, async (payload, env) => {
+ *       await sendWelcomeEmail(payload.email);
+ *     });
+ *   });
+ *
+ * Subscriptions are registered through `app.subscribe(sub | subs)`.
+ */
+/**
+ * Wrap a registration closure as a Subscription value. The closure is
+ * held by reference — when an App later `subscribe(sub)`s it, the closure
+ * runs with the App's `when` injected.
+ */
+export function subscribe(fn) {
+    return {
+        $kind: "subscription",
+        install: fn,
+    };
+}
+/** True if `value` looks like a Subscription. */
+export function isSubscription(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.$kind === "subscription" &&
+        typeof value.install === "function");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/app",
-  "version": "0.10.1",
+  "version": "0.11.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.",
   "keywords": [
     "app",
@@ -29,13 +29,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@nwire/container": "0.10.1",
-    "@nwire/envelope": "0.10.1",
-    "@nwire/handler": "0.10.1",
-    "@nwire/wires": "0.10.1",
-    "@nwire/messages": "0.10.1",
-    "@nwire/logger": "0.10.1",
-    "@nwire/hooks": "0.10.1"
+    "@nwire/container": "0.11.0",
+    "@nwire/envelope": "0.11.0",
+    "@nwire/hooks": "0.11.0",
+    "@nwire/handler": "0.11.0",
+    "@nwire/logger": "0.11.0",
+    "@nwire/runtime": "0.11.0",
+    "@nwire/messages": "0.11.0",
+    "@nwire/wires": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",