@alvin0/ai-agent-sdk-observability-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alvin0 (chaulamdinhai) <chaulamdinhai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @alvin0/ai-agent-sdk-observability-node
+
+Runtime: **Node 22.12+**.
+
+```sh
+pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-observability-node
+```
+
+Node-only durable observation journal and explicit lifecycle/diagnostic helpers.
+The journal root is always caller-supplied. Records use checksum-framed JSONL,
+private directory/file modes, unique segments, atomic acknowledgment cursors,
+bounded retention, and strict corruption recovery.
+
+Exact provider-wire diagnostics are a separate high-risk capability and refuse
+construction unless both `content: 'full'` and `allowWireBodies: true` are set.
+Nothing installs process lifecycle handlers automatically.
+
+For normal runtime composition, use the inert `jsonlObservationExporter()`
+factory. Filesystem resources are acquired only when `createAgentRuntime()`
+calls its `ready()` lifecycle boundary:
+
+```ts
+import { createAgentRuntime } from '@alvin0/ai-agent-sdk-core'
+import {
+  jsonlObservationExporter,
+  recoverRuntimeObservationJournal,
+} from '@alvin0/ai-agent-sdk-observability-node'
+
+const runtime = await createAgentRuntime({
+  providers: [provider],
+  observability: {
+    mode: 'reliable',
+    exporters: [{
+      exporter: jsonlObservationExporter({
+        rootDir: './observations',
+        mode: 'reliable',
+      }),
+      ownership: 'owned',
+      requirement: 'required',
+      boundary: 'local-durable',
+    }],
+  },
+})
+
+await runtime.close()
+const recovered = await recoverRuntimeObservationJournal('./observations')
+```
+
+The runtime adapter persists privacy-filtered events and atomic terminal run
+records in `runtime-delivery/`, and acknowledges their IDs separately. The
+caller still closes the runtime explicitly; an owned exporter is closed by the
+runtime after all active runs settle. `recoverRuntimeObservationJournal()`
+verifies checksums and returns both event and terminal-run records from this
+recommended format; `recoverJournal()` remains the advanced legacy-journal
+recovery API.
+
+Composition: `runtime.observability.exporters`. Lifecycle:
+`explicit-owned-or-borrowed`; normal JSONL composition selects owned local
+durability, while advanced hosts may retain a borrowed exporter explicitly.
+
+Use `@alvin0/ai-agent-sdk-observability-node/journal` when only durable journal and
+lifecycle APIs are needed, or `@alvin0/ai-agent-sdk-observability-node/diagnostic` for
+the separately gated exact-wire capability. That diagnostic route exports
+`createDailyJsonlRequestLogger()` and `combineProviderRequestLoggers()` for
+provider request-logger slots. The root entry re-exports both.

package/dist/diagnostic-B0r2HLqz.d.mts

