@graphorin/observability 0.5.0

package/dist/exporters/types.js.map

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

package/dist/exporters/with-validation.d.ts

@@ -0,0 +1,45 @@
+import { TraceExporter } from "./types.js";
+import { RedactionCounters, RedactionValidatorInstance, RedactionValidatorOptions } from "../redaction/types.js";
+import { SpanAttributeValue, SpanAttributes } from "@graphorin/core";
+
+//#region src/exporters/with-validation.d.ts
+
+/**
+ * Options for {@link withValidation}.
+ *
+ * @stable
+ */
+interface WithValidationOptions extends RedactionValidatorOptions {
+  /**
+   * Optional pre-built validator. When supplied, the rest of the
+   * options on this object are ignored and the supplied validator is
+   * reused — useful for sharing one validator across multiple exporters.
+   */
+  readonly validator?: RedactionValidatorInstance;
+}
+/**
+ * Wrap an exporter so every span flows through a {@link RedactionValidator}
+ * before reaching the sink. Exporters that are not wrapped are rejected
+ * by the tracer at startup.
+ *
+ * @stable
+ */
+declare function withValidation<E extends TraceExporter>(exporter: E, opts?: WithValidationOptions): TraceExporter;
+/**
+ * Quickly check whether an exporter is the result of a previous
+ * {@link withValidation} call. The tracer uses this to fail fast at
+ * startup.
+ *
+ * @stable
+ */
+declare function isValidatedExporter(exporter: TraceExporter): boolean;
+/**
+ * Pull the counters out of any exporter wrapped by {@link withValidation}.
+ * Returns `null` for exporters that were never wrapped.
+ *
+ * @stable
+ */
+declare function tryGetValidatorCounters(validator: RedactionValidatorInstance): RedactionCounters;
+//#endregion
+export { WithValidationOptions, isValidatedExporter, tryGetValidatorCounters, withValidation };
+//# sourceMappingURL=with-validation.d.ts.map

package/dist/exporters/with-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-validation.d.ts","names":[],"sources":["../../src/exporters/with-validation.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgJA;AAUA;;;UAhIiB,qBAAA,SAA8B;;;;;;uBAMxB;;;;;;;;;iBAUP,yBAAyB,yBAC7B,UACJ,wBACL;;;;;;;;iBAmGa,mBAAA,WAA8B;;;;;;;iBAU9B,uBAAA,YAAmC,6BAA6B"}

package/dist/exporters/with-validation.js

@@ -0,0 +1,99 @@
+import { VALIDATED_EXPORTER_BRAND } from "./types.js";
+import { createRedactionValidator } from "../redaction/validator.js";
+
+//#region src/exporters/with-validation.ts
+const DEFAULT_ATTR_SENSITIVITY = "internal";
+/**
+* Wrap an exporter so every span flows through a {@link RedactionValidator}
+* before reaching the sink. Exporters that are not wrapped are rejected
+* by the tracer at startup.
+*
+* @stable
+*/
+function withValidation(exporter, opts = {}) {
+	const validator = opts.validator ?? createRedactionValidator(opts);
+	return {
+		id: `${exporter.id}+validated`,
+		[VALIDATED_EXPORTER_BRAND]: true,
+		async export(record) {
+			await exporter.export(sanitizeRecord(record, validator));
+		},
+		flush: () => exporter.flush(),
+		shutdown: () => exporter.shutdown()
+	};
+}
+/**
+* @internal
+*/
+function sanitizeRecord(record, validator) {
+	const sensitivities = record.sensitivityByAttribute ?? {};
+	const sanitizedAttrs = sanitizeAttributes(record.attributes, sensitivities, validator, record.type);
+	const sanitizedEvents = sanitizeEvents(record.events, validator, record.type);
+	return {
+		...record,
+		attributes: sanitizedAttrs,
+		events: sanitizedEvents
+	};
+}
+/**
+* @internal
+*/
+function sanitizeAttributes(attrs, sensitivities, validator, spanType) {
+	const out = {};
+	for (const [key, value] of Object.entries(attrs)) {
+		const tier = readTier(sensitivities[key]);
+		const result = validator.validate({
+			value,
+			tier,
+			context: spanType === void 0 ? { attribute: key } : {
+				attribute: key,
+				spanType
+			}
+		});
+		if (result === null) continue;
+		out[key] = result.value;
+	}
+	return Object.freeze(out);
+}
+/**
+* @internal
+*/
+function sanitizeEvents(events, validator, spanType) {
+	const out = [];
+	for (const event of events) {
+		const sanitizedAttrs = sanitizeAttributes(event.attributes, {}, validator, spanType);
+		out.push({
+			name: event.name,
+			timeUnixNano: event.timeUnixNano,
+			attributes: sanitizedAttrs
+		});
+	}
+	return out;
+}
+function readTier(value) {
+	if (value === "public" || value === "internal" || value === "secret") return value;
+	return DEFAULT_ATTR_SENSITIVITY;
+}
+/**
+* Quickly check whether an exporter is the result of a previous
+* {@link withValidation} call. The tracer uses this to fail fast at
+* startup.
+*
+* @stable
+*/
+function isValidatedExporter(exporter) {
+	return exporter[VALIDATED_EXPORTER_BRAND] === true;
+}
+/**
+* Pull the counters out of any exporter wrapped by {@link withValidation}.
+* Returns `null` for exporters that were never wrapped.
+*
+* @stable
+*/
+function tryGetValidatorCounters(validator) {
+	return validator.counters();
+}
+
+//#endregion
+export { isValidatedExporter, sanitizeRecord, tryGetValidatorCounters, withValidation };
+//# sourceMappingURL=with-validation.js.map

