@gobing-ai/ts-infra 0.3.5 → 0.3.7

package/README.md

@@ -14,6 +14,8 @@ Infrastructure backbone — typed event bus, queue/scheduler contracts, adapter
 | **Telemetry** | `telemetry/` | OTel instrumentation — tracing (`traceAsync`), metrics (12 instruments), SQL sanitizer; opt-in OTLP export via the `/otel-node` subpath |
 | **API Client** | `api-client.ts` | Typed HTTP client with OTel tracing, timeout, and error handling |
 | **Logger** | `logger.ts` | LogTape-backed structured logger with levels, child loggers, injectable sinks, and mute toggle |
+| **Application Bootstrap** | `application/` | Plugin-driven lifecycle: deterministic startup → shutdown, DI orchestration, services as plugins |
+| **Plugin Host** | `application/plugins/` | Insertion-ordered plugin registry, fail-fast/fail-soft lifecycle fan-out, reason-carrying teardown |
 
 ## Architecture
 
@@ -453,20 +455,26 @@ await app.stop();
 ```
 
 The portable `runApplication` accepts pre-built services via `services` and
-never reads files. All services are created with defaults; feature flags
-control what gets initialized. Startup order is deterministic:
+never reads files. The lifecycle is **plugin-driven**: infra services (logger,
+telemetry, scheduler) and the user `start`/`stop` callbacks are registered as
+built-in plugins on a `PluginHost`, in dependency order:
 
-1. Resolve bootstrap config + app config
-2. Initialize logger
-3. Initialize telemetry
-4. Create lifecycle bus + EventBus
-5. Register injected DB adapter
-6. Initialize scheduler + register entries
-7. Call user `start(app)` callback
-8. Start scheduler if `autoStart`
+```
+logger → telemetry → [your plugins] → user-callback → scheduler
+```
+
+`loadAll()` then `startAll()` run them forward (A→Z). Plugins marked `failFast`
+(the built-in services) abort the bootstrap if their `onStart` throws; other
+plugins are fail-soft. Shutdown is the reverse fan-out — `stop(reason)` calls
+each plugin's `onStop(host, reason)` in reverse registration order (scheduler
+stop, your `stop(app, reason)`, telemetry shutdown). `stop()` is idempotent —
+safe to call from multiple signal handlers.
 
-Shutdown runs in reverse order. `stop()` is idempotent — safe to call from
-multiple signal handlers.
+**DB ownership.** The portable layer **never closes a caller-injected
+`services.db`** — you own its lifecycle and must close it yourself. Only an
+adapter the bootstrap *creates* (e.g. the Node subpath's Bun SQLite adapter) is
+closed automatically, via a built-in DB plugin. (Changed in 0.x — previously the
+portable layer closed injected adapters unconditionally.)
 
 #### Node/Bun convenience bootstrap
 
@@ -549,68 +557,95 @@ bun add @opentelemetry/sdk-trace-node @opentelemetry/sdk-metrics \
         @opentelemetry/exporter-metrics-otlp-http
 ```
 
-### Full bootstrap example
+### Full bootstrap example (recommended: `runApplication` or `runNodeApplication`)
+
+Prefer the plugin-driven bootstrap over manual wiring — the host lifecycle handles
+startup ordering, reverse-order teardown, fail-fast/fail-soft policies, and idempotent
+stop. Two entry points:
 
 ```ts
-import { createRuntimeContextFromFactory } from '@gobing-ai/ts-runtime';
-import { createDbAdapter, applyMigrations } from '@gobing-ai/ts-db';
-import {
-    EventBus,
-    setSchedulerAdapter,
-    initTelemetry,
-    APIClient,
-    getLogger,
-    initializeLogger,
-} from '@gobing-ai/ts-infra';
-import { NodeSchedulerAdapter } from '@gobing-ai/ts-infra/scheduler-node';
+// Portable — inject everything yourself:
+import { runApplication } from '@gobing-ai/ts-infra/application';
 
-// 1. Runtime
-const ctx = await createRuntimeContextFromFactory();
+const app = await runApplication({
+    config: {
+        logging: { level: 'info', console: true },
+        telemetry: { enabled: true, serviceName: 'my-app' },
+    },
+    services: { db }, // caller-owned — you close it
+    async start(app) {
+        app.logger.info('started');
+    },
+    async stop(app, reason) {
+        app.logger.info('shutting down', { reason });
+    },
+});
 
-// 2. Database
-const db = await createDbAdapter({ driver: 'bun-sqlite', url: './data/app.db' });
-await applyMigrations(db);
-ctx.register('db', db);
+await app.stop('signal');
+```
 
