@nwire/app 0.9.2 → 0.10.1

package/dist/create-app.js

@@ -1,231 +1,57 @@
 /**
- * `createApp` — generic plugin-lifecycle composition root.
- *
- * Boots a Container + a FrameworkEventBus with the supplied plugins.
- * Lightweight: no forge concepts (no Runtime, no actors, no workflows,
- * no module dep graph). For the full forge experience use `createApp`
- * from `@nwire/forge`, which composes on top of this primitive.
- *
- * What this does, in order, during `start()`:
- *
- *   1. Register every plugin synchronously — `setup(ctx)` runs; bindings
- *      declared via `ctx.provide()` are collected; framework subscriptions
- *      via `ctx.on()` are wired on the bus; boot/shutdown callbacks are
- *      captured into ordered lists.
- *   2. Fire `AppRegistering` (series-bail). A vetoing subscriber aborts.
- *   3. Boot every provided binding: call `lifecycle.boot()`, register the
- *      value on the container under its declared name. Failures abort.
- *   4. Fire `AppBooting` (series-bail). A vetoing subscriber aborts.
- *   5. Run each plugin's accumulated `boot` callbacks in registration order.
- *   6. Fire `AppBooted` (parallel).
- *
- * `stop(reason?)`:
- *
- *   1. Fire `AppShuttingDown` (series-bail).
- *   2. Run plugin `shutdown` callbacks in REVERSE registration order.
- *   3. Call `lifecycle.shutdown(value)` on each provided binding (reverse).
- *   4. Fire `AppShutdown` (parallel).
- *
- * The returned `App` satisfies `AppServable` from `@nwire/endpoint`, so
- * `endpoint("api").serve(app).run()` works without any glue.
+ * `createApp` — composition root. Constructs a Runtime, registers
+ * plugins, and exposes the lifecycle the runtime owns.
  */
-import { createContainer } from "@nwire/container";
+import { createContainer } from "@nwire/container/awilix";
 import { NoopLogger } from "@nwire/logger";