package/dist/exporters/with-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-validation.js","names":["DEFAULT_ATTR_SENSITIVITY: Sensitivity","out: Record<string, SpanAttributeValue>","out: SpanRecord['events'][number][]"],"sources":["../../src/exporters/with-validation.ts"],"sourcesContent":["/**\n * `withValidation(exporter, opts)` — the **mandatory wrapper** applied\n * to every exporter. Forwards each span record through a\n * `RedactionValidator` first; drops + counts when a value exceeds the\n * configured tier floor or matches a secret / PII pattern.\n *\n * @packageDocumentation\n */\n\nimport type { Sensitivity, SpanAttributes, SpanAttributeValue } from '@graphorin/core';\nimport type {\n  RedactionCounters,\n  RedactionValidatorInstance,\n  RedactionValidatorOptions,\n} from '../redaction/types.js';\nimport { createRedactionValidator } from '../redaction/validator.js';\n\nimport { type SpanRecord, type TraceExporter, VALIDATED_EXPORTER_BRAND } from './types.js';\n\nconst DEFAULT_ATTR_SENSITIVITY: Sensitivity = 'internal';\n\n/**\n * Options for {@link withValidation}.\n *\n * @stable\n */\nexport interface WithValidationOptions extends RedactionValidatorOptions {\n  /**\n   * Optional pre-built validator. When supplied, the rest of the\n   * options on this object are ignored and the supplied validator is\n   * reused — useful for sharing one validator across multiple exporters.\n   */\n  readonly validator?: RedactionValidatorInstance;\n}\n\n/**\n * Wrap an exporter so every span flows through a {@link RedactionValidator}\n * before reaching the sink. Exporters that are not wrapped are rejected\n * by the tracer at startup.\n *\n * @stable\n */\nexport function withValidation<E extends TraceExporter>(\n  exporter: E,\n  opts: WithValidationOptions = {},\n): TraceExporter {\n  const validator = opts.validator ?? createRedactionValidator(opts);\n  const wrapped: TraceExporter = {\n    id: `${exporter.id}+validated`,\n    [VALIDATED_EXPORTER_BRAND]: true,\n    async export(record: SpanRecord): Promise<void> {\n      // RP-18: the validator strips offending attributes (counting each drop)\n      // and always returns an exportable record — a single untagged or\n      // over-tier attribute no longer makes the whole span vanish from every\n      // exporter.\n      await exporter.export(sanitizeRecord(record, validator));\n    },\n    flush: () => exporter.flush(),\n    shutdown: () => exporter.shutdown(),\n  };\n  return wrapped;\n}\n\n/**\n * @internal\n */\nexport function sanitizeRecord(\n  record: SpanRecord,\n  validator: RedactionValidatorInstance,\n): SpanRecord {\n  const sensitivities = record.sensitivityByAttribute ?? {};\n  // RP-18: attribute-granular sanitization. Offending attributes are stripped\n  // (and counted by the validator); the span itself always survives so\n  // framework spans carrying untagged attributes still reach every exporter.\n  const sanitizedAttrs = sanitizeAttributes(\n    record.attributes,\n    sensitivities,\n    validator,\n    record.type,\n  );\n  const sanitizedEvents = sanitizeEvents(record.events, validator, record.type);\n  return {\n    ...record,\n    attributes: sanitizedAttrs,\n    events: sanitizedEvents,\n  };\n}\n\n/**\n * @internal\n */\nexport function sanitizeAttributes(\n  attrs: SpanAttributes,\n  sensitivities: Readonly<Record<string, SpanAttributeValue>>,\n  validator: RedactionValidatorInstance,\n  spanType?: string,\n): SpanAttributes {\n  const out: Record<string, SpanAttributeValue> = {};\n  for (const [key, value] of Object.entries(attrs)) {\n    const tier = readTier(sensitivities[key]);\n    const result = validator.validate({\n      value,\n      tier,\n      context: spanType === undefined ? { attribute: key } : { attribute: key, spanType },\n    });\n    if (result === null) {\n      // RP-18: this single attribute exceeded the floor (or matched a secret\n      // pattern). Strip it — the validator has already counted the drop — and\n      // keep the rest of the span rather than discarding the whole record.\n      continue;\n    }\n    out[key] = result.value as SpanAttributeValue;\n  }\n  return Object.freeze(out) as SpanAttributes;\n}\n\n/**\n * @internal\n */\nexport function sanitizeEvents(\n  events: SpanRecord['events'],\n  validator: RedactionValidatorInstance,\n  spanType?: string,\n): SpanRecord['events'] {\n  const out: SpanRecord['events'][number][] = [];\n  for (const event of events) {\n    const sanitizedAttrs = sanitizeAttributes(event.attributes, {}, validator, spanType);\n    out.push({ name: event.name, timeUnixNano: event.timeUnixNano, attributes: sanitizedAttrs });\n  }\n  return out;\n}\n\nfunction readTier(value: SpanAttributeValue | undefined): Sensitivity {\n  if (value === 'public' || value === 'internal' || value === 'secret') return value;\n  return DEFAULT_ATTR_SENSITIVITY;\n}\n\n/**\n * Quickly check whether an exporter is the result of a previous\n * {@link withValidation} call. The tracer uses this to fail fast at\n * startup.\n *\n * @stable\n */\nexport function isValidatedExporter(exporter: TraceExporter): boolean {\n  return exporter[VALIDATED_EXPORTER_BRAND] === true;\n}\n\n/**\n * Pull the counters out of any exporter wrapped by {@link withValidation}.\n * Returns `null` for exporters that were never wrapped.\n *\n * @stable\n */\nexport function tryGetValidatorCounters(validator: RedactionValidatorInstance): RedactionCounters {\n  return validator.counters();\n}\n"],"mappings":";;;;AAmBA,MAAMA,2BAAwC;;;;;;;;AAuB9C,SAAgB,eACd,UACA,OAA8B,EAAE,EACjB;CACf,MAAM,YAAY,KAAK,aAAa,yBAAyB,KAAK;AAclE,QAb+B;EAC7B,IAAI,GAAG,SAAS,GAAG;GAClB,2BAA2B;EAC5B,MAAM,OAAO,QAAmC;AAK9C,SAAM,SAAS,OAAO,eAAe,QAAQ,UAAU,CAAC;;EAE1D,aAAa,SAAS,OAAO;EAC7B,gBAAgB,SAAS,UAAU;EACpC;;;;;AAOH,SAAgB,eACd,QACA,WACY;CACZ,MAAM,gBAAgB,OAAO,0BAA0B,EAAE;CAIzD,MAAM,iBAAiB,mBACrB,OAAO,YACP,eACA,WACA,OAAO,KACR;CACD,MAAM,kBAAkB,eAAe,OAAO,QAAQ,WAAW,OAAO,KAAK;AAC7E,QAAO;EACL,GAAG;EACH,YAAY;EACZ,QAAQ;EACT;;;;;AAMH,SAAgB,mBACd,OACA,eACA,WACA,UACgB;CAChB,MAAMC,MAA0C,EAAE;AAClD,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,EAAE;EAChD,MAAM,OAAO,SAAS,cAAc,KAAK;EACzC,MAAM,SAAS,UAAU,SAAS;GAChC;GACA;GACA,SAAS,aAAa,SAAY,EAAE,WAAW,KAAK,GAAG;IAAE,WAAW;IAAK;IAAU;GACpF,CAAC;AACF,MAAI,WAAW,KAIb;AAEF,MAAI,OAAO,OAAO;;AAEpB,QAAO,OAAO,OAAO,IAAI;;;;;AAM3B,SAAgB,eACd,QACA,WACA,UACsB;CACtB,MAAMC,MAAsC,EAAE;AAC9C,MAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,iBAAiB,mBAAmB,MAAM,YAAY,EAAE,EAAE,WAAW,SAAS;AACpF,MAAI,KAAK;GAAE,MAAM,MAAM;GAAM,cAAc,MAAM;GAAc,YAAY;GAAgB,CAAC;;AAE9F,QAAO;;AAGT,SAAS,SAAS,OAAoD;AACpE,KAAI,UAAU,YAAY,UAAU,cAAc,UAAU,SAAU,QAAO;AAC7E,QAAO;;;;;;;;;AAUT,SAAgB,oBAAoB,UAAkC;AACpE,QAAO,SAAS,8BAA8B;;;;;;;;AAShD,SAAgB,wBAAwB,WAA0D;AAChG,QAAO,UAAU,UAAU"}

package/dist/gen-ai/emit.d.ts

@@ -0,0 +1,27 @@
+import { GenAIAttributes, GenAIMessage } from "./types.js";
+import { AISpan, SpanType } from "@graphorin/core";
+
+//#region src/gen-ai/emit.d.ts
+
+/**
+ * Attach the canonical `gen_ai.*` attribute set to a span. The helper
+ * is additive on the existing Graphorin-prefixed attributes and applies
+ * the per-attribute sensitivity defaults catalogue.
+ *
+ * @stable
+ */
+declare function emitGenAIAttributes<T extends SpanType>(span: AISpan<T>, attrs: GenAIAttributes): void;
+/**
+ * Emit per-message OpenTelemetry GenAI span events. The helper records
+ * one event per message — the per-message-event emission shape per the
+ * OTel semconv discipline (size-bounded individually; safer than the
+ * aggregate-attribute shape on large prompts).
+ *
+ * @stable
+ */
+declare function emitGenAIMessageEvents<T extends SpanType>(span: AISpan<T>, messages: ReadonlyArray<GenAIMessage>, opts?: {
+  readonly system?: string;
+}): void;
+//#endregion
+export { emitGenAIAttributes, emitGenAIMessageEvents };
+//# sourceMappingURL=emit.d.ts.map

package/dist/gen-ai/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","names":[],"sources":["../../src/gen-ai/emit.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBAsDgB,8BAA8B,gBACtC,OAAO,WACN;;;;;;;;;iBAoCO,iCAAiC,gBACzC,OAAO,cACH,cAAc"}

package/dist/gen-ai/emit.js

@@ -0,0 +1,88 @@
+import { asGraphorinSpan } from "../tracer/tracer.js";
+import { operationNameFor } from "./operation-mapping.js";
+
+//#region src/gen-ai/emit.ts
+const PUBLIC_KEY_PREFIXES = [
+	"gen_ai.system",
+	"gen_ai.request.model",
+	"gen_ai.response.model",
+	"gen_ai.response.id",
+	"gen_ai.response.finish_reasons",
+	"gen_ai.usage.input_tokens",
+	"gen_ai.usage.output_tokens",
+	"gen_ai.tool.name",
+	"gen_ai.tool.type",
+	"gen_ai.tool.call.id",
+	"gen_ai.tool.description",
+	"gen_ai.agent.id",
+	"gen_ai.agent.name",
+	"gen_ai.session.id",
+	"gen_ai.operation.name"
+];
+/**
+* Attach the canonical `gen_ai.*` attribute set to a span. The helper
+* is additive on the existing Graphorin-prefixed attributes and applies
+* the per-attribute sensitivity defaults catalogue.
+*
+* @stable
+*/
+function emitGenAIAttributes(span, attrs) {
+	const gs = asGraphorinSpan(span);
+	const operation = attrs.operation ?? operationNameFor(span.type);
+	if (operation !== void 0) setPublic(gs, span, "gen_ai.operation.name", operation);
+	if (attrs.system !== void 0) setPublic(gs, span, "gen_ai.system", attrs.system);
+	if (attrs.requestModel !== void 0) setPublic(gs, span, "gen_ai.request.model", attrs.requestModel);
+	if (attrs.responseModel !== void 0) setPublic(gs, span, "gen_ai.response.model", attrs.responseModel);
+	if (attrs.responseId !== void 0) setPublic(gs, span, "gen_ai.response.id", attrs.responseId);
+	if (attrs.inputTokens !== void 0) setPublic(gs, span, "gen_ai.usage.input_tokens", attrs.inputTokens);
+	if (attrs.outputTokens !== void 0) setPublic(gs, span, "gen_ai.usage.output_tokens", attrs.outputTokens);
+	if (attrs.finishReasons !== void 0) setPublic(gs, span, "gen_ai.response.finish_reasons", [...attrs.finishReasons]);
+	if (attrs.agentId !== void 0) setPublic(gs, span, "gen_ai.agent.id", attrs.agentId);
+	if (attrs.agentName !== void 0) setPublic(gs, span, "gen_ai.agent.name", attrs.agentName);
+	if (attrs.sessionId !== void 0) setPublic(gs, span, "gen_ai.session.id", attrs.sessionId);
+	if (attrs.toolName !== void 0) setPublic(gs, span, "gen_ai.tool.name", attrs.toolName);
+	if (attrs.toolType !== void 0) setPublic(gs, span, "gen_ai.tool.type", attrs.toolType);
+	if (attrs.toolCallId !== void 0) setPublic(gs, span, "gen_ai.tool.call.id", attrs.toolCallId);
+	if (attrs.toolDescription !== void 0) setPublic(gs, span, "gen_ai.tool.description", attrs.toolDescription);
+}
+/**
+* Emit per-message OpenTelemetry GenAI span events. The helper records
+* one event per message — the per-message-event emission shape per the
+* OTel semconv discipline (size-bounded individually; safer than the
+* aggregate-attribute shape on large prompts).
+*
+* @stable
+*/
+function emitGenAIMessageEvents(span, messages, opts = {}) {
+	for (const message of messages) span.addEvent(eventNameFor(message.role), buildEventAttrs(message, opts.system));
+}
+function eventNameFor(role) {
+	switch (role) {
+		case "system": return "gen_ai.system.message";
+		case "user": return "gen_ai.user.message";
+		case "assistant": return "gen_ai.assistant.message";
+		case "tool": return "gen_ai.tool.message";
+	}
+}
+function buildEventAttrs(message, system) {
+	const out = {
+		"gen_ai.message.role": message.role,
+		content: message.content
+	};
+	if (system !== void 0) out["gen_ai.system"] = system;
+	if (message.name !== void 0) out["gen_ai.message.name"] = message.name;
+	if (message.toolCallId !== void 0) out["gen_ai.tool.call.id"] = message.toolCallId;
+	if (message.toolCalls !== void 0 && message.toolCalls.length > 0) out["gen_ai.tool.calls"] = JSON.stringify(message.toolCalls);
+	return Object.freeze(out);
+}
+function setPublic(gs, span, key, value) {
+	if (gs !== null && PUBLIC_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}.`))) {
+		gs.setAttribute(key, value, { sensitivity: "public" });
+		return;
+	}
+	span.setAttributes({ [key]: value });
+}
+
+//#endregion
+export { emitGenAIAttributes, emitGenAIMessageEvents };
+//# sourceMappingURL=emit.js.map

package/dist/gen-ai/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","names":["out: Record<string, SpanAttributeValue>"],"sources":["../../src/gen-ai/emit.ts"],"sourcesContent":["/**\n * Emission helpers that attach OpenTelemetry GenAI semantic-convention\n * attributes / events to an existing span.\n *\n * The helpers are deliberately additive — they NEVER remove or rename\n * existing attributes. The new `gen_ai.*` family sits on top of the\n * Graphorin-prefixed family. Sensitivity defaults follow the catalogue\n * documented alongside the canonical mapping table:\n *\n * - `gen_ai.system` / `gen_ai.request.model` / `gen_ai.response.model` /\n *   `gen_ai.response.id` / `gen_ai.usage.{input,output}_tokens` /\n *   `gen_ai.response.finish_reasons` / `gen_ai.tool.{name,type,call.id,description}` /\n *   `gen_ai.agent.{id,name}` / `gen_ai.session.id` /\n *   `gen_ai.operation.name` → `'public'`\n * - `gen_ai.request.messages` / per-message events / `gen_ai.response.content`\n *   → `'internal'` (default-deny non-public per DEC-141)\n * - `gen_ai.tool.output` → inherits per-tool `Tool.sensitivity`\n *\n * @packageDocumentation\n */\n\nimport type { AISpan, SpanAttributes, SpanAttributeValue, SpanType } from '@graphorin/core';\n\nimport type { GraphorinSpan } from '../tracer/span.js';\nimport { asGraphorinSpan } from '../tracer/tracer.js';\n\nimport { operationNameFor } from './operation-mapping.js';\nimport type { GenAIAttributes, GenAIMessage, GenAIMessageRole } from './types.js';\n\nconst PUBLIC_KEY_PREFIXES = [\n  'gen_ai.system',\n  'gen_ai.request.model',\n  'gen_ai.response.model',\n  'gen_ai.response.id',\n  'gen_ai.response.finish_reasons',\n  'gen_ai.usage.input_tokens',\n  'gen_ai.usage.output_tokens',\n  'gen_ai.tool.name',\n  'gen_ai.tool.type',\n  'gen_ai.tool.call.id',\n  'gen_ai.tool.description',\n  'gen_ai.agent.id',\n  'gen_ai.agent.name',\n  'gen_ai.session.id',\n  'gen_ai.operation.name',\n] as const;\n\n/**\n * Attach the canonical `gen_ai.*` attribute set to a span. The helper\n * is additive on the existing Graphorin-prefixed attributes and applies\n * the per-attribute sensitivity defaults catalogue.\n *\n * @stable\n */\nexport function emitGenAIAttributes<T extends SpanType>(\n  span: AISpan<T>,\n  attrs: GenAIAttributes,\n): void {\n  const gs = asGraphorinSpan(span);\n  const operation = attrs.operation ?? operationNameFor(span.type);\n  if (operation !== undefined) setPublic(gs, span, 'gen_ai.operation.name', operation);\n\n  if (attrs.system !== undefined) setPublic(gs, span, 'gen_ai.system', attrs.system);\n  if (attrs.requestModel !== undefined)\n    setPublic(gs, span, 'gen_ai.request.model', attrs.requestModel);\n  if (attrs.responseModel !== undefined)\n    setPublic(gs, span, 'gen_ai.response.model', attrs.responseModel);\n  if (attrs.responseId !== undefined) setPublic(gs, span, 'gen_ai.response.id', attrs.responseId);\n  if (attrs.inputTokens !== undefined)\n    setPublic(gs, span, 'gen_ai.usage.input_tokens', attrs.inputTokens);\n  if (attrs.outputTokens !== undefined)\n    setPublic(gs, span, 'gen_ai.usage.output_tokens', attrs.outputTokens);\n  if (attrs.finishReasons !== undefined)\n    setPublic(gs, span, 'gen_ai.response.finish_reasons', [...attrs.finishReasons]);\n  if (attrs.agentId !== undefined) setPublic(gs, span, 'gen_ai.agent.id', attrs.agentId);\n  if (attrs.agentName !== undefined) setPublic(gs, span, 'gen_ai.agent.name', attrs.agentName);\n  if (attrs.sessionId !== undefined) setPublic(gs, span, 'gen_ai.session.id', attrs.sessionId);\n  if (attrs.toolName !== undefined) setPublic(gs, span, 'gen_ai.tool.name', attrs.toolName);\n  if (attrs.toolType !== undefined) setPublic(gs, span, 'gen_ai.tool.type', attrs.toolType);\n  if (attrs.toolCallId !== undefined) setPublic(gs, span, 'gen_ai.tool.call.id', attrs.toolCallId);\n  if (attrs.toolDescription !== undefined)\n    setPublic(gs, span, 'gen_ai.tool.description', attrs.toolDescription);\n}\n\n/**\n * Emit per-message OpenTelemetry GenAI span events. The helper records\n * one event per message — the per-message-event emission shape per the\n * OTel semconv discipline (size-bounded individually; safer than the\n * aggregate-attribute shape on large prompts).\n *\n * @stable\n */\nexport function emitGenAIMessageEvents<T extends SpanType>(\n  span: AISpan<T>,\n  messages: ReadonlyArray<GenAIMessage>,\n  opts: { readonly system?: string } = {},\n): void {\n  for (const message of messages) {\n    span.addEvent(eventNameFor(message.role), buildEventAttrs(message, opts.system));\n  }\n}\n\nfunction eventNameFor(role: GenAIMessageRole): string {\n  switch (role) {\n    case 'system':\n      return 'gen_ai.system.message';\n    case 'user':\n      return 'gen_ai.user.message';\n    case 'assistant':\n      return 'gen_ai.assistant.message';\n    case 'tool':\n      return 'gen_ai.tool.message';\n  }\n}\n\nfunction buildEventAttrs(message: GenAIMessage, system?: string): SpanAttributes {\n  const out: Record<string, SpanAttributeValue> = {\n    'gen_ai.message.role': message.role,\n    content: message.content,\n  };\n  if (system !== undefined) out['gen_ai.system'] = system;\n  if (message.name !== undefined) out['gen_ai.message.name'] = message.name;\n  if (message.toolCallId !== undefined) out['gen_ai.tool.call.id'] = message.toolCallId;\n  if (message.toolCalls !== undefined && message.toolCalls.length > 0) {\n    out['gen_ai.tool.calls'] = JSON.stringify(message.toolCalls);\n  }\n  return Object.freeze(out) as SpanAttributes;\n}\n\nfunction setPublic(\n  gs: GraphorinSpan | null,\n  span: AISpan,\n  key: string,\n  value: SpanAttributeValue,\n): void {\n  if (\n    gs !== null &&\n    PUBLIC_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}.`))\n  ) {\n    gs.setAttribute(key, value, { sensitivity: 'public' });\n    return;\n  }\n  span.setAttributes({ [key]: value });\n}\n"],"mappings":";;;;AA6BA,MAAM,sBAAsB;CAC1B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,SAAgB,oBACd,MACA,OACM;CACN,MAAM,KAAK,gBAAgB,KAAK;CAChC,MAAM,YAAY,MAAM,aAAa,iBAAiB,KAAK,KAAK;AAChE,KAAI,cAAc,OAAW,WAAU,IAAI,MAAM,yBAAyB,UAAU;AAEpF,KAAI,MAAM,WAAW,OAAW,WAAU,IAAI,MAAM,iBAAiB,MAAM,OAAO;AAClF,KAAI,MAAM,iBAAiB,OACzB,WAAU,IAAI,MAAM,wBAAwB,MAAM,aAAa;AACjE,KAAI,MAAM,kBAAkB,OAC1B,WAAU,IAAI,MAAM,yBAAyB,MAAM,cAAc;AACnE,KAAI,MAAM,eAAe,OAAW,WAAU,IAAI,MAAM,sBAAsB,MAAM,WAAW;AAC/F,KAAI,MAAM,gBAAgB,OACxB,WAAU,IAAI,MAAM,6BAA6B,MAAM,YAAY;AACrE,KAAI,MAAM,iBAAiB,OACzB,WAAU,IAAI,MAAM,8BAA8B,MAAM,aAAa;AACvE,KAAI,MAAM,kBAAkB,OAC1B,WAAU,IAAI,MAAM,kCAAkC,CAAC,GAAG,MAAM,cAAc,CAAC;AACjF,KAAI,MAAM,YAAY,OAAW,WAAU,IAAI,MAAM,mBAAmB,MAAM,QAAQ;AACtF,KAAI,MAAM,cAAc,OAAW,WAAU,IAAI,MAAM,qBAAqB,MAAM,UAAU;AAC5F,KAAI,MAAM,cAAc,OAAW,WAAU,IAAI,MAAM,qBAAqB,MAAM,UAAU;AAC5F,KAAI,MAAM,aAAa,OAAW,WAAU,IAAI,MAAM,oBAAoB,MAAM,SAAS;AACzF,KAAI,MAAM,aAAa,OAAW,WAAU,IAAI,MAAM,oBAAoB,MAAM,SAAS;AACzF,KAAI,MAAM,eAAe,OAAW,WAAU,IAAI,MAAM,uBAAuB,MAAM,WAAW;AAChG,KAAI,MAAM,oBAAoB,OAC5B,WAAU,IAAI,MAAM,2BAA2B,MAAM,gBAAgB;;;;;;;;;;AAWzE,SAAgB,uBACd,MACA,UACA,OAAqC,EAAE,EACjC;AACN,MAAK,MAAM,WAAW,SACpB,MAAK,SAAS,aAAa,QAAQ,KAAK,EAAE,gBAAgB,SAAS,KAAK,OAAO,CAAC;;AAIpF,SAAS,aAAa,MAAgC;AACpD,SAAQ,MAAR;EACE,KAAK,SACH,QAAO;EACT,KAAK,OACH,QAAO;EACT,KAAK,YACH,QAAO;EACT,KAAK,OACH,QAAO;;;AAIb,SAAS,gBAAgB,SAAuB,QAAiC;CAC/E,MAAMA,MAA0C;EAC9C,uBAAuB,QAAQ;EAC/B,SAAS,QAAQ;EAClB;AACD,KAAI,WAAW,OAAW,KAAI,mBAAmB;AACjD,KAAI,QAAQ,SAAS,OAAW,KAAI,yBAAyB,QAAQ;AACrE,KAAI,QAAQ,eAAe,OAAW,KAAI,yBAAyB,QAAQ;AAC3E,KAAI,QAAQ,cAAc,UAAa,QAAQ,UAAU,SAAS,EAChE,KAAI,uBAAuB,KAAK,UAAU,QAAQ,UAAU;AAE9D,QAAO,OAAO,OAAO,IAAI;;AAG3B,SAAS,UACP,IACA,MACA,KACA,OACM;AACN,KACE,OAAO,QACP,oBAAoB,MAAM,WAAW,QAAQ,UAAU,IAAI,WAAW,GAAG,OAAO,GAAG,CAAC,EACpF;AACA,KAAG,aAAa,KAAK,OAAO,EAAE,aAAa,UAAU,CAAC;AACtD;;AAEF,MAAK,cAAc,GAAG,MAAM,OAAO,CAAC"}

