@graphorin/observability 0.5.0

package/dist/tracer/sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.js","names":["decisionMaker: SamplingDecisionMaker","windowStart: number | undefined"],"sources":["../../src/tracer/sampling.ts"],"sourcesContent":["/**\n * Head + tail sampling helpers. The tracer pairs the configured\n * sampler with a per-type override registry so chatty span types\n * (`memory.embed`, `tool.execute.partial`, …) can be downsampled\n * without affecting the rest of the trace stream.\n *\n * @packageDocumentation\n */\n\nimport type { SpanType } from '@graphorin/core';\n\n/** @stable */\nexport type SamplingDecisionMaker = 'parent-based' | 'always-on' | 'rate-limit';\n\n/**\n * Per-span-type rate override.\n *\n * @stable\n */\nexport interface SamplingRule {\n  readonly type: SpanType | string;\n  readonly rate: number;\n}\n\n/**\n * Configuration shape consumed by {@link createSampler}.\n *\n * @stable\n */\nexport interface SamplingOptions {\n  /** Default head-sampling rate. Must be in `[0, 1]`. Defaults to `1.0`. */\n  readonly rate?: number;\n  /** Per-type overrides. Last write wins on duplicate `type`. */\n  readonly rules?: ReadonlyArray<SamplingRule>;\n  /** Decision maker. Defaults to `'parent-based'`. */\n  readonly decisionMaker?: SamplingDecisionMaker;\n  /**\n   * Cap for the `'rate-limit'` decision maker: at most this many root spans\n   * are sampled per rolling 1-second window (RP-19). `undefined` ⇒ no cap\n   * (samples everything); `0` ⇒ sample nothing. Ignored by the other\n   * decision makers.\n   */\n  readonly maxPerSecond?: number;\n  /**\n   * Clock for the `'rate-limit'` window. Defaults to `Date.now`.\n   *\n   * @internal\n   */\n  readonly now?: () => number;\n  /**\n   * Optional override for streaming-event sampling.\n   * @see RB-52 — streaming event family `tool.execute.{progress,partial}`.\n   */\n  readonly streaming?: {\n    readonly eventSamplingRate?: number;\n    readonly includeChunkContent?: 'none' | 'text-only' | 'all';\n  };\n  /**\n   * Override for the random source. Useful for deterministic tests.\n   *\n   * @internal\n   */\n  readonly random?: () => number;\n}\n\n/**\n * @stable\n */\nexport interface Sampler {\n  /** Decide whether a span of the given type should be recorded. */\n  shouldSample(type: SpanType | string, parentSampled?: boolean): boolean;\n  /** Decide whether a span event of the given name should be recorded. */\n  shouldRecordEvent(name: string): boolean;\n  /** Returns whether chunk *content* should travel through the exporter. */\n  shouldIncludeChunkContent(): boolean;\n}\n\n/**\n * Build a {@link Sampler} from the supplied options. The sampler is\n * intentionally inexpensive — every decision boils down to a single\n * `random < threshold` comparison.\n *\n * @stable\n */\nexport function createSampler(opts: SamplingOptions = {}): Sampler {\n  const baseRate = clampRate(opts.rate ?? 1.0);\n  const decisionMaker: SamplingDecisionMaker = opts.decisionMaker ?? 'parent-based';\n  const ruleByType = new Map<string, number>();\n  for (const rule of opts.rules ?? []) {\n    ruleByType.set(rule.type, clampRate(rule.rate));\n  }\n  const streamingRate = clampRate(opts.streaming?.eventSamplingRate ?? 1.0);\n  const includeChunks = opts.streaming?.includeChunkContent ?? 'none';\n  const random = opts.random ?? Math.random;\n  const maxPerSecond = opts.maxPerSecond;\n  const now = opts.now ?? Date.now;\n  let windowStart: number | undefined;\n  let windowCount = 0;\n\n  return {\n    shouldSample(type, parentSampled): boolean {\n      if (decisionMaker === 'always-on') return true;\n      if (decisionMaker === 'parent-based') {\n        // RP-19: true parent-based — follow the parent's real sampling\n        // decision. A child of an unsampled parent is NOT recorded (it would\n        // otherwise be an orphan); a root span (no parent) falls through to\n        // the rate.\n        if (parentSampled === true) return true;\n        if (parentSampled === false) return false;\n      }\n      if (decisionMaker === 'rate-limit') {\n        // RP-19: a real token-window limiter, distinct from the probabilistic\n        // path. Caps sampled spans to `maxPerSecond` per rolling second.\n        if (maxPerSecond === undefined) return true;\n        if (maxPerSecond <= 0) return false;\n        const t = now();\n        if (windowStart === undefined || t - windowStart >= 1000) {\n          windowStart = t;\n          windowCount = 0;\n        }\n        if (windowCount < maxPerSecond) {\n          windowCount += 1;\n          return true;\n        }\n        return false;\n      }\n      const rate = ruleByType.get(type) ?? baseRate;\n      if (rate >= 1) return true;\n      if (rate <= 0) return false;\n      return random() < rate;\n    },\n    shouldRecordEvent(name): boolean {\n      const rate = ruleByType.get(name) ?? streamingRate;\n      if (rate >= 1) return true;\n      if (rate <= 0) return false;\n      return random() < rate;\n    },\n    shouldIncludeChunkContent(): boolean {\n      return includeChunks !== 'none';\n    },\n  };\n}\n\nfunction clampRate(rate: number): number {\n  if (Number.isNaN(rate)) return 1;\n  if (rate < 0) return 0;\n  if (rate > 1) return 1;\n  return rate;\n}\n"],"mappings":";;;;;;;;AAoFA,SAAgB,cAAc,OAAwB,EAAE,EAAW;CACjE,MAAM,WAAW,UAAU,KAAK,QAAQ,EAAI;CAC5C,MAAMA,gBAAuC,KAAK,iBAAiB;CACnE,MAAM,6BAAa,IAAI,KAAqB;AAC5C,MAAK,MAAM,QAAQ,KAAK,SAAS,EAAE,CACjC,YAAW,IAAI,KAAK,MAAM,UAAU,KAAK,KAAK,CAAC;CAEjD,MAAM,gBAAgB,UAAU,KAAK,WAAW,qBAAqB,EAAI;CACzE,MAAM,gBAAgB,KAAK,WAAW,uBAAuB;CAC7D,MAAM,SAAS,KAAK,UAAU,KAAK;CACnC,MAAM,eAAe,KAAK;CAC1B,MAAM,MAAM,KAAK,OAAO,KAAK;CAC7B,IAAIC;CACJ,IAAI,cAAc;AAElB,QAAO;EACL,aAAa,MAAM,eAAwB;AACzC,OAAI,kBAAkB,YAAa,QAAO;AAC1C,OAAI,kBAAkB,gBAAgB;AAKpC,QAAI,kBAAkB,KAAM,QAAO;AACnC,QAAI,kBAAkB,MAAO,QAAO;;AAEtC,OAAI,kBAAkB,cAAc;AAGlC,QAAI,iBAAiB,OAAW,QAAO;AACvC,QAAI,gBAAgB,EAAG,QAAO;IAC9B,MAAM,IAAI,KAAK;AACf,QAAI,gBAAgB,UAAa,IAAI,eAAe,KAAM;AACxD,mBAAc;AACd,mBAAc;;AAEhB,QAAI,cAAc,cAAc;AAC9B,oBAAe;AACf,YAAO;;AAET,WAAO;;GAET,MAAM,OAAO,WAAW,IAAI,KAAK,IAAI;AACrC,OAAI,QAAQ,EAAG,QAAO;AACtB,OAAI,QAAQ,EAAG,QAAO;AACtB,UAAO,QAAQ,GAAG;;EAEpB,kBAAkB,MAAe;GAC/B,MAAM,OAAO,WAAW,IAAI,KAAK,IAAI;AACrC,OAAI,QAAQ,EAAG,QAAO;AACtB,OAAI,QAAQ,EAAG,QAAO;AACtB,UAAO,QAAQ,GAAG;;EAEpB,4BAAqC;AACnC,UAAO,kBAAkB;;EAE5B;;AAGH,SAAS,UAAU,MAAsB;AACvC,KAAI,OAAO,MAAM,KAAK,CAAE,QAAO;AAC/B,KAAI,OAAO,EAAG,QAAO;AACrB,KAAI,OAAO,EAAG,QAAO;AACrB,QAAO"}

package/dist/tracer/span-names.d.ts

@@ -0,0 +1,11 @@
+import { SpanType } from "@graphorin/core";
+
+//#region src/tracer/span-names.d.ts
+
+/**
+ * @stable
+ */
+declare function spanNameFor(type: SpanType): string;
+//#endregion
+export { spanNameFor };
+//# sourceMappingURL=span-names.d.ts.map

package/dist/tracer/span-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-names.d.ts","names":[],"sources":["../../src/tracer/span-names.ts"],"sourcesContent":[],"mappings":";;;;;;;iBAagB,WAAA,OAAkB"}

package/dist/tracer/span-names.js

@@ -0,0 +1,11 @@
+//#region src/tracer/span-names.ts
+/**
+* @stable
+*/
+function spanNameFor(type) {
+	return type;
+}
+
+//#endregion
+export { spanNameFor };
+//# sourceMappingURL=span-names.js.map

package/dist/tracer/span-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-names.js","names":[],"sources":["../../src/tracer/span-names.ts"],"sourcesContent":["/**\n * Default human-readable span name per {@link SpanType}. Operators\n * can override the name by passing `name` through a custom\n * `setAttributes(...)` call after `startSpan(...)` returns.\n *\n * @packageDocumentation\n */\n\nimport type { SpanType } from '@graphorin/core';\n\n/**\n * @stable\n */\nexport function spanNameFor(type: SpanType): string {\n  return type;\n}\n"],"mappings":";;;;AAaA,SAAgB,YAAY,MAAwB;AAClD,QAAO"}

package/dist/tracer/span.d.ts

@@ -0,0 +1,27 @@
+import { AISpan, Sensitivity, SpanAttributeValue, SpanAttributes, SpanType } from "@graphorin/core";
+
+//#region src/tracer/span.d.ts
+
+/**
+ * Optional metadata accepted by `setAttribute(...)` to declare the
+ * sensitivity of a single attribute. The validator uses the declared
+ * tier when deciding whether to drop the attribute.
+ *
+ * @stable
+ */
+interface SetAttributeOptions {
+  readonly sensitivity?: Sensitivity;
+}
+/**
+ * The internal span carries the convenience `setAttribute(...)` method
+ * exposed by the tracer surface (per-attribute sensitivity tagging) on
+ * top of the standard {@link AISpan} contract.
+ *
+ * @stable
+ */
+interface GraphorinSpan<T extends SpanType = SpanType> extends AISpan<T> {
+  setAttribute(name: string, value: SpanAttributeValue, opts?: SetAttributeOptions): void;
+}
+//#endregion
+export { GraphorinSpan, SetAttributeOptions };
+//# sourceMappingURL=span.d.ts.map

package/dist/tracer/span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.d.ts","names":[],"sources":["../../src/tracer/span.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;UA0BiB,mBAAA;yBACQ;;;;;;;;;UAUR,wBAAwB,WAAW,kBAAkB,OAAO;oCACzC,2BAA2B"}

package/dist/tracer/span.js

@@ -0,0 +1,80 @@
+//#region src/tracer/span.ts
+/**
+* @internal
+*/
+function createSpan(input) {
+	const startUnixNano = Math.floor(input.now() * 1e6);
+	const attributes = { ...input.attrs ?? {} };
+	const sensitivities = { ...input.attrSensitivities ?? {} };
+	const events = [];
+	let status = "ok";
+	let statusMessage;
+	let ended = false;
+	return {
+		type: input.type,
+		id: input.id,
+		traceId: input.traceId,
+		...input.parentId === void 0 ? {} : { parentId: input.parentId },
+		setAttributes(attrs) {
+			if (ended) return;
+			for (const [k, v] of Object.entries(attrs)) attributes[k] = v;
+		},
+		setAttribute(name, value, opts) {
+			if (ended) return;
+			attributes[name] = value;
+			if (opts?.sensitivity !== void 0) sensitivities[name] = opts.sensitivity;
+		},
+		addEvent(name, attrs) {
+			if (ended) return;
+			if (!input.recordEvent(name)) return;
+			events.push({
+				name,
+				timeUnixNano: Math.floor(input.now() * 1e6),
+				attributes: Object.freeze({ ...attrs ?? {} })
+			});
+		},
+		recordException(err) {
+			if (ended) return;
+			const e = err;
+			const attrs = {
+				"exception.type": typeof e?.name === "string" && e.name.length > 0 ? e.name : "Error",
+				"exception.message": typeof e?.message === "string" ? e.message : String(err),
+				...typeof e?.stack === "string" ? { "exception.stacktrace": e.stack } : {}
+			};
+			events.push({
+				name: "exception",
+				timeUnixNano: Math.floor(input.now() * 1e6),
+				attributes: attrs
+			});
+		},
+		setStatus(s, message) {
+			if (ended) return;
+			status = s;
+			if (message !== void 0) statusMessage = message;
+		},
+		end() {
+			if (ended) return;
+			ended = true;
+			const endUnixNano = Math.floor(input.now() * 1e6);
+			const record = {
+				type: input.type,
+				id: input.id,
+				traceId: input.traceId,
+				...input.parentId === void 0 ? {} : { parentId: input.parentId },
+				name: input.name,
+				startUnixNano,
+				endUnixNano,
+				status,
+				...statusMessage === void 0 ? {} : { statusMessage },
+				attributes: Object.freeze({ ...attributes }),
+				events: Object.freeze([...events]),
+				...Object.keys(sensitivities).length === 0 ? {} : { sensitivityByAttribute: Object.freeze({ ...sensitivities }) }
+			};
+			input.sink(record);
+		}
+	};
+}
+
+//#endregion
+export { createSpan };
+//# sourceMappingURL=span.js.map

package/dist/tracer/span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.js","names":["attributes: Record<string, SpanAttributeValue>","sensitivities: Record<string, Sensitivity>","events: SpanRecord['events'][number][]","status: SpanStatus","statusMessage: string | undefined","attrs: SpanAttributes","record: SpanRecord<T>"],"sources":["../../src/tracer/span.ts"],"sourcesContent":["/**\n * Concrete `AISpan<T>` implementation. The span is intentionally\n * decoupled from `@opentelemetry/api`: the tracer materialises a\n * {@link SpanRecord} on `end()` and lets exporters do the rest.\n *\n * @packageDocumentation\n */\n\nimport type {\n  AISpan,\n  Sensitivity,\n  SpanAttributes,\n  SpanAttributeValue,\n  SpanStatus,\n  SpanType,\n} from '@graphorin/core';\n\nimport type { SpanRecord } from '../exporters/types.js';\n\n/**\n * Optional metadata accepted by `setAttribute(...)` to declare the\n * sensitivity of a single attribute. The validator uses the declared\n * tier when deciding whether to drop the attribute.\n *\n * @stable\n */\nexport interface SetAttributeOptions {\n  readonly sensitivity?: Sensitivity;\n}\n\n/**\n * The internal span carries the convenience `setAttribute(...)` method\n * exposed by the tracer surface (per-attribute sensitivity tagging) on\n * top of the standard {@link AISpan} contract.\n *\n * @stable\n */\nexport interface GraphorinSpan<T extends SpanType = SpanType> extends AISpan<T> {\n  setAttribute(name: string, value: SpanAttributeValue, opts?: SetAttributeOptions): void;\n}\n\n/**\n * @internal — sink invoked when a span ends.\n */\nexport type SpanSink = (record: SpanRecord) => void;\n\n/**\n * @internal — parameters passed by the tracer to {@link createSpan}.\n */\nexport interface SpanCreateInput<T extends SpanType = SpanType> {\n  readonly type: T;\n  readonly name: string;\n  readonly traceId: string;\n  readonly id: string;\n  readonly parentId?: string;\n  readonly attrs?: SpanAttributes;\n  readonly attrSensitivities?: Readonly<Record<string, Sensitivity>>;\n  readonly sink: SpanSink;\n  readonly now: () => number;\n  readonly recordEvent: (name: string) => boolean;\n}\n\n/**\n * @internal\n */\nexport function createSpan<T extends SpanType>(input: SpanCreateInput<T>): GraphorinSpan<T> {\n  const startUnixNano = Math.floor(input.now() * 1_000_000);\n  const attributes: Record<string, SpanAttributeValue> = { ...(input.attrs ?? {}) };\n  const sensitivities: Record<string, Sensitivity> = { ...(input.attrSensitivities ?? {}) };\n  const events: SpanRecord['events'][number][] = [];\n  let status: SpanStatus = 'ok';\n  let statusMessage: string | undefined;\n  let ended = false;\n\n  const span: GraphorinSpan<T> = {\n    type: input.type,\n    id: input.id,\n    traceId: input.traceId,\n    ...(input.parentId === undefined ? {} : { parentId: input.parentId }),\n    setAttributes(attrs: SpanAttributes): void {\n      if (ended) return;\n      for (const [k, v] of Object.entries(attrs)) {\n        attributes[k] = v;\n      }\n    },\n    setAttribute(name: string, value: SpanAttributeValue, opts?: SetAttributeOptions): void {\n      if (ended) return;\n      attributes[name] = value;\n      if (opts?.sensitivity !== undefined) {\n        sensitivities[name] = opts.sensitivity;\n      }\n    },\n    addEvent(name: string, attrs?: SpanAttributes): void {\n      if (ended) return;\n      if (!input.recordEvent(name)) return;\n      events.push({\n        name,\n        timeUnixNano: Math.floor(input.now() * 1_000_000),\n        attributes: Object.freeze({ ...(attrs ?? {}) }) as SpanAttributes,\n      });\n    },\n    recordException(err: unknown): void {\n      if (ended) return;\n      const e = err as { name?: unknown; message?: unknown; stack?: unknown };\n      const attrs: SpanAttributes = {\n        'exception.type': typeof e?.name === 'string' && e.name.length > 0 ? e.name : 'Error',\n        'exception.message': typeof e?.message === 'string' ? e.message : String(err),\n        ...(typeof e?.stack === 'string' ? { 'exception.stacktrace': e.stack } : {}),\n      };\n      events.push({\n        name: 'exception',\n        timeUnixNano: Math.floor(input.now() * 1_000_000),\n        attributes: attrs,\n      });\n    },\n    setStatus(s: SpanStatus, message?: string): void {\n      if (ended) return;\n      status = s;\n      if (message !== undefined) statusMessage = message;\n    },\n    end(): void {\n      if (ended) return;\n      ended = true;\n      const endUnixNano = Math.floor(input.now() * 1_000_000);\n      const record: SpanRecord<T> = {\n        type: input.type,\n        id: input.id,\n        traceId: input.traceId,\n        ...(input.parentId === undefined ? {} : { parentId: input.parentId }),\n        name: input.name,\n        startUnixNano,\n        endUnixNano,\n        status,\n        ...(statusMessage === undefined ? {} : { statusMessage }),\n        attributes: Object.freeze({ ...attributes }) as SpanAttributes,\n        events: Object.freeze([...events]) as SpanRecord['events'],\n        ...(Object.keys(sensitivities).length === 0\n          ? {}\n          : {\n              sensitivityByAttribute: Object.freeze({ ...sensitivities }) as Readonly<\n                Record<string, SpanAttributeValue>\n              >,\n            }),\n      };\n      input.sink(record);\n    },\n  };\n\n  return span;\n}\n"],"mappings":";;;;AAiEA,SAAgB,WAA+B,OAA6C;CAC1F,MAAM,gBAAgB,KAAK,MAAM,MAAM,KAAK,GAAG,IAAU;CACzD,MAAMA,aAAiD,EAAE,GAAI,MAAM,SAAS,EAAE,EAAG;CACjF,MAAMC,gBAA6C,EAAE,GAAI,MAAM,qBAAqB,EAAE,EAAG;CACzF,MAAMC,SAAyC,EAAE;CACjD,IAAIC,SAAqB;CACzB,IAAIC;CACJ,IAAI,QAAQ;AA4EZ,QA1E+B;EAC7B,MAAM,MAAM;EACZ,IAAI,MAAM;EACV,SAAS,MAAM;EACf,GAAI,MAAM,aAAa,SAAY,EAAE,GAAG,EAAE,UAAU,MAAM,UAAU;EACpE,cAAc,OAA6B;AACzC,OAAI,MAAO;AACX,QAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,MAAM,CACxC,YAAW,KAAK;;EAGpB,aAAa,MAAc,OAA2B,MAAkC;AACtF,OAAI,MAAO;AACX,cAAW,QAAQ;AACnB,OAAI,MAAM,gBAAgB,OACxB,eAAc,QAAQ,KAAK;;EAG/B,SAAS,MAAc,OAA8B;AACnD,OAAI,MAAO;AACX,OAAI,CAAC,MAAM,YAAY,KAAK,CAAE;AAC9B,UAAO,KAAK;IACV;IACA,cAAc,KAAK,MAAM,MAAM,KAAK,GAAG,IAAU;IACjD,YAAY,OAAO,OAAO,EAAE,GAAI,SAAS,EAAE,EAAG,CAAC;IAChD,CAAC;;EAEJ,gBAAgB,KAAoB;AAClC,OAAI,MAAO;GACX,MAAM,IAAI;GACV,MAAMC,QAAwB;IAC5B,kBAAkB,OAAO,GAAG,SAAS,YAAY,EAAE,KAAK,SAAS,IAAI,EAAE,OAAO;IAC9E,qBAAqB,OAAO,GAAG,YAAY,WAAW,EAAE,UAAU,OAAO,IAAI;IAC7E,GAAI,OAAO,GAAG,UAAU,WAAW,EAAE,wBAAwB,EAAE,OAAO,GAAG,EAAE;IAC5E;AACD,UAAO,KAAK;IACV,MAAM;IACN,cAAc,KAAK,MAAM,MAAM,KAAK,GAAG,IAAU;IACjD,YAAY;IACb,CAAC;;EAEJ,UAAU,GAAe,SAAwB;AAC/C,OAAI,MAAO;AACX,YAAS;AACT,OAAI,YAAY,OAAW,iBAAgB;;EAE7C,MAAY;AACV,OAAI,MAAO;AACX,WAAQ;GACR,MAAM,cAAc,KAAK,MAAM,MAAM,KAAK,GAAG,IAAU;GACvD,MAAMC,SAAwB;IAC5B,MAAM,MAAM;IACZ,IAAI,MAAM;IACV,SAAS,MAAM;IACf,GAAI,MAAM,aAAa,SAAY,EAAE,GAAG,EAAE,UAAU,MAAM,UAAU;IACpE,MAAM,MAAM;IACZ;IACA;IACA;IACA,GAAI,kBAAkB,SAAY,EAAE,GAAG,EAAE,eAAe;IACxD,YAAY,OAAO,OAAO,EAAE,GAAG,YAAY,CAAC;IAC5C,QAAQ,OAAO,OAAO,CAAC,GAAG,OAAO,CAAC;IAClC,GAAI,OAAO,KAAK,cAAc,CAAC,WAAW,IACtC,EAAE,GACF,EACE,wBAAwB,OAAO,OAAO,EAAE,GAAG,eAAe,CAAC,EAG5D;IACN;AACD,SAAM,KAAK,OAAO;;EAErB"}

package/dist/tracer/tracer.d.ts

@@ -0,0 +1,101 @@
+import { TraceExporter } from "../exporters/types.js";
+import { RedactionCounters, RedactionValidatorInstance, RedactionValidatorOptions } from "../redaction/types.js";
+import { SamplingOptions } from "./sampling.js";
+import { GraphorinSpan } from "./span.js";
+import { AISpan, Sensitivity, SpanType, Tracer } from "@graphorin/core";
+
+//#region src/tracer/tracer.d.ts
+
+/**
+ * Configuration shape consumed by {@link createTracer}.
+ *
+ * @stable
+ */
+interface TracerOptions {
+  /** Logical service name. Embedded in the OTLP `Resource`. */
+  readonly serviceName?: string;
+  /**
+   * Configured exporters. Each exporter MUST be wrapped via
+   * `withValidation(...)` before reaching the tracer — pass them
+   * through unwrapped to use the tracer-managed validator (set by
+   * `validation`) or pass already-wrapped exporters when you want
+   * per-exporter policies.
+   */
+  readonly exporters: ReadonlyArray<TraceExporter>;
+  /**
+   * Tracer-managed validator policy.
+   *
+   * - `RedactionValidatorOptions` (default): the tracer auto-wraps any
+   *   un-wrapped exporter with `withValidation(...)` using these
+   *   options.
+   * - `'off'`: NOT recommended. Skips auto-wrap, and the tracer logs a
+   *   startup WARN to the supplied {@link warnSink}. Pre-wrapped
+   *   exporters still flow through their validators.
+   *
+   * @default `{ minTier: 'public', failOnUnredactedSensitive: false }`
+   */
+  readonly validation?: RedactionValidatorOptions | 'off';
+  /** Sampler configuration. */
+  readonly sampling?: SamplingOptions;
+  /**
+   * Default sensitivity for attributes that omit `setAttribute(_, _, { sensitivity })`.
+   * Defaults to `'internal'` per the default-deny non-public posture.
+   */
+  readonly defaultAttributeSensitivity?: Sensitivity;
+  /**
+   * Sink used for startup WARNings. Defaults to `console.warn`.
+   *
+   * @internal
+   */
+  readonly warnSink?: (line: string) => void;
+  /**
+   * Override the wall clock used for span timestamps. Returns
+   * milliseconds-since-epoch as a `number`. Default: `Date.now`.
+   *
+   * @internal
+   */
+  readonly now?: () => number;
+}
+/**
+ * The {@link createTracer} return value extends the standard
+ * {@link Tracer} contract from `@graphorin/core` with introspection
+ * helpers (counter snapshots, validator handle).
+ *
+ * @stable
+ */
+interface GraphorinTracer extends Tracer {
+  /** Service name embedded in the OTLP resource. */
+  readonly serviceName: string;
+  /**
+   * Snapshot of the redaction counters (`droppedTotal`,
+   * `droppedByReason`, `matchesByPattern`) maintained by the
+   * tracer-managed validator.
+   */
+  getMetrics(): RedactionCounters;
+  /** The tracer-managed validator. `null` when `validation: 'off'`. */
+  readonly validator: RedactionValidatorInstance | null;
+  /** Force-flush every registered exporter. */
+  flush(): Promise<void>;
+}
+/**
+ * Build a {@link GraphorinTracer} from the supplied options. Every
+ * exporter passed in must already be wrapped via
+ * `withValidation(...)` OR `validation` must be set to a concrete
+ * options object so the tracer can auto-wrap on your behalf.
+ * Registering a raw exporter while `validation: 'off'` triggers an
+ * {@link UnvalidatedExporterError} at startup.
+ *
+ * @stable
+ */
+declare function createTracer(opts: TracerOptions): GraphorinTracer;
+/**
+ * Returns the underlying {@link GraphorinSpan} when `span` is a Graphorin
+ * span. Useful when callers want to reach the per-attribute sensitivity
+ * helper from a generic `AISpan<T>`.
+ *
+ * @stable
+ */
+declare function asGraphorinSpan<T extends SpanType>(span: AISpan<T>): GraphorinSpan<T> | null;
+//#endregion
+export { GraphorinTracer, TracerOptions, asGraphorinSpan, createTracer };
+//# sourceMappingURL=tracer.d.ts.map

package/dist/tracer/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","names":[],"sources":["../../src/tracer/tracer.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAuFA;;;AAYW,UAjEM,aAAA,CAiEN;EAZ8B;EAAM,SAAA,WAAA,CAAA,EAAA,MAAA;EA8B/B;AA0LhB;;;;;;EAAmF,SAAA,SAAA,EAnQ7D,aAmQ6D,CAnQ/C,aAmQ+C,CAAA;;;;;;;;;;;;;wBAtP3D;;sBAEF;;;;;yCAKmB;;;;;;;;;;;;;;;;;;;;;;UAuBxB,eAAA,SAAwB;;;;;;;;gBAAR;;sBAUX;;WAEX;;;;;;;;;;;;iBAkBK,YAAA,OAAmB,gBAAgB;;;;;;;;iBA0LnC,0BAA0B,gBAAgB,OAAO,KAAK,cAAc"}

package/dist/tracer/tracer.js

@@ -0,0 +1,150 @@
+import { createConsoleExporter } from "../exporters/console.js";
+import { UnvalidatedExporterError } from "../redaction/errors.js";
+import { createRedactionValidator } from "../redaction/validator.js";
+import { isValidatedExporter, withValidation } from "../exporters/with-validation.js";
+import { newSpanId, newTraceId } from "./ids.js";
+import { createSampler } from "./sampling.js";
+import { createSpan } from "./span.js";
+import { spanNameFor } from "./span-names.js";
+
+//#region src/tracer/tracer.ts
+const DEFAULT_VALIDATION = Object.freeze({
+	minTier: "public",
+	failOnUnredactedSensitive: false
+});
+/**
+* Build a {@link GraphorinTracer} from the supplied options. Every
+* exporter passed in must already be wrapped via
+* `withValidation(...)` OR `validation` must be set to a concrete
+* options object so the tracer can auto-wrap on your behalf.
+* Registering a raw exporter while `validation: 'off'` triggers an
+* {@link UnvalidatedExporterError} at startup.
+*
+* @stable
+*/
+function createTracer(opts) {
+	const serviceName = opts.serviceName ?? "graphorin";
+	const sampler = createSampler(opts.sampling ?? {});
+	const warnSink = opts.warnSink ?? ((line) => console.warn(line));
+	const now = opts.now ?? (() => Date.now());
+	const defaultAttrSensitivity = opts.defaultAttributeSensitivity ?? "internal";
+	const validationMode = opts.validation ?? DEFAULT_VALIDATION;
+	let validator = null;
+	let exporters = [];
+	if (validationMode === "off") {
+		warnSink("[graphorin/observability] WARN: validation: 'off' — exporters are NOT auto-wrapped. Every exporter must call withValidation(...) explicitly. See ADR-035: OTLP RedactionValidator + default-deny non-public.");
+		for (const exporter of opts.exporters) {
+			if (!isValidatedExporter(exporter)) throw new UnvalidatedExporterError(exporter.id);
+			exporters.push(exporter);
+		}
+	} else {
+		validator = createRedactionValidator(validationMode);
+		for (const exporter of opts.exporters) exporters.push(isValidatedExporter(exporter) ? exporter : withValidation(exporter, { validator }));
+	}
+	if (exporters.length === 0) {
+		const fallback = withValidation(createConsoleExporter({ id: "console-fallback" }), { validator: validator ?? createRedactionValidator(DEFAULT_VALIDATION) });
+		warnSink("[graphorin/observability] WARN: createTracer() received zero exporters. Falling back to a sanitized ConsoleExporter so spans are not lost.");
+		exporters = [fallback];
+	}
+	const inFlight = /* @__PURE__ */ new Set();
+	function sink(record) {
+		for (const exporter of exporters) {
+			const p = Promise.resolve().then(() => exporter.export(record)).catch((err) => {
+				warnSink(`[graphorin/observability] WARN: exporter ${exporter.id} failed: ${err instanceof Error ? err.message : String(err)}`);
+			});
+			inFlight.add(p);
+			p.finally(() => {
+				inFlight.delete(p);
+			});
+		}
+	}
+	function startSpan(spec) {
+		const traceId = spec.parent?.traceId ?? newTraceId();
+		const id = newSpanId();
+		const parentId = spec.parent?.id;
+		const parentSampled = spec.parent === void 0 ? void 0 : asGraphorinSpan(spec.parent) !== null;
+		if (!sampler.shouldSample(spec.type, parentSampled)) return noopSpan(spec.type, traceId, id, parentId);
+		const sensitivities = readAttrSensitivities(spec.attrs);
+		return createSpan({
+			type: spec.type,
+			name: spanNameFor(spec.type),
+			traceId,
+			id,
+			...parentId === void 0 ? {} : { parentId },
+			...spec.attrs === void 0 ? {} : { attrs: spec.attrs },
+			...sensitivities === void 0 ? {} : { attrSensitivities: sensitivities },
+			sink,
+			now,
+			recordEvent: (name) => sampler.shouldRecordEvent(name)
+		});
+	}
+	async function span(spec, fn) {
+		const s = startSpan(spec);
+		try {
+			const out = await fn(s);
+			s.setStatus("ok");
+			return out;
+		} catch (err) {
+			s.recordException(err);
+			s.setStatus("error", err instanceof Error ? err.message : String(err));
+			throw err;
+		} finally {
+			s.end();
+		}
+	}
+	async function flush() {
+		while (inFlight.size > 0) await Promise.all([...inFlight]);
+		await Promise.all(exporters.map((e) => e.flush()));
+	}
+	async function shutdown() {
+		await flush();
+		await Promise.all(exporters.map((e) => e.shutdown()));
+	}
+	return {
+		startSpan,
+		span,
+		flush,
+		shutdown,
+		serviceName,
+		getMetrics: () => validator?.counters() ?? {
+			droppedTotal: 0,
+			droppedByReason: Object.freeze({}),
+			matchesByPattern: Object.freeze({})
+		},
+		validator
+	};
+	function readAttrSensitivities(attrs) {
+		if (attrs === void 0) return void 0;
+		const out = {};
+		for (const key of Object.keys(attrs)) out[key] = defaultAttrSensitivity;
+		return Object.freeze(out);
+	}
+	function noopSpan(type, traceId, id, parentId) {
+		return {
+			type,
+			id,
+			traceId,
+			...parentId === void 0 ? {} : { parentId },
+			setAttributes() {},
+			addEvent() {},
+			recordException() {},
+			setStatus() {},
+			end() {}
+		};
+	}
+}
+/**
+* Returns the underlying {@link GraphorinSpan} when `span` is a Graphorin
+* span. Useful when callers want to reach the per-attribute sensitivity
+* helper from a generic `AISpan<T>`.
+*
+* @stable
+*/
+function asGraphorinSpan(span) {
+	if (typeof span.setAttribute === "function") return span;
+	return null;
+}
+
+//#endregion
+export { asGraphorinSpan, createTracer };
+//# sourceMappingURL=tracer.js.map

package/dist/tracer/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","names":["DEFAULT_VALIDATION: RedactionValidatorOptions","defaultAttrSensitivity: Sensitivity","validator: RedactionValidatorInstance | null","exporters: TraceExporter[]","out: Record<string, Sensitivity>"],"sources":["../../src/tracer/tracer.ts"],"sourcesContent":["/**\n * `createTracer(...)` — the public entry point for the observability\n * tracer. Wires together the {@link Sampler}, the\n * {@link RedactionValidator}, and the registered {@link TraceExporter}s.\n *\n * @packageDocumentation\n */\n\nimport type {\n  AISpan,\n  Sensitivity,\n  SpanAttributeValue,\n  SpanType,\n  StartSpanOptions,\n  Tracer,\n} from '@graphorin/core';\n\nimport { createConsoleExporter } from '../exporters/console.js';\nimport type { SpanRecord, TraceExporter } from '../exporters/types.js';\nimport { isValidatedExporter, withValidation } from '../exporters/with-validation.js';\nimport { UnvalidatedExporterError } from '../redaction/errors.js';\nimport type { RedactionValidatorInstance, RedactionValidatorOptions } from '../redaction/types.js';\nimport { createRedactionValidator } from '../redaction/validator.js';\n\nimport { newSpanId, newTraceId } from './ids.js';\nimport { createSampler, type SamplingOptions } from './sampling.js';\nimport { createSpan, type GraphorinSpan } from './span.js';\nimport { spanNameFor } from './span-names.js';\n\n/**\n * Configuration shape consumed by {@link createTracer}.\n *\n * @stable\n */\nexport interface TracerOptions {\n  /** Logical service name. Embedded in the OTLP `Resource`. */\n  readonly serviceName?: string;\n  /**\n   * Configured exporters. Each exporter MUST be wrapped via\n   * `withValidation(...)` before reaching the tracer — pass them\n   * through unwrapped to use the tracer-managed validator (set by\n   * `validation`) or pass already-wrapped exporters when you want\n   * per-exporter policies.\n   */\n  readonly exporters: ReadonlyArray<TraceExporter>;\n  /**\n   * Tracer-managed validator policy.\n   *\n   * - `RedactionValidatorOptions` (default): the tracer auto-wraps any\n   *   un-wrapped exporter with `withValidation(...)` using these\n   *   options.\n   * - `'off'`: NOT recommended. Skips auto-wrap, and the tracer logs a\n   *   startup WARN to the supplied {@link warnSink}. Pre-wrapped\n   *   exporters still flow through their validators.\n   *\n   * @default `{ minTier: 'public', failOnUnredactedSensitive: false }`\n   */\n  readonly validation?: RedactionValidatorOptions | 'off';\n  /** Sampler configuration. */\n  readonly sampling?: SamplingOptions;\n  /**\n   * Default sensitivity for attributes that omit `setAttribute(_, _, { sensitivity })`.\n   * Defaults to `'internal'` per the default-deny non-public posture.\n   */\n  readonly defaultAttributeSensitivity?: Sensitivity;\n  /**\n   * Sink used for startup WARNings. Defaults to `console.warn`.\n   *\n   * @internal\n   */\n  readonly warnSink?: (line: string) => void;\n  /**\n   * Override the wall clock used for span timestamps. Returns\n   * milliseconds-since-epoch as a `number`. Default: `Date.now`.\n   *\n   * @internal\n   */\n  readonly now?: () => number;\n}\n\n/**\n * The {@link createTracer} return value extends the standard\n * {@link Tracer} contract from `@graphorin/core` with introspection\n * helpers (counter snapshots, validator handle).\n *\n * @stable\n */\nexport interface GraphorinTracer extends Tracer {\n  /** Service name embedded in the OTLP resource. */\n  readonly serviceName: string;\n  /**\n   * Snapshot of the redaction counters (`droppedTotal`,\n   * `droppedByReason`, `matchesByPattern`) maintained by the\n   * tracer-managed validator.\n   */\n  getMetrics(): import('../redaction/types.js').RedactionCounters;\n  /** The tracer-managed validator. `null` when `validation: 'off'`. */\n  readonly validator: RedactionValidatorInstance | null;\n  /** Force-flush every registered exporter. */\n  flush(): Promise<void>;\n}\n\nconst DEFAULT_VALIDATION: RedactionValidatorOptions = Object.freeze({\n  minTier: 'public',\n  failOnUnredactedSensitive: false,\n});\n\n/**\n * Build a {@link GraphorinTracer} from the supplied options. Every\n * exporter passed in must already be wrapped via\n * `withValidation(...)` OR `validation` must be set to a concrete\n * options object so the tracer can auto-wrap on your behalf.\n * Registering a raw exporter while `validation: 'off'` triggers an\n * {@link UnvalidatedExporterError} at startup.\n *\n * @stable\n */\nexport function createTracer(opts: TracerOptions): GraphorinTracer {\n  const serviceName = opts.serviceName ?? 'graphorin';\n  const sampler = createSampler(opts.sampling ?? {});\n  const warnSink = opts.warnSink ?? ((line: string) => console.warn(line));\n  const now = opts.now ?? (() => Date.now());\n  const defaultAttrSensitivity: Sensitivity = opts.defaultAttributeSensitivity ?? 'internal';\n\n  const validationMode = opts.validation ?? DEFAULT_VALIDATION;\n\n  let validator: RedactionValidatorInstance | null = null;\n  let exporters: TraceExporter[] = [];\n\n  if (validationMode === 'off') {\n    warnSink(\n      \"[graphorin/observability] WARN: validation: 'off' — exporters are NOT \" +\n        'auto-wrapped. Every exporter must call withValidation(...) explicitly. ' +\n        'See ADR-035: OTLP RedactionValidator + default-deny non-public.',\n    );\n    for (const exporter of opts.exporters) {\n      if (!isValidatedExporter(exporter)) {\n        throw new UnvalidatedExporterError(exporter.id);\n      }\n      exporters.push(exporter);\n    }\n  } else {\n    validator = createRedactionValidator(validationMode);\n    for (const exporter of opts.exporters) {\n      exporters.push(\n        isValidatedExporter(exporter) ? exporter : withValidation(exporter, { validator }),\n      );\n    }\n  }\n\n  if (exporters.length === 0) {\n    // The tracer is still useful (it emits records to /dev/null) but\n    // we want to surface that explicitly so consumers don't think the\n    // logger is broken.\n    const fallback = withValidation(createConsoleExporter({ id: 'console-fallback' }), {\n      validator: validator ?? createRedactionValidator(DEFAULT_VALIDATION),\n    });\n    warnSink(\n      '[graphorin/observability] WARN: createTracer() received zero exporters. ' +\n        'Falling back to a sanitized ConsoleExporter so spans are not lost.',\n    );\n    exporters = [fallback];\n  }\n\n  // RP-20: sink() exports are fire-and-forget; hold each promise so flush()\n  // can await it. Without this a span emitted moments before shutdown is lost\n  // when the exporter's closed-guard trips before its export() resolves.\n  const inFlight = new Set<Promise<void>>();\n\n  function sink(record: SpanRecord): void {\n    for (const exporter of exporters) {\n      const p = Promise.resolve()\n        .then(() => exporter.export(record))\n        .catch((err: unknown) => {\n          warnSink(\n            `[graphorin/observability] WARN: exporter ${exporter.id} failed: ${\n              err instanceof Error ? err.message : String(err)\n            }`,\n          );\n        });\n      inFlight.add(p);\n      void p.finally(() => {\n        inFlight.delete(p);\n      });\n    }\n  }\n\n  function startSpan<T extends SpanType>(spec: StartSpanOptions<T>): AISpan<T> {\n    const traceId = spec.parent?.traceId ?? newTraceId();\n    const id = newSpanId();\n    const parentId = spec.parent?.id;\n    // RP-19: a real parent-sampled flag for `'parent-based'` sampling. An\n    // unsampled parent is a noop span (no `setAttribute`), so `asGraphorinSpan`\n    // returns null — `parentId !== undefined` used to treat that as\n    // parent-sampled and record the child as an orphan.\n    const parentSampled =\n      spec.parent === undefined ? undefined : asGraphorinSpan(spec.parent) !== null;\n    const sampled = sampler.shouldSample(spec.type, parentSampled);\n    if (!sampled) {\n      return noopSpan<T>(spec.type, traceId, id, parentId);\n    }\n    const sensitivities = readAttrSensitivities(spec.attrs);\n    return createSpan<T>({\n      type: spec.type,\n      name: spanNameFor(spec.type),\n      traceId,\n      id,\n      ...(parentId === undefined ? {} : { parentId }),\n      ...(spec.attrs === undefined ? {} : { attrs: spec.attrs }),\n      ...(sensitivities === undefined ? {} : { attrSensitivities: sensitivities }),\n      sink,\n      now,\n      recordEvent: (name) => sampler.shouldRecordEvent(name),\n    }) as unknown as AISpan<T>;\n  }\n\n  async function span<T extends SpanType, R>(\n    spec: StartSpanOptions<T>,\n    fn: (s: AISpan<T>) => R | Promise<R>,\n  ): Promise<R> {\n    const s = startSpan(spec);\n    try {\n      const out = await fn(s);\n      s.setStatus('ok');\n      return out;\n    } catch (err) {\n      s.recordException(err);\n      s.setStatus('error', err instanceof Error ? err.message : String(err));\n      throw err;\n    } finally {\n      s.end();\n    }\n  }\n\n  async function flush(): Promise<void> {\n    // RP-20: drain in-flight fire-and-forget exports first, then flush.\n    while (inFlight.size > 0) {\n      await Promise.all([...inFlight]);\n    }\n    await Promise.all(exporters.map((e) => e.flush()));\n  }\n\n  async function shutdown(): Promise<void> {\n    await flush();\n    await Promise.all(exporters.map((e) => e.shutdown()));\n  }\n\n  return {\n    startSpan,\n    span,\n    flush,\n    shutdown,\n    serviceName,\n    getMetrics: () =>\n      validator?.counters() ?? {\n        droppedTotal: 0,\n        droppedByReason: Object.freeze({}),\n        matchesByPattern: Object.freeze({}),\n      },\n    validator,\n  };\n\n  function readAttrSensitivities(\n    attrs: undefined | Readonly<Record<string, SpanAttributeValue>>,\n  ): Readonly<Record<string, Sensitivity>> | undefined {\n    if (attrs === undefined) return undefined;\n    // RP-19: initial attrs that omit an explicit `setAttribute(_, _, {\n    // sensitivity })` default to `defaultAttributeSensitivity`. Threading it\n    // here makes the knob effective — untagged framework attributes carry the\n    // configured tier instead of the validator's hardcoded fallback.\n    const out: Record<string, Sensitivity> = {};\n    for (const key of Object.keys(attrs)) out[key] = defaultAttrSensitivity;\n    return Object.freeze(out);\n  }\n\n  function noopSpan<T extends SpanType>(\n    type: T,\n    traceId: string,\n    id: string,\n    parentId?: string,\n  ): AISpan<T> {\n    const stub: AISpan<T> = {\n      type,\n      id,\n      traceId,\n      ...(parentId === undefined ? {} : { parentId }),\n      setAttributes() {},\n      addEvent() {},\n      recordException() {},\n      setStatus() {},\n      end() {},\n    };\n    return stub;\n  }\n}\n\n/**\n * Returns the underlying {@link GraphorinSpan} when `span` is a Graphorin\n * span. Useful when callers want to reach the per-attribute sensitivity\n * helper from a generic `AISpan<T>`.\n *\n * @stable\n */\nexport function asGraphorinSpan<T extends SpanType>(span: AISpan<T>): GraphorinSpan<T> | null {\n  if (typeof (span as Partial<GraphorinSpan<T>>).setAttribute === 'function') {\n    return span as GraphorinSpan<T>;\n  }\n  return null;\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,138 @@
+{
+  "name": "@graphorin/observability",
+  "version": "0.5.0",
+  "description": "Observability primitives for the Graphorin framework: typed AISpan tracer over OpenTelemetry, mandatory withValidation wrapper for every exporter, sensitivity-aware RedactionValidator with built-in PII / secret patterns, GenAI Semantic Conventions conformance helpers, OpenInference span-kind emission, structured logger with span correlation, append-only JSONL exporter for replay, sanitized replay primitives, hierarchical CostTracker, and a minimal inline eval runner alongside a zero-default telemetry stub.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/observability",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/observability"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "observability",
+    "tracing",
+    "opentelemetry",
+    "otel",
+    "gen-ai",
+    "openinference",
+    "redaction",
+    "pii",
+    "cost-tracking",
+    "replay",
+    "evals",
+    "logger"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tracer": {
+      "types": "./dist/tracer/index.d.ts",
+      "import": "./dist/tracer/index.js"
+    },
+    "./redaction": {
+      "types": "./dist/redaction/index.d.ts",
+      "import": "./dist/redaction/index.js"
+    },
+    "./redaction/patterns": {
+      "types": "./dist/redaction/patterns.d.ts",
+      "import": "./dist/redaction/patterns.js"
+    },
+    "./redaction/imperative-patterns": {
+      "types": "./dist/redaction/imperative-patterns.d.ts",
+      "import": "./dist/redaction/imperative-patterns.js"
+    },
+    "./exporters": {
+      "types": "./dist/exporters/index.d.ts",
+      "import": "./dist/exporters/index.js"
+    },
+    "./gen-ai": {
+      "types": "./dist/gen-ai/index.d.ts",
+      "import": "./dist/gen-ai/index.js"
+    },
+    "./openinference": {
+      "types": "./dist/openinference/index.d.ts",
+      "import": "./dist/openinference/index.js"
+    },
+    "./cost": {
+      "types": "./dist/cost/index.d.ts",
+      "import": "./dist/cost/index.js"
+    },
+    "./replay": {
+      "types": "./dist/replay/index.d.ts",
+      "import": "./dist/replay/index.js"
+    },
+    "./eval": {
+      "types": "./dist/eval/index.d.ts",
+      "import": "./dist/eval/index.js"
+    },
+    "./logger": {
+      "types": "./dist/logger/index.d.ts",
+      "import": "./dist/logger/index.js"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "import": "./dist/telemetry/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/core": "0.5.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-node": "^0.217.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": false
+    },
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
+    "@opentelemetry/sdk-node": "^0.217.0",
+    "fast-check": "^3.23.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}