@graphorin/observability 0.5.0

package/dist/eval/types.d.ts

@@ -0,0 +1,108 @@
+//#region src/eval/types.d.ts
+/**
+ * Public types for the minimal inline eval runner. Full orchestrator,
+ * scorer libraries, dataset loaders, and reporters live in the
+ * separate `@graphorin/evals` package (post-MVP).
+ *
+ * @packageDocumentation
+ */
+/**
+ * One sample from an eval dataset.
+ *
+ * @stable
+ */
+interface Case<I, O = unknown, M = Readonly<Record<string, unknown>>> {
+  readonly id?: string;
+  readonly input: I;
+  readonly expected?: O;
+  readonly metadata?: M;
+}
+/**
+ * @stable
+ */
+interface Dataset<I, O = unknown, M = Readonly<Record<string, unknown>>> {
+  readonly cases: ReadonlyArray<Case<I, O, M>>;
+  readonly metadata?: {
+    readonly name?: string;
+    readonly description?: string;
+    readonly createdAt?: Date;
+  };
+}
+/**
+ * Output of {@link Scorer.score}.
+ *
+ * @stable
+ */
+interface ScoreResult {
+  readonly pass: boolean;
+  /** Optional normalized score in `[0, 1]`. */
+  readonly score?: number;
+  readonly reason?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * @stable
+ */
+interface Scorer<I, O = unknown> {
+  readonly name: string;
+  score(args: {
+    readonly case: Case<I, O>;
+    readonly output: O;
+    readonly durationMs: number;
+  }): Promise<ScoreResult>;
+}
+/**
+ * Per-case result.
+ *
+ * @stable
+ */
+interface EvalCaseResult<I, O> {
+  readonly caseId: string;
+  readonly input: I;
+  readonly output: O;
+  readonly durationMs: number;
+  readonly scores: ReadonlyArray<{
+    readonly scorer: string;
+    readonly result: ScoreResult;
+  }>;
+}
+/**
+ * Final report shape.
+ *
+ * @stable
+ */
+interface EvalReport<I, O> {
+  readonly results: ReadonlyArray<EvalCaseResult<I, O>>;
+  readonly summary: {
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly avgDurationMs: number;
+    readonly byScorer: Readonly<Record<string, {
+      readonly passed: number;
+      readonly failed: number;
+      readonly avgScore: number | null;
+    }>>;
+  };
+  /**
+   * `true` when the run was cut short by an aborted signal — `results` and
+   * `summary` then cover only the cases that finished before the abort (a
+   * partial report). Absent on a normal full run. See `runEvals`.
+   */
+  readonly aborted?: boolean;
+}
+/**
+ * @stable
+ */
+interface RunEvalOptions<I, O> {
+  readonly agent: {
+    readonly run: (input: I) => Promise<O>;
+  };
+  readonly dataset: Dataset<I, O>;
+  readonly scorers: ReadonlyArray<Scorer<I, O>>;
+  readonly iterations?: number;
+  readonly signal?: AbortSignal;
+}
+//#endregion
+export { Case, Dataset, EvalCaseResult, EvalReport, RunEvalOptions, ScoreResult, Scorer };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/eval/types.ts"],"sourcesContent":[],"mappings":";;AAaA;;;;;;;AAUA;;;;AACwC,UAXvB,IAWuB,CAAA,CAAA,EAAA,IAAA,OAAA,EAAA,IAXE,QAWF,CAXW,MAWX,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,CAAA,CAAA;EAAG,SAAA,EAAA,CAAA,EAAA,MAAA;EAAX,SAAA,KAAA,EATd,CASc;EAAd,SAAA,QAAA,CAAA,EARI,CAQJ;EAIO,SAAA,QAAA,CAAA,EAXH,CAWG;;AASzB;AAWA;;AAG2B,UA5BV,OA4BU,CAAA,CAAA,EAAA,IAAA,OAAA,EAAA,IA5BkB,QA4BlB,CA5B2B,MA4B3B,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,CAAA,CAAA;EAAR,SAAA,KAAA,EA3BD,aA2BC,CA3Ba,IA2Bb,CA3BkB,CA2BlB,EA3BqB,CA2BrB,EA3BwB,CA2BxB,CAAA,CAAA;EACE,SAAA,QAAA,CAAA,EAAA;IAEP,SAAA,IAAA,CAAA,EAAA,MAAA;IAAR,SAAA,WAAA,CAAA,EAAA,MAAA;IAAO,SAAA,SAAA,CAAA,EA1BY,IA0BZ;EAQI,CAAA;;;;;;AAajB;AACiD,UAvChC,WAAA,CAuCgC;EAAG,SAAA,IAAA,EAAA,OAAA;EAAlB;EAAd,SAAA,KAAA,CAAA,EAAA,MAAA;EAOd,SAAA,MAAA,CAAA,EAAA,MAAA;EADiB,SAAA,QAAA,CAAA,EAxCD,QAwCC,CAxCQ,MAwCR,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA;;AAkBvB;;;AACgD,UArD/B,MAqD+B,CAAA,CAAA,EAAA,IAAA,OAAA,CAAA,CAAA;EACpB,SAAA,IAAA,EAAA,MAAA;EAAG,KAAA,CAAA,IAAA,EAAA;IAAX,SAAA,IAAA,EAnDD,IAmDC,CAnDI,CAmDJ,EAnDO,CAmDP,CAAA;IACqB,SAAA,MAAA,EAnDpB,CAmDoB;IAAG,SAAA,UAAA,EAAA,MAAA;EAAV,CAAA,CAAA,EAjD5B,OAiD4B,CAjDpB,WAiDoB,CAAA;;;;;;;UAzCjB;;kBAEC;mBACC;;mBAEA;;qBAA0D;;;;;;;;UAQ5D;oBACG,cAAc,eAAe,GAAG;;;;;;uBAM7B,SACjB;;;;;;;;;;;;;;;;UAiBW;;0BACyB,MAAM,QAAQ;;oBACpC,QAAQ,GAAG;oBACX,cAAc,OAAO,GAAG;;oBAExB"}

package/dist/exporters/console.d.ts

@@ -0,0 +1,27 @@
+import { TraceExporter } from "./types.js";
+
+//#region src/exporters/console.d.ts
+
+/**
+ * Configuration shape for {@link createConsoleExporter}.
+ *
+ * @stable
+ */
+interface ConsoleExporterOptions {
+  /** Identifier reported via `exporter.id`. Defaults to `'console'`. */
+  readonly id?: string;
+  /** When `true`, emit JSON pretty-printed across multiple lines. */
+  readonly pretty?: boolean;
+  /** Custom sink. Defaults to `console.log`. */
+  readonly sink?: (line: string) => void;
+}
+/**
+ * Build a console-based trace exporter. Call `withValidation(exporter)`
+ * before passing the result to `createTracer({ exporters })`.
+ *
+ * @stable
+ */
+declare function createConsoleExporter(opts?: ConsoleExporterOptions): TraceExporter;
+//#endregion
+export { ConsoleExporterOptions, createConsoleExporter };
+//# sourceMappingURL=console.d.ts.map

package/dist/exporters/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","names":[],"sources":["../../src/exporters/console.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAiBiB,sBAAA;;;;;;;;;;;;;;iBAeD,qBAAA,QAA4B,yBAA8B"}

package/dist/exporters/console.js

@@ -0,0 +1,47 @@
+//#region src/exporters/console.ts
+/**
+* Build a console-based trace exporter. Call `withValidation(exporter)`
+* before passing the result to `createTracer({ exporters })`.
+*
+* @stable
+*/
+function createConsoleExporter(opts = {}) {
+	const id = opts.id ?? "console";
+	const pretty = opts.pretty === true;
+	const sink = opts.sink ?? ((line) => console.log(line));
+	let closed = false;
+	return {
+		id,
+		async export(record) {
+			if (closed) return;
+			sink(pretty ? JSON.stringify(serializableRecord(record), null, 2) : JSON.stringify(serializableRecord(record)));
+		},
+		async flush() {},
+		async shutdown() {
+			closed = true;
+		}
+	};
+}
+/**
+* @internal
+*/
+function serializableRecord(record) {
+	return {
+		type: record.type,
+		id: record.id,
+		traceId: record.traceId,
+		...record.parentId === void 0 ? {} : { parentId: record.parentId },
+		name: record.name,
+		startUnixNano: record.startUnixNano,
+		endUnixNano: record.endUnixNano,
+		status: record.status,
+		...record.statusMessage === void 0 ? {} : { statusMessage: record.statusMessage },
+		attributes: record.attributes,
+		events: record.events,
+		...record.droppedReason === void 0 ? {} : { droppedReason: record.droppedReason }
+	};
+}
+
+//#endregion
+export { createConsoleExporter, serializableRecord };
+//# sourceMappingURL=console.js.map

package/dist/exporters/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","names":[],"sources":["../../src/exporters/console.ts"],"sourcesContent":["/**\n * `ConsoleExporter` — pretty-prints finished spans to `console.log`.\n *\n * Useful for development and unit testing. Production deployments\n * should use {@link JSONLExporter} (for replay) or\n * {@link OTLPHttpExporter} (for remote OTLP collectors).\n *\n * @packageDocumentation\n */\n\nimport type { SpanRecord, TraceExporter } from './types.js';\n\n/**\n * Configuration shape for {@link createConsoleExporter}.\n *\n * @stable\n */\nexport interface ConsoleExporterOptions {\n  /** Identifier reported via `exporter.id`. Defaults to `'console'`. */\n  readonly id?: string;\n  /** When `true`, emit JSON pretty-printed across multiple lines. */\n  readonly pretty?: boolean;\n  /** Custom sink. Defaults to `console.log`. */\n  readonly sink?: (line: string) => void;\n}\n\n/**\n * Build a console-based trace exporter. Call `withValidation(exporter)`\n * before passing the result to `createTracer({ exporters })`.\n *\n * @stable\n */\nexport function createConsoleExporter(opts: ConsoleExporterOptions = {}): TraceExporter {\n  const id = opts.id ?? 'console';\n  const pretty = opts.pretty === true;\n  const sink = opts.sink ?? ((line: string) => console.log(line));\n\n  let closed = false;\n  return {\n    id,\n    async export(record: SpanRecord): Promise<void> {\n      if (closed) return;\n      const payload = pretty\n        ? JSON.stringify(serializableRecord(record), null, 2)\n        : JSON.stringify(serializableRecord(record));\n      sink(payload);\n    },\n    async flush(): Promise<void> {\n      // Console.log is synchronous on Node; nothing to flush.\n    },\n    async shutdown(): Promise<void> {\n      closed = true;\n    },\n  };\n}\n\n/**\n * @internal\n */\nexport function serializableRecord(record: SpanRecord): Record<string, unknown> {\n  return {\n    type: record.type,\n    id: record.id,\n    traceId: record.traceId,\n    ...(record.parentId === undefined ? {} : { parentId: record.parentId }),\n    name: record.name,\n    startUnixNano: record.startUnixNano,\n    endUnixNano: record.endUnixNano,\n    status: record.status,\n    ...(record.statusMessage === undefined ? {} : { statusMessage: record.statusMessage }),\n    attributes: record.attributes,\n    events: record.events,\n    ...(record.droppedReason === undefined ? {} : { droppedReason: record.droppedReason }),\n  };\n}\n"],"mappings":";;;;;;;AAgCA,SAAgB,sBAAsB,OAA+B,EAAE,EAAiB;CACtF,MAAM,KAAK,KAAK,MAAM;CACtB,MAAM,SAAS,KAAK,WAAW;CAC/B,MAAM,OAAO,KAAK,UAAU,SAAiB,QAAQ,IAAI,KAAK;CAE9D,IAAI,SAAS;AACb,QAAO;EACL;EACA,MAAM,OAAO,QAAmC;AAC9C,OAAI,OAAQ;AAIZ,QAHgB,SACZ,KAAK,UAAU,mBAAmB,OAAO,EAAE,MAAM,EAAE,GACnD,KAAK,UAAU,mBAAmB,OAAO,CAAC,CACjC;;EAEf,MAAM,QAAuB;EAG7B,MAAM,WAA0B;AAC9B,YAAS;;EAEZ;;;;;AAMH,SAAgB,mBAAmB,QAA6C;AAC9E,QAAO;EACL,MAAM,OAAO;EACb,IAAI,OAAO;EACX,SAAS,OAAO;EAChB,GAAI,OAAO,aAAa,SAAY,EAAE,GAAG,EAAE,UAAU,OAAO,UAAU;EACtE,MAAM,OAAO;EACb,eAAe,OAAO;EACtB,aAAa,OAAO;EACpB,QAAQ,OAAO;EACf,GAAI,OAAO,kBAAkB,SAAY,EAAE,GAAG,EAAE,eAAe,OAAO,eAAe;EACrF,YAAY,OAAO;EACnB,QAAQ,OAAO;EACf,GAAI,OAAO,kBAAkB,SAAY,EAAE,GAAG,EAAE,eAAe,OAAO,eAAe;EACtF"}

package/dist/exporters/index.d.ts

@@ -0,0 +1,6 @@
+import { SpanRecord, SpanRecordEvent, TraceExporter, VALIDATED_EXPORTER_BRAND } from "./types.js";
+import { ConsoleExporterOptions, createConsoleExporter } from "./console.js";
+import { JSONLExporterOptions, createJSONLExporter } from "./jsonl.js";
+import { OTLPHttpExporterOptions, createOTLPHttpExporter } from "./otlp-http.js";
+import { WithValidationOptions, isValidatedExporter, tryGetValidatorCounters, withValidation } from "./with-validation.js";
+export { type ConsoleExporterOptions, type JSONLExporterOptions, type OTLPHttpExporterOptions, type SpanRecord, type SpanRecordEvent, type TraceExporter, VALIDATED_EXPORTER_BRAND, type WithValidationOptions, createConsoleExporter, createJSONLExporter, createOTLPHttpExporter, isValidatedExporter, tryGetValidatorCounters, withValidation };

package/dist/exporters/index.js

@@ -0,0 +1,7 @@
+import { createConsoleExporter } from "./console.js";
+import { createJSONLExporter } from "./jsonl.js";
+import { createOTLPHttpExporter } from "./otlp-http.js";
+import { VALIDATED_EXPORTER_BRAND } from "./types.js";
+import { isValidatedExporter, tryGetValidatorCounters, withValidation } from "./with-validation.js";
+
+export { VALIDATED_EXPORTER_BRAND, createConsoleExporter, createJSONLExporter, createOTLPHttpExporter, isValidatedExporter, tryGetValidatorCounters, withValidation };

package/dist/exporters/jsonl.d.ts

@@ -0,0 +1,57 @@
+import { SpanRecord, TraceExporter } from "./types.js";
+
+//#region src/exporters/jsonl.d.ts
+
+/** @internal — used by tests to override the date provider. */
+type DateProvider = () => Date;
+/**
+ * Configuration shape for {@link createJSONLExporter}.
+ *
+ * @stable
+ */
+interface JSONLExporterOptions {
+  /** Identifier reported via `exporter.id`. Defaults to `'jsonl'`. */
+  readonly id?: string;
+  /** Root directory for the trace files. Created if missing. */
+  readonly path: string;
+  /**
+   * Resolver that picks the file path for a given span record. Defaults
+   * to `<rootPath>/<YYYY-MM>/<sessionId>.jsonl` keyed off the
+   * `graphorin.session.id` attribute (or `unsessioned.jsonl` when
+   * absent).
+   */
+  readonly resolveFilePath?: (record: SpanRecord, root: string) => string;
+  /**
+   * Override the date used when picking the rotation directory. Defaults
+   * to `() => new Date()`.
+   *
+   * @internal
+   */
+  readonly now?: DateProvider;
+  /**
+   * Upper bound on simultaneously-open file handles (RP-20). The pool keys
+   * by `(session, UTC-month)`, so a long-living server would otherwise hold
+   * one fd per pair forever; the least-recently-used handle is closed once
+   * the cap is reached. Defaults to `64`.
+   */
+  readonly maxOpenHandles?: number;
+}
+/**
+ * A JSONL exporter, plus an introspection seam for the bounded handle pool.
+ *
+ * @stable
+ */
+interface JSONLExporter extends TraceExporter {
+  /** Number of file handles currently open in the pool (RP-20). */
+  openHandleCount(): number;
+}
+/**
+ * Build a JSONL trace exporter. Call `withValidation(exporter)` before
+ * passing the result to `createTracer({ exporters })`.
+ *
+ * @stable
+ */
+declare function createJSONLExporter(opts: JSONLExporterOptions): JSONLExporter;
+//#endregion
+export { JSONLExporterOptions, createJSONLExporter };
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/exporters/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","names":[],"sources":["../../src/exporters/jsonl.ts"],"sourcesContent":[],"mappings":";;;;;KAuBY,YAAA,SAAqB;;;;;;UAOhB,oBAAA;;;;;;;;;;;sCAWqB;;;;;;;iBAOrB;;;;;;;;;;;;;;UAeA,aAAA,SAAsB;;;;;;;;;;iBAWvB,mBAAA,OAA0B,uBAAuB"}

package/dist/exporters/jsonl.js

@@ -0,0 +1,95 @@
+import { serializableRecord } from "./console.js";
+import { mkdir, open } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+//#region src/exporters/jsonl.ts
+/**
+* `JSONLExporter` — append-only newline-delimited JSON output. Used as
+* the default trace replay log; encryption-at-rest is opt-in via the
+* encryption hook (Phase 16).
+*
+* The exporter:
+* - creates the target directory with mode `0700`,
+* - opens the per-session file with mode `0600`,
+* - rotates per UTC month + per session id (`YYYY-MM/<sessionId>.jsonl`),
+* - flushes every write (no internal buffer) so the file is suitable
+*   for tail-style replay even after a crash.
+*
+* The output is deterministic — see {@link serializableRecord}.
+*
+* @packageDocumentation
+*/
+/**
+* Build a JSONL trace exporter. Call `withValidation(exporter)` before
+* passing the result to `createTracer({ exporters })`.
+*
+* @stable
+*/
+function createJSONLExporter(opts) {
+	const id = opts.id ?? "jsonl";
+	const root = opts.path;
+	const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+	const resolveFilePath = opts.resolveFilePath ?? defaultPathResolver(now);
+	const maxOpenHandles = Math.max(1, opts.maxOpenHandles ?? 64);
+	const handles = /* @__PURE__ */ new Map();
+	let closed = false;
+	return {
+		id,
+		async export(record) {
+			if (closed) return;
+			const entry = await openOrReuse(handles, resolveFilePath(record, root), maxOpenHandles);
+			const line = `${JSON.stringify(serializableRecord(record))}\n`;
+			await entry.handle.write(line, null, "utf8");
+		},
+		async flush() {
+			for (const entry of handles.values()) await entry.handle.datasync();
+		},
+		async shutdown() {
+			closed = true;
+			for (const entry of handles.values()) await entry.handle.close();
+			handles.clear();
+		},
+		openHandleCount() {
+			return handles.size;
+		}
+	};
+}
+async function openOrReuse(pool, filePath, maxOpenHandles) {
+	const cached = pool.get(filePath);
+	if (cached !== void 0) {
+		pool.delete(filePath);
+		pool.set(filePath, cached);
+		return cached;
+	}
+	while (pool.size >= maxOpenHandles) {
+		const lruKey = pool.keys().next().value;
+		if (lruKey === void 0) break;
+		const lru = pool.get(lruKey);
+		pool.delete(lruKey);
+		if (lru !== void 0) try {
+			await lru.handle.close();
+		} catch {}
+	}
+	await mkdir(dirname(filePath), {
+		recursive: true,
+		mode: 448
+	});
+	const entry = { handle: await open(filePath, "a", 384) };
+	pool.set(filePath, entry);
+	return entry;
+}
+function defaultPathResolver(now) {
+	return (record, root) => {
+		const sessionAttr = record.attributes["graphorin.session.id"];
+		const sessionId = typeof sessionAttr === "string" ? sessionAttr : "unsessioned";
+		const date = now();
+		const yyyy = String(date.getUTCFullYear());
+		const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+		const safeSession = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+		return join(root, `${yyyy}-${mm}`, `${safeSession}.jsonl`);
+	};
+}
+
+//#endregion
+export { createJSONLExporter };
+//# sourceMappingURL=jsonl.js.map

package/dist/exporters/jsonl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.js","names":["entry: FileHandleEntry"],"sources":["../../src/exporters/jsonl.ts"],"sourcesContent":["/**\n * `JSONLExporter` — append-only newline-delimited JSON output. Used as\n * the default trace replay log; encryption-at-rest is opt-in via the\n * encryption hook (Phase 16).\n *\n * The exporter:\n * - creates the target directory with mode `0700`,\n * - opens the per-session file with mode `0600`,\n * - rotates per UTC month + per session id (`YYYY-MM/<sessionId>.jsonl`),\n * - flushes every write (no internal buffer) so the file is suitable\n *   for tail-style replay even after a crash.\n *\n * The output is deterministic — see {@link serializableRecord}.\n *\n * @packageDocumentation\n */\n\nimport { mkdir, open } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { serializableRecord } from './console.js';\nimport type { SpanRecord, TraceExporter } from './types.js';\n\n/** @internal — used by tests to override the date provider. */\nexport type DateProvider = () => Date;\n\n/**\n * Configuration shape for {@link createJSONLExporter}.\n *\n * @stable\n */\nexport interface JSONLExporterOptions {\n  /** Identifier reported via `exporter.id`. Defaults to `'jsonl'`. */\n  readonly id?: string;\n  /** Root directory for the trace files. Created if missing. */\n  readonly path: string;\n  /**\n   * Resolver that picks the file path for a given span record. Defaults\n   * to `<rootPath>/<YYYY-MM>/<sessionId>.jsonl` keyed off the\n   * `graphorin.session.id` attribute (or `unsessioned.jsonl` when\n   * absent).\n   */\n  readonly resolveFilePath?: (record: SpanRecord, root: string) => string;\n  /**\n   * Override the date used when picking the rotation directory. Defaults\n   * to `() => new Date()`.\n   *\n   * @internal\n   */\n  readonly now?: DateProvider;\n  /**\n   * Upper bound on simultaneously-open file handles (RP-20). The pool keys\n   * by `(session, UTC-month)`, so a long-living server would otherwise hold\n   * one fd per pair forever; the least-recently-used handle is closed once\n   * the cap is reached. Defaults to `64`.\n   */\n  readonly maxOpenHandles?: number;\n}\n\n/**\n * A JSONL exporter, plus an introspection seam for the bounded handle pool.\n *\n * @stable\n */\nexport interface JSONLExporter extends TraceExporter {\n  /** Number of file handles currently open in the pool (RP-20). */\n  openHandleCount(): number;\n}\n\n/**\n * Build a JSONL trace exporter. Call `withValidation(exporter)` before\n * passing the result to `createTracer({ exporters })`.\n *\n * @stable\n */\nexport function createJSONLExporter(opts: JSONLExporterOptions): JSONLExporter {\n  const id = opts.id ?? 'jsonl';\n  const root = opts.path;\n  const now = opts.now ?? (() => new Date());\n  const resolveFilePath = opts.resolveFilePath ?? defaultPathResolver(now);\n  const maxOpenHandles = Math.max(1, opts.maxOpenHandles ?? 64);\n\n  // Pool of file handles, keyed by absolute path. Each handle is opened\n  // in append mode the first time we touch the path; subsequent exports\n  // re-use the existing handle. The pool is LRU-bounded (RP-20) — the Map's\n  // insertion order is the recency order, so the first entry is the LRU.\n  const handles = new Map<string, FileHandleEntry>();\n  let closed = false;\n\n  return {\n    id,\n    async export(record: SpanRecord): Promise<void> {\n      if (closed) return;\n      const filePath = resolveFilePath(record, root);\n      const entry = await openOrReuse(handles, filePath, maxOpenHandles);\n      const line = `${JSON.stringify(serializableRecord(record))}\\n`;\n      await entry.handle.write(line, null, 'utf8');\n    },\n    async flush(): Promise<void> {\n      for (const entry of handles.values()) {\n        await entry.handle.datasync();\n      }\n    },\n    async shutdown(): Promise<void> {\n      closed = true;\n      for (const entry of handles.values()) {\n        await entry.handle.close();\n      }\n      handles.clear();\n    },\n    openHandleCount(): number {\n      return handles.size;\n    },\n  };\n}\n\ninterface FileHandleEntry {\n  readonly handle: import('node:fs/promises').FileHandle;\n}\n\nasync function openOrReuse(\n  pool: Map<string, FileHandleEntry>,\n  filePath: string,\n  maxOpenHandles: number,\n): Promise<FileHandleEntry> {\n  const cached = pool.get(filePath);\n  if (cached !== undefined) {\n    // Mark most-recently-used by re-inserting at the tail of the Map.\n    pool.delete(filePath);\n    pool.set(filePath, cached);\n    return cached;\n  }\n\n  // RP-20: evict least-recently-used handles before exceeding the cap so the\n  // open-fd count stays bounded. An evicted path simply re-opens (append mode)\n  // on its next export — no data is lost.\n  while (pool.size >= maxOpenHandles) {\n    const lruKey = pool.keys().next().value;\n    if (lruKey === undefined) break;\n    const lru = pool.get(lruKey);\n    pool.delete(lruKey);\n    if (lru !== undefined) {\n      try {\n        await lru.handle.close();\n      } catch {\n        // Best-effort — a failed close must not block the new open.\n      }\n    }\n  }\n\n  await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });\n  const handle = await open(filePath, 'a', 0o600);\n  const entry: FileHandleEntry = { handle };\n  pool.set(filePath, entry);\n  return entry;\n}\n\nfunction defaultPathResolver(now: DateProvider) {\n  return (record: SpanRecord, root: string): string => {\n    const sessionAttr = record.attributes['graphorin.session.id'];\n    const sessionId = typeof sessionAttr === 'string' ? sessionAttr : 'unsessioned';\n    const date = now();\n    const yyyy = String(date.getUTCFullYear());\n    const mm = String(date.getUTCMonth() + 1).padStart(2, '0');\n    const safeSession = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');\n    return join(root, `${yyyy}-${mm}`, `${safeSession}.jsonl`);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,oBAAoB,MAA2C;CAC7E,MAAM,KAAK,KAAK,MAAM;CACtB,MAAM,OAAO,KAAK;CAClB,MAAM,MAAM,KAAK,8BAAc,IAAI,MAAM;CACzC,MAAM,kBAAkB,KAAK,mBAAmB,oBAAoB,IAAI;CACxE,MAAM,iBAAiB,KAAK,IAAI,GAAG,KAAK,kBAAkB,GAAG;CAM7D,MAAM,0BAAU,IAAI,KAA8B;CAClD,IAAI,SAAS;AAEb,QAAO;EACL;EACA,MAAM,OAAO,QAAmC;AAC9C,OAAI,OAAQ;GAEZ,MAAM,QAAQ,MAAM,YAAY,SADf,gBAAgB,QAAQ,KAAK,EACK,eAAe;GAClE,MAAM,OAAO,GAAG,KAAK,UAAU,mBAAmB,OAAO,CAAC,CAAC;AAC3D,SAAM,MAAM,OAAO,MAAM,MAAM,MAAM,OAAO;;EAE9C,MAAM,QAAuB;AAC3B,QAAK,MAAM,SAAS,QAAQ,QAAQ,CAClC,OAAM,MAAM,OAAO,UAAU;;EAGjC,MAAM,WAA0B;AAC9B,YAAS;AACT,QAAK,MAAM,SAAS,QAAQ,QAAQ,CAClC,OAAM,MAAM,OAAO,OAAO;AAE5B,WAAQ,OAAO;;EAEjB,kBAA0B;AACxB,UAAO,QAAQ;;EAElB;;AAOH,eAAe,YACb,MACA,UACA,gBAC0B;CAC1B,MAAM,SAAS,KAAK,IAAI,SAAS;AACjC,KAAI,WAAW,QAAW;AAExB,OAAK,OAAO,SAAS;AACrB,OAAK,IAAI,UAAU,OAAO;AAC1B,SAAO;;AAMT,QAAO,KAAK,QAAQ,gBAAgB;EAClC,MAAM,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC;AAClC,MAAI,WAAW,OAAW;EAC1B,MAAM,MAAM,KAAK,IAAI,OAAO;AAC5B,OAAK,OAAO,OAAO;AACnB,MAAI,QAAQ,OACV,KAAI;AACF,SAAM,IAAI,OAAO,OAAO;UAClB;;AAMZ,OAAM,MAAM,QAAQ,SAAS,EAAE;EAAE,WAAW;EAAM,MAAM;EAAO,CAAC;CAEhE,MAAMA,QAAyB,EAAE,QADlB,MAAM,KAAK,UAAU,KAAK,IAAM,EACN;AACzC,MAAK,IAAI,UAAU,MAAM;AACzB,QAAO;;AAGT,SAAS,oBAAoB,KAAmB;AAC9C,SAAQ,QAAoB,SAAyB;EACnD,MAAM,cAAc,OAAO,WAAW;EACtC,MAAM,YAAY,OAAO,gBAAgB,WAAW,cAAc;EAClE,MAAM,OAAO,KAAK;EAClB,MAAM,OAAO,OAAO,KAAK,gBAAgB,CAAC;EAC1C,MAAM,KAAK,OAAO,KAAK,aAAa,GAAG,EAAE,CAAC,SAAS,GAAG,IAAI;EAC1D,MAAM,cAAc,UAAU,QAAQ,oBAAoB,IAAI;AAC9D,SAAO,KAAK,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,YAAY,QAAQ"}

package/dist/exporters/otlp-http.d.ts

@@ -0,0 +1,38 @@
+import { TraceExporter } from "./types.js";
+
+//#region src/exporters/otlp-http.d.ts
+
+/**
+ * Configuration shape for {@link createOTLPHttpExporter}.
+ *
+ * @stable
+ */
+interface OTLPHttpExporterOptions {
+  /** Identifier reported via `exporter.id`. Defaults to `'otlp-http'`. */
+  readonly id?: string;
+  /** OTLP collector URL (e.g. `http://localhost:4318/v1/traces`). */
+  readonly url: string;
+  /** Optional headers (auth, tenant id, …). Avoid passing secrets in plain. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Service name embedded in the OTLP `Resource`. */
+  readonly serviceName?: string;
+  /** Optional `fetch` override — useful for testing without the network. */
+  readonly fetchImpl?: typeof fetch;
+  /** Optional timeout (ms). Defaults to 10000. */
+  readonly timeoutMs?: number;
+}
+/**
+ * Build a minimal OTLP-over-HTTP trace exporter. Call
+ * `withValidation(exporter)` before passing the result to
+ * `createTracer({ exporters })`.
+ *
+ * The implementation issues one `POST` per finished span — no
+ * batching. Operators wanting batching should wrap this exporter
+ * with their own queue or use a sidecar collector.
+ *
+ * @stable
+ */
+declare function createOTLPHttpExporter(opts: OTLPHttpExporterOptions): TraceExporter;
+//#endregion
+export { OTLPHttpExporterOptions, createOTLPHttpExporter };
+//# sourceMappingURL=otlp-http.d.ts.map

package/dist/exporters/otlp-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-http.d.ts","names":[],"sources":["../../src/exporters/otlp-http.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UA4BiB,uBAAA;;;;;;qBAMI,SAAS;;;;8BAIA;;;;;;;;;;;;;;;iBAgBd,sBAAA,OAA6B,0BAA0B"}

package/dist/exporters/otlp-http.js

@@ -0,0 +1,115 @@
+//#region src/exporters/otlp-http.ts
+/**
+* Build a minimal OTLP-over-HTTP trace exporter. Call
+* `withValidation(exporter)` before passing the result to
+* `createTracer({ exporters })`.
+*
+* The implementation issues one `POST` per finished span — no
+* batching. Operators wanting batching should wrap this exporter
+* with their own queue or use a sidecar collector.
+*
+* @stable
+*/
+function createOTLPHttpExporter(opts) {
+	const id = opts.id ?? "otlp-http";
+	const url = opts.url;
+	const headers = opts.headers ?? {};
+	const serviceName = opts.serviceName ?? "graphorin";
+	const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+	const timeoutMs = opts.timeoutMs ?? 1e4;
+	let closed = false;
+	if (typeof fetchImpl !== "function") throw new TypeError("createOTLPHttpExporter: no fetch implementation available. Provide `fetchImpl` explicitly or run on a Node.js version with global fetch (>= 18).");
+	return {
+		id,
+		async export(record) {
+			if (closed) return;
+			const body = toOtlpEnvelope(record, serviceName);
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), timeoutMs);
+			try {
+				const res = await fetchImpl(url, {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						...headers
+					},
+					body: JSON.stringify(body),
+					signal: controller.signal
+				});
+				if (!res.ok) throw new Error(`OTLP exporter received HTTP ${res.status} ${res.statusText}`);
+			} finally {
+				clearTimeout(timer);
+			}
+		},
+		async flush() {},
+		async shutdown() {
+			closed = true;
+		}
+	};
+}
+/**
+* @internal — exposed for unit tests
+*/
+function toOtlpEnvelope(record, serviceName) {
+	const otelStatus = record.status === "ok" ? 1 : record.status === "error" ? 2 : 0;
+	return { resourceSpans: [{
+		resource: { attributes: [{
+			key: "service.name",
+			value: { stringValue: serviceName }
+		}, {
+			key: "graphorin.framework.version",
+			value: { stringValue: "0.5.0" }
+		}] },
+		scopeSpans: [{
+			scope: {
+				name: "@graphorin/observability",
+				version: "0.5.0"
+			},
+			spans: [{
+				traceId: record.traceId,
+				spanId: record.id,
+				...record.parentId === void 0 ? {} : { parentSpanId: record.parentId },
+				name: record.name,
+				kind: spanKindFor(record.type),
+				startTimeUnixNano: String(record.startUnixNano),
+				endTimeUnixNano: String(record.endUnixNano),
+				attributes: toOtlpAttributes(record.attributes),
+				events: record.events.map(toOtlpEvent),
+				status: {
+					code: otelStatus,
+					...record.statusMessage === void 0 ? {} : { message: record.statusMessage }
+				}
+			}]
+		}]
+	}] };
+}
+function spanKindFor(type) {
+	if (type === "provider.generate" || type === "provider.stream" || type === "mcp.call") return 3;
+	if (type === "tool.execute" || type === "memory.embed") return 1;
+	return 1;
+}
+function toOtlpAttributes(attrs) {
+	return Object.entries(attrs).map(([k, v]) => ({
+		key: k,
+		value: toOtlpAttributeValue(v)
+	}));
+}
+function toOtlpEvent(event) {
+	return {
+		timeUnixNano: String(event.timeUnixNano),
+		name: event.name,
+		attributes: toOtlpAttributes(event.attributes)
+	};
+}
+function toOtlpAttributeValue(v) {
+	if (typeof v === "string") return { stringValue: v };
+	if (typeof v === "number") return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+	if (typeof v === "boolean") return { boolValue: v };
+	if (v === null) return { stringValue: "" };
+	if (Array.isArray(v)) return { arrayValue: { values: v.map((item) => toOtlpAttributeValue(item)) } };
+	return { stringValue: String(v) };
+}
+
+//#endregion
+export { createOTLPHttpExporter };
+//# sourceMappingURL=otlp-http.js.map

package/dist/exporters/otlp-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-http.js","names":[],"sources":["../../src/exporters/otlp-http.ts"],"sourcesContent":["/**\n * `OTLPHttpExporter` — reference implementation that POSTs span\n * records to an OpenTelemetry HTTP endpoint.\n *\n * The exporter is deliberately minimal: production hardening (retry\n * logic, batching policy tuning, gzip compression, bearer-token auth\n * rotation) is left to operators. The wire format follows the OTLP\n * `traces` resource shape and is compatible with collectors that accept\n * the `application/json` content type.\n *\n * Operators wanting the upstream OpenTelemetry SDK exporter\n * (`@opentelemetry/exporter-trace-otlp-http`) can adapt\n * {@link toOtlpEnvelope} into their own wrapper — the helper is\n * exported so the OTel adapter does not need to duplicate the wire\n * shape.\n *\n * @packageDocumentation\n */\n\nimport type { SpanAttributes, SpanAttributeValue, SpanType } from '@graphorin/core';\n\nimport type { SpanRecord, SpanRecordEvent, TraceExporter } from './types.js';\n\n/**\n * Configuration shape for {@link createOTLPHttpExporter}.\n *\n * @stable\n */\nexport interface OTLPHttpExporterOptions {\n  /** Identifier reported via `exporter.id`. Defaults to `'otlp-http'`. */\n  readonly id?: string;\n  /** OTLP collector URL (e.g. `http://localhost:4318/v1/traces`). */\n  readonly url: string;\n  /** Optional headers (auth, tenant id, …). Avoid passing secrets in plain. */\n  readonly headers?: Readonly<Record<string, string>>;\n  /** Service name embedded in the OTLP `Resource`. */\n  readonly serviceName?: string;\n  /** Optional `fetch` override — useful for testing without the network. */\n  readonly fetchImpl?: typeof fetch;\n  /** Optional timeout (ms). Defaults to 10000. */\n  readonly timeoutMs?: number;\n}\n\n/**\n * Build a minimal OTLP-over-HTTP trace exporter. Call\n * `withValidation(exporter)` before passing the result to\n * `createTracer({ exporters })`.\n *\n * The implementation issues one `POST` per finished span — no\n * batching. Operators wanting batching should wrap this exporter\n * with their own queue or use a sidecar collector.\n *\n * @stable\n */\nexport function createOTLPHttpExporter(opts: OTLPHttpExporterOptions): TraceExporter {\n  const id = opts.id ?? 'otlp-http';\n  const url = opts.url;\n  const headers = opts.headers ?? {};\n  const serviceName = opts.serviceName ?? 'graphorin';\n  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;\n  const timeoutMs = opts.timeoutMs ?? 10_000;\n  let closed = false;\n\n  if (typeof fetchImpl !== 'function') {\n    throw new TypeError(\n      'createOTLPHttpExporter: no fetch implementation available. Provide ' +\n        '`fetchImpl` explicitly or run on a Node.js version with global fetch ' +\n        '(>= 18).',\n    );\n  }\n\n  return {\n    id,\n    async export(record: SpanRecord): Promise<void> {\n      if (closed) return;\n      const body = toOtlpEnvelope(record, serviceName);\n      const controller = new AbortController();\n      const timer = setTimeout(() => controller.abort(), timeoutMs);\n      try {\n        const res = await fetchImpl(url, {\n          method: 'POST',\n          headers: { 'content-type': 'application/json', ...headers },\n          body: JSON.stringify(body),\n          signal: controller.signal,\n        });\n        if (!res.ok) {\n          throw new Error(`OTLP exporter received HTTP ${res.status} ${res.statusText}`);\n        }\n      } finally {\n        clearTimeout(timer);\n      }\n    },\n    async flush(): Promise<void> {\n      // No internal queue; each export() awaits the POST already.\n    },\n    async shutdown(): Promise<void> {\n      closed = true;\n    },\n  };\n}\n\n/**\n * @internal — exposed for unit tests\n */\nexport function toOtlpEnvelope(record: SpanRecord, serviceName: string): unknown {\n  const otelStatus = record.status === 'ok' ? 1 : record.status === 'error' ? 2 : 0;\n  return {\n    resourceSpans: [\n      {\n        resource: {\n          attributes: [\n            { key: 'service.name', value: { stringValue: serviceName } },\n            { key: 'graphorin.framework.version', value: { stringValue: '0.5.0' } },\n          ],\n        },\n        scopeSpans: [\n          {\n            scope: { name: '@graphorin/observability', version: '0.5.0' },\n            spans: [\n              {\n                traceId: record.traceId,\n                spanId: record.id,\n                ...(record.parentId === undefined ? {} : { parentSpanId: record.parentId }),\n                name: record.name,\n                kind: spanKindFor(record.type),\n                startTimeUnixNano: String(record.startUnixNano),\n                endTimeUnixNano: String(record.endUnixNano),\n                attributes: toOtlpAttributes(record.attributes),\n                events: record.events.map(toOtlpEvent),\n                status: {\n                  code: otelStatus,\n                  ...(record.statusMessage === undefined ? {} : { message: record.statusMessage }),\n                },\n              },\n            ],\n          },\n        ],\n      },\n    ],\n  };\n}\n\nfunction spanKindFor(type: SpanType): number {\n  // OTel SpanKind enum: 0 unspecified, 1 internal, 2 server, 3 client, 4 producer, 5 consumer.\n  if (type === 'provider.generate' || type === 'provider.stream' || type === 'mcp.call') return 3;\n  if (type === 'tool.execute' || type === 'memory.embed') return 1;\n  return 1;\n}\n\nfunction toOtlpAttributes(attrs: SpanAttributes): unknown[] {\n  return Object.entries(attrs).map(([k, v]) => ({ key: k, value: toOtlpAttributeValue(v) }));\n}\n\nfunction toOtlpEvent(event: SpanRecordEvent): unknown {\n  return {\n    timeUnixNano: String(event.timeUnixNano),\n    name: event.name,\n    attributes: toOtlpAttributes(event.attributes),\n  };\n}\n\nfunction toOtlpAttributeValue(v: SpanAttributeValue): unknown {\n  if (typeof v === 'string') return { stringValue: v };\n  if (typeof v === 'number') {\n    return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };\n  }\n  if (typeof v === 'boolean') return { boolValue: v };\n  if (v === null) return { stringValue: '' };\n  if (Array.isArray(v)) {\n    return {\n      arrayValue: {\n        values: v.map((item) => toOtlpAttributeValue(item as SpanAttributeValue)),\n      },\n    };\n  }\n  return { stringValue: String(v) };\n}\n"],"mappings":"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"}

package/dist/exporters/types.d.ts

@@ -0,0 +1,72 @@
+import { SpanAttributeValue, SpanAttributes, SpanStatus, SpanType } from "@graphorin/core";
+
+//#region src/exporters/types.d.ts
+
+/**
+ * Discriminator marker — every exporter that has been wrapped via
+ * `withValidation(...)` is branded with this symbol so the tracer can
+ * fail-fast at startup when a raw exporter is registered.
+ *
+ * @stable
+ */
+declare const VALIDATED_EXPORTER_BRAND: unique symbol;
+/**
+ * Sanitized, JSON-serialisable representation of a finished span. The
+ * exporters never see the live OTel span; the tracer materialises this
+ * record once the span ends and runs it through the validator.
+ *
+ * @stable
+ */
+interface SpanRecord<T extends SpanType = SpanType> {
+  readonly type: T;
+  readonly id: string;
+  readonly traceId: string;
+  readonly parentId?: string;
+  readonly name: string;
+  readonly startUnixNano: number;
+  readonly endUnixNano: number;
+  readonly status: SpanStatus;
+  readonly statusMessage?: string;
+  readonly attributes: SpanAttributes;
+  readonly events: ReadonlyArray<SpanRecordEvent>;
+  /** Optional per-attribute sensitivity map — see `setAttribute({ sensitivity })`. */
+  readonly sensitivityByAttribute?: Readonly<Record<string, SpanAttributeValue>>;
+  /** Set when the validator dropped the span entirely (replay marker). */
+  readonly droppedReason?: string;
+}
+/**
+ * Single span event carried alongside the span record.
+ *
+ * @stable
+ */
+interface SpanRecordEvent {
+  readonly name: string;
+  readonly timeUnixNano: number;
+  readonly attributes: SpanAttributes;
+}
+/**
+ * A trace exporter contract. Exporters consume a stream of finished
+ * spans and forward them to a sink (console, file, OTLP wire, …).
+ *
+ * @stable
+ */
+interface TraceExporter {
+  readonly id: string;
+  /** Forward a finished span record. Implementations should be cheap. */
+  export(record: SpanRecord): Promise<void>;
+  /** Flush any buffered spans. Called on `tracer.shutdown()`. */
+  flush(): Promise<void>;
+  /** Close any underlying resources. Idempotent. */
+  shutdown(): Promise<void>;
+  /**
+   * Branded-marker stub. Set by `withValidation(...)` to signal that the
+   * exporter has been wrapped. Direct exporters omit the brand and the
+   * tracer fails fast at startup.
+   *
+   * @internal
+   */
+  readonly [VALIDATED_EXPORTER_BRAND]?: true;
+}
+//#endregion
+export { SpanRecord, SpanRecordEvent, TraceExporter, VALIDATED_EXPORTER_BRAND };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/exporters/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAuC6C,cAxBhC,wBAwBgC,EAAA,OAAA,MAAA;;;AAU7C;AAYA;;;;AAOc,UA1CG,UA0CH,CAAA,UA1CwB,QA0CxB,GA1CmC,QA0CnC,CAAA,CAAA;EAQF,SAAA,IAAA,EAjDK,CAiDL;EAAwB,SAAA,EAAA,EAAA,MAAA;;;;;;mBA1CjB;;uBAEI;mBACJ,cAAc;;oCAEG,SAAS,eAAe;;;;;;;;;UAU3C,eAAA;;;uBAGM;;;;;;;;UASN,aAAA;;;iBAGA,aAAa;;WAEnB;;cAEG;;;;;;;;YAQF,wBAAA"}

package/dist/exporters/types.js

@@ -0,0 +1,13 @@
+//#region src/exporters/types.ts
+/**
+* Discriminator marker — every exporter that has been wrapped via
+* `withValidation(...)` is branded with this symbol so the tracer can
+* fail-fast at startup when a raw exporter is registered.
+*
+* @stable
+*/
+const VALIDATED_EXPORTER_BRAND = Symbol.for("graphorin.observability.exporter.validated");
+
+//#endregion
+export { VALIDATED_EXPORTER_BRAND };
+//# sourceMappingURL=types.js.map