@gobing-ai/ts-infra 0.3.4 → 0.3.6

package/dist/telemetry/sdk.d.ts

@@ -8,7 +8,39 @@
  * keeps the main barrel free of any SDK runtime dependency.
  */
 import { type Tracer } from '@opentelemetry/api';
-import type { TelemetryConfig } from './config';
+/**
+ * Full telemetry configuration: master enable switch, service name,
+ * environment, and debug-level DB statement capture.
+ */
+export interface TelemetryConfig {
+    /** Master switch — when false, all tracing degrades to no-ops. */
+    enabled: boolean;
+    /** Logical service name emitted on every span. */
+    serviceName: string;
+    /** Deployment environment (development, staging, production). */
+    environment: string;
+    /**
+     * Debug-only DB statement capture.
+     *
+     * When true, DB spans may include sanitized SQL text in a `db.statement`
+     * attribute. SQL text is redacted — parameter values, literals, and
+     * identifiers are stripped before capture.
+     *
+     * Default: `false`. Controlled by `OTEL_DB_STATEMENT_DEBUG` env var.
+     */
+    dbStatementDebug: boolean;
+}
+/** Partial telemetry config from the centralized config system. */
+export interface TelemetryConfigPartial {
+    enabled?: boolean | undefined;
+    serviceName?: string | undefined;
+    environment?: string | undefined;
+    dbStatementDebug?: boolean | undefined;
+    /** Deployment environment fallback (from app.env). */
+    appEnv?: string | undefined;
+}
+/** Resolve the full telemetry config by merging a partial override with defaults. */
+export declare function getTelemetryConfig(configPartial?: TelemetryConfigPartial): TelemetryConfig;
 /** Get the resolved telemetry configuration (defaults + overrides). */
 export declare function getResolvedConfig(): TelemetryConfig;
 /**

package/dist/telemetry/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/telemetry/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAShD,uEAAuE;AACvE,wBAAgB,iBAAiB,IAAI,eAAe,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAIrE;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGjD;AAED,gFAAgF;AAChF,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAED,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/telemetry/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AAIxD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC7B;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACnC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAQD,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,aAAa,GAAE,sBAA2B,GAAG,eAAe,CAO9F;AAQD,uEAAuE;AACvE,wBAAgB,iBAAiB,IAAI,eAAe,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAIrE;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAGjD;AAED,gFAAgF;AAChF,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAED,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/telemetry/sdk.js

@@ -8,7 +8,20 @@
  * keeps the main barrel free of any SDK runtime dependency.
  */
 import { trace } from '@opentelemetry/api';
-import { getTelemetryConfig } from './config.js';
+const CONFIG_DEFAULTS = {
+    enabled: true,
+    serviceName: 'ts-libs',
+    environment: 'development',
+};
+/** Resolve the full telemetry config by merging a partial override with defaults. */
+export function getTelemetryConfig(configPartial = {}) {
+    return {
+        enabled: configPartial.enabled ?? CONFIG_DEFAULTS.enabled,
+        serviceName: configPartial.serviceName ?? CONFIG_DEFAULTS.serviceName,
+        environment: configPartial.environment ?? configPartial.appEnv ?? CONFIG_DEFAULTS.environment,
+        dbStatementDebug: configPartial.dbStatementDebug ?? false,
+    };
+}
 const TRACER_NAME = '@gobing-ai/ts-infra';
 const TRACER_VERSION = '0.1.0';
 let telemetryInitialized = false;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.3.4",
