@swfte/nexus-sdk 0.1.0

package/src/otel/semconv.cjs

@@ -0,0 +1,650 @@
+'use strict';
+/**
+ * One normalised view over three GenAI span vocabularies. A port of `nexus/otel/semconv.py`.
+ *
+ * We do not write provider adapters. One OpenLLMetry provider adapter was measured at 931 lines
+ * across 8 files, over ~30 packages — 15–25k lines of maintained, permissively licensed work that
+ * three funded projects already do. Re-implementing it would be the most expensive possible way to
+ * arrive at a worse version of somebody else's tested extraction logic.
+ *
+ * So this module is a *reader*, not an adapter. It takes a span produced by whichever
+ * instrumentation the customer already runs and reduces it to {@link SpanFacts} — the small set of
+ * things the nexus ledger actually needs. Three vocabularies are read:
+ *
+ * - **OpenTelemetry GenAI semantic conventions**, targeted at v1.42.0. That spec is still
+ *   pre-stable and is a moving target: content capture moved from `gen_ai.prompt`/`gen_ai.completion`
+ *   to `gen_ai.input.messages`/`gen_ai.output.messages`, and `gen_ai.system` became
+ *   `gen_ai.provider.name`. Both spellings are read on purpose. Reading a superseded key costs one
+ *   lookup; failing to read it costs a customer their token counts for however long it takes
+ *   somebody to notice a number went quietly to zero.
+ * - **OpenInference** (Arize, Apache-2.0) — the structural base. `openinference.span.kind` is the
+ *   only vocabulary of the three that states what a span *is* rather than leaving it to be inferred
+ *   from the instrumentation's name, which is why classification keys off it first.
+ * - **OpenLLMetry** (Traceloop) / **OpenLIT** — breadth.
+ *
+ * Nothing here imports an OpenTelemetry package. A span is read *structurally* — `.attributes`,
+ * `.context`, `.parent` — so the bridge works against a real `ReadableSpan`, against an
+ * OpenInference span, and against a plain object in a test, with nothing installed.
+ *
+ * ── One rule about content, and the bug that made it a written rule ──────────────────────────
+ *
+ * Every attribute read here was written by instrumentation the customer installed, and much of it
+ * is the customer's own text and the model's own output. Three fields — `inputText`, `outputText`,
+ * `reasoningText` — are *declared* to be content: the bridge emits the last two only through the
+ * tier gate, and emits `inputText` nowhere at all. **Every other field this reader produces must be
+ * structure**: an identifier, a number, a type, a count.
+ *
+ * The rule is written down because it was broken, in exactly the shape found independently in this
+ * SDK's own `tool_action.effect`: `tool.parameters` (a tool call's arguments) and `input.value` (a
+ * span's raw input) were read into `toolTarget`, which the contract treats as an identifier. The
+ * fix is not a better gate. It is not putting a payload in front of one. See {@link identifier},
+ * which decides what may be a target, and {@link shapeOf}, which is what the arguments contribute
+ * instead.
+ *
+ * One caveat the rule does not cover: `SpanFacts.attributes` keeps the raw attribute mapping —
+ * prompts included — because the bridge re-reads counters from it. Nothing emits it and it never
+ * leaves the process, but it is why a heap dump of a host running this bridge contains prompts.
+ */
+
+/** The semconv release this module was written against. Pinned: a pre-stable convention that
+ *  silently drifts is worse than one that fails a test. */
+const GENAI_SEMCONV_VERSION = '1.42.0';
+const GENAI_SEMCONV_STABILITY = 'pre-stable';
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// Attribute keys, grouped by the concept rather than by the vocabulary that spells it.
+// First hit wins, so the order within each list is most-authoritative → most-legacy.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+const KIND_KEYS = ['openinference.span.kind', 'traceloop.span.kind', 'gen_ai.operation.name'];
+
+const PROVIDER_KEYS = [
+  'gen_ai.provider.name',      // semconv >= 1.36
+  'gen_ai.system',             // semconv < 1.36, still emitted by most shipped instrumentations
+  'llm.provider',              // OpenInference
+  'llm.system',
+];
+
+const REQUEST_MODEL_KEYS = ['gen_ai.request.model', 'llm.model_name', 'llm.request.model', 'gen_ai.model'];
+const RESPONSE_MODEL_KEYS = ['gen_ai.response.model', 'llm.response.model', 'llm.model_name'];
+
+const INPUT_TOKEN_KEYS = [
+  'gen_ai.usage.input_tokens',
+  'gen_ai.usage.prompt_tokens',          // OpenLLMetry / pre-1.27 semconv
+  'llm.token_count.prompt',              // OpenInference
+];
+const OUTPUT_TOKEN_KEYS = [
+  'gen_ai.usage.output_tokens',
+  'gen_ai.usage.completion_tokens',
+  'llm.token_count.completion',
+];
+
+// Cache accounting. This is the field set that makes "exact cost" true rather than approximately
+// true: cached input is an order of magnitude cheaper than fresh input, so a bridge that folds
+// cache reads into `input_tokens` overstates a cache-heavy workload's bill by multiples.
+const CACHE_READ_KEYS = [
+  'gen_ai.usage.cache_read_input_tokens',
+  'gen_ai.usage.cached_input_tokens',
+  'llm.token_count.prompt_details.cache_read',
+  'gen_ai.usage.cache_read_tokens',
+];
+const CACHE_WRITE_5M_KEYS = [
+  'gen_ai.usage.cache_creation.ephemeral_5m_input_tokens',
+  'gen_ai.usage.cache_creation_input_tokens',
+  'llm.token_count.prompt_details.cache_write',
+  'gen_ai.usage.cache_write_tokens',
+];
+const CACHE_WRITE_1H_KEYS = [
+  'gen_ai.usage.cache_creation.ephemeral_1h_input_tokens',
+  // Flattened spelling. OTel attribute keys are a flat namespace, so instrumentations routinely
+  // collapse Anthropic's nested `cache_creation.ephemeral_1h_input_tokens` rather than emit a
+  // dotted sub-object. Reading both costs a lookup; reading only one prices a 1-hour write at the
+  // 5-minute rate — a 1.6x understatement that looks like a plausible number.
+  'gen_ai.usage.cache_creation_1h_tokens',
+  'llm.token_count.prompt_details.cache_write_1h',
+];
+
+/** A cost the *provider* reported. Preferred over our rate-card arithmetic: a number from the
+ *  vendor is evidence, a number from a rate card is an inference. */
+const REPORTED_COST_KEYS = ['gen_ai.usage.cost', 'llm.cost.total', 'gen_ai.usage.total_cost'];
+
+/** Explicit retry/attempt counters, where the instrumentation bothers to emit one. */
+const ATTEMPT_KEYS = ['gen_ai.request.attempt', 'llm.retry.count', 'http.request.resend_count',
+  'retry.count'];
+
+const OUTPUT_TEXT_KEYS = [
+  'gen_ai.output.messages',     // semconv 1.42 content capture (opt-in upstream)
+  'gen_ai.completion',          // legacy semconv / OpenLLMetry
+  'gen_ai.completion.0.content',
+  'output.value',               // OpenInference
+  'llm.output_messages.0.message.content',
+];
+const INPUT_TEXT_KEYS = [
+  'gen_ai.input.messages',
+  'gen_ai.prompt',
+  'gen_ai.prompt.0.content',
+  'input.value',
+  'llm.input_messages.0.message.content',
+];
+
+/** Model-authored reasoning. Distinct from output text because it is a *different epistemic class*:
+ *  a model's account of its own process is `rationalisation`, never `behavior_trace`. Folding it
+ *  into the answer would launder a claim into the record as if it were an observation. */
+const REASONING_KEYS = [
+  'gen_ai.output.reasoning',
+  'gen_ai.completion.reasoning',
+  'llm.output_messages.0.message.reasoning',
+  'llm.reasoning',
+  'traceloop.entity.thinking',
+];
+
+const TOOL_NAME_KEYS = ['gen_ai.tool.name', 'tool.name', 'traceloop.entity.name'];
+
+/**
+ * Keys that name *which* tool call this is. A target is an identifier — a call id, a tool id, an
+ * endpoint — and nothing else. `tool.parameters` and `input.value` used to be read here and are not
+ * identifiers: the first is the arguments the model chose, the second is OpenInference's verbatim
+ * span input. Both are content, both landed in `tool_action.target`, and the only thing between
+ * that field and the collector was a text gate. Content must not be standing in front of a gate in
+ * the first place — see {@link TOOL_ARG_KEYS}.
+ */
+const TOOL_TARGET_KEYS = ['gen_ai.tool.call.id', 'tool.id'];
+
+/** Keys whose value is the *payload* of a call. Never read as text, only ever reduced by
+ *  {@link shapeOf}. Named and handled rather than silently unread: the ledger still wants to know
+ *  a tool was called with three arguments named `city`, `units` and `when`, and that fact does not
+ *  require their values. */
+const TOOL_ARG_KEYS = ['gen_ai.tool.call.arguments', 'tool.parameters', 'tool.arguments',
+  'input.value', 'traceloop.entity.input'];
+
+const AGENT_NAME_KEYS = ['gen_ai.agent.name', 'agent.name'];
+
+const HTTP_MARKERS = ['http.request.method', 'http.method', 'url.full', 'http.url', 'server.address'];
+
+/** Canonical span kinds. The bridge classifies against *these*, not against any one vocabulary, so
+ *  adding a fourth convention later is a table edit rather than a classifier rewrite. */
+const KIND_LLM = 'llm';
+const KIND_TOOL = 'tool';
+const KIND_CHAIN = 'chain';
+const KIND_AGENT = 'agent';
+const KIND_RETRIEVER = 'retriever';
+const KIND_EMBEDDING = 'embedding';
+const KIND_RERANKER = 'reranker';
+const KIND_GUARDRAIL = 'guardrail';
+const KIND_EVALUATOR = 'evaluator';
+const KIND_UNKNOWN = 'unknown';
+
+const KNOWN_KINDS = new Set([KIND_LLM, KIND_TOOL, KIND_CHAIN, KIND_AGENT, KIND_RETRIEVER,
+  KIND_EMBEDDING, KIND_RERANKER, KIND_GUARDRAIL, KIND_EVALUATOR]);
+
+const KIND_ALIASES = {
+  // OpenInference `openinference.span.kind`
+  llm: KIND_LLM, chain: KIND_CHAIN, tool: KIND_TOOL, agent: KIND_AGENT,
+  retriever: KIND_RETRIEVER, embedding: KIND_EMBEDDING, reranker: KIND_RERANKER,
+  guardrail: KIND_GUARDRAIL, evaluator: KIND_EVALUATOR,
+  // OTel GenAI `gen_ai.operation.name`
+  chat: KIND_LLM, text_completion: KIND_LLM, generate_content: KIND_LLM,
+  embeddings: KIND_EMBEDDING, execute_tool: KIND_TOOL, invoke_agent: KIND_AGENT,
+  create_agent: KIND_AGENT,
+  // Traceloop `traceloop.span.kind`
+  workflow: KIND_CHAIN, task: KIND_CHAIN, tool_call: KIND_TOOL,
+};
+
+/** Any of these present means the span came from *some* GenAI instrumentation. The distinction
+ *  matters: a span we cannot classify but which is plainly GenAI is a coverage failure that must be
+ *  counted and surfaced, whereas a database span is simply not ours and deserves silence. */
+const GENAI_MARKER_PREFIXES = ['gen_ai.', 'llm.', 'openinference.', 'traceloop.', 'openlit.'];
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// Readers
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * `getattr` that cannot throw.
+ *
+ * Optional chaining only defends against the property being *absent*: whatever a getter throws
+ * still propagates. Every span here comes from instrumentation we do not own — a lazy `.name`, a
+ * `.status` computed from a closed response, a `.context` on a span the exporter already recycled —
+ * and any of those exploding would put an error on the host's request path from inside a telemetry
+ * reader. Degrade to the default instead; the field being unreadable is itself the only honest
+ * thing we can say about it.
+ */
+function get(obj, name, fallback) {
+  if (obj === null || obj === undefined) return fallback;
+  try {
+    const v = obj[name];
+    return v === undefined ? fallback : v;
+  } catch (_err) {
+    return fallback;
+  }
+}
+
+function first(attrs, keys) {
+  for (const k of keys) {
+    const v = attrs[k];
+    if (v !== null && v !== undefined && v !== '') return v;
+  }
+  return null;
+}
+
+function toInt(v) {
+  if (v === null || v === undefined || typeof v === 'boolean') return null;
+  const n = typeof v === 'number' ? Math.trunc(v) : parseInt(String(v), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+function toFloat(v) {
+  if (v === null || v === undefined || typeof v === 'boolean') return null;
+  const n = typeof v === 'number' ? v : parseFloat(String(v));
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Flatten whatever the convention put in a content attribute into a string.
+ *
+ * v1.42's `gen_ai.output.messages` is a JSON-ish structure, the legacy keys are plain strings, and
+ * OpenInference's `output.value` is either. Bounded, because an unbounded stringify of a
+ * conversation history is a memory event on somebody's request path.
+ */
+function toText(v, limit) {
+  const cap = limit === undefined ? 20000 : limit;
+  if (v === null || v === undefined) return null;
+  if (typeof v === 'string') return v.slice(0, cap) || null;
+  if (Array.isArray(v)) {
+    const parts = v.slice(0, 32).map((i) => toText(i, cap)).filter(Boolean);
+    return parts.join('\n').slice(0, cap) || null;
+  }
+  if (typeof v === 'object') {
+    for (const k of ['content', 'text', 'value', 'message']) {
+      if (k in v) return toText(v[k], cap);
+    }
+    try { return JSON.stringify(v).slice(0, cap) || null; } catch (_err) { return null; }
+  }
+  return String(v).slice(0, cap) || null;
+}
+
+/**
+ * What an identifier is allowed to look like. Deliberately a whitelist and deliberately narrow:
+ * call ids (`call_01H8XQ`, `toolu_01ABC`), dotted symbol paths, URNs and bare endpoint URLs all
+ * match; a sentence does not (spaces), an email does not (`@`), a query string does not (`?`, `=`),
+ * and neither does anything with a newline or a quote in it.
+ *
+ * The rule is not "this value is safe" — it is "a value that is not shaped like an identifier is
+ * not a target", which is a property of the field rather than a guess about the content.
+ */
+const IDENTIFIER_RE = /^[A-Za-z0-9_.:/-]{1,128}$/;
+
+/** Bounds on {@link shapeOf}. A summary of an unbounded payload has to be bounded or it is a
+ *  payload again by another route: 200 field names is not shape, it is data. */
+const MAX_SHAPE_FIELDS = 16;
+const MAX_SHAPE_DEPTH = 3;
+const MAX_SHAPE_ITEMS = 32;
+
+/** A field name is emitted only if it looks like a field name. Argument names normally come from
+ *  the developer's own tool schema, which puts them in the same class as `toolName` — but a mapping
+ *  keyed by customer data (an address book, a per-user index) would turn "names are safe" into the
+ *  same leak wearing a different hat, so the shape of the *name* is checked too. */
+const SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_.-]{0,39}$/;
+
+/**
+ * `SAFE_KEY_RE` states the right requirement and then does not enforce it. It catches the two cases
+ * somebody pictured while writing it — a key that is an email address, a key that is bare digits —
+ * while `{"patient_90210443": 1, "mrn_44521": 2}` and `{"acme.customer.90210443": 1}` walk straight
+ * through. Those are not exotic: a per-patient index, a per-account rollup, a per-order dict is the
+ * ordinary shape of the payload an agent hands a tool, and the names in it *are* the identifiers.
+ *
+ * The distinction being drawn is between a *schema* name and an *instance* name. A schema name is
+ * written once by a developer and reused for every call; an instance name is minted per record and
+ * carries the record's identity. Nothing in the string says which — but identifiers are made of
+ * digit runs and schema names, being words, are not. So: a run of four or more digits, or six
+ * digits in total, means this is a value wearing a key's clothing.
+ *
+ * The threshold has a known and accepted cost. `iso8601` and `rfc3339` are legitimate schema names
+ * with a four-digit run, and they land in the anonymous bucket. That is the right side to be wrong
+ * on twice over: a false positive costs a field being reported by type instead of by name, while a
+ * false negative is a patient identifier on the wire at the tier that promises no content.
+ */
+const IDENTIFIERISH_KEY_RE = /\d{4}|(?:\D*\d){6}/;
+
+/**
+ * `v` if it is shaped like an identifier, else `null`.
+ *
+ * Rejecting is the whole function. Every value here was written by instrumentation we do not own,
+ * into a key whose *convention* says "id" and whose contents are whatever the library felt like
+ * putting there. Truncating a payload to 128 characters would still emit a payload.
+ *
+ * Known residual, stated rather than papered over: a bare number passes, because numeric call ids
+ * are ordinary and a rule against them would break real instrumentation. So an instrumentation that
+ * wrote a national ID into `tool.id` would still be believed. That is a narrower hole than a
+ * sentence-shaped one, and the tier gate downstream is the layer that covers it.
+ */
+function identifier(v, limit) {
+  const cap = limit === undefined ? 128 : limit;
+  if (v === null || v === undefined || typeof v === 'boolean') return null;
+  if (typeof v !== 'string' && typeof v !== 'number') return null;
+  const s = String(v).trim();
+  if (!s || s.length > cap) return null;
+  return IDENTIFIER_RE.test(s) ? s : null;
+}
+
+/**
+ * A bounded, content-free description of a payload: types, counts, and safe field names.
+ *
+ * This is the representation `metadata_only` is supposed to emit, applied at the *reader* rather
+ * than at the gate. It answers the questions a ledger actually asks of a tool call — was it called
+ * with arguments, how many, which named parameters, were any of them structured — and it cannot
+ * answer "what did they say", because no value ever enters the result.
+ *
+ * Three deliberate omissions:
+ *
+ * - **No values, at any depth or type.** Numbers are values too: an account number, a dose, a
+ *   salary. `{type: 'number'}` is the whole of what a number contributes here.
+ * - **No fingerprint.** `redactPreview` pairs `chars` with a hash because a paragraph of prose has
+ *   the entropy to make a hash one-way. Tool arguments frequently do not — a boolean, a zip code,
+ *   a member of a five-value enum is recoverable from its digest by trying every input — so a
+ *   fingerprint here would be a correlation handle over customer content wearing a safe costume.
+ * - **No free-form key names.** See {@link SAFE_KEY_RE}.
+ */
+function shapeOf(v, depth) {
+  const d = depth || 0;
+  if (d > MAX_SHAPE_DEPTH) return { type: '...' };
+  if (v === null || v === undefined) return { type: 'null' };
+  if (typeof v === 'boolean') return { type: 'bool' };
+  if (typeof v === 'number' || typeof v === 'bigint') return { type: 'number' };
+  if (typeof v === 'string') {
+    const s = v.trim();
+    if ((s.startsWith('{') || s.startsWith('[')) && d < MAX_SHAPE_DEPTH) {
+      let parsed = null;
+      try { parsed = JSON.parse(s); } catch (_err) { parsed = null; }
+      if (parsed !== null && typeof parsed === 'object') {
+        return Object.assign({}, shapeOf(parsed, d) || {}, { json: true });
+      }
+    }
+    // `chars` on a string is retained: it is exactly the shape signal the tier ladder already
+    // emits at T0, so it is inside the tier's existing contract rather than an extension of it.
+    return { type: 'string', chars: v.length };
+  }
+  if (Array.isArray(v) || v instanceof Set) {
+    const all = Array.isArray(v) ? v : Array.from(v);
+    const items = all.slice(0, MAX_SHAPE_ITEMS);
+    const types = [...new Set(items.map((i) => (shapeOf(i, d + 1) || {}).type || '?'))].sort();
+    return { type: 'array', count: all.length, item_types: types };
+  }
+  if (typeof v === 'object') {
+    const keys = Object.keys(v);
+    const out = { type: 'object', field_count: keys.length };
+    const fields = {};
+    let unnamed = 0;
+    let omitted = 0;
+    const unnamedTypes = [];
+    for (const key of keys) {
+      const name = String(key);
+      if (!SAFE_KEY_RE.test(name) || IDENTIFIERISH_KEY_RE.test(name)) {
+        unnamed += 1;
+        // A rejected name is not a rejected field. Dropping the entry outright would make a payload
+        // of eight per-patient numbers indistinguishable from an empty object — both less useful
+        // and less honest than saying there were eight numbers whose names could not be shown.
+        // Reported as a sibling list rather than as synthesised `field_0` entries, because
+        // `field_0` is itself a name `SAFE_KEY_RE` admits, and a real key spelled that way would
+        // then silently collide with a placeholder.
+        if (unnamedTypes.length < MAX_SHAPE_FIELDS) {
+          unnamedTypes.push((shapeOf(v[key], d + 1) || {}).type || '?');
+        }
+        continue;
+      }
+      if (Object.keys(fields).length >= MAX_SHAPE_FIELDS) { omitted += 1; continue; }
+      fields[name] = shapeOf(v[key], d + 1);
+    }
+    out.fields = fields;
+    if (unnamed) { out.fields_unnamed = unnamed; out.unnamed_types = unnamedTypes.slice().sort(); }
+    if (omitted) out.fields_omitted = omitted;
+    return out;
+  }
+  return { type: typeof v };
+}
+
+/**
+ * The shape fragment for a tool span: its arguments, plus any target we refused.
+ *
+ * A refused target is reported rather than dropped in silence. "This span had a target-shaped key
+ * holding 4 kB of string" is a fact about somebody's instrumentation that the reader of the ledger
+ * should be able to see; leaving it out would make a leak-prevention step look identical to an
+ * attribute that was never there.
+ */
+function toolArgShape(attrs, rejectedTarget) {
+  let frag = {};
+  const payload = first(attrs, TOOL_ARG_KEYS);
+  if (payload !== null && payload !== undefined) {
+    const shape = shapeOf(payload);
+    if (shape) frag = Object.assign({}, shape);
+  }
+  if (rejectedTarget !== null && rejectedTarget !== undefined) {
+    const rejected = shapeOf(rejectedTarget);
+    if (rejected) frag.target = rejected;
+  }
+  return Object.keys(frag).length ? frag : null;
+}
+
+function hex(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'number') return v.toString(16).padStart(32, '0');
+  if (typeof v === 'bigint') return v.toString(16).padStart(32, '0');
+  return String(v);
+}
+
+let anonCounter = 0;
+const anonIds = new WeakMap();
+
+/**
+ * `[traceId, spanId, parentSpanId]` from any span-shaped object.
+ *
+ * Structural rather than typed: a real `ReadableSpan` exposes `.context`, an in-flight `Span`
+ * exposes `.spanContext()`, and neither can be named here without importing an OpenTelemetry
+ * package into a zero-dependency core.
+ */
+function spanIds(span) {
+  let ctx = get(span, 'context');
+  if (ctx === undefined || ctx === null) {
+    // The JS SDK spells it `spanContext()`; the Python one `get_span_context()`. Both are tried.
+    for (const getterName of ['spanContext', 'get_span_context']) {
+      const getter = get(span, getterName);
+      if (typeof getter === 'function') {
+        try { ctx = getter.call(span); break; } catch (_err) { ctx = null; }
+      }
+    }
+  }
+  const traceId = ctx ? hex(get(ctx, 'traceId', get(ctx, 'trace_id'))) : '';
+  let spanId = ctx ? hex(get(ctx, 'spanId', get(ctx, 'span_id'))) : '';
+  const parent = get(span, 'parentSpanContext', get(span, 'parent'));
+  let parentId = null;
+  if (parent !== null && parent !== undefined) {
+    const pid = get(parent, 'spanId', get(parent, 'span_id', parent));
+    parentId = pid === null || pid === undefined ? null : hex(pid);
+  }
+  if (!spanId) {
+    // A WeakMap rather than an object identity hash: JavaScript has no `id()`, and a monotonic
+    // counter alone would give one span two ids if it were read twice. Weak so an anonymous span
+    // does not keep itself alive through this table.
+    if (typeof span === 'object' && span !== null) {
+      if (!anonIds.has(span)) { anonCounter += 1; anonIds.set(span, 'anon-' + anonCounter); }
+      spanId = anonIds.get(span);
+    } else {
+      anonCounter += 1;
+      spanId = 'anon-' + anonCounter;
+    }
+  }
+  return [traceId, spanId, parentId || null];
+}
+
+function scopeName(span) {
+  for (const attr of ['instrumentationScope', 'instrumentation_scope', 'instrumentationLibrary',
+    'instrumentation_info']) {
+    const scope = get(span, attr);
+    const name = get(scope, 'name');
+    if (name) return String(name);
+  }
+  return String(get(span, 'scope', '') || '');
+}
+
+function kindAndVocabulary(attrs) {
+  const raw = first(attrs, KIND_KEYS);
+  let vocab = 'unknown';
+  const keys = Object.keys(attrs);
+  if (attrs['openinference.span.kind'] !== undefined && attrs['openinference.span.kind'] !== null) {
+    vocab = 'openinference';
+  } else if (attrs['traceloop.span.kind'] !== undefined && attrs['traceloop.span.kind'] !== null) {
+    vocab = 'openllmetry';
+  } else if (keys.some((k) => String(k).startsWith('gen_ai.'))) {
+    vocab = 'genai';
+  } else if (keys.some((k) => String(k).startsWith('llm.'))) {
+    vocab = 'openinference';
+  }
+  if (raw === null) {
+    // No explicit kind. Infer from the token/model attributes rather than give up: several shipped
+    // instrumentations emit usage on an unlabelled span, and dropping those would mean losing the
+    // numbers we exist to record.
+    if (first(attrs, INPUT_TOKEN_KEYS) !== null || first(attrs, RESPONSE_MODEL_KEYS) !== null) {
+      return [KIND_LLM, vocab];
+    }
+    if (first(attrs, TOOL_NAME_KEYS) !== null) return [KIND_TOOL, vocab];
+    return [KIND_UNKNOWN, vocab];
+  }
+  return [KIND_ALIASES[String(raw).trim().toLowerCase()] || KIND_UNKNOWN, vocab];
+}
+
+function errorOf(span) {
+  const status = get(span, 'status');
+  const code = get(status, 'code', get(status, 'status_code'));
+  // The JS SDK uses a numeric `SpanStatusCode` where `2 === ERROR`; the Python one an enum whose
+  // `.name` is the string. Both are read, because a bridge that only understood one would report
+  // every error as a success against the other half of the ecosystem.
+  const name = get(code, 'name') || String(code === undefined || code === null ? '' : code);
+  const isError = String(name).toUpperCase().includes('ERROR') || code === 2;
+  if (!isError) return null;
+  const desc = get(status, 'message', get(status, 'description'));
+  return String(desc || 'error');
+}
+
+function durationMs(span) {
+  const start = get(span, 'startTime', get(span, 'start_time'));
+  const end = get(span, 'endTime', get(span, 'end_time'));
+  // Python's SDK uses integer nanoseconds; the JS SDK uses `[seconds, nanos]` tuples.
+  const hr = (v) => (Array.isArray(v) && v.length === 2 ? v[0] * 1e9 + v[1] : v);
+  const s = hr(start);
+  const e = hr(end);
+  if (typeof s === 'number' && typeof e === 'number' && e >= s) return Math.trunc((e - s) / 1e6);
+  return null;
+}
+
+/** Everything the ledger needs from a span, and nothing it does not. */
+function emptyFacts() {
+  return {
+    traceId: '', spanId: '', parentSpanId: null, name: '', scope: '',
+    kind: KIND_UNKNOWN, vocabulary: 'unknown', isGenai: false, isHttp: false,
+    provider: null, model: null,
+    inputTokens: null, outputTokens: null, cacheReadTokens: null,
+    cacheWrite5mTokens: null, cacheWrite1hTokens: null,
+    reportedCostUsd: null, attempts: null,
+    inputText: null, outputText: null, reasoningText: null,
+    toolName: null, toolTarget: null, toolArgShape: null, agentName: null,
+    error: null, durationMs: null, attributes: {},
+  };
+}
+
+/** True when this observation carries billable numbers, not merely structure. */
+function hasUsage(facts) {
+  return Boolean(facts.inputTokens || facts.outputTokens || facts.cacheReadTokens
+    || facts.cacheWrite5mTokens || facts.cacheWrite1hTokens);
+}
+
+/**
+ * The breakdown in `pricing.costFromUsage`'s own field names.
+ *
+ * Deliberately the *transcript's* vocabulary rather than ours, so the parity check against the
+ * Python rate card compares like with like instead of comparing two translations.
+ */
+function usageDict(facts) {
+  const u = {
+    input_tokens: facts.inputTokens || 0,
+    output_tokens: facts.outputTokens || 0,
+    cache_read_input_tokens: facts.cacheReadTokens || 0,
+  };
+  if (facts.cacheWrite1hTokens) {
+    u.cache_creation = {
+      ephemeral_5m_input_tokens: facts.cacheWrite5mTokens || 0,
+      ephemeral_1h_input_tokens: facts.cacheWrite1hTokens,
+    };
+  } else if (facts.cacheWrite5mTokens) {
+    u.cache_creation_input_tokens = facts.cacheWrite5mTokens;
+  }
+  return u;
+}
+
+/** Read a span into facts. Never throws — a malformed span yields empty facts. */
+function normalise(span) {
+  let attrs;
+  try {
+    const raw = get(span, 'attributes') || {};
+    attrs = typeof raw === 'object' && raw !== null ? Object.assign({}, raw) : {};
+  } catch (_err) {
+    attrs = {};
+  }
+
+  const facts = emptyFacts();
+  try {
+    const [traceId, spanId, parentId] = spanIds(span);
+    const [kind, vocab] = kindAndVocabulary(attrs);
+    const keys = Object.keys(attrs);
+    const model = first(attrs, RESPONSE_MODEL_KEYS) || first(attrs, REQUEST_MODEL_KEYS);
+    const rawTarget = first(attrs, TOOL_TARGET_KEYS);
+    const target = identifier(rawTarget);
+    const provider = first(attrs, PROVIDER_KEYS);
+    const toolName = first(attrs, TOOL_NAME_KEYS);
+    const agentName = first(attrs, AGENT_NAME_KEYS);
+
+    facts.traceId = traceId;
+    facts.spanId = spanId;
+    facts.parentSpanId = parentId;
+    facts.name = String(get(span, 'name', '') || '');
+    facts.scope = scopeName(span);
+    facts.kind = kind;
+    facts.vocabulary = vocab;
+    facts.isGenai = keys.some((k) => GENAI_MARKER_PREFIXES.some((p) => String(k).startsWith(p)))
+      || kind !== KIND_UNKNOWN;
+    facts.isHttp = HTTP_MARKERS.some((k) => k in attrs);
+    facts.provider = provider ? String(provider) : null;
+    facts.model = model ? String(model) : null;
+    facts.inputTokens = toInt(first(attrs, INPUT_TOKEN_KEYS));
+    facts.outputTokens = toInt(first(attrs, OUTPUT_TOKEN_KEYS));
+    facts.cacheReadTokens = toInt(first(attrs, CACHE_READ_KEYS));
+    facts.cacheWrite5mTokens = toInt(first(attrs, CACHE_WRITE_5M_KEYS));
+    facts.cacheWrite1hTokens = toInt(first(attrs, CACHE_WRITE_1H_KEYS));
+    facts.reportedCostUsd = toFloat(first(attrs, REPORTED_COST_KEYS));
+    facts.attempts = toInt(first(attrs, ATTEMPT_KEYS));
+    facts.inputText = toText(first(attrs, INPUT_TEXT_KEYS));
+    facts.outputText = toText(first(attrs, OUTPUT_TEXT_KEYS));
+    facts.reasoningText = toText(first(attrs, REASONING_KEYS));
+    facts.toolName = toolName ? String(toolName) : null;
+    facts.toolTarget = target;
+    facts.toolArgShape = toolArgShape(attrs, target === null ? rawTarget : null);
+    facts.agentName = agentName ? String(agentName) : null;
+    facts.error = errorOf(span);
+    facts.durationMs = durationMs(span);
+    facts.attributes = attrs;
+  } catch (_err) {
+    // A reader that raises into the host is worse than one that reports nothing.
+    return facts;
+  }
+  return facts;
+}
+
+module.exports = {
+  GENAI_SEMCONV_VERSION, GENAI_SEMCONV_STABILITY,
+  KIND_LLM, KIND_TOOL, KIND_CHAIN, KIND_AGENT, KIND_RETRIEVER, KIND_EMBEDDING,
+  KIND_RERANKER, KIND_GUARDRAIL, KIND_EVALUATOR, KIND_UNKNOWN, KNOWN_KINDS,
+  MAX_SHAPE_FIELDS, MAX_SHAPE_DEPTH, MAX_SHAPE_ITEMS,
+  normalise, hasUsage, usageDict, shapeOf, identifier, emptyFacts,
+  // Exported for tests that assert on the vocabulary rather than on one example.
+  INPUT_TOKEN_KEYS, OUTPUT_TOKEN_KEYS, CACHE_READ_KEYS, CACHE_WRITE_5M_KEYS, CACHE_WRITE_1H_KEYS,
+  TOOL_TARGET_KEYS, TOOL_ARG_KEYS, IDENTIFIER_RE, SAFE_KEY_RE, IDENTIFIERISH_KEY_RE,
+};