@gobing-ai/ts-infra 0.4.7 → 0.4.9

package/README.md

@@ -704,6 +704,53 @@ const app = await runNodeApplication({
 });
 ```
 
+### System Events — lifecycle bus propagation contract
+
+`runApplication` creates a single `lifecycleBus` (`EventBus<BusLifecycleEvents>`)
+and parents the application event bus to it. Downstream consumers join the same
+stream when callers pass `app.lifecycleBus` into their constructors. Domain emits
+fan out as `bus.*` lifecycle events on the parent and — when a file observer is
+attached — land in the JSONL System Events log alongside the domain event itself.
+
+**Six System Events prefixes and where they originate:**
+
+| Prefix | Source | Constructed when `events` is omitted |
+|--------|--------|---------------------------------------|
+| `bus.*` | `EventBus` lifecycle self-observability (the `lifecycleBus` itself) | always — `runApplication` creates it |
+| `api.*` | `APIClient` (`api.request.error`) | `new EventBus<ApiClientEvents>({ lifecycleBus })` (R5) |
+| `rule.*` | `RuleEngine` (rule-run structured observability) | `new EventBus<RuleEngineEvents>({ lifecycleBus })` (R2) |
+| `workflow.*` | `WorkflowService` (workflow-run observability) | `new EventBus<WorkflowEngineEvents>({ lifecycleBus })` via `resolveEvents` (R3) |
+| `agent.*` | `AiRunner` / `TeamOrchestrator` (agent invocation observability) | `new EventBus<AgentEvents>({ lifecycleBus })` (R4) |
+| `process.*` | `AiRunner` default-executor process events | `new EventBus<AiRunnerProcessEvents>({ lifecycleBus })` (R4) |
+
+**Caller-supplied `events` always wins.** Every consumer accepts an explicit
+`events?: EventBus<TEvents>` (or equivalent) and an optional `lifecycleBus?`.
+When `events` is provided the consumer uses it as-is; when `events` is omitted
+and `lifecycleBus` is provided, the consumer constructs an internal bus
+parented to the lifecycle bus. This keeps standalone use zero-config and lets
+the bootstrap opt every consumer into the System Events stream by passing a
+single `lifecycleBus`.
+
+**Portable vs Node subpath split (ADR-011).** `runApplication` (portable)
+never opens files: it calls `attachFileObserver(lifecycleBus, filePath, writer)`
+only when `services.fileObserverWriter` is provided; its portable default path is
+`logs/system-events.jsonl`. The Node subpath `runNodeApplication` constructs a
+Node writer and uses `createNodeFileSystem()` to resolve the path to
+`<projectRoot>/logs/system-events.jsonl`. Set `config.events.fileObserver: false`
+to disable; supply a custom `filePath` (or a test-stub writer via
+`services.fileObserverWriter`) to override.
+
+**Wiring a consumer manually.** When you construct a consumer outside the
+bootstrap (or want to share the bootstrap's bus), pass the exposed
+`app.lifecycleBus`:
+
+```ts
+import { RuleEngine } from '@gobing-ai/ts-rule-engine';
+
+const engine = new RuleEngine({ lifecycleBus: app.lifecycleBus });
+// engine now emits `rule.*` events into the same JSONL log as the bootstrap.
+```
+
 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.

package/dist/api-client.d.ts

@@ -1,4 +1,4 @@
-import type { EventBus } from './event-bus/event-bus';
+import { type BusLifecycleEvents, EventBus } from './event-bus/index';
 import type { ApiClientEvents } from './events';
 /** Configuration for {@link APIClient}: base URL, default headers, timeout, and optional custom fetch. */
 export interface APIClientConfig {
@@ -12,6 +12,13 @@ export interface APIClientConfig {
      * returns non-2xx statuses normally, so it emits only on network/timeout.
      */
     events?: EventBus<ApiClientEvents>;
+    /**
+     * Optional lifecycle bus to bridge `api.*` events into the application
+     * System Events stream (R5). When `events` is omitted the client
+     * constructs an internal `EventBus<ApiClientEvents>` parented to this
+     * bus so `api.request.error` appears in the JSONL log.
+     */
+    lifecycleBus?: EventBus<BusLifecycleEvents>;
 }
 /** Per-request overrides: headers, timeout, operation name, and abort signal. */
 export interface RequestOptions {
@@ -46,9 +53,7 @@ export declare class APIError extends Error {
 /**
  * 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');
  * ```

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

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAUhD,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;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;CACtC;AACD,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,mHAAmH;AACnH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACrD,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AACD;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAEX,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAKnC;AAoED;;;;;;;;;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;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;gBAEnD,MAAM,EAAE,eAAe;IAQnC,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,gBAAgB;IASxB;;;;OAIG;YACW,UAAU;YAkGV,OAAO;IAmCrB;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA+C3G,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,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzE,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":"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"}