package/dist/gen-ai/index.d.ts

@@ -0,0 +1,5 @@
+import { GenAIAttributes, GenAIMessage, GenAIMessageRole, GenAIOperationName, GenAISystem, GenAIToolType, SpanTypeToOperationName } from "./types.js";
+import { emitGenAIAttributes, emitGenAIMessageEvents } from "./emit.js";
+import { OPERATION_NAME_TABLE, operationNameFor } from "./operation-mapping.js";
+import { PROVIDER_CLASS_TO_GEN_AI_SYSTEM, _resetGenAISystemWarningsForTesting, deriveGenAISystem, setGenAISystemWarnSink } from "./system-derivation.js";
+export { type GenAIAttributes, type GenAIMessage, type GenAIMessageRole, type GenAIOperationName, type GenAISystem, type GenAIToolType, OPERATION_NAME_TABLE, PROVIDER_CLASS_TO_GEN_AI_SYSTEM, type SpanTypeToOperationName, _resetGenAISystemWarningsForTesting, deriveGenAISystem, emitGenAIAttributes, emitGenAIMessageEvents, operationNameFor, setGenAISystemWarnSink };

package/dist/gen-ai/index.js

@@ -0,0 +1,5 @@
+import { OPERATION_NAME_TABLE, operationNameFor } from "./operation-mapping.js";
+import { emitGenAIAttributes, emitGenAIMessageEvents } from "./emit.js";
+import { PROVIDER_CLASS_TO_GEN_AI_SYSTEM, _resetGenAISystemWarningsForTesting, deriveGenAISystem, setGenAISystemWarnSink } from "./system-derivation.js";
+
+export { OPERATION_NAME_TABLE, PROVIDER_CLASS_TO_GEN_AI_SYSTEM, _resetGenAISystemWarningsForTesting, deriveGenAISystem, emitGenAIAttributes, emitGenAIMessageEvents, operationNameFor, setGenAISystemWarnSink };

