@swfte/nexus-sdk 0.1.0

package/ai.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `@swfte/nexus-sdk/ai` — the Vercel AI SDK bridge.
+ *
+ * The only capture path in Node that survives bundling. Module hooks intercept an *import*, and a
+ * bundler inlines the provider so there is no import left to intercept; `registerTelemetry` is a
+ * runtime registration, so nothing about the module graph can take it away. Measured, not argued —
+ * `fixtures/vercel/bundle-check.mjs`.
+ *
+ * Two properties of this bridge are worth knowing before you reach for it, because both are
+ * permanent rather than "not yet":
+ *
+ * 1. **It cannot deny.** The AI SDK's callback type is `(event) => PromiseLike<void> | void`.
+ *    There is no return channel by which an integration could refuse a tool call, and a throw from
+ *    `onToolExecutionStart` neither stops the tool nor reaches your code — it is swallowed.
+ *    Enforcement in Node comes from the explicit API (`run.action(...)`, where you own the call
+ *    site) or not at all.
+ * 2. **It emits metadata only, at every privacy tier.** Token counts, model ids, durations, tool
+ *    names. Never prompt text, completion text, or tool inputs and outputs — not even at
+ *    `tier: 'full'`. Gating those needs a redaction pass this SDK does not have.
+ */
+
+/** Deliberately structural. This package does not depend on `ai`, so it cannot name `ai`'s types. */
+export interface TelemetryIntegration {
+  onStart?: (event: unknown) => void;
+  onLanguageModelCallEnd?: (event: unknown) => void;
+  onToolExecutionEnd?: (event: unknown) => void;
+  onEnd?: (event: unknown) => void;
+}
+
+export interface TelemetryOptions {
+  /**
+   * Open a nexus run per top-level AI SDK operation when the application is not already inside
+   * one. Defaults to `false`.
+   *
+   * Off by default because double-counting is worse than under-counting: an application that
+   * already wraps its handler in `withAgent` would otherwise report two runs for one unit of work,
+   * and nothing downstream can tell those apart afterwards. Turn it on when the AI SDK call *is*
+   * the unit of work.
+   */
+  runs?: boolean;
+  /** Emit a `tool_action` per tool execution. Defaults to `true`. */
+  toolActions?: boolean;
+}
+
+/**
+ * Build the integration object to hand to the AI SDK's `registerTelemetry`.
+ *
+ *     import { registerTelemetry } from 'ai';
+ *     import { telemetry } from '@swfte/nexus-sdk/ai';
+ *     registerTelemetry(telemetry());
+ *
+ * Every callback is individually guarded, so a bug in the bridge cannot surface inside your
+ * `generateText` call.
+ */
+export function telemetry(opts?: TelemetryOptions): TelemetryIntegration;
+
+/**
+ * Convenience wrapper: hand it the AI SDK's own `registerTelemetry` and it registers for you.
+ *
+ *     import { registerTelemetry } from 'ai';
+ *     register(registerTelemetry);
+ *
+ * @returns whether registration happened. A non-function argument is a counted no-op rather than a
+ *   throw — a telemetry SDK that crashes an application's boot over its own optional integration
+ *   has failed at its one job.
+ */
+export function register(
+  registerTelemetry: (integration: TelemetryIntegration) => unknown,
+  opts?: TelemetryOptions,
+): boolean;
+
+/** The value {@link import('./index.js').instrumentation} reports once this bridge is built. */
+export const MODE: 'ai-sdk';
+
+/**
+ * Where each number is read off the AI SDK's events, as measured against `ai@7.0.58`.
+ *
+ * Exported because it is the part most likely to move, and because two of these are traps: the
+ * cache split is `usage.inputTokenDetails.cacheReadTokens` (not `usage.cachedInputTokens`) and the
+ * duration is `performance.responseTimeMs` (not `performance.durationMs`). Reading the wrong one
+ * yields `undefined`, which `JSON.stringify` drops, which looks exactly like a working integration
+ * reporting zero tokens.
+ */
+export const FIELD_MAP: Readonly<Record<string, string>>;

package/index.d.ts

