@reproapp/node-sdk 0.0.48 → 0.0.50

package/README.md

@@ -107,6 +107,7 @@ await initRepro({
   appName: "Acme Web",
   serviceName: "api",
   apiBase: process.env.REPRO_API_BASE,
+  ingestBase: process.env.REPRO_INGEST_BASE!,
 });
 ```
 
@@ -123,14 +124,56 @@ await initRepro({
   liveMode: {
     enabled: true,
     backendOnly: true,
-    defineActorId: ({ req, ip }) => req.headers["x-user-id"] ?? (ip ? `ip:${ip}` : null),
+    // Trust only a header that your authenticated gateway overwrites.
+    defineActorId: ({ req }) => req.headers["x-user-id"] ?? null,
     shouldCapture: ({ path }) => path.startsWith("/api/") && !path.includes("/health"),
     actorType: "user",
     actorLabels: ({ path }) => ({ routeGroup: path.split("/").filter(Boolean)[0] ?? "api" }),
+    liveCapture: { sampleRate: 0.1, targets: [] },
   },
 });
 ```
 
+### Sampling, limits and runtime targets
+
+Backend-owned live capture accepts `liveMode.liveCapture.sampleRate` from 0 to 1
+(default 1 for compatibility). A chain keeps its sample decision until five minutes
+of inactivity. Actor identity separates chains; three-minute child segments admit
+new work. Admitted requests and their queue/DB/trace tails stay in the original
+segment even when delivery finishes later. Browser-correlated captures use the
+browser's admission decision, rather than sampling a second time.
+
+Keep the `liveCapture` object in your runtime configuration and replace its `targets`
+array when a support case starts or ends. Example target entries:
+
+```ts
+const liveCapture = {
+  sampleRate: 0.1,
+  targets: [
+    { actorIds: ['user-123'], expiresAt: Date.now() + 3600000 },
+    { labels: { routeGroup: 'reports' }, expiresAt: Date.now() + 3600000 },
+  ],
+};
+// Pass this object as liveMode.liveCapture; update liveCapture.targets at runtime.
+```
+
+Targets override sampling, including rate 0, but never quota admission. All labels
+in one target must match; actor IDs and label selectors are alternatives. Use a
+trusted identity source, not arbitrary client-controlled headers.
+
+Live business values have depth 10, 100 keys per object, and 100 entries per array,
+Map, Set or native collection. Partial captures carry explicit omitted path/reason/
+count metadata. `captureRaw: true` bypasses privacy processing, not live limits.
+Staging business values are unchanged. Both modes project recognized runtime
+infrastructure (connections, pools, framework/configuration machinery) into compact
+descriptions; business documents, queries, results and application payloads remain
+evidence. Unknown objects are treated as business data.
+
+HTTP 429 honors `Retry-After` without dropping critical uploads. Quota refusal (402)
+and deleted/failed capture refusal (410) stop retrying that refused batch; business
+requests continue. Quota-enabled installations must use the configured collector,
+not the legacy direct API evidence endpoints.
+
 ## Manual Wiring
 
 Use the lower-level exports when auto-attach is not appropriate or when you need

package/dist/index.d.ts

@@ -28,6 +28,7 @@ import type { Schema } from 'mongoose';
 import { type IngestClientConfig } from './ingest/client';
 import { type NormalizedRuntimePrivacyPolicy, type RuntimePrivacyConfig, type RuntimePrivacyDbContext, type RuntimePrivacySurface } from './privacy';
 import { projectSemanticInfrastructureValue } from './semantic-serialization';
