@gobing-ai/ts-infra 0.3.4 → 0.3.6

package/dist/application/plugins/builtins.js

@@ -0,0 +1,146 @@
+/**
+ * Built-in service plugins for the application bootstrap.
+ *
+ * Each factory returns a `Plugin` that maps an existing init/shutdown pair onto
+ * the PluginHost lifecycle: `onStart` = init, `onStop` = teardown. Absent
+ * hooks are omitted (no-op by absence, not by stub).
+ *
+ * @module application/plugins
+ */
+import { initializeLogger } from '../../logger.js';
+import { initMetrics, shutdownMetrics } from '../../telemetry/metrics.js';
+import { initTelemetry, shutdownTelemetry } from '../../telemetry/sdk.js';
+// ── Telemetry ──────────────────────────────────────────────────────────────
+/**
+ * Built-in plugin for telemetry + metrics.
+ *
+ * `onStart`: `initTelemetry` + `initMetrics` (pre-warm instruments).
+ * `onStop`:  `shutdownMetrics` + `shutdownTelemetry` (reverse of init).
+ * `failFast: true` — a failing telemetry init aborts the bootstrap.
+ */
+export function telemetryPlugin(config) {
+    return {
+        name: 'builtin:telemetry',
+        version: '0.0.0',
+        failFast: true,
+        onLoad: async () => { },
+        onStart: async () => {
+            if (config.enabled) {
+                initTelemetry({
+                    enabled: config.enabled,
+                    serviceName: config.serviceName,
+                    environment: config.environment,
+                    dbStatementDebug: config.dbStatementDebug,
+                });
+                initMetrics();
+            }
+        },
+        onStop: async () => {
+            if (config.enabled) {
+                shutdownMetrics();
+                await shutdownTelemetry();
+            }
+        },
+    };
+}
+// ── Logger ─────────────────────────────────────────────────────────────────
+/**
+ * Built-in plugin for the structured logger.
+ *
+ * `onStart`: `initializeLogger` (skipped when an injected logger is present).
+ * No `onStop` — the logger has no teardown.
+ * `failFast: true` — a failing logger init aborts the bootstrap.
+ */
+export function loggerPlugin(config, injected) {
+    return {
+        name: 'builtin:logger',
+        version: '0.0.0',
+        failFast: true,
+        onLoad: async () => { },
+        onStart: async () => {
+            if (config.enabled && !injected) {
+                await initializeLogger({
+                    level: config.level,
+                    console: config.console,
+                    json: config.json,
+                    fileSink: config.fileSink,
+                });
+            }
+        },
+    };
+}
+/**
+ * Built-in plugin that wraps the user's `start`/`stop` callbacks.
+ *
+ * `onStart`: calls `options.start(app)`. `failFast: true`.
+ * `onStop`:  calls `options.stop(app, reason)`. Registered after services,
+ *            before scheduler, so stopAll/reverse-order places it after
+ *            scheduler.stop and before service teardown.
+ */
+export function userCallbackPlugin(start, stop, app) {
+    return {
+        name: 'builtin:user-callback',
+        version: '0.0.0',
+        failFast: true,
+        onLoad: async () => { },
+        onStart: async () => {
+            if (app)
+                await start(app);
+        },
+        onStop: stop && app
+            ? async (_host, reason) => {
+                await stop(app, reason ?? 'manual');
+            }
+            : undefined,
+    };
+}
+/**
+ * Built-in plugin for the scheduler.
+ *
+ * `onStart`: `adapter.start()` when `autoStart` is true.
+ * `onStop`:  `adapter.stop()` — fail-soft.
+ *
+ * Registered LAST so autoStart always runs after the user callback.
+ */
+export function schedulerPlugin(adapter, autoStart) {
+    return {
+        name: 'builtin:scheduler',
+        version: '0.0.0',
+        failFast: true,
+        onLoad: async () => { },
+        onStart: async () => {
+            if (autoStart) {
+                await adapter.start();
+            }
+        },
+        onStop: async () => {
+            // Fail-soft — the host always catches stop/unload errors
+            await adapter.stop();
+        },
+    };
+}
+// ── DB (reason-aware, for owned adapters only) ────────────────────────────
+/**
+ * Built-in plugin for a DB adapter the bootstrap OWNS.
+ *
+ * `onStop(reason)`: `db.close()` — best-effort.
+ * Register ONLY when the bootstrap creates the adapter (Node subpath).
+ * Do NOT register for caller-injected `services.db` — those are caller-owned.
+ */
+export function dbPlugin(db) {
+    return {
+        name: 'builtin:db',
+        version: '0.0.0',
+        failFast: false,
+        onLoad: async () => { },
+        onStart: async () => { },
+        onStop: async () => {
+            try {
+                db.close();
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+}

package/dist/application/plugins/host.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Bare `PluginHost` — owns an insertion-ordered set of plugins and drives
+ * lifecycle fan-out (load → start → stop → unload) with fail-soft semantics
+ * for start/stop/unload and fail-fast for load.
+ *
+ * This is a runtime concern: it needs a logger and event bus, both provided
+ * by the application bootstrap. No capabilities, no trust ladder.
+ *
+ * @module application/plugins
+ */
+import type { EventBus } from '../../event-bus/event-bus';
+import type { EventMap } from '../../event-bus/types';
+import { type Logger } from '../../logger';
+import type { Plugin, PluginSummary } from './types';
+/**
+ * Plugin host: registers plugins in insertion order and drives their lifecycle
+ * fan-out (load → start → stop → unload).
+ *
+ * The host stores `EventBus<EventMap>` (the base event contract) rather than
+ * a narrower `TEvents` subtype, because `EventBus` is invariant in its type
+ * parameter and plugins only need the base contract.
+ */
+export declare class PluginHost {
+    readonly logger: Logger;
+    readonly events: EventBus<EventMap>;
+    private readonly _plugins;
+    constructor(events: EventBus<EventMap>, opts?: {
+        logger?: Logger;
+    });
+    /** Register a plugin. Throws on duplicate name. */
+    register(plugin: Plugin): void;
+    /** Remove a plugin by name. No-op if absent. */
+    unregister(name: string): void;
+    /** Check whether a plugin is registered. */
+    has(name: string): boolean;
+    /** List registered plugins in registration order. */
+    list(): readonly PluginSummary[];
+    /**
+     * Fail-fast: calls `onLoad` on every plugin in registration order.
+     * A throwing hook aborts the bootstrap.
+     */
+    loadAll(): Promise<void>;
+    /**
+     * Calls `onStart` on every plugin in registration order.
+     * Plugins with `failFast: true` rethrow (aborting boot); others log + skip.
+     */
+    startAll(): Promise<void>;
+    /**
+     * Fail-soft: calls `onStop` on every plugin in **reverse** registration order.
+     * A throwing hook is logged + skipped.
+     * `reason` is forwarded to each plugin's `onStop(host, reason?)`.
+     */
+    stopAll(reason?: string): Promise<void>;
+    /**
+     * Fail-soft: calls `onUnload` on every plugin in **reverse** registration order.
+     * A throwing hook is logged + skipped.
+     * `reason` is forwarded to each plugin's `onUnload(host, reason?)`.
+     */
+    unloadAll(reason?: string): Promise<void>;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/application/plugins/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../../src/application/plugins/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAIrD;;;;;;;GAOG;AACH,qBAAa,UAAU;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAE1C,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAOlE,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO9B,gDAAgD;IAChD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,4CAA4C;IAC5C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,qDAAqD;IACrD,IAAI,IAAI,SAAS,aAAa,EAAE;IAUhC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAO9B;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB/B;;;;OAIG;IACG,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB7C;;;;OAIG;IACG,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAelD"}

package/dist/application/plugins/host.js

@@ -0,0 +1,131 @@
+/**
+ * Bare `PluginHost` — owns an insertion-ordered set of plugins and drives
+ * lifecycle fan-out (load → start → stop → unload) with fail-soft semantics
+ * for start/stop/unload and fail-fast for load.
+ *
+ * This is a runtime concern: it needs a logger and event bus, both provided
+ * by the application bootstrap. No capabilities, no trust ladder.
+ *
+ * @module application/plugins
+ */
+import { getLogger } from '../../logger.js';
+// ── PluginHost ─────────────────────────────────────────────────────────────
+/**
+ * Plugin host: registers plugins in insertion order and drives their lifecycle
+ * fan-out (load → start → stop → unload).
+ *
+ * The host stores `EventBus<EventMap>` (the base event contract) rather than
+ * a narrower `TEvents` subtype, because `EventBus` is invariant in its type
+ * parameter and plugins only need the base contract.
+ */
+export class PluginHost {
+    logger;
+    events;
+    _plugins = new Map();
+    constructor(events, opts) {
+        this.events = events;
+        this.logger = opts?.logger ?? getLogger('plugin-host');
+    }
+    // ── Registration ────────────────────────────────────────────────────
+    /** Register a plugin. Throws on duplicate name. */
+    register(plugin) {
+        if (this._plugins.has(plugin.name)) {
+            throw new Error(`Plugin already registered: ${plugin.name}`);
+        }
+        this._plugins.set(plugin.name, plugin);
+    }
+    /** Remove a plugin by name. No-op if absent. */
+    unregister(name) {
+        this._plugins.delete(name);
+    }
+    /** Check whether a plugin is registered. */
+    has(name) {
+        return this._plugins.has(name);
+    }
+    /** List registered plugins in registration order. */
+    list() {
+        const result = [];
+        for (const p of this._plugins.values()) {
+            result.push({ name: p.name, version: p.version });
+        }
+        return result;
+    }
+    // ── Lifecycle fan-out ───────────────────────────────────────────────
+    /**
+     * Fail-fast: calls `onLoad` on every plugin in registration order.
+     * A throwing hook aborts the bootstrap.
+     */
+    async loadAll() {
+        for (const plugin of this._plugins.values()) {
+            this.logger.debug(`Loading plugin: ${plugin.name}`, { name: plugin.name });
+            await plugin.onLoad(this);
+        }
+    }
+    /**
+     * Calls `onStart` on every plugin in registration order.
+     * Plugins with `failFast: true` rethrow (aborting boot); others log + skip.
+     */
+    async startAll() {
+        for (const plugin of this._plugins.values()) {
+            if (!plugin.onStart)
+                continue;
+            try {
+                this.logger.debug(`Starting plugin: ${plugin.name}`, { name: plugin.name });
+                await plugin.onStart(this);
+            }
+            catch (err) {
+                if (plugin.failFast) {
+                    throw err;
+                }
+                this.logger.error(`Plugin start hook failed: ${plugin.name}`, {
+                    name: plugin.name,
+                    error: err.message,
+                });
+            }
+        }
+    }
+    /**
+     * Fail-soft: calls `onStop` on every plugin in **reverse** registration order.
+     * A throwing hook is logged + skipped.
+     * `reason` is forwarded to each plugin's `onStop(host, reason?)`.
+     */
+    async stopAll(reason) {
+        const reversed = [...this._plugins.values()].reverse();
+        for (const plugin of reversed) {
+            if (!plugin.onStop)
+                continue;
+            try {
+                this.logger.debug(`Stopping plugin: ${plugin.name}`, { name: plugin.name, reason });
+                await plugin.onStop(this, reason);
+            }
+            catch (err) {
+                this.logger.error(`Plugin stop hook failed: ${plugin.name}`, {
+                    name: plugin.name,
+                    error: err.message,
+                });
+            }
+        }
+    }
+    /**
+     * Fail-soft: calls `onUnload` on every plugin in **reverse** registration order.
+     * A throwing hook is logged + skipped.
+     * `reason` is forwarded to each plugin's `onUnload(host, reason?)`.
+     */
+    async unloadAll(reason) {
+        const reversed = [...this._plugins.values()].reverse();
+        for (const plugin of reversed) {
+            if (!plugin.onUnload)
+                continue;
+            try {
+                this.logger.debug(`Unloading plugin: ${plugin.name}`, { name: plugin.name, reason });
+                await plugin.onUnload(this, reason);
+            }
+            catch (err) {
+                this.logger.error(`Plugin unload hook failed: ${plugin.name}`, {
+                    name: plugin.name,
+                    error: err.message,
+                });
+            }
+        }
+    }
+}

package/dist/application/plugins/index.d.ts

@@ -0,0 +1,3 @@
+export { PluginHost } from './host';
+export type { Plugin, PluginSummary } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/application/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/plugins/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/application/plugins/index.js

@@ -0,0 +1,2 @@
+// PluginHost class doubles as the type (same contract)
+export { PluginHost } from './host.js';

package/dist/application/plugins/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Portable plugin lifecycle contract.
+ *
+ * The `Plugin` interface is a minimal runtime-neutral lifecycle contract:
+ * no capabilities, no trust ladder, no manifest schema — just `onLoad` / `onUnload`
+ * and `onStart` / `onStop` hooks. Names are deliberately runtime-neutral so
+ * CLI and long-lived server apps share the same semantics.
+ *
+ * @module application/plugins
+ */
+import type { EventBus } from '../../event-bus/event-bus';
+import type { EventMap } from '../../event-bus/types';
+import type { Logger } from '../../logger';
+/**
+ * Minimal plugin lifecycle contract.
+ *
+ * All hooks receive the host reference so a plugin can access the runtime
+ * logger, event bus, and other plugins.
+ */
+export interface Plugin {
+    /** Unique name. Used for dedup and lookup in the host. */
+    readonly name: string;
+    /** Semver-compatible version string. Informational only in this cut. */
+    readonly version: string;
+    /**
+     * When `true`, a throwing `onStart` aborts the bootstrap (fail-fast).
+     * When absent/false, a throwing `onStart` is logged and skipped (fail-soft).
+     * Has no effect on `loadAll` (always fail-fast) or `stopAll`/`unloadAll`
+     * (always fail-soft — teardown is best-effort).
+     */
+    readonly failFast?: boolean;
+    /**
+     * Called during `PluginHost.loadAll()` — fail-fast.
+     * A throwing `onLoad` aborts the bootstrap.
+     */
+    onLoad(host: PluginHost): void | Promise<void>;
+    /** Called during `PluginHost.unloadAll()` — fail-soft. */
+    onUnload?(host: PluginHost, reason?: string): void | Promise<void>;
+    /** Called during `PluginHost.startAll()` — fail-soft. */
+    onStart?(host: PluginHost): void | Promise<void>;
+    /** Called during `PluginHost.stopAll()` — fail-soft. */
+    onStop?(host: PluginHost, reason?: string): void | Promise<void>;
+}
+/**
+ * Summary view of a registered plugin (no references, just metadata).
+ */
+export interface PluginSummary {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Structural contract for the plugin host.
+ *
+ * This is the shape exposed on `ApplicationRuntime.pluginHost`. Consumers
+ * that need to register/unregister plugins at runtime use this interface.
+ */
+export interface PluginHost {
+    readonly logger: Logger;
+    readonly events: EventBus<EventMap>;
+    register(plugin: Plugin): void;
+    unregister(name: string): void;
+    has(name: string): boolean;
+    list(): readonly PluginSummary[];
+    loadAll(): Promise<void>;
+    startAll(): Promise<void>;
+    stopAll(reason?: string): Promise<void>;
+    unloadAll(reason?: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/application/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/application/plugins/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C,0DAA0D;IAC1D,QAAQ,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,yDAAyD;IACzD,OAAO,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD,wDAAwD;IACxD,MAAM,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAID;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAID;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEpC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,IAAI,IAAI,SAAS,aAAa,EAAE,CAAC;IAEjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C"}

package/dist/application/plugins/types.js

@@ -0,0 +1,10 @@
+/**
+ * Portable plugin lifecycle contract.
+ *
+ * The `Plugin` interface is a minimal runtime-neutral lifecycle contract:
+ * no capabilities, no trust ladder, no manifest schema — just `onLoad` / `onUnload`
+ * and `onStart` / `onStop` hooks. Names are deliberately runtime-neutral so
+ * CLI and long-lived server apps share the same semantics.
+ *
+ * @module application/plugins
+ */

package/dist/application/types.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Portable application bootstrap types.
+ *
+ * These types define the DI contract for `runApplication` — a thin orchestration
+ * layer over existing ts-infra primitives. The portable subpath does not import
+ * any runtime-specific adapters; everything injectable comes through the options.
+ *
+ * @module application/types
+ */
+import type { EventBus } from '../event-bus/event-bus';
+import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
+import type { InfraEvents } from '../events';
+import type { Logger, LogLevel } from '../logger';
+import type { SchedulerAdapter } from '../scheduler/types';
+import type { PluginHost } from './plugins/host';
+import type { Plugin } from './plugins/types';
+/** Logging feature flags. */
+export interface LoggingOptions {
+    /** Enable logging. Default `true`. */
+    enabled?: boolean;
+    /** Minimum log level. Default `'info'`. */
+    level?: LogLevel;
+    /** Enable console output. Default `true`. */
+    console?: boolean;
+    /**
+     * File sink writer. The portable bootstrap never opens files — the caller
+     * (or Node convenience subpath) provides a writer.
+     */
+    fileSink?: (line: string) => void;
+    /** JSON Lines format. Default `true`. */
+    json?: boolean;
+}
+/** Event bus feature flags. */
+export interface EventsOptions<TEvents extends EventMap = InfraEvents> {
+    /** Enable event bus. Default `true`. */
+    enabled?: boolean;
+    /** Create and attach a lifecycle bus. Default `true`. */
+    lifecycle?: boolean;
+    /** Attach default observers (log + telemetry). Default `true`. */
+    defaultObservers?: boolean;
+    /** Pre-built event bus (skips creation when provided). */
+    bus?: EventBus<TEvents>;
+}
+/** Telemetry feature flags. */
+export interface TelemetryOptions {
+    /** Enable telemetry instrumentation. Default `true`. */
+    enabled?: boolean;
+    /** Service name for spans. Default `'ts-libs'`. */
+    serviceName?: string;
+    /** Deployment environment. Default `'development'`. */
+    environment?: string;
+    /** Capture sanitized SQL in DB spans. Default `false`. */
+    dbStatementDebug?: boolean;
+}
+/** Scheduler feature flags. */
+export interface SchedulerOptions {
+    /** Enable scheduler. Default `false`. */
+    enabled?: boolean;
+    /** Injected adapter (skips noop default when provided). */
+    adapter?: SchedulerAdapter;
+    /** Cron entries to register: `[cron, action][]`. */
+    entries?: Array<[string, () => Promise<void>]>;
+    /** Start scheduler immediately after registration. Default `true` when enabled. */
+    autoStart?: boolean;
+}
+/**
+ * Fully-resolved bootstrap config (all optionals filled with defaults).
+ * Constructed internally by `resolveBootstrapConfig`.
+ */
+export interface ApplicationBootstrapConfig {
+    readonly logging: Readonly<Required<Pick<LoggingOptions, 'enabled' | 'level' | 'console' | 'json'>> & {
+        fileSink?: (line: string) => void;
+    }>;
+    readonly events: {
+        enabled: boolean;
+        lifecycle: boolean;
+        defaultObservers: boolean;
+    };
+    readonly telemetry: {
+        enabled: boolean;
+        serviceName: string;
+        environment: string;
+        dbStatementDebug: boolean;
+    };
+    readonly scheduler: {
+        enabled: boolean;
+        autoStart: boolean;
+    };
+}
+/** Services that may be pre-injected instead of created by the bootstrap. */
+export interface ApplicationServices<TEvents extends EventMap = InfraEvents> {
+    logger?: Logger;
+    events?: EventBus<TEvents>;
+    lifecycleBus?: EventBus<BusLifecycleEvents>;
+    db?: DbAdapterLike;
+    scheduler?: SchedulerAdapter;
+    /** Pre-built plugin host (when injecting instead of constructing). */
+    pluginHost?: PluginHost;
+}
+/**
+ * Minimal DB adapter shape the bootstrap cares about: `close()` for lifecycle.
+ * This avoids importing `ts-db` (an optional peer) from the portable subpath.
+ */
+export interface DbAdapterLike {
+    close(): void;
+}
+/** Why the application is stopping. */
+export type ApplicationStopReason = 'manual' | 'signal' | 'error' | 'shutdown';
+/**
+ * Runtime handle returned by `runApplication`.
+ *
+ * Exposes all resolved services and a `stop()` method for graceful shutdown.
+ */
+export interface ApplicationRuntime<TAppConfig = unknown, TEvents extends EventMap = InfraEvents> {
+    /** Fully-resolved bootstrap config (feature flags + defaults). */
+    readonly config: ApplicationBootstrapConfig;
+    /** Caller-provided application config, or `undefined`. */
+    readonly appConfig: TAppConfig;
+    /** Structured logger. */
+    readonly logger: Logger;
+    /** Application event bus. */
+    readonly events: EventBus<TEvents>;
+    /** Lifecycle bus (when enabled). */
+    readonly lifecycleBus?: EventBus<BusLifecycleEvents>;
+    /** DB adapter (when enabled and injected). */
+    readonly db?: DbAdapterLike;
+    /** Scheduler adapter (when enabled). */
+    readonly scheduler?: SchedulerAdapter;
+    readonly pluginHost: PluginHost;
+    /** Graceful shutdown. Idempotent — safe to call multiple times. */
+    stop(reason?: ApplicationStopReason): Promise<void>;
+}
+/**
+ * Options for the portable `runApplication`.
+ */
+export interface ApplicationBootstrapOptions<TAppConfig = unknown, TEvents extends EventMap = InfraEvents> {
+    /** Bootstrap feature flags (partial — defaults applied internally). */
+    readonly config?: {
+        logging?: LoggingOptions;
+        events?: EventsOptions<TEvents>;
+        telemetry?: TelemetryOptions;
+        scheduler?: SchedulerOptions;
+    };
+    /** Already-resolved application config. Portable — no file reads. */
+    readonly appConfig?: TAppConfig;
+    /** Pre-built services to inject instead of creating defaults. */
+    readonly services?: Partial<ApplicationServices<TEvents>>;
+    /** Plugins to register and lifecycle-manage via PluginHost. */
+    readonly plugins?: Plugin[];
+    /** User callback: application logic. Called after all services are ready. */
+    readonly start: (app: ApplicationRuntime<TAppConfig, TEvents>) => Promise<void> | void;
+    /** User callback: cleanup before services shut down. */
+    readonly stop?: (app: ApplicationRuntime<TAppConfig, TEvents>, reason: ApplicationStopReason) => Promise<void> | void;
+}
+/**
+ * Validation result matching the structural `safeParse` pattern.
+ * Avoids hard-coupling to a specific validation library.
+ */
+export interface ConfigValidationResult<T> {
+    readonly success: boolean;
+    readonly data?: T;
+    readonly errors?: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>;
+}
+/**
+ * Config validator: structural `safeParse`-compatible adapter.
+ * Accepts any validation library that produces `{ success, data?, errors? }`.
+ */
+export type ApplicationConfigValidator<TAppConfig> = {
+    safeParse(raw: unknown): ConfigValidationResult<TAppConfig>;
+} | ((raw: unknown) => TAppConfig) | {
+    validate(raw: unknown): TAppConfig;
+} | {
+    parse(raw: unknown): TAppConfig;
+};
+/**
+ * Config loader options for the Node/Bun convenience subpath.
+ */
+export interface ApplicationConfigLoader<TAppConfig = unknown> {
+    /** Path to the YAML config file. */
+    readonly configFile?: string;
+    /** YAML section name for bootstrap config. Default `'bootstrap'`. */
+    readonly bootstrapSection?: string;
+    /** YAML section name for app-specific config. Default: remaining object. */
+    readonly appSection?: string;
+    /** Caller-provided validator for the app config section. */
+    readonly appConfig?: ApplicationConfigValidator<TAppConfig>;
+    /** Override values merged after loading. */
+    readonly overrides?: Record<string, unknown>;
+}
+export type { BusLifecycleEvents, EventMap } from '../event-bus/types';
+export type { InfraEvents } from '../events';
+//# sourceMappingURL=types.d.ts.map

package/dist/application/types.d.ts.map

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

package/dist/application/types.js

@@ -0,0 +1,9 @@
+/**
+ * Portable application bootstrap types.
+ *
+ * These types define the DI contract for `runApplication` — a thin orchestration
+ * layer over existing ts-infra primitives. The portable subpath does not import
+ * any runtime-specific adapters; everything injectable comes through the options.
+ *
+ * @module application/types
+ */