@swfte/nexus-sdk 0.1.0

package/src/otel/classify.cjs

@@ -0,0 +1,166 @@
+'use strict';
+/**
+ * Epistemic classification — the thing the upstream vocabulary has no concept of.
+ *
+ * An OTel span has nowhere to put the distinction between *what the system did*, *what the model
+ * said it did*, and *what the user was told*. Every attribute in the GenAI conventions is agnostic
+ * on that question, because observability does not need to answer it and governance cannot proceed
+ * without it.
+ *
+ * The mapping is small enough to state in full:
+ *
+ * - **model output → `interaction_narrative`.** A completion is what the user was told. It may be
+ *   true. It is not evidence that anything happened.
+ * - **observed tool execution → `behavior_trace`.** A tool span is the runtime reporting an effect
+ *   it carried out. That is fact, and the only class admissible as evidence.
+ * - **model-authored reasoning → `rationalisation`.** A model's account of its own process is the
+ *   weakest class of all, and the one most often mistaken for the strongest.
+ *
+ * Token accounting is `behavior_trace`: the number of tokens billed is measured, not asserted. It
+ * is emitted by `contract.tokenUsage`, which hard-codes the class, so it cannot drift from here.
+ *
+ * ── The invariant this module exists to hold ─────────────────────────────────────────────────
+ *
+ * **An unclassified span must never reach the ledger.** Two failure modes are being ruled out at
+ * once, and they call for opposite handling:
+ *
+ * - *Silently mislabelling* — defaulting an unknown span to `behavior_trace` would put unverified
+ *   content into the class the product sells as evidence. Never do this.
+ * - *Silently dropping* — dropping without counting turns a coverage gap into an invisible one.
+ *
+ * So the runtime behaviour is **drop and count**, and the test behaviour is **throw**. `strict`
+ * defaults to on under `node --test` (and under `NEXUS_BRIDGE_STRICT=1`), so a new span kind fails
+ * a build rather than quietly thinning the ledger in production six months later.
+ */
+
+const {
+  KIND_AGENT, KIND_CHAIN, KIND_EMBEDDING, KIND_EVALUATOR, KIND_GUARDRAIL, KIND_LLM,
+  KIND_RERANKER, KIND_RETRIEVER, KIND_TOOL, KNOWN_KINDS,
+} = require('./semconv.cjs');
+
+const EPISTEMIC_BEHAVIOR = 'behavior_trace';
+const EPISTEMIC_NARRATIVE = 'interaction_narrative';
+const EPISTEMIC_RATIONALISATION = 'rationalisation';
+
+/** The classes the ledger accepts. Anything else is a bug, not a new category. */
+const VALID_CLASSES = new Set([EPISTEMIC_BEHAVIOR, EPISTEMIC_NARRATIVE, EPISTEMIC_RATIONALISATION]);
+
+/**
+ * Canonical span kind → the class of the *span itself*. Per-payload classes are decided by
+ * {@link classifyPayload}, because one LLM span legitimately produces records of two classes: its
+ * usage (measured, behaviour) and its completion (asserted, narrative).
+ */
+const SPAN_CLASS = {
+  [KIND_LLM]: EPISTEMIC_NARRATIVE,
+  [KIND_TOOL]: EPISTEMIC_BEHAVIOR,
+  [KIND_RETRIEVER]: EPISTEMIC_BEHAVIOR,
+  [KIND_EMBEDDING]: EPISTEMIC_BEHAVIOR,
+  [KIND_RERANKER]: EPISTEMIC_BEHAVIOR,
+  [KIND_GUARDRAIL]: EPISTEMIC_BEHAVIOR,
+  // A chain/agent span is the framework's own record of orchestration it performed — an observed
+  // execution, not a claim about one.
+  [KIND_CHAIN]: EPISTEMIC_BEHAVIOR,
+  [KIND_AGENT]: EPISTEMIC_BEHAVIOR,
+  // An evaluator is a model judging output. Its verdict is produced text about a process, which is
+  // the definition of a rationalisation however confident the score looks.
+  [KIND_EVALUATOR]: EPISTEMIC_RATIONALISATION,
+};
+
+// Payload kinds the bridge can emit.
+const PAYLOAD_USAGE = 'usage';
+const PAYLOAD_OUTPUT = 'output';
+const PAYLOAD_REASONING = 'reasoning';
+const PAYLOAD_TOOL = 'tool';
+
+const PAYLOAD_CLASS = {
+  [PAYLOAD_USAGE]: EPISTEMIC_BEHAVIOR,             // measured, from the provider's own accounting
+  [PAYLOAD_OUTPUT]: EPISTEMIC_NARRATIVE,           // what the user was told
+  [PAYLOAD_REASONING]: EPISTEMIC_RATIONALISATION,  // what the model said about its own process
+  [PAYLOAD_TOOL]: EPISTEMIC_BEHAVIOR,              // an effect the runtime observed
+};
+
+/**
+ * Thrown in strict mode when a GenAI span cannot be assigned an epistemic class.
+ *
+ * Never escapes the bridge in production: the bridge entry points are guarded and strict is off.
+ * It exists so the classification gap is a red test rather than a quiet decrease in a dashboard.
+ */
+class UnclassifiedSpan extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UnclassifiedSpan';
+  }
+}
+
+/**
+ * Strict under test, lenient in production — the two places want opposite failure modes.
+ *
+ * Python detects pytest via `sys.modules`. The Node equivalent is the test runner's own environment
+ * variable, which `node --test` sets in every worker it spawns. Falling back to `NODE_ENV=test`
+ * covers a customer running the suite under a different harness.
+ */
+function strictDefault() {
+  const flag = String(process.env.NEXUS_BRIDGE_STRICT || '').trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(flag)) return true;
+  if (['0', 'false', 'no', 'off'].includes(flag)) return false;
+  return Boolean(process.env.NODE_TEST_CONTEXT) || process.env.NODE_ENV === 'test';
+}
+
+/**
+ * The epistemic class of a span, or `null` when it has none.
+ *
+ * `null` means two different things and the caller must treat them differently, which is why
+ * {@link isOurs} exists alongside this:
+ *
+ * - a span that is not GenAI at all (an HTTP call, a DB query) — not ours, ignore in silence;
+ * - a GenAI span whose kind we do not recognise — ours, and a coverage failure. Counted, dropped,
+ *   and in strict mode thrown.
+ */
+function classifySpan(facts, strict) {
+  if (!facts || !facts.isGenai) return null;
+  const cls = SPAN_CLASS[facts.kind];
+  if (cls === undefined) {
+    const s = strict === undefined || strict === null ? strictDefault() : strict;
+    if (s) {
+      throw new UnclassifiedSpan(
+        'span ' + JSON.stringify(facts.name) + ' (kind=' + JSON.stringify(facts.kind) +
+        ', vocabulary=' + JSON.stringify(facts.vocabulary) + ', scope=' +
+        JSON.stringify(facts.scope) + ') carries GenAI attributes but no epistemic class is ' +
+        'defined for it. Add it to SPAN_CLASS — do NOT default it.');
+    }
+    return null;
+  }
+  if (!VALID_CLASSES.has(cls)) {   // unreachable; a typo in the table must not reach the wire
+    throw new UnclassifiedSpan(JSON.stringify(cls) + ' is not an epistemic class');
+  }
+  return cls;
+}
+
+/**
+ * The class of one emitted record. Throws on an unknown payload kind — a caller inventing a payload
+ * without deciding its class is the exact mislabelling this module forbids.
+ */
+function classifyPayload(payloadKind) {
+  const cls = PAYLOAD_CLASS[payloadKind];
+  if (cls === undefined) {
+    throw new UnclassifiedSpan('no epistemic class defined for payload ' + JSON.stringify(payloadKind));
+  }
+  return cls;
+}
+
+/** True when this span belongs to the GenAI vocabulary at all — recognised kind or not. */
+function isOurs(facts) {
+  return Boolean(facts && facts.isGenai);
+}
+
+/** A GenAI span of a kind we do not model. The number worth alerting on. */
+function isCoverageGap(facts) {
+  return Boolean(facts && facts.isGenai && !KNOWN_KINDS.has(facts.kind));
+}
+
+module.exports = {
+  EPISTEMIC_BEHAVIOR, EPISTEMIC_NARRATIVE, EPISTEMIC_RATIONALISATION, VALID_CLASSES,
+  SPAN_CLASS, PAYLOAD_CLASS,
+  PAYLOAD_USAGE, PAYLOAD_OUTPUT, PAYLOAD_REASONING, PAYLOAD_TOOL,
+  UnclassifiedSpan, strictDefault, classifySpan, classifyPayload, isOurs, isCoverageGap,
+};

