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

package/dist/journal-export-HAdAQxLv.mjs

@@ -0,0 +1,968 @@
+import { a as NodeObservationError, i as NODE_OBSERVATION_ERROR_CODES, n as ensureSafeRoot, r as openExclusiveFile, t as atomicWriteJson } from "./safe-filesystem-CbOPNSoN.mjs";
+import { createHash, randomBytes } from "node:crypto";
+import { chmod, lstat, readFile, readdir, rename, stat, truncate, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { deepFreeze, isSpanId, isTraceId } from "@alvin0/ai-agent-sdk-core";
+import { defineObservationExporter } from "@alvin0/ai-agent-sdk-core/observability";
+
+//#region src/journal/config.ts
+const JOURNAL_DEFAULTS = Object.freeze({
+	maxSegmentBytes: 67108864,
+	maxRetainedBytes: 1073741824,
+	acknowledgedRetentionMs: 6048e5,
+	syncIntervalMs: 100,
+	syncRecordCount: 256
+});
+const JOURNAL_LIMITS = Object.freeze({
+	recoverySegmentBytes: 68157440,
+	cursorBytes: 67108864,
+	identifierCharacters: 64
+});
+const JOURNAL_FILES = Object.freeze({
+	advancedCursor: "cursor.json",
+	runtimeDirectory: "runtime-delivery",
+	runtimeCursor: "cursor.json"
+});
+function positiveSafeInteger(value, field) {
+	if (!Number.isSafeInteger(value) || value < 1) throw new RangeError(`${field} must be a positive safe integer`);
+	return value;
+}
+function safeSegmentId(value) {
+	const normalized = value.replace(/[^A-Za-z0-9_-]/g, "");
+	if (normalized.length < 8 || normalized.length > JOURNAL_LIMITS.identifierCharacters) throw new TypeError("journal segmentId must yield 8-64 safe characters");
+	return normalized;
+}
+
+//#endregion
+//#region src/journal/errors.ts
+function journalFailure(code, message, cause) {
+	return new NodeObservationError(NODE_OBSERVATION_ERROR_CODES[code], message, cause === void 0 ? void 0 : { cause });
+}
+
+//#endregion
+//#region src/journal/frame.ts
+const EVENT_NAMES = /* @__PURE__ */ new Set([
+	"sdk.agent.run",
+	"sdk.agent.turn",
+	"sdk.model.call",
+	"sdk.provider.attempt",
+	"sdk.provider.retry.scheduled",
+	"sdk.tool.call",
+	"sdk.compaction",
+	"sdk.hook.call",
+	"sdk.user.input.wait",
+	"sdk.skill.operation",
+	"sdk.memory.operation",
+	"sdk.credential.operation",
+	"sdk.integration.request",
+	"sdk.observer.failure",
+	"sdk.exporter.state",
+	"sdk.log"
+]);
+function journalChecksum(payloadJson) {
+	return createHash("sha256").update(payloadJson, "utf8").digest("hex");
+}
+function validObservationEvent(value, eventId) {
+	if (typeof value !== "object" || value === null) return false;
+	try {
+		const sequence = Reflect.get(value, "sequence");
+		const monotonicMs = Reflect.get(value, "monotonicMs");
+		const occurredAt = Reflect.get(value, "occurredAt");
+		const resource = Reflect.get(value, "resource");
+		const correlation = Reflect.get(value, "correlation");
+		const name = Reflect.get(value, "name");
+		const optionalCorrelation = [
+			"conversationId",
+			"turnId",
+			"modelCallId",
+			"attemptId",
+			"toolCallId",
+			"providerRequestId",
+			"sessionId"
+		].every((key) => {
+			const field = Reflect.get(correlation, key);
+			return field === void 0 || typeof field === "string" && field.length > 0;
+		});
+		return Reflect.get(value, "schemaVersion") === 1 && Reflect.get(value, "eventId") === eventId && /^[0-9a-f]{32}$/.test(eventId) && !/^0+$/.test(eventId) && Number.isSafeInteger(sequence) && sequence > 0 && EVENT_NAMES.has(name) && [
+			"start",
+			"end",
+			"point"
+		].includes(Reflect.get(value, "phase")) && [
+			"critical",
+			"normal",
+			"verbose"
+		].includes(Reflect.get(value, "priority")) && typeof occurredAt === "string" && !Number.isNaN(Date.parse(occurredAt)) && new Date(occurredAt).toISOString() === occurredAt && typeof monotonicMs === "number" && Number.isFinite(monotonicMs) && monotonicMs >= 0 && typeof resource === "object" && resource !== null && Reflect.get(resource, "sdkName") === "ai-agent-sdk" && typeof Reflect.get(resource, "sdkVersion") === "string" && Reflect.get(resource, "sdkVersion").length > 0 && [
+			"browser",
+			"edge",
+			"node",
+			"unknown"
+		].includes(Reflect.get(resource, "runtime")) && typeof correlation === "object" && correlation !== null && isTraceId(Reflect.get(correlation, "traceId")) && isSpanId(Reflect.get(correlation, "spanId")) && (Reflect.get(correlation, "parentSpanId") === null || isSpanId(Reflect.get(correlation, "parentSpanId"))) && typeof Reflect.get(correlation, "runId") === "string" && Reflect.get(correlation, "runId").length > 0 && optionalCorrelation && typeof Reflect.get(value, "data") === "object" && Reflect.get(value, "data") !== null && !Array.isArray(Reflect.get(value, "data"));
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/journal.ts
+function journalLine(event, payloadJson) {
+	return `${JSON.stringify({
+		schemaVersion: 1,
+		eventId: event.eventId,
+		payloadJson,
+		sha256: journalChecksum(payloadJson)
+	})}\n`;
+}
+function dateDay(value) {
+	return value.toISOString().slice(0, 10);
+}
+/** Append-only Node journal whose local durability is measured with fdatasync. */
+var JsonlObservationJournalExporter = class {
+	id;
+	supportedBoundaries;
+	options;
+	rootPromise;
+	current;
+	writeTail = Promise.resolve();
+	pendingStages = /* @__PURE__ */ new Map();
+	batchEvents = /* @__PURE__ */ new Map();
+	acknowledged = /* @__PURE__ */ new Set();
+	syncTimer;
+	unsyncedRecords = 0;
+	unsyncedCritical = 0;
+	closing = false;
+	constructor(options) {
+		if (typeof options !== "object" || options === null) throw new TypeError("journal options are required");
+		if (![
+			"operational",
+			"reliable",
+			"audit"
+		].includes(options.mode)) throw new TypeError("journal mode is invalid");
+		this.id = options.id ?? "journal";
+		if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,63})$/.test(this.id)) throw new TypeError("journal id is invalid");
+		this.supportedBoundaries = Object.freeze(options.mode === "operational" ? ["none"] : ["local-durable"]);
+		this.options = {
+			mode: options.mode,
+			maxSegmentBytes: positiveSafeInteger(options.maxSegmentBytes ?? JOURNAL_DEFAULTS.maxSegmentBytes, "maxSegmentBytes"),
+			maxRetainedBytes: positiveSafeInteger(options.maxRetainedBytes ?? JOURNAL_DEFAULTS.maxRetainedBytes, "maxRetainedBytes"),
+			acknowledgedRetentionMs: positiveSafeInteger(options.acknowledgedRetentionMs ?? JOURNAL_DEFAULTS.acknowledgedRetentionMs, "acknowledgedRetentionMs"),
+			syncIntervalMs: positiveSafeInteger(options.syncIntervalMs ?? JOURNAL_DEFAULTS.syncIntervalMs, "syncIntervalMs"),
+			syncRecordCount: positiveSafeInteger(options.syncRecordCount ?? JOURNAL_DEFAULTS.syncRecordCount, "syncRecordCount"),
+			now: options.now ?? (() => /* @__PURE__ */ new Date()),
+			segmentId: options.segmentId ?? (() => randomBytes(12).toString("hex"))
+		};
+		this.rootPromise = this.initialize(options.rootDir);
+		this.rootPromise.catch(() => void 0);
+	}
+	async ready() {
+		await this.rootPromise;
+	}
+	stage(event) {
+		if (this.closing) throw journalFailure("io", "observation journal is closed");
+		const payloadJson = JSON.stringify(event);
+		const existing = this.pendingStages.get(event.eventId);
+		if (existing !== void 0) {
+			if (existing.payloadJson !== payloadJson) throw journalFailure("corrupt", "duplicate journal eventId has different data");
+			return existing.promise;
+		}
+		const promise = this.enqueueWrite(async () => {
+			const root = await this.rootPromise;
+			const line = journalLine(event, payloadJson);
+			const lineBytes = Buffer.byteLength(line);
+			if (lineBytes > JOURNAL_LIMITS.recoverySegmentBytes) throw journalFailure("io", "journal record exceeds the recovery bound");
+			await this.ensureCapacity(root, lineBytes, event.priority);
+			await this.rotateIfNeeded(root, lineBytes);
+			const segment = this.current;
+			if (segment === void 0) throw journalFailure("io", "journal segment was not opened");
+			await segment.handle.writeFile(line, "utf8");
+			segment.bytes += lineBytes;
+			segment.eventIds.push(event.eventId);
+			this.unsyncedRecords++;
+			if (event.priority === "critical") this.unsyncedCritical++;
+			if (this.options.mode === "audit") await this.syncCurrent();
+			else if (this.options.mode === "reliable") this.scheduleReliableSync();
+		});
+		this.pendingStages.set(event.eventId, {
+			payloadJson,
+			promise
+		});
+		promise.catch(() => void 0);
+		return promise;
+	}
+	async export(batch, signal) {
+		if (signal.aborted) throw signal.reason ?? /* @__PURE__ */ new Error("journal export aborted");
+		const existingBatch = this.batchEvents.get(batch.batchId);
+		if (existingBatch !== void 0) {
+			const eventIds = batch.events.map((event) => event.eventId);
+			if (eventIds.length !== existingBatch.length || eventIds.some((eventId, index) => eventId !== existingBatch[index])) throw journalFailure("corrupt", "duplicate journal batchId has different events");
+			return deepFreeze({
+				batchId: batch.batchId,
+				accepted: true,
+				retryable: false
+			});
+		}
+		await Promise.all(batch.events.map((event) => this.stage(event)));
+		if (signal.aborted) throw signal.reason ?? /* @__PURE__ */ new Error("journal export aborted");
+		if (this.options.mode !== "operational") await this.enqueueWrite(async () => {
+			await this.syncCurrent();
+		});
+		this.batchEvents.set(batch.batchId, Object.freeze(batch.events.map((event) => event.eventId)));
+		for (const event of batch.events) this.pendingStages.delete(event.eventId);
+		return deepFreeze({
+			batchId: batch.batchId,
+			accepted: true,
+			retryable: false
+		});
+	}
+	async acknowledgeBatch(batchId) {
+		const eventIds = this.batchEvents.get(batchId);
+		if (eventIds === void 0) return 0;
+		await this.acknowledgeEvents(eventIds);
+		this.batchEvents.delete(batchId);
+		return eventIds.length;
+	}
+	async acknowledgeEvents(eventIds) {
+		if (!Array.isArray(eventIds) || eventIds.some((eventId) => typeof eventId !== "string" || !/^[0-9a-f]{32}$/.test(eventId) || /^0+$/.test(eventId))) throw new TypeError("journal acknowledgments require valid event IDs");
+		await this.enqueueWrite(async () => {
+			const root = await this.rootPromise;
+			const previous = new Set(this.acknowledged);
+			for (const eventId of eventIds) this.acknowledged.add(eventId);
+			try {
+				await this.persistCursor(root);
+			} catch (error) {
+				this.acknowledged.clear();
+				for (const eventId of previous) this.acknowledged.add(eventId);
+				throw error;
+			}
+			await this.cleanupNow(root);
+		});
+	}
+	async recover() {
+		let result;
+		await this.enqueueWrite(async () => {
+			result = await recoverJournal(await this.rootPromise);
+		});
+		if (result === void 0) throw journalFailure("io", "journal recovery did not complete");
+		return result;
+	}
+	async cleanup() {
+		await this.enqueueWrite(async () => {
+			await this.cleanupNow(await this.rootPromise);
+		});
+	}
+	async cleanupNow(root) {
+		const recovered = await recoverJournal(root);
+		const bySegment = /* @__PURE__ */ new Map();
+		for (const record of recovered.records) {
+			const records = bySegment.get(record.segment) ?? [];
+			records.push(record);
+			bySegment.set(record.segment, records);
+		}
+		const now = this.options.now().getTime();
+		const candidates = [];
+		for (const [name, records] of bySegment) {
+			if (name === this.current?.name) continue;
+			const info = await stat(join(root, name));
+			candidates.push({
+				name,
+				bytes: info.size,
+				mtimeMs: info.mtimeMs,
+				acknowledged: records.every((record) => this.acknowledged.has(record.event.eventId))
+			});
+		}
+		let retained = candidates.reduce((sum, item) => sum + item.bytes, this.current?.bytes ?? 0);
+		const deletedAcknowledged = /* @__PURE__ */ new Set();
+		for (const candidate of candidates.sort((left, right) => left.mtimeMs - right.mtimeMs)) {
+			if (!candidate.acknowledged) continue;
+			if (now - candidate.mtimeMs < this.options.acknowledgedRetentionMs && retained <= this.options.maxRetainedBytes) continue;
+			await unlink(join(root, candidate.name));
+			retained -= candidate.bytes;
+			for (const record of bySegment.get(candidate.name) ?? []) deletedAcknowledged.add(record.event.eventId);
+		}
+		if (deletedAcknowledged.size > 0) {
+			for (const eventId of deletedAcknowledged) this.acknowledged.delete(eventId);
+			await this.persistCursor(root);
+		}
+		if (retained > this.options.maxRetainedBytes) throw journalFailure("io", "journal retention cap contains unacknowledged records");
+	}
+	async stats() {
+		let result;
+		await this.enqueueWrite(async () => {
+			const root = await this.rootPromise;
+			const files = (await readdir(root)).filter((name) => name.endsWith(".jsonl"));
+			let retainedBytes = 0;
+			for (const name of files) retainedBytes += (await stat(join(root, name))).size;
+			const recovered = await recoverJournal(root);
+			result = deepFreeze({
+				segmentCount: files.length,
+				retainedBytes,
+				unacknowledgedEvents: recovered.records.filter((record) => !this.acknowledged.has(record.event.eventId)).length,
+				...this.current === void 0 ? {} : { currentSegment: this.current.name }
+			});
+		});
+		if (result === void 0) throw journalFailure("io", "journal stats did not complete");
+		return result;
+	}
+	async shutdown(_signal) {
+		if (this.closing) return;
+		this.closing = true;
+		if (this.syncTimer !== void 0) clearTimeout(this.syncTimer);
+		await Promise.allSettled([...this.pendingStages.values()].map((stage) => stage.promise));
+		await this.enqueueWrite(async () => {
+			await this.syncCurrent();
+			await this.current?.handle.close();
+			this.current = void 0;
+		});
+	}
+	async initialize(rootInput) {
+		const root = await ensureSafeRoot(rootInput);
+		await this.loadCursor(root);
+		await recoverJournal(root);
+		await this.openSegment(root);
+		return root;
+	}
+	enqueueWrite(operation) {
+		const result = this.writeTail.then(operation);
+		this.writeTail = result.catch(() => void 0);
+		return result;
+	}
+	async openSegment(root) {
+		const day = dateDay(this.options.now());
+		const id = safeSegmentId(this.options.segmentId());
+		const name = `${day}-${process.pid}-${id}.jsonl`;
+		const handle = await openExclusiveFile(root, name);
+		this.current = {
+			name,
+			day,
+			handle,
+			bytes: 0,
+			eventIds: []
+		};
+	}
+	async rotateIfNeeded(root, incomingBytes) {
+		const current = this.current;
+		if (current === void 0) {
+			await this.openSegment(root);
+			return;
+		}
+		const day = dateDay(this.options.now());
+		if (current.day === day && (current.bytes === 0 || current.bytes + incomingBytes <= this.options.maxSegmentBytes)) return;
+		await this.syncCurrent();
+		await current.handle.close();
+		this.current = void 0;
+		await this.openSegment(root);
+	}
+	scheduleReliableSync() {
+		if (this.unsyncedCritical >= this.options.syncRecordCount) {
+			if (this.syncTimer !== void 0) clearTimeout(this.syncTimer);
+			this.syncTimer = void 0;
+			this.enqueueWrite(async () => {
+				await this.syncCurrent();
+			}).catch(() => void 0);
+			return;
+		}
+		if (this.syncTimer !== void 0) return;
+		this.syncTimer = setTimeout(() => {
+			this.syncTimer = void 0;
+			this.enqueueWrite(async () => {
+				await this.syncCurrent();
+			}).catch(() => void 0);
+		}, this.options.syncIntervalMs);
+		this.syncTimer.unref?.();
+	}
+	async syncCurrent() {
+		if (this.current === void 0 || this.unsyncedRecords === 0) return;
+		await this.current.handle.datasync();
+		this.unsyncedRecords = 0;
+		this.unsyncedCritical = 0;
+	}
+	async ensureCapacity(root, incomingBytes, priority) {
+		const files = (await readdir(root)).filter((name) => name.endsWith(".jsonl"));
+		let total = 0;
+		for (const name of files) total += (await stat(join(root, name))).size;
+		if (total + incomingBytes <= this.options.maxRetainedBytes) return;
+		await this.cleanupNow(root);
+		total = 0;
+		for (const name of files) {
+			const path = join(root, name);
+			total += await stat(path).then((value) => value.size, () => 0);
+		}
+		if (total + incomingBytes > this.options.maxRetainedBytes) throw journalFailure("io", priority === "critical" ? "journal capacity contains unacknowledged critical records" : "journal capacity is exhausted");
+	}
+	async loadCursor(root) {
+		let raw;
+		try {
+			const path = join(root, JOURNAL_FILES.advancedCursor);
+			const info = await lstat(path);
+			if (!info.isFile() || info.isSymbolicLink() || info.size > JOURNAL_LIMITS.cursorBytes) throw new Error("unsafe cursor");
+			raw = await readFile(path, "utf8");
+		} catch (error) {
+			if (typeof error === "object" && error !== null && Reflect.get(error, "code") === "ENOENT") return;
+			throw journalFailure("io", "journal cursor read failed", error);
+		}
+		try {
+			const value = JSON.parse(raw);
+			if (value.schemaVersion !== 1 || !Array.isArray(value.acknowledgedEventIds) || value.acknowledgedEventIds.some((id) => typeof id !== "string" || !/^[0-9a-f]{32}$/.test(id))) throw new Error("invalid cursor");
+			for (const id of value.acknowledgedEventIds) this.acknowledged.add(id);
+		} catch (error) {
+			throw journalFailure("corrupt", "journal cursor is corrupt", error);
+		}
+	}
+	async persistCursor(root) {
+		const value = {
+			schemaVersion: 1,
+			acknowledgedEventIds: [...this.acknowledged].sort()
+		};
+		if (Buffer.byteLength(JSON.stringify(value)) > JOURNAL_LIMITS.cursorBytes) throw journalFailure("io", "journal cursor exceeds its persistence bound");
+		await atomicWriteJson(root, JOURNAL_FILES.advancedCursor, value);
+	}
+};
+async function recoverJournal(rootInput) {
+	const root = await ensureSafeRoot(rootInput);
+	const names = (await readdir(root)).filter((name) => name.endsWith(".jsonl")).sort();
+	const records = [];
+	const quarantinedSegments = [];
+	const truncatedSegments = [];
+	const eventIds = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		const path = join(root, name);
+		const info = await lstat(path);
+		if (!info.isFile() || info.isSymbolicLink()) throw journalFailure("io", "journal segment is not a regular file");
+		if (info.size > JOURNAL_LIMITS.recoverySegmentBytes) throw journalFailure("corrupt", "journal segment exceeds recovery bound");
+		await chmod(path, 384);
+		let text = await readFile(path, "utf8");
+		if (text.length > 0 && !text.endsWith("\n")) {
+			const boundary = text.lastIndexOf("\n") + 1;
+			await truncate(path, Buffer.byteLength(text.slice(0, boundary)));
+			text = text.slice(0, boundary);
+			truncatedSegments.push(name);
+		}
+		const lines = text.length === 0 ? [] : text.slice(0, -1).split("\n");
+		const segmentEventIds = [];
+		for (let index = 0; index < lines.length; index++) {
+			const line = lines[index] ?? "";
+			try {
+				const envelope = JSON.parse(line);
+				if (envelope.schemaVersion !== 1 || typeof envelope.eventId !== "string" || typeof envelope.payloadJson !== "string" || typeof envelope.sha256 !== "string" || envelope.sha256 !== journalChecksum(envelope.payloadJson)) throw new Error("invalid frame");
+				const event = JSON.parse(envelope.payloadJson);
+				if (!validObservationEvent(event, envelope.eventId) || eventIds.has(envelope.eventId)) throw new Error("invalid event");
+				eventIds.add(envelope.eventId);
+				segmentEventIds.push(envelope.eventId);
+				records.push(deepFreeze({
+					segment: name,
+					line: index + 1,
+					event,
+					payloadJson: envelope.payloadJson
+				}));
+			} catch (error) {
+				if (index === lines.length - 1) {
+					const quarantine = `${name}.corrupt-${Date.now()}`;
+					await rename(path, join(root, quarantine));
+					quarantinedSegments.push(quarantine);
+					for (let recordIndex = records.length - 1; recordIndex >= 0; recordIndex--) if (records[recordIndex]?.segment === name) records.splice(recordIndex, 1);
+					for (const eventId of segmentEventIds) eventIds.delete(eventId);
+					break;
+				}
+				throw journalFailure("corrupt", `journal segment ${name} has mid-file corruption`, error);
+			}
+		}
+	}
+	return deepFreeze({
+		records,
+		quarantinedSegments,
+		truncatedSegments
+	});
+}
+
+//#endregion
+//#region src/journal/runtime-options.ts
+function captureRuntimeJournalOptions(options) {
+	if (typeof options !== "object" || options === null) throw new TypeError("journal options are required");
+	if (![
+		"operational",
+		"reliable",
+		"audit"
+	].includes(options.mode)) throw new TypeError("journal mode is invalid");
+	const id = options.id ?? "journal";
+	if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,63})$/.test(id)) throw new TypeError("journal id is invalid");
+	if (typeof options.rootDir !== "string" || options.rootDir.trim().length === 0) throw new TypeError("observation journal rootDir must be explicit and non-empty");
+	if (options.now !== void 0 && typeof options.now !== "function") throw new TypeError("journal now must be a function");
+	if (options.segmentId !== void 0 && typeof options.segmentId !== "function") throw new TypeError("journal segmentId must be a function");
+	const supportedBoundaries = Object.freeze(options.mode === "operational" ? ["none"] : ["local-durable"]);
+	return Object.freeze({
+		id,
+		rootDir: options.rootDir,
+		mode: options.mode,
+		maxSegmentBytes: positiveSafeInteger(options.maxSegmentBytes ?? JOURNAL_DEFAULTS.maxSegmentBytes, "maxSegmentBytes"),
+		maxRetainedBytes: positiveSafeInteger(options.maxRetainedBytes ?? JOURNAL_DEFAULTS.maxRetainedBytes, "maxRetainedBytes"),
+		acknowledgedRetentionMs: positiveSafeInteger(options.acknowledgedRetentionMs ?? JOURNAL_DEFAULTS.acknowledgedRetentionMs, "acknowledgedRetentionMs"),
+		syncIntervalMs: positiveSafeInteger(options.syncIntervalMs ?? JOURNAL_DEFAULTS.syncIntervalMs, "syncIntervalMs"),
+		syncRecordCount: positiveSafeInteger(options.syncRecordCount ?? JOURNAL_DEFAULTS.syncRecordCount, "syncRecordCount"),
+		now: options.now ?? (() => /* @__PURE__ */ new Date()),
+		segmentId: options.segmentId ?? (() => randomBytes(12).toString("hex")),
+		supportedBoundaries
+	});
+}
+
+//#endregion
+//#region src/journal/runtime-frame.ts
+function runtimeItemIdentity(item) {
+	const kind = "kind" in item && item.kind === "run-terminal-record" ? "run-terminal-record" : "event";
+	const id = kind === "event" ? item.eventId : item.runId;
+	return {
+		kind,
+		id,
+		key: `${kind}:${id}`
+	};
+}
+function runtimeJournalLine(item, payloadJson) {
+	const identity = runtimeItemIdentity(item);
+	return `${JSON.stringify({
+		schemaVersion: 1,
+		itemKind: identity.kind,
+		itemId: identity.id,
+		payloadJson,
+		sha256: journalChecksum(payloadJson)
+	})}\n`;
+}
+function parseRuntimeJournalLine(line, segment, lineNumber) {
+	const envelope = JSON.parse(line);
+	if (envelope.schemaVersion !== 1 || envelope.itemKind !== "event" && envelope.itemKind !== "run-terminal-record" || typeof envelope.itemId !== "string" || typeof envelope.payloadJson !== "string" || typeof envelope.sha256 !== "string" || envelope.sha256 !== journalChecksum(envelope.payloadJson)) throw new Error("invalid frame");
+	const parsed = JSON.parse(envelope.payloadJson);
+	let item;
+	if (envelope.itemKind === "event") {
+		if (!validObservationEvent(parsed, envelope.itemId)) throw new Error("invalid journal item");
+		item = parsed;
+	} else {
+		if (!validTerminalRecord(parsed, envelope.itemId)) throw new Error("invalid journal item");
+		item = parsed;
+	}
+	return {
+		segment,
+		line: lineNumber,
+		kind: envelope.itemKind,
+		id: envelope.itemId,
+		key: `${envelope.itemKind}:${envelope.itemId}`,
+		item,
+		payloadJson: envelope.payloadJson
+	};
+}
+function validTerminalRecord(value, runId) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	try {
+		const startedAt = Reflect.get(value, "startedAt");
+		const endedAt = Reflect.get(value, "endedAt");
+		const durationMs = Reflect.get(value, "durationMs");
+		return Reflect.get(value, "kind") === "run-terminal-record" && Reflect.get(value, "runId") === runId && runId.length > 0 && runId.length <= 128 && isTraceId(Reflect.get(value, "traceId")) && validIsoDate(startedAt) && validIsoDate(endedAt) && typeof durationMs === "number" && Number.isFinite(durationMs) && durationMs >= 0 && [
+			"success",
+			"error",
+			"aborted",
+			"rejected",
+			"unknown"
+		].includes(Reflect.get(value, "status")) && objectRecord(Reflect.get(value, "usage")) && Array.isArray(Reflect.get(value, "modelCalls")) && Array.isArray(Reflect.get(value, "toolSourceSnapshots")) && objectRecord(Reflect.get(value, "operationCounts")) && Array.isArray(Reflect.get(value, "errors")) && !Object.prototype.hasOwnProperty.call(value, "delivery");
+	} catch {
+		return false;
+	}
+}
+function validIsoDate(value) {
+	return typeof value === "string" && !Number.isNaN(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+function objectRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+//#endregion
+//#region src/journal/runtime-store.ts
+var RuntimeJsonlJournal = class {
+	options;
+	root;
+	current;
+	writeTail = Promise.resolve();
+	payloads = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	batches = /* @__PURE__ */ new Map();
+	accepted = /* @__PURE__ */ new Set();
+	syncTimer;
+	unsyncedRecords = 0;
+	unsyncedCritical = 0;
+	failed;
+	closing = false;
+	constructor(options) {
+		this.options = options;
+	}
+	async ready(signal) {
+		abortIfRequested(signal);
+		if (this.root !== void 0) return;
+		const parent = await ensureSafeRoot(this.options.rootDir);
+		abortIfRequested(signal);
+		const root = await ensureSafeRoot(join(parent, JOURNAL_FILES.runtimeDirectory));
+		abortIfRequested(signal);
+		await this.loadCursor(root);
+		const recovered = await recoverRuntimeJournal(root);
+		for (const record of recovered.records) {
+			const previous = this.payloads.get(record.key);
+			if (previous !== void 0 && previous !== record.payloadJson) throw journalFailure("corrupt", "duplicate runtime journal item has different data");
+			this.payloads.set(record.key, record.payloadJson);
+		}
+		for (const key of [...this.accepted]) if (!this.payloads.has(key)) this.accepted.delete(key);
+		abortIfRequested(signal);
+		await this.openSegment(root);
+		if (signal.aborted) {
+			await this.current?.handle.close().catch(() => void 0);
+			this.current = void 0;
+			abortIfRequested(signal);
+		}
+		this.root = root;
+	}
+	stage(item) {
+		this.ensureAvailable();
+		const identity = runtimeItemIdentity(item);
+		const payloadJson = JSON.stringify(item);
+		const persisted = this.payloads.get(identity.key);
+		if (persisted !== void 0) {
+			if (persisted !== payloadJson) throw journalFailure("corrupt", "duplicate runtime journal item has different data");
+			return Promise.resolve();
+		}
+		const existing = this.pending.get(identity.key);
+		if (existing !== void 0) {
+			if (existing.payloadJson !== payloadJson) throw journalFailure("corrupt", "duplicate runtime journal item has different data");
+			return existing.promise;
+		}
+		const promise = this.enqueue(async () => {
+			const root = this.requiredRoot();
+			const line = runtimeJournalLine(item, payloadJson);
+			const lineBytes = Buffer.byteLength(line);
+			if (lineBytes > JOURNAL_LIMITS.recoverySegmentBytes) throw journalFailure("io", "runtime journal record exceeds the recovery bound");
+			const priority = identity.kind === "run-terminal-record" ? "critical" : item.priority;
+			await this.ensureCapacity(root, lineBytes, priority);
+			await this.rotateIfNeeded(root, lineBytes);
+			if (this.current === void 0) throw journalFailure("io", "runtime journal segment was not opened");
+			await this.current.handle.writeFile(line, "utf8");
+			this.current.bytes += lineBytes;
+			this.payloads.set(identity.key, payloadJson);
+			this.unsyncedRecords++;
+			if (priority === "critical") this.unsyncedCritical++;
+			if (this.options.mode === "audit") await this.syncCurrent();
+			else if (this.options.mode === "reliable") this.scheduleReliableSync();
+		});
+		this.pending.set(identity.key, {
+			payloadJson,
+			promise
+		});
+		promise.then(() => {
+			this.pending.delete(identity.key);
+		}, (error) => {
+			this.failed = error;
+		});
+		return promise;
+	}
+	async export(batch, signal) {
+		this.ensureAvailable();
+		abortIfRequested(signal);
+		const items = [...batch.events, ...batch.runRecords];
+		const keys = items.map((item) => runtimeItemIdentity(item).key);
+		const previous = this.batches.get(batch.id);
+		if (previous !== void 0) {
+			if (!sameList(previous, keys)) throw journalFailure("corrupt", "duplicate runtime journal batch has different items");
+			return deliveryAck(batch);
+		}
+		await Promise.all(items.map((item) => this.stage(item)));
+		abortIfRequested(signal);
+		await this.enqueue(async () => {
+			await this.syncCurrent();
+			const before = new Set(this.accepted);
+			for (const key of keys) this.accepted.add(key);
+			try {
+				await this.persistCursor(this.requiredRoot());
+				await this.cleanupNow(this.requiredRoot());
+			} catch (error) {
+				this.accepted.clear();
+				for (const key of before) this.accepted.add(key);
+				throw error;
+			}
+		});
+		abortIfRequested(signal);
+		this.batches.set(batch.id, Object.freeze(keys));
+		return deliveryAck(batch);
+	}
+	async shutdown(signal) {
+		if (this.closing) return;
+		this.closing = true;
+		if (this.syncTimer !== void 0) clearTimeout(this.syncTimer);
+		await Promise.allSettled([...this.pending.values()].map((value) => value.promise));
+		abortIfRequested(signal);
+		await this.enqueue(async () => {
+			await this.syncCurrent();
+			await this.current?.handle.close();
+			this.current = void 0;
+		});
+	}
+	ensureAvailable() {
+		if (this.root === void 0) throw journalFailure("io", "runtime observation journal is not ready");
+		if (this.closing) throw journalFailure("io", "runtime observation journal is closed");
+		if (this.failed !== void 0) throw journalFailure("io", "runtime observation journal has failed", this.failed);
+	}
+	requiredRoot() {
+		if (this.root === void 0) throw journalFailure("io", "runtime observation journal is not ready");
+		return this.root;
+	}
+	enqueue(operation) {
+		const result = this.writeTail.then(operation);
+		this.writeTail = result.catch(() => void 0);
+		return result;
+	}
+	async openSegment(root) {
+		const day = validNow(this.options.now()).toISOString().slice(0, 10);
+		const id = safeSegmentId(this.options.segmentId());
+		const name = `${day}-${process.pid}-${id}-${randomBytes(4).toString("hex")}.jsonl`;
+		this.current = {
+			name,
+			day,
+			handle: await openExclusiveFile(root, name),
+			bytes: 0
+		};
+	}
+	async rotateIfNeeded(root, incomingBytes) {
+		const current = this.current;
+		if (current === void 0) return this.openSegment(root);
+		const day = validNow(this.options.now()).toISOString().slice(0, 10);
+		if (current.day === day && (current.bytes === 0 || current.bytes + incomingBytes <= this.options.maxSegmentBytes)) return;
+		await this.syncCurrent();
+		await current.handle.close();
+		this.current = void 0;
+		await this.openSegment(root);
+	}
+	scheduleReliableSync() {
+		if (this.unsyncedCritical >= this.options.syncRecordCount) {
+			if (this.syncTimer !== void 0) clearTimeout(this.syncTimer);
+			this.syncTimer = void 0;
+			this.enqueue(() => this.syncCurrent()).catch((error) => {
+				this.failed = error;
+			});
+			return;
+		}
+		if (this.syncTimer !== void 0) return;
+		this.syncTimer = setTimeout(() => {
+			this.syncTimer = void 0;
+			this.enqueue(() => this.syncCurrent()).catch((error) => {
+				this.failed = error;
+			});
+		}, this.options.syncIntervalMs);
+		this.syncTimer.unref?.();
+	}
+	async syncCurrent() {
+		if (this.current === void 0 || this.unsyncedRecords === 0) return;
+		await this.current.handle.datasync();
+		this.unsyncedRecords = 0;
+		this.unsyncedCritical = 0;
+	}
+	async ensureCapacity(root, incomingBytes, priority) {
+		let total = await retainedBytes(root);
+		if (total + incomingBytes <= this.options.maxRetainedBytes) return;
+		await this.cleanupNow(root);
+		total = await retainedBytes(root);
+		if (total + incomingBytes > this.options.maxRetainedBytes) throw journalFailure("io", priority === "critical" ? "runtime journal capacity contains unacknowledged critical records" : "runtime journal capacity is exhausted");
+	}
+	async cleanupNow(root) {
+		const recovered = await recoverRuntimeJournal(root);
+		const bySegment = /* @__PURE__ */ new Map();
+		for (const record of recovered.records) {
+			const records = bySegment.get(record.segment) ?? [];
+			records.push(record);
+			bySegment.set(record.segment, records);
+		}
+		const candidates = [];
+		for (const [name, records] of bySegment) {
+			if (name === this.current?.name) continue;
+			const info = await stat(join(root, name));
+			candidates.push({
+				name,
+				bytes: info.size,
+				mtimeMs: info.mtimeMs,
+				accepted: records.every((record) => this.accepted.has(record.key))
+			});
+		}
+		let retained = candidates.reduce((sum, value) => sum + value.bytes, this.current?.bytes ?? 0);
+		let cursorChanged = false;
+		const now = validNow(this.options.now()).getTime();
+		for (const candidate of candidates.sort((left, right) => left.mtimeMs - right.mtimeMs)) {
+			if (!candidate.accepted) continue;
+			if (now - candidate.mtimeMs < this.options.acknowledgedRetentionMs && retained <= this.options.maxRetainedBytes) continue;
+			await unlink(join(root, candidate.name));
+			retained -= candidate.bytes;
+			for (const record of bySegment.get(candidate.name) ?? []) {
+				this.payloads.delete(record.key);
+				if (this.accepted.delete(record.key)) cursorChanged = true;
+			}
+		}
+		if (cursorChanged) await this.persistCursor(root);
+		if (retained > this.options.maxRetainedBytes) throw journalFailure("io", "runtime journal retention cap contains unacknowledged records");
+	}
+	async loadCursor(root) {
+		try {
+			const path = join(root, JOURNAL_FILES.runtimeCursor);
+			const info = await lstat(path);
+			if (!info.isFile() || info.isSymbolicLink() || info.size > JOURNAL_LIMITS.cursorBytes) throw new Error("unsafe cursor");
+			const parsed = JSON.parse(await readFile(path, "utf8"));
+			if (parsed.schemaVersion !== 1 || !Array.isArray(parsed.acceptedItemKeys) || parsed.acceptedItemKeys.some((key) => typeof key !== "string" || key.length === 0 || key.length > 256)) throw new Error("invalid cursor");
+			for (const key of parsed.acceptedItemKeys) this.accepted.add(key);
+		} catch (error) {
+			if (typeof error === "object" && error !== null && Reflect.get(error, "code") === "ENOENT") return;
+			throw journalFailure("corrupt", "runtime journal cursor is corrupt", error);
+		}
+	}
+	async persistCursor(root) {
+		const value = {
+			schemaVersion: 1,
+			acceptedItemKeys: [...this.accepted].sort()
+		};
+		if (Buffer.byteLength(JSON.stringify(value)) > JOURNAL_LIMITS.cursorBytes) throw journalFailure("io", "runtime journal cursor exceeds its persistence bound");
+		await atomicWriteJson(root, JOURNAL_FILES.runtimeCursor, value);
+	}
+};
+async function recoverRuntimeJournal(root) {
+	const names = (await readdir(root)).filter((name) => name.endsWith(".jsonl")).sort();
+	const records = [];
+	const payloads = /* @__PURE__ */ new Map();
+	const truncatedSegments = [];
+	const quarantinedSegments = [];
+	for (const name of names) {
+		const path = join(root, name);
+		const info = await lstat(path);
+		if (!info.isFile() || info.isSymbolicLink()) throw journalFailure("io", "runtime journal segment is not a regular file");
+		if (info.size > JOURNAL_LIMITS.recoverySegmentBytes) throw journalFailure("corrupt", "runtime journal segment exceeds recovery bound");
+		await chmod(path, 384);
+		let text = await readFile(path, "utf8");
+		if (text.length > 0 && !text.endsWith("\n")) {
+			const boundary = text.lastIndexOf("\n") + 1;
+			await truncate(path, Buffer.byteLength(text.slice(0, boundary)));
+			text = text.slice(0, boundary);
+			truncatedSegments.push(name);
+		}
+		const lines = text.length === 0 ? [] : text.slice(0, -1).split("\n");
+		const segmentRecords = [];
+		for (let index = 0; index < lines.length; index++) try {
+			const record = parseRuntimeJournalLine(lines[index] ?? "", name, index + 1);
+			const previous = payloads.get(record.key);
+			if (previous !== void 0 && previous !== record.payloadJson) throw new Error("conflicting duplicate item");
+			segmentRecords.push(record);
+		} catch (error) {
+			if (index !== lines.length - 1) throw journalFailure("corrupt", `runtime journal segment ${name} has mid-file corruption`, error);
+			const quarantine = `${name}.corrupt-${Date.now()}`;
+			await rename(path, join(root, quarantine));
+			quarantinedSegments.push(quarantine);
+			segmentRecords.length = 0;
+			break;
+		}
+		for (const record of segmentRecords) {
+			payloads.set(record.key, record.payloadJson);
+			records.push(record);
+		}
+	}
+	return deepFreeze({
+		records,
+		truncatedSegments,
+		quarantinedSegments
+	});
+}
+function deliveryAck(batch) {
+	return deepFreeze({
+		batchId: batch.id,
+		acceptedEventIds: batch.events.map((event) => event.eventId),
+		acceptedRunIds: batch.runRecords.map((record) => record.runId)
+	});
+}
+function abortIfRequested(signal) {
+	if (signal.aborted) throw signal.reason ?? /* @__PURE__ */ new Error("runtime observation journal aborted");
+}
+function sameList(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function validNow(value) {
+	if (!(value instanceof Date) || Number.isNaN(value.getTime())) throw new TypeError("journal now must return a valid Date");
+	return value;
+}
+async function retainedBytes(root) {
+	const names = (await readdir(root)).filter((name) => name.endsWith(".jsonl"));
+	let total = 0;
+	for (const name of names) total += await stat(join(root, name)).then((value) => value.size, () => 0);
+	return total;
+}
+
+//#endregion
+//#region src/journal/runtime-exporter.ts
+/** Recommended runtime adapter. The advanced marker-free journal remains independent. */
+function jsonlObservationExporter(options) {
+	const captured = captureRuntimeJournalOptions(options);
+	let journal;
+	let readiness;
+	const ready = (signal) => {
+		if (readiness !== void 0) return readiness;
+		const created = new RuntimeJsonlJournal(captured);
+		journal = created;
+		readiness = created.ready(signal);
+		readiness.catch(() => void 0);
+		return readiness;
+	};
+	const requiredJournal = () => {
+		if (journal === void 0) throw journalFailure("io", "runtime observation exporter is not ready");
+		return journal;
+	};
+	return defineObservationExporter({
+		id: captured.id,
+		supportedBoundaries: captured.supportedBoundaries,
+		ready,
+		stage(item) {
+			return requiredJournal().stage(item);
+		},
+		export(batch, signal) {
+			return requiredJournal().export(batch, signal);
+		},
+		async shutdown(signal) {
+			if (journal === void 0) return;
+			await readiness?.catch(() => void 0);
+			await journal.shutdown(signal);
+		}
+	});
+}
+/** Verify and recover records written by the recommended runtime exporter. */
+async function recoverRuntimeObservationJournal(rootDir) {
+	const parent = await ensureSafeRoot(rootDir);
+	const root = await ensureSafeRoot(join(parent, JOURNAL_FILES.runtimeDirectory));
+	return recoverRuntimeJournal(root);
+}
+
+//#endregion
+//#region src/lifecycle.ts
+/** Install opt-in Node shutdown triggers and return an idempotent disposer. */
+function installNodeObservabilityLifecycle(observation, options = {}) {
+	if (typeof observation?.shutdown !== "function") throw new TypeError("Node lifecycle requires observability.shutdown");
+	const target = options.target ?? process;
+	const events = Object.freeze(["beforeExit", ...options.signals ?? []]);
+	let disposed = false;
+	let pending;
+	const shutdown = () => {
+		if (disposed || pending !== void 0) return;
+		try {
+			pending = observation.shutdown();
+			pending.catch((error) => {
+				try {
+					options.onFailure?.(error);
+				} catch {}
+			});
+		} catch (error) {
+			try {
+				options.onFailure?.(error);
+			} catch {}
+		}
+	};
+	for (const event of events) target.on(event, shutdown);
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		for (const event of events) target.off(event, shutdown);
+	};
+}
+
+//#endregion
+export { recoverJournal as a, JsonlObservationJournalExporter as i, jsonlObservationExporter as n, recoverRuntimeObservationJournal as r, installNodeObservabilityLifecycle as t };
+//# sourceMappingURL=journal-export-HAdAQxLv.mjs.map