package/dist/gen-ai/operation-mapping.d.ts

@@ -0,0 +1,24 @@
+import { GenAIOperationName } from "./types.js";
+import { SpanType } from "@graphorin/core";
+
+//#region src/gen-ai/operation-mapping.d.ts
+
+/**
+ * Resolve the canonical `gen_ai.operation.name` value for a Graphorin
+ * span type. Returns `undefined` if no mapping exists (e.g. for
+ * `replay.*` markers, which are emitted via a separate code path).
+ *
+ * @stable
+ */
+declare function operationNameFor(type: SpanType): GenAIOperationName | undefined;
+/**
+ * Full canonical span-to-operation table — exposed for tooling
+ * (documentation generators, fixture tests) that need to introspect
+ * the mapping.
+ *
+ * @stable
+ */
+declare const OPERATION_NAME_TABLE: ReadonlyArray<readonly [SpanType, GenAIOperationName]>;
+//#endregion
+export { OPERATION_NAME_TABLE, operationNameFor };
+//# sourceMappingURL=operation-mapping.d.ts.map

package/dist/gen-ai/operation-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-mapping.d.ts","names":[],"sources":["../../src/gen-ai/operation-mapping.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBA0EgB,gBAAA,OAAuB,WAAW;;;;;;;;cAWrC,sBAAsB,wBAAwB,UAAU"}