@@ -0,0 +1,44 @@
+import { JsonValue, ObservationContentPolicy } from "@alvin0/ai-agent-sdk-core/observability";
+//#region src/diagnostic/wire-logger.d.ts
+interface ProviderWireLogRecord {
+  readonly schemaVersion: 1;
+  readonly type: string;
+  readonly provider: string;
+  readonly timestamp: string;
+  readonly [key: string]: JsonValue;
+}
+interface ProviderWireLogger {
+  (record: ProviderWireLogRecord): Promise<void>;
+  shutdown(): Promise<void>;
+}
+interface DiagnosticWireLoggerOptions {
+  readonly rootDir: string;
+  readonly content: ObservationContentPolicy;
+  readonly allowWireBodies: boolean;
+  readonly now?: () => Date;
+}
+/** Create an exact-wire logger only after two explicit high-risk opt-ins. */
+declare function createDiagnosticWireLogger(options: DiagnosticWireLoggerOptions): ProviderWireLogger;
+//#endregion
+//#region src/diagnostic/request-logger.d.ts
+/** Minimum structural input accepted from an HTTP provider request logger. */
+interface ProviderRequestLogLike {
+  readonly provider: string;
+  readonly timestamp: string;
+}
+interface DailyJsonlRequestLoggerOptions {
+  readonly rootDir?: string;
+  readonly content: 'full';
+  readonly allowWireBodies: true;
+  readonly now?: () => Date;
+  /** @deprecated Unique diagnostic files always use a UTC date. */
+  readonly calendar?: 'local' | 'utc';
+}
+type DailyJsonlRequestLogger = ((record: ProviderRequestLogLike) => Promise<void>) & Pick<ProviderWireLogger, 'shutdown'>;
+/** Compatibility-shaped exact request logger hosted by the Node diagnostic capability. */
+declare function createDailyJsonlRequestLogger(options: DailyJsonlRequestLoggerOptions): DailyJsonlRequestLogger;
+/** Fan one exact request record out to independent caller-owned log sinks. */
+declare function combineProviderRequestLoggers<RecordType extends ProviderRequestLogLike>(...loggers: readonly ((record: RecordType) => Promise<void> | void)[]): (record: RecordType) => Promise<void>;
+//#endregion
+export { createDailyJsonlRequestLogger as a, ProviderWireLogger as c, combineProviderRequestLoggers as i, createDiagnosticWireLogger as l, DailyJsonlRequestLoggerOptions as n, DiagnosticWireLoggerOptions as o, ProviderRequestLogLike as r, ProviderWireLogRecord as s, DailyJsonlRequestLogger as t };
+//# sourceMappingURL=diagnostic-B0r2HLqz.d.mts.map

package/dist/diagnostic-B0r2HLqz.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-B0r2HLqz.d.mts","names":[],"sources":["../src/diagnostic/wire-logger.ts","../src/diagnostic/request-logger.ts"],"mappings":";;UAMiB;WACN;WACA;WACA;WACA;YACC,cAAc;;UAGT;GACd,QAAQ,wBAAwB;EACjC,YAAY;;UAGG;WACN;WACA,SAAS;WACT;WACA,YAAY;;;iBASP,2BAA2B,SAAS,8BAA8B;;;;UCzBjE;WACN;WACA;;UAGM;WACN;WACA;WACA;WACA,YAAY;;WAEZ;;KAGC,4BACT,QAAQ,2BAA2B,iBAClC,KAAK;;iBAGO,8BACd,SAAS,iCACR;;iBAea,8BAA8B,mBAAmB,2BAC5D,oBAAoB,QAAQ,eAAe,2BAC5C,QAAQ,eAAe"}

package/dist/diagnostic-Cf6AKmxT.mjs