package/src/otel/index.cjs

@@ -0,0 +1,84 @@
+'use strict';
+/**
+ * `@swfte/nexus-sdk/otel` — the OpenTelemetry span bridge.
+ *
+ *     import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ *     import * as nexus from '@swfte/nexus-sdk';
+ *     import { spanProcessor } from '@swfte/nexus-sdk/otel';
+ *
+ *     nexus.init({ service: 'checkout', env: 'prod' });
+ *     const provider = new NodeTracerProvider({ spanProcessors: [spanProcessor()] });
+ *     provider.register();
+ *
+ * Note the direction, which is the same one the AI SDK bridge uses: **the customer imports
+ * OpenTelemetry, not us.** This package has no dependency on any `@opentelemetry/*` package, no
+ * peer dependency, and no version range to conflict with theirs — it hands back a plain object with
+ * `onStart`/`onEnd`/`shutdown`/`forceFlush`, which is the whole of the `SpanProcessor` interface,
+ * and their provider calls it.
+ *
+ * That also means this file cannot break when OpenTelemetry changes its exports. It can only be
+ * wrong about an *attribute name*, which is what `semconv.cjs`'s tables and the tests around them
+ * exist to pin.
+ *
+ * ── What this bridge will and will not put on the wire ───────────────────────────────────────
+ *
+ * - `token_usage` with exact cost including the cache split, from whatever GenAI vocabulary the
+ *   customer's instrumentation speaks (OTel semconv, OpenInference, OpenLLMetry/OpenLIT).
+ * - `tool_action` for tool spans, whose `target` is an identifier or nothing, and whose arguments
+ *   contribute a content-free *shape* rather than their values.
+ * - `model_response` and `model_thinking` for model-authored text, re-gated by the customer's own
+ *   privacy tier because upstream redaction is not trusted, and split by epistemic class because a
+ *   completion and a reasoning trace are different kinds of claim.
+ * - **No `prompt` event.** The prompt is read and emitted nowhere, matching the Python SDK. There
+ *   is no `prompt` builder in the devtools event set for a second producer to emit against.
+ * - **Nothing at all for a GenAI span whose kind is not modelled.** Dropped and counted, never
+ *   defaulted into `behavior_trace` — see `classify.cjs`, which is the point of the module.
+ */
+
+const core = require('../core.cjs');
+const { Bridge, SEMCONV_TAG } = require('./bridge.cjs');
+const semconv = require('./semconv.cjs');
+const classify = require('./classify.cjs');
+
+let _bridge = null;
+
+/** The process-wide bridge. One per process, because it is stateless apart from its counters. */
+function bridge(opts) {
+  if (_bridge === null || (opts && opts.fresh)) _bridge = new Bridge(core, opts);
+  return _bridge;
+}
+
+/**
+ * A `SpanProcessor` for an OpenTelemetry `TracerProvider`.
+ *
+ * Duck-typed rather than subclassed, for the reason in the module header. All four methods are
+ * required by the interface; only `onEnd` does anything, because a span's attributes are not
+ * complete until it closes and reading them at `onStart` would report a call that had not happened.
+ */
+function spanProcessor(opts) {
+  const b = bridge(opts);
+  return {
+    onStart() { /* attributes are not complete until the span ends */ },
+    onEnd(span) { b.ingest(span); },
+    // Nothing is buffered here: `ingest` hands events straight to the client's own queue, which has
+    // its own flush and its own deadline. Returning a resolved promise rather than draining is
+    // therefore honest — there is nothing of ours left to drain.
+    forceFlush() { return Promise.resolve(); },
+    shutdown() { return Promise.resolve(); },
+  };
+}
+
+/** Read one span and emit its events directly, without a provider. Returns whether it emitted. */
+function ingest(span) {
+  return bridge().ingest(span);
+}
+
+/** What the bridge has seen: `{seen, emitted, ignored, unclassified}`. */
+function stats() {
+  return bridge().stats();
+}
+
+module.exports = {
+  spanProcessor, ingest, stats, bridge,
+  Bridge, SEMCONV_TAG, semconv, classify,
+};

