retrace-sdk 0.11.0 → 0.11.2

package/dist/recorder.d.ts

@@ -1,6 +1,8 @@
 import { SpanBuilder, SpanData, SpanType, TraceStatus } from "./trace.js";
 /** Drain the shared transport's in-flight data to the network (awaited on graceful shutdown). */
 export declare function flushSharedTransport(): Promise<void>;
+/** Exit-path drain — uses the transport's HTTP one-shot for buffered events when available. */
+export declare function drainSharedTransportOnExit(budgetMs?: number): Promise<void>;
 export interface RecordOptions {
     name?: string;
     input?: unknown;
@@ -13,19 +15,45 @@ export declare class TraceRecorder {
     private builder;
     private transport;
     private interceptorsInstalled;
+    private countedImperative;
+    private prevFallback;
+    private prevFallbackSink;
     private forkPointSpanId;
     private forkPointReached;
     private spanCounter;
     output: unknown;
     constructor(opts?: RecordOptions);
     get traceId(): string;
-    start(name?: string, input?: unknown): this;
-    end(output?: unknown, status?: TraceStatus): void;
+    start(name?: string, input?: unknown, opts?: {
+        managed?: boolean;
+    }): this;
+    private openSpans;
+    registerOpenSpan(spanId: string, finalize: (reason: "complete" | "partial") => void): void;
+    unregisterOpenSpan(spanId: string): void;
+    /** Finalize any still-open streaming spans as partial (capture_complete:false). Called on end()
+     *  so a stream the AFC layer abandoned mid-drain is still emitted into the trace, flagged
+     *  not-byte-replayable, rather than lost or appearing only at process exit. */
+    private finalizeOpenSpans;
+    end(output?: unknown, status?: TraceStatus, opts?: {
+        terminatedEarly?: boolean;
+    }): void;
     addSpan(span: SpanData): void;
     startSpan(name: string, spanType?: SpanType, input?: unknown, model?: string, parentId?: string): SpanBuilder;
     endSpan(spanBuilder: SpanBuilder, output?: unknown, error?: string): void;
     private installInterceptors;
 }
+/**
+ * Create a manual (imperative) recorder you drive with start()/end().
+ *
+ * CONCURRENCY: this bare imperative path is NOT context-isolated — start()/end() have no async
+ * scope to bind, so span-routing and traceparent are tracked via process/async-context state that
+ * concurrent imperative traces (e.g. several started under one Promise.all) can stomp. For
+ * concurrent workloads use `trace()`, which wraps your function in AsyncLocalStorage (provably
+ * isolated). Sequential start→end cycles are correct, and overlapping imperative use is detected
+ * and LOUDLY WARNED (never silent corruption) — pointing you at `trace()`. (Python's `@record`
+ * decorator wraps the function and IS isolated on both asyncio and threads; the TS equivalent is
+ * `trace()`.)
+ */
 export declare function record(opts?: RecordOptions): TraceRecorder;
 export declare function trace<T>(fn: (...args: unknown[]) => T, opts?: RecordOptions & {
     resumable?: boolean;

package/dist/recorder.js

@@ -1,19 +1,37 @@
 import { getConfig, requireApiKey } from "./config.js";
 import { SpanBuilder, SpanType, TraceBuilder, TraceStatus } from "./trace.js";
-import { createTransport } from "./transport.js";
+import { createTransport, registerProcessExitFlush } from "./transport.js";
 import { shouldSample } from "./utils.js";
 import { installGeminiInterceptor } from "./interceptors/gemini.js";
 import { installOpenAIInterceptor } from "./interceptors/openai.js";
 import { installAnthropicInterceptor } from "./interceptors/anthropic.js";
+import { dispatchInterceptedSpan, runWithActiveRecorder, setActiveRecorderFallback, currentFallbackSink } from "./interceptors/_dispatch.js";
+import { withTraceContext, enterTraceContext, exitTraceContext } from "./traceparent.js";
 // Shared transport — stays open across multiple traces for resume/replay listening
 let sharedTransport = null;
+// Count of imperative (non-HOF) recorders currently between start() and end(). The bare imperative
+// record()/TraceRecorder path is NOT context-isolated (see record() doc + traceparent.ts), so two
+// overlapping imperative traces can cross-attribute spans/traceparent. We can't make it isolated
+// without an async scope, but we MUST NOT let the corruption be silent — overlap is loudly warned,
+// pointing at trace() (the concurrency-safe API). HOF-managed starts pass {managed:true} and are
+// excluded (they ARE isolated via withTraceContext/runWithActiveRecorder).
+let activeImperativeRecorders = 0;
 function getSharedTransport() {
     if (!sharedTransport) {
         sharedTransport = createTransport(getConfig().transport);
-        // Flush pending data before the process exits. Flushing (not just close) ensures the
-        // final trace is actually uploaded — close() alone can race the process exiting.
-        if (typeof process !== "undefined") {
-            process.on("beforeExit", () => { void flushSharedTransport(); });
+        // Hand the transport the user's callback (or undefined). The transport owns the policy:
+        // callback-safety (a throwing onError can't kill the WS loop) and the throttled default-warn
+        // when no callback is registered — see WSTransport.surfaceSignal. Set onError in configure()
+        // before the first trace.
+        sharedTransport.onError = getConfig().onError;
+        // Flush pending data before the process exits. Covers beforeExit (graceful) + SIGTERM/SIGINT
+        // (with signal-ownership semantics), using an HTTP one-shot for buffered events since a WS
+        // handshake can't reliably complete during teardown. See registerProcessExitFlush.
+        // Only register the network exit hook when actually configured — an imported-but-unconfigured
+        // SDK installs no signal handlers and makes no outbound call on exit.
+        const cfg = getConfig();
+        if (typeof process !== "undefined" && cfg.enabled && cfg.apiKey) {
+            registerProcessExitFlush(sharedTransport);
         }
     }
     return sharedTransport;
@@ -22,10 +40,20 @@ function getSharedTransport() {
 export async function flushSharedTransport() {
     await sharedTransport?.flush();
 }
+/** Exit-path drain — uses the transport's HTTP one-shot for buffered events when available. */
+export async function drainSharedTransportOnExit(budgetMs) {
+    if (sharedTransport?.flushOnExit)
+        await sharedTransport.flushOnExit(budgetMs);
+    else
+        await sharedTransport?.flush();
+}
 export class TraceRecorder {
     builder;
     transport;
     interceptorsInstalled = false;
+    countedImperative = false;
+    prevFallback = null;
+    prevFallbackSink = null;
     forkPointSpanId;
     forkPointReached = false;
     spanCounter = 0;
@@ -49,15 +77,67 @@ export class TraceRecorder {
         }
     }
     get traceId() { return this.builder.id; }
-    start(name, input) {
+    start(name, input, opts) {
+        // Never-silent guard for the imperative path: if another imperative trace is already active when
+        // this one starts, overlapping imperative record() use can cross-attribute spans/traceparent.
+        // Warn loudly and point at trace() — convert silent corruption into a loud signal. HOF-managed
+        // starts are isolated (withTraceContext) and excluded.
+        if (!opts?.managed) {
+            if (activeImperativeRecorders > 0) {
+                console.warn("[retrace] CONCURRENT imperative record() detected: another imperative trace is still active. " +
+                    "The bare record()/TraceRecorder path is NOT concurrency-isolated — spans and traceparent from " +
+                    "overlapping imperative traces can be cross-attributed. Use trace() (the concurrency-safe API) " +
+                    "for concurrent/parallel workloads.");
+            }
+            activeImperativeRecorders++;
+            this.countedImperative = true;
+        }
         this.builder.start(name, input);
         this.installInterceptors();
+        // Imperative API: route intercepted spans to this recorder and propagate trace context for
+        // outbound requests. Save the prior fallback so end() can RESTORE it (a nested trace() must not
+        // wipe the ambient init() fallback). The trace()/HOF path additionally isolates via ALS.
+        this.prevFallbackSink = currentFallbackSink();
+        this.prevFallback = setActiveRecorderFallback((span) => this.addSpan(span), this);
+        // ALS-isolated traceparent (per async execution), NOT a module global — so concurrent imperative
+        // traces never leak context into one another's outbound requests. The trace()/HOF path also
+        // wraps in withTraceContext; this covers the bare start()/end() imperative path.
+        enterTraceContext(this.builder.id, this.builder.id);
         this.transport.send("trace_started", this.builder.toDict());
         return this;
     }
-    end(output, status = TraceStatus.COMPLETED) {
+    // ── OpenSpanSink: two-phase streaming spans (open at invocation, finalize once) ──
+    openSpans = new Map();
+    registerOpenSpan(spanId, finalize) {
+        this.openSpans.set(spanId, finalize);
+    }
+    unregisterOpenSpan(spanId) {
+        this.openSpans.delete(spanId);
+    }
+    /** Finalize any still-open streaming spans as partial (capture_complete:false). Called on end()
+     *  so a stream the AFC layer abandoned mid-drain is still emitted into the trace, flagged
+     *  not-byte-replayable, rather than lost or appearing only at process exit. */
+    finalizeOpenSpans() {
+        if (this.openSpans.size === 0)
+            return;
+        for (const [, finalize] of this.openSpans) {
+            try {
+                finalize("partial");
+            }
+            catch { /* best effort */ }
+        }
+        this.openSpans.clear();
+    }
+    end(output, status = TraceStatus.COMPLETED, opts) {
+        if (this.countedImperative) {
+            activeImperativeRecorders = Math.max(0, activeImperativeRecorders - 1);
+            this.countedImperative = false;
+        }
         if (output !== undefined)
             this.output = output;
+        // Close any dangling streaming spans (capture_complete:false) BEFORE the terminal event, so
+        // they land in this trace.
+        this.finalizeOpenSpans();
         const data = this.builder.end(this.output, status);
         this.transport.send("trace_ended", {
             id: data.id,
@@ -66,7 +146,16 @@ export class TraceRecorder {
             status: data.status,
             total_tokens: data.total_tokens,
             total_cost: data.total_cost,
+            // Force-closed by exit-flush/signal: a synthesized terminal must NOT look clean to the
+            // replay-guard. terminated_early ⇒ refuse byte-deterministic replay (same as no-terminal /
+            // lossy / capture_complete:false). Only a naturally-drained run produces a clean terminal.
+            ...(opts?.terminatedEarly ? { terminated_early: true } : {}),
         });
+        // Restore the enclosing trace's fallback (e.g. the ambient init() recorder) instead of nulling.
+        setActiveRecorderFallback(this.prevFallback, this.prevFallbackSink);
+        this.prevFallback = null;
+        this.prevFallbackSink = null;
+        exitTraceContext();
         // Shared transport stays open for resume/replay listening
     }
     addSpan(span) {
@@ -125,12 +214,26 @@ export class TraceRecorder {
     installInterceptors() {
         if (this.interceptorsInstalled)
             return;
-        installGeminiInterceptor((span) => this.addSpan(span));
-        installOpenAIInterceptor((span) => this.addSpan(span));
-        installAnthropicInterceptor((span) => this.addSpan(span));
+        // Install ONE stable dispatcher; the active recorder is resolved per async-context (see
+        // interceptors/_dispatch.ts) so concurrent traces don't cross-route intercepted spans.
+        installGeminiInterceptor(dispatchInterceptedSpan);
+        installOpenAIInterceptor(dispatchInterceptedSpan);
+        installAnthropicInterceptor(dispatchInterceptedSpan);
         this.interceptorsInstalled = true;
     }
 }
+/**
+ * Create a manual (imperative) recorder you drive with start()/end().
+ *
+ * CONCURRENCY: this bare imperative path is NOT context-isolated — start()/end() have no async
+ * scope to bind, so span-routing and traceparent are tracked via process/async-context state that
+ * concurrent imperative traces (e.g. several started under one Promise.all) can stomp. For
+ * concurrent workloads use `trace()`, which wraps your function in AsyncLocalStorage (provably
+ * isolated). Sequential start→end cycles are correct, and overlapping imperative use is detected
+ * and LOUDLY WARNED (never silent corruption) — pointing you at `trace()`. (Python's `@record`
+ * decorator wraps the function and IS isolated on both asyncio and threads; the TS equivalent is
+ * `trace()`.)
+ */
 export function record(opts) {
     const cfg = getConfig();
     if (!cfg.enabled || !shouldSample(cfg.sampleRate, cfg.sampleSeed, opts?.name)) {
@@ -165,19 +268,25 @@ export function trace(fn, opts) {
             input: opts?.input ?? args,
             metadata: opts?.metadata,
         });
-        recorder.start(opts?.name || fn.name || "anonymous", opts?.input ?? args);
-        try {
-            const result = fn(...args);
-            // Handle async functions
-            if (result && typeof result.then === "function") {
-                return result.then((resolved) => { recorder.end(resolved, TraceStatus.COMPLETED); return resolved; }, (err) => { recorder.end(undefined, TraceStatus.FAILED); throw err; });
+        // Isolate this trace's intercepted-span routing AND traceparent context to its own async
+        // context, so concurrent traces on a server never cross-route spans or leak context.
+        const tid = recorder.traceId;
+        const route = (span) => recorder.addSpan(span);
+        return runWithActiveRecorder(route, () => withTraceContext(tid, tid, () => {
+            recorder.start(opts?.name || fn.name || "anonymous", opts?.input ?? args, { managed: true });
+            try {
+                const result = fn(...args);
+                // Handle async functions
+                if (result && typeof result.then === "function") {
+                    return result.then((resolved) => { recorder.end(resolved, TraceStatus.COMPLETED); return resolved; }, (err) => { recorder.end(undefined, TraceStatus.FAILED); throw err; });
+                }
+                recorder.end(result, TraceStatus.COMPLETED);
+                return result;
             }
-            recorder.end(result, TraceStatus.COMPLETED);
-            return result;
-        }
-        catch (err) {
-            recorder.end(undefined, TraceStatus.FAILED);
-            throw err;
-        }
+            catch (err) {
+                recorder.end(undefined, TraceStatus.FAILED);
+                throw err;
+            }
+        }), recorder);
     };
 }

package/dist/stream.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `stream()` — opt-in full-fidelity wrapper for an LLM stream.
+ *
+ * Wrap a provider stream so that the auto-captured span observes a CLEAN full drain even if you stop
+ * iterating early — giving you a byte-replay-eligible span (`capture_complete: true`) for a stream you
+ * only partially consume:
+ *
+ * ```ts
+ * for await (const chunk of stream(ai.models.generateContentStream({ ... }))) {
+ *   render(chunk);
+ *   if (enough) break;   // the rest is still drained in the background → full capture
+ * }
+ * ```
+ *
+ * It does NOT record its own span — it relies on the auto-interceptor's capture. So the
+ * function-call rule still applies: a stream that emits a function call stays
+ * `capture_complete: false` regardless of how it's drained. The helper's guarantee is
+ * "true when there is no function call", never "true, period" — it can't force a function-call
+ * stream to look byte-replayable.
+ *
+ * Opt-in cost: if you break early, the remainder of the stream is still consumed (the provider may
+ * bill for the full generation) — so wrapping with `stream()` TRADES AWAY the cost/latency savings
+ * of your early stop in exchange for guaranteed full-fidelity capture. If you broke early to save
+ * money, do not wrap with `stream()`.
+ */
+export declare function stream<T>(src: AsyncIterable<T> | Promise<AsyncIterable<T>>): AsyncGenerator<T>;

package/dist/stream.js

@@ -0,0 +1,56 @@
+/**
+ * `stream()` — opt-in full-fidelity wrapper for an LLM stream.
+ *
+ * Wrap a provider stream so that the auto-captured span observes a CLEAN full drain even if you stop
+ * iterating early — giving you a byte-replay-eligible span (`capture_complete: true`) for a stream you
+ * only partially consume:
+ *
+ * ```ts
+ * for await (const chunk of stream(ai.models.generateContentStream({ ... }))) {
+ *   render(chunk);
+ *   if (enough) break;   // the rest is still drained in the background → full capture
+ * }
+ * ```
+ *
+ * It does NOT record its own span — it relies on the auto-interceptor's capture. So the
+ * function-call rule still applies: a stream that emits a function call stays
+ * `capture_complete: false` regardless of how it's drained. The helper's guarantee is
+ * "true when there is no function call", never "true, period" — it can't force a function-call
+ * stream to look byte-replayable.
+ *
+ * Opt-in cost: if you break early, the remainder of the stream is still consumed (the provider may
+ * bill for the full generation) — so wrapping with `stream()` TRADES AWAY the cost/latency savings
+ * of your early stop in exchange for guaranteed full-fidelity capture. If you broke early to save
+ * money, do not wrap with `stream()`.
+ */
+export async function* stream(src) {
+    const iterable = (await src);
+    const it = iterable[Symbol.asyncIterator]();
+    let drainedToEnd = false;
+    try {
+        while (true) {
+            const r = await it.next();
+            if (r.done) {
+                drainedToEnd = true;
+                break;
+            }
+            yield r.value;
+        }
+    }
+    finally {
+        // Consumer broke early — finish draining the source so the auto-captured span sees a clean
+        // drain. (Function-call streams still finalize capture_complete:false in the auto path.)
+        if (!drainedToEnd) {
+            try {
+                for (;;) {
+                    const r = await it.next();
+                    if (r.done)
+                        break;
+                }
+            }
+            catch {
+                /* best-effort drain */
+            }
+        }
+    }
+}

package/dist/traceparent.d.ts

@@ -6,8 +6,26 @@
  * When a traced function makes HTTP calls, the traceparent header
  * is injected so downstream services can correlate their spans.
  */
-/** Set the active trace context for outgoing requests. */
+/**
+ * Run `fn` with an isolated trace context. Outgoing-request helpers (getTraceparent /
+ * injectTraceparent) called within `fn` (including across awaits) see this context, with
+ * no cross-contamination between concurrent traces.
+ */
+export declare function withTraceContext<T>(traceId: string, spanId: string, fn: () => T): T;
+/** Set the active trace context for outgoing requests (legacy imperative API). */
 export declare function setTraceContext(traceId: string, spanId: string): void;
+/**
+ * Imperative ALS context for the recorder's start()/end(), which have no callback scope to wrap.
+ * Uses AsyncLocalStorage.enterWith so the context is isolated PER ASYNC EXECUTION — two concurrent
+ * imperative traces (each in its own async context) get their own store instead of clobbering a
+ * shared module global. This is the fix for the old setTraceContext()-writes-a-global contamination:
+ * the recorder no longer touches _currentTraceId at all; the globals remain ONLY for the explicitly
+ * legacy, single-context setTraceContext() public API.
+ */
+export declare function enterTraceContext(traceId: string, spanId: string): void;
+/** Clear the imperative ALS context for the current execution (empty store → getTraceparent returns
+ *  null WITHOUT falling through to the legacy globals). */
+export declare function exitTraceContext(): void;
 /** Clear the active trace context. */
 export declare function clearTraceContext(): void;
 /** Get the current traceparent header value, or null if no active trace. */

package/dist/traceparent.js

@@ -6,15 +6,44 @@
  * When a traced function makes HTTP calls, the traceparent header
  * is injected so downstream services can correlate their spans.
  */
+import { AsyncLocalStorage } from "async_hooks";
+// Per-async-context trace context. Concurrent traces each get their own store, so one
+// trace's context can't leak into another's outbound requests. The module-level globals
+// below remain as a fallback for the legacy imperative setTraceContext/clearTraceContext API.
+const traceContextStore = new AsyncLocalStorage();
 let _currentTraceId = null;
 let _currentSpanId = null;
-/** Set the active trace context for outgoing requests. */
+/**
+ * Run `fn` with an isolated trace context. Outgoing-request helpers (getTraceparent /
+ * injectTraceparent) called within `fn` (including across awaits) see this context, with
+ * no cross-contamination between concurrent traces.
+ */
+export function withTraceContext(traceId, spanId, fn) {
+    return traceContextStore.run({ traceId: traceId.replace(/-/g, ""), spanId: spanId.replace(/-/g, "").slice(0, 16) }, fn);
+}
+/** Set the active trace context for outgoing requests (legacy imperative API). */
 export function setTraceContext(traceId, spanId) {
     // Convert UUID format to 32-hex (remove dashes)
     _currentTraceId = traceId.replace(/-/g, "");
     // Take first 16 chars of span ID as parent span
     _currentSpanId = spanId.replace(/-/g, "").slice(0, 16);
 }
+/**
+ * Imperative ALS context for the recorder's start()/end(), which have no callback scope to wrap.
+ * Uses AsyncLocalStorage.enterWith so the context is isolated PER ASYNC EXECUTION — two concurrent
+ * imperative traces (each in its own async context) get their own store instead of clobbering a
+ * shared module global. This is the fix for the old setTraceContext()-writes-a-global contamination:
+ * the recorder no longer touches _currentTraceId at all; the globals remain ONLY for the explicitly
+ * legacy, single-context setTraceContext() public API.
+ */
+export function enterTraceContext(traceId, spanId) {
+    traceContextStore.enterWith({ traceId: traceId.replace(/-/g, ""), spanId: spanId.replace(/-/g, "").slice(0, 16) });
+}
+/** Clear the imperative ALS context for the current execution (empty store → getTraceparent returns
+ *  null WITHOUT falling through to the legacy globals). */
+export function exitTraceContext() {
+    traceContextStore.enterWith({ traceId: "", spanId: "" });
+}
 /** Clear the active trace context. */
 export function clearTraceContext() {
     _currentTraceId = null;
@@ -22,10 +51,13 @@ export function clearTraceContext() {
 }
 /** Get the current traceparent header value, or null if no active trace. */
 export function getTraceparent() {
-    if (!_currentTraceId || !_currentSpanId)
+    const scoped = traceContextStore.getStore();
+    const traceId = scoped?.traceId ?? _currentTraceId;
+    const spanId = scoped?.spanId ?? _currentSpanId;
+    if (!traceId || !spanId)
         return null;
     // version-trace_id-parent_id-flags (01 = sampled)
-    return `00-${_currentTraceId}-${_currentSpanId}-01`;
+    return `00-${traceId}-${spanId}-01`;
 }
 /**
  * Inject traceparent into a headers object (for fetch/axios/http calls).

package/dist/transport.d.ts

@@ -1,8 +1,18 @@
+import { type RetraceServerSignal } from "./errors.js";
 export interface Transport {
     send(eventType: string, data: Record<string, unknown>): void;
     close(): void;
     /** Drain in-flight data to the network (awaited on graceful shutdown). */
     flush(): Promise<void>;
+    /** Exit/signal path: drain via the most reliable channel for teardown (HTTP one-shot for
+     *  buffered events), bounded by budgetMs. Falls back to flush() when not implemented. */
+    flushOnExit?(budgetMs?: number): Promise<void>;
+    /** True if there is anything worth flushing (buffered events or an unsent in-flight payload).
+     *  Lets the exit path no-op — no fetch, no delay — for a zero-event run. */
+    hasPendingData?(): boolean;
+    /** Server-signal channel: a STRUCTURED signal (code/retryable/fatal), not a raw string — branch
+     *  on `signal.code`, never string-match `signal.message`. */
+    onError?: (signal: RetraceServerSignal) => void;
 }
 export declare class WSTransport implements Transport {
     private ws;
@@ -11,16 +21,51 @@ export declare class WSTransport implements Transport {
     private backoff;
     private queue;
     private reconnectTimer;
-    onError?: (type: string, message: string) => void;
+    private lossyTraces;
+    private droppedOpenSpanIds;
+    private droppedTotal;
+    private lastDropWarnMs;
+    private lastSignalWarnMs;
+    onError?: (signal: RetraceServerSignal) => void;
     get isConnected(): boolean;
+    /** Whether a trace lost events to a buffer drop (so the API/replay can refuse byte-replay). */
+    isTraceLossy(traceId: string): boolean;
     connect(): void;
     private reconnect;
     private flushQueue;
+    /** Serialize + send a single event, stamping trace-level `lossy` on a trace_ended whose trace
+     *  lost events to a buffer drop (so the server/replay can refuse byte-deterministic replay). */
+    private transmit;
+    /** Enqueue with a bounded (1000) buffer. On overflow drop the OLDEST event, mark its trace lossy,
+     *  and if it was an open span (span_started) remember its id so the later close is a no-op. */
+    private enqueue;
+    /** Throttled drop warning — at most once per ~5s burst, reporting the CUMULATIVE count (a
+     *  single-tick burst that exits before the next window would otherwise under-report). A final
+     *  summary is emitted on close(). */
+    private recordDrop;
+    /** Surface a structured server signal. If the user registered onError, invoke it WRAPPED — a
+     *  throwing user callback must never kill the listener / WS loop (classic footgun). With no
+     *  callback, fall back to a throttled console warning (per code) — never silent, never an
+     *  unthrottled storm. */
+    private surfaceSignal;
+    private warnUnknownType;
+    /** At most one warn per ~5s per key, so a storm (rate_limited, unknown frames) can't flood. */
+    private throttledSignalWarn;
+    /** Whether there is anything worth flushing on exit. */
+    hasPendingData(): boolean;
     send(eventType: string, data: Record<string, unknown>): void;
     close(): void;
     /** Wait for the socket's send buffer to drain so the final trace_ended actually leaves
      *  the process before exit. Best-effort with a hard timeout. */
     flush(): Promise<void>;
+    /** Exit path: drain a live socket if connected, then HTTP one-shot anything still buffered.
+     *  A WS handshake can't reliably complete during teardown, so buffered events (the common
+     *  short-lived-script case where WS never connected) go out over HTTP keepalive instead. */
+    flushOnExit(budgetMs?: number): Promise<void>;
+    /** POST whatever is still buffered over a bounded HTTP keepalive request, grouped by trace.
+     *  Incomplete traces (no terminal trace_ended buffered) and already-lossy traces are stamped
+     *  lossy:true so the server/replay refuses byte-deterministic replay. */
+    private flushViaHttp;
 }
 export declare class HTTPTransport implements Transport {
     private traceData;
@@ -29,5 +74,30 @@ export declare class HTTPTransport implements Transport {
     flush(): Promise<void>;
     private buildSpans;
     close(): void;
+    /** HTTP is already the one-shot channel — just drain. */
+    flushOnExit(): Promise<void>;
+    hasPendingData(): boolean;
 }
 export declare function createTransport(mode?: "ws" | "http" | "auto"): Transport;
+export type ExitReason = "graceful" | "signal" | "uncaught";
+/**
+ * Register a synchronous hook run on the exit/signal path BEFORE the transport drains — e.g. the
+ * ambient trace finishing itself (emitting trace_ended) so it's in the buffer for the drain.
+ */
+export declare function onProcessExit(fn: (reason: ExitReason) => void): void;
+/**
+ * Wire process-exit flushing for a shared transport. Node's exit hooks are weaker than Python's
+ * atexit, so we cover three paths with different ownership semantics:
+ *  - beforeExit: graceful (loop emptied naturally). Drain; do not exit (Node exits after).
+ *  - SIGTERM/SIGINT, and WE are the sole listener: adding a listener suppresses Node's default
+ *    terminate, so we now OWN the exit — flush THEN process.exit(), or the process hangs forever.
+ *  - SIGTERM/SIGINT, but the USER already has handlers: best-effort flush only; their handler owns
+ *    exit. We do not exit, and cannot guarantee our async flush completes (a synchronous
+ *    process.exit() in their handler will cut it off).
+ *
+ * Irreducible residual (both SDKs): process.exit() mid-flush, os._exit(), and SIGKILL bypass these
+ * hooks entirely and lose still-buffered events; a framework-owned SIGTERM (we stay a guest) drains
+ * only what that framework's shutdown allows. Both SDKs DO flush on a sole-owner SIGTERM (TS via the
+ * listenerCount gate here; Python via a SIG_DFL/main-thread gate) — that parity is real.
+ */
+export declare function registerProcessExitFlush(transport: Transport, budgetMs?: number): void;