package/dist/gen-ai/operation-mapping.js

@@ -0,0 +1,67 @@
+//#region src/gen-ai/operation-mapping.ts
+const TABLE = Object.freeze([
+	["agent.run", "agent.run"],
+	["agent.step", "agent.step"],
+	["agent.handoff", "agent.handoff"],
+	["agent.suspend", "agent.suspend"],
+	["agent.resume", "agent.resume"],
+	["provider.generate", "chat"],
+	["provider.stream", "chat"],
+	["tool.execute", "execute_tool"],
+	["tool.approval", "execute_tool"],
+	["memory.read.working", "memory.read"],
+	["memory.read.session", "memory.read"],
+	["memory.read.episodic", "memory.read"],
+	["memory.read.semantic", "memory.read"],
+	["memory.read.procedural", "memory.read"],
+	["memory.read.shared", "memory.read"],
+	["memory.write.working", "memory.write"],
+	["memory.write.session", "memory.write"],
+	["memory.write.episodic", "memory.write"],
+	["memory.write.semantic", "memory.write"],
+	["memory.write.procedural", "memory.write"],
+	["memory.write.shared", "memory.write"],
+	["memory.search.working", "memory.search"],
+	["memory.search.session", "memory.search"],
+	["memory.search.episodic", "memory.search"],
+	["memory.search.semantic", "memory.search"],
+	["memory.search.procedural", "memory.search"],
+	["memory.search.shared", "memory.search"],
+	["memory.consolidate.light", "memory.consolidate"],
+	["memory.consolidate.standard", "memory.consolidate"],
+	["memory.consolidate.deep", "memory.consolidate"],
+	["memory.conflict", "memory.conflict"],
+	["memory.embed", "embedding"],
+	["workflow.run", "workflow.run"],
+	["workflow.step", "workflow.step"],
+	["workflow.task", "workflow.task"],
+	["workflow.checkpoint", "workflow.checkpoint"],
+	["skill.activate", "skill.activate"],
+	["skill.load", "skill.load"],
+	["mcp.connect", "mcp.connect"],
+	["mcp.call", "mcp.call"],
+	["mcp.list-tools", "mcp.list-tools"]
+]);
+const LOOKUP = new Map(TABLE);
+/**
+* Resolve the canonical `gen_ai.operation.name` value for a Graphorin
+* span type. Returns `undefined` if no mapping exists (e.g. for
+* `replay.*` markers, which are emitted via a separate code path).
+*
+* @stable
+*/
+function operationNameFor(type) {
+	return LOOKUP.get(type);
+}
+/**
+* Full canonical span-to-operation table — exposed for tooling
+* (documentation generators, fixture tests) that need to introspect
+* the mapping.
+*
+* @stable
+*/
+const OPERATION_NAME_TABLE = TABLE;
+
+//#endregion
+export { OPERATION_NAME_TABLE, operationNameFor };
+//# sourceMappingURL=operation-mapping.js.map