-// 3. Logging
-await initializeLogger({ level: 'info', console: true });
-const log = getLogger('app');
+```ts
+// Node / Bun — YAML config, file logs, OTel export, Bun SQLite, Node scheduler:
+import { runNodeApplication } from '@gobing-ai/ts-infra/application-node';
 
-// 4. Telemetry
-initTelemetry({ serviceName: 'my-app', environment: 'production' });
+const app = await runNodeApplication({
+    configLoader: {
+        configFile: 'config/app.yaml',
+        bootstrapSection: 'bootstrap',
+        appSection: 'billing',
+        appConfig: { safeParse: (raw) => mySchema.safeParse(raw) },
+    },
+    async start(app) {
+        app.logger.info('started', { port: app.appConfig.port });
+    },
+});
+```
 
-// 5. Event bus
-const bus = new EventBus<AppEvents>();
+If you prefer manual wiring (e.g. you already have an init sequence), the individual
+subsystems still work standalone — `EventBus`, `APIClient`, `getLogger`, etc. are
+all importable directly from the main barrel and do not require the bootstrap.
 
-// 6. Scheduler
-const scheduler = new NodeSchedulerAdapter();
-setSchedulerAdapter(scheduler);
-scheduler.register('3600000', async () => {
-    log.info('Hourly cleanup running');
-});
-await scheduler.start();
+#### Custom plugins
+
+Plugins run in registration order forward (`loadAll → startAll`) and reverse order
+on teardown (`stopAll → unloadAll`):
 