@@ -0,0 +1,433 @@
+/**
+ * nexus — agent governance as an application dependency.
+ *
+ * These types describe the **explicit API**: the surface a customer calls by hand. It is declared
+ * separately from the implementation on purpose. `SCOPE.md` §3 shows that auto-instrumentation is
+ * permanently unavailable in bundled Node deployments, so in Node the explicit API is not the
+ * fallback — for a large share of the market it is the whole product, and it has to be pleasant
+ * enough to write by hand and typed well enough to be discoverable from an editor.
+ *
+ * Two conventions run through the whole surface:
+ *
+ * - **Nothing here throws.** Every function is fail-open; when the SDK is switched off or has
+ *   broken internally, calls return inert objects that accept the same chain. Host code never
+ *   needs `if (nexus)`, and a `try/catch` around a nexus call is always dead code.
+ * - **Absent is not false.** Fields like `verified` are optional and stay absent when nothing was
+ *   verified, rather than being recorded as `false`. The ledger has to be able to distinguish
+ *   "not captured" from "captured negative".
+ */
+
+/**
+ * How much text may leave the process.
+ *
+ * - `metadata_only` — no prompt or completion text, ever. Counts, models, durations, outcomes.
+ * - `hashed` — text is replaced by a stable fingerprint, so repetition is visible but content is not.
+ * - `full` — text on the wire. Requires a deliberate decision by whoever owns the data.
+ */
+export type PrivacyTier = 'metadata_only' | 'hashed' | 'full';
+
+/**
+ * How a run finished.
+ *
+ * The listed values are the vocabulary worth converging on — an outcome set that grows without
+ * limit becomes a free-text field, and a free-text field cannot be aggregated across services.
+ * They are suggestions with autocomplete, not a constraint: `contract/events.v1.json` declares no
+ * enum for `turn_outcome.outcome`, and the Python SDK accepts any string (truncated to 64 chars).
+ *
+ * The `(string & {})` arm is what keeps those two facts consistent. Without it this type would be
+ * *stricter than the product* — `run.outcome('success')`, the example in the Python SDK's own
+ * README, would be a compile error in Node and identical code would not port between the two.
+ */
+export type Outcome =
+  | 'resolved' | 'success' | 'partial' | 'abandoned' | 'error' | 'blocked'
+  | (string & {});
+
+/**
+ * What is capturing in this process, if anything.
+ *
+ * - `ai-sdk` — the Vercel AI SDK bridge (`@swfte/nexus-sdk/ai`). Survives bundling.
+ * - `none` — nothing is auto-capturing. In a bundled deployment this is the expected value, not a
+ *   fault: the explicit API still works and is where the events come from.
+ *
+ * `esm-hooks` and `cjs-require` describe module-hook auto-instrumentation, which this release does
+ * not ship (see the README). They remain in the union because the value travels on every
+ * `pipeline_health` record, so a collector reading events from a future build — or from the spike
+ * builds that predate this release — must be able to name what it is seeing.
+ */
+export type Instrumentation = 'ai-sdk' | 'esm-hooks' | 'cjs-require' | 'none';
+
+export interface InitOptions {
+  /** Logical service name. The primary grouping key in every report. */
+  service?: string;
+  /** Deployment environment, e.g. `prod`, `staging`. */
+  env?: string;
+  /** Build or release identifier of the service. */
+  version?: string;
+  /** Defaults to `metadata_only`. Widening it is a decision, not a default. */
+  tier?: PrivacyTier;
+  /** Where events go. A file path; may be set alongside `collectorUrl`. */
+  sink?: string;
+  /** `POST <url>` with an NDJSON body. */
+  collectorUrl?: string;
+  /** Bearer credential for `collectorUrl`. */
+  apiKey?: string;
+  /** Static labels attached to every event from this process. */
+  tags?: Record<string, string>;
+  /** Explicit off switch. `NEXUS_ENABLED=0` beats this in both directions. */
+  enabled?: boolean;
+
+  // ── provenance (ANCHOR-INTEGRATION §6.1) ─────────────────────────────────────────────────
+  //
+  // The join keys that connect this running process to the commit-anchored devtools ledger. All
+  // are auto-detected from the platform when unset, and each detected value records the variable
+  // it came from. Note the types: `string | undefined`, with no `'unknown'` fallback of the kind
+  // `service` and `env` have. That difference is the whole feature — a fabricated commit silences
+  // the shadow-deploy alarm permanently, so an absent value stays absent and the console draws
+  // the break.
+
+  /** `app_id` — the application this service belongs to. Declared, never inferred. */
+  application?: string;
+  /** `github.com/acme/portal`, or `acme/portal` where the platform publishes no host. */
+  repo?: string;
+  /** The commit this artifact was built from. */
+  commit?: string;
+  /** The branch, when the platform published one. */
+  branch?: string;
+  /** The platform's own deployment identifier, e.g. `VERCEL_DEPLOYMENT_ID`. */
+  deploymentId?: string;
+
+  // ── queue and transport ──────────────────────────────────────────────────────────────────
+
+  /** Bounded queue depth. At the limit the OLDEST events are dropped, and drops are counted. */
+  queueCapacity?: number;
+  batchSize?: number;
+  flushIntervalMs?: number;
+  flushDeadlineMs?: number;
+  httpTimeoutMs?: number;
+
+  /**
+   * The host's `waitUntil` (Vercel), so a flush can outlive the response without delaying it.
+   * Also settable later with {@link setWaitUntil}.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+/** Self-report of a deployment. Everything omitted is taken from the resolved config. */
+export interface DeploymentOptions {
+  version?: string;
+  commit?: string;
+  env?: string;
+  repo?: string;
+  appId?: string;
+  /** The platform's id. A deterministic `self:…` key is derived when there is none. */
+  deploymentId?: string;
+  /** Who or what triggered it. Fingerprinted below `full` tier. */
+  actor?: string;
+  startedTs?: string;
+  finishedTs?: string;
+  outcome?: 'succeeded' | 'failed' | 'cancelled' | 'in_progress';
+  /** The `deployment_id` this reverted to. Present only on rollbacks, and load-bearing. */
+  rollbackOf?: string;
+}
+
+export interface IntegrationOptions {
+  /** What it is, in the reader's words — `crm`, `payments`, `warehouse`. */
+  kind?: string;
+  appId?: string;
+  /** Defaults to the configured service. */
+  service?: string;
+  /** Whether credentials were accepted, when the caller can tell that apart from reachability. */
+  authOk?: boolean;
+}
+
+/**
+ * Freshness, recorded separately from liveness — and the separation is the point. Whether the
+ * call completed and how old the data is answer different questions, and merging them destroys
+ * the only fact this feature exists to surface: *the API is healthy and the data is 72 h stale.*
+ */
+export interface IntegrationData {
+  /**
+   * How many rows came back. `0` means *we counted and there were none*; omitting it means *we
+   * did not count*. Those are different facts and nothing here will invent one from the other.
+   */
+  rows?: number;
+  /**
+   * The newest **business** timestamp observed — the last row's `updated_at`, not our own clock,
+   * which would make a probe that fetched nothing look fresh.
+   */
+  watermark?: string | number | Date;
+  /** Wire-name alias for {@link IntegrationData.watermark}. */
+  lastDataTs?: string | number | Date;
+  /** Changes when the response shape changes. A silent schema break, made visible. */
+  schemaFingerprint?: string;
+}
+
+/**
+ * One bracketed observation of an outbound dependency.
+ *
+ * A handle that is never ended emits nothing — we did not observe an outcome, so there is no
+ * observation to record.
+ */
+export interface Integration {
+  readonly name: string;
+  /** Record freshness. Chainable. */
+  data(fields: IntegrationData): Integration;
+  /**
+   * Record that the call did not complete. `errorClass` is content-free (`auth`, `timeout`,
+   * `http_5xx`, `schema`, `transport`) and survives every privacy tier, which is what lets an
+   * alarm branch on it — the free-text `error` does not exist below `full`.
+   */
+  failed(error: unknown, opts?: { errorClass?: string }): Integration;
+  /** The Python SDK's spelling of {@link Integration.failed}. One meaning, two spellings. */
+  fail(error: unknown, opts?: { errorClass?: string }): Integration;
+  /**
+   * Whether the credential was accepted. Only the caller knows; the SDK never guesses.
+   *
+   * Also available as `authOk` on {@link IntegrationOptions}, but that requires knowing the answer
+   * before the call is made — and whether a credential was accepted is precisely what you learn
+   * afterwards. This wins when both are given.
+   */
+  auth(ok: boolean): Integration;
+  /**
+   * Fingerprint the response's **shape**, so a silent schema break is visible before the rows stop
+   * matching. Keys only for an object; never values, at any privacy tier.
+   *
+   * Byte-identical to the Python SDK's digest for an object sample, because the fingerprint is a
+   * wire value two producers write into one column. For a non-object it cannot be — see
+   * PARITY.md §3b.
+   */
+  schema(sample: unknown): Integration;
+  /** Close the probe and emit exactly one observation. Idempotent. */
+  end(error?: unknown): Integration;
+}
+
+export interface ExpectsDataOptions {
+  /** `24h`, `30m`, `7d`, or an ISO-8601 duration. Unparseable spellings ship verbatim, unparsed. */
+  within: string;
+  appId?: string;
+  declaredBy?: string;
+  declaredTs?: string;
+}
+
+export interface AgentOptions {
+  /**
+   * What kind of work this is (`classify`, `summarise`, `refund`…). Coarse and stable by design:
+   * it is what makes runs comparable across services and over time.
+   */
+  goalClass?: string;
+}
+
+export interface OutcomeOptions {
+  /**
+   * Whether the outcome was checked by something other than the model's own claim. Omit it when
+   * nothing checked — do not pass `false` to mean "unknown".
+   */
+  verified?: boolean;
+  /** What did the checking: `test`, `human`, `schema`, `assertion`. Required for `verified` to count. */
+  verifiedBy?: string;
+}
+
+/**
+ * One **logical** model call — not one HTTP request. Vendor clients retry internally; `attempts`
+ * records that, and the call is still billed once.
+ */
+export interface UsageRecord {
+  model: string;
+  provider?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  costUsd?: number;
+  /** How the cost was derived, e.g. `catalog` or `vendor`. Cost without provenance is a rumour. */
+  costSource?: string;
+  /** HTTP attempts behind this one logical call. */
+  attempts?: number;
+  /** `true` when a stream was abandoned before completion, so the numbers are a lower bound. */
+  incomplete?: boolean;
+  /** Set by auto-instrumentation; leave unset when calling by hand. */
+  instrumentation?: Instrumentation;
+}
+
+/**
+ * One effect on the world, bracketed. This is the object the enforcement seam (WP-6) attaches to:
+ * `block()` exists so that a denied action is a first-class record rather than an absence.
+ */
+export interface Action {
+  readonly name: string;
+  readonly target?: string;
+  /** Describe what the action actually did — `{ rows: 3 }`, `{ bytes: 812 }`. Chainable. */
+  effect(fields: Record<string, unknown>): Action;
+  /** Mark the action as refused, with a reason. Chainable. */
+  block(reason: string): Action;
+  /** Close the action, optionally with the error that ended it. Idempotent. */
+  end(error?: unknown): Action;
+}
+
+export interface Run {
+  readonly name: string;
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly goalClass: string | null;
+  /** Open an action within this run. */
+  action(name: string, target?: string): Action;
+  /** Record one logical model call. */
+  usage(record: UsageRecord): Run;
+  /** Record what the run achieved. */
+  outcome(outcome: Outcome, opts?: OutcomeOptions): Run;
+  /** Close the run. Idempotent; safe from a `finally`. */
+  end(error?: unknown): Run;
+}
+
+/** The SDK's account of itself: events emitted and dropped, sink failures, contained errors. */
+export interface Counters {
+  emitted?: number;
+  dropped?: number;
+  [key: string]: number | undefined;
+}
+
+/**
+ * Declare service identity and arm the SDK. Idempotent — safe to call from both `main()` and a
+ * framework startup hook. Optional: the first `agent()` call arms the SDK with defaults.
+ */
+export function init(opts?: InitOptions): void;
+
+/**
+ * Open a run: one unit of agent work, with an outcome.
+ *
+ * The returned object must be closed with `end()`. Prefer {@link withAgent} in async code — see
+ * the note there.
+ */
+export function agent(name: string, opts?: AgentOptions): Run;
+
+/**
+ * Scoped run. **Prefer this in async code.** Only this form propagates the current run across
+ * `await` boundaries (via `AsyncLocalStorage`); the object returned by {@link agent} cannot,
+ * because concurrent runs in one process would interleave on a shared stack.
+ *
+ * The run is closed automatically, including on throw, and the application's exception is
+ * re-thrown unchanged.
+ */
+export function withAgent<T>(name: string, fn: (run: Run) => Promise<T> | T): Promise<T>;
+export function withAgent<T>(
+  name: string,
+  opts: AgentOptions,
+  fn: (run: Run) => Promise<T> | T,
+): Promise<T>;
+
+/**
+ * Open an action against the run currently in context — for code several frames below the call
+ * that opened the run, where threading a `Run` argument through would be intrusive.
+ */
+export function action(name: string, target?: string): Action;
+
+/** The run currently in context, or `null`. */
+export function currentRun(): Run | null;
+
+/**
+ * Drain the queue within a deadline. Call before a process that is about to stop.
+ *
+ * Asynchronous, and deliberately: the calling thread never performs I/O, so there is no
+ * synchronous form to offer. The deadline is bounded on purpose — the collector is exactly the
+ * thing most likely to be unhealthy while a fleet is restarting, and a telemetry SDK that will
+ * not let a pod terminate has become the outage.
+ */
+export function flush(deadlineMs?: number): Promise<boolean>;
+
+/** Final flush, then stop the background drain. */
+export function shutdown(deadlineMs?: number): Promise<boolean>;
+
+// ── operate plane (ANCHOR-INTEGRATION §6.1–6.4) ────────────────────────────────────────────
+
+/**
+ * §6.4 — self-report a deployment, for an estate with no CI or cloud connector wired.
+ *
+ *     nexus.deployment({ version: '2026.8.1', commit: SHA, env: 'prod' });
+ *
+ * Always stamped `detected_by: 'self'`, which is not a parameter: a process asserting its own
+ * deployment is the weakest evidence on the plane — precisely what a shadow deploy would also
+ * produce — and a caller able to claim `'ci'` could erase that distinction with one argument.
+ *
+ * @returns whether a record was emitted. `false` when neither a version nor a commit is known,
+ *   because a deployment record that identifies no software makes the ledger longer, not truer.
+ */
+export function deployment(opts?: DeploymentOptions): boolean;
+
+/**
+ * §6.2 — the silent-failure primitive.
+ *
+ *     const io = nexus.integration('salesforce', { kind: 'crm' });
+ *     try {
+ *       const rows = await client.fetchAccounts();
+ *       io.data({ rows: rows.length, watermark: rows[rows.length - 1].updatedAt });
+ *     } catch (err) { io.failed(err, { errorClass: 'timeout' }); }
+ *     finally { io.end(); }
+ */
+export function integration(name: string, opts?: IntegrationOptions): Integration;
+
+/** The bracketed form of {@link integration}. Re-throws the application's exception unchanged. */
+export function withIntegration<T>(
+  name: string, fn: (io: Integration) => Promise<T> | T,
+): Promise<T>;
+export function withIntegration<T>(
+  name: string, opts: IntegrationOptions, fn: (io: Integration) => Promise<T> | T,
+): Promise<T>;
+
+/**
+ * §6.2 — declare that data is expected within a window.
+ *
+ * An expectation with no matching probe inside its window is the silent-failure alarm. The alarm
+ * fires on **absence of evidence against a declared expectation**, never on absence alone:
+ * absence alone is indistinguishable from "nobody ever declared this".
+ *
+ * Deduplicated per process, so a declaration inside a scheduled function does not re-emit on
+ * every tick.
+ *
+ * @returns whether a declaration was emitted (`false` on a repeat, or with no window).
+ */
+export function expectsData(name: string, opts: ExpectsDataOptions): boolean;
+
+/**
+ * Close the `service_health` window now and emit it, even when nothing was measured.
+ *
+ * The honest form of "this process is alive": a window with a timestamp and **no quantities**. A
+ * `requests: 0` would be a fabricated zero — zero observed spans far more often means "this service
+ * never calls `run.action`" than it means an outage, and on a console the two look identical.
+ *
+ * Call it from a cron, a liveness probe, or a worker that drains a queue slowly. Windows close on
+ * their own every `NEXUS_HEALTH_INTERVAL_MS` when there is traffic; this is for when there is not.
+ *
+ * @returns whether an event was emitted.
+ */
+export function heartbeat(): boolean;
+
+/** Give the SDK the host's `waitUntil` (Vercel), so a flush can outlive the response. */
+export function setWaitUntil(fn: (promise: Promise<unknown>) => void): void;
+
+/**
+ * Wrap a serverless handler so the queue drains before the sandbox freezes.
+ *
+ *     export const handler = nexus.instrumentHandler(async (event) => { … });
+ *
+ * The Node equivalent of Python's `instrument_lambda_handler`. **Without this, or without
+ * `waitUntil`, the last buffered events of every serverless invocation are lost — not delayed,
+ * lost.** A platform freezes the sandbox the instant the handler returns, and no library can read
+ * a signal that says it is about to happen.
+ */
+export function instrumentHandler<F extends (...args: never[]) => unknown>(
+  handler: F, opts?: { budgetMs?: number },
+): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
+
+/** Counters, for asserting in tests and for answering "is it actually capturing?" in production. */
+export function counters(): Counters;
+
+/** `true` unless `NEXUS_ENABLED` (or `init({ enabled: false })`) says otherwise. */
+export function enabled(): boolean;
+
+/**
+ * Which loader armed auto-instrumentation. `none` in a bundled deployment is expected, not a
+ * fault — see `SCOPE.md` §3.
+ */
+export function instrumentation(): Instrumentation;
+
+export const version: string;

package/otel.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `@swfte/nexus-sdk/otel` — the OpenTelemetry span bridge.
+ *
+ * Reads spans from whichever GenAI instrumentation you already run — OTel semantic conventions,
+ * OpenInference, OpenLLMetry/OpenLIT — and turns them into nexus events. **This package has no
+ * dependency on any `@opentelemetry/*` package**: `spanProcessor()` returns a plain object with the
+ * four methods the `SpanProcessor` interface requires, and your provider calls it.
+ *
+ *     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();
+ *
+ * Three properties worth knowing before you rely on it:
+ *
+ * 1. **An unclassified span is dropped, not guessed at.** A GenAI span whose kind this bridge does
+ *    not model is counted under `bridge_unclassified` and emitted nowhere — never defaulted into
+ *    `behavior_trace`, which is the class the ledger treats as evidence.
+ * 2. **Model text is re-gated by your privacy tier**, because upstream redaction is not trusted:
+ *    every instrumentation in this space has its own content switch and its own idea of what a
+ *    secret looks like, and some have none. Even `full` is redacted.
+ * 3. **One span, one observation.** The multi-span logical-call join that deduplicates retries is
+ *    not ported. Against an instrumentation that emits a span per HTTP attempt, token counts sum
+ *    across attempts rather than being deduplicated. See PARITY.md §6.
+ */
+
+/**
+ * The `SpanProcessor` interface, structurally. Deliberately not typed against
+ * `@opentelemetry/sdk-trace-base` — naming that type would require depending on it.
+ */
+export interface NexusSpanProcessor {
+  onStart(span: unknown, parentContext?: unknown): void;
+  onEnd(span: unknown): void;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+export interface BridgeOptions {
+  /**
+   * Throw on a GenAI span whose kind has no epistemic class, instead of dropping and counting it.
+   *
+   * Defaults to on under `node --test` and `NODE_ENV=test`, off otherwise — the two environments
+   * want opposite failure modes. A new span kind should fail a build; in production it should
+   * degrade to a counted gap rather than an exception on a request path.
+   */
+  strict?: boolean;
+  /** Build a new bridge rather than reusing the process-wide one. Mostly for tests. */
+  fresh?: boolean;
+}
+
+/** What the bridge has seen since it was created or reset. */
+export interface BridgeStats {
+  /** Spans handed to the bridge, of any kind. */
+  seen: number;
+  /** Spans that produced at least one event. */
+  emitted: number;
+  /** Spans that were not GenAI at all — an HTTP call, a DB query. Not a coverage gap. */
+  ignored: number;
+  /** GenAI spans whose kind is not modelled. **This is the number worth alerting on.** */
+  unclassified: number;
+}
+
+/**
+ * A span processor to register with your `TracerProvider`.
+ *
+ * Only `onEnd` does work: a span's attributes are not complete until it closes, and reading them at
+ * `onStart` would report a call that has not happened yet.
+ */
+export function spanProcessor(opts?: BridgeOptions): NexusSpanProcessor;
+
+/** Read one finished span and emit its events directly, without a provider. */
+export function ingest(span: unknown): boolean;
+
+/** Bridge counters. `unclassified` rising is a coverage gap, not a fault in your application. */
+export function stats(): BridgeStats;
+
+/** The semconv release the reader targets. The spec is pre-stable and will move. */
+export const SEMCONV_TAG: Readonly<{ genai: string; stability: string }>;