@reprova/sdk 0.4.0 → 0.6.0

package/dist/sdk.js

@@ -1,10 +1,40 @@
 import http from 'node:http';
 import https from 'node:https';
+import { readFileSync } from 'node:fs';
+import { httpFetch } from './httpFetch.js';
 import { contextStorage } from './context.js';
 import { registerContext, completeContext, snapshotCohort } from './registry.js';
 import { BatchTransport } from './transport.js';
 import { parseStack, generateTraceId, stripHeaders, captureHeaders } from './stack.js';
 import { createPrismaExtension } from './prisma.js';
+import { instrumentLegacyPrismaClient } from './legacyPrisma.js';
+import { createNestExceptionFilter, createNestContextInterceptor } from './nest.js';
+import { detectNPlusOne, PotentialNPlusOneQuery } from './nPlusOne.js';
+import { detectRetryStorm, PotentialRetryStorm } from './retryStorm.js';
+import { BusinessInvariantViolation } from './invariantRules.js';
+import { RulesPoller } from './rulesPoller.js';
+import { DEFAULT_IDEMPOTENCY_SETTINGS, HashMismatchCache, IdempotencyKeyMismatch, DuplicateReadMismatch, findIdempotencyKey, extractIdentity, hashResponseBody, } from './idempotency.js';
+import { IdempotencySettingsPoller } from './idempotencySettingsPoller.js';
+import { InferenceReporter } from './invariantInference.js';
+import { DistributionDriftReporter, ValueDistributionDrift, WriteCountDrift, extractTopLevelNumericFields, isDrift } from './distributionDrift.js';
+import { DistributionBaselinePoller } from './distributionBaselinePoller.js';
+import { reprovaMongoosePlugin, instrumentAlreadyCompiledModels } from './mongoose.js';
+import { MongoSchemaReporter } from './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(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
@@ -16,22 +46,59 @@ const kAsyncWrapped = Symbol('reprova.asyncWrapped');
 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 — by the time anything is captured, both are final.
-// Mutating ctx.request in place keeps cohort snapshots consistent too.
-function refreshRequestSnapshot(ctx) {
+// 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 ?? '');
     }