+import { type CaptureOmission } from './live-capture-limits';
 type SpanContext = {
     traceId: string | null;
     spanId: string | number | null;
@@ -88,6 +89,8 @@ type PendingTraceEventRecord = TraceEventRecord & {
     __reproTraceValueEntries?: TraceValueBatchEntry[];
 };
 type TraceValueCaptureRef = {
+    complete?: boolean;
+    omissions?: CaptureOmission[];
     status: 'stored' | 'truncated-for-storage' | 'skipped-non-meaningful' | 'failed-policy';
     valueId?: string;
     projectedKind?: string;
@@ -107,6 +110,7 @@ type TraceValueBatchEntry = {
     eventIndex?: number;
 };
 type TraceMaterializationConfig = {
+    captureMode?: 'live' | 'staging';
     tenantId: string;
     appId: string;
     appSecret?: string;
@@ -284,6 +288,7 @@ type NativeMongoSuppression = {
     ownerStore?: Ctx;
 };
 type RequestCaptureScopeState = {
+    liveCapture?: boolean;
     requestRid: string;
     transport: 'http' | 'kafka' | 'amqp' | 'background';
     backendRequestCount: number;
@@ -299,6 +304,7 @@ type RequestCaptureScopeState = {
     privacyPolicyFingerprint?: string;
     privacyStatementCount: number;
     emittedValueDefinitionIds: Set<string>;
+    traceObservationSnapshots: Map<string, any>;
 };
 type BackendLiveTimingConfig = {
     sessionMaxDurationMs: number;
@@ -341,6 +347,8 @@ declare function getEventTraceValueEntries(event: TraceEventRecord | PendingTrac
 declare function estimateTraceBatchSerializedBytes(batch: TraceEventRecord[], requestRid: string, actionId: string | null | undefined, batchIndex: number, previouslyEmittedValueIds?: ReadonlySet<string>): number;
 declare function chunkTraceEventsForTransport(events: TraceEventRecord[], requestRid: string, actionId: string | null | undefined): TraceEventRecord[][];
 export type ReproMiddlewareConfig = IngestClientConfig & {
+    /** Propagated recording mode. A tagged staging request never inherits live limits. */
+    captureMode?: 'live' | 'staging';
     /** API base used for backend-owned live session documents. Defaults to REPRO_API_BASE_URL/REPRO_API_BASE/privacy.apiBase. */
     apiBase?: string;
     /** Configure header capture/masking. Defaults to capturing with sensitive headers masked. */
@@ -369,6 +377,15 @@ export type ReproLiveActorDecision = ReproLiveActorArgs & {
     actorLabels?: Record<string, string>;
 };
 export type ReproLiveModeConfig = {
+    /** Stable chain sampling. Runtime updates apply to new chains; targets are evaluated on each claim. */
+    liveCapture?: {
+        sampleRate?: number;
+        targets?: {
+            actorIds?: string[];
+            labels?: Record<string, string>;
+            expiresAt: number;
+        }[];
+    };
     enabled?: boolean;
     backendOnly?: boolean;
     /**

package/dist/index.js

@@ -10,6 +10,7 @@ const url_1 = require("url");
 const client_1 = require("./ingest/client");
 const privacy_1 = require("./privacy");
 const semantic_serialization_1 = require("./semantic-serialization");
+const live_capture_limits_1 = require("./live-capture-limits");
 /**
  * ============================= IMPORTANT =============================
  * We snapshot Mongoose core methods BEFORE tracer init, then re-apply them
@@ -828,6 +829,7 @@ function createRequestCaptureScope(requestRid, transport, cfg) {
     return {
         requestRid,
         transport,
+        liveCapture: cfg?.captureMode === 'live' || (!!cfg && cfg.captureMode !== 'staging' && !!normalizeLiveModeConfig(cfg)),
         // Every scope represents one captured transport request. This is an
         // observed expectation, not a count of successful enqueue operations.
         backendRequestCount: 1,
@@ -839,6 +841,7 @@ function createRequestCaptureScope(requestRid, transport, cfg) {
         privacyPolicyFingerprint: privacy?.fingerprint,
         privacyStatementCount: privacy?.statements.length ?? 0,
         emittedValueDefinitionIds: new Set(),
+        traceObservationSnapshots: new Map(),
     };
 }
 function recordRequestCaptureFailure(scope, stage, target, reason) {
@@ -2053,6 +2056,7 @@ async function resolveBackendLiveContext(cfg, req, requestStart) {
     }
     const { actorId, actorType, actorLabels } = identity;
     const claim = await postLiveApiJson(cfg, liveMode, '/v1/live-sessions/claim', {
+        liveCapture: liveMode.liveCapture,
         clientTime: requestStart,
         captureMode: 'backend-only',
         actorId,
@@ -2155,6 +2159,7 @@ function stripReproQueryFromUrl(rawUrl) {
         parsed.searchParams.delete(REPRO_QUERY_SESSION_PARAM);
         parsed.searchParams.delete(REPRO_QUERY_ACTION_PARAM);
         parsed.searchParams.delete(REPRO_QUERY_START_PARAM);
+        parsed.searchParams.delete('__repro_mode');
         return `${parsed.pathname}${parsed.search}${parsed.hash}`;
     }
     catch {
@@ -2168,6 +2173,7 @@ function stripReproQueryParams(req) {
             delete query[REPRO_QUERY_SESSION_PARAM];
             delete query[REPRO_QUERY_ACTION_PARAM];
             delete query[REPRO_QUERY_START_PARAM];
+            delete query.__repro_mode;
         }
     }
     catch { }
@@ -2810,6 +2816,66 @@ function normalizeRawTraceArgs(values) {
 function hasMeaningfulRawTraceError(error) {
     return error !== undefined && error !== null;
 }
+const TRACE_OBSERVATION_SNAPSHOT = Symbol('repro.traceObservationSnapshot');
+// Trace events can remain queued after user code mutates the observed objects.
+// Intern immutable semantic snapshots per request so temporal evidence stays
+// correct without retaining another full copy for repeated unchanged values.
+function internTraceObservationSnapshot(snapshot, captureScope) {
+    if (!captureScope || snapshot === null || typeof snapshot !== 'object') {
+        return snapshot;
+    }
+    const serialized = stableSerializeTraceValue(snapshot);
+    if (serialized === null)
+        return snapshot;
+    const digest = (0, crypto_1.createHash)('sha256')
+        .update('repro-trace-observation-v1\0')
+        .update(serialized)
+        .digest('hex');
+    const existing = captureScope.traceObservationSnapshots.get(digest);
+    if (existing !== undefined)
+        return existing;
+    captureScope.traceObservationSnapshots.set(digest, snapshot);
+    return snapshot;
+}
+function snapshotTraceValueAtObservation(value, captureScope, valuePath = '$', target = 'trace.value') {
+    try {
+        if (captureScope?.liveCapture) {
+            value = target === 'trace.args' && Array.isArray(value)
+                ? (0, live_capture_limits_1.limitLiveArguments)(value)
+                : (0, live_capture_limits_1.limitLiveCapture)(value, valuePath).value;
+        }
+        const snapshot = sanitizeTraceValue(value, 0, new WeakMap(), { preserveLongStrings: true, disableTruncation: true }, valuePath);
+        return internTraceObservationSnapshot(snapshot, captureScope);
+    }
+    catch {
+        recordRequestCaptureFailure(captureScope, 'trace.snapshot', target, 'snapshot_failed');
+        return makeOmittedValue('capture-snapshot-failed');
+    }
+}
+function snapshotTraceArgsAtObservation(values, captureScope) {
+    const snapshot = snapshotTraceValueAtObservation(normalizeRawTraceArgs(values), captureScope, '$', 'trace.args');
+    return Array.isArray(snapshot) ? snapshot : [snapshot];
+}
+function snapshotRawTraceEventAtObservation(raw, captureScope) {
+    if (!raw || typeof raw !== 'object' || raw[TRACE_OBSERVATION_SNAPSHOT] === true) {
+        return raw;
+    }
+    const snapshot = { ...raw };
+    if (raw.args !== undefined) {
+        snapshot.args = snapshotTraceArgsAtObservation(raw.args, captureScope);
+    }
+    if (raw.returnValue !== undefined) {
+        snapshot.returnValue = snapshotTraceValueAtObservation(raw.returnValue, captureScope, '$', 'trace.returnValue');
+    }
+    if (hasMeaningfulRawTraceError(raw.error)) {
+        snapshot.error = snapshotTraceValueAtObservation(raw.error, captureScope, '$', 'trace.error');
+    }
+    Object.defineProperty(snapshot, TRACE_OBSERVATION_SNAPSHOT, {
+        value: true,
+        enumerable: false,
+    });
+    return snapshot;
+}
 function attachTraceValueEntry(event, entry) {
     const current = event[TRACE_FULL_VALUE_ENTRY_SYMBOL];
     if (Array.isArray(current)) {
@@ -2962,6 +3028,7 @@ async function materializePendingTraceEventsAsync(events, params) {
                 appSecret: params.cfg.appSecret,
                 appName: params.cfg.appName,
                 privacy: params.cfg.privacy,
+                captureMode: params.captureScope?.liveCapture ? 'live' : params.cfg.captureMode,
             },
             maskReq: params.maskReq,
             masking: params.masking,
@@ -3383,7 +3450,20 @@ async function initializeRuntimePrivacyPolicyAtStartup(cfg) {
     }
     throw new Error(`Runtime privacy policy failed to load during startup from ${apiBase} for env ${state.environment} (${lastFailure}).`);
 }
+function isLiveCapture(cfg, scope) {
+    if (scope)
+        return scope.liveCapture === true;
+    return cfg.captureMode === 'live' || (cfg.captureMode !== 'staging' && getCtx().captureScope?.liveCapture === true);
+}
+function constrainLiveCapture(value, cfg, target, scope) {
+    if (!isLiveCapture(cfg, scope))
+        return value;
+    return target === 'trace.args' && Array.isArray(value)
+        ? (0, live_capture_limits_1.limitLiveArguments)(value)
+        : (0, live_capture_limits_1.limitLiveCapture)(value).value;
+}
 function applyPrivacyThenMask(target, value, cfg, req, trace, masking, privacy, db) {
+    value = constrainLiveCapture(value, cfg, target);
     if (shouldCapturePrivacyRaw(cfg)) {
         return value;
     }
@@ -3404,6 +3484,7 @@ function applyPrivacyThenMask(target, value, cfg, req, trace, masking, privacy,
     return applyMasking(target, transformed, req, trace, masking);
 }
 async function applyPrivacyThenMaskAsync(target, value, cfg, req, trace, masking, privacy, db) {
+    value = constrainLiveCapture(value, cfg, target);
     if (shouldCapturePrivacyRaw(cfg)) {
         return value;
     }
@@ -3450,6 +3531,7 @@ function limitRawInlinePrivacyValue(target, value) {
     return limited.skipped ? limited : null;
 }
 function materializeInlinePrivacyValue(target, value, cfg, req, trace, masking, privacy, db, captureScope) {
+    value = constrainLiveCapture(value, cfg, target, captureScope);
     if (value === undefined) {
         return { value };
     }
@@ -3473,6 +3555,7 @@ function materializeInlinePrivacyValue(target, value, cfg, req, trace, masking,
     }
 }
 async function materializeInlinePrivacyValueAsync(target, value, cfg, req, trace, masking, privacy, db, captureScope) {
+    value = constrainLiveCapture(value, cfg, target, captureScope);
     if (value === undefined) {
         return { value };
     }
@@ -4449,6 +4532,8 @@ function boundTraceEventsForTransport(events) {
 function createCapturedValueEntry(params) {
     if (!__FULL_VALUE_CAPTURE_ENABLED)
         return undefined;
+    const limitedRaw = constrainLiveCapture(params.rawValue, params.capture.runtimeConfig, params.target);
+    const omissions = isLiveCapture(params.capture.runtimeConfig) ? (0, live_capture_limits_1.collectCaptureOmissions)(limitedRaw) : [];
     const preferredLimits = {
         maxDepth: TRACE_FULL_VALUE_MAX_DEPTH,
         maxKeys: TRACE_FULL_VALUE_MAX_KEYS,
@@ -4458,7 +4543,7 @@ function createCapturedValueEntry(params) {
     const buildMaskedCandidate = (limits) => {
         const projected = params.target === 'request.headers'
             ? sanitizeHeaders(params.rawValue, params.capture.captureHeaders)
-            : cloneFullValueCandidate(params.rawValue, params.capture, limits);
+            : cloneFullValueCandidate(limitedRaw, params.capture, limits);
         if (projected === undefined)
             return undefined;
         return applyPrivacyThenMask(params.target, projected, params.capture.runtimeConfig, params.capture.maskReq, params.capture.trace, params.capture.masking, params.capture.privacy, params.capture.db);
@@ -4469,7 +4554,7 @@ function createCapturedValueEntry(params) {
         return { captureRef: { status: 'skipped-non-meaningful' } };
     }
     const candidateSerialized = stableSerializeTraceValue(candidate);
-    if (!candidateSerialized || candidateSerialized === previewSerialized) {
+    if (!candidateSerialized || (candidateSerialized === previewSerialized && !omissions.length)) {
         return undefined;
     }
     const valueId = contentAddressedValueId(params.target, candidateSerialized, params.capture);
@@ -4489,6 +4574,7 @@ function createCapturedValueEntry(params) {
             status: 'stored',
             valueId,
             projectedKind: entry.projectedKind,
+            ...(omissions.length ? { complete: false, omissions } : {}),
         },
         entry,
     };
@@ -4496,6 +4582,8 @@ function createCapturedValueEntry(params) {
 async function createCapturedValueEntryAsync(params) {
     if (!__FULL_VALUE_CAPTURE_ENABLED)
         return undefined;
+    const limitedRaw = constrainLiveCapture(params.rawValue, params.capture.runtimeConfig, params.target);
+    const omissions = isLiveCapture(params.capture.runtimeConfig) ? (0, live_capture_limits_1.collectCaptureOmissions)(limitedRaw) : [];
     const preferredLimits = {
         maxDepth: TRACE_FULL_VALUE_MAX_DEPTH,
         maxKeys: TRACE_FULL_VALUE_MAX_KEYS,
@@ -4505,7 +4593,7 @@ async function createCapturedValueEntryAsync(params) {
     const buildMaskedCandidate = async (limits) => {
         const projected = params.target === 'request.headers'
             ? sanitizeHeaders(params.rawValue, params.capture.captureHeaders)
-            : await cloneFullValueCandidateAsync(params.rawValue, params.capture, limits);
+            : await cloneFullValueCandidateAsync(limitedRaw, params.capture, limits);
         if (projected === undefined)
             return undefined;
         return applyPrivacyThenMaskAsync(params.target, projected, params.capture.runtimeConfig, params.capture.maskReq, params.capture.trace, params.capture.masking, params.capture.privacy, params.capture.db);
@@ -4516,7 +4604,7 @@ async function createCapturedValueEntryAsync(params) {
         return { captureRef: { status: 'skipped-non-meaningful' } };
     }
     const candidateSerialized = stableSerializeTraceValue(candidate);
-    if (!candidateSerialized || candidateSerialized === previewSerialized) {
+    if (!candidateSerialized || (candidateSerialized === previewSerialized && !omissions.length)) {
         return undefined;
     }
     const valueId = contentAddressedValueId(params.target, candidateSerialized, params.capture);
@@ -4536,6 +4624,7 @@ async function createCapturedValueEntryAsync(params) {
             status: 'stored',
             valueId,
             projectedKind: entry.projectedKind,
+            ...(omissions.length ? { complete: false, omissions } : {}),
         },
         entry,
     };
@@ -4738,6 +4827,7 @@ function reproMiddleware(cfg) {
         const querySid = readRequestQueryParam(req, REPRO_QUERY_SESSION_PARAM);
         const queryAid = readRequestQueryParam(req, REPRO_QUERY_ACTION_PARAM);
         const queryTs = readRequestQueryNumber(req, REPRO_QUERY_START_PARAM);
+        const queryCaptureMode = readRequestQueryParam(req, '__repro_mode');
         if (querySid || queryAid || queryTs !== null) {
             stripReproQueryParams(req);
         }
@@ -4774,21 +4864,25 @@ function reproMiddleware(cfg) {
             res.on('close', endTrackedClientRequest);
             return next(); // only capture tagged requests
         }
-        const captureCfg = backendLiveChild
-            ? {
+        let captureCfg = cfg;
+        if (backendLiveChild) {
+            captureCfg = {
                 ...cfg,
                 actorId: backendLiveChild.actorId,
                 actorType: backendLiveChild.actorType,
                 actorLabels: backendLiveChild.actorLabels,
-            }
-            : taggedActorIdentity
-                ? {
-                    ...cfg,
-                    actorId: taggedActorIdentity.actorId,
-                    actorType: taggedActorIdentity.actorType,
-                    actorLabels: taggedActorIdentity.actorLabels,
-                }
-                : cfg;
+            };
+            shareRuntimePrivacyState(cfg, captureCfg);
+        }
+        else if (taggedActorIdentity) {
+            captureCfg = {
+                ...cfg,
+                actorId: taggedActorIdentity.actorId,
+                actorType: taggedActorIdentity.actorType,
+                actorLabels: taggedActorIdentity.actorLabels,
+            };
+            shareRuntimePrivacyState(cfg, captureCfg);
+        }
         if (taggedActorIdentity) {
             post(captureCfg, sid, {
                 entries: [{
@@ -4803,6 +4897,11 @@ function reproMiddleware(cfg) {
                     }],
             }, { priority: 'high' });
         }
+        const captureMode = backendLiveContext || req.headers['x-repro-capture-mode'] === 'live' || queryCaptureMode === 'live'
+            ? 'live' : 'staging';
+        const modeConfig = { ...captureCfg, captureMode };
+        shareRuntimePrivacyState(captureCfg, modeConfig);
+        captureCfg = modeConfig;
         const resolvePrivacy = () => getRuntimePrivacyState(captureCfg).policy ?? null;
         const clockSkewMs = headerTs !== null ? headerTs - requestStartRaw : 0;
         const rid = nextRequestId(requestEpochMs);
@@ -5262,17 +5361,17 @@ function reproMiddleware(cfg) {
                                 evt.__reproPending = {
                                     ...(ev.args !== undefined
                                         ? {
-                                            argsRaw: normalizeRawTraceArgs(ev.args),
+                                            argsRaw: snapshotTraceArgsAtObservation(ev.args, captureScope),
                                         }
                                         : {}),
                                     ...(ev.returnValue !== undefined
                                         ? {
-                                            returnValueRaw: ev.returnValue,
+                                            returnValueRaw: snapshotTraceValueAtObservation(ev.returnValue, captureScope, '$', 'trace.returnValue'),
                                         }
                                         : {}),
                                     ...(hasErrorPayload
                                         ? {
-                                            errorRaw: ev.error,
+                                            errorRaw: snapshotTraceValueAtObservation(ev.error, captureScope, '$', 'trace.error'),
                                         }
                                         : {}),
                                 };
@@ -6227,6 +6326,8 @@ function patchNodeFetchForPropagation() {
         if (runtime.aid && !hasHttpHeader(headers, KAFKA_HEADER_ACTION_ID)) {
             setHttpHeader(headers, KAFKA_HEADER_ACTION_ID, runtime.aid);
         }
+        if (runtime.sid)
+            setHttpHeader(headers, 'x-repro-capture-mode', getCtx().captureScope?.liveCapture ? 'live' : 'staging');
         if (runtime.traceId && !hasHttpHeader(headers, KAFKA_HEADER_TRACE_ID)) {
             setHttpHeader(headers, KAFKA_HEADER_TRACE_ID, runtime.traceId);
         }
@@ -6277,6 +6378,8 @@ function patchNodeHttpModuleRequest(mod) {
             maybeSet(REQUEST_START_HEADER, String(alignedNow()));
             maybeSet(KAFKA_HEADER_SESSION_ID, runtime.sid);
             maybeSet(KAFKA_HEADER_ACTION_ID, runtime.aid);
+            if (runtime.sid)
+                maybeSet('x-repro-capture-mode', getCtx().captureScope?.liveCapture ? 'live' : 'staging');
             maybeSet(KAFKA_HEADER_TRACE_ID, runtime.traceId);
             maybeSet(KAFKA_HEADER_PARENT_SPAN_ID, runtime.parentSpanId);
             maybeSet(KAFKA_HEADER_REQUEST_ID, runtime.requestRid);
@@ -6453,6 +6556,11 @@ function cloneKafkaTelemetryValue(value) {
     }
 }
 async function materializeKafkaRequestBody(cfg, maskReq, body, captureScope) {
+    // Broker bodies have no separate full-value reference. Returning the trace
+    // inline preview here would permanently replace message arrays with 20 items.
+    if (shouldCapturePrivacyRaw(cfg)) {
+        return { value: constrainLiveCapture(sanitizeInlinePrivacyValue(body), cfg, 'request.body', captureScope) };
+    }
     return materializeInlinePrivacyValueAsync('request.body', sanitizeInlinePrivacyValue(body), cfg, maskReq, null, normalizeMaskingConfig(cfg.masking), getRuntimePrivacyState(cfg).policy ?? null, undefined, captureScope);
 }
 function summarizeKafkaError(error) {
@@ -6497,7 +6605,8 @@ function resolveKafkaContext(cfg, headers) {
         readKafkaHeader(headers, KAFKA_HEADER_PARENT_SPAN_ID) ??
         null;
     const requestRid = readKafkaHeader(headers, KAFKA_HEADER_REQUEST_ID);
-    return { sid, aid, traceId, parentSpanId, requestRid };
+    return { sid, aid, traceId, parentSpanId, requestRid,
+        captureMode: readKafkaHeader(headers, 'x-repro-capture-mode') === 'live' || ctx.captureScope?.liveCapture ? 'live' : 'staging' };
 }
 function withOptionalTraceContext(traceId, fn) {
     const tracerWithTrace = __TRACER__?.withTrace;
@@ -6621,6 +6730,7 @@ function recordKafkaTraceEvent(raw, sink, cfg, maskReq) {
 function buildPendingKafkaTraceEvent(raw) {
     if (!raw || (raw.type !== 'enter' && raw.type !== 'exit'))
         return null;
+    raw = snapshotRawTraceEventAtObservation(raw, getCtx().captureScope);
     const sourceFileForLibrary = typeof raw.sourceFile === 'string' && raw.sourceFile
         ? String(raw.sourceFile)
         : null;
@@ -6796,6 +6906,7 @@ function patchKafkaProducerInstance(producer, cfg) {
                         [KAFKA_HEADER_REQUEST_ID]: publishRid,
                         [KAFKA_HEADER_SESSION_ID]: sid,
                         [KAFKA_HEADER_ACTION_ID]: aid,
+                        'x-repro-capture-mode': ctx.captureScope?.liveCapture ? 'live' : 'staging',
                     }),
                 };
             });
@@ -6918,6 +7029,7 @@ function patchKafkaProducerInstance(producer, cfg) {
                                 [KAFKA_HEADER_REQUEST_ID]: publishRid,
                                 [KAFKA_HEADER_SESSION_ID]: sid,
                                 [KAFKA_HEADER_ACTION_ID]: aid,
+                                'x-repro-capture-mode': ctx.captureScope?.liveCapture ? 'live' : 'staging',
                             }),
                         };
                     }),
@@ -7030,6 +7142,7 @@ function wrapKafkaEachMessageHandler(eachMessage, cfg, consumer) {
         const consumeRid = nextRequestId(`${topic}-${message?.offset ?? alignedNow()}`);
         const traceId = consumeRid;
         const captureScope = createRequestCaptureScope(consumeRid, 'kafka', cfg);
+        captureScope.liveCapture = runtime.captureMode === 'live';
         emitRequestCaptureStart(cfg, sid, aid, captureScope);
         const rawTraceEvents = [];
         const maskReq = {
@@ -7054,7 +7167,7 @@ function wrapKafkaEachMessageHandler(eachMessage, cfg, consumer) {
                     unsubscribe = __TRACER__.tracer.on((event) => {
                         if (!event || event.traceId !== traceId)
                             return;
-                        rawTraceEvents.push(event);
+                        rawTraceEvents.push(snapshotRawTraceEventAtObservation(event, captureScope));
                     });
                 }
                 catch { }
@@ -7144,6 +7257,7 @@ function wrapKafkaEachBatchHandler(eachBatch, cfg, consumer) {
         const consumeRid = nextRequestId(`${topic}-batch-${alignedNow()}`);
         const traceId = consumeRid;
         const captureScope = createRequestCaptureScope(consumeRid, 'kafka', cfg);
+        captureScope.liveCapture = runtime.captureMode === 'live';
         emitRequestCaptureStart(cfg, sid, aid, captureScope);
         const rawTraceEvents = [];
         const maskReq = {
@@ -7168,7 +7282,7 @@ function wrapKafkaEachBatchHandler(eachBatch, cfg, consumer) {
                     unsubscribe = __TRACER__.tracer.on((event) => {
                         if (!event || event.traceId !== traceId)
                             return;
-                        rawTraceEvents.push(event);
+                        rawTraceEvents.push(snapshotRawTraceEventAtObservation(event, captureScope));
                     });
                 }
                 catch { }
@@ -7581,7 +7695,8 @@ function resolveAmqpContext(cfg, headers) {
         readAmqpHeader(headers, KAFKA_HEADER_PARENT_SPAN_ID) ??
         null;
     const requestRid = readAmqpHeader(headers, KAFKA_HEADER_REQUEST_ID);
-    return { sid, aid, traceId, parentSpanId, requestRid };
+    return { sid, aid, traceId, parentSpanId, requestRid,
+        captureMode: readAmqpHeader(headers, 'x-repro-capture-mode') === 'live' || ctx.captureScope?.liveCapture ? 'live' : 'staging' };
 }
 function withOptionalTraceContextSync(traceId, fn) {
     const tracerWithTrace = __TRACER__?.withTrace;
@@ -7756,6 +7871,7 @@ function patchAmqplibPublishMethod(channel, cfg, methodName) {
             [KAFKA_HEADER_REQUEST_ID]: publishRid,
             [KAFKA_HEADER_SESSION_ID]: sid,
             [KAFKA_HEADER_ACTION_ID]: aid,
+            'x-repro-capture-mode': ctx.captureScope?.liveCapture ? 'live' : 'staging',
         };
         const shouldPropagate = hasAmqpPropagationValues(propagationValues);
         const callbackIndex = args.length > 0 && typeof args[args.length - 1] === 'function'
@@ -7861,6 +7977,7 @@ function wrapAmqplibConsumeHandler(onMessage, cfg, queue) {
         const consumeRid = nextRequestId(`${queueName}-${deliveryTag}`);
         const traceId = consumeRid;
         const captureScope = createRequestCaptureScope(consumeRid, 'amqp', cfg);
+        captureScope.liveCapture = runtime.captureMode === 'live';
         emitRequestCaptureStart(cfg, sid, aid, captureScope);
         const rawTraceEvents = [];
         const maskReq = {
@@ -7886,7 +8003,7 @@ function wrapAmqplibConsumeHandler(onMessage, cfg, queue) {
                 unsubscribe = __TRACER__.tracer.on((event) => {
                     if (!event || event.traceId !== traceId)
                         return;
-                    rawTraceEvents.push(event);
+                    rawTraceEvents.push(snapshotRawTraceEventAtObservation(event, captureScope));
                 });
             }
             catch { }

package/dist/ingest/client.js

@@ -47,6 +47,8 @@ let backoffMs = 0;
 let criticalBackoffMs = 0;
 let shouldDeferDrain = null;
 let deferDrainMs = DEFAULT_DEFER_DRAIN_MS;
+const throttledUntil = new Map();
+const throttleDelay = (config) => Math.max(0, (throttledUntil.get(resolveIngestUrl(config)) ?? 0) - Date.now());
 const configureIngestQueueDrain = (options) => {
     shouldDeferDrain = options.shouldDefer ?? null;
     if (Number.isFinite(options.deferMs) && Number(options.deferMs) >= 0) {
@@ -166,6 +168,9 @@ const postIngestEntries = async (config, sessionId, entries) => {
 };
 exports.postIngestEntries = postIngestEntries;
 const sendIngestEntries = async (config, sessionId, entries) => {
+    if (throttleDelay(config) > 0)
+        return 'throttled';
+    throttledUntil.delete(resolveIngestUrl(config));
     if (!sessionId || !Array.isArray(entries) || entries.length === 0) {
         return true;
     }
@@ -197,6 +202,18 @@ const sendIngestEntries = async (config, sessionId, entries) => {
             body: JSON.stringify({ events }),
             ...(controller ? { signal: controller.signal } : {}),
         });
+        if (response.status === 429) {
+            const retryAfter = response.headers?.get?.('retry-after');
+            const seconds = retryAfter ? Number(retryAfter) : NaN;
+            const date = retryAfter ? Date.parse(retryAfter) : NaN;
+            const delay = Number.isFinite(seconds) ? seconds * 1000 : Number.isFinite(date) ? date - Date.now() : 1000;
+            throttledUntil.set(resolveIngestUrl(config), Date.now() + Math.max(1000, Math.min(86400000, delay)));
+            return 'throttled';
+        }
+        if (response.status === 402 || response.status === 410) {
+            console.warn(`[repro] Upload refused for ${sessionId}: ${response.status === 402 ? 'capture quota exhausted' : 'capture deleted, expired or failed'}. This batch will not be retried.`);
+            return 'denied';
+        }
         return response.ok;
     }
     catch {
@@ -257,7 +274,11 @@ const drainCriticalIngestQueue = async () => {
                 return;
             }
             const ok = await sendIngestEntries(selected.batch.config, selected.batch.sessionId, selected.batch.entries);
-            if (ok) {
+            if (ok === 'throttled') {
+                scheduleCriticalDrain(throttleDelay(selected.batch.config));
+                return;
+            }
+            if (ok === true || ok === 'denied') {
                 criticalIngestQueue.splice(0, selected.queueItems);
                 criticalBackoffMs = 0;
                 continue;
@@ -298,7 +319,11 @@ const drainIngestQueue = async () => {
             }
             const batch = selected.batch;
             const ok = await sendIngestEntries(batch.config, batch.sessionId, batch.entries);
-            if (ok) {
+            if (ok === 'throttled') {
+                scheduleDrain(throttleDelay(batch.config));
+                return;
+            }
+            if (ok === true || ok === 'denied') {
                 ingestQueue.splice(0, selected.queueItems);
                 backoffMs = 0;
                 continue;

package/dist/live-capture-limits.d.ts

@@ -0,0 +1,19 @@
+export type CaptureOmission = {
+    reason: 'max-depth' | 'max-keys' | 'max-entries' | 'accessor' | 'uninspectable';
+    path: string;
+    limit?: number;
+    originalCount?: number;
+    capturedCount: number;
+};
+export declare const LIVE_CAPTURE_LIMITS: Readonly<{
+    maxDepth: 10;
+    maxKeys: 100;
+    maxEntries: 100;
+}>;
+/** Snapshot only data descriptors: capture must never execute application getters. */
+export declare function limitLiveCapture(value: unknown, rootPath?: string): {
+    value: any;
+    omissions: CaptureOmission[];
+};
+export declare function collectCaptureOmissions(value: any): CaptureOmission[];
+export declare function limitLiveArguments(args: any[]): any[];