@nwire/forge 0.9.1 → 0.10.0

package/dist/create-app.js

@@ -1,703 +0,0 @@
-/**
- * `createApp` — declarative app composition.
- *
- *   const app = createApp({
- *     modules:   [submissions, enrollments],
- *     actorStore: new InMemoryActorStore(),
- *     projectionStore: new InMemoryProjectionStore()
- *   })
- *   await app.start()
- *
- * `createApp` walks each module's manifest and registers actions, actors,
- * handlers, projections, queries, and workflows into a fresh `Runtime`.
- * The runtime is exposed for transports (HTTP, queue, cron) to bind to.
- *
- * Transports are NOT bundled here yet — for now, wires hand-attach Koa
- * routers using `createDispatchHttp(app)`. Full `expose: [http(...), worker(...)]`
- * shape lands when the second wire (queue worker) needs it.
- *
- * Lifecycle:
- *   - `start()` — currently a no-op (registration happens at construction).
- *     Becomes meaningful when transports + timer scheduler join the surface.
- *   - `stop()` — drains pending work; reserved.
- *   - `runtime` — escape hatch for transports and tests.
- */
-import { seedEnvelope } from "@nwire/envelope";
-import { hook } from "@nwire/hooks";
-import { Runtime } from "./runtime.js";
-import { adaptAppPlugin, buildPluginContext } from "./define-plugin.js";
-import { isAppPlugin } from "@nwire/app";
-import { AppRegistering, AppBooting, AppBooted, AppShuttingDown, AppShutdown, PluginRegistered, PluginBooting, PluginBooted, PluginShuttingDown, PluginShutdown, builtInLifecycleEvents, } from "./framework-events.js";
-export function createApp(options) {
-    // Normalize the plugin list: callers may pass either the rich forge
-    // PluginDefinition or the narrow @nwire/app AppPluginDefinition. The
-    // downstream pipeline (register loop, framework events, shutdown) is
-    // written against the rich shape, so adapt narrow → rich here. Every
-    // subsequent use of `options.plugins` reads from `plugins` instead.
-    const plugins = (options.plugins ?? []).map((p) => isAppPlugin(p) ? adaptAppPlugin(p) : p);
-    // Index local provides up-front — both validators and the bus-subscription
-    // loop need to know "is this event satisfiable locally in this app?"
-    const localEventProviders = indexLocalEventProviders(options.modules);
-    const localActionProviders = indexLocalActionProviders(options.modules);
-    validateModuleDepGraph(options.modules, localEventProviders, localActionProviders, !!options.bus);
-    validateExternalEventDeps(options.modules, localEventProviders, !!options.bus);
-    /**
-     * Sort modules topologically by `needs.events / needs.actions`.
-     * Producers register before consumers. Registration is order-independent
-     * for correctness today (every reference resolves through the runtime's
-     * registries which are populated up-front), but the order DOES affect:
-     *
-     *   - Studio's render order (modules appear in dep order, not source order)
-     *   - Telemetry: PluginRegistered events fire in topological order
-     *   - Future module-as-plugin work: if defineModule ever produces a
-     *     plugin with its own boot phase, the order will become load-bearing.
-     *
-     * Topo failures (cycles, unknown refs) throw at boot with a readable
-     * trace — same error class as validateModuleDepGraph so the cause is
-     * surfaced before any traffic.
-     */
-    const orderedModules = topoSortModules(options.modules, localEventProviders, localActionProviders);
-    const runtime = new Runtime({
-        container: options.container,
-        actorStore: options.actorStore,
-        projectionStore: options.projectionStore,
-        logger: options.logger,
-        deadLetterSink: options.deadLetterSink,
-        bus: options.bus,
-        publishToBus: options.publishToBus,
-        appName: options.appName,
-    });
-    /**
-     * Register app capabilities on the container so handlers in any
-     * transport (HTTP / queue / CLI) can `ctx.resolve("execute")` etc.
-     * Each call seeds a fresh envelope — transports running outside an
-     * existing dispatch chain don't have one to inherit. For HTTP that's
-     * exactly right: each request is its own causal root.
-     *
-     * Share the runtime's container so caller-provided + base-default forms
-     * both wire to the same instance — separate fallback container creation
-     * would produce divergent containers and break `ctx.resolve("execute")`.
-     */
-    const containerForCaps = runtime.getContainer();
-    containerForCaps.register("execute", () => {
-        return async function execute(actionOrCmd, input) {
-            const { resolveDispatch } = await import("./define-action.js");
-            const { action, input: resolvedInput } = resolveDispatch(actionOrCmd, input, runtime.findActionByName.bind(runtime));
-            return await runtime.dispatch(action, resolvedInput, seedEnvelope({}));
-        };
-    });
-    containerForCaps.register("send", () => {
-        return async function send(actionOrCmd, input) {
-            // Fire-and-forget — same envelope-per-call story as `execute`.
-            const { resolveDispatch } = await import("./define-action.js");
-            const { action, input: resolvedInput } = resolveDispatch(actionOrCmd, input, runtime.findActionByName.bind(runtime));
-            await runtime.dispatch(action, resolvedInput, seedEnvelope({}));
-        };
-    });
-    containerForCaps.register("useProjection", () => {
-        return async function useProjection(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        queryDef, input) {
-            return runtime.query(queryDef.name, input, "");
-        };
-    });
-    let timerInterval = null;
-    /** Subscription handle from attachDevLogger — called in stop() to detach. */
-    let detachDevLogger = null;
-    /** Subscribe the bus for an external event name once (dedup across modules). */
-    const subscribedExternal = new Set();
-    const subscribeExternal = (eventName) => {
-        if (subscribedExternal.has(eventName))
-            return;
-        subscribedExternal.add(eventName);
-        runtime.registerExternalEvent(eventName);
-        if (!options.bus)
-            return; // validators ensured this won't happen
-        options.bus.subscribe(eventName, async (msg) => {
-            if (msg.origin && options.appName && msg.origin === options.appName)
-                return;
-            await runtime.applyExternalEvent(eventName, msg.payload, msg.envelope);
-        });
-    };
-    for (const module of orderedModules) {
-        const m = module.manifest;
-        for (const actor of m.actors ?? [])
-            runtime.registerActor(actor);
-        for (const handler of m.handlers ?? [])
-            runtime.registerHandler(handler);
-        // Inline handlers — `defineAction({..., handler})` attaches a synthesized
-        // HandlerDefinition to the action. Register here so authors can pick
-        // either form (inline action+handler OR separate defineHandler) without
-        // a module-manifest change.
-        for (const action of m.actions ?? []) {
-            if (action.handler)
-                runtime.registerHandler(action.handler);
-        }
-        for (const projection of m.projections ?? [])
-            runtime.registerProjection(projection);
-        for (const query of m.queries ?? [])
-            runtime.registerQuery(query);
-        for (const workflow of m.workflows ?? []) {
-            runtime.registerWorkflow(workflow);
-        }
-        // Orchestrator primitives — Studio sees them, runtime registers the
-        // call definitions for executor binding by wires/adapters.
-        for (const call of m.externalCalls ?? []) {
-            runtime.registerExternalCall(call);
-        }
-        // Track public-event names so the runtime knows which to bus-publish.
-        for (const e of m.events ?? []) {
-            if ((e.visibility ?? "public") === "public") {
-                runtime.registerPublicEvent(e.name);
-            }
-        }
-        // For each declared event need: if a producer lives in THIS app,
-        // do nothing (the in-process publish pipeline handles it). If not,
-        // and a bus is configured, auto-subscribe — the same declaration
-        // works in monolith and split topologies.
-        for (const e of m.needs?.events ?? []) {
-            if (!localEventProviders.has(e.name)) {
-                subscribeExternal(e.name);
-            }
-        }
-        // `externalEvents` is the strict-marker form — requires NON-local.
-        // The validator enforces that; here we just auto-wire.
-        for (const e of m.needs?.externalEvents ?? []) {
-            subscribeExternal(e.name);
-        }
-        // Routes are bound by transports, not by the runtime.
-    }
-    // Pre-create per-module lifecycle hooks so `listHooks()` + scan see
-    // them even before start() runs. The hooks are adopted by the runtime
-    // immediately (so taps are wired); chain steps are attached in start().
-    const pluginBootHooks = new Map();
-    const pluginShutdownHooks = new Map();
-    for (const module of orderedModules) {
-        const bootH = hook(`plugin.boot:${module.name}`);
-        const shutdownH = hook(`plugin.shutdown:${module.name}`);
-        runtime.adoptHook(bootH);
-        runtime.adoptHook(shutdownH);
-        pluginBootHooks.set(module.name, bootH);
-        pluginShutdownHooks.set(module.name, shutdownH);
-    }
-    // Same for real plugins.
-    for (const plugin of plugins) {
-        const bootH = hook(`plugin.boot:${plugin.name}`);
-        const shutdownH = hook(`plugin.shutdown:${plugin.name}`);
-        runtime.adoptHook(bootH);
-        runtime.adoptHook(shutdownH);
-        pluginBootHooks.set(plugin.name, bootH);
-        pluginShutdownHooks.set(plugin.name, shutdownH);
-    }
-    const container = runtime.getContainer();
-    /** Booted provider values, indexed by provider name. Populated in start(). */
-    // Plugins: register synchronously up-front (before async boot) so they
-    // can declare container values + framework subscriptions + middleware
-    // before the first dispatch.
-    //
-    // The closure form's `setup` runs here too; its `boot`/`shutdown`
-    // builder calls accumulate into per-plugin lists that get fired in
-    // order during start() / stop().
-    /**
-     * Per-plugin closure-form boots, keyed by plugin index. Keeping the
-     * association lets the start() loop wrap each plugin with its own
-     * PluginBooting/PluginBooted framework events (rather than firing one
-     * "everyone's boots fired" event for the collapsed list).
-     */
-    const closureBoots = new Map();
-    /** Keyed by plugin index so we can fire reverse on stop in-order. */
-    const closureShutdowns = new Map();
-    let pluginIdx = 0;
-    for (const plugin of plugins) {
-        if (plugin.register)
-            plugin.register(container);
-        if (plugin.setup) {
-            const { api, boots, shutdowns } = buildPluginContext(container, runtime, options.config ?? {}, plugin.name);
-            // The setup function may be async; we kick it off and await its
-            // promise so the closure can use top-level `await` if it wants.
-            const result = plugin.setup(api);
-            if (result instanceof Promise) {
-                // Top-level register loop is sync; we can't await here without
-                // restructuring createApp. Surface the requirement explicitly.
-                throw new Error(`definePlugin("${plugin.name}"): closure form must be synchronous. ` +
-                    `Use the api.boot(...) builder for async startup work.`);
-            }
-            closureBoots.set(pluginIdx, boots);
-            closureShutdowns.set(pluginIdx, shutdowns);
-        }
-        for (const mw of plugin.middleware ?? [])
-            runtime.use(mw);
-        if (plugin.actorHooks?.afterTransition) {
-            runtime.registerActorTransitionHook(plugin.actorHooks.afterTransition);
-        }
-        pluginIdx++;
-    }
-    // Name → definition map for `dispatchFrameworkEvent`. Built once from
-    // the built-in lifecycle catalog; endpoint passes event NAMES (strings)
-    // so it stays decoupled from `@nwire/app`'s typed event definitions.
-    const lifecycleEventsByName = new Map();
-    for (const def of builtInLifecycleEvents) {
-        lifecycleEventsByName.set(def.name, def);
-    }
-    const app = {
-        $nwireApp: true,
-        runtime,
-        modules: options.modules,
-        plugins,
-        container,
-        get appName() {
-            return runtime.appName;
-        },
-        async dispatchFrameworkEvent(eventName, payload) {
-            const def = lifecycleEventsByName.get(eventName);
-            if (!def) {
-                // Unknown event — silently no-op. The endpoint may send events
-                // a future framework version defines; an older app shouldn't
-                // crash on receipt. Returning `true` matches "nothing
-                // prevented" semantics.
-                return true;
-            }
-            return runtime.frameworkEvents.fire(def, payload);
-        },
-        async boot() {
-            return this.start();
-        },
-        async shutdown() {
-            return this.stop();
-        },
-        async start() {
-            const appName = runtime.appName;
-            // Announce composition BEFORE lifecycle fires. Modules first (in
-            // topological order — same order they registered into the runtime),
-            // then plugins. Same `PluginRegistered` event with `kind: "module" |
-            // "plugin"` so observers can render them differently but read from
-            // one channel.
-            for (const module of orderedModules) {
-                await runtime.frameworkEvents.fire(PluginRegistered, {
-                    appName,
-                    pluginName: module.name,
-                    kind: "module",
-                });
-            }
-            for (const plugin of plugins) {
-                await runtime.frameworkEvents.fire(PluginRegistered, {
-                    appName,
-                    pluginName: plugin.name,
-                    kind: "plugin",
-                });
-            }
-            // Framework event: AppRegistering — interceptable. Plugins that
-            // subscribed during their `register` hook can refuse boot here.
-            const registeringOk = await runtime.frameworkEvents.fire(AppRegistering, { appName });
-            if (!registeringOk) {
-                throw new Error(`Boot prevented by AppRegistering subscriber (app: ${appName})`);
-            }
-            // Framework event: AppBooting — interceptable. Fired after the sync
-            // plugin-register phase has populated the container, before any
-            // async plugin boot runs.
-            const bootingOk = await runtime.frameworkEvents.fire(AppBooting, { appName });
-            if (!bootingOk) {
-                throw new Error(`Boot prevented by AppBooting subscriber (app: ${appName})`);
-            }
-            // Modules first — same lifecycle event surface + per-name hooks as
-            // plugins. The hook was pre-created in createApp body so scan +
-            // listHooks() see it before start() runs.
-            for (const module of orderedModules) {
-                const bootHook = pluginBootHooks.get(module.name);
-                const t = Date.now();
-                const okBoot = await runtime.frameworkEvents.fire(PluginBooting, {
-                    appName,
-                    pluginName: module.name,
-                    kind: "module",
-                });
-                if (!okBoot) {
-                    throw new Error(`Boot of module "${module.name}" prevented by PluginBooting subscriber`);
-                }
-                await bootHook.run({ name: module.name, kind: "module" });
-                await runtime.frameworkEvents.fire(PluginBooted, {
-                    appName,
-                    pluginName: module.name,
-                    durationMs: Date.now() - t,
-                    kind: "module",
-                });
-            }
-            // Plugins boot in declaration order. Each plugin is wrapped with
-            // PluginBooting (interceptable) + PluginBooted (observable, with
-            // duration) so logging/tracing/Studio can show per-plugin boot
-            // timing.
-            //
-            // Object-form plugins run their `boot` callback; closure-form
-            // plugins additionally fire every `api.boot(...)` they registered
-            // in setup, in declaration order.
-            const allPlugins = plugins;
-            for (let i = 0; i < allPlugins.length; i++) {
-                const plugin = allPlugins[i];
-                const pluginName = plugin.name;
-                const okToBoot = await runtime.frameworkEvents.fire(PluginBooting, {
-                    appName,
-                    pluginName,
-                    kind: "plugin",
-                });
-                if (!okToBoot) {
-                    throw new Error(`Boot of plugin "${pluginName}" prevented by PluginBooting subscriber`);
-                }
-                // Per-plugin boot hook — pre-created in createApp body. Chain
-                // steps attach JIT so listHooks() sees an empty hook until start()
-                // runs (matches Studio's expected view of "what runs at boot").
-                const bootHook = pluginBootHooks.get(pluginName);
-                if (plugin.boot) {
-                    bootHook.use(async (_c, next) => {
-                        await plugin.boot(container);
-                        await next();
-                    }, {
-                        name: "boot",
-                    });
-                }
-                const boots = closureBoots.get(i);
-                if (boots) {
-                    for (let k = 0; k < boots.length; k++) {
-                        const fn = boots[k];
-                        bootHook.use(async (_c, next) => {
-                            await fn();
-                            await next();
-                        }, {
-                            name: `closure[${k}]`,
-                        });
-                    }
-                }
-                const startedAt = Date.now();
-                await bootHook.run({ name: pluginName, kind: "plugin" });
-                await runtime.frameworkEvents.fire(PluginBooted, {
-                    appName,
-                    pluginName,
-                    durationMs: Date.now() - startedAt,
-                    kind: "plugin",
-                });
-            }
-            // Default dev console logger. Off when:
-            //   - `devLogs: false` is explicit
-            //   - NODE_ENV=production (assume structured logger is configured)
-            //   - NODE_ENV=test (vitest output stays clean)
-            //   - a `logger` (pino/winston) is provided (structured wins)
-            const devLogsOpt = options.devLogs;
-            const env = process.env.NODE_ENV;
-            const wantDevLogs = devLogsOpt === undefined
-                ? env !== "production" && env !== "test" && !options.logger
-                : devLogsOpt !== false;
-            if (wantDevLogs) {
-                const { attachDevLogger } = await import("./dev-logger.js");
-                detachDevLogger = attachDevLogger(runtime, typeof devLogsOpt === "object" ? devLogsOpt : undefined);
-            }
-            // Framework event: AppBooted — observable. Awaited (parallel under
-            // the hood) so start() returns only after every observer had a fair
-            // window; useful for diagnostics that want to flush before serving.
-            await runtime.frameworkEvents.fire(AppBooted, {
-                appName,
-                bootedAt: new Date().toISOString(),
-            });
-            if (options.timerScheduler) {
-                const intervalMs = typeof options.timerScheduler === "object"
-                    ? (options.timerScheduler.intervalMs ?? 60_000)
-                    : 60_000;
-                timerInterval = setInterval(() => {
-                    void runtime.fireDueTimers().catch(() => {
-                        // Swallow per-tick errors so a single bad timer doesn't
-                        // halt the scheduler. Production wires should plug in
-                        // a logger here.
-                    });
-                }, intervalMs);
-                // Don't keep the process alive solely on the timer interval —
-                // the wire's HTTP server is the foreground process.
-                if (typeof timerInterval.unref === "function") {
-                    timerInterval.unref();
-                }
-            }
-        },
-        async stop(reason) {
-            const appName = runtime.appName;
-            // Framework event: AppShuttingDown — interceptable. Subscribers
-            // throwing here propagate as a failed shutdown; returning false
-            // cleanly aborts (the wire can decide to retry or hard-kill).
-            const shutdownOk = await runtime.frameworkEvents.fire(AppShuttingDown, {
-                appName,
-                reason,
-            });
-            if (!shutdownOk) {
-                throw new Error(`Shutdown prevented by AppShuttingDown subscriber (app: ${appName})`);
-            }
-            if (timerInterval) {
-                clearInterval(timerInterval);
-                timerInterval = null;
-            }
-            if (detachDevLogger) {
-                detachDevLogger();
-                detachDevLogger = null;
-            }
-            // Plugins shut down in REVERSE declaration order. For each
-            // closure-form plugin, fire every `api.shutdown(...)` it registered
-            // — also in reverse, so dependencies declared late tear down first.
-            //
-            // Shutdown error isolation: a plugin's shutdown that throws MUST
-            // NOT block subsequent plugins from running. A buggy plugin leaving
-            // resources leaked is bad; that same bug also skipping every
-            // downstream plugin's cleanup would compound the outage. Each
-            // shutdown step is wrapped + logged; we collect errors and re-throw
-            // the first one only AFTER the full sweep completes.
-            //
-            // Two contracts, both important:
-            //   (a) A single bad shutdown must NOT block subsequent plugins from
-            //       cleaning up. (production-readiness)
-            //   (b) Wires must still be able to detect shutdown failure so
-            //       SIGTERM → stop() → exit can surface the problem.
-            // Resolution: collect errors during the sweep, complete every step,
-            // then re-throw the first error AFTER the full sweep finishes.
-            const shutdownErrors = [];
-            const safeRun = async (label, fn) => {
-                try {
-                    await fn();
-                }
-                catch (err) {
-                    shutdownErrors.push(err);
-                    // eslint-disable-next-line no-console
-                    console.error(`[nwire/shutdown] step "${label}" threw — continuing with remaining steps:`, err);
-                }
-            };
-            for (let i = plugins.length - 1; i >= 0; i--) {
-                const plugin = plugins[i];
-                const pluginName = plugin.name;
-                // PluginShuttingDown is interceptable, but a refusal at shutdown
-                // is harder to honor cleanly — the app is on its way out and the
-                // host (lightship) may force-kill us regardless. Honor the signal
-                // by logging + skipping this plugin's teardown, NOT by throwing,
-                // so downstream plugins still get a chance to clean up.
-                const shutdownOkPerPlugin = await runtime.frameworkEvents.fire(PluginShuttingDown, {
-                    appName,
-                    pluginName,
-                    kind: "plugin",
-                });
-                if (!shutdownOkPerPlugin) {
-                    // eslint-disable-next-line no-console
-                    console.warn(`[nwire/shutdown] PluginShuttingDown subscriber refused — skipping plugin "${pluginName}"`);
-                    continue;
-                }
-                const startedAt = Date.now();
-                if (plugin.shutdown)
-                    await safeRun(`plugin:${pluginName}`, () => plugin.shutdown(container));
-                const shutdowns = closureShutdowns.get(i);
-                if (shutdowns) {
-                    for (let j = shutdowns.length - 1; j >= 0; j--) {
-                        await safeRun(`plugin:${pluginName}:closure[${j}]`, () => shutdowns[j]());
-                    }
-                }
-                await runtime.frameworkEvents.fire(PluginShutdown, {
-                    appName,
-                    pluginName,
-                    durationMs: Date.now() - startedAt,
-                    kind: "plugin",
-                });
-            }
-            // Symmetric module shutdown — emit lifecycle events for modules in
-            // REVERSE order. Modules don't have explicit shutdown callbacks; the
-            // events exist so observers see the full lifecycle close cleanly.
-            for (let i = orderedModules.length - 1; i >= 0; i--) {
-                const module = orderedModules[i];
-                const t = Date.now();
-                const ok = await runtime.frameworkEvents.fire(PluginShuttingDown, {
-                    appName,
-                    pluginName: module.name,
-                    kind: "module",
-                });
-                if (!ok)
-                    continue;
-                await runtime.frameworkEvents.fire(PluginShutdown, {
-                    appName,
-                    pluginName: module.name,
-                    durationMs: Date.now() - t,
-                    kind: "module",
-                });
-            }
-            // Framework event: AppShutdown — observable. Awaited so stop()
-            // doesn't return until subscribers had a fair window.
-            await runtime.frameworkEvents.fire(AppShutdown, { appName });
-            // Surface the first shutdown error (if any) AFTER every other step
-            // has run. Wires (and tests) that need to know shutdown failed will
-            // see the throw; meanwhile, downstream plugins still got cleaned up.
-            if (shutdownErrors.length > 0) {
-                throw shutdownErrors[0];
-            }
-        },
-    };
-    return app;
-}
-function indexLocalEventProviders(modules) {
-    const map = new Map();
-    for (const mod of modules) {
-        for (const e of mod.manifest.events ?? []) {
-            // Visibility: the `.public()` marker in the module manifest is the
-            // canonical signal. The older `visibility: "public" | "internal"`
-            // field on the event definition is still honored for back-compat
-            // until every example migrates to `.public()`.
-            const markedPublic = mod.publicSurface.events.has(e.name);
-            const declared = e.visibility;
-            const visibility = markedPublic ? "public" : (declared ?? "internal");
-            map.set(e.name, { module: mod.name, visibility });
-        }
-    }
-    return map;
-}
-function indexLocalActionProviders(modules) {
-    const map = new Map();
-    for (const mod of modules) {
-        for (const a of mod.manifest.actions ?? []) {
-            const visibility = mod.publicSurface.actions.has(a.name)
-                ? "public"
-                : "internal";
-            map.set(a.name, { module: mod.name, visibility });
-        }
-    }
-    return map;
-}
-/**
- * Validate that every `needs.externalEvents` entry has a bus to flow through
- * and is NOT also provided by this same app (you don't go cross-service to
- * reach your own publishes).
- */
-function validateExternalEventDeps(modules, localEventProviders, hasBus) {
-    for (const mod of modules) {
-        const externals = mod.manifest.needs?.externalEvents;
-        if (!externals || externals.length === 0)
-            continue;
-        if (!hasBus) {
-            throw new Error(`Module "${mod.name}" declares needs.externalEvents but no bus is configured. ` +
-                `Pass a bus instance to createApp({ bus, publishToBus? }).`);
-        }
-        for (const e of externals) {
-            if (localEventProviders.has(e.name)) {
-                throw new Error(`Module "${mod.name}" declares needs.externalEvents for "${e.name}" ` +
-                    `but this app also provides it. External needs are for events that ` +
-                    `originate in OTHER services. Move "${e.name}" to needs.events instead.`);
-            }
-        }
-    }
-}
-/**
- * Validate the cross-module dep graph for `needs.events` and `needs.actions`.
- *
- * For `needs.events`: the same declaration must work whether the producer is
- * local (in-process apply) or remote (cross-service via bus). So:
- *   - If a local provider exists: validate visibility (no internal events
- *     leaking across modules) and reject self-references.
- *   - If no local provider exists: require a bus — the runtime will
- *     auto-subscribe at boot. No visibility check (the producer service
- *     decides what it exports).
- *
- * For `needs.actions`: must be local (we don't have cross-service action
- * dispatch yet — that's a future RPC story over the bus or HTTP).
- */
-function validateModuleDepGraph(modules, localEventProviders, localActionProviders, hasBus) {
-    for (const mod of modules) {
-        const needs = mod.manifest.needs;
-        if (!needs)
-            continue;
-        for (const event of needs.events ?? []) {
-            const provider = localEventProviders.get(event.name);
-            if (provider) {
-                if (provider.module === mod.name) {
-                    throw new Error(`Module "${mod.name}" needs event "${event.name}" but provides it itself. ` +
-                        `A module's needs are its dependencies — drop the self-reference.`);
-                }
-                if (provider.visibility === "internal") {
-                    throw new Error(`Module "${mod.name}" needs event "${event.name}" but module "${provider.module}" ` +
-                        `marks it as visibility: 'internal'. Internal events are module-private; ` +
-                        `either change the producer to visibility: 'public' or refactor to avoid the cross-module subscription.`);
-                }
-                continue;
-            }
-            // No local provider — only satisfiable via the bus.
-            if (!hasBus) {
-                throw new Error(`Module "${mod.name}" needs event "${event.name}" but no module in this app provides it ` +
-                    `and no bus is configured. Either include a providing module in this app, configure a bus ` +
-                    `so the event can arrive from another service, or remove "${event.name}" from needs.events.`);
-            }
-            // hasBus + non-local: the createApp wiring loop auto-subscribes.
-        }
-        for (const action of needs.actions ?? []) {
-            const provider = localActionProviders.get(action.name);
-            if (!provider) {
-                throw new Error(`Module "${mod.name}" needs action "${action.name}" but no module provides it. ` +
-                    `Cross-service action dispatch is not supported yet — actions must be local to the app.`);
-            }
-            if (provider.module === mod.name) {
-                throw new Error(`Module "${mod.name}" needs action "${action.name}" but provides it itself. ` +
-                    `A module's needs are its cross-module dependencies — drop the self-reference.`);
-            }
-            if (provider.visibility === "internal") {
-                throw new Error(`Module "${mod.name}" needs action "${action.name}" but module "${provider.module}" ` +
-                    `did not call .public() on it in its module manifest. Internal actions are ` +
-                    `module-private; mark the action public in the producer's manifest or refactor ` +
-                    `to avoid the cross-module dispatch.`);
-            }
-        }
-    }
-}
-/**
- * Kahn-style topological sort over the `needs` graph.
- *
- * Two modules form an edge `A → B` when A needs an event or action that B
- * provides locally. The returned order satisfies "producers before
- * consumers." Modules without any deps preserve their declaration order
- * (stable sort), so a no-needs codebase boots in the order the user wrote.
- *
- * Cycles throw a `Cycle detected` error naming every module on the cycle
- * — readable so the offending pair is obvious. Cycles between BCs usually
- * indicate the boundary is drawn wrong; the fix is to extract the shared
- * concept into a third module, not paper over with externalEvents.
- *
- * External / unknown refs are ignored here because `validateModuleDepGraph`
- * has already proven every `needs.events` either has a local provider OR
- * a bus subscription path. Topo sort cares only about LOCAL edges.
- */
-function topoSortModules(modules, localEventProviders, localActionProviders) {
-    if (modules.length <= 1)
-        return modules;
-    const byName = new Map();
-    for (const m of modules)
-        byName.set(m.name, m);
-    // edges[consumer] = set of producer module names
-    const edges = new Map();
-    for (const m of modules)
-        edges.set(m.name, new Set());
-    for (const m of modules) {
-        const needs = m.manifest.needs;
-        if (!needs)
-            continue;
-        for (const e of needs.events ?? []) {
-            const p = localEventProviders.get(e.name);
-            if (p && p.module !== m.name)
-                edges.get(m.name).add(p.module);
-        }
-        for (const a of needs.actions ?? []) {
-            const p = localActionProviders.get(a.name);
-            if (p && p.module !== m.name)
-                edges.get(m.name).add(p.module);
-        }
-    }
-    // Kahn: repeatedly emit nodes whose dep set is empty, in stable declaration order.
-    const remaining = new Set(modules.map((m) => m.name));
-    const ordered = [];
-    while (remaining.size > 0) {
-        const ready = modules.filter((m) => remaining.has(m.name) && [...edges.get(m.name)].every((dep) => !remaining.has(dep)));
-        if (ready.length === 0) {
-            const cycle = [...remaining].sort();
-            throw new Error(`createApp: cycle detected in module needs graph among: ${cycle.join(", ")}. ` +
-                `Two or more modules need each other (directly or transitively). ` +
-                `Extract the shared concept into a third module or move one side to externalEvents (bus).`);
-        }
-        for (const m of ready) {
-            ordered.push(m);
-            remaining.delete(m.name);
-        }
-    }
-    return ordered;
-}
-//# sourceMappingURL=create-app.js.map