-    if (req.auth !== undefined && ctx.request.authClaims === undefined) {
-        ctx.request.authClaims = req.auth;
+    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.
@@ -50,13 +117,14 @@ function instrumentHttpServers() {
         const originalEmit = proto.emit;
         proto.emit = function (event, ...args) {
             const sdk = instance;
-            if (event !== 'request' || !sdk || sdk.disabled) {
+            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);
             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.
@@ -90,6 +158,14 @@ function contextFromIncoming(req) {
         // keep raw url
     }
     const traceId = req.headers['traceparent'] ?? 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(),
@@ -101,6 +177,8 @@ function contextFromIncoming(req) {
         },
         footprint: [],
         outboundCalls: [],
+        businessInvariantHits: [],
+        writeCountDriftHits: [],
         rawRequest: req,
     };
 }
@@ -215,18 +293,66 @@ function patchLayerPrototype(app) {
 export 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 HashMismatchCache(DEFAULT_IDEMPOTENCY_SETTINGS.max_keys, DEFAULT_IDEMPOTENCY_SETTINGS.ttl_ms);
+    duplicateReadCache = new HashMismatchCache(DEFAULT_IDEMPOTENCY_SETTINGS.max_keys, DEFAULT_IDEMPOTENCY_SETTINGS.duplicate_read_window_ms);
     release;
-    sdkVersion = '0.4.0';
+    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: constructed so internal wiring stays uniform, but
-            // never started and capture() never enqueues into it.
+            // 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 BatchTransport({ endpoint: 'http://disabled.invalid/v1/ingest', apiKey: '' });
+            this.rulesPoller = new RulesPoller({ endpoint: 'http://disabled.invalid/v1/business-invariant-rules', apiKey: '' });
+            this.idempotencySettingsPoller = new IdempotencySettingsPoller({ endpoint: 'http://disabled.invalid/v1/settings/idempotency', apiKey: '' });
+            this.inferenceReporter = new InferenceReporter({ endpoint: 'http://disabled.invalid/v1/inferred-invariants/observe', apiKey: '' });
+            this.distributionDriftReporter = new DistributionDriftReporter({ endpoint: 'http://disabled.invalid/v1/distribution-baselines/observe', apiKey: '' });
+            this.distributionBaselinePoller = new DistributionBaselinePoller({ endpoint: 'http://disabled.invalid/v1/distribution-baselines', apiKey: '' });
+            this.writeCountDriftReporter = new DistributionDriftReporter({ endpoint: 'http://disabled.invalid/v1/write-count-baselines/observe', apiKey: '' });
+            this.writeCountBaselinePoller = new 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);
@@ -234,13 +360,78 @@ export class Reprova {
             const endpoint = `${url.protocol}//${url.host}/v1/ingest`;
             this.transport = new BatchTransport({ endpoint, apiKey });
             this.transport.start();
+            this.rulesPoller = new RulesPoller({
+                endpoint: `${url.protocol}//${url.host}/v1/business-invariant-rules`,
+                apiKey,
+                intervalMs: opts.rulesRefreshIntervalMs,
+            });
+            this.rulesPoller.start();
+            this.idempotencySettingsPoller = new IdempotencySettingsPoller({
+                endpoint: `${url.protocol}//${url.host}/v1/settings/idempotency`,
+                apiKey,
+                intervalMs: opts.rulesRefreshIntervalMs,
+            });
+            this.idempotencySettingsPoller.start();
+            this.inferenceReporter = new InferenceReporter({
+                endpoint: `${url.protocol}//${url.host}/v1/inferred-invariants/observe`,
+                apiKey,
+            });
+            this.inferenceReporter.start();
+            this.distributionDriftReporter = new DistributionDriftReporter({
+                endpoint: `${url.protocol}//${url.host}/v1/distribution-baselines/observe`,
+                apiKey,
+            });
+            this.distributionDriftReporter.start();
+            this.distributionBaselinePoller = new DistributionBaselinePoller({
+                endpoint: `${url.protocol}//${url.host}/v1/distribution-baselines`,
+                apiKey,
+                intervalMs: opts.rulesRefreshIntervalMs,
+            });
+            this.distributionBaselinePoller.start();
+            this.writeCountDriftReporter = new DistributionDriftReporter({
+                endpoint: `${url.protocol}//${url.host}/v1/write-count-baselines/observe`,
+                apiKey,
+            });
+            this.writeCountDriftReporter.start();
+            this.writeCountBaselinePoller = new 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);
-        if (!instance.disabled) {
+        // 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();
@@ -251,6 +442,25 @@ export class Reprova {
     }
     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.
@@ -263,35 +473,167 @@ export class Reprova {
     // $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) {
-        if (this.disabled)
+        // 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: extend, then copy the extended client's behavior
-        //    back onto the original so every importer of the singleton records.
-        const ext = createPrismaExtension(opts?.dmmf);
-        Object.assign(c, c.$extends(ext));
+        // 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 = 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 {
+            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) {
-            try {
-                const rows = await c.$queryRaw `
-          SELECT migration_name FROM _prisma_migrations ORDER BY finished_at DESC LIMIT 1
-        `;
+            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);
                 }
             }
-            catch {
-                // migration_id stays 'unknown'
-            }
         }
     }