@@ -0,0 +1,80 @@
+import { n as ensureSafeRoot, r as openExclusiveFile } from "./safe-filesystem-CbOPNSoN.mjs";
+import { randomBytes } from "node:crypto";
+import { join, resolve } from "node:path";
+
+//#region src/diagnostic/wire-logger.ts
+function providerSegment(value) {
+	const safe = value.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_");
+	return safe.length === 0 ? "_unknown" : safe;
+}
+/** Create an exact-wire logger only after two explicit high-risk opt-ins. */
+function createDiagnosticWireLogger(options) {
+	if (options?.content !== "full" || options.allowWireBodies !== true) throw new TypeError("wire diagnostics require content: 'full' and allowWireBodies: true");
+	const rootInput = resolve(options.rootDir);
+	const handles = /* @__PURE__ */ new Map();
+	let tail = Promise.resolve();
+	let closed = false;
+	const handleFor = (provider) => {
+		const segment = providerSegment(provider);
+		const existing = handles.get(segment);
+		if (existing !== void 0) return existing;
+		const pending = (async () => {
+			const root = await ensureSafeRoot(join(rootInput, segment, "wire"));
+			const day = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+			return await openExclusiveFile(root, `${day}-${process.pid}-${randomBytes(8).toString("hex")}.wire.jsonl`);
+		})();
+		handles.set(segment, pending);
+		return pending;
+	};
+	const logger = (async (record) => {
+		if (closed) throw new TypeError("wire diagnostic logger is closed");
+		const write = tail.then(async () => {
+			await (await handleFor(record.provider)).writeFile(`${JSON.stringify({
+				...record,
+				timestamp: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString()
+			})}\n`, "utf8");
+		});
+		tail = write.catch(() => void 0);
+		await write;
+	});
+	logger.shutdown = async () => {
+		if (closed) return;
+		closed = true;
+		await tail;
+		for (const handle of await Promise.all(handles.values())) {
+			await handle.datasync();
+			await handle.close();
+		}
+	};
+	return logger;
+}
+
+//#endregion
+//#region src/diagnostic/request-logger.ts
+/** Compatibility-shaped exact request logger hosted by the Node diagnostic capability. */
+function createDailyJsonlRequestLogger(options) {
+	const wire = createDiagnosticWireLogger({
+		rootDir: options.rootDir ?? ".providers",
+		content: options.content,
+		allowWireBodies: options.allowWireBodies,
+		...options.now === void 0 ? {} : { now: options.now }
+	});
+	const logger = (async (record) => {
+		await wire(record);
+	});
+	logger.shutdown = () => wire.shutdown();
+	return logger;
+}
+/** Fan one exact request record out to independent caller-owned log sinks. */
+function combineProviderRequestLoggers(...loggers) {
+	const sinks = Object.freeze([...loggers]);
+	return async (record) => {
+		await Promise.all(sinks.map(async (logger) => {
+			await logger(record);
+		}));
+	};
+}
+
+//#endregion
+export { createDailyJsonlRequestLogger as n, createDiagnosticWireLogger as r, combineProviderRequestLoggers as t };
+//# sourceMappingURL=diagnostic-Cf6AKmxT.mjs.map

