@nwire/app 0.7.0

package/dist/define-plugin.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `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.
+ */
+import type { Container } from "@nwire/container";
+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>;
+}
+/**
+ * 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

package/dist/define-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-plugin.d.ts","sourceRoot":"","sources":["../src/define-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAItF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACvB,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,WAAW,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9C;AAID;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE/D;;;;OAIG;IACH,EAAE,CAAC,QAAQ,EACT,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EACzC,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EACxC,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAAC;IAER;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CAChD;AAID;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACrD,mBAAmB,CAMrB;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,mBAAmB,CAMhE"}

package/dist/define-plugin.js

@@ -0,0 +1,72 @@
+/**
+ * `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.
+ */
+// ─── 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) {
+    return {
+        $nwireAppPlugin: true,
+        name,
+        setup,
+    };
+}
+/** Type guard — does this look like an app-layer plugin definition? */
+export function isAppPlugin(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        x.$nwireAppPlugin === true);
+}
+//# sourceMappingURL=define-plugin.js.map

package/dist/define-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-plugin.js","sourceRoot":"","sources":["../src/define-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA8GH,qEAAqE;AAErE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,KAAsD;IAEtD,OAAO;QACL,eAAe,EAAE,IAAI;QACrB,IAAI;QACJ,KAAK;KACN,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAmC,CAAC,eAAe,KAAK,IAAI,CAC9D,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,89 @@
+/**
+ * `FrameworkEventBus` — the dispatcher behind framework events.
+ *
+ * Owned by an app's runtime. One bus per app instance. Plugins, apps,
+ * and modules subscribe with `bus.on(Event, handler)`; the runtime fires
+ * events at the appropriate lifecycle points with `bus.fire(Event, payload)`.
+ *
+ * Dispatch semantics come from the event's `mode`:
+ *
+ *   parallel    → all handlers concurrently; one failing doesn't affect
+ *                 others; errors are logged via the supplied logger.
+ *   series      → sequential await; one failing stops the chain and throws.
+ *   series-bail → sequential await; a handler returning `false` stops the
+ *                 chain cleanly (no throw) and `fire` returns false to
+ *                 signal "prevented". Returning anything else (including
+ *                 undefined/void) is treated as "ok, continue".
+ *
+ * The series-bail mode is the interceptable hook — `*-ing` events use it
+ * so plugins can veto an action, refuse a shutdown, etc.
+ *
+ * The bus lives in `@nwire/app` (the "managed Container with lifecycle"
+ * layer). `@nwire/forge` re-exports the same surface so consumers that
+ * pull from forge get one import line.
+ */
+import type { FrameworkEventDefinition } from "./framework-events.js";
+import type { Logger } from "@nwire/logger";
+/**
+ * Handler signature. The handler MAY:
+ *   - return nothing                            → "continue"
+ *   - return false                              → "prevent" (series-bail only)
+ *   - return a Promise resolving to either
+ *   - throw                                     → "fail" (propagates in series modes,
+ *                                                  logged-and-swallowed in parallel)
+ *
+ * In parallel/series modes the return value is ignored entirely.
+ */
+export type FrameworkEventHandler<TPayload> = (payload: TPayload) => Promise<void | boolean> | void | boolean;
+/**
+ * Per-fire observer — receives every framework-event firing on the bus.
+ * Used by the dev logger, Studio Live stream, and OTel exporter to surface
+ * lifecycle activity without each one re-subscribing per event type.
+ *
+ *   `phase: "fired"`     — handler chain completed without a veto.
+ *   `phase: "prevented"` — a series-bail handler returned false.
+ */
+export interface FrameworkEventObservation {
+    readonly eventName: string;
+    readonly payload: unknown;
+    readonly mode: "parallel" | "series" | "series-bail";
+    readonly phase: "fired" | "prevented";
+    readonly ts: string;
+}
+export type FrameworkEventObserver = (record: FrameworkEventObservation) => void;
+/**
+ * The bus. Subscriptions and dispatch live here so an app's runtime stays
+ * focused on the domain pipeline. Designed to be reusable — Studio, the
+ * orchestrator, and external plugins all hit the same surface.
+ */
+export declare class FrameworkEventBus {
+    private readonly subs;
+    private readonly observers;
+    private readonly logger;
+    constructor(logger: Logger);
+    /**
+     * Subscribe to EVERY framework-event firing on this bus. Used by the
+     * dev logger, Studio Live, and OTel exporter to surface lifecycle
+     * activity without each one re-subscribing per event type.
+     *
+     * Returns an unsubscribe handle.
+     */
+    onFire(observer: FrameworkEventObserver): () => void;
+    private notify;
+    /**
+     * Subscribe to a framework event. `priority` controls ordering for
+     * series-bail / series modes (higher runs first; default 0). Framework
+     * built-ins should subscribe at priority 100+; debug/observer plugins
+     * at -100 so they see the final post-mutation state.
+     */
+    on<TPayload>(event: FrameworkEventDefinition<TPayload>, handler: FrameworkEventHandler<TPayload>, priority?: number): () => void;
+    /**
+     * Fire a framework event. Resolves to `false` when a series-bail handler
+     * vetoed; `true` otherwise. The boolean is irrelevant for parallel /
+     * series modes and always returns `true` there for them.
+     */
+    fire<TPayload>(event: FrameworkEventDefinition<TPayload>, payload: TPayload): Promise<boolean>;
+    /** Count subscribers for an event — diagnostic surface (Studio, tests). */
+    subscriberCount(event: FrameworkEventDefinition): number;
+}
+//# sourceMappingURL=framework-event-bus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"framework-event-bus.d.ts","sourceRoot":"","sources":["../src/framework-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,CAAC,QAAQ,IAAI,CAC5C,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC;AAO9C;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AACD,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,yBAAyB,KAAK,IAAI,CAAC;AAEjF;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8C;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM;IAI1B;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAQpD,OAAO,CAAC,MAAM;IAgBd;;;;;OAKG;IACH,EAAE,CAAC,QAAQ,EACT,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EACzC,OAAO,EAAE,qBAAqB,CAAC,QAAQ,CAAC,EACxC,QAAQ,GAAE,MAAU,GACnB,MAAM,IAAI;IAgBb;;;;OAIG;IACG,IAAI,CAAC,QAAQ,EACjB,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EACzC,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;IA8DnB,2EAA2E;IAC3E,eAAe,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM;CAGzD"}

