@constructive-io/express-context 0.26.1 → 0.27.0

package/index.js

@@ -36,7 +36,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.webauthnLoader = exports.rlsLoader = exports.requireIdentityProvider = exports.requireDatabaseId = exports.pubkeyLoader = exports.llmLoader = exports.inferenceLogLoader = exports.identityProvidersLoader = exports.databaseSettingsLoader = exports.createModuleLoader = exports.createLoaderRegistry = exports.createDefaultRegistry = exports.corsLoader = exports.computeLoader = exports.billingLoader = exports.authSurfaceLoader = exports.authSettingsLoader = exports.agentChatLoader = exports.createContextMiddleware = exports.buildContext = exports.requestIdMiddleware = exports.withPgClient = exports.buildPgSettings = exports.createBillingClient = void 0;
+exports.webauthnLoader = exports.rlsLoader = exports.requireIdentityProvider = exports.requireDatabaseId = exports.requestProtectionLoader = exports.pubkeyLoader = exports.llmLoader = exports.inferenceLogLoader = exports.identityProvidersLoader = exports.databaseSettingsLoader = exports.createModuleLoader = exports.createLoaderRegistry = exports.createDefaultRegistry = exports.corsLoader = exports.computeLoader = exports.billingLoader = exports.authSurfaceLoader = exports.authSettingsLoader = exports.agentChatLoader = exports.createContextMiddleware = exports.buildContext = exports.requestIdMiddleware = exports.CounterFlusher = exports.BoundedCounter = exports.UNKNOWN_SOURCE = exports.sourceBucket = exports.refusalRows = exports.RefusalRecorder = exports.refusalOverflowKey = exports.refusalKeyOf = exports.REFUSAL_REASONS = exports.OVERFLOW_SOURCE = exports.OVERFLOW_ROUTE = exports.DEFAULT_REFUSAL_MAX_KEYS = exports.DEFAULT_REFUSAL_FLUSH_JITTER_MS = exports.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = exports.createRecordRefusalsSink = exports.trustedProxyHops = exports.RateWindow = exports.ConcurrencyLimiter = exports.clientIpFrom = exports.resolveRequestProtection = exports.protectionPgSettings = exports.PROTECTION_BOUNDS = exports.INTROSPECTION_BOUND = exports.DEFAULT_REQUEST_PROTECTION = exports.ASSUMED_PAGE_SIZE = exports.withPgClient = exports.buildPgSettings = exports.createBillingClient = void 0;
 var billing_client_1 = require("./billing-client");
 Object.defineProperty(exports, "createBillingClient", { enumerable: true, get: function () { return billing_client_1.createBillingClient; } });
 var pg_settings_1 = require("./pg-settings");
