@gobing-ai/ts-infra 0.3.4 → 0.3.6

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
 
@@ -419,6 +421,125 @@ bun add @opentelemetry/sdk-trace-node @opentelemetry/sdk-metrics \
         @opentelemetry/exporter-metrics-otlp-http
 ```
 
+
+### Application Bootstrap
+
+The application bootstrap API provides a deterministic lifecycle for wiring
+infrastructure services. Two layers:
+
+1. **Portable DI bootstrap** (`@gobing-ai/ts-infra/application`) — orchestrates
+   injected dependencies. Never opens files, creates DB connections, or wires
+   runtime-specific exporters.
+2. **Node/Bun convenience** (`@gobing-ai/ts-infra/application-node`) — composes
+   the portable bootstrap with runtime-specific adapters: YAML config loading,
+   file log sink, Bun SQLite DB creation, Node OTel export, Node scheduler.
+
+#### Portable DI bootstrap
+
+```ts
+import { runApplication } from '@gobing-ai/ts-infra/application';
+
+const app = await runApplication({
+    config: {
+        logging: { level: 'info', console: true },
+        telemetry: { enabled: true, serviceName: 'my-api' },
+    },
+    appConfig: { port: 3000 },
+    async start(app) {
+        app.logger.info('started', { port: app.appConfig.port });
+    },
+});
+
+// Graceful shutdown — idempotent
+await app.stop();
+```
+
+The portable `runApplication` accepts pre-built services via `services` and
+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:
+
+```
+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.
+
+**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
+
+```ts
+import { runNodeApplication } from '@gobing-ai/ts-infra/application-node';
+
+await runNodeApplication({
+    configLoader: {
+        configFile: 'config/app.yaml',
+        bootstrapSection: 'bootstrap',
+        appSection: 'billing',
+        appConfig: {
+            // Structural safeParse adapter — works with Zod or any validator
+            safeParse(raw) {
+                return billingSchema.safeParse(raw);
+            },
+        },
+    },
+    async start(app) {
+        app.logger.info('billing app started', {
+            settlementWindowMinutes: app.appConfig.settlementWindowMinutes,
+        });
+    },
+});
+```
+
+Example YAML config file:
+
+```yaml
+app:
+  name: billing-api
+  env: production
+
+bootstrap:
+  logging:
+    level: info
+    console: true
+    filePath: ./logs/app.jsonl
+  telemetry:
+    enabled: true
+    serviceName: billing-api
+    endpoint: http://otel-collector:4318
+  database:
+    enabled: true
+    driver: bun-sqlite
+    url: ./data/app.db
+
+billing:
+  settlementWindowMinutes: 15
+  riskLimit: 100000
+```
+
+Config validators accept four shapes:
+- `{ safeParse(raw) → { success, data?, errors? } }` — Zod-compatible
+- `(raw) => TAppConfig` — bare function
+- `{ validate(raw) => TAppConfig }` — method form
+- `{ parse(raw) => TAppConfig }` — method form
+
+Validation errors include the config file path and section name for diagnostics.
+
+**What is intentionally NOT in the main barrel:** `runApplication` and
+`runNodeApplication` live behind explicit subpaths so the main
+`@gobing-ai/ts-infra` import stays portable and adapter-light. A future ADR
+may decide whether type-only re-exports are acceptable.
+
 ## Usage
 
 ### Install
@@ -436,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';
+
+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 });
+    },
+});
+```
 
-// 4. Telemetry
-initTelemetry({ serviceName: 'my-app', environment: 'production' });
+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.
 
-// 5. Event bus
-const bus = new EventBus<AppEvents>();
+#### Custom plugins
 
-// 6. Scheduler
-const scheduler = new NodeSchedulerAdapter();
-setSchedulerAdapter(scheduler);
-scheduler.register('3600000', async () => {
-    log.info('Hourly cleanup running');
-});
-await scheduler.start();
+Plugins run in registration order forward (`loadAll → startAll`) and reverse order
+on teardown (`stopAll → unloadAll`):
+
+```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 */ },
+};
 