package/dist/framework-event-bus.js

@@ -0,0 +1,154 @@
+/**
+ * `FrameworkEventBus` — the dispatcher behind framework events.
+ *
+ * Owned by an app's runtime. One bus per app instance. Plugins, apps,
+ * and modules subscribe with `bus.on(Event, handler)`; the runtime fires
+ * events at the appropriate lifecycle points with `bus.fire(Event, payload)`.
+ *
+ * Dispatch semantics come from the event's `mode`:
+ *
+ *   parallel    → all handlers concurrently; one failing doesn't affect
+ *                 others; errors are logged via the supplied logger.
+ *   series      → sequential await; one failing stops the chain and throws.
+ *   series-bail → sequential await; a handler returning `false` stops the
+ *                 chain cleanly (no throw) and `fire` returns false to
+ *                 signal "prevented". Returning anything else (including
+ *                 undefined/void) is treated as "ok, continue".
+ *
+ * The series-bail mode is the interceptable hook — `*-ing` events use it
+ * so plugins can veto an action, refuse a shutdown, etc.
+ *
+ * The bus lives in `@nwire/app` (the "managed Container with lifecycle"
+ * layer). `@nwire/forge` re-exports the same surface so consumers that
+ * pull from forge get one import line.
+ */
+/**
+ * The bus. Subscriptions and dispatch live here so an app's runtime stays
+ * focused on the domain pipeline. Designed to be reusable — Studio, the
+ * orchestrator, and external plugins all hit the same surface.
+ */
+export class FrameworkEventBus {
+    subs = new Map();
+    observers = [];
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Subscribe to EVERY framework-event firing on this bus. Used by the
+     * dev logger, Studio Live, and OTel exporter to surface lifecycle
+     * activity without each one re-subscribing per event type.
+     *
+     * Returns an unsubscribe handle.
+     */
+    onFire(observer) {
+        this.observers.push(observer);
+        return () => {
+            const i = this.observers.indexOf(observer);
+            if (i >= 0)
+                this.observers.splice(i, 1);
+        };
+    }
+    notify(rec) {
+        // Observers run after the actual fire — they MUST NOT veto or alter
+        // semantics. Errors are swallowed + logged so a buggy observer can't
+        // break the lifecycle.
+        for (const o of this.observers) {
+            try {
+                o(rec);
+            }
+            catch (err) {
+                this.logger.error?.("framework-event observer threw", {
+                    event: rec.eventName,
+                    error: err?.message ?? String(err),
+                });
+            }
+        }
+    }
+    /**
+     * Subscribe to a framework event. `priority` controls ordering for
+     * series-bail / series modes (higher runs first; default 0). Framework
+     * built-ins should subscribe at priority 100+; debug/observer plugins
+     * at -100 so they see the final post-mutation state.
+     */
+    on(event, handler, priority = 0) {
+        const list = this.subs.get(event.name) ?? [];
+        const sub = { handler, priority };
+        list.push(sub);
+        // Sort by priority desc so higher-priority handlers run first.
+        list.sort((a, b) => b.priority - a.priority);
+        this.subs.set(event.name, list);
+        return () => {
+            const current = this.subs.get(event.name);
+            if (!current)
+                return;
+            const i = current.indexOf(sub);
+            if (i >= 0)
+                current.splice(i, 1);
+        };
+    }
+    /**
+     * Fire a framework event. Resolves to `false` when a series-bail handler
+     * vetoed; `true` otherwise. The boolean is irrelevant for parallel /
+     * series modes and always returns `true` there for them.
+     */
+    async fire(event, payload) {
+        const handlers = (this.subs.get(event.name) ?? []);
+        // Always notify observers — even when no subscribers exist for this
+        // event. The lifecycle is the signal worth recording; subscribers are
+        // an orthogonal concern (could be none in dev, several in prod).
+        const ts = new Date().toISOString();
+        const obsRec = (phase) => ({
+            eventName: event.name,
+            payload,
+            mode: event.mode,
+            phase,
+            ts,
+        });
+        if (handlers.length === 0) {
+            this.notify(obsRec("fired"));
+            return true;
+        }
+        switch (event.mode) {
+            case "parallel": {
+                const settled = await Promise.allSettled(handlers.map(({ handler }) => Promise.resolve().then(() => handler(payload))));
+                for (const r of settled) {
+                    if (r.status === "rejected") {
+                        this.logger.error?.("framework-event handler threw (parallel)", {
+                            event: event.name,
+                            error: r.reason?.message ?? String(r.reason),
+                        });
+                    }
+                }
+                this.notify(obsRec("fired"));
+                return true;
+            }
+            case "series": {
+                for (const { handler } of handlers) {
+                    await handler(payload);
+                }
+                this.notify(obsRec("fired"));
+                return true;
+            }
+            case "series-bail": {
+                for (const { handler } of handlers) {
+                    const result = await handler(payload);
+                    if (result === false) {
+                        this.logger.info?.("framework-event prevented by handler", {
+                            event: event.name,
+                        });
+                        this.notify(obsRec("prevented"));
+                        return false;
+                    }
+                }
+                this.notify(obsRec("fired"));
+                return true;
+            }
+        }
+    }
+    /** Count subscribers for an event — diagnostic surface (Studio, tests). */
+    subscriberCount(event) {
+        return this.subs.get(event.name)?.length ?? 0;
+    }
+}
+//# sourceMappingURL=framework-event-bus.js.map

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

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