package/dist/api-client.js

@@ -3,6 +3,7 @@
  */
 import { SpanKind } from '@opentelemetry/api';
 import { ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_STATUS_CODE, ATTR_URL_FULL, } from '@opentelemetry/semantic-conventions';
+import { EventBus } from './event-bus/index.js';
 import { getHttpClientRequestDuration, getHttpClientRequestErrors, getHttpClientRequestTotal, } from './telemetry/metrics.js';
 import { traceAsync } from './telemetry/tracing.js';
 /**
@@ -82,9 +83,7 @@ async function readBodyCapped(response, maxResponseBytes) {
 /**
  * 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');
  * ```
@@ -100,7 +99,9 @@ export class APIClient {
         this.defaultHeaders = config.defaultHeaders ?? {};
         this.timeout = config.timeout ?? 30_000;
         this.fetchFn = config.fetch ?? globalThis.fetch;
-        this.events = config.events;
+        this.events =
+            config.events ??
+                (config.lifecycleBus ? new EventBus({ lifecycleBus: config.lifecycleBus }) : undefined);
     }
     buildUrl(path) {
         return `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;

package/dist/application/index.d.ts

@@ -19,6 +19,12 @@ import type { ApplicationBootstrapOptions, ApplicationRuntime } from './types';
  * Accepts injected dependencies; never opens files, reads config from disk,
  * or wires runtime-specific exporters.
  *
+ * The returned `lifecycleBus` is the parent of the application `events` bus and
+ * can be passed to RuleEngine, WorkflowService, AiRunner, TeamOrchestrator, and
+ * APIClient so their domain events share one System Events stream. A supplied
+ * file-observer writer records that stream as JSONL; the Node subpath supplies
+ * the writer and default `logs/system-events.jsonl` path.
+ *
  * 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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/application/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAsB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;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,CAmIlD;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/application/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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,CAyJlD;AAED,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE7D,YAAY,EACR,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,SAAS,CAAC"}

package/dist/application/index.js

@@ -11,6 +11,7 @@
  */
 import { attachDefaultObservers, createLifecycleBus } from '../event-bus/default-observers.js';
 import { EventBus } from '../event-bus/event-bus.js';
+import { attachFileObserver } from '../event-bus/file-observer.js';
 import { getLogger } from '../logger.js';
 import { initScheduler } from '../scheduler/factory.js';
 import { loggerPlugin, schedulerPlugin, telemetryPlugin, userCallbackPlugin } from './plugins/builtins.js';
