@reprova/sdk 0.5.0 → 0.6.0

package/dist/cjs/idempotency.js

@@ -0,0 +1,132 @@
+"use strict";
+// Idempotency/consistency checks: two independent, domain-agnostic
+// detectors for "silent 200" bugs, unlike business-invariant rules — neither
+// needs a dashboard-authored condition tree, since neither depends on
+// knowing anything about the app's data model.
+//
+// 1. Idempotency-key mismatch: the app itself asserts two requests are "the
+//    same operation" by sending an identical value in a known header (e.g.
+//    Stripe-style Idempotency-Key). If the response differs between them,
+//    that's unambiguously a bug — no heuristic tuning needed, the app told
+//    us these should match.
+// 2. Duplicate-read mismatch: the SAME GET (route + query + caller
+//    identity) repeated within a short window returning a different
+//    result. Real false-positive risk exists here (data can legitimately
+//    change between two reads), so it's scoped tight: a short window turns
+//    it into "did two near-simultaneous reads of what should be the same
+//    snapshot disagree" (a race-condition/double-fetch signal), not general
+//    staleness detection — and it's skipped entirely when no caller
+//    identity is available, since an identity-less GET trivially disagrees
+//    across different callers.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HashMismatchCache = exports.DuplicateReadMismatch = exports.IdempotencyKeyMismatch = exports.DEFAULT_IDEMPOTENCY_SETTINGS = void 0;
+exports.hashResponseBody = hashResponseBody;
+exports.findIdempotencyKey = findIdempotencyKey;
+exports.extractIdentity = extractIdentity;
+const node_crypto_1 = require("node:crypto");
+// Mirrors the control plane's idempotency_settings table defaults — used
+// before the first successful poll, and if polling never succeeds at all
+// (e.g. an older control plane without this endpoint yet).
+exports.DEFAULT_IDEMPOTENCY_SETTINGS = {
+    key_check_enabled: true,
+    header_names: ['Idempotency-Key', 'X-Idempotency-Key'],
+    ttl_ms: 86_400_000,
+    max_keys: 100_000,
+    duplicate_read_enabled: false,
+    duplicate_read_window_ms: 500,
+};
+// One reusable Error class per detector, mirroring BusinessInvariantViolation
+// — per-endpoint identity comes from capture()'s errorType override, not a
+// per-instance subclass, so many distinct endpoints share one class without
+// collapsing into a single issue.
+class IdempotencyKeyMismatch extends Error {
+}
+exports.IdempotencyKeyMismatch = IdempotencyKeyMismatch;
+class DuplicateReadMismatch extends Error {
+}
+exports.DuplicateReadMismatch = DuplicateReadMismatch;
+// Deterministic regardless of key insertion order, so { a:1, b:2 } and
+// { b:2, a:1 } hash identically — otherwise two genuinely-equivalent
+// responses serialized in a different key order would look like a mismatch
+// that isn't one.
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
+}
+function hashResponseBody(body) {
+    return (0, node_crypto_1.createHash)('sha256').update(stableStringify(body)).digest('hex');
+}
+// Bounded signature -> last-seen-hash cache with TTL + LRU eviction, shared
+// by both detectors — the underlying mechanism ("has this signature's hash
+// changed within its window") is identical for both; only what goes into
+// the signature and how long it's remembered differs. Map iteration order
+// is insertion order, and delete-then-reinsert on every access keeps it in
+// least-recently-used order, so eviction always drops the LRU entry.
+class HashMismatchCache {
+    maxKeys;
+    ttlMs;
+    map = new Map();
+    constructor(maxKeys, ttlMs) {
+        this.maxKeys = maxKeys;
+        this.ttlMs = ttlMs;
+    }
+    // Settings can change on every poll — reconfigure in place rather than
+    // recreating the cache, so a TTL/cap edit doesn't silently drop everything
+    // currently tracked.
+    configure(maxKeys, ttlMs) {
+        this.maxKeys = maxKeys;
+        this.ttlMs = ttlMs;
+    }
+    // Records `hash` for `signature`, returning true if a live (non-expired)
+    // prior hash for the same signature exists and differs from this one.
+    checkAndRecord(signature, hash, now = Date.now()) {
+        const existing = this.map.get(signature);
+        this.map.delete(signature); // re-inserted below either way, refreshing LRU order
+        const mismatch = !!existing && existing.expiresAt > now && existing.hash !== hash;
+        this.map.set(signature, { hash, expiresAt: now + this.ttlMs });
+        while (this.map.size > this.maxKeys) {
+            const oldest = this.map.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.map.delete(oldest);
+        }
+        return mismatch;
+    }
+    get size() {
+        return this.map.size;
+    }
+}
+exports.HashMismatchCache = HashMismatchCache;
+// Checks each configured header name case-insensitively — Node normalizes
+// incoming header names to lowercase, and captureHeaders (stack.ts) passes
+// that through unchanged, so ctx.request.headers keys are already lowercase.
+function findIdempotencyKey(headers, headerNames) {
+    for (const name of headerNames) {
+        const value = headers[name.toLowerCase()];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+// A small, conventional set of claim keys checked in order — not exhaustive,
+// just enough to cover common shapes (Auth0/JWT `sub`, a plain `id`,
+// Passport-style `userId`/`user_id`). Returns undefined, never a guess, when
+// none match: duplicate-read detection is skipped entirely without an
+// identity, rather than risk comparing two different callers' data and
+// calling the difference a bug.
+const IDENTITY_CLAIM_KEYS = ['sub', 'id', 'userId', 'user_id'];
+function extractIdentity(authClaims) {
+    if (!authClaims)
+        return undefined;
+    for (const key of IDENTITY_CLAIM_KEYS) {
+        const value = authClaims[key];
+        if (typeof value === 'string' || typeof value === 'number')
+            return String(value);
+    }
+    return undefined;
+}

package/dist/cjs/idempotencySettingsPoller.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotencySettingsPoller = void 0;
+const idempotency_js_1 = require("./idempotency.js");
+const httpFetch_js_1 = require("./httpFetch.js");
+const WARN_INTERVAL_MS = 60_000;
+// Same start()/stop()/setInterval+unref shape as RulesPoller — periodically
+// fetches the tenant's dashboard-configured idempotency-check settings so a
+// toggle flipped in the dashboard reaches a running process without a
+// redeploy. Falls back to DEFAULT_IDEMPOTENCY_SETTINGS before the first
+// successful poll and keeps the last-known-good settings on any failure,
+// never throwing and never leaving the detectors unconfigured.
+class IdempotencySettingsPoller {
+    settings = idempotency_js_1.DEFAULT_IDEMPOTENCY_SETTINGS;
+    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(); // don't wait a full interval before settings are usable
+        this.timer = setInterval(() => void this.refresh(), this.intervalMs);
+        if (this.timer.unref)
+            this.timer.unref(); // don't block process exit
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    getSettings() {
+        return this.settings;
+    }
+    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: idempotency settings fetch returned ${res.status}`);
+                return;
+            }
+            this.seed((await res.json()));
+        }
+        catch (err) {
+            this.warnOnce(`reprova: idempotency settings fetch error: ${err.message}`);
+        }
+    }
+    // Applies an already-fetched settings object 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 checkIdempotencyIfAny (sdk.ts) sees exactly the same
+    // shape it would from a real refresh().
+    seed(settings) {
+        this.settings = settings;
+    }
+    warnOnce(msg) {
+        const now = Date.now();
+        if (now - this.lastWarnAt > WARN_INTERVAL_MS) {
+            this.lastWarnAt = now;
+            console.warn(msg);
+        }
+    }
+}
+exports.IdempotencySettingsPoller = IdempotencySettingsPoller;

package/dist/cjs/index.js

@@ -0,0 +1,96 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDrift = exports.updateWelfordState = exports.newWelfordState = exports.WriteCountDrift = exports.ValueDistributionDrift = exports.InferenceReporter = exports.IdempotencySettingsPoller = exports.hashResponseBody = exports.extractIdentity = exports.findIdempotencyKey = exports.DuplicateReadMismatch = exports.IdempotencyKeyMismatch = exports.HashMismatchCache = exports.DEFAULT_IDEMPOTENCY_SETTINGS = exports.RulesPoller = exports.BusinessInvariantViolation = exports.operationMatchesHook = exports.evaluateInvariant = exports.compileInvariant = exports.PotentialRetryStorm = exports.describeRetryStorm = exports.detectRetryStorm = exports.PotentialNPlusOneQuery = exports.describeNPlusOne = exports.detectNPlusOne = exports.createDrizzleFootprint = exports.createDrizzleCache = exports.createDrizzleLogger = exports.createNextAdapter = exports.createNestContextInterceptor = exports.createNestExceptionFilter = exports.installKnexHooks = exports.MongoSchemaReporter = exports.discoverMongooseSchema = exports.reprovaMongoosePlugin = exports.installMikroOrmSubscriber = exports.installTypeOrmQueryLogger = exports.installTypeOrmSubscriber = exports.installSequelizeHooks = exports.createKyselyPlugin = exports.instrumentLegacyPrismaClient = exports.recordPrismaOperation = exports.createPrismaExtension = exports.setAuthClaims = exports.currentContext = exports.contextStorage = exports.replayErrorHandler = exports.forwardAsyncErrors = exports.wrapResponse = exports.Reprova = void 0;
+exports.SDK_VERSION = exports.DistributionBaselinePoller = exports.DistributionDriftReporter = exports.extractTopLevelNumericFields = void 0;
+var sdk_js_1 = require("./sdk.js");
+Object.defineProperty(exports, "Reprova", { enumerable: true, get: function () { return sdk_js_1.Reprova; } });
+Object.defineProperty(exports, "wrapResponse", { enumerable: true, get: function () { return sdk_js_1.wrapResponse; } });
+Object.defineProperty(exports, "forwardAsyncErrors", { enumerable: true, get: function () { return sdk_js_1.forwardAsyncErrors; } });
+Object.defineProperty(exports, "replayErrorHandler", { enumerable: true, get: function () { return sdk_js_1.replayErrorHandler; } });
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "contextStorage", { enumerable: true, get: function () { return context_js_1.contextStorage; } });
+Object.defineProperty(exports, "currentContext", { enumerable: true, get: function () { return context_js_1.currentContext; } });
+Object.defineProperty(exports, "setAuthClaims", { enumerable: true, get: function () { return context_js_1.setAuthClaims; } });
+var prisma_js_1 = require("./prisma.js");
+Object.defineProperty(exports, "createPrismaExtension", { enumerable: true, get: function () { return prisma_js_1.createPrismaExtension; } });
+Object.defineProperty(exports, "recordPrismaOperation", { enumerable: true, get: function () { return prisma_js_1.recordPrismaOperation; } });
+var legacyPrisma_js_1 = require("./legacyPrisma.js");
+Object.defineProperty(exports, "instrumentLegacyPrismaClient", { enumerable: true, get: function () { return legacyPrisma_js_1.instrumentLegacyPrismaClient; } });
+var kysely_js_1 = require("./kysely.js");
+Object.defineProperty(exports, "createKyselyPlugin", { enumerable: true, get: function () { return kysely_js_1.createKyselyPlugin; } });
+var sequelize_js_1 = require("./sequelize.js");
+Object.defineProperty(exports, "installSequelizeHooks", { enumerable: true, get: function () { return sequelize_js_1.installSequelizeHooks; } });
+var typeorm_js_1 = require("./typeorm.js");
+Object.defineProperty(exports, "installTypeOrmSubscriber", { enumerable: true, get: function () { return typeorm_js_1.installTypeOrmSubscriber; } });
+Object.defineProperty(exports, "installTypeOrmQueryLogger", { enumerable: true, get: function () { return typeorm_js_1.installTypeOrmQueryLogger; } });
+var mikroorm_js_1 = require("./mikroorm.js");
+Object.defineProperty(exports, "installMikroOrmSubscriber", { enumerable: true, get: function () { return mikroorm_js_1.installMikroOrmSubscriber; } });
+var mongoose_js_1 = require("./mongoose.js");
+Object.defineProperty(exports, "reprovaMongoosePlugin", { enumerable: true, get: function () { return mongoose_js_1.reprovaMongoosePlugin; } });
+Object.defineProperty(exports, "discoverMongooseSchema", { enumerable: true, get: function () { return mongoose_js_1.discoverMongooseSchema; } });
+var mongoSchemaReporter_js_1 = require("./mongoSchemaReporter.js");
+Object.defineProperty(exports, "MongoSchemaReporter", { enumerable: true, get: function () { return mongoSchemaReporter_js_1.MongoSchemaReporter; } });
+var knex_js_1 = require("./knex.js");
+Object.defineProperty(exports, "installKnexHooks", { enumerable: true, get: function () { return knex_js_1.installKnexHooks; } });
+var nest_js_1 = require("./nest.js");
+Object.defineProperty(exports, "createNestExceptionFilter", { enumerable: true, get: function () { return nest_js_1.createNestExceptionFilter; } });
+Object.defineProperty(exports, "createNestContextInterceptor", { enumerable: true, get: function () { return nest_js_1.createNestContextInterceptor; } });
+var nextjs_js_1 = require("./nextjs.js");
+Object.defineProperty(exports, "createNextAdapter", { enumerable: true, get: function () { return nextjs_js_1.createNextAdapter; } });
+var drizzle_js_1 = require("./drizzle.js");
+Object.defineProperty(exports, "createDrizzleLogger", { enumerable: true, get: function () { return drizzle_js_1.createDrizzleLogger; } });
+Object.defineProperty(exports, "createDrizzleCache", { enumerable: true, get: function () { return drizzle_js_1.createDrizzleCache; } });
+Object.defineProperty(exports, "createDrizzleFootprint", { enumerable: true, get: function () { return drizzle_js_1.createDrizzleFootprint; } });
+var nPlusOne_js_1 = require("./nPlusOne.js");
+Object.defineProperty(exports, "detectNPlusOne", { enumerable: true, get: function () { return nPlusOne_js_1.detectNPlusOne; } });
+Object.defineProperty(exports, "describeNPlusOne", { enumerable: true, get: function () { return nPlusOne_js_1.describeNPlusOne; } });
+Object.defineProperty(exports, "PotentialNPlusOneQuery", { enumerable: true, get: function () { return nPlusOne_js_1.PotentialNPlusOneQuery; } });
+var retryStorm_js_1 = require("./retryStorm.js");
+Object.defineProperty(exports, "detectRetryStorm", { enumerable: true, get: function () { return retryStorm_js_1.detectRetryStorm; } });
+Object.defineProperty(exports, "describeRetryStorm", { enumerable: true, get: function () { return retryStorm_js_1.describeRetryStorm; } });
+Object.defineProperty(exports, "PotentialRetryStorm", { enumerable: true, get: function () { return retryStorm_js_1.PotentialRetryStorm; } });
+var invariantRules_js_1 = require("./invariantRules.js");
+Object.defineProperty(exports, "compileInvariant", { enumerable: true, get: function () { return invariantRules_js_1.compileInvariant; } });
+Object.defineProperty(exports, "evaluateInvariant", { enumerable: true, get: function () { return invariantRules_js_1.evaluateInvariant; } });
+Object.defineProperty(exports, "operationMatchesHook", { enumerable: true, get: function () { return invariantRules_js_1.operationMatchesHook; } });
+Object.defineProperty(exports, "BusinessInvariantViolation", { enumerable: true, get: function () { return invariantRules_js_1.BusinessInvariantViolation; } });
+var rulesPoller_js_1 = require("./rulesPoller.js");
+Object.defineProperty(exports, "RulesPoller", { enumerable: true, get: function () { return rulesPoller_js_1.RulesPoller; } });
+var idempotency_js_1 = require("./idempotency.js");
+Object.defineProperty(exports, "DEFAULT_IDEMPOTENCY_SETTINGS", { enumerable: true, get: function () { return idempotency_js_1.DEFAULT_IDEMPOTENCY_SETTINGS; } });
+Object.defineProperty(exports, "HashMismatchCache", { enumerable: true, get: function () { return idempotency_js_1.HashMismatchCache; } });
+Object.defineProperty(exports, "IdempotencyKeyMismatch", { enumerable: true, get: function () { return idempotency_js_1.IdempotencyKeyMismatch; } });
+Object.defineProperty(exports, "DuplicateReadMismatch", { enumerable: true, get: function () { return idempotency_js_1.DuplicateReadMismatch; } });
+Object.defineProperty(exports, "findIdempotencyKey", { enumerable: true, get: function () { return idempotency_js_1.findIdempotencyKey; } });
+Object.defineProperty(exports, "extractIdentity", { enumerable: true, get: function () { return idempotency_js_1.extractIdentity; } });
+Object.defineProperty(exports, "hashResponseBody", { enumerable: true, get: function () { return idempotency_js_1.hashResponseBody; } });
+var idempotencySettingsPoller_js_1 = require("./idempotencySettingsPoller.js");
+Object.defineProperty(exports, "IdempotencySettingsPoller", { enumerable: true, get: function () { return idempotencySettingsPoller_js_1.IdempotencySettingsPoller; } });
+var invariantInference_js_1 = require("./invariantInference.js");
+Object.defineProperty(exports, "InferenceReporter", { enumerable: true, get: function () { return invariantInference_js_1.InferenceReporter; } });
+var distributionDrift_js_1 = require("./distributionDrift.js");
+Object.defineProperty(exports, "ValueDistributionDrift", { enumerable: true, get: function () { return distributionDrift_js_1.ValueDistributionDrift; } });
+Object.defineProperty(exports, "WriteCountDrift", { enumerable: true, get: function () { return distributionDrift_js_1.WriteCountDrift; } });
+Object.defineProperty(exports, "newWelfordState", { enumerable: true, get: function () { return distributionDrift_js_1.newWelfordState; } });
+Object.defineProperty(exports, "updateWelfordState", { enumerable: true, get: function () { return distributionDrift_js_1.updateWelfordState; } });
+Object.defineProperty(exports, "isDrift", { enumerable: true, get: function () { return distributionDrift_js_1.isDrift; } });
+Object.defineProperty(exports, "extractTopLevelNumericFields", { enumerable: true, get: function () { return distributionDrift_js_1.extractTopLevelNumericFields; } });
+Object.defineProperty(exports, "DistributionDriftReporter", { enumerable: true, get: function () { return distributionDrift_js_1.DistributionDriftReporter; } });
+var distributionBaselinePoller_js_1 = require("./distributionBaselinePoller.js");
+Object.defineProperty(exports, "DistributionBaselinePoller", { enumerable: true, get: function () { return distributionBaselinePoller_js_1.DistributionBaselinePoller; } });
+__exportStar(require("./proto.gen.js"), exports);
+exports.SDK_VERSION = '0.1.0';

package/dist/cjs/invariantInference.js

@@ -0,0 +1,90 @@
+"use strict";
+// Invariant inference, v1 slice: instead of hand-authoring a
+// business-invariant-rule condition tree, passively observe whether a
+// same-named numeric field on a parent row equals the sum of that same
+// field across an already-included to-many relation (Invoice.total vs
+// sum(lineItems.total)) — and report pass/fail counts to the control plane.
+// Once a candidate has been observed enough times at a high enough pass
+// rate, the dashboard offers it as a one-click "confirm" that creates a
+// normal business_invariant_rule — no new evaluation mechanism needed once
+// confirmed, it becomes an ordinary dashboard-authored rule.
+//
+// Deliberately scoped down from the general idea: only the same-field-name
+// shape (not every numeric-field-pair combination, which would be
+// combinatorial and noisy), only `sum` (no `count`), and no dashboard-
+// configurable thresholds yet — see PROGRESS.md for the fuller design this
+// is a first slice of.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InferenceReporter = void 0;
+const httpFetch_js_1 = require("./httpFetch.js");
+const WARN_INTERVAL_MS = 60_000;
+// Reports observation deltas, not cumulative totals — the control plane
+// owns the running (checked_count, held_count) per candidate; the SDK only
+// ever adds to it. That makes a dropped/failed flush harmless to correctness
+// (the next flush's delta is unaffected by a prior one failing) at the cost
+// of only ever undercounting on a genuine send failure, never overcounting.
+class InferenceReporter {
+    counts = 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(); // don't block process exit
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    record(model, field, relation, held) {
+        const key = `${model}\x00${field}\x00${relation}`;
+        let c = this.counts.get(key);
+        if (!c) {
+            c = { model, field, relation, checked: 0, held: 0 };
+            this.counts.set(key, c);
+        }
+        c.checked++;
+        if (held)
+            c.held++;
+    }
+    async flush() {
+        if (this.counts.size === 0)
+            return;
+        const observations = [...this.counts.values()];
+        this.counts.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: inferred-invariant observation report returned ${res.status}`);
+            }
+        }
+        catch (err) {
+            this.warnOnce(`reprova: inferred-invariant observation report error: ${err.message}`);
+        }
+    }
+    warnOnce(msg) {
+        const now = Date.now();
+        if (now - this.lastWarnAt > WARN_INTERVAL_MS) {
+            this.lastWarnAt = now;
+            console.warn(msg);
+        }
+    }
+}
+exports.InferenceReporter = InferenceReporter;

