@reprova/sdk 0.4.0 → 0.6.0

package/README.md

@@ -55,7 +55,7 @@ anything else records them with one `recordFootprint` call per query site.
 | Sequelize | `installSequelizeHooks` | ✅ exact (model metadata) | ✅ |
 | TypeORM | `installTypeOrmSubscriber` | ✅ exact (entity metadata) | ➖ |
 | Knex / Objection | `installKnexHooks` | ✅ SELECT; INSERT depends on driver RETURNING | ➖ |
-| Drizzle | `createDrizzleLogger` | ❌ shape-only (no result hook) | ✅ |
+| Drizzle | `createDrizzleFootprint` | ✅ SELECT (via Cache hook); ❌ writes (Drizzle exposes no result hook for them) | ✅ |
 
 ## Express (optional enrichment)
 
@@ -64,6 +64,70 @@ const sdk = Reprova.init({ dsn: process.env.REPROVA_DSN, release: gitSha });
 sdk.setupExpress(app);   // async-rejection forwarding + error-middleware capture + parsed bodies
 ```
 
+## Auth claims (automatic for most apps, zero code changes)
+
+`repro run`/`repro test` re-sign the captured request's auth claims into a
+token the replayed app can validate — but only if the SDK captured claims in
+the first place. Auto-detection covers the two dominant conventions, no
+wiring needed:
+
+- `req.auth` — `express-oauth2-jwt-bearer` / Auth0-style middleware
+- `req.user` — Passport, and the overwhelming majority of hand-rolled
+  Express JWT middleware (`req.user = decoded` right after `jwt.verify`)
+
+Only apps using neither — a custom property, a non-Express framework — need
+one explicit call from inside their own auth middleware:
+
+```ts
+import { setAuthClaims } from '@reprova/sdk';
+
+function verifyToken(req, res, next) {
+  const decoded = jwt.verify(token, secret);
+  req.identity = decoded; // some other property auto-detection doesn't check
+  setAuthClaims(decoded); // tells Reprova what to re-sign at replay time
+  next();
+}
+```
+
+Without it, replay has no claims to re-sign, sends no `Authorization`
+header, and the app rejects the replayed request as unauthenticated before
+it ever reaches the captured bug — `repro run` reports `DIFFERENT FAILURE`
+instead of reproducing the original error. `setAuthClaims` is a no-op
+outside a Reprova request context, so it's safe to call unconditionally.
+
+## Framework adapters (auth claims + migration_id for anything else)
+
+`setAuthClaims` (above) and `sdk.setMigrationId` cover apps that can call
+something from inside their own request/startup code. Some frameworks
+resolve both through their own machinery instead — a DI container, a
+non-Express request shape — with no single call site to hook. One call
+covers both at once:
+
+```ts
+const sdk = Reprova.init({ dsn: process.env.REPROVA_DSN, release: gitSha });
+
+sdk.registerFrameworkAdapter({
+  // Return undefined (not {}) to fall back to the built-in req.auth/req.user
+  // check instead of claiming "no auth" — useful if your framework only
+  // sometimes populates its own property.
+  extractAuthClaims: (rawRequest) => {
+    const req = rawRequest as { auth_context?: Record<string, unknown> };
+    return req.auth_context; // e.g. Medusa's own auth context
+  },
+  // Called once at registration — re-register (or call sdk.setMigrationId
+  // directly) if it can change during the process's lifetime.
+  resolveMigrationId: async () => {
+    const row = await db.query('SELECT name FROM my_migrations_table ORDER BY applied_at DESC LIMIT 1');
+    return row?.name ?? 'unknown';
+  },
+});
+```
+
+Both fields are optional independently — supply only the one your framework
+needs. Neither ever throws into request handling: `extractAuthClaims`
+falls back to `req.auth ?? req.user` on error or `undefined`, and a
+rejected `resolveMigrationId` just leaves `migration_id` as `'unknown'`.
+
 ## Prisma (optional enrichment — automatic footprints)
 
 One call wires both automatic footprints and `migration_id`:
@@ -161,18 +225,116 @@ affected-row count; INSERT PK fidelity depends on the driver's RETURNING
 support (full on Postgres, last-id only on sqlite/mysql). No `where_shape`
 (Knex has no query AST).
 
-## Drizzle (optional enrichment — shape-only)
+## Drizzle (optional enrichment — exact PKs for SELECT, shape-only writes)
 
-Drizzle has no result-aware hook, only a logger — so this adapter records the
-table, operation, and WHERE column names, but **cannot extract PKs**:
+Drizzle has no single result-aware hook for every operation, but it has two
+partial ones that together cover most of it: a `logger` (SQL text, no rows)
+and a `Cache` (real result rows for SELECT, no rows for writes).
+`createDrizzleFootprint()` wires both, merged into one footprint entry per
+query — no double-counting:
 
 ```ts