package/dist/diagnostic-Cf6AKmxT.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-Cf6AKmxT.mjs","names":[],"sources":["../src/diagnostic/wire-logger.ts","../src/diagnostic/request-logger.ts"],"sourcesContent":["import { randomBytes } from 'node:crypto'\nimport type { FileHandle } from 'node:fs/promises'\nimport { join, resolve } from 'node:path'\nimport type { JsonValue, ObservationContentPolicy } from '@alvin0/ai-agent-sdk-core/observability'\nimport { ensureSafeRoot, openExclusiveFile } from '../common/safe-filesystem.ts'\n\nexport interface ProviderWireLogRecord {\n  readonly schemaVersion: 1\n  readonly type: string\n  readonly provider: string\n  readonly timestamp: string\n  readonly [key: string]: JsonValue\n}\n\nexport interface ProviderWireLogger {\n  (record: ProviderWireLogRecord): Promise<void>\n  shutdown(): Promise<void>\n}\n\nexport interface DiagnosticWireLoggerOptions {\n  readonly rootDir: string\n  readonly content: ObservationContentPolicy\n  readonly allowWireBodies: boolean\n  readonly now?: () => Date\n}\n\nfunction providerSegment(value: string): string {\n  const safe = value.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\\.+/, '_')\n  return safe.length === 0 ? '_unknown' : safe\n}\n\n/** Create an exact-wire logger only after two explicit high-risk opt-ins. */\nexport function createDiagnosticWireLogger(options: DiagnosticWireLoggerOptions): ProviderWireLogger {\n  if (options?.content !== 'full' || options.allowWireBodies !== true) {\n    throw new TypeError(\"wire diagnostics require content: 'full' and allowWireBodies: true\")\n  }\n  const rootInput = resolve(options.rootDir)\n  const handles = new Map<string, Promise<FileHandle>>()\n  let tail: Promise<void> = Promise.resolve()\n  let closed = false\n  const handleFor = (provider: string): Promise<FileHandle> => {\n    const segment = providerSegment(provider)\n    const existing = handles.get(segment)\n    if (existing !== undefined) return existing\n    const pending = (async () => {\n      const root = await ensureSafeRoot(join(rootInput, segment, 'wire'))\n      const day = (options.now?.() ?? new Date()).toISOString().slice(0, 10)\n      return await openExclusiveFile(root, `${day}-${process.pid}-${randomBytes(8).toString('hex')}.wire.jsonl`)\n    })()\n    handles.set(segment, pending)\n    return pending\n  }\n  const logger = (async (record: ProviderWireLogRecord) => {\n    if (closed) throw new TypeError('wire diagnostic logger is closed')\n    const write = tail.then(async () => {\n      const handle = await handleFor(record.provider)\n      await handle.writeFile(\n        `${JSON.stringify({ ...record, timestamp: (options.now?.() ?? new Date()).toISOString() })}\\n`,\n        'utf8',\n      )\n    })\n    tail = write.catch(() => undefined)\n    await write\n  }) as ProviderWireLogger\n  logger.shutdown = async () => {\n    if (closed) return\n    closed = true\n    await tail\n    for (const handle of await Promise.all(handles.values())) {\n      await handle.datasync()\n      await handle.close()\n    }\n  }\n  return logger\n}\n","import {\n  createDiagnosticWireLogger,\n  type ProviderWireLogRecord,\n  type ProviderWireLogger,\n} from './wire-logger.ts'\n\n/** Minimum structural input accepted from an HTTP provider request logger. */\nexport interface ProviderRequestLogLike {\n  readonly provider: string\n  readonly timestamp: string\n}\n\nexport interface DailyJsonlRequestLoggerOptions {\n  readonly rootDir?: string\n  readonly content: 'full'\n  readonly allowWireBodies: true\n  readonly now?: () => Date\n  /** @deprecated Unique diagnostic files always use a UTC date. */\n  readonly calendar?: 'local' | 'utc'\n}\n\nexport type DailyJsonlRequestLogger = (\n  (record: ProviderRequestLogLike) => Promise<void>\n) & Pick<ProviderWireLogger, 'shutdown'>\n\n/** Compatibility-shaped exact request logger hosted by the Node diagnostic capability. */\nexport function createDailyJsonlRequestLogger(\n  options: DailyJsonlRequestLoggerOptions,\n): DailyJsonlRequestLogger {\n  const wire = createDiagnosticWireLogger({\n    rootDir: options.rootDir ?? '.providers',\n    content: options.content,\n    allowWireBodies: options.allowWireBodies,\n    ...(options.now === undefined ? {} : { now: options.now }),\n  })\n  const logger = (async (record: ProviderRequestLogLike): Promise<void> => {\n    await wire(record as ProviderWireLogRecord)\n  }) as DailyJsonlRequestLogger\n  logger.shutdown = () => wire.shutdown()\n  return logger\n}\n\n/** Fan one exact request record out to independent caller-owned log sinks. */\nexport function combineProviderRequestLoggers<RecordType extends ProviderRequestLogLike>(\n  ...loggers: readonly ((record: RecordType) => Promise<void> | void)[]\n): (record: RecordType) => Promise<void> {\n  const sinks = Object.freeze([...loggers])\n  return async record => {\n    await Promise.all(sinks.map(async logger => { await logger(record) }))\n  }\n}\n"],"mappings":";;;;;AA0BA,SAAS,gBAAgB,OAAuB;CAC9C,MAAM,OAAO,MAAM,QAAQ,oBAAoB,GAAG,CAAC,CAAC,QAAQ,QAAQ,GAAG;CACvE,OAAO,KAAK,WAAW,IAAI,aAAa;AAC1C;;AAGA,SAAgB,2BAA2B,SAA0D;CACnG,IAAI,SAAS,YAAY,UAAU,QAAQ,oBAAoB,MAC7D,MAAM,IAAI,UAAU,oEAAoE;CAE1F,MAAM,YAAY,QAAQ,QAAQ,OAAO;CACzC,MAAM,0BAAU,IAAI,IAAiC;CACrD,IAAI,OAAsB,QAAQ,QAAQ;CAC1C,IAAI,SAAS;CACb,MAAM,aAAa,aAA0C;EAC3D,MAAM,UAAU,gBAAgB,QAAQ;EACxC,MAAM,WAAW,QAAQ,IAAI,OAAO;EACpC,IAAI,aAAa,QAAW,OAAO;EACnC,MAAM,WAAW,YAAY;GAC3B,MAAM,OAAO,MAAM,eAAe,KAAK,WAAW,SAAS,MAAM,CAAC;GAClE,MAAM,OAAO,QAAQ,MAAM,qBAAK,IAAI,KAAK,EAAC,CAAE,YAAY,CAAC,CAAC,MAAM,GAAG,EAAE;GACrE,OAAO,MAAM,kBAAkB,MAAM,GAAG,IAAI,GAAG,QAAQ,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,SAAS,KAAK,EAAE,YAAY;EAC3G,EAAC,CAAE;EACH,QAAQ,IAAI,SAAS,OAAO;EAC5B,OAAO;CACT;CACA,MAAM,UAAU,OAAO,WAAkC;EACvD,IAAI,QAAQ,MAAM,IAAI,UAAU,kCAAkC;EAClE,MAAM,QAAQ,KAAK,KAAK,YAAY;GAElC,OAAM,MADe,UAAU,OAAO,QAAQ,EAClC,CAAC,UACX,GAAG,KAAK,UAAU;IAAE,GAAG;IAAQ,YAAY,QAAQ,MAAM,qBAAK,IAAI,KAAK,EAAC,CAAE,YAAY;GAAE,CAAC,EAAE,KAC3F,MACF;EACF,CAAC;EACD,OAAO,MAAM,YAAY,MAAS;EAClC,MAAM;CACR;CACA,OAAO,WAAW,YAAY;EAC5B,IAAI,QAAQ;EACZ,SAAS;EACT,MAAM;EACN,KAAK,MAAM,UAAU,MAAM,QAAQ,IAAI,QAAQ,OAAO,CAAC,GAAG;GACxD,MAAM,OAAO,SAAS;GACtB,MAAM,OAAO,MAAM;EACrB;CACF;CACA,OAAO;AACT;;;;;AChDA,SAAgB,8BACd,SACyB;CACzB,MAAM,OAAO,2BAA2B;EACtC,SAAS,QAAQ,WAAW;EAC5B,SAAS,QAAQ;EACjB,iBAAiB,QAAQ;EACzB,GAAI,QAAQ,QAAQ,SAAY,CAAC,IAAI,EAAE,KAAK,QAAQ,IAAI;CAC1D,CAAC;CACD,MAAM,UAAU,OAAO,WAAkD;EACvE,MAAM,KAAK,MAA+B;CAC5C;CACA,OAAO,iBAAiB,KAAK,SAAS;CACtC,OAAO;AACT;;AAGA,SAAgB,8BACd,GAAG,SACoC;CACvC,MAAM,QAAQ,OAAO,OAAO,CAAC,GAAG,OAAO,CAAC;CACxC,OAAO,OAAM,WAAU;EACrB,MAAM,QAAQ,IAAI,MAAM,IAAI,OAAM,WAAU;GAAE,MAAM,OAAO,MAAM;EAAE,CAAC,CAAC;CACvE;AACF"}

package/dist/diagnostic.d.mts

@@ -0,0 +1,2 @@
+import { a as createDailyJsonlRequestLogger, c as ProviderWireLogger, i as combineProviderRequestLoggers, l as createDiagnosticWireLogger, n as DailyJsonlRequestLoggerOptions, o as DiagnosticWireLoggerOptions, r as ProviderRequestLogLike, s as ProviderWireLogRecord, t as DailyJsonlRequestLogger } from "./diagnostic-B0r2HLqz.mjs";
+export { type DailyJsonlRequestLogger, type DailyJsonlRequestLoggerOptions, type DiagnosticWireLoggerOptions, type ProviderRequestLogLike, type ProviderWireLogRecord, type ProviderWireLogger, combineProviderRequestLoggers, createDailyJsonlRequestLogger, createDiagnosticWireLogger };

package/dist/diagnostic.mjs

@@ -0,0 +1,3 @@
+import { n as createDailyJsonlRequestLogger, r as createDiagnosticWireLogger, t as combineProviderRequestLoggers } from "./diagnostic-Cf6AKmxT.mjs";
+
+export { combineProviderRequestLoggers, createDailyJsonlRequestLogger, createDiagnosticWireLogger };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { a as createDailyJsonlRequestLogger, c as ProviderWireLogger, i as combineProviderRequestLoggers, l as createDiagnosticWireLogger, n as DailyJsonlRequestLoggerOptions, o as DiagnosticWireLoggerOptions, r as ProviderRequestLogLike, s as ProviderWireLogRecord, t as DailyJsonlRequestLogger } from "./diagnostic-B0r2HLqz.mjs";
+import { _ as JsonlObservationJournalOptions, a as NodeLifecycleTarget, c as recoverRuntimeObservationJournal, d as JournalRecoveryRecord, f as JournalRecoveryResult, g as JournalDurabilityMode, h as recoverJournal, i as NodeLifecycleOptions, l as RuntimeJournalRecoveryResult, m as JsonlObservationJournalExporter, n as NodeObservationError, o as installNodeObservabilityLifecycle, p as JournalStats, r as NodeObservationErrorCode, s as jsonlObservationExporter, t as NODE_OBSERVATION_ERROR_CODES, u as RuntimeJournalRecord } from "./journal-export-BMfSC4Z6.mjs";
+export { type DailyJsonlRequestLogger, type DailyJsonlRequestLoggerOptions, type DiagnosticWireLoggerOptions, type JournalDurabilityMode, type JournalRecoveryRecord, type JournalRecoveryResult, type JournalStats, JsonlObservationJournalExporter, type JsonlObservationJournalOptions, NODE_OBSERVATION_ERROR_CODES, type NodeLifecycleOptions, type NodeLifecycleTarget, NodeObservationError, type NodeObservationErrorCode, type ProviderRequestLogLike, type ProviderWireLogRecord, type ProviderWireLogger, type RuntimeJournalRecord as RuntimeJournalRecoveryRecord, type RuntimeJournalRecoveryResult, combineProviderRequestLoggers, createDailyJsonlRequestLogger, createDiagnosticWireLogger, installNodeObservabilityLifecycle, jsonlObservationExporter, recoverJournal, recoverRuntimeObservationJournal };

package/dist/index.mjs

@@ -0,0 +1,5 @@
+import { a as recoverJournal, i as JsonlObservationJournalExporter, n as jsonlObservationExporter, r as recoverRuntimeObservationJournal, t as installNodeObservabilityLifecycle } from "./journal-export-HAdAQxLv.mjs";
+import { a as NodeObservationError, i as NODE_OBSERVATION_ERROR_CODES } from "./safe-filesystem-CbOPNSoN.mjs";
+import { n as createDailyJsonlRequestLogger, r as createDiagnosticWireLogger, t as combineProviderRequestLoggers } from "./diagnostic-Cf6AKmxT.mjs";
+
+export { JsonlObservationJournalExporter, NODE_OBSERVATION_ERROR_CODES, NodeObservationError, combineProviderRequestLoggers, createDailyJsonlRequestLogger, createDiagnosticWireLogger, installNodeObservabilityLifecycle, jsonlObservationExporter, recoverJournal, recoverRuntimeObservationJournal };

package/dist/journal-export-BMfSC4Z6.d.mts

@@ -0,0 +1,125 @@
+import { ObservationBoundary, ObservationEvent } from "@alvin0/ai-agent-sdk-core";
+import { ExportAck, Observability, ObservationBatch, ObservationExportItem, ObservationExporter, ObservationExporterPlugin } from "@alvin0/ai-agent-sdk-core/observability";
+//#region src/journal/types.d.ts
+type JournalDurabilityMode = 'operational' | 'reliable' | 'audit';
+interface JsonlObservationJournalOptions {
+  readonly id?: string;
+  readonly rootDir: string;
+  readonly mode: JournalDurabilityMode;
+  readonly maxSegmentBytes?: number;
+  readonly maxRetainedBytes?: number;
+  readonly acknowledgedRetentionMs?: number;
+  readonly syncIntervalMs?: number;
+  readonly syncRecordCount?: number;
+  readonly now?: () => Date;
+  readonly segmentId?: () => string;
+}
+//#endregion
+//#region src/journal.d.ts
+interface JournalRecoveryRecord {
+  readonly segment: string;
+  readonly line: number;
+  readonly event: ObservationEvent;
+  readonly payloadJson: string;
+}
+interface JournalRecoveryResult {
+  readonly records: readonly JournalRecoveryRecord[];
+  readonly quarantinedSegments: readonly string[];
+  readonly truncatedSegments: readonly string[];
+}
+interface JournalStats {
+  readonly segmentCount: number;
+  readonly retainedBytes: number;
+  readonly unacknowledgedEvents: number;
+  readonly currentSegment?: string;
+}
+/** Append-only Node journal whose local durability is measured with fdatasync. */
+declare class JsonlObservationJournalExporter implements ObservationExporter {
+  readonly id: string;
+  readonly supportedBoundaries: readonly ObservationBoundary[];
+  private readonly options;
+  private readonly rootPromise;
+  private current;
+  private writeTail;
+  private readonly pendingStages;
+  private readonly batchEvents;
+  private readonly acknowledged;
+  private syncTimer;
+  private unsyncedRecords;
+  private unsyncedCritical;
+  private closing;
+  constructor(options: JsonlObservationJournalOptions);
+  ready(): Promise<void>;
+  stage(event: ObservationEvent): Promise<void>;
+  export(batch: ObservationBatch, signal: AbortSignal): Promise<ExportAck>;
+  acknowledgeBatch(batchId: string): Promise<number>;
+  acknowledgeEvents(eventIds: readonly string[]): Promise<void>;
+  recover(): Promise<JournalRecoveryResult>;
+  cleanup(): Promise<void>;
+  private cleanupNow;
+  stats(): Promise<JournalStats>;
+  shutdown(_signal: AbortSignal): Promise<void>;
+  private initialize;
+  private enqueueWrite;
+  private openSegment;
+  private rotateIfNeeded;
+  private scheduleReliableSync;
+  private syncCurrent;
+  private ensureCapacity;
+  private loadCursor;
+  private persistCursor;
+}
+declare function recoverJournal(rootInput: string): Promise<JournalRecoveryResult>;
+//#endregion
+//#region src/journal/runtime-frame.d.ts
+type RuntimeFrameKind = 'event' | 'run-terminal-record';
+interface RuntimeJournalRecord {
+  readonly segment: string;
+  readonly line: number;
+  readonly kind: RuntimeFrameKind;
+  readonly id: string;
+  readonly key: string;
+  readonly item: ObservationExportItem;
+  readonly payloadJson: string;
+}
+//#endregion
+//#region src/journal/runtime-store.d.ts
+interface RuntimeJournalRecoveryResult {
+  readonly records: readonly RuntimeJournalRecord[];
+  readonly truncatedSegments: readonly string[];
+  readonly quarantinedSegments: readonly string[];
+}
+//#endregion
+//#region src/journal/runtime-exporter.d.ts
+/** Recommended runtime adapter. The advanced marker-free journal remains independent. */
+declare function jsonlObservationExporter(options: JsonlObservationJournalOptions): ObservationExporterPlugin;
+/** Verify and recover records written by the recommended runtime exporter. */
+declare function recoverRuntimeObservationJournal(rootDir: string): Promise<RuntimeJournalRecoveryResult>;
+//#endregion
+//#region src/lifecycle.d.ts
+interface NodeLifecycleTarget {
+  on(event: 'beforeExit' | 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+  off(event: 'beforeExit' | 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+interface NodeLifecycleOptions {
+  readonly target?: NodeLifecycleTarget;
+  readonly signals?: readonly ('SIGINT' | 'SIGTERM')[];
+  readonly onFailure?: (error: unknown) => void;
+}
+/** Install opt-in Node shutdown triggers and return an idempotent disposer. */
+declare function installNodeObservabilityLifecycle(observation: Pick<Observability, 'shutdown'>, options?: NodeLifecycleOptions): () => void;
+//#endregion
+//#region src/common/errors.d.ts
+declare const NODE_OBSERVATION_ERROR_CODES: Readonly<{
+  readonly corrupt: 'OBSERVABILITY_JOURNAL_CORRUPT';
+  readonly io: 'OBSERVABILITY_JOURNAL_IO';
+}>;
+type NodeObservationErrorCode = typeof NODE_OBSERVATION_ERROR_CODES[keyof typeof NODE_OBSERVATION_ERROR_CODES];
+declare class NodeObservationError extends Error {
+  readonly name = "NodeObservationError";
+  readonly code: NodeObservationErrorCode;
+  constructor(code: NodeObservationErrorCode, message: string, options?: ErrorOptions);
+}
+//#endregion
+export { JsonlObservationJournalOptions as _, NodeLifecycleTarget as a, recoverRuntimeObservationJournal as c, JournalRecoveryRecord as d, JournalRecoveryResult as f, JournalDurabilityMode as g, recoverJournal as h, NodeLifecycleOptions as i, RuntimeJournalRecoveryResult as l, JsonlObservationJournalExporter as m, NodeObservationError as n, installNodeObservabilityLifecycle as o, JournalStats as p, NodeObservationErrorCode as r, jsonlObservationExporter as s, NODE_OBSERVATION_ERROR_CODES as t, RuntimeJournalRecord as u };
+//# sourceMappingURL=journal-export-BMfSC4Z6.d.mts.map

package/dist/journal-export-BMfSC4Z6.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-export-BMfSC4Z6.d.mts","names":[],"sources":["../src/journal/types.ts","../src/journal.ts","../src/journal/runtime-frame.ts","../src/journal/runtime-store.ts","../src/journal/runtime-exporter.ts","../src/lifecycle.ts","../src/common/errors.ts"],"mappings":";;;KAAY;UAEK;WACN;WACA;WACA,MAAM;WACN;WACA;WACA;WACA;WACA;WACA,YAAY;WACZ;;;;UCqBM;WACN;WACA;WACA,OAAO;WACP;;UAGM;WACN,kBAAkB;WAClB;WACA;;UAGM;WACN;WACA;WACA;WACA;;;cA8BE,2CAA2C;WAC7C;WACA,8BAA8B;mBACtB;mBAEA;UACT;UACA;mBACS;mBACA;mBACA;UACT;UACA;UACA;UACA;EAER,YAAY,SAAS;EAsBf,SAAS;EAIf,MAAM,OAAO,mBAAmB;EAgC1B,OAAO,OAAO,kBAAkB,QAAQ,cAAc,QAAQ;EAmB9D,iBAAiB,kBAAkB;EAQnC,kBAAkB,8BAA8B;EAkBhD,WAAW,QAAQ;EASnB,WAAW;UAMH;EAqCR,SAAS,QAAQ;EAmBjB,SAAS,SAAS,cAAc;UAYxB;UAQN;UAMM;UASA;UAcN;UAeM;UAOA;UAkBA;UAwBA;;iBAYM,eAAe,oBAAoB,QAAQ;;;KCvYrD;UAEK;WACN;WACA;WACA,MAAM;WACN;WACA;WACA,MAAM;WACN;;;;UCkCM;WACN,kBAAkB;WAClB;WACA;;;;;iBC5BK,yBACd,SAAS,iCACR;;iBAoCmB,iCACpB,kBACC,QAAQ;;;UC5DM;EACf,GAAG,4CAA4C;EAC/C,IAAI,4CAA4C;;UAGjC;WACN,SAAS;WACT;WACA,aAAa;;;iBAIR,kCACd,aAAa,KAAK,4BAClB,UAAS;;;cChBE,8BAA4B;WAC9B;WACL;;KAGM,kCAAkC,0CAA0C;cAE3E,6BAA6B;WACtB;WACT,MAAM;EAEf,YAAY,MAAM,0BAA0B,iBAAiB,UAAU"}