@gobing-ai/ts-infra 0.3.1 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # @gobing-ai/ts-infra
 
-Infrastructure backbone — typed event bus, DB-backed job queue, cron scheduler, OpenTelemetry telemetry, HTTP API client, and structured logging.
+Infrastructure backbone — typed event bus, queue/scheduler contracts, adapter subpaths, OpenTelemetry instrumentation, HTTP API client, and structured logging.
 
 ## Overview
 
@@ -9,11 +9,11 @@ Infrastructure backbone — typed event bus, DB-backed job queue, cron scheduler
 | Subsystem | Module | Purpose |
 |-----------|--------|---------|
 | **Event Bus** | `event-bus/` | Typed pub/sub with sync + async dispatch, lifecycle self-observability |
-| **Job Queue** | `job-queue/` | DB-backed enqueue and consume flow (`DBJobQueue`, `DBQueueConsumer`) plus queue interfaces |
-| **Scheduler** | `scheduler/` | Cron-like scheduled actions — Node (interval), Cloudflare (Cron Triggers), Noop (test) |
+| **Job Queue** | core + `/job-queue-db` | Queue interfaces in core; DB-backed enqueue/consume flow (`DBJobQueue`, `DBQueueConsumer`) via opt-in subpath |
+| **Scheduler** | core + scheduler subpaths | Scheduler contracts, registry, built-in actions, noop adapter in core; Node and Cloudflare adapters via opt-in subpaths |
 | **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` | Structured JSON logger with levels, child loggers, and mute toggle |
+| **Logger** | `logger.ts` | LogTape-backed structured logger with levels, child loggers, injectable sinks, and mute toggle |
 
 ## Architecture
 
@@ -139,16 +139,15 @@ classDiagram
         }
         class LoggerFactory {
             +getLogger(category) Logger
-            +initializeLogger(level) void
+            +initializeLogger(options?) Promise~void~
         }
     }
 
     SchedulerAdapter <|.. NodeSchedulerAdapter : implements
     SchedulerAdapter <|.. CloudflareSchedulerAdapter : implements
     SchedulerAdapter <|.. NoopSchedulerAdapter : implements
-    SchedulerFactory --> NodeSchedulerAdapter
-    SchedulerFactory --> CloudflareSchedulerAdapter
-    SchedulerFactory --> NoopSchedulerAdapter
+    SchedulerFactory --> SchedulerAdapter : "uses injected adapter"
+    SchedulerFactory --> NoopSchedulerAdapter : "default when none injected"
     EventBus --> JobQueue : "async dispatch"
     DBJobQueue --> JobQueue : "implements"
     DBQueueConsumer --> QueueConsumer : "implements"
@@ -162,7 +161,7 @@ classDiagram
 ### Event Bus — typed pub/sub
 
 ```ts