package/dist/cjs/invariantRules.js

@@ -0,0 +1,142 @@
+"use strict";
+// Dashboard-authored business-invariant rules: CEL (Common Expression
+// Language) expressions evaluated in-process against real Prisma query
+// results (not just the footprint's PKs/counts — actual field values), so
+// bugs that never throw and never return a 5xx (an invoice total that
+// silently drifted from its line items, negative inventory, an order marked
+// shipped with no shipment row) can still produce a reproduction.
+//
+// Replaces an earlier JSON condition-tree evaluator (see git history) — CEL
+// gives the same same-row-comparison-and-relation-aggregate expressiveness
+// with a much friendlier authoring surface (`total ==
+// lineItems.map(x, x.total).sum()` instead of a nested op/field/right tree),
+// using the actively-maintained, zero-dependency @marcbachmann/cel-js.
+//
+// `expr` is the INVARIANT itself — what should always be true — not the
+// violation condition: a rule fires when `expr` evaluates to exactly
+// `false`. This is the opposite polarity from the old JSON tree (which
+// encoded the violation, e.g. `not: eq(...)`), but reads naturally in CEL
+// and matches how an admin would actually describe the rule out loud.
+//
+// A field or relation the app's own query didn't `include` simply isn't a
+// key on the row object, which CEL reports as a runtime "no such attribute"
+// error rather than `false` — evaluateInvariant treats any evaluation error,
+// and any non-boolean result (an author mistake, e.g. forgetting a
+// comparison operator), as "can't evaluate" and skips, never firing a false
+// violation on data the query simply didn't load. Same principle
+// `invariantInference.ts`/`distributionDrift.ts` use: never guess.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BusinessInvariantViolation = void 0;
+exports.operationMatchesHook = operationMatchesHook;
+exports.compileInvariant = compileInvariant;
+exports.evaluateInvariant = evaluateInvariant;
+let envPromise = null;
+function loadEnv() {
+    if (!envPromise) {
+        envPromise = Promise.resolve().then(() => __importStar(require('@marcbachmann/cel-js'))).then(({ Environment }) => new Environment({ unlistedVariablesAreDyn: true }).registerFunction({
+            name: 'sum',
+            receiverType: 'list',
+            returnType: 'double',
+            handler: (list) => list.reduce((a, b) => a + b, 0),
+            params: [],
+        }))
+            .catch(() => null); // can't load the CEL engine at all — every rule silently never fires, never crashes the host app
+    }
+    return envPromise;
+}
+const READ_OPS = new Set(['findUnique', 'findUniqueOrThrow', 'findFirst', 'findFirstOrThrow', 'findMany']);
+const WRITE_OPS = new Set(['create', 'createMany', 'update', 'updateMany', 'upsert', 'delete', 'deleteMany']);
+// Whether a Prisma operation name belongs to the read/write class a rule's
+// when_hook asks to run on. Anything neither (e.g. $queryRaw, aggregate,
+// count, groupBy) never matches — a rule needs real field values on a real
+// row, which those don't uniformly provide.
+function operationMatchesHook(op, whenHook) {
+    return whenHook === 'after_read' ? READ_OPS.has(op) : WRITE_OPS.has(op);
+}
+// Compiled programs are cached by (rule id, expr) so an edited rule
+// recompiles (new expr under the same id misses the cache) while an
+// unchanged one is parsed exactly once for the life of the process — CEL
+// parsing is not free, and this runs on every matching query result.
+// Invalid CEL syntax caches a `null` miss rather than re-attempting the
+// same broken parse on every request. A CEL-engine load failure (see
+// loadEnv's own doc comment) is deliberately NOT cached here — that's a
+// process-wide condition already memoized by envPromise itself, not a
+// per-rule outcome, so a later rule with valid syntax isn't punished by an
+// earlier one's transient load timing.
+const compileCache = new Map();
+async function compileInvariant(rule) {
+    const key = `${rule.id}\x00${rule.expr}`;
+    if (compileCache.has(key))
+        return compileCache.get(key);
+    const env = await loadEnv();
+    if (!env)
+        return null;
+    let compiled;
+    try {
+        compiled = env.parse(rule.expr);
+    }
+    catch {
+        compiled = null; // invalid CEL — never crash the host app on a bad admin-authored rule
+    }
+    compileCache.set(key, compiled);
+    return compiled;
+}
+// Runs a compiled invariant against one row. Returns `false` only for a
+// genuine, cleanly-evaluated violation; `undefined` for anything else
+// (evaluation error from a missing field/relation, or a non-boolean result
+// from a malformed expression) so the caller never mistakes "couldn't tell"
+// for "violated".
+function evaluateInvariant(compiled, row) {
+    let result;
+    try {
+        result = compiled(row);
+    }
+    catch {
+        return undefined;
+    }
+    return typeof result === 'boolean' ? result : undefined;
+}
+// One reusable Error class for every rule violation. Per-rule identity comes
+// from capture()'s extra.errorType override (see sdk.ts), not from a
+// per-rule subclass — many rules can share this class without collapsing
+// into one issue, since fingerprinting keys off errorType, not the class
+// name, once errorType is supplied explicitly.
+class BusinessInvariantViolation extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+exports.BusinessInvariantViolation = BusinessInvariantViolation;