-import { createDrizzleLogger } from '@reprova/sdk';
-const db = drizzle(client, { logger: createDrizzleLogger() });
+import { createDrizzleFootprint } from '@reprova/sdk';
+const { logger, cache } = createDrizzleFootprint();
+const db = drizzle(client, { logger, cache });
+```
+
+- **SELECT**: exact PKs and row count, extracted from the real rows Drizzle's
+  `Cache.put()` hook receives — `get()` always returns a miss, so this never
+  serves a cached (possibly stale) result back to the app, it only observes.
+  PK columns default to `['id']`; override for composite or non-`id` keys the
+  same way as Kysely: `createDrizzleFootprint({ primaryKey: (table) => [...] })`.
+- **INSERT/UPDATE/DELETE**: shape-only (table + operation + WHERE column
+  names), same as before — Drizzle's mutation hook (`onMutate`) gets table
+  names only, never rows or even a count, and it races the real query
+  internally. For PK-level fidelity on writes, still call
+  `sdk.recordFootprint(...)` at the query sites that matter.
+- Only works for **async drivers** (`node-postgres`, `postgres-js`, `mysql2`,
+  etc. — Reprova's two supported dialects for the customer's own database).
+  Sync drivers (`better-sqlite3`, `bun:sqlite`) bypass Drizzle's cache path
+  entirely; use `createDrizzleLogger()` alone there (shape-only, as before).
+  Drizzle ships no SQL Server driver at all, so this adapter never covers
+  that lane regardless of driver.
+
+Prefer to build the pair yourself, or use just one half?
+`createDrizzleLogger()` and `createDrizzleCache({ logger })` are still
+exported individually — pass the SAME logger instance to `createDrizzleCache`
+to get the merge behavior; omit it to run the cache standalone (exact
+SELECT PKs, no `where_shape`, no write coverage).
+
+## N+1 query detection (automatic once any ORM adapter above is wired up)
+
+Every adapter above feeds the same per-request footprint (one entry per
+query call). The SDK watches that footprint on every response — success or
+failure — for the same `(model, operation)` shape executed repeatedly as
+separate calls in one request: a `for` loop firing one `findUnique` per
+item instead of a single batched query. No exception, no 5xx — the request
+usually returns 200 while doing far more DB round-trips than it should,
+which is exactly the case nothing else here catches.
+
+```ts
+const sdk = Reprova.init({ dsn: process.env.REPROVA_DSN, release: gitSha, n1Threshold: 5 });
+```
+
+`n1Threshold` (default `5`) is how many times the same shape has to repeat
+in one request before it's flagged; `0` disables detection entirely. It
+can't mistake one efficient query for N+1: an `include`/join produces
+exactly one footprint entry per relation regardless of how many rows it
+returns, so only genuinely separate calls count.
+
+## Retry storm detection (automatic — no wiring needed)
+
+Every outbound `fetch()` call is already recorded per request (host,
+method, path, status, outcome — used for outbound-call replay). The SDK
+watches those calls, on every response, for the same `(host, method, path)`
+called repeatedly with at least one failure among the attempts — a naive
+retry loop hammering an already-struggling dependency instead of backing
+off. Repetition alone isn't enough to flag: calling the same endpoint
+several times and getting `200` every time is normal pagination or batch
+fetching, not a storm — only repeats that include a failure (a `5xx`, or a
+network error/timeout) count.
+
+```ts
+const sdk = Reprova.init({ dsn: process.env.REPROVA_DSN, release: gitSha, retryStormThreshold: 3 });
+```
+
+`retryStormThreshold` (default `3`, lower than `n1Threshold`'s `5` since
+real backoff configs commonly cap around 3 attempts) is how many calls to
+the same target it takes before a repeat-with-failures is flagged; `0`
+disables it. The query string is stripped before grouping, since a real
+retry commonly varies a request id or cache-busting param per attempt.
+
+## NestJS (optional enrichment — original stacks + replay parity)
+
+Nest's exception layer catches thrown errors before Express error middleware
+ever sees them and converts them to 500s — so with only `init()`, Nest errors
+are captured via the silent-5xx hook: full request context and footprint, but
+a synthesized error instead of the real one. The filter closes that gap, and
+gives Nest apps the same `REPROVA_REPLAY` exact-stack contract as
+`replayErrorHandler`:
+
+```ts
+const sdk = Reprova.init({ dsn: process.env.REPROVA_DSN, release: gitSha });
+const app = await NestFactory.create(AppModule);
+await sdk.setupNest(app, { prisma: app.get(PrismaService), dmmf: Prisma.dmmf });
 ```
 
-For PK-level fidelity with Drizzle, add `sdk.recordFootprint(...)` at the query
-sites that matter; the logger gives cheap table-level coverage on top.
+`setupNest` registers the exception filter and (when given a Prisma client)
+wires automatic footprints + `migration_id` — the whole integration in one
+call, like `setupExpress`. Using TypeORM/Knex/etc. instead? Call
+`setupNest(app)` bare and add the usual one-liner
+(`installTypeOrmSubscriber(dataSource)`, ...). Prefer manual control?
+`app.useGlobalFilters(sdk.nestExceptionFilter())` is still exported.
+
+No decorator needed — a filter without `@Catch` metadata is catch-all, and
+the SDK never imports `@nestjs/*` (structural typing, like every adapter
+here; proven against real Nest in `test/nest.integration.test.ts`). Behavior
+mirrors Nest's own default filter: intentional `HttpException`s (4xx) pass
+through untouched and uncaptured; non-HTTP exceptions and 5xx
+`HttpException`s are captured with their original type/message/stack and
+answered with the default body. Works on the Express and Fastify adapters.
+If you register other filters, list this one first in `useGlobalFilters` so
+more specific `@Catch(...)` filters keep winning.
 
 ## Express (continued)
 

package/dist/cjs/context.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextStorage = void 0;
+exports.currentContext = currentContext;
+exports.setAuthClaims = setAuthClaims;
+const async_hooks_1 = require("async_hooks");
+exports.contextStorage = new async_hooks_1.AsyncLocalStorage();
+function currentContext() {
+    return exports.contextStorage.getStore();
+}
+/**
+ * Explicitly records the authenticated identity for the in-flight request.
+ * Auto-detection already covers `req.auth` (express-oauth2-jwt-bearer/Auth0)
+ * and `req.user` (Passport and most hand-rolled Express JWT middleware) —
+ * see detectAuthClaims in sdk.ts — so most apps need zero code changes. This
+ * is the escape hatch for anything else: a custom property, a non-Express
+ * framework. Call it from inside your own auth middleware once the token is
+ * verified, e.g. `setAuthClaims(decoded)` right after `jwt.verify`. Without
+ * captured claims one way or the other, replay has nothing to re-sign into a
+ * token and the app bounces the replayed request as unauthenticated before
+ * it ever reaches the captured bug. No-ops outside a Reprova request
+ * context.
+ */
+function setAuthClaims(claims) {
+    const ctx = currentContext();
+    if (ctx)
+        ctx.request.authClaims = claims;
+}