package/dist/gen-ai/operation-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-mapping.js","names":["TABLE: ReadonlyArray<readonly [SpanType, GenAIOperationName]>","OPERATION_NAME_TABLE: ReadonlyArray<readonly [SpanType, GenAIOperationName]>"],"sources":["../../src/gen-ai/operation-mapping.ts"],"sourcesContent":["/**\n * Mapping table from Graphorin `SpanType` values to canonical\n * `gen_ai.operation.name` enum values.\n *\n * The table mirrors the canonical-mapping reference table published\n * in the architecture documentation and is the authoritative source\n * for the `emitGenAIAttributes` helper.\n *\n * @packageDocumentation\n */\n\nimport type { SpanType } from '@graphorin/core';\n\nimport type { GenAIOperationName } from './types.js';\n\nconst TABLE: ReadonlyArray<readonly [SpanType, GenAIOperationName]> = Object.freeze([\n  ['agent.run', 'agent.run'],\n  ['agent.step', 'agent.step'],\n  ['agent.handoff', 'agent.handoff'],\n  ['agent.suspend', 'agent.suspend'],\n  ['agent.resume', 'agent.resume'],\n\n  ['provider.generate', 'chat'],\n  ['provider.stream', 'chat'],\n\n  ['tool.execute', 'execute_tool'],\n  ['tool.approval', 'execute_tool'],\n\n  ['memory.read.working', 'memory.read'],\n  ['memory.read.session', 'memory.read'],\n  ['memory.read.episodic', 'memory.read'],\n  ['memory.read.semantic', 'memory.read'],\n  ['memory.read.procedural', 'memory.read'],\n  ['memory.read.shared', 'memory.read'],\n  ['memory.write.working', 'memory.write'],\n  ['memory.write.session', 'memory.write'],\n  ['memory.write.episodic', 'memory.write'],\n  ['memory.write.semantic', 'memory.write'],\n  ['memory.write.procedural', 'memory.write'],\n  ['memory.write.shared', 'memory.write'],\n  ['memory.search.working', 'memory.search'],\n  ['memory.search.session', 'memory.search'],\n  ['memory.search.episodic', 'memory.search'],\n  ['memory.search.semantic', 'memory.search'],\n  ['memory.search.procedural', 'memory.search'],\n  ['memory.search.shared', 'memory.search'],\n  ['memory.consolidate.light', 'memory.consolidate'],\n  ['memory.consolidate.standard', 'memory.consolidate'],\n  ['memory.consolidate.deep', 'memory.consolidate'],\n  ['memory.conflict', 'memory.conflict'],\n  ['memory.embed', 'embedding'],\n\n  ['workflow.run', 'workflow.run'],\n  ['workflow.step', 'workflow.step'],\n  ['workflow.task', 'workflow.task'],\n  ['workflow.checkpoint', 'workflow.checkpoint'],\n\n  ['skill.activate', 'skill.activate'],\n  ['skill.load', 'skill.load'],\n\n  ['mcp.connect', 'mcp.connect'],\n  ['mcp.call', 'mcp.call'],\n  ['mcp.list-tools', 'mcp.list-tools'],\n] as const);\n\nconst LOOKUP = new Map<SpanType, GenAIOperationName>(TABLE);\n\n/**\n * Resolve the canonical `gen_ai.operation.name` value for a Graphorin\n * span type. Returns `undefined` if no mapping exists (e.g. for\n * `replay.*` markers, which are emitted via a separate code path).\n *\n * @stable\n */\nexport function operationNameFor(type: SpanType): GenAIOperationName | undefined {\n  return LOOKUP.get(type);\n}\n\n/**\n * Full canonical span-to-operation table — exposed for tooling\n * (documentation generators, fixture tests) that need to introspect\n * the mapping.\n *\n * @stable\n */\nexport const OPERATION_NAME_TABLE: ReadonlyArray<readonly [SpanType, GenAIOperationName]> = TABLE;\n"],"mappings":";AAeA,MAAMA,QAAgE,OAAO,OAAO;CAClF,CAAC,aAAa,YAAY;CAC1B,CAAC,cAAc,aAAa;CAC5B,CAAC,iBAAiB,gBAAgB;CAClC,CAAC,iBAAiB,gBAAgB;CAClC,CAAC,gBAAgB,eAAe;CAEhC,CAAC,qBAAqB,OAAO;CAC7B,CAAC,mBAAmB,OAAO;CAE3B,CAAC,gBAAgB,eAAe;CAChC,CAAC,iBAAiB,eAAe;CAEjC,CAAC,uBAAuB,cAAc;CACtC,CAAC,uBAAuB,cAAc;CACtC,CAAC,wBAAwB,cAAc;CACvC,CAAC,wBAAwB,cAAc;CACvC,CAAC,0BAA0B,cAAc;CACzC,CAAC,sBAAsB,cAAc;CACrC,CAAC,wBAAwB,eAAe;CACxC,CAAC,wBAAwB,eAAe;CACxC,CAAC,yBAAyB,eAAe;CACzC,CAAC,yBAAyB,eAAe;CACzC,CAAC,2BAA2B,eAAe;CAC3C,CAAC,uBAAuB,eAAe;CACvC,CAAC,yBAAyB,gBAAgB;CAC1C,CAAC,yBAAyB,gBAAgB;CAC1C,CAAC,0BAA0B,gBAAgB;CAC3C,CAAC,0BAA0B,gBAAgB;CAC3C,CAAC,4BAA4B,gBAAgB;CAC7C,CAAC,wBAAwB,gBAAgB;CACzC,CAAC,4BAA4B,qBAAqB;CAClD,CAAC,+BAA+B,qBAAqB;CACrD,CAAC,2BAA2B,qBAAqB;CACjD,CAAC,mBAAmB,kBAAkB;CACtC,CAAC,gBAAgB,YAAY;CAE7B,CAAC,gBAAgB,eAAe;CAChC,CAAC,iBAAiB,gBAAgB;CAClC,CAAC,iBAAiB,gBAAgB;CAClC,CAAC,uBAAuB,sBAAsB;CAE9C,CAAC,kBAAkB,iBAAiB;CACpC,CAAC,cAAc,aAAa;CAE5B,CAAC,eAAe,cAAc;CAC9B,CAAC,YAAY,WAAW;CACxB,CAAC,kBAAkB,iBAAiB;CACrC,CAAU;AAEX,MAAM,SAAS,IAAI,IAAkC,MAAM;;;;;;;;AAS3D,SAAgB,iBAAiB,MAAgD;AAC/E,QAAO,OAAO,IAAI,KAAK;;;;;;;;;AAUzB,MAAaC,uBAA+E"}