package/dist/cjs/knex.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installKnexHooks = installKnexHooks;
+const context_js_1 = require("./context.js");
+const OP_BY_METHOD = {
+    select: 'select',
+    first: 'select',
+    pluck: 'select',
+    insert: 'insert',
+    update: 'update',
+    del: 'delete',
+    delete: 'delete',
+};
+function isRowArray(v) {
+    return Array.isArray(v) && v.length > 0 && typeof v[0] === 'object' && v[0] !== null;
+}
+function distinct(values) {
+    const seen = new Set();
+    const out = [];
+    for (const v of values) {
+        if (!seen.has(v)) {
+            seen.add(v);
+            out.push(v);
+        }
+    }
+    return out;
+}
+function extractRowPks(rows, pkCols) {
+    if (pkCols.length === 0)
+        return [];
+    const out = [];
+    for (const row of rows) {
+        const vals = pkCols.map((c) => row[c]);
+        if (vals.some((v) => v === undefined || v === null))
+            continue;
+        out.push(vals.map((v) => String(v)).join(':'));
+    }
+    return distinct(out);
+}
+// Installs a footprint listener on a Knex instance. Also covers Objection.js
+// models bound to this same instance.
+function installKnexHooks(knex, opts = {}) {
+    const primaryKey = opts.primaryKey ?? (() => ['id']);
+    try {
+        knex.on('query-response', (response, obj, builder) => {
+            try {
+                const ctx = context_js_1.contextStorage.getStore();
+                if (!ctx)
+                    return;
+                const method = obj?.method ?? builder?._method;
+                const op = method ? OP_BY_METHOD[method] : undefined;
+                if (!op)
+                    return; // schema/DDL/raw — skip
+                const table = builder?._single?.table;
+                if (typeof table !== 'string' || !table)
+                    return;
+                let pks = [];
+                let count = 0;
+                if (isRowArray(response)) {
+                    pks = extractRowPks(response, primaryKey(table));
+                    count = response.length;
+                }
+                else if (Array.isArray(response)) {
+                    // Primitive array — insert returning ids (partial on sqlite/mysql).
+                    if (op === 'insert')
+                        pks = distinct(response.filter((v) => v != null).map((v) => String(v)));
+                    count = response.length;
+                }
+                else if (typeof response === 'number') {
+                    count = response; // affected-row count from update/delete
+                }
+                const entry = {
+                    model: table,
+                    op,
+                    pks,
+                    count,
+                    note: count === 0 ? 'returned 0 rows' : undefined,
+                    resolved: true,
+                };
+                ctx.footprint.push(entry);
+            }
+            catch { /* never break the query pipeline */ }
+        });
+    }
+    catch { /* never throw from install */ }
+}