-import { AppRegistering, AppBooting, AppBooted, AppReady, AppShuttingDown, AppShutdown, PluginRegistered, PluginBooting, PluginBooted, PluginShuttingDown, PluginShutdown, } from "./framework-events.js";
-import { FrameworkEventBus } from "./framework-event-bus.js";
-/**
- * Build a generic Nwire app from plugin definitions. No forge concepts —
- * use `@nwire/forge`'s `createApp` for the rich CQRS / actor / workflow
- * surface.
- *
- *   const app = createApp({
- *     appName: "users",
- *     plugins: [authPlugin, dbPlugin],
- *   });
- *   await app.start();
- *   // app.container.cradle.db is now resolvable
- *   await app.stop();
- */
+import { createInterface, } from "@nwire/wires";
+import { createRuntime } from "./runtime/index.js";
 export function createApp(options) {
     const appName = options.appName;
     const container = options.container ?? createContainer();
     const logger = options.logger ?? new NoopLogger();
-    const bus = options.bus ?? new FrameworkEventBus(logger);
+    const runtime = options.runtime ?? createRuntime({ container, logger, appName });
     const plugins = options.plugins ?? [];
-    /**
-     * Captured per plugin during setup. Indexed by the plugin's position in
-     * `plugins` so the start/stop loops can re-associate.
-     */
-    const provides = [];
-    const boots = [];
-    const shutdowns = [];
-    /** Booted provider values, indexed by their `name`. Populated in start(). */
-    const bootedValues = new Map();
-    // ─── 1. Synchronous register: run each plugin's setup closure now ─────
-    // Plugins contribute container bindings, framework subscriptions, and
-    // boot/shutdown callbacks via the captured-builder pattern.
-    plugins.forEach((plugin, pluginIdx) => {
-        const ctx = {
-            container,
-            bus,
-            provide(name, lifecycle) {
-                provides.push({
-                    pluginIdx,
-                    name,
-                    lifecycle: lifecycle,
-                });
-            },
-            on(event, handler, priority) {
-                bus.on(event, handler, priority);
-            },
-            boot(fn) {
-                boots.push({ pluginIdx, fn });
-            },
-            shutdown(fn) {
-                shutdowns.push({ pluginIdx, fn });
-            },
-        };
-        // setup may be sync or async — we await during start(), not here, so
-        // the constructor returns immediately. Defer the call: setup returns
-        // a value/promise that start() awaits.
-        plugin.setup(ctx);
-    });
-    let started = false;
-    let stopped = false;
-    const start = async () => {
-        if (started)
-            return;
-        started = true;
-        // Per-plugin registered event — observable; no veto.
-        for (const plugin of plugins) {
-            await bus.fire(PluginRegistered, {
-                appName,
-                pluginName: plugin.name,
-                kind: "plugin",
-            });
-        }
-        // AppRegistering — interceptable.
-        const okReg = await bus.fire(AppRegistering, { appName });
-        if (!okReg) {
-            throw new Error(`createApp("${appName}"): AppRegistering vetoed by subscriber`);
-        }
-        // 2. Boot every provided binding; register the value on the container.
-        for (const { name, lifecycle } of provides) {
-            const value = await lifecycle.boot();
-            container.register(name, value);
-            bootedValues.set(name, value);
-        }
-        // 3. AppBooting — interceptable.
-        const okBoot = await bus.fire(AppBooting, { appName });
-        if (!okBoot) {
-            throw new Error(`createApp("${appName}"): AppBooting vetoed by subscriber`);
-        }
-        // 4. Per-plugin boot — interceptable + observed per plugin.
-        for (const { pluginIdx, fn } of boots) {
-            const plugin = plugins[pluginIdx];
-            const okPlug = await bus.fire(PluginBooting, {
-                appName,
-                pluginName: plugin.name,
-                kind: "plugin",
-            });
-            if (!okPlug) {
-                throw new Error(`createApp("${appName}"): plugin "${plugin.name}" boot vetoed by subscriber`);
-            }
-            const startedAt = performance.now();
-            await fn();
-            await bus.fire(PluginBooted, {
-                appName,
-                pluginName: plugin.name,
-                durationMs: performance.now() - startedAt,
-                kind: "plugin",
-            });
-        }
-        // 5. AppBooted — parallel observation.
-        await bus.fire(AppBooted, {
-            appName,
-            bootedAt: new Date().toISOString(),
-        });
-        // 6. AppReady — parallel observation. Endpoint fires this after the
-        // wire is listening; we fire here too for the standalone case.
-        await bus.fire(AppReady, {
-            appName,
-            readyAt: new Date().toISOString(),
-        });
-    };
-    const stop = async (reason) => {
-        if (stopped)
-            return;
-        stopped = true;
-        // AppShuttingDown — interceptable. Throwing fails the shutdown; the
-        // caller is responsible for hard-timeout SIGKILL via @nwire/endpoint.
-        await bus.fire(AppShuttingDown, { appName, reason });
-        // 1. Plugin shutdown callbacks (reverse registration order).
-        for (let i = shutdowns.length - 1; i >= 0; i--) {
-            const { pluginIdx, fn } = shutdowns[i];
-            const plugin = plugins[pluginIdx];
-            await bus.fire(PluginShuttingDown, {
-                appName,
-                pluginName: plugin.name,
-                kind: "plugin",
-            });
-            const startedAt = performance.now();
-            try {
-                await fn();
-            }
-            catch (err) {
-                logger.error?.(`plugin "${plugin.name}" shutdown threw`, {
-                    error: err?.message ?? String(err),
-                });
-            }
-            await bus.fire(PluginShutdown, {
-                appName,
-                pluginName: plugin.name,
-                durationMs: performance.now() - startedAt,
-                kind: "plugin",
-            });
-        }
-        // 2. Provided-binding shutdowns (reverse boot order).
-        for (let i = provides.length - 1; i >= 0; i--) {
-            const { name, lifecycle } = provides[i];
-            if (!lifecycle.shutdown)
-                continue;
-            const value = bootedValues.get(name);
-            if (value === undefined)
-                continue;
-            try {
-                await lifecycle.shutdown(value);
-            }
-            catch (err) {
-                logger.error?.(`provider "${name}" shutdown threw`, {
-                    error: err?.message ?? String(err),
-                });
-            }
-        }
-        // 3. AppShutdown — parallel observation.
-        await bus.fire(AppShutdown, { appName });
-    };
-    return {
+    const iface = createInterface();
+    for (const h of options.handlers ?? []) {
+        runtime.registerHandler(h);
+    }
+    for (const p of plugins) {
+        runtime.registerPlugin(p);
+    }
+    const app = {
         $nwireApp: true,
+        $kind: "app",
         appName,
+        name: appName,
         container,
-        bus,
+        runtime,
+        interface: iface,
         plugins,
-        start,
-        stop,
-        boot: start,
-        shutdown: () => stop(),
-        dispatchFrameworkEvent: async (eventName, payload) => {
-            // Generic dispatch by name — used by @nwire/endpoint to fire
-            // wire-lifecycle events the bus has built-ins for. We look up the
-            // event in builtInLifecycleEvents; unknown names fire as parallel.
-            const { builtInLifecycleEvents } = await import("./framework-events.js");
-            const def = builtInLifecycleEvents.find((e) => e.name === eventName);
-            if (def)
-                return bus.fire(def, payload);
-            // Unknown event name — fire as a synthetic parallel event so observers
-            // still see it on the bus.
-            return bus.fire({ $kind: "framework-event", name: eventName, mode: "parallel" }, payload);
+        wire(binding, handler) {
+            iface.wire(binding, handler);
+            // Tag the just-appended wire with its source app so adopters can
+            // resolve `containerOf(wire)` back to this app's container.
+            const appended = iface.wires[iface.wires.length - 1];
+            appended.app = app;
+            return app;
+        },
+        provide(builder) {
+            iface.provide(builder);
+            return app;
+        },
+        start: () => runtime.start(),
+        stop: (reason) => runtime.stop(reason),
+        boot: () => runtime.start(),
+        shutdown: () => runtime.stop(),
+        dispatchFrameworkEvent: async (slot, payload) => {
+            const hooks = runtime.hooks;
+            const h = hooks[slot];
+            if (!h)
+                return true;
+            const result = await h.runDetailed(payload);
+            return result.outcome === "completed";
         },
     };
+    return app;
 }
-//# sourceMappingURL=create-app.js.map

package/dist/define-plugin.d.ts

@@ -1,153 +1,14 @@
 /**
- * `definePlugin` — the narrow, generic plugin primitive for `@nwire/app`.
- *
- * Plugins are the ONLY extension primitive in the sealed architecture.
- * They install once, run during app lifecycle, and contribute three things:
- *
- *   1. **Container bindings** via `provide(name, lifecycle)` — bootable
- *      values (DB pool, Redis client, HTTP client, anything that needs
- *      `boot()` + optional `shutdown()` + optional `healthCheck()`).
- *   2. **Event subscriptions** via `on(FrameworkEvent, handler, priority?)`
- *      — react to app lifecycle, custom events, or anything else fired
- *      through the FrameworkEventBus.
- *   3. **Lifecycle callbacks** via `boot(fn)` + `shutdown(fn)` — async
- *      work at known transitions (post-provider-boot, pre-shutdown).
- *
- * This narrow shape covers 100% of "extend the app" cases that don't
- * need forge-specific knowledge. For plugins that need action middleware,
- * actor lifecycle hooks, or `before("action.name", ...)` sugar, use the
- * richer `definePlugin` in `@nwire/forge` — it's a superset that wraps
- * this one.
- *
- * ## When to reach for this vs forge's
- *
- *   - Connecting a database / cache / queue / SDK? → this one.
- *   - Tracing every dispatched action? → forge's (needs middleware).
- *   - Reacting to a workflow saga timer? → forge's (needs actor hooks).
- *   - Multi-tenant request context propagation? → forge's (needs middleware).
- *   - Custom framework events fired by your own code? → this one.
- *
- * In other words: if you don't need to peek inside action dispatch or
- * actor transitions, you don't need forge's plugin form. Use this one.
+ * 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.
  */
-import type { Container } from "@nwire/container";
 import { type SourceLocation } from "@nwire/messages";
-import type { FrameworkEventDefinition } from "./framework-events.js";
-import type { FrameworkEventBus, FrameworkEventHandler } from "./framework-event-bus.js";
-/**
- * Describes a value the plugin produces. The framework calls `boot()` to
- * obtain it during app start, registers it on the container under the
- * plugin's chosen name, calls `healthCheck` periodically (if provided),
- * and calls `shutdown(value)` during graceful drain.
- */
-export interface BindingLifecycle<T> {
-    boot(): Promise<T> | T;
-    shutdown?(value: T): Promise<void> | void;
-    healthCheck?(value: T): Promise<void> | void;
-}
-/**
- * What the setup closure gets. Every method is a builder — each call
- * accrues into the plugin's contribution to the app's lifecycle. There's
- * no separate "apply" step; the framework collects everything the closure
- * does and threads it into the right lifecycle phases.
- */
-export interface AppPluginContext {
-    /**
-     * The app's container. Read-only here; the plugin contributes bindings
-     * via `provide()`, not by writing to the container directly. This
-     * reference is exposed for the rare case where the plugin needs to
-     * inspect existing bindings (e.g., feature detection).
-     */
-    readonly container: Container;
-    /**
-     * The app's framework-event bus. Exposed for advanced cases; most
-     * subscriptions go through `on()` for ergonomic registration.
-     */
-    readonly bus: FrameworkEventBus;
-    /**
-     * Register a bootable binding. The framework calls `lifecycle.boot()`
-     * during app start, stores the result on the container under `name`,
-     * and wires `shutdown` + `healthCheck` into the lifecycle.
-     *
-     * ```ts
-     * provide("db", {
-     *   boot:        () => new Pool(env.DATABASE_URL),
-     *   shutdown:    (pool) => pool.end(),
-     *   healthCheck: (pool) => pool.query("SELECT 1"),
-     * })
-     * ```
-     */
-    provide<T>(name: string, lifecycle: BindingLifecycle<T>): void;
-    /**
-     * Subscribe to a framework event. Higher priorities run earlier in
-     * series/series-bail modes (default 0; framework built-ins should use
-     * 100+; debug/observer plugins -100).
-     */
-    on<TPayload>(event: FrameworkEventDefinition<TPayload>, handler: FrameworkEventHandler<TPayload>, priority?: number): void;
-    /**
-     * Register a callback that runs once during app boot, after all
-     * provided bindings are registered and other plugins' `boot` callbacks
-     * have run. Use for warm-up work: prefetching, idempotency caches,
-     * pre-flight connectivity checks beyond the basic healthCheck.
-     */
-    boot(fn: () => Promise<void> | void): void;
-    /**
-     * Register a callback that runs during graceful shutdown, BEFORE
-     * provided bindings' `shutdown(value)` callbacks. Use for "flush pending
-     * work" style cleanup — finalizing analytics events, draining queues
-     * the plugin owns directly, etc.
-     */
-    shutdown(fn: () => Promise<void> | void): void;
-}
-/**
- * What the framework receives. Opaque to user code — it carries the setup
- * function the app's lifecycle will invoke during boot, plus identity
- * metadata for diagnostics.
- *
- * Note the `$nwireAppPlugin: true` marker — lets the runtime discriminate
- * this from forge's richer `PluginDefinition` (which has its own marker).
- * Both shapes can be used in the same app's plugin list; the runtime
- * dispatches each through the right wiring path.
- */
-export interface AppPluginDefinition {
-    readonly $nwireAppPlugin: true;
-    readonly name: string;
-    /**
-     * The setup closure. The framework calls this during plugin
-     * registration with an `AppPluginContext` bound to the app's container
-     * + bus. Returns void or a Promise; if async, the framework awaits
-     * before proceeding to provider boot.
-     */
-    readonly setup: (ctx: AppPluginContext) => void | Promise<void>;
-    /** Call-site of `definePlugin(...)` — Studio + scan render this. */
+import type { PluginContext, PluginDefinition } from "./runtime/index.js";
+export declare function definePlugin(name: string, setup: (ctx: PluginContext) => void): PluginDefinition & {
     readonly $source?: SourceLocation;
-}
-/**
- * Build a plugin. The returned value is opaque — pass it to your app's
- * plugin list. The framework invokes the setup closure once during boot
- * with a context bound to the app's container + bus.
- *
- * ```ts
- * import { definePlugin } from "@nwire/app"
- * import { AppBooted } from "@nwire/app"
- *
- * export const tracingPlugin = definePlugin("tracing", ({ provide, on, boot }) => {
- *   provide("tracer", {
- *     boot:     () => new OtelTracer({ exporter: process.env.OTEL_ENDPOINT }),
- *     shutdown: (t) => t.shutdown(),
- *   })
- *
- *   on(AppBooted, ({ appName }) => {
- *     console.log(`tracing started for ${appName}`)
- *   })
- *
- *   boot(async () => {
- *     // warm up — initialize span context, register process exit handlers, …
- *   })
- * })
- * ```
- */
-export declare function definePlugin(name: string, setup: (ctx: AppPluginContext) => void | Promise<void>): AppPluginDefinition;
-/** Type guard — does this look like an app-layer plugin definition? */
-export declare function isAppPlugin(x: unknown): x is AppPluginDefinition;
-//# sourceMappingURL=define-plugin.d.ts.map
+};
+/** Discriminator for runtime-side checks. */
+export declare function isPlugin(x: unknown): x is PluginDefinition;

package/dist/define-plugin.js

@@ -1,74 +1,23 @@
 /**
- * `definePlugin` — the narrow, generic plugin primitive for `@nwire/app`.
- *
- * Plugins are the ONLY extension primitive in the sealed architecture.
- * They install once, run during app lifecycle, and contribute three things:
- *
- *   1. **Container bindings** via `provide(name, lifecycle)` — bootable
- *      values (DB pool, Redis client, HTTP client, anything that needs
- *      `boot()` + optional `shutdown()` + optional `healthCheck()`).
- *   2. **Event subscriptions** via `on(FrameworkEvent, handler, priority?)`
- *      — react to app lifecycle, custom events, or anything else fired
- *      through the FrameworkEventBus.
- *   3. **Lifecycle callbacks** via `boot(fn)` + `shutdown(fn)` — async
- *      work at known transitions (post-provider-boot, pre-shutdown).
- *
- * This narrow shape covers 100% of "extend the app" cases that don't
- * need forge-specific knowledge. For plugins that need action middleware,
- * actor lifecycle hooks, or `before("action.name", ...)` sugar, use the
- * richer `definePlugin` in `@nwire/forge` — it's a superset that wraps
- * this one.
- *
- * ## When to reach for this vs forge's
- *
- *   - Connecting a database / cache / queue / SDK? → this one.
- *   - Tracing every dispatched action? → forge's (needs middleware).
- *   - Reacting to a workflow saga timer? → forge's (needs actor hooks).
- *   - Multi-tenant request context propagation? → forge's (needs middleware).
- *   - Custom framework events fired by your own code? → this one.
- *
- * In other words: if you don't need to peek inside action dispatch or
- * actor transitions, you don't need forge's plugin form. Use this one.
+ * 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.
  */
 import { captureSourceLocation } from "@nwire/messages";
-// ─── The factory ──────────────────────────────────────────────────
-/**
- * Build a plugin. The returned value is opaque — pass it to your app's
- * plugin list. The framework invokes the setup closure once during boot
- * with a context bound to the app's container + bus.
- *
- * ```ts
- * import { definePlugin } from "@nwire/app"
- * import { AppBooted } from "@nwire/app"
- *
- * export const tracingPlugin = definePlugin("tracing", ({ provide, on, boot }) => {
- *   provide("tracer", {
- *     boot:     () => new OtelTracer({ exporter: process.env.OTEL_ENDPOINT }),
- *     shutdown: (t) => t.shutdown(),
- *   })
- *
- *   on(AppBooted, ({ appName }) => {
- *     console.log(`tracing started for ${appName}`)
- *   })
- *
- *   boot(async () => {
- *     // warm up — initialize span context, register process exit handlers, …
- *   })
- * })
- * ```
- */
 export function definePlugin(name, setup) {
+    const $source = captureSourceLocation();
     return {
-        $nwireAppPlugin: true,
         name,
         setup,
-        $source: captureSourceLocation(),
+        $source,
     };
 }
-/** Type guard — does this look like an app-layer plugin definition? */
-export function isAppPlugin(x) {
+/** Discriminator for runtime-side checks. */
+export function isPlugin(x) {
     return (typeof x === "object" &&
         x !== null &&
-        x.$nwireAppPlugin === true);
+        typeof x.name === "string" &&
+        typeof x.setup === "function");
 }
-//# sourceMappingURL=define-plugin.js.map

package/dist/runtime/framework-hooks.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Per-runtime framework-hook registry. Each slot is a `Hook<TPayload>`
+ * accessed as a typed property on `runtime.hooks`. Plugins extend via
+ * TS module augmentation + `runtime.defineHook(name)`.
+ */
+import { type Hook } from "@nwire/hooks";
+/**
+ * Plugins can distinguish "module compiled onto plugin lifecycle" from a
+ * normal plugin. Lifecycle payloads include this so observers can filter.
+ */
+export type PluginKind = "plugin" | "module";
+/**
+ * The typed registry. Plugin packages augment this interface to add their
+ * own slots; the foundation contributes the lifecycle slots below.
+ *
+ * Every slot is `Hook<TPayload>` — no dispatch-mode discriminator.
+ * Consumers call `.use()` to participate in the chain (with optional veto
+ * via not calling `next()`), `.on()` to observe in parallel, `.tap()` to
+ * receive step-level telemetry.
+ */
+export interface FrameworkHooks {
+    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;
+    }>;
+    WireMounting: Hook<{
+        readonly appName: string;
+        readonly transport: string;
+        readonly manifest: unknown;
+    }>;
+    WireMounted: Hook<{
+        readonly appName: string;
+        readonly transport: string;
+        readonly manifest: unknown;
+    }>;
+    WireUnmounted: Hook<{
+        readonly appName: string;
+        readonly transport: string;
+    }>;
+}
+/** Canonical names for the built-in slots — used to label the underlying Hooks. */
+declare const BUILT_IN_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";
+    readonly WireMounting: "nwire.wire.mounting";
+    readonly WireMounted: "nwire.wire.mounted";
+    readonly WireUnmounted: "nwire.wire.unmounted";
+};
+/**
+ * Construct the per-runtime registry, with every built-in slot
+ * pre-instantiated. Plugin slots added via `runtime.defineHook(name)`
+ * land on the same registry instance.
+ */
+export declare function createFrameworkHooks(): FrameworkHooks;
+/** True if `slot` is one of the built-in hook keys. */
+export declare function isBuiltInHook(slot: string): slot is keyof typeof BUILT_IN_HOOK_NAMES;
+export {};

package/dist/runtime/framework-hooks.js

@@ -0,0 +1,39 @@
+/**
+ * Per-runtime framework-hook registry. Each slot is a `Hook<TPayload>`
+ * accessed as a typed property on `runtime.hooks`. Plugins extend via
+ * TS module augmentation + `runtime.defineHook(name)`.
+ */
+import { hook } from "@nwire/hooks";
+/** Canonical names for the built-in slots — used to label the underlying Hooks. */
+const BUILT_IN_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",
+    WireMounting: "nwire.wire.mounting",
+    WireMounted: "nwire.wire.mounted",
+    WireUnmounted: "nwire.wire.unmounted",
+};
+/**
+ * Construct the per-runtime registry, with every built-in slot
+ * pre-instantiated. Plugin slots added via `runtime.defineHook(name)`
+ * land on the same registry instance.
+ */
+export function createFrameworkHooks() {
+    const registry = {};
+    for (const [slot, name] of Object.entries(BUILT_IN_HOOK_NAMES)) {
+        registry[slot] = hook(name);
+    }
+    return registry;
+}
+/** True if `slot` is one of the built-in hook keys. */
+export function isBuiltInHook(slot) {
+    return slot in BUILT_IN_HOOK_NAMES;
+}