-// 7. API client
-const stripeApi = new APIClient({
-    baseUrl: 'https://api.stripe.com/v1',
-    defaultHeaders: { Authorization: `Bearer ${process.env.STRIPE_KEY}` },
+```ts
+import { runApplication } from '@gobing-ai/ts-infra/application';
+import type { Plugin } from '@gobing-ai/ts-infra';
+
+const auditPlugin: Plugin = {
+    name: 'audit-logger',
+    version: '1.0.0',
+    failFast: false, // fail-soft: a throwing onStart is logged, boot continues
+    onLoad: async (host) => { /* validate preconditions — throws abort boot */ },
+    onStart: async (host) => { host.events.on('order.placed', auditHandler); },
+    onStop: async (host, reason) => { host.logger.info('persisting audit buffer', { reason }); },
+    onUnload: async () => { /* release resources */ },
+};
+
+const app = await runApplication({
+    plugins: [auditPlugin],
+    config: { logging: { console: true } },
 });
+```
 
-log.info('Application started');
+The host forwards the optional teardown `reason` (a plain `string` on the core contract,
+`ApplicationStopReason` — `'manual' | 'signal' | 'error' | 'shutdown'` — at the app level)
+to every plugin's `onStop`/`onUnload`. Built-in service plugins use this for log context;
+the user-callback plugin delivers it to your `stop(app, reason)`.
 ```
 
 ### Graceful shutdown
 
-```ts
-async function shutdown() {
-    log.info('Shutting down...');
-    await scheduler.stop();
-    db.close();
-    await shutdownTelemetry();
-    await ctx.dispose();
-    process.exit(0);
-}
+With `runApplication` or `runNodeApplication`, shutdown is a single idempotent call:
 
-process.on('SIGTERM', shutdown);
-process.on('SIGINT', shutdown);
+```ts
+process.on('SIGTERM', () => app.stop('signal'));
+process.on('SIGINT', () => app.stop('signal'));
 ```
+
+The host runs `stopAll(reason) → unloadAll(reason)` in reverse registration order:
+scheduler stops, your `stop` callback fires, telemetry flushes, and the optional
+DB adapter closes (if the bootstrap created it — caller-injected adapters are
+your responsibility). Idempotent: safe from overlapping signal handlers.

package/dist/application/index.d.ts

@@ -19,24 +19,20 @@ import type { ApplicationBootstrapOptions, ApplicationRuntime } from './types';
  * Accepts injected dependencies; never opens files, reads config from disk,
  * or wires runtime-specific exporters.
  *
- * Startup order (deterministic, per R5):
- * 1. Resolve bootstrap config + app config
- * 2. Initialize logger
- * 3. Initialize telemetry
- * 4. Create lifecycle bus + application EventBus
- * 5. Register DB adapter (injected only)
- * 6. Initialize scheduler + register entries
- * 7. Call user `start(app)` callback
- * 8. Start scheduler if `autoStart`
- *
- * Shutdown order (reverse, per R5):
- * 1. User `stop(app, reason)` callback
- * 2. Stop scheduler
- * 3. Close DB adapter
- * 4. Shut down telemetry
- *
- * If any startup step fails, already-started services are cleaned up in reverse
- * order before rethrowing. `stop()` is idempotent.
+ * Startup is plugin-driven. Built-in service plugins are registered in dependency
+ * order, then `loadAll()` + `startAll()` run them forward:
+ * 1. Resolve bootstrap config; build EventBus + PluginHost
+ * 2. Register built-ins in order: logger → telemetry → [caller plugins] →
+ *    user-callback → scheduler (scheduler last so autoStart runs after user start)
+ * 3. `loadAll()` then `startAll()` — `failFast` plugins abort boot on failure
+ *
+ * Shutdown is the reverse fan-out: `stopAll(reason)` → `unloadAll(reason)` calls
+ * every plugin's `onStop`/`onUnload` in reverse registration order (scheduler stop,
+ * user `stop(app, reason)`, telemetry shutdown, owned-DB close). Caller-injected
+ * `services.db` is caller-owned and never closed here.
+ *
+ * If startup fails, the host's reverse-order `stopAll('error')`/`unloadAll('error')`
+ * tears down whatever started before rethrowing. `stop()` is idempotent.
  *
  * @example
  * ```ts
@@ -53,5 +49,7 @@ import type { ApplicationBootstrapOptions, ApplicationRuntime } from './types';
 export declare function runApplication<TAppConfig = unknown, TEvents extends EventMap = InfraEvents>(options: ApplicationBootstrapOptions<TAppConfig, TEvents>): Promise<ApplicationRuntime<TAppConfig, TEvents>>;
 export type { BusLifecycleEvents, EventMap } from '../event-bus/types';
 export type { InfraEvents } from '../events';
+export type { PluginHost } from './plugins/host';
+export type { Plugin, PluginSummary } from './plugins/types';
 export type { ApplicationBootstrapConfig, ApplicationBootstrapOptions, ApplicationConfigLoader, ApplicationConfigValidator, ApplicationRuntime, ApplicationServices, ApplicationStopReason, ConfigValidationResult, DbAdapterLike, EventsOptions, LoggingOptions, SchedulerOptions, TelemetryOptions, } from './types';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/application/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAsB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAK7C,OAAO,KAAK,EAER,2BAA2B,EAC3B,kBAAkB,EAGrB,MAAM,SAAS,CAAC;AAuDjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,cAAc,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW,EAC7F,OAAO,EAAE,2BAA2B,CAAC,UAAU,EAAE,OAAO,CAAC,GAC1D,OAAO,CAAC,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAyIlD;AAED,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,YAAY,EACR,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/application/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAsB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAM7C,OAAO,KAAK,EAER,2BAA2B,EAC3B,kBAAkB,EAGrB,MAAM,SAAS,CAAC;AAiCjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,cAAc,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW,EAC7F,OAAO,EAAE,2BAA2B,CAAC,UAAU,EAAE,OAAO,CAAC,GAC1D,OAAO,CAAC,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAkIlD;AAED,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE7D,YAAY,EACR,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,SAAS,CAAC"}

package/dist/application/index.js

@@ -11,9 +11,10 @@
  */
 import { attachDefaultObservers, createLifecycleBus } from '../event-bus/default-observers.js';
 import { EventBus } from '../event-bus/event-bus.js';
-import { getLogger, initializeLogger } from '../logger.js';
-import { initScheduler, setSchedulerAdapter } from '../scheduler/factory.js';
-import { initTelemetry, shutdownTelemetry } from '../telemetry/sdk.js';
+import { getLogger } from '../logger.js';
+import { initScheduler } from '../scheduler/factory.js';
+import { loggerPlugin, schedulerPlugin, telemetryPlugin, userCallbackPlugin } from './plugins/builtins.js';
+import { PluginHost } from './plugins/host.js';
 // ── Shutdown (deterministic reverse order per R5) ─────────────────────────
 async function performShutdown(state, reason) {
     if (state.stopped)
@@ -22,29 +23,13 @@ async function performShutdown(state, reason) {
     const app = state.app;
     if (!app)
         return;
-    // 1. User stop callback
-    if (state.userStop) {
-        await state.userStop(app, reason);
-    }
-    // 2. Stop scheduler
-    if (state.schedulerStarted && state.schedulerAdapter) {
-        await state.schedulerAdapter.stop().catch(() => { });
-        state.schedulerStarted = false;
-    }
-    // 3. Close DB adapter
-    if (app.db) {
-        try {
-            app.db.close();
-        }
-        catch {
-            /* best-effort */
-        }
-    }
-    // 4. Shutdown telemetry
-    if (state.telemetryInitialized) {
-        await shutdownTelemetry();
-        state.telemetryInitialized = false;
-    }
+    // 1. Stop + unload plugins in reverse registration order (fail-soft).
+    //    Scheduler stop and telemetry shutdown run here via their onStop hooks.
+    await state.pluginHost.stopAll(reason);
+    await state.pluginHost.unloadAll(reason);
+    // Shutdown is complete — the host's stopAll/unloadAll calls every plugin's
+    // onStop/onUnload in reverse registration order, including user callback,
+    // scheduler, and service teardown. No inline steps.
 }
 // ── Public API ────────────────────────────────────────────────────────────
 /**
@@ -54,24 +39,20 @@ async function performShutdown(state, reason) {
  * Accepts injected dependencies; never opens files, reads config from disk,
  * or wires runtime-specific exporters.
  *
- * Startup order (deterministic, per R5):
- * 1. Resolve bootstrap config + app config
- * 2. Initialize logger
- * 3. Initialize telemetry
- * 4. Create lifecycle bus + application EventBus
- * 5. Register DB adapter (injected only)
- * 6. Initialize scheduler + register entries
- * 7. Call user `start(app)` callback
- * 8. Start scheduler if `autoStart`
+ * Startup is plugin-driven. Built-in service plugins are registered in dependency
+ * order, then `loadAll()` + `startAll()` run them forward:
+ * 1. Resolve bootstrap config; build EventBus + PluginHost
+ * 2. Register built-ins in order: logger → telemetry → [caller plugins] →
+ *    user-callback → scheduler (scheduler last so autoStart runs after user start)
+ * 3. `loadAll()` then `startAll()` — `failFast` plugins abort boot on failure
  *
- * Shutdown order (reverse, per R5):
- * 1. User `stop(app, reason)` callback
- * 2. Stop scheduler
- * 3. Close DB adapter
- * 4. Shut down telemetry
+ * Shutdown is the reverse fan-out: `stopAll(reason)` → `unloadAll(reason)` calls
+ * every plugin's `onStop`/`onUnload` in reverse registration order (scheduler stop,
+ * user `stop(app, reason)`, telemetry shutdown, owned-DB close). Caller-injected
+ * `services.db` is caller-owned and never closed here.
  *
- * If any startup step fails, already-started services are cleaned up in reverse
- * order before rethrowing. `stop()` is idempotent.
+ * If startup fails, the host's reverse-order `stopAll('error')`/`unloadAll('error')`
+ * tears down whatever started before rethrowing. `stop()` is idempotent.
  *
  * @example
  * ```ts
@@ -112,41 +93,13 @@ export async function runApplication(options) {
     const eventsDefaultObservers = options.config?.events?.defaultObservers ?? true;
     const state = {
         app: undefined,
-        userStop: options.stop,
-        schedulerAdapter: undefined,
-        schedulerStarted: false,
-        loggerInitialized: false,
-        telemetryInitialized: false,
         stopped: false,
+        pluginHost: undefined,
     };
     try {
-        // ── 1. Initialize logger ────────────────────────────────────────
-        let logger;
-        if (options.services?.logger) {
-            logger = options.services.logger;
-        }
-        else if (loggingConfig.enabled) {
-            await initializeLogger({
-                level: loggingConfig.level,
-                console: loggingConfig.console,
-                fileSink: loggingConfig.fileSink,
-                json: loggingConfig.json,
-            });
-            logger = getLogger('bootstrap');
-        }
-        else {
-            logger = getLogger('bootstrap');
-        }
-        // ── 2. Initialize telemetry ────────────────────────────────────
-        if (telemetryConfig.enabled) {
-            initTelemetry({
-                enabled: telemetryConfig.enabled,
-                serviceName: telemetryConfig.serviceName,
-                environment: telemetryConfig.environment,
-                dbStatementDebug: telemetryConfig.dbStatementDebug,
-            });
-            state.telemetryInitialized = true;
-        }
+        // ── 1. Resolve logger (init deferred to loggerPlugin) ───────────
+        const logger = options.services?.logger ?? getLogger('bootstrap');
+        const loggerInjected = !!options.services?.logger;
         // ── 3. Create lifecycle bus + EventBus ─────────────────────────
         const lifecycleBus = eventsEnabled && eventsLifecycle ? (options.services?.lifecycleBus ?? createLifecycleBus()) : undefined;
         if (lifecycleBus && eventsDefaultObservers) {
@@ -161,20 +114,24 @@ export async function runApplication(options) {
         let scheduler;
         if (schedulerConfig.enabled) {
             const adapter = options.services?.scheduler ?? schedOpts?.adapter;
-            if (adapter) {
-                setSchedulerAdapter(adapter);
-            }
-            scheduler = initScheduler(schedOpts?.entries);
-            state.schedulerAdapter = scheduler;
+            scheduler = initScheduler(adapter, schedOpts?.entries);
         }
-        // ── Build resolved config ──────────────────────────────────────
+        // ── 5.5 Plugin host + built-in service plugins ─────────────────
+        const pluginHost = options.services?.pluginHost ?? new PluginHost(events);
+        state.pluginHost = pluginHost;
+        // Register built-in service plugins in dependency order: logger -> telemetry.
+        pluginHost.register(loggerPlugin(loggingConfig, loggerInjected));
+        pluginHost.register(telemetryPlugin(telemetryConfig));
+        // Caller-injected `services.db` is NOT closed by the portable layer — it is
+        // caller-owned (task 0028). Only adapters the bootstrap CREATES (the Node
+        // subpath) are wrapped in a `dbPlugin` whose onStop closes them.
+        // ── Build runtime handle (before startAll so plugins can capture it) ─
         const resolvedConfig = {
             logging: loggingConfig,
             events: { enabled: eventsEnabled, lifecycle: eventsLifecycle, defaultObservers: eventsDefaultObservers },
             telemetry: telemetryConfig,
             scheduler: schedulerConfig,
         };
-        // ── Build runtime handle ───────────────────────────────────────
         const app = {
             config: resolvedConfig,
             appConfig: options.appConfig,
@@ -183,28 +140,34 @@ export async function runApplication(options) {
             lifecycleBus,
             db,
             scheduler,
+            pluginHost,
             stop: (reason) => performShutdown(state, reason ?? 'manual'),
         };
         state.app = app;
-        // ── 6. User start callback ─────────────────────────────────────
-        await options.start(app);
-        // ── 7. Start scheduler ─────────────────────────────────────────
-        if (schedulerConfig.enabled && schedulerConfig.autoStart && scheduler) {
-            await scheduler.start();
-            state.schedulerStarted = true;
+        // ── Register caller-provided plugins (before user callback) ─────────
+        if (options.plugins) {
+            for (const p of options.plugins) {
+                pluginHost.register(p);
+            }
+        }
+        // ── Register user-callback plugin (after services, before scheduler) ─
+        pluginHost.register(userCallbackPlugin(options.start, options.stop, app));
+        // ── Register scheduler plugin (LAST — autoStart after user callback) ─
+        if (schedulerConfig.enabled && scheduler) {
+            pluginHost.register(schedulerPlugin(scheduler, schedulerConfig.autoStart));
         }
+        // ── Load + start (built-in failFast=rethrow on critical failure) ─
+        await pluginHost.loadAll();
+        await pluginHost.startAll();
         return app;
     }
     catch (error) {
-        // Reverse-order cleanup of services this bootstrap owns.
-        // Scheduler: start() is the last async op before return; if it throws,
-        // schedulerStarted is still false, so there is nothing started to stop.
-        // DB: injected by the caller (portable bootstrap never creates one), so
-        // its lifecycle is caller-owned and not closed here.
-        // Telemetry: owned by the bootstrap — shut it down if it was initialized.
-        if (state.telemetryInitialized) {
-            await shutdownTelemetry();
-        }
+        // Startup failed: tear down whatever started, in reverse registration
+        // order, via the host. Each plugin's onStop/onUnload is best-effort, so a
+        // partially-started ring still releases its resources (telemetry, scheduler,
+        // owned DB). Caller-injected services.db is caller-owned and not touched.
+        await state.pluginHost.stopAll('error');
+        await state.pluginHost.unloadAll('error');
         throw error;
     }
 }

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

@@ -0,0 +1,64 @@
+/**
+ * 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 type { LogLevel } from '../../logger';
+import type { ApplicationBootstrapConfig, DbAdapterLike } from '../types';
+import type { Plugin } from './types';
+/**
+ * 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 declare function telemetryPlugin(config: ApplicationBootstrapConfig['telemetry']): Plugin;
+/**
+ * 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 declare function loggerPlugin(config: {
+    enabled: boolean;
+    level: LogLevel;
+    console: boolean;
+    json: boolean;
+    fileSink?: ((line: string) => void) | undefined;
+}, injected?: boolean): Plugin;
+import type { EventMap } from '../../event-bus/types';
+import type { ApplicationRuntime } from '../types';
+/**
+ * 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 declare function userCallbackPlugin<TAppConfig, TEvents extends EventMap>(start: (app: ApplicationRuntime<TAppConfig, TEvents>) => Promise<void> | void, stop: ((app: ApplicationRuntime<TAppConfig, TEvents>, reason: string) => Promise<void> | void) | undefined, app?: ApplicationRuntime<TAppConfig, TEvents>): Plugin;
+import type { SchedulerAdapter } from '../../scheduler/types';
+/**
+ * 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 declare function schedulerPlugin(adapter: SchedulerAdapter, autoStart: boolean): Plugin;
+/**
+ * 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 declare function dbPlugin(db: DbAdapterLike): Plugin;
+//# sourceMappingURL=builtins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../../src/application/plugins/builtins.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAI7C,OAAO,KAAK,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAItC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,0BAA0B,CAAC,WAAW,CAAC,GAAG,MAAM,CAwBvF;AAID;;;;;;GAMG;AACH,wBAAgB,YAAY,CACxB,MAAM,EAAE;IACJ,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACnD,EACD,QAAQ,CAAC,EAAE,OAAO,GACnB,MAAM,CAiBR;AAID,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,OAAO,SAAS,QAAQ,EACnE,KAAK,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAC7E,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,EAC1G,GAAG,CAAC,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,GAC9C,MAAM,CAgBR;AAGD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAgBrF;AAID;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,CAelD"}