@reproapp/node-sdk 0.0.1 → 0.0.2

package/src/index.ts

@@ -0,0 +1,2851 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { Schema, Model, Query } from 'mongoose';
+import * as mongoose from 'mongoose';
+import { AsyncLocalStorage } from 'async_hooks';
+
+/**
+ * ============================= IMPORTANT =============================
+ * We snapshot Mongoose core methods BEFORE tracer init, then re-apply them
+ * AFTER tracer init. This guarantees Model.find() still returns a Query and
+ * chainability (e.g., .sort().lean()) is preserved. No behavior changes.
+ * =====================================================================
+ */
+const __ORIG = (() => {
+    const M: any = (mongoose as any).Model;
+    const Qp: any = (mongoose as any).Query?.prototype;
+    const Ap: any = (mongoose as any).Aggregate?.prototype;
+    return {
+        Model: {
+            find: M?.find,
+            findOne: M?.findOne,
+            findById: M?.findById,
+            create: M?.create,
+            insertMany: M?.insertMany,
+            updateOne: M?.updateOne,
+            updateMany: M?.updateMany,
+            replaceOne: M?.replaceOne,
+            deleteOne: M?.deleteOne,
+            deleteMany: M?.deleteMany,
+            countDocuments: M?.countDocuments,
+            estimatedDocumentCount: M?.estimatedDocumentCount,
+            distinct: M?.distinct,
+            findOneAndUpdate: M?.findOneAndUpdate,
+            findOneAndDelete: M?.findOneAndDelete,
+            findOneAndReplace: M?.findOneAndReplace,
+            findOneAndRemove: M?.findOneAndRemove,
+            bulkWrite: M?.bulkWrite,
+        },
+        Query: {
+            exec: Qp?.exec,
+            lean: Qp?.lean,
+            sort: Qp?.sort,
+            select: Qp?.select,
+            limit: Qp?.limit,
+            skip: Qp?.skip,
+            populate: Qp?.populate,
+            getFilter: Qp?.getFilter,
+            getUpdate: Qp?.getUpdate,
+            getOptions: Qp?.getOptions,
+            projection: Qp?.projection,
+        },
+        Aggregate: {
+            exec: Ap?.exec,
+        }
+    };
+})();
+
+function restoreMongooseIfNeeded() {
+    try {
+        const M: any = (mongoose as any).Model;
+        const Qp: any = (mongoose as any).Query?.prototype;
+        const Ap: any = (mongoose as any).Aggregate?.prototype;
+        const safeSet = (obj: any, key: string, val: any) => {
+            if (!obj || !val) return;
+            if (obj[key] !== val) { try { obj[key] = val; } catch {} }
+        };
+
+        // Restore Model methods (chainability depends on these returning Query)
+        Object.entries(__ORIG.Model).forEach(([k, v]) => safeSet(M, k, v));
+
+        // Restore Query prototype essentials (exec/lean/etc.)
+        Object.entries(__ORIG.Query).forEach(([k, v]) => safeSet(Qp, k, v));
+
+        // Restore Aggregate exec
+        Object.entries(__ORIG.Aggregate).forEach(([k, v]) => safeSet(Ap, k, v));
+    } catch {}
+}
+
+function flushQueryFinalizers(query: any, value: any, threw: boolean, error: any) {
+    try {
+        const callbacks = (query as any)?.__repro_query_finalizers;
+        if (!Array.isArray(callbacks) || callbacks.length === 0) return;
+        (query as any).__repro_query_finalizers = [];
+        for (const fn of callbacks) {
+            try { fn(value, threw, error); } catch {}
+        }
+    } catch {}
+}
+
+function patchMongooseExecCapture(targetMongoose: any = mongoose) {
+    // Patch Query.prototype.exec to capture resolved results for trace return values.
+    try {
+        const Qp: any = targetMongoose?.Query?.prototype;
+        if (Qp && !Qp.__repro_exec_patched) {
+            const origExec = Qp.exec;
+            if (typeof origExec === 'function') {
+                Qp.__repro_exec_patched = true;
+                Qp.exec = function reproPatchedExec(this: any, ...args: any[]) {
+                    try {
+                        (this as any).__repro_is_query = true;
+                        const ctx = __TRACER__?.getCurrentSpanContext?.();
+                        const traceId = ctx?.traceId ?? __TRACER__?.getCurrentTraceId?.() ?? null;
+                        if (ctx || traceId) {
+                            Object.defineProperty(this, '__repro_span_context', {
+                                value: {
+                                    traceId,
+                                    spanId: ctx?.spanId ?? null,
+                                    parentSpanId: ctx?.parentSpanId ?? null,
+                                    depth: ctx?.depth ?? null,
+                                },
+                                configurable: true,
+                                writable: true,
+                                enumerable: false,
+                            });
+                        }
+                    } catch {}
+                    const p = origExec.apply(this, args);
+                    try {
+                        if (p && typeof p.then === 'function') {
+                            this.__repro_result_promise = p;
+                            p.then(
+                                (res: any) => {
+                                    try { this.__repro_result = res; } catch {}
+                                    flushQueryFinalizers(this, res, false, null);
+                                    return res;
+                                },
+                                (err: any) => {
+                                    flushQueryFinalizers(this, undefined, true, err);
+                                    return err;
+                                }
+                            );
+                        }
+                    } catch {}
+                    return p;
+                };
+            }
+        }
+    } catch {}
+
+    // Patch Aggregate.prototype.exec as well so aggregation pipelines surface their results in traces.
+    try {
+        const Ap: any = targetMongoose?.Aggregate?.prototype;
+        if (Ap && !Ap.__repro_agg_exec_patched) {
+            const origAggExec = Ap.exec;
+            if (typeof origAggExec === 'function') {
+                Ap.__repro_agg_exec_patched = true;
+                Ap.exec = function reproPatchedAggExec(this: any, ...args: any[]) {
+                    try {
+                        (this as any).__repro_is_query = true;
+                        const ctx = __TRACER__?.getCurrentSpanContext?.();
+                        const traceId = ctx?.traceId ?? __TRACER__?.getCurrentTraceId?.() ?? null;
+                        if (ctx || traceId) {
+                            Object.defineProperty(this, '__repro_span_context', {
+                                value: {
+                                    traceId,
+                                    spanId: ctx?.spanId ?? null,
+                                    parentSpanId: ctx?.parentSpanId ?? null,
+                                    depth: ctx?.depth ?? null,
+                                },
+                                configurable: true,
+                                writable: true,
+                                enumerable: false,
+                            });
+                        }
+                    } catch {}
+                    const p = origAggExec.apply(this, args);
+                    try {
+                        if (p && typeof p.then === 'function') {
+                            this.__repro_result_promise = p;
+                            p.then(
+                                (res: any) => {
+                                    try { this.__repro_result = res; } catch {}
+                                    flushQueryFinalizers(this, res, false, null);
+                                    return res;
+                                },
+                                (err: any) => {
+                                    flushQueryFinalizers(this, undefined, true, err);
+                                    return err;
+                                }
+                            );
+                        }
+                    } catch {}
+                    return p;
+                };
+            }
+        }
+    } catch {}
+}
+
+function patchAllKnownMongooseInstances() {
+    // Patch the SDK's bundled mongoose first.
+    patchMongooseExecCapture(mongoose as any);
+
+    // Also patch any other mongoose copies the host app might have installed (e.g., different versions).
+    try {
+        const cache = (require as any)?.cache || {};
+        const seen = new Set<any>();
+        Object.keys(cache).forEach((key) => {
+            if (!/node_modules[\\/](mongoose)[\\/]/i.test(key)) return;
+            const mod = cache[key];
+            const exp = mod?.exports;
+            if (!exp || seen.has(exp)) return;
+            seen.add(exp);
+            patchMongooseExecCapture(exp);
+        });
+    } catch {}
+}
+
+// ====== tiny, safe tracer auto-init (no node_modules patches) ======
+type SpanContext = {
+    traceId: string | null;
+    spanId: string | number | null;
+    parentSpanId: string | number | null;
+    depth: number | null;
+};
+
+type TracerApi = {
+    init?: (opts: any) => void;
+    tracer?: { on: (fn: (ev: any) => void) => () => void };
+    getCurrentTraceId?: () => string | null;
+    getCurrentSpanContext?: () => SpanContext | null;
+    patchHttp?: () => void; // optional in your tracer
+    setFunctionLogsEnabled?: (enabled: boolean) => void;
+};
+
+const REQUEST_START_HEADER = 'x-bug-request-start';
+
+function escapeRx(s: string) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+let __TRACER__: TracerApi | null = null;
+let __TRACER_READY = false;
+
+type TraceEventPhase = 'enter' | 'exit';
+export type TraceRulePattern = string | number | RegExp | Array<string | number | RegExp>;
+
+export type TraceEventForFilter = {
+    type: TraceEventPhase; // legacy alias for eventType
+    eventType: TraceEventPhase;
+    functionType?: string | null;
+    fn?: string;
+    wrapperClass?: string | null;
+    file?: string | null;
+    line?: number | null;
+    depth?: number;
+    library?: string | null;
+};
+
+type TraceEventRecord = {
+    t: number;
+    type: 'enter' | 'exit';
+    functionType?: string | null;
+    fn?: string;
+    file?: string;
+    line?: number | null;
+    depth?: number;
+    spanId?: string | number | null;
+    parentSpanId?: string | number | null;
+    args?: any;
+    returnValue?: any;
+    threw?: boolean;
+    error?: any;
+    unawaited?: boolean;
+};
+
+type EndpointTraceInfo = {
+    fn: string | null;
+    file: string | null;
+    line: number | null;
+    functionType: string | null;
+};
+
+export type HeaderRule = string | RegExp;
+export type HeaderCaptureOptions = {
+    /** When true, sensitive headers such as Authorization are kept unmasked; default masks them. */
+    allowSensitiveHeaders?: boolean;
+    /**
+     * Header names (string or RegExp) to mask.
+     * `dropHeaders` is kept for backward-compatibility and treated as an alias for `maskHeaders`.
+     */
+    maskHeaders?: HeaderRule | HeaderRule[];
+    /** @deprecated Alias for {@link maskHeaders}. */
+    dropHeaders?: HeaderRule | HeaderRule[];
+    /**
+     * Header names (string or RegExp) to keep unmasked, overriding defaults and `maskHeaders`.
+     * `keepHeaders` is kept for backward-compatibility and treated as an alias for `unmaskHeaders`.
+     */
+    unmaskHeaders?: HeaderRule | HeaderRule[];
+    /** @deprecated Alias for {@link unmaskHeaders}. */
+    keepHeaders?: HeaderRule | HeaderRule[];
+};
+
+type NormalizedHeaderCapture = {
+    enabled: boolean;
+    allowSensitive: boolean;
+    mask: HeaderRule[];
+    unmask: HeaderRule[];
+};
+
+/** Lightweight helper to disable every trace emitted from specific files. */
+export interface DisableTraceByFilename {
+    file: TraceRulePattern;
+}
+
+type DisableTraceFileConfig = TraceRulePattern | DisableTraceByFilename | null | undefined;
+
+/**
+ * Declarative rule that disables trace events matching the provided patterns.
+ *
+ * Each property accepts a string (substring match), a RegExp, or an array of
+ * either. When an array is provided, a single match of any entry is enough to
+ * drop the event. Provide no value to leave that dimension unrestricted.
+ */
+export type DisableFunctionTraceRule = {
+    /** Shortcut for {@link functionName}. */
+    fn?: TraceRulePattern;
+    /** Function name (e.g. `"findOne"`, `/^UserService\./`). */
+    functionName?: TraceRulePattern;
+    /** Shortcut for {@link wrapperClass}. */
+    wrapper?: TraceRulePattern;
+    /**
+     * Wrapper/owner name derived from {@link functionName} (e.g. `"UserService"` in `"UserService.create"`).
+     * Useful when multiple functions share the same method name.
+     */
+    wrapperClass?: TraceRulePattern;
+    /** Alias for {@link wrapperClass}. */
+    className?: TraceRulePattern;
+    /** Alias for {@link wrapperClass}. */
+    owner?: TraceRulePattern;
+    /** Source filename reported by the trace event. */
+    file?: TraceRulePattern;
+    /** Line number reported by the trace event. */
+    line?: TraceRulePattern;
+    /** Shortcut for {@link library}. */
+    lib?: TraceRulePattern;
+    /** Library/package name inferred from the file path (e.g. `"mongoose"`). */
+    library?: TraceRulePattern;
+    /** Shortcut for {@link functionType}. */
+    type?: TraceRulePattern;
+    /** Function classification such as `"constructor"`, `"method"`, or `"arrow"`. */
+    functionType?: TraceRulePattern;
+    /** Shortcut for {@link eventType}. */
+    event?: TraceRulePattern;
+    /** Trace phase to filter (`"enter"` or `"exit"`). */
+    eventType?: TraceRulePattern;
+};
+
+export type DisableFunctionTracePredicate = (event: TraceEventForFilter) => boolean;
+
+export type DisableFunctionTraceConfig =
+    | DisableFunctionTraceRule
+    | DisableFunctionTracePredicate;
+
+export type ReproMaskTarget =
+    | 'request.headers'
+    | 'request.body'
+    | 'request.params'
+    | 'request.query'
+    | 'response.body'
+    | 'trace.args'
+    | 'trace.returnValue'
+    | 'trace.error';
+
+export type ReproMaskWhen = DisableFunctionTraceRule & {
+    /** Match HTTP method (e.g. `"GET"`, `/^post$/i`). */
+    method?: TraceRulePattern;
+    /** Match request path without query string (e.g. `"/api/auth/login"`). */
+    path?: TraceRulePattern;
+    /** Match normalized endpoint key (e.g. `"POST /api/auth/login"`). */
+    key?: TraceRulePattern;
+};
+
+export type ReproMaskRule = {
+    when?: ReproMaskWhen;
+    target: ReproMaskTarget | ReproMaskTarget[];
+    /**
+     * Dot/bracket paths to mask (supports `*`, `[0]`, `[*]`).
+     * Examples: `"password"`, `"user.token"`, `"items[*].serial"`, `"0.password"` (for trace args arrays).
+     */
+    paths?: string | string[];
+    /** Key name patterns to mask anywhere in the payload. */
+    keys?: TraceRulePattern;
+    /** Override replacement value for this rule (defaults to config replacement / `"[REDACTED]"`). */
+    replacement?: any;
+};
+
+export type ReproMaskingConfig = {
+    /** Default replacement value (defaults to `"[REDACTED]"`). */
+    replacement?: any;
+    rules?: ReproMaskRule[] | null;
+};
+
+const DEFAULT_INTERCEPTOR_TRACE_RULES: DisableFunctionTraceConfig[] = [
+    { fn: /switchToHttp$/i },
+    { fn: /intercept$/i },
+];
+
+let interceptorTracingEnabled = false;
+let userDisabledFunctionTraceRules: DisableFunctionTraceConfig[] | null = null;
+
+function computeDisabledFunctionTraceRules(
+    rules?: DisableFunctionTraceConfig[] | null,
+): DisableFunctionTraceConfig[] {
+    const normalized = Array.isArray(rules)
+        ? rules.filter((rule): rule is DisableFunctionTraceConfig => !!rule)
+        : [];
+    if (interceptorTracingEnabled) {
+        return normalized;
+    }
+    return [...DEFAULT_INTERCEPTOR_TRACE_RULES, ...normalized];
+}
+
+function refreshDisabledFunctionTraceRules() {
+    disabledFunctionTraceRules = computeDisabledFunctionTraceRules(userDisabledFunctionTraceRules);
+}
+
+let disabledFunctionTraceRules: DisableFunctionTraceConfig[] = computeDisabledFunctionTraceRules();
+let disabledFunctionTypePatterns: Array<string | number | RegExp> = [];
+let disabledTraceFilePatterns: Array<string | number | RegExp> = [];
+let __TRACE_LOG_PREF: boolean | null = null;
+
+function setInterceptorTracingEnabled(enabled: boolean) {
+    const next = !!enabled;
+    if (interceptorTracingEnabled === next) return;
+    interceptorTracingEnabled = next;
+    refreshDisabledFunctionTraceRules();
+}
+
+function hasOwn(obj: unknown, key: string): boolean {
+    return !!obj && Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function normalizePatternArray<T>(pattern?: T | T[] | null): Exclude<T, null | undefined>[] {
+    if (pattern === undefined || pattern === null) return [];
+    const arr = Array.isArray(pattern) ? pattern : [pattern];
+    return arr.filter((entry): entry is Exclude<T, null | undefined> => entry !== undefined && entry !== null);
+}
+
+function matchesPattern(
+    value: string | null | undefined,
+    pattern?: TraceRulePattern,
+    defaultWhenEmpty: boolean = true,
+): boolean {
+    if (pattern === undefined || pattern === null) return defaultWhenEmpty;
+    const val = value == null ? '' : String(value);
+    const candidates = normalizePatternArray(pattern);
+    if (!candidates.length) return defaultWhenEmpty;
+    return candidates.some(entry => {
+        if (entry instanceof RegExp) {
+            try { return entry.test(val); } catch { return false; }
+        }
+        const needle = String(entry).toLowerCase();
+        if (!needle) return val === '';
+        return val.toLowerCase().includes(needle);
+    });
+}
+
+function inferLibraryNameFromFile(file?: string | null): string | null {
+    if (!file) return null;
+    const normalized = String(file).replace(/\\/g, '/');
+    const idx = normalized.lastIndexOf('/node_modules/');
+    if (idx === -1) return null;
+    const remainder = normalized.slice(idx + '/node_modules/'.length);
+    if (!remainder) return null;
+    const segments = remainder.split('/');
+    if (!segments.length) return null;
+    if (segments[0].startsWith('@') && segments.length >= 2) {
+        return `${segments[0]}/${segments[1]}`;
+    }
+    return segments[0] || null;
+}
+
+function inferWrapperClassFromFn(fn?: string | null): string | null {
+    if (!fn) return null;
+    const raw = String(fn);
+    if (!raw) return null;
+    const hashIdx = raw.indexOf('#');
+    if (hashIdx > 0) {
+        const left = raw.slice(0, hashIdx).trim();
+        return left || null;
+    }
+    const dotIdx = raw.lastIndexOf('.');
+    if (dotIdx > 0) {
+        const left = raw.slice(0, dotIdx).trim();
+        return left || null;
+    }
+    return null;
+}
+
+function matchesRule(rule: DisableFunctionTraceRule, event: TraceEventForFilter): boolean {
+    const namePattern = rule.fn ?? rule.functionName;
+    if (!matchesPattern(event.fn, namePattern)) return false;
+
+    const wrapperPattern = rule.wrapper ?? rule.wrapperClass ?? rule.className ?? rule.owner;
+    if (!matchesPattern(event.wrapperClass, wrapperPattern)) return false;
+
+    if (!matchesPattern(event.file, rule.file)) return false;
+    if (!matchesPattern(event.line == null ? null : String(event.line), rule.line)) return false;
+
+    const libPattern = rule.lib ?? rule.library;
+    if (!matchesPattern(event.library, libPattern)) return false;
+
+    const fnTypePattern = rule.functionType ?? rule.type;
+    if (!matchesPattern(event.functionType, fnTypePattern)) return false;
+
+    const eventTypePattern = rule.eventType ?? rule.event;
+    if (!matchesPattern(event.eventType, eventTypePattern)) return false;
+
+    return true;
+}
+
+function shouldDropTraceEvent(event: TraceEventForFilter): boolean {
+    if (disabledTraceFilePatterns.length) {
+        if (matchesPattern(event.file, disabledTraceFilePatterns, false)) {
+            return true;
+        }
+    }
+    if (disabledFunctionTypePatterns.length) {
+        if (matchesPattern(event.functionType, disabledFunctionTypePatterns, false)) {
+            return true;
+        }
+    }
+    if (!disabledFunctionTraceRules.length) return false;
+    for (const rule of disabledFunctionTraceRules) {
+        try {
+            if (typeof rule === 'function') {
+                if (rule(event)) return true;
+            } else if (matchesRule(rule, event)) {
+                return true;
+            }
+        } catch {
+            // ignore user filter errors
+        }
+    }
+    return false;
+}
+
+function shouldPropagateUserDisabledFunctionTrace(event: TraceEventForFilter): boolean {
+    const rules = userDisabledFunctionTraceRules;
+    if (!rules || rules.length === 0) return false;
+    for (const rule of rules) {
+        try {
+            if (typeof rule === 'function') {
+                const enterEvent = { ...event, type: 'enter', eventType: 'enter' } as TraceEventForFilter;
+                const exitEvent = { ...event, type: 'exit', eventType: 'exit' } as TraceEventForFilter;
+                if (rule(enterEvent) && rule(exitEvent)) return true;
+            } else if (matchesRule(rule, event)) {
+                const eventTypePattern = rule.eventType ?? rule.event;
+                if (!matchesPattern('enter', eventTypePattern)) continue;
+                if (!matchesPattern('exit', eventTypePattern)) continue;
+                return true;
+            }
+        } catch {
+            // ignore user filter errors
+        }
+    }
+    return false;
+}
+
+export function setDisabledFunctionTraces(rules?: DisableFunctionTraceConfig[] | null) {
+    if (!rules || !Array.isArray(rules)) {
+        userDisabledFunctionTraceRules = null;
+    } else {
+        userDisabledFunctionTraceRules = rules.filter((rule): rule is DisableFunctionTraceConfig => !!rule);
+    }
+    refreshDisabledFunctionTraceRules();
+}
+
+export function setDisabledFunctionTypes(patterns?: TraceRulePattern | null) {
+    disabledFunctionTypePatterns = normalizePatternArray(patterns);
+}
+
+function flattenTraceFilePatterns(config: DisableTraceFileConfig): Array<string | number | RegExp> {
+    if (config === null || config === undefined) return [];
+    if (Array.isArray(config)) {
+        return config.flatMap(entry => flattenTraceFilePatterns(entry));
+    }
+    if (config instanceof RegExp || typeof config === 'string' || typeof config === 'number') {
+        return [config];
+    }
+    if (typeof config === 'object' && 'file' in config) {
+        return normalizePatternArray(config.file);
+    }
+    return [];
+}
+
+export function setDisabledTraceFiles(config?: DisableTraceFileConfig | DisableTraceFileConfig[] | null) {
+    if (config === null || config === undefined) {
+        disabledTraceFilePatterns = [];
+        return;
+    }
+    const items = Array.isArray(config) ? config : [config];
+    disabledTraceFilePatterns = items.flatMap(entry => flattenTraceFilePatterns(entry)).filter(Boolean);
+}
+
+function applyTraceLogPreference(tracer?: TracerApi | null) {
+    if (__TRACE_LOG_PREF === null) return;
+    try { tracer?.setFunctionLogsEnabled?.(__TRACE_LOG_PREF); } catch {}
+}
+
+export function setReproTraceLogsEnabled(enabled: boolean) {
+    __TRACE_LOG_PREF = !!enabled;
+    applyTraceLogPreference(__TRACER__);
+}
+
+export function enableReproTraceLogs() { setReproTraceLogsEnabled(true); }
+
+export function disableReproTraceLogs() { setReproTraceLogsEnabled(false); }
+
+function summarizeEndpointFromEvents(events: TraceEventRecord[]) {
+    let endpointTrace: EndpointTraceInfo | null = null;
+    let preferredAppTrace: EndpointTraceInfo | null = null;
+    let firstAppTrace: EndpointTraceInfo | null = null;
+
+    for (const evt of events) {
+        if (evt.type !== 'enter') continue;
+        if (!isLikelyAppFile(evt.file)) continue;
+        const depthOk = evt.depth === undefined || evt.depth <= 6;
+        const trace = toEndpointTrace(evt);
+
+        if (!firstAppTrace && depthOk) {
+            firstAppTrace = trace;
+        }
+
+        if (isLikelyNestControllerFile(evt.file)) {
+            endpointTrace = trace;
+        } else if (depthOk && !preferredAppTrace && !isLikelyNestGuardFile(evt.file)) {
+            preferredAppTrace = trace;
+        }
+    }
+
+    return { endpointTrace, preferredAppTrace, firstAppTrace };
+}
+
+// (function ensureTracerAutoInit() {
+//     if (__TRACER_READY) return;
+//
+//     try {
+//         const tracerPkg: TracerApi = require('../tracer');
+//
+//         const cwd = process.cwd().replace(/\\/g, '/');
+//         const sdkRoot = __dirname.replace(/\\/g, '/');
+//
+//         // include ONLY app code (no node_modules) to avoid interfering with deps
+//         const include = [ new RegExp('^' + escapeRx(cwd) + '/(?!node_modules/)') ];
+//
+//         // exclude this SDK itself (and any babel internals if present)
+//         const exclude = [
+//             new RegExp('^' + escapeRx(sdkRoot) + '/'),
+//             /node_modules[\\/]@babel[\\/].*/,
+//         ];
+//
+//         tracerPkg.init?.({
+//             instrument: true,               // tracer can instrument app code
+//             include,
+//             exclude,                        // but never our SDK
+//             mode: process.env.TRACE_MODE || 'v8',
+//             samplingMs: 10,
+//         });
+//
+//         tracerPkg.patchHttp?.();
+//
+//         __TRACER__ = tracerPkg;
+//         __TRACER_READY = true;
+//     } catch {
+//         __TRACER__ = null; // optional tracer
+//     } finally {
+//         // Critical: make sure Mongoose core is pristine after tracer init.
+//         restoreMongooseIfNeeded();
+//         // And again on next tick (if tracer defers some wrapping)
+//         setImmediate(restoreMongooseIfNeeded);
+//     }
+// })();
+// ===================================================================
+
+// ===== Configurable tracer init (explicit, no auto-run) =====
+type TracerInitOpts = {
+    instrument?: boolean;
+    include?: RegExp[];
+    exclude?: RegExp[];
+    mode?: string;
+    samplingMs?: number;
+};
+
+export type ReproTracingInitOptions = TracerInitOpts & {
+    /**
+     * Optional list of rules or predicates that suppress unwanted function
+     * trace events. When omitted, every instrumented function will be
+     * recorded. Provide an empty array to reset filters after a previous call.
+     */
+    disableFunctionTraces?: DisableFunctionTraceConfig[] | null;
+    /**
+     * Convenience filter that disables every trace event emitted for the
+     * provided function types (e.g. `"constructor"`). Accepts a string,
+     * regular expression, or array matching the rule syntax above.
+     */
+    disableFunctionTypes?: TraceRulePattern | null;
+    /**
+     * Prevents traces emitted from specific files. Accepts glob-like substrings
+     * or regular expressions, or the {@link DisableTraceByFilename} helper.
+     */
+    disableTraceFiles?: DisableTraceFileConfig | DisableTraceFileConfig[] | null;
+    /**
+     * When `false` (default) Nest interceptors are stripped from traces.
+     * Set to `true` to include them if you need to debug interceptor logic.
+     */
+    traceInterceptors?: boolean;
+    /**
+     * Enables or silences console logs emitted by the tracer when functions
+     * are entered/exited. Equivalent to calling `setReproTraceLogsEnabled`.
+     */
+    logFunctionCalls?: boolean;
+};
+
+function defaultTracerInitOpts(): TracerInitOpts {
+    const cwd = process.cwd().replace(/\\/g, '/');
+    const sdkRoot = __dirname.replace(/\\/g, '/');
+    const escapeRx = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+    const include = [ new RegExp('^' + escapeRx(cwd) + '/(?!node_modules/)') ];
+    // Only skip our own files and Babel internals; repository/service layers stay instrumented.
+    const exclude = [
+        new RegExp('^' + escapeRx(sdkRoot) + '/'), // never instrument the SDK itself
+        /node_modules[\\/]@babel[\\/].*/,
+    ];
+
+    return {
+        instrument: true,
+        include,
+        exclude,
+        mode: process.env.TRACE_MODE || 'trace',
+        samplingMs: 10,
+    };
+}
+
+/** Call this from the client app to enable tracing. Safe to call multiple times. */
+export function initReproTracing(opts?: ReproTracingInitOptions) {
+    const options = opts ?? {};
+
+    if (hasOwn(options, 'traceInterceptors')) {
+        setInterceptorTracingEnabled(!!options.traceInterceptors);
+    }
+    if (hasOwn(options, 'disableFunctionTypes')) {
+        setDisabledFunctionTypes(options.disableFunctionTypes ?? null);
+    }
+    if (hasOwn(options, 'disableFunctionTraces')) {
+        setDisabledFunctionTraces(options.disableFunctionTraces ?? null);
+    }
+    if (hasOwn(options, 'disableTraceFiles')) {
+        setDisabledTraceFiles(options.disableTraceFiles ?? null);
+    }
+    if (hasOwn(options, 'logFunctionCalls') && typeof options.logFunctionCalls === 'boolean') {
+        setReproTraceLogsEnabled(options.logFunctionCalls);
+    }
+
+    if (__TRACER_READY) {
+        applyTraceLogPreference(__TRACER__);
+        return __TRACER__;
+    }
+    try {
+        const tracerPkg: TracerApi = require('../tracer');
+        __TRACER__ = tracerPkg;
+
+        applyTraceLogPreference(tracerPkg);
+
+        const {
+            disableFunctionTraces: _disableFunctionTraces,
+            disableFunctionTypes: _disableFunctionTypes,
+            disableTraceFiles: _disableTraceFiles,
+            logFunctionCalls: _logFunctionCalls,
+            traceInterceptors: _traceInterceptors,
+            ...rest
+        } = options;
+        const initOpts = { ...defaultTracerInitOpts(), ...(rest as TracerInitOpts) };
+        tracerPkg.init?.(initOpts);
+        tracerPkg.patchHttp?.();
+        applyTraceLogPreference(tracerPkg);
+        __TRACER_READY = true;
+        patchAllKnownMongooseInstances();
+        // Patch again on the next tick to catch mongoose copies that load after init (different versions/copies).
+        setImmediate(() => patchAllKnownMongooseInstances());
+    } catch {
+        __TRACER__ = null; // SDK still works without tracer
+    } finally {
+        // keep Mongoose prototypes pristine in either case
+        restoreMongooseIfNeeded();
+        setImmediate(restoreMongooseIfNeeded);
+    }
+    return __TRACER__;
+}
+
+/** Optional helper if users want to check it. */
+export function isReproTracingEnabled() { return __TRACER_READY; }
+
+function captureSpanContextFromTracer(source?: any): SpanContext | null {
+    try {
+        // Prefer a preserved store captured at the call-site for thenables (e.g., Mongoose Query),
+        // because the tracer intentionally detaches spans before the query is actually executed.
+        const promiseStore = source && source[Symbol.for('__repro_promise_store')];
+        if (promiseStore) {
+            const stack = Array.isArray(promiseStore.__repro_span_stack) ? promiseStore.__repro_span_stack : [];
+            const top = stack.length ? stack[stack.length - 1] : null;
+            const spanId = top && top.id != null ? top.id : null;
+            const parentSpanId = top && top.parentId != null
+                ? top.parentId
+                : (stack.length >= 2 ? (stack[stack.length - 2]?.id ?? null) : null);
+            const depth = top && top.depth != null
+                ? top.depth
+                : (typeof promiseStore.depth === 'number'
+                    ? promiseStore.depth
+                    : (stack.length ? stack.length : null));
+            const traceId = promiseStore.traceId ?? null;
+            if (traceId || spanId !== null || parentSpanId !== null) {
+                return { traceId, spanId, parentSpanId, depth: depth == null ? null : depth };
+            }
+        }
+
+        const fromSource = source && source.__repro_span_context;
+        if (fromSource) {
+            return {
+                traceId: fromSource.traceId ?? null,
+                spanId: fromSource.spanId ?? null,
+                parentSpanId: fromSource.parentSpanId ?? null,
+                depth: fromSource.depth ?? null,
+            };
+        }
+
+        const ctx = __TRACER__?.getCurrentSpanContext?.();
+        if (ctx) {
+            const span: SpanContext = {
+                traceId: ctx.traceId ?? __TRACER__?.getCurrentTraceId?.() ?? null,
+                spanId: ctx.spanId ?? null,
+                parentSpanId: ctx.parentSpanId ?? null,
+                depth: ctx.depth ?? null,
+            };
+            if (span.traceId || span.spanId !== null || span.parentSpanId !== null) {
+                return span;
+            }
+        } else if (__TRACER__?.getCurrentTraceId) {
+            const traceId = __TRACER__?.getCurrentTraceId?.() ?? null;
+            if (traceId) {
+                return { traceId, spanId: null, parentSpanId: null, depth: null };
+            }
+        }
+    } catch {}
+    return null;
+}
+
+function isExcludedSpanId(spanId: string | number | null | undefined): boolean {
+    if (spanId === null || spanId === undefined) return false;
+    try {
+        const excluded = (getCtx() as Ctx).excludedSpanIds;
+        if (!excluded || excluded.size === 0) return false;
+        return excluded.has(String(spanId));
+    } catch {
+        return false;
+    }
+}
+
+function shouldCaptureDbSpan(span: SpanContext | null | undefined): span is SpanContext {
+    if (!span || span.spanId === null || span.spanId === undefined) return false;
+    if (isExcludedSpanId(span.spanId)) return false;
+    return true;
+}
+
+function attachSpanContext<T extends Record<string, any>>(target: T, span?: SpanContext | null): T {
+    if (!target) return target;
+    const ctx = span ?? captureSpanContextFromTracer();
+    if (ctx) {
+        try { (target as any).spanContext = ctx; } catch {}
+    }
+    return target;
+}
+
+type Ctx = { sid?: string; aid?: string; clockSkewMs?: number; excludedSpanIds?: Set<string> };
+const als = new AsyncLocalStorage<Ctx>();
+const getCtx = () => als.getStore() || {};
+
+function currentClockSkewMs(): number {
+    const store = als.getStore();
+    const skew = store?.clockSkewMs;
+    return Number.isFinite(skew) ? Number(skew) : 0;
+}
+
+function alignTimestamp(ms: number): number {
+    if (!Number.isFinite(ms)) return ms;
+    const skew = currentClockSkewMs();
+    return Number.isFinite(skew) ? ms + skew : ms;
+}
+
+function alignedNow(): number {
+    return alignTimestamp(Date.now());
+}
+
+let __REQUEST_SEQ = 0;
+function nextRequestId(base: number | string): string {
+    const seq = (++__REQUEST_SEQ).toString(36);
+    const rand = Math.floor(Math.random() * 1e6).toString(36);
+    return `${base}-${seq}${rand}`;
+}
+
+// Track in-flight requests per session so we can delay flushing until a session is drained.
+const sessionInFlight = new Map<string, number>();
+const sessionWaiters = new Map<string, Array<() => void>>();
+
+function beginSessionRequest(sessionId: string) {
+    if (!sessionId) return;
+    sessionInFlight.set(sessionId, (sessionInFlight.get(sessionId) || 0) + 1);
+}
+
+function endSessionRequest(sessionId: string) {
+    if (!sessionId) return;
+    const next = (sessionInFlight.get(sessionId) || 0) - 1;
+    if (next > 0) {
+        sessionInFlight.set(sessionId, next);
+        return;
+    }
+    sessionInFlight.delete(sessionId);
+    const waiters = sessionWaiters.get(sessionId);
+    if (waiters && waiters.length) {
+        sessionWaiters.delete(sessionId);
+        waiters.forEach(fn => { try { fn(); } catch {} });
+    }
+}
+
+function waitForSessionDrain(sessionId: string): Promise<void> {
+    if (!sessionId) return Promise.resolve();
+    const remaining = sessionInFlight.get(sessionId) || 0;
+    if (remaining <= 0) return Promise.resolve();
+
+    return new Promise(resolve => {
+        const list = sessionWaiters.get(sessionId) || [];
+        list.push(resolve);
+        sessionWaiters.set(sessionId, list);
+        if (SESSION_DRAIN_TIMEOUT_MS > 0 && Number.isFinite(SESSION_DRAIN_TIMEOUT_MS)) {
+            setTimeout(resolve, SESSION_DRAIN_TIMEOUT_MS);
+        }
+    });
+}
+
+function balanceTraceEvents(events: TraceEventRecord[]): TraceEventRecord[] {
+    // No balancing / synthetic exits — preserve raw event stream.
+    return Array.isArray(events) ? events : [];
+}
+
+function sortTraceEventsChronologically(events: TraceEventRecord[]): TraceEventRecord[] {
+    return events
+        .map((ev, idx) => ({ ev, idx }))
+        .sort((a, b) => {
+            const ta = typeof a.ev.t === 'number' ? a.ev.t : Number.POSITIVE_INFINITY;
+            const tb = typeof b.ev.t === 'number' ? b.ev.t : Number.POSITIVE_INFINITY;
+            if (ta !== tb) return ta - tb;
+            return a.idx - b.idx; // stable fallback
+        })
+        .map(w => w.ev);
+}
+
+function computeDepthsFromParentsChronologically(events: TraceEventRecord[]): TraceEventRecord[] {
+    const depthBySpan = new Map<string, number>();
+
+    const normId = (v: any) => (v === null || v === undefined ? null : String(v));
+
+    return events.map(ev => {
+        const out = { ...ev };
+        const sid = normId(ev.spanId);
+        const pid = normId(ev.parentSpanId);
+
+        if (ev.type === 'enter') {
+            const parentDepth = pid ? depthBySpan.get(pid) ?? 0 : 0;
+            const depth = Math.max(1, parentDepth + 1);
+            out.depth = depth;
+            if (sid) depthBySpan.set(sid, depth);
+            return out;
+        }
+
+        if (ev.type === 'exit') {
+            if (sid && depthBySpan.has(sid)) {
+                out.depth = depthBySpan.get(sid);
+            } else if (pid && depthBySpan.has(pid)) {
+                out.depth = Math.max(1, (depthBySpan.get(pid) ?? 0) + 1);
+            } else if (typeof ev.depth === 'number') {
+                out.depth = ev.depth;
+            } else {
+                out.depth = 1;
+            }
+            return out;
+        }
+
+        return out;
+    });
+}
+
+function reorderTraceEvents(events: TraceEventRecord[]): TraceEventRecord[] {
+    if (!Array.isArray(events) || !events.length) return events;
+
+    type SpanNode = {
+        id: string;
+        parentId: string | null;
+        enter?: TraceEventRecord;
+        exit?: TraceEventRecord;
+        children: SpanNode[];
+        order: number;
+    };
+
+    const nodes = new Map<string, SpanNode>();
+    const roots: Array<SpanNode | { order: number; ev: TraceEventRecord }> = [];
+
+    const normalizeId = (v: any) => (v === null || v === undefined ? null : String(v));
+
+    const ensureNode = (id: string): SpanNode => {
+        let n = nodes.get(id);
+        if (!n) {
+            n = { id, parentId: null, children: [], order: Number.POSITIVE_INFINITY };
+            nodes.set(id, n);
+        }
+        return n;
+    };
+
+    events.forEach((ev, idx) => {
+        const spanId = normalizeId(ev.spanId);
+        const parentId = normalizeId(ev.parentSpanId);
+        if (!spanId) {
+            roots.push({ order: idx, ev });
+            return;
+        }
+        const node = ensureNode(spanId);
+        node.order = Math.min(node.order, idx);
+        node.parentId = parentId;
+        if (ev.type === 'enter') node.enter = node.enter ?? ev;
+        if (ev.type === 'exit') node.exit = ev;
+    });
+
+    nodes.forEach(node => {
+        if (node.parentId && nodes.has(node.parentId)) {
+            const parent = nodes.get(node.parentId)!;
+            parent.children.push(node);
+        } else {
+            roots.push(node);
+        }
+    });
+
+    const sortChildren = (node: SpanNode) => {
+        node.children.sort((a, b) => a.order - b.order);
+        node.children.forEach(sortChildren);
+    };
+    nodes.forEach(sortChildren);
+
+    roots.sort((a, b) => a.order - b.order);
+
+    const out: TraceEventRecord[] = [];
+    const emitNode = (node: SpanNode, depth: number) => {
+        if (node.enter) {
+            node.enter.depth = depth;
+            out.push(node.enter);
+        }
+        node.children.forEach(child => emitNode(child, depth + 1));
+        if (node.exit) {
+            node.exit.depth = depth;
+            out.push(node.exit);
+        }
+    };
+
+    roots.forEach(entry => {
+        if ('ev' in entry) {
+            out.push(entry.ev);
+        } else {
+            emitNode(entry as SpanNode, 1);
+        }
+    });
+
+    return out;
+}
+
+function getCollectionNameFromDoc(doc: any): string | undefined {
+    const direct =
+        doc?.$__?.collection?.collectionName ||
+        (doc?.$collection as any)?.collectionName ||
+        doc?.collection?.collectionName ||
+        (doc?.collection as any)?.name ||
+        (doc?.constructor as any)?.collection?.collectionName;
+
+    if (direct) return direct;
+
+    if (doc?.$isSubdocument && typeof doc.ownerDocument === 'function') {
+        const parent = doc.ownerDocument();
+        return (
+            parent?.$__?.collection?.collectionName ||
+            (parent?.$collection as any)?.collectionName ||
+            parent?.collection?.collectionName ||
+            (parent?.collection as any)?.name ||
+            (parent?.constructor as any)?.collection?.collectionName
+        );
+    }
+
+    const ctor = doc?.constructor as any;
+    if (ctor?.base && ctor?.base?.collection?.collectionName) {
+        return ctor.base.collection.collectionName;
+    }
+
+    return undefined;
+}
+
+function getCollectionNameFromQuery(q: any): string | undefined {
+    return q?.model?.collection?.collectionName || (q?.model?.collection as any)?.name;
+}
+
+function resolveCollectionOrWarn(source: any, type: 'doc' | 'query'): string {
+    const name =
+        (type === 'doc'
+            ? getCollectionNameFromDoc(source)
+            : getCollectionNameFromQuery(source)) || undefined;
+
+    if (!name) {
+        try {
+            const modelName =
+                type === 'doc'
+                    ? (source?.constructor as any)?.modelName ||
+                    (source?.ownerDocument?.() as any)?.constructor?.modelName
+                    : source?.model?.modelName;
+            // eslint-disable-next-line no-console
+            console.warn('[repro] could not resolve collection name', { type, modelName });
+        } catch {}
+        return 'unknown';
+    }
+    return name;
+}
+
+async function post(
+    cfg: { appId: string; appSecret: string; appName?: string; apiBase?: string },
+    sessionId: string,
+    body: any,
+) {
+    try {
+        const envBase = typeof process !== 'undefined' ? (process as any)?.env?.REPRO_API_BASE : undefined;
+        const legacyBase = (cfg as any)?.apiBase;
+        const apiBase = String(envBase || legacyBase || 'https://oozy-loreta-gully.ngrok-free.dev').replace(/\/+$/, '');
+        await fetch(`${apiBase}/v1/sessions/${sessionId}/backend`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-App-Id': cfg.appId,
+                'X-App-Secret': cfg.appSecret,
+                ...(cfg.appName ? { 'X-App-Name': cfg.appName } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+    } catch { /* swallow in SDK */ }
+}
+
+function readHeaderNumber(value: string | string[] | undefined): number | null {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (typeof raw !== 'string') return null;
+    const trimmed = raw.trim();
+    if (!trimmed) return null;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+
+// -------- helpers for response capture & grouping --------
+function normalizeRouteKey(method: string, rawPath: string) {
+    const base = (rawPath || '/').split('?')[0] || '/';
+    return `${String(method || 'GET').toUpperCase()} ${base}`;
+}
+
+function normalizeFilePath(file?: string | null): string {
+    return file ? String(file).replace(/\\/g, '/').toLowerCase() : '';
+}
+
+function isLikelyAppFile(file?: string | null): boolean {
+    if (!file) return false;
+    const normalized = String(file).replace(/\\/g, '/');
+    if (!normalized) return false;
+    return !normalized.includes('/node_modules/');
+}
+
+function isLikelyNestControllerFile(file?: string | null): boolean {
+    const normalized = normalizeFilePath(file);
+    if (!normalized) return false;
+    if (!isLikelyAppFile(file)) return false;
+    return (
+        normalized.includes('.controller.') ||
+        normalized.includes('/controllers/') ||
+        normalized.includes('.resolver.') ||
+        normalized.includes('/resolvers/')
+    );
+}
+
+function isLikelyNestGuardFile(file?: string | null): boolean {
+    const normalized = normalizeFilePath(file);
+    if (!normalized) return false;
+    return normalized.includes('.guard.') || normalized.includes('/guards/');
+}
+
+function toEndpointTrace(evt: {
+    fn?: string;
+    file?: string;
+    line?: number | null;
+    functionType?: string | null;
+}): EndpointTraceInfo {
+    return {
+        fn: evt.fn ?? null,
+        file: evt.file ?? null,
+        line: evt.line ?? null,
+        functionType: evt.functionType ?? null,
+    };
+}
+
+function coerceBodyToStorable(body: any, contentType?: string | number | string[]) {
+    if (body && typeof body === 'object' && !Buffer.isBuffer(body)) return body;
+
+    const ct = Array.isArray(contentType) ? String(contentType[0]) : String(contentType || '');
+    const isLikelyJson = ct.toLowerCase().includes('application/json');
+
+    try {
+        if (Buffer.isBuffer(body)) {
+            const s = body.toString('utf8');
+            return isLikelyJson ? JSON.parse(s) : s;
+        }
+        if (typeof body === 'string') {
+            return isLikelyJson ? JSON.parse(body) : body;
+        }
+    } catch {
+        if (Buffer.isBuffer(body)) return body.toString('utf8');
+        if (typeof body === 'string') return body;
+    }
+    return body;
+}
+
+const TRACE_VALUE_MAX_DEPTH = 3;
+const TRACE_VALUE_MAX_KEYS = 20;
+const TRACE_VALUE_MAX_ITEMS = 20;
+const TRACE_VALUE_MAX_STRING = 2000;
+const TRACE_BATCH_SIZE = 100;
+const TRACE_FLUSH_DELAY_MS = 20;
+// Choose how to order trace events in payloads.
+//  - "chronological" (default): preserve event arrival order (no reshuffle).
+//  - "tree": rebuild a parent/child tree from spanIds for depth visualizations (can shuffle concurrent spans).
+const TRACE_ORDER_MODE = (() => {
+    const mode = String(process.env.TRACE_ORDER_MODE || '').toLowerCase().trim();
+    return mode === 'tree' ? 'tree' : 'chronological';
+})();
+// Extra grace period after res.finish to catch late fire-and-forget work before unsubscribing.
+const TRACE_LINGER_AFTER_FINISH_MS = (() => {
+    const env = Number(process.env.TRACE_LINGER_AFTER_FINISH_MS);
+    if (Number.isFinite(env) && env >= 0) return env;
+    return 1000; // default 1s to catch slow async callbacks (e.g., email sends)
+})();
+const TRACE_IDLE_FLUSH_MS = (() => {
+    const env = Number(process.env.TRACE_IDLE_FLUSH_MS);
+    if (Number.isFinite(env) && env > 0) return env;
+    // Keep the listener alive until no new events arrive for this many ms after finish.
+    return 2000;
+})();
+const SESSION_DRAIN_TIMEOUT_MS = (() => {
+    const env = Number(process.env.SESSION_DRAIN_TIMEOUT_MS);
+    if (Number.isFinite(env) && env >= 0) return env;
+    // Bound wait for draining sessions to avoid lost flushes when a request hangs.
+    return 10000;
+})();
+
+function isThenable(value: any): value is PromiseLike<any> {
+    return value != null && typeof value === 'object' && typeof (value as any).then === 'function';
+}
+
+function coerceMongoId(value: any): string | null {
+    if (!value) return null;
+    const name = value?.constructor?.name;
+    if (name === 'ObjectId' || name === 'ObjectID' || value?._bsontype === 'ObjectID') {
+        try {
+            if (typeof (value as any).toHexString === 'function') return (value as any).toHexString();
+            if (typeof (value as any).toString === 'function') return (value as any).toString();
+        } catch {}
+        return '[mongo-id]';
+    }
+    return null;
+}
+
+function isMongoSessionLike(value: any): boolean {
+    const ctor = value?.constructor?.name?.toLowerCase?.() || '';
+    return (
+        !!ctor &&
+        ctor.includes('session') &&
+        (typeof (value as any).endSession === 'function' || typeof (value as any).inTransaction === 'function')
+    );
+}
+
+function describeMongoPlaceholder(value: any): string | null {
+    const ctor = value?.constructor?.name;
+    if (!ctor) return null;
+    const lower = ctor.toLowerCase();
+
+    if (isMongoSessionLike(value)) return 'mongo-session';
+    if (lower.includes('cursor')) return 'mongo-cursor';
+    if (lower.includes('topology')) return 'mongo-topology';
+    if (lower.includes('connection')) return 'mongo-connection';
+    if (lower.includes('collection')) {
+        const name = (value as any)?.collectionName || (value as any)?.name;
+        return name ? `mongo-collection(${name})` : 'mongo-collection';
+    }
+    if (lower.includes('db') && typeof (value as any).command === 'function') return 'mongo-db';
+    return null;
+}
+
+function isMongooseDocumentLike(value: any): boolean {
+    return !!value && typeof value === 'object' && typeof (value as any).toObject === 'function' && !!(value as any).$__;
+}
+
+function toPlainMongooseDoc(value: any): any | null {
+    try {
+        const plain = (value as any).toObject?.({ depopulate: true, virtuals: false, minimize: false, getters: false });
+        if (plain && plain !== value) return plain;
+    } catch {}
+    try {
+        const json = (value as any).toJSON?.();
+        if (json && json !== value) return json;
+    } catch {}
+    return null;
+}
+
+function isMongooseQueryLike(value: any): boolean {
+    return !!value && typeof value === 'object' && typeof (value as any).exec === 'function' && ((value as any).model || (value as any).op);
+}
+
+function summarizeMongooseQueryValue(value: any, depth: number, seen: WeakSet<object>) {
+    try {
+        const model = (value as any).model?.modelName || (value as any)._model?.modelName || undefined;
+        const op = (value as any).op || (value as any).operation || (value as any).options?.op || undefined;
+        return {
+            __type: 'MongooseQuery',
+            model,
+            op,
+            filter: sanitizeTraceValue((value as any).getFilter?.() ?? (value as any)._conditions, depth + 1, seen),
+            update: sanitizeTraceValue((value as any).getUpdate?.() ?? (value as any)._update, depth + 1, seen),
+            options: sanitizeTraceValue((value as any).getOptions?.() ?? (value as any).options, depth + 1, seen),
+        };
+    } catch {
+        return 'mongo-query';
+    }
+}
+
+function safeStringifyUnknown(value: any): string | undefined {
+    try {
+        const str = String(value);
+        if (str === '[object Object]') return '[unserializable]';
+        return str;
+    } catch {
+        return undefined;
+    }
+}
+
+function chunkArray<T>(arr: T[], size: number): T[][] {
+    if (!Array.isArray(arr) || arr.length === 0) return [];
+    if (!size || size <= 0) return [arr.slice()];
+
+    const batches: T[][] = [];
+    for (let i = 0; i < arr.length; i += size) {
+        batches.push(arr.slice(i, i + size));
+    }
+    return batches;
+}
+
+function sanitizeTraceValue(value: any, depth = 0, seen: WeakSet<object> = new WeakSet()): any {
+    if (value === null || value === undefined) return value;
+    const type = typeof value;
+
+    if (type === 'number' || type === 'boolean') return value;
+    if (type === 'string') {
+        if (value.length <= TRACE_VALUE_MAX_STRING) return value;
+        return `${value.slice(0, TRACE_VALUE_MAX_STRING)}…(${value.length - TRACE_VALUE_MAX_STRING} more chars)`;
+    }
+    if (type === 'bigint') return value.toString();
+    if (type === 'symbol') return value.toString();
+    if (type === 'function') return `[Function${value.name ? ` ${value.name}` : ''}]`;
+
+    const mongoId = coerceMongoId(value);
+    if (mongoId !== null) return mongoId;
+
+    if (isMongooseQueryLike(value)) {
+        const captured = (value as any).__repro_result;
+        if (captured !== undefined) {
+            return sanitizeTraceValue(captured, depth + 1, seen);
+        }
+        return summarizeMongooseQueryValue(value, depth, seen);
+    }
+
+    const mongoPlaceholder = describeMongoPlaceholder(value);
+    if (mongoPlaceholder) return mongoPlaceholder;
+
+    if (isThenable(value)) {
+        return { __type: 'Promise', state: 'pending' };
+    }
+
+    if (isMongooseDocumentLike(value)) {
+        const plain = toPlainMongooseDoc(value);
+        if (plain && plain !== value) {
+            return sanitizeTraceValue(plain, depth, seen);
+        }
+    }
+
+    if (Buffer.isBuffer(value)) {
+        return {
+            __type: 'Buffer',
+            length: value.length,
+            preview: value.length ? value.slice(0, 32).toString('hex') : '',
+        };
+    }
+
+    if (value instanceof Date) return value.toISOString();
+    if (value instanceof RegExp) return value.toString();
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: value.message,
+            stack: value.stack,
+        };
+    }
+
+    if (type !== 'object') return String(value);
+
+    if (!Array.isArray(value) && !(value instanceof Map) && !(value instanceof Set)) {
+        const dehydrated = dehydrateComplexValue(value);
+        if (dehydrated !== value) {
+            return sanitizeTraceValue(dehydrated, depth, seen);
+        }
+    }
+
+    if (seen.has(value)) return '[Circular]';
+    seen.add(value);
+
+    if (depth >= TRACE_VALUE_MAX_DEPTH) {
+        const shallow = safeJson(value);
+        if (shallow !== undefined) {
+            return shallow;
+        }
+        const ctor = value?.constructor?.name;
+        return ctor && ctor !== 'Object'
+            ? { __class: ctor, __truncated: `depth>${TRACE_VALUE_MAX_DEPTH}` }
+            : { __truncated: `depth>${TRACE_VALUE_MAX_DEPTH}` };
+    }
+
+    if (Array.isArray(value)) {
+        const out = value.slice(0, TRACE_VALUE_MAX_ITEMS)
+            .map(item => sanitizeTraceValue(item, depth + 1, seen));
+        if (value.length > TRACE_VALUE_MAX_ITEMS) {
+            out.push(`…(${value.length - TRACE_VALUE_MAX_ITEMS} more items)`);
+        }
+        return out;
+    }
+
+    if (value instanceof Map) {
+        const entries: Array<[any, any]> = [];
+        for (const [k, v] of value) {
+            if (entries.length >= TRACE_VALUE_MAX_ITEMS) break;
+            entries.push([
+                sanitizeTraceValue(k, depth + 1, seen),
+                sanitizeTraceValue(v, depth + 1, seen)
+            ]);
+        }
+        if (value.size > TRACE_VALUE_MAX_ITEMS) {
+            entries.push([`…(${value.size - TRACE_VALUE_MAX_ITEMS} more entries)`, null]);
+        }
+        return { __type: 'Map', entries };
+    }
+
+    if (value instanceof Set) {
+        const arr: any[] = [];
+        for (const item of value) {
+            if (arr.length >= TRACE_VALUE_MAX_ITEMS) break;
+            arr.push(sanitizeTraceValue(item, depth + 1, seen));
+        }
+        if (value.size > TRACE_VALUE_MAX_ITEMS) {
+            arr.push(`…(${value.size - TRACE_VALUE_MAX_ITEMS} more items)`);
+        }
+        return { __type: 'Set', values: arr };
+    }
+
+    const ctor = value?.constructor?.name;
+    const result: Record<string, any> = {};
+    const keys = Object.keys(value);
+    for (const key of keys.slice(0, TRACE_VALUE_MAX_KEYS)) {
+        try {
+            result[key] = sanitizeTraceValue((value as any)[key], depth + 1, seen);
+        } catch (err) {
+            result[key] = `[Cannot serialize: ${(err as Error)?.message || 'unknown error'}]`;
+        }
+    }
+    if (keys.length > TRACE_VALUE_MAX_KEYS) {
+        result.__truncatedKeys = keys.length - TRACE_VALUE_MAX_KEYS;
+    }
+    if (ctor && ctor !== 'Object') {
+        result.__class = ctor;
+    }
+    return result;
+}
+
+function sanitizeTraceArgs(values: any): any {
+    if (!Array.isArray(values)) return values;
+    return values.map(v => sanitizeTraceValue(v));
+}
+
+function sanitizeRequestSnapshot(value: any) {
+    if (value === undefined) return undefined;
+    try {
+        return sanitizeTraceValue(value);
+    } catch {
+        if (value === null) return null;
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            return value;
+        }
+        try { return JSON.parse(JSON.stringify(value)); } catch {}
+        return safeStringifyUnknown(value);
+    }
+}
+
+const DEFAULT_SENSITIVE_HEADERS: Array<string | RegExp> = [
+    'authorization',
+    'proxy-authorization',
+    'authentication',
+    'auth',
+    'x-api-key',
+    'api-key',
+    'apikey',
+    'x-api-token',
+    'x-access-token',
+    'x-auth-token',
+    'x-id-token',
+    'x-refresh-token',
+    'id-token',
+    'refresh-token',
+    'cookie',
+    'set-cookie',
+];
+
+const DEFAULT_MASK_REPLACEMENT = '[REDACTED]';
+
+function normalizeHeaderRules(rules?: HeaderRule | HeaderRule[] | null): HeaderRule[] {
+    return normalizePatternArray<HeaderRule>(rules || []);
+}
+
+function matchesHeaderRule(name: string, rules: HeaderRule[]): boolean {
+    if (!rules || !rules.length) return false;
+    const lower = name.toLowerCase();
+    return rules.some(rule => {
+        if (rule instanceof RegExp) {
+            try { return rule.test(name); } catch { return false; }
+        }
+        return lower === String(rule).toLowerCase();
+    });
+}
+
+function normalizeHeaderCaptureConfig(raw?: boolean | HeaderCaptureOptions): NormalizedHeaderCapture {
+    if (raw === false) {
+        return { enabled: false, allowSensitive: false, mask: [], unmask: [] };
+    }
+    const opts: HeaderCaptureOptions = raw && raw !== true ? raw : {};
+    return {
+        enabled: true,
+        allowSensitive: opts.allowSensitiveHeaders === true,
+        mask: [...normalizeHeaderRules(opts.maskHeaders), ...normalizeHeaderRules(opts.dropHeaders)],
+        unmask: [...normalizeHeaderRules(opts.unmaskHeaders), ...normalizeHeaderRules(opts.keepHeaders)],
+    };
+}
+
+function sanitizeHeaderValue(value: any): any {
+    if (value === undefined) return undefined;
+    if (Array.isArray(value)) {
+        const arr = value.map(v => sanitizeHeaderValue(v)).filter(v => v !== undefined);
+        return arr.length ? arr : undefined;
+    }
+    if (value === null) return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+    const safe = safeJson(value);
+    if (safe !== undefined) return safe;
+    return safeStringifyUnknown(value);
+}
+
+function sanitizeHeaders(headers: any, rawCfg?: boolean | HeaderCaptureOptions) {
+    const cfg = normalizeHeaderCaptureConfig(rawCfg);
+    if (!cfg.enabled) return {};
+
+    const out: Record<string, any> = {};
+
+    for (const [rawKey, rawVal] of Object.entries(headers || {})) {
+        const key = String(rawKey || '').toLowerCase();
+        if (!key) continue;
+        const sanitizedValue = sanitizeHeaderValue(rawVal);
+        if (sanitizedValue !== undefined) {
+            out[key] = sanitizedValue;
+        }
+    }
+
+    const maskList = cfg.allowSensitive ? cfg.mask : [...DEFAULT_SENSITIVE_HEADERS, ...cfg.mask];
+    Object.keys(out).forEach((key) => {
+        if (!matchesHeaderRule(key, maskList)) return;
+        if (matchesHeaderRule(key, cfg.unmask)) return;
+        const current = out[key];
+        if (Array.isArray(current)) {
+            out[key] = current.map(() => DEFAULT_MASK_REPLACEMENT);
+            return;
+        }
+        out[key] = DEFAULT_MASK_REPLACEMENT;
+    });
+
+    return out;
+}
+
+// ===================================================================
+// Masking (request/response payloads + trace args/returns/errors)
+// ===================================================================
+type NormalizedMaskRule = {
+    when?: ReproMaskWhen;
+    targets: ReproMaskTarget[];
+    paths: string[][];
+    keys?: TraceRulePattern;
+    replacement: any;
+};
+
+type NormalizedMaskingConfig = {
+    replacement: any;
+    rules: NormalizedMaskRule[];
+};
+
+type MaskRequestContext = {
+    method: string;
+    path: string;
+    key: string;
+};
+
+function normalizeMaskTargets(target: ReproMaskTarget | ReproMaskTarget[]): ReproMaskTarget[] {
+    const out = Array.isArray(target) ? target : [target];
+    return out.filter((t): t is ReproMaskTarget => typeof t === 'string' && t.length > 0);
+}
+
+function parseMaskPath(raw: string): string[] {
+    if (!raw) return [];
+    let path = String(raw).trim();
+    if (!path) return [];
+    if (path.startsWith('$.')) path = path.slice(2);
+    if (path.startsWith('.')) path = path.slice(1);
+    path = path.replace(/\[(\d+|\*)\]/g, '.$1');
+    return path.split('.').map(s => s.trim()).filter(Boolean);
+}
+
+function normalizeMaskPaths(paths?: string | string[]): string[][] {
+    if (!paths) return [];
+    const list = Array.isArray(paths) ? paths : [paths];
+    return list
+        .map(p => parseMaskPath(p))
+        .filter(parts => parts.length > 0);
+}
+
+function normalizeMaskingConfig(raw?: ReproMaskingConfig): NormalizedMaskingConfig | null {
+    const rules = raw?.rules;
+    if (!Array.isArray(rules) || rules.length === 0) return null;
+    const replacement = raw?.replacement ?? DEFAULT_MASK_REPLACEMENT;
+    const normalized: NormalizedMaskRule[] = [];
+    for (const rule of rules) {
+        if (!rule) continue;
+        const targets = normalizeMaskTargets(rule.target);
+        if (!targets.length) continue;
+        const paths = normalizeMaskPaths(rule.paths);
+        const keys = rule.keys ?? undefined;
+        if (!paths.length && !keys) continue;
+        normalized.push({
+            when: rule.when,
+            targets,
+            paths,
+            keys,
+            replacement: rule.replacement ?? replacement,
+        });
+    }
+    return normalized.length ? { replacement, rules: normalized } : null;
+}
+
+function maskWhenRequiresTrace(when: ReproMaskWhen): boolean {
+    return Boolean(
+        when.fn ||
+        when.functionName ||
+        when.wrapper ||
+        when.wrapperClass ||
+        when.className ||
+        when.owner ||
+        when.file ||
+        when.lib ||
+        when.library ||
+        when.type ||
+        when.functionType ||
+        when.event ||
+        when.eventType
+    );
+}
+
+function matchesMaskWhen(when: ReproMaskWhen | undefined, req: MaskRequestContext, trace: TraceEventForFilter | null): boolean {
+    if (!when) return true;
+    if (!matchesPattern(req.method, when.method)) return false;
+    if (!matchesPattern(req.path, when.path)) return false;
+    if (!matchesPattern(req.key, when.key)) return false;
+
+    if (maskWhenRequiresTrace(when)) {
+        if (!trace) return false;
+        if (!matchesRule(when, trace)) return false;
+    }
+
+    return true;
+}
+
+function maskKeysInPlace(node: any, keys: TraceRulePattern, replacement: any) {
+    if (!node) return;
+    if (Array.isArray(node)) {
+        node.forEach(item => maskKeysInPlace(item, keys, replacement));
+        return;
+    }
+    if (typeof node !== 'object') return;
+    Object.keys(node).forEach((key) => {
+        if (matchesPattern(key, keys, false)) {
+            try { node[key] = replacement; } catch {}
+            return;
+        }
+        maskKeysInPlace(node[key], keys, replacement);
+    });
+}
+
+function maskPathInPlace(node: any, pathParts: string[], replacement: any, depth: number = 0) {
+    if (!node) return;
+    if (depth >= pathParts.length) return;
+    const part = pathParts[depth];
+    const isLast = depth === pathParts.length - 1;
+
+    const applyAt = (container: any, key: string | number) => {
+        if (!container) return;
+        try { container[key] = replacement; } catch {}
+    };
+
+    if (part === '*') {
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                if (isLast) applyAt(node, i);
+                else maskPathInPlace(node[i], pathParts, replacement, depth + 1);
+            }
+        } else if (typeof node === 'object') {
+            for (const key of Object.keys(node)) {
+                if (isLast) applyAt(node, key);
+                else maskPathInPlace(node[key], pathParts, replacement, depth + 1);
+            }
+        }
+        return;
+    }
+
+    const index = Number(part);
+    const isIndex = Number.isInteger(index) && String(index) === part;
+    if (Array.isArray(node) && isIndex) {
+        if (index < 0 || index >= node.length) return;
+        if (isLast) applyAt(node, index);
+        else maskPathInPlace(node[index], pathParts, replacement, depth + 1);
+        return;
+    }
+
+    if (typeof node !== 'object') return;
+    if (!Object.prototype.hasOwnProperty.call(node, part)) return;
+    if (isLast) applyAt(node, part);
+    else maskPathInPlace(node[part], pathParts, replacement, depth + 1);
+}
+
+function applyMasking(
+    target: ReproMaskTarget,
+    value: any,
+    req: MaskRequestContext,
+    trace: TraceEventForFilter | null,
+    masking: NormalizedMaskingConfig | null
+) {
+    if (!masking || !masking.rules.length) return value;
+    if (value === undefined) return value;
+    for (const rule of masking.rules) {
+        if (!rule.targets.includes(target)) continue;
+        if (!matchesMaskWhen(rule.when, req, trace)) continue;
+        const replacement = rule.replacement ?? masking.replacement ?? DEFAULT_MASK_REPLACEMENT;
+        if (rule.keys) maskKeysInPlace(value, rule.keys, replacement);
+        if (rule.paths.length) {
+            rule.paths.forEach(parts => maskPathInPlace(value, parts, replacement, 0));
+        }
+    }
+    return value;
+}
+
+// ===================================================================
+// reproMiddleware — unchanged behavior + passive per-request trace
+// ===================================================================
+export type ReproMiddlewareConfig = {
+    appId: string;
+    appSecret: string;
+    appName?: string;
+    /** Configure header capture/masking. Defaults to capturing with sensitive headers masked. */
+    captureHeaders?: boolean | HeaderCaptureOptions;
+    /** Optional masking rules for request/response payloads and function traces. */
+    masking?: ReproMaskingConfig;
+};
+
+export function reproMiddleware(cfg: ReproMiddlewareConfig) {
+    const masking = normalizeMaskingConfig(cfg.masking);
+    return function (req: Request, res: Response, next: NextFunction) {
+        const sid = (req.headers['x-bug-session-id'] as string) || '';
+        const aid = (req.headers['x-bug-action-id'] as string) || '';
+        if (!sid || !aid) return next(); // only capture tagged requests
+
+        const requestStartRaw = Date.now();
+        const headerTs = readHeaderNumber(req.headers[REQUEST_START_HEADER]);
+        const clockSkewMs = headerTs !== null ? headerTs - requestStartRaw : 0;
+        const requestEpochMs = headerTs !== null ? headerTs : requestStartRaw + clockSkewMs;
+        const rid = nextRequestId(requestEpochMs);
+        const t0 = requestStartRaw;
+        const url = (req as any).originalUrl || req.url || '/';
+        const urlPathOnly = (url || '/').split('?')[0] || '/';
+        const path = url; // back-compat
+        const key = normalizeRouteKey(req.method, url);
+        const maskReq: MaskRequestContext = { method: String(req.method || 'GET').toUpperCase(), path: urlPathOnly, key };
+        const requestHeaders = sanitizeHeaders(req.headers, cfg.captureHeaders);
+        beginSessionRequest(sid);
+
+        // ---- response body capture (unchanged) ----
+        let capturedBody: any = undefined;
+        const origJson = res.json.bind(res as any);
+        (res as any).json = (body: any) => { capturedBody = body; return origJson(body); };
+
+        const origSend = res.send.bind(res as any);
+        (res as any).send = (body: any) => {
+            if (capturedBody === undefined) {
+                capturedBody = coerceBodyToStorable(body, res.getHeader?.('content-type'));
+            }
+            return origSend(body);
+        };
+
+        const origWrite = (res as any).write.bind(res as any);
+        const origEnd = (res as any).end.bind(res as any);
+        const chunks: Array<Buffer | string> = [];
+        (res as any).write = (chunk: any, ...args: any[]) => { try { if (chunk != null) chunks.push(chunk); } catch {} return origWrite(chunk, ...args); };
+        (res as any).end = (chunk?: any, ...args: any[]) => { try { if (chunk != null) chunks.push(chunk); } catch {} return origEnd(chunk, ...args); };
+
+        // ---- our ALS (unchanged) ----
+        const tracerApiWithTrace = __TRACER__ as (TracerApi & { withTrace?: (id: string, fn: () => void) => void }) | null;
+        const runInTrace = (fn: () => void) => {
+            if (tracerApiWithTrace?.withTrace) {
+                return tracerApiWithTrace.withTrace(rid, fn);
+            }
+            return fn();
+        };
+
+	        runInTrace(() => als.run({ sid, aid, clockSkewMs, excludedSpanIds: new Set<string>() }, () => {
+            const events: TraceEventRecord[] = [];
+            let endpointTrace: EndpointTraceInfo | null = null;
+            let preferredAppTrace: EndpointTraceInfo | null = null;
+            let firstAppTrace: EndpointTraceInfo | null = null;
+            let unsubscribe: undefined | (() => void);
+            let flushed = false;
+            let finished = false;
+            let finishedAt: number | null = null;
+            let lastEventAt: number = Date.now();
+            let idleTimer: NodeJS.Timeout | null = null;
+	            let hardStopTimer: NodeJS.Timeout | null = null;
+            let drainTimer: NodeJS.Timeout | null = null;
+            let flushPayload: null | (() => void) = null;
+            const activeSpans = new Set<string>();
+            let anonymousSpanDepth = 0;
+	            const ACTIVE_SPAN_FORCE_FLUSH_MS = 60000; // hard cutoff after finish to avoid endlessly running replies
+
+            const clearTimers = () => {
+                if (idleTimer) {
+                    try { clearTimeout(idleTimer); } catch {}
+                    idleTimer = null;
+                }
+                if (hardStopTimer) {
+                    try { clearTimeout(hardStopTimer); } catch {}
+                    hardStopTimer = null;
+                }
+                if (drainTimer) {
+                    try { clearTimeout(drainTimer); } catch {}
+                    drainTimer = null;
+                }
+            };
+
+            const hasActiveWork = () => activeSpans.size > 0 || anonymousSpanDepth > 0;
+
+            const scheduleIdleFlush = (delay: number = TRACE_IDLE_FLUSH_MS) => {
+                if (!finished || flushed) return;
+                if (hasActiveWork()) return;
+                if (idleTimer) {
+                    try { clearTimeout(idleTimer); } catch {}
+                }
+                idleTimer = setTimeout(() => doFlush(false), delay);
+            };
+
+	            const doFlush = (force: boolean = false) => {
+	                if (flushed) return;
+	                const now = Date.now();
+	                const stillActive = hasActiveWork();
+	                const quietMs = now - lastEventAt;
+	                const waitedFinish = finishedAt === null ? 0 : now - finishedAt;
+
+                // If work is still active and we haven't been quiet long enough, defer.
+                if (stillActive && !force) {
+                    const remaining = Math.max(0, TRACE_LINGER_AFTER_FINISH_MS - quietMs);
+                    scheduleIdleFlush(Math.max(remaining, 10));
+                    return;
+                }
+	                if (stillActive && force) {
+	                    // Allow forced flush after either linger window of silence or max guard.
+	                    if (quietMs < TRACE_LINGER_AFTER_FINISH_MS && waitedFinish < ACTIVE_SPAN_FORCE_FLUSH_MS) {
+	                        const remainingQuiet = TRACE_LINGER_AFTER_FINISH_MS - quietMs;
+	                        const remainingGuard = ACTIVE_SPAN_FORCE_FLUSH_MS - waitedFinish;
+	                        if (hardStopTimer) {
+	                            try { clearTimeout(hardStopTimer); } catch {}
+	                        }
+	                        hardStopTimer = setTimeout(() => doFlush(true), Math.max(10, Math.min(remainingQuiet, remainingGuard)));
+	                        return;
+	                    }
+	                }
+	                flushed = true;
+	                clearTimers();
+                try { unsubscribe && unsubscribe(); } catch {}
+                try { flushPayload?.(); } catch {}
+            };
+
+            const bumpIdle = () => {
+                if (!finished || flushed) return;
+                if (idleTimer) {
+                    try { clearTimeout(idleTimer); } catch {}
+                }
+                scheduleIdleFlush();
+            };
+
+            const normalizeSpanId = (val: any): string | null => {
+                if (val === null || val === undefined) return null;
+                const str = String(val);
+                return str ? str : null;
+            };
+
+            try {
+                if (__TRACER__?.tracer?.on) {
+                    const getTid = __TRACER__?.getCurrentTraceId;
+                    const tidNow = getTid ? getTid() : null;
+                    if (tidNow) {
+                        unsubscribe = __TRACER__.tracer.on((ev: any) => {
+                            if (!ev || ev.traceId !== tidNow) return;
+
+                            const sourceFileForLibrary = typeof ev.sourceFile === 'string' && ev.sourceFile
+                                ? String(ev.sourceFile)
+                                : null;
+
+                            const evt: TraceEventRecord = {
+                                t: alignTimestamp(ev.t),
+                                type: ev.type,
+                                fn: ev.fn,
+                                file: ev.file,
+                                line: ev.line,
+                                depth: ev.depth,
+                                spanId: ev.spanId ?? null,
+                                parentSpanId: ev.parentSpanId ?? null,
+                            };
+
+                            if (ev.functionType !== undefined) {
+                                evt.functionType = ev.functionType;
+                            }
+
+                            const candidate: TraceEventForFilter = {
+                                type: evt.type,
+                                eventType: evt.type,
+                                functionType: evt.functionType ?? null,
+                                fn: evt.fn,
+                                wrapperClass: inferWrapperClassFromFn(evt.fn),
+                                file: evt.file ?? null,
+                                line: evt.line ?? null,
+                                depth: evt.depth,
+                                library: inferLibraryNameFromFile(sourceFileForLibrary ?? evt.file),
+                            };
+
+                            if (ev.args !== undefined) {
+                                evt.args = applyMasking(
+                                    'trace.args',
+                                    sanitizeTraceArgs(ev.args),
+                                    maskReq,
+                                    candidate,
+                                    masking
+                                );
+                            }
+                            if (ev.returnValue !== undefined) {
+                                evt.returnValue = applyMasking(
+                                    'trace.returnValue',
+                                    sanitizeTraceValue(ev.returnValue),
+                                    maskReq,
+                                    candidate,
+                                    masking
+                                );
+                            }
+                            if (ev.error !== undefined) {
+                                evt.error = applyMasking(
+                                    'trace.error',
+                                    sanitizeTraceValue(ev.error),
+                                    maskReq,
+                                    candidate,
+                                    masking
+                                );
+                            }
+                            if (ev.threw !== undefined) {
+                                evt.threw = Boolean(ev.threw);
+                            }
+	                            if (ev.unawaited !== undefined) {
+	                                evt.unawaited = ev.unawaited === true;
+	                            }
+
+	                            const dropEvent = shouldDropTraceEvent(candidate);
+	                            const dropSpanTree = shouldPropagateUserDisabledFunctionTrace(candidate);
+	                            const spanKey = normalizeSpanId(evt.spanId);
+	                            const parentSpanKey = normalizeSpanId(evt.parentSpanId);
+	                            const isChildOfExcluded = parentSpanKey ? isExcludedSpanId(parentSpanKey) : false;
+	                            const isExcluded = spanKey ? isExcludedSpanId(spanKey) : false;
+	                            if (evt.type === 'enter') {
+	                                lastEventAt = Date.now();
+	                                if (spanKey) {
+	                                    activeSpans.add(spanKey);
+                                } else {
+                                    anonymousSpanDepth = Math.max(0, anonymousSpanDepth + 1);
+                                }
+                            } else if (evt.type === 'exit') {
+                                lastEventAt = Date.now();
+                                if (spanKey && activeSpans.has(spanKey)) {
+                                    activeSpans.delete(spanKey);
+                                } else if (!spanKey && anonymousSpanDepth > 0) {
+                                    anonymousSpanDepth = Math.max(0, anonymousSpanDepth - 1);
+	                                }
+	                            }
+
+	                            if (dropEvent || isChildOfExcluded || isExcluded) {
+	                                if (evt.type === 'enter' && spanKey && (dropSpanTree || isChildOfExcluded || isExcluded)) {
+	                                    try { (getCtx() as Ctx).excludedSpanIds?.add(spanKey); } catch {}
+	                                }
+	                                if (finished) {
+	                                    scheduleIdleFlush();
+	                                }
+                                return;
+                            }
+
+                            if (finished) {
+                                scheduleIdleFlush();
+                            }
+
+                            if (evt.type === 'enter' && isLikelyAppFile(evt.file)) {
+                                const depthOk = evt.depth === undefined || evt.depth <= 6;
+                                const trace = toEndpointTrace(evt);
+
+                                if (depthOk && !firstAppTrace) {
+                                    firstAppTrace = trace;
+                                }
+
+                                if (isLikelyNestControllerFile(evt.file)) {
+                                    endpointTrace = trace;
+                                } else if (depthOk && !preferredAppTrace && !isLikelyNestGuardFile(evt.file)) {
+                                    preferredAppTrace = trace;
+                                }
+                            }
+
+                            events.push(evt);
+                            bumpIdle();
+                        });
+                    }
+                }
+            } catch { /* never break user code */ }
+
+            const handleDone = () => {
+                if (finished && flushed) return;
+                finished = true;
+                if (finishedAt === null) {
+                    finishedAt = Date.now();
+                }
+                if (capturedBody === undefined && chunks.length) {
+                    const buf = Buffer.isBuffer(chunks[0])
+                        ? Buffer.concat(chunks.map(c => (Buffer.isBuffer(c) ? c : Buffer.from(String(c)))))
+                        : Buffer.from(chunks.map(String).join(''));
+                    capturedBody = coerceBodyToStorable(buf, res.getHeader?.('content-type'));
+                }
+
+                if (!flushPayload) {
+                    flushPayload = () => {
+                    const baseEvents = balanceTraceEvents(events.slice());
+                    const orderedEvents = TRACE_ORDER_MODE === 'tree'
+                        ? reorderTraceEvents(baseEvents)
+                        : sortTraceEventsChronologically(baseEvents);
+                        const summary = summarizeEndpointFromEvents(orderedEvents);
+                        const chosenEndpoint = summary.endpointTrace
+                            ?? summary.preferredAppTrace
+                            ?? summary.firstAppTrace
+                            ?? endpointTrace
+                            ?? preferredAppTrace
+                            ?? firstAppTrace
+                            ?? { fn: null, file: null, line: null, functionType: null };
+                        const traceBatches = chunkArray(orderedEvents, TRACE_BATCH_SIZE);
+                        const endpointTraceCtx: TraceEventForFilter | null = (() => {
+                            if (!chosenEndpoint?.fn && !chosenEndpoint?.file) return null;
+                            return {
+                                type: 'enter',
+                                eventType: 'enter',
+                                fn: chosenEndpoint.fn ?? undefined,
+                                wrapperClass: inferWrapperClassFromFn(chosenEndpoint.fn),
+                                file: chosenEndpoint.file ?? null,
+                                line: chosenEndpoint.line ?? null,
+                                functionType: chosenEndpoint.functionType ?? null,
+                                library: inferLibraryNameFromFile(chosenEndpoint.file),
+                            };
+                        })();
+
+                        const requestBody = applyMasking(
+                            'request.body',
+                            sanitizeRequestSnapshot((req as any).body),
+                            maskReq,
+                            endpointTraceCtx,
+                            masking
+                        );
+                        const requestParams = applyMasking(
+                            'request.params',
+                            sanitizeRequestSnapshot((req as any).params),
+                            maskReq,
+                            endpointTraceCtx,
+                            masking
+                        );
+                        const requestQuery = applyMasking(
+                            'request.query',
+                            sanitizeRequestSnapshot((req as any).query),
+                            maskReq,
+                            endpointTraceCtx,
+                            masking
+                        );
+                        const maskedHeaders = applyMasking(
+                            'request.headers',
+                            requestHeaders,
+                            maskReq,
+                            endpointTraceCtx,
+                            masking
+                        );
+                        const responseBody = applyMasking(
+                            'response.body',
+                            capturedBody === undefined ? undefined : sanitizeRequestSnapshot(capturedBody),
+                            maskReq,
+                            endpointTraceCtx,
+                            masking
+                        );
+
+                        const requestPayload: Record<string, any> = {
+                            rid,
+                            method: req.method,
+                            url,
+                            path,
+                            status: res.statusCode,
+                            durMs: Date.now() - t0,
+                            headers: maskedHeaders,
+                            key,
+                            respBody: responseBody,
+                            trace: traceBatches.length ? undefined : '[]',
+                        };
+                        if (requestBody !== undefined) requestPayload.body = requestBody;
+                        if (requestParams !== undefined) requestPayload.params = requestParams;
+                        if (requestQuery !== undefined) requestPayload.query = requestQuery;
+                        requestPayload.entryPoint = chosenEndpoint;
+
+	                        post(cfg, sid, {
+	                            entries: [{
+	                                actionId: aid,
+	                                request: requestPayload,
+	                                t: alignedNow(),
+	                            }]
+	                        });
+
+                        if (traceBatches.length) {
+                            for (let i = 0; i < traceBatches.length; i++) {
+                                const batch = traceBatches[i];
+                                let traceStr = '[]';
+                                try { traceStr = JSON.stringify(batch); } catch {}
+
+	                                post(cfg, sid, {
+	                                    entries: [{
+	                                        actionId: aid,
+	                                        trace: traceStr,
+	                                        traceBatch: {
+	                                            rid,
+                                            index: i,
+                                            total: traceBatches.length,
+                                        },
+                                        t: alignedNow(),
+                                    }],
+                                });
+                            }
+                        }
+                    };
+                }
+
+                const waitDrain = waitForSessionDrain(sid);
+                endSessionRequest(sid);
+
+                if (SESSION_DRAIN_TIMEOUT_MS > 0) {
+                    drainTimer = setTimeout(() => doFlush(true), SESSION_DRAIN_TIMEOUT_MS);
+                }
+
+                waitDrain.then(() => {
+                    if (drainTimer) {
+                        try { clearTimeout(drainTimer); } catch {}
+                        drainTimer = null;
+                    }
+                    if (__TRACER_READY) {
+                        bumpIdle();
+                        const hardDeadlineMs = Math.max(
+                            TRACE_FLUSH_DELAY_MS + TRACE_LINGER_AFTER_FINISH_MS,
+                            TRACE_IDLE_FLUSH_MS + TRACE_FLUSH_DELAY_MS,
+                        );
+                        hardStopTimer = setTimeout(() => doFlush(true), hardDeadlineMs);
+                    } else {
+                        doFlush(true);
+                    }
+                }).catch(() => {
+                    doFlush(true);
+                });
+            };
+
+            res.on('finish', handleDone);
+            res.on('close', handleDone);
+
+            next();
+        }));
+    };
+}
+
+// ===================================================================
+// reproMongoosePlugin — stable + NON-intrusive query logs
+//   - NO prototype monkey-patching of Mongoose
+//   - ONLY schema middleware (pre/post) for specific ops
+//   - keeps your existing doc-diff hooks
+// ===================================================================
+export function reproMongoosePlugin(cfg: { appId: string; appSecret: string; appName?: string }) {
+    return function (schema: Schema) {
+        // -------- pre/post save (unchanged) --------
+        schema.pre('save', { document: true }, async function (next) {
+            const { sid, aid } = getCtx();
+            if (!sid || !aid) return next();
+            if ((this as any).$isSubdocument) return next();
+
+            let before: any = null;
+            try {
+                if (!this.isNew) {
+                    const model = this.constructor as Model<any>;
+                    before = await model.findById(this._id).lean().exec();
+                }
+            } catch {}
+            (this as any).__repro_meta = {
+                wasNew: this.isNew,
+                before,
+                collection: resolveCollectionOrWarn(this, 'doc'),
+                spanContext: captureSpanContextFromTracer(this),
+            };
+            next();
+        });
+
+        schema.post('save', { document: true }, function () {
+            const { sid, aid } = getCtx();
+            if (!sid || !aid) return;
+            if ((this as any).$isSubdocument) return;
+
+            const meta = (this as any).__repro_meta || {};
+            const before = meta.before ?? null;
+            const after = this.toObject({ depopulate: true });
+            const collection = meta.collection || resolveCollectionOrWarn(this, 'doc');
+            const spanContext = meta.spanContext || captureSpanContextFromTracer(this);
+            if (!shouldCaptureDbSpan(spanContext)) return;
+
+            const query = meta.wasNew
+                ? { op: 'insertOne', doc: after }
+                : { filter: { _id: this._id }, update: buildMinimalUpdate(before, after), options: { upsert: false } };
+
+	            post(cfg, (getCtx() as Ctx).sid!, {
+	                entries: [{
+	                    actionId: (getCtx() as Ctx).aid!,
+	                    db: [attachSpanContext({
+	                        collection,
+                        pk: { _id: (this as any)._id },
+                        before,
+                        after,
+                        op: meta.wasNew ? 'insert' : 'update',
+                        query,
+                    }, spanContext)],
+                    t: alignedNow(),
+                }]
+            });
+        });
+
+        // -------- findOneAndUpdate capture (unchanged) --------
+        schema.pre<Query<any, any>>('findOneAndUpdate', async function (next) {
+            const { sid, aid } = getCtx();
+            if (!sid || !aid) return next();
+            try {
+                const filter = this.getFilter();
+                const model = this.model as Model<any>;
+                (this as any).__repro_before = await model.findOne(filter).lean().exec();
+                this.setOptions({ new: true });
+                (this as any).__repro_collection = resolveCollectionOrWarn(this, 'query');
+                (this as any).__repro_spanContext = captureSpanContextFromTracer(this);
+            } catch {}
+            next();
+        });
+
+        schema.post<Query<any, any>>('findOneAndUpdate', function (res: any) {
+            const { sid, aid } = getCtx();
+            if (!sid || !aid) return;
+
+            const before = (this as any).__repro_before ?? null;
+            const after = res ?? null;
+            const collection = (this as any).__repro_collection || resolveCollectionOrWarn(this, 'query');
+            const spanContext = (this as any).__repro_spanContext || captureSpanContextFromTracer(this);
+            if (!shouldCaptureDbSpan(spanContext)) return;
+            const pk = after?._id ?? before?._id;
+
+	            post(cfg, (getCtx() as Ctx).sid!, {
+	                entries: [{
+	                    actionId: (getCtx() as Ctx).aid!,
+	                    db: [attachSpanContext({
+	                        collection,
+                        pk: { _id: pk },
+                        before,
+                        after,
+                        op: after && before ? 'update' : after ? 'insert' : 'update',
+                    }, spanContext)],
+                    t: alignedNow()
+                }]
+            });
+        });
+
+        // -------- deleteOne capture (unchanged) --------
+        schema.pre<Query<any, any>>('deleteOne', { document: false, query: true }, async function (next) {
+            const { sid, aid } = getCtx(); if (!sid || !aid) return next();
+            try {
+                const filter = this.getFilter();
+                (this as any).__repro_before = await (this.model as Model<any>).findOne(filter).lean().exec();
+                (this as any).__repro_collection = resolveCollectionOrWarn(this, 'query');
+                (this as any).__repro_filter = filter;
+                (this as any).__repro_spanContext = captureSpanContextFromTracer(this);
+            } catch {}
+            next();
+        });
+
+        schema.post<Query<any, any>>('deleteOne', { document: false, query: true }, function () {
+            const { sid, aid } = getCtx(); if (!sid || !aid) return;
+            const before = (this as any).__repro_before ?? null;
+            if (!before) return;
+            const collection = (this as any).__repro_collection || resolveCollectionOrWarn(this, 'query');
+            const filter = (this as any).__repro_filter ?? { _id: before._id };
+            const spanContext = (this as any).__repro_spanContext || captureSpanContextFromTracer(this);
+            if (!shouldCaptureDbSpan(spanContext)) return;
+	            post(cfg, (getCtx() as Ctx).sid!, {
+	                entries: [{
+	                    actionId: (getCtx() as Ctx).aid!,
+	                    db: [attachSpanContext({
+	                        collection,
+                        pk: { _id: before._id },
+                        before,
+                        after: null,
+                        op: 'delete',
+                        query: { filter },
+                    }, spanContext)],
+                    t: alignedNow()
+                }]
+            });
+        });
+
+        // -------- NON-intrusive generic query telemetry via schema hooks -------
+        const sanitizeDbValue = (value: any) => {
+            const sanitized = sanitizeTraceValue(value);
+            return sanitized === undefined ? undefined : sanitized;
+        };
+
+        const READ_OPS = [
+            'find',
+            'findOne',
+            'countDocuments',
+            'estimatedDocumentCount',
+            'distinct',
+        ] as const;
+
+        const WRITE_OPS = [
+            'updateOne',
+            'updateMany',
+            'replaceOne',
+            'deleteMany',
+            'findOneAndUpdate',
+            'findOneAndDelete',
+            'findOneAndRemove',
+            'findOneAndReplace',
+            'findByIdAndUpdate',
+            'findByIdAndDelete',
+            'findByIdAndRemove',
+            'findByIdAndReplace',
+        ] as const;
+
+        function attachQueryHooks(op: string) {
+            schema.pre(op as any, function (this: any, next: Function) {
+                try {
+                    (this as any).__repro_qmeta = {
+                        t0: Date.now(),
+                        collection: this?.model?.collection?.name || 'unknown',
+                        op,
+                        spanContext: captureSpanContextFromTracer(this),
+                        filter: sanitizeDbValue(this.getFilter?.() ?? this._conditions ?? undefined),
+                        update: sanitizeDbValue(this.getUpdate?.() ?? this._update ?? undefined),
+                        projection: sanitizeDbValue(this.projection?.() ?? this._fields ?? undefined),
+                        options: sanitizeDbValue(this.getOptions?.() ?? this.options ?? undefined),
+                    };
+                } catch {
+                    (this as any).__repro_qmeta = {
+                        t0: Date.now(),
+                        collection: 'unknown',
+                        op,
+                        spanContext: captureSpanContextFromTracer(this),
+                    };
+                }
+                next();
+            });
+
+            schema.post(op as any, function (this: any, res: any) {
+                const { sid, aid } = getCtx();
+                if (!sid) return;
+
+                const meta = (this as any).__repro_qmeta || { t0: Date.now(), collection: 'unknown', op };
+                const resultMeta = summarizeQueryResult(op, res);
+                const spanContext = meta.spanContext || captureSpanContextFromTracer(this);
+
+                emitDbQuery(cfg, sid, aid, {
+                    collection: meta.collection,
+                    op,
+                    query: { filter: meta.filter, update: meta.update, projection: meta.projection, options: meta.options },
+                    resultMeta,
+                    durMs: Date.now() - meta.t0,
+                    t: alignedNow(),
+                    spanContext,
+                });
+            });
+        }
+
+        READ_OPS.forEach(attachQueryHooks);
+        WRITE_OPS.forEach(attachQueryHooks);
+
+        // bulkWrite + insertMany (non-query middleware)
+        schema.pre<any>('insertMany' as any, { document: false, query: false } as any, function (this: any, next: Function, docs?: any[]) {
+            try {
+                (this as any).__repro_insert_meta = {
+                    t0: Date.now(),
+                    collection: this?.collection?.name || this?.model?.collection?.name || 'unknown',
+                    docs: sanitizeDbValue(docs),
+                    spanContext: captureSpanContextFromTracer(this),
+                };
+            } catch {
+                (this as any).__repro_insert_meta = {
+                    t0: Date.now(),
+                    collection: 'unknown',
+                    spanContext: captureSpanContextFromTracer(this),
+                };
+            }
+            next();
+        } as any);
+
+        schema.post<any>('insertMany' as any, { document: false, query: false } as any, function (this: any, docs: any[]) {
+            const { sid, aid } = getCtx();
+            if (!sid) return;
+            const meta = (this as any).__repro_insert_meta || { t0: Date.now(), collection: 'unknown' };
+            const resultMeta = Array.isArray(docs) ? { inserted: docs.length } : summarizeQueryResult('insertMany', docs);
+            const spanContext = meta.spanContext || captureSpanContextFromTracer(this);
+
+            emitDbQuery(cfg, sid, aid, {
+                collection: meta.collection,
+                op: 'insertMany',
+                query: { docs: meta.docs ?? undefined },
+                resultMeta,
+                durMs: Date.now() - meta.t0,
+                t: alignedNow(),
+                spanContext,
+            });
+        } as any);
+
+        schema.pre<any>('bulkWrite' as any, { document: false, query: false } as any, function (this: any, next: Function, ops?: any[]) {
+            try {
+                (this as any).__repro_bulk_meta = {
+                    t0: Date.now(),
+                    collection: this?.collection?.name || this?.model?.collection?.name || 'unknown',
+                    ops: sanitizeDbValue(ops),
+                    spanContext: captureSpanContextFromTracer(this),
+                };
+            } catch {
+                (this as any).__repro_bulk_meta = {
+                    t0: Date.now(),
+                    collection: 'unknown',
+                    spanContext: captureSpanContextFromTracer(this),
+                };
+            }
+            next();
+        } as any);
+
+        schema.post<any>('bulkWrite' as any, { document: false, query: false } as any, function (this: any, res: any) {
+            const { sid, aid } = getCtx();
+            if (!sid) return;
+            const meta = (this as any).__repro_bulk_meta || { t0: Date.now(), collection: 'unknown' };
+            const bulkResult = summarizeBulkResult(res);
+            const resultMeta = { ...bulkResult, result: sanitizeResultForMeta(res?.result ?? res) };
+            const spanContext = meta.spanContext || captureSpanContextFromTracer(this);
+
+            emitDbQuery(cfg, sid, aid, {
+                collection: meta.collection,
+                op: 'bulkWrite',
+                query: { ops: meta.ops ?? undefined },
+                resultMeta,
+                durMs: Date.now() - meta.t0,
+                t: alignedNow(),
+                spanContext,
+            });
+        } as any);
+
+        // Aggregate middleware (non-intrusive)
+        schema.pre('aggregate', function (this: any, next: Function) {
+            try {
+                (this as any).__repro_aggmeta = {
+                    t0: Date.now(),
+                    collection:
+                        this?.model?.collection?.name ||
+                        this?._model?.collection?.name ||
+                        (this?.model && this.model.collection?.name) ||
+                        'unknown',
+                    spanContext: captureSpanContextFromTracer(this),
+                    pipeline: sanitizeDbValue(this.pipeline?.() ?? this._pipeline ?? undefined),
+                };
+            } catch {
+                (this as any).__repro_aggmeta = {
+                    t0: Date.now(),
+                    collection: 'unknown',
+                    pipeline: undefined,
+                    spanContext: captureSpanContextFromTracer(this),
+                };
+            }
+            next();
+        });
+
+        schema.post('aggregate', function (this: any, res: any[]) {
+            const { sid, aid } = getCtx();
+            if (!sid) return;
+
+            const meta = (this as any).__repro_aggmeta || { t0: Date.now(), collection: 'unknown' };
+            const resultMeta = summarizeQueryResult('aggregate', res);
+            const spanContext = meta.spanContext || captureSpanContextFromTracer(this);
+
+            emitDbQuery(cfg, sid, aid, {
+                collection: meta.collection,
+                op: 'aggregate',
+                query: { pipeline: meta.pipeline },
+                resultMeta,
+                durMs: Date.now() - meta.t0,
+                t: alignedNow(),
+                spanContext,
+            });
+        });
+    };
+}
+
+function summarizeQueryResult(op: string, res: any) {
+    const resultPreview = sanitizeResultForMeta(res);
+
+    if (
+        op === 'find' ||
+        op === 'findOne' ||
+        op === 'aggregate' ||
+        op === 'distinct' ||
+        op.startsWith('count')
+    ) {
+        const summary: Record<string, any> = {};
+        if (Array.isArray(res)) summary.docsCount = res.length;
+        else if (res && typeof res === 'object' && typeof (res as any).toArray === 'function') summary.docsCount = undefined;
+        else if (res == null) summary.docsCount = 0;
+        else summary.docsCount = 1;
+
+        if (typeof resultPreview !== 'undefined') {
+            summary.result = resultPreview;
+        }
+        return summary;
+    }
+
+    if (op === 'insertMany') {
+        const summary: Record<string, any> = {};
+        if (Array.isArray(res)) summary.inserted = res.length;
+        if (typeof resultPreview !== 'undefined') summary.result = resultPreview;
+        return summary;
+    }
+
+    if (op === 'bulkWrite') {
+        return { ...summarizeBulkResult(res), result: resultPreview };
+    }
+
+    const stats = pickWriteStats(res);
+    if (typeof resultPreview !== 'undefined') {
+        return { ...stats, result: resultPreview };
+    }
+    return stats;
+}
+
+function summarizeBulkResult(res: any) {
+    return {
+        matched: res?.matchedCount ?? res?.nMatched ?? undefined,
+        modified: res?.modifiedCount ?? res?.nModified ?? undefined,
+        upserted: res?.upsertedCount ?? undefined,
+        deleted: res?.deletedCount ?? undefined,
+    };
+}
+
+function pickWriteStats(r: any) {
+    return {
+        matched: r?.matchedCount ?? r?.n ?? r?.nMatched ?? undefined,
+        modified: r?.modifiedCount ?? r?.nModified ?? undefined,
+        upsertedId: r?.upsertedId ?? r?.upserted?._id ?? undefined,
+        deleted: r?.deletedCount ?? undefined,
+    };
+}
+
+function safeJson(v: any) {
+    try { return v == null ? undefined : JSON.parse(JSON.stringify(v)); } catch { return undefined; }
+}
+
+function sanitizeResultForMeta(value: any) {
+    if (value === undefined) return undefined;
+    if (typeof value === 'function') return undefined;
+    try {
+        return sanitizeTraceValue(value);
+    } catch {
+        const fallback = safeJson(value);
+        return fallback === undefined ? undefined : fallback;
+    }
+}
+
+function dehydrateComplexValue(value: any) {
+    if (!value || typeof value !== 'object') return value;
+    if (Array.isArray(value)) return value;
+    if (value instanceof Date || value instanceof RegExp || Buffer.isBuffer(value)) return value;
+    if (value instanceof Map || value instanceof Set) return value;
+
+    try {
+        if (typeof (value as any).toJSON === 'function') {
+            const plain = (value as any).toJSON();
+            if (plain && plain !== value) return plain;
+        }
+    } catch {}
+
+    try {
+        if (typeof (value as any).toObject === 'function') {
+            const plain = (value as any).toObject();
+            if (plain && plain !== value) return plain;
+        }
+    } catch {}
+
+    const ctor = (value as any)?.constructor?.name;
+    if (ctor && ctor !== 'Object') {
+        const plain = safeJson(value);
+        if (plain !== undefined) return plain;
+    }
+
+    return value;
+}
+
+function emitDbQuery(cfg: any, sid?: string, aid?: string, payload?: any) {
+    if (!sid) return;
+    const spanContext = payload?.spanContext ?? captureSpanContextFromTracer();
+    if (!shouldCaptureDbSpan(spanContext)) return;
+    const dbEntry = attachSpanContext({
+        collection: payload.collection,
+        op: payload.op,
+        query: payload.query ?? undefined,
+        resultMeta: payload.resultMeta ?? undefined,
+        durMs: payload.durMs ?? undefined,
+        pk: null, before: null, after: null,
+        error: payload.error ?? undefined,
+    }, spanContext);
+	    post(cfg, sid, {
+	        entries: [{
+	            actionId: aid ?? null,
+	            db: [dbEntry],
+	            t: payload.t,
+        }]
+    });
+}
+
+function buildMinimalUpdate(before: any, after: any) {
+    const set: Record<string, any> = {};
+    const unset: Record<string, any> = {};
+
+    function walk(b: any, a: any, path = '') {
+        const bKeys = b ? Object.keys(b) : [];
+        const aKeys = a ? Object.keys(a) : [];
+        const all = new Set([...bKeys, ...aKeys]);
+        for (const k of all) {
+            const p = path ? `${path}.${k}` : k;
+            const bv = b?.[k];
+            const av = a?.[k];
+
+            const bothObj =
+                bv && av &&
+                typeof bv === 'object' &&
+                typeof av === 'object' &&
+                !Array.isArray(bv) &&
+                !Array.isArray(av);
+
+            if (bothObj) {
+                walk(bv, av, p);
+            } else if (typeof av === 'undefined') {
+                unset[p] = '';
+            } else if (JSON.stringify(bv) !== JSON.stringify(av)) {
+                set[p] = av;
+            }
+        }
+    }
+
+    walk(before || {}, after || {});
+    const update: any = {};
+    if (Object.keys(set).length) update.$set = set;
+    if (Object.keys(unset).length) update.$unset = unset;
+    return update;
+}
+
+// ===================================================================
+// Sendgrid — unchanged
+// ===================================================================
+export type SendgridPatchConfig = {
+    appId: string;
+    appSecret: string;
+    appName?: string;
+    resolveContext?: () => { sid?: string; aid?: string } | undefined;
+};
+
+export function patchSendgridMail(cfg: SendgridPatchConfig) {
+    let sgMail: any;
+    try { sgMail = require('@sendgrid/mail'); } catch { return; } // no-op if not installed
+
+    if (!sgMail || (sgMail as any).__repro_patched) return;
+    (sgMail as any).__repro_patched = true;
+
+    const origSend = sgMail.send?.bind(sgMail);
+    const origSendMultiple = sgMail.sendMultiple?.bind(sgMail);
+
+    if (origSend) {
+        sgMail.send = async function patchedSend(msg: any, isMultiple?: boolean) {
+            const t0 = Date.now();
+            let statusCode: number | undefined;
+            let headers: Record<string, any> | undefined;
+            try {
+                const res = await origSend(msg, isMultiple);
+                const r = Array.isArray(res) ? res[0] : res;
+                statusCode = r?.statusCode ?? r?.status;
+                headers = r?.headers ?? undefined;
+                return res;
+            } finally {
+                fireCapture('send', msg, t0, statusCode, headers);
+            }
+        };
+    }
+
+    if (origSendMultiple) {
+        sgMail.sendMultiple = async function patchedSendMultiple(msg: any) {
+            const t0 = Date.now();
+            let statusCode: number | undefined;
+            let headers: Record<string, any> | undefined;
+            try {
+                const res = await origSendMultiple(msg);
+                const r = Array.isArray(res) ? res[0] : res;
+                statusCode = r?.statusCode ?? r?.status;
+                headers = r?.headers ?? undefined;
+                return res;
+            } finally {
+                fireCapture('sendMultiple', msg, t0, statusCode, headers);
+            }
+        };
+    }
+
+    function fireCapture(kind: 'send' | 'sendMultiple', rawMsg: any, t0: number, statusCode?: number, headers?: any) {
+        const ctx = getCtx();
+        const sid = ctx.sid ?? cfg.resolveContext?.()?.sid;
+        const aid = ctx.aid ?? cfg.resolveContext?.()?.aid;
+        if (!sid) return;
+
+        const norm = normalizeSendgridMessage(rawMsg);
+	        post(cfg, sid, {
+	            entries: [{
+	                actionId: aid ?? null,
+	                email: {
+	                    provider: 'sendgrid',
+                    kind,
+                    to: norm.to, cc: norm.cc, bcc: norm.bcc, from: norm.from,
+                    subject: norm.subject, text: norm.text, html: norm.html,
+                    templateId: norm.templateId, dynamicTemplateData: norm.dynamicTemplateData,
+                    categories: norm.categories, customArgs: norm.customArgs,
+                    attachmentsMeta: norm.attachmentsMeta,
+                    statusCode, durMs: Date.now() - t0, headers: headers ?? {},
+                },
+                t: alignedNow(),
+            }]
+        });
+    }
+
+    function normalizeAddress(a: any): { email: string; name?: string } | null {
+        if (!a) return null;
+        if (typeof a === 'string') return { email: a };
+        if (typeof a === 'object' && a.email) return { email: String(a.email), name: a.name ? String(a.name) : undefined };
+        return null;
+    }
+    function normalizeAddressList(v: any) {
+        if (!v) return undefined;
+        const arr = Array.isArray(v) ? v : [v];
+        const out = arr.map(normalizeAddress).filter(Boolean) as Array<{ email: string; name?: string }>;
+        return out.length ? out : undefined;
+    }
+    function normalizeSendgridMessage(msg: any) {
+        const base = {
+            from: normalizeAddress(msg?.from) ?? undefined,
+            to: normalizeAddressList(msg?.to),
+            cc: normalizeAddressList(msg?.cc),
+            bcc: normalizeAddressList(msg?.bcc),
+            subject: msg?.subject ? String(msg.subject) : undefined,
+            text: typeof msg?.text === 'string' ? msg.text : undefined,
+            html: typeof msg?.html === 'string' ? msg.html : undefined,
+            templateId: msg?.templateId ? String(msg.templateId) : undefined,
+            dynamicTemplateData: msg?.dynamic_template_data ?? msg?.dynamicTemplateData ?? undefined,
+            categories: Array.isArray(msg?.categories) ? msg.categories.map(String) : undefined,
+            customArgs: msg?.customArgs ?? msg?.custom_args ?? undefined,
+            attachmentsMeta: Array.isArray(msg?.attachments)
+                ? msg.attachments.map((a: any) => ({
+                    filename: a?.filename ? String(a.filename) : undefined,
+                    type: a?.type ? String(a.type) : undefined,
+                    size: a?.content ? byteLen(a.content) : undefined,
+                }))
+                : undefined,
+        };
+        const p0 = Array.isArray(msg?.personalizations) ? msg.personalizations[0] : undefined;
+        if (p0) {
+            base.to = normalizeAddressList(p0.to) ?? base.to;
+            base.cc = normalizeAddressList(p0.cc) ?? base.cc;
+            base.bcc = normalizeAddressList(p0.bcc) ?? base.bcc;
+            if (!base.subject && p0.subject) base.subject = String(p0.subject);
+            if (!base.dynamicTemplateData && (p0 as any).dynamic_template_data) base.dynamicTemplateData = (p0 as any).dynamic_template_data;
+            if (!base.customArgs && (p0 as any).custom_args) base.customArgs = (p0 as any).custom_args;
+        }
+        return base;
+    }
+    function byteLen(content: any): number | undefined {
+        try {
+            if (typeof content === 'string') return Buffer.byteLength(content, 'utf8');
+            if (content && typeof content === 'object' && 'length' in content) return Number((content as any).length);
+        } catch {}
+        return undefined;
+    }
+}