@reprova/sdk 0.4.0 → 0.6.0

package/dist/cjs/sdk.js

@@ -0,0 +1,1231 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Reprova = void 0;
+exports.forwardAsyncErrors = forwardAsyncErrors;
+exports.replayErrorHandler = replayErrorHandler;
+exports.wrapResponse = wrapResponse;
+const node_http_1 = __importDefault(require("node:http"));
+const node_https_1 = __importDefault(require("node:https"));
+const node_fs_1 = require("node:fs");
+const httpFetch_js_1 = require("./httpFetch.js");
+const context_js_1 = require("./context.js");
+const registry_js_1 = require("./registry.js");
+const transport_js_1 = require("./transport.js");
+const stack_js_1 = require("./stack.js");
+const prisma_js_1 = require("./prisma.js");
+const legacyPrisma_js_1 = require("./legacyPrisma.js");
+const nest_js_1 = require("./nest.js");
+const nPlusOne_js_1 = require("./nPlusOne.js");
+const retryStorm_js_1 = require("./retryStorm.js");
+const invariantRules_js_1 = require("./invariantRules.js");
+const rulesPoller_js_1 = require("./rulesPoller.js");
+const idempotency_js_1 = require("./idempotency.js");
+const idempotencySettingsPoller_js_1 = require("./idempotencySettingsPoller.js");
+const invariantInference_js_1 = require("./invariantInference.js");
+const distributionDrift_js_1 = require("./distributionDrift.js");
+const distributionBaselinePoller_js_1 = require("./distributionBaselinePoller.js");
+const mongoose_js_1 = require("./mongoose.js");
+const mongoSchemaReporter_js_1 = require("./mongoSchemaReporter.js");
+// Missing/malformed snapshot degrades to "no seeded settings" — replay mode
+// still runs (context establishment, http_5xx/unhandled_exception capture
+// all work independent of this), just without drift/invariant/idempotency
+// detection firing, exactly like today. Never a hard failure.
+function loadReplaySettingsSnapshot() {
+    const path = process.env.REPROVA_REPLAY_SETTINGS_PATH;
+    if (!path)
+        return undefined;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+let instance = null;
+// Zero-code-change async error capture: Express 4 discards the promise an
+// async handler returns, so a rejection never reaches error middleware unless
+// the app hand-plumbs next(err). We patch the router's Layer dispatch (the
+// same semantics Express 5's router ships natively) so every handler's
+// returned promise gets a rejection-forwarder attached automatically.
+const kAsyncWrapped = Symbol('reprova.asyncWrapped');
+// Apps we've already probed (added even when probing no-ops, e.g. Express 5).
+const patchedApps = new WeakSet();
+// Layer prototypes already patched — one per physical express copy.
+const patchedLayerProtos = new WeakSet();
+// Best-effort auto-detection, no app code changes required: req.auth is the
+// express-oauth2-jwt-bearer / Auth0 convention; req.user is what Passport
+// and the overwhelming majority of hand-rolled Express JWT middleware
+// assigns instead (`req.user = decoded` right after verifying the token).
+// req.auth wins when both are present since it's the more specific,
+// auth-only convention — req.user sometimes carries a broader profile.
+// Apps using neither (a custom property, a non-Express framework) still
+// need the explicit setAuthClaims() escape hatch from context.ts.
+function detectAuthClaims(req, customExtractor) {
+    if (customExtractor) {
+        try {
+            const claims = customExtractor(req);
+            if (claims !== undefined)
+                return claims;
+        }
+        catch {
+            // A misbehaving adapter must never break request capture — fall
+            // through to the built-in convention below.
+        }
+    }
+    return req.auth ?? req.user;
+}
+// refreshRequestSnapshot re-reads body and auth claims from the live req at
+// capture time. The request middleware runs at the very front of the stack
+// (before body parsers and auth middleware), so its eager snapshot can miss
+// req.body/req.auth/req.user — by the time anything is captured, all three
+// are final. Mutating ctx.request in place keeps cohort snapshots consistent
+// too.
+function refreshRequestSnapshot(ctx, customExtractor) {
+    const req = ctx.rawRequest;
+    if (!req)
+        return;
+    if (req.body !== undefined) {
+        ctx.request.body = typeof req.body === 'string' ? req.body : JSON.stringify(req.body ?? '');
+    }
+    const claims = detectAuthClaims(req, customExtractor);
+    if (claims !== undefined && ctx.request.authClaims === undefined) {
+        ctx.request.authClaims = claims;
+    }
+}
+// Fallback for errorHandler(): the request's context, keyed by the raw
+// req/IncomingMessage object rather than AsyncLocalStorage. Needed because
+// ALS's active store can be lost partway through a middleware chain if a
+// middleware BEFORE the route handler resumes its continuation through a
+// promise/microtask chain not properly linked back to the async context ALS
+// was tracking — confirmed live against `celebrate` (a common Express/Joi
+// validation middleware): a route wrapped in celebrate(...) reaches its
+// actual handler with contextStorage.getStore() already undefined, even
+// though the SAME app's non-celebrate routes keep it intact throughout. The
+// req object itself has no such problem — it's the same single reference
+// for the whole request regardless of which continuation mechanism resumed
+// execution, so a direct lookup on it survives whatever broke ALS.
+const ctxByRequest = new WeakMap();
+// Universal HTTP instrumentation: wrap the 'request' event on node's own
+// http/https servers, so EVERY Node app — vanilla http.createServer, Koa,
+// Fastify, Express — runs its request handling inside a Reprova context.
+// Framework middleware becomes an enrichment, not a requirement. Installed
+// once; per-request behavior is gated on the CURRENT init'd instance, so
+// re-inits (and disabled mode) behave correctly without re-patching.
+let httpInstrumented = false;
+function instrumentHttpServers() {
+    if (httpInstrumented)
+        return;
+    httpInstrumented = true;
+    // https.Server does NOT inherit from http.Server (it extends tls.Server),
+    // and neither defines its own emit — both use EventEmitter's. Patch both
+    // prototypes with an own emit that delegates upward.
+    for (const proto of [node_http_1.default.Server.prototype, node_https_1.default.Server.prototype]) {
+        const originalEmit = proto.emit;
+        proto.emit = function (event, ...args) {
+            const sdk = instance;
+            if (event !== 'request' || !sdk || (sdk.disabled && !sdk.replayMode)) {
+                return originalEmit.apply(this, [event, ...args]);
+            }
+            const req = args[0];
+            const res = args[1];
+            const ctx = contextFromIncoming(req);
+            (0, registry_js_1.registerContext)(ctx);
+            ctxByRequest.set(req, ctx);
+            res.on('finish', () => {
+                // Silent 5xx: the handler responded 5xx without throwing. Vanilla
+                // responses have no res.json to wrap, so the check runs at finish.
+                if (res.statusCode >= 500 && !ctx.captured) {
+                    context_js_1.contextStorage.run(ctx, () => sdk.captureHttp5xx(null, res.statusCode, ''));
+                }
+                (0, registry_js_1.completeContext)(ctx);
+            });
+            res.on('close', () => (0, registry_js_1.completeContext)(ctx));
+            try {
+                return context_js_1.contextStorage.run(ctx, () => originalEmit.apply(this, [event, ...args]));
+            }
+            catch (err) {
+                // A synchronous throw unwinds out of the ALS frame before the
+                // process-level handler could see the store — capture WITH context
+                // here, then rethrow to preserve Node's semantics. The process
+                // handler skips already-captured contexts.
+                if (err instanceof Error)
+                    sdk.capture('unhandled_exception', err, ctx);
+                throw err;
+            }
+        };
+    }
+}
+function contextFromIncoming(req) {
+    let path = req.url ?? '/';
+    try {
+        path = new URL(path, 'http://placeholder').pathname;
+    }
+    catch {
+        // keep raw url
+    }
+    const traceId = req.headers['traceparent'] ?? (0, stack_js_1.generateTraceId)();
+    // Write the resolved value back onto the raw request's own headers (even
+    // when it was just generated, not client-sent) so any framework that
+    // builds ITS OWN request representation from these headers — notably
+    // Next.js App Router, which constructs a fresh Fetch API Request rather
+    // than reusing this IncomingMessage — carries the same traceId forward.
+    // That's what lets findContextByTraceId recover THIS exact context later,
+    // even across a request-object boundary ALS itself doesn't survive.
+    req.headers['traceparent'] = traceId;
+    return {
+        traceId,
+        capturedAt: new Date(),
+        request: {
+            method: req.method ?? 'GET',
+            path,
+            headers: (0, stack_js_1.captureHeaders)(req.headers),
+            body: '', // refreshed at capture time from rawRequest if a framework parsed it
+        },
+        footprint: [],
+        outboundCalls: [],
+        businessInvariantHits: [],
+        writeCountDriftHits: [],
+        rawRequest: req,
+    };
+}
+// The error-middleware layer setupExpress mounted for each app, so the
+// request middleware can keep it at the end of the stack even when routes
+// are registered after setup (position independence).
+const setupErrorLayers = new WeakMap();
+// keepErrorHandlerLast repositions setupExpress's error layer when ROUTE
+// registrations have landed after it — but never past the app's own error
+// middleware (4-arg layers), which must stay downstream so it still receives
+// the error after we capture and next(err) it. Runs from the request
+// middleware, i.e. early in dispatch: moving a NOT-YET-VISITED layer within
+// the live stack array is safe — express iterates with a forward-only index
+// and re-reads stack.length each step, so unvisited layers shift one slot
+// and are still each visited exactly once.
+function keepErrorHandlerLast(app) {
+    const errLayer = setupErrorLayers.get(app);
+    if (!errLayer)
+        return;
+    const stack = app._router?.stack;
+    if (!stack || stack.length === 0)
+        return;
+    const i = stack.indexOf(errLayer);
+    if (i === -1)
+        return;
+    // Find the last NON-error layer (handler arity < 4) after ours — a route
+    // or middleware registered after setupExpress. If none, we're already
+    // positioned correctly (anything after us is user error middleware).
+    let lastNonError = -1;
+    for (let j = i + 1; j < stack.length; j++) {
+        const handle = stack[j].handle;
+        if (typeof handle === 'function' && handle.length < 4)
+            lastNonError = j;
+    }
+    if (lastNonError === -1)
+        return;
+    stack.splice(i, 1);
+    // Indices shifted down by one past i; insert right AFTER the late layer.
+    stack.splice(lastNonError, 0, errLayer);
+}
+// forwardAsyncErrors applies the rejection-forwarding patch to an app
+// explicitly. requestHandler() does this automatically on the first request,
+// so most apps never call it — it exists for the cases that middleware can't
+// reach: a sub-app running a different physical copy of express, or an app
+// that mounts routes needing Express-5 rejection semantics WITHOUT running
+// the SDK (e.g. the demo app under `repro run` replay, where no DSN is set).
+// Call it after routes are registered. Idempotent.
+function forwardAsyncErrors(app) {
+    patchLayerPrototype(app);
+}
+// Express error middleware that emits the structured error `repro run` needs to
+// compare a replayed failure against the originally captured one — the type,
+// message, and normalized stack (via the SAME parseStack used at capture, so
+// the two can never drift). Active ONLY under REPROVA_REPLAY=1, which the CLI
+// sets when it launches the app for replay; otherwise it forwards to the app's
+// own error handler (next(err)), so it's a transparent no-op in normal
+// operation. Register it BEFORE the app's own 500 responder.
+function replayErrorHandler() {
+    const replay = process.env.REPROVA_REPLAY === '1';
+    return (err, _req, res, next) => {
+        if (!replay)
+            return next(err);
+        res.status(500).json({
+            error: {
+                type: err.constructor?.name ?? err.name ?? 'Error',
+                message: err.message,
+                stack: (0, stack_js_1.parseStack)(err),
+            },
+        });
+    };
+}
+function patchLayerPrototype(app) {
+    if (patchedApps.has(app))
+        return;
+    patchedApps.add(app);
+    // Express 4 keeps the router at app._router; Express 5 renamed it (and its
+    // router forwards rejected promises natively), so failing any of these
+    // guards means there is nothing for us to do.
+    const router = app._router;
+    const firstLayer = router?.stack?.[0];
+    if (!firstLayer)
+        return;
+    const proto = Object.getPrototypeOf(firstLayer);
+    if (!proto || typeof proto.handle_request !== 'function')
+        return;
+    if (patchedLayerProtos.has(proto))
+        return;
+    patchedLayerProtos.add(proto);
+    const original = proto.handle_request;
+    proto.handle_request = function handle_request(req, res, next) {
+        const fn = this.handle;
+        // Wrap plain request handlers only (arity < 4 — express uses fn.length to
+        // recognize error middleware; the wrapper keeps arity 3 for the same
+        // reason). Wrapping is once per layer, marked with a symbol.
+        if (typeof fn === 'function' && fn.length < 4 && !(kAsyncWrapped in fn)) {
+            const inner = fn;
+            const wrapped = function (rq, rs, nx) {
+                const ret = inner(rq, rs, nx);
+                if (ret && typeof ret.then === 'function') {
+                    // Same coercion as Express 5's router: a falsy rejection reason
+                    // still has to travel the error chain as *something*.
+                    ret.then(undefined, (err) => nx(err || new Error('unhandled promise rejection in request handler')));
+                }
+                return ret;
+            };
+            Object.defineProperty(wrapped, kAsyncWrapped, { value: true });
+            this.handle = wrapped;
+        }
+        return original.call(this, req, res, next);
+    };
+}
+class Reprova {
+    opts;
+    transport;
+    rulesPoller;
+    idempotencySettingsPoller;
+    inferenceReporter;
+    distributionDriftReporter;
+    distributionBaselinePoller;
+    writeCountDriftReporter;
+    writeCountBaselinePoller;
+    // Unlike the other reporters above, there's nothing to point this at
+    // until an app actually calls instrumentMongoose(mongooseInstance) — apps
+    // that never do (every SQL-dialect app) pay/leak nothing.
+    mongoSchemaReporter;
+    instrumentedMongooseInstances = new WeakSet();
+    idempotencyKeyCache = new idempotency_js_1.HashMismatchCache(idempotency_js_1.DEFAULT_IDEMPOTENCY_SETTINGS.max_keys, idempotency_js_1.DEFAULT_IDEMPOTENCY_SETTINGS.ttl_ms);
+    duplicateReadCache = new idempotency_js_1.HashMismatchCache(idempotency_js_1.DEFAULT_IDEMPOTENCY_SETTINGS.max_keys, idempotency_js_1.DEFAULT_IDEMPOTENCY_SETTINGS.duplicate_read_window_ms);
+    release;
+    sdkVersion = '0.6.0';
+    disabled;
+    // True when running under the CLI's `repro run`/`repro test` replay
+    // (REPROVA_REPLAY=1). Independent of `disabled`: replay apps have no live
+    // DSN (disabled stays true — no network transport, no live polling ever),
+    // but still need detection/instrumentation to run against a locally
+    // seeded settings snapshot instead of doing nothing. See capture(),
+    // static init(), and requestHandler() for where this is checked.
+    replayMode;
+    migrationId = 'unknown';
+    authClaimsExtractor;
+    outboundOpts;
+    n1Threshold;
+    retryStormThreshold;
+    constructor(opts) {
+        this.opts = opts;
+        this.disabled = !opts.dsn;
+        this.replayMode = process.env.REPROVA_REPLAY === '1';
+        if (this.disabled) {
+            // Inert transport/pollers: constructed so internal wiring stays
+            // uniform, but never started — capture() never enqueues (outside
+            // replay mode), no rule ever evaluates true (getInvariantRules() stays
+            // empty), and idempotency checks stay off (getIdempotencySettings()
+            // stays at the disabled-safe default) UNLESS replay mode seeds them
+            // from a one-time snapshot below (still never .start()'d — no live
+            // polling from inside a replayed app either way).
+            this.transport = new transport_js_1.BatchTransport({ endpoint: 'http://disabled.invalid/v1/ingest', apiKey: '' });
+            this.rulesPoller = new rulesPoller_js_1.RulesPoller({ endpoint: 'http://disabled.invalid/v1/business-invariant-rules', apiKey: '' });
+            this.idempotencySettingsPoller = new idempotencySettingsPoller_js_1.IdempotencySettingsPoller({ endpoint: 'http://disabled.invalid/v1/settings/idempotency', apiKey: '' });
+            this.inferenceReporter = new invariantInference_js_1.InferenceReporter({ endpoint: 'http://disabled.invalid/v1/inferred-invariants/observe', apiKey: '' });
+            this.distributionDriftReporter = new distributionDrift_js_1.DistributionDriftReporter({ endpoint: 'http://disabled.invalid/v1/distribution-baselines/observe', apiKey: '' });
+            this.distributionBaselinePoller = new distributionBaselinePoller_js_1.DistributionBaselinePoller({ endpoint: 'http://disabled.invalid/v1/distribution-baselines', apiKey: '' });
+            this.writeCountDriftReporter = new distributionDrift_js_1.DistributionDriftReporter({ endpoint: 'http://disabled.invalid/v1/write-count-baselines/observe', apiKey: '' });
+            this.writeCountBaselinePoller = new distributionBaselinePoller_js_1.DistributionBaselinePoller({ endpoint: 'http://disabled.invalid/v1/write-count-baselines', apiKey: '' });
+            if (this.replayMode) {
+                const snapshot = loadReplaySettingsSnapshot();
+                if (snapshot?.rules)
+                    this.rulesPoller.seed(snapshot.rules);
+                if (snapshot?.distributionBaselines)
+                    this.distributionBaselinePoller.seed(snapshot.distributionBaselines);
+                if (snapshot?.writeCountBaselines)
+                    this.writeCountBaselinePoller.seed(snapshot.writeCountBaselines);
+                if (snapshot?.idempotencySettings)
+                    this.idempotencySettingsPoller.seed(snapshot.idempotencySettings);
+            }
+        }
+        else {
+            const url = new URL(opts.dsn);
+            const apiKey = url.pathname.slice(1); // strip leading slash
+            const endpoint = `${url.protocol}//${url.host}/v1/ingest`;
+            this.transport = new transport_js_1.BatchTransport({ endpoint, apiKey });
+            this.transport.start();
+            this.rulesPoller = new rulesPoller_js_1.RulesPoller({
+                endpoint: `${url.protocol}//${url.host}/v1/business-invariant-rules`,
+                apiKey,
+                intervalMs: opts.rulesRefreshIntervalMs,
+            });
+            this.rulesPoller.start();
+            this.idempotencySettingsPoller = new idempotencySettingsPoller_js_1.IdempotencySettingsPoller({
+                endpoint: `${url.protocol}//${url.host}/v1/settings/idempotency`,
+                apiKey,
+                intervalMs: opts.rulesRefreshIntervalMs,
+            });
+            this.idempotencySettingsPoller.start();
+            this.inferenceReporter = new invariantInference_js_1.InferenceReporter({
+                endpoint: `${url.protocol}//${url.host}/v1/inferred-invariants/observe`,
+                apiKey,
+            });
+            this.inferenceReporter.start();
+            this.distributionDriftReporter = new distributionDrift_js_1.DistributionDriftReporter({
+                endpoint: `${url.protocol}//${url.host}/v1/distribution-baselines/observe`,
+                apiKey,
+            });
+            this.distributionDriftReporter.start();
+            this.distributionBaselinePoller = new distributionBaselinePoller_js_1.DistributionBaselinePoller({
+                endpoint: `${url.protocol}//${url.host}/v1/distribution-baselines`,
+                apiKey,
+                intervalMs: opts.rulesRefreshIntervalMs,
+            });
+            this.distributionBaselinePoller.start();
+            this.writeCountDriftReporter = new distributionDrift_js_1.DistributionDriftReporter({
+                endpoint: `${url.protocol}//${url.host}/v1/write-count-baselines/observe`,
+                apiKey,
+            });
+            this.writeCountDriftReporter.start();
+            this.writeCountBaselinePoller = new distributionBaselinePoller_js_1.DistributionBaselinePoller({
+                endpoint: `${url.protocol}//${url.host}/v1/write-count-baselines`,
+                apiKey,
+                intervalMs: opts.rulesRefreshIntervalMs,
+            });
+            this.writeCountBaselinePoller.start();
+        }
+        this.release = opts.release;
+        this.outboundOpts = opts.recordOutbound;
+        this.n1Threshold = opts.n1Threshold ?? 5;
+        this.retryStormThreshold = opts.retryStormThreshold ?? 3;
+        // Opts into `await using sdk = Reprova.init(...)` (TC39 explicit
+        // resource management) on runtimes that have it, WITHOUT declaring a
+        // [Symbol.asyncDispose] class member — that syntax requires the
+        // computed key to be a `unique symbol` type, which in turn requires
+        // every CONSUMER's own tsconfig to include the esnext.disposable lib
+        // just to type-check a feature they may never use (most projects'
+        // `lib` arrays don't include it). Assigning it dynamically here is a
+        // plain runtime property write, invisible to the type checker
+        // entirely, so it can't break anyone's build regardless of their
+        // `lib` setting — identical behavior for anyone actually using `await
+        // using`, zero effect on everyone else.
+        const asyncDisposeSymbol = Symbol.asyncDispose;
+        if (asyncDisposeSymbol) {
+            this[asyncDisposeSymbol] = () => this.disposeInternal();
+        }
+    }
+    // Live-cached rules for the tenant, refreshed on rulesRefreshIntervalMs —
+    // read by the Prisma extension on every query, never re-fetched per-query.
+    getInvariantRules() {
+        return this.rulesPoller.getEnabledRules();
+    }
+    static init(opts) {
+        instance = new Reprova(opts);
+        // replayMode runs this block too even though disabled stays true — a
+        // replayed app still needs context establishment (so detectors have
+        // something to attach to) and instrumentation, just with no live
+        // transport/polling underneath it.
+        if (!instance.disabled || instance.replayMode) {
+            instance.patchOutbound();
+            if (opts.instrumentHttp !== false)
+                instrumentHttpServers();
+            if (opts.processHandlers !== false)
+                instance.attachProcessHandlers();
+        }
+        return instance;
+    }
+    static getInstance() { return instance; }
+    setMigrationId(id) { this.migrationId = id; }
+    // Generic per-framework extension point — see frameworkAdapter.ts for why
+    // this is two seams (auth detection, migration_id) rather than a bigger
+    // plugin system. resolveMigrationId is awaited once, at registration time;
+    // call registerFrameworkAdapter again (or setMigrationId directly) if it
+    // can change during the process's lifetime.
+    registerFrameworkAdapter(adapter) {
+        if (adapter.extractAuthClaims)
+            this.authClaimsExtractor = adapter.extractAuthClaims;
+        if (adapter.resolveMigrationId) {
+            adapter
+                .resolveMigrationId()
+                .then((id) => this.setMigrationId(id))
+                .catch(() => {
+                // Never let a broken migration-id resolver affect anything else —
+                // migrationId simply stays whatever it already was ('unknown' by
+                // default).
+            });
+        }
+    }
+    // One-call Prisma integration. Splices the footprint-recording extension
+    // onto an existing PrismaClient (in place, preserving its identity) and
+    // best-effort reads the latest applied migration into migration_id.
+    //
+    // Typed structurally so the SDK never has to import '@prisma/client' —
+    // Prisma stays an optional peer. No-op when the SDK is disabled (no DSN /
+    // replay), like recordFootprint, so callers need no `if (dsn)` guard.
+    //
+    // Mutates `client` in place via Object.assign($extends(...)) because
+    // $extends returns a NEW client and the shared singleton must keep
+    // recording. Await it so migration_id is set before the first request.
+    async instrumentPrisma(client, opts) {
+        // Found live while proving the replay-mode detector fix end to end: this
+        // gate originally matched every other disabled-mode no-op, but replay
+        // mode needs the Prisma extension actually installed — that's the ONLY
+        // thing that runs applyInvariantRules()/observeWriteCountDrift() at all.
+        // Nothing else in this method touches opts.dsn or the network, so
+        // widening the gate is safe.
+        if (this.disabled && !this.replayMode)
+            return;
+        const c = client;
+        // 1. Footprint capture. Two paths, same recording logic underneath
+        //    (recordPrismaOperation, shared by both): $extends (Prisma's
+        //    Client Extensions API, 4.16+) is the modern, official hook — extend,
+        //    then copy the extended client's behavior back onto the original so
+        //    every importer of the singleton records. Older clients have no
+        //    $extends (and no $use, its deprecated predecessor) at all —
+        //    confirmed live against a real @prisma/client@2.0.0-beta.4 — so for
+        //    those, legacyPrisma.ts monkey-patches each model delegate's own CRUD
+        //    methods directly instead, the same shape this SDK already uses for
+        //    TypeORM's QueryRunner and Mongoose's pre-compiled models.
+        if (typeof c.$extends === 'function') {
+            const ext = (0, prisma_js_1.createPrismaExtension)(opts?.dmmf, () => this.getInvariantRules(), 
+            // Suspended: invariant inference ("Suggested invariants") is paused —
+            // pass undefined instead of this.inferenceReporter so
+            // observeInferredInvariants never runs. Not removed: the reporter,
+            // the observation logic, and the control-plane endpoints are all
+            // still intact; pass this.inferenceReporter here again to re-enable.
+            undefined, this.writeCountDriftReporter, this.writeCountBaselinePoller);
+            Object.assign(c, c.$extends(ext));
+        }
+        else {
+            (0, legacyPrisma_js_1.instrumentLegacyPrismaClient)(client, {
+                dmmf: opts?.dmmf,
+                getRules: () => this.getInvariantRules(),
+                inferenceReporter: undefined, // suspended, same as the modern path above
+                writeCountDriftReporter: this.writeCountDriftReporter,
+                writeCountBaselinePoller: this.writeCountBaselinePoller,
+            });
+        }
+        // 2. migration_id: best-effort. Absent table (migrations not run) or any
+        //    query error leaves it at the 'unknown' default — never fatal at boot.
+        // Three tries, in order: modern `prisma migrate`'s `_prisma_migrations`
+        // (Postgres/MySQL dialect, then SQL Server's TOP-instead-of-LIMIT
+        // dialect — the SDK deliberately has no notion of "which dialect" since
+        // it never imports @prisma/client), then the OLD experimental Prisma
+        // Migrate's `_Migration` table (singular, capitalized — confirmed live
+        // against a real @prisma/client@2.0.0-beta.4 project: that era tracked
+        // migrations in `_Migration(name, status, finished_at)`, not
+        // `_prisma_migrations`, and only reached "success" rows count). Also
+        // tries `client.raw` (that same ancient client's pre-$queryRaw tagged-
+        // template method — confirmed live to behave identically for a SELECT)
+        // when `$queryRaw` isn't there at all.
+        if (opts?.readMigrationId !== false) {
+            const rawQuery = c.$queryRaw ?? c.raw;
+            if (rawQuery) {
+                let rows = [];
+                try {
+                    rows = await rawQuery.bind(c) `
+            SELECT migration_name FROM _prisma_migrations ORDER BY finished_at DESC LIMIT 1
+          `;
+                }
+                catch {
+                    try {
+                        rows = await rawQuery.bind(c) `
+              SELECT TOP 1 migration_name FROM _prisma_migrations ORDER BY finished_at DESC
+            `;
+                    }
+                    catch {
+                        try {
+                            const legacyRows = await rawQuery.bind(c) `
+                SELECT name FROM _Migration WHERE status = 'MigrationSuccess' ORDER BY finished_at DESC LIMIT 1
+              `;
+                            rows = legacyRows.map((r) => ({ migration_name: r.name }));
+                        }
+                        catch {
+                            // migration_id stays 'unknown'
+                        }
+                    }
+                }
+                if (rows[0]?.migration_name) {
+                    this.setMigrationId(rows[0].migration_name);
+                }
+            }
+        }
+    }
+    // One-call Mongoose integration: installs the footprint plugin (unless
+    // this exact mongoose instance already has it — repeat calls are harmless)
+    // and starts a MongoSchemaReporter pointed at it, so reference edges
+    // (ref: declarations across every compiled model) get reported to the
+    // control plane without the app doing any manual config. No-op when the
+    // SDK is disabled, like instrumentPrisma/recordFootprint.
+    instrumentMongoose(mongooseInstance) {
+        // Footprint capture (this half) needs to run in replay mode too — it's
+        // what feeds the adapter-generic detectors (n_plus_one_query,
+        // retry_storm) that don't depend on a live DSN at all. The schema
+        // reporter below genuinely needs one (it POSTs discovered reference
+        // edges to a live control plane), so THAT half stays disabled-only,
+        // replay mode included — there's no dsn to build its endpoint from.
+        if (this.disabled && !this.replayMode)
+            return;
+        if (!this.instrumentedMongooseInstances.has(mongooseInstance)) {
+            this.instrumentedMongooseInstances.add(mongooseInstance);
+            mongooseInstance.plugin(mongoose_js_1.reprovaMongoosePlugin);
+        }
+        // Covers models compiled BEFORE this call — mongoose.plugin() above
+        // only reaches schemas compiled after it, so an app whose own bootstrap
+        // already compiled a model earlier (or that simply calls
+        // instrumentMongoose() late) would otherwise capture nothing for it.
+        (0, mongoose_js_1.instrumentAlreadyCompiledModels)(mongooseInstance);
+        if (this.disabled)
+            return; // replay mode, no live dsn — nothing to report edges to
+        this.mongoSchemaReporter?.stop();
+        const url = new URL(this.opts.dsn);
+        const apiKey = url.pathname.slice(1);
+        this.mongoSchemaReporter = new mongoSchemaReporter_js_1.MongoSchemaReporter({
+            endpoint: `${url.protocol}//${url.host}/v1/mongo-schema/observe`,
+            apiKey,
+            mongooseInstance,
+        });
+        this.mongoSchemaReporter.start();
+    }
+    // Escape hatch for apps using the raw MongoDB driver (no Mongoose, hence
+    // no schema registry to auto-discover ref: edges from). Mirrors
+    // registerFrameworkAdapter's philosophy — a seam, not a plugin system:
+    // supply the same {from_collection, from_field, to_collection, array}
+    // shape by hand instead of it being walked from schema.paths. Feeds the
+    // same reporting path a Mongoose app's auto-discovery would, just without
+    // the "model" indirection (raw-driver apps only ever deal in collection
+    // names, so edges here are already fully resolved — no to_model lookup
+    // needed control-plane-side).
+    registerReferenceEdges(edges) {
+        if (this.disabled)
+            return;
+        const url = new URL(this.opts.dsn);
+        const apiKey = url.pathname.slice(1);
+        const endpoint = `${url.protocol}//${url.host}/v1/mongo-schema/observe`;
+        // A raw-driver edge already names its target by collection, not by a
+        // Mongoose model — reusing each target collection as its own "model"
+        // name still resolves correctly, because RecordMongoSchema resolves
+        // ToModel against this SAME report's Models list, and a self-
+        // referential entry (model name == collection name) makes every edge
+        // resolve to itself with zero extra server-side logic.
+        const collections = new Set(edges.map((e) => e.toCollection));
+        const models = [...collections].map((collection) => ({ model: collection, collection }));
+        const wireEdges = edges.map((e) => ({ from_collection: e.fromCollection, from_field: e.fromField, to_model: e.toCollection, array: e.array }));
+        void (0, httpFetch_js_1.httpFetch)(endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-Reprova-Key': apiKey },
+            body: JSON.stringify({ models, edges: wireEdges }),
+        }).catch(() => {
+            // Best-effort, same as every other reporter — never break the host app.
+        });
+    }
+    // One-call Express integration (Sentry-style): mounts the request context
+    // middleware (repositioned to run before everything, wherever setup is
+    // called), the error-capture middleware (kept last even if routes are
+    // registered later), the http_5xx response hook, and async rejection
+    // forwarding. Equivalent to the manual requestHandler/errorHandler/
+    // wrapResponse wiring — same capture payloads, one line.
+    // ExpressAppLike (see its own doc comment above) rather than express's
+    // own Application/Express type — either real type satisfies this
+    // trivially, regardless of which @types/express version produced it.
+    setupExpress(app) {
+        app.use(this.requestHandler());
+        const router = app._router;
+        const stack = router?.stack;
+        if (stack && stack.length > 0) {
+            // Move the just-pushed request layer to sit right after express's
+            // leading built-ins (query/expressInit), so it runs first even when
+            // setupExpress is called after the routes.
+            const reqLayer = stack[stack.length - 1];
+            let insertAt = 0;
+            while (insertAt < stack.length - 1) {
+                const name = stack[insertAt].name;
+                if (name === 'query' || name === 'expressInit') {
+                    insertAt++;
+                }
+                else {
+                    break;
+                }
+            }
+            stack.splice(stack.length - 1, 1);
+            stack.splice(insertAt, 0, reqLayer);
+        }
+        app.use(this.errorHandler());
+        if (stack && stack.length > 0) {
+            setupErrorLayers.set(app, stack[stack.length - 1]);
+        }
+    }
+    // Express middleware: opens per-request context. Also installs the async
+    // rejection forwarder on first request (see patchLayerPrototype) so plain
+    // `async (req, res) => ...` handlers need no wrapper and no next(err).
+    requestHandler() {
+        return (req, res, next) => {
+            if (req.app) {
+                patchLayerPrototype(req.app);
+                keepErrorHandlerLast(req.app);
+            }
+            // http_5xx-without-throw hook rides along automatically.
+            if (!this.disabled || this.replayMode)
+                wrapResponse(res, this);
+            // With HTTP-server instrumentation active (init default), a context
+            // for this very request already exists — don't shadow it with a
+            // second one; every capture path reads the same store either way.
+            const existing = context_js_1.contextStorage.getStore();
+            if (existing && existing.rawRequest === req) {
+                next();
+                return;
+            }
+            const traceId = req.headers['traceparent'] ?? (0, stack_js_1.generateTraceId)();
+            const ctx = {
+                traceId,
+                capturedAt: new Date(),
+                request: {
+                    method: req.method,
+                    path: req.path,
+                    headers: (0, stack_js_1.captureHeaders)(req.headers),
+                    body: typeof req.body === 'string' ? req.body : JSON.stringify(req.body ?? ''),
+                    authClaims: detectAuthClaims(req, this.authClaimsExtractor),
+                },
+                footprint: [],
+                outboundCalls: [],
+                businessInvariantHits: [],
+                writeCountDriftHits: [],
+                rawRequest: req,
+            };
+            // Track this context so a concurrent request's capture can see it
+            // (and, briefly after completion, that it recently overlapped).
+            (0, registry_js_1.registerContext)(ctx);
+            ctxByRequest.set(req, ctx);
+            const done = () => (0, registry_js_1.completeContext)(ctx);
+            res.on('finish', done);
+            res.on('close', done);
+            context_js_1.contextStorage.run(ctx, next);
+        };
+    }
+    // Express error middleware: captures unhandled_exception. Falls back to
+    // ctxByRequest when the AsyncLocalStorage store has gone missing by the
+    // time an error reaches here (see ctxByRequest's own comment) — a route
+    // wrapped in some validation middlewares would otherwise capture nothing
+    // but a switch to the generic http_5xx fallback: a real error with a real
+    // stack, silently downgraded to a synthetic "HTTP 500 response".
+    errorHandler() {
+        return (err, req, res, next) => {
+            const ctx = context_js_1.contextStorage.getStore() ?? ctxByRequest.get(req);
+            if (ctx && err instanceof Error) {
+                this.capture('unhandled_exception', err, ctx);
+            }
+            next(err);
+        };
+    }
+    // Manual capture.
+    captureError(err, opts) {
+        const ctx = context_js_1.contextStorage.getStore();
+        this.capture(opts?.trigger ?? 'manual_capture', err, ctx);
+    }
+    // NestJS global exception filter: hands Nest-caught exceptions to the
+    // capture pipeline with the ORIGINAL stack (Nest's exception layer
+    // otherwise converts them to 500s before Express error middleware ever
+    // sees them, leaving only the silent-5xx capture), honors the
+    // REPROVA_REPLAY contract for exact replay verdicts, and responds the way
+    // Nest's own default filter would. Usage:
+    //   app.useGlobalFilters(sdk.nestExceptionFilter());
+    nestExceptionFilter() {
+        return (0, nest_js_1.createNestExceptionFilter)({
+            capture: (err) => {
+                const ctx = context_js_1.contextStorage.getStore();
+                if (!ctx?.captured)
+                    this.capture('unhandled_exception', err, ctx);
+            },
+        });
+    }
+    // Recovers request context across Nest's own pipe resolution — see
+    // createNestContextInterceptor's doc comment in nest.ts for the full story
+    // (found and confirmed against a real NestJS 7 app: any route with a
+    // @Body() DTO reached its service/repository code with
+    // contextStorage.getStore() already empty). resolveContext reuses the SAME
+    // req-keyed side channel recordFootprint() already falls back to — the
+    // interceptor is just the one place in a Nest app that reliably has the
+    // raw request AND runs early enough to re-anchor context before any pipe
+    // or controller code executes, which no ORM adapter can do on its own
+    // (none of them have the request object in scope).
+    nestContextInterceptor() {
+        return (0, nest_js_1.createNestContextInterceptor)({
+            resolveContext: (req) => (req !== undefined ? ctxByRequest.get(req) : undefined) ?? context_js_1.contextStorage.getStore(),
+            runInContext: (ctx, fn) => context_js_1.contextStorage.run(ctx, fn),
+        });
+    }
+    // One-call NestJS setup, the setupExpress of the Nest world: registers the
+    // exception filter and context-recovery interceptor, and (when given a
+    // Prisma client) wires automatic data footprints + migration_id in the
+    // same breath. The whole integration:
+    //   const sdk = Reprova.init({ dsn, release });
+    //   const app = await NestFactory.create(AppModule);
+    //   await sdk.setupNest(app, { prisma: app.get(PrismaService), dmmf: Prisma.dmmf });
+    // Other ORMs stay their usual one line (installTypeOrmSubscriber(dataSource),
+    // installKnexHooks(knex), ...) — they aren't Reprova-instance methods, but
+    // the interceptor registered here benefits ALL of them equally: it fixes
+    // context before any ORM code runs, not per-adapter.
+    //
+    // The interceptor is registered here, first, deliberately — Nest merges
+    // multiple useGlobalInterceptors() calls in registration order, and
+    // registering ours before any app-defined interceptor makes it the
+    // outermost wrapper, covering the whole remaining chain (every other
+    // interceptor, every pipe, the controller itself).
+    async setupNest(app, opts) {
+        app.useGlobalFilters(this.nestExceptionFilter());
+        app.useGlobalInterceptors(this.nestContextInterceptor());
+        if (opts?.prisma) {
+            await this.instrumentPrisma(opts.prisma, { dmmf: opts.dmmf });
+        }
+    }
+    // Called by response hook for http_5xx (no thrown error).
+    captureHttp5xx(err, statusCode, responseBody) {
+        const ctx = context_js_1.contextStorage.getStore();
+        if (!ctx)
+            return;
+        // Skip: an error was already thrown and captured for this request (e.g. via
+        // errorHandler/captureError) — this 5xx response is just that error surfacing,
+        // not an independent silent failure. Reporting both would double-count the issue.
+        if (ctx.captured)
+            return;
+        const syntheticErr = err ?? new Error(`HTTP ${statusCode} response`);
+        this.capture('http_5xx', syntheticErr, ctx, {
+            response: { status: statusCode, body: responseBody.slice(0, 16 * 1024) },
+        });
+    }
+    // Called by response hook on every response, success or failure. Unlike
+    // captureHttp5xx this isn't gated on status code — an N+1 request usually
+    // returns 200 while doing far more DB round-trips than it should, which is
+    // exactly the case with no exception and no 5xx to hook into otherwise.
+    // Skips (like captureHttp5xx) once this request already has a capture, so
+    // a request that both throws AND has an N+1 pattern doesn't get reported
+    // twice — the thrown error takes priority. One capture PER offending
+    // (model, op) pair, not one aggregating all of them: that keeps each
+    // pattern's fingerprint stable and independently trackable as its own
+    // issue, rather than lumping unrelated repeated-query patterns together
+    // or producing a message whose composition varies request to request.
+    captureNPlusOneIfAny() {
+        if (this.n1Threshold <= 0)
+            return;
+        const ctx = context_js_1.contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        for (const finding of (0, nPlusOne_js_1.detectNPlusOne)(ctx.footprint, this.n1Threshold)) {
+            this.capture('n_plus_one_query', new nPlusOne_js_1.PotentialNPlusOneQuery(finding), ctx);
+        }
+    }
+    // Same shape and same reasoning as captureNPlusOneIfAny: not gated on
+    // status code (the OUTER request can easily still return 200 — an
+    // upstream dependency getting hammered by retries doesn't necessarily
+    // fail the request that triggered them), skipped once this request
+    // already has a capture, one capture per offending (host, method, path)
+    // group rather than one aggregating every group found.
+    captureRetryStormIfAny() {
+        if (this.retryStormThreshold <= 0)
+            return;
+        const ctx = context_js_1.contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        for (const finding of (0, retryStorm_js_1.detectRetryStorm)(ctx.outboundCalls, this.retryStormThreshold)) {
+            this.capture('retry_storm', new retryStorm_js_1.PotentialRetryStorm(finding), ctx);
+        }
+    }
+    // Drains business-invariant violations the Prisma extension recorded
+    // during this request (prisma.ts — the only place the actual row values a
+    // rule needs are available). One capture per violated rule, same
+    // one-per-pattern reasoning as captureNPlusOneIfAny; errorType is set
+    // explicitly per rule so different rules fingerprint into different
+    // issues despite sharing one Error class.
+    captureBusinessInvariantViolationsIfAny() {
+        const ctx = context_js_1.contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        for (const hit of ctx.businessInvariantHits) {
+            this.capture('business_invariant', new invariantRules_js_1.BusinessInvariantViolation(hit.message), ctx, {
+                errorType: `InvariantViolation:${hit.ruleId}`,
+            });
+        }
+    }
+    // Drains write-count-drift hits the Prisma extension recorded during this
+    // request (prisma.ts's observeWriteCountDrift — the only place a bulk
+    // write's affected-row count is available). Same one-per-hit shape as
+    // captureBusinessInvariantViolationsIfAny; errorType is per (route,
+    // operation, model) so distinct bulk-write anomalies fingerprint into
+    // distinct issues despite sharing one Error class.
+    captureWriteCountDriftIfAny() {
+        const ctx = context_js_1.contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        for (const hit of ctx.writeCountDriftHits) {
+            this.capture('write_count_drift', new distributionDrift_js_1.WriteCountDrift(`${hit.route} ${hit.operation} on ${hit.model} affected an unusual number of rows`), ctx, { errorType: `WriteCountDrift:${hit.route}:${hit.operation}:${hit.model}` });
+        }
+    }
+    // Unlike the other capture*IfAny methods, this one needs the actual
+    // response body — not something already sitting on ctx — so it's called
+    // directly from wrapResponse's res.json override with body in hand,
+    // rather than generically after the fact. Checks the idempotency-key
+    // detector first; if that already captured (one per request, same as
+    // every other trigger), the duplicate-read detector is skipped rather
+    // than risk a second capture for the same response.
+    checkIdempotencyIfAny(body) {
+        const ctx = context_js_1.contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        const settings = this.idempotencySettingsPoller.getSettings();
+        const req = ctx.rawRequest;
+        const routePattern = req?.route?.path;
+        const method = ctx.request.method;
+        if (settings.key_check_enabled) {
+            const key = (0, idempotency_js_1.findIdempotencyKey)(ctx.request.headers, settings.header_names);
+            if (key) {
+                this.idempotencyKeyCache.configure(settings.max_keys, settings.ttl_ms);
+                const hash = (0, idempotency_js_1.hashResponseBody)(body);
+                const signature = `${method} ${routePattern ?? ''} ${key}`;
+                if (this.idempotencyKeyCache.checkAndRecord(signature, hash)) {
+                    this.capture('idempotency_key_mismatch', new idempotency_js_1.IdempotencyKeyMismatch(`Idempotent ${method} request${routePattern ? ` to ${routePattern}` : ''} returned a different response for the same idempotency key`), ctx, { errorType: 'IdempotencyKeyMismatch' });
+                    return;
+                }
+            }
+        }
+        if (settings.duplicate_read_enabled && method === 'GET') {
+            const identity = (0, idempotency_js_1.extractIdentity)(ctx.request.authClaims);
+            if (identity) {
+                const rawUrl = req?.originalUrl ?? req?.url ?? '';
+                const query = rawUrl.split('?')[1] ?? '';
+                this.duplicateReadCache.configure(settings.max_keys, settings.duplicate_read_window_ms);
+                const hash = (0, idempotency_js_1.hashResponseBody)(body);
+                const signature = `${routePattern ?? ctx.request.path} ${query} identity:${identity}`;
+                if (this.duplicateReadCache.checkAndRecord(signature, hash)) {
+                    this.capture('duplicate_read_mismatch', new idempotency_js_1.DuplicateReadMismatch(`Duplicate GET${routePattern ? ` to ${routePattern}` : ''} within ${settings.duplicate_read_window_ms}ms returned a different result`), ctx, { errorType: 'DuplicateReadMismatch' });
+                }
+            }
+        }
+    }
+    // Numeric-only v1 slice (see distributionDrift.ts's module doc). Always
+    // records every observed value into the local reporter regardless of
+    // whether drift detection itself is enabled — the baseline needs to keep
+    // accumulating so it's actually populated by the time an admin flips the
+    // dashboard toggle on, rather than starting from zero at that moment.
+    // Only the CAPTURE side is gated on the polled enabled flag.
+    checkDistributionDriftIfAny(body) {
+        const ctx = context_js_1.contextStorage.getStore();
+        if (!ctx)
+            return;
+        const req = ctx.rawRequest;
+        const routePattern = req?.route?.path;
+        if (!routePattern)
+            return; // no stable key to group on — a resolved path would leak a real id into the key
+        const route = `${ctx.request.method} ${routePattern}`;
+        const fields = (0, distributionDrift_js_1.extractTopLevelNumericFields)(body);
+        if (Object.keys(fields).length === 0)
+            return;
+        for (const [field, value] of Object.entries(fields)) {
+            this.distributionDriftReporter.record(route, field, value);
+        }
+        if (!this.distributionBaselinePoller.isEnabled() || ctx.captured)
+            return;
+        for (const [field, value] of Object.entries(fields)) {
+            const baseline = this.distributionBaselinePoller.getBaseline(route, field);
+            if (baseline && (0, distributionDrift_js_1.isDrift)(value, baseline)) {
+                this.capture('value_distribution_drift', new distributionDrift_js_1.ValueDistributionDrift(`${route} field "${field}" is far outside its observed baseline range`), ctx, { errorType: `ValueDistributionDrift:${route}:${field}` });
+                return; // one capture max per response, same as every other *IfAny
+            }
+        }
+    }
+    capture(trigger, err, ctx, extra) {
+        if (this.disabled) {
+            // Replay mode: there's no live control plane to report to (the app is
+            // running against an anonymized disposable DB, not production), so
+            // instead of a network capture, stash the same {type, message} a real
+            // occurrence would have stored — extra?.errorType ?? the class name,
+            // exactly matching the payload's own error.type resolution below —
+            // onto the context. wrapResponse surfaces it via a response header for
+            // the CLI's verdict comparison to read instead of the transport.
+            // First-wins, same one-capture-per-response contract every other
+            // trigger already follows.
+            if (this.replayMode && ctx && !ctx.captured) {
+                ctx.captured = true;
+                ctx.replayDetection = {
+                    trigger,
+                    type: extra?.errorType ?? (err.constructor?.name ?? err.name ?? 'Error'),
+                    message: err.message,
+                };
+            }
+            return;
+        }
+        if (ctx) {
+            ctx.captured = true;
+            refreshRequestSnapshot(ctx, this.authClaimsExtractor);
+        }
+        const payload = {
+            trigger: trigger,
+            trace_id: ctx?.traceId ?? (0, stack_js_1.generateTraceId)(),
+            timestamp: (ctx?.capturedAt ?? new Date()).toISOString(),
+            release: this.release,
+            migration_id: this.migrationId,
+            sdk_version: this.sdkVersion,
+            error: {
+                // extra.errorType overrides the class-name default — needed for
+                // business-invariant violations, where many different dashboard
+                // rules share one Error class (BusinessInvariantViolation) and must
+                // still fingerprint into separate issues (see invariantRules.ts).
+                type: extra?.errorType ?? (err.constructor?.name ?? err.name ?? 'Error'),
+                message: err.message,
+                stack: (0, stack_js_1.parseStack)(err),
+            },
+            request: ctx
+                ? {
+                    method: ctx.request.method,
+                    path: ctx.request.path,
+                    headers: (0, stack_js_1.stripHeaders)(ctx.request.headers),
+                    body: ctx.request.body,
+                    auth_claims: ctx.request.authClaims,
+                }
+                : { method: '', path: '', headers: {}, body: '' },
+            response: extra?.response,
+            data_footprint: { queries: ctx?.footprint ?? [] },
+            outbound_calls: ctx?.outboundCalls ?? [],
+        };
+        // Concurrency cohort: what else was in flight (or just finished) when
+        // this error happened — the raw material for race-condition replay.
+        // The key is omitted entirely when the request was alone.
+        const cohort = ctx ? (0, registry_js_1.snapshotCohort)(ctx) : [];
+        if (cohort.length > 0) {
+            payload.concurrent_requests = cohort;
+        }
+        this.transport.enqueue(payload);
+    }
+    // Attach process-level handlers. AsyncLocalStorage context survives into
+    // both handlers for errors from async continuations (verified on Node 22),
+    // so even these captures carry request context when one exists. Contexts
+    // already captured (e.g. by the http emit wrapper's sync-throw catch) are
+    // skipped to avoid double-reporting.
+    attachProcessHandlers() {
+        process.on('uncaughtException', (err) => {
+            const ctx = context_js_1.contextStorage.getStore();
+            if (!ctx?.captured)
+                this.capture('unhandled_exception', err, ctx);
+            // Allow flush before exit.
+            void this.transport.flush().finally(() => process.exit(1));
+        });
+        process.on('unhandledRejection', (reason) => {
+            const err = reason instanceof Error ? reason : new Error(String(reason));
+            const ctx = context_js_1.contextStorage.getStore();
+            if (!ctx?.captured)
+                this.capture('unhandled_exception', err, ctx);
+        });
+    }
+    // Run any operation — a queue consumer, a script step, anything without
+    // an HTTP request — inside a capture context: errors are captured (then
+    // rethrown, so the caller's error flow is unchanged), and footprints /
+    // outbound calls recorded inside land on the capture.
+    async runWithContext(info, fn) {
+        return this.runInContext('unhandled_exception', info, fn);
+    }
+    // Background-job wrapper: like runWithContext, but failures ingest with
+    // the job_failure trigger so they're distinguishable on the dashboard.
+    async runJob(name, fn) {
+        return this.runInContext('job_failure', { name }, fn);
+    }
+    async runInContext(trigger, info, fn) {
+        const ctx = {
+            traceId: (0, stack_js_1.generateTraceId)(),
+            capturedAt: new Date(),
+            request: {
+                method: info.method ?? 'JOB',
+                path: info.path ?? info.name ?? 'task',
+                headers: info.headers ?? {},
+                body: info.body ?? '',
+            },
+            footprint: [],
+            outboundCalls: [],
+            businessInvariantHits: [],
+            writeCountDriftHits: [],
+        };
+        (0, registry_js_1.registerContext)(ctx);
+        try {
+            return await context_js_1.contextStorage.run(ctx, () => fn());
+        }
+        catch (err) {
+            if (err instanceof Error)
+                this.capture(trigger, err, ctx);
+            throw err;
+        }
+        finally {
+            (0, registry_js_1.completeContext)(ctx);
+        }
+    }
+    // Record a data-footprint entry from ANY data layer (knex, raw SQL, an
+    // in-house DAO): one call per query site is what makes an error
+    // REPRODUCIBLE rather than just visible. `model` maps to a table via the
+    // tenant's naming strategy, exactly like a Prisma model name.
+    //
+    // Falls back to ctxByRequest when AsyncLocalStorage's active store is
+    // gone — the SAME condition errorHandler() already falls back for (see
+    // ctxByRequest's own doc comment: a validation middleware like celebrate
+    // resuming through its own internal .then(next).catch(next) chain, not
+    // through the continuation ALS was tracking). errorHandler() gets this
+    // fallback for free because Express always hands error middleware the
+    // raw req — a manual call site like this one doesn't have req unless the
+    // caller passes it, which is why rawRequest is a second, optional
+    // parameter here: pass the same value setAuthClaims-style code already
+    // has on hand (Express's req, or any framework's raw request object) and
+    // a footprint recorded from inside a request whose ALS context broke
+    // stops silently vanishing. Still a silent no-op only when BOTH lookups
+    // find nothing — never throws, same as every other capture path.
+    recordFootprint(query, rawRequest) {
+        const ctx = context_js_1.contextStorage.getStore() ?? (rawRequest !== undefined ? ctxByRequest.get(rawRequest) : undefined);
+        ctx?.footprint.push(query);
+    }
+    patchOutbound() {
+        const sdk = this;
+        const allowHosts = this.outboundOpts?.allowHosts;
+        const denyHosts = this.outboundOpts?.denyHosts;
+        function shouldRecord(host) {
+            if (denyHosts?.some(h => host.includes(h)))
+                return false;
+            if (allowHosts && !allowHosts.some(h => host.includes(h)))
+                return false;
+            return true;
+        }
+        // Patch global fetch.
+        const originalFetch = globalThis.fetch;
+        if (typeof originalFetch === 'function') {
+            globalThis.fetch = async function patchedFetch(input, init) {
+                // Parse the URL before the fetch so the failure path below can name
+                // the destination even when the call never connects.
+                const url = typeof input === 'string' ? new URL(input) : input instanceof URL ? input : new URL(input.url);
+                const started = performance.now();
+                let res;
+                try {
+                    res = await originalFetch(input, init);
+                }
+                catch (err) {
+                    // A failed call (timeout, DNS, refused connection) is often THE
+                    // cause of the error being captured — record it, then re-throw so
+                    // application behavior is untouched.
+                    const ctx = context_js_1.contextStorage.getStore();
+                    if (ctx && shouldRecord(url.host)) {
+                        const name = err?.name;
+                        ctx.outboundCalls.push({
+                            host: url.host,
+                            method: (init?.method ?? 'GET').toUpperCase(),
+                            path: url.pathname + url.search,
+                            status: 0,
+                            duration_ms: Math.round(performance.now() - started),
+                            outcome: name === 'TimeoutError' || name === 'AbortError' ? 'timeout' : 'network_error',
+                            recorded_for_replay: true,
+                        });
+                    }
+                    throw err;
+                }
+                const ctx = context_js_1.contextStorage.getStore();
+                if (ctx) {
+                    const host = url.host;
+                    if (shouldRecord(host)) {
+                        const ct = res.headers.get('content-type') ?? '';
+                        let responseBody;
+                        if (ct.includes('json') || ct.includes('text')) {
+                            try {
+                                const clone = res.clone();
+                                const text = await clone.text();
+                                responseBody = text.slice(0, 64 * 1024);
+                            }
+                            catch { /* ignore */ }
+                        }
+                        ctx.outboundCalls.push({
+                            host,
+                            method: (init?.method ?? 'GET').toUpperCase(),
+                            path: url.pathname + url.search,
+                            status: res.status,
+                            response_body: responseBody,
+                            duration_ms: Math.round(performance.now() - started),
+                            outcome: 'success',
+                            recorded_for_replay: true,
+                        });
+                    }
+                }
+                return res;
+            };
+        }
+    }
+    // Wired up dynamically onto [Symbol.asyncDispose] in the constructor —
+    // see the comment there for why this is a plain private method instead
+    // of a computed class member.
+    async disposeInternal() {
+        this.rulesPoller.stop();
+        this.idempotencySettingsPoller.stop();
+        this.inferenceReporter.stop();
+        await this.inferenceReporter.flush();
+        this.distributionBaselinePoller.stop();
+        this.distributionDriftReporter.stop();
+        await this.distributionDriftReporter.flush();
+        this.writeCountBaselinePoller.stop();
+        this.writeCountDriftReporter.stop();
+        await this.writeCountDriftReporter.flush();
+        this.mongoSchemaReporter?.stop();
+        this.transport.stop();
+        await this.transport.flush();
+    }
+}
+exports.Reprova = Reprova;
+// Auto-setup http_5xx hook for Express responses.
+function wrapResponse(res, sdk) {
+    if (typeof res.json !== 'function')
+        return; // non-standard res (tests, mocks)
+    const originalJson = res.json.bind(res);
+    res.json = function (body) {
+        if (res.statusCode >= 500) {
+            const bodyStr = typeof body === 'string' ? body : JSON.stringify(body);
+            sdk.captureHttp5xx(null, res.statusCode, bodyStr.slice(0, 16 * 1024));
+        }
+        // Checked on every response, not just failures — an N+1 request usually
+        // returns 200 while doing far more DB round-trips than it should.
+        sdk.captureNPlusOneIfAny();
+        sdk.captureRetryStormIfAny();
+        sdk.captureBusinessInvariantViolationsIfAny();
+        sdk.captureWriteCountDriftIfAny();
+        // Suspended: idempotency checks (both the key-mismatch and the
+        // duplicate-read detector live inside checkIdempotencyIfAny) are
+        // paused. Not removed: the method, its settings poller, and the
+        // control-plane endpoints are all still intact; uncomment this line
+        // to re-enable both checks.
+        // sdk.checkIdempotencyIfAny(body);
+        sdk.checkDistributionDriftIfAny(body);
+        // Replay mode only: capture() stashed a detector's {trigger, type,
+        // message} on the context instead of transporting it (no live control
+        // plane to report to). Surface it here, as a header rather than folding
+        // it into the body, so the CLI's verdict comparison can read it without
+        // disturbing the app's real response shape — checked only as a fallback
+        // when the body itself carries no error (parseReplayResponse in
+        // cli/src/lib/verdict.ts), since a thrown exception's own
+        // replayErrorHandler/nestExceptionFilter body always takes priority.
+        if (sdk.replayMode) {
+            const ctx = context_js_1.contextStorage.getStore();
+            if (ctx?.replayDetection && typeof res.setHeader === 'function') {
+                try {
+                    res.setHeader('X-Reprova-Replay-Detection', JSON.stringify(ctx.replayDetection));
+                }
+                catch {
+                    /* never break the response */
+                }
+            }
+        }
+        return originalJson(body);
+    };
+}