package/dist/cjs/distributionBaselinePoller.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DistributionBaselinePoller = void 0;
+const httpFetch_js_1 = require("./httpFetch.js");
+const WARN_INTERVAL_MS = 60_000;
+// Same start()/stop()/setInterval+unref shape as RulesPoller and
+// IdempotencySettingsPoller — periodically fetches the tenant's current
+// aggregate baselines (and the drift-detection on/off toggle) so a running
+// process can check each response against a live baseline without a
+// redeploy, and so drift detection stays off by default until an admin
+// opts in from the dashboard. Falls back to disabled + no baselines before
+// the first successful poll and on any failure, so a bad response or an
+// unreachable control plane fails closed (no captures), not open (spurious
+// captures from a stale or empty baseline).
+class DistributionBaselinePoller {
+    enabled = false;
+    baselines = new Map();
+    timer = null;
+    lastWarnAt = 0;
+    endpoint;
+    apiKey;
+    intervalMs;
+    constructor(opts) {
+        this.endpoint = opts.endpoint;
+        this.apiKey = opts.apiKey;
+        this.intervalMs = opts.intervalMs ?? 60_000;
+    }
+    start() {
+        void this.refresh();
+        this.timer = setInterval(() => void this.refresh(), this.intervalMs);
+        if (this.timer.unref)
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    getBaseline(route, field) {
+        return this.baselines.get(`${route}\x00${field}`);
+    }
+    async refresh() {
+        try {
+            const res = await (0, httpFetch_js_1.httpFetch)(this.endpoint, {
+                headers: { 'X-Reprova-Key': this.apiKey },
+            });
+            if (!res.ok) {
+                this.warnOnce(`reprova: distribution baselines fetch returned ${res.status}`);
+                return;
+            }
+            const body = (await res.json());
+            this.applyResponse(body);
+        }
+        catch (err) {
+            this.warnOnce(`reprova: distribution baselines fetch error: ${err.message}`);
+        }
+    }
+    // Applies an already-fetched response directly, with no network call —
+    // used by replay mode to seed a one-time snapshot the CLI fetched ahead of
+    // time (there's no live control plane to poll from inside a replayed
+    // app), so drift detection (checkDistributionDriftIfAny/
+    // captureWriteCountDriftIfAny in sdk.ts) sees exactly the same shape it
+    // would from a real refresh().
+    seed(body) {
+        this.applyResponse(body);
+    }
+    applyResponse(body) {
+        this.enabled = body.enabled ?? false;
+        const next = new Map();
+        for (const b of body.baselines ?? []) {
+            next.set(`${b.route}\x00${b.field}`, { sampleCount: b.sample_count, mean: b.mean, stddev: b.stddev });
+        }
+        this.baselines = next;
+    }
+    warnOnce(msg) {
+        const now = Date.now();
+        if (now - this.lastWarnAt > WARN_INTERVAL_MS) {
+            this.lastWarnAt = now;
+            console.warn(msg);
+        }
+    }
+}
+exports.DistributionBaselinePoller = DistributionBaselinePoller;

package/dist/cjs/distributionDrift.js

@@ -0,0 +1,170 @@
+"use strict";
+// Distributional drift, numeric-only v1 slice: baseline the typical range
+// of a numeric response field per (route, field) using Welford's online
+// mean/variance algorithm, and flag a value that's implausibly far from
+// that baseline — a `total` field that's normally 10-500 suddenly
+// returning -40, with no rule authored and no equality asserted anywhere.
+// Unlike business-invariant-rules and idempotency-key matching, this is a
+// statistical guess with real false-positive risk (there's no
+// "asymptotically safe" case the way an app-asserted equality is), so it's
+// off by default and the thresholds below are fixed, not yet
+// tenant-configurable.
+//
+// Deliberately scoped to numeric fields only for this slice — categorical
+// novelty (a status enum emitting a never-seen value) is a structurally
+// different mechanism (tracking a bounded set of distinct values, not a
+// running mean/variance) and is left for a later slice.
+//
+// Observes the top-level fields of a JSON object response body only — not
+// nested objects/arrays, and not array-shaped top-level responses (a list
+// endpoint's items each have their own values; there's no single baseline
+// for "the array"). That keeps the walk trivial and the key space bounded
+// to (route, field) instead of an unbounded set of JSON paths.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DistributionDriftReporter = exports.WriteCountDrift = exports.ValueDistributionDrift = void 0;
+exports.newWelfordState = newWelfordState;
+exports.updateWelfordState = updateWelfordState;
+exports.isDrift = isDrift;
+exports.extractTopLevelNumericFields = extractTopLevelNumericFields;
+const httpFetch_js_1 = require("./httpFetch.js");
+const MIN_SAMPLES = 200;
+const SIGMA_MULTIPLIER = 6;
+class ValueDistributionDrift extends Error {
+}
+exports.ValueDistributionDrift = ValueDistributionDrift;
+// Same mean/variance mechanism, same MIN_SAMPLES/SIGMA_MULTIPLIER thresholds,
+// entirely different observation site: prisma.ts's observeWriteCountDrift
+// baselines a Prisma updateMany/deleteMany/createMany's affected-row count
+// per (route, operation:model) instead of an HTTP response field's value. Shares
+// WelfordState/updateWelfordState/isDrift directly — the math doesn't care
+// what number it's baselining — and DistributionDriftReporter/
+// DistributionBaselinePoller are already fully generic (record/getBaseline
+// take arbitrary string keys), so a second instance of each, pointed at a
+// separate control-plane endpoint, is all that's needed there too. Kept as
+// a distinct Error class/trigger since it's a conceptually separate
+// question ("did this write touch a weird number of rows" vs. "is this
+// response value weird") with its own independent dashboard toggle.
+class WriteCountDrift extends Error {
+}
+exports.WriteCountDrift = WriteCountDrift;
+function newWelfordState() {
+    return { count: 0, mean: 0, m2: 0, min: Infinity, max: -Infinity };
+}
+// Standard single-pass Welford update — mean and M2 (sum of squared
+// deviations from the running mean) stay numerically stable across an
+// unbounded stream, unlike naively accumulating sum/sum-of-squares.
+function updateWelfordState(state, x) {
+    state.count++;
+    const delta = x - state.mean;
+    state.mean += delta / state.count;
+    const delta2 = x - state.mean;
+    state.m2 += delta * delta2;
+    if (x < state.min)
+        state.min = x;
+    if (x > state.max)
+        state.max = x;
+}
+// A value is drift when the baseline has enough samples to trust AND the
+// value is more than SIGMA_MULTIPLIER standard deviations from the mean.
+// A zero-variance baseline (every sample identical so far) treats ANY
+// different value as infinite deviation — flagged, since after MIN_SAMPLES
+// consistent observations a field that never varied suddenly doing so is
+// exactly the kind of thing worth surfacing, not a numerical edge case to
+// special-case away.
+function isDrift(value, baseline) {
+    if (baseline.sampleCount < MIN_SAMPLES)
+        return false;
+    const deviation = baseline.stddev === 0 ? (value !== baseline.mean ? Infinity : 0) : Math.abs(value - baseline.mean) / baseline.stddev;
+    return deviation > SIGMA_MULTIPLIER;
+}
+// Extracts finite numeric values from the response body's OWN top-level
+// keys — null/NaN/Infinity are skipped (not a "value", nothing to
+// baseline), and a non-object or array body yields nothing (see module doc
+// for why array-shaped top-level responses are out of scope for this slice).
+function extractTopLevelNumericFields(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(body)) {
+        if (typeof v === 'number' && Number.isFinite(v))
+            out[k] = v;
+    }
+    return out;
+}
+const WARN_INTERVAL_MS = 60_000;
+// Accumulates local Welford state per (route, field) since the last flush
+// and periodically reports it as a delta — same start/stop/periodic-flush
+// shape as BatchTransport/InferenceReporter. The control plane merges each
+// report into the tenant's cumulative baseline via the parallel-variance
+// formula; a dropped/failed flush only ever loses that batch's
+// contribution (undercounts), never double-reports on retry, since there
+// is no retry — same trade-off every other reporter in this SDK already
+// makes.
+class DistributionDriftReporter {
+    states = new Map();
+    timer = null;
+    lastWarnAt = 0;
+    endpoint;
+    apiKey;
+    flushIntervalMs;
+    constructor(opts) {
+        this.endpoint = opts.endpoint;
+        this.apiKey = opts.apiKey;
+        this.flushIntervalMs = opts.flushIntervalMs ?? 30_000;
+    }
+    start() {
+        this.timer = setInterval(() => void this.flush(), this.flushIntervalMs);
+        if (this.timer.unref)
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    record(route, field, value) {
+        const key = `${route}\x00${field}`;
+        let entry = this.states.get(key);
+        if (!entry) {
+            entry = { route, field, state: newWelfordState() };
+            this.states.set(key, entry);
+        }
+        updateWelfordState(entry.state, value);
+    }
+    async flush() {
+        if (this.states.size === 0)
+            return;
+        const observations = [...this.states.values()].map(({ route, field, state }) => ({
+            route,
+            field,
+            count: state.count,
+            mean: state.mean,
+            m2: state.m2,
+            min: state.min,
+            max: state.max,
+        }));
+        this.states.clear();
+        try {
+            const res = await (0, httpFetch_js_1.httpFetch)(this.endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'X-Reprova-Key': this.apiKey },
+                body: JSON.stringify({ observations }),
+            });
+            if (!res.ok) {
+                this.warnOnce(`reprova: distribution baseline report returned ${res.status}`);
+            }
+        }
+        catch (err) {
+            this.warnOnce(`reprova: distribution baseline report error: ${err.message}`);
+        }
+    }
+    warnOnce(msg) {
+        const now = Date.now();
+        if (now - this.lastWarnAt > WARN_INTERVAL_MS) {
+            this.lastWarnAt = now;
+            console.warn(msg);
+        }
+    }
+}
+exports.DistributionDriftReporter = DistributionDriftReporter;