package/dist/gen-ai/system-derivation.d.ts

@@ -0,0 +1,41 @@
+import { GenAISystem } from "./types.js";
+
+//#region src/gen-ai/system-derivation.d.ts
+
+/**
+ * Canonical mapping from a provider class name (or substring) to the
+ * `gen_ai.system` enum value. The table is an export so consumers
+ * (e.g. provider adapters in Phase 06) can introspect or extend it.
+ *
+ * @stable
+ */
+declare const PROVIDER_CLASS_TO_GEN_AI_SYSTEM: ReadonlyArray<readonly [RegExp, GenAISystem]>;
+/**
+ * Override the WARN-once sink used for unrecognised provider class
+ * names. Useful in tests so the suite does not pollute stderr.
+ *
+ * @internal
+ */
+declare function setGenAISystemWarnSink(sink: (line: string) => void): void;
+/**
+ * Reset the WARN-once cache. Test-only.
+ *
+ * @internal
+ */
+declare function _resetGenAISystemWarningsForTesting(): void;
+/**
+ * Derive the canonical `gen_ai.system` value from a provider class
+ * name. Returns `null` when the name does not match any known
+ * pattern; callers should declare `Provider.genAiSystem` explicitly
+ * in that case.
+ *
+ * The first time an unknown class name is seen, the function emits
+ * one structured WARN line to the configured sink so operators
+ * notice the gap. Subsequent lookups for the same class are silent.
+ *
+ * @stable
+ */
+declare function deriveGenAISystem(providerClassName: string): GenAISystem | null;
+//#endregion
+export { PROVIDER_CLASS_TO_GEN_AI_SYSTEM, _resetGenAISystemWarningsForTesting, deriveGenAISystem, setGenAISystemWarnSink };
+//# sourceMappingURL=system-derivation.d.ts.map

package/dist/gen-ai/system-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-derivation.d.ts","names":[],"sources":["../../src/gen-ai/system-derivation.ts"],"sourcesContent":[],"mappings":";;;;;;AAwCA;AASA;AAgBA;;;cAlDa,iCAAiC,wBAAwB,QAAQ;;;;;;;iBAyB9D,sBAAA;;;;;;iBASA,mCAAA,CAAA;;;;;;;;;;;;;iBAgBA,iBAAA,6BAA8C"}

package/dist/gen-ai/system-derivation.js

@@ -0,0 +1,67 @@
+//#region src/gen-ai/system-derivation.ts
+/**
+* Canonical mapping from a provider class name (or substring) to the
+* `gen_ai.system` enum value. The table is an export so consumers
+* (e.g. provider adapters in Phase 06) can introspect or extend it.
+*
+* @stable
+*/
+const PROVIDER_CLASS_TO_GEN_AI_SYSTEM = Object.freeze([
+	[/anthropic/i, "anthropic"],
+	[/openai(?!compat)/i, "openai"],
+	[/google|gemini/i, "google"],
+	[/mistral/i, "mistral"],
+	[/ollama/i, "ollama"],
+	[/openrouter/i, "openrouter"],
+	[/azure/i, "azure_ai_inference"],
+	[/bedrock|aws/i, "aws.bedrock"],
+	[/cohere/i, "cohere"],
+	[/vertex/i, "vertex_ai"],
+	[/llamacpp|llama-cpp|llama_cpp/i, "graphorin-llamacpp"],
+	[/openaicompatible|openai-compatible/i, "graphorin-openai-compatible"]
+]);
+const WARNED_CLASSES = /* @__PURE__ */ new Set();
+let WARN_SINK = (line) => console.warn(line);
+/**
+* Override the WARN-once sink used for unrecognised provider class
+* names. Useful in tests so the suite does not pollute stderr.
+*
+* @internal
+*/
+function setGenAISystemWarnSink(sink) {
+	WARN_SINK = sink;
+}
+/**
+* Reset the WARN-once cache. Test-only.
+*
+* @internal
+*/
+function _resetGenAISystemWarningsForTesting() {
+	WARNED_CLASSES.clear();
+}
+/**
+* Derive the canonical `gen_ai.system` value from a provider class
+* name. Returns `null` when the name does not match any known
+* pattern; callers should declare `Provider.genAiSystem` explicitly
+* in that case.
+*
+* The first time an unknown class name is seen, the function emits
+* one structured WARN line to the configured sink so operators
+* notice the gap. Subsequent lookups for the same class are silent.
+*
+* @stable
+*/
+function deriveGenAISystem(providerClassName) {
+	for (const [regex, system] of PROVIDER_CLASS_TO_GEN_AI_SYSTEM) if (regex.test(providerClassName)) return system;
+	warnOnce(providerClassName);
+	return null;
+}
+function warnOnce(providerClassName) {
+	if (WARNED_CLASSES.has(providerClassName)) return;
+	WARNED_CLASSES.add(providerClassName);
+	WARN_SINK(`[graphorin/observability] WARN: provider class "${providerClassName}" is not in the auto-derivation table for \`gen_ai.system\`. Declare \`Provider.genAiSystem\` explicitly on the adapter so OpenTelemetry GenAI dashboards attribute the spans correctly. See \`@graphorin/observability/gen-ai\` and the OpenTelemetry GenAI semantic conventions for the canonical vendor enum.`);
+}
+
+//#endregion
+export { PROVIDER_CLASS_TO_GEN_AI_SYSTEM, _resetGenAISystemWarningsForTesting, deriveGenAISystem, setGenAISystemWarnSink };
+//# sourceMappingURL=system-derivation.js.map

