@gobing-ai/ts-infra 0.3.9 → 0.3.11

package/dist/telemetry/metrics.js

@@ -2,7 +2,8 @@
  * OpenTelemetry metrics — lazy-initialized instruments.
  * All degrade to no-ops when telemetry is disabled.
  */
-import { metrics } from '@opentelemetry/api';
+import { createNoopMeter, metrics } from '@opentelemetry/api';
+import { getResolvedConfig } from './sdk.js';
 let metricsInitialized = false;
 /** Whether the metrics subsystem has been initialized via {@link initMetrics}. */
 export function isMetricsInitialized() {
@@ -16,13 +17,32 @@ function getMeter() {
 }
 // ── Instrument cache ────────────────────────────────────────────────
 const instruments = {};
+// Master switch (`TelemetryConfig.enabled`): when explicitly disabled, getters
+// return shared no-op instruments WITHOUT touching the cache, so a later
+// re-enable rebuilds real instruments against the live meter.
+let _noopCounter;
+let _noopHistogram;
+function noopCounter() {
+    if (!_noopCounter)
+        _noopCounter = createNoopMeter().createCounter('noop');
+    return _noopCounter;
+}
+function noopHistogram() {
+    if (!_noopHistogram)
+        _noopHistogram = createNoopMeter().createHistogram('noop');
+    return _noopHistogram;
+}
 function getOrCreateCounter(key, name, description, unit = '{operation}') {
+    if (!getResolvedConfig().enabled)
+        return noopCounter();
     if (!instruments[key]) {
         instruments[key] = getMeter().createCounter(name, { description, unit });
     }
     return instruments[key];
 }
 function getOrCreateHistogram(key, name, description, unit = 'ms') {
+    if (!getResolvedConfig().enabled)
+        return noopHistogram();
     if (!instruments[key]) {
         instruments[key] = getMeter().createHistogram(name, { description, unit });
     }

package/dist/telemetry/sdk.d.ts

@@ -13,7 +13,11 @@ import { type Tracer } from '@opentelemetry/api';
  * environment, and debug-level DB statement capture.
  */
 export interface TelemetryConfig {
-    /** Master switch — when false, all tracing degrades to no-ops. */
+    /**
+     * Master switch — when false, infra-created spans and metric instruments
+     * degrade to no-ops even if a global OTel provider is registered.
+     * Explicitly injected tracer ports (ADR-009 addendum) are unaffected.
+     */
     enabled: boolean;
     /** Logical service name emitted on every span. */
     serviceName: string;
@@ -26,7 +30,8 @@ export interface TelemetryConfig {
      * attribute. SQL text is redacted — parameter values, literals, and
      * identifiers are stripped before capture.
      *
-     * Default: `false`. Controlled by `OTEL_DB_STATEMENT_DEBUG` env var.
+     * Default: `false`. Set via config — ts-infra core never reads env vars
+     * (ADR-011); map an env var to this flag in your bootstrap if desired.
      */
     dbStatementDebug: boolean;
 }

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;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"}
+{"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;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;OASG;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/tracing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/telemetry/tracing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAW,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AAG9F;;;GAGG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAY3G;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAK7F;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAKvG;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI,IAAI,GAAG,SAAS,CAEhD;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;AAED,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC"}
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/telemetry/tracing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAiC,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AAiBpH;;;GAGG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,WAAW,EACrB,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAc3G;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAK7F;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAKvG;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI,IAAI,GAAG,SAAS,CAEhD;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;AAED,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC"}

package/dist/telemetry/tracing.js

@@ -1,13 +1,27 @@
 /**
  * High-level tracing helpers for application code.
  */
-import { context, trace } from '@opentelemetry/api';
-import { getTracer } from './sdk.js';
+import { context, INVALID_SPAN_CONTEXT, trace } from '@opentelemetry/api';
+import { getResolvedConfig, getTracer } from './sdk.js';
+/**
+ * Master switch (`TelemetryConfig.enabled`): when explicitly disabled, infra
+ * helpers bypass the global provider entirely. An explicitly injected tracer
+ * (ADR-009 addendum structural port) is honored regardless — the caller opted in.
+ */
+function isSuppressed(tracer) {
+    return tracer === undefined && !getResolvedConfig().enabled;
+}
+/** A non-recording span satisfying the `Span` interface — every method is a no-op. */
+function nonRecordingSpan() {
+    return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
+}
 /**
  * Execute an async function within an active OTel span.
  * The span is automatically ended and its status set on error.
  */
 export async function traceAsync(name, fn, options, tracer) {
+    if (isSuppressed(tracer))
+        return fn(nonRecordingSpan());
     const resolvedTracer = tracer ?? getTracer();
     return resolvedTracer.startActiveSpan(name, options ?? {}, async (span) => {
         try {
@@ -27,6 +41,8 @@ export async function traceAsync(name, fn, options, tracer) {
  * The span is automatically ended and its status set on error.
  */
 export function traceSync(name, fn, options, tracer) {
+    if (isSuppressed(tracer))
+        return fn(nonRecordingSpan());
     const resolvedTracer = tracer ?? getTracer();
     return resolvedTracer.startActiveSpan(name, options ?? {}, (span) => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.3.9",
+    "version": "0.3.11",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -77,8 +77,8 @@
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.3.9",
-        "@gobing-ai/ts-runtime": "^0.3.9",
+        "@gobing-ai/ts-db": "^0.3.11",
+        "@gobing-ai/ts-runtime": "^0.3.11",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -111,8 +111,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.3.9",
-        "@gobing-ai/ts-runtime": "^0.3.9",
+        "@gobing-ai/ts-db": "^0.3.11",
+        "@gobing-ai/ts-runtime": "^0.3.11",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/api-client.ts

@@ -7,6 +7,8 @@ import {
     ATTR_HTTP_RESPONSE_STATUS_CODE,
     ATTR_URL_FULL,
 } from '@opentelemetry/semantic-conventions';
+import type { EventBus } from './event-bus/event-bus';
+import type { ApiClientEvents } from './events';
 import {
     getHttpClientRequestDuration,
     getHttpClientRequestErrors,
@@ -22,8 +24,13 @@ export interface APIClientConfig {
     defaultHeaders?: Record<string, string>;
     timeout?: number;
     fetch?: typeof globalThis.fetch;
+    /**
+     * Optional bus for `api.request.error` events. Emitted on network errors,
+     * timeouts, and (for the JSON methods) non-2xx responses. `rawRequest`
+     * returns non-2xx statuses normally, so it emits only on network/timeout.
+     */
+    events?: EventBus<ApiClientEvents>;
 }
-
 /** Per-request overrides: headers, timeout, operation name, and abort signal. */
 export interface RequestOptions {
     headers?: Record<string, string>;
@@ -32,7 +39,25 @@ export interface RequestOptions {
     signal?: AbortSignal;
 }
 
-/** HTTP error with status code and response body text. */
+/** Options for {@link APIClient.rawRequest}: extends RequestOptions with redirect policy and response-size cap. */
+export interface RawRequestOptions extends RequestOptions {
+    /** Redirect policy (default `'manual'`). */
+    redirect?: 'follow' | 'error' | 'manual';
+    maxResponseBytes?: number;
+}
+
+/** Raw HTTP response returned by {@link APIClient.rawRequest} for all status codes. */
+export interface RawHttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    /** True when `maxResponseBytes` capped the body. Omitted when no cap was applied. */
+    truncated?: boolean;
+}
+/**
+ * HTTP error with status code and response body text.
+ * Timeouts are reported with `status === 0` (no response was received).
+ */
 export class APIError extends Error {
     constructor(
         public readonly status: number,
@@ -43,6 +68,52 @@ export class APIError extends Error {
     }
 }
 
+// ── Body reading ────────────────────────────────────────────────────
+
+/**
+ * Read a response body capped at `maxResponseBytes` (UTF-8 bytes). Returns the
+ * decoded text and whether the body was truncated. Falls back to `text()` with
+ * a character cap when the response exposes no readable stream.
+ */
+async function readBodyCapped(
+    response: Response,
+    maxResponseBytes: number,
+): Promise<{ text: string; truncated?: boolean }> {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        const full = await response.text();
+        if (full.length > maxResponseBytes) {
+            return { text: full.slice(0, maxResponseBytes), truncated: true };
+        }
+        return { text: full };
+    }
+
+    const chunks: string[] = [];
+    const decoder = new TextDecoder();
+    let total = 0;
+    let truncated = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const remaining = maxResponseBytes - total;
+        if (value.length > remaining) {
+            // The streaming decoder holds back a trailing partial multibyte
+            // sequence, which is then dropped — the cap is a byte budget.
+            chunks.push(decoder.decode(value.slice(0, remaining), { stream: true }));
+            truncated = true;
+            break;
+        }
+        chunks.push(decoder.decode(value, { stream: true }));
+        total += value.length;
+    }
+    if (truncated) {
+        // Stop the underlying stream instead of letting it keep downloading.
+        await reader.cancel().catch(() => {});
+    }
+    reader.releaseLock();
+    return { text: chunks.join(''), ...(truncated ? { truncated } : {}) };
+}
+
 // ── Client ──────────────────────────────────────────────────────────
 
 /**
@@ -60,26 +131,43 @@ export class APIClient {
     private readonly defaultHeaders: Record<string, string>;
     private readonly timeout: number;
     private readonly fetchFn: typeof globalThis.fetch;
+    private readonly events: EventBus<ApiClientEvents> | undefined;
 
     constructor(config: APIClientConfig) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.defaultHeaders = config.defaultHeaders ?? {};
         this.timeout = config.timeout ?? 30_000;
         this.fetchFn = config.fetch ?? globalThis.fetch;
+        this.events = config.events;
     }
 
     private buildUrl(path: string): string {
         return `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
     }
 
-    private async request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
-        const url = this.buildUrl(path);
-        const headers: Record<string, string> = {
-            'Content-Type': 'application/json',
-            ...this.defaultHeaders,
-            ...opts?.headers,
-        };
+    private emitRequestError(method: string, url: string, error: string, status?: number): void {
+        void this.events?.emit('api.request.error', {
+            url,
+            method,
+            ...(status !== undefined ? { status } : {}),
+            error,
+        });
+    }
 
+    /**
+     * Shared request lifecycle: span + attributes, timeout/abort wiring,
+     * total/duration/error metrics, the fetch call, and timeout-vs-abort error
+     * mapping. `consume` owns response handling (parse/throw policy).
+     */
+    private async runRequest<T>(
+        method: string,
+        url: string,
+        headers: Record<string, string>,
+        body: string | undefined,
+        opts: RequestOptions | undefined,
+        redirect: RawRequestOptions['redirect'] | undefined,
+        consume: (response: Response, span: Span) => Promise<T>,
+    ): Promise<T> {
         const operationName = opts?.operationName ?? `HTTP ${method} ${url}`;
 
         return traceAsync(
@@ -106,8 +194,9 @@ export class APIClient {
                     const response = await this.fetchFn(url, {
                         method,
                         headers,
-                        body: body !== undefined ? JSON.stringify(body) : undefined,
+                        body,
                         signal: combinedSignal,
+                        ...(redirect ? { redirect } : {}),
                     });
 
                     span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.status);
@@ -116,35 +205,40 @@ export class APIClient {
                         'http.request.method': method,
                         'http.response.status_code': response.status,
                     });
-
-                    const duration = performance.now() - start;
-                    getHttpClientRequestDuration().record(duration, {
+                    getHttpClientRequestDuration().record(performance.now() - start, {
                         'http.request.method': method,
                         'http.response.status_code': response.status,
                     });
 
-                    if (!response.ok) {
-                        const text = await response.text();
+                    return await consume(response, span);
+                } catch (error) {
+                    // Timeout (our own AbortController fired) — but never relabel a
+                    // caller-initiated abort via opts.signal as a timeout.
+                    if (error instanceof DOMException && error.name === 'AbortError' && !opts?.signal?.aborted) {
                         getHttpClientRequestErrors().add(1, {
                             'http.request.method': method,
-                            'error.type': `HTTP_${response.status}`,
+                            'error.type': 'Timeout',
                         });
-                        throw new APIError(response.status, text);
+                        const timeoutError = new APIError(
+                            0,
+                            `Request timed out after ${timeoutMs}ms: ${method} ${url}`,
+                        );
+                        this.emitRequestError(method, url, timeoutError.message);
+                        throw timeoutError;
                     }
 
-                    const contentType = response.headers.get('content-type') ?? '';
-                    if (contentType.includes('application/json')) {
-                        return (await response.json()) as T;
-                    }
-
-                    return (await response.text()) as unknown as T;
-                } catch (error) {
                     if (!(error instanceof APIError)) {
                         getHttpClientRequestErrors().add(1, {
                             'http.request.method': method,
                             'error.type': error instanceof Error ? error.name : 'Unknown',
                         });
                     }
+                    this.emitRequestError(
+                        method,
+                        url,
+                        error instanceof Error ? error.message : String(error),
+                        error instanceof APIError && error.status > 0 ? error.status : undefined,
+                    );
 
                     throw error;
                 } finally {
@@ -155,6 +249,96 @@ export class APIClient {
         );
     }
 
+    private async request<T>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
+        const url = this.buildUrl(path);
+        const headers: Record<string, string> = {
+            'Content-Type': 'application/json',
+            ...this.defaultHeaders,
+            ...opts?.headers,
+        };
+
+        return this.runRequest<T>(
+            method,
+            url,
+            headers,
+            body !== undefined ? JSON.stringify(body) : undefined,
+            opts,
+            undefined,
+            async (response) => {
+                if (!response.ok) {
+                    const text = await response.text();
+                    getHttpClientRequestErrors().add(1, {
+                        'http.request.method': method,
+                        'error.type': `HTTP_${response.status}`,
+                    });
+                    throw new APIError(response.status, text);
+                }
+
+                const contentType = response.headers.get('content-type') ?? '';
+                if (contentType.includes('application/json')) {
+                    return (await response.json()) as T;
+                }
+
+                return (await response.text()) as unknown as T;
+            },
+        );
+    }
+
+    /**
+     * Make a raw HTTP request returning status, headers, and body for ALL status codes.
+     * Never throws on HTTP status codes (2xx, 4xx, 5xx all return a {@link RawHttpResponse}).
+     * Throws only on network/timeout errors.
+     *
+     * Deliberately does NOT force Content-Type: application/json — callers pass raw
+     * string bodies and set their own content-type header.
+     */
+    async rawRequest(method: string, path: string, body?: string, opts?: RawRequestOptions): Promise<RawHttpResponse> {
+        const url = this.buildUrl(path);
+        const headers: Record<string, string> = {
+            ...this.defaultHeaders,
+            ...opts?.headers,
+        };
+        const redirect = opts?.redirect ?? 'manual';
+        const maxResponseBytes = opts?.maxResponseBytes;
+
+        return this.runRequest<RawHttpResponse>(
+            method,
+            url,
+            headers,
+            body ?? undefined,
+            opts,
+            redirect,
+            async (response) => {
+                if (!response.ok) {
+                    getHttpClientRequestErrors().add(1, {
+                        'http.request.method': method,
+                        'error.type': `HTTP_${response.status}`,
+                    });
+                }
+
+                let text: string;
+                let truncated: boolean | undefined;
+                if (maxResponseBytes !== undefined) {
+                    ({ text, truncated } = await readBodyCapped(response, maxResponseBytes));
+                } else {
+                    text = await response.text();
+                }
+
+                const responseHeaders: Record<string, string> = {};
+                response.headers.forEach((value, key) => {
+                    responseHeaders[key] = value;
+                });
+
+                return {
+                    status: response.status,
+                    headers: responseHeaders,
+                    body: text,
+                    ...(truncated !== undefined ? { truncated } : {}),
+                };
+            },
+        );
+    }
+
     async get<T>(path: string, opts?: RequestOptions): Promise<T> {
         return this.request<T>('GET', path, undefined, opts);
     }
@@ -167,6 +351,10 @@ export class APIClient {
         return this.request<T>('PUT', path, body, opts);
     }
 
+    async patch<T>(path: string, body?: unknown, opts?: RequestOptions): Promise<T> {
+        return this.request<T>('PATCH', path, body, opts);
+    }
+
     async delete<T>(path: string, opts?: RequestOptions): Promise<T> {
         return this.request<T>('DELETE', path, undefined, opts);
     }

package/src/application/index.ts

@@ -143,9 +143,10 @@ export async function runApplication<TAppConfig = unknown, TEvents extends Event
             attachDefaultObservers(lifecycleBus);
         }
 
-        const events = options.services?.events
-            ? options.services.events
-            : new EventBus<TEvents>({ lifecycleBus: lifecycleBus as EventBus<BusLifecycleEvents> | undefined });
+        const events =
+            options.services?.events ??
+            options.config?.events?.bus ??
+            new EventBus<TEvents>({ lifecycleBus: lifecycleBus as EventBus<BusLifecycleEvents> | undefined });
 
         // ── 4. Database (injected only) ────────────────────────────────
         const db: DbAdapterLike | undefined = options.services?.db;

package/src/application/plugins/builtins.ts

@@ -31,21 +31,23 @@ export function telemetryPlugin(config: ApplicationBootstrapConfig['telemetry'])
         failFast: true,
         onLoad: async () => {},
         onStart: async () => {
+            // Always record the resolved config — `enabled: false` must reach the
+            // master switch so infra spans/instruments actually go quiet.
+            initTelemetry({
+                enabled: config.enabled,
+                serviceName: config.serviceName,
+                environment: config.environment,
+                dbStatementDebug: config.dbStatementDebug,
+            });
             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();
             }
+            await shutdownTelemetry();
         },
     };
 }

package/src/application/types.ts

@@ -75,7 +75,7 @@ export interface SchedulerOptions {
 
 /**
  * Fully-resolved bootstrap config (all optionals filled with defaults).
- * Constructed internally by `resolveBootstrapConfig`.
+ * Constructed internally by `runApplication`.
  */
 export interface ApplicationBootstrapConfig {
     readonly logging: Readonly<

package/src/application-node.ts

@@ -33,6 +33,7 @@ import type {
     ConfigValidationResult,
     DbAdapterLike,
     EventMap,
+    EventsOptions,
     InfraEvents,
     LoggingOptions,
     SchedulerOptions,
@@ -161,12 +162,29 @@ function loadYamlConfig<TAppConfig>(
 
 // ── Node/Bun options ──────────────────────────────────────────────────────
 
+/**
+ * Telemetry options for the Node subpath: the portable flags plus OTLP export
+ * wiring. Presence of `endpoint` (with `enabled` not false) turns on Node OTel
+ * export via `@gobing-ai/ts-infra/otel-node`.
+ */
+export interface NodeTelemetryBootstrapOptions extends TelemetryOptions {
+    /** OTLP/HTTP collector endpoint base, e.g. `http://localhost:4318`. */
+    endpoint?: string;
+    /** Extra headers sent on every OTLP request (e.g. an auth token). */
+    headers?: Record<string, string>;
+}
+
 /** Options for the Node/Bun convenience {@link runNodeApplication}. */
 export interface NodeApplicationOptions<TAppConfig = unknown, TEvents extends EventMap = InfraEvents> {
     /** YAML config loading options. When omitted, uses defaults. */
     readonly configLoader?: ApplicationConfigLoader<TAppConfig>;
     /** Inline bootstrap config (overrides YAML-loaded config). */
-    readonly config?: ApplicationBootstrapOptions<TAppConfig, TEvents>['config'];
+    readonly config?: {
+        logging?: LoggingOptions;
+        events?: EventsOptions<TEvents>;
+        telemetry?: NodeTelemetryBootstrapOptions;
+        scheduler?: SchedulerOptions;
+    };
     /** Pre-built services to inject. */
     readonly services?: ApplicationBootstrapOptions<TAppConfig, TEvents>['services'];
     /** User callback: application logic. */
@@ -232,12 +250,12 @@ export async function runNodeApplication<TAppConfig = unknown, TEvents extends E
 
     // ── Resolve bootstrap config from YAML + inline options ────────────
     const yamlLog = yamlBootstrap.logging as Partial<LoggingOptions> | undefined;
-    const yamlTel = yamlBootstrap.telemetry as Partial<TelemetryOptions> | undefined;
+    const yamlTel = yamlBootstrap.telemetry as Partial<NodeTelemetryBootstrapOptions> | undefined;
     const yamlSched = yamlBootstrap.scheduler as Partial<SchedulerOptions> | undefined;
     const databaseOpts = (yamlBootstrap.database ?? {}) as Record<string, unknown>;
 
     const loggingOpts: Partial<LoggingOptions> = { ...yamlLog, ...options.config?.logging };
-    const telemetryOpts: Partial<TelemetryOptions> = { ...yamlTel, ...options.config?.telemetry };
+    const telemetryOpts: Partial<NodeTelemetryBootstrapOptions> = { ...yamlTel, ...options.config?.telemetry };
     const schedulerOpts: Partial<SchedulerOptions> = { ...yamlSched, ...options.config?.scheduler };
 
     const logFilePath = (yamlBootstrap.logging as Record<string, unknown> | undefined)?.filePath as string | undefined;
@@ -256,20 +274,25 @@ export async function runNodeApplication<TAppConfig = unknown, TEvents extends E
     // ── Node-owned plugins ──────────────────────────────────────────────
     const plugins: Plugin[] = [];
     let dbAdapter: DbAdapterLike | undefined = options.services?.db;
-    const rawTel = { ...telemetryOpts } as Record<string, unknown>;
 
     // Node OTel telemetry as a failFast plugin
-    if (rawTel.enabled !== false && rawTel.endpoint) {
+    const otlpEndpoint = telemetryOpts.endpoint;
+    if (telemetryOpts.enabled !== false && otlpEndpoint) {
+        const otlpHeaders = telemetryOpts.headers;
+        const serviceName = telemetryOpts.serviceName ?? 'ts-libs';
         plugins.push({
             name: 'builtin:node-telemetry',
             version: '0.0.0',
             failFast: true,
-            onLoad: async () => {},
-            onStart: async () => {
+            // Providers must register during loadAll: the OTel metrics API has no
+            // proxy provider, so instruments created by telemetryPlugin's onStart
+            // (`initMetrics` pre-warm) bind permanently to whatever meter provider
+            // is global at that moment. loadAll runs before every onStart.
+            onLoad: async () => {
                 initNodeTelemetry({
-                    serviceName: (rawTel.serviceName as string | undefined) ?? 'ts-libs',
-                    endpoint: rawTel.endpoint as string,
-                    headers: rawTel.headers as Record<string, string> | undefined,
+                    serviceName,
+                    endpoint: otlpEndpoint,
+                    ...(otlpHeaders ? { headers: otlpHeaders } : {}),
                 });
             },
             onStop: async () => {