-// 7. API client
-const stripeApi = new APIClient({
-    baseUrl: 'https://api.stripe.com/v1',
-    defaultHeaders: { Authorization: `Bearer ${process.env.STRIPE_KEY}` },
+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

@@ -0,0 +1,55 @@
+/**
+ * Portable `runApplication` — DI bootstrap over existing ts-infra primitives.
+ *
+ * Orchestrates logger, telemetry, event bus, (optional) DB adapter, and
+ * (optional) scheduler into a deterministic startup/shutdown lifecycle.
+ * The portable subpath never opens files, creates DB connections, or wires
+ * runtime-specific exporters — those are injected or handled by the
+ * Node/Bun convenience subpath.
+ *
+ * @module application
+ */
+import type { EventMap } from '../event-bus/types';
+import type { InfraEvents } from '../events';
+import type { ApplicationBootstrapOptions, ApplicationRuntime } from './types';
+/**
+ * Portable application bootstrap.
+ *
+ * Orchestrates logger, telemetry, events, optional DB, and optional scheduler.
+ * Accepts injected dependencies; never opens files, reads config from disk,
+ * or wires runtime-specific exporters.
+ *
+ * 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
+ * import { runApplication } from '@gobing-ai/ts-infra/application';
+ *
+ * const app = await runApplication({
+ *     config: { logging: { level: 'debug' } },
+ *     async start(app) {
+ *         app.logger.info('started');
+ *     },
+ * });
+ * ```
+ */
+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

@@ -0,0 +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;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

@@ -0,0 +1,173 @@
+/**
+ * Portable `runApplication` — DI bootstrap over existing ts-infra primitives.
+ *
+ * Orchestrates logger, telemetry, event bus, (optional) DB adapter, and
+ * (optional) scheduler into a deterministic startup/shutdown lifecycle.
+ * The portable subpath never opens files, creates DB connections, or wires
+ * runtime-specific exporters — those are injected or handled by the
+ * Node/Bun convenience subpath.
+ *
+ * @module application
+ */
+import { attachDefaultObservers, createLifecycleBus } from '../event-bus/default-observers.js';
+import { EventBus } from '../event-bus/event-bus.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)
+        return;
+    state.stopped = true;
+    const app = state.app;
+    if (!app)
+        return;
+    // 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 ────────────────────────────────────────────────────────────
+/**
+ * Portable application bootstrap.
+ *
+ * Orchestrates logger, telemetry, events, optional DB, and optional scheduler.
+ * Accepts injected dependencies; never opens files, reads config from disk,
+ * or wires runtime-specific exporters.
+ *
+ * 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
+ * import { runApplication } from '@gobing-ai/ts-infra/application';
+ *
+ * const app = await runApplication({
+ *     config: { logging: { level: 'debug' } },
+ *     async start(app) {
+ *         app.logger.info('started');
+ *     },
+ * });
+ * ```
+ */
+export async function runApplication(options) {
+    // ── Resolve config ─────────────────────────────────────────────────
+    const logOpts = options.config?.logging;
+    const loggingConfig = {
+        enabled: logOpts?.enabled ?? true,
+        level: logOpts?.level ?? 'info',
+        console: logOpts?.console ?? true,
+        json: logOpts?.json ?? true,
+        ...(logOpts?.fileSink ? { fileSink: logOpts.fileSink } : {}),
+    };
+    const telOpts = options.config?.telemetry;
+    const telemetryConfig = {
+        enabled: telOpts?.enabled ?? true,
+        serviceName: telOpts?.serviceName ?? 'ts-libs',
+        environment: telOpts?.environment ?? 'development',
+        dbStatementDebug: telOpts?.dbStatementDebug ?? false,
+    };
+    const schedOpts = options.config?.scheduler;
+    const schedulerConfig = {
+        enabled: schedOpts?.enabled ?? false,
+        autoStart: schedOpts?.autoStart ?? true,
+    };
+    const eventsEnabled = options.config?.events?.enabled ?? true;
+    const eventsLifecycle = options.config?.events?.lifecycle ?? true;
+    const eventsDefaultObservers = options.config?.events?.defaultObservers ?? true;
+    const state = {
+        app: undefined,
+        stopped: false,
+        pluginHost: undefined,
+    };
+    try {
+        // ── 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) {
+            attachDefaultObservers(lifecycleBus);
+        }
+        const events = options.services?.events
+            ? options.services.events
+            : new EventBus({ lifecycleBus: lifecycleBus });
+        // ── 4. Database (injected only) ────────────────────────────────
+        const db = options.services?.db;
+        // ── 5. Scheduler ───────────────────────────────────────────────
+        let scheduler;
+        if (schedulerConfig.enabled) {
+            const adapter = options.services?.scheduler ?? schedOpts?.adapter;
+            scheduler = initScheduler(adapter, schedOpts?.entries);
+        }
+        // ── 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,
+        };
+        const app = {
+            config: resolvedConfig,
+            appConfig: options.appConfig,
+            logger,
+            events,
+            lifecycleBus,
+            db,
+            scheduler,
+            pluginHost,
+            stop: (reason) => performShutdown(state, reason ?? 'manual'),
+        };
+        state.app = app;
+        // ── 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) {
+        // 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"}