-import { EventBus, type EventMap } from '@gobing-ai/ts-infra';
+import { attachDefaultObservers, createLifecycleBus, EventBus, type EventMap } from '@gobing-ai/ts-infra';
 
 // Define your event map
 type AppEvents = {
@@ -193,14 +192,11 @@ bus.once('user.signed_up', () => console.log('one-time'));
 **Lifecycle events** — inject a second `EventBus` to observe bus internals:
 
 ```ts
-type LifecycleEvents = {
-    'bus.emit.done': (detail: { event: string; syncCount: number; asyncCount: number; emitDurationMs: number }) => void;
-};
-
-const lifecycleBus = new EventBus<LifecycleEvents>();
+const lifecycleBus = createLifecycleBus();
+attachDefaultObservers(lifecycleBus); // log + telemetry spans; metrics are emitted by EventBus itself
 lifecycleBus.on('bus.emit.done', (detail) => {
     // { event, syncCount, asyncCount, emitDurationMs, errors }
-    metrics.recordEmit(detail);
+    console.debug('EventBus emit complete', detail);
 });
 
 const bus = new EventBus<AppEvents>({ lifecycleBus });
@@ -208,11 +204,11 @@ const bus = new EventBus<AppEvents>({ lifecycleBus });
 
 ### Job Queue — DB-backed async work
 
-`DBJobQueue` and `DBQueueConsumer` run over `@gobing-ai/ts-db`'s `QueueJobDao`. Use this when event handlers, schedulers, or API handlers need durable background work with retries.
+`DBJobQueue` and `DBQueueConsumer` live behind the `@gobing-ai/ts-infra/job-queue-db` subpath and run over `@gobing-ai/ts-db`'s `QueueJobDao`. Use this when event handlers, schedulers, or API handlers need durable background work with retries.
 
 ```ts
 import { createDbAdapter, QueueJobDao } from '@gobing-ai/ts-db';
-import { DBJobQueue, DBQueueConsumer } from '@gobing-ai/ts-infra';
+import { DBJobQueue, DBQueueConsumer } from '@gobing-ai/ts-infra/job-queue-db';
 
 const db = await createDbAdapter({ driver: 'bun-sqlite', url: './jobs.db' });
 const dao = new QueueJobDao(db);
@@ -248,7 +244,8 @@ The consumer claims ready jobs, resets stuck processing jobs after the visibilit
 ### Scheduler — cron-like actions
 
 ```ts
-import { NodeSchedulerAdapter, initScheduler } from '@gobing-ai/ts-infra';
+import { initScheduler, setSchedulerAdapter } from '@gobing-ai/ts-infra';
+import { NodeSchedulerAdapter } from '@gobing-ai/ts-infra/scheduler-node';
 
 // Node.js (interval-based)
 const scheduler = new NodeSchedulerAdapter();
@@ -260,7 +257,8 @@ scheduler.register('*/5 * * * *', async () => {
 });
 await scheduler.start();
 
-// Or use factory
+// Or use the core factory after injecting the runtime adapter
+setSchedulerAdapter(new NodeSchedulerAdapter());
 const sched = initScheduler([
     ['300000', async () => cleanupExpiredSessions()],
     ['3600000', async () => generateReports()],
@@ -268,7 +266,7 @@ const sched = initScheduler([
 await sched.start();
 
 // Cloudflare Workers
-import { CloudflareSchedulerAdapter } from '@gobing-ai/ts-infra';
+import { CloudflareSchedulerAdapter } from '@gobing-ai/ts-infra/scheduler-cloudflare';
 const cfScheduler = new CloudflareSchedulerAdapter();
 cfScheduler.register('* * * * *', async () => { /* ... */ });
 
@@ -312,7 +310,11 @@ The client auto-instruments every request: creates a `CLIENT` span, records meth
 ```ts
 import { getLogger, initializeLogger } from '@gobing-ai/ts-infra';
 
-initializeLogger('debug'); // set minimum level
+await initializeLogger({
+    level: 'debug',
+    console: true,
+    json: true,
+});
 
 const log = getLogger('auth');
 log.info('User logged in', { userId: 'u1', method: 'password' });
@@ -323,7 +325,15 @@ const reqLog = log.child({ requestId: 'req-123' });
 reqLog.error('Validation failed', { field: 'email' });
 // → {...,"category":"auth","requestId":"req-123","field":"email"}
 
-// In tests, prefer injecting a logger boundary or initializing at a quiet level.
+// File logging is also injectable; ts-infra never opens files directly.
+await initializeLogger({
+    console: false,
+    fileSink: (line) => {
+        // Append `line` using the host runtime's FileSystem / stream owner.
+    },
+});
+
+// In tests, prefer injecting a logger boundary or initializing with console: false.
 ```
 
 ### Telemetry — OpenTelemetry
@@ -397,8 +407,10 @@ process.on('SIGTERM', async () => {
 ```
 
 The exporter packages are **optional peers** — only consumers of `/otel-node`
-need them installed. The main `@gobing-ai/ts-infra` import never pulls them, so
-BYO and browser/edge consumers stay lean. To use the subpath:
+need them installed. `@opentelemetry/api` and semantic conventions are the only
+OTel packages used by the core instrumentation surface. The main
+`@gobing-ai/ts-infra` import never pulls exporter/provider SDKs, so BYO and
+browser/edge consumers stay lean. To use the subpath:
 
 ```bash
 bun add @opentelemetry/sdk-trace-node @opentelemetry/sdk-metrics \
@@ -412,25 +424,35 @@ bun add @opentelemetry/sdk-trace-node @opentelemetry/sdk-metrics \
 ### Install
 
 ```bash
-bun add @gobing-ai/ts-infra @gobing-ai/ts-runtime @gobing-ai/ts-db
+bun add @gobing-ai/ts-infra
+
+# Only needed when using @gobing-ai/ts-infra/job-queue-db.
+bun add @gobing-ai/ts-db
+
+# Only needed when using @gobing-ai/ts-infra/otel-node.
+bun add @opentelemetry/sdk-trace-node @opentelemetry/sdk-metrics \
+        @opentelemetry/resources \
+        @opentelemetry/exporter-trace-otlp-http \
+        @opentelemetry/exporter-metrics-otlp-http
 ```
 
 ### Full bootstrap example
 
 ```ts
-import { createRuntimeContext } from '@gobing-ai/ts-runtime';
+import { createRuntimeContextFromFactory } from '@gobing-ai/ts-runtime';
 import { createDbAdapter, applyMigrations } from '@gobing-ai/ts-db';
 import {
     EventBus,
-    NodeSchedulerAdapter,
+    setSchedulerAdapter,
     initTelemetry,
     APIClient,
     getLogger,
     initializeLogger,
 } from '@gobing-ai/ts-infra';
+import { NodeSchedulerAdapter } from '@gobing-ai/ts-infra/scheduler-node';
 
 // 1. Runtime
-const ctx = createRuntimeContext({ runtimeName: 'node-bun' });
+const ctx = await createRuntimeContextFromFactory();
 
 // 2. Database
 const db = await createDbAdapter({ driver: 'bun-sqlite', url: './data/app.db' });
@@ -438,7 +460,7 @@ await applyMigrations(db);
 ctx.register('db', db);
 
 // 3. Logging
-initializeLogger('info');
+await initializeLogger({ level: 'info', console: true });
 const log = getLogger('app');
 
 // 4. Telemetry
@@ -449,6 +471,7 @@ const bus = new EventBus<AppEvents>();
 
 // 6. Scheduler
 const scheduler = new NodeSchedulerAdapter();
+setSchedulerAdapter(scheduler);
 scheduler.register('3600000', async () => {
     log.info('Hourly cleanup running');
 });

package/dist/api-client.d.ts

@@ -1,20 +1,33 @@
+/** Configuration for {@link APIClient}: base URL, default headers, timeout, and optional custom fetch. */
 export interface APIClientConfig {
     baseUrl: string;
     defaultHeaders?: Record<string, string>;
     timeout?: number;
     fetch?: typeof globalThis.fetch;
 }
+/** Per-request overrides: headers, timeout, operation name, and abort signal. */
 export interface RequestOptions {
     headers?: Record<string, string>;
     timeout?: number;
     operationName?: string;
     signal?: AbortSignal;
 }
+/** HTTP error with status code and response body text. */
 export declare class APIError extends Error {
     readonly status: number;
     readonly body: string;
     constructor(status: number, body: string);
 }
+/**
+ * Typed HTTP client builder wrapping fetch with automatic JSON serialization,
+ * timeout support, and OpenTelemetry tracing on every request.
+ *
+ * @example
+ * ```ts
+ * const client = new APIClient({ baseUrl: 'https://api.example.com' });
+ * const data = await client.get<User>('/users/1');
+ * ```
+ */
 export declare class APIClient {
     private readonly baseUrl;
     private readonly defaultHeaders;

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,qBAAa,QAAS,SAAQ,KAAK;aAEX,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAKnC;AAID,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,MAAM,EAAE,eAAe;IAOnC,OAAO,CAAC,QAAQ;YAIF,OAAO;IAqFf,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvD,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvE,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CAGnE"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAkBA,0GAA0G;AAC1G,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACnC;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,0DAA0D;AAC1D,qBAAa,QAAS,SAAQ,KAAK;aAEX,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAKnC;AAID;;;;;;;;;GASG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,MAAM,EAAE,eAAe;IAOnC,OAAO,CAAC,QAAQ;YAIF,OAAO;IAmFf,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvD,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvE,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CAGnE"}

package/dist/api-client.js

@@ -5,6 +5,7 @@ import { SpanKind } from '@opentelemetry/api';
 import { ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_URL_FULL, } from '@opentelemetry/semantic-conventions';
 import { getHttpClientRequestDuration, getHttpClientRequestErrors, getHttpClientRequestTotal, } from './telemetry/metrics.js';
 import { traceAsync } from './telemetry/tracing.js';
+/** HTTP error with status code and response body text. */
 export class APIError extends Error {
     status;
     body;
@@ -16,6 +17,16 @@ export class APIError extends Error {
     }
 }
 // ── Client ──────────────────────────────────────────────────────────
+/**
+ * Typed HTTP client builder wrapping fetch with automatic JSON serialization,
+ * timeout support, and OpenTelemetry tracing on every request.
+ *
+ * @example
+ * ```ts
+ * const client = new APIClient({ baseUrl: 'https://api.example.com' });
+ * const data = await client.get<User>('/users/1');
+ * ```
+ */
 export class APIClient {
     baseUrl;
     defaultHeaders;
@@ -58,8 +69,6 @@ export class APIClient {
                     body: body !== undefined ? JSON.stringify(body) : undefined,
                     signal: combinedSignal,
                 });
-                if (timer)
-                    clearTimeout(timer);
                 span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.status);
                 getHttpClientRequestTotal().add(1, {
                     'http.request.method': method,
@@ -85,8 +94,6 @@ export class APIClient {
                 return (await response.text());
             }
             catch (error) {
-                if (timer)
-                    clearTimeout(timer);
                 if (!(error instanceof APIError)) {
                     getHttpClientRequestErrors().add(1, {
                         'http.request.method': method,
@@ -95,6 +102,10 @@ export class APIClient {
                 }
                 throw error;
             }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
         }, { kind: SpanKind.CLIENT });
     }
     async get(path, opts) {

package/dist/event-bus/default-observers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Default lifecycle observers for EventBus self-observability.
+ *
+ * Connect `BusLifecycleEvents` to the logging and telemetry infrastructure so
+ * operators get visibility without wiring everything by hand. Opt-in: nothing
+ * is attached unless you call one of these.
+ *
+ * **Metrics are intentionally omitted here.** Unlike the original design, the
+ * `EventBus` core now increments `eventbus.emits.total` / `eventbus.errors.total`
+ * inline on every emit (see `event-bus.ts`). A metrics observer would
+ * double-count, so the restored default set is **log + telemetry-trace only**.
+ *
+ * @example One-liner setup
+ * ```ts
+ * import { EventBus, createLifecycleBus, attachDefaultObservers } from '@gobing-ai/ts-infra';
+ *
+ * const lifecycleBus = createLifecycleBus();
+ * attachDefaultObservers(lifecycleBus);
+ *
+ * const appBus = new EventBus<AppEvents>({ lifecycleBus });
+ * ```
+ */
+import { EventBus } from './event-bus';
+import type { BusLifecycleEvents } from './types';
+/**
+ * Create a dedicated `EventBus<BusLifecycleEvents>` for use as the
+ * `lifecycleBus` constructor argument on another `EventBus`.
+ */
+export declare function createLifecycleBus(): EventBus<BusLifecycleEvents>;
+/**
+ * Register handlers that write structured log entries for every lifecycle event.
+ *
+ * - `bus.emit.done`   → debug (warn if errors > 0)
+ * - `bus.emit.noop`   → debug
+ * - `bus.handler.error` → warn
+ * - `bus.handler.async.enqueued` → debug
+ */
+export declare function attachLogObserver(lifecycleBus: EventBus<BusLifecycleEvents>): void;
+/**
+ * Register handlers that create OpenTelemetry spans for emit operations.
+ *
+ * Each `bus.emit.done` creates a span named `eventbus.emit.{EVENT}` with
+ * attributes for sync/async counts, duration, and error count. Degrades
+ * gracefully when telemetry is not initialised (`traceAsync` is a pass-through).
+ */
+export declare function attachTelemetryObserver(lifecycleBus: EventBus<BusLifecycleEvents>): void;
+/**
+ * Attach the built-in observers (log + telemetry) to the lifecycle bus in one
+ * call. Recommended default for production deployments. Metrics are emitted by
+ * the `EventBus` core inline, so they are not part of this set.
+ */
+export declare function attachDefaultObservers(lifecycleBus: EventBus<BusLifecycleEvents>): void;
+//# sourceMappingURL=default-observers.d.ts.map

package/dist/event-bus/default-observers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-observers.d.ts","sourceRoot":"","sources":["../../src/event-bus/default-observers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAQlD;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,CAAC,kBAAkB,CAAC,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAoBlF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,IAAI,CA2BxF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAGvF"}

package/dist/event-bus/default-observers.js

@@ -0,0 +1,107 @@
+/**
+ * Default lifecycle observers for EventBus self-observability.
+ *
+ * Connect `BusLifecycleEvents` to the logging and telemetry infrastructure so
+ * operators get visibility without wiring everything by hand. Opt-in: nothing
+ * is attached unless you call one of these.
+ *
+ * **Metrics are intentionally omitted here.** Unlike the original design, the
+ * `EventBus` core now increments `eventbus.emits.total` / `eventbus.errors.total`
+ * inline on every emit (see `event-bus.ts`). A metrics observer would
+ * double-count, so the restored default set is **log + telemetry-trace only**.
+ *
+ * @example One-liner setup
+ * ```ts
+ * import { EventBus, createLifecycleBus, attachDefaultObservers } from '@gobing-ai/ts-infra';
+ *
+ * const lifecycleBus = createLifecycleBus();
+ * attachDefaultObservers(lifecycleBus);
+ *
+ * const appBus = new EventBus<AppEvents>({ lifecycleBus });
+ * ```
+ */
+import { getLogger } from '../logger.js';
+import { addSpanAttributes, addSpanEvent, traceAsync } from '../telemetry/tracing.js';
+import { EventBus } from './event-bus.js';
+let _obsLogger;
+function obsLogger() {
+    if (!_obsLogger)
+        _obsLogger = getLogger('event-bus.observers');
+    return _obsLogger;
+}
+/**
+ * Create a dedicated `EventBus<BusLifecycleEvents>` for use as the
+ * `lifecycleBus` constructor argument on another `EventBus`.
+ */
+export function createLifecycleBus() {
+    return new EventBus();
+}
+/**
+ * Register handlers that write structured log entries for every lifecycle event.
+ *
+ * - `bus.emit.done`   → debug (warn if errors > 0)
+ * - `bus.emit.noop`   → debug
+ * - `bus.handler.error` → warn
+ * - `bus.handler.async.enqueued` → debug
+ */
+export function attachLogObserver(lifecycleBus) {
+    lifecycleBus.on('bus.emit.done', (detail) => {
+        if (detail.errors > 0) {
+            obsLogger().warn('emit completed with errors', { ...detail });
+        }
+        else {
+            obsLogger().debug('emit done', { ...detail });
+        }
+    });
+    lifecycleBus.on('bus.emit.noop', (detail) => {
+        obsLogger().debug('emit with zero handlers', { ...detail });
+    });
+    lifecycleBus.on('bus.handler.error', (detail) => {
+        obsLogger().warn('handler error', { ...detail });
+    });
+    lifecycleBus.on('bus.handler.async.enqueued', (detail) => {
+        obsLogger().debug('async job enqueued', { ...detail });
+    });
+}
+/**
+ * Register handlers that create OpenTelemetry spans for emit operations.
+ *
+ * Each `bus.emit.done` creates a span named `eventbus.emit.{EVENT}` with
+ * attributes for sync/async counts, duration, and error count. Degrades
+ * gracefully when telemetry is not initialised (`traceAsync` is a pass-through).
+ */
+export function attachTelemetryObserver(lifecycleBus) {
+    lifecycleBus.on('bus.emit.done', (detail) => {
+        void traceAsync(`eventbus.emit.${detail.event}`, async (_span) => {
+            addSpanAttributes({
+                'eventbus.event': detail.event,
+                'eventbus.sync_count': detail.syncCount,
+                'eventbus.async_count': detail.asyncCount,
+                'eventbus.duration_ms': detail.emitDurationMs,
+                'eventbus.errors': detail.errors,
+            });
+            if (detail.errors > 0) {
+                addSpanEvent('eventbus.emit.errors', { 'eventbus.error_count': detail.errors });
+            }
+        });
+    });
+    lifecycleBus.on('bus.handler.error', (detail) => {
+        void traceAsync('eventbus.handler.error', async (span) => {
+            addSpanAttributes({
+                'eventbus.event': detail.event,
+                'eventbus.handler_mode': detail.mode,
+                'eventbus.error': detail.error,
+            });
+            span.setStatus({ code: 2, message: detail.error }); // ERROR
+        });
+    });
+}
+/**
+ * Attach the built-in observers (log + telemetry) to the lifecycle bus in one
+ * call. Recommended default for production deployments. Metrics are emitted by
+ * the `EventBus` core inline, so they are not part of this set.
+ */
+export function attachDefaultObservers(lifecycleBus) {
+    attachLogObserver(lifecycleBus);
+    attachTelemetryObserver(lifecycleBus);
+}

package/dist/event-bus/event-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/event-bus/event-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,KAAK,EAER,kBAAkB,EAElB,QAAQ,EAER,gBAAgB,EACnB,MAAM,SAAS,CAAC;AAQjB;;;GAGG;AACH,qBAAa,QAAQ,CAAC,OAAO,SAAS,QAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyD;IACtF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyD;IACvF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiD;IACjF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,kBAAkB,CAAK;gBAEnB,IAAI,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;QACpB,YAAY,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;KAC/C;IAKD,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAQzF,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAS3F,GAAG,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAkBjE,kBAAkB,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI;IAUtD,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA2E7F,aAAa,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM;IAMjF,UAAU,IAAI,MAAM,EAAE;IAOtB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,oBAAoB;CAU/B"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/event-bus/event-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,KAAK,EAER,kBAAkB,EAElB,QAAQ,EAER,gBAAgB,EACnB,MAAM,SAAS,CAAC;AAQjB;;;GAGG;AACH,qBAAa,QAAQ,CAAC,OAAO,SAAS,QAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyD;IACtF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyD;IACvF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiD;IACjF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,kBAAkB,CAAK;gBAEnB,IAAI,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;QACpB,YAAY,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;KAC/C;IAKD,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAQzF,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAS3F,GAAG,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAkBjE,kBAAkB,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI;IAUtD,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4E7F,aAAa,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM;IAMjF,UAAU,IAAI,MAAM,EAAE;IAOtB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,oBAAoB;CAU/B"}

package/dist/event-bus/event-bus.js

@@ -97,6 +97,7 @@ export class EventBus {
                         });
                         busLogger().debug('async job enqueued', { event: eventName, jobId, handlerCount: 1 });
                         this.publishAsyncEnqueued(eventName, jobId, 1);
+                        continue;
                     }
                     catch (error) {
                         errors++;

package/dist/event-bus/file-observer.d.ts

@@ -0,0 +1,25 @@
+import type { EventBus } from './event-bus';
+import type { BusLifecycleEvents } from './types';
+/**
+ * Minimal append-only file writer the file observer needs.
+ *
+ * ADR-011: ts-infra must not import `node:fs`. The caller injects a writer —
+ * typically `@gobing-ai/ts-runtime`'s `FileSystem`, which already satisfies
+ * this shape (`ensureDir` + `appendFile`).
+ */
+export interface FileObserverWriter {
+    /** Ensure the directory exists. Called once with the parent dir of the file. */
+    ensureDir(dir: string): void | Promise<void>;
+    /** Append `content` to `path`, creating the file if absent. */
+    appendFile(path: string, content: string): void | Promise<void>;
+}
+/**
+ * Register handlers on `lifecycleBus` that append structured JSON lines to
+ * `filePath` for every lifecycle event.
+ *
+ * @param lifecycleBus - The bus to observe.
+ * @param filePath - Path to the JSONL output file.
+ * @param writer - Injected file writer (e.g. ts-runtime `FileSystem`).
+ */
+export declare function attachFileObserver(lifecycleBus: EventBus<BusLifecycleEvents>, filePath: string, writer: FileObserverWriter): void;
+//# sourceMappingURL=file-observer.d.ts.map

package/dist/event-bus/file-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-observer.d.ts","sourceRoot":"","sources":["../../src/event-bus/file-observer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAC/B,gFAAgF;IAChF,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,+DAA+D;IAC/D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAYD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,YAAY,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,GAC3B,IAAI,CAqGN"}

package/dist/event-bus/file-observer.js

@@ -0,0 +1,110 @@
+import { getLogger } from '../logger.js';
+/** Parent directory of a `/`-separated path (no `node:path` dependency). */
+function parentDir(filePath) {
+    const idx = filePath.lastIndexOf('/');
+    return idx <= 0 ? '.' : filePath.slice(0, idx);
+}
+function isPromiseLike(value) {
+    return value !== null && typeof value === 'object' && 'then' in value;
+}
+/**
+ * Register handlers on `lifecycleBus` that append structured JSON lines to
+ * `filePath` for every lifecycle event.
+ *
+ * @param lifecycleBus - The bus to observe.
+ * @param filePath - Path to the JSONL output file.
+ * @param writer - Injected file writer (e.g. ts-runtime `FileSystem`).
+ */
+export function attachFileObserver(lifecycleBus, filePath, writer) {
+    const logger = getLogger('event-bus.file-observer');
+    const ensureResult = writer.ensureDir(parentDir(filePath));
+    let ready = !isPromiseLike(ensureResult);
+    let pending = isPromiseLike(ensureResult);
+    let setupFailed = false;
+    let sequence = 0;
+    let writeChain = isPromiseLike(ensureResult)
+        ? Promise.resolve(ensureResult)
+            .then(() => {
+            ready = true;
+        })
+            .catch((error) => {
+            setupFailed = true;
+            logger.warn('failed to prepare event bus file observer directory', {
+                filePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        })
+        : Promise.resolve();
+    function setPending(next) {
+        const current = ++sequence;
+        pending = true;
+        writeChain = next
+            .catch((error) => {
+            logger.warn('failed to append event bus lifecycle event', {
+                filePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .finally(() => {
+            if (sequence === current)
+                pending = false;
+        });
+    }
+    function writeLine(line) {
+        const content = `${JSON.stringify(line)}\n`;
+        if (setupFailed)
+            return;
+        if (ready && !pending) {
+            const result = writer.appendFile(filePath, content);
+            if (isPromiseLike(result)) {
+                setPending(Promise.resolve(result));
+            }
+            return;
+        }
+        setPending(writeChain.then(() => {
+            if (setupFailed)
+                return;
+            return writer.appendFile(filePath, content);
+        }));
+    }
+    lifecycleBus.on('bus.emit.done', (d) => {
+        const payload = d.detail !== null && typeof d.detail === 'object' && !Array.isArray(d.detail)
+            ? d.detail
+            : undefined;
+        writeLine({
+            ts: new Date().toISOString(),
+            lifecycle: 'bus.emit.done',
+            event: d.event,
+            syncCount: d.syncCount,
+            asyncCount: d.asyncCount,
+            emitDurationMs: d.emitDurationMs,
+            errors: d.errors,
+            ...(payload && Object.keys(payload).length > 0 ? { payload } : {}),
+        });
+    });
+    lifecycleBus.on('bus.emit.noop', (d) => {
+        writeLine({
+            ts: new Date().toISOString(),
+            lifecycle: 'bus.emit.noop',
+            event: d.event,
+        });
+    });
+    lifecycleBus.on('bus.handler.error', (d) => {
+        writeLine({
+            ts: new Date().toISOString(),
+            lifecycle: 'bus.handler.error',
+            event: d.event,
+            mode: d.mode,
+            error: d.error,
+        });
+    });
+    lifecycleBus.on('bus.handler.async.enqueued', (d) => {
+        writeLine({
+            ts: new Date().toISOString(),
+            lifecycle: 'bus.handler.async.enqueued',
+            event: d.event,
+            jobId: d.jobId,
+            handlerCount: d.handlerCount,
+        });
+    });
+}

package/dist/event-bus/index.d.ts

@@ -1,3 +1,5 @@
+export { attachDefaultObservers, attachLogObserver, attachTelemetryObserver, createLifecycleBus, } from './default-observers';
 export { EventBus } from './event-bus';
+export { attachFileObserver, type FileObserverWriter } from './file-observer';
 export type { AsyncEnqueuedDetail, BusLifecycleEvents, EmitDoneDetail, EventMap, HandlerErrorDetail, SubscribeOptions, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/event-bus/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/event-bus/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EACR,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,GACnB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/event-bus/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,sBAAsB,EACtB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,YAAY,EACR,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,GACnB,MAAM,SAAS,CAAC"}

package/dist/event-bus/index.js

@@ -1 +1,3 @@
+export { attachDefaultObservers, attachLogObserver, attachTelemetryObserver, createLifecycleBus, } from './default-observers.js';
 export { EventBus } from './event-bus.js';
+export { attachFileObserver } from './file-observer.js';