package/dist/gen-ai/system-derivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-derivation.js","names":["PROVIDER_CLASS_TO_GEN_AI_SYSTEM: ReadonlyArray<readonly [RegExp, GenAISystem]>","WARN_SINK: (line: string) => void"],"sources":["../../src/gen-ai/system-derivation.ts"],"sourcesContent":["/**\n * Auto-derivation lookup table for the `gen_ai.system` attribute.\n *\n * @packageDocumentation\n */\n\nimport type { GenAISystem } from './types.js';\n\n/**\n * Canonical mapping from a provider class name (or substring) to the\n * `gen_ai.system` enum value. The table is an export so consumers\n * (e.g. provider adapters in Phase 06) can introspect or extend it.\n *\n * @stable\n */\nexport const PROVIDER_CLASS_TO_GEN_AI_SYSTEM: ReadonlyArray<readonly [RegExp, GenAISystem]> =\n  Object.freeze([\n    [/anthropic/i, 'anthropic'],\n    [/openai(?!compat)/i, 'openai'],\n    [/google|gemini/i, 'google'],\n    [/mistral/i, 'mistral'],\n    [/ollama/i, 'ollama'],\n    [/openrouter/i, 'openrouter'],\n    [/azure/i, 'azure_ai_inference'],\n    [/bedrock|aws/i, 'aws.bedrock'],\n    [/cohere/i, 'cohere'],\n    [/vertex/i, 'vertex_ai'],\n    [/llamacpp|llama-cpp|llama_cpp/i, 'graphorin-llamacpp'],\n    [/openaicompatible|openai-compatible/i, 'graphorin-openai-compatible'],\n  ] as const);\n\nconst WARNED_CLASSES = new Set<string>();\nlet WARN_SINK: (line: string) => void = (line) => console.warn(line);\n\n/**\n * Override the WARN-once sink used for unrecognised provider class\n * names. Useful in tests so the suite does not pollute stderr.\n *\n * @internal\n */\nexport function setGenAISystemWarnSink(sink: (line: string) => void): void {\n  WARN_SINK = sink;\n}\n\n/**\n * Reset the WARN-once cache. Test-only.\n *\n * @internal\n */\nexport function _resetGenAISystemWarningsForTesting(): void {\n  WARNED_CLASSES.clear();\n}\n\n/**\n * Derive the canonical `gen_ai.system` value from a provider class\n * name. Returns `null` when the name does not match any known\n * pattern; callers should declare `Provider.genAiSystem` explicitly\n * in that case.\n *\n * The first time an unknown class name is seen, the function emits\n * one structured WARN line to the configured sink so operators\n * notice the gap. Subsequent lookups for the same class are silent.\n *\n * @stable\n */\nexport function deriveGenAISystem(providerClassName: string): GenAISystem | null {\n  for (const [regex, system] of PROVIDER_CLASS_TO_GEN_AI_SYSTEM) {\n    if (regex.test(providerClassName)) return system;\n  }\n  warnOnce(providerClassName);\n  return null;\n}\n\nfunction warnOnce(providerClassName: string): void {\n  if (WARNED_CLASSES.has(providerClassName)) return;\n  WARNED_CLASSES.add(providerClassName);\n  WARN_SINK(\n    `[graphorin/observability] WARN: provider class \"${providerClassName}\" is not in ` +\n      'the auto-derivation table for `gen_ai.system`. Declare `Provider.genAiSystem` ' +\n      'explicitly on the adapter so OpenTelemetry GenAI dashboards attribute the spans ' +\n      'correctly. See `@graphorin/observability/gen-ai` and the OpenTelemetry GenAI ' +\n      'semantic conventions for the canonical vendor enum.',\n  );\n}\n"],"mappings":";;;;;;;;AAeA,MAAaA,kCACX,OAAO,OAAO;CACZ,CAAC,cAAc,YAAY;CAC3B,CAAC,qBAAqB,SAAS;CAC/B,CAAC,kBAAkB,SAAS;CAC5B,CAAC,YAAY,UAAU;CACvB,CAAC,WAAW,SAAS;CACrB,CAAC,eAAe,aAAa;CAC7B,CAAC,UAAU,qBAAqB;CAChC,CAAC,gBAAgB,cAAc;CAC/B,CAAC,WAAW,SAAS;CACrB,CAAC,WAAW,YAAY;CACxB,CAAC,iCAAiC,qBAAqB;CACvD,CAAC,uCAAuC,8BAA8B;CACvE,CAAU;AAEb,MAAM,iCAAiB,IAAI,KAAa;AACxC,IAAIC,aAAqC,SAAS,QAAQ,KAAK,KAAK;;;;;;;AAQpE,SAAgB,uBAAuB,MAAoC;AACzE,aAAY;;;;;;;AAQd,SAAgB,sCAA4C;AAC1D,gBAAe,OAAO;;;;;;;;;;;;;;AAexB,SAAgB,kBAAkB,mBAA+C;AAC/E,MAAK,MAAM,CAAC,OAAO,WAAW,gCAC5B,KAAI,MAAM,KAAK,kBAAkB,CAAE,QAAO;AAE5C,UAAS,kBAAkB;AAC3B,QAAO;;AAGT,SAAS,SAAS,mBAAiC;AACjD,KAAI,eAAe,IAAI,kBAAkB,CAAE;AAC3C,gBAAe,IAAI,kBAAkB;AACrC,WACE,mDAAmD,kBAAkB,kTAKtE"}

package/dist/gen-ai/types.d.ts

@@ -0,0 +1,87 @@
+import { SpanType } from "@graphorin/core";
+
+//#region src/gen-ai/types.d.ts
+
+/**
+ * Canonical OpenTelemetry semantic-conventions vendor enum used as the
+ * value of the `gen_ai.system` attribute.
+ *
+ * @stable
+ */
+type GenAISystem = 'anthropic' | 'openai' | 'google' | 'mistral' | 'ollama' | 'openrouter' | 'azure_ai_inference' | 'aws.bedrock' | 'cohere' | 'vertex_ai' | 'graphorin-llamacpp' | 'graphorin-openai-compatible' | (string & {
+  readonly __genAiSystem?: never;
+});
+/**
+ * `gen_ai.tool.type` enum value. Defaults to `'function'` for
+ * user-defined and MCP-derived tools without explicit declaration.
+ *
+ * @stable
+ */
+type GenAIToolType = 'function' | 'web_search' | 'database' | 'code_interpreter' | 'image_generation' | 'file_search';
+/**
+ * Canonical `gen_ai.operation.name` enum used per the OpenTelemetry
+ * GenAI semantic conventions for AI agent + framework spans.
+ *
+ * @stable
+ */
+type GenAIOperationName = 'agent.run' | 'agent.step' | 'agent.handoff' | 'agent.suspend' | 'agent.resume' | 'agent.fanout.spawned' | 'agent.fanout.merged' | 'agent.evaluator.iteration' | 'chat' | 'embedding' | 'execute_tool' | 'memory.read' | 'memory.write' | 'memory.search' | 'memory.consolidate' | 'memory.conflict' | 'workflow.run' | 'workflow.step' | 'workflow.task' | 'workflow.checkpoint' | 'mcp.connect' | 'mcp.call' | 'mcp.list-tools' | 'skill.activate' | 'skill.load' | 'replay.run' | 'replay.skipped';
+/**
+ * Per-message event type used by {@link emitGenAIMessageEvents}.
+ *
+ * @stable
+ */
+type GenAIMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * Single per-message record passed to {@link emitGenAIMessageEvents}.
+ *
+ * @stable
+ */
+interface GenAIMessage {
+  readonly role: GenAIMessageRole;
+  readonly content: string;
+  /** Optional model-specific metadata (tool calls, names, …). */
+  readonly toolCalls?: ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+  }>;
+  readonly toolCallId?: string;
+  readonly name?: string;
+}
+/**
+ * Per-span attribute payload expected by {@link emitGenAIAttributes}.
+ * The fields mirror the OpenTelemetry GenAI semantic conventions and
+ * are merged with the existing Graphorin-prefixed attributes — the
+ * `gen_ai.*` family is additive, never replacing.
+ *
+ * @stable
+ */
+interface GenAIAttributes {
+  readonly system?: GenAISystem;
+  readonly requestModel?: string;
+  readonly responseModel?: string;
+  readonly responseId?: string;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly finishReasons?: ReadonlyArray<string>;
+  readonly operation?: GenAIOperationName;
+  readonly agentId?: string;
+  readonly agentName?: string;
+  readonly sessionId?: string;
+  readonly toolName?: string;
+  readonly toolType?: GenAIToolType;
+  readonly toolCallId?: string;
+  readonly toolDescription?: string;
+}
+/**
+ * Mapping from a Graphorin `SpanType` to the canonical
+ * `gen_ai.operation.name` value. Returns `undefined` for span types
+ * that do not have a canonical operation enum (`replay.*` is recorded
+ * as `'replay.run'` / `'replay.skipped'` per the doc table).
+ *
+ * @stable
+ */
+type SpanTypeToOperationName = (type: SpanType) => GenAIOperationName | undefined;
+//#endregion
+export { GenAIAttributes, GenAIMessage, GenAIMessageRole, GenAIOperationName, GenAISystem, GenAIToolType, SpanTypeToOperationName };
+//# sourceMappingURL=types.d.ts.map