+    "version": "0.3.6",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -47,6 +47,14 @@
         "./scheduler-node": {
             "types": "./dist/scheduler-node.d.ts",
             "import": "./dist/scheduler-node.js"
+        },
+        "./application": {
+            "types": "./dist/application/index.d.ts",
+            "import": "./dist/application/index.js"
+        },
+        "./application-node": {
+            "types": "./dist/application-node.d.ts",
+            "import": "./dist/application-node.js"
         }
     },
     "files": [
@@ -69,7 +77,8 @@
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.3.4",
+        "@gobing-ai/ts-db": "^0.3.6",
+        "@gobing-ai/ts-runtime": "^0.3.6",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -82,6 +91,9 @@
         "@gobing-ai/ts-db": {
             "optional": true
         },
+        "@gobing-ai/ts-runtime": {
+            "optional": true
+        },
         "@opentelemetry/sdk-trace-node": {
             "optional": true
         },
@@ -99,7 +111,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.3.4",
+        "@gobing-ai/ts-db": "^0.3.6",
+        "@gobing-ai/ts-runtime": "^0.3.6",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/application/index.ts

@@ -0,0 +1,248 @@
+/**
+ * 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';
+import { EventBus } from '../event-bus/event-bus';
+import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
+import type { InfraEvents } from '../events';
+import { getLogger, type Logger } from '../logger';
+import { initScheduler } from '../scheduler/factory';
+import type { SchedulerAdapter } from '../scheduler/types';
+import { loggerPlugin, schedulerPlugin, telemetryPlugin, userCallbackPlugin } from './plugins/builtins';
+import { PluginHost } from './plugins/host';
+import type {
+    ApplicationBootstrapConfig,
+    ApplicationBootstrapOptions,
+    ApplicationRuntime,
+    ApplicationStopReason,
+    DbAdapterLike,
+} from './types';
+
+// ── Internal runtime state ────────────────────────────────────────────────
+
+interface RuntimeState<TAppConfig, TEvents extends EventMap> {
+    app: ApplicationRuntime<TAppConfig, TEvents> | undefined;
+    pluginHost: PluginHost;
+    stopped: boolean;
+}
+
+// ── Shutdown (deterministic reverse order per R5) ─────────────────────────
+
+async function performShutdown<TAppConfig, TEvents extends EventMap>(
+    state: RuntimeState<TAppConfig, TEvents>,
+    reason: ApplicationStopReason,
+): Promise<void> {
+    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<TAppConfig = unknown, TEvents extends EventMap = InfraEvents>(
+    options: ApplicationBootstrapOptions<TAppConfig, TEvents>,
+): Promise<ApplicationRuntime<TAppConfig, TEvents>> {
+    // ── Resolve config ─────────────────────────────────────────────────
+
+    const logOpts = options.config?.logging;
+    const loggingConfig: ApplicationBootstrapConfig['logging'] = {
+        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: ApplicationBootstrapConfig['telemetry'] = {
+        enabled: telOpts?.enabled ?? true,
+        serviceName: telOpts?.serviceName ?? 'ts-libs',
+        environment: telOpts?.environment ?? 'development',
+        dbStatementDebug: telOpts?.dbStatementDebug ?? false,
+    };
+
+    const schedOpts = options.config?.scheduler;
+    const schedulerConfig: ApplicationBootstrapConfig['scheduler'] = {
+        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: RuntimeState<TAppConfig, TEvents> = {
+        app: undefined,
+        stopped: false,
+        pluginHost: undefined as unknown as PluginHost,
+    };
+
+    try {
+        // ── 1. Resolve logger (init deferred to loggerPlugin) ───────────
+        const logger: 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<TEvents>({ lifecycleBus: lifecycleBus as EventBus<BusLifecycleEvents> | undefined });
+
+        // ── 4. Database (injected only) ────────────────────────────────
+        const db: DbAdapterLike | undefined = options.services?.db;
+
+        // ── 5. Scheduler ───────────────────────────────────────────────
+        let scheduler: SchedulerAdapter | undefined;
+        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: PluginHost =
+            options.services?.pluginHost ?? new PluginHost(events as unknown as EventBus<EventMap>);
+        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: ApplicationBootstrapConfig = {
+            logging: loggingConfig,
+            events: { enabled: eventsEnabled, lifecycle: eventsLifecycle, defaultObservers: eventsDefaultObservers },
+            telemetry: telemetryConfig,
+            scheduler: schedulerConfig,
+        };
+
+        const app: ApplicationRuntime<TAppConfig, TEvents> = {
+            config: resolvedConfig,
+            appConfig: options.appConfig as TAppConfig,
+            logger,
+            events,
+            lifecycleBus,
+            db,
+            scheduler,
+            pluginHost,
+            stop: (reason?: ApplicationStopReason) => 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 as ((app: ApplicationRuntime<TAppConfig, TEvents>, reason: string) => void) | undefined,
+                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;
+    }
+}
+
+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';
+// Re-export types
+export type {
+    ApplicationBootstrapConfig,
+    ApplicationBootstrapOptions,
+    ApplicationConfigLoader,
+    ApplicationConfigValidator,
+    ApplicationRuntime,
+    ApplicationServices,
+    ApplicationStopReason,
+    ConfigValidationResult,
+    DbAdapterLike,
+    EventsOptions,
+    LoggingOptions,
+    SchedulerOptions,
+    TelemetryOptions,
+} from './types';

package/src/application/plugins/builtins.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 { initializeLogger } from '../../logger';
+import { initMetrics, shutdownMetrics } from '../../telemetry/metrics';
+import { initTelemetry, shutdownTelemetry } from '../../telemetry/sdk';
+import type { ApplicationBootstrapConfig, DbAdapterLike } from '../types';
+import type { Plugin } from './types';
+
+// ── 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: ApplicationBootstrapConfig['telemetry']): Plugin {
+    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: {
+        enabled: boolean;
+        level: LogLevel;
+        console: boolean;
+        json: boolean;
+        fileSink?: ((line: string) => void) | undefined;
+    },
+    injected?: boolean,
+): Plugin {
+    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,
+                });
+            }
+        },
+    };
+}
+
+// ── User callback ──────────────────────────────────────────────────────────
+
+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 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 {
+    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,
+    };
+}
+
+// ── Scheduler ──────────────────────────────────────────────────────────────
+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 function schedulerPlugin(adapter: SchedulerAdapter, autoStart: boolean): Plugin {
+    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: DbAdapterLike): Plugin {
+    return {
+        name: 'builtin:db',
+        version: '0.0.0',
+        failFast: false,
+        onLoad: async () => {},
+        onStart: async () => {},
+        onStop: async () => {
+            try {
+                db.close();
+            } catch {
+                /* best-effort */
+            }
+        },
+    };
+}