@@ -39,6 +40,12 @@ async function performShutdown(state, reason) {
  * Accepts injected dependencies; never opens files, reads config from disk,
  * or wires runtime-specific exporters.
  *
+ * The returned `lifecycleBus` is the parent of the application `events` bus and
+ * can be passed to RuleEngine, WorkflowService, AiRunner, TeamOrchestrator, and
+ * APIClient so their domain events share one System Events stream. A supplied
+ * file-observer writer records that stream as JSONL; the Node subpath supplies
+ * the writer and default `logs/system-events.jsonl` path.
+ *
  * 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
@@ -91,6 +98,9 @@ export async function runApplication(options) {
     const eventsEnabled = options.config?.events?.enabled ?? true;
     const eventsLifecycle = options.config?.events?.lifecycle ?? true;
     const eventsDefaultObservers = options.config?.events?.defaultObservers ?? true;
+    const eventsFileObserver = options.config?.events?.fileObserver ?? true;
+    const fileObserverWriter = options.services?.fileObserverWriter;
+    const eventsFilePath = options.config?.events?.filePath ?? (fileObserverWriter !== undefined ? 'logs/system-events.jsonl' : undefined);
     const state = {
         app: undefined,
         stopped: false,
@@ -105,6 +115,18 @@ export async function runApplication(options) {
         if (lifecycleBus && eventsDefaultObservers) {
             attachDefaultObservers(lifecycleBus);
         }
+        // Attach the JSONL file observer when a writer is available. The
+        // portable subpath never opens files (ADR-011): the Node subpath
+        // injects `createNodeFileSystem()` (or a test stub) and resolves the
+        // default path against the project root. Without a writer or path
+        // the observer is a no-op even if `events.fileObserver` is `true`.
+        let fileObserverAttached = false;
+        let fileObserverPath;
+        if (lifecycleBus && eventsFileObserver && eventsFilePath !== undefined && fileObserverWriter !== undefined) {
+            attachFileObserver(lifecycleBus, eventsFilePath, fileObserverWriter);
+            fileObserverAttached = true;
+            fileObserverPath = eventsFilePath;
+        }
         const events = options.services?.events ??
             options.config?.events?.bus ??
             new EventBus({ lifecycleBus: lifecycleBus });
@@ -128,7 +150,13 @@ export async function runApplication(options) {
         // ── Build runtime handle (before startAll so plugins can capture it) ─
         const resolvedConfig = {
             logging: loggingConfig,
-            events: { enabled: eventsEnabled, lifecycle: eventsLifecycle, defaultObservers: eventsDefaultObservers },
+            events: {
+                enabled: eventsEnabled,
+                lifecycle: eventsLifecycle,
+                defaultObservers: eventsDefaultObservers,
+                fileObserver: fileObserverAttached,
+                ...(fileObserverPath !== undefined ? { filePath: fileObserverPath } : {}),
+            },
             telemetry: telemetryConfig,
             scheduler: schedulerConfig,
         };

package/dist/application/types.d.ts

@@ -8,6 +8,7 @@
  * @module application/types
  */
 import type { EventBus } from '../event-bus/event-bus';
+import type { FileObserverWriter } from '../event-bus/file-observer';
 import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
 import type { InfraEvents } from '../events';
 import type { Logger, LogLevel } from '../logger';
@@ -38,6 +39,20 @@ export interface EventsOptions<TEvents extends EventMap = InfraEvents> {
     lifecycle?: boolean;
     /** Attach default observers (log + telemetry). Default `true`. */
     defaultObservers?: boolean;
+    /**
+     * Attach a file observer that appends JSONL rows for every lifecycle
+     * event to `filePath`. Default `true` when a writer is available
+     * (Node subpath injects `createNodeFileSystem()`; portable callers must
+     * supply one via `services.fileObserverWriter`). No-op when `lifecycle`
+     * is disabled or no writer is present.
+     */
+    fileObserver?: boolean;
+    /**
+     * JSONL output path. Defaults to `logs/system-events.jsonl` when a writer
+     * is supplied; the Node subpath resolves this against the project root.
+     * Portable callers may override it with an absolute path.
+     */
+    filePath?: string;
     /** Pre-built event bus (skips creation when provided). */
     bus?: EventBus<TEvents>;
 }
@@ -75,6 +90,10 @@ export interface ApplicationBootstrapConfig {
         enabled: boolean;
         lifecycle: boolean;
         defaultObservers: boolean;
+        /** Whether the JSONL file observer was attached (false when no writer is available). */
+        fileObserver: boolean;
+        /** Resolved JSONL absolute path, or undefined when fileObserver is false. */
+        filePath?: string;
     };
     readonly telemetry: {
         enabled: boolean;
@@ -92,6 +111,13 @@ export interface ApplicationServices<TEvents extends EventMap = InfraEvents> {
     logger?: Logger;
     events?: EventBus<TEvents>;
     lifecycleBus?: EventBus<BusLifecycleEvents>;
+    /**
+     * Writer for `attachFileObserver`. Portable subpath never opens files
+     * (ADR-011); the Node subpath injects `createNodeFileSystem()`. When
+     * absent, the file observer is skipped even if `events.fileObserver`
+     * is `true`.
+     */
+    fileObserverWriter?: FileObserverWriter;
     db?: DbAdapterLike;
     scheduler?: SchedulerAdapter;
     /** Pre-built plugin host (when injecting instead of constructing). */

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/application/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/application/types.ts"],"names":[],"mappings":"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"}

package/dist/application-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application-node.d.ts","sourceRoot":"","sources":["../src/application-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,OAAO,KAAK,EACR,2BAA2B,EAC3B,uBAAuB,EAEvB,kBAAkB,EAClB,qBAAqB,EAGrB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EACnB,MAAM,qBAAqB,CAAC;AAM7B,kGAAkG;AAClG,qBAAa,qBAAsB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI9B;AAgHD;;;;GAIG;AACH,MAAM,WAAW,6BAA8B,SAAQ,gBAAgB;IACnE,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW;IAChG,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC,UAAU,CAAC,CAAC;IAC5D,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,cAAc,CAAC;QACzB,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QAChC,SAAS,CAAC,EAAE,6BAA6B,CAAC;QAC1C,SAAS,CAAC,EAAE,gBAAgB,CAAC;KAChC,CAAC;IACF,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC;IACjF,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvF,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,CACZ,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,EAC5C,MAAM,EAAE,qBAAqB,KAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW,EACjG,OAAO,EAAE,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,GACrD,OAAO,CAAC,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAmGlD"}
+{"version":3,"file":"application-node.d.ts","sourceRoot":"","sources":["../src/application-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,OAAO,KAAK,EACR,2BAA2B,EAC3B,uBAAuB,EAEvB,kBAAkB,EAClB,qBAAqB,EAGrB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EACnB,MAAM,qBAAqB,CAAC;AAM7B,kGAAkG;AAClG,qBAAa,qBAAsB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI9B;AAgHD;;;;GAIG;AACH,MAAM,WAAW,6BAA8B,SAAQ,gBAAgB;IACnE,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW;IAChG,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC,UAAU,CAAC,CAAC;IAC5D,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE;QACd,OAAO,CAAC,EAAE,cAAc,CAAC;QACzB,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QAChC,SAAS,CAAC,EAAE,6BAA6B,CAAC;QAC1C,SAAS,CAAC,EAAE,gBAAgB,CAAC;KAChC,CAAC;IACF,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC;IACjF,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvF,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,CACZ,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,EAC5C,MAAM,EAAE,qBAAqB,KAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW,EACjG,OAAO,EAAE,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,GACrD,OAAO,CAAC,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAgIlD"}

package/dist/application-node.js

@@ -17,7 +17,7 @@
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createDbAdapter } from '@gobing-ai/ts-db';
-import { interpolateTree, parseYamlObject } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, interpolateTree, parseYamlObject } from '@gobing-ai/ts-runtime';
 import { runApplication } from './application/index.js';
 import { dbPlugin } from './application/plugins/builtins.js';
 import { NodeSchedulerAdapter } from './scheduler-node.js';
@@ -160,10 +160,12 @@ export async function runNodeApplication(options) {
     const yamlLog = yamlBootstrap.logging;
     const yamlTel = yamlBootstrap.telemetry;
     const yamlSched = yamlBootstrap.scheduler;
+    const yamlEvents = yamlBootstrap.events;
     const databaseOpts = (yamlBootstrap.database ?? {});
     const loggingOpts = { ...yamlLog, ...options.config?.logging };
     const telemetryOpts = { ...yamlTel, ...options.config?.telemetry };
     const schedulerOpts = { ...yamlSched, ...options.config?.scheduler };
+    const eventsOpts = { ...yamlEvents, ...options.config?.events };
     const logFilePath = yamlBootstrap.logging?.filePath;
     const loggingConfig = typeof logFilePath === 'string' ? { ...loggingOpts, fileSink: createFileSink(logFilePath) } : loggingOpts;
     // ── Scheduler adapter ───────────────────────────────────────────────
@@ -218,14 +220,40 @@ export async function runNodeApplication(options) {
                 `(expected "bun-sqlite"). Provide a supported driver or inject a DbAdapter via services.db.`);
         }
     }
+    // ── Inject Node file observer (ADR-011 writer for the JSONL bus log) ──
+    // The portable `runApplication` never opens files; the Node subpath
+    // supplies the writer and resolves the default path against the project
+    // root. Caller-provided `services.fileObserverWriter` and
+    // `config.events.filePath` overrides win; `fileObserver: false` disables.
+    const injectedFileSystem = createNodeFileSystem();
+    const fileObserverWriter = options.services?.fileObserverWriter ?? {
+        ensureDir: (dir) => {
+            mkdirSync(dir, { recursive: true });
+        },
+        appendFile: (path, content) => {
+            appendFileSync(path, content);
+        },
+    };
+    const eventsFilePath = eventsOpts.filePath ?? injectedFileSystem.resolve('logs', 'system-events.jsonl');
+    const eventsConfig = {
+        ...eventsOpts,
+        filePath: eventsFilePath,
+        ...(eventsOpts.fileObserver === false ? {} : { fileObserver: true }),
+    };
     // ── Delegate to portable runApplication ─────────────────────────────
     // Node-specific cleanup is handled by plugins in the service ring —
     // node-telemetry onStop, owned-db onStop. No manual try/catch or stop
     // override needed.
     return await runApplication({
-        config: { ...options.config, logging: loggingConfig, telemetry: telemetryOpts, scheduler: schedulerConfig },
+        config: {
+            ...options.config,
+            logging: loggingConfig,
+            telemetry: telemetryOpts,
+            scheduler: schedulerConfig,
+            events: eventsConfig,
+        },
         appConfig: loadedAppConfig,
-        services: { ...options.services, ...(dbAdapter ? { db: dbAdapter } : {}) },
+        services: { ...options.services, fileObserverWriter, ...(dbAdapter ? { db: dbAdapter } : {}) },
         start: options.start,
         stop: options.stop,
         plugins: plugins.length ? plugins : undefined,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { APIClient, type APIClientConfig, APIError, type RawHttpResponse, type RawRequestOptions, type RequestOptions, } from './api-client';
-export { type AsyncEventJobPayload, attachDefaultObservers, attachFileObserver, attachLogObserver, attachTelemetryObserver, createLifecycleBus, EventBus, type EventMap, type FileObserverWriter, type SubscribeOptions, } from './event-bus/index';
+export { type AsyncEventJobPayload, attachDefaultObservers, attachFileObserver, attachLogObserver, attachTelemetryObserver, type BusLifecycleEvents, createLifecycleBus, EventBus, type EventMap, type FileObserverWriter, type SubscribeOptions, } from './event-bus/index';
 export type { ApiClientEvents, ApiRequestErrorDetail, DbConnectionErrorDetail, DbEvents, InfraEvents, QueueEvents, QueueJobFailedDetail, QueueJobRetryingDetail, SchedulerEvents, SchedulerJobExecutedDetail, } from './events';
 export type { EnqueueOptions, Job, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig, QueueStats, } from './job-queue/index';
 export { getLogger, type InitLoggerOptions, initializeLogger, type Logger, type LogLevel, setLoggerMuted, } from './logger';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,SAAS,EACT,KAAK,eAAe,EACpB,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACH,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACR,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,QAAQ,EACR,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,0BAA0B,GAC7B,MAAM,UAAU,CAAC;AAElB,YAAY,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,UAAU,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACH,SAAS,EACT,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,cAAc,GACjB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACH,cAAc,EACd,KAAK,4BAA4B,EACjC,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,UAAU,EACV,SAAS,EACT,QAAQ,GACX,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACH,SAAS,EACT,KAAK,eAAe,EACpB,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACH,KAAK,oBAAoB,EACzB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACR,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,QAAQ,EACR,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,0BAA0B,GAC7B,MAAM,UAAU,CAAC;AAElB,YAAY,EACR,cAAc,EACd,GAAG,EACH,UAAU,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,UAAU,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACH,SAAS,EACT,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,cAAc,GACjB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACH,cAAc,EACd,KAAK,4BAA4B,EACjC,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,iBAAiB,EACjB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACH,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,UAAU,EACV,SAAS,EACT,QAAQ,GACX,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.4.7",
+    "version": "0.4.9",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -78,12 +78,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-infra-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.4.7",
+        "@gobing-ai/ts-utils": "^0.4.9",
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.7",
-        "@gobing-ai/ts-runtime": "^0.4.7",
+        "@gobing-ai/ts-db": "^0.4.9",
+        "@gobing-ai/ts-runtime": "^0.4.9",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -116,8 +116,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.7",
-        "@gobing-ai/ts-runtime": "^0.4.7",
+        "@gobing-ai/ts-db": "^0.4.9",
+        "@gobing-ai/ts-runtime": "^0.4.9",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/api-client.ts

@@ -7,7 +7,7 @@ import {
     ATTR_HTTP_RESPONSE_STATUS_CODE,
     ATTR_URL_FULL,
 } from '@opentelemetry/semantic-conventions';
-import type { EventBus } from './event-bus/event-bus';
+import { type BusLifecycleEvents, EventBus } from './event-bus/index';
 import type { ApiClientEvents } from './events';
 import {
     getHttpClientRequestDuration,
@@ -30,6 +30,13 @@ export interface APIClientConfig {
      * returns non-2xx statuses normally, so it emits only on network/timeout.
      */
     events?: EventBus<ApiClientEvents>;
+    /**
+     * Optional lifecycle bus to bridge `api.*` events into the application
+     * System Events stream (R5). When `events` is omitted the client
+     * constructs an internal `EventBus<ApiClientEvents>` parented to this
+     * bus so `api.request.error` appears in the JSONL log.
+     */
+    lifecycleBus?: EventBus<BusLifecycleEvents>;
 }
 /** Per-request overrides: headers, timeout, operation name, and abort signal. */
 export interface RequestOptions {
@@ -137,9 +144,7 @@ async function readBodyCapped(
 /**
  * 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');
  * ```
@@ -156,7 +161,9 @@ export class APIClient {
         this.defaultHeaders = config.defaultHeaders ?? {};
         this.timeout = config.timeout ?? 30_000;
         this.fetchFn = config.fetch ?? globalThis.fetch;
-        this.events = config.events;
+        this.events =
+            config.events ??
+            (config.lifecycleBus ? new EventBus<ApiClientEvents>({ lifecycleBus: config.lifecycleBus }) : undefined);
     }
 
     private buildUrl(path: string): string {

package/src/application/index.ts

@@ -12,6 +12,7 @@
 
 import { attachDefaultObservers, createLifecycleBus } from '../event-bus/default-observers';
 import { EventBus } from '../event-bus/event-bus';
+import { attachFileObserver } from '../event-bus/file-observer';
 import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
 import type { InfraEvents } from '../events';
 import { getLogger, type Logger } from '../logger';
@@ -65,6 +66,12 @@ async function performShutdown<TAppConfig, TEvents extends EventMap>(
  * Accepts injected dependencies; never opens files, reads config from disk,
  * or wires runtime-specific exporters.
  *
+ * The returned `lifecycleBus` is the parent of the application `events` bus and
+ * can be passed to RuleEngine, WorkflowService, AiRunner, TeamOrchestrator, and
+ * APIClient so their domain events share one System Events stream. A supplied
+ * file-observer writer records that stream as JSONL; the Node subpath supplies
+ * the writer and default `logs/system-events.jsonl` path.
+ *
  * 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
@@ -119,10 +126,13 @@ export async function runApplication<TAppConfig = unknown, TEvents extends Event
         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 eventsFileObserver = options.config?.events?.fileObserver ?? true;
+    const fileObserverWriter = options.services?.fileObserverWriter;
+    const eventsFilePath =
+        options.config?.events?.filePath ?? (fileObserverWriter !== undefined ? 'logs/system-events.jsonl' : undefined);
 
     const state: RuntimeState<TAppConfig, TEvents> = {
         app: undefined,
@@ -143,6 +153,19 @@ export async function runApplication<TAppConfig = unknown, TEvents extends Event
             attachDefaultObservers(lifecycleBus);
         }
 
+        // Attach the JSONL file observer when a writer is available. The
+        // portable subpath never opens files (ADR-011): the Node subpath
+        // injects `createNodeFileSystem()` (or a test stub) and resolves the
+        // default path against the project root. Without a writer or path
+        // the observer is a no-op even if `events.fileObserver` is `true`.
+        let fileObserverAttached = false;
+        let fileObserverPath: string | undefined;
+        if (lifecycleBus && eventsFileObserver && eventsFilePath !== undefined && fileObserverWriter !== undefined) {
+            attachFileObserver(lifecycleBus, eventsFilePath, fileObserverWriter);
+            fileObserverAttached = true;
+            fileObserverPath = eventsFilePath;
+        }
+
         const events =
             options.services?.events ??
             options.config?.events?.bus ??
@@ -173,7 +196,13 @@ export async function runApplication<TAppConfig = unknown, TEvents extends Event
         // ── Build runtime handle (before startAll so plugins can capture it) ─
         const resolvedConfig: ApplicationBootstrapConfig = {
             logging: loggingConfig,
-            events: { enabled: eventsEnabled, lifecycle: eventsLifecycle, defaultObservers: eventsDefaultObservers },
+            events: {
+                enabled: eventsEnabled,
+                lifecycle: eventsLifecycle,
+                defaultObservers: eventsDefaultObservers,
+                fileObserver: fileObserverAttached,
+                ...(fileObserverPath !== undefined ? { filePath: fileObserverPath } : {}),
+            },
             telemetry: telemetryConfig,
             scheduler: schedulerConfig,
         };

package/src/application/types.ts

@@ -9,6 +9,7 @@
  */
 
 import type { EventBus } from '../event-bus/event-bus';
+import type { FileObserverWriter } from '../event-bus/file-observer';
 import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
 import type { InfraEvents } from '../events';
 import type { Logger, LogLevel } from '../logger';
@@ -43,6 +44,20 @@ export interface EventsOptions<TEvents extends EventMap = InfraEvents> {
     lifecycle?: boolean;
     /** Attach default observers (log + telemetry). Default `true`. */
     defaultObservers?: boolean;
+    /**
+     * Attach a file observer that appends JSONL rows for every lifecycle
+     * event to `filePath`. Default `true` when a writer is available
+     * (Node subpath injects `createNodeFileSystem()`; portable callers must
+     * supply one via `services.fileObserverWriter`). No-op when `lifecycle`
+     * is disabled or no writer is present.
+     */
+    fileObserver?: boolean;
+    /**
+     * JSONL output path. Defaults to `logs/system-events.jsonl` when a writer
+     * is supplied; the Node subpath resolves this against the project root.
+     * Portable callers may override it with an absolute path.
+     */
+    filePath?: string;
     /** Pre-built event bus (skips creation when provided). */
     bus?: EventBus<TEvents>;
 }
@@ -81,7 +96,15 @@ export interface ApplicationBootstrapConfig {
     readonly logging: Readonly<
         Required<Pick<LoggingOptions, 'enabled' | 'level' | 'console' | 'json'>> & { fileSink?: (line: string) => void }
     >;
-    readonly events: { enabled: boolean; lifecycle: boolean; defaultObservers: boolean };
+    readonly events: {
+        enabled: boolean;
+        lifecycle: boolean;
+        defaultObservers: boolean;
+        /** Whether the JSONL file observer was attached (false when no writer is available). */
+        fileObserver: boolean;
+        /** Resolved JSONL absolute path, or undefined when fileObserver is false. */
+        filePath?: string;
+    };
     readonly telemetry: { enabled: boolean; serviceName: string; environment: string; dbStatementDebug: boolean };
     readonly scheduler: { enabled: boolean; autoStart: boolean };
 }
@@ -93,6 +116,13 @@ export interface ApplicationServices<TEvents extends EventMap = InfraEvents> {
     logger?: Logger;
     events?: EventBus<TEvents>;
     lifecycleBus?: EventBus<BusLifecycleEvents>;
+    /**
+     * Writer for `attachFileObserver`. Portable subpath never opens files
+     * (ADR-011); the Node subpath injects `createNodeFileSystem()`. When
+     * absent, the file observer is skipped even if `events.fileObserver`
+     * is `true`.
+     */
+    fileObserverWriter?: FileObserverWriter;
     db?: DbAdapterLike;
     scheduler?: SchedulerAdapter;
     /** Pre-built plugin host (when injecting instead of constructing). */

package/src/application-node.ts

@@ -19,7 +19,7 @@ import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 
 import { createDbAdapter, type DbAdapter } from '@gobing-ai/ts-db';
-import { interpolateTree, parseYamlObject } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, interpolateTree, parseYamlObject } from '@gobing-ai/ts-runtime';
 
 import { runApplication } from './application/index';
 import { dbPlugin } from './application/plugins/builtins';
@@ -252,11 +252,13 @@ export async function runNodeApplication<TAppConfig = unknown, TEvents extends E
     const yamlLog = yamlBootstrap.logging as Partial<LoggingOptions> | undefined;
     const yamlTel = yamlBootstrap.telemetry as Partial<NodeTelemetryBootstrapOptions> | undefined;
     const yamlSched = yamlBootstrap.scheduler as Partial<SchedulerOptions> | undefined;
+    const yamlEvents = yamlBootstrap.events as Partial<EventsOptions<TEvents>> | undefined;
     const databaseOpts = (yamlBootstrap.database ?? {}) as Record<string, unknown>;
 
     const loggingOpts: Partial<LoggingOptions> = { ...yamlLog, ...options.config?.logging };
     const telemetryOpts: Partial<NodeTelemetryBootstrapOptions> = { ...yamlTel, ...options.config?.telemetry };
     const schedulerOpts: Partial<SchedulerOptions> = { ...yamlSched, ...options.config?.scheduler };
+    const eventsOpts: EventsOptions<TEvents> = { ...yamlEvents, ...options.config?.events };
 
     const logFilePath = (yamlBootstrap.logging as Record<string, unknown> | undefined)?.filePath as string | undefined;
     const loggingConfig: Partial<LoggingOptions> =
@@ -319,14 +321,41 @@ export async function runNodeApplication<TAppConfig = unknown, TEvents extends E
         }
     }
 
+    // ── Inject Node file observer (ADR-011 writer for the JSONL bus log) ──
+    // The portable `runApplication` never opens files; the Node subpath
+    // supplies the writer and resolves the default path against the project
+    // root. Caller-provided `services.fileObserverWriter` and
+    // `config.events.filePath` overrides win; `fileObserver: false` disables.
+    const injectedFileSystem = createNodeFileSystem();
+    const fileObserverWriter = options.services?.fileObserverWriter ?? {
+        ensureDir: (dir: string) => {
+            mkdirSync(dir, { recursive: true });
+        },
+        appendFile: (path: string, content: string) => {
+            appendFileSync(path, content);
+        },
+    };
+    const eventsFilePath = eventsOpts.filePath ?? injectedFileSystem.resolve('logs', 'system-events.jsonl');
+    const eventsConfig: EventsOptions<TEvents> = {
+        ...eventsOpts,
+        filePath: eventsFilePath,
+        ...(eventsOpts.fileObserver === false ? {} : { fileObserver: true }),
+    };
+
     // ── Delegate to portable runApplication ─────────────────────────────
     // Node-specific cleanup is handled by plugins in the service ring —
     // node-telemetry onStop, owned-db onStop. No manual try/catch or stop
     // override needed.
     return await runApplication<TAppConfig, TEvents>({
-        config: { ...options.config, logging: loggingConfig, telemetry: telemetryOpts, scheduler: schedulerConfig },
+        config: {
+            ...options.config,
+            logging: loggingConfig,
+            telemetry: telemetryOpts,
+            scheduler: schedulerConfig,
+            events: eventsConfig,
+        },
         appConfig: loadedAppConfig,
-        services: { ...options.services, ...(dbAdapter ? { db: dbAdapter } : {}) },
+        services: { ...options.services, fileObserverWriter, ...(dbAdapter ? { db: dbAdapter } : {}) },
         start: options.start,
         stop: options.stop,
         plugins: plugins.length ? plugins : undefined,

package/src/index.ts

@@ -15,6 +15,7 @@ export {
     attachFileObserver,
     attachLogObserver,
     attachTelemetryObserver,
+    type BusLifecycleEvents,
     createLifecycleBus,
     EventBus,
     type EventMap,