@reprova/sdk 0.4.0 → 0.6.0

package/dist/cjs/nextjs.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNextAdapter = createNextAdapter;
+const context_js_1 = require("./context.js");
+const sdk_js_1 = require("./sdk.js");
+const registry_js_1 = require("./registry.js");
+const stack_js_1 = require("./stack.js");
+function toError(value) {
+    if (value instanceof Error)
+        return value;
+    return new Error(typeof value === 'string' ? value : JSON.stringify(value));
+}
+function headersToRecord(headers) {
+    const out = {};
+    headers.forEach((value, key) => {
+        out[key] = value;
+    });
+    return out;
+}
+// Builds a brand-new, self-contained context directly from a Fetch API
+// Request — used when there is no ambient ALS context AND no outer context
+// could be recovered by traceId (instrumentHttp disabled, an edge runtime
+// with no Node http.Server underneath, or any other setup with no "outer"
+// context to begin with). Registered/completed by the caller, same lifecycle
+// runWithContext/runJob already give background work with no HTTP layer at
+// all.
+function contextFromFetchRequest(req) {
+    let path = '/';
+    try {
+        path = new URL(req.url).pathname;
+    }
+    catch {
+        // keep the default
+    }
+    const traceId = req.headers.get('traceparent') ?? (0, stack_js_1.generateTraceId)();
+    return {
+        traceId,
+        capturedAt: new Date(),
+        request: {
+            method: req.method,
+            path,
+            headers: headersToRecord(req.headers),
+            body: '',
+        },
+        footprint: [],
+        outboundCalls: [],
+        businessInvariantHits: [],
+        writeCountDriftHits: [],
+    };
+}
+// The core of wrapRouteHandler's universality: never assumes ambient ALS
+// context survived whatever dispatch mechanism called into this route.
+// Three cases, in order:
+//   1. Ambient context is present — the common case for Pages Router/tRPC,
+//      and for any future Next.js version where App Router propagation
+//      works. Used as-is; nothing to register/complete, that's already
+//      owned by whoever established it.
+//   2. No ambient context, but the request carries the SAME traceparent
+//      value contextFromIncoming wrote onto the raw connection — recovers
+//      the REAL outer context (the one instrumentHttpServers's res 'finish'
+//      handler already closes over for its own http_5xx fallback), so
+//      running the handler inside it and capturing marks that SAME ctx as
+//      captured, suppressing the fallback with zero coordination beyond the
+//      header. This is the case that fixes Next.js App Router: Next
+//      constructs its own Fetch Request rather than reusing the
+//      IncomingMessage, so object-identity recovery (ctxByRequest) can't
+//      work there, but the header survives regardless of what request
+//      object Next builds.
+//   3. Neither — genuinely nothing to recover (instrumentHttp disabled, an
+//      edge runtime). Build a fresh context from the Request itself so a
+//      real capture still happens instead of silently deferring to a
+//      fallback that, in this case, doesn't exist either.
+function resolveRequestContext(req) {
+    const existing = context_js_1.contextStorage.getStore();
+    if (existing)
+        return { ctx: existing, isFresh: false };
+    const traceId = req.headers.get('traceparent');
+    const recovered = traceId ? (0, registry_js_1.findContextByTraceId)(traceId) : undefined;
+    if (recovered)
+        return { ctx: recovered, isFresh: false };
+    const fresh = contextFromFetchRequest(req);
+    (0, registry_js_1.registerContext)(fresh);
+    return { ctx: fresh, isFresh: true };
+}
+// Shared by wrapRouteHandler and withRequestContext: resolves the context
+// once, runs fn() inside it via ALS, and tears down a freshly-built one
+// (never a recovered or already-ambient one — those are owned by whoever
+// created them).
+async function runInResolvedContext(req, fn) {
+    const { ctx, isFresh } = resolveRequestContext(req);
+    try {
+        return await context_js_1.contextStorage.run(ctx, () => fn(ctx));
+    }
+    finally {
+        if (isFresh)
+            (0, registry_js_1.completeContext)(ctx);
+    }
+}
+function createNextAdapter(opts) {
+    const { prisma, dmmf, ...reprovaOpts } = opts;
+    const sdk = sdk_js_1.Reprova.init(reprovaOpts);
+    // Not caught here deliberately: a Prisma instrumentation failure is a real
+    // setup bug (bad dmmf, a client shape instrumentPrisma doesn't recognize),
+    // not something to silently swallow — every ensureInit() caller sees the
+    // same rejection instrumentPrisma itself produced, same as the original
+    // cal.diy wiring this replaces (`await reprovaSdk.instrumentPrisma(...)`,
+    // no try/catch).
+    const initPromise = prisma !== undefined ? sdk.instrumentPrisma(prisma, { dmmf }) : Promise.resolve();
+    function ensureInit() {
+        return initPromise;
+    }
+    // Used by wrapApiHandler and trpcMiddleware — both reliably see the
+    // ambient context established further up the stack (Pages Router's
+    // apiResolver mutates the SAME req object instrumentHttpServers already
+    // saw; tRPC procedures run inside whatever context wrapped the HTTP
+    // handler that dispatches them). Confirmed live: only App Router's own
+    // internal dispatch loses the ALS store (see wrapRouteHandler below for
+    // the fix) — Pages Router and tRPC carry it through fine, so they don't
+    // need the recovery dance.
+    function captureUnhandled(err) {
+        const ctx = context_js_1.contextStorage.getStore();
+        if (!ctx || ctx.captured)
+            return;
+        sdk.capture('unhandled_exception', toError(err), ctx);
+    }
+    return {
+        ensureInit,
+        captureError(err) {
+            const ctx = context_js_1.contextStorage.getStore();
+            if (!ctx || ctx.captured)
+                return;
+            sdk.captureError(toError(err));
+        },
+        wrapRouteHandler(handler) {
+            return (async (req, ...rest) => {
+                await ensureInit();
+                // Establishing ALS directly around this call — rather than
+                // depending on whatever context Next's own dispatch may or may not
+                // have carried through to get here — is what makes this work
+                // regardless of Next.js version, App Router internals, or
+                // Turbopack vs. webpack: there is no dispatch layer left between
+                // this contextStorage.run() and the handler for anything to lose.
+                return runInResolvedContext(req, async (ctx) => {
+                    try {
+                        return await handler(req, ...rest);
+                    }
+                    catch (err) {
+                        if (!ctx.captured)
+                            sdk.capture('unhandled_exception', toError(err), ctx);
+                        throw err;
+                    }
+                });
+            });
+        },
+        async withRequestContext(req, fn) {
+            await ensureInit();
+            return runInResolvedContext(req, () => Promise.resolve(fn()));
+        },
+        wrapApiHandler(handler) {
+            return async (req, res) => {
+                await ensureInit();
+                try {
+                    await handler(req, res);
+                }
+                catch (err) {
+                    captureUnhandled(err);
+                    throw err;
+                }
+            };
+        },
+        trpcMiddleware: async ({ next }) => {
+            await ensureInit();
+            const result = await next();
+            if (!result.ok && result.error?.code === 'INTERNAL_SERVER_ERROR') {
+                captureUnhandled(result.error.cause ?? result.error);
+            }
+            return result;
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/prisma.js

@@ -0,0 +1,363 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPkFields = getPkFields;
+exports.extractPks = extractPks;
+exports.isWriteOperation = isWriteOperation;
+exports.recordFailedWrite = recordFailedWrite;
+exports.recordPrismaOperation = recordPrismaOperation;
+exports.createPrismaExtension = createPrismaExtension;
+const context_js_1 = require("./context.js");
+const shape_js_1 = require("./shape.js");
+const invariantRules_js_1 = require("./invariantRules.js");
+const distributionDrift_js_1 = require("./distributionDrift.js");
+function getPkFields(dmmf, modelName) {
+    const model = dmmf.datamodel.models.find(m => m.name === modelName);
+    if (!model)
+        return ['id'];
+    // Composite PK
+    if (model.primaryKey?.fields?.length)
+        return model.primaryKey.fields;
+    // Single @id field
+    const idField = model.fields.find(f => f.isId);
+    return idField ? [idField.name] : ['id'];
+}
+function getRelationFields(dmmf, modelName) {
+    const model = dmmf.datamodel.models.find(m => m.name === modelName);
+    if (!model)
+        return [];
+    return model.fields.filter(f => f.kind === 'object' && !!f.relationName);
+}
+const NUMERIC_SCALAR_TYPES = new Set(['Int', 'Float', 'Decimal', 'BigInt']);
+function getNumericFieldNames(dmmf, modelName) {
+    const model = dmmf.datamodel.models.find(m => m.name === modelName);
+    if (!model)
+        return new Set();
+    const out = new Set();
+    for (const f of model.fields) {
+        if (f.kind === 'scalar' && NUMERIC_SCALAR_TYPES.has(f.type))
+            out.add(f.name);
+    }
+    return out;
+}
+function extractFromRow(row, pkFields) {
+    const vals = pkFields.map(f => row[f]);
+    if (vals.some(v => v === undefined))
+        return null;
+    return vals.map(v => String(v)).join(':');
+}
+function extractPks(result, pkFields) {
+    if (result === null || result === undefined)
+        return [];
+    if (Array.isArray(result)) {
+        const pks = [];
+        for (const item of result) {
+            if (item && typeof item === 'object') {
+                const pk = extractFromRow(item, pkFields);
+                if (pk !== null)
+                    pks.push(pk);
+            }
+        }
+        return pks;
+    }
+    if (typeof result === 'object') {
+        const pk = extractFromRow(result, pkFields);
+        return pk !== null ? [pk] : [];
+    }
+    return [];
+}
+// Walk one level of included relations on the result (single object or array of
+// objects) and produce one footprint entry per relation field that was actually
+// present in the result (i.e. included in the query).
+function extractNestedFootprints(dmmf, modelName, result) {
+    if (!dmmf)
+        return [];
+    const rows = Array.isArray(result)
+        ? result.filter(r => r && typeof r === 'object')
+        : result && typeof result === 'object'
+            ? [result]
+            : [];
+    if (rows.length === 0)
+        return [];
+    const entries = [];
+    for (const field of getRelationFields(dmmf, modelName)) {
+        if (!rows.some(row => field.name in row))
+            continue; // relation wasn't included
+        const nestedPkFields = getPkFields(dmmf, field.type);
+        const nestedItems = [];
+        for (const row of rows) {
+            const val = row[field.name];
+            if (Array.isArray(val))
+                nestedItems.push(...val);
+            else if (val !== null && val !== undefined)
+                nestedItems.push(val);
+        }
+        const pks = extractPks(field.isList ? nestedItems : nestedItems[0] ?? null, nestedPkFields);
+        entries.push({
+            model: field.type,
+            op: field.isList ? 'findMany' : 'findUnique',
+            pks,
+            count: nestedItems.length,
+            note: nestedItems.length === 0 ? 'returned 0 rows' : undefined,
+        });
+    }
+    return entries;
+}
+// Evaluates every enabled rule matching this model/operation against the
+// query result, recording at most one hit per rule per request (see
+// context.ts's businessInvariantHits). Evaluation only sees relation data
+// the app's own query already `include`d — a rule referencing anything else
+// is silently inapplicable (evaluateInvariant returns undefined), never a
+// false violation. Must run here, inside the extension: this is the only
+// place actual field values are available — the footprint pushed above only
+// ever carries PKs/counts, never row content.
+async function applyInvariantRules(ctx, rules, model, operation, result, pkFields) {
+    if (rules.length === 0)
+        return;
+    const rows = Array.isArray(result)
+        ? result.filter((r) => r && typeof r === 'object')
+        : result && typeof result === 'object'
+            ? [result]
+            : [];
+    if (rows.length === 0)
+        return;
+    for (const rule of rules) {
+        if (rule.model !== model)
+            continue;
+        if (!(0, invariantRules_js_1.operationMatchesHook)(operation, rule.when_hook))
+            continue;
+        if (ctx.businessInvariantHits.some((h) => h.ruleId === rule.id))
+            continue; // one hit per rule per request
+        const compiled = await (0, invariantRules_js_1.compileInvariant)(rule);
+        if (!compiled)
+            continue; // invalid CEL syntax (or CEL engine unavailable on this runtime) — never crash, never fire
+        for (const row of rows) {
+            if ((0, invariantRules_js_1.evaluateInvariant)(compiled, row) === false) {
+                ctx.businessInvariantHits.push({ ruleId: rule.id, message: rule.message, pks: extractPks(row, pkFields) });
+                break; // first offending row is enough evidence for this rule
+            }
+        }
+    }
+}
+// Invariant inference, v1 slice: passively observes whether a same-named
+// numeric field on the parent equals the sum of that same field across an
+// already-included to-many relation (Invoice.total vs
+// sum(lineItems.total)), reporting pass/fail counts — never capturing or
+// altering behavior on its own. Same-field-name only, not every numeric-
+// field-pair combination: that keeps candidate volume bounded (at most one
+// candidate per shared field name per relation, not N×M) and the heuristic
+// legible. Runs unconditionally whenever a reporter is configured; see
+// invariantInference.ts's module doc for the fuller design this is a first
+// slice of.
+function observeInferredInvariants(dmmf, modelName, result, reporter) {
+    if (!dmmf)
+        return;
+    const rows = Array.isArray(result)
+        ? result.filter(r => r && typeof r === 'object')
+        : result && typeof result === 'object'
+            ? [result]
+            : [];
+    if (rows.length === 0)
+        return;
+    const parentNumeric = getNumericFieldNames(dmmf, modelName);
+    if (parentNumeric.size === 0)
+        return;
+    for (const field of getRelationFields(dmmf, modelName)) {
+        if (!field.isList)
+            continue; // sum only makes sense over a to-many relation
+        if (!rows.some(row => field.name in row))
+            continue; // relation wasn't included
+        const childNumeric = getNumericFieldNames(dmmf, field.type);
+        const sharedFields = [...parentNumeric].filter(f => childNumeric.has(f));
+        if (sharedFields.length === 0)
+            continue;
+        for (const row of rows) {
+            const relVal = row[field.name];
+            if (!Array.isArray(relVal))
+                continue; // relation not included on this specific row
+            for (const fieldName of sharedFields) {
+                const parentVal = row[fieldName];
+                if (typeof parentVal !== 'number')
+                    continue;
+                let sum = 0;
+                let allNumeric = true;
+                for (const item of relVal) {
+                    const v = item && typeof item === 'object' ? item[fieldName] : undefined;
+                    if (typeof v !== 'number') {
+                        allNumeric = false;
+                        break;
+                    }
+                    sum += v;
+                }
+                if (!allNumeric)
+                    continue; // partial/missing data — never guess, same principle as evaluateCondition
+                // Float-tolerant: Decimal fields commonly arrive as floating-point
+                // numbers, where exact equality would misreport ordinary rounding
+                // as a "violation" on every single request.
+                const held = Math.abs(parentVal - sum) < 1e-6 * Math.max(1, Math.abs(parentVal));
+                reporter.record(modelName, fieldName, field.name, held);
+            }
+        }
+    }
+}
+const BULK_WRITE_OPS = new Set(['updateMany', 'deleteMany', 'createMany']);
+// Write-pattern anomalies, row-count-drift slice: baselines the
+// affected-row count of a bulk write (updateMany/deleteMany/createMany —
+// a single update/delete/create always affects exactly 1 row or throws,
+// nothing to baseline there) per (route, operation:model), and flags a
+// live count implausibly far from it — "0 rows where normally ~3" and
+// "50,000 rows where normally ~5" are the same phenomenon, just opposite
+// ends of one baseline. Reuses isDrift and the DistributionDriftReporter/
+// DistributionBaselinePoller classes directly from distributionDrift.ts —
+// see that module's doc comment on WriteCountDrift for why this needs no
+// new statistical machinery, only a new observation site and a second
+// pair of instances pointed at a separate endpoint. Recording is
+// unconditional (same reasoning as observeInferredInvariants/
+// checkDistributionDriftIfAny — the baseline must already be populated by
+// the time an admin opts in); only the CAPTURE side gates on the polled
+// enabled flag, and hits push onto ctx for wrapResponse to drain and
+// capture at response time (the same deferred-capture shape
+// applyInvariantRules already uses via businessInvariantHits) rather than
+// capturing directly from inside the Prisma extension.
+function observeWriteCountDrift(ctx, model, operation, result, reporter, poller) {
+    if (!BULK_WRITE_OPS.has(operation))
+        return;
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        return;
+    const count = result.count;
+    if (typeof count !== 'number')
+        return;
+    const req = ctx.rawRequest;
+    const routePattern = req?.route?.path;
+    if (!routePattern)
+        return; // no stable key to group on
+    const route = `${ctx.request.method} ${routePattern}`;
+    const key = `${operation}:${model}`;
+    reporter.record(route, key, count);
+    if (!poller.isEnabled())
+        return;
+    const baseline = poller.getBaseline(route, key);
+    if (!baseline || !(0, distributionDrift_js_1.isDrift)(count, baseline))
+        return;
+    if (ctx.writeCountDriftHits.some((h) => h.route === route && h.model === model && h.operation === operation))
+        return;
+    ctx.writeCountDriftHits.push({ route, model, operation });
+}
+// Shared with legacyPrisma.ts's instrumentLegacyPrismaClient, which has its
+// own copy of this same set for the exact same reason: a rejected read has
+// no "what would have been written" story, so only writes get a footprint
+// entry when the database rejects them.
+const WRITE_OPS = new Set(['create', 'createMany', 'update', 'updateMany', 'upsert', 'delete', 'deleteMany']);
+function isWriteOperation(operation) {
+    return WRITE_OPS.has(operation);
+}
+// Column NAMES only — never the bound values (the too-long username, the
+// duplicate email), which are row data and must never enter a footprint per
+// the metadata-only rule. Mirrors typeorm.ts's parseFailedWrite and
+// legacyPrisma.ts's recordFailedWrite; this is the version createPrismaExtension's
+// $allOperations uses for modern ($extends-capable) clients, whose failed
+// queries previously left no trace at all — `$allOperations` only had a
+// `.then()`, no rejection handler, so a write the database rejected (a
+// unique-constraint violation, a length-limited column, a FK violation)
+// silently vanished from the footprint even though it's often exactly the
+// query that explains the bug.
+function recordFailedWrite(ctx, model, operation, args) {
+    const data = args.data;
+    const where = args.where;
+    const columns = [...new Set([...(data ? Object.keys(data) : []), ...(where ? Object.keys(where) : [])])];
+    ctx.footprint.push({
+        model,
+        op: `${operation}_failed`,
+        pks: [],
+        count: 0,
+        where_shape: columns.length ? columns.join(',') : undefined,
+        note: 'rejected by database — see error for reason',
+    });
+}
+// The one place a completed Prisma operation (result in hand, whatever
+// hooked into its lifecycle) gets turned into a footprint entry and run
+// through every detector. Shared by BOTH createPrismaExtension's
+// $allOperations (clients with $extends) and legacyPrisma.ts's
+// instrumentLegacyPrismaClient (clients with neither $extends nor $use —
+// confirmed live against a real @prisma/client@2.0.0-beta.4, which has
+// none of Prisma's query-lifecycle hooks at all) — same recording logic
+// regardless of how the installed client exposes its queries. `args` here
+// is whatever the model delegate method itself was called with (where/data/
+// select/include), same shape on every Prisma version.
+async function recordPrismaOperation(ctx, model, operation, args, result, hooks) {
+    const { dmmf, getRules, inferenceReporter, writeCountDriftReporter, writeCountBaselinePoller } = hooks;
+    const pkFields = dmmf ? getPkFields(dmmf, model) : ['id'];
+    const pks = extractPks(result, pkFields);
+    const count = Array.isArray(result) ? result.length : (result !== null && result !== undefined ? 1 : 0);
+    const whereShape = args.where ? (0, shape_js_1.shapeArgs)(args.where) : undefined;
+    ctx.footprint.push({
+        model,
+        op: operation,
+        pks,
+        where_shape: whereShape,
+        count,
+        note: count === 0 ? 'returned 0 rows' : undefined,
+    });
+    for (const nested of extractNestedFootprints(dmmf, model, result)) {
+        ctx.footprint.push(nested);
+    }
+    if (getRules) {
+        await applyInvariantRules(ctx, getRules(), model, operation, result, pkFields);
+    }
+    if (inferenceReporter) {
+        observeInferredInvariants(dmmf, model, result, inferenceReporter);
+    }
+    if (writeCountDriftReporter && writeCountBaselinePoller) {
+        observeWriteCountDrift(ctx, model, operation, result, writeCountDriftReporter, writeCountBaselinePoller);
+    }
+}
+// Creates the Reprova Prisma client extension. getRules returns the SDK's
+// live-cached business-invariant rules (RulesPoller) — read on every query
+// rather than captured once, so a rule enabled/edited in the dashboard
+// takes effect on the next poll without touching this extension.
+// Usage: const prisma = new PrismaClient().$extends(reprova.prismaExtension())
+function createPrismaExtension(dmmf, getRules, inferenceReporter, writeCountDriftReporter, writeCountBaselinePoller) {
+    return {
+        name: 'reprova-footprint',
+        query: {
+            $allOperations({ model, operation, args, query }) {
+                const ctx = context_js_1.contextStorage.getStore();
+                return query(args).then(async (result) => {
+                    if (!ctx)
+                        return result;
+                    // Handle raw queries
+                    if (model === undefined || operation === '$queryRaw' || operation === '$executeRaw') {
+                        const sqlText = Array.isArray(args) ? String(args[0]) : '[raw]';
+                        ctx.footprint.push({
+                            model: '$raw',
+                            op: operation,
+                            pks: [],
+                            count: 0,
+                            note: 'raw query — partial coverage',
+                            where_shape: sqlText.replace(/\$\d+/g, '?'),
+                        });
+                        return result;
+                    }
+                    await recordPrismaOperation(ctx, model, operation, args, result, {
+                        dmmf,
+                        getRules,
+                        inferenceReporter,
+                        writeCountDriftReporter,
+                        writeCountBaselinePoller,
+                    });
+                    return result;
+                }, 
+                // The two-argument form of .then (not a chained .catch) so a
+                // throw from the success branch above never gets mistaken for a
+                // rejected query. Only writes get a footprint entry here — same
+                // "no what-would-have-been-read story" reasoning as the legacy
+                // adapters — and the original error is always rethrown unchanged.
+                (err) => {
+                    if (ctx && model !== undefined && isWriteOperation(operation)) {
+                        recordFailedWrite(ctx, model, operation, args);
+                    }
+                    throw err;
+                });
+            },
+        },
+    };
+}

package/dist/cjs/proto.gen.js

@@ -0,0 +1,4 @@
+"use strict";
+// Code generated by scripts/gen-ts-types.mjs — DO NOT EDIT MANUALLY
+// Source: proto/schemas/*.json
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/registry.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerContext = registerContext;
+exports.completeContext = completeContext;
+exports.findContextByTraceId = findContextByTraceId;
+exports.snapshotCohort = snapshotCohort;
+exports.resetRegistryForTests = resetRegistryForTests;
+const stack_js_1 = require("./stack.js");
+const active = new Set();
+const recent = [];
+// Recovery index for when AsyncLocalStorage's active store has gone missing
+// partway through a request — keyed by traceId rather than object identity,
+// because the framework layer that lost the ALS store may ALSO have
+// constructed a brand-new request object with no reference in common with
+// the one instrumentHttpServers saw (Next.js App Router builds its own Fetch
+// API Request rather than reusing the raw http.IncomingMessage; Pages Router
+// and Express-style frameworks mutate the SAME object instead, which is what
+// ctxByRequest in sdk.ts already handles). traceId survives that boundary
+// because contextFromIncoming writes the resolved value back onto the raw
+// request's headers before handing off to whatever dispatches next — any
+// correct request implementation must copy incoming headers, so the injected
+// traceparent is guaranteed to reach a freshly-constructed request even when
+// object identity doesn't. See nextjs.ts's wrapRouteHandler for the consumer.
+const byTraceId = new Map();
+const RECENT_CAP = 16;
+const RETENTION_MS = 5000;
+const COHORT_CAP = 8; // must match capture_payload.json's maxItems
+const BODY_CAP = 16 * 1024;
+const FOOTPRINT_QUERY_CAP = 200;
+function registerContext(ctx) {
+    active.add(ctx);
+    byTraceId.set(ctx.traceId, ctx);
+}
+function completeContext(ctx) {
+    // 'finish' and 'close' can both fire for one response — only move once.
+    if (!active.delete(ctx))
+        return;
+    if (byTraceId.get(ctx.traceId) === ctx)
+        byTraceId.delete(ctx.traceId);
+    recent.push({ ctx, endedAt: new Date() });
+    const cutoff = Date.now() - RETENTION_MS;
+    while (recent.length > RECENT_CAP || (recent.length > 0 && recent[0].endedAt.getTime() < cutoff)) {
+        recent.shift();
+    }
+}
+// Looks up a still-in-flight context by its traceId. Returns undefined once
+// the request has completed (completeContext already removed it) — recovery
+// only ever targets a request that is still being handled.
+function findContextByTraceId(traceId) {
+    return byTraceId.get(traceId);
+}
+// snapshotCohort returns every other request that overlapped the failing one:
+// all currently-active contexts, plus recently-completed ones that ended at or
+// after the failing request started (their writes shaped the state the failing
+// request saw). offset_ms is signed: negative = started before the failing
+// request. Sorted nearest-first, capped at COHORT_CAP.
+function snapshotCohort(failing) {
+    const failingStart = failing.capturedAt.getTime();
+    const out = [];
+    for (const ctx of active) {
+        if (ctx === failing)
+            continue;
+        out.push(toSnapshot(ctx, failingStart, 'in_flight'));
+    }
+    const cutoff = Date.now() - RETENTION_MS;
+    for (const { ctx, endedAt } of recent) {
+        if (ctx === failing)
+            continue;
+        if (endedAt.getTime() < cutoff)
+            continue;
+        if (endedAt.getTime() < failingStart)
+            continue; // ended before the failing request began — no overlap
+        out.push(toSnapshot(ctx, failingStart, 'completed', endedAt));
+    }
+    out.sort((a, b) => Math.abs(a.offset_ms) - Math.abs(b.offset_ms));
+    return out.slice(0, COHORT_CAP);
+}
+function toSnapshot(ctx, failingStart, state, endedAt) {
+    const startMs = ctx.capturedAt.getTime();
+    return {
+        trace_id: ctx.traceId,
+        offset_ms: startMs - failingStart,
+        state,
+        duration_ms: endedAt ? endedAt.getTime() - startMs : undefined,
+        request: {
+            method: ctx.request.method,
+            path: ctx.request.path,
+            headers: (0, stack_js_1.stripHeaders)(ctx.request.headers),
+            body: ctx.request.body.slice(0, BODY_CAP),
+            auth_claims: ctx.request.authClaims,
+        },
+        data_footprint: ctx.footprint.length > 0 ? { queries: ctx.footprint.slice(0, FOOTPRINT_QUERY_CAP) } : undefined,
+    };
+}
+// Test hook: clears all registry state between tests.
+function resetRegistryForTests() {
+    active.clear();
+    byTraceId.clear();
+    recent.length = 0;
+}