package/src/otel/index.js

@@ -0,0 +1,39 @@
+/**
+ * `@swfte/nexus-sdk/otel` — ESM entry for the OpenTelemetry span bridge.
+ *
+ *     import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ *     import * as nexus from '@swfte/nexus-sdk';
+ *     import { spanProcessor } from '@swfte/nexus-sdk/otel';
+ *
+ *     nexus.init({ service: 'checkout', env: 'prod' });
+ *     new NodeTracerProvider({ spanProcessors: [spanProcessor()] }).register();
+ *
+ * A facade over `./index.cjs`, for the same reason `src/index.js` and `src/ai.js` are facades: the
+ * state has to live in exactly one module instance, or a process reaching this package through both
+ * `import` and `require` gets two clients and two session ids. Written out as named re-exports
+ * rather than relying on CJS interop, so the named bindings are guaranteed rather than dependent on
+ * how well the module lexer reads the CommonJS file.
+ */
+import bridgeModule from './index.cjs';
+
+/** A `SpanProcessor` for an OpenTelemetry `TracerProvider`. Duck-typed; nothing is imported from
+ *  `@opentelemetry/*`, so there is no dependency and no version range to conflict with yours. */
+export const spanProcessor = bridgeModule.spanProcessor;
+
+/** Read one finished span and emit its events directly, without a provider. */
+export const ingest = bridgeModule.ingest;
+
+/** What the bridge has seen: `{seen, emitted, ignored, unclassified}`. */
+export const stats = bridgeModule.stats;
+
+/** The process-wide bridge instance. Mostly for tests. */
+export const bridge = bridgeModule.bridge;
+
+/** Which semconv release the reader was written against. */
+export const SEMCONV_TAG = bridgeModule.SEMCONV_TAG;
+
+/** The span reader. Exported so a customer can inspect what a span reduces to before trusting it. */
+export const semconv = bridgeModule.semconv;
+
+/** The epistemic classifier, including `UnclassifiedSpan` and the strict-mode switch. */
+export const classify = bridgeModule.classify;