+    // 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(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.
+        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({
+            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 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;
@@ -329,7 +671,7 @@ export class Reprova {
                 keepErrorHandlerLast(req.app);
             }
             // http_5xx-without-throw hook rides along automatically.
-            if (!this.disabled)
+            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
@@ -348,25 +690,33 @@ export class Reprova {
                     path: req.path,
                     headers: captureHeaders(req.headers),
                     body: typeof req.body === 'string' ? req.body : JSON.stringify(req.body ?? ''),
-                    authClaims: req['auth'],
+                    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).
             registerContext(ctx);
+            ctxByRequest.set(req, ctx);
             const done = () => completeContext(ctx);
             res.on('finish', done);
             res.on('close', done);
             contextStorage.run(ctx, next);
         };
     }
-    // Express error middleware: captures unhandled_exception.
+    // 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 = contextStorage.getStore();
+            const ctx = contextStorage.getStore() ?? ctxByRequest.get(req);
             if (ctx && err instanceof Error) {
                 this.capture('unhandled_exception', err, ctx);
             }
@@ -378,6 +728,62 @@ export class Reprova {
         const ctx = 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 createNestExceptionFilter({
+            capture: (err) => {
+                const ctx = 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 createNestContextInterceptor({
+            resolveContext: (req) => (req !== undefined ? ctxByRequest.get(req) : undefined) ?? contextStorage.getStore(),
+            runInContext: (ctx, fn) => 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 = contextStorage.getStore();
@@ -393,12 +799,169 @@ export class Reprova {
             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 = contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        for (const finding of detectNPlusOne(ctx.footprint, this.n1Threshold)) {
+            this.capture('n_plus_one_query', new 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 = contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        for (const finding of detectRetryStorm(ctx.outboundCalls, this.retryStormThreshold)) {
+            this.capture('retry_storm', new 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 = contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        for (const hit of ctx.businessInvariantHits) {
+            this.capture('business_invariant', new 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 = contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        for (const hit of ctx.writeCountDriftHits) {
+            this.capture('write_count_drift', new 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 = 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 = findIdempotencyKey(ctx.request.headers, settings.header_names);
+            if (key) {
+                this.idempotencyKeyCache.configure(settings.max_keys, settings.ttl_ms);
+                const hash = hashResponseBody(body);
+                const signature = `${method} ${routePattern ?? ''} ${key}`;
+                if (this.idempotencyKeyCache.checkAndRecord(signature, hash)) {
+                    this.capture('idempotency_key_mismatch', new 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 = 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 = hashResponseBody(body);
+                const signature = `${routePattern ?? ctx.request.path} ${query} identity:${identity}`;
+                if (this.duplicateReadCache.checkAndRecord(signature, hash)) {
+                    this.capture('duplicate_read_mismatch', new 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 = 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 = 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 && isDrift(value, baseline)) {
+                this.capture('value_distribution_drift', new 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)
+        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);
+            refreshRequestSnapshot(ctx, this.authClaimsExtractor);
         }
         const payload = {
             trigger: trigger,
@@ -408,7 +971,11 @@ export class Reprova {
             migration_id: this.migrationId,
             sdk_version: this.sdkVersion,
             error: {
-                type: err.constructor?.name ?? err.name ?? '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: parseStack(err),
             },
@@ -478,6 +1045,8 @@ export class Reprova {
             },
             footprint: [],
             outboundCalls: [],
+            businessInvariantHits: [],
+            writeCountDriftHits: [],
         };
         registerContext(ctx);
         try {
@@ -495,10 +1064,24 @@ export class Reprova {
     // 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. Silent
-    // no-op outside a capture context.
-    recordFootprint(query) {
-        contextStorage.getStore()?.footprint.push(query);
+    // 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 = contextStorage.getStore() ?? (rawRequest !== undefined ? ctxByRequest.get(rawRequest) : undefined);
+        ctx?.footprint.push(query);
     }
     patchOutbound() {
         const sdk = this;
@@ -572,7 +1155,21 @@ export class Reprova {
             };
         }
     }
-    async [Symbol.asyncDispose]() {
+    // 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();
     }
@@ -587,6 +1184,38 @@ export function wrapResponse(res, sdk) {
             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 = 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);
     };
 }