@@ -44,6 +44,35 @@ Object.defineProperty(exports, "buildPgSettings", { enumerable: true, get: funct
 // withPgClient helper
 var pg_client_1 = require("./pg-client");
 Object.defineProperty(exports, "withPgClient", { enumerable: true, get: function () { return pg_client_1.withPgClient; } });
+var request_protection_1 = require("./request-protection");
+Object.defineProperty(exports, "ASSUMED_PAGE_SIZE", { enumerable: true, get: function () { return request_protection_1.ASSUMED_PAGE_SIZE; } });
+Object.defineProperty(exports, "DEFAULT_REQUEST_PROTECTION", { enumerable: true, get: function () { return request_protection_1.DEFAULT_REQUEST_PROTECTION; } });
+Object.defineProperty(exports, "INTROSPECTION_BOUND", { enumerable: true, get: function () { return request_protection_1.INTROSPECTION_BOUND; } });
+Object.defineProperty(exports, "PROTECTION_BOUNDS", { enumerable: true, get: function () { return request_protection_1.PROTECTION_BOUNDS; } });
+Object.defineProperty(exports, "protectionPgSettings", { enumerable: true, get: function () { return request_protection_1.protectionPgSettings; } });
+Object.defineProperty(exports, "resolveRequestProtection", { enumerable: true, get: function () { return request_protection_1.resolveRequestProtection; } });
+var admission_1 = require("./admission");
+Object.defineProperty(exports, "clientIpFrom", { enumerable: true, get: function () { return admission_1.clientIpFrom; } });
+Object.defineProperty(exports, "ConcurrencyLimiter", { enumerable: true, get: function () { return admission_1.ConcurrencyLimiter; } });
+Object.defineProperty(exports, "RateWindow", { enumerable: true, get: function () { return admission_1.RateWindow; } });
+Object.defineProperty(exports, "trustedProxyHops", { enumerable: true, get: function () { return admission_1.trustedProxyHops; } });
+var refusals_1 = require("./refusals");
+Object.defineProperty(exports, "createRecordRefusalsSink", { enumerable: true, get: function () { return refusals_1.createRecordRefusalsSink; } });
+Object.defineProperty(exports, "DEFAULT_REFUSAL_FLUSH_INTERVAL_MS", { enumerable: true, get: function () { return refusals_1.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS; } });
+Object.defineProperty(exports, "DEFAULT_REFUSAL_FLUSH_JITTER_MS", { enumerable: true, get: function () { return refusals_1.DEFAULT_REFUSAL_FLUSH_JITTER_MS; } });
+Object.defineProperty(exports, "DEFAULT_REFUSAL_MAX_KEYS", { enumerable: true, get: function () { return refusals_1.DEFAULT_REFUSAL_MAX_KEYS; } });
+Object.defineProperty(exports, "OVERFLOW_ROUTE", { enumerable: true, get: function () { return refusals_1.OVERFLOW_ROUTE; } });
+Object.defineProperty(exports, "OVERFLOW_SOURCE", { enumerable: true, get: function () { return refusals_1.OVERFLOW_SOURCE; } });
+Object.defineProperty(exports, "REFUSAL_REASONS", { enumerable: true, get: function () { return refusals_1.REFUSAL_REASONS; } });
+Object.defineProperty(exports, "refusalKeyOf", { enumerable: true, get: function () { return refusals_1.refusalKeyOf; } });
+Object.defineProperty(exports, "refusalOverflowKey", { enumerable: true, get: function () { return refusals_1.refusalOverflowKey; } });
+Object.defineProperty(exports, "RefusalRecorder", { enumerable: true, get: function () { return refusals_1.RefusalRecorder; } });
+Object.defineProperty(exports, "refusalRows", { enumerable: true, get: function () { return refusals_1.refusalRows; } });
+Object.defineProperty(exports, "sourceBucket", { enumerable: true, get: function () { return refusals_1.sourceBucket; } });
+Object.defineProperty(exports, "UNKNOWN_SOURCE", { enumerable: true, get: function () { return refusals_1.UNKNOWN_SOURCE; } });
+var usage_counter_1 = require("./usage-counter");
+Object.defineProperty(exports, "BoundedCounter", { enumerable: true, get: function () { return usage_counter_1.BoundedCounter; } });
+Object.defineProperty(exports, "CounterFlusher", { enumerable: true, get: function () { return usage_counter_1.CounterFlusher; } });
 // Request ID middleware
 var request_id_1 = require("./request-id");
 Object.defineProperty(exports, "requestIdMiddleware", { enumerable: true, get: function () { return request_id_1.requestIdMiddleware; } });
@@ -65,6 +94,7 @@ Object.defineProperty(exports, "identityProvidersLoader", { enumerable: true, ge
 Object.defineProperty(exports, "inferenceLogLoader", { enumerable: true, get: function () { return loaders_1.inferenceLogLoader; } });
 Object.defineProperty(exports, "llmLoader", { enumerable: true, get: function () { return loaders_1.llmLoader; } });
 Object.defineProperty(exports, "pubkeyLoader", { enumerable: true, get: function () { return loaders_1.pubkeyLoader; } });
+Object.defineProperty(exports, "requestProtectionLoader", { enumerable: true, get: function () { return loaders_1.requestProtectionLoader; } });
 Object.defineProperty(exports, "requireDatabaseId", { enumerable: true, get: function () { return loaders_1.requireDatabaseId; } });
 Object.defineProperty(exports, "requireIdentityProvider", { enumerable: true, get: function () { return loaders_1.requireIdentityProvider; } });
 Object.defineProperty(exports, "rlsLoader", { enumerable: true, get: function () { return loaders_1.rlsLoader; } });

package/loaders/index.d.ts

@@ -9,6 +9,7 @@
  *   - rlsModule       (routing-plane rls_settings)
  *   - corsOrigins     (routing-plane cors_settings)
  *   - databaseSettings(routing-plane database_settings)
+ *   - requestProtection (routing-plane database_settings/api_settings bounds)
  *   - pubkeyChallengeSettings (routing-plane pubkey_settings)
  *   - webauthnSettings(routing-plane webauthn_settings)
  *   - authSettings    (metaschema_modules_public.sessions_module → tenant DB)
@@ -46,6 +47,7 @@ export { identityProvidersLoader, requireIdentityProvider } from './identity-pro
 export { inferenceLogLoader } from './inference-log';
 export { llmLoader } from './llm';
 export { pubkeyLoader } from './pubkey';
+export { requestProtectionLoader } from './request-protection';
 export { rlsLoader } from './rls';
 export { webauthnLoader } from './webauthn';
 export declare function createDefaultRegistry(): import("./registry").LoaderRegistry;

package/loaders/index.js

@@ -10,6 +10,7 @@
  *   - rlsModule       (routing-plane rls_settings)
  *   - corsOrigins     (routing-plane cors_settings)
  *   - databaseSettings(routing-plane database_settings)
+ *   - requestProtection (routing-plane database_settings/api_settings bounds)
  *   - pubkeyChallengeSettings (routing-plane pubkey_settings)
  *   - webauthnSettings(routing-plane webauthn_settings)
  *   - authSettings    (metaschema_modules_public.sessions_module → tenant DB)
@@ -31,7 +32,7 @@
  *   registry.register(myLoader);
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.webauthnLoader = exports.rlsLoader = exports.pubkeyLoader = exports.llmLoader = exports.inferenceLogLoader = exports.requireIdentityProvider = exports.identityProvidersLoader = exports.databaseSettingsLoader = exports.corsLoader = exports.computeLoader = exports.billingLoader = exports.authSurfaceLoader = exports.authSettingsLoader = exports.agentChatLoader = exports.createLoaderRegistry = exports.createModuleLoader = exports.requireDatabaseId = void 0;
+exports.webauthnLoader = exports.rlsLoader = exports.requestProtectionLoader = exports.pubkeyLoader = exports.llmLoader = exports.inferenceLogLoader = exports.requireIdentityProvider = exports.identityProvidersLoader = exports.databaseSettingsLoader = exports.corsLoader = exports.computeLoader = exports.billingLoader = exports.authSurfaceLoader = exports.authSettingsLoader = exports.agentChatLoader = exports.createLoaderRegistry = exports.createModuleLoader = exports.requireDatabaseId = void 0;
 exports.createDefaultRegistry = createDefaultRegistry;
 var types_1 = require("./types");
 Object.defineProperty(exports, "requireDatabaseId", { enumerable: true, get: function () { return types_1.requireDatabaseId; } });
@@ -63,6 +64,8 @@ var llm_1 = require("./llm");
 Object.defineProperty(exports, "llmLoader", { enumerable: true, get: function () { return llm_1.llmLoader; } });
 var pubkey_1 = require("./pubkey");
 Object.defineProperty(exports, "pubkeyLoader", { enumerable: true, get: function () { return pubkey_1.pubkeyLoader; } });
+var request_protection_1 = require("./request-protection");
+Object.defineProperty(exports, "requestProtectionLoader", { enumerable: true, get: function () { return request_protection_1.requestProtectionLoader; } });
 var rls_1 = require("./rls");
 Object.defineProperty(exports, "rlsLoader", { enumerable: true, get: function () { return rls_1.rlsLoader; } });
 var webauthn_1 = require("./webauthn");
@@ -81,6 +84,7 @@ const inference_log_2 = require("./inference-log");
 const llm_2 = require("./llm");
 const pubkey_2 = require("./pubkey");
 const registry_2 = require("./registry");
+const request_protection_2 = require("./request-protection");
 const rls_2 = require("./rls");
 const webauthn_2 = require("./webauthn");
 function createDefaultRegistry() {
@@ -97,5 +101,6 @@ function createDefaultRegistry() {
     registry.register(agent_chat_2.agentChatLoader);
     registry.register(llm_2.llmLoader);
     registry.register(compute_2.computeLoader);
+    registry.register(request_protection_2.requestProtectionLoader);
     return registry;
 }

package/loaders/request-protection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Request Protection Loader
+ *
+ * Reads the per-database bounds and the per-API overrides raw, then resolves
+ * them through the platform's own defaults and ceilings.
+ *
+ * Unlike the feature-flag loader next door this cannot `COALESCE` in SQL: an
+ * API override is lower-only, so the two scopes are combined with `LEAST` and
+ * then clamped in code, where the platform constants live.
+ *
+ * The columns are also selected by feature detection rather than by name
+ * alone. A serving cluster runs routing planes of several ages — the plane is
+ * a published package a tenant upgrades on its own schedule — and a plane that
+ * predates these columns must resolve to the platform defaults, not fail every
+ * request against it with `column ds.… does not exist`.
+ */
+import type { Pool } from 'pg';
+import type { RequestProtection } from '../request-protection';
+import type { ModuleLoader } from './types';
+/** Test seam: forget what a pool's routing plane looked like. */
+export declare const forgetProtectionColumns: (pool: Pool) => void;
+export declare const requestProtectionLoader: ModuleLoader<RequestProtection>;

package/loaders/request-protection.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Request Protection Loader
+ *
+ * Reads the per-database bounds and the per-API overrides raw, then resolves
+ * them through the platform's own defaults and ceilings.
+ *
+ * Unlike the feature-flag loader next door this cannot `COALESCE` in SQL: an
+ * API override is lower-only, so the two scopes are combined with `LEAST` and
+ * then clamped in code, where the platform constants live.
+ *
+ * The columns are also selected by feature detection rather than by name
+ * alone. A serving cluster runs routing planes of several ages — the plane is
+ * a published package a tenant upgrades on its own schedule — and a plane that
+ * predates these columns must resolve to the platform defaults, not fail every
+ * request against it with `column ds.… does not exist`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestProtectionLoader = exports.forgetProtectionColumns = void 0;
+const request_protection_1 = require("../request-protection");
+const create_loader_1 = require("./create-loader");
+const types_1 = require("./types");
+// ─── SQL ────────────────────────────────────────────────────────────────────
+const PROTECTION_COLUMNS = [
+    'statement_timeout_ms',
+    'idle_in_transaction_timeout_ms',
+    'lock_timeout_ms',
+    'max_concurrent_requests',
+    'max_queue_wait_ms',
+    'rate_limit_rpm',
+    'rate_limit_burst',
+    'max_query_depth',
+    'max_query_cost',
+    'max_page_size',
+    'max_request_bytes',
+    'enable_introspection'
+];
+const availableColumnsSql = `
+  SELECT table_name, column_name
+  FROM information_schema.columns
+  WHERE table_schema = $1
+    AND table_name IN ('database_settings', 'api_settings')
+    AND column_name = ANY($2::text[])
+`;
+const requestProtectionSql = (schema, columns) => {
+    const select = PROTECTION_COLUMNS.flatMap((column) => [
+        columns.database.has(column) ? `ds.${column} AS db_${column}` : null,
+        columns.api.has(column) ? `aps.${column} AS api_${column}` : null
+    ])
+        .filter((expr) => expr !== null)
+        .join(',\n    ');
+    // The join is dropped when the plane carries no API-scope column, so a plane
+    // without an `api_settings` table at all is still readable.
+    const join = columns.api.size
+        ? `\n  LEFT JOIN "${schema}".api_settings aps ON ds.database_id = aps.database_id AND aps.api_id = $2`
+        : '';
+    return `
+  SELECT
+    ds.database_id${select ? `,\n    ${select}` : ''}
+  FROM "${schema}".database_settings ds${join}
+  WHERE ds.database_id = $1
+  LIMIT 1
+`;
+};
+/**
+ * The routing plane's shape changes only when it is redeployed, so it is read
+ * once per pool+schema. Keyed by the pool object so a test pool and a serving
+ * pool never share an answer.
+ */
+const columnCache = new WeakMap();
+const availableColumns = (pool, schema) => {
+    let bySchema = columnCache.get(pool);
+    if (!bySchema) {
+        bySchema = new Map();
+        columnCache.set(pool, bySchema);
+    }
+    const cached = bySchema.get(schema);
+    if (cached)
+        return cached;
+    const pending = pool
+        .query(availableColumnsSql, [
+        schema,
+        [...PROTECTION_COLUMNS]
+    ])
+        .then((result) => {
+        const columns = { database: new Set(), api: new Set() };
+        for (const { table_name, column_name } of result.rows) {
+            if (table_name === 'database_settings')
+                columns.database.add(column_name);
+            else
+                columns.api.add(column_name);
+        }
+        return columns;
+    })
+        .catch((e) => {
+        // A failed probe is not an answer: drop it so the next request retries
+        // rather than caching "this plane has no protection columns" forever.
+        bySchema.delete(schema);
+        throw e;
+    });
+    bySchema.set(schema, pending);
+    return pending;
+};
+/** Test seam: forget what a pool's routing plane looked like. */
+const forgetProtectionColumns = (pool) => {
+    columnCache.delete(pool);
+};
+exports.forgetProtectionColumns = forgetProtectionColumns;
+/**
+ * `bigint` columns arrive as strings from node-postgres (pg returns int8 as
+ * text to avoid the 2^53 cliff), so every numeric bound is normalized here
+ * rather than trusted to already be a number.
+ */
+const num = (value) => {
+    if (value === null || value === undefined)
+        return null;
+    const parsed = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+};
+const bool = (value) => value === null || value === undefined ? null : Boolean(value);
+const scopeOf = (row, prefix) => ({
+    statementTimeoutMs: num(row[`${prefix}_statement_timeout_ms`]),
+    idleInTransactionTimeoutMs: num(row[`${prefix}_idle_in_transaction_timeout_ms`]),
+    lockTimeoutMs: num(row[`${prefix}_lock_timeout_ms`]),
+    maxConcurrentRequests: num(row[`${prefix}_max_concurrent_requests`]),
+    maxQueueWaitMs: num(row[`${prefix}_max_queue_wait_ms`]),
+    rateLimitRpm: num(row[`${prefix}_rate_limit_rpm`]),
+    rateLimitBurst: num(row[`${prefix}_rate_limit_burst`]),
+    maxQueryDepth: num(row[`${prefix}_max_query_depth`]),
+    maxQueryCost: num(row[`${prefix}_max_query_cost`]),
+    maxPageSize: num(row[`${prefix}_max_page_size`]),
+    maxRequestBytes: num(row[`${prefix}_max_request_bytes`]),
+    enableIntrospection: bool(row[`${prefix}_enable_introspection`])
+});
+// ─── Loader ─────────────────────────────────────────────────────────────────
+exports.requestProtectionLoader = (0, create_loader_1.createModuleLoader)({
+    name: 'requestProtection',
+    ttlMs: 5 * 60_000,
+    async resolve(ctx) {
+        const { routingPool, databaseId, apiId } = ctx;
+        const schema = (0, types_1.routingSchemaOf)(ctx);
+        const columns = await availableColumns(routingPool, schema);
+        const params = columns.api.size ? [databaseId, apiId ?? null] : [databaseId];
+        const result = await routingPool.query(requestProtectionSql(schema, columns), params);
+        const row = result.rows[0];
+        if (!row)
+            return undefined;
+        return (0, request_protection_1.resolveRequestProtection)(scopeOf(row, 'db'), scopeOf(row, 'api'));
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/express-context",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Extractable Express middleware for Constructive tenant context — domain resolution, JWT auth, pgSettings, and withPgClient",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -29,21 +29,21 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@constructive-io/url-domains": "^2.30.0",
-    "@pgpmjs/env": "^2.43.1",
-    "@pgpmjs/logger": "^2.25.0",
-    "@pgpmjs/server-utils": "^3.27.1",
-    "@pgpmjs/types": "^2.52.1",
+    "@constructive-io/url-domains": "^2.30.1",
+    "@pgpmjs/env": "^2.43.3",
+    "@pgpmjs/logger": "^2.25.1",
+    "@pgpmjs/server-utils": "^3.27.3",
+    "@pgpmjs/types": "^2.53.1",
     "lru-cache": "^11.2.7",
     "pg": "^8.21.0",
-    "pg-cache": "^3.27.1",
-    "pg-query-context": "^2.30.0"
+    "pg-cache": "^3.27.3",
+    "pg-query-context": "^2.30.1"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
     "@types/pg": "^8.20.4",
     "express": "^5.2.1",
-    "makage": "^0.3.0"
+    "makage": "^0.8.0"
   },
   "peerDependencies": {
     "express": "^5.0.0"
@@ -59,5 +59,5 @@
     "jwt",
     "pgSettings"
   ],
-  "gitHead": "77d58bb93796be91d4e00156bb6847392584d3bc"
+  "gitHead": "6e2d71a9eb4e1f49f0de0b2b594b2f811de97442"
 }

package/refusals.d.ts

@@ -0,0 +1,154 @@
+/**
+ * refusals — the refusal-observability instantiation of `usage-counter`.
+ *
+ * Every refusal the platform issues (a 429 from admission control, a 413 for an
+ * oversized body, a document-gate rejection, a gateway's route or IP window)
+ * is one `RefusalRecorder.record(...)` call at the point the response is
+ * written. That call is an in-memory increment and nothing else — no promise,
+ * no pool, no allocation beyond the key — so a flood costs a counter bump and
+ * refusing traffic keeps working when the recorder's store is down.
+ *
+ * Counts are keyed by `(minute, database, lane, reason, route, source /24)`,
+ * which is exactly the set of questions the platform table answers: which
+ * tenant, why, on which route, from which network, since when. Raw addresses
+ * are never part of the key; `sourceBucket` truncates to a /24 (v4) or /48
+ * (v6) before anything is counted.
+ *
+ * The flush writes the drained batch as one `record_refusals(jsonb)` call —
+ * one statement per window regardless of how many keys it holds.
+ *
+ * @module refusals
+ */
+import type { Pool } from 'pg';
+import type { CounterEntry, CounterFlusherStats } from './usage-counter';
+/** Which platform surface refused the request. */
+export type RefusalLane = 'graphql' | 'sync' | 'static';
+/**
+ * Why a request was refused. Text in the table rather than an enum, so a new
+ * reason is a code change and not a migration; this union is the one list.
+ */
+export type RefusalReason = 'rate_limited' | 'concurrency_saturated' | 'queue_timeout' | 'request_too_large' | 'query_too_deep' | 'query_too_costly' | 'page_size_too_large' | 'anonymous_not_callable' | 'route_rate_limited';
+export declare const REFUSAL_REASONS: readonly RefusalReason[];
+/** One refused request, as the emitter sees it. */
+export interface Refusal {
+    /** The tenant refused, or null when the request never resolved one. */
+    databaseId: string | null;
+    lane: RefusalLane;
+    reason: RefusalReason;
+    /** `"POST /graphql"`, a route binding id, `host+path` — what the lane keys on. */
+    routeKey: string;
+    /** The client address as the lane resolved it. Bucketed before it is counted. */
+    sourceIp: string | null | undefined;
+    /** Epoch ms; defaults to now. */
+    at?: number;
+}
+/** The aggregation key — one `refusal_log` row per distinct value per window. */
+export interface RefusalKey {
+    /** Epoch ms, truncated to the minute. */
+    minuteBucket: number;
+    databaseId: string | null;
+    lane: RefusalLane;
+    reason: RefusalReason;
+    routeKey: string;
+    sourceBucket: string;
+}
+/** `source_bucket` when the lane could not resolve an address. */
+export declare const UNKNOWN_SOURCE = "unknown";
+/** `source_bucket` / `route_key` of the fold-down entry once the counter is full. */
+export declare const OVERFLOW_SOURCE = "overflow";
+export declare const OVERFLOW_ROUTE = "*";
+/** A row as `constructive_usage_private.record_refusals(jsonb)` reads it. */
+export interface RefusalRow {
+    minute_bucket: string;
+    database_id: string | null;
+    lane: RefusalLane;
+    reason: RefusalReason;
+    route_key: string;
+    source_bucket: string;
+    count: number;
+    first_seen_at: string;
+    last_seen_at: string;
+}
+export type RefusalSink = (rows: RefusalRow[]) => Promise<void>;
+/**
+ * Reduce a client address to a network prefix: `/24` for IPv4, `/48` for IPv6.
+ * Enough to tell "one network hammering an anonymous route" from "the tenant's
+ * own users"; not enough to be a person. Anything unparseable is `unknown`.
+ */
+export declare const sourceBucket: (ip: string | null | undefined) => string;
+export declare const refusalKeyOf: (key: RefusalKey) => string;
+/**
+ * Where a key folds to once the counter is full: same minute, tenant, lane and
+ * reason; route and source collapsed. A source-spraying flood therefore costs
+ * `maxKeys` entries plus one per `(database, lane, reason)`, the tenant/reason
+ * attribution is never lost, and the presence of an `overflow` row is itself
+ * the signal that a spray happened.
+ */
+export declare const refusalOverflowKey: (key: RefusalKey) => RefusalKey;
+/** Shape a drained batch for `record_refusals(jsonb)`. */
+export declare const refusalRows: (entries: CounterEntry<RefusalKey>[]) => RefusalRow[];
+export interface RefusalRecorderOptions {
+    /** Where a drained batch goes. See `createRecordRefusalsSink`. */
+    sink: RefusalSink;
+    /** Base flush interval. Default 10 s. */
+    intervalMs?: number;
+    /** Jitter added to each interval. Default 2 s. */
+    jitterMs?: number;
+    /** Distinct keys held per window before folding. Default 2,000. */
+    maxKeys?: number;
+    /**
+     * Failure reporter. Defaults to an error log naming the SQL error and how
+     * many refusals were dropped; every failed flush is reported.
+     */
+    onError?: (err: unknown, dropped: CounterEntry<RefusalKey>[]) => void;
+}
+export declare const DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = 10000;
+export declare const DEFAULT_REFUSAL_FLUSH_JITTER_MS = 2000;
+export declare const DEFAULT_REFUSAL_MAX_KEYS = 2000;
+export interface RefusalRecorderStats {
+    keys: number;
+    overflowed: number;
+    recordFailures: number;
+    flusher: CounterFlusherStats;
+}
+/**
+ * `BoundedCounter<RefusalKey>` + `CounterFlusher` + a `record_refusals` sink.
+ * Construct one per process, `start()` it, `record()` from every refusal site,
+ * `stop()` on shutdown.
+ */
+export declare class RefusalRecorder {
+    private readonly counter;
+    private readonly flusher;
+    private recordFailures;
+    constructor(opts: RefusalRecorderOptions);
+    /**
+     * Count one refusal. Synchronous and never throws: the request that is
+     * being refused must finish being refused whatever state the recorder is in.
+     */
+    record(refusal: Refusal): void;
+    start(): void;
+    /** Final flush, then stop. */
+    stop(): Promise<void>;
+    /** Drain and write now; a sink failure is reported, never thrown. */
+    flush(): Promise<void>;
+    stats(): RefusalRecorderStats;
+}
+export interface RecordRefusalsSinkOptions {
+    /** The platform database's pool. */
+    pool: Pool;
+    /**
+     * The transaction-local claims the flush runs under, resolved by the caller
+     * (a service principal plus the platform database id). The function raises
+     * if `jwt.claims.user_id` is absent, so a resolver that returns nothing
+     * useful fails loudly at the first flush rather than writing unattributed.
+     */
+    claims: () => Promise<Record<string, string>>;
+    /** Default `constructive_usage_private.record_refusals`. */
+    functionName?: string;
+}
+/**
+ * A sink that writes a batch as one `record_refusals(jsonb)` call inside a
+ * transaction carrying the caller's claims. Claims are resolved per flush so a
+ * pool that was unreachable at startup does not leave the recorder wedged.
+ */
+export declare const createRecordRefusalsSink: (opts: RecordRefusalsSinkOptions) => RefusalSink;